From seam-commits at lists.jboss.org Thu Aug 21 08:13:58 2008 Content-Type: multipart/mixed; boundary="===============0343460788485032799==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r8760 - trunk/doc/Seam_Reference_Guide/en-US. Date: Thu, 21 Aug 2008 08:13:57 -0400 Message-ID: --===============0343460788485032799== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: pete.muir(a)jboss.org Date: 2008-08-21 08:13:57 -0400 (Thu, 21 Aug 2008) New Revision: 8760 Modified: trunk/doc/Seam_Reference_Guide/en-US/Cache.xml Log: Docs for new caching stuff Modified: trunk/doc/Seam_Reference_Guide/en-US/Cache.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 --- trunk/doc/Seam_Reference_Guide/en-US/Cache.xml 2008-08-21 11:34:46 UTC = (rev 8759) +++ trunk/doc/Seam_Reference_Guide/en-US/Cache.xml 2008-08-21 12:13:57 UTC = (rev 8760) @@ -83,9 +83,10 @@ The application can cache transactional state using the Seam - pojoCache component, which integrates JBoss= Cache - into the Seam environment. This state will be visible to other= nodes - if you run JBoss cache in a clustered mode. + cacheProvider component, which integrates = + JBossCache, JBoss POJO Cache or EHCache into the Seam environm= ent. = + This state will be visible to other nodes if your cache suppor= ts + running in a clustered mode. @@ -102,72 +103,228 @@ For more information about the second-level cache, you'll need to re= fer to the documentation of your ORM solution, since this is an extremely c= omplex - topic. In this section we'll discuss the use of JBossCache directly,= via - the pojoCache component, or as the page fragment = cache, + topic. In this section we'll discuss the use of caching directly, via + the cacheProvider component, or as the page fragm= ent cache, via the <s:cache> control. =
- Using JBossCache in Seam + Using Caching in Seam = - The built-in pojoCache component manages an in= stance - of org.jboss.cache.aop.PojoCache. You can safe= ly put - any immutable Java object in the cache, and it will be replicated = - across the cluster (assuming that replication is enabled). If you= want = - to keep mutable objects in the cache, you'll need to run the JBos= sCache - bytecode preprocessor to ensure that changes to the objects will = be = - automatically detected and replicated. + The built-in cacheProvider component manages a= n instance + of: + = + + + + JBoss Cache 1.x (suitable for use in JBoss 4.2.x and other + containers) + + + + org.jboss.cache.TreeCache + + + + + + JBoss Cache 2.x (suitable for use in JBoss 5.x and other + containers) + + + + org.jboss.cache.Cache + + + + + + JBoss POJO Cache 1.x (suitable for use in JBoss 4.2.x and o= ther + containers) + + + + org.jboss.cache.aop.PojoCache + + + + + + EHCache (suitable for use in any container) + + + + net.sf.ehcache.CacheManager + + + + + = + = + You can safely put any immutable Java object in the cache, and it= will = + be stored in the cache and replicated across the cluster (assumin= g that + replication is supported and enabled). If you want to keep mutabl= e = + objects in the cache read the documentation of the underling cach= ing = + project documentation to discover how to notify the cache of chan= ges to = + the cache. + = - To use pojoCache, all you need to do is put th= e = - JBossCache jars in the classpath, and provide a resource named + To use cacheProvider, you need to include the = jars = + of the cache implementation in your project: + + = + + + + JBoss Cache 1.x + + + + + + jboss-cache.jar - JBoss Cache 1= .4.1 + + + + + jgroups.jar - JGroups 2.4.1 + + + + + + + + JBoss Cache 2.x + + + + + + jboss-cache.jar - JBoss Cache 2= .2.0 + + + + + jgroups.jar - JGroups 2.6.2 + + + + + + + + JBoss POJO Cache 1.x + + + + + + jboss-cache.jar - JBoss Cache 1= .4.1 + + + + + jgroups.jar - JGroups 2.4.1 + + + + + jboss-aop.jar - JBoss AOP 1.5.0 + + + + + + + + EHCache + + + + + + ehcache.jar - EHCache 1.2.3 + + + + + + + = + + + If you are using JBoss Cache in containers other than JBoss + Application Server, look at the JBoss Cache + wiki page + for more dependencies. + + + = + + For an EAR depoyment of Seam, we recommend that the cache jars and + configuration go directly into the EAR. + + = + + You'll also need to provide a configuration file for JBossCache. = Place treecache.xml with an appropriate cache = - configuration. JBossCache has many scary and confusing configurat= ion = - settings, so we won't discuss them here. Please refer to the JBos= sCache - documentation for more information. + configuration into the classpath (e.g. the ejb jar or + WEB-INF/classes). JBossCache has many scary an= d = + confusing configuration settings, so we won't discuss them here. = Please + refer to the JBossCache documentation for more information. = You can find a sample treecache.xml in examples/blog/resources/treecache.xml. - - + = - For an EAR depoyment of Seam, we recommend that the JBossCache ja= rs and - configuration go directly into the EAR. Make sure you place both - jboss-cache.jar and jgroups.jar - in your EAR's lib folder. + EHCache will run in it's default configuration without a configur= ation + file + = + + To alter the configuration file in use, configure your cache in + components.xml: + + = + + +]]> = Now you can inject the cache into any Seam component: = userList =3D (Set) pojoCache.get("chatroom", = "userList"); - if (userList=3D=3Dnull) { - userList =3D new HashSet(); - pojoCache.put("chatroom", "userList", userList); - } - userList.put(username); - } catch (CacheException ce) { - throw new RuntimeException(ce); + Set userList =3D (Set) pojoCache.get("chatroom", "us= erList"); + if (userList=3D=3Dnull) { + userList =3D new HashSet(); + cacheProvider.put("chatroom", "userList", userList); } + userList.put(username); } }]]> = - If you want to have multiple JBossCache configurations in your - application, use components.xml: + If you want to have multiple cache configurations in your + application, use components.xml to configure + multiple cache providers: = - ]]> + + + +]]> =
= @@ -175,7 +332,7 @@ Page fragment caching = - The most interesting user of JBossCache is the = + The most interesting use of caching in Seam is the = <s:cache> tag, Seam's solution to the pr= oblem = of page fragment caching in JSF. <s:cache> uses pojoCache internally, so you need to foll= ow the @@ -203,10 +360,10 @@ The key let's you have multiple cached version= s of = each page fragment. In this case, there is one cached version per= blog. - The region determines the JBossCache node that= all = - version will be stored in. Different nodes may have different exp= iry = - policies. (That's the stuff you set up using the aforementioned s= cary = - configuration options.) + The region determines the cache or region node= that = + all version will be stored in. Different nodes may have different = + expiry policies. (That's the stuff you set up using the aforement= ioned = + scary configuration options.) = @@ -219,13 +376,13 @@ = Alternatively, if it is not critical that changes are immediately visible to the user, you could set a short expiry time on the - JbossCache node. + cache node. = --===============0343460788485032799==--