com.sun.corba.se.spi.monitoring

General Information Monitoring Framework SPI's is used internally by the ORB to instrument for JMX based Management and Monitoring.  more ...

Interfaces:

Abstract Classes:

Classes:

General Information

Monitoring Framework SPI's is used internally by the ORB to instrument for JMX based Management and Monitoring. The
framework is very generic and easy to use and acts as facade to retrieve the information from the running CORBA system.

This framework helps in building a nice Hierarchical Structure of Monitored Objects that contains Monitored Attributes.
com.sun.corba.se.spi.orb.ORB has an API to get the RootMonitoredObject and then User can traverse through the tree to
either instrument or retrieve the information for Monitoring.

Code Snippet to Instrument Connection Monitored Object

This example shows on how to instrument CorbaConnectionImpl 's attributes. It exposes two
attributes, namely

1. Connection State
2. Response time statistics to Appeserver Admin Console or CLI
 

1. Instrumenting Connection State

/**
 *  Code Snippet to Instrument Connection Monitored Object with
 *  ConnectionState Monitored Attribute. Steps to follow
 *
 *  Step 1: Define a Monitored Attribute (ConnectionStateMonitoredAttribute) Class by extending
 *               StringMonitoredAttributeBase
 *
 *  Step 2: Create Connection Manager Monitored Object and add that to
 *                Root Monitored Object.
 *
 *  Step 3: Create Connection Monitored Object  and add it to Connection Manager Monitored Object
 *
 *  Step 4: Instantiate Concrete Attribute (ConnectionStateMonitoredAttribute) Class and add that to
 *                the Connection MonitoredObject
 *
 *  Step 5: Adds ConnectionMonitoredObject to ConnectionManagerMonitoredObject
 *
 */

/**
  *  Step 1: Define a Monitored Attribute Class by extending
  *                StringMonitoredAttributeBase
  */

/**
  *  ConnectionState gets the value on demand.
  */
#import com.sun.corba.se.spi.monitoring.LongMonitoredAttributeBase
#import com.sun.corba.se.spi.transport.CorbaConnection;

public class ConnectionStateMonitoredAttribute extends StringMonitoredAttributeBase
{
    CorbaConnection connection;
    public ConnectionInUseMonitoredAttribute( String name, String desc,
        CorbaConnection con )
    {
        super( name, desc );
        connection = con;
    }

    public Object getValue( ) {
        // Delegate the getValue call to connection
        // so, there is no state maintained in this attribute object itself
        // and also the locking will be the responsibility of Connection
        // Object. By doing this we will avoid global locking and possibly
        // avoiding the bottleneck
        return connection.getState( );
    }

    // IMPORTANT: In this case we don't have to implement clearState() method
    // If there is a need to implement this method like for POACounter, the
    // call again can be delegated to the Object which maintains the real
    // state. clearState() is invoked whenever there is a call to CORBAMBean.startMonitoring()
}
 

/**
 *  Step 2: Create Connection Manager Monitored Object and add that to
 *          Root Monitored Object.
 */
import com.sun.corba.se.spi.monitoring.MonitoringFactories;
import com.sun.corba.se.spi.monitoring.MonitoredObject;

private static MonitoredObject connectionManagerMonitoredObject;
private static MonitoredObject connectionMonitoredObject;
 

    private void instrumentConnectionManager( ) {
        connectionManagerMonitoredObject =
            MonitoringFactories.getMonitoredObjectFactory().createMonitoredObject(
                "ConnectionManagerMonitoredObject",
                "Used to Monitor the stats on All IIOP Connections " );
        orb.getRootMonitoredObject().addChild(connectionManagerMonitoredObject );
    }
 

/**
  *  Step 3: Create Connection Monitored Object  and add it to Connection Manager Monitored Object
  *
  *  Step 4: Instantiate Concrete Attribute (ConnectionStateMonitoredAttribute) Class and add that to
  *                the Connection MonitoredObject
  *
  *  Step 5: Add ConnectionMonitoredObject to ConnectionManagerMonitoredObject
  */
