avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From h..@apache.org
Subject cvs commit: jakarta-avalon-phoenix/src/xdocs guide-mx-overview.xml guide-mx-xdoctags.xml guide-mx-structure.xml guide-mx-mxinfo.xml
Date Tue, 20 Aug 2002 04:50:47 GMT
huw         2002/08/19 21:50:47

  Added:       src/xdocs guide-mx-overview.xml guide-mx-xdoctags.xml
                        guide-mx-structure.xml guide-mx-mxinfo.xml
  Log:
  Initial draft of management documentation
  
  Revision  Changes    Path
  1.1                  jakarta-avalon-phoenix/src/xdocs/guide-mx-overview.xml
  
  Index: guide-mx-overview.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
      <properties>
          <title>Guide - Step by Step Overview</title>
          <author email="huw@apache.org">Huw Roberts</author>
      </properties>
      <body>
          <section name="Overview" >
              <p>
                This section gives a quick overview of how to go from a blocks source code,
to a managed object accessible
                in a management interface.  It does not cover every aspect, nor is it strictly
'correct'.
              </p>
  
              <subsection name="In Development">
                  <p>
                    For a block to be manageable, the developer inserts a series of XDoclet
tags
                    in the class file.  Right now these are:
                  </p>
                  <p>
                  At the class level:
                  </p>
  
                  <source>
  /**
   * 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
  ...
                  </source>
                  <p>
                  where @phoenix:mx-topic marks the block as eligible for management.
                  </p>
                  <p>
                  For each attribute:
                  </p>
                  <source>
      /**
       * @phoenix:mx-attribute
       * @phoenix:mx-description Returns the top published directory
       * @phoenix:mx-isWriteable false
       */
      public String getDefaultRoot() {
      ...
                  </source>
                  <p>
                  and finally for each operation:
                  </p>
                  <source>
      /**
       * @phoenix:mx-operation
       * @phoenix:mx-description Returns port that the server listens on
       */
      public String getServerPort(Integer instance) {
      ...
                  </source>
                  <p>
                      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.
                  </p>
                  <p>
                      Here's what the entry generated from the tags above looks like:
                  </p>
  
                  <source><![CDATA[
  <?xml version="1.0"?>
  <!DOCTYPE mxinfo PUBLIC "-//PHOENIX/Mx Info DTD Version 1.0//EN"
                    "http://jakarta.apache.org/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>
  
                  ]]></source>
  
                  <p>
                      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 available [TODO]here.
                  </p>
              </subsection>
              <subsection name="At Startup">
                  <p>
                      At startup, Phoenix registers each block to a local SystemManager context.
 This
                      context determines where the block fits into the management hierarchy.
                  </p>
                  <source>
                  [TODO - code snippet on the register line]
                  </source>
                  <p>
                      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.
                  </p>
              </subsection>
              <subsection name="While Running">
                  <p>
                      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.
                  </p>
                  <p>
                      The server is accessed on port 8082 of the server. eg. http://localhost:8082.
                  </p>
                  <p>TODO: Include screenshot?</p>
              </subsection>
          </section>
      </body>
  </document>
  
  
  
  1.1                  jakarta-avalon-phoenix/src/xdocs/guide-mx-xdoctags.xml
  
  Index: guide-mx-xdoctags.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Management Guide - XDoclet Tagging</title>
      <author email="huw@apache.org">Huw Roberts</author>
    </properties>
    <body>
      <section name="Outline">
        <ul>
          <li>
              describe the XDoclet tags and how they generate the mxinfo
          </li>
          <li>
              including how defaults are generated
          </li>
          <li>
              dependencies and how to set up ant to generate the mxinfo files
          </li>
        </ul>
      </section>
      <section name="Overview" >
        <p>
          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:
        </p>
        <ul>
          <li>
            its a lot faster than writing mxinfo files by hand
          </li>
          <li>
            its harder to make mistakes, since much of the data required for the mxinfo file
is
            parsed out of the source code
          </li>
          <li>
            useful defaults can be used by reading the standard javadoc.
          </li>
        </ul>
        <p>
          Any class or interface can be used to produce mxinfo files.  How they get used is
up to 
          container and its Management subsystem.
        </p>
      </section>
      <section name="The Tags" >
        <p>
          The following tags are defined:
        </p>
        <subsection name="phoenix:mx-topic">
          <table>
            <tr>
              <td>Scope</td>
              <td>
                Applies to a class and interfaces.
              </td>
            </tr>
            <tr>
              <td>Purpose</td>
              <td>
                Marks the class or interface as eligible for management.  
              </td>
            </tr>
            <tr>
              <td>Parameters</td>
              <td>
                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.
              </td>
            </tr>
            <tr>
              <td>Notes</td>
              <td>
           
              </td>
            </tr>
          </table>
          <p>
            Example:
          </p>
          <source>
  /**
   * This is the interface via which you can manager
   * the root container of Applications.
   *
   * @phoenix:mx-topic name="Kernel"
   *
   * @author <a href="mailto:peter at apache.org">Peter Donald</a>
   */
          </source>
        </subsection>
        <subsection name="phoenix:mx-attribute">
          <table>
            <tr>
              <td>Scope</td>
              <td>
                Applies to getter and setter methods.
              </td>
            </tr>
            <tr>
              <td>Purpose</td>
              <td>
                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.  
              </td>
            </tr>
            <tr>
              <td>Parameters</td>
              <td>
                None
              </td>
            </tr>
            <tr>
              <td>Notes</td>
              <td>
                Often used in conjuntion with the mx-isWriteable tag
              </td>
            </tr>
          </table>
          <p>
            Example:
          </p>
          <source>
      /**
       * Gets the list of applications running in the container
       *
       * @phoenix:mx-attribute
       *
       * @return applicationNames The array of application names
       */
      String[] getApplicationNames();
          </source>
        </subsection>
        <subsection name="phoenix:mx-operation">
          <table>
            <tr>
              <td>Scope</td>
              <td>
                Applies to methods that are not getters or setters.
              </td>
            </tr>
            <tr>
              <td>Purpose</td>
              <td>
                Marks the method as elible to be a management operation.  
              </td>
            </tr>
            <tr>
              <td>Parameters</td>
              <td>
                None
              </td>
            </tr>
            <tr>
              <td>Notes</td>
              <td>
                The standard javadoc is used to generate descriptions for any parameters to
the
                method.
              </td>
            </tr>
          </table>
          <p>
            Example:
          </p>
          <source>
      /**
       * Removes the application from the container
       *
       * @phoenix:mx-operation
       *
       * @param name the name of application to remove
       */
      void removeApplication( String name )
          </source>
        </subsection>
        <subsection name="phoenix:mx-description">
          <table>
            <tr>
              <td>Scope</td>
              <td>
                Applies to manageable attributes and operations (i.e. to methods that also
                have the mx-operation or mx-attribute tag).
              </td>
            </tr>
            <tr>
              <td>Purpose</td>
              <td>
                The text following the tag is a description of the method suitable for presentation
                in the management agent.
              </td>
            </tr>
            <tr>
              <td>Parameters</td>
              <td>
                None
              </td>
            </tr>
            <tr>
              <td>Notes</td>
              <td>
                Optional.  If ommitted the javadoc definition is used.            
              </td>
            </tr>
          </table>
          <p>
            Example:
          </p>
          <source>
      /**
       * 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();
          </source>
        </subsection>
        <subsection name="phoenix:mx-proxy">
          <table>
            <tr>
              <td>Scope</td>
              <td>
                Applies to classes.
              </td>
            </tr>
            <tr>
              <td>Purpose</td>
              <td>
                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.
              </td>
            </tr>
            <tr>
              <td>Parameters</td>
              <td>
                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.
              </td>
            </tr>
            <tr>
              <td>Notes</td>
              <td>
                At runtime it is expected the manager will instantiate the proxy class and
use
                it in place of the Target object.
              </td>
            </tr>
          </table>
          <p>
            Example:
          </p>
          <source>
  <![CDATA[                
  /**
   * 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
   */
   ]]>
          </source>
        </subsection>
      </section> 
      <section name="Build Instructions">
        <p>
          To have mxinfo files generated as part as your ant build
          script, include a task like that this:
        </p>
        <source>
  <![CDATA[                
  <!-- 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>  
   ]]>
        </source>
        <p>
          Where build.xdoclet is where the .mxinfo files should be placed, and java.dir 
          is the location of the source files.
        </p>
        <p>
          The xdoclet jars, phoenix-client.jar and log4j.jar need to be in 
          ant's classpath.
        </p>
      </section>
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon-phoenix/src/xdocs/guide-mx-structure.xml
  
  Index: guide-mx-structure.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Management Guide - Organizing Structure</title>
      <author email="huw@apache.org">Huw Roberts</author>
    </properties>
    <body>
      <section name="Outline">
        <ul>
          <li>
  	  a conceptual overview for management
          </li>
        </ul>
      </section>
      <section name="Elements" >
        <p>
          Management information is stored in a structured format that contains both a 
          functional definition of the actions (what can be done) and descriptive information
          about the actions (to help guide the user).  It is composed of the following elements:
        </p>
        <subsection name="Context">
          <p>
            The Context contains a list of managed components called Targets, and a
            list of sub-Contexts.
          </p>
        </subsection>
        <subsection name="Target">
          <p>
            A target is a manageable object.  Examples of Targets in Phoenix include the 
            components, the applications and the blocks.  Each target has one or more topics.
  	</p>
        </subsection>
        <subsection name="Topic">
          <p>
            A topic is a group of attributes that can be get and/or set on the Target and
