2 Tutorial Example

This chapter is a tutorial based on the Simple example provided with the Java Dynamic Management Kit. The directory containing the source files for the Simple example depends on the operating environment:


Operating Environment	Directory
Solaris	installDir`/SUNWconn/jaw/examples/src/tutorial`
Windows NT	installDir`\SUNWconn\jaw\examples\src\tutorial`

Before compiling any of the examples, copy the contents of the directory containing the example to another location. The file access permissions of the directories under the installation directory do not allow ordinary users write access.

Note - For standard JDK commands, only the command name and any required arguments are given. It is assumed that the path to the command is defined either in the command you type or in your PATH variable.

Developing an M-Bean

The simple m-bean provided in SimpleBean.java implements the following design guidelines:

Methods for reading and writing m-bean properties (getters and setters)
Public methods that are called remotely (actions)

CODE EXAMPLE 2-1 shows the Java class definition of a simple m-bean.

package examples.tutorial;

// Copyright (c) 07/22/98, by Sun Microsystems, Inc.

// "@(#)SimpleBean.java 1.2 98/07/22 SMI"

public class SimpleBean {

// Getter for the "State" property.

public String getState() {

return state ;

}

// Setter for the "State" property.

public void setState(String s) {

state = s ;

nbChanges++ ;

}

// Getter for the "NbChanges" property.

public Integer getNbChanges() {

return new Integer(nbChanges) ;

}

// Action on the "NbChanges" property.

public void performReset() {

nbChanges = 0 ;

}

// M-bean properties.

protected String state = "initial state" ;

protected int nbChanges = 0 ;

}

To compile the m-bean, type this command:


`prompt% javac SimpleBean.java`

Developing an Agent

The SimpleAgent example shows the code required in an agent for:

Initializing the framework
Adding the metadata service
Adding adaptors for two protocols

The Java source code of this example is shown in CODE EXAMPLE 2-2.

package examples.tutorial;

// Copyright (c) 07/22/98, by Sun Microsystems, Inc.

// "@(#)SimpleAgent.java 1.5 98/07/22 SMI"

import com.sun.jaw.reference.common.* ;

import com.sun.jaw.reference.agent.cmf.* ;

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

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

