JObject (Permazen 4.1.6 API)

All Known Subinterfaces:

Body, HasSatellites<S>, Satellite<P>

All Known Implementing Classes:

AbstractBody, AbstractHasSatellites, Moon, Planet, Star, UntypedJObject
```
public interface JObject
```
Interface implemented by Permazen Java model objects.
All Permazen database objects are instances of runtime-generated sub-classes of user-provided Java model types. These generated subclasses will always implement this interface, providing convenient access to database operations. Therefore, it is convenient 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.
Object Identity and State

Every JObject has a unique 64-bit object identifier, represented as an ObjId. All JObject instances are permanently associated with a specific transaction, and are the unique representatives for their corresponding ObjId in that transaction. All field state derives from the associated transaction.
There are two types of transactions: normal transactions reflecting an open transaction on the underlying key/value database, and snapshot transactions, which are in-memory containers of object data. Snapshot transactions are fully functional, supporting index queries, object versioning, etc.
Copying Objects

This interface provides methods for copying a graph of objects between transactions, for example, from an open key/value database transaction into an in-memory snapshot transaction ("copy out"), or vice-versa ("copy in"). A graph of objects can be copied by specifying a starting object and either a list of reference paths, or a cascade name (see @JField). Object ID's can be remapped during the copy if necessary, e.g., to ensure existing objects are not overwritten (see CopyState).

See Also:

JTransaction

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default JObject`	`cascadeCopyIn(String cascadeName, boolean clone)` Copy this instance and all objects reachable from it via the specified cascade into the transaction associated with the current thread.
`default JObject`	`cascadeCopyOut(String cascadeName, boolean clone)` Copy this instance and all objects reachable from it via the specified cascade into the associated in-memory snapshot transaction.
`default JObject`	`cascadeCopyTo(JTransaction dest, String cascadeName, boolean clone)` Copy this instance and all objects reachable from it via the specified cascade into the specified destination transaction.
`default JObject`	`cascadeCopyTo(JTransaction dest, String cascadeName, int recursionLimit, boolean clone)` Copy this instance and all objects reachable from it via the specified cascade into the specified destination transaction.
`default 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.
`default JObject`	`copyOut(String... refPaths)` Copy this instance and other instances it references through the specified reference paths (if any) into the associated in-memory snapshot transaction.
`default JObject`	`copyTo(JTransaction dest, CopyState copyState, String... refPaths)` Copy this instance, and other instances it references through the specified reference paths, into the specified destination transaction.
`default boolean`	`delete()` Delete this instance, if it exists, in this instance's associated transaction.
`default boolean`	`exists()` Determine whether this instance still exists in its associated transaction.
`default <R> NavigableSet<R>`	`findReferring(Class<R> type, String fieldName)` Find all objects of the given type referring to this object through the specified reference field.
`default JClass<?>`	`getJClass()` Get the `JClass` of which this `JObject` is an instance.
`Class<?>`	`getModelClass()` Get the original Java model class of which this `JObject` is an instance.
`ObjId`	`getObjId()` Get this instance's unique Permazen object identifier.
`default int`	`getSchemaVersion()` Get this instance's current schema version.
`JTransaction`	`getTransaction()` Get this instance's associated `JTransaction`.
`default boolean`	`isSnapshot()` Determine whether this instance is a normal instance or is an in-memory "snapshot" instance associated with a `SnapshotJTransaction`.
`default boolean`	`recreate()` Recreate a deleted instance, if it does not exist, in its associated transaction.
`void`	`resetCachedFieldValues()` Reset cached simple field values.
`default void`	`revalidate(Class<?>... groups)` Add this instance to the validation queue for validation in its associated transaction.
`default 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 Permazen object identifier.
    This method always succeeds, even if the object does not exist.
    
    Returns:
    
    unique database identifier for this instance
  - getSchemaVersion
```
default 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.
    
    Returns:
    
    the JTransaction that contains this instance's field state
  - delete
```
default 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
```
default 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
```
default boolean isSnapshot()
```
    Determine whether this instance is a normal instance or is an in-memory "snapshot" instance associated with a SnapshotJTransaction.
    Equivalent to getTransaction().isSnapshot().
    
    Returns:
    
    true if instance is a snapshot instance
  - recreate
```
default 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
```
default 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
```
default 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
```
default JObject copyTo(JTransaction dest,
                       CopyState copyState,
                       String... refPaths)
