Chapter 2 The Java Dynamic Management Kit Development Process

Developing an Application

Figure 2-1 MBean Development and Distribution Process

The main steps in developing an application with the Java Dynamic Management Kit are:

• Creating new MBeans/ adapting existing resources through instrumentation

• Registering MBeans

• Testing the MBeans with a web browser

• Optional: generating proxy MBeans

• Developing a manager

Creating New MBeans/Adapting Existing Resources

As discussed earlier in "Key Concepts", MBeans conform to the JMX specification, which formalizes the representation of the MBean's management interface. Management interfaces are represented as attributes and operations which you can invoke. You must create new MBeans which adhere to the design patterns for exposing these attributes, specified by JMX. The design patterns for developing MBeans are specific to the MBean model, and are defined to ease the interaction between objects and the MBean server. You may also select MBeans from those included in the toolkit and customize them, using a Java Development Environment in order to generate MBeans for the services you require.

Attributes define the appearance or behavior of an MBean or are attributes of the managed resource that the MBean represents. For example, an attribute named ipackets in an MBean representing an Ethernet driver could be defined to represent the number of incoming packets. Attributes can have arbitrary types, including built-in Java types, and class or interface types such as java.awt.Color.

Attributes are always accessed via operation calls on the object that owns them. For readable attributes, there is a getter operation to read the attribute value. For writable attributes, there is a setter operation to allow the attribute value to be updated.

By default, the following design pattern is used for identifying attributes:

public attributeType getattributeName();
public void setattributeName(attributeType value);

If a class definition contains a matching pair of getattributeName() and setattributeName() operations these operations define a read-write attribute. If a class definition contains only one of these operations the operation defines either a read-only or write-only attribute called attributeName.

Registering MBeans

To enable an MBean to be managed by a Java Dynamic Management agent, register it in the MBean server. Registering an MBean does not necessarily require any modification of code. You can write the MBean so that it can control its own registration, should you wish to do so.

An MBean is registered by code in the agent which is to manage the MBean's resources. The Java Dynamic Management Kit enables you to register an existing MBean instance or to instantiate and register an MBean in a single operation. When registered, an MBean is assigned an object name by the user. If the user does not give the object a name then the object can assign a name for itself.

An MBean can also be instantiated and registered remotely by code in a Java Dynamic Management client.

Regardless of the registration operation, the MBean server generates a notification whenever an MBean is registered. The information sent with the notification includes the object name of the new MBean.

Testing MBeans With A Web Browser

After you have compiled your MBean classes, you are able to use a web browser to test them. You do this by connecting a web browser to a running agent (for example, the base agent), instantiating MBeans, and performing other operations on the MBean instances. Before connecting a web browser to an agent, make sure that:

• The agent is running on a machine that you can access by using the HTTP protocol

• The agent contains an instance of HTML adaptor

• The compiled MBean classes are stored at a location specified in the CLASSPATH environment variable of the agent

To use a web browser to communicate with an agent, open the page given by the following URL in a web browser:

http://host:port

where:

• host is the host name of the machine on which the agent is running

• port is the port number used by the HTML adaptor in the agent; the default port number is 8082

The HTML page displayed is generated by the HTML adaptor and enables you to perform the following operations on MBeans in the agent:

• Reading or writing the attributes of an MBean instance

• Performing an operation on an MBean instance

• Instantiating an MBean

• Deleting an MBean instance

Optional: Generating Proxy MBeans

As discussed earlier in this guide, a proxy MBean is an object that represents a remote MBean to a Java Dynamic Management manager. The manager accesses an MBean by performing operations on the proxy MBean. The operations are then propagated to the MBean.

A proxy MBean is generated from its MBean by using the proxygen compiler supplied with the Java Dynamic Management Kit. A generic proxy MBean can be created by simply creating an instance and, hence, there it is not generated using the proxygen compiler. The MBean's input to proxygen must be in the form of compiled Java classes, not source files. The numerous options of this tool allow you to customize your MBeans depending on how you wish to use them in your management application.

