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="[EMAIL PROTECTED]">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="[EMAIL PROTECTED]">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 <[EMAIL PROTECTED]>
* @author Paul Hammant <[EMAIL PROTECTED]>
* @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="[EMAIL PROTECTED]">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="[EMAIL PROTECTED]">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:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
