You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by hu...@apache.org on 2002/09/16 07:40:21 UTC
cvs commit: jakarta-avalon-phoenix/src/xdocs/mx xdoctags.xml structure.xml overview.xml index.xml mxinfo.xml
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="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" >
+ <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="huw@apache.org">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="huw@apache.org">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="huw@apache.org">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="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" >
+ <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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>