A proxy MBean consists of two components:

• A Java interface that defines which of the operations of the MBean are accessible to a Java manager

• A Java class that implements the operations defined in the Java interface

For example, if you have an MBean MyClass, the proxygen compiler gives you a proxy MBean that consists of the following files:

• MyClassProxyMBean.java - the Java interface

• MyClassProxy.java - the Java class

The proxygen compiler generates Java source code, not compiled Java classes. For your proxy MBeans to be accessible to a Java manager, you have to compile the files that proxygen generates, and make sure that the compiled Java classes are stored at the location specified by the CLASSPATH environment variable of the manager, or are accessible by the class loader of the manager.

Proxy MBean Interface

A proxy MBean consists of:

• A Java interface that defines which of the operations of an MBean are accessible to a Java management application

• A Java class which implements the operations defined in the MBean's interface

The interface of a proxy MBean exposes the attributes and operations of the corresponding MBean. All operations have the same signature as in the original MBean, apart from the exceptions which are unique to the proxy MBean interface.

The generated class provides an implementation for the proxy MBean's interface. Therefore, the Java class contains the code to implement the getters, setters and operations of the proxy MBean. To do this, the Java class relies on the com.sun.jdmk.comm.RemoteMBeanServer interface. This interface specifies the API for the connector client object which the management application uses to communicate with its agents. For example, the Java class implementation of a getter operation calls the appropriate operations of the interface. Through this interface, the corresponding getter operation of the MBean is called remotely, and its result is sent back to the proxy MBean.

The generated class implements the com.sun.jdmk.Proxy interface in order to provide additional management capabilities.

As the interface is used by all connector client objects in the Java Dynamic Management Kit, all proxy MBeans can be connected to their corresponding MBean through any of the communication protocols. It also guarantees that the behavior of the proxies is not affected by how the connector client is implemented.

Using The proxygen Compiler

The proxygen compiler takes the compiled Java class of an MBean and generates the Java interface and Java proxies of a proxy MBean. The Java proxies consist of Java source code that implements the interface. To develop a Java manager with code generated by proxygen, you call the operations of the proxy MBean's interface. This allows you to remotely manipulate the corresponding MBean on an agent.

Options of the proxygen compiler enable you to modify the characteristics of the proxies you generate from an MBean. For example, options are available that enable you to generate read-only or read-write proxies. By generating a set of stubs with different characteristics from the same MBean, you can develop a Java manager whose behavior is modified at runtime, depending on which stubs are loaded. For example, when the read-only stubs are loaded, the Java manager will not be able to modify properties in the MBean.

To start proxygen, type the command for your operating environment:

• In a Solaris operating environment:

  prompt% installDir/SUNWjdmk/jdmk4.0/1.1 or 1.2/bin/proxygen <options> < classes>

• In a Windows NT operating environment:

  C:\> "installDir\SUNWjdmk\jdmk4.0\1.1 or 1.2\bin\proxygen" <options> < classes>

Developing A Manager

You can develop a manager in the Java language by using the connector client management interface. The main steps in developing a Java manager are:

• Initializing a connector client

• Adding and Implementing a Connector/Protocol Adaptor to an Agent

• Controlling access by a manager to an agent

• Adding the services that the connector client requires in order to operate (refer to "Agent Services")

• Instantiating MBeans in an agent

• Getting or setting attributes of MBeans

• Performing operations on MBeans

Initializing A Connector Client

A connector provides access to MBeans through a communication protocol. It enables management applications to perform management operations on a Java Dynamic Management agent. For a Java Dynamic Management agent to be manageable, it must contain at least one connector. However, a Java Dynamic Management agent can contain many protocol adaptors, allowing it to be managed remotely through different protocols.

The following connectors/protocol adaptors are supplied with the Java Dynamic Management Kit:

• RMI

• HTTP/TCP

• HTML

