AndrewKassPart No: 806-2986December 1999Sun Microsystems, Inc.

901 San Antonio RoadPalo Alto, CA94303-4900U.S.A.

1999 Sun MicrosystemsThis book leads the reader through the development of dynamic agents and remote managers based on the components of the Java Dynamic Management Kit. Along the way it explains the concepts and the architecture of the Java Management extensions and discusses some design issues of management solutions. It is modeled after the learn-by-example of The Java Tutorial, and based on the source code of the example applications provided with the product. This book is aimed at resource providers who wish to instrument their objects to make them manageable and developers of agent and manager applications. Familiarity with Java programming is assumed, and an understanding of network management concepts is helpful.This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third party software, including font technology, is copyrighted and licensed from Sun suppliers. Federal Acquisitions: Commercial Software--Government Users Subject to Standard License Terms and Conditions.Sun, Sun Microsystems, the Sun Logo, Java, Java Dynamic Management, JavaBeans, JavaScript, JDK, the Java Coffee Cup logo, docs.sun.com, AnswerBook, AnswerBook2, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc in the U.S. and other countries. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open, Ltd.All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS. REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l'utilisation, la copie, la distribution, et la décompilation. Aucune partie de ce produit ou document ne peut être reproduite sous aucune forme, par quelque moyen que ce soit, sans l'autorisation préalable et écrite de Sun et de ses bailleurs de licence, s'il y en a. Le logiciel détenu par des tiers, et qui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun.Sun, Sun Microsystems, le logo Sun, Java, Java Dynamic Management, JavaBeans, JavaScript, JDK, Java Coffee Cup logo, docs.sun.com, AnswerBook, AnswerBook2 et Solaris sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays. UNIX est une marque enregistrée aux Etats-Unis et dans d'autres pays, et exclusivement licenciée par X/Open Ltd.Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d'autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc.LA DOCUMENTATION EST FOURNIE "EN L'ETAT" ET TOUTES AUTRES CONDITIONS, DÉCLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES DANS LA MESURE AUTORISÉE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE À LA QUALITÉ MARCHANDE, À L'APTITUDE À UNE UTILISATION PARTICULIÈRE OU À L'ABSENCE DE CONTREFAÇON.JavaNetwork SoftwareProgramming & ToolsPrefacePrefaceThe Java Dynamic Management Kit provides a set of Java 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 manageableHow to write an agent and access it through a web browserHow to load resources and services dynamically from a remote managerThe details of programming SNMP managers and agents with the provided toolsTaken 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.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.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.0Java Dynamic Management Kit 4.0 Tools ReferenceThese 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 EnvironmentHome-Page LocationSolarisinstallDir/SUNWjdmk/jdmk4.0/JDKversion/index.htmlWindows NTinstallDir\SUNWjdmk\jdmk4.0\JDKversion\index.htmlIn these file names, installDir refers to the base directory of your Java Dynamic Management Kit installation. The JDKversion is that of the JDK (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 platformC:\Program Files on the Windows NT platformThese 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 EnvironmentExamples DirectorySolarisinstallDir/SUNWjdmk/jdmk4.0/JDKversion/examplesWindows NTinstallDir\SUNWjdmk\jdmk4.0\JDKversion\examplesExcept 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 VersionClasspath for Compiling or Running the Examples on Solaris1.1.:installDir/SUNWjdmk/jdmk4.0/1.1/lib/jdmkrt.jar:installDir/SUNWjdmk/jdmk4.0/1.1/lib/collections.jar1.2.:installDir/SUNWjdmk/jdmk4.0/1.2/lib/jdmkrt.jarThe 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 EnvironmentBinaries DirectorySolarisinstallDir/SUNWjdmk/jdmk4.0/JDKversion/binWindows NTinstallDir\SUNWjdmk\jdmk4.0\JDKversion\binEach 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.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.htmlPaperback 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: 0201310074Fatbrain.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.The docs.sun.com 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://docs.sun.com.The following table describes the typographic changes used in this book.Table P-1 Typeface or SymbolMeaningExampleAaBbCc123Book titles, new words or terms, or words to be emphasizedRead Chapter 6 in User's Guide. These are called class options. You must be root to do this.AaBbCc123Class or object names, methods, parameters or any other element of the Java programming languageInstantiate the MyBean class.AaBbCc123The names of commands, files, and directories; on-screen computer outputEdit your .login file. Use ls -a to list all files. AaBbCc123What you type, contrasted with on-screen computer outputmachine_name% suPassword:AaBbCc123A placeholder: replace with the appropriate name or intended valueTo delete a file, type rm filename.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 ShellPromptC shell promptmachine_name%C shell superuser promptmachine_name#Bourne shell and Korn shell prompt$Bourne shell and Korn shell superuser prompt#Windows NT system promptC:\Chapter 11. Standard MBeansA standard MBean is the simplest and fastest way to instrument a resource from scratch: attributes and operations are simply methods which follow certain design patterns. A standard MBean is composed of the MBean interface which lists the methods for all exposed attributes and operations, and of the class which implements this interface and provides the functionality of the resource.The code samples in this topic are taken from the files in the StandardMBean example directory located in the main examplesDir (see "Directories and Classpath" in the preface).Contents:"Exposing the MBean Interface" demonstrates the design patterns for attributes and operations and gives some general rules for writing the MBean interface"Implementing the MBean" shows how the MBean interface is related to the code for the manageable resource"Running the Standard MBean Example" demonstrates the runtime behavior of a standard MBeanTypically, you would first determine the management interface of your resource, that is the information needed to manage it. This information is expressed as attributes and operations. An attribute is a value of any type that a manager can get or set remotely. An operation is a method with any signature and any return type that the manager can invoke remotely.Note - Attributes and operations are conceptually equivalent to properties and actions on JavaBeans objects. However, their translation into Java code is entirely different to accommodate the management functionality.As specified by the Java Management extensions for instrumentation, all attributes and operations are explicitly listed in an MBean interface. This is a Java interface that defines the full management interface of an MBean. This interface must have the same name as the class that implements it, followed by the MBean suffix. Since the interface and its implementation are usually in different files, there are two files which make up a standard MBean.For example, the class SimpleStandard (in the file SimpleStandard.java) will have its management interface defined in the interface SimpleStandardMBean (in the file SimpleStandardMBean.java).Example 1-1 public interface SimpleStandardMBean { public String getState() ; public void setState(String s) ; public Integer getNbChanges() ; public void reset() ; }Only public methods in the MBean interface are taken into consideration for the management interface. When present, non-public methods should be grouped separately, to make the code clearer for human readers.Attributes are conceptual variables that are exposed for management through getter and setter methods in the MBean interface:A getter is any public method whose name begins with get and which doesn't return void; it lets a manager read the value of the attribute, whose type is that of the returned objectA public method whose name begins with is and which returns a boolean or Boolean object is also a getter, though a boolean attribute may have only one getter (it must be one form or the other)A setter is any public method whose name begins with set and which takes a single parameter; it lets a manager write a new value in the attribute, whose type is that of the parameterAttribute types can be arrays of objects, but individual array elements cannot be accessed individually through the getters and setters. Use operations to access the array elements, as described below. The following code example demonstrates an attribute with an array type:public String[] getMessages(); public void setMessages(String[] msgArray);The name of the attribute is the literal part of the method name following get, is, or set. This name is case sensitive in all Java Dynamic Management Kit objects that manipulate attribute names. Using these patterns, we can determine the attributes exposed in the code sample above:State is a readable and writeable attribute of type StringNbChanges is a read-only attribute of type IntegerThe specification of the design patterns for attributes implies the following rules:Attributes may be read-only, write-only, or readable and writeableAttribute names cannot be overloaded: for any given attribute name there can be at most one setter and one getter, and if both are defined, they must use the same typeOperations are methods that management applications can call remotely on a resource. They can be defined with any number of parameters of any type and can return any type.The design patterns for operations are simple: any public method defined in the MBean interface that is not an attribute getter or setter is an operation. For this reason, getters and setters are usually declared first in the Java code, so that all operations are grouped afterwards. The name of an operation is the name of the corresponding method.The SimpleStandardMBean in the example defines one operation, reset, which takes no parameters and returns nothing.While the following methods define valid operations (and not attributes), these types of names should not be used to avoid confusion:public void getFoo(); public Integer getBar(Float p); public void setFoo(Integer one, Integer two); public String isReady();For performance reasons, you may want to define operations for accessing individual elements of an array type attribute. In this case, use non-ambiguous operation names:public String singleGetMessage(int index); public void singleSetMessage(int index, String msg);Note - The Java Dynamic Management Kit imposes no restrictions on attribute types, operation attribute types, and operation return types. However, the developer must insure that the corresponding classes are available to all applications manipulating these objects, and that they are compatible with the type of communication used. For example, attribute and operation types must be serializable in order to be manipulated remotely using the RMI or HTTP protocol.The second part of an MBean is the class that implements the MBean interface. This class encodes the expected behavior of the manageable resource in its implementation of the attribute and operation methods. Of course, the resource does not need to reside entirely in this class, the MBean implementation can rely on other objects.Beyond the implementation of the corresponding MBean interface, there are two requirements on the MBean class:It must be a concrete class so that it can be instantiatedIt must expose at least one public constructor so that any other class can create an instanceOtherwise, the developer is free to implement the management interface in any way, provided of course that the object has the expected behavior. Here is the sample code that implements our MBean interface:Example 1-2 public class SimpleStandard implements SimpleStandardMBean { public String getState() { return state; } public void setState(String s) { state = s; nbChanges++; } public Integer getNbChanges() { return new Integer(nbChanges); } public void reset() { state = "initial state"; nbChanges = 0; nbResets++; } // This method is not a getter in the management sense because // it is not exposed in the "SimpleStandardMBean" interface. public Integer getNbResets() { return new Integer(nbResets); } // internal variables for exposed attributes private String state = "initial state"; private int nbChanges = 0; // other private variables private int nbResets = 0; }In this example there is no constructor. Since the Java compiler provides a public, no-argument constructor by default in such cases, this is a valid MBean.As in this example, attributes are usually implemented as internal variables whose value is returned or modified by the getter and setter methods. However, an MBean may implement any access and storage scheme to fit particular management needs, provided getters and setters retain their read and write semantics. Methods in the MBean implementation may have side-effects, but it is up to the programmer to insure that these are safe and coherent within the full management solution.As we shall see later, management applications never have a direct handle on an MBean. They only have an identification of an instance and the knowledge of the management interface. In this case, the mechanism for exposing attributes through methods in the MBean interface makes it impossible for an application to access the MBean directly. Internal variables and methods, and even public ones, are totally encapsulated and their access is controlled by the programmer through the implementation of the MBean interface.The examplesDir/StandardMBean directory contains the SimpleStandard.java and SimpleStandardMBean.java files which make up the MBean. This directory also contains a simple agent application which instantiates this MBean, introspects its management interface and manipulates its attributes and operations.Compile all files in this directory with the javac command. For example, on the Solaris platform with the Korn shell, you would type:$ cd examplesDir/StandardMBean/ $ javac -classpath classpath *.javaTo run the example, launch the agent class which will interact with the SimpleStandard MBean:$ java -classpath classpath StandardAgentType return when the application pauses to step through the example. The agent application handles all input and output in this example and gives us a view of the MBean at runtime.We will look at how agents work in "The MBean Server in a Minimal Agent", but this example demonstrates how the MBean interface limits the view of what the MBean exposes for management. Roughly, the agent introspects the MBean interface at runtime to determine what attributes and operations are available. You then see the result of calling the getters, setters and operations.The lesson on agents will also cover the topics of object names and exceptions which you see when running this example.Chapter 22. Dynamic MBeansA dynamic MBean implements its management interface programmatically, instead of through static method names. To do this, it relies on descriptor classes which represent the attributes and operations exposed for management. Management applications then call generic getters and setters whose implementation must resolve the attribute or operation name to its intended behavior.One advantage of this instrumentation is that you can use it to quickly make an existing resource manageable. The implementation of the DynamicMBean interface can provide an instrumentation wrapper for an existing resource.Another advantage is that the descriptor classes for the management interface can provide human-readable descriptions of the attributes, operations and MBean itself. This information could be displayed to a user on a management console to describe how to interact with this particular resource.The code samples in this topic are taken from the files in the DynamicMBean example directory located in the main examplesDir (see "Directories and Classpath" in the preface).Contents:"Exposing the Management Interface" explains the DynamicMBean interface and its generic methods common to all dynamic MBeans"Implementing a Dynamic MBean" shows how to implement this interface to expose specific attributes and operations"Running the Dynamic MBean Example" demonstrates the runtime behavior of a dynamic MBeanIn the standard MBean, attributes and operations are exposed statically in the names of methods in the MBean interface. Dynamic MBeans all share the same interface which defines generic methods to access attributes and operations. Since the management interface is no longer visible through introspection, dynamic MBeans must also provide a description of their attributes and operations explicitly.The DynamicMBean class is a Java interface defined by the Java Management extensions. It specifies the methods that a resource implemented as a dynamic MBean must provide to expose its management interface. Here is an uncommented version of the code:Example 2-1 public interface DynamicMBean { public Object getAttribute(String attribute) throws AttributeNotFoundException, MBeanException, ReflectionException; public void setAttribute(Attribute attribute) throws AttributeNotFoundException, InvalidAttributeValueException, MBeanException, ReflectionException ; public AttributeList getAttributes(String[] attributes); public AttributeList setAttributes(AttributeList attributes); public Object invoke( String actionName, Object params[], String signature[]) throws MBeanException, ReflectionException ; public MBeanInfo getMBeanInfo(); }The getMBeanInfo method is the one which provides a description of the MBean's management interface. This method returns an MBeanInfo object which is the descriptor type that contains information about attributes and operations.The attribute getters and setters are generic, since they take the name of the attribute which needs to be read or written. For convenience, dynamic MBeans must also define bulk getters and setters to operate on any number of attributes at once. These methods use the Attribute and AttributeList classes to represent attribute name-value pairs and lists of name-value pairs, respectively.Since the names of the attributes are not revealed until runtime, the getters and setters are necessarily generic. In the same way, the invoke method takes the name of an operation and its signature, in order to invoke any method which might be exposed. As a consequence of implementing generic getters, setters, and invokers, the code for a dynamic MBean is more complex than for a standard MBean. For example, instead of having a specific getter called by name, the generic getter must verify the attribute name and then encode the functionality to read each of the possible attributes.A dynamic MBean has the burden of building the description of its own management interface. The JMX specification defines the Java objects used to completely describe the management interface of an MBean. Dynamic MBeans use these objects to provide a complete self description as returned by the getMBeanInfo method. Agents also use these classes to describe a standard MBean after it has been introspected.As a group, they are referred to as the MBean descriptor classes because they provide information about the MBean. This information includes the attributes and operations of the management interface but also the list of constructors for the MBean class and the notifications that the MBean may send. Notifications are messages in the event mechanism that is defined by the JMX architecture; they are covered in the notification example in examplesDir/Notification.Each element is described by its descriptor object containing its name, a description string, and its characteristics. For example, an attribute has a type and is readable and/or writeable. The following table lists all MBean descriptor classes:Class NamePurposeMBeanInfoTop-level object containing arrays of descriptors for all MBean elements; also includes the name of the MBean's Java class and a description stringMBeanFeatureInfoParent class for all other descriptors so that they inherit a name and a description stringMBeanOperationInfoDescribes an operation: the return type, the signature as an array of parameters, and the impact (whether the operation just returns information or modifies the resource)MBeanConstructorInfoDescribes a constructor by its signatureMBeanParameterInfoGives the type of a parameter in an operation or constructor signatureMBeanAttributeInfoDescribes an attribute: its type, whether it is readable, and whether it is writeableMBeanNotificationInfoContains an array of notification type stringsA dynamic MBean consists of a class that implements the DynamicMBean interface coherently. By this, we mean a class which exposes a management interface whose description matches the attributes and operations which are accessible through the generic getters, setters and invokers.Note - MBeans are not allowed to be both standard and dynamic. When a class is instantiated as an MBean, the agent checks the interfaces that it implements. If the class implements or inherits an implementation of both the corresponding MBean interface and the DynamicMBean interface, then an exception is raised and the MBean cannot be created.Beyond this restriction, a dynamic MBean must also follow the same two rules as a standard MBean, namely: It must be a concrete class so that it can be instantiatedIt must expose at least one public constructor so that any other class can create an instanceThereafter, a dynamic MBean class is free to declare any number of public or private methods and variables. None of these are visible to management applications, only the methods implementing the DynamicMBean interface are exposed for management. A dynamic MBean is also free to rely on other classes which may be a part of the manageable resource.An MBean is a manageable resource that exposes a specific management interface. The name dynamic MBean refers to the fact that the interface is revealed at runtime, as opposed to through the introspection of static class names. The term dynamic is not meant to imply that the MBean can dynamically change its management interface. The management architecture defined by JMX and implemented in the Java Dynamic Management Kit does not support MBeans whose management interface is modified during runtime.This is not an issue with standard MBeans which would need to be recompiled in order to change their interface. However, dynamic MBeans could be programmed so that their interface description and their generic getters, setters and the invoker have a different behavior at different times. In practice, this type of MBean could be created but it couldn't be managed after any change of interface. As a rule, the value returned by the MBeanInfo method of a dynamic MBean, and the corresponding behavior of getters, setters and the invoker, must never change over the lifetime of a given instance of the MBean. However, it is permissible to have the same dynamic MBean class expose different management interfaces depending upon the instantiation conditions. This would be a valid MBean, since the agent architecture manages object instances, not class types. It would also be a very advanced MBean for a complex management solution, beyond the scope of this tutorial.Since the MBean description should never change, it is usually created once at instantiation, and the getMBeanInfo method just returns its reference at every call. The MBean constructor should therefore build the MBeanInfo object from the MBean descriptor classes such that it accurately describes the management interface. And since most dynamic MBeans will always be instantiated with the same management interface, building the MBeanInfo object is fairly straightforward.The following code shows how the SimpleDynamic MBean defines its management interface, as built at instantiation and returned by its getMBeanInfo method:Example 2-2 // class constructor public SimpleDynamic() { buildDynamicMBeanInfo(); } // internal variables describing the MBean private String dClassName = this.getClass().getName(); private String dDescription = "Simple implementation of a dynamic MBean."; // internal variables for describing MBean elements private MBeanAttributeInfo[] dAttributes = new MBeanAttributeInfo[2]; private MBeanConstructorInfo[] dConstructors = new MBeanConstructorInfo[1]; private MBeanOperationInfo[] dOperations = new MBeanOperationInfo[1]; private MBeanInfo dMBeanInfo = null; // internal method private void buildDynamicMBeanInfo() { dAttributes[0] = new MBeanAttributeInfo( "State", // name "java.lang.String", // type "State: state string.", // description true, // readable true); // writable dAttributes[1] = new MBeanAttributeInfo( "NbChanges", "java.lang.Integer", "NbChanges: number of times the State string has been changed.", true, false); // use reflection to get constructor signatures Constructor[] constructors = this.getClass().getConstructors(); dConstructors[0] = new MBeanConstructorInfo( "SimpleDynamic(): No-parameter constructor", //description constructors[0]); // the contructor object MBeanParameterInfo[] params = null; dOperations[0] = new MBeanOperationInfo( "reset", // name "Resets State and NbChanges attributes to their initial values", // description params, // parameter types "void", // return type MBeanOperationInfo.ACTION); // impact dMBeanInfo = new MBeanInfo(dClassName, dDescription, dAttributes, dConstructors, dOperations, new MBeanNotificationInfo[0]); } // exposed method implementing the DynamicMBean.getMBeanInfo interface public MBeanInfo getMBeanInfo() { // return the information we want to expose for management: // the dMBeanInfo private field has been built at instantiation time, return(dMBeanInfo); }Generic getters and setters take a parameter that indicates the name of the attribute to read or write. There are two issues to keep in mind when implementing these methods:Attribute names must be correctly mapped to their corresponding internal representationInvalid attribute names and types should raise an exception, including when writing to a read-only attribute (and vice-versa)The getAttribute method is the simplest, since only the attribute name must be verified:Example 2-3 public Object getAttribute(String attribute_name) throws AttributeNotFoundException, MBeanException, ReflectionException { // Check attribute_name to avoid NullPointerException later on if (attribute_name == null) { throw new RuntimeOperationsException( new IllegalArgumentException("Attribute name cannot be null"), "Cannot invoke a getter of " + dClassName + " with null attribute name"); } // Call the corresponding getter for a recognized attribute_name if (attribute_name.equals("State")) { return getState(); } if (attribute_name.equals("NbChanges")) { return getNbChanges(); } // If attribute_name has not been recognized throw(new AttributeNotFoundException( "Cannot find " + attribute_name + " attribute in " + dClassName)); } // internal methods for getting attributes public String getState() { return state; } public Integer getNbChanges() { return new Integer(nbChanges); } // internal variables representing attributes private String state = "initial state"; private int nbChanges = 0;The setAttribute method is more complicated, since you must also insure that the given type can be assigned to the attribute and handle the special case for a null value:Example 2-4 public void setAttribute(Attribute attribute) throws AttributeNotFoundException, InvalidAttributeValueException, MBeanException, ReflectionException { // Check attribute to avoid NullPointerException later on if (attribute == null) { throw new RuntimeOperationsException( new IllegalArgumentException("Attribute cannot be null"), "Cannot invoke a setter of " + dClassName + " with null attribute"); } // Note: Attribute class constructor ensures the name not null String name = attribute.getName(); Object value = attribute.getValue(); // Call the corresponding setter for a recognized attribute name if (name.equals("State")) { // if null value, try and see if the setter returns any exception if (value == null) { try { setState( null ); } catch (Exception e) { throw(new InvalidAttributeValueException( "Cannot set attribute "+ name +" to null")); } } // if non null value, make sure it is assignable to the attribute else { try { if ((Class.forName("java.lang.String")).isAssignableFrom( value.getClass())) { setState((String) value); } else { throw(new InvalidAttributeValueException( "Cannot set attribute "+ name + " to a " + value.getClass().getName() + " object, String expected")); } } catch (ClassNotFoundException e) { e.printStackTrace(); } } } // optional: recognize an attempt to set a read-only attribute else if (name.equals("NbChanges")) { throw(new AttributeNotFoundException( "Cannot set attribute "+ name + " because it is read-only")); } // unrecognized attribute name else { throw(new AttributeNotFoundException( "Attribute " + name + " not found in " + this.getClass().getName())); } } // internal method for setting attribute public void setState(String s) { state = s; nbChanges++; }Notice that the generic getter and setter methods usually hard-code information about the attributes. If a change in your management solution requires you to change your management interface, it will be harder to do with a dynamic MBean. In a standard MBean, each attribute and operation is a separate method, so unchanged attributes are unaffected. In a dynamic MBean, you must modify these generic methods that encode all attributes.The DynamicMBean interface includes bulk getter and setter methods for reading or writing more than one attribute at once. These methods rely on the following classes:Class NamePurposeAttributeA simple object which contains the name string and value object of any attribute.AttributeListA dynamically extendable list of Attribute objects (extends java.util.ArrayList)The AttributeList class extends the java.util.ArrayList class which is specific to Java 2. For this class and others that rely on similar sets and collection, the Java Dynamic Management Kit provides the collections.jar file for complete compatibility using any JDK version 1.1.x. See Directories and Classpath in the preface for more information.The bulk getter and setter methods usually rely on the generic getter and setter, respectively. This makes them independent of the management interface, which can simplify certain modifications. In this case, their implementation consists mostly of error checking on the list of attributes. However, all bulk getters and setters must implement the following behavior: an error on any one attribute does not interrupt or invalidate the bulk operation on the other attributes.If an attribute cannot be read, then its name-value pair does not figure in the list of results. If an attribute cannot be written, it will not be copied to the returned list of successful set operations. As a result, if there are any errors, the lists returned by bulk operators will not have the same length as the array or list passed to them. In any case, the bulk operators do not guarantee that their returned lists have the same ordering of attributes as the input array or list.The SimpleDynamic MBean shows one way of implementing the bulk getter and setter methods:Example 2-5 public AttributeList getAttributes(String[] attributeNames) { // Check attributeNames to avoid NullPointerException later on if (attributeNames == null) { throw new RuntimeOperationsException( new IllegalArgumentException( "attributeNames[] cannot be null"), "Cannot invoke a getter of " + dClassName); } AttributeList resultList = new AttributeList(); // if attributeNames is empty, return an empty result list if (attributeNames.length == 0) return resultList; // build the result attribute list for (int i=0 ; i<attributeNames.length ; i++){ try { Object value = getAttribute((String) attributeNames[i]); resultList.add(new Attribute(attributeNames[i],value)); } catch (Exception e) { // print debug info but continue processing list e.printStackTrace(); } } return(resultList); } public AttributeList setAttributes(AttributeList attributes) { // Check attributesto avoid NullPointerException later on if (attributes == null) { throw new RuntimeOperationsException( new IllegalArgumentException( "AttributeList attributes cannot be null"), "Cannot invoke a setter of " + dClassName); } AttributeList resultList = new AttributeList(); // if attributeNames is empty, nothing more to do if (attributes.isEmpty()) return resultList; // try to set each attribute and add to result list if successful for (Iterator i = attributes.iterator(); i.hasNext();) { Attribute attr = (Attribute) i.next(); try { setAttribute(attr); String name = attr.getName(); Object value = getAttribute(name); resultList.add(new Attribute(name,value)); } catch(Exception e) { // print debug info but keep processing list e.printStackTrace(); } } return(resultList); }Finally, a dynamic MBean must implement the invoke method so that operations in the management interface can be called. This method requires the same considerations as the generic getter and setter:Operations and their parameters should be mapped to their internal representation and the result must be returnedOperation names and parameter types need to be verifiedThese verifications are usually hard-coded, again making modifications to the management interface more delicate than in a standard MBeanThe implementation in the SimpleDynamic MBean is relatively simple due to the one operation with no parameters:Example 2-6 public Object invoke( String operationName, Object params[], String signature[]) throws MBeanException, ReflectionException { // Check operationName to avoid NullPointerException later on if (operationName == null) { throw new RuntimeOperationsException( new IllegalArgumentException( "Operation name cannot be null"), "Cannot invoke a null operation in " + dClassName); } // Call the corresponding operation for a recognized name if (operationName.equals("reset")){ // this code is specific to the internal "reset" method: reset(); // no parameters to check return null; // and no return value } else { // unrecognized operation name: throw new ReflectionException( new NoSuchMethodException(operationName), "Cannot find the operation " + operationName + " in " + dClassName); } } // internal variable private int nbResets = 0; // internal method for implementing the reset operation public void reset() { state = "initial state"; nbChanges = 0; nbResets++; } // Method not revealed in the MBean description and not accessible // through "invoke" therefore it is only available for internal mgmt public Integer getNbResets() { return new Integer(nbResets); }As it is written, the SimpleDynamic MBean correctly provides a description of its management interface and implements its attributes and operations. However, this example demonstrates the need for a strict coherence between what is exposed by the getMBeanInfo method and what can be accessed through the generic getters, setters, and invoker.A dynamic MBean whose getMBeanInfo method describes an attribute or operation which cannot be accessed is not compliant with the Java Management extensions and is technically not a manageable resource. Similarly, a class could make attributes or operations accessible without describing them in the returned MBeanInfo object. Since MBeans should raise an exception when an undefined attribute or operation is accessed, this would, again, technically not be a compliant resource.The examplesDir/DynamicMBean directory contains the SimpleDynamic.java file which makes up the MBean. The DynamicMBean interface is defined in the javax.management package provided in the run-time jar file (jdmkrt.jar) of the Java Dynamic Management Kit. This directory also contains a simple agent application which instantiates this MBean, calls its getMBeanInfo method to get its management interface and manipulates its attributes and operations.Compile all files in this directory with the javac command. For example, on the Solaris platform, you would type:$ cd examplesDir/DynamicMBean/$ javac -classpath classpath *.javaTo run the example, launch the agent class which will interact with the SimpleDynamic MBean:$ java -classpath classpath DynamicAgentType return when the application pauses to step through the example. The agent application handles all input and output in this example and gives us a view of the MBean at runtime.This example demonstrates how the management interface encoded in the getMBeanInfo method is made visible in the agent application. We can then see the result of calling the generic getters and setters and the invoke method. Finally, the code for filtering attribute and operation errors is exercised, and we see the exceptions from the code samples as they are raised at runtime.Now that we have implemented both types of MBeans we can compare how they are managed. We purposely created a dynamic MBean and a standard MBean with the same management interface so that we can do exactly the same operations on them. On the Solaris platform, we can compare the relevant code of the two agent applications with the diff utility (your output may vary):$ cd examplesDir $ diff ./StandardMBean/StandardAgent.java ./DynamicMBean/DynamicAgent.java [...] 41c40 < public class StandardAgent { --- > public class DynamicAgent { 49c48 < public StandardAgent() { --- > public DynamicAgent() { 77c76 < StandardAgent agent = new StandardAgent(); --- > DynamicAgent agent = new DynamicAgent(); 88c87 < println("\n>>> END of the SimpleStandard example:\n"); --- > println("\n>>> END of the SimpleDynamic example:\n"); 113c112 < String mbeanName = "SimpleStandard"; --- > String mbeanName = "SimpleDynamic";If the two agent classes had the same name, we see that the only programmatic difference would be the following:113c112 < String mbeanName = "SimpleStandard"; --- > String mbeanName = "SimpleDynamic";We can see that there is only one difference between the two example agents handling different types of MBeans: the name of the MBean class that is instantiated! In other words, standard and dynamic MBeans are indistinguishable from the agent's point of view. This is the power of the JMX architecture: managers interact with the attributes and operations of a manageable resource, and the specification of the agent hides any implementation differences between MBeans.Since we know that the two MBeans are being managed identically, we can also compare their runtime behavior. In doing so, we can draw two conclusions:The dynamic MBean was programmed to have the same behavior as the standard MBean; the example output shows that this is indeed the case: despite the different implementations, the functionality of the resource is strictly the sameThe only functional difference between the two is that the agent can obtain the self-description strings encoded in the dynamic MBean: attributes and operations are associated with the explanation that the programmer provides for themNote - There is no mechanism allowing a standard MBean to provide a self-description, the agent provides a default description string for each feature in standard MBeans--these descriptions are the same for all standard MBeans.In the introduction to this topic we presented two structural advantages of dynamic MBeans, namely the ability to wrap existing code to make it manageable and the ability to provide a self-description of the MBean and its features. Another advantage is that using dynamic MBeans can lead to faster overall execution time. The performance gain depends on the nature of the MBean and how it is managed in the agent. For example, the SimpleDynamic MBean, as it is used, is probably not measurably faster than the SimpleStandard example in the Chapter 1, Standard MBeans topic. When seeking improved performance, there are two situations which must be considered: MBean introspection, and management operations.Since the dynamic MBean provides its own description, the agent doesn't need to introspect it as it would a standard MBean. Since introspection is done only once by the agent, this is a one-time performance gain during the lifetime of the MBean. In an environment where there are many MBean creations and where MBeans have a short lifetime, a slight performance increase can be measured.However, the largest performance gain is in the management operations: calling the getters, setters and invoker. As we shall see in the next lesson ("The MBean Server in a Minimal Agent"), the agent makes MBeans manageable through generic getters, setters, and invokers. In the case of standard MBeans, the agent must do the computations for resolving attribute and operation names according to the design patterns. Since dynamic MBeans necessarily expose the same generic methods, these are called directly by the agent. When a dynamic MBean has a simple management interface requiring simple programming logic in its generic methods, its implementation can show a better performance than the same functionality in a standard MBean.Chapter 33. The MBean Server in a Minimal AgentAn agent application is a program written in the Java language which contains an MBean server and some way of accessing its functionality. This would be a minimal agent, anything less couldn't be managed. In our example of a minimal agent, we will access the MBean server through the HTML protocol adaptor from a web browser.In a real management solution, the agent could be instantiated and loaded with MBeans for all services and resources that it might need when launched. However, a minimal agent might also be used when resources and services are unknown at launch time. They would be instantiated dynamically at a later date by some management application connected to the agent. This flexibility shows how the Java Dynamic Management Kit lets you develop many different management solutions, depending on your intended deployment strategy.For now we will focus on the functionality of the MBean server and how to interact with it through the HTML protocol adaptor. The code samples in this chapter are taken from the files in the MinimalAgent example directory located in the main examplesDir (see "Directories and Classpath" in the preface).Contents:"MBean Server Classes" explains the interfaces of the MBean server classes"The Minimal Agent" shows the code needed to write an agent application"Referencing MBeans" covers the objects used to reference an MBean in an agent"A Minimalist Agent" shows the code for a very small but complete agent"Running the Minimal Agent Example" demonstrates its run-time behaviorBefore writing an agent application, it is important to understand the functionality of the MBean server. It is actually an interface and a factory object defined by the agent specification level of the Java Management extensions. The Java Dynamic Management Kit provides an implementation of this interface and factory. The factory object finds or creates the MBean server instance, making it possible to substitute different implementations of the MBean server.The specification of the interface defines all operations that can be applied to resources and other agent objects through the MBean server. Its methods can be divided into three main groups:Methods for controlling MBean instances:createMBean, or instantiate and registerMBean add a new MBean to the agentunregisterMBean removes an MBean from the agentisRegistered and getObjectInstance associate the class name with the MBean's management nameaddNotificationListener and removeNotificationListener control event listeners for a particular MBeandeserialize is used to download new MBean classesMethods for accessing MBean attributes and operations; these methods are identical to those presented in "The DynamicMBean Interface", except they all have an extra parameter for specifying the target MBean:getMBeanInfogetAttribute and getAttributessetAttribute and setAttributesinvokeMethods for managing the agent as a whole:getDefaultDomain (domains are a way of grouping MBeans in the agent)getMBeanCount of all MBeans in an agentqueryMBeans and queryNames are used to find MBeans by name or by valueThe MBeanServerImpl class in the Java Dynamic Management Kit implements the MBeanServer interface. It is the class that will be instantiated in an agent. However, it is never instantiated directly by the agent application. Instead, you rely on the MBean server factory to return a new instance of the implementing class.The MBeanServerFactory is a static class defined by the Java Management extensions that makes the agent application independent of the MBean server implementation. It resides in the Java virtual machine and centralizes all MBean server instantiation. It provides two static methods:createMBeanServer which returns a new MBean server instancefindMBeanServer which returns a list of MBean servers in the Java virtual machineYou must use this class to create an MBean server so that other objects can obtain its reference by calling the findMBeanServer method. This method allows dynamically loaded objects to find the MBean server in an agent which has already been launched.The minimal agent contains only the essential components of a complete agent application. These are:An instance of the MBean serverSome means of communicationThe following code is the complete application from the MinimalAgent.java file:Example 3-1 import javax.management.ObjectInstance; import javax.management.MBeanServer; import javax.management.MBeanServerFactory; public class MinimalAgent { public static void main(String[] args) { // Instantiate the MBean server System.out.println("\nCreate the MBean server"); MBeanServer server = MBeanServerFactory.createMBeanServer(); // Create and start some way of communicating: // - an HTML protocol adaptor // - an HTTP connector server // - an RMI connector server // Any single one of these would be sufficient try { System.out.println( "\nCreate and start an HTML protocol adaptor"); ObjectInstance html = server.createMBean( "com.sun.jdmk.comm.HtmlAdaptorServer", null); server.invoke(html.getObjectName(), "start", new Object[0], new String[0]); System.out.println( "\nCreate and start an HTTP connector server"); ObjectInstance http = server.createMBean( "com.sun.jdmk.comm.HttpConnectorServer", null); server.invoke(http.getObjectName(), "start", new Object[0], new String[0]); System.out.println( "\nCreate and start an RMI connector server"); ObjectInstance rmi = server.createMBean( "com.sun.jdmk.comm.RmiConnectorServer", null); server.invoke(rmi.getObjectName(), "start", new Object[0], new String[0]); } catch(Exception e) { e.printStackTrace(); return; } System.out.println( "\nNow, you can point your browser to http://localhost:8082/"); System.out.println( "or start your management application to connect to this agent.\n"); } }Here we analyze the most important lines of code in this example. We start with the instantiation of the MBean server:MBeanServer server = MBeanServerFactory.createMBeanServer();The MBean server is created through the static MBeanServerFactory object, and we store its object reference. Its true type is hidden by the factory object, which casts the returned object as an MBeanServer interface. The MBean server is the only functional class referenced directly in this application.Then we just need some means of communicating (only the HTML adaptor is shown here):ObjectInstance html = server.createMBean("com.sun.jdmk.comm.HtmlAdaptorServer", null); server.invoke(html.getObjectName(), "start", new Object[0], new String[0]);For each of the communications protocols we ask the MBean server to create the corresponding MBean. We must provide the class name of the MBean which we want the MBean server to instantiate. The MBean server instantiates the object, registers it for management, and returns its ObjectInstance reference (see "The ObjectInstance of an MBean").When an MBean is created through the MBean server, you can never obtain a direct programmatic reference on an MBean. The object instance is the only handle the caller has on the MBean. The MBean server hides the MBean object instance and only exposes its management interface.We then ask the server to invoke the start operation of the HTML adaptor's MBean. The object instance gives us the MBean's object name which is what we use to identify the MBean (see "Object Names"). The other parameters correspond to the signature of the start operation which takes no parameters. This operation activates the adaptor or connector so that it will respond to remote management operations on its default port. We can now connect to the HTML protocol adaptor from a web browser.As demonstrated by the minimal agent, most agent applications interact with MBeans through the MBean server. It is possible for an object to instantiate an MBean class itself which it can then register in the MBean server. In this case, it may keep a programmatic reference to the MBean instance. All other objects can only interact with the MBean through its management interface exposed by the MBean server. In particular, service MBeans and connectivity MBeans rely solely on the MBean server to access resources. The MBean server centralizes the access to all MBeans: it unburdens all other objects from having to keep numerous object references. To insure this function, the MBean server relies on object names to uniquely identify MBean instances.Each MBean object registered in the MBean server is identified by an object name. The same MBean class can have multiple instances, but each must have a unique name. The ObjectName class encapsulates an object name which is composed of a domain name and a set of key properties. The object name can be represented as a string in the following format:DomainName:property=value[,property2=value2]*The DomainName, the properties and their values can be any alpha-numeric string, so long as they don't contain any of the following characters: : , = * ?. All elements of the object name are treated as literal strings, meaning that they are case sensitive.A domain is an abstract category that can be used to group MBeans arbitrarily. The MBean server lets you easily search for all MBeans with the same domain. For example, all connectivity MBeans in the minimal server could have been registered into a domain called Communications.Since all object names must have a domain, the MBeans in an MBean server necessarily define at least one domain. When the domain name is not important, the MBean server provides a default domain name which you can use. By default, it is called the DefaultDomain, but you may specify a different default domain name when creating the MBean server from its factory.A key is a property-value pair that can also have any meaning that you assign to it. An object name must have at least one key. Keys and their values are independent of the MBean's attributes: the object name is a static identifier which should identify the MBean, whereas attributes are the exposed, run-time values of the corresponding resource. Keys are not positional and can be given in any order to identify an MBean.Keys usually provide the specificity for identifying a unique MBean instance. For example, a better object name for the HTML protocol adaptor MBean might be: Communications:protocol=html,port=8082, assuming the port will not change.All MBeans must be given an object name that is unique. It can be assigned by the MBean's pre-registration method, if the MBean supports pre-registration (see the JMX specification). Or it can be assigned by the object which creates or registers the MBean, which overrides the one given during pre-registration. However, if neither of these assign an object name, the MBean server will not create the MBean and raise an exception. Once an MBean is instantiated and registered, its assigned object name cannot be modified.You are free to encode any meaning into the domain and key strings, the MBean server just handles them as literal strings. The contents of the object name should be determined by your management needs. Keys could be meaningless serial numbers if MBeans are always handled programmatically. On the other hand, the keys could be human-readable to simplify their translation to the graphical user interface of a management application. With the HTML protocol adaptor, object names are displayed directly to the user.An object instance represents the complete reference of an MBean in the MBean server. It contains the MBean's object name and its Java class name. Object instances are returned by the MBean server when an MBean is created or in response to queries about MBeans. Since the object name and class name cannot change over the life of a given MBean, its returned object instance will always have the same value.You cannot modify the class or object name in an object instance, this information can only be read. The object name is used to refer to the MBean instance in any management operation through the MBean server. The class name may be used to instantiate similar MBeans or introspect characteristics of the class.The following code is one of the smaller agents you can write. It retains all of the functionality that we will need to connect to it with a web browser in the next topic ("The HTML Protocol Adaptor").Example 3-2 import javax.management.ObjectInstance; import javax.management.MBeanServer; import javax.management.MBeanServerFactory; public class MinimalistAgent { public static void main(String[] args) { MBeanServer server = MBeanServerFactory.createMBeanServer(); try { ObjectInstance html = server.createMBean( "com.sun.jdmk.comm.HtmlAdaptorServer", null); server.invoke(html.getObjectName(), "start", null, null); } catch(Exception e) { e.printStackTrace(); return; } } }Note - Only three classes are "imported" by this program and needed to compile it. However, the MBean server dynamically instantiates other classes such as the HtmlAdaptorServer which are needed at run-time. As a result, the Java Dynamic Management Kit runtime jar file (jdmkrt.jar) must be in the classpath of the Java virtual machine running the minimal agent.The MinimalistAgent relies on the HTML adaptor, but we could have used any MBean that provides some way of accessing the MBean server. You could even use your own MBean that encodes some proprietary protocol, provided it makes all functionality of the MBean server available remotely.It is important to realize that this minimalist agent is a fully functional agent that is every bit as powerful as any agent that may be deployed. Since we can connect to this agent, we can dynamically create new MBeans for it to manage, and classes that aren't available locally can be downloaded from the network (this is covered in "The M-Let Class Loader"). Because resources, services and other connections may be added on-the-fly, this agent can participate in any management scheme.Of course, it is more efficient for the agent application to perform the initialization, including the creation of all MBeans that are known to be necessary. Typically, an agent application also needs to set up data structures or launch specific applications that its resources require. For example, it may establish a database session that an MBean will use to expose stored information. The agent application usually includes everything necessary for making the intended resources ready to be managed within the intended management solution.However, there is no single management solution. Many different agent applications could perform the same management function, requiring more or less intervention after they are launched. And the flexibility of the Java Dynamic Management Kit means that there are many different management solutions to achieve the same goal. For example, an MBean could also establish the database session itself during its registration phase (see "MBean Registration Control" in the JMX agent specification).The example code for the MinimalAgent application is located in the examplesDir/MinimalAgent directory. As we saw, this agent application only has minimal output and is intended to be accessed for management through one of its communications MBeans. However, you will need to compile and launch the minimal agent if you continue on to the next topic.Compile the MinimalAgent.java file in this directory with the javac command. For example, on the Solaris platform, you would type:$ cd examplesDir/MinimalAgent/ $ javac -classpath classpath *.javaWhen we access the minimal agent through the HTML adaptor, we will instantiate the SimpleStandard and SimpleDynamic classes. Since we don't use a dynamic class loader, the agent will need these classes at runtime. You will need to have compiled the standard and dynamic MBean classes as described in "Running the Standard MBean Example" and "Running the Dynamic MBean Example". To run the example, update your classpath to find the MBeans and launch the agent class:$ java -classpath classpath:../StandardMBean:../DynamicMBean MinimalAgentThis being a minimal agent, the example doesn't have much output. The MBean server is launched, and the three communication MBeans are created: it is now possible to connect to this agent. The HTTP and RMI connector servers communicate with connector clients in manager applications, see the applications in the examplesDir/SimpleClients directory.The simplest way to communicate with the agent is through the HTML protocol adaptor. This adaptor provides a view of the agent and its MBeans through standard HTML pages which can be viewed on almost any web browser. To connect to the agent, load the following URL in your browser:http://localhost:8082/If you get an error, you may have to switch off proxies in your preference settings or substitute your machine name for localhost. Any browser on your local network can also connect to this agent by using your machine name in this URL. In the next topic, "The HTML Protocol Adaptor", we will go into the details of managing this agent from its web view.Chapter 44. The HTML Protocol AdaptorThe HTML protocol adaptor provides a view of the agent and its registered MBeans through a basic interface on any web browser. It is the easiest way to access an agent since no further coding is necessary. For this reason, it can be useful for testing and debugging your MBeans in the minimal agent.In fact, we will use your browser to "manage" the minimal agent and its MBeans. The HTML protocol adaptor outputs HTML pages which represent the agent and its MBeans. The adaptor also interprets the commands sent back by the buttons and fields appearing in your browser. It then interacts with the agent's MBean server in order to get information about the MBeans that it has registered and operate on them. The HTML adaptor relies mostly on plain HTML. The only JavaScript that the generated pages contain are pop-up windows for displaying information. Browsers that are not JavaScript enabled might give an incompatibility message and won't be able to display the information. Otherwise, the generated pages contain no further scripting (JavaScript, Visual Basic or other), no frames and no images that might slow down loading.This topic relies on the minimal agent which you will need to launch first, as explained in "Running the Minimal Agent Example". Once you can connect to the HTML protocol adaptor in the minimal agent, you are ready to go through these topics:"The Agent View" is the main page for managing an agent through the HTML protocol adaptor"The MBean View" exposes an MBean's management interfaceThe "Agent Administration" lets you instantiate new MBeans"Instantiating and Managing MBeans" shows how to modify attributes and invoke operations"Filtering MBeans" is used to select the MBeans displayed in the agent viewThe first page displayed by the HTML adaptor is always the agent view. It originally contains a list of all registered MBeans. The following figure shows the agent view for the minimal agent. It contains four MBeans: the three communication MBeans, one of which is the HTML adaptor, and the MBean server delegate. The delegate is a special MBean covered in "The MBean Server Delegate".

