Package org.apache.openjpa.persistence

Interface OpenJPAEntityManager

  • All Superinterfaces:
    AutoCloseable, jakarta.persistence.EntityManager, jakarta.persistence.EntityTransaction
    All Known Subinterfaces:
    OpenJPAEntityManagerSPI
    All Known Implementing Classes:
    EntityManagerImpl
    public interface OpenJPAEntityManager
extends jakarta.persistence.EntityManager, jakarta.persistence.EntityTransaction
    Interface implemented by OpenJPA entity managers. This interface extends EntityTransaction, but this extension is deprecated.
    Since:
    0.4.0
    Author:
    Abe White

    • Method Detail

      • getEntityManagerFactory

        OpenJPAEntityManagerFactory getEntityManagerFactory()
        Return the factory that produced this entity manager.
        Specified by:
        getEntityManagerFactory in interface jakarta.persistence.EntityManager

      • getFetchPlan

        FetchPlan getFetchPlan()
        Return the (mutable) fetch plan for loading objects from this entity manager.

      • pushFetchPlan

        FetchPlan pushFetchPlan()
        Pushes a new fetch plan that inherits from the current fetch plan onto a stack, and makes the new plan the active one.
        Returns:
        the new fetch plan
        Since:
        1.1.0

      • popFetchPlan

        void popFetchPlan()
        Pops the fetch plan from the top of the stack, making the next one down the active one. This returns void to avoid confusion, since fetch plans tend to be used in method-chaining patterns often.
        Since:
        1.1.0

      • getConnectionRetainMode

        ConnectionRetainMode getConnectionRetainMode()
        Return the connection retain mode for this entity manager.

      • isTransactionManaged

        boolean isTransactionManaged()
        Whether this entity manager is using managed transactions.
        Since:
        1.1.0

      • isManaged

        @Deprecated