• SNMP

RMI Connector

The RMI connector enables Java managers to access a Java Dynamic Management agent using the Java remote operation invocation (RMI) system.

HTTP/TCP Connector

The HTTP/TCP connector enables Java managers to access a Java Dynamic Management agent using HTTP over a TCP/IP connection. It also allows these management applications to access an agent across proxy servers. By default, the HTTP/TCP adaptor listens for incoming requests on port 8081. The HTTP/TCP connector provides login/password authentication.

HTML Protocol Adaptor

The HTML protocol adaptor is an HTML server that enables web browsers to access a Java Dynamic Management agent through the HTTP communication protocol. When an HTML protocol adaptor is instantiated, it creates a TCP/IP socket and waits for incoming requests. By default, the HTML adaptor listens for incoming requests on port 8082. The HTML adaptor provides login/password authentication.

The HTML protocol adaptor is provided as a tool for debugging and speeding the development of agents. As such, it has certain limitations, for example it does not display complex types or multi-dimensional arrays.

SNMP Protocol Adaptor

The SNMP protocol adaptor enables an SNMP manager to perform management operations on a Java Dynamic Management Kit agent. Before using the SNMP protocol adaptor, you need to configure it for the MIB used by the SNMP manager application.

Adding And Implementing Connector/Protocol Adaptor To An Agent

To add a connector/protocol adaptor to an agent, create an instance of the Java class that implements the connector/protocol adaptor you want to use.

Adaptor	Java Class
RMI	com.sun.jdmk.comm.RmiConnectorServer
HTTP/TCP	com.sun.jdmk.comm.HttpConnectorServer
HTML	com.sun.jdmk.comm.HtmlAdaptorServer
SNMP	com.sun.jdmk.comm.SnmpAdaptorServer

The Java Dynamic Management Kit provides the following ways to add a connector/protocol adaptor to an agent:

A connector/protocol adaptor is an abstraction of a communications protocol. This means that the communication mechanism between agent and manager is hidden. The connectors/protocol adaptors provided by the Java Dynamic Management Kit are implemented as MBeans. This enables them to be managed. The Java Dynamic Management Kit does not require a connector/protocol adaptor to conform to a specific interface definition or implementation. However, a connector/protocol adaptor must be able to access the MBean server to retrieve and change information in MBeans in an agent.

Controlling Access By A Manager To An Agent

The Java Dynamic Management Kit provides mechanisms for controlling access by a manager to an agent. The access control operations available depend on the connector/protocol adaptor used.

• The HTTP connector and HTML protocol adaptor both provide login/password authentication.

• The SNMP protocol adaptor provides access control using information contained in an access control (ACL) file.

• The SNMP protocol adaptor can also provide access control using information contained in an access control object.

The Java Dynamic Management Kit does not provide access control for the RMI connector.

The HTTP/TCP connector and the HTML protocol adaptor provide login/password authentication. In this authentication scheme, the client object and the server object contain authentication information. The server side object contains an array of objects that contain authentication information for all known clients. When a client attempts to login, the login/password object that it sends is compared with the array to see if the client is on the list of permitted clients. If the list of permitted clients is null, no client authentication is performed by the adaptor and access is granted to all clients.

Access To A Connector

A connector client enables a Java manager to access MBeans in a remote agent through a particular communications protocol. The Java Dynamic Management Kit provides a connector client for each of the protocols supported . All connector clients have the same interface, meaning that the manager is protocol-independent.

Connector client objects are the objects that management applications use to communicate with the agents that they wish to manipulate. These objects establish a connection to a corresponding connector server in an agent, through the specific protocol they implement. There is thus one connector server and client pair for each protocol supported.

A connector client enables Java managers to perform management operations on a Java agent. Connector clients provide a level of abstraction by allowing a manager to manipulate local objects, the effects of which are remote. The manager does not need information on the protocol used to communicate with the agent; it needs either the class name or object name of the objects to be managed.

