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, copyState may be reused.

  Note: if target is not equal to this instance's object ID, and through one of the refPaths there is a circular reference back to this instance, then that reference is copied as-is (i.e., it is not copied onto target).

  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()