Package one.microstream.storage.types

Interface StorageManager

  • All Superinterfaces:
    AutoCloseable, DatabasePart, one.microstream.reference.ObjectSwizzling, one.microstream.persistence.types.PersistenceStoring, one.microstream.persistence.types.Persister, StorageActivePart, StorageConnection, StorageController
    public interface StorageManager
extends StorageController, StorageConnection, DatabasePart
    Central managing type for a native Java database's storage layer.

    For all intents and purposes, a StorageManager instance represents the storage of a database in the Java application that uses it. It is used for starting and stopping storage managements threads, call storage-level utility functionality like clearing the low-level data cache, cleaning up / condensing storage files or calling the storage-level garbage collector to remove data that has become unreachable in the entity graph. This type also allows querying the used StorageConfiguration or the StorageTypeDictionary that defines the persistent structure of all handled types.

    For the most cases, only the methods root(), setRoot(Object), start() and shutdown() are important. Everything else is used for more or less advanced purposes and should only be used with good knowledge about the effects caused by it.

    A StorageManager instance is also implicitly a StorageConnection, so that developers don't need to care about connections at all if a single connection suffices.

    • Method Detail

      • start

        StorageManager start()
        "Starts" the storage controlled by this StorageController instance, with "starting" meaning:
        • Reading, indexing and potentially caching all the persisted data in the storage.
        • Starting storage managing threads to execute requests like storing, loading and issued utility functions.
        Specified by:
        start in interface StorageController
        Returns:
        this to allow writing of fluent code.

      • shutdown

        boolean shutdown()
        Issues a command to shut down all active threads managing the storage.
        Specified by:
        shutdown in interface StorageController
        Returns:
        true after a successful shutdown or false if an internal InterruptedException happened.

      • createConnection

        StorageConnection createConnection()
        Creates a new StorageConnection instance. See the type description for details.
        Not that while it makes sense on an architectural level to have a connecting mechanism between application logic and storage level, there is currently no need to create additional connections beyond the intrinsic one held inside a StorageManager instance. Just use it instead.
        Returns:
        a new StorageConnection instance.

      • root

        Object root()
        Return the persistent object graph's root object, without specific typing.

        If a specifically typed root instance reference is desired, it is preferable to hold a properly typed constant reference to it and let the storage initialization use that instance as the root.
        See the following code snippet on how to do that: 

        
static final MyAppRoot      ROOT    = new MyAppRoot();
static final StorageManager STORAGE = EmbeddedStorage.start(ROOT);
        Returns:
        the persistent object graph's root object.

      • setRoot

        Object setRoot​(Object newRoot)
        Sets the passed instance as the new root for the persistent object graph.
        Note that this will replace the old root instance, potentially resulting in wiping the whole database.
        Parameters:
        newRoot - the new root instance to be set.
        Returns:
        the passed newRoot to allow fluent usage of this method.

      • storeRoot

        long storeRoot()
        Stores the registered root instance (as returned by root()) by using the default storing logic by calling StorageConnection.createStorer() to create the Storer to be used.
        Depending on the storer logic, storing the root instance can cause many other object to be stored, as well. For example for the default behavior (as implemented in StorageConnection.createLazyStorer(), all recursively referenced instances that are not yet known to the persistent context (i.e. have an associated objectId registered in the context's PersistenceObjectRegistry) are stored as well. If the default storing logic is "lazy" and the current root object has been persisted already, this call may not update the whole graph!
        Returns:
        the root instance's objectId.

      • viewRoots

        one.microstream.persistence.types.PersistenceRootsView viewRoots()
        Returns a read-only view on all technical root instance registered in this StorageManager instance.
        See the description in PersistenceRootsView for details.
        Returns:
        a new PersistenceRootsView instance allowing to iterate all technical root instances.

      • databaseName

        default String databaseName()
        Alias for return this.database().databaseName();
        Specified by:
        databaseName in interface DatabasePart
        Returns:
        the identifying name of the Database.