nicolaken 2002/11/18 06:19:14
Added: src/documentation/content/mx book.xml index.xml mxinfo.xml
overview.xml structure.xml xdoctags.xml
Log:
First step of migration of documentation to Forrest.
New docs dir:
jakarta-avalon-phoenix/src/documentation
New content dir:
jakarta-avalon-phoenix/src/documentation/content
New resources and images dir:
jakarta-avalon-phoenix/src/documentation/resources
To build the documentation download Forrest from CVS
http://xml.apache.org/forrest/your-project.html#N10022
install it as described here
http://xml.apache.org/forrest/your-project.html#N10036
cd in the jakarta-avalon-phoenix dir and run "forrest"
To see the site real-time from a local embedded webserver run "forrest run"
and point the browser to http://localhost:8888/
The sources to change are in ./build/webapp, you will need to synch them with
the actual docs manually.
Or run the Phoenix build.xml with target "site".
Revision Changes Path
1.1
jakarta-avalon-phoenix/src/documentation/content/mx/book.xml
Index: book.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
"book-cocoon-v10.dtd">
<book title="Avalon Phoenix" copyright="Avalon Phoenix" software="Avalon
Phoenix">
<menu label="Essentials">
<menu-item href="../index.html" label="Overview"/>
<menu-item href="../features.html" label="Features"/>
<menu-item href="../getting-started.html" label="Getting started"/>
<menu-item href="../http://jakarta.apache.org/builds/jakarta-avalon-phoenix";
label="Download"/>
<menu-item href="../install.html" label="Install"/>
</menu>
<menu label="Guide">
<menu-item href="../guide-architecture.html" label="Architectural Overview"/>
<menu-item href="../guide-roles.html" label="Development Roles"/>
<menu-item href="../guide-administrator.html" label="for Administrators"/>
<menu-item href="../guide-deployers.html" label="for Deployers"/>
<menu-item href="../assemblers/index.html" label="for Assemblers"/>
<menu-item href="../bdg/index.html" label="for Block Developers"/>
<menu-item href="../mx/index.html" label="Management Guide"/>
<menu-item href="../guide-example-configuration.html" label="Example
configuration"/>
</menu>
<menu label="Reference">
<menu-item href="../api/index.html" label="API Docs"/>
<menu-item href="../assemblers/config-xml-specification.html"
label="config.xml Specification"/>
<menu-item href="../assemblers/assembly-xml-specification.html"
label="assembly.xml Specification"/>
<menu-item href="../assemblers/environment-xml-specification.html"
label="environment.xml Specification"/>
<menu-item href="../bdg/blockinfo-specification.html" label="BlockInfo
Specification"/>
</menu>
<menu label="For Developers">
<menu-item href="../changes.html" label="Changes"/>
<menu-item href="../http://jakarta.apache.org/avalon/code-standards.html";
label="Coding standards"/>
<menu-item href="../for-developers-project-structure.html" label="Project
Structure"/>
<menu-item href="../http://jakarta.apache.org/site/cvsindex.html"; label="CVS
Repositories"/>
<menu-item href="../http://jakarta.apache.org/site/mail.html"; label="Mailing
Lists"/>
<menu-item
href="../http://nagoya.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=RESOLVED&product=Avalon&component=Phoenix";
label="TODO"/>
<menu-item
href="../http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Avalon&component=Phoenix";
label="Bug Database"/>
<menu-item
href="../http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Avalon&component=Phoenix&bug_severity=Enhancement";
label="Enhancement Requests"/>
<menu-item href="../for-developers-alternate-kernel.html" label="Alternate
Kernels"/>
</menu>
</book>
1.1
jakarta-avalon-phoenix/src/documentation/content/mx/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Management Guide</title>
<authors><person name="Huw Roberts" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
Management refers to how a running instance of Phoenix, along
with
its components, applications and blocks is supervised and
manipulated.
This guide covers the steps required to write
management-enabled
applications using Phoenix.
</p>
</section>
<section><title>Overview</title>
<p>
Management in Phoenix is divided into two distinct areas.
The first
area is the the management metadata. This information about
which
applications, blocks and
components should be managed, the operations and attributes
to expose, and descriptions for each these to help guide the
user.
Each block and component
stores this data in an 'MXINFO file' that is distributed along
with the class files that make up Phoenix and the
Phoenix-enabled
applications.
</p>
<p>
The second area is the Phoenix component that uses the
MXINFO files to generate a user interface through which
Phoenix
and its applications are interacted with. It is anticated
that a number
of such interfaces will be developed. The current
implementation
of the management component uses the MXINFO files to generate
ModelMBeans that are then registered and exposed through a
slightly
customized JMX implementation called
<link href="http://mx4j.sourceforge.net/";>MX4J</link>.
</p>
<p>
Note that nothing about the MXINFO file is dependant on using
JMX, and the block author does not need to know or care about
how Phoenix, the application, and its blocks will be managed.
His/her responsibility is limited to creating an MXINFO file.
</p>
<p>
The guide is broken into a number of sections, each
covering a particular aspect of the management picture.
</p>
</section>
<section><title>Organizing Structure for Management Data</title>
<p>
This section provides a conceptual overview of the elements
that
are used to represent management information within Phoenix.
An understanding of these elements and their relationships is
essential for all users are the management functionality.
</p>
<p>
<link href="structure.html">Structure</link>
</p>
</section>
<section><title>Step-By-Step Walk-Through</title>
<p>
This section walks through the steps that are needed to make a
block manageable. The emphasis is on illuminating the
process,
it does not cover every feature or option.
</p>
<p>
<link href="overview.html">Step-by-Step</link>
</p>
</section>
<section><title>MXINFO File Format</title>
<p>
Management meta-data is stored in MXINFO files. This section
describes its structure, as well as the runtime requirements
of the management agent.
</p>
<p>
<link href="mxinfo.html">MXINFO Format</link>
</p>
</section>
<section><title>Using XDoclet Tags to Generate MXINFO file</title>
<p>
Instead of writing MXINFO files directly it is recommended
that
component and block authors make use of custom tags inserted
into the source code. These tags are parsed using the
<link href="http://xdoclet.sourceforge.net/";>XDoclet</link>
engine to produce the MXINFO file. This section describes
how to use the feature.
</p>
<p>
<link href="xdoctags.html">XDoclet Tags</link>
</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/mx/mxinfo.xml
Index: mxinfo.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Management Guide - MXINFO File Format</title>
<authors><person name="Huw Roberts" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<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. It can be generated
automatically using xdoclet tags (<link
href="xdoctags.html">described here</link>)
or by hand.
</p>
<p>
At runtime it is expected that the mxinfo file will be have the same
name
as the class it describes (e.g. FtpServer.class would be described by
an
FtpServer.mxinfo file), and be located in the same package as that
class.
At startup the mxinfo file is parsed and, in conjuntion with class
introspection,
is used to define the in-memory metadata for management of the target
object.
</p>
<p>
Note that a target object is not restricted to having a single mxinfo
file, although the specifics of how that
works is dependant on the management component. 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><title>Example</title>
<p>
Since mxinfo files are somewhat confusing in the abstract, but
straight forward in practice,
the rest of this section describes an imaginary, yet somewhat
plausible, mxinfo file.
</p>
<source>
<?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="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>
1.1
jakarta-avalon-phoenix/src/documentation/content/mx/overview.xml
Index: overview.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Guide - Step by Step Overview</title>
<authors><person name="Huw Roberts" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
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.
</p>
<section><title>In Development</title>
<p>
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.
</p>
<p>
First, at the class level, the block must be tagged as
manageable
with @phoenix:mx-topic tag:
</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>
Then, for each attribute that should be exposed add the
@phoenix:mx-attribute tag:
</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 add the @phoenix:mx-operation
tag:
</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>
<?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>
</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 called 'mxinfo.dtd' and is available in the
/src/schema
directory of the source.
</p>
</section>
<section><title>At Startup</title>
<p>
At startup, Phoenix registers each block to a local
SystemManager context. This
context determines where the block fits into the
management hierarchy.
</p>
<p>
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.
</p>
<source>
// get the management context
final SystemManager componentManager =
systemManager.getSubContext( null, "component" );
// register the component
componentManager.register( ManagementRegistration.EMBEDDOR.getName(),
this,
ManagementRegistration.EMBEDDOR.getInterfaces() );
</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>
</section>
<section><title>While Running</title>
<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>
By default, the server is accessed on port 8082 of the
server. eg. http://localhost:8082.
</p>
</section>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/mx/structure.xml
Index: structure.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Management Guide - Organizing Structure</title>
<authors><person name="Huw Roberts" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
Phoenix Management seperates the information on what should be managed
from the implementation of the management agent. In order to maintain
this seperation, yet still allow the management interface to be rich
and structured enough to be useful, it is necessary to impose an
organizing
strucuture on the management metadata. This structure will be common
across all management interfaces, althought the specifics of how it is
exposed is up to the implementor.
</p>
</section>
<section><title>Elements</title>
<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>
<section><title>Context</title>
<p>
In Phoenix, each managed object belongs to a single Context
The Context contains a list of managed components called Targets.
In
addition to the list of Targets, a Context can also have zero or
more
sub-Contexts.
</p>
<p>
This nested structure of Contexts is the principle
organizing element for management data, and is the bridge between
the management code embedded in Phoenix and the implementation of
the
management component. It is represented by the
<pre>org.apache.avalon.phoenix.interfaces.SystemManager</pre>
interface.
</p>
</section>
<section><title>Target</title>
<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>
</section>
<section><title>Topic</title>
<p>
A topic is a logical grouping 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>
</section>
</section>
<section><title>Hierarchy</title>
<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>
Again, 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 between the two areas.
</p>
</section>
<section><title>Management Proxies</title>
<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 a more friendly type, (eg. from Date to String and back),
cleaning up method names,
providing backwards compatibility with older versions, and exposing
methods
missing from the target class, but available to it via a reference.
</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/mx/xdoctags.xml
Index: xdoctags.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Management Guide - XDoclet Tagging</title>
<authors><person name="Huw Roberts" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
Doclet tags inserted into source code 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><title>The Tags</title>
<p>
The following tags are defined:
</p>
<section><title>phoenix:mx-topic</title>
<table>
<tr>
<td>Scope</td>
<td>
Applies to classes 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 <link href="mailto:peter at apache.org">Peter Donald</link>
*/
</source>
</section>
<section><title>phoenix:mx-attribute</title>
<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>
</section>
<section><title>phoenix:mx-operation</title>
<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>
</section>
<section><title>phoenix:mx-description</title>
<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>
</section>
<section><title>phoenix:mx-proxy</title>
<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>
/**
* 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>
</section>
</section>
<section><title>Build Instructions</title>
<p>
To have mxinfo files generated as part as your ant build
script, include a task like that this:
</p>
<source>
<!-- 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>
</source>
<p>
Where build.qdox is where the .mxinfo files should be placed, and
java.dir
is the location of the source files.
</p>
<p>
The qdox jar and phoenix-client.jar need to be in the
project.class.path.
</p>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
