FIELD-level http session replication example
  Ben Wang (ben dot wang at jboss dot com)
  and Brian Stansberry (bstansberry at jboss dot com)
  03-06

This is an example that illustrates how to use the FIELD replication
granularity to replicate over a clustered state information about
students and the courses they take in JBoss AS4.0.4 and up (I am
currently running it using 4.0.4.CR2). In addition,
the application is run with the JBoss scoped class loader. If you don't
need it, you can comment it out from jboss-web.xml (in etc/WEB-INF).

In this example, where necessary the domain model classes have been
annotated with "@@org.jboss.web.tomcat.tc5.session.AopMarker" and
"@@org.jboss.web.tomcat.tc5.session.InstanceOfAopMarker" (PojoCache JDK1.4
annotations) where "InstanceOfAopMarker" signifies that every subclass will be
instrumented as well, e.g., no need for Student to annotate again). 

To run the example, the annoc pre-compiler needs to be executed first to
compile the annotations. Once annoc has been run, aopc is used to
instrument the classes in the domain model before the example is run
(such that you don't need a special class loader during start up). Note
that both annoc and aopc targets all have been bundled into dist target
in build.xml. Please refer it there for details.

The example involves 4 domain model classes: Person, Student, Address
and Course where Student is a subclass of Person. A Person has an Address,
while a Student can be registered for 0 or more Courses (use of Collection
here).

Note that in order to run this example, you will need to have run the JBoss
web clustering before (e.g., how to use the load balancer, failvoer, sticky session).
If you have not done that, please refer to
http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossHA. Please refer to:
 http://wiki.jboss.org/wiki/Wiki.jsp?page=ConfiguringMultipleJBossInstancesOnOneMachine
on how to setup two separate JBoss instances on the same machine,
and also go through the "Web Clustering" section, specifically, this wiki:
http://wiki.jboss.org/wiki/Wiki.jsp?page=UsingMod_jk1.2WithJBoss. It will
be a little involved to set it up first to make sure sticky session and
loadbalancing is working correctly. But if you use a HW load balancer, I think
life will be easier for you (well, to some extent).

To run it, 

1) build the war file (by typing "ant dist -Djboss.config=XXX") where
"XXX" is your jboss config directory. (Note that if you have spaces in
your jboss.config path, you can enclose it with "".) This will produce
a war file called test-http-scoped-FIELD.war. Also note that this example
requires ant 1.6.5 and higher to run, and the JDK required is 1.4.2 and up.

Finally, we have bundled a third-party library (qdox.jar) under "lib"
directory to support JDK1.4 annotation. This is used for "annoc" target
only.

2) Copy this war file to your jboss clustered deploy directories, an equivalent
 of "all/deploy", e.g.). In my case, they are node0 and node1 (and the jvmRoute that
 I assigned for jk loadbalancer are "node0" and "node1" as well).

3) Start up your 2 JBoss instances. For example, in my case,
"run.sh -c node0 -b ${MYTESTIP_1}" and "run.sh -c node1 -b ${MYTESTIP_2}.

4) The relevant urls are:
  http://hostX/test-http-scoped-FIELD/setSession.jsp
  http://hostX/test-http-scoped-FIELD/modifyAttribute.jsp
  http://hostX/test-http-scoped-FIELD/getAttribute.jsp
here hostX points to the loadbalancer, e.g., Apache.

You can examine the jsps under the etc directory. Basically, setSession.jsp
tries to store the POJOS in the http session using session.setAttribute(),
modifyAttribute.jsp then tries to modify it, and finally getAttribute.jsp can
retrieve the POJOs.

To illustrate the fine-grained replication, here is what I run (assuming we have
clustered node of 0 & 1):
a) setSession.jsp (should go to node0)
b) getAttribute.jsp (go to node0)
c) kill node0 and failover to node1
d) getAttribute.jsp to validate the values (go to node1 now)
e) modifyAttribute.jsp to modify the POJOs (go to node1)
f) restart node0 to join the cluster
g) kill node1 so it will failover back to node0
h) getAttribute.jsp (this is node0)

Note if you can check the session id postfix for the jvmRoute to make sure which
node that the request goes to.

When you get to this far, you can also modify your jsp and experiment with it!

Please report problems to the Clustering user forum:
http://www.jboss.com/index.html?module=bb&op=viewforum&f=64