Java Dynamic Management Kit 3.2 Programming Guide
[ Previous ][ Fast Back ]Chapter 7. Adaptor Clients [ Next ]

Operations on an Agent

After an adaptor client has been initialized, the manager is ready to perform the following operations on a remote agent:

The AdaptorMO interface lets you retrieve handles on existing m-beans, or instantiate new ones in the remote agent. When retrieving handles on existing m-beans, you can choose to retrieve object names, or to instantiate their corresponding c-bean. When instantiating new m-beans in a remote agent, you give an object name and choose whether or not to instantiate their corresponding c-bean.

Once you have a handle on an m-bean, you can perform the other management operations on it. All of the other operations can be performed either through a c-bean or through the AdaptorMO interface.

Retrieving Handles on M-Beans

The AdaptorMO interface defines methods for retrieving handles on objects in remote agents. When retrieving m-bean handles, you give an object name, and you can specify filters to limit the m-beans selected. You may choose to retrieve:

Retrieving Object Names

Use the getOnlyNames() method of the AdaptorMO interface to retrieve a vector of object names. Example 7-4 shows how to retrieve the object names of all the objects managed by an agent.

Example 7-4. Retrieving the Names of all M-Beans
ObjectName allNames = new ObjectName( ":" );
Vector result = AdaptorClient.getOnlyNames( allNames, null );

