Java Dynamic Management Kit 5.1 Getting Started Guide

2.5 Agent Services

To simplify the development of agents for network, system, application, and service management, the Java DMK supplies a set of agent services. These services are implemented as MBeans that perform some operations on the other MBeans in an agent. All the provided agent services are briefly explained in this section.

2.5.1 Querying and Filtering

Querying and filtering are performed by the MBean server, not by a separate MBean. This ensures that such critical services are always available. Queries and filters are performed in a single operation, whose goal is to select the MBeans on which management operations are performed.

Usually, a management application performs a query to find the MBeans that are the target of its management requests. To select MBeans, applications can specify the following.

An object name filter, which is a possibly incomplete object name that the MBean server tries to match with the object names of all registered MBeans. All MBeans whose names match the filter pattern are selected. Filters can contain wildcards to select sets of MBeans, or a filter can be a complete object name that must be matched exactly. Filter rules are explained in detail in the JMX specification.
A query expression, which is an object that represents a set of constraints applied to the attribute of an MBean. For each MBean that passes the filter, the MBean server determines if the current state of the MBean satisfies the query expression. Queries usually test for attribute values or MBean class names.

For example, a filter could select all the MBeans whose object names contain MyMBeans and for which the attribute named color is currently equal to red.

The result of a query operation is a list of MBean object names, which can then be used in other management requests.

2.5.2 Dynamic Loading

Dynamic class loading is performed by loading management applets or m-lets containing MBeans. This service loads classes from an arbitrary network location and creates the MBeans that they represent. The m-let service is defined by the JMX specification. The m-let service makes it possible to create dynamically extensible agents.

A management applet is an HTML-like tag called <MLET> that specifies information about the MBeans to be loaded. It resembles the <APPLET> tag, except that it loads only MBean classes. The tag contains information for downloading the class, such as the classname and the location of its class file. You can also specify any arguments to the constructor that is used to instantiate the MBean.

The m-let service loads a URL that identifies the file containing <MLET> tags, one for each MBean to be instantiated. The service uses a class loader to load the class files into the application's Java virtual machine. It then instantiates these classes and registers them as MBeans in the MBean server.

The m-let service is implemented as an MBean and instantiated and registered in the MBean server. Thus, the m-let service can be used either by other MBeans or by management applications. For example, an application could make new MBean classes available at a location, generate the m-let file, and instruct the m-let service in an agent to load the new MBeans.

Dynamic loading effectively pushes new functionality into agents, allowing management applications to deploy upgrades and to implement new resources in their agents.

2.5.3 Monitoring

The monitoring service complies with the JMX specification and provides a polling mechanism based on the value of MBean attributes. The monitoring service contains three monitor MBeans, one MBean for counter attributes, another MBean for gauge-like attributes, and a third MBean for strings. These monitors send notifications when the observed attribute meets certain conditions, mainly equaling or exceeding a threshold.

Monitor MBeans observe the variation of an MBean attribute's value over time. All monitors have a configurable granularity period that determines how often the attribute is polled. Each monitor has specific settings for the type of the observed attribute, as follows.

Counter monitor, which observes an attribute of the integer type (byte, integer, short or long) that is monotonically increasing. The counter monitor has a threshold value and an offset value to detect counting intervals. The counter monitor resets the threshold if the counter rolls over.
Gauge monitor, which observes an attribute of integer (byte, integer, short, or long) or floating-point (float or double) types that fluctuates within a given range. The gauge monitor has both a high and low threshold, each of which can trigger a distinct notification. The two thresholds can also be used to avoid repeated triggering when an attribute oscillates around a threshold.
String monitor – Observes an attribute of type String. The string monitor performs a full string comparison between the observed attribute and its match string. A string monitor sends notifications both when the string matches and when it differs at the observation time. Repeated notifications are not sent, meaning that only one notification is sent the first time the string matches or differs.

Monitor notifications contain the name of the observed MBean, the name of the observed attribute, and the value that triggered the event, as well as the previous value for comparison. This information allows listeners to know which MBean triggered an event. The listeners do not need to access the MBean before taking the appropriate action.

Monitor MBeans can also send notifications when certain error cases are encountered during an observation.

2.5.4 Scheduling

The timer service is a notification broadcaster that sends notifications at specific dates and times. The timer service provides a scheduling mechanism that can be used to trigger actions in the listeners. Timer notifications can be single events, repeated events, or indefinitely repeating events. The timer notifications are sent to all of the service's listeners when a timer event occurs.

The timer service manages a list of dated notifications, each of which has its own schedule. Users can add or remove scheduled notifications from this list at any time. When adding a notification, users provide its schedule, defined by the trigger date and repetition policy, and information that identifies the notification to its listeners. The timer service uses a single Java thread to trigger all notifications at their designated time.

You can stop the timer service to prevent it from sending notifications. When you start it again, notifications that could not be sent while the timer was stopped are either sent immediately or discarded, as determined by the configuration of the service.

Like all other agent services, the timer is implemented as an MBean so that it can be registered in an agent and configured by remote applications. However, the timer MBean can also be used as a stand-alone object in any application that needs a simple scheduling service.

For more information about the timer service, see the JMX specification document.

2.5.5 Cascading

Cascading is the term used to describe a hierarchy of agents, where management requests are passed from a master agent to one of its subagents. A master agent connects to other agents, possibly remotely, through their connector server components, much like a manager connects to an agent. In a set of cascading agents, all MBeans in a subagent are visible as if they are registered in their master agent. The master agent hides the physical location of subagents and provides client applications with a centralized access point.

In Java DMK 5.1, the cascading service is implemented over JMX Remote API connectors. The CascadingServiceMBean makes it possible to mount source MBean servers, that are possibly located in subagents, into a target MBean server, that is located in the master agent, in a manner that is somewhat analogous to a File System mount operation.

2.5.5.1 Object Names and Domain Paths

The Java DMK cascading API introduces the notion of a domain path. An ObjectName is thus decomposed into three parts, as follows.

domain-path/domain-base-name:key-property-list

