avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hamm...@apache.org
Subject cvs commit: jakarta-avalon-phoenix/src/xdocs/mx index.xml mxinfo.xml overview.xml structure.xml xdoctags.xml
Date Mon, 16 Sep 2002 20:47:32 GMT
hammant     2002/09/16 13:47:31

  Modified:    src/xdocs/mx Tag: RELEASE_402-branch index.xml mxinfo.xml
                        overview.xml structure.xml xdoctags.xml
  Log:
  Updated MX4J/JMX docs for Huw.
  
  Revision  Changes    Path
  No                   revision
  
  
  No                   revision
  
  
  1.1.2.2   +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.1.2.1
  retrieving revision 1.1.2.2
  diff -u -r1.1.2.1 -r1.1.2.2
  --- index.xml	6 Sep 2002 23:26:38 -0000	1.1.2.1
  +++ index.xml	16 Sep 2002 20:47:31 -0000	1.1.2.2
  @@ -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.1.2.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.1.2.2
  retrieving revision 1.1.2.3
  diff -u -r1.1.2.2 -r1.1.2.3
  --- mxinfo.xml	6 Sep 2002 23:51:36 -0000	1.1.2.2
  +++ mxinfo.xml	16 Sep 2002 20:47:31 -0000	1.1.2.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
  
  
  
  1.1.2.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.1.2.2
  retrieving revision 1.1.2.3
  diff -u -r1.1.2.2 -r1.1.2.3
  --- overview.xml	6 Sep 2002 23:51:36 -0000	1.1.2.2
  +++ overview.xml	16 Sep 2002 20:47:31 -0000	1.1.2.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.1.2.2   +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.1.2.1
  retrieving revision 1.1.2.2
  diff -u -r1.1.2.1 -r1.1.2.2
  --- structure.xml	6 Sep 2002 23:26:38 -0000	1.1.2.1
  +++ structure.xml	16 Sep 2002 20:47:31 -0000	1.1.2.2
  @@ -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.1.2.2   +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.1.2.1
  retrieving revision 1.1.2.2
  diff -u -r1.1.2.1 -r1.1.2.2
  --- xdoctags.xml	6 Sep 2002 23:26:38 -0000	1.1.2.1
  +++ xdoctags.xml	16 Sep 2002 20:47:31 -0000	1.1.2.2
  @@ -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>
  
  
  

--
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