Management Guide - XDoclet Tagging

Doclet tags inserted into source code 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 following tags are defined:

Scope	Applies to classes 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 Peter Donald
 */
        

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();
        

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 )
        

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();
        

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 an 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
 */
 
        

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-qdox" depends="compile">

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

  <taskdef name="generatemeta"
      classname="org.apache.avalon.phoenix.tools.metagenerate.MetaGenerateTask">
    <classpath refid="project.class.path" />
  </taskdef>

  <generatemeta dest="${build.qdox}">
    <fileset dir="${java.dir}">
      <include name="**/*.java"/>
    </fileset>
  </generatemeta>

</target>

      

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

The qdox jar and phoenix-client.jar need to be in the project.class.path.