Proposal for Modeler Package

(0) Rationale

Among the myriad of Java APIs available is the Java Management Extensions (JMX) APIs, which define "an architecture, the design patterns, the APIs, and the services for application and network management in the Java programming language." These APIs include standards for designing "Managed Beans" (MBeans) that are associated with components of your application that you wish to make manageable via a variety of tools (either local or remote.

The JMX architecture includes a variety of design patterns for MBeans. The two most commonly used patterns are:

• Standard MBeans - The developer designs an interface that corresponds with the class for each managed resource, exposing only the attributes and operations required for management. The managed resource class must implement this interface, according to standard Java language rules, for this resource to become manageable.
• Model MBeans - A generic, configurable MBean which can be used to make almost any resource manageable. Rather than relying on implementing a Java interface, Model MBeans utilize metadata about the constructors, attributes, and operations that are supported to make calls on the managed resource's class, using Java's reflection APIs to call arbitrary methods with arbitrary arguments.

At first glance, Model MBeans sound incredibly useful -- they require no changes at all to the Java class representing the managed resource, and you can use a standard base class provided with the JMX implementation to perform almost all of your management requirements. However, the developer is still required to provide the metadata, which can be tedious to create when there are many managed resources, with many attributes and operations made available by those resources. This is where the Modeler comes in.

Modeler provides the following services to the application developer who wishes to make their applications manageable via JMX:

• Reads an XML-based description of the Model MBeans to be provided for a set of managed resource classes, defining all of the constructors, attributes (i.e. properties) and operations (i.e. methods) to be exposed to a management application. Note that, in many cases, additions to or removals from the set of APIs exposed for management can be made with no code changes.
• Provides a registry of these descriptions that allows the javax.management.modelmbean.ModelMBeanInfo object required by the JMX architecture to be synthesized in one or two lines of code.
• Supplies a base Model MBean implementation class that can be used for all management activities where the attribute accesses or operation calls are simply reflected on to the managed object, but can also serve as a superclass for cases where the MBean needs to perform additional functionality, such as event notification, in addition to calling the appropriate method on the managed resource class.

(1) Scope of the Package

The Modeler project shall create and maintain a set of Java classes to provide the facilities described in the preceeding section, plus unit tests and small examples of using these facilities to instrument Java classes with Model MBean support.

(1.5) Interaction With Other Packages

Modeler relies on:

• Java Development Kit (Version 1.2 or later)
• A JAXP 1.1 implementation
• A SAX 2.0 parser conforming to the JAXP 1.1 APIs
• BeanUtils from Commons - for instrospection information
• Collections from Commons - for object collections
• Digester from Commons - for parsing scripts in XML
• A JMX compliant implementation, like the JMX Instrumentation and Agent Specification reference implementation or OpenJMX

(2) Initial Source of the Package

This package represents original code that will be used initially to instrument the Tomcat 4 servlet container with JMX manageability for all major components.

The proposed package name for the new component is org.apache.commons.modeler.

(3) Required Jakarta-Commons Resources

• CVS Repository - New directory modeler in the jakarta-commons CVS repository.
• Mailing List - Discussions will take place on the general dev@commons.apache.org mailing list. To help list subscribers identify messages of interest, it is suggested that the message subject of messages about this component be prefixed with [Modeler].
• Bugzilla - New component "Modeler" under the "Commons" product category, with appropriate version identifiers as needed.
• Jyve FAQ - New category "commons-modeler" (when available).

(4) Initial Committers

The initial committers on the Modeler component shall be:

• Craig R. McClanahan
• Remy Maucherat
• Costin Manolache