Java Dynamic Management Kit 4.1 Tutorial

Preface

The Java Dynamic Management^TM Kit provides a set of Java^TM classes and tools for developing management solutions. This product conforms to the Java Management extensions (JMX), a specification which defines a three-level architecture: resource instrumentation, dynamic agents and remote management applications. The JMX architecture is applicable to network management, remote system maintenance, application provisioning and the new management needs of the service-based network.

Once you are familiar with management concepts, the Java Dynamic Management Kit 4.1 Tutorial is intended to demonstrate each of the management levels and how they interact. Through their working code samples taken from the example applications, these tutorials will show you:

The different ways of making your resources manageable
How to write an agent and add management services dynamically
How to access your resources from a remote management application
The mechanism used to forward management events from agent to manager

Taken as a whole, these topics will demonstrate the complete development process for implementing a management solution in the Java programming language.

This book ends with a lesson devoted to the details of programming SNMP managers and agents (peers) using the Java Dynamic Management Kit.

Who Should Use This Book

These tutorials are aimed at developers who would like to learn how to instrument new or existing resources for management, write dynamic agents, or write management applications. Familiarity with Java programming is assumed. Some tutorials also rely on system and network management concepts: knowledge of these is helpful though not required.

This book is not intended to be an exhaustive reference. Management concepts and product features are covered in Getting Started with the Java Dynamic Management Kit 4.1, and the complete Javadoc API definitions are provided in the product documentation package.

Before You Read This Book

In order to build and run the sample programs in these tutorials, or use the tool commands, you must have a complete installation of the Java Dynamic Management Kit on your machine. Please refer to the Java Dynamic Management Kit 4.1 Installation Guide and Release Notes document for instructions on how to install the product components and configure your environment.

Before programming with the Java Dynamic Management Kit, you should be familiar with the concepts and tools used throughout these tutorials. The following books are part of the product documentation set:

Getting Started with the Java Dynamic Management Kit 4.1
Java Dynamic Management Kit 4.1 Tools Reference

These books are available on-line after you have installed the documentation package of the Java Dynamic Management Kit. The on-line documentation also includes the Javadoc API for the Java packages and classes. Using any web browser, open the home-page corresponding to your platform:

Operating Environment	Home-Page Location
Solaris	`installDir/SUNWjdmk/jdmk4.1/JDKversion/index.html`
Windows NT	`installDir\SUNWjdmk\jdmk4.1\JDKversion\index.html`

In these file names, installDir refers to the base directory of your Java Dynamic Management Kit installation. The JDKversion is that of the Java Development Kit which you use and which you selected during installation; it can be either 1.1 or 1.2. This convention is used throughout this book whenever referring to files or directories which are part of the installation. In a default installation procedure, installDir is:

/opt on the Solaris platform
C:\Program Files on the Windows NT platform

Directories and Classpath

These tutorials are based on the example programs shipped with the Java Dynamic Management Kit. Each example is a set of Java source code files in a separate subdirectory. The following table gives the location of the main examples directory:

Operating Environment	Examples Directory
Solaris	`installDir/SUNWjdmk/jdmk4.1/JDKversion/examples`
Windows NT	`installDir\SUNWjdmk\jdmk4.1\JDKversion\examples`

Except where noted, the source code in this book is taken from these example programs. However, code fragments may be rearranged or comments may be changed. Program listings in the tutorials usually simplify comments and remove output statements for space considerations.

On the Solaris platform, you must have root access in order to write in the installed examples directory. For this reason, it may be necessary to copy all examples to a different location before compiling them. Throughout the rest of this book, we will use the term examplesDir to refer to the main examples directory in a location where you can compile and run them.

When either compiling or running the example programs, the jar file for the Java Dynamic Management Kit runtime must be in your classpath:

JDK Version	Classpath for Compiling or Running the Examples on Solaris
1.1	`.:installDir/SUNWjdmk/jdmk4.1/1.1/lib/jdmkrt.jar:installDir/SUNWjdmk/jdmk4.1/1.1/lib/collections.jar`
1.2	`.:installDir/SUNWjdmk/jdmk4.1/1.2/lib/jdmkrt.jar`

These classpaths are identical on the Windows NT platform, with the forward slashes (/) replaced with back-slashes (\), and the colons (:) replaced with semi-colons (;).

This classpath assumes that you are in the subdirectory of a particular example when compiling or running it. You specify the classpath on the command line of the javac and java tools with the -classpath option. The JDK version must match the version of the javac or java command that you are using.