a group of operations that can be called on it.  It is intended that Topics group together
            a particular aspect of Targets manageability.
          </p>
        </subsection>
      </section>
      <section name='Hierarchy'>
        <p>
  	This diagram illustrates how this might be presented in a management GUI:
        </p>
        <source>
  Phoenix 
   | 
   +--Components 
   |   +-- Kernel 
   |   +-- Deployer 
   |   +-- etc. 
   | 
   +--Applications 
       +--Hello World 
       |    +-- Blocks
       |          +-- Block 1 
       |          +-- Block 2 
       | 
       +-- Ftp Server 
            +-- Blocks
                  +-- Block 1 
                  +-- Block 2 
        </source>
        <p>
          In this example Phoenix, Components and Blocks are Contexts.  Kernel, Deployer,
Hello World, Block 1, etc are Targets.  Each Target will then have one or more Topics.  Topics
might be Logging, Lifecycle, Deployer, etc.  
        </p>
        <p>
          In a jmx environment each topic would most likely be exported as its own mbean 
          (so in the above example the jmx name would be 'Instance=Phoenix,Application=Hello_World,Block=Block_2,Topic=Logger'.
 
        </p>
        <p>
          In a swing environment each topic might have its own tab.
        </p>
        <p>
  	In a command line environment, the syntax might be:
        </p>
        <source>
  phoenix-mx.set( "Phoenix/Applications/Hello World/Logging/LogLevel", "DEBUG" );
  phoenix-mx.describe( ""Phoenix/Applications/Hello World/Logging/LogLevel" );
        </source>
        <p>
          The point behind the 'Organizing Structure' is to keep the management specification

          seperated from the  management agent, while at the same time providing enough definition

          to keep a shared conceptual view.
        </p>
      </section>
      <section name="Management Proxies" >
        <p>
          There is one remaining concept to cover, the proxy.  It is a class that can be used

          to wrap access to the underlying target.  Posible uses include the mapping of data

          types to more friendly type, (eg. from Date to String and back), cleaning up method
names, providing backwards
          compatibility with older versions, and exposing methods from classes reFerenced
by 
          the target class.
        </p>
      </section>
    </body>
  </document >
  
  
  1.1                  jakarta-avalon-phoenix/src/xdocs/guide-mx-mxinfo.xml
  
  Index: guide-mx-mxinfo.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Management Guide - MXINFO File Format</title>
      <author email="huw@apache.org">Huw Roberts</author>
    </properties>
    <body>
      <section name="Outline">
        <ul>
          <li>
            specified in the DTD, available here.[TODO]
          </li>
          <li>
            explain the various elements
          </li>
          <li>
            explain runtime requirements
          </li>
        </ul>
      </section>
      <section name="Overview" >
        <p>
          The mxinfo file is contains information about how the object it describes can be
managed.  It
          includes functional information intended for the management application, and descriptive
data
          to help guide the user.
        </p>
        <p>
          An mxinfo file is created at design time, either automatically using xdoclet tags
(TODO described here) 
          or by hand.  At startup the mxinfo file is parsed, and in conjuntion with class
introspection 
          is used to define the in-memory metadata for the management of the target object.
        </p>
        <p>
          A target object is not restricted to having a single mxinfo file, although the specifics
of how that
          works is dependant on the container (described [TODO] here).  Similarly it is expected
that
          at runtime the mxinfo file will be located in the classpath of the Target class,
in the same
          package as that class, but this is also under the control of the Container.  Finally,
its worth pointing out that an mxinfo file generated from interface can be applied to
          any class that implements the interface.
        </p>
      </section>
      <section name="Example" >
        <p>
          Since mxinfo files are somewhat confusing in the abstractm, but straight forward
in practice, 
          the rest of this section describes an imaginary, yet somewhat plausible, mxinfo
file.
        </p>
        <source>
  <![CDATA[        
  <?xml version="1.0"?>
  <!DOCTYPE mxinfo PUBLIC "-//PHOENIX/Mx Info DTD Version 1.0//EN"
                    "http://jakarta.apache.org/phoenix/mxinfo_1_0.dtd">
  
  <mxinfo>
  
      <topic name="ftpServer" >
  
        <!-- attributes -->
        <attribute
          name="addressString"
          description="Address String"
          isWriteable="no"
          type="java.lang.String"
        />
        <attribute
          name="serverAddress"
          description="Server bind address."
          isWriteable="no"
          type="java.net.InetAddress"
        />
  
        <!-- operations -->
        <operation
          name="getDefaultRoot"
          description="Gets the default root"
          type="java.lang.String"
        >
        </operation>
        <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>
  
      <proxy name="userManager" />
  
  </mxinfo>
  ]]>
        </source>
      </section> 
    </body>
  </document>
  
  
  

--
To unsubscribe, e-mail:   <mailto:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message