Cache.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<chapter id="cache">
   <title>Caching</title>

   <para>
      In almost all enterprise applications, the database is the primary
      bottleneck, and the least scalable tier of the runtime environment. People
      from a PHP/Ruby environment will try to tell you that so-called "shared
      nothing" architectures scale well. While that may be literally true, I
      don't know of many interesting multi-user applications which can be
      implemented with no sharing of resources between different nodes of the
      cluster. What these silly people are really thinking of is a "share
      nothing except for the database" architecture. Of course, sharing the
      database is the primary problem with scaling a multi-user
      application &#8212; so the claim that this architecture is highly scalable
      is absurd, and tells you a lot about the kind of applications that these
      folks spend most of their time working on.
   </para>

   <para>
      Almost anything we can possibly do to share the database
      <emphasis>less often</emphasis> is worth doing.
   </para>

   <para>
      This calls for a cache. Well, not just one cache. A well designed Seam
      application will feature a rich, multi-layered caching strategy that
      impacts every layer of the application:
   </para>

   <itemizedlist>
      <listitem>
         <para>
            The database, of course, has its own cache. This is super-important,
            but can't scale like a cache in the application tier.
         </para>
      </listitem>
      <listitem>
         <para>
            Your ORM solution (Hibernate, or some other JPA implementation) has
            a second-level cache of data from the database. This is a very
            powerful capability, but is often misused. In a clustered
            environment, keeping the data in the cache transactionally
            consistent across the whole cluster, and with the database, is quite
            expensive. It makes most sense for data which is shared between many
            users, and is updated rarely. In traditional stateless
            architectures, people often try to use the second-level cache for
            conversational state. This is always bad, and is especially wrong in
            Seam.
         </para>
      </listitem>
      <listitem>
         <para>
            The Seam conversation context is a cache of conversational state.
            Components you put into the conversation context can hold and cache
            state relating to the current user interaction.
         </para>
      </listitem>
      <listitem>
         <para>
            In particular, the Seam-managed persistence context (or an extended
            EJB container-managed persistence context associated with a
            conversation-scoped stateful session bean) acts as a cache of data
            that has been read in the current conversation. This cache tends to
            have a pretty high hitrate! Seam optimizes the replication of
            Seam-managed persistence contexts in a clustered environment, and
            there is no requirement for transactional consistency with the
            database (optimistic locking is sufficient) so you don't need to
            worry too much about the performance implications of this cache,
            unless you read thousands of objects into a single persistence
            context.
         </para>
      </listitem>
      <listitem>
         <para>
            The application can cache non-transactional state in the Seam
            application context. State kept in the application context is of
            course not visible to other nodes in the cluster.
         </para>
      </listitem>
      <listitem>
         <para>
            The application can cache transactional state using the Seam
            <literal>cacheProvider</literal> component, which integrates 
            JBossCache, JBoss POJO Cache, Infinispan or EHCache into the Seam environment. 
            This state will be visible to other nodes if your cache supports
            running in a clustered mode.
         </para>
      </listitem>
      <listitem>
         <para>
            Finally, Seam lets you cache rendered fragments of a JSF page.
            Unlike the ORM second-level cache, this cache is not automatically
            invalidated when data changes, so you need to write application code
            to perform explicit invalidation, or set appropriate expiration
            policies.
         </para>
      </listitem>
   </itemizedlist>

   <para>
      For more information about the second-level cache, you'll need to refer to
      the documentation of your ORM solution, since this is an extremely complex
      topic. In this section we'll discuss the use of caching directly, via
      the <literal>cacheProvider</literal> component, or as the page fragment cache,
      via the <literal>&lt;s:cache&gt;</literal> control.
   </para>

   <section>
      <title>Using Caching in Seam</title>

      <para>
         The built-in <literal>cacheProvider</literal> component manages an instance
         of:
      </para>
      
      <variablelist>
         <varlistentry>
            <term>
               Infinispan 5.x (suitable for use in JBoss AS 7.1.x or later and other
               containers)
            </term>
            <listitem>
               <para>
                  <literal>org.infninispan.tree.TreeCache</literal>
               </para>
            </listitem>
         </varlistentry>      
         <varlistentry>
            <term>
               JBoss Cache 1.x (suitable for use in JBoss 4.2.x or later and other
               containers)
            </term>
            <listitem>
               <para>
                  <literal>org.jboss.cache.TreeCache</literal>
               </para>
            </listitem>
         </varlistentry>
         <varlistentry>
            <term>
               JBoss Cache 2.x (suitable for use in JBoss 5.x and other
               containers)
            </term>
            <listitem>
               <para>
                  <literal>org.jboss.cache.Cache</literal>
               </para>
            </listitem>
         </varlistentry>
         <varlistentry>
            <term>
               JBoss POJO Cache 1.x (suitable for use in JBoss 4.2.x or later and other
               containers)
            </term>
            <listitem>
               <para>
                  <literal>org.jboss.cache.aop.PojoCache</literal>
               </para>
            </listitem>
         </varlistentry>
         <varlistentry>
            <term>
               EHCache (suitable for use in any container)
            </term>
            <listitem>
               <para>
                  <literal>net.sf.ehcache.CacheManager</literal>
               </para>
            </listitem>
         </varlistentry>
      </variablelist>
      
      <para>  
         You can safely put any immutable Java object in the cache, and it will 
         be stored in the cache and replicated across the cluster (assuming that
         replication is supported and enabled). If you want to keep mutable 
         objects in the cache read the documentation of the underling caching 
         project documentation to discover how to notify the cache of changes to 
         the cache.
      </para>

      <para>
         To use <literal>cacheProvider</literal>, you need to include the jars 
         of the cache implementation in your project:
      </para>
      
      <variablelist>
         <varlistentry>
            <term>
               Infinispan 5.x
            </term>
            <listitem>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>infinispan-core.jar</literal> - Infinispan Core 5.1.x.Final
                     </para>
                     <para>
                        <literal>infinispan-tree.jar</literal> - Infinispan TreeCache 5.1.x.Final
                     </para>                     
                  </listitem>
                  <listitem>
                     <para>
                        <literal>jgroups.jar</literal> - JGroups 3.0
                     </para>
                  </listitem>
               </itemizedlist>
            </listitem>
         </varlistentry>      
         <varlistentry>
            <term>
               JBoss Cache 1.x
            </term>
            <listitem>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>jboss-cache.jar</literal> - JBoss Cache 1.4.1
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>jgroups.jar</literal> - JGroups 2.4.1
                     </para>
                  </listitem>
               </itemizedlist>
            </listitem>
         </varlistentry>
         <varlistentry>
            <term>
               JBoss Cache 2.x
            </term>
            <listitem>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>jboss-cache.jar</literal> - JBoss Cache 2.2.0
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>jgroups.jar</literal> - JGroups 2.6.2
                     </para>
                  </listitem>
               </itemizedlist>
            </listitem>
         </varlistentry>
         <varlistentry>
            <term>
               JBoss POJO Cache 1.x
            </term>
            <listitem>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>jboss-cache.jar</literal> - JBoss Cache 1.4.1
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>jgroups.jar</literal> - JGroups 2.4.1
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>jboss-aop.jar</literal> - JBoss AOP 1.5.0
                     </para>
                  </listitem>
               </itemizedlist>
            </listitem>
         </varlistentry>
         <varlistentry>
            <term>
               EHCache
            </term>
            <listitem>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>ehcache.jar</literal> - EHCache 1.2.3
                     </para>
                  </listitem>
               </itemizedlist>
            </listitem>
         </varlistentry>
      </variablelist>
      
      <tip>
         <para>
            If you would like to know more details about Infinispan, look at the Infinispan 
            <ulink url="https://docs.jboss.org/author/display/ISPN/Home">Documentation</ulink> page.
         </para>
      </tip>
      
      <para>
         For an EAR deployment of Seam, we recommend that the infinispan jars and
         configuration go directly into the EAR.
      </para>
      
      <note>
        <para>JBoss AS7 already provides Infinispan and JGroups jars, so you need to turn on that 
        dependencies in your JBoss AS 7 deployment file or modify <literal>META-INF/Manifest.mf</literal>
        to have this dependencies. Check the Blog example or JBoss AS7 documentation how to do that.</para>
      </note>
      
      <para>
         You'll also need to provide a configuration file for Infinispan. Place
         <literal>infinispan.xml</literal> with an appropriate cache 
         configuration into the Web applicaiton classpath (e.g. the ejb jar or
         <literal>WEB-INF/classes</literal>). Infinispan  has many configuration settings,
          so we won't discuss them here. Please refer to the Infinispan documentation for more information.
      </para>

      <para>
         You can find a sample configuration file <literal>infinispan.xml</literal> in
         <literal>examples/blog/blog-web/src/main/resources/infinispan.xml</literal>.
      </para>
      
      <para>
         EHCache will run in it's default configuration without a configuration
         file
      </para>
      
      <para>
         To alter the configuration file in use, configure your cache in
         <literal>components.xml</literal>:
      </para>
      
      <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.org/schema/seam/components"
            xmlns:cache="http://jboss.org/schema/seam/cache">
   <cache:infinispan-cache-provider configuration="infinispan.xml" />
