io.permazen

Class JTransaction

java.lang.Object

io.permazen.JTransaction

Direct Known Subclasses:

SnapshotJTransaction

@ThreadSafe
public class JTransaction
extends Object

A transaction associated with a Permazen instance.

Commonly used methods in this class can be divided into the following categories:

Transaction Meta-Data

• getPermazen() - Get the associated Permazen instance
• getTransaction() - Get the core API Transaction underlying this instance

Transaction Lifecycle

• commit() - Commit transaction
• rollback() - Roll back transaction
• getCurrent() - Get the JTransaction instance associated with the current thread
• setCurrent() - Set the JTransaction instance associated with the current thread
• isValid() - Test transaction validity
• performAction() - Perform action with this instance as the current transaction

Object Access

• get() - Get the Java model object corresponding to a specific database object ID
• getAll() - Get all database objects that are instances of a given Java type
• create() - Create a new database object

Copying Objects

• copyTo() - Copy a Stream of objects into another transaction
• copyTo() - Copy objects reachable through specified reference path(s) into another transaction
• cascadeFindAll() - Find all objects reachable through a named cascade
• ImportContext - Import plain (POJO) model objects
• ExportContext - Export plain (POJO) model objects

Validation

• validate() - Validate objects in the validation queue
• resetValidationQueue() - Clear the validation queue

Index Queries

• queryIndex() - Access the index associated with a simple field
• queryListElementIndex() - Access the composite index associated with a list field that includes corresponding list indices
• queryMapValueIndex() - Access the composite index associated with a map value field that includes corresponding map keys
• queryCompositeIndex() - Access a composite index defined on two fields
• queryCompositeIndex() - Access a composite index defined on three fields
• queryCompositeIndex() - Access a composite index defined on four fields
• queryVersion() - Get database objects grouped according to their schema versions

Reference Paths

• followReferencePath() - Find all objects referred to by to any element in a given set of starting objects through a specified ReferencePath
• invertReferencePath() - Find all objects that refer to any element in a given set of objects through a specified ReferencePath

Snapshot Transactions

• getSnapshotTransaction() - Get the default in-memory snapshot transaction associated with this regular transaction
• createSnapshotTransaction() - Create a new in-memory snapshot transaction
• isSnapshot() - Determine whether this transaction is a snapshot transaction

Lower Layer Access

• getKey() - Get the KVDatabase key prefix for a specific object
• getKey() - Get the KVDatabase key for a specific field in a specific object

The remaining methods in this class are normally only used by generated Java model object subclasses. Instead of using these methods directly, using the appropriately annotated Java model object method or JObject interface method is recommended.

Java Model Object Methods

• readSimpleField() - Read the value of a simple field
• writeSimpleField() - Write the value of a simple field
• readCounterField() - Access a Counter field
• readSetField() - Access a set field
• readListField() - Access a list field
• readMapField() - Access a map field
• registerJObject() - Ensure a JObject is registered in the object cache

JObject Methods

• delete() - Delete an object from this transaction
• exists() - Test whether an object exists in this transaction
• recreate() - Recreate an object in this transaction
• revalidate() - Manually add an object to the validation queue
• getSchemaVersion() - Get this schema version of an object
• updateSchemaVersion() - Update an object's schema version

Method Summary

