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

This is a sample management application which is using the 
Management EJB (MEJB) accordingly to the J2EE Management 
Specification (JSR77), to implement some management operations 
described below. 
The MEJB is an Enterprise Session bean implementing the
javax.management.j2ee.Management interface and provides access 
to the platform's manageable objects through the EJB 
interoperability protocol.

The MEJB is automatically deployed in a JOnAS EJB container 
at start-up because the ejb-jar file  (mejb.jar)
is installed in (JONAS_ROOT | JONAS_BASE)/ejbjars/autoload directory. 
(Note you can use "ant update_jonasbase" for updating JONAS_BASE 
directory).

The application's main component is a servlet which creates
a MEJB and calls the management methods defined in its remote interface. 

In order to create the MEJB, the servlet gets a reference on the 
bean's home using a JNDI lookup with the "java:comp/env/ejb/MEJB" name.

Management operations
---------------------
The management operations implemented in this example are:
1/ Find the servers which run in the current management domain.
2/ Register an event listener in order to receive notifications 
emitted by a J2EE server.

Example structure and packaging
-------------------------------

This example is a J2EE application, so it is packaged in a EAR.
Compiling the example creates the j2eemanagement.ear file 
that includes a web application (WAR).

The servlet source code is contained in 
$JONAS_ROOT/examples/j2eemanagement/src/.. directory.

The "etc" directory contains
 - the "xml" directory containing the application's deployment descriptors:
    * application.xml (ear file)
    * web.xml, jonas-web.xml (war file)
 - the "resources" directory which contains the resources for this application
     * "web" directory contains all resources used by the servlet


Prerequisites
-------------
First, you must have installed a web container (i.e.: Catalina or Jetty) 
as the web container service.


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

in JONAS_ROOT/examples/j2eemanagement.

Running this example:
--------------------
You will run a JOnAS server having at least a default configuration 
(the ejb service, to deploy mejb.jar, and the web service, to
deploy jonasAdmin.war and j2eemanagement.ear).

Commands are given for an Unix system. 
(Similar commands can be done on Windows)

0) Server configuration:
- Currently, if you wish to test the event notifications, you have to 
be sure the mail service is in the services list in jonas.properties. 
Otherwise, default configuration is sufficient.
- You may add j2eemanagement.ear in the ear descriptors list in jonas.properties;
this avoids executing step 2)
- Be sure that JOnAS is using SUN RI JMX implementation.

1) Run a jonas server:
	jonas start [-n name] [-Ddomain.name=domainName]

2) Load j2eemanagement.ear if you haven't added j2eemanagement.ear to the ear
descriptors list:
   jonas admin -a j2eemanagement.ear

   or via the jonasAdmin management application 
	(http://<hostname>:<port>/jonasAdmin)

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

4) Run the servlet after providing the domain name.

   The displayed information traces out the executed management operations:
   - initial naming context creation
   - MEJB creation
   - access to J2EEDomain MBean and listing the J2EEServer MBeans
   (we have one server in the present case) 
   - the next operation is creation of a client notification listener and
   its registration as listener on notifications emitted by the
   J2EEServer MBean via the usage of a ListenerRegistration object
   provided by the MEJB.

   As specified at step 0) the mail service has to be started in order 
to test the event listener. 
   Make the following operations:
   Run the JOnAS management application to add or remove a mail resource:
   - open http://<hostname>:<port>/jonasAdmin url
   - go in the Resources->Mail sub-tree
   - deploy, or undeploy, a Mail Factory 

   As a side effect of this action, the J2EEServer MBean sends a notification
to the registered notification listeners. The notification's type is 
 	AttributeAddNotification or AttributeRemoveNotification.
It contains information about the added/removed resource.
	The implementation of the MEJB's event listener requirement allow 
the notification to be delivered to the client notification listener.
This can be verified by a click on one of the links allowing to list the 
received notifications.
   
5) Stop the jonas server:
	jonas stop [-n name]
