Java Dynamic Management Kit 4.0 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.

To demonstrate the management features and tools, the Java Dynamic Management Kit provides a set of example applications. These sample programs show you the source code for implementing various sorts of agents and managers and give you an understanding of different management practices. The Java Dynamic Management Kit 4.0 Tutorial is intended to help you understand these examples and introduce you to programming with the Java Dynamic Management Kit. The examples covered by this tutorial will show you:

The different ways of making your resources manageable
How to write an agent and access it through a web browser
How to load resources and services dynamically from a remote manager
The details of programming SNMP managers and agents with the provided tools

Taken as a whole, the examples demonstrate the complete development process for implementing a management solution in Java. This tutorial only covers certain examples, but all examples are documented in their respective directories.

Who Should Use This Book

This tutorial is 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.0, 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 this tutorial, 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.0 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.0
Java Dynamic Management Kit 4.0 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.0/JDKversion/index.html`
Windows NT	`installDir\SUNWjdmk\jdmk4.0\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 JDK^TM (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.0/JDKversion/examples`
Windows NT	`installDir\SUNWjdmk\jdmk4.0\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^TM 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.0/1.1/lib/jdmkrt.jar:installDir/SUNWjdmk/jdmk4.0/1.1/lib/collections.jar`
1.2	`.:installDir/SUNWjdmk/jdmk4.0/1.2/lib/jdmkrt.jar`

The classpath is 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.0/JDKversion/bin`
Windows NT	`installDir\SUNWjdmk\jdmk4.0\JDKversion\bin`

How This Book Is Organized

Each chapter of this book documents a single topic covered by the example application.

"Standard MBeans" shows how to write a standard MBean by following the design patterns defined by the Java Management extensions. The example shows how an agent then accesses the attributes and operations.
"Dynamic MBeans" shows how to implement the DynamicMBean interface to expose a coherent management interface. Running the example highlights the similarities and differences between dynamic and standard MBeans, with an analysis of performance issues.
"The MBean Server in a Minimal Agent" covers the interface of the MBean server which is used by all agents. We introduce the object name of an MBean which is its only reference in the MBean server. The only MBeans in the minimal agent are the communications MBeans, but this is enough to connect to the agent and manage it.
"The HTML Protocol Adaptor" gives us a management view of the MBeans in an agent through a web browser. It lets us create MBeans, update their attributes, invoke their operations, and remove them dynamically in a running agent.
"The Base Agent" is similar to the minimal agent but it shows how to manipulate MBeans programmatically through the instance of the MBean server. It covers the different ways of creating and interacting with MBeans in the MBean server. This topic also covers how to process the descriptor objects that represent MBean information.
"The M-Let Class Loader" is a service that lets agents and managers load MBean classes dynamically from the network. It is a fully manageable service, which means that a remote manager can create it in an agent and ask it to download classes for new services or new resources.
"Creating an SNMP Agent" demonstrates how the SNMP protocol adaptor makes a Java Dynamic Management agent also act as an SNMP agent. The MBeans generated by the mibgen tool represent SNMP MIBs which can be accessed by any SNMP manager connecting to the SNMP adaptor. This lets you implement your MIB through Java code and take advantage of the agent services.
"Developing an SNMP Manager" shows you how to use the SNMP manager API to program an SNMP manager. An SNMP manager handles Java objects representing peers, parameters, sessions, and requests to access SNMP agents and perform management operations.
"Implementing an SNMP Proxy" gives an example of an SNMP proxy that you can use in an SNMP agent developed with the SNMP adaptor. An SNMP proxy is an object that handles remote MIBs in a sub-agent. The proxy acts as a single point-of-entry to let a manager access a whole hierarchy of sub-agents.

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

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.
`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.

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

Table P-2 Shell Prompts


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