Multi-Protocol Agent Architecture

 

Overview

Instrumentation Level (MBeans)

MBean Server

Adaptors

Overview

 

AdventNet supports six adaptors/connectors for various protocols viz. SNMP, RMI, CORBA, TL1, HTTP.  Users can write their own adaptors for other protocols and plug them into the multi-protocol agent architecture. Since the JMX specification does not spell out any standards for adaptors, AdventNet's adaptors have proprietory implementation. However, if JMX evolves with specs for protocol adaptors, AdventNet's adaptors can be easily migrated to the same. 

 

This chapter explains the AdventNet Multi-Protocol agent architecture, which comprises of the following components :

Instrumentation Level (MBeans)

 

The instrumentation level is the level in which the management data is collected by the agent or applied on the agent. This level is common for all the management protocols supported on the agent. The agent developer is required to implement the instrumentation at this level, and make it available as Java components called MBeans.

 

What  are MBeans?

 

A Managed Bean or MBean in short  is a Java object that implements specific interfaces and conforms to certain design patterns. MBeans encapsulate manageable objects as attributes and operations through their public methods and follow the design patterns for exposing them to management applications.

 

For example, a read-only attribute will have just a getter method, whereas a read-write attribute will have getter and setter methods.

 

Why MBeans?

 

Any object that is implemented as an MBean and registered with the agent can be managed from outside the agents Java virtual machine. Such objects include the following :

Different Types of MBeans

 

AdventNet supports three types of MBeans namely :

Each of these correspond to different instrumentation requirements.  The following section covers the three ways to instrument a resource by writing a standard MBean, by implementing a dynamic MBean, or by dynamically instantiating a configurable model MBean.

 

Standard MBean

 

Overview

 

A Standard MBean is the easiest way to define an MBean. It provides a static management interface, which is fixed at compile time and is invoked by reflection. The management information is exposed using the interface which drives the standard mbeans.

 

The interface of a standard MBean is referred to as its MBean interface. Its name is formed by adding the suffix "MBean" to its class name. For example, the MBean interface name for the MBean called "MyClass"  would be "MyClassMBean.

 

Standard MBean's Interface

 

The Standard Mbean's interface is made up of the methods it makes available for reading and writing its attributes and for invoking its operations. When defining this management interface for the Java object, it should follow the  design patterns listed in the instrumentation part of the JMX specification. The management interface of a standard MBean is composed of its attributes and operations.

Running the Standard MBean Example

 

The Standard MBean example is available in the <Agent Toolkit Home>/examples/jmx/standardMBean directory.   It illustrates  the usage of  the StandardMBean registered with the Multi-Protocol agent. To run the example, please refer to the Readme.html file.

 

Dynamic MBean

 

Overview

 

Unlike the Standard MBean, the Dynamic MBeans do not have getter and setter methods for each attribute and operation. Instead, they have generic methods for getting or setting an attribute by name, and for invoking operations by name. These methods are common to all dynamic MBeans and are defined by the DynamicMBean interface.

 

The management interface is determined by the set of attribute and operation names to which these methods will respond. The getMBeanInfo method of the DynamicMBean interface returns a data structure,  which describes the management interface. This metadata contains the attribute and operation names, their types, and the notifications that may be sent if the MBean is a broadcaster.

 

The management interface of a dynamic MBean is static, but this interface is exposed dynamically when the MBean server calls its getMBeanInfo method.

 

When Dynamic MBean is used?

 

Let's consider a scenario where the attributes and operations exposed are likely to change often. In this case, the instrumentation must provide more flexibility, such as being determined dynamically at run time.  In such case, the standard MBean model doesn't work well, Dynamic MBeans bring this adaptability and provide an alternative instrumentation with more elaborate management capabilities.

The DynamicMBean Interface

 

The javax.management.DynamicMBean interface,  exposes the attributes and operations only at run time. Instead of exposing the attribute and operation names directly, it exposes them through relevant descriptors.  The resource object's class, to be recognized as a dynamic MBean by the Multi-Protocol agent or one of its super classes, must implement the DynamicMBean interface.

 

