org.chronos.chronodb.api.ChronoDB Maven / Gradle / Ivy
Show all versions of org.chronos.chronodb.api Show documentation
package org.chronos.chronodb.api;
import org.chronos.chronodb.internal.api.ChronoDBConfiguration;
import org.chronos.chronodb.internal.api.cache.ChronoDBCache;
import org.chronos.common.version.ChronosVersion;
import java.io.File;
/**
* The top-level interface for interaction with a {@link ChronoDB} instance.
*
*
* This interface represents the entire database instance. Its primary purpose is to spawn instances of {@link ChronoDBTransaction}. Instances of this interface represent (and abstract from) an active connection to a backing datastore.
*
*
* You can acquire an instance of this class by using the static {@link #FACTORY} variable, like so:
*
*
* ChronoDB db = ChronoDB.FACTORY... ;
*
*
*
* Note that this interface extends {@link AutoCloseable}. The {@link #close()} method is used to close this database. As a database instance may hold resources that do not get released automatically upon garbage collection, calling {@link #close()} is mandatory.
*
*
* Instances of this class are guaranteed to be thread-safe and may be shared freely among threads.
*
* @author [email protected] -- Initial Contribution and API
*/
public interface ChronoDB extends TransactionSource, AutoCloseable {
/**
* Provides access to the factory for this class.
*/
public static final ChronoDBFactory FACTORY = ChronoDBFactory.INSTANCE;
/**
* Returns the configuration of this {@link ChronoDB} instance.
*
* @return The configuration. Never null.
*/
public ChronoDBConfiguration getConfiguration();
/**
* Returns the branch manager associated with this database instance.
*
* @return The branch manager. Never null.
*/
public BranchManager getBranchManager();
/**
* Returns the index manager for this {@link ChronoDB} instance.
*
* @return The index manager. Never null.
*/
public IndexManager getIndexManager();
/**
* Returns the serialization manager associated with this database instance.
*
* @return The serialization manager. Never null.
*/
public SerializationManager getSerializationManager();
/**
* Returns the maintenance manager associated with this database instance.
*
* @return The maintenance manager. Never null.
*/
public MaintenanceManager getMaintenanceManager();
/**
* Returns the statistics manager associated with this database instance.
*
* @return The statistics manager. Never null.
*/
public StatisticsManager getStatisticsManager();
/**
* Returns the dateback manager associated with this database instance.
*
*
* Dateback operations allow to modify the history of the database content. It is strongly discouraged to execute any dateback operation while the database is online and accessible for regular transactions.
*
*
* /!\ WARNING /!\
* Dateback operations should be a last resort and should be avoided at all costs during regular database operation. They have the following properties:
*
* - They are not ACID safe. Back up your database before attempting any dateback operation.
*
- They require an exclusive lock on the entire database.
*
- They invalidate all currently ongoing transactions. Transactions which are continued after a dateback operation are not guaranteed to be ACID anymore.
*
- They cannot be undone.
*
- They provide direct access to the temporal stores. There is no safety net to prevent erroneous states.
*
*
* DO NOT USE THE DATEBACK API UNLESS YOU KNOW EXACTLY WHAT YOU ARE DOING.
*
* @return The dateback manager. Never null.
*/
public DatebackManager getDatebackManager();
/**
* Returns the backup manager associated with this ChronoDB instance.
*
* @return The backup manager associated with this ChronoDB instance. Never null.
*/
public BackupManager getBackupManager();
/**
* Returns the cache of this database instance.
*
* @return The cache. Never null. May be a bogus instance if caching is disabled.
*/
public ChronoDBCache getCache();
/**
* Creates a database dump of the entire current database state.
*
*
* Please note that the database is not available for write operations while the dump process is running. Read operations will work concurrently as usual.
*
*
* WARNING: The file created by this process may be very large (several gigabytes), depending on the size of the database. It is the responsibility of the user of this API to ensure that enough disk space is available; this method does not perform any checks regarding disk space availability!
*
*
* WARNING: The given file will be overwritten without further notice!
*
* @param dumpFile The file to store the dump into. Must not be null. Must point to a file (not a directory). The standard file extension *.chronodump is recommmended, but not required. If the file does not exist, the file (and any missing parent directory) will be created.
* @param dumpOptions The options to use for this dump (optional). Please refer to the documentation of the invididual constants for details.
*
* @deprecated Use {@link #getBackupManager()} methods instead.
*/
@Deprecated
public default void writeDump(File dumpFile, DumpOption... dumpOptions){
this.getBackupManager().writeDump(dumpFile, dumpOptions);
}
/**
* Reads the contents of the given dump file into this database.
*
*
* This is a management operation; it completely locks the database. No concurrent writes or reads will be permitted while this operation is being executed.
*
*
* WARNING: The current contents of the database will be merged with the contents of the dump! In case of conflicts, the data stored in the dump file will take precedence. It is strongly recommended to perform this operation only on an empty database!
*
*
* WARNING: As this is a management operation, there is no rollback or undo option!
*
* @param dumpFile The dump file to read the data from. Must not be null, must exist, and must point to a file (not a directory).
* @param options The options to use while reading (optional). May be empty.
*
* @deprecated Use {@link #getBackupManager()} methods instead.
*/
@Deprecated
public default void readDump(File dumpFile, DumpOption... options){
this.getBackupManager().readDump(dumpFile, options);
}
/**
* Closes this instance of ChronoDB.
*
*
* This completely shuts down the database. Any further calls to retrieve or store data will fail.
*
*
* Users are responsible for calling this method when the interaction with the database stops in order to allow ChronoDB to shutdown gracefully.
*/
@Override
public void close();
/**
* Checks if this instance of ChronoDB has already been closed or not.
*
*
* This method is safe to call even after {@link #close()} has been called.
*
* @return true if this ChronoDB instance is closed, otherwise false.
*/
public boolean isClosed();
/**
* Checks if this {@link ChronoDB} instance relies on a file-based backend.
*
* @return true if the backend is file-based, otherwise false.
* @since 0.6.0
*/
public boolean isFileBased();
/**
* Returns the current version of Chronos, as used by this binary.
*
*
* Note that this version might be different from the version of chronos which
* has last written to this database (see {@link #getStoredChronosVersion()}.
*
*
* @return The chronos version of this binary. Never null.
*/
public ChronosVersion getCurrentChronosVersion();
/**
* Returns the version of Chronos which was last used to write to this database.
*
* @return The last version of Chronos used to write to this database. May be null if it was never written.
*/
public ChronosVersion getStoredChronosVersion();
/**
* Returns the features supported by this database.
*
* @return The supported features. Never null.
*/
public ChronoDBFeatures getFeatures();
}