4 Operations on M-Beans

Any object in a Java Dynamic Management agent can perform operations on m-beans. An m-bean on which an operation is to be performed is identified by its object name.

Object Name

An object name uniquely identifies an m-bean within a framework. Management applications use object names to identify the m-beans on which to perform management operations. An object name is represented by the class com.sun.jaw.reference.common.ObjectName.

An object name consists of the following parts:

Domain
Class
Search key

Syntax of an Object Name

`domainPart:classPart[.attribute=value[,attribute=value]*]`

`domainPart:classPart[.attribute=value[,attribute=value]*]`

The variable parts of this syntax are:

domainPart

The domain part of the object name. It must be followed by a colon (:).

classPart

The class part of the object name.

attribute

An attribute in the search key.

value

The value assigned to attribute.

The first attribute-value pair in a search key must be preceded by a period (.). You can specify any number of attribute-value pairs in a search key, each separated by a comma (,). Each attribute must be separated from its corresponding value by an equals sign (=).

Note - If the object name does not contain at least one equals sign (=), the entire string after the colon is considered the class part of the object name. In this case, the class is a singleton.

For example, an object representing a specific bank account could be named:


`TheBank:account.id=123456,owner=smith`

Registering an M-Bean

To enable an m-bean to be managed by a Java Dynamic Management agent, register it in the repository. Registering an m-bean does not require modification of code within the m-bean itself. All that is required is to add to the agent or its manager new code for registering the m-bean. The Java Dynamic Management Kit enables you to register an existing m-bean instance and to instantiate and register an m-bean in a single operation. Registering an m-bean causes an object name to be assigned to it.

For information on the repositories supplied with the Java Dynamic Management Kit, refer to "Repository Service" on page 128.

Registering an Existing M-Bean

To register an m-bean, invoke one of the following methods of the Framework class:

addObject to use the default storage mechanism for storing the m-bean and its object name
addDBObject to specify that the m-bean and its object name are persistent

When you invoke either of these methods, you have to provide:

An existing m-bean
The object name (see page 41) to be used for registering the m-bean

CODE EXAMPLE 4-1 shows how to add an m-bean to the repository by invoking the addObject method of the Framework class.

// Instantiate the text m-bean

text= new TextSimple();

// Create the object name

String domain= cmf.getDomain();

name = new ObjectName(domain + ":" + "TextSimple.SerialNo=1");

// Register the text m-bean

cmf.addObject(text, name);

CODE EXAMPLE 4-2 shows how to add persistent information to the repository.

// Instantiate the text m-bean

text= new TextSimple();

// Create the object name

String domain= cmf.getDomain();

name = new ObjectName(domain + ":" + "TextSimple.SerialNo = 1");

// Register the text m-bean in persistent storage

try {

cmf.addDBObject(text, name);

} catch(ServiceNotFoundException e) {

e.printStackTrace();

}

Instantiating and Registering an M-Bean in a Single Operation

To instantiate and register an m-bean in a single operation, invoke one of the following methods of the Framework class:

newObject to use the default storage mechanism for storing the m-bean
newDBObject to specify that the m-bean is persistent

When you invoke either of these methods, you have to provide:

The Java class of the m-bean to be instantiated
The object name (see page 41) to be used for registering the m-bean

Note - The Java class of the m-bean to be instantiated must contain a public constructor that does not take any arguments. If it does not, an exception is thrown when the newObject or newDBObject is invoked.

The framework uses a class loader (see Chapter 12) to locate the Java class of the m-bean to be instantiated. It then creates an instance of the class. Once the m-bean has been instantiated, it must be registered with the framework. It is possible to register an m-bean by using:

The initCmf method of the m-bean, or
The framework

Using the `initCmf` Method of the M-Bean

To register an m-bean by using the initCmf method, all you need to do is make sure that the Java class definition of the m-bean contains this method. The initCmf method must be implemented as described in "Initializing an M-Bean - initCmf Method" on page 37.

After the m-bean has been instantiated, the framework uses the metadata service to find a method called initCmf in the newly created m-bean. Provided such a method is present in the m-bean, the framework invokes it, giving:

A reference to itself as first parameter
The object name to use for registering the m-bean as second parameter

The m-bean then registers itself with the repository if the initCmf method is implemented correctly. The initCmf method can also take two additional parameters, see "Initializing an M-Bean - initCmf Method" on page 37.

The services provided under com.sun.jaw.impl.agent.services contain an implementation of the initCmf method.

Using the Framework

If you do not define an initCmf method in an m-bean, the framework registers the m-bean by invoking one of these methods:

addObject if the m-bean was instantiated by invoking newObject
addDBObject if the m-bean was instantiated by invoking newDBObject

Refer to "Registering an Existing M-Bean" on page 43 for more information.

Example

CODE EXAMPLE 4-3 shows how to add an m-bean, in this example the metadata service, to the framework.

String domain=cmf.getDomain();

