
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/mgmt/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)

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) Test the new domain management features:
5.1) Cluster creation
  - Go back to the previous page (to /j2eemanagement)
  - Provide the cluster name to create and run the cluster creation (2nd run button)

5.2) Add additional server to the domain.
You may test one of the following scenarios:

5.2.1) In the first scenario, you add an additional slave server which
is not running when the "addServer" operation is invoked. The server is added to the 'servers'
list in 'created' state.
  - Go back to the previous page (to /j2eemanagement)
  - Provide the server name, the connector server URL, and run by clicking on the last run button.
Later on, when starting the server, it passes in 'running' state.
  - Start the server having the provided name and connector server URL
  - Check the new server passed in the 'running' state by re-executing the servlet (first run button)

5.2.2) In the second scenario, you add an additional server which doesn't has the discovery service
enabled. The server is added in the 'servers' list in 'running' state.
  - Start the server to add
  - Go back to the previous page (to /j2eemanagement)
  - Provide the server name, the connector server URL, and run by clicking on the last run button.

6) Stop the jonas server:
	jonas stop [-n name]
