
Example Overview:
-----------------

This example shows how to access an EJB deployed in a JOnAS EJB container, from 
 - a servlet deployed in a Tomcat/Jetty container (thin client)
 - a client running inside the client container (heavy client)

It also shows how to use security in Tomcat or Jetty to authentificate the user and in JOnAS 
to authorize the user to access the EJB methods. This aspect is described in details 
in the "Use Security in JOnAS with TOMCAT" howto of the JOnAS documentation.

Besides, this example shows the uniform naming resource access supported in JOnAS.
The servlet gets a javax.transaction.UserTransaction object reference from the JNDI
using the "java:comp/UserTransaction" name. Moreover, it gets a reference on the
bean's home using an environment entry: "java:comp/env/ejb/".

This sample contains an example of using ejb-link which allows to link the EJB to the 
servlet. It is used in the web.xml file for both the ejb-ref and
ejb-local-ref tags. It implies that when the servlet performs a lookup on the bean,
the web classloader has got the visibility of the ejb class.
This is due to the classloader hierarchy between the ear classloader, ejb 
classloader and the web classloader.

The "src" directory contains
 - An EJB that mimics $JONAS_ROOT/examples/src/sb with the addition of
     security access to the bean methods.
 - The servlet source of ServletOp.
 - The source of a client which run inside the client container with uniform naming available

The "etc" directory contains
 - the "xml" directory which contains all the deployment descriptors used for this example :
     * application.xml (ear file)
     * ejb-jar.xml and jonas-ejb-jar.xml (jar file)
     * web.xml, jonas-web.xml and web-jetty.xml (war file)
     * application-client.xml, jonas-client1.xml and jonas-client2.xml (two clients jar file)
 - the "resources" directory which contains all the resources for this application
     * "web" directory contains all resources used by the servlet


Compiling this example creates an .ear file that represents an application including :
 - a session bean used by the web application
 - a web application that will be used by Tomcat or Jetty to run the servlet.

Prerequisites
-------------
First, you must have installed a web container (ie : Catalina or Jetty) 
as the web container service or you will use the heavy client

You have to set the environment variables
   CATALINA_HOME and CATALINA_BASE as indicated in the Tomcat 4.1.x documentation.
or JETTY_HOME for Jetty 4.2.x

Compiling and installing this example:
--------------------------------------
 ant install

Running this example:
--------------------
Commands are given for an Unix system. 
(Similar commands can be done on Windows)

1) Run a jonas server:
	jonas start

2) Load earsample.ear (if you have not added it in the ear service descriptors list) using the jonasAadmin
management application (http://<hostname>:<port>/jonasAdmin) or the 'jonas admin' command.

3a) Run your web browser (e.g., netscape):
	netscape http://<hostname>:<port>/earsample
	where <hostname> is the name of your machine (localhost by default)
	and <port> the port number (9000 by default)

3b) You can also lookup the Bean by using one of the client of the ear

 Use the default client (first found)
 java -jar $JONAS_ROOT/lib/client.jar ($JONAS_ROOT |$JONAS_BASE)/apps/earsample.ear -carolFile ($JONAS_ROOT |$JONAS_BASE)/conf/carol.properties

 Use a specific client
 java -jar $JONAS_ROOT/lib/client.jar ($JONAS_ROOT |$JONAS_BASE)/apps/earsample.ear -jarClient client2.jar -carolFile ($JONAS_ROOT |$JONAS_BASE)/conf/carol.properties


Notes :
 a) that when you use the packages JOnAS-Tomcat and JOnAS-Jetty the earsample.ear is  found    $JONAS_BASE/apps/autoload directory.
 b) the argument -carolFile is useless if you have rebuilt this example because in this
    case the carol.properties of your environment is inserted in earsample.ear

4) Stop the jonas server
	jonas stop
