Provides access to the components and profiles in an IOR without the overhead of CDR encoding.

The abstract model of IORs works as follows:

• An IOR has a type ID string, and contains TaggedProfile instances.
• An IIOPProfile isA TaggedProfile.
• An IIOPProfile is composed of an IIOPProfileTemplate and an object ID.
• An IIOPProfileTemplate has an ObjectKeyTemplate, and contains TaggedComponents.
• A TaggedComponent has an ID, and can be written to an OuputStream.
• A TaggedComponentFactory reads a TaggedComponent from an InputStream.

In all cases, containment is represented by having the appropriate interface (IOR and IIOPProfileTemplate above) extend java.util.List. This makes it easy to use all of the facilities in the Java collections framework with IORs. However, note that all objects available through these APIs are immutable. Thus all list update operations through UnsupportedOperationException, and list iterators cannot modify the underlying list.

Templates are used because the basic object adapter model for object creation is to establish all properties of an IOR (except for type and object ID) when the object adapter is created. This has been present for the POA essentially from the beginning, since policies can only be passed to create_POA, and cannot be changed on an existing POA. The Portable Interceptors work has also made this clear, since the IOR interceptor runs only when an object adapter is created, which is the only time that user code can add tagged components to an IOR.

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

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

1. Instrumenting Connection State

/**
  *  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