</components>]]></programlisting>

      <para>Now you can inject the cache into any Seam component:</para>

      <programlisting role="JAVA"><![CDATA[@Name("chatroomUsers")
@Scope(ScopeType.STATELESS)
public class ChatroomUsers
{
    @In CacheProvider cacheProvider;

    @Unwrap
    public Set<String> getUsers() throws CacheException   {
        Set<String> userList = (Set<String>) cacheProvider.get("chatroom", "userList");
        if (userList==null) {
            userList = new HashSet<String>();
            cacheProvider.put("chatroom", "userList", userList);
        }
        return userList;
    }
}]]></programlisting>

      <para>
         If you want to have multiple cache configurations in your
         application, use <literal>components.xml</literal> to configure
         multiple cache providers:
      </para>

      <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.org/schema/seam/components"
            xmlns:cache="http://jboss.org/schema/seam/cache">
   <cache:infinispan-cache-provider name="myCache" configuration="myown/cache.xml"/>
   <cache:infinispan-cache-provider name="myOtherCache" configuration="myother/cache.xml"/>
</components>]]></programlisting>

   </section>

   <section>
      <title>Page fragment caching</title>

      <para>
         The most interesting use of caching in Seam is the 
         <literal>&lt;s:cache&gt;</literal> tag, Seam's solution to the problem 
         of page fragment caching in JSF. <literal>&lt;s:cache&gt;</literal>
         uses <literal>pojoCache</literal> internally, so you need to follow the
         steps listed above before you can use it. (Put the jars in the EAR, 
         wade through the scary configuration options, etc.)
      </para>

      <para>
         <literal>&lt;s:cache&gt;</literal> is used for caching some rendered 
         content which changes rarely. For example, the welcome page of our blog
         displays the recent blog entries:
      </para>

      <programlisting role="XHTML"><![CDATA[<s:cache key="recentEntries-#{blog.id}" region="welcomePageFragments">
   <h:dataTable value="#{blog.recentEntries}" var="blogEntry">
      <h:column>
         <h3>#{blogEntry.title}</h3>
         <div>
            <s:formattedText value="#{blogEntry.body}"/>
         </div>
      </h:column>
   </h:dataTable>
</s:cache>]]></programlisting>

      <para>
         The <literal>key</literal> let's you have multiple cached versions of 
         each page fragment. In this case, there is one cached version per blog.
         The <literal>region</literal> 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 aforementioned 
         scary configuration options.)
      </para>

      <para>
         Of course, the big problem with <literal>&lt;s:cache&gt;</literal> is 
         that it is too stupid to know when the underlying data changes (for
         example, when the blogger posts a new entry). So you need to evict the
         cached fragment manually:
      </para>

      <programlisting role="JAVA"><![CDATA[public void post() {
    ...
    entityManager.persist(blogEntry);
    cacheProvider.remove("welcomePageFragments", "recentEntries-" + blog.getId() );
}]]></programlisting>

      <para>
         Alternatively, if it is not critical that changes are immediately
         visible to the user, you could set a short expiry time on the
         cache node.
      </para>

   </section>

</chapter>