cmf.newObject(metImplName, domain + ":" + ServiceName.META, null);

Assignment of Object Names

Registering an m-bean causes an object name to be assigned to it. To specify the object name explicitly, use the format defined in "Object Name" on page 41. If you do not specify the object name explicitly, the framework assigns a default object name to the m-bean. The format of a default object name is:


`frameworkDomain:Class`

The variable parts of this format are:

frameworkDomain

The domain associated with the instance of the Framework class in the Java Dynamic Management agent.

m-beanClass

The full Java class name, including the package name, of the m-bean. This is the class part of the object name of the m-bean. Only one instance of this class is permitted within the domain.

Note - A default object name does not contain a search key. Therefore, any m-bean assigned a default name by the framework, will be a singleton m-bean.

Registration of M-Beans in Persistent Storage

When the addDBObject method is invoked, the framework invokes the isPersistent method to check if the repository provides persistent storage. If the repository does not provide persistent storage, invoking addDBObject throws a ServiceNotFoundException exception. The isPersistent method is defined in the MoRepSrvIf interface.

The repository that provides persistent storage is represented by the com.sun.jaw.impl.agent.services.persistent.PersistentRepSrv Java class.

The com.sun.jaw.impl.agent.services.light.RepositorySrv repository provides both volatile and persistent storage.

Retrieving M-Beans

The framework provides services for retrieving registered m-beans from the repository. These services enable you to retrieve m-beans by using:

Pattern matching on their object names
Filters applied to the Java properties they contain

Retrieving M-Beans Using Object Names

By using pattern matching on the object names of m-beans, it is possible to retrieve:

A specific m-bean using its full object name and search key
A set of m-beans sharing the same logical class as expressed in the object name
A set of m-beans sharing the same domain name
All the m-beans contained in a Java Dynamic Management agent

CODE EXAMPLE 4-4 shows how to retrieve a specific m-bean using its full object name and the search key ident = 2288.

Vector MyMO = cmf.getObject(new ObjectName

("sky:examples.mo.Simple.SimpleMO.ident = 2288"), null);

CODE EXAMPLE 4-5 shows how to retrieve all the m-beans in a given domain with the same class part in their object names.

Vector listOfAccounts= cmf.getObject(new ObjectName

("sky:account"), null);

CODE EXAMPLE 4-6 shows how to retrieve all the m-beans in a given domain.

Vector listOfMOs = cmf.getObject("sky:"), null);

CODE EXAMPLE 4-7 shows how to retrieve all the m-beans in all domains.

Vector listOfMOs = cmf.getObject(null, null)

// or

Vector listOfMOs = cmf.getObject(new Objectname(":"), null);

Retrieving M-Beans Using Filters

Using filters enables you to retrieve m-beans according to Java properties and their values within m-beans. The repository evaluates filters if it is able to do so. Otherwise, the framework evaluates filters itself. The supplied repository service is able to evaluate filters. To determine whether a repository is able to evaluate filters, the framework invokes the isQuerySrv method defined by the MoRepSrvIf interface.

The filter expressed in CODE EXAMPLE 4-8 retrieves all the m-beans for which the property age is greater than 5 and the property name starts with G and ends with ling.

QueryExp exp = Query.and(

Query.gt(Query.attr("age"),

Query.value(5)),

Query.match(Query.attr("name"),

Query.value("G*ling")))

After a filter is built, it can be used for retrieving objects in conjunction with retrieval based on object names.

Getting and Setting Properties

The Java Dynamic Management Kit provides services for getting or setting properties of m-beans. The prerequisites for using these services are:

The Java Dynamic Management agent must provide a metadata service.
The m-bean must provide getter and setter methods for properties. They must be implemented as described in "Properties" on page 34.

To use these services, invoke the getter or setter method of the m-bean specifying:

The name of the property to be retrieved or set
The object name of the m-bean that contains the property

Getting a Property

CODE EXAMPLE 4-9 shows how to get the value of a specific property for an m-bean identified by its object name. In this example, the object name is sky:account.name=smith and the property to be obtained is bank.

Object val= cmf.getValue("sky:account.name=smith", "bank");

Setting a Property

When setting a property, the value can be set directly by the caller, as illustrated by CODE EXAMPLE 4-10. In this example, the object name is sky:account.name=smith, and the property bank is to be set to the value Acme.

cmf.setValue("sky:account.name=smith", "bank", "Acme");

Using an Operator to Set a Property

You can also use an operator to set a property. An operator implements the com.sun.jaw.reference.agent.services.OperatorSrvIf Java interface. The operator is responsible for setting the value using a default value provided by the caller and any algorithm the operator implements.

In CODE EXAMPLE 4-11, the object name is sky:account.name=smith, and the property bank is to be set to the value toUpperCase.perform(Acme).

cmf.setValue("sky:account.name=smith", "bank", "Acme",

"Acme", "toUpperCase");

4

Operations on M-Beans