 ===============================
|       SampleCluster2	        |
 ===============================

Date: 03/31/2005
Version: v1.6

Application Overview:
----------------------

This application aims to demonstrate the JOnAS's clustering features in a 'pedagogic' way:

- load balancing at Apache level
	. mod_jk
- failover at the web level (Tomcat)
	. HTTP session replication
- load balancing at EJB level
	. CMI

and in coming version

- failover at EJB level
	. Stateful EJB replication
- load balancing/failover at database level
	. C_JDBC

Description of the application
------------------------------

The application is composed of three EJBs. A stateful, stateless session bean and an entity bean.
These EJBs are instantiated by the web interface. When the user connects the first time to the 
web interface, an HTTP session is created. During this process a stateful session bean is created
in one of the JOnAS nodes where the EJB container is started. The handle of this stateful session
bean is added to the HTTP session (see remark).
Next, the web interface creates a new instance of the stateless session bean. The first time no 
entity bean is created !. The useful information from the stateless session bean (JOnAS node name,
number of instances) is set in the stateful session bean.
The user can see the result in the web interface where all the necessary information is displayed. 
(See the description of the interface). The user should now execute the same servlet some times again 
inorder to see the changes made by the cluster. Each time the servlet is executed, the servlet 
may be executed on a different node (JOnAS with web container). The servlet gets a reference to 
the stateful session bean (through the handle). After that, a new stateless session bean is created
and its information is passed to the stateful session bean. But when de number of instantiations 
of the stateless session bean modulo 10 is 0, an entity bean is created.
The stateful session bean is always executed in the same EJB contained where it was instantiated.
This is due to the non replication between the EJB containers (Not YET). But the stateless 
session bean may be instantiated in a different EJB container than the stateful session bean.
In this sample we are using local interfaces between stateless sessionbean and the entity bean. As
a result, the entity bean is created in the same EJB container than the stateless session bean.
The entity bean writes the time and the name of the node in the database.


Remark: 	The handle is added to the http session and not the stateful session bean because the 
		handle is able to get a reference to stateful session bean when the JVM has changed !
 

Directory Structure:
---------------------

/lib        librairies needed by the aplication to run
/output     generated ear,jar,war files
/src	    source code

Prerequisite:
--------------

Use a package JOnAS/TomCat 4.4.x

set $JONAS_BASE to your jonas_base folder
 unix : export $JONAS_BASE=path/to/jonas/base
 windows : set $JONAS_BASE=path/to/jonas/base

JOnAS needs to be configured for clustering
 See $JONAS_ROOT/doc/howto/Clustering.html

Compiling this application:
----------------------------

A. for one JOnAS  instance: 
  Use the Ant build tool:
    ant install

  The application file sampleCluster2.ear is copied to your $JONAS_BASE/apps folder 

B. for more JOnAS instances:
  
  Use the Ant build tool:
    ant ear

  Copy file output/webapps/sampleCluster2.war to the JOnAS instances used for the webapplication
  Copy file output/ejbjars/ejbs.jar to the JOnAS instances used for the EJBs

Configure the different cluster nodes:
--------------------------------------

   The jonas.properties file must specify the following services:
	A. nodes starting the web container and the EJB container (separated war- and jar-file):
           - registry,jmx,jtm,dbm,resource,ejb,web,ear
	B. nodes starting only the web container:
           - registry,jmx,jtm,dbm,resource,web,ear
	C. nodes starting only the EJB container:
           - registry,jmx,jtm,dbm,resource,ejb,ear	

   The carol.properties file must specify that the used JNDI is cmi
       - carol.protocols=cmi

   For load balancing at web level with mod_jk
      - configure httpd.conf, mod_jk, workers.properties and server.xml

   Configuring a 4 nodes cluster on a single machine, please consult the PortConfiguration.txt

   See http://jonas.objectweb.org/current/doc/howto/Clustering.html for information about 
      the configuration of the cluster nodes. 

Running the application:
-------------------------

A. for one JOnAS instance:
 
 1) start JOnAS:
     jonas start -n node0
 
 2) deploy the application:
     jonas admin -a sampleCluster2.ear
 
 3) test the application
     use your webbrowser
      url : http://<hostWebApplicationAddr>/sampleCluster2
 
 4) stop JOnAS:
     jonas stop -n node0

B. for more JOnAS instances: 
 
   Remark: X is the number of the node in the cluster

 1) start each JOnAS instance:
       jonas start -n nodeX 	

 2) 
    2.1) deploy the EJBs on the JOnAS instances used for the EJBs.
            jonas admin -a ejbs.jar -n nodeX

    2.2) deploy the webapplication on the JOnAS instances used for the webapplication
            jonas admin -a sampleCluster2.war -n nodeX

   or
	
    2.1) deploy the whole application using the sampleCluster2.ear:
     		jonas admin -a sampleCluster2.ear -n nodeX

 3) test the application
       use your webbrowser
        url: http://<hostWebApplicationAddr>/sampleCluster2

 4) stop each JOnAS instance:
       jonas stop -n nodeX


Description of the sampleCluster2 Web Interface:
------------------------------------------------

+ Home of sampleCluster2

	- Open a session : creates a new session
	- Release a session : invalidates the http session and if a cookie is present, it will be obsoleted
	- Check a session : checks if a session is valid

+ After click on open session link

	- getRequestURL 
		indicates the number of request for the indicated URL
	- from <Client_IP> 
		Client requesting the page 
	- to <JOnAS_IP> 
		JOnAS web-container who has executed the servlet
	- Request path:
		* Serlvet
			the node-name(-n nodeX) of the 
			JOnAS web-container who has executed the servlet  
		* Stateless EJB
			the node-name(-n nodeX) of the
			JOnAS ejb-container where the stateless session bean has been created
	- Session Data : New Session : true 
		indicates if a new http session has been created in the web container
	- Session ID 
		id of the http session
	- Creation Time
		date of the http session creation
	- Last Accessed
		date of the last access to the session
	- JOnAS instance=<node-name>
		ejb-container where the stateful ejb has been created
	- Table
		* servlet running on
			web-container who has executed the servlet
		* stateless bean created
			ejb-container who has created the stateless session bean
		* stateless bean total calls
			number of instantiations of the stateless bean on a specific node
		* stateless bean instance count
		
		* entity bean created
			if an entity bean has been created, this indicates the node-name 
				of the EJB container who created the entity bean
	- links
		* Ask again
			executes the servlet again
		* release session
			invalidates the opened http session and if a cookie is present, it will be obsoleted	
		* check session
			checks if the session is valid
		* home
			returns to the main page

+ After click on check session link
	- JSessionID 
		id of the http session
	- links
		* go to session
			returns to the opened session
		* check session
			checks if the session is valid
		* home
			returns to the main page

Attachments:
-------------
+ example configurations (in exampleConfig):
	- Jakarta Tomcat 5.5.x (server-5.5_director.xml,server-5.5_mod_jk.xml)
	- mod_jk (workers.properties, tomcat_jk.conf)
	- Enhydra Director (enhydra_director.conf)



---------------------------
Good luck!!
=================================================================================
