10 Base Services - Customizing the Framework

The base services are the services that the framework requires to be able to function. They are supplied as separate components to enable you to customize the framework by choosing the implementation you require. If you do not want to use the supplied implementation of a base service, you can further customize the framework by writing your own implementation and adding it to the framework.

Initializing the Framework

An agent developed with the Java Dynamic Management Kit must contain one instance of the framework, that is, one instance of the com.sun.jaw.reference.agent.cmf.Framework class. The constructors of this class provide the following options for initializing the framework:

Default initialization
Initialization with a specific domain
Initialization with a specific repository service and domain

Repository Service

The repository service stores m-beans as normal Java objects. For each m-bean, the repository service stores and retrieves:

The association between the m-bean and its object name
Its attribute values

M-beans can be managed only if they are registered with an object name (see page 41) in the repository. Each time an m-bean is registered with the framework, the framework calls the repository service to store the object name of the m-bean. When querying the repository, agents and managers identify an m-bean by its object name.

You have to add the repository service to an agent before the agent is operational. An agent can be associated with only one repository service at a time. It is not possible to change the repository service with which an agent is associated while the agent is running.

Supplied Repository Services

The Java Dynamic Management Kit provides the following types of repository:

Volatile repository - all m-beans are stored in memory
Persistent repository - contains a mixture of m-beans stored in memory and in persistent storage

All the information in memory is lost when the agent is stopped. When an agent is started, it has to reload the information into the repository. Information in persistent storage is not lost when the agent is stopped.

The Java Dynamic Management Kit provides implementations of persistent storage based on a flat-file database.

If you need to store large volumes of data or you require absolute data integrity, you should implement a persistent repository using a database. The Java Dynamic Management Kit provides an example repository based on a relational database using the JDBC driver.

Volatile Repository

To add a volatile repository to an agent, create an instance of the com.sun.jaw.impl.agent.services.light.RepositorySrv class.

Persistent Repository

The persistent repository stores all persistent m-beans in an agent in a flat-file database. Each m-bean is stored as a serialized Java object. For each m-bean, the repository stores:

The object name of the m-bean
The serialized m-bean
The object name of the class loader that loaded the m-bean when it was instantiated

The repository stores the object name of the class loader to enable it to locate the class loader when an agent deserializes the m-bean. The repository needs to locate this class loader to obtain the Java byte codes of the m-bean class, which are required for deserializing the m-bean. An agent deserializes an m-bean when it needs to load it from persistent storage into memory (for example, when an agent is restarted after it has been stopped).

Adding a Persistent Repository

To add a persistent repository to an agent, create an instance of the com.sun.jaw.impl.agent.services.persistent.PersistentRepSrv class:

Configuring a Persistent Repository

Before trying to register any m-beans with a persistent repository, use the setConfig method to configure the repository and start the database. The configuration parameters are as follows and must be specified in the order given:

The base directory of the database. By default it is the current working directory of the agent.
The name of the database. The repository creates a directory with this name in the base directory. The file that contains the database is written to the directory created. The default name of the database is default.db. The suffix .db is appended to the name if you do not specify it explicitly.

When you invoke the setConfig method, you have to specify each configuration parameter as an element in a vector. CODE EXAMPLE 10-1 shows code for configuring a flat-file repository. In this example, the base directory is the working directory of the agent. The name of the database is persist.db.

//Create vector that contains the configuration parameters

Vector params = new Vector();

params.addElement(null); // The same directory as agent

params.addElement("persist"); // Call the database "persist.db"

//Invoke setConfig with this vector to configure the repository

ffpersrep.setConfig (params);

Making M-beans Persistent

Any m-bean that you want to be persistent must be serializable. When you write an m-bean that you want to be serializable it can implement either the java.io.Serializable or java.io.Externalizable interface.

Making M-Beans Serializable

For classes that implement java.io.Serializable, you do not have to write any methods to ensure that the object is stored properly. Java provides a default mechanism to automatically write the contents of an object to a stream and to automatically read them back from a stream.

The class of a serializable object must:

Implement the java.io.Serializable interface
Use the transient keyword to denote non-serializable fields
Be able to access the no-argument constructor of its first nonserializable superclass

For each instance of a class that implements the java.io.Serializable interface, Java writes:

The class and superclass metadata, that is, the class name of the class and its superclasses
The serialVersionUID
Field metadata and contents, that is, the name and type of each field in the class and superclasses as well as the values of the fields

The classes of a serializable object can also implement the writeObject method or the readObject method for customization (overriding the default mechanism).

The writeObject method is used to control the information that is saved for the class (not the superclasses), or to append additional information.
The readObject method is used so that the class can read the information written by the writeObject method or to update the state of the object after it has been restored.

The default read and write of superclass metadata and their field metadata is still carried out automatically.

Making M-beans Externalizable

The java.io.Externalizable interface extends java.io.Serializable. Using the java.io.Externalizable interface requires more work to implement and all the benefits of the default mechanism are lost. Externalization allows a class to specify the methods to be used to write the object's contents to a stream and to read them back from a stream. The java.io.Externalizable interface's writeExternal and readExternal methods are implemented by a class to give complete control over the format and contents of the stream for an object and its superclasses. These methods must explicitly coordinate with the superclasses to save its state. When an externalizable object is reconstructed, an instance is created using the public no-argument constructor and the readExternal method is called. Serializable objects are restored by reading them from an ObjectInputStream.