Modifier and Type	Method and Description
ObjIdSet	cascadeFindAll(ObjId id, String cascadeName, int recursionLimit) Recursively traverse cascade references starting from the given object to find all objects reachable through the specified cascade.
void	cascadeFindAll(ObjId id, String cascadeName, int recursionLimit, ObjIdSet visitedIds) Recursively traverse cascade references starting from the given object to find all objects reachable through the specified cascade.
void	commit() Commit this transaction.
void	copyTo(JTransaction dest, CopyState copyState, Iterable<? extends JObject> jobjs) Copy the specified objects into the specified destination transaction.
void	copyTo(JTransaction dest, CopyState copyState, ObjIdSet ids) Copy the specified objects into the specified destination transaction.
void	copyTo(JTransaction dest, CopyState copyState, Stream<? extends JObject> jobjs) Copy the specified objects into the specified destination transaction.
JObject	copyTo(JTransaction dest, JObject jobj, CopyState copyState, String... refPaths) Copy the specified object, and any other objects referenced through the specified reference paths, into the specified destination transaction.
<T> T	create(Class<T> type) Create a new instance of the given model class in this transaction.
<T> T	create(JClass<T> jclass) Create a new instance of the given type in this transaction.
ObjIdMap<ObjId>	createClones(ObjIdSet ids) Create a new object in this transaction of the same type for each object ID in the given set.
SnapshotJTransaction	createSnapshotTransaction(ValidationMode validationMode) Create an empty snapshot transaction based on this instance.
boolean	delete(JObject jobj) Delete the object with the given object ID in this transaction.
boolean	exists(ObjId id) Determine whether the object with the given object ID exists in this transaction.
NavigableSet<JObject>	followReferencePath(ReferencePath path, Iterable<? extends JObject> startObjects) Find all objects that are reachable from the given starting object set through the specified ReferencePath.
JObject	get(ObjId id) Get the Java model object that is associated with this transaction and has the given ID.
<T> T	get(ObjId id, Class<T> type) Get the Java model object that is associated with this transaction and has the given ID, cast to the given type.
<T extends JObject> T	get(T jobj) Get the Java model object with the same object ID as the given JObject and whose state derives from this transaction.
<T> NavigableSet<T>	getAll(Class<T> type) Get all instances of the given type.
static JTransaction	getCurrent() Get the JTransaction associated with the current thread, if any, otherwise throw an exception.
byte[]	getKey(JObject jobj) Get the byte[] key in the underlying key/value store corresponding to the specified object.
byte[]	getKey(JObject jobj, String fieldName) Get the byte[] key in the underlying key/value store corresponding to the specified field in the specified object.
Permazen	getPermazen() Get the Permazen associated with this instance.
int	getSchemaVersion(ObjId id) Get this schema version of the specified object.
SnapshotJTransaction	getSnapshotTransaction() Get the default SnapshotJTransaction associated with this instance.
Transaction	getTransaction() Get the Transaction associated with this instance.
ValidationMode	getValidationMode() Get the ValidationMode configured for this instance.
NavigableSet<JObject>	invertReferencePath(ReferencePath path, Iterable<? extends JObject> targetObjects) Find all objects that refer to any object in the given target set through the specified ReferencePath.
boolean	isSnapshot() Determine whether this instance is a SnapshotJTransaction.
boolean	isValid() Determine whether this transaction is still usable.
void	performAction(Runnable action) Invoke the given Runnable with this instance as the current transaction.
<V1,V2,T> Index2<V1,V2,T>	queryCompositeIndex(Class<T> targetType, String indexName, Class<V1> value1Type, Class<V2> value2Type) Access a composite index on two fields.
<V1,V2,V3,T> Index3<V1,V2,V3,T>	queryCompositeIndex(Class<T> targetType, String indexName, Class<V1> value1Type, Class<V2> value2Type, Class<V3> value3Type) Access a composite index on three fields.
<V1,V2,V3,V4,T> Index4<V1,V2,V3,V4,T>	queryCompositeIndex(Class<T> targetType, String indexName, Class<V1> value1Type, Class<V2> value2Type, Class<V3> value3Type, Class<V4> value4Type) Access a composite index on four fields.
<V,T> Index<V,T>	queryIndex(Class<T> targetType, String fieldName, Class<V> valueType) Get the index on a simple field.
Object	queryIndex(int storageId) Query an index by storage ID.
<V,T> Index2<V,T,Integer>	queryListElementIndex(Class<T> targetType, String fieldName, Class<V> valueType) Get the composite index on a list field that includes list indices.
<V,T,K> Index2<V,T,K>	queryMapValueIndex(Class<T> targetType, String fieldName, Class<V> valueType, Class<K> keyType) Get the composite index on a map value field that includes map keys.
<T> NavigableMap<Integer,NavigableSet<T>>	queryVersion(Class<T> type) Get all instances of the given type, grouped according to schema version.
Counter	readCounterField(ObjId id, int storageId, boolean updateVersion) Read a counter field.
List<?>	readListField(ObjId id, int storageId, boolean updateVersion) Read a list field.
NavigableMap<?,?>	readMapField(ObjId id, int storageId, boolean updateVersion) Read a map field.
NavigableSet<?>	readSetField(ObjId id, int storageId, boolean updateVersion) Read a set field.
Object	readSimpleField(ObjId id, int storageId, boolean updateVersion) Read a simple field.
boolean	recreate(JObject jobj) Recreate the given instance in this transaction.
static void	registerJObject(JObject jobj) Ensure the given JObject is registered in its associated transaction's object cache.
void	resetValidationQueue() Clear the validation queue associated with this transaction.
void	revalidate(ObjId id, Class<?>... groups) Add the given instance to the validation queue for validation, which will occur either at commit() time or at the next invocation of validate(), whichever occurs first.
void	rollback() Roll back this transaction.
static void	setCurrent(JTransaction jtx) Set the JTransaction associated with the current thread.
boolean	updateSchemaVersion(JObject jobj) Update the schema version of the specified object, if necessary, so that its version matches the schema version associated with this instance's Permazen.
void	validate() Perform validation checks on all objects currently in the validation queue.
static void	weakConsistency(Runnable action) Apply weaker transaction consistency while invoking the given Runnable, if applicable.
void	writeSimpleField(JObject jobj, int storageId, Object value, boolean updateVersion) Write a simple field.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getCurrent

public static JTransaction getCurrent()

Get the JTransaction associated with the current thread, if any, otherwise throw an exception.

Returns:

instance previously associated with the current thread via setCurrent()

Throws:

IllegalStateException - if there is no such instance

setCurrent

public static void setCurrent(JTransaction jtx)

Set the JTransaction associated with the current thread.

Parameters:

jtx - transaction to associate with the current thread

getPermazen

public Permazen getPermazen()

Get the Permazen associated with this instance.

Returns:

the associated database

getTransaction

public Transaction getTransaction()

