Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EclipseLink/Release/2.5/JPA21
Contents
EclipseLink JPA 2.1
This page contains a summary of the major features supported in EclipseLink that implements the JPA 2.1 (JSR 338) specification requirements. The features and examples on this page do not represent a complete list. For more information, please see: the JSR 338 page.
Bulk Update
Until JPA 2.1, performing deletes or updates was not available using the Criteria API. Through the addition of CriteriaUpdate/CriteriaDelete classes, support for bulkupdate/delete queries has now been added.
Update Example
The following example will update the salary and status, of all Employees who make less than 10000$, and give them a raise.
CriteriaUpdate<Employee> q = cb.createCriteriaUpdate(Employee.class); Root<Employee> emp = q.from(Employee.class); .set(e.get(Employee_.salary), cb.prod(e.get(Employee_.salary), 1.1f)) .set(e.get(Employee_.status), "full_time") .where(cb.lt(emp.get(Emploee_.salary), 10000));
The following Java Persistence query language update statement is equivalent.
UPDATE Employee e SET e.salary = e.salary * 1.1, e.status = "full_time" WHERE e.salary < 10000
Delete Example
The folowwing example deletes all the PhoneNumbers that are no longer in service
CriteriaDelete<PhoneNumber> q = cb.createCriteriaDelete(PhoneNumber.class); Root<PhoneNumber> p = q.from(PhoneNumber.class); q.where(cb.equal(p.get(PhoneNumber_.status), "out_of_service"),
The following Java Persistence query language delete statement is equivalent.
DELETE FROM PhoneNumber p WHERE p.status = 'out_of_service'
Stored Procedures
JPA specification 2.1 has introduced support for executing Stored Procedure calls. This includes a new StoredProcedureQuery API and Named Stored Procedure Queries (pre-existing portions of code on the database).
All the stored procedure examples below assume stored procedures already exist on the DB. Stored procedure creation is performed differently on different Databases. All the following example Stored procedure creation is using MySQL syntax.
Simple Result Set example
Creation of the Stored Procedure in MySQL
CREATE PROCEDURE getIds() BEGIN SELECT ID FROM CUSTOMER ORDER BY ID ASC; END !
Execution of Stored procedure
StoredProcedureQuery spq = em.createStoredProcedureQuery("getIds", Customer.class); List customers = spq.getResultList();
Alternatively, users can call spq.execute() directly (which is what getResultList() will call behind the scenes). The execute method will return a boolean indicating true if a result set is returned and false otherwise.
boolean result = spq.execute(); if (result == true) { customers = spq.getResultList(); } else { // Handle the false for no result set returned, e.g. throw new RuntimeException("No result set(s) returned from the stored procedure"); }
In parameter Example
Build the query:
StoredProcedureQuery spq = em.createStoredProcedureQuery("Update_Address_Postal_Code"); spq.registerStoredProcedureParameter("new_p_code_v", String.class, ParameterMode.IN); spq.registerStoredProcedureParameter("old_p_code_v", String.class, ParameterMode.IN);
Execute the query:
spq.setParameter("new_p_code_v", "123 NEW"); spq.setParameter("old_p_code_v", "321 OLD"); int updateCount = spq.executeUpdate();
Alternatively, the user could call the execute method directly (also note the parameters can be chained):
spq.setParameter("new_p_code_v", "123 NEW").setParameter("old_p_code_v", "321 OLD").execute(); int updateCount = spq.getUpdateCount();
OUT parameter Example
Build the query:
StoredProcedureQuery query = em.createStoredProcedureQuery("Read_Address_City"); query.registerStoredProcedureParameter("address_id_v", Integer.class, ParameterMode.IN); query.registerStoredProcedureParameter("city_v", String.class, ParameterMode.OUT);
Execute the query:
boolean resultSet = query.setParameter("address_id_v", "1").execute(); if (resultSet) { // Result sets must be processed first through getResultList() calls. } // Once the result sets and update counts have been processed, output parameters are available for processing. String city = (String) query.getOutputParameterValue("city_v");
IN/OUT parameter Example
Ref cursor Example
Named Stored Procedure Example
Named stored procedures are those that are specified through metadata and uniquely identified by name.
Annotation Example
@NamedStoredProcedureQuery( name = "ReadAddressByID", resultClasses = org.eclipse.persistence.testing.models.jpa21.advanced.Address.class, procedureName = "Read_Address", parameters = { @StoredProcedureParameter(mode=IN, name="address_id_v", type=Integer.class) } ) public Address() { .... }
XML Example
<named-stored-procedure-query name="ReadAddressByID" procedure-name="Read_Address"> <parameter name="address_id_v" mode="IN" class="Integer"/> <result-class>Address</result-class> </named-stored-procedure-query>
Execution
EntityManager em = createEntityManager(); em.createNamedStoredProcedureQuery("ReadAddressByID").setParameter("address_id_v", 1).getSingleResult();
Multiple result sets
JPQL function
The SQL spec and many databases have SQL functions that are not covered by the JPA specification. With the latest JPA specification the ability to call generic SQL functions was added to the JPQL syntax.
CDI Entity Listeners
Entity Listeners now support the Contexts and Dependency Injection API (CDI) when used inside a Java EE container. This support allows entity listeners to use CDI to inject objects and also provides support for @PostConstruct and @PreDestroy method calls.
CDI Example
The following example shows how a SessionBean can be injected into an EntityListener
public class LoggerEntityListener { @EJB protected LoggerBean logger; @PrePersist public void prePersist(Object object) { logger.log("prepersist", object); } @PostPersist public void postPersist(Object object){ logger.log("postpersist", object); } @PreDestroy public void preDestroy(){ logger.close(); } @PostConstruct public void postConstruct(){ logger.initialize(); } }
@Entity @EntityListeners({LoggerEntityListener.class}) public class MyLoggedEntity { ... }
Treat
Allows relationship joins to be treated as a subclass of the join type.
Converters
Provides control over the conversion from an attribute type and value to the corresponding database type and value
DDL generation
In previous versions for JPA, although DDL generation was present it was not standardized or required. JPA 2.1 has added standardized provider DDL generation and made DDL generation a requirement.
Entity Graphs
Entity graphs are subgraphs of the entity model metadata. The entity graph contains metamodel representations of a set of the entity classes' attributes and metamodel representations of related entity classes. A constructed entity graph can be used as a template for applying operations like attribute loading.