Red Hat Training

A Red Hat training course is available for JBoss Enterprise Application Platform Common Criteria Certification

22.3. Using FIELD-level replication

Warning

This feature is deprecated as of JBoss Enterprise Web Platform 5.1, and will be removed in a future release of JBoss Enterprise Web Platform. Customers are recommended to migrate away from this feature in existing implementations, and not use it in new implementations.
FIELD-level replication only replicates modified data fields inside objects stored in the session. It can reduce the data traffic between clustered nodes, and hence improve the performance of the whole cluster. To use FIELD-level replication, you must first prepare (that is, bytecode enhance) your Java class to allow the session cache to detect when fields in cached objects have been changed and need to be replicated.
First, you need to identify the classes that you need to prepare. You can identify these classes by using annotations, like so: 
@org.jboss.cache.pojo.annotation.Replicable
public class Address 
{
...
}
If you annotate a class with @Replicable, then all of its subclasses will be automatically annotated as well. Similarly, you can annotate an interface with @Replicable and all of its implementing classes will be annotated. For example: 
@org.jboss.cache.aop.InstanceOfAopMarker
public class Person 
{
...
}

public class Student extends Person
{
...
}
There is no need to annotate Student. POJO Cache will recognize it as @Replicable because it is a sub-class of Person.
JBoss Enterprise Application Platform 5 requires JDK 5 at runtime, but some users may still need to build their projects using JDK 1.4. In this case, annotating classes can be done via JDK 1.4 style annotations embedded in JavaDocs. For example: 
/**
 * Represents a street address.
 * @org.jboss.cache.pojo.annotation.Replicable
 */
public class Address 
{
...
}
Once you have annotated your classes, you will need to perform a pre-processing step to bytecode enhance your classes for use by POJO Cache. You need to use the JBoss AOP pre-compiler annotationc and post-compiler aopc to process the above source code before and after they are compiled by the Java compiler. The annotationc step is only need if the JDK 1.4 style annotations are used; if JDK 5 annotations are used it is not necessary. Here is an example of how to invoke those commands from command line. 
$ annotationc [classpath] [source files or directories]
$ javac -cp [classpath] [source files or directories]
$ aopc [classpath] [class files or directories]
Please see the JBoss AOP documentation for the usage of the pre- and post-compiler. The JBoss AOP project also provides easy to use ANT tasks to help integrate those steps into your application build process.

Note

You can see a complete example of how to build, deploy, and validate a FIELD-level replicated web application from this page: http://www.jboss.org/community/wiki/httpsessionfieldlevelexample. The example bundles the pre- and post-compile tools so you do not need to download JBoss AOP separately.
Finally, let's see an example on how to use FIELD-level replication on those data classes. First, we see some servlet code that reads some data from the request parameters, creates a couple of objects and stores them in the session: 
Person husband = new Person(getHusbandName(request), getHusbandAge(request)); Person wife = new
Person(getWifeName(request), getWifeAge(request)); Address addr = new Address();
addr.setPostalCode(getPostalCode(request));

husband.setAddress(addr);
wife.setAddress(addr); // husband and wife share the same address!

session.setAttribute("husband", husband); // that's it.
session.setAttribute("wife", wife); // that's it.
Later, a different servlet could update the family's postal code: 
Person wife = (Person)session.getAttribute("wife"); wife.getAddress().setPostalCode(getPostalCode(request));
// this will update and replicate the postal code
Notice that in there is no need to call session.setAttribute() after you make changes to the data object, and all changes to the fields are automatically replicated across the cluster.
Besides plain objects, you can also use regular Java collections of those objects as session attributes. POJO Cache automatically figures out how to handle those collections and replicate field changes in their member objects.