Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-4933 Add documentation on caching 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@18920 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Emmanuel Bernard 2010-03-03 14:50:25 +00:00
parent 6dce44c363
commit 0065a221a3
2 changed files with 125 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

187
annotations/src/main/docbook/en/modules/entity.xml
View File

@ -2393,8 +2393,8 @@ public class Order {
@Entity class Order { ... }
Customer customer = em.get(Customer.class, 1l);
Order order = em.get(Order.class, 1l);
Customer customer = em.find(Customer.class, 1l);
Order order = em.find(Order.class, 1l);
customer.getOrders().remove(order); //order will be deleted by cascade</programlisting>
</section>
@ -2561,9 +2561,128 @@ public class Cat implements Serializable {
the same column name, the <literal>MainCat</literal> id column has).
Plus a unique constraint on <literal>storyPart2</literal> has been
set.</para>
</section>
<para>Check out the JBoss EJB 3 tutorial or the Hibernate Annotations
unit test suite for more examples.</para>
<section>
<title>Caching entities</title>
<para>Hibernate offers naturally a first level cache for entities called
a persistence context via the notion of <classname>Session</classname>.
This cache is contextual to the use case at hand. Some entities however
are shared by many different use cases and are barely changed. You can
cache these in what is called the second level cache.</para>
<para>By default, entities are not part of the second level cache. While
we do not recommend that, you can override this by setting the
<literal>shared-cache-mode</literal> element in your persistence.xml
file or by using the <literal>javax.persistence.sharedCache.mode
property</literal>. The following values are possible:</para>
<itemizedlist>
<listitem>
<para><literal>ENABLE_SELECTIVE</literal> (Default and recommended
value): entities are not cached unless explicitly marked as
cacheable.</para>
</listitem>
<listitem>
<para><literal>DISABLE_SELECTIVE</literal>: entities are cached
unless explicitly marked as not cacheable.</para>
</listitem>
<listitem>
<para><literal>ALL</literal>: all entities are always cached even if
marked as non cacheable.</para>
</listitem>
<listitem>
<para><literal>NONE</literal>: no entity are cached even if marked
as cacheable. This option can make sense to disable second-level
cache altogether.</para>
</listitem>
</itemizedlist>
<para>The cache concurrency strategy used by default can be set with the
<literal>hibernate.cache.default_cache_concurrency_strategy</literal>
property:</para>
<itemizedlist>
<listitem>
<para><literal>read-only</literal></para>
</listitem>
<listitem>
<para><literal>read-write</literal></para>
</listitem>
<listitem>
<para><literal>nonstrict-read-write</literal></para>
</listitem>
<listitem>
<para><literal>transactional</literal></para>
</listitem>
</itemizedlist>
<note>
<para>It is recommended to define the cache concurrency strategy per
entity rather than using a global one. Use the
<classname>@org.hibernate.annotations.Cache</classname> annotation for
that.</para>
</note>
<programlisting>@Entity @Cacheable
@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
public class Forest { ... }</programlisting>
<para>Hibernate also let's you cache the content of a collection or the
identifiers if the collection contains other entities. Use the
<classname>@Cache</classname> annotation on the collection
property.</para>
<programlisting>@OneToMany(cascade=CascadeType.ALL, fetch=FetchType.EAGER)
@JoinColumn(name="CUST_ID")
@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
public SortedSet&lt;Ticket&gt; getTickets() {
return tickets;
}</programlisting>
<para><literal>@org.hibernate.annotations.Cache</literal> defines the
caching strategy and region of a given second level cache.</para>
<programlistingco>
<areaspec>
<area coords="2 55" id="cache-hm1" />
<area coords="3 55" id="cache-hm2" />
<area coords="4 55" id="cache-hm3" />
</areaspec>
<programlisting>@Cache(
CacheConcurrencyStrategy usage();
String region() default "";
String include() default "all";
)</programlisting>
<calloutlist>
<callout arearefs="cache-hm1">
<para>usage: the given cache concurrency strategy (NONE,
READ_ONLY, NONSTRICT_READ_WRITE, READ_WRITE, TRANSACTIONAL)</para>
</callout>
<callout arearefs="cache-hm2">
<para>region (optional): the cache region (default to the fqcn of
the class or the fq role name of the collection)</para>
</callout>
<callout arearefs="cache-hm3">
<para><literal>include</literal> (optional): all to include all
properties, non-lazy to only include non lazy properties (default
all).</para>
</callout>
</calloutlist>
</programlistingco>
</section>
</section>
@ -3934,66 +4053,6 @@ public Collection&lt;Employer&gt; getEmployers()</programlisting>
previous example.</para>
</section>
<section>
<title>Cache</title>
<para>In order to optimize your database accesses, you can activate the
so called second level cache of Hibernate. This cache is configurable on
a per entity and per collection basis.</para>
<para><literal>@org.hibernate.annotations.Cache</literal> defines the
caching strategy and region of a given second level cache. This
annotation can be applied on the root entity (not the sub entities), and
on the collections.</para>
<programlisting>@Entity
@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
public class Forest { ... }</programlisting>
<programlisting> @OneToMany(cascade=CascadeType.ALL, fetch=FetchType.EAGER)
@JoinColumn(name="CUST_ID")
@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
public SortedSet&lt;Ticket&gt; getTickets() {
return tickets;
}</programlisting>
<para></para>
<programlistingco>
<areaspec>
<area coords="2 55" id="cache-hm1" />
<area coords="3 55" id="cache-hm2" />
<area coords="4 55" id="cache-hm3" />
</areaspec>
<programlisting>@Cache(
CacheConcurrencyStrategy usage();
String region() default "";
String include() default "all";
)</programlisting>
<calloutlist>
<callout arearefs="cache-hm1">
<para>usage: the given cache concurrency strategy (NONE,
READ_ONLY, NONSTRICT_READ_WRITE, READ_WRITE, TRANSACTIONAL)</para>
</callout>
<callout arearefs="cache-hm2">
<para>region (optional): the cache region (default to the fqcn of
the class or the fq role name of the collection)</para>
</callout>
<callout arearefs="cache-hm3">
<para><literal>include</literal> (optional): all to include all
properties, non-lazy to only include non lazy properties (default
all).</para>
</callout>
</calloutlist>
</programlistingco>
</section>
<section id="entity-hibspec-filters">
<title>Filters</title>

2
annotations/src/main/docbook/en/modules/setup.xml
View File

@ -92,7 +92,7 @@
<para>We recommend you use <ulink
url="http://validator.hibernate.org">Hibernate Validator</ulink> and the
Bean VAlidation specification capabilities. Download Hibernate Validator 4
Bean Validation specification capabilities. Download Hibernate Validator 4
or above from the Hibernate website and add
<filename>hibernate-validator.jar</filename> and
<filename>validation-api.jar</filename> in your classpath. Alternatively