org.chronos.chronosphere.emf.internal.api

Interface ChronoResource

All Superinterfaces:

java.lang.AutoCloseable, org.eclipse.emf.common.notify.Notifier, org.eclipse.emf.ecore.resource.Resource

public interface ChronoResource
extends org.eclipse.emf.ecore.resource.Resource, java.lang.AutoCloseable

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ChronoResource.TimeMachine The ChronoResource.TimeMachine controls the point in time at which data is read in an associated ChronoResource.

Nested classes/interfaces inherited from interface org.eclipse.emf.ecore.resource.Resource

org.eclipse.emf.ecore.resource.Resource.Diagnostic, org.eclipse.emf.ecore.resource.Resource.Factory, org.eclipse.emf.ecore.resource.Resource.Internal, org.eclipse.emf.ecore.resource.Resource.IOWrappedException

Field Summary

Fields inherited from interface org.eclipse.emf.ecore.resource.Resource

OPTION_CIPHER, OPTION_LINE_DELIMITER, OPTION_LINE_DELIMITER_UNSPECIFIED, OPTION_SAVE_ONLY_IF_CHANGED, OPTION_SAVE_ONLY_IF_CHANGED_FILE_BUFFER, OPTION_SAVE_ONLY_IF_CHANGED_MEMORY_BUFFER, OPTION_ZIP, RESOURCE__CONTENTS, RESOURCE__ERRORS, RESOURCE__IS_LOADED, RESOURCE__IS_MODIFIED, RESOURCE__IS_TRACKING_MODIFICATION, RESOURCE__RESOURCE_SET, RESOURCE__TIME_STAMP, RESOURCE__URI, RESOURCE__WARNINGS

Method Summary

Modifier and Type	Method and Description
void	close() Closes this resource.
void	commit() Performs a full commit of the changes performed in the context of this resource.
void	commitIncremental() Performs an incremental commit on this resource.
default org.chronos.chronograph.api.structure.ChronoGraph	getGraph() Returns the ChronoGraph instance associated with this resource.
org.chronos.chronograph.api.transaction.ChronoGraphTransaction	getGraphTransaction() Returns the graph transaction to which this resource is currently bound.
default long	getTimestamp() Returns the timestamp on which the resource is currently operating.
default boolean	isClosed() Checks if this resource is closed.
boolean	isOpen() Checks if this resource is still open.
void	rollback() Rolls back all changes performed in the context of this resource.
ChronoResource.TimeMachine	timeMachine() Returns the time machine that is bound to this resource.

Methods inherited from interface org.eclipse.emf.ecore.resource.Resource

delete, getAllContents, getContents, getEObject, getErrors, getResourceSet, getTimeStamp, getURI, getURIFragment, getWarnings, isLoaded, isModified, isTrackingModification, load, load, save, save, setModified, setTimeStamp, setTrackingModification, setURI, unload

Methods inherited from interface org.eclipse.emf.common.notify.Notifier

eAdapters, eDeliver, eNotify, eSetDeliver

Method Detail

getGraphTransaction

org.chronos.chronograph.api.transaction.ChronoGraphTransaction getGraphTransaction()

Returns the graph transaction to which this resource is currently bound.

Over the lifetime of a resource, it can be bound to several different transactions (but never more than one at a time).

Returns:

The graph transaction this resource is currently bound to. Never null.

Throws:

ResourceIsAlreadyClosedException - Thrown if isOpen() returns false and this method was called.

getTimestamp

default long getTimestamp()

Returns the timestamp on which the resource is currently operating.

Returns:

The current timestamp. Never negative. May be zero.

Throws:

ResourceIsAlreadyClosedException - Thrown if isOpen() returns false and this method was called.

getGraph

default org.chronos.chronograph.api.structure.ChronoGraph getGraph()

Returns the ChronoGraph instance associated with this resource.

Returns:

The graph instance. Never null.

Throws:

ResourceIsAlreadyClosedException - Thrown if isOpen() returns false and this method was called.

close

void close()

Closes this resource.

/!\ WARNING: Closing a resource before saving it will roll back any changes on the resource or its attached elements!

If this resource is already closed, this method is a no-op and returns immediately.

This method overrides AutoCloseable.close() and removes the throws Exception declaration. This method will not throw checked exceptions.

Specified by:

close in interface java.lang.AutoCloseable

