Package io.permazen

Class PermazenTransaction

java.lang.Object
io.permazen.PermazenTransaction
Direct Known Subclasses:
DetachedPermazenTransaction
@ThreadSafe public class PermazenTransaction 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

Transaction Lifecycle

Object Access

  • get() - Get the Java model object in this transaction corresponding to a specific database object ID
  • getSingleton() - Get a singleton instance in this transaction, creating it on demand if needed
  • getAll() - Get all Java model objects in this transaction that are instances of a given Java type
  • create() - Create a new Java model object in this transaction
  • cascade() - Find all objects reachable through a reference cascade

Copying Objects

Validation

Index Queries

Reference Paths

Detached Transactions

Lower Layer Access

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 PermazenObject interface method is recommended.

Java Model Object Methods

PermazenObject 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
  • migrateSchema() - Migrate an object's schema to match this transaction's data model

  • Method Details

    • getCurrent

      public static PermazenTransaction getCurrent()
      Get the PermazenTransaction 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(PermazenTransaction ptx)
      Set the PermazenTransaction associated with the current thread.
      Parameters:
      ptx - transaction to associate with the current thread

    • hasCurrent

      public static boolean hasCurrent()
      Determine if there is a PermazenTransaction associated with the current thread.
      Returns:
      true if there is a current PermazenTransaction, otherwise false

    • 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 schemas. Use querySchemaIndex() to find objects with a specific schema.

      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

    • getSingleton

      public <T> T getSingleton(Class<T> type)
      Get the singleton instance of the given type, creating it on demand if needed.

      This is a convenience method for accessing the singleton instances of any type annotated with @PermazenType(singleton = true). If type is not a singleton type, an exception is thrown.

      If no instance exists yet, one is created. So this method is essentially shorthand for: 

      
  try {
      return this.getAll(type).first();
  } catch (NoSuchElementException e) {
      return this.create(type);
  }
      Type Parameters:
      T - singleton type
      Parameters:
      type - singleton model class
      Returns:
      the singleton instance of type type
      Throws:
      IllegalArgumentException - if type is not a singleton type
      IllegalArgumentException - if type is null
      StaleTransactionException - if this transaction is no longer usable
      See Also:

    • querySchemaIndex

      public <T> NavigableMap<SchemaId,NavigableSet<T>> querySchemaIndex(Class<T> type)
      Get all instances of the given type, grouped according to schema index.
      Type Parameters:
      T - containing Java type
      Parameters:
      type - any Java type; use Object.class to return all database objects
      Returns:
      live, read-only mapping from SchemaId to objects having that schema
      Throws:
      IllegalArgumentException - if type is null
      StaleTransactionException - if this transaction is no longer usable

    • getKey

      public byte[] getKey(PermazenObject pobj)
      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:
      pobj - Java model object
      Returns:
      the KVDatabase key corresponding to pobj
      Throws:
      IllegalArgumentException - if pobj is null
      See Also:

    • isDetached

      public boolean isDetached()
      Determine whether this instance is a DetachedPermazenTransaction.
      Returns:
      true if this instance is a DetachedPermazenTransaction, otherwise false

    • getDetachedTransaction

      public DetachedPermazenTransaction getDetachedTransaction()
      Get the default DetachedPermazenTransaction associated with this instance.

      The default DetachedPermazenTransaction uses ValidationMode.MANUAL.

      This instance must not itself be a DetachedPermazenTransaction; use createDetachedTransaction() to create additional detached transactions.

      Returns:
      the associated detached transaction
      Throws:
      IllegalArgumentException - if this instance is itself a DetachedPermazenTransaction
      See Also:

    • createDetachedTransaction

      public DetachedPermazenTransaction createDetachedTransaction(ValidationMode validationMode)
      Create a new, empty detached transaction.

      The returned transaction will have the same schema meta-data as this instance. It will be a mutable transaction, but being detached, changes can't be committed.

      The returned DetachedPermazenTransaction does not support commit() or rollback(). It can be used indefinitely after this transaction closes, but it must be close()'d when no longer needed to release any associated resources.

      Parameters:
      validationMode - the ValidationMode to use for the new transaction
      Returns:
      newly created detached transaction
      Throws:
      IllegalArgumentException - if validationMode is null
      StaleTransactionException - if this instance is no longer usable

    • createSnapshotTransaction

      public DetachedPermazenTransaction createSnapshotTransaction(ValidationMode validationMode)
      Create a new detached transaction pre-populated with a snapshot of this transaction.

      The returned transaction will have the same schema meta-data and object content as this instance. It will be a mutable transaction, but being detached, changes can't be committed.

      The returned DetachedPermazenTransaction does not support commit() or rollback(). It can be used indefinitely after this transaction closes, but it must be close()'d when no longer needed to release any associated resources.

      This method requires the underlying key/value transaction to support KVTransaction.readOnlySnapshot(). As with any other information extracted from this transaction, the returned content is not guaranteed to be valid until this transaction has been successfully committed.

      Parameters:
      validationMode - the ValidationMode to use for the new transaction
      Returns:
      newly created detached transaction
      Throws:
      IllegalArgumentException - if validationMode is null
      UnsupportedOperationException - if they underlying key/value transaction doesn't support KVTransaction.readOnlySnapshot()
      StaleTransactionException - if this instance is no longer usable

    • copyTo

      public void copyTo(PermazenTransaction dest, CopyState copyState, ObjIdSet ids)
      Copy the specified objects into the specified destination transaction.

      This is a convenience method; equivalent to copyTo(PermazenTransaction, 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(PermazenTransaction dest, CopyState copyState, Stream<? extends PermazenObject> pobjs)
      Copy the specified objects into the specified destination transaction.

      If a target object does not exist, it will be created, otherwise its schema will be migrated to match the source object if necessary (with resulting @OnSchemaChange notifications). If CopyState.isSuppressNotifications() returns false, @OnCreate and @OnChange notifications will also be delivered.

      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 schemas encountered, those schemas must be identical in both transactions.

      If dest is not a DetachedPermazenTransaction and any copied objects contain reference fields configured with PermazenField.allowDeleted()= false, then any objects referenced by those fields must also be copied, or else must already exist in dest. 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
      pobjs - 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
      UnknownTypeException - if any source object's type does not exist in dest
      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

    • cascade

      public Iterator<ObjId> cascade(ObjId id, int maxDistance, ObjIdSet visited, String... cascades)
      Find all objects reachable through the specified reference cascades.

      This method finds all objects reachable from the given starting object through forward and inverse reference field cascades with the specified names. In other words, a reference field is traversed in the forward or inverse direction if any of the given cascades are found in the field's @PermazenField.forwardCascades() or @PermazenField.inverseCascades() annotation property, respectively.

      The visited set contains the ID's of objects already visited (or is empty if none); these objects will not be traversed. In particular, if id is in visited, then this method does nothing. Upon return, visited will have had all of the new objects found added.

      All new objects found will be migrated to the this transaction's schema if necessary.

      The maxDistance parameter can be used to limit the maximum distance of any reachable object, measured in the number of reference field hops from the starting object. If a value other than -1 is given, objects will be visited in breadth-first manner (i.e., ordered by distance) and the search is truncated at maxDistance hops. If -1 is given, there is no limit and also no implied ordering of the objects in the iteration.

      Parameters:
      id - starting object ID
      maxDistance - the maximum number of reference fields to hop through, or -1 for no limit
      visited - on entry objects already visited, on return all objects reached
      cascades - zero or more reference cascade names
      Returns:
      iteration of reachable objects
      Throws:
      DeletedObjectException - if any object containing a traversed reference field does not actually exist
      IllegalArgumentException - if maxDistance is less than -1
      IllegalArgumentException - if any parameter is null
      See Also:

    • get

      public PermazenObject 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 by this transaction.

      A non-null object is always returned, but the corresponding object may not actually exist in this transaction. If not, attempts to access its fields will throw DeletedObjectException. Use PermazenObject.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 UntypedPermazenObject is returned.

      Parameters:
      id - object ID
      Returns:
      Java model object
      Throws:
      IllegalArgumentException - if id is null
      See Also:

    • 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 by this transaction.

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

      This method just invokes 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 either parameter is null
      See Also:

    • get

      public <T extends PermazenObject> T get(T pobj)
      Get the Java model object with the same object ID as the given PermazenObject 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. If not, attempts to access its fields will throw DeletedObjectException. Use PermazenObject.exists() to check.

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

      Type Parameters:
      T - expected Java type
      Parameters:
      pobj - Java model object
      Returns:
      Java model object in this transaction with the same object ID (possibly pobj itself)
      Throws:
      IllegalArgumentException - if pobj 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 pobj
      See Also:

    • 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(PermazenClass<T> pclass)
      Create a new instance of the given type in this transaction.
      Type Parameters:
      T - Java model type
      Parameters:
      pclass - object type
      Returns:
      newly created instance
      Throws:
      IllegalArgumentException - if pclass is null or not valid for this instance
      StaleTransactionException - if this transaction is no longer usable

    • delete

      public boolean delete(PermazenObject pobj)
      Delete the object with the given object ID in this transaction.

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

      Parameters:
      pobj - 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
      IllegalArgumentException - if pobj 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, PermazenObject.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
      IllegalArgumentException - if id is null

    • recreate

      public boolean recreate(PermazenObject pobj)
      Recreate the given instance in this transaction.

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

      Parameters:
      pobj - 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
      IllegalArgumentException - if pobj 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, PermazenObject.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

    • migrateSchema

      public boolean migrateSchema(PermazenObject pobj)
      Update the schema of the specified object, if necessary, so that it matches the schema associated with this instance's Permazen.

      If a schema change occurs, @OnSchemaChange methods will be invoked prior to this method returning.

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

      Parameters:
      pobj - object to update
      Returns:
      true if the object's schema was migrated, false if it was already updated
      Throws:
      StaleTransactionException - if this transaction is no longer usable
      DeletedObjectException - if pobj does not exist in this transaction
      TypeNotInSchemaException - if the current schema does not contain the object's type
      IllegalArgumentException - if pobj is null

    • registerPermazenObject

      public static void registerPermazenObject(PermazenObject pobj)
      Ensure the given PermazenObject 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 PermazenObject is fully constructed and associated with its PermazenTransaction.

      Parameters:
      pobj - object to register
      Throws:
      IllegalArgumentException - if pobj is null

    • readSimpleField

      public Object readSimpleField(ObjId id, String fieldName, boolean migrateSchema)
      Read a simple field.

      This returns the value returned by Transaction.readSimpleField() with ObjIds converted into PermazenObjects, etc.

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

      Parameters:
      id - ID of the object containing the field
      fieldName - the name of the PermazenSimpleField
      migrateSchema - true to automatically migrate the object's schema, false to not change it
      Returns:
      the 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 PermazenSimpleField corresponding to fieldName in id exists
      TypeNotInSchemaException - if migrateSchema is true but the object has a type that does not exist in this instance's schema
      IllegalArgumentException - if id or fieldName is null

    • writeSimpleField

      public void writeSimpleField(PermazenObject pobj, String fieldName, Object value, boolean migrateSchema)
      Write a simple field.

      This writes the value via Transaction.writeSimpleField() after converting PermazenObjects into ObjIds, etc.

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

      Parameters:
      pobj - object containing the field
      fieldName - the name of the PermazenSimpleField
      value - new value for the field
      migrateSchema - true to automatically migrate the object's schema, false to not change it
      Throws:
      StaleTransactionException - if this transaction is no longer usable
      DeletedObjectException - if pobj does not exist in this transaction
      UnknownFieldException - if no PermazenSimpleField corresponding to fieldName exists
      TypeNotInSchemaException - if migrateSchema is true but pobj has a type that does not exist in this instance's schema
      IllegalArgumentException - if value is not an appropriate value for the field
      IllegalArgumentException - if pobj or fieldName is null

    • readCounterField

      public Counter readCounterField(ObjId id, String fieldName, boolean migrateSchema)
      Read a counter field.

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

      Parameters:
      id - ID of the object containing the field
      fieldName - the name of the PermazenCounterField
      migrateSchema - true to automatically migrate the object's schema, false to not change it
      Returns:
      the 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 PermazenCounterField corresponding to fieldName exists
      TypeNotInSchemaException - if migrateSchema is true but the object has a type that does not exist in this instance's schema
      IllegalArgumentException - if id or fieldName is null

    • readSetField

      public NavigableSet<?> readSetField(ObjId id, String fieldName, boolean migrateSchema)
      Read a set field.

      This returns the set returned by Transaction.readSetField() with ObjIds converted into PermazenObjects, etc.

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

      Parameters:
      id - ID of the object containing the field
      fieldName - the name of the PermazenSetField
      migrateSchema - true to automatically migrate the object's schema, false to not change it
      Returns:
      the 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 PermazenSetField corresponding to fieldName exists
      TypeNotInSchemaException - if migrateSchema is true but the object has a type that does not exist in this instance's schema
      IllegalArgumentException - if id or fieldName is null

    • readListField

      public List<?> readListField(ObjId id, String fieldName, boolean migrateSchema)
      Read a list field.

      This returns the list returned by Transaction.readListField() with ObjIds converted into PermazenObjects, etc.

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

      Parameters:
      id - ID of the object containing the field
      fieldName - the name of the PermazenListField
      migrateSchema - true to automatically migrate the object's schema, false to not change it
      Returns:
      the 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 PermazenListField corresponding to fieldName exists
      TypeNotInSchemaException - if migrateSchema is true but the object has a type that does not exist in this instance's schema
      IllegalArgumentException - if id or fieldName is null

    • readMapField

      public NavigableMap<?,?> readMapField(ObjId id, String fieldName, boolean migrateSchema)
      Read a map field.

      This returns the map returned by Transaction.readMapField() with ObjIds converted into PermazenObjects, etc.

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

      Parameters:
      id - ID of the object containing the field
      fieldName - the name of the PermazenMapField
      migrateSchema - true to automatically migrate the object's schema, false to not change it
      Returns:
      the 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 PermazenMapField corresponding to fieldName exists
      TypeNotInSchemaException - if migrateSchema is true but the object has a type that does not exist in this instance's schema
      IllegalArgumentException - if id or fieldName is null

    • followReferencePath

      public NavigableSet<PermazenObject> followReferencePath(ReferencePath path, Stream<? extends PermazenObject> startObjects)
      Find all target 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:

    • invertReferencePath

      public NavigableSet<PermazenObject> invertReferencePath(ReferencePath path, Stream<? extends PermazenObject> targetObjects)
      Find all starting 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:

    • querySimpleIndex

      public <V, T> Index1<V,T> querySimpleIndex(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:
      T - Java type containing the field
      V - Java type corresponding to the indexed 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") unless there is only one sub-field (i.e., sets and lists but not maps)
      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:
      T - Java type containing the field
      V - Java type corresponding to the indexed list's element 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:
      T - Java type containing the field
      V - Java type corresponding to the indexed map's value 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:
      T - Java type containing the field
      V1 - Java type corresponding to the first indexed field
      V2 - Java type corresponding to the second indexed 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:
      T - Java type containing the field
      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
      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:
      T - Java type containing the field
      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
      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 Index<?> 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 PermazenSimpleField'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
      RetryKVTransactionException - 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.

    • isOpen

      public boolean isOpen()
      Determine whether this transaction is still usable.
      Returns:
      true if this transaction is still valid
      See Also:

    • 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:
      RetryKVTransactionException - 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:

    • 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

    • performAction

      public <T> T performAction(Supplier<T> action)
      Invoke the given Supplier 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
      Returns:
      result from action
      Throws:
      IllegalArgumentException - if action is null

    • withWeakConsistency

      public void withWeakConsistency(Runnable action)
      Apply weaker transaction consistency while performing the given action, if supported.

      Some key/value implementations support reads with weaker consistency guarantees. These reads generate fewer transaction conflicts but return possibly out-of-date information. Depending on the implementation, when operating in this mode writes may not be supported and may generate a IllegalStateException or just be ignored.

      The weaker consistency is only applied for the current thread, and it ends when this method returns.

      This method is for experts only; inappropriate use can result in a corrupted database. You should not make any changes to the database after this method returns based on any information read by the action.

      Parameters:
      action - the action to perform
      Throws:
      IllegalArgumentException - if action is null