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
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.
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.
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 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
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.
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.
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> |
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
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:
The RMI connector enables Java managers to access a Java Dynamic Management agent using the Java remote operation invocation (RMI) system.
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.
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.
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.
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.
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.
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:
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: