What’s New in Jakarta Persistence 3.1

A new version of the Jakarta Persistence specification, which defines a standard for managing persistence and object and relational mapping in Java environments, will be included in the Jakarta EE 10 release. The updated specification:

• Contains a few improvements and clarifications
• Completes several features introduced in previous releases
• Maintains backwards compatibility with previous releases

Here’s a closer look at some of the most important changes.

UUID Class Now Treated as Basic Java Type

One of the most interesting enhancements in Jakarta Persistence 3.1 is support for the java.util.UUID Java type.

The java.util.UUID type is now treated as a Basic type. It can also be used as a simple primary key or as a field or property of a composite primary key. If the java.util.UUID type is stored in a VARCHAR or an equivalent type of column, persistence providers are required to retain the type value in its canonical representation according to RFC 4122. Otherwise, the application must explicitly indicate that some other representation is preferred.

The java.util.UUID Java type is typically used in value generation. Therefore, the jakarta.persistence.GenerationType enum has been extended to support it.

@Entity
public class Item {
    @ID @GeneratedValue(strategy=GenerationType.UUID)
    private java.util.UUID id;
    private String description;
…
}

Note that if a field or property has the java.util.UUID type, the AUTO strategy is equivalent to UUID.

Extensions to Query Language and Criteria API

The most improved area in the Jakarta Persistence 3.1 specification is the Jakarta Persistence Query Language (QL) and the Criteria API. Improvements include:

• New numeric functions
• Special functions for local date and time 
• A standardized EXTRACT function from SQL 

Let’s take a brief look at these improvements.

New Numeric Functions

Every SQL database provides several math functions, but only a few were supported in a portable way in the Jakarta Persistence QL and Criteria API. The following table summarizes the new math functions supported in Jakarta Persistence QL, their counterparts in the CriteriaBuilder, and their descriptions.

Jakarta Persistence QL Function	CriteriaBuilder Method	Description
CEILING(arithmetic_expression)	ceiling()	Returns the ceiling of its argument: that is, the smallest integer greater than or equal to its argument.
EXP(arithmetic_expression)	exp()	Returns the exponential of its argument: that is, Euler's number e raised to the power of its argument.
FLOOR(arithmetic_expression)	floor()	Returns the floor of its argument: that is, the largest integer greater than or equal to its argument.
LN(arithmetic_expression)	ln()	Returns the natural logarithm of its argument.
POWER(arithmetic_expression, arithmetic_expression)	power()	Returns the first argument raised to the power of its second argument.
ROUND(arithmetic_expression, arithmetic_expression)	round()	Returns the first argument rounded to the number of decimal places given by the second argument.
SIGN(arithmetic_expression)	sign()	Returns the sign of its argument: that is, 1 if its argument is positive, -1 if its argument is negative, or 0 if its argument is zero.

Special Functions for Local Date and Time

Initial support for basic java.time java types was introduced in a previous version of the specification, but the functions for returning them were not. 

In Jakarta Persistence 3.1, new LOCAL DATE, LOCAL DATETIME, and LOCAL TIME functions for returning java.time.LocalDate, java.time.LocalDateTime, and java.time.LocalTime have been added. Existing CURRENT_DATE, CURRENT_TIME, and CURRENT_TIMESTAMP functions are still in place, but as use of java.sql.Date, java.sql.Time, and java.sql.Timestamp is going down, the newly introduced functions are recommended for use going forward.

The following table summarizes the new date/time related functions supported in Jakarta Persistence QL, their counterparts in the CriteriaBuilder, and their descriptions.

Jakarta Persistence QL Function	CriteriaBuilder Method	Description
LOCAL DATE	localDate()	Returns current local date as defined by the database server.
LOCAL DATETIME	localDateTime()	Returns current local date and time as defined by the database server.
LOCAL TIME	localTime()	Returns current local time as defined by the database server.

Standardized EXTRACT Function From SQL 

The EXTRACT function is defined to extract a numeric part from a given date and it can only retrieve a single field. In Jakarta Persistence QL, only a subset of the field types from EXTRACT, as defined by the SQL standard, are supported.

extract_datetime_field :=

    EXTRACT(datetime_field FROM datetime_expression)

datetime_field := identification_variable

Jakarta Persistence QL supports field type identifiers for which EXTRACT returns:

• An integer value
• A floating point value

EXTRACT returns an integer value for the following field type identifiers:

• YEAR, which is the calendar year.
• QUARTER, which is the calendar quarter, numbered from 1 to 4.
• MONTH, which is the calendar month of the year, numbered from 1.
• WEEK, which is the ISO-8601 week number.
• DAY, which is the calendar day of the month, numbered from 1.
• HOUR, which is the hour of the day in 24-hour time, numbered from 0 to 23.
• MINUTE, which is the minute of the hour, numbered from 0 to 59.

EXTRACT returns a floating point value for the following field type identifier:

• SECOND, which is the second of the minute, numbered from 0 to 59, including a fractional part representing fractions of a second.

Other Improvements

The Jakarta Persistence 3.1 specification also includes other minor improvements:

• jakarta.persistence.EntityManagerFactory and jakarta.persistence.EntityManager now implement an AutoCloseable interface. 
• There’s improved support for using the Specification API Java Archive (JAR) file on a Java Platform Module System (JPMS) by defining a module name for jakarta.persistence and fixing ClassTransformer to throw Persistence API specific exception to avoid transitive dependencies in the API’s Java module.
• Adds support for Expressions as conditions in Criteria CASE expressions
• The specification document clarifies the Basic type, the order of parameters in the LOCATE function, and contradictions related to mixing input parameter types.

Get Involved in Jakarta Persistence 

We welcome everyone interested in helping the Jakarta Persistence specification evolve to join the team. There are many ways to contribute. For more information:

• View the full list of changes
• See what’s going on in GitHub
• Subscribe to our mailing list