The DynamicMBean interface in the javax.management package is defined by the following methods :

      public interface DynamicMBean {
      public MBeanInfo getMBeanInfo();
      public Object getAttribute(String attribute) throws
      AttributeNotFoundException, MBeanException,
      ReflectionException;
      public void setAttribute(Attribute attribute) throws
      AttributeNotFoundException,   InvalidAttributeValueException,
      MBeanException, ReflectionException ;
      public AttributeList getAttributes(String[ ] attributes);
      public AttributeList setAttributes(AttributeList attributes);
      public Object invoke(String actionName, Object params[], String
      signature[])
      throws MBeanException, ReflectionException ;}

The getMBeanInfo method returns an MBeanInfo object,  which contains the definition of the MBean's management interface. It contains a list of attribute names and types, a list of operations and their parameters, and other management information.

 

From the MBeanInfo object,  the Multi-Protocol agent can get the  characteristics of all the Attributes/Operations. With this information of the Attribute, the Multi-Protocol agent can access the attribute(s) value(s) through the getAttribute(s) methods. Similarly, attribute(s) can be set by calling the setAttribute(s) methods using the Dynamic MBean interface of the resource object.

 

For invoking any method (the Operation that is exposed by the MBeanInfo) on the resource through a DynamicMBean object, the invoke method of the Dynamic MBean interface will be used by the JMX agent. If the operation is expected to return an object, then that object will be returned by this invoke method.

 

Running the Dynamic MBean Example

 

The Dynamic MBean example is available in the <Agent Toolkit Home>/examples/jmx/dynamicMBean directory.   It illustrates  the usage of  the Dynamic MBean registered with the Multi-Protocol agent. It would also serve to know how to develop a Dynamic MBean.  To run the example, please refer to the Readme.html file.

 

Model MBean

 

Overview

 

The Model MBean specification is an interface that provides a management template for managed resources. It is a generic and configurable form of Dynamic MBean. The javax.management.RequiredModelMBean class is an implementation of Model MBean interface along with the Dynamic MBean interface. Model MBeans are used for instrumenting resources programmatically at run time.

 

To instrument a resource and expose it dynamically, follow the steps given below:

How Model MBean is different from other MBeans?

 

In the case of Dynamic MBean model, the properties of the instrumentation class, which the user is interested to manage, are exposed through the Dynamic MBean interface implemented by this instrumentation class. In Model MBean model, these properties are described, i.e., initialized, by XML files.

 

The Model MBean information includes a descriptor for each attribute, constructor and notification in its management interface. A descriptor is an essential component of the Model MBean. It contains dynamic, extensible, and configurable behavior information for each MBean component. They provide the mapping between the attributes and the operations in the management interface and the actual methods that need to be called to satisfy the get, set, or invoke request.

 

Merits of Model MBean

 

The javax.management.RequiredModelMBean class acts as a generic template for creating manageable objects dynamically. Thus, resources, services, and applications can use this class by passing their instrumentation object and configure the exposure of default behavior through XML file or through DescriptorList and register it with the server (Multi-Protocol agent).

 

For example,

      // User Instrumentation class
      agentSystemInstrument= new AgentSystemInstrument();// Initialize the RequiredModelMBean with the xml file.
      rmm = new RequiredModelMBean
      (com.adventnet.utils.jmx.Utilities.convertXmlToModelMBeanInfo
      ("./agentProjects/jmxProject/mySources/AgentSystemInstrument.xml"));

      rmm.setManagedResource(agentSystemInstrumentExt, "objectReference");

      // the ObjectName for the instrumentation.
      name = "AGENT_SAMPLE_MIB_JMX:type=AgentSystemInstrumentExt";

      // finally register with the Multi-Protocol agent, i.e, MBeanServer.
      server.registerMBean(rmm, new ObjectName(name));

Key Features of RequiredModelMBean supported in this release :

XML Initialization

 

Why is it required?

 

This allows the XML encoded data, representing the metadata of a Model MBean, to be used for initializing the MBean. The ModelMBean(Attribute)Info[], ModelMBean(Operation)Info[], andModelMBean(Notification)Info[] get initialized by this XML.

 

During initialization, the MBeanInfo of the Dynamic MBean interface gets created from the formed ModelMBean(Attribute)Info[], ModelMBean(Operation)Info[], ModelMBean(Notification)Info[].

Retrieval of various fields present in the XML (the descriptor for each attribute/operation /notification) class can be done as follows :

 

For AgentSystemInstrument.xml (the XML file for agentSystem group in agent-sample-mib.txt located in  <Agent Toolkit Home>/mibs directory) file,  the code for retrieving the OID for AgentDescr attribute from the Model MBean that is registered with the MBean Server with ObjectName "AGENT_SAMPLE_MIB_JMX:type=AgentSystemInstrument" is as follows:

      String descr = ads.getFieldValue("description");
      //returns "Location information for the Agent"

      Descriptor adss = attrInfo[0].getDescriptor();
      Descriptor columnDescriptor =
      (Descriptor)adss.getFieldValue("columnAttribute1");
      String name = (String)columnDescriptor.getFieldValue("name");
      // return AdiskID

      Descriptor descr = attrInfo[0].getDescriptor();
      int count=0;
      while(true) {

      if(descr.getFieldValue("columnAttribute"+ (++count)) == null) {
      count--;
      break;
      }
      }
      String type = null;
      for(int j=0; j<count; j++)
      {

      Descriptor columnDescr = (Descriptor)descr.getFieldValue("columnAttribute" + (j+1));
      if(columnDescr.getFieldValue("name").toString().equals("AdiskName")) {
      type = columnDescr.getFieldValue("type").toString();
      // This will give the type of AdiskName
      break;
      }
      }

       

Similarly, you can get the operations/notifications field information from its relevant XMLString. The descriptor.xml file defined by Agent Toolkit follows the schema defined in this DTD file.

 

Flat File Persistence Support

 

The Model MBean attribute information is saved into a flat file depending on the persistence policy specified for each attribute in the XML file/descriptor. 

 

This default name can be changed by calling its setter method. Thus, during the Multi-Protocol agent's next startup,  the Model MBean gets loaded with the stored attribute values in the constructor of RequiredModelMBean (Since, the RequiredModelMBean implements the PersistentMBean interface, which has load and store methods). The various Persist Policy supported are as follows :

Catched Values Support

 

What is Caching?

 

Caching mechanism is provided to store attribute values that are offered by the management resource, in the Model MBean. Maintaining the values of fairly static variables in the Model MBean itself, allows it to return that value without contacting the managed resource.

 

The resource may also set its Model MBean to disable caching, implying that the resource would be called whenever an attribute is accessed. In this case, the managed resource is invoked and it returns the attribute values to the Model MBean. In turn, the Model MBean returns these values to the MBean Server, which returns them to the request originator, usually a management application.

 

What benefit does Caching provide?

 

In general, the adaptors access the application's RequiredModelMBean as it is returned by the Multi-Protocol agent. If the data requested by the adaptor is current, then the managed resource is not interrupted with a data retrieval request. Therefore, direct interaction with the managed resource is not required for each interaction with the management system. This helps to minimize the impact of management activity on run-time application resources and performance.

 

The attribute descriptor contains and lastUpdatedTimeStamp fields. If the current time is past lastUpdatedTimeStamp + curencyTimeLimit, then the attribute value is stale (or no value). If a getAttribute is received for an attribute with a stale value (or no value), then the getMethod for the attribute will be invoked and the returned value will be recorded for the attribute, lastUpdatedTimeStamp will be reset, and the requester will be handed the new value.

 

If there is no getMethod defined, then the default value from MBeanInfo for the attribute will be returned.

 

When to use Model MBean

 

Model MBean usage is recommended over standard or dynamic MBeans on below scenario :

    1. When you wish to use any protocol adaptors that has model :

      If you wish to use SNMP adaptor, SOAP adaptor, CIM / WBEM adaptor (which has metadata model ), the flexibility of defining the protocol properties (like OID, CIM schema) for an MBean attribute can be achieved only by ModelMBeans.  On the other hand, if you wish to use protocol adaptors like RMI, HTTP (which doesn't have any meta model), then you can choose to use either standard or dynamic mbeans.

    2. Out of the box persistence support for MBean and its attributes

    3. Out of the box caching support for MBean and its attributes

Running the Model MBean Example

 

The Model MBean example is available in the <Agent Toolkit Home>/examples/jmx/modelMBean directory.   It illustrates  the usage of  the Model MBean registered with the Multi-Protocol agent. To run the example, please refer to the Readme.html file.

 

Agent Level (MBean Server)

 

The manager requests are received and processed at the agent level. This level handles the different  protocols and converts manager requests into the common protocol independent instrumentation provided by MBeans.  The task of converting from specific protocols is done by protocol-specific adaptors/connectors. These interface with a common MBean server, which controls and interacts with the MBeans.

 

The MBeanServer is the core component of the JMX infrastructure. It provides a protocol-independent and information model-independent framework with services for manipulating JMX manageable resources.

 

Registering a resources MBean makes it visible to management applications and exposes requests. The server no distinction between types of MBeans: standard, dynamic model MBeans are all managed in exactly same manner. <

 

You can register objects in the MBean server through:

The MBean server responds to the following management requests on registered MBeans:

Methods in MBean Server

 

The following are the methods for creating/registering/deleting MBeans

For accessing the attributes and operations on the MBean, the method names are same as specified in the DynamicMBean interface. The methods contain an extra parameter for passing the ObjectName information on the MBean, which you would like to access through the BeanServer.

For adding and removing NotificationListener for a NotificationBroadcaster MBean :

For querying the MBeans based on a Query constraint along with a filter mechanism :

All management requests are handled by the MBean server, which dispatches them to the appropriate MBean. An MBean is identified by a unique symbolic name, called object name. The object name can be assigned either by the entity registering the MBean, or by the MBean itself, if its implementation has been designed to provide one. Managers give this object name to designate the target of their management requests.

 

Generally, whatever the access the API user would like to have on the MBean, it is achieved via the MBean Server, with ObjectName of the MBean being passed as an extra parameter to all the methods.

 

Creating the MBean Server

 

The MBean Server object can be created using the createMBeanServer static method in the MBeanServer factory class. This method creates an instance of MBeanServer implementation class, which is exposed as MBeanServer interface. This implementation class is present in the Agent Toolkit as MBeanServerImpl class. Thus,; the following single line code will create an MBean Server instance :

      MBeanServer server = MBeanServerFactory.createMBeanServer();

Connector Level (Adaptors)

 

Adaptors and connectors are protocol handlers,  which expose MBeans information to their respective protocol  clients/managers. The MBean (instrumentation) is common and needs to be instrumented only once. This instrumentation is  made available through all the adaptors/connectors.

 

An agent may contain any number of connectors or protocol adaptors, enabling it to be managed simultaneously by several managers, through different protocols. It is up to the agent application to coordinate all the port numbers on which it intends to receive requests.

 

The AdventNet Multi-Protocol agent supports to provide management of the Multi-Protocol agent through the following adaptors. You can also create custom protocol adaptors and integrate them to the AdventNet adaptor framework. To do this, please refer to the topic "Writing custom protocol Adapters for the Multi-Protocol Agent".

SNMP Adaptor Architecture

 

SNMP Adaptor just acts as a wrapper class for AdventNet Standalone SNMP Agent, ensuring to provide the same SNMP agent stability that has come from the standalone SNMP agent.

 

Fig.2 SNMP Adaptor Architecture

 

CORBA Connector

 

The CORBA Connector enables CORBA clients to manage MBeans residing in AdventNet Multi-Protocol agent. The CORBA connector uses CORBA naming service provided by the ORB implementation for CORBA object lookup. The IDL implemented by this CORBA connector is published with the toolkit, thus exposing the MBean Server remotely accessed by a non-Java connector client.

 

 

Fig 3. CORBA Connector Architecture

 

 

 

Copyright © 1996-2004, AdventNet Inc. All Rights Reserved.