EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/Indexes

EclipseLink JPA

• EclipseLink Destinations:
• Documentation
• FAQ
• Examples
• Development

Key API

• @CacheIndex
• @CacheIndexes

Native API

• CachePolicy
• CacheIndex

Cache Indexes

The EclipseLink cache is indexed by the entities Id. This allows the find() operation, relationships, and queries by Id to obtain cache hits and avoid database access. The cache is not used by default for any non-Id query. All non-Id queries will access the database then resolve with the cache for each row returned in the result-set.

Applications tend to have other unique keys in their model in addition to their Id. This is quite common when a generated Id is used. The application frequently queries on these unique keys, and it is desirable to be able to obtain cache hits to avoid database access on these queries.

Cache indexes allow an in-memory index to be created in the EclipseLink cache to allow cache hits on non-Id fields. The cache index can be on a single field, or on a set of fields. The indexed fields can be updateable, and although they should be unique, this is not a requirement. Queries that contain the indexed fields will be able to obtain cache hits. Only single results can be obtained from indexed queries.

Cache indexes can be configured using the @CacheIndex and @CacheIndexes annotations and <cache-index> XML element. A @CacheIndex can be defined on the entity, or on an attribute to index the attribute. Indexes defined on the entity must define the columnNames used for the index. An index can be configured to be re-indexed when the object is updated using the updateable attribute.

It is still possible to cache query results for non-indexed queries using the query result cache, (see Query Results Cache).

Cache index annotation example

...
@Entity
@CacheIndex(columnNames={"F_NAME", "L_NAME"}, updateable=true)
public class Employee {
  @Id
  private long id;
  @CacheIndex
  private String ssn;
  @Column(name="F_NAME")
  private String firstName;
  @Column(name="L_NAME")
  private String lastName;
}

Cache index XML example

<?xml version="1.0"?>
<entity-mappings
	xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/orm"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/orm http://www.eclipse.org/eclipselink/xsds/eclipselink_orm_2_4.xsd"
	version="2.4">
    <entity name="Employee" class="org.acme.Employee" access="FIELD">
        <cache-index updateable="true">
            <column-name>F_NAME</column-name>
            <column-name>L_NAME</column-name>
        </cache-index>
        <attributes>
            <id name="id"/>
            <basic name="ssn">
                <cache-index/>
            </basic>
            <basic name="firstName">
                <column name="F_NAME"/>
            </basic>
            <basic name="lastName">
                <column name="L_NAME"/>
            </basic>
        </attributes>
    </entity>
</entity-mappings>

Cache index query example

Query query = em.createQuery("Select e from Employee e where e.firstName = :firstName and e.lastName = :lastName");
query.setParameter("firstName", "Bob");
query.setParameter("lastName", "Smith");
Employee employee = (Employee)query.getSingleResult();

Version: 2.4 DRAFT
Other versions...

Database Event Notification and Oracle DCN/QCN	Caching	Query Results Cache
EclipseLink Home JPA User Guide: Table of Contents, Search
How to contribute to this guide...