JMX4Ant v1.2 Beta

by

Brian Dueck

Welcome

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

Like many other programmers, I find Ant to be an extremely handy tool to use in automating away the daily drudgery of routine development tasks. In J2EE development, one kind of drudgery that I have a special dislike for is the creation and management of J2EE resources that my applications depend upon.

My motivation therefore was to provide tasks 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 (i.e. general purpose J2EE server and application administration).

If you have questions, comments, or suggestions for improvements please feel free to contact me directly, or post to one of the JMX4Ant lists on Sourceforge.

Version 1.2 of JMX4Ant contains a number of important new features and some bug fixes as well. One of the most requested enhancements for JMX4Ant that is now part of v1.2 is support for WebLogic's Targets property, and addTarget method. This enhancement allows JMX4Ant to deploy and undeploy the resources that are created to a particular target server. For more information on v1.2 features, refer to the Change History section of this document.

Downloading

JMX4Ant is an open source project hosted on Sourceforge at this location.

You can download JMX4Ant by clicking here.

Overview

This manual details optional Ant task extensions that provide integration with JMX (Java Management Extensions). Please refer to http://java.sun.com/products/JavaManagement for more details on JMX.

The following JMX4Ant tasks are provided: In addition to the above tasks, an ANT type has been added that allows references to specific MBeans to be reused: Here is a simple ANT snippet that shows how to use the configureMBean task with a BEA WebLogic Server mbean:
<!-- Declare a reference to the mbean -->
<mbean id="myMBean" name="mydomain:Name=myPool,Type=JDBCConnectionPool"
serverType="weblogic" user="system" password="secret"/>

<!-- Attempt to get and set a few mbean attributes -->
<configureMBean mbeanref="myMBean">
   <setAttribute name="MaxCapacity" value="${pool.size}"/>
   <setAttribute name="Targets">:Name=myserver,Type=Server</setAttribute>
   <getAttribute name="TestTableName" property="testTable"/>
</configureMBean>

Requirements

Currently, this implementation supports BEA WebLogic Server 6.x/7.x and JBoss 3.x implementations of JMX. Support for additional JMX Server can be achieved by implementing the JMXConnector interface provided with this package. See the jmx.connector package for details.

Support for additional JMX functionality is planned with alignment to JSR 000077 - J2EE[TM] Management Specification and JSR 000160 JavaTM Management Extensions (JMX) 1.5 Specification (JMX Remoting) as these specifiations are released and implementations become available.

For BEA WebLogic Server support, the following external library is required:
weblogic.jar

IMPORTANT: You must place weblogic.jar on the classpath before starting ant.

This jar file is required to use these tasks with BEA WebLogic Server (serverType="weblogic"). weblogic.jar is NOT included in this distribution. It is your responsibility to obtain these libraries from BEA directly.

For JBoss support, the following external libraries are required:
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

IMPORTANT: You must place the above jar files on the classpath before starting ant.

These jar files are required to use these tasks with JBoss. These jar files are NOT included in this distribution, but are included (at the time of this writing) in the JBoss 3.0x distribution. It is your responsibility to obtain these libraries from JBoss directly.

Type Support

One of the challenges in providing support for JMX in Ant is the type conversion required between Ant properties/parameters and JMX MBean types. Since Ant expresses all values as Strings, whereas JMX allows any Java class or primitive to be exchanged, this presents a problem in ensuring values exchanged between Ant and JMX retain their fidelity.

