Java Persistence API (JPA) Extensions Reference for EclipseLink, Release 2.4
  Go To Table Of Contents


Use @CacheIndex to define a cached index. Cache indexes are used only when caching is enabled.

Annotation Elements

Table 2-5 describes this annotation's elements.

Table 2-5 @CacheIndex Annotation Elements

Annotation Element Description Default


(Optional) The set of columns on which to define the index. Not required when annotated on a field/method.


(Optional) Specify if the indexed field is updateable.

If true, the object will be re-indexed on each update or refresh.



A cache index allows singleResult queries to obtain a cache hit when querying on the indexed fields. A resultList query cannot obtain cache hits, as it is unknown if all of the objects are in memory, (unless the cache usage query hint is used).

The index should be unique. If it is not, the first indexed object will be returned.

You can use @CacheIndex on an Entity class or on an attribute. The column is defaulted when defined on a attribute.


Example 2-13 shows an example of using the @CacheIndex annotation.

Example 2-13 Using @CacheIndex Annotation

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

Example 2-14 shows an example of using the <cache-index> XML element in the eclipselink-orm.xml file.

Example 2-14 Using <cache-index> XML

<?xml version="1.0"?>
    <entity name="Employee" class="org.acme.Employee" access="FIELD">
        <cache-index updateable="true">
            <id name="id"/>
            <basic name="ssn">
            <basic name="firstName">
                <column name="F_NAME"/>
            <basic name="lastName">
                <column name="L_NAME"/>

Example 2-15 shows an example query using a cache index.

Example 2-15 Caching an Index Query

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();

See Also

For more information, see: