huw 2002/09/15 22:40:21
Modified: src/xdocs/mx xdoctags.xml structure.xml overview.xml
index.xml mxinfo.xml
Log:
Incremental improvements to each of the pages. Filled in or removed the TODO
tags.
Revision Changes Path
1.3 +4 -17 jakarta-avalon-phoenix/src/xdocs/mx/xdoctags.xml
Index: xdoctags.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-phoenix/src/xdocs/mx/xdoctags.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- xdoctags.xml 15 Sep 2002 02:07:32 -0000 1.2
+++ xdoctags.xml 16 Sep 2002 05:40:20 -0000 1.3
@@ -6,27 +6,14 @@
<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" >
+ <section name="Introduction" >
<p>
- XDoclet tags can be inserted into source code to automatically
generate the mxinfo file.
+ XDoclet 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
+ 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
@@ -37,7 +24,7 @@
</li>
</ul>
<p>
- Any class or interface can be used to produce mxinfo files. How
they get used is up to
+ 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>
1.3 +29 -14 jakarta-avalon-phoenix/src/xdocs/mx/structure.xml
Index: structure.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-phoenix/src/xdocs/mx/structure.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- structure.xml 15 Sep 2002 02:07:32 -0000 1.2
+++ structure.xml 16 Sep 2002 05:40:20 -0000 1.3
@@ -6,12 +6,16 @@
<author email="[EMAIL PROTECTED]">Huw Roberts</author>
</properties>
<body>
- <section name="Outline">
- <ul>
- <li>
- a conceptual overview for management
- </li>
- </ul>
+ <section name="Introduction">
+ <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 name="Elements" >
<p>
@@ -21,8 +25,18 @@
</p>
<subsection name="Context">
<p>
- The Context contains a list of managed components called Targets,
and a
- list of sub-Contexts.
+ 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>
</subsection>
<subsection name="Target">
@@ -33,7 +47,8 @@
</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 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>
</subsection>
@@ -79,18 +94,18 @@
phoenix-mx.describe( ""Phoenix/Applications/Hello World/Logging/LogLevel" );
</source>
<p>
- The point behind the 'Organizing Structure' is to keep the
management specification
+ 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.
+ to keep a shared conceptual view between the two areas.
</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.
+ 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>
1.3 +34 -17 jakarta-avalon-phoenix/src/xdocs/mx/overview.xml
Index: overview.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-phoenix/src/xdocs/mx/overview.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- overview.xml 15 Sep 2002 02:07:32 -0000 1.2
+++ overview.xml 16 Sep 2002 05:40:20 -0000 1.3
@@ -6,19 +6,25 @@
<author email="[EMAIL PROTECTED]">Huw Roberts</author>
</properties>
<body>
- <section name="Overview" >
+ <section name="Introduction" >
<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'.
+ 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>
<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:
+ 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>
- At the class level:
+ First, at the class level, the block must be tagged as
manageable
+ with @phoenix:mx-topic tag:
</p>
<source>
@@ -35,10 +41,8 @@
...
</source>
<p>
- where @phoenix:mx-topic marks the block as eligible for
management.
- </p>
- <p>
- For each attribute:
+ Then, for each attribute that should be exposed add the
+ @phoenix:mx-attribute tag:
</p>
<source>
/**
@@ -50,7 +54,7 @@
...
</source>
<p>
- and finally for each operation:
+ and finally for each operation add the @phoenix:mx-operation
tag:
</p>
<source>
/**
@@ -108,7 +112,8 @@
<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.
+ The DTD is called 'mxinfo.dtd' and is available in the
/src/schema
+ directory of the source.
</p>
</subsection>
<subsection name="At Startup">
@@ -116,9 +121,22 @@
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 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><![CDATA[
+// 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
@@ -132,9 +150,8 @@
blocks.
</p>
<p>
- The server is accessed on port 8082 of the server. eg.
http://localhost:8082.
+ By default, the server is accessed on port 8082 of the
server. eg. http://localhost:8082.
</p>
- <p>TODO: Include screenshot?</p>
</subsection>
</section>
</body>
1.3 +83 -12 jakarta-avalon-phoenix/src/xdocs/mx/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-phoenix/src/xdocs/mx/index.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.xml 15 Sep 2002 02:07:32 -0000 1.2
+++ index.xml 16 Sep 2002 05:40:20 -0000 1.3
@@ -6,19 +6,90 @@
<author email="[EMAIL PROTECTED]">Huw Roberts</author>
</properties>
<body>
- <section name="Who Should Read This Book?">
- <p>This guide documents how a developer will go about enabling
- JMX Management support for their application or for the kernel.
- The text assumes that the reader has a basic understanding of
- JMX.</p>
+ <section name="Introduction">
+ <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 name="Contents">
- <ol>
- <li><a href="overview.html">Overview</a></li>
- <li><a href="structure.html">The Structure of Management
hierarchy</a></li>
- <li><a href="mxinfo.html">The MXInfo format</a></li>
- <li><a href="xdoctags.html">Integration with XDoclet</a></li>
- </ol>
+ <section name="Overview">
+ <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
+ <a href="http://mx4j.sourceforge.net/";>MX4J</a>.
+ </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 name="Organizing Structure for Management Data">
+ <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>
+ <a href="structure.html">Structure</a>
+ </p>
+ </section>
+ <section name="Step-By-Step Walk-Through">
+ <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>
+ <a href="overview.html">Step-by-Step</a>
+ </p>
+ </section>
+ <section name="MXINFO File Format">
+ <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>
+ <a href="mxinfo.html">MXINFO Format</a>
+ </p>
+ </section>
+ <section name="Using XDoclet Tags to Generate MXINFO file">
+ <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
+ <a href="http://xdoclet.sourceforge.net/";>XDoclet</a>
+ engine to produce the MXINFO file. This section describes
+ how to use the feature.
+ </p>
+ <p>
+ <a href="xdoctags.html">XDoclet Tags</a>
+ </p>
+ </section>
</body>
</document>
1.3 +4 -17 jakarta-avalon-phoenix/src/xdocs/mx/mxinfo.xml
Index: mxinfo.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-phoenix/src/xdocs/mx/mxinfo.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- mxinfo.xml 15 Sep 2002 02:07:32 -0000 1.2
+++ mxinfo.xml 16 Sep 2002 05:40:20 -0000 1.3
@@ -6,33 +6,20 @@
<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" >
+ <section name="Introduction" >
<p>
- The mxinfo file is contains information about how the object it
describes can be managed. It
+ 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)
+ An mxinfo file is created at design time, either automatically using
xdoclet tags (<a href="xdoctags.html">described here</a>)
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
+ works is dependant on the management component. 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
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
