Package cz.cvut.kbss.jopa.model

Interface EntityManager

All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
AbstractEntityManager
All Known Implementing Classes:
EntityManagerImpl
public interface EntityManager extends AutoCloseable

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Clear the persistence context, causing all managed entities to become detached.
    void
    close()
    Close an application-managed EntityManager.
    boolean
    contains(Object entity)
    Check if the instance belongs to the current persistence context.
    default Descriptor
    createDescriptor(Class<?> cls)
    Creates a Descriptor for instances of the specified entity class.
    Query
    createNamedQuery(String name)
    Create an instance of Query for executing a named query (in native SPARQL).
    <T> TypedQuery<T>
    createNamedQuery(String name, Class<T> resultClass)
    Create an instance of TypedQuery for executing a SPARQL named query.
    Query
    createNativeQuery(String sparqlString)
    Create an instance of Query for executing a native SPARQL(-DL) query in SPARQL syntax.
    <T> TypedQuery<T>
    createNativeQuery(String sparqlString, Class<T> resultClass)
    Create an instance of Query for executing a native SPARQL(-DL) query returning only specific object type.
    Query
    createNativeQuery(String sparqlString, String resultSetMapping)
    Create an instance of Query for executing a native SPARQL query.
    <T> TypedQuery<T>
    createQuery(CriteriaQuery<T> criteriaQuery)
    Create an instance of TypedQuery for executing a criteria query.
    Query
    createQuery(String qlString)
    Create an instance of Query for executing a Java Persistence query language statement.
    <T> TypedQuery<T>
    createQuery(String query, Class<T> resultClass)
    Creates an instance of query for executing Java persistence query language statement.
    void
    detach(Object entity)
    Remove the given entity from the persistence context, causing a managed entity to become detached.
    <T> T
    find(Class<T> entityClass, Object identifier)
    Find by identifier.
    <T> T
    find(Class<T> entityClass, Object identifier, Descriptor descriptor)
    Find by identifier.
    void
    flush()
    Synchronize the persistence context to the underlying database.
    List<URI>
    getContexts()
    Returns a list of repository contexts available to this entity manager.
    CriteriaBuilder
    getCriteriaBuilder()
    Return a criteriaFactory for making CriteriaQuery.
    Object
    getDelegate()
    Return the underlying provider object for the EntityManager, if available.
    EntityManagerFactory
    getEntityManagerFactory()
    Return the entity manager factory for the entity manager.
    Metamodel
    getMetamodel()
    Return an instance of Metamodel interface for access to the metamodel of the persistence unit.
    Map<String,Object>
    getProperties()
    Get the properties and hints and associated values that are in effect for the entity manager.
    <T> T
    getReference(Class<T> entityClass, Object identifier)
    Get an instance, whose state may be lazily fetched.
    <T> T
    getReference(Class<T> entityClass, Object identifier, Descriptor descriptor)
    Get an instance, whose state may be lazily fetched.
    EntityTransaction
    getTransaction()
    Return the resource-level transaction object.
    boolean
    isConsistent(URI context)
    Checks consistency of the specified context.
    <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.
    boolean
    isOpen()
    Determine whether the EntityManager is open.
    <T> T
    merge(T entity)
    Merge the state of the given entity into the current persistence context.
    <T> T
    merge(T entity, Descriptor descriptor)
    Merge the state of the given entity into the current persistence context and into the repository specified by descriptor.
    void
    persist(Object entity)
    Make an instance managed and persistent.
    void
    persist(Object entity, Descriptor descriptor)
    Make an instance managed and persistent.
    void
    refresh(Object entity)
    Refresh the state of the instance from the data source, overwriting changes made to the entity, if any.
    void
    remove(Object entity)
    Remove the entity instance.
    void
    setProperty(String propertyName, Object value)
    Set an entity manager property or hint.
    <T> T
    unwrap(Class<T> cls)
    Return an object of the specified type to allow access to the provider-specific API.

  • Method Details

    • persist

      void persist(Object entity)
      Make an instance managed and persistent.

      The entity is persisted into the default context.

      Parameters:
      entity - entity instance
      Throws:
      OWLEntityExistsException - if the entity already exists. (The EntityExistsException may be thrown when the persist operation is invoked, or the EntityExistsException or another PersistenceException may be thrown at flush or commit time.)
      IllegalArgumentException - if not an entity
      NullPointerException - If entity is null
      TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.
      See Also:

    • persist

      void persist(Object entity, Descriptor descriptor)
      Make an instance managed and persistent.

      The descriptor represents repository and context into which the entity and its fields should be persisted.

      Parameters:
      entity - entity instance
      descriptor - Entity descriptor
      Throws:
      OWLEntityExistsException - if the entity already exists. (The EntityExistsException may be thrown when the persist operation is invoked, or the EntityExistsException or another PersistenceException may be thrown at flush or commit time.)
      IllegalArgumentException - if not an entity
      NullPointerException - If entity or descriptor is null
      TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

    • merge

      <T> T merge(T entity)
      Merge the state of the given entity into the current persistence context.

      The entity is merged into the default repository context.

      Parameters:
      entity - The entity to merge
      Returns:
      the instance that the state was merged to
      Throws:
      IllegalArgumentException - if instance is not an entity or is a removed entity
      TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

    • merge

      <T> T merge(T entity, Descriptor descriptor)
      Merge the state of the given entity into the current persistence context and into the repository specified by descriptor.
      Parameters:
      entity - The entity to merge
      descriptor - Entity descriptor
      Returns:
      the instance that the state was merged to
      Throws:
      IllegalArgumentException - if instance is not an entity or is a removed entity
      TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

    • remove

      void remove(Object entity)
      Remove the entity instance.
      Parameters:
      entity - The instance to remove
      Throws:
      IllegalArgumentException - if not an entity or if a detached entity
      TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

    • find

      <T> T find(Class<T> entityClass, Object identifier)
      Find by identifier.

      Search for an entity of the specified class and identifier. If the entity instance is contained in the persistence context, it is returned from there.

      Parameters:
      entityClass - Entity class
      identifier - Entity identifier
      Returns:
      the found entity instance or null if the entity does not exist in the given ontology context
      Throws:
      IllegalArgumentException - if the first argument does not denote an entity type or the second argument is not a valid type for that entity’s identifier
      NullPointerException - If entityClass, identifier is null

    • find

      <T> T find(Class<T> entityClass, Object identifier, Descriptor descriptor)
      Find by identifier.

      Search for an entity of the specified class and identifier. If the entity instance is contained in the persistence context, it is returned from there.

      The descriptor parameter represents repository and context in which the entity should be looked for.

      Parameters:
      entityClass - Entity class
      identifier - Entity identifier
      descriptor - Entity descriptor
      Returns:
      the found entity instance or null if the entity does not exist in the given ontology context
      Throws:
      IllegalArgumentException - if the first argument does not denote an entity type or the second argument is not a valid type for that entity’s identifier
      NullPointerException - If entityClass, identifier or contextUri is null
      See Also:

    • getReference

      <T> T getReference(Class<T> entityClass, Object identifier)
      Get an instance, whose state may be lazily fetched.

      If the requested instance does not exist in the database, the EntityNotFoundException is thrown when the instance state is first accessed. (The persistence provider runtime is permitted to throw the EntityNotFoundException when getReference is called.)

      The application should not expect that the instance state will be available upon detachment, unless it was accessed by the application while the entity manager was open.

      Parameters:
      entityClass - entity class
      identifier - identifier of the instance
      Returns:
      the found entity instance
      Throws:
      IllegalArgumentException - if the first argument does not denote an entity type or the second argument is not a valid type for that entity’s identifier

    • getReference

      <T> T getReference(Class<T> entityClass, Object identifier, Descriptor descriptor)
      Get an instance, whose state may be lazily fetched.

      If the requested instance does not exist in the database, the EntityNotFoundException is thrown when the instance state is first accessed. (The persistence provider runtime is permitted to throw the EntityNotFoundException when getReference is called.)

      The application should not expect that the instance state will be available upon detachment, unless it was accessed by the application while the entity manager was open.

      The descriptor parameter represents configuration of the entity loading (e.g., repository context).

      Parameters:
      entityClass - entity class
      identifier - identifier of the instance
      descriptor - Entity descriptor
      Returns:
      the found entity instance
      Throws:
      IllegalArgumentException - if the first argument does not denote an entity type or the second argument is not a valid type for that entity’s identifier

    • flush

      void flush()
      Synchronize the persistence context to the underlying database.
      Throws:
      TransactionRequiredException - if there is no transaction
      OWLPersistenceException - if the flush fails

    • refresh

      void refresh(Object entity)
      Refresh the state of the instance from the data source, overwriting changes made to the entity, if any.
      Parameters:
      entity - The entity instance to refresh
      Throws:
      IllegalArgumentException - if not an entity or entity is not managed
      TransactionRequiredException - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

    • clear

      void clear()
      Clear the persistence context, causing all managed entities to become detached. Changes made to entities that have not been flushed to the database will not be persisted.

    • detach

      void detach(Object entity)
      Remove the given entity from the persistence context, causing a managed entity to become detached. Unflushed changes made to the entity if any (including removal of the entity), will not be synchronized to the database. Entities which previously referenced the detached entity will continue to reference it.
      Parameters:
      entity - The instance to detach
      Throws:
      IllegalArgumentException - if the instance is not an entity

    • contains

      boolean contains(Object entity)
      Check if the instance belongs to the current persistence context.
      Parameters:
      entity - The instance to check
      Returns:
      True if the instance is managed, false otherwise
      Throws:
      IllegalArgumentException - if not an entity

    • isConsistent

      boolean isConsistent(URI context)
      Checks consistency of the specified context.

      The context URI can be null, which indicates that consistency of the whole repository should be verified.

      Parameters:
      context - Context URI, can be null
      Returns:
      true if consistent, false otherwise

    • 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

    • getProperties

      Map<String,Object> getProperties()
      Get the properties and hints and associated values that are in effect for the entity manager.

      Changing the contents of the map does not change the configuration in effect.

      Returns:
      Map of properties and hints in effect for entity manager

    • setProperty

      void setProperty(String propertyName, Object value)
      Set an entity manager property or hint.

      If a vendor-specific property or hint is not recognized, it is silently ignored.

      Parameters:
      propertyName - Name of property or hint
      value - Value for property or hint
      Throws:
      IllegalArgumentException - If the second argument is not valid for the implementation

    • createQuery

      Query createQuery(String qlString)
      Create an instance of Query for executing a Java Persistence query language statement.
      Parameters:
      qlString - a Java Persistence query string
      Returns:
      the new query instance
      Throws:
      IllegalArgumentException - if query string is not valid

    • createQuery

      <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery)
      Create an instance of TypedQuery for executing a criteria query.
      Parameters:
      criteriaQuery - criteria query object
      Returns:
      the new query instance

    • createQuery

      <T> TypedQuery<T> createQuery(String query, Class<T> resultClass)
      Creates an instance of query for executing Java persistence query language statement.
      Parameters:
      query - query string
      resultClass - result type
      Returns:
      the new query instance

    • createNamedQuery

      Query createNamedQuery(String name)
      Create an instance of Query for executing a named query (in native SPARQL).
      Parameters:
      name - the name of a query defined in metadata
      Returns:
      the new query instance
      Throws:
      IllegalArgumentException - if a query has not been defined with the given name

    • createNamedQuery

      <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass)
      Create an instance of TypedQuery for executing a SPARQL named query.

      The select list of the query must contain only a single item, which must be assignable to the type specified by the resultClass argument.

      Parameters:
      name - the name of a query defined in metadata
      resultClass - the type of the query result
      Returns:
      the new query instance
      Throws:
      IllegalArgumentException - if a query has not been defined with the given name or if the query string is found to be invalid or if the query result is found to not be assignable to the specified type

    • createNativeQuery

      Query createNativeQuery(String sparqlString)
      Create an instance of Query for executing a native SPARQL(-DL) query in SPARQL syntax.
      Parameters:
      sparqlString - a native SPARQL query string
      Returns:
      the new query instance

    • createNativeQuery

      <T> TypedQuery<T> createNativeQuery(String sparqlString, Class<T> resultClass)
      Create an instance of Query for executing a native SPARQL(-DL) query returning only specific object type.
      Parameters:
      sparqlString - a native SQL query string
      resultClass - the class of the resulting instance(s)
      Returns:
      the new query instance

    • createNativeQuery

      Query createNativeQuery(String sparqlString, String resultSetMapping)
      Create an instance of Query for executing a native SPARQL query.
      Parameters:
      sparqlString - a native SQL query string
      resultSetMapping - the name of the result set mapping
      Returns:
      the new query instance

    • unwrap

      <T> T unwrap(Class<T> cls)
      Return an object of the specified type to allow access to the provider-specific API. If the provider's EntityManager implementation does not support the specified class, the OWLPersistenceException is thrown.
      Parameters:
      cls - The class of the object to be returned. This can be also an implementation of the underlying driver
      Returns:
      an instance of the specified class
      Throws:
      OWLPersistenceException - If the provider does not support the specified class

    • getDelegate

      Object getDelegate()
      Return the underlying provider object for the EntityManager, if available. The result of this method is implementation specific.
      Returns:
      underlying provider object for EntityManager

    • close

      void close()
      Close an application-managed EntityManager. After the close method has been invoked, all methods on the EntityManager instance and any Query objects obtained from it will throw the IllegalStateException except for getTransaction and isOpen (which will return false). If this method is called when the EntityManager is associated with an active transaction, the persistence context remains managed until the transaction completes.
      Specified by:
      close in interface AutoCloseable
      Throws:
      IllegalStateException - if the EntityManager is container-managed.

    • isOpen

      boolean isOpen()
      Determine whether the EntityManager is open.
      Returns:
      true until the EntityManager has been closed.

    • getTransaction

      EntityTransaction getTransaction()
      Return the resource-level transaction object. The EntityTransaction instance may be used serially to begin and commit multiple transactions.
      Returns:
      EntityTransaction instance
      Throws:
      IllegalStateException - if invoked on a JTA EntityManager.

    • getEntityManagerFactory

      EntityManagerFactory getEntityManagerFactory()
      Return the entity manager factory for the entity manager.
      Returns:
      EntityManagerFactory instance
      Since:
      JPA 2.0

    • getContexts

      List<URI> getContexts()
      Returns a list of repository contexts available to this entity manager.
      Returns:
      List of repository context URIs

    • getCriteriaBuilder

      CriteriaBuilder getCriteriaBuilder()
      Return a criteriaFactory for making CriteriaQuery.
      Returns:
      CriteriaBuilder instance

    • getMetamodel

      Metamodel getMetamodel()
      Return an instance of Metamodel interface for access to the metamodel of the persistence unit.
      Returns:
      Metamodel instance

    • createDescriptor

      default Descriptor createDescriptor(Class<?> cls)
      Creates a Descriptor for instances of the specified entity class.
      Parameters:
      cls - Entity class to create descriptor for
      Returns:
      Entity descriptor