org.jsimpledb

Interface JObject

All Known Implementing Classes:

UntypedJObject

public interface JObject

Interface implemented by JSimpleDB Java model objects.

All JSimpleDB database objects are instances of runtime-generated sub-classes of user-provided Java model classes. These generated subclasses will always implement this interface, providing convenient access to database operations. Therefore, it is conveninent to declare Java model classes abstract and implements JObject. However, this is not strictly necessary; all of the methods declared here ultimately delegate to one of the JTransaction support methods.

All JObjects are associated with a specific JTransaction, and are the unique representatives for their corresponding ObjId in that transaction. All field state derives from the transaction.

See Also:

JTransaction

Method Summary

Modifier and Type	Method and Description
JObject	copyIn(String... refPaths) Copy this instance, and other instances it references through the specified refPaths (if any), into the transaction associated with the current thread.
JObject	copyOut(String... refPaths) Snapshot this instance and other instances it references through the specified refPaths (if any).
JObject	copyTo(JTransaction dest, ObjId target, CopyState copyState, String... refPaths) Copy this instance, and other instances it references through the specified refPaths (if any), into a (possibly) different JTransaction.
boolean	delete() Delete this instance, if it exists, in this instance's associated transaction.
boolean	exists() Determine whether this instance still exists in its associated transaction.
ObjId	getObjId() Get this instance's unique JSimpleDB object identifier.
int	getSchemaVersion() Get this instance's current schema version.
JTransaction	getTransaction() Get this instance's associated JTransaction.
boolean	isSnapshot() Determine whether this instance is a normal instance or is a "snapshot" instance associated with a SnapshotJTransaction.
boolean	recreate() Recreate a deleted instance, if it does not exist, in its associated transaction.
void	resetCachedFieldValues() Reset cached simple field values.
void	revalidate(Class<?>... groups) Add this instance to the validation queue for validation in its associated transaction.
boolean	upgrade() Update the schema version of this instance, if necessary, so that it matches the schema version of its associated transaction.

Method Detail

getObjId

ObjId getObjId()

Get this instance's unique JSimpleDB object identifier.

This method always succeeds, even if the object does not exist.

Returns:

unique database identifier for this instance

getSchemaVersion

int getSchemaVersion()

Get this instance's current schema version. Does not change this instance's schema version.

Returns:

the schema version of this instance

Throws:

DeletedObjectException - if this object does not exist in the JTransaction associated with this instance

StaleTransactionException - if the transaction associated with this instance is no longer usable

getTransaction

JTransaction getTransaction()

Get this instance's associated JTransaction.

If this is a regular database instance, this returns the JTransaction associated with the current thread. Otherwise, this instance is a snapshot instance and this method returns the associated SnapshotJTransaction.

Returns:

the JTransaction that contains this instance's field state

delete

boolean delete()

Delete this instance, if it exists, in this instance's associated transaction.

See Transaction.delete() for details on secondary deletions from DeleteAction.DELETE and JField.cascadeDelete().

Returns:

true if instance was deleted, false if it did not exist

Throws:

StaleTransactionException - if the transaction associated with the current thread is no longer usable

ReferencedObjectException - if the object is referenced by some other object through a reference field configured for DeleteAction.EXCEPTION

exists

boolean exists()

Determine whether this instance still exists in its associated transaction.

Returns:

true if instance exists, otherwise false

Throws:

StaleTransactionException - if the transaction associated with this instance is no longer usable

isSnapshot

boolean isSnapshot()

Determine whether this instance is a normal instance or is a "snapshot" instance associated with a SnapshotJTransaction.

Returns:

true if instance is a snapshot instance

recreate

boolean recreate()

Recreate a deleted instance, if it does not exist, in its associated transaction. The fields of a recreated object are set to their initial values. If the object already exists, nothing changes.

Returns:

true if instance was recreated, false if it already existed

Throws:

StaleTransactionException - if the transaction associated with this instance is no longer usable

revalidate

void revalidate(Class<?>... groups)

Add this instance to the validation queue for validation in its associated transaction.

The actual validation will occur either during JTransaction.commit() or at the next invocation of JTransaction.validate(), whichever occurs first. The specified validation groups, if any, will be used.

If the associated transaction was opened with ValidationMode.DISABLED, no validation will be performed.

Parameters:

groups - validation group(s) to use for validation; if empty, Default is assumed

Throws:

DeletedObjectException - if this object does not exist in the JTransaction associated with this instance

IllegalStateException - if transaction commit is already in progress

StaleTransactionException - if the transaction associated with this instance is no longer usable

NullPointerException - if groups is null

upgrade

boolean upgrade()

Update the schema version of this instance, if necessary, so that it matches the schema version of its associated transaction.

If a version change occurs, matching @OnVersionChange methods will be invoked prior to this method returning.

Returns:

true if the object's schema version was changed, false if it was already updated

Throws:

DeletedObjectException - if this object does not exist in the JTransaction associated with this instance

StaleTransactionException - if the transaction associated with this instance is no longer usable

copyTo

JObject copyTo(JTransaction dest,
               ObjId target,
               CopyState copyState,
               String... refPaths)

Copy this instance, and other instances it references through the specified refPaths (if any), into a (possibly) different JTransaction. This is a more general method; see copyIn() and copyOut() for more common and specific use cases.