This version of JMX4Ant provides support for a fairly wide range of Java types that are used in WebLogic and JBoss MBean methods and properties. The following provides details of the specific types that are currently supported:

  • Java primitives (boolean, byte, char, double, float, int, long, short)
  • java.lang.String, java.util.Properties, and java.util.Set
  • Classes with a static valueOf() method. This support is provided via reflection.
  • Classes with a constructor with a single argument of type java.lang.String. This support is provided via reflection.
  • Any descendents of weblogic.management.WebLogicMBean
  • Arrays of any of the above types
  • If JMX4Ant does not support a type required by a specific JMX MBean you are trying to use a message will appear in the Ant log indicating there is a type support problem. To add support for additional types to JMX4Ant, you may provide an implementation of the ValueConverter interface and register the implementation by calling the registerValueConverter() method of the ValueFactory. Please let me know if there are specific types you'd like to see added to JMX4Ant.

    For readers interested in understanding a bit more about whats under the hood of JMX4Ant's type support, read on.

  • When converting from a value received from JMX into an Ant property, JMX4Ant relies on the .toString() method of the object received from JMX. This is crude but has proven to be effective.
  • When converting from an Ant property to a value that will be passed to JMX the problem is more complex. JMX4Ant must coerce the value it receives from Ant represented as a String into an Object of the type specified on the JMX MBean interface. To do this conversion, JMX4Ant specifies a ValueConverter interface. Implementations of ValueConverter simply convert a String value into an object of a particular type. Each ValueConverter implementation can support 1 or more types (Java primitives or classes) and registers itself with a ValueFactory singleton that is responsible for all Ant value to JMX value conversion.
  • Each time the ValueFactory is asked to convert a String value to the value of a particular type (class), it first checks to see if there is a ValueConverter implementation that has registered itself as being able to handle that particular type. If a suitable implementation is found it is used. If one cannot be found, a check is done to see convert the value using the DefaultValueConverter implementation.
  • License

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

    Change History

    Version 1.2 - June 2003

  • Added much requested support for setting the Targets property or invoking the addTarget() in WebLogic. This enables JMX4Ant to deploy the resources it creates. For example you can now call addTarget() on a JMSServer you create to deploy the JMSServer to a WebLogic server. Refer to JMX4Ant's WebLogic examples to see how to use this capability.
  • Added "warn" and "replaceAttributes" options to IfExists attribute. When IfExists is set to "warn", createMBean will write a warning to the log message if the mbean to be created already exists, and will leave the existing mbean in place without any modification and ignore any nested setAttribute elements. When IfExists is set to "replaceAttributes", createMBean will will leave the existing mbean in place but will process any nested setAttribute elements.
  • Added support for JBoss EJB connector (set serverType to "jboss.ejb"). This enhancement was contributed by Eric Jain, one of JMX4Ant's users. This connector may be more appropriate for remote JBoss servers as it supports authentication via user-id/password. If using this connector, you must have jbosssx-client.jar on the classpath before running Ant and must have the jmx-ejb-connector-server.sar service properly deployed within JBoss.
  • Added optional type attribute to the <parameter> element of <invokeMBean>. This allows parameters to be specified in any order (if type is supplied), and also allows for MBeans with overloaded methods to be invoked. This contribution was submitted by John Vasileff, another one of JMX4Ant's users.
  • Improved readability of output of showMBean
  • Added full support for arrays.
  • Fixed problem with failonerror attribute not halting the build if set to false
  • Cleaned up code to remove violations reported by PMD
  • Refactored IfExists functionality to reduce code.
  • Improved error handling and messages for incorrectly formatted parameter values of type java.util.Properties
  • Improved error messages when authentication problems occur
  • Improved error messages when parameter value conversion errors occur
  • Fixed null message on exception from JBoss connector
  • Version 1.1 - March 2003

  • Added jndiLookup task to allow JMX to test to see if a JMX entry exists.
  • Added context type to make it easier to reference the same JNDI context across multiple tasks.
  • Added mbean type to make it easier to reference the same MBean across multiple tasks
  • Enhanced CreateMBean and ConfigureMBean to allow setAttribute nested elements to allow the value to be specified as the content of those elements.
  • Enhanced InvokeMBean to allow parameter nested elements to allow the value to be specified as the content of those elements.
  • Enhanced weblogic examples.
  • Version 1.0 - January 17, 2003

  • Initial version supporting JBoss 3.x and WebLogic Server 6.x/7.x
  • $Id: overview.html,v 1.10 2003/05/28 22:26:16 bdueck Exp $


    Copyright © 2003. All rights Reserved.