isOpen

boolean isOpen()

Checks if this resource is still open.

Returns:

true if the resource is still open, or false if it has been closed.

isClosed

default boolean isClosed()

Checks if this resource is closed.

This is just syntactic sugar for isOpen() == false.

Returns:

true if the resource is closed, otherwise false.

rollback

void rollback()

Rolls back all changes performed in the context of this resource.

After this operation returns, it will be in sync with the persistence backend, at the specified timestamp. The resource itself remains open and client code may continue using it as usual.

/!\ WARNING:
This operation cannot be undone and all uncommitted changes will be permanently lost!

Throws:

ResourceIsAlreadyClosedException - Thrown if isOpen() returns false and this method was called.

commit

void commit()

Performs a full commit of the changes performed in the context of this resource.

After this operation returns, the changes will be persisted, and the timestamp of the resource will be advanced to the commit timestamp. This implies that all changes by the commit will continue to be visible, but also commits performed by other transactions will be visible.

Please note that each full commit creates a new revision for all changed elements. For larger processes (e.g. batch imports) which should show up as a single commit in the history, but have change sets which are too big to fit into main memory, clients may use commitIncremental() instead.

Throws:

ResourceIsAlreadyClosedException - Thrown if isOpen() returns false and this method was called.

See Also:

commitIncremental()

commitIncremental

void commitIncremental()

Performs an incremental commit on this resource.

Incremental commits can be used to insert large batches of data into a repository. Their advantage over normal commits is that they do not require the entire data to be contained in main memory before writing it to the storage backend.

Recommended usage of this method:

 ChronoResource resource = ...; // acquire a resource
 try {
        // ... do some heavy work
        resource.commitIncremental();
        // ... more work...
        resource.commitIncremental();
        // ... more work...
        // ... and finally, accept the changes and make them visible to others
        resource.commit();
 } finally {
        // make absolutely sure that the incremental process is terminated in case of error
        resource.rollback();
 }
 

Using an incremental commit implies all of the following facts:

• Only one incremental commit process may be active on any given ChronoSphere instance at any point in time. Attempting to have multiple incremental commit processes on the same ChronoSphere instance will result in a ChronoSphereCommitException on all processes, except for the first process.
• While an incremental commit process is active, no regular commits on other transactions can be accepted.
• Other transactions may continue to read data while an incremental commit process is active, but they cannot see the changes made by incremental commits.
• An incremental commit process consists of several calls to commitIncremental(), and is terminated either by a full-fledged commit(), or by a rollback().
• It is the responsibility of the caller to ensure that either commit() or rollback() are called after the initial commitIncremental() was called. Failure to do so will result in this ChronoSphere instance no longer accepting any commits.
• After the terminating commit(), the changes will be visible to other transactions, provided that they use an appropriate timestamp.
• The timestamp of all changes in an incremental commit process is the timestamp of the first commitIncremental() invocation.
• In contrast to regular transactions, several calls to commitIncremental() may modify the same data. Overwrites within the same incremental commit process are not tracked by the versioning system, and follow the "last writer wins" principle.
• In the history of any given key, an incremental commit process appears as a single, large commit. In particular, it is not possible to select a point in time where only parts of the incremental commit process were applied.
• A call to commitIncremental() does not update the "now" (head revision) timestamp. Only the terminating call to commit() updates this timestamp.
• The timestamp of the transaction executing the incremental commit will be increased after each call to commitIncremental() in order to allow the transaction to read the data it has written in the incremental update. If the incremental commit process fails at any point, this timestamp will be reverted to the original timestamp of the transaction before the incremental commit process started.
• Durability of the changes made by commitIncremental() can only be guaranteed by ChronoSphere if the terminating call to commit() is successful. Any other changes may be lost in case of errors.
• If the JVM process is terminated during an incremental commit process, and the terminating call to commit() has not yet been completed successfully, any data stored by that process will be lost and rolled back on the next startup.

Throws:

ChronoSphereCommitException - Thrown if the commit fails. If this exception is thrown, the entire incremental commit process is aborted, and any changes to the data made by that process will be rolled back.

ResourceIsAlreadyClosedException - Thrown if isOpen() returns false and this method was called.

timeMachine

ChronoResource.TimeMachine timeMachine()

Returns the time machine that is bound to this resource.

Returns:

The time machine. Never null.