The "granularity" of the copy operation is one object, which includes all of the object's fields. This method will always copy at least this instance, and possibly others if refPaths is non-empty.

This method will copy this object's fields into the object with ID target (or this instance's object ID if target is null) in the dest transaction, overwriting any previous values there, along with all other objects reachable from this instance through any of the specified reference paths (including intermediate objects visited). This instance will first be upgrade()ed if necessary. If target (or any other referenced object) already exists in dest, it will have its schema version updated first, if necessary, otherwise it will be created. Any @OnVersionChange, @OnCreate, and @OnChange methods will be notified accordingly as usual (in dest); however, for @OnCreate and @OnChange, the annotation must have snapshotTransactions = true if dest is a SnapshotJTransaction.

The two transactions must be compatible in that for any schema versions encountered, those schema versions must be identical in both transactions.

Circular references are handled properly: if an object is encountered more than once, it is not copied again. The copyState parameter can be used to keep track of objects that have already been copied and/or traversed along some reference path (however, if an object is marked as copied in copyState and is traversed, but does not actually already exist in dest, an exception is thrown). For a "fresh" copy operation, pass a newly created CopyState; for a copy operation that is a continuation of a previous copy, reuse the previous CopyState.

Warning: if two threads attempt to copy objects between the same two transactions at the same time but in opposite directions, deadlock could result.

Parameters:

dest - destination transaction for copies

target - target object ID in dest onto which to copy this instance's fields, or null for this instance

copyState - tracks which indirectly referenced objects have already been copied

refPaths - zero or more reference paths that refer to additional objects to be copied

Returns:

the copied version of this instance in dest

Throws:

DeletedObjectException - if this object does not exist in the JTransaction associated with this instance (no exception is thrown however if an indirectly referenced object does not exist unless it is traversed)

DeletedObjectException - if an object in copied is traversed but does not actually exist

SchemaMismatchException - if the schema corresponding to this object's version is not identical in both the JTransaction associated with this instance and dest (as well for any referenced objects)

IllegalArgumentException - if dest, copied, or refPaths is null

IllegalArgumentException - if any path in refPaths is invalid

See Also:

copyIn(), copyOut(), JTransaction.copyTo()

copyOut

JObject copyOut(String... refPaths)

Snapshot this instance and other instances it references through the specified refPaths (if any).

The "granularity" of the copy operation is one object, which includes all of the object's fields. This method will always copy at least this instance, and possibly others if refPaths is non-empty.

This method will copy this object and all of its fields, along with all other objects reachable through any of the specified reference paths into the SnapshotJTransaction corresponding to this instance's associated transaction (including intermediate objects visited). This instance will first be upgrade()ed if necessary. If any object already exists there, it will be overwritten, otherwise it will be created. @OnCreate and @OnChange notifications will be delivered accordingly; however, the annotation must have snapshotTransactions = true.

Normally this method would only be invoked on a regular database JObject. The returned object will always be a snapshot JObject.

This is a convenience method, and is equivalent to invoking:

this.copyTo(this.getTransaction().getSnapshotTransaction(), null, new CopyState(), refPaths);

Parameters:

refPaths - zero or more reference paths that refer to additional objects to be copied

Returns:

the snapshot JObject copy of this instance

Throws:

DeletedObjectException - if this object does not exist in the JTransaction associated with this instance (no exception is thrown however if an indirectly referenced object does not exist)

IllegalArgumentException - if any path in refPaths is invalid

See Also:

copyIn()

copyIn

JObject copyIn(String... refPaths)

Copy this instance, and other instances it references through the specified refPaths (if any), into the transaction associated with the current thread.

The "granularity" of the copy operation is one object, which includes all of the object's fields. This method will always copy at least this instance, and possibly others if refPaths is non-empty.

This method will copy this object and all of its fields, along with all other objects reachable through any of the specified reference paths into the JTransaction associated with the current thread (including intermediate objects visited). If any object already exists in the current thread's transaction, it will be overwritten, otherwise it will be created. @OnCreate and @OnChange notifications will be delivered accordingly.

Normally this method would only be invoked on a snapshot JObject. If this instance is a regular database JObject, then it is immediately returned unchanged. The returned object will always be a regular database JObject.

This is a convenience method, and is equivalent to invoking:

this.copyTo(JTransaction.getCurrent(), null, new CopyState(), refPaths)

Parameters:

refPaths - zero or more reference paths that refer to additional objects to be copied

Returns:

the regular database copy of this instance

Throws:

DeletedObjectException - if this object does not exist in the JTransaction associated with this instance (no exception is thrown however if an indirectly referenced object does not exist)

SchemaMismatchException - if the schema corresponding to this object's version is not identical in both transactions

IllegalArgumentException - if any path in refPaths is invalid

See Also:

copyOut()

resetCachedFieldValues

void resetCachedFieldValues()

Reset cached simple field values.

JObjects instances may cache simple field values after they have been read from the underlying key/value store for efficiency. This method causes any such cached values to be forgotten, so they will be re-read from the underlying key/value store on the next read of the field.

Normally this method does not need to be used. It may be needed to maintain consistency in exotic situations, for example, where the underlying key/value store is being modified directly.