Get the Transaction associated with this instance.

Returns:

the associated core API transaction

getValidationMode

public ValidationMode getValidationMode()

Get the ValidationMode configured for this instance.

Returns:

the configured validation mode

getAll

public <T> NavigableSet<T> getAll(Class<T> type)

Get all instances of the given type.

The returned set includes objects from all schema versions. Use queryVersion() to find objects with a specific schema version.

The returned set is mutable, with the exception that add() is not supported. Deleting an element results in deleting the corresponding object.

Type Parameters:

T - containing Java type

Parameters:

type - any Java type; use Object.class to return all database objects

Returns:

a live view of all instances of type

Throws:

IllegalArgumentException - if type is null

StaleTransactionException - if this transaction is no longer usable

queryVersion

public <T> NavigableMap<Integer,NavigableSet<T>> queryVersion(Class<T> type)

Get all instances of the given type, grouped according to schema version.

Type Parameters:

T - containing Java type

Parameters:

type - any Java type; use Object.class to return all database objects

Returns:

mapping from schema version to objects having that version

Throws:

IllegalArgumentException - if type is null

StaleTransactionException - if this transaction is no longer usable

getKey

public byte[] getKey(JObject jobj)

Get the byte[] key in the underlying key/value store corresponding to the specified object.

Notes:

• Objects utilize multiple keys; the return value is the common prefix of all such keys.
• The KVDatabase should not be modified directly, otherwise behavior is undefined

Parameters:

jobj - Java model object

Returns:

the KVDatabase key corresponding to jobj

Throws:

IllegalArgumentException - if jobj is null

See Also:

KVTransaction.watchKey(), Transaction.getKey()

getKey

public byte[] getKey(JObject jobj,
                     String fieldName)

Get the byte[] key in the underlying key/value store corresponding to the specified field in the specified object.

Notes:

• Complex fields utilize multiple keys; the return value is the common prefix of all such keys.
• The KVDatabase should not be modified directly, otherwise behavior is undefined

Parameters:

jobj - Java model object

fieldName - the name of a field in jobj's type

Returns:

the KVDatabase key of the field in the specified object

Throws:

TypeNotInSchemaVersionException - if the current schema version does not contain the object's type

IllegalArgumentException - if jobj does not contain the specified field

IllegalArgumentException - if fieldName is otherwise invalid

IllegalArgumentException - if either parameter is null

See Also:

KVTransaction.watchKey(), Transaction.getKey()

isSnapshot

public boolean isSnapshot()

Determine whether this instance is a SnapshotJTransaction.

Returns:

true if this instance is a SnapshotJTransaction, otherwise false

getSnapshotTransaction

public SnapshotJTransaction getSnapshotTransaction()

Get the default SnapshotJTransaction associated with this instance.

The default SnapshotJTransaction uses ValidationMode.MANUAL.

This instance must not itself be a SnapshotJTransaction; use createSnapshotTransaction() to create additional snapshot transactions.

Returns:

the associated snapshot transaction

Throws:

IllegalArgumentException - if this instance is itself a SnapshotJTransaction

See Also:

JObject.copyOut()

createSnapshotTransaction

public SnapshotJTransaction createSnapshotTransaction(ValidationMode validationMode)

Create an empty snapshot transaction based on this instance.

This new instance will have the same schema meta-data as this instance.

Parameters:

validationMode - the ValidationMode to use for the new transaction

Returns:

newly created snapshot transaction

Throws:

IllegalArgumentException - if validationMode is null

StaleTransactionException - if this instance is no longer usable

copyTo

public JObject copyTo(JTransaction dest,
                      JObject jobj,
                      CopyState copyState,
                      String... refPaths)

Copy the specified object, and any other objects referenced through the specified reference paths, into the specified destination transaction.

If the target object does not exist, it will be created, otherwise its schema version will be updated to match the source object if necessary (with resulting @OnVersionChange notifications). If CopyState.isSuppressNotifications() returns false, @OnCreate and @OnChange notifications will also be delivered; however, these annotations must also have snapshotTransactions = true if dest is a SnapshotJTransaction).

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.

This instance and dest must be compatible in that for any schema versions encountered, those schema versions must be identical in both transactions.

If any copied objects contain reference fields configured with JField.allowDeleted() equal to false, then any objects referenced by those fields must also be copied, or else must already exist in dest (if dest is a SnapshotJTransaction, then JField.allowDeletedSnapshot() applies instead). Otherwise, a DeletedObjectException is thrown and it is indeterminate which objects were copied.

Note: 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

jobj - object to copy

copyState - tracks which objects have already been copied and traversed and whether to remap object ID's

refPaths - zero or more reference paths that refer to additional objects to be copied (including intermediate objects)

Returns:

the copied object, i.e., the object having ID dstId in dest

Throws:

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 this instance and dest

TypeNotInSchemaVersionException - if the current schema version does not contain the source object's type

StaleTransactionException - if this transaction or dest is no longer usable

IllegalArgumentException - if any path in refPaths is invalid

IllegalArgumentException - if any parameter other than dstId is null

See Also:

JObject.copyTo(), JObject.copyOut(), JObject.copyIn(), copyTo(JTransaction, CopyState, Iterable), ReferencePath

copyTo

public void copyTo(JTransaction dest,
                   CopyState copyState,
                   Iterable<? extends JObject> jobjs)

Copy the specified objects into the specified destination transaction.

This is a convenience method; equivalent to:

copyTo(dest, copyState, Streams.stream(jobjs))

Parameters:

dest - destination transaction

copyState - tracks which objects have already been copied and whether to remap object ID's

jobjs - Iterable returning the objects to copy; null values are ignored

Throws:

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 this instance and dest

StaleTransactionException - if this transaction or dest is no longer usable

IllegalArgumentException - if any parameter is null

copyTo

public void copyTo(JTransaction dest,
                   CopyState copyState,
                   ObjIdSet ids)

Copy the specified objects into the specified destination transaction.

This is a convenience method; equivalent to copyTo(JTransaction, CopyState, Stream)} but with the objects specified by object ID.

Parameters:

dest - destination transaction

copyState - tracks which objects have already been copied and whether to remap object ID's

ids - the object ID's of the objects to copy

Throws:

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 this instance and dest

StaleTransactionException - if this transaction or dest is no longer usable

IllegalArgumentException - if any parameter is null

copyTo

public void copyTo(JTransaction dest,
                   CopyState copyState,
                   Stream<? extends JObject> jobjs)

Copy the specified objects into the specified destination transaction.

If a target object does not exist, it will be created, otherwise its schema version will be updated to match the source object if necessary (with resulting @OnVersionChange notifications). If CopyState.isSuppressNotifications() returns false, @OnCreate and @OnChange notifications will also be delivered; however, these annotations must also have snapshotTransactions = true if dest is a SnapshotJTransaction).

The copyState tracks which objects have already been copied. 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.

This instance and dest must be compatible in that for any schema versions encountered, those schema versions must be identical in both transactions.

If any copied objects contain reference fields configured with JField.allowDeleted()= false, then any objects referenced by those fields must also be copied, or else must already exist in dest (if dest is a SnapshotJTransaction, then JField.allowDeletedSnapshot() applies instead). Otherwise, a DeletedObjectException is thrown and it is indeterminate which objects were copied.

Note: 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

jobjs - Iterable returning the objects to copy; null values are ignored

copyState - tracks which objects have already been copied and whether to remap object ID's

Throws:

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 this instance and dest

StaleTransactionException - if this transaction or dest is no longer usable

IllegalArgumentException - if dest, copyState, or jobjs is null

createClones

public ObjIdMap<ObjId> createClones(ObjIdSet ids)

Create a new object in this transaction of the same type for each object ID in the given set.

The newly created objects will be in their initial states.

Parameters:

ids - object ID's

Returns:

mapping from object ID in ids to newly created object

Throws:

IllegalArgumentException - if ids is null

cascadeFindAll

public ObjIdSet cascadeFindAll(ObjId id,
                               String cascadeName,
                               int recursionLimit)

Recursively traverse cascade references starting from the given object to find all objects reachable through the specified cascade.

This method finds all objects reachable from the starting 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.

All objects found will be upgraded if necessary.

The recursionLimit parameter can be used to limit the maximum distance of any reachable object, measured in the number of reference field "hops" from the given object.

Parameters:

id - starting object ID

cascadeName - cascade name, or null for no cascade (returns just the id object)

recursionLimit - the maximum number of references to hop through, or -1 for infinity

Returns:

the object ID's of all objects reachable through the specified cascade (including the id object)

Throws:

DeletedObjectException - if any object containing a traversed reference field does not actually exist

IllegalArgumentException - if recursionLimit is less that -1

IllegalArgumentException - if id is null

See Also:

JObject.cascadeCopyTo(JTransaction, String, int, boolean)

cascadeFindAll

public void cascadeFindAll(ObjId id,
                           String cascadeName,
                           int recursionLimit,
                           ObjIdSet visitedIds)

Recursively traverse cascade references starting from the given object to find all objects reachable through the specified cascade.

Upon invocation visitedIds contains the ID's of objects already visited; these objects will not be traversed. In particular, if id is in visitedIds, then this method does nothing. Upon return, visitedIds will also contain the ID's of all new objects found.

All objects found will be upgraded if necessary.

The recursionLimit parameter can be used to limit the maximum distance of any reachable object, measured in the number of reference field "hops" from the given object.

Parameters:

id - starting object ID

cascadeName - cascade name, or null for no cascade

recursionLimit - the maximum number of references to hop through, or -1 for infinity

visitedIds - on entry objects already visited, on return all objects reachable

Throws:

DeletedObjectException - if any object containing a traversed reference field does not actually exist

IllegalArgumentException - if recursionLimit is less that -1

IllegalArgumentException - if id or visitedIds is null

See Also:

JObject.cascadeCopyTo(JTransaction, String, int, boolean)

get

public JObject get(ObjId id)

Get the Java model object that is associated with this transaction and has the given ID.

This method guarantees that for any particular id, the same Java instance will always be returned.