boolean isManaged()
        Deprecated.
        use isTransactionManaged() instead to interrogate whether or not this EntityManager's transaction is managed. To determine if a given entity instance is managed, use EntityManager.contains(java.lang.Object).

      • getSyncWithManagedTransactions

        boolean getSyncWithManagedTransactions()
        Whether to check for a global transaction upon every managed, non-transactional operation. Defaults to false.

      • setSyncWithManagedTransactions

        void setSyncWithManagedTransactions​(boolean resync)
        Whether to check for a global transaction upon every managed, non-transactional operation. Defaults to false.

      • getClassLoader

        ClassLoader getClassLoader()
        Return the current thread's class loader at the time this entity manager was obtained from the factory.

      • getConnectionUserName

        String getConnectionUserName()
        Return the connection user name.

      • getConnectionPassword

        String getConnectionPassword()
        Return the connection password.

      • getMultithreaded

        boolean getMultithreaded()
        Whether the entity manager or its managed instances are used in a multithreaded environment.

      • setMultithreaded

        void setMultithreaded​(boolean multi)
        Whether the entity manager or its managed instances are used in a multithreaded environment.

      • getIgnoreChanges

        boolean getIgnoreChanges()
        Whether to take into account changes in the transaction when executing a query or iterating an extent.

      • setIgnoreChanges

        void setIgnoreChanges​(boolean ignore)
        Whether to take into account changes in the transaction when executing a query or iterating an extent.

      • getNontransactionalRead

        boolean getNontransactionalRead()
        Whether to allow nontransactional access to persistent state.

      • setNontransactionalRead

        void setNontransactionalRead​(boolean read)
        Whether to allow nontransactional access to persistent state.

      • getNontransactionalWrite

        boolean getNontransactionalWrite()
        Whether to allow nontransactional changes to persistent state.

      • setNontransactionalWrite

        void setNontransactionalWrite​(boolean write)
        Whether to allow nontransactional changes to persistent state.

      • getOptimistic

        boolean getOptimistic()
        Whether to use optimistic transactional semantics.

      • setOptimistic

        void setOptimistic​(boolean opt)
        Whether to use optimistic transactional semantics.

      • getRestoreState

        RestoreStateType getRestoreState()
        Whether to restore an object's original state on rollback.

      • setRestoreState

        void setRestoreState​(RestoreStateType restoreType)
        Whether to restore an object's original state on rollback.

      • getRetainState

        boolean getRetainState()
        Whether objects retain their persistent state on transaction commit.

      • setRetainState

        void setRetainState​(boolean retain)
        Whether objects retain their persistent state on transaction commit.

      • getDetachState

        DetachStateType getDetachState()
        Detach mode constant to determine which fields are part of the detached graph.

      • setDetachState

        void setDetachState​(DetachStateType type)
        Detach mode constant to determine which fields are part of the detached graph.

      • getAutoClear

        AutoClearType getAutoClear()
        Whether to clear state when entering a transaction.

      • setAutoClear

        void setAutoClear​(AutoClearType clearType)
        Whether to clear state when entering a transaction.

      • setAutoDetach

        void setAutoDetach​(AutoDetachType value)
        AutoDetachType values which indicate when persistent managed objects should be automatically detached in-place. The current value is replaced in its entirety.

      • setAutoDetach

        void setAutoDetach​(EnumSet<AutoDetachType> values)
        AutoDetachType values which indicate when persistent managed objects should be automatically detached in-place. The current value is replaced in its entirety.

      • setAutoDetach

        void setAutoDetach​(AutoDetachType value,
                   boolean on)
        Bit flags marked in AutoDetachType which indicate when persistent managed objects should be automatically detached in-place.
        Since:
        1.1.0

      • getEvictFromStoreCache

        boolean getEvictFromStoreCache()
        Whether to also evict an object from the store cache when it is evicted through this entity manager.

      • setEvictFromStoreCache

        void setEvictFromStoreCache​(boolean evict)
        Whether to also evict an object from the store cache when it is evicted through this entity manager.

      • getPopulateStoreCache

        boolean getPopulateStoreCache()
        Whether objects accessed during this transaction will be added to the store cache. Defaults to true.
        Since:
        0.3.4

      • setPopulateStoreCache

        void setPopulateStoreCache​(boolean cache)
        Whether to populate the store cache with objects used by this transaction. Defaults to true.
        Since:
        0.3.4

      • isTrackChangesByType

        boolean isTrackChangesByType()
        Whether memory usage is reduced during this transaction at the expense of tracking changes at the type level instead of the instance level, resulting in more aggressive cache invalidation.
        Since:
        1.0.0

      • setTrackChangesByType

        void setTrackChangesByType​(boolean track)
        If a large number of objects will be created, modified, or deleted during this transaction setting this option to true will reduce memory usage if you perform periodic flushes by tracking changes at the type level instead of the instance level, resulting in more aggressive cache invalidation.
        Since:
        1.0.0

      • putUserObject

        Object putUserObject​(Object key,
                     Object val)
        Put the specified key-value pair into the map of user objects. Use a value of null to remove the key.

      • getUserObject

        Object getUserObject​(Object key)
        Get the value for the specified key from the map of user objects.

      • findAll

        <T> T[] findAll​(Class<T> cls,
                Object... oids)
        Return the objects with the given oids.
        Parameters:
        oids - the oids of the objects to return
        Returns:
        the objects that were looked up, in the same order as the oids parameter.
        See Also:
        EntityManager.find(Class,Object)

      • findAll

        <T> Collection<T> findAll​(Class<T> cls,
                          Collection oids)
        Return the objects with the given oids.
        Parameters:
        oids - the oids of the objects to return
        Returns:
        the objects that were looked up, in the same order as the oids parameter.
        See Also:
        EntityManager.find(Class,Object)

      • findCached

        <T> T findCached​(Class<T> cls,
                 Object oid)
        Return the cached instance for the given oid/object, or null if not cached.
        Parameters:
        oid - the object's id
        Returns:
        the cached object, or null if not cached

      • getObjectIdClass

        Class getObjectIdClass​(Class pcClass)
        Return the application identity class the given persistent class uses for object ids, or null if not a type that uses application identity.

      • getTransaction

        OpenJPAEntityTransaction getTransaction()
        Specified by:
        getTransaction in interface jakarta.persistence.EntityManager

      • setSavepoint

        void setSavepoint​(String name)
        Set a transactional savepoint where operations after this savepoint will be rolled back.

      • rollbackToSavepoint

        void rollbackToSavepoint()
        Rollback the current transaction to the last savepoint. Savepoints set after this one will become invalid.

      • rollbackToSavepoint

        void rollbackToSavepoint​(String name)
        Rollback the current transaction to the given savepoint name. Savepoints set after this one will become invalid.

      • releaseSavepoint

        void releaseSavepoint()
        Release the last set savepoint and any resources associated with it. The given savepoint and any set after it will become invalid.

      • releaseSavepoint

        void releaseSavepoint​(String name)
        Release the savepoint and any resources associated with it. The given savepoint and any set after it will become invalid.

      • preFlush

        void preFlush()
        Run pre-flush actions on transactional objects, including persistence-by-reachability, inverse relationship management, deletion of dependent instances, and instance callbacks. Transaction listeners are not invoked.
        Since:
        0.3.3

      • validateChanges

        void validateChanges()
        Validate the changes made in this transaction, reporting any optimistic violations, constraint violations, etc. In a datastore transaction or a flushed optimistic transaction, this method will act just like EntityManager.flush(). In an optimistic transaction that has not yet begun a datastore-level transaction, however, it will only report exceptions that would occur on flush, without retaining any datastore resources.

      • isStoreActive

        boolean isStoreActive()
        Whether a store transaction is active.

      • beginStore

        void beginStore()
        Begins a store transaction if one isn't already started. The entity manager must already be in a logical transaction.

      • containsAll

        boolean containsAll​(Object... pcs)
        Whether the given objects are managed.

      • containsAll

        boolean containsAll​(Collection pcs)
        Whether the given objects are managed.

      • persistAll

        void persistAll​(Object... pcs)
        Persist the given objects.

      • persistAll

        void persistAll​(Collection pcs)
        Persist the given objects.

      • removeAll

        void removeAll​(Object... pcs)
        Delete the given persistent objects.

      • removeAll

        void removeAll​(Collection pcs)
        Delete the given persistent objects.

      • release

        void release​(Object pc)
        Release the given object from management. This operation is not recursive.

      • releaseAll

        void releaseAll​(Object... pcs)
        Release the given object from management. This operation is not recursive.

      • releaseAll

        void releaseAll​(Collection pcs)
        Release the given objects from management. This operation is not recursive.

      • retrieve

        void retrieve​(Object pc)
        Immediately load the given object's persistent fields. One might use this action to make sure that an instance's fields are loaded before transitioning it to transient. Note that this action is not recursive. Any related objects that are loaded will not necessarily have their fields loaded.

      • refreshAll

        void refreshAll​(Object... pcs)
        Refresh the state of the given objects.

      • refreshAll

        void refreshAll​(Collection pcs)
        Refresh the state of the given objects.

      • refreshAll

        void refreshAll()
        Refresh all transactional objects.

      • evict

        void evict​(Object pc)

        Evict the given object.

        Eviction acts as a hint to the persistence provider, and indicates that the persistent object is no longer needed by the application and may be garbage collected. It does not remove the object from the L1 cache and only affects objects which are managed and unmodified.

        Parameters:
        pc - A persistent class which will be evicted

      • evictAll

        void evictAll​(Object... pcs)

        Evict the given objects.

        Eviction acts as a hint to the persistence provider, and indicates that the persistent object is no longer needed by the application and may be garbage collected. It does not remove the object from the L1 cache and only affects objects which are managed and unmodified.

        Parameters:
        pcs - The persistent classes which will be evicted

      • evictAll

        void evictAll​(Collection pcs)

        Evict the given objects.

        Eviction acts as a hint to the persistence provider, and indicates that the persistent object is no longer needed by the application and may be garbage collected. It does not remove the object from the L1 cache and only affects objects which are managed and unmodified.

        Parameters:
        pcs - A collection of persistent classes which will be evicted.

      • evictAll

        void evictAll()

        Evict all clean objects.

        Eviction acts as a hint to the persistence provider, and indicates that the persistent object is no longer needed by the application and may be garbage collected. It does not remove the object from the L1 cache and only affects objects which are managed and unmodified.

      • evictAll

        void evictAll​(Class cls)

        Evict all persistent-clean and persistent-nontransactional instances in the extent of the given class (including subclasses).

        Eviction acts as a hint to the persistence provider, and indicates that the persistent object is no longer needed by the application and may be garbage collected. It does not remove the object from the L1 cache and only affects objects which are managed and unmodified.

        Parameters:
        cls - All clean instances of this class will be evicted.

      • evictAll

        void evictAll​(Extent extent)

        Evict all persistent-clean and persistent-nontransactional instances in the given Extent.

        Eviction acts as a hint to the persistence provider, and indicates that the persistent object is no longer needed by the application and may be garbage collected. It does not remove the object from the L1 cache and only affects objects which are managed and unmodified.

        Parameters:
        extent - Extend which contains the persistent classes to evict.

      • detachCopy

        <T> T detachCopy​(T pc)
        Detach the specified object from the entity manager, detaching based on the AutoDetach value specified and returning a copy of the detached entity.
        Parameters:
        pc - the instance to detach
        Returns:
        the detached instance
        Since:
        2.0.0 Note: This method provides the same contract as the detach method with signature: public T detach(T pc) available in the 1.x release of OpenJPA. The JPA 2.0 specification defined a method with an incompatible signature and different semantics. The specification defined method trumped the existing method.

      • detachAll

        Collection detachAll​(Collection pcs)
        Detach the specified objects from the entity manager.
        Parameters:
        pcs - the instances to detach
        Returns:
        the detached instances

      • detachAll

        Object[] detachAll​(Object... pcs)
        Detach the specified objects from the entity manager.
        Parameters:
        pcs - the instances to detach
        Returns:
        the detached instances

      • mergeAll

        Object[] mergeAll​(Object... pcs)
        Merge the specified objects into the entity manager.
        Parameters:
        pcs - instances to import
        Returns:
        the re-attached instances

      • mergeAll

        Collection mergeAll​(Collection pcs)
        Merge the specified detached objects into the entity manager.
        Parameters:
        pcs - Collection of instances to import
        Returns:
        the re-attached instances

      • transactional

        void transactional​(Object pc,
                   boolean updateVersion)
        Make the given object transactional.
        Parameters:
        pc - instance to make transactional
        updateVersion - if true, the instance's version will be incremented at the next flush

      • transactionalAll

        void transactionalAll​(Collection objs,
                      boolean updateVersion)
        Make the given objects transactional.
        Parameters:
        objs - instances to make transactional
        updateVersion - if true, the instance's version will be incremented at the next flush

      • transactionalAll

        void transactionalAll​(Object[] objs,
                      boolean updateVersion)
        Make the given objects transactional.
        Parameters:
        objs - instances to make transactional
        updateVersion - if true, the instance's version will be incremented at the next flush

      • nontransactional

        void nontransactional​(Object pc)
        Make the given object nontransactional.

      • nontransactionalAll

        void nontransactionalAll​(Collection objs)
        Make the given objects nontransactional.

      • nontransactionalAll

        void nontransactionalAll​(Object[] objs)
        Make the given objects nontransactional.

      • getNamedGenerator

        Generator getNamedGenerator​(String name)
        Return the named generator defined in the metadata.

      • getIdGenerator

        Generator getIdGenerator​(Class forClass)
        Returns a Generator for the datastore identity values of the specified type, or null if the type is unmanaged or its identity cannot be represented by a sequence.

      • getFieldGenerator

        Generator getFieldGenerator​(Class forClass,
                            String fieldName)
        Returns a Generator for the generated values of the specified type, or null if the field is not generated.

      • createExtent

        <T> Extent<T> createExtent​(Class<T> cls,
                           boolean subs)
        Return an extent of the given class, optionally including subclasses.

      • createQuery

        OpenJPAQuery createQuery​(String query)
        Specified by:
        createQuery in interface jakarta.persistence.EntityManager

      • createNamedQuery

        OpenJPAQuery createNamedQuery​(String name)
        Specified by:
        createNamedQuery in interface jakarta.persistence.EntityManager

      • createNativeQuery

        OpenJPAQuery createNativeQuery​(String sql)
        Specified by:
        createNativeQuery in interface jakarta.persistence.EntityManager

      • createNativeQuery

        OpenJPAQuery createNativeQuery​(String sql,
                               Class resultClass)
        Specified by:
        createNativeQuery in interface jakarta.persistence.EntityManager

      • createNativeQuery

        OpenJPAQuery createNativeQuery​(String sql,
                               String resultMapping)
        Specified by:
        createNativeQuery in interface jakarta.persistence.EntityManager

      • createQuery

        OpenJPAQuery createQuery​(jakarta.persistence.Query query)
        Create a new query from the given one.

      • createDynamicQuery

        OpenJPAQuery createDynamicQuery​(QueryDefinition dynamic)
        Create an executable query from a dynamically defined query.
        Since:
        2.0.0

      • getLockMode

        jakarta.persistence.LockModeType getLockMode​(Object pc)
        Return the lock mode of the given instance, or null if not locked.
        Specified by:
        getLockMode in interface jakarta.persistence.EntityManager

      • lock

        void lock​(Object pc,
          jakarta.persistence.LockModeType mode,
          int timeout)
        Ensure that the given instance is locked at the given lock level.
        Parameters:
        pc - the object to lock
        mode - the lock level to use
        timeout - the number of milliseconds to wait for the lock before giving up, or -1 for no limit

      • lock

        void lock​(Object pc)
        Ensure that the given instance is locked at the current lock level, as set in the FetchPlan for the entity manager.

      • lockAll

        void lockAll​(Collection pcs,
             jakarta.persistence.LockModeType mode,
             int timeout)
        Ensure that the given instances are locked at the given lock level.
        Parameters:
        pcs - the objects to lock
        mode - the lock level to use
        timeout - the number of milliseconds to wait for the lock before giving up, or -1 for no limit

      • lockAll

        void lockAll​(Collection pcs)
        Ensure that the given instances are locked at the current lock level, as set in the FetchPlan for the entity manager.

      • lockAll

        void lockAll​(Object[] pcs,
             jakarta.persistence.LockModeType mode,
             int timeout)
        Ensure that the given instances are locked at the given lock level.
        Parameters:
        pcs - the objects to lock
        mode - the lock level to use
        timeout - the number of milliseconds to wait for the lock before giving up, or -1 for no limit

      • lockAll

        void lockAll​(Object... pcs)
        Ensure that the given instances are locked at the current lock level, as set in the FetchPlan for the entity manager.

      • cancelAll

        boolean cancelAll()
        Cancel all pending data store statements. If statements are cancelled while a flush is in progress, the transaction rollback only flag will be set.
        Returns:
        true if any statements were cancelled, false otherwise

      • getConnection

        Object getConnection()
        Return the connection in use by the entity manager, or a new connection if none.

      • getManagedObjects

        Collection getManagedObjects()
        Return a set of all managed instances.

      • getTransactionalObjects

        Collection getTransactionalObjects()
        Return a set of current transaction instances.

      • getPendingTransactionalObjects

        Collection getPendingTransactionalObjects()
        Return a set of instances which will become transactional upon the next transaction.

      • getDirtyObjects

        Collection getDirtyObjects()
        Return a set of current dirty instances.

      • getOrderDirtyObjects

        boolean getOrderDirtyObjects()
        Whether dirty objects will be returned in the order they were dirtied. Default is determined by the store manager.

      • setOrderDirtyObjects

        void setOrderDirtyObjects​(boolean order)
        Whether dirty objects will be returned in the order they were dirtied. Default is determined by the store manager.

      • dirtyClass

        void dirtyClass​(Class cls)
        Mark the given class as dirty within the current transaction.

      • getPersistedClasses

        Collection<Class> getPersistedClasses()
        Return the set of classes that have been made persistent in the current transaction.

      • getRemovedClasses

        Collection<Class> getRemovedClasses()
        Return the set of classes that have been deleted in the current transaction.

      • getUpdatedClasses

        Collection<Class> getUpdatedClasses()
        Return the set of classes for objects that have been modified in the current transaction.

      • createInstance

        <T> T createInstance​(Class<T> cls)
        Create a new instance of type cls. If cls is an interface or an abstract class whose abstract methods follow the JavaBeans convention, this method will create a concrete implementation according to the metadata that defines the class. If cls is a non-final concrete type that has metadata but does not implement PersistenceCapable, this method will create a subclass of the type that does implement PersistenceCapable, and will attempt to redefine the methods in cls to enable persistent attribute tracking. Otherwise, if cls is a managed type, this will return an instance of the specified class.
        Throws:
        IllegalArgumentException - if cls is not a managed type or interface.

      • dirty

        void dirty​(Object o,
           String field)
        Make the named field of the given object dirty.

      • getObjectId

        Object getObjectId​(Object o)
        Return the oid of the given instance.

      • isDirty

        boolean isDirty​(Object o)
        Return whether the given object is dirty.

      • isTransactional

        boolean isTransactional​(Object o)
        Return whether the given object is transactional.

      • isPersistent

        boolean isPersistent​(Object o)
        Return whether the given object is persistent.

      • isNewlyPersistent

        boolean isNewlyPersistent​(Object o)
        Return whether the given object was made persistent in the current transaction.

      • isRemoved

        boolean isRemoved​(Object o)
        Return whether the given object is deleted.

      • isDetached

        boolean isDetached​(Object o)
        Returns true if pc is a detached object (one that can be reattached to a EntityManager via a call to EntityManager.merge(T)); otherwise returns false.

      • getVersion

        Object getVersion​(Object o)
        Returns the current version indicator for o.

      • addTransactionListener

        @Deprecated
void addTransactionListener​(Object listener)
        Deprecated.
        cast to OpenJPAEntityManagerSPI instead. This method pierces the published-API boundary, as does the SPI cast.

      • removeTransactionListener

        @Deprecated
void removeTransactionListener​(Object listener)
        Deprecated.
        cast to OpenJPAEntityManagerSPI instead. This method pierces the published-API boundary, as does the SPI cast.

      • getTransactionListenerCallbackMode

        @Deprecated
int getTransactionListenerCallbackMode()
        Deprecated.
        cast to OpenJPAEntityManagerSPI instead. This method pierces the published-API boundary, as does the SPI cast.

      • setTransactionListenerCallbackMode

        @Deprecated
void setTransactionListenerCallbackMode​(int callbackMode)
        Deprecated.
        cast to OpenJPAEntityManagerSPI instead. This method pierces the published-API boundary, as does the SPI cast.

      • removeLifecycleListener

        @Deprecated
void removeLifecycleListener​(Object listener)
        Deprecated.
        cast to OpenJPAEntityManagerSPI instead. This method pierces the published-API boundary, as does the SPI cast.

      • getLifecycleListenerCallbackMode

        @Deprecated
int getLifecycleListenerCallbackMode()
        Deprecated.
        cast to OpenJPAEntityManagerSPI instead. This method pierces the published-API boundary, as does the SPI cast.

      • setLifecycleListenerCallbackMode

        @Deprecated