Figure 4-1

The text field for filtering by object name lets you modify the list of displayed MBeans. The filter string is initially *:*, which gives all registered MBeans. Further use of the filter is covered in "Filtering MBeans". The agent's registered domain tells you the name of the default domain in this agent. The number of MBeans on this page is the count of those listed beneath the separator line. The "Admin" button is a link to the agent administration page which we will cover in "Agent Administration".The MBean list contains all MBeans whose object name matches the filter string. Object names can be filtered by their domain name and list of key-value pairs. In this list, MBeans are sorted and grouped by their domain name. Each MBean name listed is an active link to the page of the corresponding MBean view.After its initialization, the contents of an agent are dynamic: new MBeans may be created and registered into new or existing domains and old MBeans may be removed. These changes can also affect the functionality of the agent: new agent services may be registered (or removed) as well. We will demonstrate examples of dynamic management in "Instantiating and Managing MBeans".The MBean server delegate is an MBean that is automatically instantiated and registered by the MBean server when it is created. It provides information about the version of the Java Dynamic Management Kit which is running, and it represents the MBean server when sending notifications.Notifications are events sent by MBeans, they are covered by the JMX specification and the notification example in examplesDir/Notification. Since the MBean server instance is not an MBean object, it relies on its delegate MBean to send notifications. The MBean server delegate sends notifications to inform interested listeners about such events as MBean registrations and de-registrations.The exposed attributes of the delegate MBean provide vendor and version information about the MBean server. This can let a remote management application know which agent version is running and which version of the Java Runtime Environment it is using. The delegate MBean also provides a unique identification string for its MBean server.Click on the name of the delegate MBean to see its attributes. Version, vendor and identification information is listed in the table of attributes.Click on the Back to Agent View link or use your browser's Previous page function to return to the MBean list in the agent view.The MBean view has two functions: it presents the management interface of the MBean and it lets you interact with its instance. The management interface of an MBean is given through the name of the attributes, the operation signatures, and a self-description. You may interact with the MBean by reloading its attribute values, setting new values or invoking an operation. In the agent view, click on the object name of the HTML adaptor MBean: name=HTMLAdaptorServer in the default domain. This will bring up its MBean view.As shown in the following figure, the top part of the page contains the description of the MBean and some controls for managing it:

