Interface StorageManager

All Superinterfaces:
AutoCloseable, DatabasePart, ObjectSwizzling, PersistenceStoring, Persister, StorageActivePart, StorageConnection, StorageController
All Known Subinterfaces:
EmbeddedStorageManager
All Known Implementing Classes:
EmbeddedStorageManager.Default

public interface StorageManager
extends StorageController, StorageConnection, DatabasePart
Central managing type of 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 theStorageTypeDictionary that defines the persistent structure of all handled types.

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

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

  • Method Details

    • configuration

      StorageConfiguration configuration()
      Returns the StorageConfiguration used to initialize this StorageManager instance.
      Returns:
      the used configuration.
    • typeDictionary

      StorageTypeDictionary typeDictionary()
      Returns the StorageTypeDictionary that contains a completely list of types currently known to / handled by the storage represented by this StorageManager instance. This list grows dynamically as so far unknown types are discovered, analyzed, mapped and added on the fly by a store.
      Returns:
      thr current StorageTypeDictionary.
    • 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.
      Returns:
      the root instance's objectId.
    • 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.
    • defaultRoot

      @Deprecated Reference<Object> defaultRoot()
      Deprecated.
      This method is deprecated due to simplified root handling and will be removed in a future version.
      It is advised to use root() and setRoot(Object) instead.
      Returns:
      a mutable Reference to the root object.
    • customRoot

      @Deprecated default Object customRoot()
      Deprecated.
      This method is deprecated due to simplified root handling and will be removed in a future version.
      It is advised to use root() instead, for which this method is an alias.
      Returns:
      the root object.
    • storeDefaultRoot

      @Deprecated default long storeDefaultRoot()
      Deprecated.
      This method is deprecated due to simplified root handling and will be removed in a future version.
      It is advised to use storeRoot() instead, for which this method is an alias.
      Returns:
      stores the root object and returns its objectId.
    • database

      Database database()
      Returns the Database instance this StorageManager is associated with. See its description for details.
      Returns:
      the associated Database instance.
    • databaseName

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