Sun GlassFish Enterprise Server v3 Add-On Component Development Guide

Updating the Monitorable Object Tree

A monitorable object is a component, subcomponent, or service that can be monitored. Enterprise Server uses a tree structure to track monitorable objects.

Because the tree is dynamic, the tree changes as components of the Enterprise Server instance are added, modified, or removed. Objects are also added to or removed from the tree in response to configuration changes. For example, if monitoring for a component is turned off, the component's monitorable object is removed from the tree.

To enable system administrators to access statistics for all components in the same way, you must provide statistics for an add-on component by updating the monitorable object tree. Statistics for the add-on component are then available through the Enterprise Server administrative commands get(1), list(1), and set(1). These commands locate an object in the tree through the object's dotted name.

For more information about the tree structure of monitorable objects, see How the Monitoring Tree Structure Works in Sun GlassFish Enterprise Server v3 Administration Guide.

To make an add-on component a monitorable object, you must add the add-on component to the monitorable object tree.

To update the statistics for an add-on component, you must add the statistics to the monitorable object tree, and create event listeners to gather statistics from events that represent these statistics. At runtime, these listeners must update monitorable objects with statistics that these events contain. The events are sent by event provider classes. For information about how to create event provider classes and send events, see Defining Statistics That Are to Be Monitored.

Updating the monitorable object tree involves the following tasks:

Creating Event Listeners

An event listener gathers statistics from events that an event provider sends. To enable an add-on component to gather statistics from events, create listeners to receive events from the event provider. The listener can receive events from the add-on component in which the listener is created and from other components.

To create an event listener, write a Java class to represent the listener. The listener can be any Java object.

An event listener also represents a component's statistics. To enable the Application Server Management Extensions (AMX) to expose the statistics to client applications, annotate the declaration of the class with the org.glassfish.gmbal.ManagedObject annotation.

Ensure that the class that you write meets these requirements:

The return value of all callback methods in the listener must be void.
Because the methods of your event provider class may be entered by multiple threads, the listener must be thread safe.
The listener must have the same restrictions as a Java Platform, Enterprise Edition (Java EE) application. For example, the listener cannot open server sockets, or create threads.

A listener is called in the same thread as the event method. As a result, the listener can use thread locals. If the monitored system allows access to thread locals, the listener can access thread locals of the monitored system.

Note –

A listener that is not registered to listen for events is never called by the framework. Therefore, unregistered listeners do not consume any computing resources, such as memory or processor cycles.

Representing a Component's Statistics in an Event Listener Class

Represent each statistic as the property of a JavaBeans^TM specification getter method of your listener class. Methods in the listener class for processing events can then access the property through the getter method. For more information, see Subscribing to Events From Event Provider Classes.

To enable AMX to expose the statistic to client applications, annotate the declaration of the getter method with the org.glassfish.gmbal.ManagedAttribute annotation. Set the id element of the @ManagedAttribute annotation to the property name all in lowercase.

The data type of the property that represents a statistic must be a class that provides methods for computing the statistic from event data.

The org.glassfish.external.statistics.impl package provides the following classes to gather and compute statistics data:

AverageRangeStatisticImpl: Provides standard measurements of the lowest and highest values that an attribute has held and the current value of the attribute.
BoundaryStatisticImpl: Provides standard measurements of the upper and lower limits of the value of an attribute.
BoundedRangeStatisticImpl: Aggregates the attributes of RangeStatisticImpl and BoundaryStatisticImpl and provides standard measurements of a range that has fixed limits.
CountStatisticImpl: Provides standard count measurements.
RangeStatisticImpl: Provides standard measurements of the lowest and highest values that an attribute has held and the current value of the attribute.
StatisticImpl: Provides performance data.
StringStatisticImpl: Provides a string equivalent of a counter statistic.
TimeStatisticImpl: Provides standard timing measurements.

Example 5–5 Representing a Component's Statistics in an Event Listener Class

This example shows the code for representing the txcount statistic in the TxListener class.

...
import org.glassfish.external.statistics.CountStatistic;
import org.glassfish.external.statistics.impl.CountStatisticImpl;
...
import org.glassfish.gmbal.ManagedAttribute;
import org.glassfish.gmbal.ManagedObject;

...
@ManagedObject
public class TxListener {

    private CountStatisticImpl txCount = new CountStatisticImpl("TxCount", 
        "count", "Number of completed transactions");
...
    @ManagedAttribute(id="txcount")
    public CountStatistic  getTxCount(){
         return txCount;
    }
}

