MicroStream Reference Manual
MicroStream HomeAPI Docs
4.0
4.0
  • Preface
  • System Requirements
  • License
  • Changelog
  • Installation
  • Data-Store
    • Overview
    • Getting Started
    • Root Instances
    • Configuration
      • Properties
      • Storage Files and Directories
      • Using Channels
      • Housekeeping
      • Backup
      • Lock File
    • Storage Targets
      • Local File System
      • SQL Databases
        • Oracle
        • MySQL
        • SQLite
      • Blob Stores
        • Oracle Cloud
        • Oracle NoSQL
        • Coherence
    • Storing Data
      • Convenience Methods and Explicit Storing (Transactions)
      • Lazy and Eager Storing
      • Transient Fields
      • Best Practice
    • Loading Data
      • Lazy Loading
        • Touched Timestamp, Null-Safe Variant
        • Clearing Lazy References
    • Deleting Data
    • Queries
    • Application Life-Cycle
    • Legacy Type Mapping
      • User Interaction
    • Backup Strategies
    • Import / Export
    • Housekeeping
    • Customizing
      • Custom Type Handler
      • Custom Legacy Type Handler
      • Custom Class Loader
      • Custom Storing Behavior
      • Optional Storage Manager Reference in Entities
    • REST Interface
      • Setup
      • REST API
      • Client GUI
    • FAQ
      • Data Model
      • Data Management
      • File Storage
      • Java Features
      • Miscellaneous
    • Addendum
      • Supported Java Features
      • Specialized Type Handlers
      • Examples and Demo Projects
  • Cache
    • Overview
    • Getting Started
    • Configuration
      • Properties
      • Storage
    • Use Cases
      • Hibernate Second Level Cache
      • Spring Cache
  • Basic Concepts
    • Layered Entities
      • Configuration
      • Defining Entities
      • Creating Entities
      • Updating Entities
      • Versioning
      • Logging
      • Multiple Layers
    • Wrapping
      • Configuration
      • Usage
Powered by GitBook
On this page
  • Prerequisites
  • Hello World
  • The Root Instance
  • Creating a Database
  • Storing Data
  • Stopping a Live Database
Export as PDF
  1. Data-Store

Getting Started

PreviousOverviewNextRoot Instances

Last updated 3 years ago

This is the manual for older MicroStream versions (Version < 5.0).

The new documentation (Version >= 5.0) is located at:

Prerequisites

pom.xml
<repositories>
    <repository>
        <id>microstream-releases</id>
        <url>https://repo.microstream.one/repository/maven-public/</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>one.microstream</groupId>
        <artifactId>storage.embedded</artifactId>
        <version>04.00.00-MS-GA</version>
    </dependency>
    <dependency>
        <groupId>one.microstream</groupId>
        <artifactId>storage.embedded.configuration</artifactId>
        <version>04.00.00-MS-GA</version>
    </dependency>
</dependencies>

Hello World

// Initialize a storage manager ("the database") with purely defaults.
final EmbeddedStorageManager storageManager = EmbeddedStorage.start();

// print the last loaded root instance, 
// replace it with a current version and store it
System.out.println(storageManager.root());
storageManager.setRoot("Hello World! @ " + new Date());
storageManager.storeRoot();

// shutdown storage
storageManager.shutdown();

This simplest example will create a new storage if no existing storage is found, if a existing storage is found it will be loaded (this is all done at line 2 in the example above).

In line 6 the current storage's content is printed.

Line 7 assigns some data to the storage, replacing existing data if there is some.

In line 8 everything gets stored.

The Root Instance

When using MicroStream, your entire database is accessed starting at a root instance. This instance is the root object of an object graph that gets persisted by the MicroStream storage logic. While the root instance can be of any type (for example just a collection or an array), it is a good idea to define an explicit root type specific for the application. In this simple example, it is a class called DataRoot, which wraps a single String.

public class DataRoot
{
    private String content;

    public DataRoot()
    {
        super();
    }

    public String getContent()
    {
        return this.content;
    }

    public void setContent(final String content)
    {
        this.content = content;
    }

    @Override
    public String toString()
    {
        return "Root: " + this.content;
    }
}

More about root instances:

Creating a Database

The following code is all that is required to setup a an application backed by a MicroStream database. The application's convenience root instance is defined and an EmbeddedStorageManager instance, linked to the root, is created (and its database managing threads are started). This is a fully operational Java database application.

// Application-specific root instance
final DataRoot root = new DataRoot();

// Initialize a storage manager ("the database") with the given directory.
final EmbeddedStorageManager storageManager = EmbeddedStorage.start(
    root,             // root object
    Paths.get("data") // storage directory
);

Storing Data

// Set content data to the root element, including the time to visualize 
// changes on the next execution.
root.setContent("Hello World! @ " + new Date());

// Store the modified root and its content.
storageManager.storeRoot();

This call is all that is necessary to store data in the simplest case.

Stopping a Live Database

Best practice is to safely shutdown the storage manager by simply calling:

storageManager.shutdown();

storageManager.storeRoot() is a special case method that always stores the root object. If you want to store any other object than the root itself, just call storageManager.store(modifiedObject)

The full code for the Hello World example is on .

https://docs.microstream.one/
Root Instances
GitHub