4.2. Organization of Data in the Cache

4.2. Organization of Data in the Cache
Prev	Chapter 4. Cache Eviction	Next

4.2.1. Region Prefix and Region Name

All FQNs in a second level cache include two elements:

A Region Prefix, which is simply any value assigned to the hibernate.cache.region_prefix Hibernate configuration property. If no Region Prefix is set, this portion of the FQN is omitted.

If different session factories are sharing the same underlying JBoss Cache instance(s) it is strongly encouraged that a distinct Region Prefix be assigned to each. This will help ensure that the different session factories cache their data in different subtrees in JBoss Cache.
A Region Name, which is either
- any value assigned to a <cache> element's region attribute in a class or collection mapping. See Section 4.2.2, “Entities” for an example.
- Any value assigned to a Hibernate Query object's cacheRegion property. See Section 4.2.4, “Queries” for an example.
- The escaped class name of the type being cached. An escaped class name is simply a fully-qualified class name with any . replaced with a / -- for example org/example/Foo.

4.2.2. Entities

The FQN for the cache region where entities of a particular class are stored is derived as follows:

/ + Region Prefix + / + Region Name + /ENTITY

If no region prefix was specified, the leading / and Region Prefix is not included in the FQN. So, if hibernate.cache.region_prefix was set to "appA" and a class was mapped like this:

<class name="org.example.Foo">
    <cache usage="transactional" region="foo_region"/>
    ....
</class>

The FQN of the region where Foo entities would be cached is /appA/foo_region/ENTITY.

If the class mapping does not include a region attribute, the region name is based on the name of the entity class, e.g.

<class name="org.example.Bar">
    <cache usage="transactional"/>
    ....
</class>

the FQN of the region where Bar entities would be cached is /appA/org/example/Bar/ENTITY.

4.2.3. Collections

The FQN for the cache region where entities of a particular class is stored is derived as follows:

/ + Region Prefix + / + Region Name + /COLL

So, let's say our example Foo entity included a collection field bars that we wanted to cache:

<class name="org.example.Foo">
    <cache usage="transactional"/>
    ....
    <set name="bars">
        <cache usage="transactional" region="foo_region"/>
        <key column="FOO_ID"/>
        <one-to-many class="org.example.Bar"/>
    </set>
</class>

The FQN of the region where the collection would be cached would be /appA/foo_region/COLL.

If the collection's <cache> element did not include a region, the FQN would be /appA/org/example/Foo/COLL.

4.2.4. Queries

Queries follow this pattern:

/ + Region Prefix + / + Region Name + /QUERY

Say we had the following query (again with a region prefix set to "appA"):

List blogs = sess.createQuery("from Blog blog " + 
                              "where blog.blogger = :blogger")
    .setEntity("blogger", blogger)
    .setMaxResults(15)
    .setCacheable(true)
    .setCacheRegion("frontpages")
    .list();

The FQN of the region where this query's results would be cached would be /appA/frontpages/QUERY.

If the call to setCacheRegion("frontpages") were ommitted, the Region Name portion of the FQN would be based on a Hibernate class: /appA/org/hibernate/cache/StandardQueryCache/QUERY

4.2.5. Timestamps

Timestamps follow this pattern:

/TS/ + Region Prefix + /org/hibernate/cache/UpdateTimestampsCache

again with a / and the Region Prefix portion omitted if no region prefix was set.

Note that in the timestamps case the special constant ("TS") comes at the start of the FQN rather than the end. This makes it easier to ensure that eviction is never enabled for the timestamps region.