Outline

  • describe the XDoclet tags and how they generate the mxinfo
  • including how defaults are generated
  • dependencies and how to set up ant to generate the mxinfo files

Overview

XDoclet tags can be inserted into source code to automatically generate the mxinfo file. There are a number of advantages to doing it this way:

  • its a lot faster than writing mxinfo files by hand
  • its harder to make mistakes, since much of the data required for the mxinfo file is parsed out of the source code
  • useful defaults can be used by reading the standard javadoc.

Any class or interface can be used to produce mxinfo files. How they get used is up to container and its Management subsystem.

The Tags

The following tags are defined:

phoenix:mx-topic

Scope Applies to a class and interfaces.
Purpose Marks the class or interface as eligible for management.
Parameters It takes a single attribute, called name, that will be used to uniquely define the Topic for each Target that includes it. This name may be presented to the user in the management agent.
Notes

Example: 

/**
 * This is the interface via which you can manager
 * the root container of Applications.
 *
 * @phoenix:mx-topic name="Kernel"
 *
 * @author 
 */

phoenix:mx-attribute

Scope Applies to getter and setter methods.
Purpose Marks the method as being a getter or setter and as eligible for management. If the class defines a getter and setter, then just getter should be marked up.
Parameters None
Notes Often used in conjuntion with the mx-isWriteable tag

Example: 

/**
     * Gets the list of applications running in the container
     *
     * @phoenix:mx-attribute
     *
     * @return applicationNames The array of application names
     */
    String[] getApplicationNames();

phoenix:mx-operation

Scope Applies to methods that are not getters or setters.
Purpose Marks the method as elible to be a management operation.
Parameters None
Notes The standard javadoc is used to generate descriptions for any parameters to the method.

Example: 

/**
     * Removes the application from the container
     *
     * @phoenix:mx-operation
     *
     * @param name the name of application to remove
     */
    void removeApplication( String name )

phoenix:mx-description

Scope Applies to manageable attributes and operations (i.e. to methods that also have the mx-operation or mx-attribute tag).
Purpose The text following the tag is a description of the method suitable for presentation in the management agent.
Parameters None
Notes Optional. If ommitted the javadoc definition is used.

Example: 

/**
     * Retrieve a string identifying version of server.
     * Usually looks like "v4.0.1a".
     *
     * @phoenix:mx-attribute
     * @phoenix:mx-description Retrieve a string identifying version of server.
     *
     * @return version string of server.
     */
    String getVersion();

phoenix:mx-proxy

Scope Applies to classes.
Purpose The proxy tag is used to indicate that a proxy class should be used to manage some aspect(s) of this object. At runtime, the management system will instantiate in instance of the proxy class passing in a reference to the managed object in the constructor. Management calls are then made on the proxy instead of the managed object.
Parameters Takes a single attribute, "name" that must be the full class name of a class to be used as proxy for the management of this class.
Notes At runtime it is expected the manager will instantiate the proxy class and use it in place of the Target object.

Example: 

/**
 * Ftp server starting point. Avalon framework will load this
 * from the jar file. This is also the starting point of remote
 * admin.
 *
 * @phoenix:block
 * @phoenix:service name="org.apache.avalon.ftpserver.interfaces.FtpServerInterface"
 *
 * @phoenix:mx-proxy class="org.apache.avalon.ftpserver.FtpServerMxProxy"
 *
 * @author  Rana Bhattacharyya <rana_b@yahoo.com>
 * @author  Paul Hammant <Paul_Hammant@yahoo.com>
 * @version 1.0
 */

Build Instructions

To have mxinfo files generated as part as your ant build script, include a task like that this: 

<!-- Make .mxinfo automatically for blocks -->
<target name="phoenix-xdoclet" depends="compile">

  <mkdir dir="${build.xdoclet}"/>

  <taskdef name="phoenix-mxinfo"
           classname="org.apache.avalon.phoenix.tools.xdoclet.PhoenixXDoclet"
           classpathref="project.class.path"/>

  <phoenix-mxinfo
     destdir="${build.xdoclet}"
      classpathref="project.class.path">
    <fileset dir="${java.dir}">
      <include name="**" />
    </fileset>
    <mxinfo/>
  </phoenix-mxinfo>

</target>

Where build.xdoclet is where the .mxinfo files should be placed, and java.dir is the location of the source files.

The xdoclet jars, phoenix-client.jar and log4j.jar need to be in ant's classpath.