A non-null object is always returned, but the corresponding object may not actually exist in this transaction. In that case, attempts to access its fields will throw DeletedObjectException. Use JObject.exists() to check.

Also, it's possible that id corresponds to an object type that no longer exists in the schema version associated with this transaction. In that case, an UntypedJObject is returned.

Parameters:

id - object ID

Returns:

Java model object

Throws:

IllegalArgumentException - if id is null

See Also:

get(ObjId, Class), get(JObject)

get

public <T> T get(ObjId id,
                 Class<T> type)

Get the Java model object that is associated with this transaction and has the given ID, cast to the given type.

This method guarantees that for any particular id, the same Java instance will always be returned.

A non-null object is always returned, but the corresponding object may not actually exist in this transaction. In that case, attempts to access its fields will throw DeletedObjectException. Use JObject.exists() to check.

This method just invoke get(ObjId) and then casts the result.

Type Parameters:

T - expected Java model type

Parameters:

id - object ID

type - expected type

Returns:

Java model object

Throws:

ClassCastException - if the Java model object does not have type type

IllegalArgumentException - if type is null

See Also:

get(ObjId), get(JObject)

get

public <T extends JObject> T get(T jobj)

Get the Java model object with the same object ID as the given JObject and whose state derives from this transaction.

This method can be thought of as a "refresh" operation for objects being imported from other transactions into this one.

A non-null object is always returned, but the corresponding object may not actually exist in this transaction. In that case, attempts to access its fields will throw DeletedObjectException. Use JObject.exists() to check.

This method is equivalent to get(jobj.getObjId()) followed by an appropriate cast to type T.

Type Parameters:

T - expected Java type

Parameters:

jobj - Java model object

Returns:

Java model object in this transaction with the same object ID (possibly jobj itself)

Throws:

IllegalArgumentException - if jobj is null, or not a Permazen database object

ClassCastException - if the Java model object in this transaction somehow does not have the same type as jobj

See Also:

get(ObjId), get(ObjId, Class)

create

public <T> T create(Class<T> type)

Create a new instance of the given model class in this transaction.

Type Parameters:

T - Java model type

Parameters:

type - Java object model type

Returns:

newly created instance

Throws:

IllegalArgumentException - if type is not a known Java object model type

StaleTransactionException - if this transaction is no longer usable

create

public <T> T create(JClass<T> jclass)

Create a new instance of the given type in this transaction.

Type Parameters:

T - Java model type

Parameters:

jclass - object type

Returns:

newly created instance

Throws:

IllegalArgumentException - if jclass is not valid for this instance

StaleTransactionException - if this transaction is no longer usable

delete

public boolean delete(JObject jobj)

Delete the object with the given object ID in this transaction.

This method is typically only used by generated classes; normally, JObject.delete() would be used instead.

Parameters:

jobj - the object to delete

Returns:

true if object was found and deleted, false if object was not found

Throws:

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

StaleTransactionException - if this transaction is no longer usable

NullPointerException - if jobj is null

exists

public boolean exists(ObjId id)

Determine whether the object with the given object ID exists in this transaction.

This method is typically only used by generated classes; normally, JObject.exists() would be used instead.

Parameters:

id - ID of the object to test for existence

Returns:

true if object was found, false if object was not found

Throws:

StaleTransactionException - if this transaction is no longer usable

NullPointerException - if id is null

recreate

public boolean recreate(JObject jobj)

Recreate the given instance in this transaction.

This method is typically only used by generated classes; normally, JObject.recreate() would be used instead.

Parameters:

jobj - the object to recreate

Returns:

true if the object was recreated, false if the object already existed

Throws:

StaleTransactionException - if this transaction is no longer usable

NullPointerException - if jobj is null

revalidate

public void revalidate(ObjId id,
                       Class<?>... groups)

Add the given instance to the validation queue for validation, which will occur either at commit() time or at the next invocation of validate(), whichever occurs first.

This method is typically only used by generated classes; normally, JObject.revalidate(java.lang.Class<?>...) would be used instead.

Parameters:

id - ID of the object to revalidate

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

Throws:

StaleTransactionException - if this transaction is no longer usable

IllegalStateException - if transaction commit is already in progress

DeletedObjectException - if the object does not exist in this transaction

IllegalArgumentException - if either parameter is null

IllegalArgumentException - if any group in groups is null

resetValidationQueue

public void resetValidationQueue()

Clear the validation queue associated with this transaction. Any previously enqueued objects that have not yet been validated will no longer receive validation.

Throws:

StaleTransactionException - if this transaction is no longer usable

IllegalStateException - if transaction commit is already in progress

getSchemaVersion

public int getSchemaVersion(ObjId id)

Get this schema version of the specified object. Does not change the object's schema version.

This method is typically only used by generated classes; normally, JObject.getSchemaVersion() would be used instead.

Parameters:

id - ID of the object containing the field

Returns:

object's schema version

Throws:

StaleTransactionException - if this transaction is no longer usable

DeletedObjectException - if the object does not exist in this transaction

NullPointerException - if id is null

updateSchemaVersion

public boolean updateSchemaVersion(JObject jobj)