void setLifecycleListenerCallbackMode​(int callbackMode)
        Deprecated.
        cast to OpenJPAEntityManagerSPI instead. This method pierces the published-API boundary, as does the SPI cast.

      • begin

        @Deprecated
void begin()
        Deprecated.
        use EntityTransaction.begin() instead: em.getTransaction().begin()
        Specified by:
        begin in interface jakarta.persistence.EntityTransaction

      • commit

        @Deprecated
void commit()
        Deprecated.
        use EntityTransaction.commit() instead: em.getTransaction().commit()
        Specified by:
        commit in interface jakarta.persistence.EntityTransaction

      • rollback

        @Deprecated
void rollback()
        Deprecated.
        use EntityTransaction.rollback() instead: em.getTransaction().rollback()
        Specified by:
        rollback in interface jakarta.persistence.EntityTransaction

      • isActive

        @Deprecated
boolean isActive()
        Deprecated.
        use EntityTransaction.isActive() instead: em.getTransaction().isActive()
        Specified by:
        isActive in interface jakarta.persistence.EntityTransaction

      • setRollbackOnly

        @Deprecated
void setRollbackOnly()
        Deprecated.
        use EntityTransaction.setRollbackOnly() instead: em.getTransaction().setRollbackOnly()
        Specified by:
        setRollbackOnly in interface jakarta.persistence.EntityTransaction

      • getRollbackOnly

        @Deprecated
boolean getRollbackOnly()
        Deprecated.
        use EntityTransaction.getRollbackOnly() instead: em.getTransaction().getRollbackOnly()
        Specified by:
        getRollbackOnly in interface jakarta.persistence.EntityTransaction

      • getCriteriaBuilder

        OpenJPACriteriaBuilder getCriteriaBuilder()
        Gets the QueryBuilder with OpenJPA-extended capabilities.
        Specified by:
        getCriteriaBuilder in interface jakarta.persistence.EntityManager
        Since:
        2.0.0

      • getSupportedProperties

        Set<String> getSupportedProperties()
        Get the properties supported by this runtime.
        Since:
        2.0.0