From hibernate-commits at lists.jboss.org Wed Mar 3 09:50:25 2010 Content-Type: multipart/mixed; boundary="===============2690915369808386542==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r18920 - core/trunk/annotations/src/main/docbook/en/modules. Date: Wed, 03 Mar 2010 09:50:25 -0500 Message-ID: <201003031450.o23EoP6N017719@svn01.web.mwc.hst.phx2.redhat.com> --===============2690915369808386542== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: epbernard Date: 2010-03-03 09:50:25 -0500 (Wed, 03 Mar 2010) New Revision: 18920 Modified: core/trunk/annotations/src/main/docbook/en/modules/entity.xml core/trunk/annotations/src/main/docbook/en/modules/setup.xml Log: HHH-4933 Add documentation on caching Modified: core/trunk/annotations/src/main/docbook/en/modules/entity.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- core/trunk/annotations/src/main/docbook/en/modules/entity.xml 2010-03-0= 3 11:00:54 UTC (rev 18919) +++ core/trunk/annotations/src/main/docbook/en/modules/entity.xml 2010-03-0= 3 14:50:25 UTC (rev 18920) @@ -2393,8 +2393,8 @@ = @Entity class Order { ... } = -Customer customer =3D em.get(Customer.class, 1l); -Order order =3D em.get(Order.class, 1l); +Customer customer =3D em.find(Customer.class, 1l); +Order order =3D em.find(Order.class, 1l); customer.getOrders().remove(order); //order will be deleted by cascade = @@ -2561,9 +2561,128 @@ the same column name, the MainCat id column has). Plus a unique constraint on storyPart2 has been set. + = - Check out the JBoss EJB 3 tutorial or the Hibernate Annotations - unit test suite for more examples. +
+ Caching entities + + Hibernate offers naturally a first level cache for entities ca= lled + a persistence context via the notion of Session. + This cache is contextual to the use case at hand. Some entities howe= ver + are shared by many different use cases and are barely changed. You c= an + cache these in what is called the second level cache. + + By default, entities are not part of the second level cache. W= hile + we do not recommend that, you can override this by setting the + shared-cache-mode element in your persistence.xml + file or by using the javax.persistence.sharedCache.mode + property. The following values are possible: + + + + ENABLE_SELECTIVE (Default and recommend= ed + value): entities are not cached unless explicitly marked as + cacheable. + + + + DISABLE_SELECTIVE: entities are cached + unless explicitly marked as not cacheable. + + + + ALL: all entities are always cached eve= n if + marked as non cacheable. + + + + NONE: no entity are cached even if mark= ed + as cacheable. This option can make sense to disable second-level + cache altogether. + + + + The cache concurrency strategy used by default can be set with= the + hibernate.cache.default_cache_concurrency_strategy + property: + + + + read-only + + + + read-write + + + + nonstrict-read-write + + + + transactional + + + + + It is recommended to define the cache concurrency strategy p= er + entity rather than using a global one. Use the + @org.hibernate.annotations.Cache annotation= for + that. + + + @Entity @Cacheable +(a)Cache(usage =3D CacheConcurrencyStrategy.NONSTRICT_READ_WRITE) +public class Forest { ... } + + Hibernate also let's you cache the content of a collection or = the + identifiers if the collection contains other entities. Use the + @Cache annotation on the collection + property. + + @OneToMany(cascade=3DCascadeType.ALL, fetch=3DFetchT= ype.EAGER) +(a)JoinColumn(name=3D"CUST_ID") +(a)Cache(usage =3D CacheConcurrencyStrategy.NONSTRICT_READ_WRITE) +public SortedSet<Ticket> getTickets() { + return tickets; +} + + @org.hibernate.annotations.Cache defines the + caching strategy and region of a given second level cache. + + + + + + + + + + + @Cache( + CacheConcurrencyStrategy usage(); + String region() default ""; + String include() default "all"; +) + + + + usage: the given cache concurrency strategy (NONE, + READ_ONLY, NONSTRICT_READ_WRITE, READ_WRITE, TRANSACTIONAL) + + + + region (optional): the cache region (default to the fqcn= of + the class or the fq role name of the collection) + + + + include (optional): all to include all + properties, non-lazy to only include non lazy properties (defa= ult + all). + + +
= @@ -3934,66 +4053,6 @@ previous example. = -
- Cache - - In order to optimize your database accesses, you can activate = the - so called second level cache of Hibernate. This cache is configurabl= e on - a per entity and per collection basis. - - @org.hibernate.annotations.Cache 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. - - @Entity -(a)Cache(usage =3D CacheConcurrencyStrategy.NONSTRICT_READ_WRITE) -public class Forest { ... } - - @OneToMany(cascade=3DCascadeType.ALL, fetch=3DFe= tchType.EAGER) - @JoinColumn(name=3D"CUST_ID") - @Cache(usage =3D CacheConcurrencyStrategy.NONSTRICT_READ_WRITE) - public SortedSet<Ticket> getTickets() { - return tickets; - } - - - - - - - - - - - - - @Cache( - CacheConcurrencyStrategy usage(); - String region() default ""; - String include() default "all"; -) - - - - usage: the given cache concurrency strategy (NONE, - READ_ONLY, NONSTRICT_READ_WRITE, READ_WRITE, TRANSACTIONAL) - - - - region (optional): the cache region (default to the fqcn= of - the class or the fq role name of the collection) - - - - include (optional): all to include all - properties, non-lazy to only include non lazy properties (defa= ult - all). - - - -
-
Filters = Modified: core/trunk/annotations/src/main/docbook/en/modules/setup.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- core/trunk/annotations/src/main/docbook/en/modules/setup.xml 2010-03-03= 11:00:54 UTC (rev 18919) +++ core/trunk/annotations/src/main/docbook/en/modules/setup.xml 2010-03-03= 14:50:25 UTC (rev 18920) @@ -92,7 +92,7 @@ = We recommend you use Hibernate Validator and= the - Bean VAlidation specification capabilities. Download Hibernate Validat= or 4 + Bean Validation specification capabilities. Download Hibernate Validat= or 4 or above from the Hibernate website and add hibernate-validator.jar and validation-api.jar in your classpath. Alternative= ly @@ -317,4 +317,4 @@ url=3D"http://www.hibernate.org/hib_docs/v3/reference/en/html_single/#= configuration-logging">Logging in the Hibernate Core documentation.
- \ No newline at end of file + --===============2690915369808386542==--