Package cz.cvut.kbss.jopa.sessions

Interface UnitOfWork

All Superinterfaces:
ConfigurationHolder, MetamodelProvider, Wrapper
All Known Implementing Classes:
AbstractUnitOfWork, ChangeTrackingUnitOfWork, OnCommitChangePropagatingUnitOfWork, ReadOnlyUnitOfWork
public interface UnitOfWork extends ConfigurationHolder, MetamodelProvider, Wrapper
Represents a persistence context.

All interactions with objects managed in a persistence context are tracked by its corresponding UoW and on commit, the UoW propagates them into the repository.

  • Method Details

    • clear

      void clear()
      Clears this Unit of Work.

    • begin

      void begin()
      Notifies this Unit of Work that a transaction has begun.

    • commit

      void commit()
      Commit changes to the repository.

    • rollback

      void rollback()
      Rolls back changes done since last commit.
      See Also:

    • contains

      boolean contains(Object entity)
      Checks whether the specified entity is managed in this Unit of Work.
      Parameters:
      entity - Entity to check
      Returns:
      true if entity is managed, false otherwise

    • isActive

      boolean isActive()
      Is this Unit of Work active?
      Returns:
      boolean

    • isInTransaction

      boolean isInTransaction()
      Returns true if this UnitOfWork represents the persistence context of a currently running transaction.
      Returns:
      True if in an active transaction

    • isFlushingChanges

      boolean isFlushingChanges()
      Returns true if this Unit of Work is currently flushing changes to the repository.
      Returns:
      true if the UoW is flushing changes, false otherwise

    • isObjectManaged

      boolean isObjectManaged(Object entity)
      Return true if the given entity is managed.

      This means it is tracked by this persistence context either as a new object or an existing object loaded from the repository.

      Parameters:
      entity - Object to check
      Returns:
      true when the entity is managed, false otherwise

    • isObjectNew

      boolean isObjectNew(Object entity)
      Checks whether the specified entity has been registered in this Unit of Work as a new object for persist.
      Parameters:
      entity - Object to check
      Returns:
      true when entity is managed and new, false otherwise
      See Also:

    • isConsistent

      boolean isConsistent(URI context)
      Checks whether the specified repository context is consistent.
      Parameters:
      context - Context URI, null indicates the whole repository should be checked
      Returns:
      true if the context is consistent, false otherwise
      Throws:
      OWLPersistenceException - If an ontology access error occurs

    • loadEntityField

      <T> Object loadEntityField(T entity, FieldSpecification<? super T,?> fieldSpec)
      Loads value of the specified field for the specified entity.

      The value is set on the entity.

      Parameters:
      entity - The entity to load field for
      fieldSpec - Metamodel element representing the field to load
      Returns:
      The loaded field value
      Throws:
      NullPointerException - If entity or field is null
      OWLPersistenceException - If an error occurs, this may be e.g. that the field is not present on the entity, an ontology access error occurred etc.

    • mergeDetached

      <T> T mergeDetached(T entity, Descriptor descriptor)
      Merges the state of the given entity into the current persistence context.

      The descriptor argument specified the ontology contexts into which the detached entity and its fields belong and should be merged.

      Parameters:
      entity - entity instance
      descriptor - Entity descriptor, specifies repository context
      Returns:
      the managed instance that the state was merged to
      Throws:
      NullPointerException - If entity or repository is null

    • readObject

      <T> T readObject(Class<T> cls, Object identifier, Descriptor descriptor)
      Retrieves object with the specified identifier.

      The object as well as its fields are looked for in contexts specified by the descriptor. The result is then cast to the specified type.

      Parameters:
      cls - The type of the returned object
      identifier - Instance identifier
      descriptor - Entity descriptor
      Returns:
      The retrieved object or null if there is no object with the specified identifier in the specified repository
      Throws:
      NullPointerException - If cls, identifier or repository is null
      OWLPersistenceException - If an error occurs during object loading

    • readObjectWithoutRegistration

      <T> T readObjectWithoutRegistration(Class<T> cls, Object identifier, Descriptor descriptor)
      Reads an object but does not register it with this persistence context.

      Useful when the caller knows the object will be registered eventually by another routine.

      Parameters:
      cls - Expected result class
      identifier - Object identifier
      descriptor - Entity descriptor
      Returns:
      The retrieved object or null if there is no object with the specified identifier in the specified repository

    • readObjectFromAxioms

      <T> T readObjectFromAxioms(Class<T> cls, Collection<Axiom<?>> axioms, Descriptor descriptor)
      Reads an object from the specified axioms.

      It is assumed the axioms correspond to the provided descriptor.

      Type Parameters:
      T - Return type
      Parameters:
      cls - Expected result class
      axioms - Axioms representing the object
      descriptor - Entity descriptor
      Returns:
      The retrieved object or null if no object of the expected target class can be reconstructed

    • getReference

      <T> T getReference(Class<T> cls, Object identifier, Descriptor descriptor)
      Retrieves a reference to an object with the specified identifier.

      A reference is permitted to have its state fetched lazily.

      Type Parameters:
      T - Entity type
      Parameters:
      cls - The type of the returned object
      identifier - Instance identifier
      descriptor - Entity descriptor
      Returns:
      The retrieved object or null if none can be found
      Throws:
      OWLPersistenceException - If an error occurs during object loading

    • registerExistingObject

      Object registerExistingObject(Object object, Descriptor descriptor)
      Register an existing object in this Unit of Work.

      This is a shortcut for registerExistingObject(Object, CloneRegistrationDescriptor).

      Parameters:
      object - Object
      descriptor - Entity descriptor identifying repository contexts
      Returns:
      Registered clone of the specified object
      See Also:

    • registerExistingObject

      Object registerExistingObject(Object object, CloneRegistrationDescriptor registrationDescriptor)
      Register an existing object in this Unit of Work.

      Creates a working clone of the specified object according to the configuration and puts the given object into this Unit of Work cache.

      Parameters:
      object - Object
      registrationDescriptor - Configuration of the registration
      Returns:
      Registered clone of the specified object

    • registerNewObject

      void registerNewObject(Object object, Descriptor descriptor)
      Registers the specified new object in this Unit of Work.

      The object will be persisted into the context specified by descriptor.

      Parameters:
      object - The object to register
      descriptor - Entity descriptor
      Throws:
      NullPointerException - If entity or context is null
      OWLPersistenceException - If context is not a valid context URI or if an error during registration occurs

    • removeObject

      void removeObject(Object object)
      Remove the given object from the repository.
      Parameters:
      object - Object to remove

    • restoreRemovedObject

      void restoreRemovedObject(Object entity)
      Restores the specified removed object.

      This means it is reinstated as a managed entity and reinserted into the repository.

      Parameters:
      entity - The object to restore

    • putObjectIntoCache

      void putObjectIntoCache(Object identifier, Object entity, Descriptor descriptor)
      Puts the specified object into the live object cache.
      Parameters:
      identifier - Object identifier
      entity - Object to cache
      descriptor - Descriptor of repository context

    • removeObjectFromCache

      void removeObjectFromCache(Object object, URI context)
      Removes the specified object from the live object cache.

      This is particularly meant for merging deleted objects from transactions.

      Parameters:
      object - Object to remove from cache
      context - Entity context URI

    • release

      void release()
      Releases this unit of work.

      Releasing an active Unit of Work with uncommitted changes causes all pending changes to be discarded.

    • refreshObject

      <T> void refreshObject(T object)
      Refreshes the state of the specified object from the repository, overwriting any changes made to it.
      Type Parameters:
      T - Object type
      Parameters:
      object - The object to revert
      Throws:
      IllegalArgumentException - If the object is not managed

    • getCloneForOriginal

      Object getCloneForOriginal(Object original)
      Finds clone of the specified original object.
      Parameters:
      original - The original object whose clone we are looking for
      Returns:
      The clone or null, if there is none

    • unregisterObject

      void unregisterObject(Object object)
      Detaches the specified registered object from this Unit of Work.
      Parameters:
      object - Clone to detach

    • writeUncommittedChanges

      void writeUncommittedChanges()
      Writes any uncommitted changes into the ontology.

    • getContexts

      List<URI> getContexts()
      Gets repository contexts available to this session.
      Returns:
      Unmodifiable list of context URIs

    • getLoadStateRegistry

      LoadStateDescriptorRegistry getLoadStateRegistry()
      Gets the registry of entity load state descriptors.
      Returns:
      LoadStateDescriptorRegistry for this persistence context

    • isLoaded

      LoadState isLoaded(Object entity, String attributeName)
      Gets the load status of the specified attribute on the specified entity.
      Parameters:
      entity - Entity instance
      attributeName - Attribute whose load status is to be determined
      Returns:
      Attribute load status
      See Also:

    • isLoaded

      LoadState isLoaded(Object entity)
      Gets the load status of the specified entity.
      Parameters:
      entity - Entity whose load status is to be determined.
      Returns:
      Entity load status
      See Also:

    • getState

      EntityState getState(Object entity)
      Gets the lifecycle state of the specified entity.

      Note that since no repository is specified we can only determine if the entity is managed or removed. Therefore, if the case is different this method returns EntityState.NOT_MANAGED.

      Parameters:
      entity - Entity whose state to resolve
      Returns:
      Entity state

    • getState

      EntityState getState(Object entity, Descriptor descriptor)
      Gets the lifecycle state of the specified entity with respect to a repository context indicated by the specified descriptor.
      Parameters:
      entity - Entity whose state to resolve
      descriptor - Descriptor of repository contexts
      Returns:
      Entity state

    • isInferred

      <T> boolean isInferred(T entity, FieldSpecification<? super T,?> attribute, Object value)
      Checks whether the specified attribute value of the specified entity is inferred in the underlying repository.

      Note that given the nature of the repository implementation, this method may return true if the corresponding statement is both inferred and asserted. Also note that this method will use the descriptor associated with the specified entity in this persistence context to resolve the repository context, but some underlying repositories do not store inferences in data contexts, so the attribute context may be ignored.

      Parameters:
      entity - Entity whose attribute to examine. Must be managed by this persistence context
      attribute - Attribute whose value to examine
      value - The value whose inference to examine
      Returns:
      true if the entity attribute value is inferred, false otherwise

    • attributeChanged

      void attributeChanged(Object entity, Field f)
      Persists changed value of the specified field.
      Parameters:
      entity - Entity with changes (the clone)
      f - The field whose value has changed
      Throws:
      IllegalStateException - If this UoW is not in transaction
      See Also:

    • attributeChanged

      void attributeChanged(Object entity, FieldSpecification<?,?> fieldSpec)
      Persists changed value of the specified field.
      Parameters:
      entity - Entity with changes (the clone)
      fieldSpec - Metamodel element representing the attribute that changed
      Throws:
      IllegalStateException - If this UoW is not in transaction

    • createIndirectCollection

      Object createIndirectCollection(Object collection, Object owner, Field field)
      Creates an indirect collection that wraps the specified collection instance and propagates changes to this persistence context.
      Parameters:
      collection - Collection to be proxied
      owner - Collection owner instance
      field - Field filled with the collection
      Returns:
      Indirect collection

    • sparqlQueryFactory

      SparqlQueryFactory sparqlQueryFactory()
      Gets a SparqlQueryFactory instance associated with this persistence context.
      Returns:
      SPARQL query factory

    • getCriteriaBuilder

      CriteriaBuilder getCriteriaBuilder()
      Gets a CriteriaBuilder instance for building Criteria API queries.
      Returns:
      Criteria query builder