Update the schema version of the specified object, if necessary, so that its version matches the schema version associated with this instance's Permazen.

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

This method is typically only used by generated classes; normally, JObject.upgrade() would be used instead.

Parameters:

jobj - object to update

Returns:

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

Throws:

StaleTransactionException - if this transaction is no longer usable

DeletedObjectException - if jobj does not exist in this transaction

TypeNotInSchemaVersionException - if the current schema version does not contain the object's type

NullPointerException - if jobj is null

registerJObject

public static void registerJObject(JObject jobj)

Ensure the given JObject is registered in its associated transaction's object cache.

This method is used internally, to handle mutations in model class superclass constructors, which will occur before the newly created JObject is fully constructed and associated with its JTransaction.

Parameters:

jobj - object to register

Throws:

NullPointerException - if jobj is null

readSimpleField

public Object readSimpleField(ObjId id,
                              int storageId,
                              boolean updateVersion)

Read a simple field. This returns the value returned by Transaction.readSimpleField() with ObjIds converted into JObjects, etc.

This method is used by generated @JField getter override methods and not normally invoked directly by user code.

Parameters:

id - ID of the object containing the field

storageId - storage ID of the JSimpleField

updateVersion - true to first automatically update the object's schema version, false to not change it

Returns:

value of the field in the object

Throws:

StaleTransactionException - if this transaction is no longer usable

DeletedObjectException - if the object does not exist in this transaction

UnknownFieldException - if no JSimpleField corresponding to storageId exists

TypeNotInSchemaVersionException - if updateVersion is true but the object has a type that does not exist in this instance's schema version

NullPointerException - if id is null

writeSimpleField

public void writeSimpleField(JObject jobj,
                             int storageId,
                             Object value,
                             boolean updateVersion)

Write a simple field. This writes the value via Transaction.writeSimpleField() after converting JObjects into ObjIds, etc.

This method is used by generated @JField setter override methods and not normally invoked directly by user code.

Parameters:

jobj - object containing the field

storageId - storage ID of the JSimpleField

value - new value for the field

updateVersion - true to first automatically update the object's schema version, false to not change it

Throws:

StaleTransactionException - if this transaction is no longer usable

DeletedObjectException - if jobj does not exist in this transaction

UnknownFieldException - if no JSimpleField corresponding to storageId exists

TypeNotInSchemaVersionException - if updateVersion is true but jobj has a type that does not exist in this instance's schema version

IllegalArgumentException - if value is not an appropriate value for the field

NullPointerException - if jobj is null

readCounterField

public Counter readCounterField(ObjId id,
                                int storageId,
                                boolean updateVersion)

Read a counter field.

This method is used by generated @JField getter override methods and not normally invoked directly by user code.

Parameters:

id - ID of the object containing the field

storageId - storage ID of the JCounterField

updateVersion - true to first automatically update the object's schema version, false to not change it

Returns:

value of the counter in the object

Throws:

StaleTransactionException - if this transaction is no longer usable

DeletedObjectException - if the object does not exist in this transaction

UnknownFieldException - if no JCounterField corresponding to storageId exists

TypeNotInSchemaVersionException - if updateVersion is true but the object has a type that does not exist in this instance's schema version

NullPointerException - if id is null

readSetField

public NavigableSet<?> readSetField(ObjId id,
                                    int storageId,
                                    boolean updateVersion)

Read a set field. This returns the set returned by Transaction.readSetField() with ObjIds converted into JObjects, etc.

This method is used by generated @JSetField getter override methods and not normally invoked directly by user code.

Parameters:

id - ID of the object containing the field

storageId - storage ID of the JSetField

updateVersion - true to first automatically update the object's schema version, false to not change it

Returns:

the set field in the object with storage ID storageId

Throws:

StaleTransactionException - if this transaction is no longer usable

DeletedObjectException - if the object does not exist in this transaction

UnknownFieldException - if no JSetField corresponding to storageId exists

TypeNotInSchemaVersionException - if updateVersion is true but the object has a type that does not exist in this instance's schema version

NullPointerException - if id is null

readListField

public List<?> readListField(ObjId id,
                             int storageId,
                             boolean updateVersion)

Read a list field. This returns the list returned by Transaction.readListField() with ObjIds converted into JObjects, etc.

This method is used by generated @JListField getter override methods and not normally invoked directly by user code.

Parameters:

id - ID of the object containing the field

storageId - storage ID of the JListField

updateVersion - true to first automatically update the object's schema version, false to not change it

Returns:

the list field in the object with storage ID storageId

Throws:

StaleTransactionException - if this transaction is no longer usable

DeletedObjectException - if the object does not exist in this transaction

UnknownFieldException - if no JListField corresponding to storageId exists

TypeNotInSchemaVersionException - if updateVersion is true but the object has a type that does not exist in this instance's schema version

NullPointerException - if id is null

readMapField

public NavigableMap<?,?> readMapField(ObjId id,
                                      int storageId,
                                      boolean updateVersion)

Read a map field. This returns the map returned by Transaction.readMapField() with ObjIds converted into JObjects, etc.

