root/doc/nuxeo-cache.txt

[This doc is probably outdated. It will be updated and moved to the Nuxeo Book
someday.]

1. How to enable cache in Nuxeo 5
- as a latest easy way to deploy nuxeo with cache enabled is
  to execute task 'deploy-with-cache' in Nuxeo/build.xml
  
2. Differences from normal deployment
  2.1. Added/changed files
    [] Files needed to setup the JBossCache as a jboss MBean service
       ; being copied by NXJBossCache/build.xml
      - replSync-service.xml  -> into [jboss server]/deploy/nuxeo.ear/
      - jgroups.jar           -> into [jboss server]/lib
      - jboss-cache-jdk50.jar -> into [jboss server]/lib ; this might be already in jboss 4.0.5
    
    [] Interceptors setup. The jboss-specific setup for ejb client side interceptors
    is in [jboss server]/deploy/ejb3-interceptors-aop.xml file. Our interceptor is
    being added to this file through xsl transformation task in NXClientCache/build.xml

  2.2. Nuxeo ear
    The nuxeo.ear will include a different JNDILocations.properties that contains
    > DocumentManager=NXServerCache/CacheableDocumentManagerBean/remote
    so the cache enabled proxy of the DocumentManager ejb will be used by client 
    code in Nuxeo
    
  2.3. NXServerCache ear
    Unless the cache is enabled this file is not required to be deployed. Thought
    it shouldn't affect the behaviour of a non-enabled application

3. How cache affects the application at runtime
  3.1. Process description:
   - document objects [DocumentModel instances] are being retrieved from the 
   server and stored in a client cache. The subsequent calls that require 
   availability of the same document will check first in the local (client) 
   cache and get it from there. 
   That unless the document has been deleted from repository (in this cache it
   should be removed from the cache in the same transaction).
   
  3.2. Differences in application behaviour:
    3.2.1. Automatic user sessions updates
      There are a couple of constructs kept on user (Seam) session contexts.
      Some lists that keep references to documents cannot be dinamically updated
      (that is without reloading them from the server) without cache notifications
      
      Use Case:
      To check this, open 2 user sessions (on 2 browser instances - not just windows)
      and load the same content view of document folder which contains children docs.
      Remove a doc from one side and click the [Content] tab again from the
      other window. The list should have been updated.
      If the cache hasn't been enabled the second list wouldn't have been updated
      unless the user clicks on the tree or breadcrumb item.
      
    3.2.2. Document objects update (short term benefit - should be fixed)
      ex: change the document metadata
        - without cache the last change date remains the same
        - with cache the date is updated
  
  3.3. Application response times
    This issue is subjective to deployment environment.
    
    
4. Developer userguide

  Features like notifications can be used in client code to update specific
  structures like trees or tables.
  Though the cache notifier (in the Nuxeo proj) can automatically update 
  common structures (like List<DocumentModel>) found on the session context (Seam),
  for special constructs the developer have to register a CacheListener and
  perform specific operations (delete,update etc) when an event is received.
  
  This is the case for [DocModelTableModel] actual implementation and for the
  [TreeManagerBean].
  
5. Issues
  On Linux if you have ipv6 - then you need to specify jvm params at startup
  to use only ipv4 otherwise jgroup (needed by jbosscache) won't work.

        => JVM option to add: -Djava.net.preferIPv4Stack=true

  Wiki page about an IPV6 problem with jgroups on Linux.
        http://wiki.jboss.org/wiki/Wiki.jsp?page=IPv6