Management Proposal

[Huw Roberts <Hu...@mmlive.com>]

I sent an email about 3 weeks ago which outlined a plan for using xdoclets
to generate xml, which is read by a configuration mbean that is then
exported for management via jmx or some other method.  Work swallowed me up
for a while there, and then over the last week or so i've been trying to
flesh out the details of how this might work.

This email reintroduces and expands on the idea, describing an alternative
implementation for management functionality.

1. Managed object repository
============================

This replaces the current SystemManager implementations with a
RegistrySystemManager which stores the managed object metadata into a
management hierarchy.  The hierarchy consists of MgmtTargets and MgmtLists.
For example the hierarchy might look like this:

Phoenix
 |
 +--Component List
 |   +-- Kernel
 |   +-- Deployer
 |   +-- etc.
 |
 +--Application List
     +--Hello World
     |    +-- Block List
     |          +-- Block 1
     |          +-- Block 2
     |
     +-- Ftp Server
          +-- Block List
                +-- Block 1
                +-- Block 2

In this example Phoenix, Kernel, Deployer, Hellow World, Block 1 are
MgmtTargets and Components, Applications and Blocks are MgmtLists.  In a JMX
type management environment the targets are exported as MBeans while the
lists provide naming information.  For example, when export Hello World's
Block 2 the name would be generated by walking the list resulting in:
Instance=Phoenix,Application=Hello_World,Block=Block_2.

Each MgmtTarget has one or more MgmtTopics.  A Mgmt topic is a set of
attributes and operations that relate to one particular aspect of an objects
manageability. For example the 'Logger' topic is one that would appear be
reused over and over again in the hierarchy.  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'.  In a
swing environment each topic might have its own tab.

The classes implementing this functionality, (currently) in the
org.apache.avalon.metainfo.mx package, are MgmtTarget, MgmtList, MgmtTopic,
MgmtListener, MgmtAttributeDescriptor, MgmtOperationDescriptor and
MgmtOperationParamDescriptor.

(see org-apache-avalon-phoenix-metainfo-mx.zip)

At least the last three of these could/should be replaced with analoguous
classes from the java.beans package, but i'm learning as i go.

2. Building the Hierarchy
=========================

The hierarchy is built by exporting objects to the current
ManagementContext.  The ManagementContext is an implementation of the
SystemManager interface that has a new method added for getting a named
subcontext from the current context.  The RegistrySystemManager is the root
context.  In the example above the root context has two subcontexts, the
Component context and the Application context.  Each Application context in
turn has a Block context.

So the code that registers the Phoenix Components (in DefaultEmbeddor)
changes from:

  systemManager.register( ManagementRegistration.EMBEDDOR.getName(),
                          this, 
                          ManagementRegistration.EMBEDDOR.getInterfaces() );

  for( int i = 0; i < m_entries.length; i++ )
  {
    final ManagementRegistration registration =
    ManagementRegistration.getManagementInfoForRole( m_entries[ i
].getRole() );
    if ( null != registration )
    {
      systemManager.register( registration.getName(), 
                              m_entries[ i ].getObject(), 
                              registration.getInterfaces() );
    }
  }

to:

  SystemManager componentManager = systemManager.getSubContext( "component"
);
        
  componentManager.register( ManagementRegistration.EMBEDDOR.getName(),
                             this, 
                             ManagementRegistration.EMBEDDOR.getInterfaces()
);

  for( int i = 0; i < m_entries.length; i++ )
  {
    final ManagementRegistration registration =
      ManagementRegistration.getManagementInfoForRole( m_entries[ i
].getRole() );
      if ( null != registration )
      {
        componentManager.register( registration.getName(),
                                   m_entries[ i ].getObject(), 
                                   registration.getInterfaces() );
      }
  }

Subcontexts are received in an identical way for the Application list and
each block list.

To implement this, the getSubContext() method needs to be added to the
SystemManager interface.  There are two new class ManagementContext (which
is the implementation of SystemManager used by subcontexts) and
RegistrySystemManager which is the root context as well as a component.
There is also a JMXBridge class that is used to drive the MX4JSystemManager
as a temporary hack.

(see org-apache-avalon-phoenix-components-manager.zip)

3. Defining the Topics
======================

So, there is a management hierarchy and there is an interface to the
existing code for registering objects for management.  How does it know what
methods to expose, and how is additional info about the methods specified?

When an object is registered for management, the ManagementContext calls the
MxTopicBuilder class to generate the MgmtTopic class(es) for it.  There are
four ways it does this:
1) by reading the class's mxinfo file which describes the attributes and
operations for the classes 'main' topic
2) by specifying proxy classes that expose some management functionality for
the class.  The idea here is to be able to specify facades for classes when
there public methods are not suitable.  More about this one later - one
example where i think it works well is exposing the logger to management.
3) if an interface is explicitly requested in the export method, its mxinfo
file is loaded and used to generate a topic.
4) if an interface is explicitly requested but no mxinfo can be found then
the topic is generated through introspection.

As noted above, pretty much all of this is implemented by the
org.apache.avalon.tools.infobuilder.MxTopicBuilder class.

(see org-apache-avalon-phoenix-tools-infobuilder.zip.  it includes some
mxinfo examples)

4. Generating .mxinfo Files
===========================

.mxinfo files can be written by hand (I guess) or the source code can be
marked up with xdoclet tags.

That part is described in the previous email, accessible here:
http://www.mail-archive.com/avalon-phoenix-dev@jakarta.apache.org/msg00519.h
tml

There is one new class:
org.apache.avalon.phoenix.tools.xdoclet.MxInfoSubTask.  Minor mods are also
required to the build scripts for phoenix and the applications.



---------------

So that's more or less where I've got to.  I'd like to see it as part of
Phoenix, and am happy to make modifications and improvements as required to
get all or part of it accepted, assuming there is interest.  I really
believe that it provides a way for phoenix and phoenix  enabled applications
to expose a rich management interface without knowing or caring about what
that interface will be, and this seperation of concerns is what draws me to
Avalon in the first place.  That said, I don't think the classes, as
attached, are ready to be added straight into the source tree.  Instead I'd
like to submit changes over the course of a week or two that bring this
about with less risk and more opportunity for input.  Please let me know
what you think.

Re: Management Proposal

[Leo Simons <le...@apache.org>]

Huw,

I haven't got time atm to respond to this in detail, unfortuneately.
However at a glance it looks to be just about what we need.

I think you're on a roll and if you were to completely integrate all
this with phoenix, that'd really cool =)

more later,

- Leo Simons



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>