Guide - Step by Step Overview

This section gives a quick overview of how to go from a block's source code, to a managed object accessible in a management interface. It discusses the role of actors at three different points in the life cycle of the application: during development, at start-up, and while running.

For a block to be manageable, the developer must provide an MXINFO file along with the compiled code. The easiest way to do that is to insert a series of XDoclet tags into the source file. An example of how to use these tags follows.

First, at the class level, the block must be tagged as manageable with @phoenix:mx-topic tag:

/**
 * 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:mx-topic name="ftpServer"
 * @phoenix:service name="org.apache.avalon.ftpserver...
 */
public class FtpServerImpl extends AbstractLogEnabled
...
                

Then, for each attribute that should be exposed add the @phoenix:mx-attribute tag:

    /**
     * @phoenix:mx-attribute
     * @phoenix:mx-description Returns the top published directory
     * @phoenix:mx-isWriteable false
     */
    public String getDefaultRoot() {
    ...
                

and finally for each operation add the @phoenix:mx-operation tag:

    /**
     * @phoenix:mx-operation
     * @phoenix:mx-description Returns port that the server listens on
     */
    public String getServerPort(Integer instance) {
    ...
                

When this is compiled the PhoenixDoclet task extracts this and inserts it into an mxinfo file. If a method doesn't have a @pheonix:mx-attribute tag it is not exposed for management.

Here's what the entry generated from the tags above looks like:

<?xml version="1.0"?>
<!DOCTYPE mxinfo PUBLIC "-//PHOENIX/Mx Info DTD Version 1.0//EN"
                  "http://jakarta.apache.org/avalon/dtds/phoenix/mxinfo_1_0.dtd">

<mxinfo>

    <topic name="ftpServer" >

      <!-- attributes -->
      <attribute
        name="defaultRoot"
        description="Returns the top published directory"
        isWriteable="no"
        type="java.lang.String"
      />

      <!-- operations -->
      <operation
        name="getServerPort"
        description="Returns port that the server listens on"
        type="java.lang.String"
      >
        <param
          name="instance"
          description="no description"
          type="java.lang.Integer"
        />
      </operation>

    </topic>

</mxinfo>

                

Alternatively, you could write the mxinfo file directly (particularly in cases where you can't/don't want to modify the source code). The DTD is called 'mxinfo.dtd' and is available in the /src/schema directory of the source.

At startup, Phoenix registers each block to a local SystemManager context. This context determines where the block fits into the management hierarchy.

The following code snippet shows the code snippet that registers the Embeddor component with the 'component' management context. A similar process is followed for registering the blocks in the application.

// get the management context
final SystemManager componentManager =
    systemManager.getSubContext( null, "component" );

// register the component
componentManager.register( ManagementRegistration.EMBEDDOR.getName(),
                           this,
                           ManagementRegistration.EMBEDDOR.getInterfaces() );    
                

The system manager uses the mxinfo file in conjunction with introspection to generate a ModelMBeanInfo object for each topic. A RequiredModelMBean is then created and exposed for management.

In the default configuration, management is provided through MX4J. The administrator can perform various tasks such as deploying, starting and stopping applications and changing the configuration of various blocks.

By default, the server is accessed on port 8082 of the server. eg. http://localhost:8082.