The class of an externalizable object must:

Implement the java.io.Externalizable interface.
Implement the writeExternal method to save the state of the object to the stream. It must explicitly coordinate with its superclasses to save their states.
Implement the readExternal method to read the data written by the writeExternal method from the stream and restore the state of the object. It must explicitly coordinate with its superclasses to restore their states.
Have a no-argument constructor.

For each instance of a class that implements the java.io.Externalizable interface, Java writes:

The class metadata, that is, the class name of the class (the class name of the superclasses is not written)
The serialVersionUID
Data (whatever the writeExternal method writes)

Superclass metadata or their field metadata are not written automatically.

Marking Fields as Transient

When using java.io.Serializable, you can design your classes for more compact storage by storing only the fields needed to reconstruct a class.

Transient fields assume the default value for their specific type after deserialization. Transient variables are instantiated, but their static initializations are never applied during deserialization.

For example.


`transient int count = 10;`

After deserialization, count assumes the value zero, which is the default value for type int.


`transient String protocol = "http";`

After deserialization, protocol assumes the value null, which is the default value for type object.

Use the readObject method to restore the state of transient fields, to be initialized to a non-default value, after the object has been restored.

Note - Do not apply the transient modifier to fields that reference the framework. Although the framework is not serializable, the repository ensures that all m-beans that reference the framework will stay synchronized.

Retrieving the Class of an M-Bean for Deserialization

An agent deserializes an m-bean when it needs to load it from persistent storage into memory (for example, when an agent is restarted). When an m-bean is deserialized, the Java byte codes of its class are required. To enable an agent to obtain the Java byte codes of the class from the correct source, the repository service must be able to locate the class loader that loaded the m-bean when it was instantiated.

To enable the repository service to locate a class loader, ensure that the class loader provides the getter method getLoaderName to retrieve its object name. If you want the class loader to be persistent, ensure that it implements the java.io.Externalizable interface. If the class loader is not persistent, make sure it is present when the m-bean is deserialized.

If the repository service cannot locate the class loader that loaded the m-bean when it was instantiated, the agent uses the default class loader.

Specifying the Storage Medium in the Persistent Repository

You specify whether an m-bean in the persistent repository is stored in memory or in persistent storage by choosing the method of the framework invoked to register the m-bean:


To store an m-bean in:	Invoke:
Memory	`addObject` to register an existing m-bean instance `newObject` to instantiate and register an m-bean in a single operation
Persistent storage	`addDBObject` to register an existing m-bean instance `newDBObject` to instantiate and register an m-bean in a single operation

For more information on how to use these methods, refer to Chapter 4.

Implementing Your Own Repository Service

The repository service must implement the com.sun.jaw.reference.agent.services.MoRepSrvIf Java interface. When you implement a repository, you must specify whether it uses volatile or persistent storage.

Activation Interface

M-beans that require other services to be able to control their execution must implement the com.sun.jaw.reference.agent.services.ActivatableIf interface. Services that are able to control m-beans implementing the ActivatableIf interface are referred to as activation services. Activation services are able to perform two actions on an activatable m-bean:

Start the execution of an activatable m-bean using the performStart method
Stop the execution of an activatable m-bean using the performStop method

For example, the activation interface may be used by a persistent repository to restart m-beans after an agent has been stopped. The activation interface may be used in m-beans that are intended to be started or stopped as an element in a job scheduling service.

Metadata Service

An agent uses the metadata service to obtain the properties and actions supported by an m-bean. A metadata service is supplied with the Java Dynamic Management Kit as the com.sun.jaw.impl.agent.services.light.MetaDataSrv class. This implementation uses the design patterns for m-beans to obtain the properties and actions supported by an m-bean. It is based on the Reflection API provided by the Java Development Kit (JDK). The metadata service implements the com.sun.jaw.reference.agent.services.MetaDataSrvIf Java interface.

Changing the Metadata Service

When you initialize the framework, it is initialized with the default implementation of the metadata service, regardless of the constructor you invoke. If you want to change the metadata service that an agent uses, add a new metadata service to replace the existing one.

The Java Dynamic Management Kit enables you to add a new metadata service to an agent in either of the following ways:

Invoking a setter method for the service within the Framework class
Adding the service to the repository

Adding the metadata service by invoking a setter method gives faster performance than adding it to the repository. However, if the service has been added by invoking a setter method:

It is not visible to remote applications
It cannot be stored in persistent storage

Adding the Metadata Service by Invoking a Setter Method

CODE EXAMPLE 10-2 shows how to add the metadata service to an agent by invoking a setter method.

import com.sun.jaw.impl.agent.services.light.MetaDataSrv;

import com.sun.jaw.reference.agent.services.MetaDataSrvIf;

...

meta= new MetaDataSrv();

// Pass the metadata service to the core management framework

cmf.setMetaDataSrvIf(meta);

Adding the Metadata Service to the Repository

When you add the metadata service to the repository, the class part of the object name (see page 41) you specify must contain the class name defined in the com.sun.jaw.reference.common.ServiceName Java class. The class name is used by the framework to retrieve the service from the repository. Once registered, the service is accessible to management applications, after the agent contains an adaptor.

CODE EXAMPLE 10-3 shows how to add the metadata service to the repository.