Figure 4-2

The first two lines give the object instance (object name and class name) for this MBean. The MBean name is the full object name of this MBean instance, including the domain. The key-property pairs may or may not identify the MBean to a human reader, depending on the agent developer's intention. The MBean Java class is the full class name for the Java object of which this MBean is an instance.The reload controls include a text field for entering a reload period and a manual "Reload" button. Originally, the reload period is set to zero indicating that the contents of the MBean view are not automatically refreshed. Clicking the reload button will force the page to reload, thereby updating all of the attribute values displayed. If you have entered a reload period, clicking the button will begin automatic reloading with the given period. The reload period must be at least five seconds. Enter a reload period of five and click the "Reload" button. Every five seconds the page will blink as it reloads.In another browser window, open another connection to the HTML adaptor at http://localhost:8082/. Observe the new values for the ActiveClientCount and LastConnectedClient attributes in the original window. Due to the way the adaptor works, you may have to try several connections before you see the attribute values change. The reload period is reset to zero every time you open an MBean view.The "Unregister" button is a shortcut for removing this MBean from the agent. Unregistering is covered in "Instantiating and Managing MBeans". The MBean description text provides some information about the MBean. Because standard MBeans are statically defined, they cannot describe themselves, and the MBean server provides a generic text. Dynamic MBeans are required to provide their own description string at runtime according to the JMX specification. Except for the class name, this is the only way to tell standard and dynamic MBeans apart in the MBean view. The second part of the MBean view is a table containing all attributes exposed by the MBean. For each attribute, this table lists its name, its Java type, its read-write access and a string representation of its current value.While MBean attributes may be of any type, not all types can be displayed in the MBean view. The HTML adaptor is limited to basic data types that can be displayed and entered as strings. For the complete list, see the Javadoc API of the HtmlAdaptorServer class. The table of attributes contains only those which can be displayed or entered as a string. Read-only attributes whose type support the toString method are also displayed.Attributes with array types are represented by a link to a page which displays the array values in a table. If the attribute is writeable, you may enter values for the array elements to set them. Attributes of type com.sun.jdmk.Enumerated or its sub-classes are displayed as a menu with a pop-up selection list.The name of each attribute is a link that pops up a dialog box containing the description for this attribute. Like the MBean description, attribute descriptions can only be provided by dynamic MBeans. The MBean server inserts a generic message for standard MBean attributes. The following figure shows the attributes of the HTML adaptor with a description of the Active attribute:

Figure 4-3

Click on the attribute names of the HTML adaptor to read their description. Since the HTML adaptor is implemented as a dynamic MBean, its attribute descriptions are meaningful.Note - Due to the use of JavaScript commands in the generated HTML, these pop-up windows might not be available on browsers that are not JavaScript-enabled.Writable attributes have a text field for entering new values. To set the value of a writable attribute, you would enter or replace its current value in the text field and click the "Apply" button at the bottom of the attributes table.You should not try to modify the attributes of the HTML protocol adaptor here, we will see why in "Instantiating and Managing MBeans". Because there is only one "Apply" button for all attributes, this button has a particular behavior: it systematically invokes the setter for all writeable attributes, whether or not their field has actually been modified. This may impact the MBean if setters have side effects, such as counting the number of modifications as in the SimpleStandard and SimpleDynamic examples given in Chapter 1, Standard MBeans and Chapter 2, Dynamic MBeans.The HTML adaptor detects attributes which are ObjectName types and provides a link to the MBean view of the corresponding MBean. This link is labeled view, and it is located just under the displayed value of the object name. Since MBeans often need to reference other MBeans, this provides a quick way of navigating through MBean hierarchies.The last part of the MBean view contains all of the operations exposed by the MBean. Each operation in the list is presented like a method signature: there is a return type, then a button with the operation name, and if applicable, a list of parameters, each with their type as well.As with the table of attributes, the list of operations contains only those involving types that can be represented as strings. The return type must support the toString method and the type of each parameter must be one of basic data types supported by the HTML adaptor. For the complete list, see the Javadoc API of the HtmlAdaptorServer class.Above each operation is a link to its description. Parameter names are also active links which pop up a window with a description text. Again, descriptions are only meaningful when provided by dynamic MBeans. The following figure shows some of the operations exposed by the HTML adaptor MBean and a description of the Start operation.

Figure 4-4