This method is used by generated @JMapField getter override methods and not normally invoked directly by user code.

Parameters:

id - ID of the object containing the field

storageId - storage ID of the JMapField

updateVersion - true to first automatically update the object's schema version, false to not change it

Returns:

the map field in the object with storage ID storageId

Throws:

StaleTransactionException - if this transaction is no longer usable

DeletedObjectException - if the object does not exist in this transaction

UnknownFieldException - if no JMapField corresponding to storageId exists

TypeNotInSchemaVersionException - if updateVersion is true but the object has a type that does not exist in this instance's schema version

NullPointerException - if id is null

followReferencePath

public NavigableSet<JObject> followReferencePath(ReferencePath path,
                                                 Iterable<? extends JObject> startObjects)

Find all objects that are reachable from the given starting object set through the specified ReferencePath.

Parameters:

path - reference path

startObjects - starting objects

Returns:

read-only set of objects reachable from startObjects via path

Throws:

UnknownFieldException - if path contains an unknown field

IllegalArgumentException - if either parameter is null

See Also:

ReferencePath

invertReferencePath

public NavigableSet<JObject> invertReferencePath(ReferencePath path,
                                                 Iterable<? extends JObject> targetObjects)

Find all objects that refer to any object in the given target set through the specified ReferencePath.

Parameters:

path - reference path

targetObjects - target objects

Returns:

read-only set of objects that refer to any of the targetObjects via path

Throws:

UnknownFieldException - if path contains an unknown field

IllegalArgumentException - if either parameter is null

See Also:

ReferencePath

queryIndex

public <V,T> Index<V,T> queryIndex(Class<T> targetType,
                                   String fieldName,
                                   Class<V> valueType)

Get the index on a simple field. The simple field may be a sub-field of a complex field.

Type Parameters:

V - Java type corresponding to the indexed field

T - Java type containing the field

Parameters:

targetType - Java type containing the indexed field; may also be any super-type (e.g., an interface type), as long as fieldName is not ambiguous among all sub-types

fieldName - name of the indexed field; for complex fields, must include the sub-field name (e.g., "mylist.element", "mymap.key")

valueType - the Java type corresponding to the field value

Returns:

read-only, real-time view of field values mapped to sets of objects having that value in the field

Throws:

IllegalArgumentException - if any parameter is null, or invalid

StaleTransactionException - if this transaction is no longer usable

queryListElementIndex

public <V,T> Index2<V,T,Integer> queryListElementIndex(Class<T> targetType,
                                                       String fieldName,
                                                       Class<V> valueType)

Get the composite index on a list field that includes list indices.

Type Parameters:

V - Java type corresponding to the indexed list's element field

T - Java type containing the field

Parameters:

targetType - type containing the indexed field; may also be any super-type (e.g., an interface type), as long as fieldName is not ambiguous among all sub-types

fieldName - name of the indexed field; must include "element" sub-field name (e.g., "mylist.element")

valueType - the Java type corresponding to list elements

Returns:

read-only, real-time view of field values, objects having that value in the field, and corresponding list indices

Throws:

IllegalArgumentException - if any parameter is null, or invalid

StaleTransactionException - if this transaction is no longer usable

queryMapValueIndex

public <V,T,K> Index2<V,T,K> queryMapValueIndex(Class<T> targetType,
                                                String fieldName,
                                                Class<V> valueType,
                                                Class<K> keyType)

Get the composite index on a map value field that includes map keys.

Type Parameters:

V - Java type corresponding to the indexed map's value field

T - Java type containing the field

K - Java type corresponding to the indexed map's key field

Parameters:

targetType - type containing the indexed field; may also be any super-type (e.g., an interface type), as long as fieldName is not ambiguous among all sub-types

fieldName - name of the indexed field; must include "value" sub-field name (e.g., "mymap.value")

valueType - the Java type corresponding to map values

keyType - the Java type corresponding to map keys

Returns:

read-only, real-time view of map values, objects having that value in the map field, and corresponding map keys

Throws:

IllegalArgumentException - if any parameter is null, or invalid

StaleTransactionException - if this transaction is no longer usable

queryCompositeIndex

public <V1,V2,T> Index2<V1,V2,T> queryCompositeIndex(Class<T> targetType,
                                                     String indexName,
                                                     Class<V1> value1Type,
                                                     Class<V2> value2Type)

Access a composite index on two fields.

Type Parameters:

V1 - Java type corresponding to the first indexed field

V2 - Java type corresponding to the second indexed field

T - Java type containing the field

Parameters:

targetType - type containing the indexed fields; may also be any super-type (e.g., an interface type)

indexName - the name of the composite index

value1Type - the Java type corresponding to the first field value

value2Type - the Java type corresponding to the second field value

Returns:

read-only, real-time view of the fields' values and the objects having those values in the fields

Throws:

IllegalArgumentException - if any parameter is null, or invalid

StaleTransactionException - if this transaction is no longer usable

queryCompositeIndex

public <V1,V2,V3,T> Index3<V1,V2,V3,T> queryCompositeIndex(Class<T> targetType,
                                                           String indexName,
                                                           Class<V1> value1Type,
                                                           Class<V2> value2Type,
                                                           Class<V3> value3Type)