Subscribing to Events From Event Provider Classes

To receive events from event provider classes, a listener must subscribe to the events. Subscribing to events also specifies the provider and the type of events that the listener will receive.

To subscribe to events from event provider classes, write one method in your listener class to process each type of event. To specify the provider and the type of event, annotate the method with the org.glassfish.external.probe.provider.annotations.ProbeListener annotation. In the @ProbeListener annotation, specify the provider and the type as follows:

"module-providername:module-name:probe-provider-name:event-type"

module-providername: The application to which the event provider belongs. This parameter must be the value of the moduleProviderName element or attribute in the definition of the event provider. See Defining an Event Provider by Writing a Java Class and Defining an Event Provider by Writing an XML Fragment.
module-name: The module for which the event provider is defined. This parameter must match be the value of the moduleName element or attribute in the definition of the event provider . See Defining an Event Provider by Writing a Java Class and Defining an Event Provider by Writing an XML Fragment.
probe-provider-name: The name of the event provider. This parameter must match be the value of the probeProviderName element or attribute in the definition of the event provider. See Defining an Event Provider by Writing a Java Class and Defining an Event Provider by Writing an XML Fragment.
event-type: The type of the event. This type is defined in the event provider class. For more information, see Defining Event Types in an Event Provider Class.

Annotate each parameter in the method signature with the @ProbeParam annotation. Set the value element of the @ProbeParam annotation to the name of the parameter.

In the method body, provide the code to update monitoring statistics in response to the event.

Example 5–6 Subscribing to Events From Event Provider Classes

This example shows the code for subscribing to events of type begin from the tx component. The provider of the component is TxManager. The body of the begin method contains code to increase the transaction count txcount by 1 each time that an event is received.

The definition of the begin event type is shown in Example 5–1.

The code for sending begin events is shown in Example 5–4.

The instantiation of the txCount object is shown in Example 5–5.

...
import org.glassfish.external.probe.provider.annotations.ProbeListener;
import org.glassfish.external.probe.provider.annotations.ProbeParam;
import org.glassfish.gmbal.ManagedObject;
...
@ManagedObject
public class TxListener {
    ...;    @ProbeListner("examplecomponent:transaction:manager:begin")
    public void begin(
    @ProbeParam("{txId}")
    String txId) {
      txCount.increment();
    }
  }

Registering an Event Listener

Registering an event listener enables the listener to receive callbacks from the Enterprise Server event infrastructure. The listener can then collect data from events and update monitorable objects in the object tree. These monitorable objects form the basis for monitoring statistics.

Registering an event listener also makes a component and its statistics monitorable objects by adding statistics for the component to the monitorable object tree.

At runtime, the Enterprise Server event infrastructure registers listeners for an event provider when the event provider is started and unregisters them when the event provider is shut down. As a result, listeners have no dependencies on other components.

To register a listener, invoke the static org.glassfish.external.probe.provider.StatsProviderManager.register method in the class that represents your add-on component. In the method invocation, pass the following information as parameters:

The name of the configuration element with which all statistics in the event listener are to be associated. System administrators use this element for enabling or disabling monitoring for the event listener.
The node in the monitorable object tree under which the event listener is to be registered. To specify the node, pass one of the following constants of the org.glassfish.external.probe.provider.PluginPointPluginPoint enumeration:
- To register the listener under the server/applications node, pass the APPLICATIONS constant.
- To register the listener under the server node, pass the SERVER constant.
The path through the monitorable object tree from the node under which the event listener is registered down to the statistics in the event listener. The nodes in this path are separated by the slash (/) character.
The listener object that you are registering.

Example 5–7 Registering an Event Listener

This example shows the code for registering the event listener TxListener for the add-on component that is represented by the class TransactionManagerImpl. The statistics that are defined in this listener are associated with the web-container configuration element. The listener is registered under the server/applications node. The path from this node to the statistics in the event listener is tx/txapp.

Code for the constructor of the TxListener class is beyond the scope of this example.

...
import org.glassfish.external.probe.provider.StatsProviderManager;
import org.glassfish.external.probe.provider.PluginPoint
...
public class TransactionManagerImpl {
...
    StatsProviderManager.register("web-container", PluginPoint.APPLICATIONS, 
        "tx/txapp", new TxListener());
...
}