4.4.4.1. EntityManager

EntityManager – main ORM interface, used to manage persistent entities.

Reference to the EntityManager may be obtained via the Persistence interface, by calling the getEntityManager() method. The retrieved instance of EntityManager is bound to the current transaction, i.e. all calls to getEntityManager() as part of one transaction return one and the same instance of EntityManager. After the end of transaction calls to the corresponding EntityManager instance are impossible.

An instance of EntityManager contains a "persistent context" – a set of instances loaded from DB or newly created. Persistent context is a kind of data cache within a transaction. EntityManager automatically flushes to DB all changes done in its persistent context at the moment when a transaction is committed or when the flush() method is called explictly.

EntityManager interface used in CUBA applications mainly copies the standard javax.persistence.EntityManager interface. Let us have a look at its main methods:

  • persist() – adds a new instance of the entity to the persistent context. When the transaction is committed a corresponding record is created in DB using SQL INSERT.

  • merge() – copies the state of detached instance to the persistent context the following way: an instance with the same identifier gets loaded from DB and the state of the passed Detached instance is copied into it and then the loaded Managed instance is returned. After that you should work with the returned Managed instance. The state of this entity will be stored in DB using SQL UPDATE on transaction commit.

  • remove() – removes an object from the database, or, if soft deletion mode is turned on, sets deleteTs and deletedBy attributes.

    If the passed instance is in Detached state, merge() is performed first.

  • find() – loads an entity instance by its identifier.

    When forming a request to the database the system considers the view which has been passed as a parameter to this method, or set to the entire EntityManager via setView(). As a result the persistent context will contain a graph of objects with all non-lazy view attributes loaded. The rest of the attributes may be loaded by calling the corresponding access methods of the entity, or by calling EntityManager.fetch().

  • createQuery() – creates a Query object for executing a JPQL query.

    We recommend using the variant of this method, which receives an entity class to return an instance of TypedQuery.

  • createNativeQuery() – creates a Query object to execute an SQL query.

  • setView() – sets the default view, which will be used for further loading of instance via find() or JPQL requests. As a result, all non-lazy attributes of the view will be eagerly fetched.

    Passing null to this method or not calling it at all will load the attributes according to entity annotations.

    The views explicitly passed to find() method or set in the Query object have a priority over the one set by this method.

  • addView() is similar to setView(), but does not replace the view if it was already set in the EntityManager. Instead it adds the attributes of the passed view to it.

  • fetch() – ensures loading of all attributes of the specified view for the entity instance, including lazy attributes. The entity instance should be in Managed state.

    We recommend calling this method before committing a transaction, if the view contains lazy attributes and the entity instance should be sent to the client tier. In this case, only calling fetch() will ensure that all attributes required by the client code have been actually loaded.

  • reload() – reloads the entity instance with the provided view. Ensures loading of all view attributes by calling fetch() internally.

  • isSoftDeletion() – checks if the EntityManager is in soft deletion mode.

  • setSoftDeletion() – sets soft deletion mode for this EntityManager.

  • getConnection() – returns a java.sql.Connection, which is used by this instance of EntityManager, and hence by the current transaction. Such connection does not need to be closed, it will be closed automatically when the transaction is complete.

  • getDelegate() – returns javax.persistence.EntityManager provided by the ORM implementation.

Prev  Up  Next
  Home