Access a composite index on three fields.

Type Parameters:

V1 - Java type corresponding to the first indexed field

V2 - Java type corresponding to the second indexed field

V3 - Java type corresponding to the third indexed field

T - Java type containing the field

Parameters:

targetType - type containing the indexed fields; may also be any super-type (e.g., an interface type)

indexName - the name of the composite index

value1Type - the Java type corresponding to the first field value

value2Type - the Java type corresponding to the second field value

value3Type - the Java type corresponding to the third field value

Returns:

read-only, real-time view of the fields' values and the objects having those values in the fields

Throws:

IllegalArgumentException - if any parameter is null, or invalid

StaleTransactionException - if this transaction is no longer usable

queryCompositeIndex

public <V1,V2,V3,V4,T> Index4<V1,V2,V3,V4,T> queryCompositeIndex(Class<T> targetType,
                                                                 String indexName,
                                                                 Class<V1> value1Type,
                                                                 Class<V2> value2Type,
                                                                 Class<V3> value3Type,
                                                                 Class<V4> value4Type)

Access a composite index on four fields.

Type Parameters:

V1 - Java type corresponding to the first indexed field

V2 - Java type corresponding to the second indexed field

V3 - Java type corresponding to the third indexed field

V4 - Java type corresponding to the fourth indexed field

T - Java type containing the field

Parameters:

targetType - type containing the indexed fields; may also be any super-type (e.g., an interface type)

indexName - the name of the composite index

value1Type - the Java type corresponding to the first field value

value2Type - the Java type corresponding to the second field value

value3Type - the Java type corresponding to the third field value

value4Type - the Java type corresponding to the fourth field value

Returns:

read-only, real-time view of the fields' values and the objects having those values in the fields

Throws:

IllegalArgumentException - if any parameter is null, or invalid

StaleTransactionException - if this transaction is no longer usable

queryIndex

public Object queryIndex(int storageId)

Query an index by storage ID. For storage ID's corresponding to simple fields, this method returns an Index, except for list element and map value fields, for which an Index2 is returned. For storage ID's corresponding to composite indexes, this method returns an Index2, Index3, etc. as appropriate.

This method exists mainly for the convenience of programmatic tools, etc.

Parameters:

storageId - indexed JSimpleField's storage ID

Returns:

read-only, real-time view of the fields' values and the objects having those values in the fields

Throws:

IllegalArgumentException - if storageId does not correspond to an indexed field or composite index

StaleTransactionException - if this transaction is no longer usable

commit

public void commit()

Commit this transaction.

Prior to actual commit, if this transaction was created with a validation mode other than ValidationMode.DISABLED, validation of outstanding objects in the validation queue is performed.

If a ValidationException is thrown, the transaction is no longer usable. To perform validation and leave the transaction open, invoke validate() prior to commit.

Throws:

StaleTransactionException - if this transaction is no longer usable

RetryTransactionException - from KVTransaction.commit()

ValidationException - if a validation error is detected

IllegalStateException - if this method is invoked re-entrantly from within a validation check

rollback

public void rollback()

Roll back this transaction.

This method may be invoked at any time, even after a previous invocation of commit() or rollback(), in which case the invocation will be ignored.

isValid

public boolean isValid()

Determine whether this transaction is still usable.

Returns:

true if this transaction is still valid

See Also:

Transaction.isValid()

validate

public void validate()

Perform validation checks on all objects currently in the validation queue. This method may be called at any time prior to commit() to process and clear the queue of validatable objects.

If validation fails, validation stops, all remaining unvalidated objects are left on the validation queue, and a ValidationException is thrown. The transaction will remain usable.

Note: if the this transaction was created with ValidationMode.DISABLED, then this method does nothing.

Throws:

RetryTransactionException - from KVTransaction.commit()

ValidationException - if a validation error is detected

IllegalStateException - if transaction commit is already in progress

StaleTransactionException - if this transaction is no longer usable

See Also:

JObject.revalidate(java.lang.Class<?>...)

performAction

public void performAction(Runnable action)

Invoke the given Runnable with this instance as the current transaction.

If another instance is currently associated with the current thread, it is set aside for the duration of action's execution, and then restored when action is finished (regardless of outcome).

Parameters:

action - action to perform

Throws:

IllegalArgumentException - if action is null

weakConsistency

public static void weakConsistency(Runnable action)

Apply weaker transaction consistency while invoking the given Runnable, if applicable.

If the the underlying KVTransaction does not implement ReadTracking, then this method simply invokes action. Otherwise, it disables tracking of reads while performing action, which means some reads could return stale data.

This method is for experts only; inappropriate use can result in a corrupted database. In particular, you should not perform any writes based on information read with weak consistency. Note that this includes the writes associated with implicit schema migration; therefore, you must ensure any objects accessed do not need to be upgraded.

There must be a current transaction associated with the current thread.

Parameters:

action - action to perform

Throws:

IllegalStateException - if there is no current transaction

IllegalArgumentException - if action is null

See Also:

ReadTracking