```
    Copy this instance, and other instances it references through the specified reference paths, into the specified destination transaction.
    This is a more general method; see copyIn() and copyOut() for more common and specific use cases.
    This method copies this object and 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 any copied object already exists in dest, it will have its schema version updated first, if necessary, then be overwritten. 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 tracks which objects have already been copied and/or traversed along some reference path. 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. The CopyState may also be configured to remap object ID's.
    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
    
    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 any object to be copied does not actually exist
    
    DeletedObjectException - if any copied object ends up with a reference to an object that does not exist in dest through a reference field configured to disallow deleted assignment
    
    SchemaMismatchException - if the schema corresponding to any copied object is not identical in both the JTransaction associated with this instance and dest
    
    IllegalArgumentException - if any parameter is null
    
    IllegalArgumentException - if any path in refPaths is invalid
    
    See Also:
    
    copyIn(), copyOut(), JTransaction.copyTo(), ReferencePath
  - copyOut
```
default JObject copyOut(String... refPaths)
```
    Copy this instance and other instances it references through the specified reference paths (if any) into the associated in-memory snapshot transaction.
    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(), 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 any copied object ends up with a reference to an object that does not exist in dest through a reference field configured to disallow deleted assignment in snapshot transactions
    
    IllegalArgumentException - if this instance is a snapshot instance
    
    IllegalArgumentException - if any path in refPaths is invalid
    
    See Also:
    
    copyIn()
  - copyIn
```
default 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.
    Normally this method would only be invoked on a snapshot JObject. The returned object will be a JObject in the currently open transaction.
    This is a convenience method, and is equivalent to invoking:
    this.copyTo(JTransaction.getCurrent(), 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 any copied object ends up with a reference to an object that does not exist in dest through a reference field configured to disallow deleted assignment
    
    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()
  - cascadeCopyTo
```
default JObject cascadeCopyTo(JTransaction dest,
                              String cascadeName,
                              boolean clone)
```
    Copy this instance and all objects reachable from it via the specified cascade into the specified destination transaction.
    This is a convenience method, and is equivalent to invoking:
    this.cascadeCopyTo(dest, cascadeName, -1, clone);
    
    Parameters:
    
    dest - destination transaction for copies
    
    cascadeName - cascade name, or null for no cascade (i.e., copy only this instance)
    
    clone - true to clone objects, i.e., assign the copies new, unused object ID's in dest, or false to preserve the same object ID's, overwriting any existing objects in dest
    
    Returns:
    
    the copied version of this instance in dest
    
    Throws:
    
    DeletedObjectException - if any object to be copied does not exist
    
    DeletedObjectException - if any copied object ends up with a reference to an object that does not exist in dest through a reference field configured to disallow deleted assignment
    
    SchemaMismatchException - if the schema version corresponding to any copied object is not identical in both transactions
    
    IllegalArgumentException - if dest is null
    
    See Also:
    
    cascadeCopyTo(JTransaction, String, int, boolean)
  - cascadeCopyTo
```
default JObject cascadeCopyTo(JTransaction dest,
                              String cascadeName,
                              int recursionLimit,
                              boolean clone)
```
    Copy this instance and all objects reachable from it via the specified cascade into the specified destination transaction.
    This is a more general method; see cascadeCopyIn() and cascadeCopyOut() for more common and specific use cases.
    This method finds and copies all objects reachable from this object based on @JField.cascades() and @JField.inverseCascades() annotation properties on reference fields: a reference field is traversed in the forward or inverse direction if cascadeName is specified in the corresponding annotation property. See @JField for details.
    The recursionLimit parameter can be used to limit the maximum distance of any copied object, measured in the number of reference field "hops" from this object.
    This instance will first be upgrade()ed if necessary. If any copied object already exists in dest, it will have its schema version updated first, if necessary, then be overwritten. 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 tracks which objects have already been copied and traversed. 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. The CopyState may also be configured to remap object ID's.
    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
    
    cascadeName - cascade name, or null for no cascade (i.e., copy only this instance)
    
    recursionLimit - the maximum number of references to hop through, or -1 for infinity
    
    clone - true to clone objects, i.e., assign the copies new, unused object ID's in dest, or false to preserve the same object ID's, overwriting any existing objects in dest
    
    Returns:
    
    the copied version of this instance in dest
    
    Throws:
    
    DeletedObjectException - if any object to be copied does not exist
    
    DeletedObjectException - if any copied object ends up with a reference to an object that does not exist in dest through a reference field configured to disallow deleted assignment
    
    SchemaMismatchException - if the schema version corresponding to any copied object is not identical in both transactions
    
    IllegalArgumentException - if recursionLimit is less that -1
    
    IllegalArgumentException - if dest is null
    
    See Also:
    
    cascadeCopyIn(), cascadeCopyOut(), JTransaction.cascadeFindAll()
  - cascadeCopyOut
```
default JObject cascadeCopyOut(String cascadeName,
                               boolean clone)
```
    Copy this instance and all objects reachable from it via the specified cascade into the associated in-memory snapshot transaction.
    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.cascadeCopyTo(this.getTransaction().getSnapshotTransaction(), cascadeName, clone);
    
    Parameters:
    
    cascadeName - cascade name, or null for no cascade (i.e., copy only this instance)
    
    clone - true to clone objects, i.e., assign the copies new, unused object ID's in the snapshot transaction, or false to preserve the same object ID's, overwriting any existing objects
    
    Returns:
    
    the snapshot JObject copy of this instance
    
    Throws:
    
    DeletedObjectException - if any object to be copied does not exist
    
    DeletedObjectException - if any copied object ends up with a reference to an object that does not exist in dest through a reference field configured to disallow deleted assignment in snapshot transactions
    
    SchemaMismatchException - if the schema version corresponding to any copied object is not identical in both transactions
    
    IllegalArgumentException - if this instance is a snapshot instance
    
    See Also:
    
    cascadeCopyIn(), cascadeCopyTo()
  - cascadeCopyIn
```
default JObject cascadeCopyIn(String cascadeName,
                              boolean clone)
```
    Copy this instance and all objects reachable from it via the specified cascade into the transaction associated with the current thread.
    Normally this method would only be invoked on a snapshot JObject. The returned object will be a JObject in the currently open transaction.
    This is a convenience method, and is equivalent to invoking:
    this.cascadeCopyTo(JTransaction.getCurrent(), cascadeName, clone);
    
    Parameters:
    
    cascadeName - cascade name, or null for no cascade (i.e., copy only this instance)
    
    clone - true to clone objects, i.e., assign the copies new, unused object ID's in the database transaction, or false to preserve the same object ID's, overwriting any existing objects
    
    Returns:
    
    the regular database copy of this instance
    
    Throws:
    
    DeletedObjectException - if any object to be copied does not exist
    
    DeletedObjectException - if any copied object ends up with a reference to an object that does not exist in dest through a reference field configured to disallow deleted assignment
    
    SchemaMismatchException - if the schema version corresponding to any copied object is not identical in both transactions
    
    See Also:
    
    cascadeCopyOut(), cascadeCopyTo()
  - 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.
  - findReferring
```
default <R> NavigableSet<R> findReferring(Class<R> type,
                                          String fieldName)
```
    Find all objects of the given type referring to this object through the specified reference field.
    The fieldName can be the name of a simple reference field (e.g., "teacher") or a sub-field of a complex field (e.g., "students.element").
    
    Type Parameters:
    
    R - type of referring objects
    
    Parameters:
    
    type - type of referring objects
    
    fieldName - name of reference field
    
    Returns:
    
    all objects of the specified type referring to this object through the named field
    
    Throws:
    
    StaleTransactionException - if the transaction associated with this instance is no longer open
    
    IllegalArgumentException - if either parameter is null
  - getJClass
```
default JClass<?> getJClass()
```
    Get the JClass of which this JObject is an instance.
    
    Returns:
    
    associated JClass
    
    Throws:
    
    TypeNotInSchemaVersionException - if this instance has a type that does not exist in this instance's schema version, i.e., this instance is an UntypedJObject
  - getModelClass
```
Class<?> getModelClass()
```
    Get the original Java model class of which this JObject is an instance.
    
    Returns:
    
    Java model class

Interface JObject

Method Summary

Method Detail

getObjId

getSchemaVersion

getTransaction

delete

exists

isSnapshot

recreate

revalidate

upgrade

copyTo

copyOut

copyIn

cascadeCopyTo

cascadeCopyTo

cascadeCopyOut

cascadeCopyIn

resetCachedFieldValues

findReferring

getJClass

getModelClass