public class SimpleAgent {

public static void main(String argv[]) {

try {

String domain = "defaultDomain" ;

// Set up the Framework.

Framework cmf = new Framework() ;

// Set up the Metadata service.

String mtdSrvClass = "com.sun.jaw.impl.agent.services.light.MetaDataSrv" ;

String mtdSrvName = domain + ":" + ServiceName.META ;

cmf.newObject(mtdSrvClass, mtdSrvName, null) ;

// Set up the RMI Adaptor.

String rmiSrvClass = "com.sun.jaw.impl.adaptor.rmi.AdaptorServerImpl" ;

String rmiSrvName = domain + ":" + ServiceName.ADAPTOR + ".protocol=rmi" ;

cmf.newObject(rmiSrvClass, rmiSrvName, null) ;

// Set up the HTTP Adaptor.

String httpSrvClass = "com.sun.jaw.impl.adaptor.http.AdaptorServerImpl" ;

String httpSrvName = domain + ":" + ServiceName.ADAPTOR + ".protocol=http" ;

cmf.newObject(httpSrvClass, httpSrvName, null) ;

}

catch(Exception e) {

System.out.println("Got an exception !") ;

e.printStackTrace() ;

System.exit(1) ;

}

Initializing the Framework

To initialize the framework, create an instance of the Java class com.sun.jaw.reference.agent.cmf.Framework. CODE EXAMPLE 2-3 shows code for initializing the framework. In this example, the default constructor of the com.sun.jaw.reference.agent.cmf.Framework is used.

import com.sun.jaw.reference.common.* ;

import com.sun.jaw.reference.agent.cmf.* ;

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

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

...

// Set up the Framework.

Framework cmf = new Framework() ;

Adding the Metadata Service

To add an instance of the metadata service supplied with the Java Dynamic Management Kit, create an instance of the Java class com.sun.jaw.impl.agent.services.light.MetaDataSrv and pass this instance to the framework. CODE EXAMPLE 2-4 shows code for adding the metadata service to a Java Dynamic Management agent.

// Set up the Metadata service.

String mtdSrvClass = "com.sun.jaw.impl.agent.services.light.MetaDataSrv" ;

String mtdSrvName = domain + ":" + ServiceName.META ;

cmf.newObject(mtdSrvClass, mtdSrvName, null) ;

Adding Adaptors

For a Java Dynamic Management agent to be manageable, it must contain at least one adaptor. CODE EXAMPLE 2-5 shows code for adding the HTTP/TCP adaptor to a Java Dynamic Management agent. In this example, the newObject method of the Framework class is called to create an instance of the adaptor.

// Set up the HTTP Adaptor.

String httpSrvClass = "com.sun.jaw.impl.adaptor.http.AdaptorServerImpl" ;

String httpSrvName = domain + ":" + ServiceName.ADAPTOR + ".protocol=http" ;

cmf.newObject(httpSrvClass, httpSrvName, null) ;

}

Compiling and Running the Agent

Before running the example agent, make sure that the Java Dynamic Management base agent is not running on the same machine. You must also make sure that the CLASSPATH environment variable is set correctly, see Appendix B "Environment Variables" for further details.

To Compile the Agent

: 1. Go to the directory that contains the source files of the example agent.

2. Type this command:


`prompt% javac SimpleAgent.java`

To Run the Agent

: 1. If necessary, stop the Java Dynamic Management base agent.

In the Solaris operating environment, type

prompt% /opt/SUNWconn/jaw/bin/jaw stop
In the Windows NT operating environment, use the Task Manager, or in the window where you started the base agent, type Control+C.

`prompt% /opt/SUNWconn/jaw/bin/jaw stop`

2. Type this command:


`prompt% java examples.tutorial.SimpleAgent`

Generating a C-Bean

A c-bean is a representation of an m-bean to a Java manager. The mogen tool provided with the Java Dynamic Management Kit enables a c-bean to be generated automatically from an m-bean.

The Java class definition of a simple m-bean is shown in CODE EXAMPLE 2-1. Use mogen to generate a c-bean from the SimpleBean.class m-bean. The m-bean class input to mogen must be in the form of a compiled Java class, not a source file. The c-bean that mogen generates is in the form of Java source code, which you have to compile.

To Generate the Example C-Bean

Type the appropriate command for your operating environment:

In a Solaris operating environment:

prompt% /opt/SUNWconn/jaw/bin/mogen examples.tutorial.SimpleBean
In a Windows NT operating environment:

C:\> "C:\Program Files\SUNWconn\jaw\bin\mogen"
examples.tutorial.SimpleBean

`prompt% /opt/SUNWconn/jaw/bin/mogen examples.tutorial.SimpleBean`

`C:\> "C:\Program Files\SUNWconn\jaw\bin\mogen"` `examples.tutorial.SimpleBean`

The SimpleBeanMO interface that mogen generates when compiling this simple m-bean is shown in CODE EXAMPLE 2-6. In addition, mogen generates the file SimpleBeanMOStub.java containing an implementation of the SimpleBeanMO interface.

package examples.tutorial;

import java.lang.*;

import java.lang.reflect.*;

import com.sun.jaw.reference.common.*;

import com.sun.jaw.reference.client.mo.*;

/**

* Generated by the mogen compiler version:

* Generator.java 1.6 06/04/98 SMI

*

* @see com.sun.jaw.tools.MoGen

*/

public interface SimpleBeanMO extends ManagedObject {

public Integer getNbChanges()

throws InstanceNotFoundException, PropertyNotFoundException,

InvocationTargetException;

public String getState()

throws InstanceNotFoundException, PropertyNotFoundException,

InvocationTargetException;

public void setState(String value)

throws InstanceNotFoundException, IllegalAccessException,

PropertyNotFoundException, InvalidPropertyValueException,

ClassNotFoundException, InstantiationException,

InvocationTargetException;

public void SetState(String oper, String value)

throws InstanceNotFoundException, IllegalAccessException,

PropertyNotFoundException, InvalidPropertyValueException,

ClassNotFoundException, InstantiationException,

InvocationTargetException;

public void performReset()

throws InstanceNotFoundException, NoSuchMethodException,

InvocationTargetException, IllegalAccessException;

}

To Compile the Example C-Bean

Type this command:

prompt javac SimpleBeanMO.java SimpleBeanMOStub.java

Developing a Manager

The SimpleClient example shows the code required in a manager for:

Instantiating an adaptor client
Connecting an adaptor client
Creating an m-bean remotely
Performing management operations
Disconnecting an adaptor client

The Java source code of this example is shown in CODE EXAMPLE 2-7.

package examples.tutorial;

// Copyright (c) 07/23/98, by Sun Microsystems, Inc.

// "@(#)SimpleClient.java 1.7 98/07/23 SMI"

import java.net.* ;

import java.util.* ;

import com.sun.jaw.reference.common.* ;

import com.sun.jaw.impl.adaptor.rmi.* ;

public class SimpleClient {

public static void main(String argv[]) {

try {

String agentHost = InetAddress.getLocalHost().getHostName() ;

if (argv.length >= 1)

agentHost = argv[0] ;

System.out.println(">>> Connecting to " + agentHost + "...") ;

// Set up the RMI AdaptorClient.

//

AdaptorClient adaptor = new AdaptorClient() ;

// Initialize communication with the remote RMI managed object server.

//

adaptor.connect(null, agentHost, 1099, ServiceName.APT_RMI) ;

// Create an instance of the SimpleBean m-bean in the

// remote object server.

//

String simpleClass = "examples.tutorial.SimpleBean" ;

ObjectName simpleName = new

ObjectName("defaultDomain:examples.tutorial.SimpleBean.id=1") ;

SimpleBeanMO simple = (SimpleBeanMO)adaptor.cb_newMO(simpleClass,

simpleName, null) ;

// Access and modify the properties of the SimpleBean m-bean remotely.

//

System.out.println("\nsimple.state = " + simple.getState()) ;

System.out.println("simple.nbChanges = " + simple.getNbChanges()) ;

System.out.println("\n>>> Changing state...") ;

simple.setState("New state") ;

System.out.println("simple.state = " + simple.getState()) ;

System.out.println("simple.nbChanges = " + simple.getNbChanges()) ;

System.out.println("\n>>> Resetting change counters...") ;

simple.performReset() ;

System.out.println("simple.state = " + simple.getState()) ;

System.out.println("simple.nbChanges = " + simple.getNbChanges()) ;

// Terminates the communication with the remote managed object server.

//

adaptor.disconnect() ;

System.exit(0) ;

}

catch(Exception e) {

System.out.println("Got an exception !") ;

e.printStackTrace() ;

System.exit(1) ;

}

Performing Management Operations

CODE EXAMPLE 2-11 shows how to use a handle on an m-bean to perform management operations on the m-bean. In this example, the manager is able to change the state of the m-bean by invoking the setState method and reset the number state changes by invoking the performReset method.

// Access and modify the properties of the SimpleBean m-bean remotely.

//

System.out.println("\nsimple.state = " + simple.getState()) ;

System.out.println("simple.nbChanges = " + simple.getNbChanges()) ;

System.out.println("\n>>> Changing state...") ;

simple.setState("New state") ;

System.out.println("simple.state = " + simple.getState()) ;

System.out.println("simple.nbChanges = " + simple.getNbChanges()) ;

System.out.println("\n>>> Resetting change counters...") ;

simple.performReset() ;

System.out.println("simple.state = " + simple.getState()) ;

System.out.println("simple.nbChanges = " + simple.getNbChanges()) ;

Disconnecting an Adaptor Client

To disconnect an adaptor client from an adaptor, invoke the disconnect method of the adaptor client as shown in CODE EXAMPLE 2-12.

// Terminates the communication with the remote managed object server.

//

adaptor.disconnect() ;

Compiling and Running the Manager

To Compile the Manager

Type this command:

prompt javac SimpleClient.java

To Run the Manager

Type this command:

prompt java examples.tutorial.SimpleClient

Further Examples

The Java Dynamic Management Kit provides a number of examples. The directory containing the source files for the examples depends on the operating environment:


Operating Environment	Directory
Solaris	installDir`/SUNWconn/jaw/examples/src`
Windows NT	installDir`\SUNWconn\jaw\examples\src`

For further information on these examples, including README files, open the HTML page for your operating environment in a web browser:


Operating Environment	Web Page
Solaris	installDir/SUNWconn/jaw/docs/locale/C/JDMKMAIN/index.htm
Windows NT	installDir\SUNWconn\jaw\docs\locale\C\JDMKMAIN\index.htm

A further agent example is described in Appendix D.