JMX4Ant Readme - July 22, 2002
==============================


Table of Contents
=================
1. Overview
2. License
3. Distribution Contents
4. FAQ
5. Areas for Improvement
6. Changes History For this Readme


1. Overview
===========

Welcome to the Readme file for JMX4Ant. JMX4Ant is a set
of optional Ant tasks that allows interactions with JMX MBeans.

I wrote these tasks because (surprisingly) I couldn't find anything 
that would let me integrate with JMX from Ant (believe me, I searched).

My motivation was to provide tools for J2EE resource creation and 
management from Ant that I use to build/deploy application. 
(e.g. create my JDBC pool and JMS queues/topics before I deploy my 
entity and message driven beans...), but the tasks are general enough 
for much broader use.

In brief, the tasks provided are:

    configureMBean :    get/set MBean properties
    invokeMBean :       invoke an MBean operation
    copyMBean :         copies all the properties of an MBean to a new MBean of
                        the same type
    removeMBean :       unregisters an MBean from the MBeanServer
    createMBean :       creates a new MBean
    showMBean :         writes information about the MBean to the Ant log

Here's a simple example of how configureMBean works follows:

	<configureMBean name="mydomain:Name=mypool,Type=JDBCConnectionPool" 
            failOnError="false" serverType="weblogic" user="system" 
            password="secret">
            <setAttribute name="MaxCapacity" value="${pool.size}"/> 
            <getAttribute name="TestTableName" property="testTable"/> 
        </configureMBean> 

Please refer to the user documentation for more information on all 
the tasks.

The current implementation supports BEA WLS 6.x/7.x and JBoss 3.0.1RC1.
Support for the JSR77 standard, and other JMX implementations is planned.

All constructive comments and feedback is very much appreciated.

Regards,

Brian Dueck
b_dueck@hotmail.com


2. License
==========
This distribution is released under the Apache Software License 1.1.
Please refer to the LICENSE for details.


3. Distribution Contents
========================

The contents of this distribution are as follows:

    README   : this file
    LICENSE  : the Apache license file
    docs     : user manual and api documentation 
                (start at docs\index.html)
    examples : simple examples of how to use these tasks
    lib      : jar file for these tasks
    src : source code and build files for these tasks


4. FAQ
======

Q. What version of Ant is required?
A. Version 1.4 or greater.

Q. What external libraries does this task depend on?
A. In addition to base requirements common to all Ant tasks,
   this library depends on the following jar files:

        For BEA WebLogic Server support:
        - weblogic.jar : This is required to use these
          tasks with BEA WebLogic Server (serverType="WebLogic"). 
          weblogic.jar is NOT included in this distribution,
          this is up to you to legally obtain from BEA directly
          (http://www.bea.com).

        For JBoss support:
        - jboss-jmx.jar, jnp-client.jar, jboss-j2ee.jar, 
          jboss-common-client.jar, jnet.jar, 
          jmx-rmi-connector-client.jar, 
          jmx-ejb-connector-client.jar, log4j.jar
          These jar files are required to use these tasks
          with JBoss. These jar files are NOT included in this
          distribution, and are up to you to legally obtain
          from JBoss directly (http://www.jboss.org).

Q. How do I use these tasks?
A. Assuming you already know how to use Ant, and your environment
   is set-up to use Ant, you can start by examinging and running
   the provided examples for WebLogic and JBoss:
   1. Set your current directory to 'examples\jboss' or
      'examples\weblogic'.
   2. Edit the example.properties and setenv.cmd files in that 
      directory to match your environment.
   3. Run 'ant' to execute the sample build.xml file.

Q. How do I build the code?
A. Assuming you already know how to use Ant, and your environment
   is set-up to use Ant:
   1. Set your current directory to 'src'.
   2. Edit the build.properties file to match your environment.
   3. Run Ant to build the default target.
   NOTE: The 'release' target will clean and prepare all releaseable 
   targets - for now this is the jar file and javadocs.
   The 'build' target will produce an up-to-date jar file.
   The 'clean' target will remove all releaseable targets and
   intermediary files.


5. Areas for Improvement
========================

general     - allow properites to be set/get based to/from a file
            - better handling of property and arguments in 
                arrays and lists (array of string, object name, etc)
            - JUnit test cases

examples    - need simple working MBean implementation to demonstrate
              createMBean and removeMBean

showMBean   - pretty useless as it stands right now, just a (barely readable) 
              dump of a bunch of MBean information.
            - direction I'd like to see this task move is a structured XML
              form for MBean instance and class information (no standard
              for this XML unfortunately)
            - showMBean would then convert an MBean to this format



6. Changes History For this Readme
==================================
$Log: README,v $
Revision 1.1  2003/01/17 11:38:34  bdueck
Intial check-in