// print out each of the object names found
//
for(Enumeration e = result.elements(); e.hasMoreElements(); ) {
    ObjectName name = (ObjectName) e.nextElement();
    System.out.println( name.toString() );

To filter the list object names retrieved, you can specify more complete object names and/or query expressions, as shown in Example 7-5.

Example 7-5. Retrieving the Names of Selected M-Beans
import com.sun.jaw.reference.query.*

ObjectName mySimpleBeans = new ObjectName( "myDomain:Simple" );
QueryExp OKfilter = Query.match( Query.attr( "State" ),
                               Query.value( "OK" ) ); 

Vector myOKBeans = AdaptorClient.getOnlyNames( mySimpleBeans, OKfilter );

Retrieving C-Beans

Use the getObject() method of the AdaptorMO interface to retrieve a vector of c-beans. Example 7-6 shows how to retrieve c-beans for all the objects managed by an agent. In the example, the getObjectName() method of the ManagedObject interface is used to retrieve the name of the associated m-bean.

Example 7-6. Retrieving C-Beans for all M-Beans
ObjectName allNames = new ObjectName( ":" );
Vector result = AdaptorClient.getObject( allNames, null );
if ( result.isEmpty() ) {
    // no c-beans to retrieve
    return;
}
for(Enumeration e = result.elements(); e.hasMoreElements(); ) {
    ManagedObject cbean = (ManagedObject) e.nextElement();
    ObjectName name = cbean.getObjectName();
    System.out.println( name.toString() );
}

The getObject() method also allows you to specify more precise object names and query expressions. Example 7-7 shows how to retrieve a specific c-bean by giving its full object name.

Example 7-7. Retrieving a Specific C-Bean
ObjectName name = new ObjectName( "myHost:SimpleMO.id=123" );
Vector result = AdaptorClient.getObject( name, null );
if ( result.isEmpty() ) {
    System.out.println( name.toString() + "not found" );
    return;
}
SimpleMO cbean = (SimpleMO) result.firstElement();

Another way to get specific c-beans is to combine calls to both getOnlyNames() and getObject() methods. First invoke getOnlyNames() with null arguments for the object name and query. This will give you a list of all object names on the remote agent. Step through this list and match string patterns in the object names to find the specific objects you want. For example, you can search for the class names of the base services or the port attributes of the adaptor servers. Finally, invoke the getObject() method with the full object names which match your search criteria.

Instantiating New M-Beans

Management applications can instantiate new m-beans in remote agents by calling methods of the AdaptorMO interface. Managers can also choose to instantiate the corresponding c-beans locally at the same time. Invoke these methods of an adaptor client:

The new m-beans will be registered in the agent's repository, either by the object's initCmf method, if defined, or else by the agent's framework. You may also instantiate persistent m-beans if the remote agent's repository service offers persistency. Invoke these methods of an adaptor client:


Note - There is no inherent notion of persistency for manager-side objects such as c-beans, this is beyond the scope of the AdaptorMO interface and the adaptor client. Should you wish to do so, you must implement persistency within a manager by some other means.


Regardless of the repository used, a new m-bean will be instatiated and registered. As described in Framework Events in Chapter 4, the framework will generate an event to signal that a new object has been registered.

When instantiating remote m-beans, you may specify all or some of the following arguments:

You must specify either the Java class name or an object name with a class part so that the remote agent knows which Java class to instantiate. If you specify both, you must insure that the class part of the object name is coherent with the Java class name. If you don't specify an object name, the m-bean will be created in the agent's default domain (see Assigning Object Names in Chapter 4) and will necessarily be a singleton. You must use object names with unique search keys to instantiate more than one remote m-bean of the same class.

When specifying only an object name, you must give both the domain and class part, as well as a unique search key for m-beans that shouldn't be singletons. The adaptor client will apply its mapping rules (see Mapping Rules for Class Names) to the class part in order to obtain the name of the Java class to be instantiated in the agent.

Example 7-8 shows various ways of instantiating m-beans, using the different arguments. In this example, the invoked methods do not include a class loader object name in their signature; this functionality is not covered here.

Example 7-8. Instantiating Remote M-Beans
import com.sun.jaw.reference.common.*;

// just instantiate the m-bean by class name
AdaptorClient.newMO( "MyBean", null, null );
//
// you'll then have to get it's object name explicitly
ObjectName name = new ObjectName( ":MyBean" );
Vector myList = AdaptorClient.getOnlyNames( myName, null );
ObjectName myBeanName = (ObjectName) myList.firstElement();

// now use object names and keys to instantiate
// several m-beans of the same class
String domain = AdaptorClient.getDomain();
String aClass = "SimpleMO";
ObjectName name1 = new ObjectName( domain + ":" + aClass + "id=1" );
ObjectName name2 = new ObjectName( domain + ":" + aClass + "id=2" );

// get an uninitialized c-bean for the first
SimpleMO cbean1 = (SimpleMO)
    AdaptorClient.cb_newMO( null, name1, null );

// build a modifications list for initializing
ModificationList initList = new ModificationList();
initList.addElement( new Modification( "State", "OK" ));

// get an initialized c-bean for the second
SimpleMO cbean2 = (SimpleMO)
    AdaptorClient.cb_newMO( null, name2, initList );

Getting Properties of M-Beans

Once you have a handle on a remote m-bean, you may get the value of its properties either directly through the AdaptorMO interface or by calling the getter methods of a c-bean.

Getting Properties through the AdaptorMO Interface

To get the value of a property through the AdaptorMO interface, you need to know:

Example 7-9 shows how to retrieve a property called State of type String.

Example 7-9. Using the AdaptorMO Interface to Get a Property Value
// usually the object name will be found by calling getOnlyNames
// to be sure the object exists on the agent beforehand
//
ObjectName name = new ObjectName( "myHost:SimpleMO.id=123" );

String state = (String) AdaptorClient.getValue( name, "State" );

The AdaptorMO interface also provides a method for getting several properties of the same m-bean in a single call. Example 7-10 shows how to retrieve several properties at once.

Example 7-10. Using the AdaptorMO Interface to Get Several Properties
// usually the object name will be found by calling getOnlyNames
// to be sure the object exists on the agent beforehand
//
ObjectName name = new ObjectName( "myHost:SimpleMO.id=123" );
Vector propList = new Vector();
propList.addElement( "State" );
propList.addElement( "NbChanges" );
PropertyList propValues = AdaptorClient.getValues( name, propList );

String state = (String) propValues.elementAt( 1 );
Integer counter = (Integer) propValues.elementAt( 2 );

Getting Properties through a C-Bean

Getting the value of a property from a c-bean is straightforward: invoke the getter associated with the property you want. Example 7-11 shows how to retrieve a specific c-bean and get the value for each of its properties.

Example 7-11. Using the C-Bean to Get Property Values
ObjectName name = new ObjectName( "myHost:SimpleMO.id=123" );
Vector result= AdaptorClient.getObject( name, null );
if ( result.isEmpty() ) {
    // object not found on the agent
    return;
}

SimpleMO cbean = (SimpleMO) result.firstElement();
String state = cbean.getState();
Integer counter = cbean.getNbChanges();

Optimizing Getter Operations on C-Beans

Since every call to a c-bean getter method involves some communication with the agent, calling individual getters can lead to inefficient network traffic. For this reason, the ManagedObject interface implemented by all c-beans includes a caching mechanism. This allows you to read all desired property values into the local cache at one time and then get cached values individually with the c-bean getters.

Caching in a c-bean improves the performance of applications by limiting the network traffic between a local c-bean and its remote m-bean. Caching behavior is controlled by the GroupOper flag of a c-bean. By default, this flag is set to false : the c-bean will communicate with its remote m-bean to get a property's value every time its getter is called.

The simplest way to optimize getter operations is to read all of the properties of a c-bean in a single operation. Assuming you have already instantiated the target c-bean, this involves:

Example 7-12 shows how to retrieve the properties of the SimpleMO c-bean from its cache.

Example 7-12. Optimized Property Retrieval
// Read all properties and put their values in the cache
cbean.readAll();

// Notify the c-bean that values in cache should be
// returned. Therefore, the calls below will not
// generate network requests for the remote agent.
//
cbean.setGroupOper( true );
String state = cbean.getState();
Integer counter = cbean.getNbChanges();

// Tell the c-bean not to use the cached values.
// Now, getters will read the value in the remote
// agent over then network
//
cbean.setGroupOper( false );
String newState = cbean.getState();

If your m-beans have many properties, reading them all at once over the network can also be inefficient if you only need a few values. The readObject() method in c-beans also retrieves several values in one operation, but only for a subset of all properties. This allows you to efficiently update the cache for only those property values you require. Assuming you have already instantiated the target c-bean, this operation involves:

The marked properties are unmarked after the call to readObject(). This insures that only properties marked since the previous update will be retrieved. Example 7-13 shows how to use the marking and retrieving in a loop to poll property values.

Example 7-13. Further Optimized Property Retrieval
// Indicate that get operations should use the cache
cbean.setGroupOper( true );

// Load all properties in the cache for initialization
cbean.readAll();

boolean everythingOK;
while ( everythingOK ) {

    // Getting properties while GroupOper is true
    // will mark them for selective update
    // The values returned are cached values
    //
    String state = cbean.getState();
    Integer counter = cbean.getNbChanges();
    
    everythingOK = processValues( state, counter );

    // Update marked properties in the cache for
    // next loop iteration
    //
    cbean.readObject();
}


TIP: When the GroupOper flag is set to false, calls to getter methods retrieve a value from the remote m-bean through the network, not from the cache. As a side-effect, the cache is updated with the newly retrieved value. However, the property is not marked for updating by the readObject() method.

For clarity, it is best not to mix getters for cached and non-cached properties. You should either work with the cache and update its values when needed (GroupOper always true), or get values from the m-bean every time a getter is called (GroupOper always false).


Setting Properties of M-Beans

All getter operations on remote m-bean properties have an equivalent setting operation. You may set a property's value either directly through the AdaptorMO interface or by calling the setter methods of a c-bean.

Setting Properties Through the AdaptorMO Interface

To set the value of a property through the AdaptorMO interface, you need to know:

Example 7-14 shows how to set the property called State of type String.

Example 7-14. Using the AdaptorMO Interface to Set a Property
// usually the object name will be found by calling getOnlyNames
// to be sure the object exists on the agent beforehand
//
ObjectName name = new ObjectName( "myHost:SimpleMO.id=123" );

AdaptorClient.setValue( name, "State", "OK", null );

The last argument of the setValue method enables you to specify the name of an operator class when setting a property. The framework of the remote agent will instantiate the specified operator and invoke it to set the property value. See Using an Operator to Set a Property in Chapter 4 for more information about operators. The setValue method returns the value used to set the property, which is useful when this value was computed by an operator.

The AdaptorMO interface also provides a method for setting several properties of the same m-bean in a single call. Before invoking this method, you have to build a list of modifications using the ModificationList and Modification classes of the com.sun.jaw.reference.common package. As in setValue method, you can specify an operator when constructing a Modification object. Example 7-15 shows how to build a modification list and set several properties at once.

Example 7-15. Using the AdaptorMO Interface to Set Several Properties
import com.sun.jaw.reference.common.*;

ObjectName name = new ObjectName( "myHost:SimpleMO.id=123" );

ModificationList modifList = new ModificationList();
modifList.addElement( new Modification( "State", "OK" ));
modifList.addElement( new Modification( "Color", "green" ));

AdaptorClient.setValues( name, modifList );

Setting Properties Through a C-Bean

Setting the value of a property from a c-bean is again straightforward: invoke the setter associated with the property you want to modify. For each property, a c-bean also contains a setter method that allows you to specify an operator; this method is automatically generated by the mogen compiler. The framework of the remote agent will instantiate the specified operator and invoke it to set the property value. See Using an Operator to Set a Property in Chapter 4 for more information about operators.

Example 7-16 shows how to retrieve a specific c-bean and set the value of its properties, with and without using an operator.

Example 7-16. Using the C-Bean to Set Property Values
ObjectName name = new ObjectName( "myHost:SimpleMO.id=123" );
Vector result = AdaptorClient.getObject( name, null );
if ( result.isEmpty() ) {
    // object not found on the agent
    return;
}

SimpleMO cbean = (SimpleMO) result.firstElement();

cbean.setState( "OK" );

// assuming the RandomShadeOf is a valid operator
// class available to the remote agent
cbean.SetColor( "RandomShadeOf", "green" );

Optimizing Setter Operations on C-Beans

Setting individual properties on remote m-beans can also lead to inefficient network usage, since each operation is sent as a separate communication. Therefore, setter operations on c-beans can also be optimized by a caching mechanism and group operations defined in the ManagedObject interface.

There is no method for setting all cached values in a c-bean at once, since this is not a very useful operation. Rather, setting a cached property gives it a new cache value and marks it for a group set operation. In that way, only those properties which need to be set take part in the group operation.

Caching behavior is still controlled by the GroupOper flag of a c-bean. When this flag is true, the effect of a setter method is to update the c-bean's setter cache and mark the property for group setting. By default, this flag is set to false : the c-bean will communicate with its remote m-bean to set a property's value every time its setter is called.

To avoid caching conflicts between values written by setters and read by getters, c-beans contain two separate caches for each property. Each cache has its own marking mechanism for controlling group operations. Values written to the set cache are never reflected in the get cache. The consequence of this is that you must call the readAll() method after a group set operation or after an uncached set operation for the get cache to contain valid data. You only need to take this into consideration if you get and set the same properties of a remote m-bean.

Assuming you have already instantiated the target c-bean, optimizing the set operation involves:

Example 7-17 shows how to set the properties of the SimpleMO c-bean using the cache.

Example 7-17. Optimize Property Setting
// Indicate that set operations should use the cache
cbean.setGroupOper( true );

// Set values in the c-bean setter cache and
// mark these properties for group setting
cbean.setState( "OK" );
cbean.setColor( "green" );

// Group operation to set all marked properties
// at once in the remote m-bean
cbean.modifyObject();

// NOTE: getter cache is no longer up to date
// if you wish to keep it current you must do
// so explicitly. For example, an uncached get
// of the property will update the cache
cbean.setGroupOper( false );
String state = cbean.getState();

Invoking Actions of M-Beans

You may invoke a remote m-bean's actions either through the AdaptorMO interface or by calling the performAction methods of its c-bean.

Invoking Actions through the AdaptorMO Interface

To invoke the action of a remote m-bean through the AdaptorMO interface, you need to know:

Use the invokePerform method to call a remote action and get its return value. Example 7-18 shows how to invoke a fictional performMyAction action of a remote m-bean.

Example 7-18. Using the AdaptorMO Interface to Invoke an Action
// usually the object name will be found by calling getOnlyNames
// to be sure the object exists on the agent beforehand
//
ObjectName name = new ObjectName( "myHost:SimpleMO.id=123" );

// construct the array of parameter types
String[] paramTypes = { "java.lang.String", "java.lang.Integer" };

// construct the array of parameter values
Object[] paramVals = { "aValue", new Integer( 101 ) };

Float result = (Float)
    AdaptorClient.invokePerform(
        name, "MyAction", paramVals, paramTypes );

Invoking Actions of a C-Bean

The simplest way to invoke a remote action is to call the corresponding performAction method of a local c-bean.

Example 7-19 shows how to retrieve a specific c-bean and invoke its performMyAction method.

Example 7-19. Using the C-Bean to Invoke an Action
ObjectName name = new ObjectName( "myHost:SimpleMO.id=123" );
Vector result = AdaptorClient.getObject( name, null );
if ( result.isEmpty() ) {
    // object not found on the agent
    return;
}

SimpleMO cbean = (SimpleMO) result.firstElement();

Float result = cbean.performMyAction( "aValue", new Integer( 101 ) );

Deleting M-Bean Instances

You can delete a remote m-bean using either the AdaptorMO interface or the object's corresponding c-bean. The m-bean will be removed from the repository of the remote agent's framework. As described in Framework Events in Chapter 4, the framework will also generate an event to signal that an object has been deleted.

When calling the deleteMO method of the AdaptorMO interface, you must provide the full (and therefore unique) object name of the target m-bean. Example 7-20 shows how to delete an m-bean through the adaptor client.

Example 7-20. Using the AdaptorMO Interface to Delete an M-Bean
// usually the object name will be found by calling getOnlyNames
// to be sure the object exists on the agent beforehand
//
ObjectName name = new ObjectName( "myHost:SimpleMO.id=123" );

AdaptorClient.deleteMO( name );

The ManagedObject interface implemented by all c-beans defines the deleteObject() method for deleting its corresponding m-bean. Example 7-21 shows how to retrieve a specific c-bean and call this method.

Example 7-21. Using a C-Bean to Delete its M-Bean
ObjectName name = new ObjectName( "myHost:SimpleMO.id=123" );
Vector result = AdaptorClient.getObject( name, null );
if ( result.isEmpty() ) {
    // object not found on the agent
    return;
}

SimpleMO cbean = (SimpleMO) result.firstElement();
cbean.deleteObject();


[ Previous ][ Home ][ Next ]
Initializing an Adaptor Client[ Up ]Advanced Configuration