We will not invoke any operations on this MBean until a brief explanation in "Instantiating and Managing MBeans". If we stopped the HTML adaptor or blocked it with an error, there would no longer be any way to connect with a browser: we would have to stop the minimal agent and restart it. To invoke an operation, you would fill in any and all parameter values in the corresponding text fields and then click the operation's button. The HTML adaptor would then display a page with the result of the operation: the return value if successful or the reason the operation was unsuccessful. Go back to the agent view by clicking the link near the top of the MBean view page. Then click on the "Admin" button in the agent view to bring up the agent administration page in your browser window.The agent administration page contains a form for entering MBean information when creating or unregistering MBeans. You may also instantiate an MBean through one of its public constructors. In order to instantiate an MBean, its class must be available in the agent application's classpath. Optionally, you may specify a different class loader in the appropriate field if the agent contains other class loader MBeans.The first two fields, "Domain" and "Keys" are mandatory for all administrative actions. The "Domain" field initially contains the string representing the agent's default domain. Together, these fields define the object name, whether for a new MBean to be created or the name of an existing MBean to unregister. The "Java Class" is the full class name of the object to be instantiated as a new MBean. This field is ignored when unregistering an MBean. Using the drop-down menu, you may select one of three actions on this page: Create - Instantiates the given Java class of an MBean and registers the new instance in the MBean server. If successful, the MBean will then appear in the agent view. The class must have a public constructor without parameters in order to be created in this way.Unregister - Unregisters an MBean from the MBean server so that it is no longer available in the agent. The class instance is not explicitly deleted, though if no other references to it exist, it will be garbage collected.Constructors - Displays the list of public constructors at the bottom of the administration page for the given Java class. This lets you provide parameters to a specific constructor and create the MBean in this manner. This is the only way to create MBeans which do not have a no-parameter constructor.When you click the "Send Request" button, the HTML adaptor processes the action and updates the bottom of the page with the action results. You may have to scroll down to see the result. The text fields are not cleared after a request so that you can do multiple operations. The "Reset" button will return the fields to their last posted value after you have modified them. Sometimes, launching an MBean requires several steps: this is particularly the case for agent services which require some sort of configuration. For example, you can instantiate another HTML adaptor for connecting to a different port. Usually, this would be done programmatically in the agent application, but we need to do it through the browser for the minimal agent.On the agent administration page, fill in the fields as follows:Domain:CommunicationsKeys:protocol=html,port=8088Java Class:com.sun.jdmk.comm.HtmlAdaptorServerClass Loader:leave blankNote: In previous versions of product, specifying the port number in the object name would initialize communication MBeans. Starting with the Java Dynamic Management Kit 4.0, the names and contents of key properties no longer have any significance for any components of the product. We must set the port in other ways.Make sure the selected action is "Create" and send the request. If you scroll down the page, you should see if your request was successful.We can't connect to this HTML adaptor quite yet, we need to configure it first. Go to the new HTML adaptor's MBean view with the provided link. We couldn't modify any of the adaptor's attributes before because the implementation is designed so that they can't be modified while it is on-line. Our new HTML adaptor is instantiated in the stopped state (the StateString attribute indicates "OFFLINE"), so we can change its attributes. Set the Port attribute to "8088" and MaxActiveClientCount to "2", then click the "Apply" button. If the page is reloaded and the new values are displayed, the attribute write operation was successful. You may also click the attribute names to get an explanation for them. Scroll down the MBean view to the Start operation and click its button. This brings up a new page to tell us the operation was successful. If you go back to the MBean view with the provided link, you can see that the StateString is now indicating ONLINE.Now you should be able to access your minimal agent through a browser on port 8088. Try going to a different machine on the same network and connecting to the URL:http://agentHostName:8088/where agentHostName is the name or IP address of the machine where you launched the MinimalAgent. If you reload the MBean view of the new HTML adaptor on either browser, the name of this other machine should be the new value of the LastConnectedClient attribute. Through this other connection, you could stop, modify or remove the HTML adaptor MBean using port 8082. In that case, your original browser will have to use http://localhost:8088/ as well to connect. Instead, we will manage the minimal agent from this other machine.From the browser on the other machine, go to the administration page. Fill in the fields as follows and request the constructors:Domain:Standard_MBeansKeys:name=SimpleStandard,number=1Java Class:SimpleStandardClass Loader:leave blankThe list of constructors for the SimpleStandard class is given at the bottom of the page. The MBean name is also given: this is the object name that will be assigned to the MBean when using one of the listed constructors. As you can see, the SimpleStandard class only has one constructor that takes no parameters. Click on the "Create" button: the result will be appended to the bottom of the page. Scroll down and go to the MBean view with the provided link. Since it is a standard MBean, all of its description strings are generic: this shows the necessity of programming meaningful attribute names. In the agent view on the original browser window, click in the filter field and hit "Return" to refresh the agent view. Click on the new MBean's name and set its reload period to 15. Back on the other machine, type in a different string for the State attribute and click "Apply". On the original machine, you should see the MBean's attributes get updated when the MBean view is periodically reloaded. On the other machine, click the reset operation button at the bottom of the MBean view page. This brings up the operation result page which indicates the success of the operation.This page also gives the return value of the operation when it is not void. If you go back to the MBean view, you will see the result of the operation on the attributes. You should also see it on the original machine after it reloads. The browser on the other machine is no longer needed, and we can remove the HTML adaptor on port 8088.Go to the administration page and fill in the object name of the HTML adaptor we want to remove (you don't need its Java class to unregister it):Domain:CommunicationsKeys:protocol=html,port=8088Java Class:leave blankClass Loader:leave blankSelect "Unregister" from the drop down menu and click the "Send Request" button. The result then appears at the bottom of the page.You can also unregister an MBean directly from its MBean view: just click the "Unregister" button on the upper right hand-side of the page.Since an agent can manage hundreds of MBeans, the agent view provides a filtering mechanism for the list that is displayed. An object name with wildcard characters is used as the filter, and only those MBeans which match are counted and displayed.Go to the administration page, and create three more of the standard MBeans. Modify only the number value in their object name so that they are numbered sequentially. In the same way, create four dynamic MBeans starting with:Domain:Dynamic_MBeansKeys:name=SimpleDynamic,number=1Java Class:SimpleDynamicClass Loader:leave blankGo back to the agent view which should display all of the new MBeans.Filters restrict the set of MBeans listed in the agent view. This may not be particularly useful for our small agent, but it can help you find MBeans among hundreds in a complex agent. In addition, management applications use the same filter syntax when requesting an agent's MBeans through the programmatic interface of a connector. The filtering lets managers get either lists of MBean names or find a particular MBean instance.Filters are entered as partial object names with wild-card characters or as a full object name for which to search. Here are the basic substitution rules for filtering: You may search for partial domain names:the asterisk (*) stands for any number (including zero) of any characters;the question mark (?) stands for any one characterAn empty domain name stands for the default domain string;an empty key list is illegalKeys are atomic: you must search for the full property=value key, you may not search for a partial property name or an incomplete valueThe asterisk (*) may be used to terminate the key list, where it stands for any number of any keys (complete property-value pairs)You must match all keys exactly: use the form property=value,* to search for one key in names with multiple keysKeys are unordered when filtering: giving one or more keys (and an asterisk) finds all object names which contain that subset of keysEnter the following filter strings to see the resulting MBean list: Standard_MBeans:*Gives all of the standard MBeans we created*_MBeans:*Gives all of the standard and dynamic MBeans we created DefaultDomain:Not allowed by rule 2:*Lists all MBeans in the default domain*:name=Simple*,*Not allowed by rule 3*:name=SimpleStandardAllowed, but list is empty (rule 5)*:name=*Not allowed by rule 3*_??????:number=2,*Gives the second standard and dynamic MBean we created Communications:port=8088,protocol=htmlGives the one MBean matching the domain and both (unordered) keys empty stringallowed: special case equivalent to *:*Notice how the MBean count is updated with each filter: this count gives the number of MBeans that were found with the current filter, which is the number of MBeans appearing on the page. It is not the total number of MBeans in the agent, unless the filter is *:*.When you are ready to stop the minimal agent example, go to the window where you launched its class and type Control-C.Chapter 55. The Base AgentThe base agent demonstrates the programming details of writing an agent application. We will cover how to access the MBean server, ask it to create MBeans, and then interact with those MBeans. Everything that we could do through the HTML adaptor can be done through the code of your agent application.Interacting programmatically with the MBean server gives you more flexibility in your agent application. This topic covers the three main ways to create MBeans through the MBean server, how to interact with MBeans, and how to unregister them. The base agent is functionally equivalent to the minimal agent, but instead of writing the smallest agent, we will demonstrate good defensive programming with error checking. We will create the same three connectivity MBeans and do some of the same management operations that we did through the browser interface.The program listings in this tutorial show only functional code: comments and output statements have been modified or removed for space considerations. However, all management functionality has been retained for the various demonstrations. The complete source code is available in the BaseAgent and StandardMBean example directories located in the main examplesDir (see "Directories and Classpath" in the preface).Contents:"The Agent Application" shows how to launch the base agent programmatically"Creating an MBean (Method 1)" relies on the MBean server's register method after instantiating the MBean class ourselves"Creating an MBean (Method 2)" relies on the MBean server's create method to instantiate and register an MBean in one step"Creating an MBean (Method 3)" relies on the MBean server's instantiate and register methods"Managing MBeans" demonstrates the same management operations that we did through the HTML protocol adaptor"Filtering MBeans" shows how to get various lists of MBeans from the MBean server"Running the Base Agent Example" demonstrates its run-time behaviorThe base agent is a stand-alone application with a main method, but it also has a constructor so that it may be instantiated dynamically by another class.Example 5-1 public BaseAgent() { // Enable the TRACE level according to the level set in system properties try { Trace.parseTraceProperties(); } catch (IOException e) { e.printStackTrace(); System.exit(1); } println("\n\tInstantiating the MBean server of this agent..."); myMBeanServer = MBeanServerFactory.createMBeanServer(); // Retrieves ID of the MBean server from the delegate try { System.out.println("ID = "+ myMBeanServer.getAttribute( new ObjectName(ServiceName.DELEGATE), "MBeanServerId")); } catch (Exception e) { e.printStackTrace(); System.exit(1); } }In the first statement of the constructor, we enable tracing messages for the agent. The tracing lets us see internal information at runtime, which is useful for debugging. See "Setting Trace Messages" for specifying tracing parameters on the command line. Then we create the MBean server through its static factory class (see "The MBean Server Implementation and Factory"). Its reference is stored in a variable with class-wide scope so that all internal methods have access to the MBean server. Finally, we retrieve the MBean server identification string, for informational purposes only.After the MBean server is initialized, we are going to create the same three communications MBeans that we saw in the minimal agent.The methods of the MBean server let you create an MBean in three different ways. The base agent demonstrates all three ways, and we will discuss the advantages of each.One way of creating an MBean consists of first instantiating its class and then registering this instance in the MBean server. Registration is the internal process of the MBean server which takes a manageable resource's MBean instance and exposes it for management.Bold text in this and the following code samples highlights the important statements that vary between the three methods.Example 5-2 // instantiate the HTML protocol adaptor object to use the default port HtmlAdaptorServer htmlAdaptor = new HtmlAdaptorServer(); try { // We know that the HTML adaptor provides a default object name ObjectInstance htmlAdaptorInstance = myMBeanServer.registerMBean(htmlAdaptor, null); println("CLASS NAME = " + htmlAdaptorInstance.getClassName()); println("OBJECT NAME = " + htmlAdaptorInstance.getObjectName().toString()); } catch(Exception e) { e.printStackTrace(); System.exit(0); } // Now we need to explicitly start the html protocol adaptor htmlAdaptor.start(); while (htmlAdaptor.getState() == CommunicatorServer.STARTING) { sleep(1000); } println("STATE = " + htmlAdaptor.getStateString()); [...]In this first case, we instantiate the HtmlAdaptorServer class and keep a reference to this object. We then pass it to the registerMBean method of the MBean server to make our instance manageable in the agent. During the registration, the instance can also obtain a reference to the MBean server, something it requires to function as a protocol adaptor.In the minimal agent, we saw that the HTML adaptor gives itself a default name in the default domain. Its Javadoc API confirms this, so we can safely let it provide a default name. We print the object name in the object instance returned by the registration to confirm that the default was used.Once the MBean is registered, we can perform management operations on it. Because we kept a reference to the instance, we don't need to go through the MBean server to manage this MBean. This lets us call the start and getStateString methods directly. The fact that these methods are publicly exposed is particular to the implementation: the HTML adaptor is a dynamic MBean, so without any prior knowledge of the class, we would have to go through its DynamicMBean interface.In a standard MBean you would directly call the implementation of its management interface. Since the HTML adaptor is a dynamic MBean, the start method is just a shortcut for the start operation. For example, we could start the adaptor and get its StateString attribute with the following calls:htmlAdaptor.invoke("start", new Object[0], new String[0]); println("STATE = " + (String)htmlAdaptor.getAttribute("StateString"));This type of shortcut is not specified by the Java Management extensions, nor is its functionality necessarily identical to that of the start operation exposed for management. In the case of the HTML adaptor, its Javadoc API confirms that it is identical, and in other cases, it is up to the MBean programmer to guarantee this functionality if it is offered.The second way to create an MBean is the single createMBean method of the MBean server. In this case, the MBean server instantiates the class and registers it all at once. As a result, the caller never has a direct reference to the new object.Example 5-3 ObjectInstance httpConnectorInstance = null; try { String httpConnectorClassName = "com.sun.jdmk.comm.HttpConnectorServer"; // Let the HTTP connector server provides its default name httpConnectorInstance = myMBeanServer.createMBean(httpConnectorClassName, null); } catch(Exception e) { e.printStackTrace(); System.exit(0); } // We need the object name to refer to our MBean ObjectName httpConnectorName = httpConnectorInstance.getObjectName(); println("CLASS NAME = " + httpConnectorInstance.getClassName()); println("OBJECT NAME = " + httpConnectorName.toString()); // Now we demonstrate the bulk getter of the MBean server try { String att1 = "Protocol"; String att2 = "Port"; String attNames[]= {att1, att2}; AttributeList attList = myMBeanServer.getAttributes(httpConnectorName, attNames); Iterator attValues = attList.iterator(); println(att1 + "\t=" + ((Attribute) attValues.next()).getValue()); println(att2 + "\t=" + ((Attribute) attValues.next()).getValue()); } catch (Exception e) { e.printStackTrace(); System.exit(0); } // Now we explicitly start the HTTP connector server try { myMBeanServer.invoke(httpConnectorName, "start", new Object[0], new String[0]); // waiting to leave starting state... while (new Integer(CommunicatorServer.STARTING).equals (myMBeanServer.getAttribute(httpConnectorName,"State"))) { sleep(1000); } println("STATE = " + myMBeanServer.getAttribute(httpConnectorName, "StateString")); } catch (Exception e) { e.printStackTrace(); System.exit(0); } [...]The advantage of this method for creating MBeans is that the instantiation and registration are done in one call. In addition, if we have registered any class loaders in the MBean server, they will automatically be used if the class is not available locally. See "The M-Let Class Loader" for more information on class loading.The createMBean method has several forms, some with parameters for class constructors and some without. In this examples we don't give any parameters for the constructor because we wish to use the default constructor that takes no arguments. If your MBean class has no default constructor, you must use a form that allows you to pass parameters to a constructor.The major difference is that we no longer have a reference to our MBean instance. The object instance that was only used for display purposes in the previous example now gives us the only reference we have on the MBean: its object name.What can be seen as a drawback of this method is that all management of the new MBean must now be done through the MBean server. For the attributes of the MBean, we need to call the generic getter and setter of the MBean server, and for the operations we need to call the invoke method. When the agent needs to access the MBean, having to go through the MBean server adds some complexity to the code. It does have the advantage of not relying on any shortcuts provided by the MBean, making the code more portable and reusable.However, the createMBean method is ideal for quickly launching new MBeans that the agent application doesn't need to manipulate. In just one call, the new objects are instantiated and exposed for management.The last way of creating an MBean relies on the instantiate method of the MBean server. In addition, we use a non-default constructor to instantiate the class with a different behavior.Example 5-4 CommunicatorServer rmiConnector = null; Object[] params = {new Integer(8086)}; String[] signature = {new String("int")}; try { String RmiConnectorClassName = "com.sun.jdmk.comm.RmiConnectorServer"; // specify the RMI port number to use as a parameter to the constructor rmiConnector = (CommunicatorServer)myMBeanServer.instantiate( RmiConnectorClassName, params, signature); } catch(Exception e) { e.printStackTrace(); System.exit(0); } try { // Let the RMI connector server provides its default name ObjectInstance rmiConnectorInstance = myMBeanServer.registerMBean(rmiConnector, null); // Confirm the class and default object name println("CLASS NAME = " + rmiConnectorInstance.getClassName()); println("OBJECT NAME = " + rmiConnectorInstance.getObjectName().toString()); } catch(Exception e) { e.printStackTrace(); System.exit(0); } // Now we explicitly start the RMI connector server rmiConnector.start(); // waiting to leave starting state... while (rmiConnector.getState() == CommunicatorServer.STARTING) { sleep(1000); } println("STATE = " + rmiConnector.getStateString()); // Check that the RMI connector server is started if (rmiConnector.getState() != CommunicatorServer.ONLINE) { println("Cannot start the RMI connector server"); System.exit(0); } [...]As in the first example of MBean creation, we instantiate and register the MBean in separate steps. First, we instantiate the class using the instantiate method of the MBean server. This method lets you specify the constructor you wish to use when instantiating. Note that we could also have specified a constructor to the createMBean method in the previous example.To specify a constructor, you give an array of objects for the parameters and an array of strings which defines the signature. If these arrays are empty or null, the MBean server will try to use the default no-parameter constructor. If the class does not have a default constructor, you must specify the parameters and signature of a valid, public constructor.In our case, we specify an integer parameter to set the port through one of the constructors of the RmiConnectorServer class. Then, we register the MBean with the registerMBean method of the MBean server, as in the first example.The advantage of this creation method is that the instantiate method of the MBean server also supports class loaders. If any are registered in the MBean server, they will automatically be used if the class is not available locally. See "The M-Let Class Loader" for more information on class loading.Since we don't take advantage of the class loaders here, we could have just called the class' constructor directly. The main advantage is that, like the first method of MBean creation, we retain a direct reference to the new object. The direct reference lets us again use the MBean's shortcut methods explicitly.There are other combinations of instantiating and registering MBeans for achieving the same result. For example, we could use the default constructor and then set the port attribute of the MBean before starting it. Other combinations are left as an exercise to the reader.In "Creating an MBean (Method 2)", we rely totally on the MBean server to create and access an MBean. The code example in that section demonstrates how to get attributes and invoke operations through the MBean server. Here we will concentrate on the usage of MBean descriptor classes when accessing MBeans representing resources.We will rely on the StandardAgent and DynamicAgent classes presented in Chapter 1, Standard MBeans and Chapter 2, Dynamic MBeans. As mentioned in "Comparison with the SimpleStandard Example", the two are nearly identical. We examine the MBean descriptor method that is common to both: the same code works for any registered MBean, whether standard or dynamic.Example 5-5 private MBeanServer server = null; // assigned by MBeanServerFactory private void printMBeanInfo(ObjectName name) { println("Getting the management information for " + name.toString() ); MBeanInfo info = null; try { info = server.getMBeanInfo(name); } catch (Exception e) { e.printStackTrace(); return; } println("\nCLASSNAME: \t"+ info.getClassName()); println("\nDESCRIPTION: \t"+ info.getDescription()); println("\nATTRIBUTES"); MBeanAttributeInfo[] attrInfo = info.getAttributes(); if (attrInfo.length>0) { for(int i=0; i<attrInfo.length; i++) { println(" ** NAME: \t"+ attrInfo[i].getName()); println(" DESCR: \t"+ attrInfo[i].getDescription()); println(" TYPE: \t"+ attrInfo[i].getType() + "\tREAD: "+ attrInfo[i].isReadable() + "\tWRITE: "+ attrInfo[i].isWritable()); } } else println(" ** No attributes **"); println("\nCONSTRUCTORS"); MBeanConstructorInfo[] constrInfo = info.getConstructors(); // Note: the class necessarily has at least one constructor for(int i=0; i<constrInfo.length; i++) { println(" ** NAME: \t"+ constrInfo[i].getName()); println(" DESCR: \t"+ constrInfo[i].getDescription()); println(" PARAM: \t"+ constrInfo[i].getSignature().length + " parameter(s)"); } println("\nOPERATIONS"); MBeanOperationInfo[] opInfo = info.getOperations(); if (opInfo.length>0) { for(int i=0; i<constrInfo.length; i++) { println(" ** NAME: \t"+ opInfo[i].getName()); println(" DESCR: \t"+ opInfo[i].getDescription()); println(" PARAM: \t"+ opInfo[i].getSignature().length + " parameter(s)"); } } else println(" ** No operations ** "); println("\nNOTIFICATIONS"); MBeanNotificationInfo[] notifInfo = info.getNotifications(); if (notifInfo.length>0) { for(int i=0; i<constrInfo.length; i++) { println(" ** NAME: \t"+ notifInfo[i].getName()); println(" DESCR: \t"+ notifInfo[i].getDescription()); } } else println(" ** No notifications **"); } The getMBeanInfo method of the MBean server gets the descriptor of an MBean's management interface and hides the MBean's implementation. This method returns an MBeanInfo object which contains the MBean's description. We can also get the lists of attributes, operations, constructors, and notifications to display their descriptions. Recall that the dynamic MBean provides its own meaningful descriptions and that those of the standard MBean are default strings provided by the introspection mechanism of the MBean server.The base agent does very little filtering because it does very little management. Usually, filters are applied programmatically in order to get a list of MBeans to which some operations will apply. There are no management operations in the MBean server which apply to a list of MBeans: you must loop through your list and apply the desired operation to each MBean. Before exiting the agent application, we do a query of all MBeans so that we can unregister them properly. MBeans should be unregistered before being destroyed since they may need to perform some actions before or after being unregistered. See "MBean Registration Control" in the JMX agent specification for more information.Example 5-6 public void removeAllMBeans() { try { Set allMBeans = myMBeanServer.queryNames(null, null); for (Iterator i = allMBeans.iterator(); i.hasNext();) { ObjectName name = (ObjectName) i.next(); // Don't unregister the MBean server delegate if ( ! name.toString().equals( ServiceName.DELEGATE ) ) { println("Unregistering " + name.toString() ); myMBeanServer.unregisterMBean(name); } } } catch (Exception e) { e.printStackTrace(); System.exit(0); } }We use the queryNames method because we only need the object names to operate on MBeans. The null object name as a filter gives us all MBeans in the MBean server. We then iterate through the resulting set and unregister each one, except for the MBean server delegate. As described in "The MBean Server Delegate", the delegate is also an MBean and so it will be returned by the query. However, if we unregister it, the MBean server can no longer function and remove the rest of our MBeans.We recognized the delegate by its standard name which is given by the static field ServiceName.DELEGATE. The ServiceName class provides standard names and other default properties for communications and service MBeans. It also provides the version strings that are exposed by the delegate MBean. Note that, since the delegate is the only MBean created directly by the MBean server, it is the only one whose name cannot be overridden during its registration. This is why the delegate always has the same object name, and we are always sure to detect it.The examplesDir/BaseAgent/ directory contains the source file of the BaseAgent application. Compile the BaseAgent.java file in this directory with the javac command. For example, on the Solaris platform, you would type:$ cd examplesDir/BaseAgent/ $ javac -classpath classpath *.javaAgain, we don't need the MBean classes at compile time, but they will be needed at run-time, since we don't use a dynamic class loader. You will need to have compiled the standard and dynamic MBean classes as described in "Running the Standard MBean Example" and "Running the Dynamic MBean Example". If you wish to load any other class in the base agent, you must include its directory or jar file in the classpath. To run the example, update your classpath to find the MBeans and launch the agent class:$ java -classpath classpath:../StandardMBean:../DynamicMBean BaseAgentSince the base agent enables internal tracing (see Example 5-1), you can also set the trace level and trace output on the command line. The tracing mechanism is covered in the Java Dynamic Management Kit 4.0 Tools Reference guide and in the Javadoc API of the Trace class. The simplest way to get the default tracing is to specify the filename for a trace log on the java command line:$ java -classpath classpath -DTRACE_OUTPUT=filename BaseAgentBesides any trace information, this agent displays output for the three types of MBean creation.When the connection MBeans have been created, it is possible to connect to the agent through one of the protocols. If you connect to the base agent through the HTML adaptor, you could go through the same procedures as with the minimal agent.When you are done, type "Enter" to remove all MBeans from the agent and exit the agent application.Chapter 66. The M-Let Class LoaderThe "Dynamic" in Java Dynamic Management Kit not only stands for dynamic loading, it also stands for dynamic downloading. The agent service that provides this functionality is the m-let class loader. M-let stands for management applet, an HTML-style tag that tells the class loader how to retrieve the desired class. Using this information, the m-let loader can retrieve an MBean class from a remote location given as a URL (uniform resource locator) and create it in the agent.The m-let resides in a separate text file which acts as a loading manifest. The contents of the m-let file let you specify any number of classes to load, possibly a different source for each, arguments for the class constructor, and the object name for the instantiated MBean. Since this mechanism is sometimes too heavy, the m-let loader can also be used to load classes directly and create MBeans in the agent.The m-let loader is a service implemented as an MBean, so it can be called either directly by the agent or remotely by a management application. It can also be managed remotely, which allows a manager to effectively "push" MBeans to an agent: the manager instantiates the m-let loader in an agent and instructs it to load classes from a predetermined location.Class loading is significantly different between Java 2 and JDK 1.1.x, and this leads to different implementations of the m-let loader. We cover these in separate sections. The example code in the MLetAgent and MLetClient directories of the main examplesDir corresponds to the Java version which you specified during installation (see "Directories and Classpath" in the preface).Contents:"The M-Let Loader (JDK 1.1)""M-Let Loading from a Manager (JDK1.1)""The M-Let Loader (Java 2)""M-Let Loading from a Manager (Java 2)"In an agent application, we might need to load MBeans from remote hosts during the initialization. Or we might have local threads which need to load MBeans in the agent. In this example we demonstrate how to create the m-let loader service and use it to dynamically load new MBean classes.In an installation of the Java Dynamic Management Kit for the JDK 1.1.x, the m-let loader is the MLetSrv class in the javax.management.loading package. It is an MBean which needs to be registered in the MBean server before we can use it to load classes.Example 6-1 MBeanServer server = MBeanServerFactory.createMBeanServer(); // Get the domain name from the MBeanServer. String domain = server.getDefaultDomain(); // Create a new MLetSrv MBean and add it to the MBeanServer. String mletClass = "javax.management.loading.MLetSrv"; ObjectName mletName = new ObjectName(domain + ":name=" + mletClass); server.createMBean(mletClass, mletName);There is no special initialization that needs to be done for the m-let loader.In order to download an MBean, we must first have its corresponding m-let definition in an HTML file. In our example, we define the following file with three MLET tags:Example 6-2 <HTML> <MLET CODE=Square.class ARCHIVE=Square.jar NAME=MLetExample:name=Square,id=1 > <ARG TYPE=java.lang.Integer VALUE=10> </MLET> <MLET CODE=EquilateralTriangle.class ARCHIVE=EquilateralTriangle.jar NAME=MLetExample:name=EquilateralTriangle,id=1 > <ARG TYPE=java.lang.Integer VALUE=8> </MLET> <MLET CODE=EquilateralTriangle.class ARCHIVE=EquilateralTriangle.jar NAME=MLetExample:name=EquilateralTriangle,id=2 > <ARG TYPE=java.lang.Integer VALUE=15> </MLET> </HTML>This file tells the m-let loader to create three MBeans with the given object names, using the given classes in the jar files. The ARG tag gives a parameter to be passed to the class' constructor. The number and type of ARG tags specified must match one of the public constructors for the classThe jar files must be located in the same directory as this file, regardless of whether the directory is on a local or remote host. The MLET tag may also specify a CODEBASE, which is an alternate location for the jar file. This m-let loader relies on the definition of MLET tag given by the JMX specification.Now we are ready to call the performLoadURL method of our m-let loader. In parsing the result vector, we use our knowledge of the class names that we wrote in the m-let file.Example 6-3 ObjectName squareMLetClassLoader = null; ObjectName triangleMLetClassLoader = null; // The url string is read from the command line Object mletParams[] = {url}; String mletSignature[] = {"java.lang.String"}; Vector mbeanList = (Vector) server.invoke( mletName, "performLoadURL", mletParams, mletSignature); for (Enumeration enum = mbeanList.elements(); enum.hasMoreElements(); ) { Object element = enum.nextElement(); if (element instanceof Vector) { // Success, we retrieve the new object name Vector v = (Vector) element; ObjectInstance objectInstance = (ObjectInstance) v.elementAt(0); ObjectName classLoaderObjectName = (ObjectName) v.elementAt(1); if (objectInstance.getClassName().equals("Square")) { // Retrieve MBean that loaded the class Square squareMLetClassLoader = classLoaderObjectName; } else if (objectInstance.getClassName().equals( "EquilateralTriangle")) { // Retrieve MBean that loaded the class EquilateralTriangle triangleMLetClassLoader = classLoaderObjectName; } println("\tOBJECT NAME = " + objectInstance.getObjectName()); } else { // Failure, find out why println("\tEXCEPTION = " + ((Throwable)element).getMessage()); } }The result of the call to performLoadURL is a Vector object containing as many elements as there are MLET tags in the file designated by the URL. Each element is either a vector containing the object instance of the new MBean and the object name of its class loader, or a Throwable object containing the exception or error that prevented the MBean from being loaded. The order of the elements may differ from the order of the tags in the file.In the result, we obtain the object name of the MBeans that were created from the downloaded classes. The management architecture specified by JMX is designed so that objects are manipulated through the MBean server, not by direct reference. Therefore, downloaded classes are directly registered in the MBean server by the m-let loader, and the caller never receives a direct reference to the new object.The object names of the class loaders are references to the internal class loader objects used by the m-let service to actually fetch the classes. We save them because they can be used if we ever need to instantiate these classes again. We will see how in the next section.Loading MBeans from a URL requires some preparation and additional files. In some cases, we don't have the ability to create files ahead of time or modify them when we need different classes. In these cases, we would just like to load a class from a jar file and create its MBean.The MLetSrv is not a class loader, we only ask it to load a class from a URL and it instantiates its private class loader for doing this. Even though the internal class loader object used by the m-let loader is a public type, it should not be instantiated to act as a class loader. The m-let loader stores internal information about its private class loaders, and it won't be able to handle one outside of its control.Instead, use the class loader name that is returned when an MBean is successfully loaded. You can specify this class loader name when creating a class through the MBean server. You will be able to create new MBeans from the same class or from other classes in the associated archive (jar file).This implies that you must first call the performLoadURL with a known URL and a known m-let file. The m-let loader will create one class loader for each code-base specified in the file, and one for the code-base of the file itself. For example, the class loader name returned with the "Square" MBean name is the one used to load its class from the Square.jar file in the same directory as the HTML file. We can create other instances of that MBean now just through the MBean server, without needing to call the m-let loader.The following code sample uses the object name references that were declared and assigned in Example 6-3.Example 6-4 // Create a new Square MBean from its class in the Square.jar file String squareClass = "Square"; ObjectName squareName = new ObjectName( "MLetExample:name=" + squareClass + ",id=2"); Object squareParams[] = {new Integer(12)}; String squareSignature[] = {"java.lang.Integer"}; server.createMBean(squareClass, squareName, squareMLetClassLoader, squareParams, squareSignature); // Create a new EquilateralTriangle MBean from its class in the // EquilateralTriangle.jar file String triangleClass = "EquilateralTriangle"; ObjectName triangleName = new ObjectName( "MLetExample:name=" + triangleClass + ",id=3"); Object triangleParams[] = {new Integer(20)}; String triangleSignature[] = {"java.lang.Integer"}; server.createMBean(triangleClass, triangleName, triangleMLetClassLoader, triangleParams, triangleSignature);To run the m-let agent example for the JDK 1.1.x, you must have installed the Java Dynamic Management Kit for 1.1, and set your classpath accordingly. This example is located in the examplesDir/MLetAgent/ directory, see "Directories and Classpath" in the preface for details.In our example, we have two MBeans representing geometrical shapes. Before running the example, we compile them and create a jar file for each. We also compile the agent application at the same time.$ cd examplesDir/MLetAgent/ $ javac -classpath classpath *.java $ jar cf Square.jar Square.class SquareMBean.class $ rm Square.class SquareMBean.class $ jar cf EquilateralTriangle.jar EquilateralTriangle.class \ EquilateralTriangleMBean.class $ rm EquilateralTriangle.class EquilateralTriangleMBean.classSince the MBean classes are only found in the jar files now, they cannot be found in our usual classpath, even if it includes the current directory (.). However, these jar files are given as the archive in the MLET tags of the HTML file, so the m-let loader should find them.The agent requires you to specify the URL of the m-let file on command line. We have left this file in the examples directory, but you could place it and the jar files on a remote machine. With the Korn shell on the Solaris platform, you would type the following command:$ java -classpath classpath Agent file:${PWD}/GeometricShapes.htmlIn the output of the agent, you can see it create the m-let service MBean, and then load the HTML file which specifies the three MBeans to be loaded. Once these have been loaded, we can see the two MBeans that were loaded directly through the class loader shortcut.This agent uses the tracing mechanism, and you can select to receive the messages from the m-let loader by specifying the -DINFO_MLET property on the command line. The tracing mechanism is covered in the Java Dynamic Management Kit 4.0 Tools Reference guide and in the Javadoc API of the Trace class.The agent then launches an HTML adaptor so that we can easily view the new MBeans. In them we can see that the values contained in the ARG tags of the m-let file were used to initialize the MBeans. Point your web browser to the following URL and click on the MBeans in the MLetExample domain:http://localhost:8082/. When you are done, type "Control-C" in the window where you launched the agent.Like the other agent services of the Java Dynamic Management Kit, the m-let loader is an MBean and fully manageable from a remote manager. A manager application might want an agent to load a new MBean to represent a new resource or provide a new management service. In this example, we show a manager which interacts with the m-let loader of an agent to load exactly the same MBeans as in the previous example.The agent that we will manage only contains an RMI connector and an HTML adaptor when it is launched. We will use the RMI connector to access the agent and perform all of our management operations. You can then view the new MBeans through the HTML adaptor.The manager is just a simple application which creates its connector client, does its management operations and exits. Here is the code of its main method and the constructor that it calls.Example 6-5 public Client() { // Enable the trace mechanism [...] // Connect a new RMI connector client to the agent connectorClient = new RmiConnectorClient(); // Use the default address (localhost) RmiConnectorAddress address = new RmiConnectorAddress(); try { connectorClient.connect(address); } catch (Exception e) { println("Could not connect to the agent!"); e.printStackTrace(); System.exit(1); } } public static void main(String[] args) { // Parse command line arguments. [...] // Call the constructor to establish the connection Client client = new Client(); // Run the MLet example (see below) client.runMLetExample(); // Disconnect connector client from the connector server. client.connectorClient.disconnect(); System.exit(0); }Now that the manager is connected to the client, we can "push" classes to it. We do this by first creating an m-let loader service, then having that loader create MBeans from the classes designated by our HTML file. The following code is taken from manager's runMLetExample method. The code is identical to the code of the agent example, except that we now go through the RemoteMBeanServer interface of the connector client instead of directly through the MBean server.Example 6-6 // Get the domain name from the Agent String domain = connectorClient.getDefaultDomain(); // Create a new MLetSrv MBean and add it to the Agent String mletClass = "javax.management.loading.MLetSrv"; ObjectName mletName = new ObjectName(domain + ":name=" + mletClass); connectorClient.createMBean(mletClass, mletName); [...] // Create and register new Square and EquilateralTriangle MBeans // by means of an HTML document containing MLET tags // The url string is read from the command line ObjectName squareMLetClassLoader = null; ObjectName triangleMLetClassLoader = null; Object mletParams[] = {url}; String mletSignature[] = {"java.lang.String"}; Vector mbeanList = (Vector) connectorClient.invoke( mletName, "performLoadURL", mletParams, mletSignature); for (Enumeration enum = mbeanList.elements(); enum.hasMoreElements(); ) { Object element = enum.nextElement(); if (element instanceof Vector) { // Success, we retrieve the new object name Vector v = (Vector) element; ObjectInstance objectInstance = (ObjectInstance) v.elementAt(0); ObjectName classLoaderObjectName = (ObjectName) v.elementAt(1); if (objectInstance.getClassName().equals("Square")) { // Retrieve the MBean that loaded the Square squareMLetClassLoader = classLoaderObjectName; } else if (objectInstance.getClassName().equals( "EquilateralTriangle")) { // Retrieve the MBean that loaded the EquilateralTriangle triangleMLetClassLoader = classLoaderObjectName; } println("\tOBJECT NAME = " + objectInstance.getObjectName()); } else { // Failure, find out why println("\tEXCEPTION = " + ((Throwable)element).getMessage()); } }As in the agent application, we may need a shortcut for instantiating other MBeans without specifying an m-let file. Again, we can use an existing class loader from a previously loaded class to download the same classes again. We use the createMBean method of the connector client which lets us specify a class loader name. The following code is the rest of the manager's runMLetExample method, and it is also nearly identical to the agent's code.Example 6-7 // Create a new Square MBean from its class in the Square.jar file. String squareClass = "Square"; ObjectName squareName = new ObjectName( "MLetExample:name=" + squareClass + ",id=2"); Object squareParams[] = {new Integer(12)}; String squareSignature[] = {"java.lang.Integer"}; connectorClient.createMBean(squareClass, squareName, squareMLetClassLoader, squareParams, squareSignature); // Create a new EquilateralTriangle MBean from its class in the // EquilateralTriangle.jar file. String triangleClass = "EquilateralTriangle"; ObjectName triangleName = new ObjectName( "MLetExample:name=" + triangleClass + ",id=3"); Object triangleParams[] = {new Integer(20)}; String triangleSignature[] = {"java.lang.Integer"}; connectorClient.createMBean(triangleClass, triangleName, triangleMLetClassLoader, triangleParams, triangleSignature);Simulating a "push" of the MBeans in this way is plausible, since the management application can specify a URL where it controls the contents of the HTML file and knows which classes are available.The MBeans in the agent and manager (client) examples are identical, and we will set up the example in exactly the same manner.$ cd examplesDir/MLetClient/ $ javac -classpath classpath *.java $ jar cf Square.jar Square.class SquareMBean.class $ rm Square.class SquareMBean.class $ jar cf EquilateralTriangle.jar EquilateralTriangle.class \ EquilateralTriangleMBean.class $ rm EquilateralTriangle.class EquilateralTriangleMBean.classThe manager is written to be run on the same host as the agent application. If you wish to run it on a different host, you will need to modify the code for the Client class constructor where the agent address is specified (see Example 6-5). You could place the jar files and the m-let file on a remote machine and specify its new URL as the parameter to the manager application; we run the example with this file in the current directory.Before launching the manager, you must launch the agent. Here we give commands for launching the applications from the same terminal window running the Korn shell. On the Windows NT platform, you will have to launch each application in a separate window.$ java -classpath classpath Agent & $ java -classpath classpath Client file:${PWD}/GeometricShapes.htmlIn the output of the manager, you can see it create the m-let service MBean, and then ask it to load the HTML file. Finally, we can see the two MBeans that were loaded directly through the class loader shortcut. If you connect to the agent in a web browser at the following URL: http://localhost:8082/ and reload its agent view every time the manager pauses, you can see the MBeans as they are created.The agent terminates after it disconnects its connector client. When you are done viewing the agent, type the following commands to stop the agent application:$ fg java [...] Agent <Control-C> ^C$ In the version of the Java Dynamic Management Kit for Java 2, the m-let loader is itself a class loader object. It extends the URLClassLoader class of the java.net package to simplify the downloading service it provides.The m-let loader service is an instance of the MLet class in the javax.management.loading package. It is also an MBean that can be accessed remotely. It provides m-let file loading and the shortcut method seen in the version for the JDK 1.1. In addition, it inherits the behavior which lets it be used directly as a class loader, without requiring an m-let file.We will start by demonstrating the usage of the m-let service as it would be used in an agent or in an MBean. In our example, the agent application creates an MBean server and then the m-let loader.Example 6-8 // Parse debug properties and command line arguments. [...] // Instantiate the MBean server MBeanServer server = MBeanServerFactory.createMBeanServer(); String domain = server.getDefaultDomain(); // Create a new MLet MBean and add it to the MBeanServer. String mletClass = "javax.management.loading.MLet"; ObjectName mletName = new ObjectName(domain + ":name=" + mletClass); server.createMBean(mletClass, mletName);There is no special initialization that needs to be done before loading classes through an m-let file.In this example we will only load EquilateralTriangle MBeans through the m-let file. We use the same m-let file which is shown in Example 6-2, but without the tags for the Square MBeans.The code for downloading the MBeans specified in the m-let file is also similar. In the Java 2 version of the m-let loader, only the name of the method to call and the format of its return value is different. In this code we call the getMBeansFromURL method and analyze the result:Example 6-9 // the url_2 string is read from the command line println("\tURL = " + url_2); Object mletParams_2[] = {url_2}; String mletSignature_2[] = {"java.lang.String"}; Set mbeanSet = (Set) server.invoke(mletName, "getMBeansFromURL", mletParams_2, mletSignature_2); for (Iterator i = mbeanSet.iterator(); i.hasNext(); ) { Object element = i.next(); if (element instanceof ObjectInstance) { // Success, we display the new MBean's name println("\tOBJECT NAME = " + ((ObjectInstance)element).getObjectName()); } else { // Failure, we display why println("\tEXCEPTION = " + ((Throwable)element).getMessage()); } }The structure of the returned set is much simpler than in the case of the JDK 1.1 loader. In the JDK 1.1 version, the m-let loader handles separate class loader objects, one for each code-base it has accessed. In the Java 2 version, the m-let loader is the class loader, and it handles just a list of code-bases that it has accessed directly. You can view this list by calling the getURLs method of the m-let loader MBean.This behavior means that the getMBeansFromURL method does not need to return the object names of class loaders it has used. Instead it just returns either the object instance of the downloaded and registered MBean or a Throwable object in case or an error or an exception. These are returned in a Set object containing as many elements as there are MLET tags in the target m-let file.This behavior also simplifies any repeated loading of the classes after they have been loaded from an m-let file. Because the m-let loader has already used the code-base of the MBean, it is available to be used again. All you need to do is specify the object name of the m-let loader as the class loader when creating the MBean.You can also load other MBeans in the same code-base, once the code-base has been accessed by a call to the getMBeansFromURL method. In our example we will just download another MBean of the EquilateralTriangle class.Example 6-10 // Create another EquilateralTriangle MBean from its class // in the EquilateralTriangle.jar file. String triangleClass = "EquilateralTriangle"; ObjectName triangleName = new ObjectName( "MLetExample:name=" + triangleClass + ",id=3"); Object triangleParams[] = {new Integer(20)}; String triangleSignature[] = {"java.lang.Integer"}; server.createMBean(triangleClass, triangleName, mletName, triangleParams, triangleSignature);Since the m-let loader object is a class loader, you can use it to load classes directly, without needing to define an m-let file. This is the main advantage of the Java 2 version of the m-let loader service.Before you can load an MBean directly, you need to add the URL of its code-base to the m-let loader's internal list. Then we just use the m-let loader's object name as the class loader name when creating the MBean. Here is the code to do this in the agent example:Example 6-11 // Add a new URL to the MLet class loader // The url_1 string is read from the command line Object mletParams_1[] = {url_1}; String mletSignature_1[] = {"java.lang.String"}; server.invoke(mletName, "addURL", mletParams_1, mletSignature_1); // Create a Square MBean from its class in the Square.jar file. String squareClass = "Square"; ObjectName squareName = new ObjectName( "MLetExample:name=" + squareClass); Object squareParams[] = {new Integer(10)}; String squareSignature[] = {"java.lang.Integer"}; server.createMBean(squareClass, squareName, mletName, squareParams, squareSignature);You only need to add the URL to the m-let loader the first time you want to download a class. Once it is added, we can load it as many times as necessary by calling createMBean directly.Since this loading mechanism doesn't use the MLET tag, the programmer must insure that either the downloaded class provides its own object name or, as in the example above, the agent provides one.The fact that the m-let loader is also a class loader into which you can load multiple URLs brings up the issue of name spaces. If there exists two classes with the same name within the code-bases defined by the set of all URLs, the m-let loader will load one of them non-deterministically. In order to specify one of them precisely, you shouldn't add the URL of the second code-base to the m-let loader. Instead, you will have to create a second m-let loader MBean to which you can add the URL for the second version of the class. In this case, you will have one m-let MBean that can load one version of the class and another m-let MBean that can load the other.To run the m-let agent example for Java 2, you must have installed the Java Dynamic Management Kit for 1.2, and set your classpath accordingly. This example is located in the examplesDir/MLetAgent/ directory, see "Directories and Classpath" in the preface for details.In our example, we have two MBeans representing geometrical shapes. Before running the example, we compile them and create a jar file for each. We also compile the agent application at the same time.$ cd examplesDir/MLetAgent/ $ javac -classpath classpath *.java $ jar cf Square.jar Square.class SquareMBean.class $ rm Square.class SquareMBean.class $ jar cf EquilateralTriangle.jar EquilateralTriangle.class \ EquilateralTriangleMBean.class $ rm EquilateralTriangle.class EquilateralTriangleMBean.classThe agent command line requires you to specify first the URL of a jar file for directly loading the Square class, then the URL of the m-let file. We have left these files in the examples directory, but you could place them on a remote machine. With the Korn shell on the Solaris platform, you would type the following command:$ java -classpath classpath Agent \ file:${PWD}/Square.jar file:${PWD}/GeometricShapes.htmlIn the output of the agent, you can see it create the m-let loader MBean, and then download classes to create MBeans. It starts with the direct loading of the Square class, and then loads from the HTML file which specifies two EquilateralTriangle MBeans to be loaded. Once these have been loaded, we can see the third one that is loaded through the class loader shortcut.This agent uses the tracing mechanism, and you can select to receive the messages from the m-let loader by specifying the -DINFO_MLET property on the command line. The tracing mechanism is covered in the Java Dynamic Management Kit 4.0 Tools Reference guide and in the Javadoc API of the Trace class.The agent then launches an HTML adaptor so that we can easily view the new MBeans. In them we can see that the values contained in the ARG tags of the m-let file were used to initialize the MBeans. Point your web browser to the following URL and click on the MBeans in the MLetExample domain: http://localhost:8082/. When you are done, type "Control-C" in the window where you launched the agent.Since the MLet class is an MBean, the m-let loader service is fully manageable from a remote manager. This lets a manager create an m-let loader in an agent, add URLs to its list of code-bases, and create MBeans whose classes must be downloaded first.Using the Java 2 m-let class loader, we can again implement a "push" mechanism originating from a management application. In fact, it is even easier due to the direct class loading that the MLet MBean allows.In the example, our manager will create an m-let loader in an agent and have it load new MBean classes. Launched with only an RMI connector and an HTML adaptor, we can see at the end that the agent contains all of the new MBeans loaded from jar files, along with the m-let loader MBean. The initialization of manager is very simple:Example 6-12 public Client() { // Enable the trace mechanism [...] // Connect a new RMI connector client to the agent connectorClient = new RmiConnectorClient(); // Use the default address (localhost) RmiConnectorAddress address = new RmiConnectorAddress(); try { connectorClient.connect(address); } catch (Exception e) { println("Could not connect to the agent!"); e.printStackTrace(); System.exit(1); } } public static void main(String[] args) { // Parse command line arguments. [...] // Call the constructor to establish the connection Client client = new Client(); // Run the MLet example (see below) client.runMLetExample(); // Disconnect connector client from the connector server. client.connectorClient.disconnect(); System.exit(0); }Now that the manager is connected to the client, we can ask it to load classes. First we have it create an m-let loader MBean that we can use to download classes. Then we demonstrate the various ways of loading classes:Through an m-let file, which has the advantage of loading many MBeans at onceDirectly, from a code-base that was used in an m-let fileDirectly, after specifying a URL for the code-baseThe following code is taken from manager's runMLetExample method. The code is identical to the code of the agent example, except that we now go through the RemoteMBeanServer interface of the connector client instead of directly through the MBean server.Example 6-13 // Get the domain name from the MBeanServer. String domain = connectorClient.getDefaultDomain(); // Create a new MLet MBean and add it to the MBeanServer String mletClass = "javax.management.loading.MLet"; ObjectName mletName = new ObjectName(domain + ":name=" + mletClass); connectorClient.createMBean(mletClass, mletName); [...] // Create new EquilateralTriangle MBeans through MLET tags // The url_2 string is read from the command line Object mletParams_2[] = {url_2}; String mletSignature_2[] = {"java.lang.String"}; Set mbeanSet = (Set) connectorClient.invoke( mletName, "getMBeansFromURL", mletParams_2, mletSignature_2); for (Iterator i = mbeanSet.iterator(); i.hasNext(); ) { Object element = i.next(); if (element instanceof ObjectInstance) { // Success println("OBJECT NAME = " + ((ObjectInstance)element).getObjectName()); } else { // Failure println("EXCEPTION = " + ((Throwable)element).getMessage()); } }Now that the class loader has used the code-base of the jar file, we can create more of the MBeans from the same jar file. We invoke the createMBean method of the server with the object name of the class loader.Example 6-14 // Create another EquilateralTriangle MBean from the same jar file // used in the MLET file String triangleClass = "EquilateralTriangle"; ObjectName triangleName = new ObjectName( "MLetExample:name=" + triangleClass + ",id=3"); Object triangleParams[] = {new Integer(20)}; String triangleSignature[] = {"java.lang.Integer"}; connectorClient.createMBean(triangleClass, triangleName, mletName, triangleParams, triangleSignature);Finally, if we have a different code-base not associated with an m-let file, we can give its URL directly to the loader. This allows us to ask the agent to create almost any MBean, imitating a class "push" mechanism. Example 6-15 // Add a new URL to the MLet MBean to look for classes // The url_1 string is read from the command line Object mletParams_1[] = {url_1}; String mletSignature_1[] = {"java.lang.String"}; connectorClient.invoke(mletName, "addURL", mletParams_1, mletSignature_1); // Create a new Square MBean from its class in the Square.jar file String squareClass = "Square"; ObjectName squareName = new ObjectName( "MLetExample:name=" + squareClass); Object squareParams[] = {new Integer(10)}; String squareSignature[] = {"java.lang.Integer"}; connectorClient.createMBean(squareClass, squareName, mletName, squareParams, squareSignature);In this way, the manager can make code available on the network, and it can direct its agents to load the classes to create new MBeans ready for management. This mechanism can be used to distribute new resources, provide new services,or update applications, all under the control of the manager.The MBeans in the agent and manager (client) examples are identical, and we will set up the example in exactly the same manner.$ cd examplesDir/MLetClient/ $ javac -classpath classpath *.java $ jar cf Square.jar Square.class SquareMBean.class $ rm Square.class SquareMBean.class $ jar cf EquilateralTriangle.jar EquilateralTriangle.class \ EquilateralTriangleMBean.class $ rm EquilateralTriangle.class EquilateralTriangleMBean.classThe manager is written to be run on the same host as the agent application. If you wish to run it on a different host, you will need to modify the code for the Client class constructor where the agent address is specified (see Example 6-12). You could place the jar files and the m-let file on a remote machine and specify its new URL as the parameter to the manager application; we run the example with this file in the current directory.Before launching the manager, you must launch the agent. Here we give commands for launching the applications from the same terminal window running the Korn shell. On the Windows NT platform, you will have to launch each application in a separate window.$ java -classpath classpath Agent & $ java -classpath classpath Client \ file:${PWD}/Square.jar file:${PWD}/GeometricShapes.htmlIn the output of the manager, you can see it create the m-let service MBean, and then load all of the MBeans from different sources. If you connect to the agent in a web browser at the following URL: http://localhost:8082/ and reload its agent view every time the manager pauses, you can see the MBeans as they are created.The agent terminates after it disconnects it connector client. When you are done viewing the agent, type the following commands to stop the agent application:$ fg java [...] Agent <Control-C> ^C$ Chapter 77. Creating an SNMP AgentUsing the Java Dynamic Management Kit, you can create an agent application that is both an SNMP agent and normal JMX agent. SNMP MIBs can be represented as MBeans and the SNMP protocol adaptor exposes them to SNMP managers. Only MBeans derived from MIBs may be managed through the SNMP protocol adaptor, but other managers may view and manage them through other protocols.The provided mibgen tool generates the code for MBeans that represent a MIB. Groups and table entries are represented as MBean instances which expose the SNMP variables through their attributes. The mibgen tool creates skeleton getters and setters which only read or write internal variables. In order to expose the behavior of your host machine or device, you need to implement the code that will access the host- or device-specific functionality.The SNMP protocol adaptor interacts with your customized MIB MBeans to implement a compatible SNMPv1 and SNMPv2 agent. It also provides the mechanisms for sending traps and implementing both community-based access control and message-level data security.The program listings in this tutorial show only functional code: comments and output statements have been modified or removed for space considerations. However, all management functionality has been retained for the various demonstrations. The complete source code is available in the Snmp/Agent example directory located in the main examplesDir (see "Directories and Classpath" in the preface).Contents:"MIB Development Process" explains how MIBs are implemented as MBeans"The SNMP Protocol Adaptor" shows how to build an SNMP agent with the components of the Java Dynamic Management Kit"Sending Traps" demonstrates the SNMP trap mechanism in the SNMP adaptor"Access Control Lists (ACL)" shows how to specify host communities to limit access and send traps"Message-Level Security" demonstrates a more flexible way of limiting access to the SNMP agent"Stand-Alone SNMP Agents" demonstrates an alternative way of implementing an SNMP agentHere we describe the process for making MIBs manageable through the SNMP protocol adaptor of the Java Dynamic Management Kit. In our example, we demonstrate this process on a subset of the MIB-II defined by RFC 1213.Once you have defined the MIB you want to manage in your SNMP agent you need to generate its MBean representation using the mibgen tool. This command-line tool and its output are fully described in the Java Dynamic Management Kit 4.0 Tools Reference guide. This tool generates MBeans that represent the whole MIB, each of its groups and each of its table entries.To run the mibgen tool for our example, go to the examplesDir/Snmp/Agentdirectory and enter the following command:$ mibgen -d . mib_II_subset.txtThis will generate the following files in the current directory:The MBean (by inheritance) for the whole MIB: RFC1213_MIB.javaThe MBean and its metadata class for the Snmp group: Snmp.java, SnmpMBean.java, SnmpMeta.javaThe MBean and its metadata class for the System group: System.java, SystemMBean.java, SystemMeta.javaThe MBean and its metadata class for the Interfaces group: Interfaces.java, InterfacesMBean.java, InterfacesMeta.javaThe class representing an interface table, and the MBean representing entries in the table: TableIfTable.java, IfEntry.java, IfEntryMBean.java, IfEntryMeta.javaClasses representing enumerated types used in these groups and entries: EnumSnmpEnableAuthenTraps.java, EnumIfOperStatus.java, EnumIfAdminStatus.java, EnumIfType.javaThe OID table for representing the name definition of all MIB variables: RFC1213_MIBOidTable.javaThe MBean with the name of the MIB is just a central administrative class for managing the other MBeans which implement the MIB. All of the other MBeans contain the SNMP variables as attributes of their management interface. The mibgen tool generates standard MBeans for the MIB, so attributes are implemented with individual getter and setter methods.These MBeans are just skeletons, meaning that the attributes do not do anything. You must implement the getters and setters of the attributes to read and write data with the correct semantic meaning of the SNMP variable.Since SNMP does not support actions in MIBs, the only operations in these MBeans are checkers for implementing the SNMP set request in writeable variable. You may add operations and expose them in the MBean interface, but the SNMP manager will not be able to access them. However, other managers will be able to call these operations if they are connected through another protocol.Our example only implements a fraction of the attributes, those that are used in this tutorial. The others are just initialized with some plausible value. These implementations are contained in the classes with the Impl suffix. These implementation classes extend those that are generated by mibgen so that we can regenerate them without overwriting our customizations.Here is a summary of the implementation shown in the agent example:InterfaceImpl.java - adds a new entry notification listener to the IfTable object, then creates two table entries with plausible values and adds them to the table; associated with:TableEntryListenerImpl.java - the listener for table entry creation and deletion notifications: prints out the new table entry's valuesIfEntryImpl.java - implements a table entry and provides an internal method for switching the OperStatus variable that triggers a trap (see Example 7-2); this method is not exposed in the MBean interface, so it is only available to the code of this agent applicationSnmpImpl.java - initializes and implement variables of the Snmp group; many of these are state variables of the SNMP agent, so we call the getter methods of the SNMP adaptor object to return the informationSystemImpl.java - initializes the System group variables with some realistic valuesThe SnmpImpl.java and SystemImpl.java files provide code that you may reuse when you need to implement these common SNMP groups.The only class that we need to replace is RFC1213_MIB. Our implementation is located in patchfiles/RFC1213_MIB.java so that we can overwrite the one generated by mibgen. The main function of this MBean is to register the other MBeans of the MIB during its pre-registration phase. Our customization consists of specifying our *Impl classes when instantiating the group and table entry MBeans.We replace the generated file with our implementation before compiling all of the classes in the examplesDir/Snmp/Agent directory. The classpath must contain the current directory (.):$ cp -i patchfiles/RFC1213_MIB.java . cp: overwrite ./RFC1213_MIB.java (yes/no)? y $ javac -classpath classpath -d . *.javaWe are now ready to look at the implementation of an SNMP agent and run the example applications.Once your MIBs are implemented as MBeans, your agent application needs an SNMP protocol adaptor in order to function as an SNMP agent. Since the SNMP adaptor is also an MBean, it can be created and started dynamically in your agent by a connected manager or through the HTML adaptor. In our simple Agent example, we will launch it through the code of the agent application.Example 7-1 public class Agent { static SnmpAdaptorServer snmpAdaptor = null; public static void main(String args[]) { MBeanServer server; ObjectName htmlObjName; ObjectName snmpObjName; ObjectName mibObjName; ObjectName trapGeneratorObjName; int htmlPort = 8082; int snmpPort = 8085; // non-standard [...] try { server = MBeanServerFactory.createMBeanServer(); String domain = server.getDefaultDomain(); // Create and start the HTML adaptor. // htmlObjName = new ObjectName( domain + ":class=HtmlAdaptorServer,protocol=html,port=" + htmlPort); HtmlAdaptorServer htmlAdaptor = new HtmlAdaptorServer(htmlPort); server.registerMBean(htmlAdaptor, htmlObjName); htmlAdaptor.start(); // Create and start the SNMP adaptor. // snmpObjName = new ObjectName(domain + ":class=SnmpAdaptorServer,protocol=snmp,port=" + snmpPort); snmpAdaptor = new SnmpAdaptorServer(snmpPort); server.registerMBean(snmpAdaptor, snmpObjName); snmpAdaptor.start(); // The rest of the code is specific to our SNMP agent // Send a coldStart SNMP Trap (use port = snmpPort+1) // Trap communities are defined in the ACL file // snmpAdaptor.setTrapPort(new Integer(snmpPort+1)); snmpAdaptor.sendV1Trap(0, 0, null); // Create the MIB-II (RFC 1213) and add it to the MBean server. // mibObjName = new ObjectName("snmp:class=RFC1213_MIB"); RFC1213_MIB mib2 = new RFC1213_MIB(); // The MBean will register all group and table entry MBeans // during its pre-registration server.registerMBean(mib2, mibObjName); // Bind the SNMP adaptor to the MIB mib2.setSnmpAdaptorName(snmpObjName); [...] } catch (Exception e) { e.printStackTrace(); } } // Needed to get a reference on the SNMP adaptor object static public SnmpAdaptorServer getSnmpAdaptor() { return snmpAdaptor; } }We launch the SNMP adaptor in the same way that we launch the HTML adaptor. First we create a meaningful object name for its MBean, then we instantiate the class with a constructor allowing us to specify a non-default port, we register the MBean with the MBean server, and we start the adaptor to make it active.By default, the SNMP protocol adaptor uses the standard SNMP port 161. Since other applications may be using this port on a machine, our simple agent uses port 8085. When we connect to this agent our SNMP manager will need to specify this non-standard port number.Note - On certain platforms, applications also require super-user privileges to assign the default SNMP port 161. If your SNMP adaptor uses this port, its agent application will have to be launched with super-user privileges.Our agent application creates and manages one MIB, our subset of MIB-II. To do so, it instantiates the corresponding RFC1213_MIB MBean that has been generated by the mibgen tool (see "MIB Development Process"). We give it a meaningful object name and then we register it in the MBean server.The registration process lets the MBean instantiate and register other MBeans that represent the groups of the MIB and the entries of its tables. The set of all these MBeans at the end of registration make up the MBean representation of the MIB.If you do not wish to expose a MIB through the MBean server, you do not have to register it. However, you still need to create all of its other constituent objects. The generated code provides the init method in the main MBean of the MIB. Calling this method will create all necessary MBean objects without registering them in the MBean server.Because the SNMP data model relies on MIBs, only MBeans representing MIBs can be managed through SNMP. The main MBean of a MIB must be explicitly bound to the instance of the SNMP adaptor. The SNMP adaptor does not interact with any other MBeans, nor with the MBean server.After a MIB is instantiated, you must set the SnmpAdaptorName attribute of its main MBean to bind it to the SNMP adaptor. You can either call its setSnmpAdaptorName method directly or, if the MIB's MBean was registered in the MBean server, another management application may set the attribute through the MBean's exposed interface. In this way, the SNMP adaptor will have a reference of all MIBs it must expose.In the binding process, the SNMP adaptor obtains the root OID of the MIB. The adaptor uses this OID to determine which variables are implemented in the MIB's corresponding MBeans. In order for the SNMP adaptor to resolve a request on a given OID, the root OID of all bound MIBs must be distinct. This implies that no root OID may be equal to another or be a substring of another.Even though the SNMP adaptor may be registered in the MBean server, the adaptor only makes MIBs visible to SNMP managers. Other MBeans in the agent cannot be accessed or even represented in the SNMP protocol. The SNMP manager is limited by its protocol: it cannot take full advantage of a Java Dynamic Management agent through the basic MIBs, and it does not have access to any other MBeans.Once the MBean representing a MIB has been instantiated and bound to the SNMP adaptor, it is accessible through the SNMP adaptor. SNMP managers can send requests to operate on the contents of the MIB. The SNMP adaptor interprets the SNMP management requests, performs the operation on the corresponding MBean and returns the SNMP response to the manager. The SNMP protocol adaptor is compatible with SNMPv1 and SNMPv2 PDUs, with the exception of InformRequest which it doesn't handle.The advantage of having an SNMP agent "inside" a Java Dynamic Management agent is that you can use the other communications protocols to interact with MIBs and manage the SNMP adaptor. Since both the registered MIBs and the adaptor are MBeans, they are exposed for management. In our simple agent, the MIB was registered, and you can view its MBeans in a web browser through the HTML protocol adaptor. Furthermore, the MIB implementations in the SNMP agent could be easily upgraded using the m-let loader service (see Chapter 6, The M-Let Class Loader).If our agent included other connectors, management applications could connect to the agent and also manage the MIB and the SNMP adaptor. A non-SNMP manager could instantiate new MIB objects, bind them to the SNMP adaptor and operate on the exposed attributes and operations of the MIB.Non-SNMP managers may operate on the variables of a MIB, getting and setting values regardless of any SNMP manager that might also be accessing them through the SNMP adaptor. The designer of the agent and management applications is responsible for all coherence issues when accessing MIBs concurrently through different protocols.Non-SNMP managers can also control the SNMP agent through the MBean of the SNMP adaptor. Like the other communications MBeans, the port and other attributes can be modified when the SNMP adaptor is stopped. You can also get information about its state, and stop or restart it to control when it is on-line. These administrative attributes and operations are defined in the CommunicatorServerMBean interface.The SNMP adaptor server also implements the SnmpAdaptorServerMBean interface to define its operating information. The Snmp group of MIB-II defines certain statistics variables that SNMP agents must expose. For example, the SNMP adaptor provides methods for getSnmpInPkts and getSnmpOutBadValues. Non-SNMP managers can read these variables as attributes of the SNMP adaptor MBean.The SNMP adaptor also exposes other operating information that is unavailable to SNMP managers. For example, the ActiveClientCount and ServedClientCount read-only attributes report on SNMP manager connections to this agent. The read-write BufferSize attribute lets you change the size of the message buffer when the adaptor is stopped. The adaptor MBean also exposes operations for sending traps or implementing your own security (see "Message-Level Security").After building the example as described in "MIB Development Process", launch the simple agent with the following command:$ java -classpath classpath AgentYou should see some initialization messages, including our notification listener giving information about the two table entries which are created. Then, you should see the agent sending out a trap every two seconds. Traps are covered in "Sending Traps", and we can ignore these messages. Access this agent's HTML adaptor by pointing a web browser to the following URL: http://localhost:8082/. Through the HTML adaptor, you can see the MBeans representing the MIB:The class=RFC1213_MIB MBean in the snmp domain is the topmost MBean, it contains a name and information about the SNMP adaptor to which the MIB is boundThe RFC1213_MIB domain contains the MBeans for each group; these MBeans contain variables with values provided by our customizationsThe ifTable domain contains the entries of the interface tableIn any of these MBeans, you could write new values into the text fields of exposed attributes and click the "Apply" button. This will set the corresponding SNMP variable, and thereafter, SNMP managers will see the new value. This is an example of managing a MIB through a protocol other than SNMP.For any SNMP agent application, you can turn on trace messages for the SNMP adaptor by specifying the -DINFO_ADAPTOR_SNMP property on the command line. The tracing mechanism is covered in the Java Dynamic Management Kit 4.0 Tools Reference guide and in the Javadoc API of the Trace class.Type "Control-C" when you are done viewing the agent.The simple SNMP agent application also demonstrates how the agent can send traps. The customized class IfEntryImpl in the example directory extends the IfEntry class generated by mibgen in order to provide a method that switches the IfOperStatus variable and sends a trap. This is an example of customization of the generated code: some agent-side entity will switch the operation status, the MIB variable will be updated and a trap will be sent to SNMP managers.The IfEntryImpl.java file provided in the example directory contains the code for sending the trap through the SNMP adaptor.Example 7-2 public void switchifOperStatus() { // implements the switch and then calls sendTrap indirectly [...] } // Method called after the variable has been switched // Should be called with generic==2 (up) or 3 (down or testing) public void sendTrap(int generic) { SnmpAdaptorServer snmpAdaptor = null; // Retrieve the reference of the SNMP protocol adaptor through // the static method of the Agent or StandAloneSnmpAgent class snmpAdaptor = Agent.getSnmpAdaptor(); if (snmpAdaptor == null) { snmpAdaptor = StandAloneSnmpAgent.getSnmpAdaptor(); } if (snmpAdaptor == null) { return; } Vector varBindList = new Vector(); // IfIndex is the index of the current If table entry SnmpOid oid1 = new SnmpOid("1.3.6.1.2.1.2.2.1.1." + IfIndex); SnmpInt value1 = new SnmpInt(IfIndex); SnmpVarBind varBind1 = new SnmpVarBind(oid1, (SnmpValue) value1); varBindList.addElement(varBind1); try { snmpAdaptor.sendV1Trap(generic, 0, varBindList); } catch (Exception e) { e.printStackTrace(); } }Since the sendTrap method runs in a different thread, it needs to get a reference to the SNMP adaptor instance. Here we call the static methods of our two possible agent implementations. This code is specific to these agents and is only an example of how to retrieve this information.Since our example has no real operation status, we invent the LinkTrapGenerator class which will switch the status periodically. It is an MBean which contains a thread which loops endlessly. The interval period between traps and the index of the table entry can be modified through the MBean's attributes.Example 7-3 public void run() { while (true) { try { sleep(interval); } catch (Exception e) { e.printStackTrace(); } sendTrap(); } } public void sendTrap() { // get the entry whose status we will switch IfEntryImpl ifEntryImpl = InterfacesImpl.find(ifIndex); if (ifEntryImpl == null) { errors++; return; } ifEntryImpl.switchifOperStatus(); successes++; }To start the trap generator, the example application creates a LinkTrapGenerator MBean. During its registration, the MBean starts the thread, sending a trap every two seconds by default.Example 7-4 // Create a LinkTrapGenerator (specify the ifIndex in the object name) // String trapGeneratorClass = "LinkTrapGenerator"; int ifIndex = 1; trapGeneratorObjName = new ObjectName("trapGenerator:class=" + trapGeneratorClass + ",ifIndex=" + ifIndex); server.createMBean(trapGeneratorClass, trapGeneratorObjName);In order for an SNMP adaptor to send traps to remote managers, you must define the trap group in the access control list (ACL) file. This group of community definitions lists all of the hosts to which the agent will send every trap. A community definition associates a community name with a list of hosts specified either by their hostname or by their IP address. All hosts in a community will receive the trap in a packet identified by the community name.Note - Since access control and trap recipients share the same file, you must fully define the access control when you want to send traps.See "Access Control Lists (ACL)" for a formal definition of the trap group and instructions for defining the ACL file when starting the agent. In this example we provide the following template:Example 7-5 acl = { { communities = public access = read-only managers = yourmanager } { communities = private access = read-write managers = yourmanager } } trap = { { trap-community = public hosts = yourmanager } }Traps are sent to the port specified by the TrapPort attribute of the SnmpAdaptorServer MBean. In our simple agent, we set the trap port to 8086, but this can be changed at any time by a custom MIB implementation or a management application.If the ACL file is not defined, or if the trap group is empty, the default behavior of the SNMP adaptor is to send a trap to the localhost.Before launching the SNMP agent again, edit the jdmk.acl file to replace the occurrences of yourmanager with the name of a host running an SNMP manager. Then copy this file to the configuration directory:$ cp jdmk.acl installDir/SUNWjdmk/jdmk4.0/JDKversion/etc/confIf you don't have an SNMP manager or a second host, don't copy the ACL file. In the absence of the trap-community definitions, the traps will be addressed to the trap port on the local host. And even if no manager is running, we can still see the agent sending the traps. See "SNMP Trap Handler" in the SNMP manager topic for details about receiving traps.Then launch the simple agent example again:$ java -classpath classpath AgentAccess this agent's HTML adaptor by pointing a web browser to the following URL: http://localhost:8082/. Click on the class=LinkTrapGenerator,ifIndex=1 MBean in the trapGenerator domain.Through the HTML adaptor, you can see the MBean representing the trap generator object. You can modify its attributes to change the table entry that it operates on and to change the interval between traps.Change the trap interval to 10000 so that traps are sent every 10 seconds.Go back to the agent view and click on the ifEntry.ifIndex=1 MBean in the ifTable domain. Set the reload period to 10, and click the "Reload" button.You should see the effect of the trap generator which is to switch the value of the IfOperStatus variable. It is our implementation of the table entry which sends a trap when this status is changed.Go back to the agent view and click on the name=Snmp MBean in the RFC1213_MIB domain. Scroll down to see the SnmpOutPkts and SnmpOutTraps variables.These variables should be the only non zero values, if no manager has connected to the SNMP agent. The Snmp group shows information about the SNMP adaptor, and we can see how many traps have been sent since the agent was launched.Type "Control-C" when you are done interacting with the agent.The LinkTrapGenerator MBean is not manageable through the SNMP adaptor because it is not part of any MIB. It is an example of another MBean providing some control of the SNMP agent, and this control can be exercised by other managers connecting through other protocols. This shows that designing an SNMP agent application involves both the implementation of the MIB functionality and, if desired, the implementation of other dynamic controls afforded by the JMX architecture and the services of the Java Dynamic Management Kit.For the SNMP adaptor, the Java Dynamic Management Kit provides access control based on the IP address and community of the manager's host machine. Information on the access rights for communities and host machines is stored in an ACL file.The ACL file also defines the hosts of managers to which to agent will send traps. When a trap is sent, the agent will send it to all hosts listed in the trap definitions of the ACL file.To enable access control and traps for the SNMP adaptor, ensure that an ACL file exists when any agents are started. The ACL file must be named jdmk.acl and must be located in the configuration directory.Operating EnvironmentConfiguration DirectorySolarisinstallDir/SUNWjdmk/jdmk4.0/JDKversion/etc/conf/Windows NTinstallDir\SUNWjdmk\jdmk4.0\JDKversion\etc\conf\Alternatively, you may specify a different file by setting the jdmk.acl.file property when launching your agent. For example, if the full pathname of your ACL file is MyAclFile, use this command to launch the agent with access control enabled:$ java -classpath classpath -Djdmk.acl.file=MyAclFile MyAgentIf an ACL file exists, the access rights it defines apply to all managers or proxy servers that access the agent through its SNMP adaptor. If the ACL file does not exist when the agents are started, all managers are granted full access to the agent through the SNMP adaptor.An ACL file contains an acl group defining community and manager access rights and a trap group defining the community and hosts for sending traps.The acl group contains one or more lists of community configurations.acl = { list1 list2 ... listN }Each list has the following format: { communities = communityList access = accessRights managers = hostList }The communityList is a list of SNMP community names to which this access control applies. The community names in this list are separated by commas.The accessRights specifies the rights to be granted to all managers running on the machines specified in the managers item. There are two possible values: either read-write or read-only.The hostList item specifies the host machines of the managers to be granted the access rights. The hostList is a comma-separated list of hosts, each of which can be expressed as any one of the following:A host name An IP addressA subnet maskNote - To distinguish between IP addresses and subnet masks in an ACL file, each integer in a subnet mask is separated by an exclamation mark (!) instead of a dot.The trap group specifies the hosts to which the agent can send traps. This group contains a one or more trap community definitions.trap = { community1 community2 ... communityN }Each defines the association between a set of hosts and the SNMP community string in the traps to be sent to them. Each trap definition has the following format: { trap-community = trapCommunityString hosts = trapInterestHostList }The trapCommunityString item specifies the SNMP community string. It will be included in the traps sent to the hosts specified in the hosts item.The trapInterestHostList item specifies a comma-separated list of hosts. Each host must be identified by its name or complete IP address.The ACL file is the default access control mechanism in the SNMP adaptor. The SnmpAdaptorServer class has constructors that let you specify your own access control mechanism. For example, if your agent runs on a device with no file system, you could implement a mechanism which doesn't rely on the jdmk.acl file.Your access mechanism must be a class that implements the IPAcl interface. This interface specifies the methods that the SNMP adaptor uses to check permissions when processing a request. If you instantiate the SNMP adaptor with your access control class, the adaptor will call your implementation of the access control methods.The JdmkAcl class implements the default access mechanism that uses an ACL file. It is also an implementation of the IPAcl interface. By default, the SNMP adaptor will use this implementation if no other is passed to its constructor.The SecureAgent example shows another level of security at the SNMP message level. Whereas the access control mechanism handles access rights to all MIBs for communities of manager hosts, message-level security lets you control how PDUs (protocol data units) representing requests are encoded and decoded by the SNMP protocol adaptor.The data in an SNMP message is stored in its raw form as a byte array. When receiving a message, the SNMP protocol adaptor must decode the data to obtain the corresponding request, and before sending a request, the adaptor must encode it as a message. By default, the basic encoding rules (BER) are used to translate back and forth between message and decoded PDU. The SNMP protocol adaptor provides a hook to let you implement your own encoding and decoding mechanism.Message-level security relies on the following classes in the javax.management.snmp package:SnmpPduPacket classSnmpMessage classSnmpPduFactory interfaceAn SnmpPduPacket object represents the fully decoded description of an SNMP request. In particular, it includes the operation type (get, set, ...), the list of variables to which the operation applies, the request identifier, and the protocol version.The SnmpMessage object is a partially decoded representation of the SNMP request. The type of the request, the variables and their values all remain encoded as a byte array. This object also contains the default BER encoding and decoding methods. The SnmpMessage class is derived from the Message syntax in RFC 1157 and RFC1902.Both of these classes also contain port and address information of the SNMP manager. When implementing your own security mechanism, you also have access to the contents of the PDU or message you are handling. This lets you implement security based on several factors:The host or community of the SNMP manager in a message before it is decodedThe type or contents of a request after it is decodedSome encryption of the raw dataBecause message-based security gives you access to all these different factors, you can perform elaborate filtering of incoming requests. For example, you could limit the access of certain SNMP managers to certain variables, or you could filter values, such as untrusted IP addresses, before they are assigned.If your security is based on the encryption of the message data, your manager must also be using the same encryption. Since the SNMP classes are also part of the SNMP manager API, you can reuse the same encryption code in your manager if it is developed in the Java programming language. Security in the SNMP manager API is implemented in the SnmpPeer object, see "SNMP Manager Security" for more information.If your security scheme is based only on the sender of the message or contents of the PDU, it can be applied unilaterally by the agent, without requiring any coordination with the manager application. This is what is demonstrated in the SecureAgent example.In the SNMP protocol adaptor, the task of translating an SnmpMessage object into an SnmpPduPacket object is delegated to an object which implements the SnmpPduFactory interface. This interface defines two methods, one for decoding messages into PDUs and one for encoding PDUs into messages:decodePdu takes an SnmpMessage and should return a decoded SnmpPduPacket object; if it returns null or raises an exception, the incoming message is assumed to have failed the security checkencodePdu takes a SnmpPduPacket and should return an encoded SnmpMessage to sendIn our example, the SnmpPduFactoryImpl class implements these methods and rejects messages if they originate from certain hosts. The list of hosts to refuse is passed to the class constructor at instantiation.Example 7-6 To use your custom PDU factory in your SNMP agent, you need to call the usePduFactory method of your SnmpAdaptorServer instance. First instantiate your PDU factory implementation and then pass it to this method. Your encoding and decoding scheme will then replace the standard one used by the SNMP protocol adaptor.The SecureAgent.java file contains a simple agent like the one presented in "The SNMP Protocol Adaptor". It only adds the call to force the SNMP adaptor to use the new PDU factory that we specify.// Use SnmpPduFactoryImpl class for SnmpPduFactory to filter requests. // Enter your list of refused hosts as arguments when launching this agent. // The agent will reject requests coming from the specified hosts. // String[] refusedHosts = new String[args.length]; refusedHosts = args; snmpAdaptor.usePduFactory(new SnmpPduFactoryImpl(refusedHosts));The secure agent does not use the trap generator and does not demonstrate traps. The LinkTrapGenerator class is not written to function with the SecureAgent class.You can only demonstrate the output of our custom PDU factory if you have an SNMP manager application which can connect to the secure agent. See "Developing an SNMP Manager" for example applications you can use.The SecureAgent class takes command line arguments to create the list of hosts from which it will refuse SNMP requests. Use the following command to launch the secure agent example:$ java -classpath classpath Agent [host1..hostN]Whenever one of the refused hosts sends a request, you should see the message displayed by our custom PDU factory implementation. Type "Control-C" when you are done running the secure agent.You can combine message-level security and access control defined by the presence of an ACL file. The ACL file indicates trusted hosts and communities from which requests are accepted. After they are accepted, they are decoded with the message-level security you provide. This lets you provide more precise security based on types of requests or the target variable, as well as any encryption.The design of the SNMP protocol adaptor and of the MBeans generated by mibgen give you the option of creating an SNMP agent that is not a Java Dynamic Management agent.This stand-alone agent has no MBean server and thus no possibility of being managed other than through the SNMP protocol. The application must instantiate all MIBs that the SNMP agent will need, as it will be impossible to create them through some other manager. The advantage of a stand-alone agent is the reduced size of application, in terms of memory usage.Example 7-7 import com.sun.jdmk.Trace; import com.sun.jdmk.comm.SnmpAdaptorServer; public class StandAloneSnmpAgent { static SnmpAdaptorServer snmpAdaptor = null; public static void main(String args[]) { // enable tracing [...] try { // The agent is started on a non standard SNMP port: 8085 int port = 8085; snmpAdaptor = new SnmpAdaptorServer(port); java.lang.System.out.println( "NOTE: SNMP Adaptor is bound on port " + port); // Start the adaptor snmpAdaptor.start(); // Send a coldStart SNMP Trap snmpAdaptor.sendV1Trap(0, 0, null); // Create the MIB you want in the agent (ours is MIB-II subset) RFC1213_MIB mib2 = new RFC1213_MIB(); // Initialize the MIB so it creates the associated MBeans mib2.init(); // Bind the MIB to the SNMP adaptor mib2.setSnmpAdaptor(snmpAdaptor); // Optional: create a LinkTrapGenerator int ifIndex = 1; LinkTrapGenerator trapGen = new LinkTrapGenerator(ifIndex); trapGen.start(); } catch (Exception e) { e.printStackTrace(); } } // Needed to get a reference on the SNMP adaptor object static public SnmpAdaptorServer getSnmpAdaptor() { return snmpAdaptor; } }As this example demonstrates, the stand-alone agent uses exactly the same MIB MBeans, with the same customization, as our other agents. However, instead of registering them in MBean server, they are only instantiated. And whereas the registration process creates all subordinate MBeans of the MIB, now we must call its init method explicitly. The init method performs the same function as the preRegister method, only it does not register the MBean with the MBean server.The mibgen tool automatically generates both the pre-registration methods and the init methods in the MIB MBeans. Therefore, no special action is necessary to use them in either a regular agent or a stand-alone agent. If you use a stand-alone agent for memory considerations, you can remove the registration process from the MBean and only customize the init process.In our example, we have applied the customizations to both processes so that the MIB can be used by either agent. In the following code, customizations are noted with MODIF_ comments:Example 7-8 public class RFC1213_MIB extends SnmpMib implements Serializable { // Default constructor. Initialize the Mib tree public RFC1213_MIB() { mibName = "RFC1213_MIB"; } // Initialization of the MIB with no registration in the MBean server public void init() throws IllegalAccessException { // Allow only one initialization of the MIB if (isInitialized == true) { return ; } // Initialization of the "Snmp" group { SnmpMeta meta = new SnmpMeta((SnmpMib)this); // MODIF_BEGIN //meta.setInstance(new Snmp((SnmpMib)this)); meta.setInstance(new SnmpImpl((SnmpMib)this)); // MODIF_END root.registerNode("1.3.6.1.2.1.11", (SnmpMibNode)meta); } // Initialization of the other groups [...] isInitialized = true; } // Initialization of the MIB with AUTOMATIC REGISTRATION // in the MBean server public ObjectName preRegister(MBeanServer server, ObjectName name) throws Exception { // Allow only one initialization of the MIB if (isInitialized == true) { throw new InstanceAlreadyExistsException(); } // Initialize MBeanServer information this.server = server; // Initialization of the "Snmp" group { SnmpMeta meta = new SnmpMeta((SnmpMib)this); // MODIF_BEGIN //Snmp instance = new Snmp((SnmpMib)this, server); Snmp instance = new SnmpImpl((SnmpMib)this, server); // MODIF_END meta.setInstance(instance); root.registerNode("1.3.6.1.2.1.11", (SnmpMibNode)meta); server.registerMBean( instance, new ObjectName(mibName + ":name=Snmp")); } // Initialization of the other groups [...] isInitialized = true; return name; } private boolean isInitialized = false; }After the MIB is initialized, it only needs to be bound to the SNMP adaptor, as in the other agents. That is all you need to do when programing a stand-alone SNMP agent.Launch the stand-alone agent with the following command:$ java -classpath classpath StandAloneSnmpAgentYou should see the same initialization messages as with the simple agent. Then, you should see the agent sending out a trap every two seconds. If you have an SNMP manager application, you can send requests to the agent and receive its traps. See "Developing an SNMP Manager" for example applications you can use.The only limitation of a stand-alone agent is that you cannot access or manage the SNMP adaptor and MIB MBeans in the dynamic management sense. However, the SNMP adaptor still relies on the ACL file for access control and traps, and you can implement other security schemes as described in "Message-Level Security".Type "Control-C" when you are done running the stand-alone agent.Chapter 88. Developing an SNMP ManagerThe Java Management extensions specify the SNMP manager API for implementing an SNMP manager application in the Java programming language. This API is covered in the JMX specification and in the Javadoc API provided with the Java Dynamic Management Kit (see "Related Books" in the preface for more information). Here we explain the example applications that use this API.The SNMP manager API can be used to access any SNMP agent, not just those developed with the Java Dynamic Management Kit. The manager only requires a definition of the MIB that it will access. We generate the class representing the OID table from the MIB file using the mibgen tool.The complete source code for these applications is available in the Snmp/Manager example directory located in the main examplesDir (see "Directories and Classpath" in the preface).Contents:"The Synchronous Manager Example" shows the simplest way to program an SNMP manager in the Java programming language"The Asynchronous Manager Example" demonstrates the more advanced features of the SNMP manager APIThe synchronous SNMP manager is the simplest to program. The manager sends a request to an agent (peer) and waits a given timeout period for the answer. During the wait, the manager is blocked, and when the timeout delay expires, the manager can see if the request was answered or not.A manager issues requests on variables identified by their full OID. If it has initialized the OID table description of the MIB it will access, it can also refer to the variables by their name. To do this, the manager should call the setSnmpOidTable method of the static SnmpOid object. It should pass in the OID table object instantiated from the SnmpOidTableSupport sub-class generated by the mibgen tool when "compiling" the MIB.The SNMP manager API specifies the SnmpPeer object for describing an agent, and the SnmpParameters object for describing its read-write communities and its protocol version (SNMPv1 or SNMPv2). The SnmpSession is an object for sending requests and we can associate a default peer to it. The session instance has an SnmpOptions field which we can use to set multiplexing and error fixing behavior.Note - The objects specified by the SNMP manager API are not MBeans and cannot be registered in an MBean server to create a manager that could be controlled remotely. However, you could write an MBean that uses these classes to retrieve and expose information from SNMP agents.A manager can contain any number of peers, one for each agent it wishes to access, and any number of sessions, one for each type of behavior it wishes to implement. Once the peers and the sessions are initialized, the manager can build lists of variables and send session requests to operate on them. The session returns a request object, and the manager calls its waitForCompletion method with the desired timeout delay.Finally, the manager analyzes the result of the request, first to see if there were any errors, then to extract the data returned by the request.Here is the code of the main method of the SimpleManager application. It performs all of the above steps to perform a very simple management operation.Example 8-1 // read the command line parameters String host = argv[0]; String port = argv[1]; // Specify the OidTable containing all the MIB II knowledge // Use the OidTable generated by mibgen when compiling MIB II // SnmpOidTableSupport oidTable = new RFC1213_MIBOidTable(); SnmpOid.setSnmpOidTable(oidTable); SnmpPeer agent = new SnmpPeer(host, Integer.parseInt(port)); // When creating the parameter object, you can specify the // read and write community to be used when querying the agent. SnmpParameters params = new SnmpParameters("public", "private"); agent.setSnmpParam(params); SnmpSession session = new SnmpSession("SimpleManager session"); // When invoking a service provided by the SnmpSession, it // will use the default peer if none is specified explicitly session.setDefaultPeer(agent); // Build the list of variables you want to query. // For debugging, you can associate a name to your list. SnmpVarbindList list= new SnmpVarbindList( "SimpleManager varbind list"); // We want to read the "sysDescr" variable. list.addVariable("sysDescr.0"); // Make the SNMP get request and wait for the result. SnmpRequest request = session.snmpGet(null, list); boolean completed = request.waitForCompletion(10000); // Check for a timeout of the request. if (completed == false) { java.lang.System.out.println( "Request timed out. Check reachability of agent"); java.lang.System.exit(0); } // Check if the response contains an error. int errorStatus = request.getErrorStatus(); if (errorStatus != SnmpDefinitions.snmpRspNoError) { java.lang.System.out.println("Error status = " + SnmpRequest.snmpErrorToString(errorStatus)); java.lang.System.out.println("Error index = " + request.getErrorIndex()); java.lang.System.exit(0); } // Now we can extract the content of the result. SnmpVarbindList result = request.getResponseVbList(); java.lang.System.out.println("Result: \n" + result); // End the session properly and we're done session.destroySession(); java.lang.System.exit(0);In the examplesDir/Snmp/Manager directory, we first need to generate the OID table description of MIB-II that our manager will access. Then we compile the example classes. To set up your environment, see "Directories and Classpath" in the preface.$ mibgen -mo -d . mib_II.txt [output omitted] $ javac -classpath classpath -d . *.javaMake sure that no other agent is running on port 8085, and launch the simple SNMP agent in examplesDir/Snmp/Agent. See "MIB Development Process" if you have not already built and run this example.Here we give commands for launching the applications from the same terminal window running the Korn shell. On the Windows NT platform, you will have to launch each application in a separate window. We redirect the output messages since this agent sends traps periodically.$ cd examplesDir/Snmp/Agent $ java -classpath classpath Agent > Agent.out &Now we can launch the manager application to connect to this agent. If you wish to run the manager on a different host, replace localhost with the name of the machine where you launched the agent.$ cd examplesDir/Snmp/Manager $ java -classpath classpath SimpleManager localhost 8085 SimpleManager::main: Send get request to SNMP agent on localhost port 8085 Result: [Object ID : 1.3.6.1.2.1.1.1.0 (Syntax : String) Value : SunOS sparc 5.7]Here we see the output of the SNMP request, it is the value of the sysDescr on the agent.Leave the agent running if you are going on to the next example, otherwise remember to stop it with the following commands:$ fg java [...] Agent > agent.out <Control-C> ^C$ rm examplesDir/Snmp/Agent/agent.outThe asynchronous SNMP manager lets you handle more requests in the same amount of time because the manager is not blocked waiting for responses. Instead it creates a request handler object which runs as a separate thread and processes several responses concurrently. Otherwise, the initialization of peers, parameters, sessions and options is identical to that of a synchronous manager.In this example application, we also demonstrate how to implement and enable a trap listener for the traps sent by the agent. First we need to instantiate an SnmpEventReportDispatcher object. Then we add our listener implementation through its addEventReportListener method, and finally we start its thread. Trap listeners can be implemented in any manager using the SNMP manager API, not only asynchronous managers.Example 8-2 // read the command line parameters String host = argv[0]; String port = argv[1]; // Use the OidTable generated by migen when compiling MIB II. SnmpOidTableSupport oidTable = new RFC1213_MIBOidTable(); // Sample use of the OidTable. SnmpOidRecord record = oidTable.resolveVarName("udpLocalPort"); java.lang.System.out.println( "AsyncManager::main: variable = " + record.getName() + " oid = " + record.getOid() + " type = " + record.getType()); // Initialize the SNMP Manager API. SnmpOid.setSnmpOidTable(oidTable); // Create an SnmpPeer object for representing the agent SnmpPeer agent = new SnmpPeer(host, Integer.parseInt(port)); // Create parameters for communicating with the agent SnmpParameters params = new SnmpParameters("public", "private"); agent.setSnmpParam(params); // Build the session and assign its default peer SnmpSession session = new SnmpSession("AsyncManager session"); session.setDefaultPeer(agent); // Create a listener and dispatcher for SNMP traps: // SnmpEventReportDispatcher will run as a thread and // listens for traps in UDP port = agent port + 1 SnmpEventReportDispatcher trapAgent = new SnmpEventReportDispatcher(Integer.parseInt(port)+1); // TrapListenerImpl will receive a callback // when a valid trap PDU is received. trapAgent.addEventReportListener(new TrapListenerImpl()); new Thread(trapAgent).start(); // Build the list of variables to query SnmpVarbindList list = new SnmpVarbindList("AsyncManager varbind list"); list.addVariable("sysDescr.0"); // Create a simple implementation of an SnmpHandler. AsyncRspHandler handler = new AsyncRspHandler(); // Make the SNMP walk request with our handler SnmpRequest request = session.snmpWalkUntil( handler, list, new SnmpOid("sysServices")); // Here you could do whatever processing you need. // In the context of the example, we are just going to wait // 5 seconds so that we can receive trap PDUs. Thread.sleep(5000); // Here the handle should have resume the activity of the thread // so the request is over java.lang.System.out.println("done"); // End the session properly and we're done. // session.destroySession(); java.lang.System.exit(0);In this example, the manager performs an snmpWalkUntil request which will give a response for each variable that it gets. The response handler will be called every time to process the response.A trap handler for the SNMP manager is an object that implements the SnmpEventReportListener interface in the javax.management.snmp.manager package. When this object is bound as a listener of an SnmpEventReportDispatcher object, its methods will be called to handle trap PDUs.The interface defines two methods, one for processing SNMPv1 traps and the other for SNMPv2 traps. Trap PDUs have already been decoded by the dispatcher: the v1 handler must process an SnmpPduTrap object, and the v2 handler must process an SnmpPduRequest object representing a trap. In our implementation, we are only interested in v1 traps, and we just print out the trap information fields.Example 8-3 public class TrapListenerImpl implements SnmpEventReportListener { public void processSnmpTrapV1(SnmpPduTrap trap) { java.lang.System.out.println( "NOTE: TrapListenerImpl received trap :"); java.lang.System.out.println( "\tGeneric " + trap.genericTrap); java.lang.System.out.println( "\tSpecific " + trap.specificTrap); java.lang.System.out.println( "\tTimeStamp " + trap.timeStamp); java.lang.System.out.println( "\tAgent address " + trap.agentAddr.stringValue()); } public void processSnmpTrapV2(SnmpPduRequest trap) { java.lang.System.out.println("NOTE: Trap V2 ignored"); } }A request handler for an asynchronous manager is an implementation of the SnmpHandler interface. When a handler object is associated with a request, its methods are called when the agent returns an answer or fails to return an answer. In these methods, you implement whatever actions you wish for processing the results of a request. The timeout used by the request handler is the one specified by the SnmpPeer object representing the agent. The handler is also called to process any errors caused by the request in the session. This insures that the manager application is never interrupted after issue a request.Example 8-4 public class AsyncRspHandler implements SnmpHandler { // Empty constructor public AsyncRspHandler() { } // Called when the agent responds to a request public void processSnmpPollData( SnmpRequest request, int errStatus, int errIndex, SnmpVarbindList vblist) { java.lang.System.out.println( "Processing response: " + request.toString()); java.lang.System.out.println( "errStatus = " + SnmpRequest.snmpErrorToString(errStatus) + " errIndex = " + errIndex); // Check if a result is available. if (request.getRequestStatus() == SnmpRequest.stResultsAvailable) { // Extract the result for display SnmpVarbindList result = request.getResponseVbList(); java.lang.System.out.println( "Result = " + result.vbListToString()); } } // Called when the agent fails to respond to a request public void processSnmpPollTimeout(SnmpRequest request) { java.lang.System.out.println( "Request timed out: " + request.toString()); if (request.getRequestStatus() == SnmpRequest.stResultsAvailable) { // The result is empty and will display an error message SnmpVarbindList result = request.getResponseVbList(); java.lang.System.out.println( "Result = " + result.vbListToString()); } } // Called when there is an error in the session public void processSnmpInternalError(SnmpRequest request, String errmsg) { java.lang.System.out.println( "Session error: " + request.toString()); java.lang.System.out.println("Error is: " + errmsg); } }These example applications do not cover the security features in the SNMP manager. However, security can be implemented at the message level with a custom PDU factory, in the same way that it is for SNMP agents (see "Message-Level Security"). The hook for using your own implementation of the PDU factory is the setPduFactory method of an SnmpPeer instance.Message-level security can be implemented in this manner in both synchronous and asynchronous managers. See the Java Management Extensions SNMP Manager API document and its Javadoc API for more details.If you have not done so already, launch the simple SNMP agent in examplesDir/Snmp/Agent, after making sure that no other agent is running on port 8085. The manager also requires the same OID table description that we generated for the synchronous manager. See "Running the SimpleManager Example" for instructions to do this.Here we give commands for launching the agent and manager from the same terminal window running the Korn shell. On the Windows NT platform, you will have to launch each application in a separate window. We redirect the output messages since this agent sends traps periodically.$ cd examplesDir/Snmp/Agent $ java -classpath classpath Agent > Agent.out &Now we can launch the manager application to connect to this agent. If you wish to run the manager on a different host, replace localhost with the name of the machine where you launched the agent.$ cd examplesDir/Snmp/Manager $ java -classpath classpath AsyncManager localhost 8085You should then see the output of the SnmpWalkUntil request: the response handler method is called for each variable that is returned. Since this manager also has a trap listener running in a different thread, the output may be interspersed with trap reports.When you are done with the agent, don't forget to stop it with the following commands:$ fg java [...] Agent > agent.out <Control-C> ^C$ rm examplesDir/Snmp/Agent/agent.outChapter 99. Implementing an SNMP ProxyIt is easier to manage a large number of SNMP agents when they have a hierarchical structure of master agents and sub-agents. Master agents concentrate and relay the information in their sub-agents and can provide their own specific information as well. Managers only communicate with the master agents and access the sub-agents transparently, as if the information actually resided in the master agent.In order to do this, agents must contain an SNMP proxy for each sub-agent that they manage. The proxy is a Java class that looks like a MIB MBean to the agent, but which actually accesses the sub-agent to provide the information that is requested of it. In order to access sub-agents, the proxy object relies on the SNMP manager API.The SNMP proxy is used in this simple example to allow a manager to access two MIBs through one agent. You can reuse the proxy class in your management solutions to implement any hierarchy of managers, master agents and sub-agents.The source code for the proxy object and the sample application is available in the Snmp/Proxy example directory located in the main examplesDir (see "Directories and Classpath" in the preface).Contents:"The Proxy Roles" explains how the example SNMP proxy works and how it interacts with the manager and its sub-agent"The SNMP Proxy Implementation" gives details about how the proxy is programmed"Running the SNMP Proxy Example" shows how to build and launch the sub-agent, the master agent and the manager applicationAs we saw in "MIB Development Process", the MBeans that represent a MIB are generated from the MIB definition by the mibgen tool. This tool generates one main MBean representing the MIB and then one MBean for each group and each table entry. The main MBean extends the SnmpMib class whose implementation of the abstract SnmpMibAgent class processes all requests on a MIB. For example, if an agent receives a get request for some variable, it will call the get method that the main MBean inherits from SnmpMibAgent. The implementation of this method relies on the MIB structure to find the MBean containing the corresponding attribute and then call its getter to read the value of the variable.A proxy is another implementation of the SnmpMibAgent class which, instead of resolving variables in local MBeans, reformulates an SNMP request, sends it to a designated sub-agent and forwards the answer that it receives. Since only the main MBean of a MIB is bound to the SNMP adaptor, we bind the proxy instead, and the master agent transparently exposes the MIB which actually resides in the sub-agent.The master agent needs to instantiate one SNMP proxy object for each sub-agent containing MIBs that it wishes to serve. The remote MIBs can be on any number of sub-agents, and the master agent can have several proxy objects. Sub-agents themselves may contain proxies: it is up to the designer to define the complexity of the agent hierarchy.The master agent may also contain a mix of proxies and MBeans for other MIBs. In the proxy example, the master agent exposes the DEMO MIB through local MBeans and a subset of the RFC1213 MIB through a proxy.Example 9-1 MBeanServerImpl server; ObjectName snmpObjName; ObjectName localMibObjName; ObjectName remoteMibObjName; int htmlPort = 8082; int snmpPort = 8085; // read sub-agent connection info from the command line String host = argv[0]; String port = argv[1]; try { server = MBeanServerFactory.createMBeanServer(); String domain = server.getDefaultDomain(); // Create and start the HTML adaptor. [...] // Create and start the SNMP adaptor. [...] // Create, initialize, and bind the local MIB Demo. // localMibObjName = new ObjectName("snmp:class=DEMO_MIB"); server.registerMBean(localMib, localMibObjName); localMib.setSnmpAdaptorName(snmpObjName); // Create and initialize the SNMP proxy. // remoteMibObjName = new ObjectName("snmp:class=proxy"); SnmpMibAgentImpl remoteMib = new SnmpMibAgentImpl(); server.registerMBean(remoteMib, remoteMibObjName); remoteMib.initializeProxy(host, Integer.parseInt(port), "1.3.6.1.2.1"); // Bind the MIB proxy to the SNMP adaptor // ((SnmpMibAgent)remoteMib).setSnmpAdaptorName(snmpObjName); } catch (Exception e) { e.printStackTrace(); java.lang.System.exit(1); }We register the proxy object as any other MBean and then initialize it. We call the initialize method of the proxy, giving the host and port of the sub-agent it must communicate with and the root OID of the MIB or subset that it represents.A single proxy object can serve several MIBs on a sub-agent, and in this case, the root OID is the common prefix of all objects. However, the OIDs of all proxies and MIBs in an agent must be distinct, none may be a substring of another (see "Binding the MIB MBeans"). Finally, we bind the proxy to the SNMP adaptor just as we would a MIB MBean.The sub-agent in our example is a stand-alone agent which serves a subset of the RFC1213 MIB. Since it implements no proxies of its own, it is just a plain agent which responds to SNMP management requests that happen to originate from a proxy object. Any SNMP manager could also send requests to this agent.Stand-alone agents are covered in "Stand-Alone SNMP Agents". Since this stand-alone agent contains no code that is specific to its role as a sub-agent, we will not repeat its program listing here. The StandAloneAgent.java file only contains some extra code for reading its assigned port from the command line. We will use this to launch the agent on a known port to which the proxy can connect.The manager application is not affected by proxies in the agents to which it sends requests. It sends the requests to the master agent, in the same way that it would send a request for a MIB that is not served by a proxy. In fact, the SNMP manager cannot even distinguish between a MIB served by an agent and another MIB served through a proxy in the agent, except perhaps by analyzing the values returned.There is one consideration for proxies, and that is the timeout interval. Since the proxy issues another request and only answers at the end of its timeout, the manager must have a longer timeout. The manager should be designed with some knowledge of all sub-agents in a hierarchy, so that the timeout can take into account all proxy delays and the multiple communication times.As with any manager application written with the SNMP manager API, the manager in the proxy example must have access to the OID table objects that represent the MIBs that it will manage. Here is the code to initialize the manager:Example 9-2 String host = argv[0]; String port = argv[1]; // Initialize the SNMP Manager API. // Specify the OidTables containing all the MIB Demo and MIB II knowledge. // Use the OidTables generated by mibgen when compiling MIB Demo and MIB II. // SnmpOidDatabaseSupport oidDB = new SnmpOidDatabaseSupport(); SnmpOid.setSnmpOidTable(oidDB); oidDB.add(new RFC1213_MIBOidTable()); oidDB.add(new DEMO_MIBOidTable()); SnmpPeer agent = new SnmpPeer(host, Integer.parseInt(port)); SnmpParameters params = new SnmpParameters("public", "private"); SnmpSession session = new SnmpSession("Manager session"); // We update the time out to let the agent enough time // to do his job before retry. // agent.setTimeout(100000); agent.setSnmpParam(params); session.setDefaultPeer(agent);The rest of the manager application is the code for synchronous get and set requests, similar to the one shown in "The Synchronous Manager Example".The SNMP proxy is an extension of the abstract SnmpMibAgent which implements all of its abstract methods and can be instantiated. The proxy implements a synchronous SNMP manager that forwards the requests to the sub-agent. It does some error fixing for SNMPv2 requests but doesn't claim to be extensive. In any case, the SNMP proxy implementation is provided as an example and Sun Microsystems makes no claim as to its suitability for any particular usage.Note - The implementation of the example proxy does not support the getBulk request or the check method that allows the SNMP Walk request.Before it is used, the proxy must be initialized with the hostname and port of the sub-agent. It uses this information to create SNMP parameter and SNMP peer objects. It then creates three SNMP sessions:One for SNMPv1 requestsOne for SNMPv2 requestsOne for failed SNMPv2 requests that are retried as v1 requestsExample 9-3 public void initializeProxy(String h, int p, String strOid, String name) throws UnknownHostException, SnmpStatusException { host = h; port = p; oid = strOid; mibName = name; // Initialization for SNMP v1 protocol. // SnmpParameters paramsV1 = new SnmpParameters("public", "private"); paramsV1.setProtocolVersion(SnmpDefinitions.snmpVersionOne); SnmpPeer peerV1 = new SnmpPeer(host, port); peerV1.setSnmpParam(paramsV1); sessionV1 = new SnmpSession("SnmpMibAgentImpl session V1"); sessionV1.setDefaultPeer(peerV1); // Using SNMP v1 protocol, errors are not fixed and // forwarded to the manager sessionV1.snmpOptions.setPduFixedOnError(false); // Initialization for SNMP v2 protocol. // SnmpParameters paramsV2 = new SnmpParameters("public", "private"); paramsV2.setProtocolVersion(SnmpDefinitions.snmpVersionTwo); SnmpPeer peerV2 = new SnmpPeer(host, port); peerV2.setSnmpParam(paramsV2); // If we get an error, we don't retry the request using SNMP v2, // but we try the request using SNMP v1 peerV2.setMaxRetries(0); sessionV2 = new SnmpSession("SnmpMibAgentImpl session V2"); sessionV2.setDefaultPeer(peerV2); // Using SNMP v2 protocol, the error is fixed // sessionV2.snmpOptions.setPduFixedOnError(true); // Initialization for SNMP v2 protocol simulated // using SNMP v1 protocol // sessionV2WithV1 = new SnmpSession("SnmpMibAgentImpl session V2 with V1"); sessionV2WithV1.setDefaultPeer(peerV1); // Simulating SNMP v2 with SNMP v1 protocol, the error is fixed. // sessionV2WithV1.snmpOptions.setPduFixedOnError(true); }The proxy exposes the public methods for handling requests, and then this algorithm for reducing errors is implemented by internal methods. Roughly, the proxy must determine the version of the incoming request and handle it as promised. Version 1 requests that timeout or fail are dropped, and v2 requests that timeout or fail are retried as v1 requests. Here we only show the code for implementing the get method.Example 9-4 // the exposed method public void get(Vector list, int version) throws SnmpStatusException { java.lang.System.out.println( "Proxy: Sending get request to SNMP sub-agent on " + host + " using port " + port); // Request using SNMP v1 protocol if (version == SnmpDefinitions.snmpVersionOne) { get(list, version, sessionV1); } // Request using SNMP v2 protocol. if (version == SnmpDefinitions.snmpVersionTwo) { get(list, version, sessionV2); } } // the internal implementation private void get(Vector list, int version, SnmpSession session) throws SnmpStatusException { SnmpVarbindList varbindlist = setVarBindList(list); try { request = session.snmpGet(null, varbindlist); } catch (SnmpStatusException e) { throw new SnmpStatusException(SnmpDefinitions.snmpRspGenErr, 0); } java.lang.System.out.println("\nRequest:\n" + request.toString()); boolean completed = request.waitForCompletion(10000); if (completed == false) { // If the completion failed using SNMP v1, we give up if (version == SnmpDefinitions.snmpVersionOne) { java.lang.System.out.println( "\nRequest timed out: check reachability of sub-agent."); return; } // If the completion failed using SNMP v2, we try again using v1 if (version == SnmpDefinitions.snmpVersionTwo) { get(list, SnmpDefinitions.snmpVersionOne, sessionV2WithV1); return; } } int errorStatus = request.getErrorStatus(); int errorIndex = request.getErrorIndex() + 1; if (errorStatus != SnmpDefinitions.snmpRspNoError) { // If there is an error status using v1, we throw an exception if (version == SnmpDefinitions.snmpVersionOne) { throw new SnmpStatusException(errorStatus, errorIndex); } // If there is an error status using v2, we try again using v1 if (version == SnmpDefinitions.snmpVersionTwo) { get(list, SnmpDefinitions.snmpVersionOne, sessionV2WithV1); return; } } result = request.getResponseVbList(); // Update the list parameter with the result Enumeration l = list.elements(); for (Enumeration e = result.elements(); e.hasMoreElements();) { SnmpVarBind varres = (SnmpVarBind) e.nextElement(); SnmpVarBind varbind = (SnmpVarBind) l.nextElement(); varbind.value = varres.value; } }The complete list of methods that a proxy must implement are the same as for MIB MBeans represented by instances of the SnmpMib class:long[] getRootOid() - Gets the root object identifier of the MIBvoid get(java.util.Vector list, int version) - Processes a get operation.void getNext(java.util.Vector list, int version) - Processes a getNext operation.void getBulk(java.util.Vector list, int nonRepeat, int maxRepeat, int version) - Processes a getBulk operation.void check(java.util.Vector list) - Prepares a walk operation.void set(java.util.Vector list, int version) - Processes a set operation.First, we generate the MBeans for our MIBs using the mibgen tool:$ cd examplesDir/Snmp/Proxy/ $ mibgen -a -d . mib_II_subset.txt mib_demo.txtSince the proxy acts as an SNMP manager, the master agent application now needs the SNMP manager API in its classpath, for both compilation and execution. Similarly, the proxy object also needs the class representing the SNMP OID table of the MIB that it accesses on the sub-agent.These issues are resolved in our case by having all classes in the example directory and using dot (.) in our usual classpath. Replace the two MIB files with those from the patchfiles directory and then compile all of the classes in the example directory:$ cp -i patchfiles/*_MIB.java . cp: overwrite ./DEMO_MIB.java (yes/no)? y cp: overwrite ./RFC1213_MIB.java (yes/no)? y $ javac -classpath classpath -d . *.javaWe can run all three applications on the same machine as long as we choose different port numbers. Here we give commands for launching the applications from the same terminal window running the Korn shell. On the Windows NT platform, you will have to launch each application in a separate window, in which case you will not see the sequence of the merged output.First we launch the sub-agent; by default it will reply to port 8086, or we can specify a different one on the command line:$ java -classpath classpath StandAloneAgent 8090 & Adding SNMP adaptor using port 8090 Initializing the MIB RFC1213_MIBThen we launch the master agent, giving it the sub-agent's hostname and port number:$ java -classpath classpath Agent localhost 8090 & NOTE: HTML adaptor is bound on TCP port 8082 NOTE: SNMP Adaptor is bound on UDP port 8085 Initializing the MIB snmp:class=DEMO_MIB Initializing the SNMP proxy snmp:class=proxy to query host localhost using port 8090Now you can view the master agent through its HTML adaptor. In your web browser, go to the following URL: http://localhost:8082/The class=proxy MBean in the snmp domain is the proxy object, but we cannot see the MBean that it represents. In order to manage the actual MIB, we would have to connect to the sub-agent, but in our example it is a stand-alone and therefore unreachable.The name=Demo MBean in the DEMO_MIB domain is the MIB that is served locally. If we click on its name, we can see its initial values.Finally, we launch the manager application, giving it the master agent's hostname and port:$ java -classpath classpath Manager localhost 8085The manager will run through its requests to the master agent. If the output is in the correct order, there are messages from the manager issuing a request, and then the proxy which relays a request for two of the variable to the sub-agent. The proxy then prints the result it received for the two variables, then the manager receives the final response with all of the variables, including the same two that the proxy just forwarded.In the name=Demo MBean on the web browser, you should see the new values that were set in the DEMO_MIB as part of the manager's set operation.Don't forget to stop the agent applications with the following commands (just use "Control-C" if they are in separate terminal windows):$ fg java [...] Agent localhost 8090 <Control-C> ^C$ fg java [...] StandAloneAgent 8090 <Control-C> ^C$