@ThreadSafe public class JTransaction extends Object
Permazen
instance.
Commonly used methods in this class can be divided into the following categories:
Transaction Meta-Data
getPermazen()
- Get the associated Permazen
instancegetTransaction()
- Get the core API Transaction
underlying this instanceTransaction Lifecycle
commit()
- Commit transactionrollback()
- Roll back transactiongetCurrent()
- Get the JTransaction
instance associated with the current threadsetCurrent()
- Set the JTransaction
instance associated with the current threadisValid()
- Test transaction validityperformAction()
- Perform action with this instance as the current transactionObject Access
get()
- Get the Java model object corresponding to a specific database object IDgetAll()
- Get all database objects that are instances of a given Java typecreate()
- Create a new database objectCopying Objects
copyTo()
- Copy a Stream
of objects into another transactioncopyTo()
- Copy objects reachable through specified reference path(s) into another transactioncascadeFindAll()
- Find all objects reachable through a named cascadeImportContext
- Import plain (POJO) model objectsExportContext
- Export plain (POJO) model objectsValidation
validate()
- Validate objects in the validation queueresetValidationQueue()
- Clear the validation queueIndex Queries
queryIndex()
- Access the index associated with a simple fieldqueryListElementIndex()
- Access the composite index associated with a list field that includes corresponding list indicesqueryMapValueIndex()
- Access the composite index associated with a map value field that includes corresponding map keysqueryCompositeIndex()
- Access a composite index defined on two fieldsqueryCompositeIndex()
- Access a composite index defined on three fieldsqueryCompositeIndex()
- Access a composite index defined on four fieldsqueryVersion()
- Get database objects grouped according to their schema versionsReference 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 transactioncreateSnapshotTransaction()
- Create a new in-memory snapshot transactionisSnapshot()
- Determine whether this transaction is a snapshot transactionLower Layer Access
getKey()
- Get the KVDatabase
key prefix for a specific objectgetKey()
- 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 fieldwriteSimpleField()
- Write the value of a simple fieldreadCounterField()
- Access a Counter
fieldreadSetField()
- Access a set fieldreadListField()
- Access a list fieldreadMapField()
- Access a map fieldregisterJObject()
- Ensure a JObject
is registered in the object cache
JObject
Methods
delete()
- Delete an object from this transactionexists()
- Test whether an object exists in this transactionrecreate()
- Recreate an object in this transactionrevalidate()
- Manually add an object to the validation queuegetSchemaVersion()
- Get this schema version of an objectupdateSchemaVersion()
- Update an object's schema versionModifier 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> |
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> |
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> |
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.
|
public static JTransaction getCurrent()
JTransaction
associated with the current thread, if any, otherwise throw an exception.setCurrent()
IllegalStateException
- if there is no such instancepublic static void setCurrent(JTransaction jtx)
JTransaction
associated with the current thread.jtx
- transaction to associate with the current threadpublic Permazen getPermazen()
Permazen
associated with this instance.public Transaction getTransaction()
Transaction
associated with this instance.public ValidationMode getValidationMode()
ValidationMode
configured for this instance.public <T> NavigableSet<T> getAll(Class<T> 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.
T
- containing Java typetype
- any Java type; use Object.class
to return all database objectstype
IllegalArgumentException
- if type
is nullStaleTransactionException
- if this transaction is no longer usablepublic <T> NavigableMap<Integer,NavigableSet<T>> queryVersion(Class<T> type)
T
- containing Java typetype
- any Java type; use Object.class
to return all database objectsIllegalArgumentException
- if type
is nullStaleTransactionException
- if this transaction is no longer usablepublic byte[] getKey(JObject jobj)
byte[]
key in the underlying key/value store corresponding to the specified object.
Notes:
KVDatabase
should not be modified directly, otherwise behavior is undefinedjobj
- Java model objectKVDatabase
key corresponding to jobj
IllegalArgumentException
- if jobj
is nullKVTransaction.watchKey()
,
Transaction.getKey()
public byte[] getKey(JObject jobj, String fieldName)
byte[]
key in the underlying key/value store corresponding to the specified field in the specified object.
Notes:
KVDatabase
should not be modified directly, otherwise behavior is undefinedjobj
- Java model objectfieldName
- the name of a field in jobj
's typeKVDatabase
key of the field in the specified objectTypeNotInSchemaVersionException
- if the current schema version does not contain the object's typeIllegalArgumentException
- if jobj
does not contain the specified fieldIllegalArgumentException
- if fieldName
is otherwise invalidIllegalArgumentException
- if either parameter is nullKVTransaction.watchKey()
,
Transaction.getKey()
public boolean isSnapshot()
SnapshotJTransaction
.SnapshotJTransaction
, otherwise falsepublic SnapshotJTransaction getSnapshotTransaction()
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.
IllegalArgumentException
- if this instance is itself a SnapshotJTransaction
JObject.copyOut()
public SnapshotJTransaction createSnapshotTransaction(ValidationMode validationMode)
This new instance will have the same schema meta-data as this instance.
validationMode
- the ValidationMode
to use for the new transactionIllegalArgumentException
- if validationMode
is nullStaleTransactionException
- if this instance is no longer usablepublic JObject copyTo(JTransaction dest, JObject jobj, CopyState copyState, String... refPaths)
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.
dest
- destination transactionjobj
- object to copycopyState
- tracks which objects have already been copied and traversed and whether to remap object ID'srefPaths
- zero or more reference paths that refer to additional objects to be copied (including intermediate objects)dstId
in dest
DeletedObjectException
- if any object to be copied does not actually existDeletedObjectException
- 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 assignmentSchemaMismatchException
- 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 typeStaleTransactionException
- if this transaction or dest
is no longer usableIllegalArgumentException
- if any path in refPaths
is invalidIllegalArgumentException
- if any parameter other than dstId
is nullJObject.copyTo()
,
JObject.copyOut()
,
JObject.copyIn()
,
copyTo(JTransaction, CopyState, Iterable)
,
ReferencePath
public void copyTo(JTransaction dest, CopyState copyState, Iterable<? extends JObject> jobjs)
This is a convenience method; equivalent to:
copyTo
(dest, copyState,
Streams.stream
(jobjs))
dest
- destination transactioncopyState
- tracks which objects have already been copied and whether to remap object ID'sjobjs
- Iterable
returning the objects to copy; null values are ignoredDeletedObjectException
- if any object to be copied does not actually existDeletedObjectException
- 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 assignmentSchemaMismatchException
- 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 usableIllegalArgumentException
- if any parameter is nullpublic void copyTo(JTransaction dest, CopyState copyState, ObjIdSet ids)
This is a convenience method; equivalent to copyTo(JTransaction, CopyState, Stream)
}
but with the objects specified by object ID.
dest
- destination transactioncopyState
- tracks which objects have already been copied and whether to remap object ID'sids
- the object ID's of the objects to copyDeletedObjectException
- if any object to be copied does not actually existDeletedObjectException
- 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 assignmentSchemaMismatchException
- 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 usableIllegalArgumentException
- if any parameter is nullpublic void copyTo(JTransaction dest, CopyState copyState, Stream<? extends JObject> jobjs)
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.
dest
- destination transactionjobjs
- Iterable
returning the objects to copy; null values are ignoredcopyState
- tracks which objects have already been copied and whether to remap object ID'sDeletedObjectException
- if any object to be copied does not actually existDeletedObjectException
- 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 assignmentSchemaMismatchException
- 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 usableIllegalArgumentException
- if dest
, copyState
, or jobjs
is nullpublic ObjIdMap<ObjId> createClones(ObjIdSet ids)
The newly created objects will be in their initial states.
ids
- object ID'sids
to newly created objectIllegalArgumentException
- if ids
is nullpublic ObjIdSet cascadeFindAll(ObjId id, String cascadeName, int recursionLimit)
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.
id
- starting object IDcascadeName
- cascade name, or null for no cascade (returns just the id
object)recursionLimit
- the maximum number of references to hop through, or -1 for infinityid
object)DeletedObjectException
- if any object containing a traversed reference field does not actually existIllegalArgumentException
- if recursionLimit
is less that -1IllegalArgumentException
- if id
is nullJObject.cascadeCopyTo(JTransaction, String, int, boolean)
public void cascadeFindAll(ObjId id, String cascadeName, int recursionLimit, ObjIdSet visitedIds)
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.
id
- starting object IDcascadeName
- cascade name, or null for no cascaderecursionLimit
- the maximum number of references to hop through, or -1 for infinityvisitedIds
- on entry objects already visited, on return all objects reachableDeletedObjectException
- if any object containing a traversed reference field does not actually existIllegalArgumentException
- if recursionLimit
is less that -1IllegalArgumentException
- if id
or visitedIds
is nullJObject.cascadeCopyTo(JTransaction, String, int, boolean)
public JObject get(ObjId 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.
id
- object IDIllegalArgumentException
- if id
is nullget(ObjId, Class)
,
get(JObject)
public <T> T get(ObjId id, Class<T> 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.
T
- expected Java model typeid
- object IDtype
- expected typeClassCastException
- if the Java model object does not have type type
IllegalArgumentException
- if type
is nullget(ObjId)
,
get(JObject)
public <T extends JObject> T get(T jobj)
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
.
T
- expected Java typejobj
- Java model objectjobj
itself)IllegalArgumentException
- if jobj
is null, or not a Permazen
database objectClassCastException
- if the Java model object in this transaction somehow does not have the same type as jobj
get(ObjId)
,
get(ObjId, Class)
public <T> T create(Class<T> type)
T
- Java model typetype
- Java object model typeIllegalArgumentException
- if type
is not a known Java object model typeStaleTransactionException
- if this transaction is no longer usablepublic <T> T create(JClass<T> jclass)
T
- Java model typejclass
- object typeIllegalArgumentException
- if jclass
is not valid for this instanceStaleTransactionException
- if this transaction is no longer usablepublic boolean delete(JObject jobj)
This method is typically only used by generated classes; normally, JObject.delete()
would be used instead.
jobj
- the object to deleteReferencedObjectException
- if the object is referenced by some other object
through a reference field configured for DeleteAction.EXCEPTION
StaleTransactionException
- if this transaction is no longer usableNullPointerException
- if jobj
is nullpublic boolean exists(ObjId id)
This method is typically only used by generated classes; normally, JObject.exists()
would be used instead.
id
- ID of the object to test for existenceStaleTransactionException
- if this transaction is no longer usableNullPointerException
- if id
is nullpublic boolean recreate(JObject jobj)
This method is typically only used by generated classes; normally, JObject.recreate()
would be used instead.
jobj
- the object to recreateStaleTransactionException
- if this transaction is no longer usableNullPointerException
- if jobj
is nullpublic void revalidate(ObjId id, Class<?>... groups)
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.
id
- ID of the object to revalidategroups
- validation group(s) to use for validation; if empty, Default
is assumedStaleTransactionException
- if this transaction is no longer usableIllegalStateException
- if transaction commit is already in progressDeletedObjectException
- if the object does not exist in this transactionIllegalArgumentException
- if either parameter is nullIllegalArgumentException
- if any group in groups
is nullpublic void resetValidationQueue()
StaleTransactionException
- if this transaction is no longer usableIllegalStateException
- if transaction commit is already in progresspublic int getSchemaVersion(ObjId id)
This method is typically only used by generated classes; normally, JObject.getSchemaVersion()
would be used instead.
id
- ID of the object containing the fieldStaleTransactionException
- if this transaction is no longer usableDeletedObjectException
- if the object does not exist in this transactionNullPointerException
- if id
is nullpublic boolean updateSchemaVersion(JObject jobj)
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.
jobj
- object to updateStaleTransactionException
- if this transaction is no longer usableDeletedObjectException
- if jobj
does not exist in this transactionTypeNotInSchemaVersionException
- if the current schema version does not contain the object's typeNullPointerException
- if jobj
is nullpublic static void registerJObject(JObject jobj)
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
.
jobj
- object to registerNullPointerException
- if jobj
is nullpublic Object readSimpleField(ObjId id, int storageId, boolean updateVersion)
Transaction.readSimpleField()
with ObjId
s converted into JObject
s, etc.
This method is used by generated @JField
getter override methods
and not normally invoked directly by user code.
id
- ID of the object containing the fieldstorageId
- storage ID of the JSimpleField
updateVersion
- true to first automatically update the object's schema version, false to not change itStaleTransactionException
- if this transaction is no longer usableDeletedObjectException
- if the object does not exist in this transactionUnknownFieldException
- if no JSimpleField
corresponding to storageId
existsTypeNotInSchemaVersionException
- if updateVersion
is true but the object has a type
that does not exist in this instance's schema versionNullPointerException
- if id
is nullpublic void writeSimpleField(JObject jobj, int storageId, Object value, boolean updateVersion)
Transaction.writeSimpleField()
after converting JObject
s into ObjId
s, etc.
This method is used by generated @JField
setter override methods
and not normally invoked directly by user code.
jobj
- object containing the fieldstorageId
- storage ID of the JSimpleField
value
- new value for the fieldupdateVersion
- true to first automatically update the object's schema version, false to not change itStaleTransactionException
- if this transaction is no longer usableDeletedObjectException
- if jobj
does not exist in this transactionUnknownFieldException
- if no JSimpleField
corresponding to storageId
existsTypeNotInSchemaVersionException
- if updateVersion
is true but jobj
has a type
that does not exist in this instance's schema versionIllegalArgumentException
- if value
is not an appropriate value for the fieldNullPointerException
- if jobj
is nullpublic Counter readCounterField(ObjId id, int storageId, boolean updateVersion)
This method is used by generated @JField
getter override methods
and not normally invoked directly by user code.
id
- ID of the object containing the fieldstorageId
- storage ID of the JCounterField
updateVersion
- true to first automatically update the object's schema version, false to not change itStaleTransactionException
- if this transaction is no longer usableDeletedObjectException
- if the object does not exist in this transactionUnknownFieldException
- if no JCounterField
corresponding to storageId
existsTypeNotInSchemaVersionException
- if updateVersion
is true but the object has a type
that does not exist in this instance's schema versionNullPointerException
- if id
is nullpublic NavigableSet<?> readSetField(ObjId id, int storageId, boolean updateVersion)
Transaction.readSetField()
with
ObjId
s converted into JObject
s, etc.
This method is used by generated @JSetField
getter override methods and not normally invoked directly by user code.
id
- ID of the object containing the fieldstorageId
- storage ID of the JSetField
updateVersion
- true to first automatically update the object's schema version, false to not change itstorageId
StaleTransactionException
- if this transaction is no longer usableDeletedObjectException
- if the object does not exist in this transactionUnknownFieldException
- if no JSetField
corresponding to storageId
existsTypeNotInSchemaVersionException
- if updateVersion
is true but the object has a type
that does not exist in this instance's schema versionNullPointerException
- if id
is nullpublic List<?> readListField(ObjId id, int storageId, boolean updateVersion)
Transaction.readListField()
with
ObjId
s converted into JObject
s, etc.
This method is used by generated @JListField
getter override methods and not normally invoked directly by user code.
id
- ID of the object containing the fieldstorageId
- storage ID of the JListField
updateVersion
- true to first automatically update the object's schema version, false to not change itstorageId
StaleTransactionException
- if this transaction is no longer usableDeletedObjectException
- if the object does not exist in this transactionUnknownFieldException
- if no JListField
corresponding to storageId
existsTypeNotInSchemaVersionException
- if updateVersion
is true but the object has a type
that does not exist in this instance's schema versionNullPointerException
- if id
is nullpublic NavigableMap<?,?> readMapField(ObjId id, int storageId, boolean updateVersion)
Transaction.readMapField()
with
ObjId
s converted into JObject
s, etc.
This method is used by generated @JMapField
getter override methods and not normally invoked directly by user code.
id
- ID of the object containing the fieldstorageId
- storage ID of the JMapField
updateVersion
- true to first automatically update the object's schema version, false to not change itstorageId
StaleTransactionException
- if this transaction is no longer usableDeletedObjectException
- if the object does not exist in this transactionUnknownFieldException
- if no JMapField
corresponding to storageId
existsTypeNotInSchemaVersionException
- if updateVersion
is true but the object has a type
that does not exist in this instance's schema versionNullPointerException
- if id
is nullpublic NavigableSet<JObject> followReferencePath(ReferencePath path, Iterable<? extends JObject> startObjects)
ReferencePath
.path
- reference pathstartObjects
- starting objectsstartObjects
via path
UnknownFieldException
- if path
contains an unknown fieldIllegalArgumentException
- if either parameter is nullReferencePath
public NavigableSet<JObject> invertReferencePath(ReferencePath path, Iterable<? extends JObject> targetObjects)
ReferencePath
.path
- reference pathtargetObjects
- target objectstargetObjects
via path
UnknownFieldException
- if path
contains an unknown fieldIllegalArgumentException
- if either parameter is nullReferencePath
public <V,T> Index<V,T> queryIndex(Class<T> targetType, String fieldName, Class<V> valueType)
V
- Java type corresponding to the indexed fieldT
- Java type containing the fieldtargetType
- 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-typesfieldName
- 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 valueIllegalArgumentException
- if any parameter is null, or invalidStaleTransactionException
- if this transaction is no longer usablepublic <V,T> Index2<V,T,Integer> queryListElementIndex(Class<T> targetType, String fieldName, Class<V> valueType)
V
- Java type corresponding to the indexed list's element fieldT
- Java type containing the fieldtargetType
- 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-typesfieldName
- name of the indexed field; must include "element"
sub-field name (e.g., "mylist.element"
)valueType
- the Java type corresponding to list elementsIllegalArgumentException
- if any parameter is null, or invalidStaleTransactionException
- if this transaction is no longer usablepublic <V,T,K> Index2<V,T,K> queryMapValueIndex(Class<T> targetType, String fieldName, Class<V> valueType, Class<K> keyType)
V
- Java type corresponding to the indexed map's value fieldT
- Java type containing the fieldK
- Java type corresponding to the indexed map's key fieldtargetType
- 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-typesfieldName
- name of the indexed field; must include "value"
sub-field name (e.g., "mymap.value"
)valueType
- the Java type corresponding to map valueskeyType
- the Java type corresponding to map keysIllegalArgumentException
- if any parameter is null, or invalidStaleTransactionException
- if this transaction is no longer usablepublic <V1,V2,T> Index2<V1,V2,T> queryCompositeIndex(Class<T> targetType, String indexName, Class<V1> value1Type, Class<V2> value2Type)
V1
- Java type corresponding to the first indexed fieldV2
- Java type corresponding to the second indexed fieldT
- Java type containing the fieldtargetType
- type containing the indexed fields; may also be any super-type (e.g., an interface type)indexName
- the name of the composite indexvalue1Type
- the Java type corresponding to the first field valuevalue2Type
- the Java type corresponding to the second field valueIllegalArgumentException
- if any parameter is null, or invalidStaleTransactionException
- if this transaction is no longer usablepublic <V1,V2,V3,T> Index3<V1,V2,V3,T> queryCompositeIndex(Class<T> targetType, String indexName, Class<V1> value1Type, Class<V2> value2Type, Class<V3> value3Type)
V1
- Java type corresponding to the first indexed fieldV2
- Java type corresponding to the second indexed fieldV3
- Java type corresponding to the third indexed fieldT
- Java type containing the fieldtargetType
- type containing the indexed fields; may also be any super-type (e.g., an interface type)indexName
- the name of the composite indexvalue1Type
- the Java type corresponding to the first field valuevalue2Type
- the Java type corresponding to the second field valuevalue3Type
- the Java type corresponding to the third field valueIllegalArgumentException
- if any parameter is null, or invalidStaleTransactionException
- if this transaction is no longer usablepublic <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)
V1
- Java type corresponding to the first indexed fieldV2
- Java type corresponding to the second indexed fieldV3
- Java type corresponding to the third indexed fieldV4
- Java type corresponding to the fourth indexed fieldT
- Java type containing the fieldtargetType
- type containing the indexed fields; may also be any super-type (e.g., an interface type)indexName
- the name of the composite indexvalue1Type
- the Java type corresponding to the first field valuevalue2Type
- the Java type corresponding to the second field valuevalue3Type
- the Java type corresponding to the third field valuevalue4Type
- the Java type corresponding to the fourth field valueIllegalArgumentException
- if any parameter is null, or invalidStaleTransactionException
- if this transaction is no longer usablepublic Object queryIndex(int storageId)
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.
storageId
- indexed JSimpleField
's storage IDIllegalArgumentException
- if storageId
does not correspond to an indexed field or composite indexStaleTransactionException
- if this transaction is no longer usablepublic void commit()
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.
StaleTransactionException
- if this transaction is no longer usableRetryTransactionException
- from KVTransaction.commit()
ValidationException
- if a validation error is detectedIllegalStateException
- if this method is invoked re-entrantly from within a validation checkpublic void rollback()
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.
public boolean isValid()
Transaction.isValid()
public void validate()
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.
RetryTransactionException
- from KVTransaction.commit()
ValidationException
- if a validation error is detectedIllegalStateException
- if transaction commit is already in progressStaleTransactionException
- if this transaction is no longer usableJObject.revalidate(java.lang.Class<?>...)
public void performAction(Runnable action)
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).
action
- action to performIllegalArgumentException
- if action
is nullpublic static void weakConsistency(Runnable action)
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.
action
- action to performIllegalStateException
- if there is no current transactionIllegalArgumentException
- if action
is nullReadTracking
Copyright © 2022. All rights reserved.