Show TOC

Background documentationCaches in the JPA Implementation Locate this document in the navigation structure

 

An application that uses JPA reads an entity either explicitly (by executing a find or a query) or implicitly (by navigating to a related entity). To guarantee referential consistency, JPA first tries to locate an entity in the persistence context associated with the entity manager. Only if an entity is not found in the persistence context, does JPA retrieve its persistent state from the database. Therefore, the persistence context is also referred to as a “first level cache”.

However, when the persistence context is closed, it is cleared. In case of a transaction-scoped persistence context, this happens at the end of a transaction.

Many applications use entities that are frequently read but rarely changed. To avoid accessing the database upon each reading of such entities in a new persistence context, a server-side caching mechanism is necessary to outlast the persistence context. This is the “second level cache”.

For second-level caching on the object layer, the SAP implementation of JPA provides caching “read-only entities” in the “Entity cache”. If you are running JPA on the Open SQL layer, second level caching can also be achieved by using the table buffer to cache database rows.

More information:

Running JPA Applications on the System Data Source

Table Buffer

Read-Only Entities

A “read-only entity” is an entity that is not being changed by the application during its life cycle, that is, the application only inserts or reads entities of this class, but never changes or deletes these entities.

The JPA implementation by SAP allows declaring that selected entities are read-only. These can be specified, using the com.sap.jpa.cache.read-only-classes property in the persistence unit's properties section of the persistence.xml file.

More information: The persistence.xml File

Working with read-only entities has the following specifics:

  • The SAP implementation of JPA is not required to perform change tracking on read-only entities. If an application changes or deletes a read-only entity, the behavior is undefined.

  • Read-only entities must not be part of an inheritance hierarchy.

  • Declaring an entity as read-only also declares it to be “cacheable”.

    Only read-only entities are cacheable, currently.

Entity Cache

The Entity cache is a second level cache for entity instances that are declared to be cacheable. Upon retrieval of a cacheable entity, the SAP's JPA first looks for this entity in the persistence context, then in the Entity cache, and at last in the database. If the entity is found in the Entity cache, the JPA implementation does not return a copy of this entity, but a reference to the shared instance, which is stored in the cache.

Query Result Cache

The Query Result cache stores the result sets of JPQL queries or native queries. To hit the cache, a query must be executed subsequently with the same query text, the same parameter values and the same hints.

By default, no queries are cached. To indicate that a certain query is to be cached, you must set the com.sap.jpa.cache.query-result hint with the value cached on this query. The Query Result cache stores only the primary keys of the entities contained in the result set. Therefore, the Query Result cache must always be used in conjunction with the Entity cache or with the table buffer.

Note Note

  • To avoid reading old data, the Entity cache and the Query Result cache do not return data that is older than 20 minutes. Upon request, the relevant data is reread from the database instead.

    This timeout is not configurable, currently.

  • The JPA caches can be configured and monitored via the JPA Monitors tool in the SAP NetWeaver Administrator.

    More information: JPA Monitors

End of the note.
SAP Compliance Switch

The Entity cache and the Query Result cache cannot be used by applications that declare compliance with the SAP Product Standard.

To declare SAP Product Standard compliance, the SAP implementation of JPA uses the com.sap.jpa.compliance.sap-product-standard property in the persistence.xml file.

More information: The persistence.xml File

For more information about the SAP Product Standard compliance, refer to SAP Note 1169694.