Throughout the rest of this book, we will use the term classpath in command line examples to indicate that you must use the classpath indicated above. You may also define this classpath in an environment variable according to your platform and omit its definition on the command line.

In order to use the proxygen and mibgen tools provided with the Java Dynamic Management Kit, you should add the installation's binaries directory your environment's path. The following table give the location of this directory:

Operating Environment	Binaries Directory
Solaris	`installDir/SUNWjdmk/jdmk4.1/JDKversion/bin`
Windows NT	`installDir\SUNWjdmk\jdmk4.1\JDKversion\bin`

How This Book Is Organized

This book is organized like a trail of the The Java Tutorial, each part is a lesson covering a subject and each chapter covers a topic within that subject.

Part I, "Instrumentation through MBeans," shows various ways of making a resource manageable. Topics:

"Standard MBeans"
"Dynamic MBeans"

Part II, "Agent Applications," demonstrates the functionality of the MBean server at the heart of an agent. Topics:

"The MBean Server in a Minimal Agent"
"The HTML Protocol Adaptor"
"The Base Agent"

Part III, "Notification Mechanisms," shows how to send and receive events between resources, agents and remote managers. Topics:

"Agent-Side Notifications"
"Notification Forwarding"

Part IV, "Agent Services," demonstrates the various kinds of management intelligence which can be dynamically added to an agent. Topics:

"The M-Let Class Loader"
"The Relation Service"
"Cascading Agents"
"The Discovery Service"

Part V, "SNMP Interoperability," shows how Java agents can also implement an SNMP agent and how to write a manager with the SNMP manager API. Topics:

"Creating an SNMP Agent"
"Developing an SNMP Manager"
"Security Mechanisms in the SNMP Toolkit"
"Implementing an SNMP Proxy"

Related Books

The Java Dynamic Management Kit relies on the management architecture of the Java Management extensions. The three specifications documents are provided in the product documentation package:

Java Management Extensions Instrumentation and Agent Specification (jmx_instr_agent.pdf)
Java Management Extensions SNMP Manager API (jmx_snmp_api.pdf)

The structure of this book was inspired by that of the The Java Tutorial:

On-line versionhttp://java.sun.com/docs/books/tutorial/index.html
Paperback reference:The Java Tutorial Second Edition: Object-Oriented Programming for the Internet (Java Series) by Mary Campione and Kathy Walrath; 2nd book and CD-ROM edition (March 1998) Addison-Wesley Pub. Co.; ISBN: 0201310074

Some topics refer to RFC "standards" for further information, particularly in the lesson on SNMP. The complete text of RFC papers can be found on the following site. This site is in no way affiliated with Sun Microsystems, Inc. and Sun makes no claim as to the accuracy or relevance of the data it contains:

http://sunsite.auc.dk/RFC/

Ordering Sun Documents

Fatbrain.com, an Internet professional bookstore, stocks selected product documentation from Sun Microsystems, Inc.

For a list of documents and how to order them, visit the Sun Documentation Center on Fatbrain.com at http://www1.fatbrain.com/documentation/sun.

Accessing Sun Documentation Online

The docs.sun.com^SM Web site enables you to access Sun technical documentation online. You can browse the docs.sun.com archive or search for a specific book title or subject. The URL is http://www.oracle.com/technetwork/indexes/documentation/index.html.

Typographic Conventions

The following table describes the typographic changes used in this book.

Table P-1 Typographic Conventions


Typeface or Symbol	Meaning	Example
AaBbCc123	Book titles, new words or terms, or words to be emphasized	Read Chapter 6 in User's Guide. These are called class options. You must be root to do this.
`AaBbCc123`	Class or object names, methods, parameters or any other element of the Java programming language	Instantiate the `MyBean` class.
`AaBbCc123`	The names of commands, files, and directories; on-screen computer output	Edit your `.login` file. Use `ls -a` to list all files. `machine_name% you have mail`
`AaBbCc123`	What you type, contrasted with on-screen computer output	`machine_name%` `su``Password:`
`AaBbCc123`	A placeholder: replace with the appropriate name or intended value	To delete a file, type `rm` `filename`.

Shell Prompts

The following table shows the default system prompts for the different platforms and shells.

Table P-2 Shell Prompts


Shell	Prompt
Bourne shell and Korn shell prompt	`$`
Bourne shell and Korn shell superuser prompt	`#`
Windows NT system prompt	`C:\>`

Unless otherwise noted, the command examples in this book use the Korn shell.