Managing Entity Instances

Use

To manage entity instances, you trigger Entity Manager (EM) methods on them.

Entity instances become managed by the EM as a result of a persist, find, or merge operation, or as a result of a query. When the owning persistence context is closed, the entity becomes detached. In contrast to EJB 2.1, when entities in EJB 3.0 become detached, they can be passed directly to other components as data transfer objects.

The Java Persistence API also supports a detach and merge mechanism. Entities are detached from the EM at the end of the persistence context or when they get serialized. Detached entities can be manipulated in persistence-unaware environments like plain Java objects. They can also be merged into a different persistence context by the EM.

Procedure

Persisting Entity Instances

To make new entity instances managed and persistent, you use the persist() method of the EM.

Sample Code

To persist all projects, you generate a list of all projects and trigger persist() on each one.

                  List<Project> projects= dataDomain.getDemoProjects();
for (Project project : projects) {
        em.persist(project);
}

Finding Entity Instances

In an application, you may need to identify an entity instance in the database to perform operations on it. To find a particular entity instance against its primary key, you use the find() method of the EM.

Sample Code

The EM looks up the employeeId in the database and returns an instance of the employee with the given ID in the employee variable. You can then view and manipulate the data for this particular employee using the instance that is obtained.

                  public Employee findEmployeeById(int employeeId) {
        Employee employee = em.find(Employee.class, Integer.valueOf(employeeId));
        return employee;
}

Updating and Merging Detached Entity Instances

To update entities, you use the merge() method of the EM.

Sample Code

To update the data of employees of selected departments, you use the getAllDepartments() business method. Since the relationship employees of the entity Department is annotated with fetch type EAGER , the employees working in departments are loaded simultaneously with the departments. At the end of the getAllDepartments business method, the JTA transaction ends and the departments as well as the employees become detached. The changed employee data is synchronized with the database by the updateDepartment() business method.

                  public void updateDepartment(Department updatedDepartment) {
        em.merge(updatedDepartment);
}

The merge operation does the following:

Loads the Department entity with the same ID as the given detached Department entity from the database.
Copies all persistent properties from the detached department to the loaded department.
Since the relationship employees of the entity Department is annotated with cascade type ALL , the merge operation is cascaded to the detached employees accordingly.

More Information

Cascading Entity Manager Operations