There are two ways for a manager to interact with its connector client:

• The management application can call the operations of the connector client to interact with remote MBeans directly

• The application can have the connector client instantiate local proxy MBean objects which represent each MBean in a remote agent; in this case, the manager calls the operations of the proxy MBean, derived from its corresponding MBean.

  The proxy MBeans themselves rely upon the remote MBean server interface; they provide simplified access to the remote objects. In both cases, a manager must have information on the semantics of the MBeans it manages. It is much easier to write a management application using proxy MBeans, rather than calling the remote MBean server interface. However, this requires that the appropriate proxy MBean objects be available to the management application. Manipulating proxy MBeans also uses more memory resources as they are instantiated objects.

Java managers access a connector through a connector client. The Java Dynamic Management Kit provides connector clients to enable a Java manager to access a connector using these protocols:

• RMI

• HTTP/TCP

Access To A Protocol Adaptor

The purpose of a protocol adaptor is to enable a manager to:

• Read and, if allowed, set attributes of MBeans

• Invoke operations on MBeans

• Receive notifications emitted by MBeans

• Request that MBeans are instantiated, registered and deregistered

  When a request from a manager to instantiate and register an MBean is carried out, the Java class of the MBean needs to be specified. The code of the class does not have to be present on the same machine as the agent in which the MBean is to be instantiated.

These types of management applications access adaptors directly:

• Web browsers accessing the HTML adaptor

• SNMP managers

Benefits Of The Java Dynamic Management Kit

Benefits of the Java Dynamic Management Kit include:

• Dynamic extensibility and scalability

• Easy management of Java applications

• Easy development of smart agents

• Protocol independence

Dynamic Extensibility And Scalability

The Java Dynamic Management Kit simplifies the development of extensible agents. An agent is able to instantiate Java classes loaded from an arbitrary location. Therefore, it is possible to extend the functionality of a running agent by making new classes available at an arbitrary location and requesting that the agent load and instantiate them.

Agents developed using the Java Dynamic Management Kit are also scalable. MBeans can be registered and unregistered with the MBean server in an agent while it is running. By registering and un-registering new MBeans, the agent can use only what it needs when it needs it. This feature enables the size and complexity of an agent to be modified while the agent is running, without having to stop the agent.

Easy Management Of Java Applications

The MBean server enables easy management of Java applications. For a Java application to be manageable, it only needs to be modified so that it:

• Instantiates the MBean server and a connector

• Registers the objects that, in conjunction with their states, accurately represent the application

The only restriction is that the registered objects have to be instances of an MBean. This is not a serious restriction, as it does not force the existing design to be changed, nor does it require a fixed class inheritance scheme. When you design an MBean, you do not need to explicitly take into account the interaction of the MBean with the MBean server or the adaptors. This is handled for you by the design patterns for MBeans. An application that includes the MBean server and a connector provides remote access for management operations without the need for any further development.

Easy Development Of Smart Agents

Agents developed using the Java Dynamic Management Kit are smart agents. A smart agent provides the services needed to process management requests. In a smart agent, much of the processing can be done locally in the agent itself, reducing the load on the network connection between the agent and the manager. This also enables an agent to continue to work if the connection between it and its manager is lost.

Protocol Independence

The design patterns for MBeans do not depend in any way on the protocol an agent uses for communicating with external applications. This is because the connectors interact with MBeans through the MBean server. New connectors (with new protocols) can be developed and used without rewriting existing MBeans or external applications. All that is required is that the new connector is able to interact with the MBean server.

Agent Services

To simplify the development of agents for network, system, application, and service management, the Java Dynamic Management Kit supplies a set of agent services, which includes base services. Agent services are simply manageable resources, implemented as MBeans, that can perform management operations on other MBeans, thus, enabling agents to manage resources.

Filtering Service (Base Service)

The filtering service selects MBeans to be the subjects of management operations. Selection is based on the presence and values of specific attributes in object names. For example, a filter could select all the MBeans for which the attribute color is red. The filtering service is not implemented as an MBean. It is part of the infrastructure of the MBean server.

Monitoring Service

The monitoring service observes numerical values and strings, enabling the variation over time of a attribute in an MBean to be monitored. The observed attribute is monitored at intervals specified by the granularity period. An event notification is sent when the value of the attribute satisfies one of a set of conditions, thus monitors can notify other objects of several types of changes in the target. You specify the conditions when you initialize a monitor.

Timer Service

The timer service enables you to create notifications for specific dates and times, providing a scheduling mechanism based either on a one-time notification or on a repeated, periodic notification. The notifications or notification events are sent to all objects registered to receive timer events.

This service performs a function similar to that of the cron daemon of the UNIX® operating system. There are two types of timer notifications:

• One-time notification

• Periodic notification: a set number of occurrences at equal intervals over a given time period

M-Let Service

The management applet or m-let service enables an agent to obtain MBeans from a remote Java Archive (JAR) file. The agent does this by loading an m-let text file, which specifies information on the MBeans to be obtained. The information on each MBean is specified in a single instance of a tag, called an MLET tag. The location of the m-let text file is specified by a URL. When an m-let text file is loaded, an instance of each MBean specified in the file is created.

The SNMP Toolkit

The Java Dynamic Management Kit provides a toolkit for developing SNMP agents and managers. This includes:

• an SNMP agent toolkit

• Developing An SNMP Agent

• SNMP MIB Compiler -- mibgen

• SNMP Protocol Adaptor

• SNMP Manager API

Developing An SNMP Agent

Developing an SMNP Agent using the Java Dynamic Management Kit involves three steps:

• Generating Java code by running mibgen on the target SNMP MIB

• Filling in the access operations in the generated Java code

• Configuring the SNMP adaptor with the target MIB

  mibgen parses an SNMP MIB and generates the following:

  • an MBean representing the whole MIB

  • a class representing the metadata definitions for the MIB variables

  • classes representing SNMP groups/entries as MBeans (and a metadata class for each instance generated)

  • classes representing SNMP tables

  • classes representing SNMP enumerated types

  MBeans generated by mibgen need to be updated to provide the definitive implementation.

  SNMP agents developed with the Java Dynamic Management Kit are extensible in that MIBs can be added or removed during an agent's lifetime. They are open as SNMP is not the only protocol available and HTTP, HTML and RMI protocol adaptors can also be used to access the agent. They can be SNMP-only because the SNMP adaptor can be used alone and the MBean server is not mandatory.

  For more information regarding this development process, please refer to the Java Dynamic Management Kit Tools Reference Guide.

SNMP MIB Compiler -- mibgen

The mibgen compiler takes as input a set of SNMP MIBs and generates standard MBeans that implement the MIBs. MIBs can be expressed using SNMP v1 or SNMP v2 syntax.

The mibgen compiler is able to process:

• Tables with cross references indexed across several MIBs

• MIBs that contain both v1 and v2 definitions

The mibgen compiler also generates the Java source code required for representing a whole MIB in an SNMP manager. Table objects provide methods for adding and removing entries from the table.

When the whole MIB file is registered in the MBean server, all the associated groups are automatically instantiated and added to the MBean server.

SNMP Protocol Adaptor

The SNMP adaptor implements the SNMP v1 and v2 protocol stack. The protocol adaptor is able to manage an unlimited number of different Management Information Bases, commonly referred to as MIBs. By providing a unified view of all the MIBs, the SNMP adaptor solves the subagent problem that commonly occurs with SNMP. The SNMP protocol adaptor allows MIBs to be loaded or unloaded dynamically. This enables a MIB to be loaded into, updated, and unloaded from an agent while it is running.

SNMP Manager API

The SNMP manager API is a set of Java classes that simplifies the development of applications for managing SNMP agents. The agents may be developed using the Java Dynamic Management Kit, or by other means.