private void instrumentConnectionObject( CorbConnection connection ) {
    // Step 3
    MonitoredObject connectionMonitoredObject =
        MonitoringFactories.getMonitoredObjectFactory().createMonitoredObject(
            connection.getName(),
            "Used to Monitor the stats on one connection" );
    // Step 4
    ConnectionStateMonitoredAttribute connectionState =
        new ConnectionStateMonitoredAttribute( "Connection_State",
            "Provides the state of the IIOP Connection ...",  connection );
    connectionMonitoredObject.addAttribute( connectionState );
    // Step 5
    connectionManagerMonitoredObject.addChild( connectionMonitoredObject );
}
 
 

Code Snippet to Instrument A Statistic Type Monitored Attribute

/**
  *  Assuming ConnectionMonitoredObject is already added to the MonitoredObject Hierarchy.
  *  This example code shows how to instrument ConnectionMonitoredObject with a new
  *   StatisticMonitoredAttribute.
  *
  *    IMPORTANT: StatisticsMonitoredAttribute is mostly write mostly and read sparingly, i.e.,
  *    the frequency of writes(Collecting samples) is high.  It is the responsibility of user to synchronize
  *    the sample() method and the StatisticMonitoredAttribute will synchronize clearState() and
  *    getValue() using the mutex object sent.
  */
private void instrumentStatsToConnectionObject( MonitoredObject connectionMonitoredObject  ) {
     // Step 4
    StatisticsAccumulator connectRequestStatsAccumulator =
        // Microseconds is the unit used for statistics measure
        new StatisticsAccumulator( "Micro Seconds" );

    // Pass Name, Description, Statistic Accumulator Instance, Mutex (The
    // Object on which we need to synchronize for stats sample collection)
    StatisticMonitoredAttribute sm = new StatisticMonitoredAttribute(
        connection.getName() + "Stats",
        "Connection Request Stats", connectRequestStatsAccumulator, this );

    connectionMonitoredObject.addAttribute( sm );
 

    // Now, The user can accumulate the samples by calling into
    // connectRequestStatsAccumulator.sample( <value> );
    // Finally When ASAdmin request for the value of this Stats Monitored Attribute
    // by using standard getValue() call. It will return a formatted Stats Value like
    //  For Example
    //
    //  Minimum Value = 200 Microseconds
    //  Maximum Value = 928 Microseconds
    //  Average Value = 523 Microseconds
    //  Standard Deviation = 53.72 Microseconds
    //  Sample Collected = 435

}

Caution On Global Locking (Synchronization):

It's important to make sure that collecting Stats and other state information for monitoring doesn't impact performance. Please look at the following don'ts
to understand better.

Do not add a special mutex for synchronizing MonitoredObject:
Let's take an example of exposing a counter that counts Requests on this connection and 2 possible ways of doing this
1. Define Counter by extending LongMonitoredAttributeBase
     public class Counter extends LongMonitoredAttributeBase {
        private long counter;
 
        Counter( String name, String desc ) {
            super( name, desc );
        }
 
         public synchronized void increment( ) {
              counter++;
         }

          public synchronized Object getValue( ) {
              return new Long( counter );
          }
    }
 

2. Or Define a RequestCounter by extending LongMonitoredAttributeBase again, but no special
    synchronization is done

    public class RequestCounter extends LongMonitoredAttributeBase {
        private CorbaConnection connection;
        RequestCounter( String name, String desc, CorbaConnection con ) {
            super( name, desc );
            connection = con;
        }

        public Object getValue( ) {
            return connection.getRequestCount( );
       }
    }

    The problem with Alternative (1) is that there may be unneccesary extra synchronization happening for every method and it may become a bottle neck
     particularly if this object is accessed quite often. In Alternative (2), the synchronization happens only in the Connection object and no special sync
     is required in the RequestCounter object.
 

Important Thing To Know On StatisticMonitoredAttribute type:
The clearState() and getValue() call will be synchronized using the mutex passed by the external object, but sample() method in StatisticsAccumulator
is not synchronized. It is the responsibility of user to synchronize to make sure that the samples collected (The mutex passed into the StatisticsAccumulator must be the one used to synchronize calls to sample() ).
 

@since JDK1.5 @serial exclude