Package one.microstream.storage.types

Interface StorageConnection

All Superinterfaces:
ObjectSwizzling, PersistenceStoring, Persister
All Known Subinterfaces:
EmbeddedStorageManager, StorageManager
All Known Implementing Classes:
EmbeddedStorageManager.Default, StorageConnection.Default
public interface StorageConnection
extends Persister
Ultra-thin delegatig type that connects the application context to a storage instance via a Persistence layer (a PersistenceManager instance, potentially exclusively created).

Note that this is a rather "internal" type that users usually do not have to use or care about. Since StorageManager implements this interface, is is normally sufficient to use just that.

  • Method Details

    • issueFullGarbageCollection

      default void issueFullGarbageCollection()
      Issues a full garbage collection to be executed. Depending on the size of the database, the available cache, used hardware, etc., this can take any amount of time.

      Garbage collection marks all persisted objects/records that are reachable from the root (mark phase) and once that is completed, all non-marked records are determined to be effectively unreachable and are thus deleted. This common mechanism in graph-organised data completely removes the need for any explicit deleting.

      Note that the garbage collection on the storage level has nothing to do with the JVM's Garbage Collector on the heap level. While the technical principle is the same, both GCs are separate from each other and do not have anything to do with each other.

      See Also:
      issueGarbageCollection(long)

    • issueGarbageCollection

      boolean issueGarbageCollection​(long nanoTimeBudget)
      Issues garbage collection to be executed, limited to the time budget in nanoseconds specified by the passed nanoTimeBudget.
      When the time budget is used up, the garbage collector will keep the current progress and continue there at the next opportunity. The same progress marker is used by the implicit housekeeping, so both mechanisms will continue on the same progress.
      If no store has occured since the last completed garbage sweep, this method will have no effect and return immediately.
      Parameters:
      nanoTimeBudget - the time budget in nanoseconds to be used to perform garbage collection.
      Returns:
      whether the returned call has completed garbage collection.
      See Also:
      issueFullGarbageCollection()

    • issueFullFileCheck

      default void issueFullFileCheck()
      Issues a full storage file check to be executed. Depending on the size of the database, the available cache, used hardware, etc., this can take any amount of time.

      File checking evaluates every storage data file about being either too small, too big or having too many logical "gaps" in it (created by storing newer versions of an object or by garbage collection). If one of those checks applies, the remaining live data in the file is moved to the current head file and once that is done, the source file (now consisting of 100% logical "gaps", making it effectively superfluous) is then deleted.

      The exact logic is defined by StorageConfiguration.dataFileEvaluator()

      See Also:
      issueFileCheck(long)

    • issueFileCheck

      boolean issueFileCheck​(long nanoTimeBudget)
      Issues a storage file check to be executed, limited to the time budget in nanoseconds specified by the passed nanoTimeBudget.
      When the time budget is used up, the checking logic will keep the current progress and continue there at the next opportunity. The same progress marker is used by the implicit housekeeping, so both mechanisms will continue on the same progress.
      If no store has occured since the last completed check, this method will have no effect and return immediately.
      Parameters:
      nanoTimeBudget - the time budget in nanoseconds to be used to perform file checking.
      Returns:
      whether the returned call has completed file checking.

    • issueFullCacheCheck

      default void issueFullCacheCheck()
      Issues a full storage cache check to be executed. Depending on the size of the database, the available cache, used hardware, etc., this can take any amount of time.

      Cache checking evaluates every cache entity data about being worth to be kept in cache according to the configured StorageEntityCacheEvaluator logic. If deemed unworthy, its data will be cleared from the cache and has to be loaded from the persistent form on the next reading access.
      The check will run until the used cache size is 0 or every entity is checked at least once.

      See Also:
      issueFullCacheCheck(StorageEntityCacheEvaluator), issueCacheCheck(long), issueCacheCheck(long,StorageEntityCacheEvaluator)

    • issueFullCacheCheck

      default void issueFullCacheCheck​(StorageEntityCacheEvaluator entityEvaluator)
      Same as issueFullCacheCheck(), but with using the passed StorageEntityCacheEvaluatorlogic instead of the configured one.
      Parameters:
      entityEvaluator - the entity cache evaluation logic to be used for the call.
      See Also:
      issueFullCacheCheck(), issueCacheCheck(long), issueCacheCheck(long,StorageEntityCacheEvaluator)

    • issueCacheCheck

      default boolean issueCacheCheck​(long nanoTimeBudget)
      Issues a storage cache check to be executed, limited to the time budget in nanoseconds specified by the passed nanoTimeBudget.
      When the time budget is used up, the checking logic will keep the current progress and continue there at the next opportunity. The same progress marker is used by the implicit housekeeping, so both mechanisms will continue on the same progress.
      If the used cache size is 0, this method will have no effect and return immediately.
      Parameters:
      nanoTimeBudget - the time budget in nanoseconds to be used to perform cache checking.
      Returns:
      whether the used cache size is 0 or became 0 via the performed check.
      See Also:
      issueFullCacheCheck(), issueFullCacheCheck(StorageEntityCacheEvaluator), issueCacheCheck(long,StorageEntityCacheEvaluator)

    • issueCacheCheck

      boolean issueCacheCheck​(long nanoTimeBudget, StorageEntityCacheEvaluator entityEvaluator)
      Same as issueCacheCheck(long), but with using the passed StorageEntityCacheEvaluatorlogic instead of the configured one.
      Parameters:
      entityEvaluator - the entity cache evaluation logic to be used for the call.
      See Also:
      issueFullCacheCheck(), issueFullCacheCheck(StorageEntityCacheEvaluator), issueCacheCheck(long)

    • createStorageStatistics

      StorageRawFileStatistics createStorageStatistics()
      Creates a StorageRawFileStatistics instance, (obviously) containing raw file statistics about every channel in the storage.
      Returns:
      a StorageRawFileStatistics instance based on the current state.

    • exportChannels

      void exportChannels​(StorageIoHandler ioHandler, boolean performGarbageCollection)
      Exports the data of all channels in the storage by using the passed StorageIoHandler instance.
      This is basically a simple file copy applied to all files in the storage, however with the guaranteed safety of no other task / access to the storage's files intervening with the ongoing process. This is useful to safely create a complete copy of the storage, e.g. a full backup.
      Parameters:
      ioHandler - the StorageIoHandler logic to be used for the export.
      performGarbageCollection - whether a issueFullGarbageCollection() shall be issued before performing the export.

    • exportChannels

      default void exportChannels​(StorageIoHandler ioHandler)
      Alias for this.exportChannels(fileHandler, true);.
      Parameters:
      ioHandler - the StorageIoHandler logic to be used for the export.
      See Also:
      exportChannels(StorageIoHandler,boolean)

    • exportTypes

      StorageEntityTypeExportStatistics exportTypes​(StorageEntityTypeExportFileProvider exportFileProvider, Predicate<? super StorageEntityTypeHandler> isExportType)
      Exports the entity data of all selected types of all channels into one file per type.
      The data will be in the native binary format used internally by the storage. Converters can be used to transform the data into a different, for example human readable, form like CSV.

      This is useful to extract the data contained in the storage in a structured way, for example to migrate it into another storage system or to analyze it, like converting it into human readable form.

      Parameters:
      exportFileProvider - the StorageEntityTypeExportFileProvider logic to be used.
      isExportType - a Predicate selecting which type's entity data to be exported.
      Returns:
      a StorageEntityTypeExportStatistics information instance about the completed export.
      See Also:
      exportTypes(StorageEntityTypeExportFileProvider)

    • exportTypes

      default StorageEntityTypeExportStatistics exportTypes​(StorageEntityTypeExportFileProvider exportFileProvider)
      Alias for this.exportTypes(exportFileProvider, null);, meaning all types are exported.
      Parameters:
      exportFileProvider - the StorageEntityTypeExportFileProvider logic to be used.
      Returns:
      a StorageEntityTypeExportStatistics information instance about the completed export.
      See Also:
      exportTypes(StorageEntityTypeExportFileProvider,Predicate)

    • importFiles

      void importFiles​(XGettingEnum<Path> importFiles)
      Imports all files specified by the passed Enum (ordered set) of Path in order.
      The files are assumed to be in the native binary format used internally by the storage.
      All entities contained in the specified files will be imported. If they already exist in the storage (identified by their ObjectId), their current data will be replaced by the imported data.
      Note that importing data that is not reachable from any root entity will have no effect and will eventually be deleted by the garbage collector.
      Parameters:
      importFiles - the files whose native binary content shall be imported.

    • persistenceManager

      PersistenceManager<Binary> persistenceManager()
      Returns:
      the PersistenceManager used by this StorageConnection.

    • store

      default long store​(Object instance)
      Stores the passed instance in any case and all referenced instances of persistable references recursively, but stores referenced instances only if they are newly encountered (e.g. don't have an id associated with them in the object registry, yet and are therefore required to be handled). This is useful for the common case of just storing an updated instance and potentially newly created instances along with it while skipping all existing (and normally unchanged) referenced instances.

      Specified by:
      store in interface PersistenceStoring
      Specified by:
      store in interface Persister
      Parameters:
      instance - the root instance of the subgraph of required instances to be stored.
      Returns:
      the object id representing the passed instance.

    • storeAll

      default long[] storeAll​(Object... instances)
      Convenience method to PersistenceStoring.store(Object) multiple instances. The passed array (maybe implicitely created by the compiler) itself is NOT stored.
      Specified by:
      storeAll in interface PersistenceStoring
      Specified by:
      storeAll in interface Persister
      Parameters:
      instances - multiple root instances of the subgraphs of required instances to be stored.
      Returns:
      an array containing the object ids representing the passed instances.

    • storeAll

      default void storeAll​(Iterable<?> instances)
      Convenience method to PersistenceStoring.store(Object) all instances of an Iterable type, usually a collection.
      The passed instance itself is NOT stored.
      Note that this method does not return an array of objectIds, since the amount of instances supplied by the passed Iterable cannot be known until after all instances have been stored and the memory and performance overhead to collect them dynamically would not be worth it in most cases since the returned array is hardly ever needed. If it should be needed, the desired behavior can be easily achieved with a tiny custom-made utility method.
      Specified by:
      storeAll in interface PersistenceStoring
      Specified by:
      storeAll in interface Persister
      Parameters:
      instances - multiple root instances of the subgraphs of required instances to be stored.

    • createLazyStorer

      default Storer createLazyStorer()
      Creates a new Storer instance with lazy storing behavior. This means an entity instance encountered while traversing the entity graph is only stored if it is not yet known to the persistence context, i.e. does not have an objectId associated with it in the persistence context's PersistenceObjectRegistry.
      Specified by:
      createLazyStorer in interface Persister
      Returns:
      the newly created Storer instance.

    • createStorer

      default Storer createStorer()
      Creates a new Storer instance with default storing behavior. The default is lazy storing. See Persister.createLazyStorer().
      Specified by:
      createStorer in interface Persister
      Returns:
      the newly created Storer instance.

    • createEagerStorer

      default Storer createEagerStorer()
      Creates a new Storer instance with eager storing behavior. This means an entity instance encountered while traversing the entity graph is always stored, regardless of if it is already known to the persistence context or not, i.e. does have an objectId associated with it in the persistence context's PersistenceObjectRegistry.

      Note: Eager storing is a dangerous behavior since - depending on the entity graph's referential layout - it can cause the whole entity graph present in the heap to be stored. Therefore, it is stronly advised to instead use lazy storing logic (see Persister.createLazyStorer()) or some other kind of limiting storing logic.

      Specified by:
      createEagerStorer in interface Persister
      Returns:
      the newly created Storer instance.

    • getObject

      default Object getObject​(long objectId)
      Retrieves the instance associated with the passed objectId. Retrieving means guaranteeing that the associated instance is returned. If it does not yet exist, it will be created from persisted data, including all non-lazily referenced objects it is connected to.
      Specified by:
      getObject in interface ObjectSwizzling
      Specified by:
      getObject in interface Persister
      Parameters:
      objectId - the objectId defining which instance to return.
      Returns:
      the instance associated with the passed objectId.

    • New

      static StorageConnection New​(PersistenceManager<Binary> persistenceManager, StorageRequestAcceptor connectionRequestAcceptor)