Defining an Event Provider by Writing a Java Class

To define an event provider, write a Java language class that defines the types of events for the component. Your class is not required to extend any specific class or implement any interfaces.

To identify your class as an event provider, annotate the declaration of the class with the org.glassfish.external.probe.provider.annotations.ProbeProvider annotation.

To create a name space for event providers and to uniquely identify an event provider to the monitoring infrastructure of Enterprise Server, set the elements of the @ProbeProvider annotation as follows:

moduleProviderName

Your choice of text to identify the application to which the event provider belongs. The value of the moduleProviderName element is not required to be unique.

For example, for event providers from Sun GlassFish^TM Enterprise Server, moduleProviderName is glassfish.

moduleName

Your choice of name for the module for which the event provider is defined. A module provides significant functionality of an application. The value of the moduleName element is not required to be unique.

In Enterprise Server, examples of module names are web-container, ejb-container, transaction, and webservices.

probeProviderName

Your choice of name to identify the event provider. To uniquely identify the event provider, ensure that probeProviderName is unique for all event providers in the same module.

In Enterprise Server, examples of event—provider names are jsp, servlet, and web-module.

Defining Event Types in an Event Provider Class

To define event types in an event provider class, write one method for each type of event that is related to the component. The requirements for each method are as follows:

• The return value of the callback methods must be void.

• The method body must be empty. You instantiate the event provider class in the class that invokes the method to send the event. For more information, see Sending an Event.

• To enable the event to be used as a Solaris DTrace probe, each parameter in the method signature must be a Java language primitive, such as Integer, boolean, or String.

Annotate the declaration of each method with the org.glassfish.external.probe.provider.annotations.Probe annotation.

By default, the type of the event is the method name. If you overload a method in your class, you must uniquely identify the event type for each form of the method. To uniquely identify the event type, set the name element of the @Probe annotation to the name of the event type.

You are not required to uniquely identify the event type for methods that are not overloaded.

Specifying Event Parameters

To enable methods in an event listener to select a subset of values, annotate each parameter in the method signature with the org.glassfish.external.probe.provider.annotations.ProbeParam annotation. Set the value element of the @ProbeParam annotation to the name of the parameter.

Example of Defining an Event Provider by Writing a Java Class

Example 5–1 Defining an Event Provider by Writing a Java Class

This example shows the definition of the TxManager class. This class defines events for the start and end of transactions that are performed by a transaction manager.

The methods in this class are as follows:

onTxBegin

This method sends an event to indicate the start of a transaction. The name of the event type that is associated with this method is begin. A parameter that is named txId is passed to the method.

onCompletion

This method sends an event to indicate the end of a transaction. The name of the event type that is associated with this method is end. A parameter that is named outcome is passed to the method.

import org.glassfish.external.probe.provider.annotations.Probe;
import org.glassfish.external.probe.provider.annotations.ProbeParam;
import org.glassfish.external.probe.provider.annotations.ProbeProvider;
@ProbeProvider(moduleProviderName="examplecomponent", 
moduleName="transaction", probeProviderName="manager")
public class TxManager {
    
    @Probe("begin")
    public void onTxBegin(
        @ProbeParam("{txId}") String txId
    ){}

    @Probe ("end")
    public void onCompletion(
        @ProbeParam("{outcome}") boolean outcome
    ){}
 }