The domain path is a hierarchical name similar to a File System path name, using the character `/' as a separator.

2.5.5.2 File System Analogy

The CascadingServiceMBean provided in the Java DMK 5.1 makes it possible to mount MBeans from a source MBean server under a target domain path in a target MBean server, in a similar way to a File System mount operation.

Although our API also allows you to implement different cascading schemes, we recommend that applications only implement those schemes that can be compared to a regular File System mount, as follows.

When calling the CascadingServiceMBean.mount operation, always use a non null targetPath. The target path can be assimilated to a target mount point in the File System analogy.
Never use a targetPath under which MBeans are already registered in the target MBean server. Using such a target path could cause a naming conflict when mounting the source MBeans to the target MBean server.
Never give the same targetPath to two different mount operations. Like in the file system analogy, you should not attempt to mount two sources to the same target path.

Our implementation does not enforce those rules, but applications which are concerned with naming consistency and coherency should make sure to respect them. See the package description in the API documentation for the com.sun.jdmk.remote.cascading package for details.

2.5.5.3 `CascadingServiceMBean`

The cascading service proposed in the com.sun.jdmk.remote.cascading package is based on a simple MBean class, the CascadingServiceMBean.

The CascadingServiceMBean provides methods that make it possible to mount MBeans from a source MBean server in a target MBean server under a target domain path. Usually the target MBean server is the MBean server in which the CascadingService is registered.

There should be only one CascadingServiceMBean per target MBean server.
The CascadingServiceMBean.mount method mounts a partial view of a source MBean server known by its JMXServiceURL in the target MBean server of the CascadingServiceMBean.
The CascadingServiceMBean.unmount method cancels a previous mount operation. The unmount operation will close the connection that was opened by the mount operation.

The default CascadingService implementation provided in the Java DMK 5.1 relies on proxy-based cascading and implements the mount operation by instantiating a ProxyCascadingAgent behind the scenes. Although the ProxyCascadingAgent offers a public API, you should not use it directly. Applications should use the CascadingServiceMBean instead.

CascadingServiceMBeans are also notification emitters, which emit notifications when mountpoints are unmounted, as a result of a an unmount operation, or because the underlying connection with the source MBean server has been closed or failed.

2.5.5.4 Cascading over Java DMK legacy connectors

There are two possibilities to implement cascading over Java DMK legacy connectors.

Use the legacy cascading service that was provided in earlier versions of the Java DMK. This legacy cascading service is still provided for reasons of backwards compatibility, but it is now deprecated. This alternative is therefore not recommended.
Create a JMXServiceURL from which a JMXConnector wrapping a legacy Java DMK ConnectorClient can be obtained from the JMXConnectorFactory. You can then use this JMXServiceURL with the new CascadingServiceMBean API. See the Java Dynamic Management Kit 5.1 Tutorial for more information about wrapping legacy connectors.

2.5.6 Discovering Agents

You can use the discovery service to discover Java dynamic management agents in a network. Only agents that have a discovery responder registered in their MBean server can be discovered when you use this service.

The discovery service for legacy connectors can be functionally divided into two parts:

The discovery search service which actively finds other agents
The discovery support service which listens for other agents to be activated

2.5.7 Discovery Search Service

In a discovery search operation, the discovery client sends a discovery request to a multicast group and waits for responses. To be found by the discovery service, the agents must have a DiscoveryResponder registered in their MBean server. All discovery responders that receive the discovery request send a response that contains information about the connectors and the protocol adaptor that are available in their agent.

Figure 2–4 The Discovery Search Service

A manager application might use the discovery search service during its initialization phase, to determine all agents that are accessible in its network environment.

2.5.8 Discovery Support Service

The discovery support service passively monitors discovery responders in a multicast group. When discovery responders are activated or deactivated, indicating that their agent is starting or stopping, they send a multicast message about their new state. A discovery monitor object listens for discovery responder objects starting or stopping in the multicast group.

By registering listeners with the discovery monitor, a management application knows when agents become available or unavailable. The discovery support message for an agent that is being started also lists its connector and protocol adaptor.

A management application can use the discovery monitor to maintain a list of active agents and the protocols they support.

2.5.9 Defining Relations

The Relation Service is used to record relationships between MBeans in an MBean server. The Relation Service is itself an MBean. More than one instance of a Relation Service MBean can be registered in an MBean server.

A relation type defines a relationship between MBeans. A relation type contains roles that the MBeans play in the relationship. Usually, there are at least two roles in a relation type.

A relation is a named instance of a relation type, where specific MBeans appear in the roles, represented by their object names.

For example, suppose Module MBeans represent the modules within an application. A DependsOn relation type could express the relationship that some modules depend on others, which could be used to determine the order in which the modules are started or stopped. The DependsOn relation type would have two roles, dependent and dependedOn.

Every role is typed, meaning that an MBean that appears in that role must be an instance of the role's type. In the DependsOn example, both roles would be of type Module.

Every role has a cardinality, which provides lower and upper bounds on the number of MBeans that can appear in that role in a given relation instance. Usually, the lower and upper bounds are both 1, with exactly one MBean appearing in the role. The cardinality only limits the number of MBeans in the role per relation instance. The same MBean can appear in the same role in any number of instances of a relation type. In the DependsOn example, a given module can depend on many other modules, and be depended on by many others, but any given relation instance links exactly one dependent module with exactly one dependedOn module.

A relation type can be created explicitly, as an object implementing the RelationType interface, typically a RelationTypeSupport. Alternatively, a relation type can be created implicitly using the Relation Service's createRelationType method. A relation instance can be created explicitly, as an object implementing the Relation interface, typically a RelationSupport. A RelationSupport is itself a valid MBean, so it can be registered in the MBean server, though this is not required. Alternatively, a relation instance can be created implicitly using the Relation Service's createRelation method.

Through the relation service, users can create relation types and then create, access, and delete instances of a relation. All MBeans are referenced by their object name, so that a relation can be accessed from a remote application. An MBean does not need to know what relations it participates in. New kinds of relations can be added to an agent without having to modify the code of the MBeans that they link.

The relation service provides query mechanisms to retrieve MBeans that are related to each other. The relation service is notified when MBeans in a relation are unregistered, and it verifies that any relation involving that MBean still has the required cardinality.

The relation service can represent a relation instance either internally or externally. If the user defines a relation instance through the API of the relation service, the relation is represented by internal structures that are not accessible to the user. This is the simplest way to define relations, because the relation service handles all coherence issues through its internal structures.

A relation instance can also be a separate MBean object that fulfills certain requirements. The user instantiates and registers these MBeans, ensures that they represent a coherent relationship, and places these MBeans under the control of the relation service. This process places the responsibility of maintaining coherency on the user, but external relations have certain advantages. They can implement operations on a relation instance. Because external relations are MBeans, these extended operations are available to remote management applications.