This invention relates to computer technology, more particu- larly to software management.

Proposals in application software management are described in the following patent publications: EP-A-909057, EP-A-915419, EP-A-908816 and EP-A-909058. In particular, EP-A-909057 introduces the concept of Managed Beans or MBeans, which will be described hereinafter in more detail. MBeans may be defined as manageable software objects, bringing the possibility to manage software systems.

This invention provides improved management using such software objects.

An object of this invention is to enable flexibility in the definition of MBeans, e. g. when developing new software.

Further objects of the invention will appear in the course of this specification.

The invention applies in an object oriented software environ- ment, comprising an object processor, and at least one manageable object, e. g. an MBean. The object has public object management methods. The manageable object has a management interface, deducible from the object according to a predefined rule, which may be e. g. a naming rule.

In an embodiment, where the manageable object derives from a class, the predefined rule comprises a naming rule applied to the class name of the manageable object to designate the corresponding management interface. For example, the naming rule may comprise suffixing the class name in a predefined fashion, with the suffixed name designating a class defining said management interface.

The public management methods may comprise accessor/mutator methods for readina and/or writing attributes. The attributes

and accessor/mutator methods may correspond to each other in accordance with lexical design pattern rules, which will be described in more detail hereinafter.

Certain of the manageable object may act as a notification source, and/or an event listener, and/or monitor other objects. The object oriented software environment may also comprise a management information class (MBeanInfo), compris- ing methods capable of introspecting a manageable object.

These functions will also be described in more detail hereinafter.

The invention also encompasses: -a computer, comprising: * the above defined object oriented software environ- ment, and * a managed object server, or MBean server, capable of registering objects having a management interface, for serving management applications, * optionally, at least one link to a management appli- cation.

-a computer system, capable of riosting at least one such computer as a real or virtual machine.

-a computer network, comprising a plurality of interconnected computers, wherein at least one of the computers is a computer as above defined.

The invention also proposes a method of processing a manage- able object, which will be defined in the following descrip- tion.

Other alternative features and advantages of the invention will appear in the detailed description below and in the appended drawings, in which : -figure 1 is a general diagram of a computer system in which the invention is applicable;

-figure 2 is a general diagram of an object-oriented software environment in a computer system; -figure 3 is a partial diagram of an object software environment system; -figure 4 is an example of a computer system having a software environment in accordance with the invention; -figures 5A and 5B together define a flow chart showing an algorithm for determining how a software object may qualify as an MBean; -figures 6-A through 6-D illustrate four cases of application of the algorithm to a standard MBean; -figure 7 illustrates an example of the dot notation ; -figure 8A shows an UML (Unified Modeling Language) diagram of the"MBeanInfo"class; -figure 8B shows another UML diagram of an alternative embodiment of the"MBeanInfo"class; -figure 9A shows an UML diagram of an extension of the "MBeanInfo"class of figure 8A for open MBeans; -figure 9B shows an UML diagram of an extension of the alternative"MBeanInfo"class of figure 8B for open MBeans; -figure 10 shows the main types of components of a software environment embodying the invention; -figure 11 is a tree diagram showing an object model for exceptions; -figure 12 is a tree diagram showing another object model for runtime exceptions;

-figures 13 and 14 are flow charts showing the way of calling the registration and de-registration methods of an "MBeanRegistratior"interface; -figure 15 diagrammatically illustrates the propagation of a remote operation to an MBean; -figure 16 diagrammatically illustrates the operation of an "M-let"service; -figure 17 diagrammatically illustrates the implementation of the"M-let"service of Figure 16; -figure 18 is a tree representation of Monitor Notification types; -figure 19 is a timing diagram showing the operation of a counter Monitor; -figure 20 is a class diagram of Monitor MBeans ; -figure 21 is a timing diagram showing the operation of a String Monitor; and -figure 22 is a timing diagram showing the operation of a Gauge Monitor.

Certain of the drawings refer to the Unified Modeling Language, or UML, defined inter alia in Appendix D of the Common Information Model (CIM) specification, available on the web site of the Distributed Management Task Force (DMTF) http://www. dtmf. org/ or on the web site: http://www. rational. com/uml or in the corresponding printed documentation.

As cited in this specification, Sun, Sun Microsystems, Solaris, Java, EmbeddedJava, PersonalJava, JavaBeans, Java Naming and Directory Interface, JDBC, Enterprise JavaBeans,

Jini and Sun Spontaneous Management are trademarks of Sun Microsystems, Inc SPARC is a trademark of SPARC Interna- tional, Inc.

Additionally, the detailed description is supplemented with the following Exhibits:- -Exhibit A. 1 describes Foundation classes; -Exhibit A. 2 describes a Notification system ;<BR> -Exhibit A. 3 describes"MBeanInfo"Classes ;<BR> -Exhibit B. 1 describes"Standard MBeans" ;<BR> -Exhibit B. 2 describes"Dynamic MBeans" ;<BR> -Exhibit B. 3 describes"Open MBeans" ;<BR> -Exhibit B. 4 describes"Model MBeans" ; -Exhibit C. 1 describes a Managed Bean Server (MBean Server); -Exhibit C. 2 describes a Queries system; -Exhibit C. 3 describes an Advanced Dynamic Loading system; -Exhibit C. 4 describes a Monitoring system ; -Exhibit C. 5 describes Timer services; -Exhibit D shows examples of code, for use in other parts of the detailed description and of its Exhibits.

These Exhibits are integral part of the description of this invention. Similarly, the description below and its Exhibits will disclose a vast combination of means, in which numerous interactive aspects are novel, either independently or in combination.

These Exhibits contain rewritten portions of the priority document, i. e. French patent application FR-9907583, filed June 15,1999. In addition, the priority document in English language is incorporated by reference into this patent specification, with the following remarks: FR-9907583 is a provisional filing, based on a JMX specification intended for software users; the JMX specification is a non limiting example of application of this invention; the JMX specifica- tion also includes a variety of statements expressed in a mandatory form; while these statements may be mandatory for compliance with the JMX specification in itself, such

statements are noL intended to restrict the scope of this invention in any way.

Now, making reference to software entities imposes certain conventions in notation. For example, in the detailed description, the quote sign"and/or Italics may be used when deemed necessary for clarity, e. g. to distinguish between a basic object and another object having the same name, for example: a dynamic MBean has a"DynamicMBean"interface.

However, in code examples: -quote signs are used only when required in accordance with the rules of writing code, i. e. for string values.

-an expression framed with square brackets, e. g. [, prop- erty=value] * is optional and may be repeated if followed by * ; -a name followed with [] indicates an array.

A portion of the disclosure of this patent document contains material which is subject to copyright protection. The copyright owner has no objection to the facsimile reproduction by anyone of the patent document or the patent disclosure, as it appears in the Patent and Trademark Office patent file or records of each relevant country, but otherwise reserves all copyright and/or author's rights whatsoever.

This invention may be implemented in a computer system, or in a network comprising computer systems. The hardware of such a computer system is for example as shown in Fig. 1, where: -11 is a processor, e. g. an Ultra-Sparc (SPARC is a Trademark of SPARC International Inc); -12 is a program memory, e. g. an EPROM for BIOS; -13 is a working memory, e. g. a RAM of any suitable technol- ogy (SDRAM for example); -14 is a mass memory, e. g. one or more hard disks; -15 is a display, e. g. a monitor; -16 is a user input device, e. g. a keyboard and/or mouse; and -21 is a network interface device connected to a communica- tion medium 20, itself in communication with other computers.

Network interface device 21 may be an Ethernet device, a serial line device, or an ATM device, inter alia. Medium 20 may be based on wire cables, fiber optics, or radio-communica- tions, for example.

Data may be exchanged between the components of Figure 1 through a bus system 10, schematically shown as a single bus for simplification of the drawing. As is known, bus systems may often include a processor bus, e. g. of the PCI type, connected via appropriate bridges to e. g. an ISA bus and/or an SCSI bus.

In figure 2, the CPU and hardware of figure 1 is diagrammati- cally shown as 1. The computer system also has an operating system 3, e. g. Solaris (an operating system product and trademark of SUN MICROSYSTEMS). Operating systems other than Solaris may be used in accordance with the invention. An object supporting software 4 may be installed over operating system 3. The object supporting software 4 may e. g. include the necessary software to build a Java virtual machine or JVM.

It includes an object processor or object provider 41, e. g. the method ClassLoader () of the Java language. Object supporting software other than a JVM may be used in accordance with the invention. The object supporting software 4 may then serve to run object oriented application software 5. When required, changes in object oriented application software 5 may be made using software management tools 6. The software management tools may be designed in accordance with the JMX/JDMK specification. However, the invention may apply to other software management tools as well.

The invention may apply within a single machine as shown in figure 2. However it will more likely be applied within a distributed environment, as shown in figure 3, in the example of two machines Ml and M2, interconnected by a link 20, e. g. a network medium. The machines may have the exemplary structure of figure 1, or any equivalent structure. In figure 3, the blocks showing the same functions as in figure 2 are identified by the same reference number, immediately followed

by the machine identifier. For example the operating system of machine Ml is noted 3M1. As shown, an exemplary architec- ture may include the object oriented application software 5M1 in machine M1, and the software management tools 6M2 in machine M2, which thus may be dedicated to software manage- ment. However, many other combinations are possible, based on two machines or more. Provision for a management dedicated machine is an option. One or more machines may include both application software and management tools, as shown in figure 2. Also, each machine may support one or more Java virtual machines or other types of machines or devices.

The reader is assumed to be familiar with object oriented programming in general, more specifically with Java, still more specifically with JavaBeans. Details may be found at: http://Java. sun. com for Java http://Java. sun. com/beans/spec. html for JavaBeans and/or in the corresponding printed documentation, e. g."The Java Language Specification", J. GOSLING, Bill JOY, Guy STEELE, Addison Wesley, 1996, ISBN 0-201-63451-1.

In object oriented programming, an object may comprise properties and methods, together termed [object] members. For convenience, the methods are usually identified by their name followed with (). Where a method requires parameters, these are inserted between the two round brackets. Most of the methods are directed to the members or internal contents of the object: get () for reading a property, set () for writing a property, other property-related methods, access to other methods, etc...

A method contained in an object may be inter alia public or private, depending upon whether it is accessible (may be invoked) from outside the object, or not.

As known, when using an object oriented programming framework, e. g. Java, defining object structures (properties and methods) is generally sufficient for enabling men skilled in the art to write corresponding executable software. Thus, generally,

this specification will mainly present object structure definitions.

Object oriented programming uses"classes", which may serve the following purposes: -objects may be"instantiated"from a class, using an object constructor (in short, a constructor); in Java, a constructor is a method having the same name as the class it belongs to.

-a class may"extend"a parent class, thus inheriting the properties and methods of the parent class.

A class termed"abstract"cannot be instantiated, only inherited. A class termed"concrete"may instantiated and/or inherited. A method in a class may also be abstract: this means that the method will have to be defined in any object instantiating that class.

In Java, a given class may have only one parent class, which in turn may inherit ("extend") one parent class, etc... Other object oriented languages may support multiple inheritance, i. e. a given class may inherit several parents.

However, Java supports a special type of entity, named "interfaces". Interfaces may be viewed as a special form of classes, which may support multiple inheritance. Interfaces may basically contain abstract methods. The word"interface" is used herein to refer to such entities. It covers any similar entities which may be developed in a language other than Java.

A class may"imp_ement"an interface. This means that the class concretely defines the abstract methods existing in the interface.

JavaBeans components (in short Beans) are re-usable software components which can be manipulated visually in a builder tool, e. g. an editor or graphical use interface builder. An example of a builder tool is the Java Workshop (JWS). Further details about Beans may be found in the abundant literature,

for example in book entitled"Mastering JavaBeans"by Lawrence Vanhelsuwe, published by SYBEX (ISBN 0-7821-2097-0).

Beans share certain common defining features, providing: -a set of properties (also termed variables); -a set of methods for performing actions; and -support for events and for introspection (also termed reflection), which enables access to the structure of java objects from outside. The Java Development Kit includes a corresponding reflection API.

A JavaBean supports the so-called getter/setter pairs, defined in accordance with lexical design patterns. This is described in detail in the above cited JavaBean documentation, and will now be summarized.

One considers, for a given Bean, all the public methods, the name of which begins with one of the following prefixes: a."set", e. g. setCurrency () or setActive () ; b."get", e. g. getCurrency ()- c. Optionally,"is", e. g. isActive ().

The methods verifying a. are termed setter or mutator methods.

The methods verifying b. or c. are termed getter or accessor methods. In fact, the prefix"get"is sufficient to define getter methods; the prefix"is"is optional, and may be used e. g. for booleans where it is more suggestive in English language.

In each case, the method name is"reduced"by removing its prefix"set","get"or"is". In the above examples, the reduced method names would be currency or active. Generically, the reduced method name is noted <Myname>. Also, <type> denotes the type of an entity, e. g. int [eger], string, bool [ean], etc..., and <Myvalue> designates a value of the entity having the <type>. Formally, the above methods may now be generically represented as follows, in the example of Java code: -void set<Myname> (<Type> <Myvalue>) -<Type> get<Myname> ()

-Boolean is<Myna > (ì- Where at least one of the above public methods exists for a given Java object, <Myname> is termed an attribute of that object, with the following possibilities: -if there are both a setter method set<Myname> () and at least one of the two getter methods get<Myname> () or is<Myname> (), all accepting the same type of parameter value, the attribute <Myname> is read-write; -if there is only one of the two getter methods get<Myname> () or is<Myname> (), the attribute <Myname> is read-only, and has the type of that method; -if there are only the two getter methods get<Myname> () and is<Myname> (), all accepting a common type of parameter value, the attribute <Myname> is also read-only, and has the common type; -if there is only a"setter"method set<Myname> (), the attribute <Myname> is write-only, and has the type of that method.

In fact, the attribute may be a property of the Bean, or not. In Java (although exceptions may exist), a property <myname> may conveniently begin with a lower case letter, while a corresponding attribute (<Myname>) begins with an upper case letter.

In other words, whenever a Bean offers a pair of getter and setter methods having the same <Myname>, then they form a getter/setter pair, defining a <Myname> read-write attribute of the JavaBean. In practice, since read-only or write-only attributes are less common, the expression"getter/setter pair"is usually broadened to mean"getter and/or setter", i. e. to cover also the cases where only a getter or accessor method or only a setter or mutator method is present. A getter and/or setter pair constitute accessor/mutator method (s). In the following, the expression"accessor methods"will be used to encompass both accessors and/or mutators.

The invention is not restricted to the above examples of getter and setter methods. More generally, the invention may apply where a preselected rule enables the following: -in correspondence with a name, i. e. the attribute name, defining uniquely the names of a read method and/or of a write method associated to that attribute; -conversely, in correspondence with the names of a read method and/or of a write method, defining uniquely a name, i. e. the attribute name, associated to these methods.

Thus, those of the public methods which correspond to a getter and/or a setter method are correctly represented by the corresponding attribute. The read and/or write status of the attribute depends upon whether it corresponds to a getter method, a setter method, or both.

All the other public methods of a Bean which do not belong to a getter and/or setter pair are termed"operations".

It must be understood that the word"attribute" (of an object), as above defined, is based on accessor methods, e. g. the getter/setter pair, and also constitutes a representation of the accessor methods. This is not the same as the common meaning of the word attribute in the computer art, as used for example in an expression like"color attribute", where "attribute"refers to a property of an object, rather than to the object itself.

In EP-A-909057, it has been proposed to use Beans for managing resources in a computer system, especially a computer network. Beans used for tnis purpose are termed Managed Beans or MBeans. More generally, an MBean may be termed"managed object". In EP-A-909057, it has been generally proposed to provide each MBean with public methods enabling the management of the resource represented by that MBean. In order to avoid unduly lengthening this specification, the descriptive contents of EP-A-909057 (USSN 944,174, filed October 6,1997), EP-A-915419 (USSN 944,396, filed October 6,1997), EP-A-908816 (USSN 944,383, fi ed crobe..", 1997 ; and EP-A-909058 (USSN

946,140, filed October 6,1997) are incorporated herein by reference.

Generally, the above cited prior patent applications define: managed objects or MBeans, a framework for registering MBeans, an MBean repository service for storing pointers to registered MBeans, a filtering service enabling selection of MBeans, a metadata service, an access control service, an event service, a relationship service, a dynamic native library loading service, a managed object adaptor server.

Now, managing a resource necessitates that the resource is "instrumented", i. e. that access is enabled to corresponding information on that resource. The instrumentation should obey preselected general rules (e. g. the JMX rules). Thus, in accordance with another definition, MBeans are software objects which implement not only resources, but also the instrumentation of such resources, in accordance with pre- defined rules. Conversely, the instrumentation of a given resource may be provided by one or more MBeans.

In accordance with another aspect of this invention, there is defined for each MBean a management interface, comprising: -attributes, each corresponding to a getter/setter pair of public methods, and -operations, comprising those of the public methods which do not belong to getter/setter pairs.

Thus, in an example, an MBean may be viewed as a Java object that implements specified interfaces in accordance with specified rules, e. g. specified lexical design patterns. The exposed interface may be controlled: for example, an MBean attribute can allow read-only or read-write access.

In accordance with an embodiment of this invention, a software management framework may comprise: -an instrumentation level, comprising"MBeans", -an agent level, comprising an MBean server and optional Management services,

-a manager level.

In an exemplary embodiment (Figure 4), based illustratively on two Java virtual machines 4M1 and 4M2, implementing the agent level and instrumentation level: a) the manager level comprises e. g. a JMX-compliant Management Application 1100, a Web Browser 1110, and a Proprietary Management Application 1120 ; b) in the"agent level" : bl) machine 4M1 has an MBean server 2100 having Protocol Connectors or Adaptors 2101,2102, enabling communication with JMX-compliant Management Application 1100, and Web Browser 1110, respectively. Proprietary Management Application 1120 needs a JMX Manager 1122 to be connected with MBean server 2100 via protocol connector 2103. The agent level may further include a service module 2110; b2) machine 4M2 has two MBean servers 2200 and 2300, illustratively provided with Protocol Connectors or Adaptors 2201,2202, respectively, interconnected with JMX manager 1122.

C) at the"instrumentation level" : cl) machine 4M1 has objects 3101 and 3102, which are MBeans, i. e. beans registered in MBean server 2100, and a plain JavaBean component 3103, which is a non MBean object, i. e. is not registered in MBean server 2100.

C2) machine 4M2 has objects 3201 and 3202, registered in MBean server 2200, and objects 3301 and 3302, registered in MBean server 2300.

The MBean objects have a management interface, e. g. 3101-I for MBean 3101 (which is supposed to be a standard MBean). Only the interface label 3101-1 is shown in figure 4, to avoid too much complexity in the drawing.

The elements of an embodiment of this invention will now be described in more detail.

A given object oriented programming framework uses fundamental entities (object definitions). Usually, e. g. in Java, these entities are defined as"classes".

The fundamental entities or"Foundation classes"used in the exemplary embodiment of this detailed description are defined in Exhibit A. l.

The main components of the instrumentation level are the MBeans, which may support a Notification Model. The instrumentation level relates to rendering resources manageable. In computer systems, including distributed computer systems, the concept of"resource"now goes far beyond its traditional hardware meaning. A resource may be e. g. an application, an implementation of a service, a device, a user, and so forth. It may be developed e. g. in Java, or offer a Java wrapper.

In the example, MBeans are Java objects that conform to design patterns derived from the JavaBeans component model. In fact, the MBeans in the embodiment follow specified design patterns and interfaces, in order to provide instrumentation of managed resources in a standardized way.

In addition, the instrumentation level may also specify a notification mechanism, e. g. as described in Exhibit A. 2. This allows MBeans to generate and propagate notification events to components of the other levels. The notification model may be based on the Java event model. In the context of the agent, notifications are emitted by MBean instances, as well as by the MBean server.

A embodiment of this invention may also provide services that allow distribution of this notification model, thus allowing a management application to listen to MBean and MBean server events remotely. Such a model can be made transparent to both the event producer and the event listener. Another mode of operation may also allow the event propagation infrastructure

to store the event until further %-f ; rieval by the management application.

In accordance with another aspect of this invention, the interface of an MBean may be determined using an MBeanInfo class, described in general terms in Exhibit A. 3. The MBeanInfo class comprises methods capable of introspecting a manageable object, to determine its attributes, operations, and also the notifications it may process, and, finally, its constructors. The MBeanInfo class also offers an object structure to expose the management interface of an MBean, i. e. again basically its attributes and operations, optionally the notifications it may process, and/or its constructors.

In accordance with still another aspect of this invention, the MBeans may be: -standard MBeans, as described in Exhibit B. 1, Standard MBeans are the simplest to design and implement, their management interface is described by their method names; -Dynamic MBeans, as described in Exhibit B. 2, Dynamic MBeans implement a pre-defined interface, and expose their management interface at run-time for greatest flexibility.

As it will be understood, existing objects can easily be evolved to produce standard MBeans or wrapped as dynamic MBeans, thus making existing resources manageable with minimum effort.

Additionally, anyone of the following particular types of dynamic MBeans may be implemented optionally: -Open MBeans (described in Exhibit B. 3) are dynamic MBeans which rely on basic data types for universal manageability and self-description for user-friendliness.

-Model MBeans (described in Exhibit B. 4) are dynamic MBeans that are fully configurable and self-described at run-time.

They provide a generic MBean class, which may be made always available.

Once instrumented (by one or more MBeans), a resource may be managed through a agent in the agent level. Generally, the agent level implements agents, adapted to work with resources being instrumented according to the Instrumentation level, i. e. using MBeans.

Basically, one may define standard agent"to manage resources, comprising: -a managed object server or MBean server, -a set of management services for handling MBeans, and -at least one communications adaptor or connector.

Thus, an MBean server relies on protocol adaptors and/or connectors to make the agent accessible from management applications outside the agent's Java Virtual Machine: -each adaptor provides a view through a specific communications protocol of all MBeans instantiated and registered in the MBean server. They enable all agent level operations to be available to a remote management application.

For an agent to be managed, it must include at least one protocol adaptor. However, an agent can include any number of these, allowing it to be managed by multiple management applications, through different protocols.

An agent may be implemented e. g. as follows: -embedded in the machine that hosts the manageable resources, e. g. when a Java Virtual Machine is available in that machine; -instantiated into a mediation/concentrator element when the managed resource only offers a proprietary (non-Java) environment.

An exemplary reference implementation of the agent is a set of Java classes which provide an MBean server, all agent services and communicazions means. The MBean server classes and functions are described in Exhibit C. l.

Each object that needs to be accessible from outside the agent's Java Virtual Machine should be registered as an MBean by an MBean server. Such objects may include inter alia: -the resources an application needs to manage, -value-added services provided to help manage resources; and -components of the infrastructure that can be managed.

As noted, the Agent level comprises the MBean server, and management services which enable the MBean server to integrate management intelligence for more autonomy and performance.

Briefly, the MBean server is a registry for objects which are exposed to management operations in an agent. Any object registered with the MBean server becomes visible to management applications. Any JavaBeans component one wants to manage from outside the agent's Java Virtual Machine should be registered as an MBean on the server. MBeans may be instantiated and registered by: -another MBean, -the agent itself, -a management application.

When an MBean is registered, it is assigned a unique object name. A management application uses the object name to identify the object on which it is to perform a management operation.

Management Services may be used to perform management operations on other MBeans. By including management intelligence in the agent, these services enhance the added- value of the agents. The following services may be defined: -queries and filtering, described in Exhibit C. 2; this helps applications find the MBeans on which to perform operations, based on object name and current attribute value criteria. Query expressions may be built in order to retrieve collections of MBeans in one operation. The query expressions are based on the values of MBean attributes. The query mechanism may be used

both by the agent and by the manager to perform filtered retrieval of MBeans.

-dynamic class leading, described in Exhibit C. 3; this downloads and instantiates new classes and native libraries dynamically from an arbitrary location as they are needed. _ -monitors, described in Exhibit C. 4; they are fully configurable to observe numerical values and strings and be notified of several types of changes.

-timers, described in Exhibit C. 5; they provide a scheduling mechanism based on a period notification ("heartbeat").

Optionally, implementing some or all of the above described components and management services as MBeans enables them to benefit from the infrastructure of the present system and offer a management interface. Corresponding compiled MBean classes may be stored at any location specified in the agent e. g. in the usual"CLASSPATH"environment variable of Java, or at a remote site, when using Advanced Dynamic Loading (to be described later in this specification).

Such an architecture allows the following operations to be performed on an agent running in a Java Virtual Machine, for example: -Manage existing MBeans by: -Listing MBeans -Getting their attribute values -Changing their attribute values -Performing operations defined by the MBeans -Getting notifications emitted by MBeans -Discovering the management interface of MBeans -Instantiate and register new MBeans from: . Java classes already loaded into the agent . New classes downloaded either from the local machine, or from the network

After having presented ar exemplary software framework, various aspects of the invention will now be discussed in more detail.

As described in EP-A-909057, MBeans are software objects, e. g. JavaBeans, offering management methods. However, in EP-A- 909057, these management methods are simply a part of the other attributes and methods contained in the software object or MBean.

In accordance with an aspect of this invention, an MBean is given a distinct management interface, which includes only the management oriented members of the MBean: e. g. the management methods, the events and the introspection.

Thus, an MBean may be a concrete Java class that includes the following instrumentation: -a public constructor, allowing the MBean to be instantiated by an agent on demand from a management application, -the implementation of an MBean interface, -optionally, an implementation of a notifying interface, e. g. the"NotificationBroadcaster"interface described in Exhibit A. 2.

A requirement on MBeans is that they cannot be abstract classes. Abstract classes cannot be instantiated and therefore cannot be managed. The methods of an MBean must all be implemented so that the MBean class can be instantiated, and the instance can be managed.

In accordance with another aspec-of this invention, a "standard MBean"is a class which implements a corresponding MBean interface. The MBean interface of an MBean is determined from an identifier of the MBean in a unique fashion.

Optionally, inheritance is taken into account, if required.

Although other possibilities exist, the MBean interface of an MBean may be deduced from the name of the MBean. For example, if <MyClass> denotes the name of an MBean, the corresponding

interface (if any) would be named: <MyClass>MBean, i. e. by adding"MBean"to the MBean name <MyClass>.

The"standard MBean"type of instrumentation may be used when developing new manageable resources. When developing a Java class from the standard-MBean interface, exposes the resource to be managed directly through its attributes and operations. As defined hereinabove, attributes are internal entities for which there exist public accessor method (s).

Operations are the other methods of the class that are available to managers. All of these methods are defined statically in the MBean interface and visible to an agent through introspection. This is the simples way of instrumenting a new resource.

Preferably, the management interface <MyClass>MBean of a standard MBean deriving from the <MyClass> class is used as follows: -all public methods of the <MyClass> class are considered.

-a first group is made with those of the public methods which qualify as accessor methods, i. e. define attributes.

-a second group is made with those of the public methods which do not qualify as accessor methods, i. e. are "operations" ; alternatively, only part of the non-accessor public methods could qualify as"operations", relying e. g. on a predefined filtering criterion, which may use naming rules. This might be used to eliminate certain public methods which in no case should be part of the management interface.

-finally, the methods available for management in each group are restricted to those of the methods which are listed in the management interface <MyClass>MBean. This is illustrated in the MyClass Example MBean, described in Exhibit B. 1 with reference to CODE EXAMPLE CE-2: among the public methods defined in the MyClass Java class, getHidden () and setHidden () qualify as accessor methods; however, they will not be part of the management interface of the MyClass MBean, since they are not listed in the MyClassMBean interface. Although no illustration is given, a public non-accessor method

("operation") may also be ignored in the management interface, when not listed in <MyClass>MBean.

When writing an MBean, the developer does not necessarily have to provide a constructor for it: when a Java class does not define any constructor,-the Java compiler automatically provides a public"default constructor" ; that is, a constructor which takes no arguments.

If there is a need to define one or several (non-default) constructors, then in order to allow an agent to do the instantiation, the developer must explicitly define at least one constructor as public. This is shown in CODE EXAMPLE CE-1, which also shows that the public constructor may have any number and type of arguments. In addition, an MBean can have any number of public constructors, which are all available to a management application through the MBean's agent.

Standard MBeans may be used for straightforward management structures, where the structure of managed data is well defined in advance and unlikely to change often. In such cases, standard MBeans provide the quickest and easiest way to instrument manageable resources.

However, when the data structures are likely to evolve often over time, the instrumentation must provide more flexibility, such as being determined dynamically at run-time. The dynamic MBeans bring this adaptability to the JMX specification and provide an alternative instrumentation with more elaborate management capabilities.

A dynamic MBean differs from a standard MBean by the following: i. Dynamic MBeans are resources tha are instrumented through a pre-defined interface which exposes the attributes and operations only at run-time. Instead of exposing them directly through method names, dynamic MBeans implement a method which returns all attributes and operation signatures. Since the

names of the attributes and operations are determined dynamically, thé MBeans provide great flexibility when instrumenting existing resources. An MBean which implements the"DynamicMBean"interface provides a mapping for existing resources which do not follow standard MBean design patterns. Instead of introspection,-agents call the method of the MBean which determines the name of the attributes and operations it exposes. ii. When developing a Java class implementing the "DynamicMBean"interface, attributes and operations are exposed indirectly through methods. Instead of introspection, agents now call one method to find the name and nature of attributes and operations. Then when accessing an attribute or operation, the agent calls a generic"getter","setter"or "invoke"method whose argument is the name of the attribute or operation. Thus, Dynamic MBeans enable to rapidly instrument existing resources and other legacy code objects one wishes to manage. iii. certain elements of the instrumentation of a dynamic MBean can be controlled at runtime.

The interface implemented by the MBean determines how it will be developed, not how it will be managed. In fact, when both standard MBeans and dynamic MBeans are being managed in a agent, management applications can handle them in a similar manner. The agents handle both types of instrumentation transparently.

Like standard MBeans, dynamic MBeans can also inherit their instrumentation from a superclass. Unless the subclass redefines the method which exposes the management interface, the subclass will have the same attributes and operations as its superclass.

Thus, in order for a resource object to be recognized as a dynamic MBean by the agent, its Java class or one of its superclasses must implement the"DynamicMBean"public

interface. Preferably, an MBean is not allowed to implement both the"Dynam. _MBean"interface and its own"MBean" interface with standard design patterns. The agent verifies that all MBean are either dynamic or standard but not both at the same time.

In an example, the"DynamicMBean"interface may have the method signatures shown in section A of Exhibit B. 2. The behavior of Dynamic MBeans is described in section B. of Exhibit B. 2.

Instrumentation developers may choose the management scheme which fits with the nature of their manageable resources.

Although combined use of standard MBeans and Dynamic MBeans has advantages, it is possible to use standard MBeans only, or to use standard MBeans in combination with another type of MBeans which would not be the Dynamic MBeans. For example, it is possible to use MBeans which are pure notification sources, with no management interface. Preferably, such other type of MBeans are identifiable from a preselected rule specific to their type.

The inheritance patterns of MBeans will now be discussed.

As objects, MBeans may inherit from parents. This must be taken into account by the agents, when trying to determine the management interface of an MBean.

The introspection of an MBean is the process that an agent uses to determine the management interface of an MBean being registered in that agent. The introspection algorithm is applied at run-time by an agent. One of the problems with this algorithm is to determine how the inheritance scheme of an MBean influences its management interface. Two cases are considered: -when introspecting a standard MBean, the management interface may be defined by the design patterns used in its "MBean"interface. Since interfaces may also extend parent interfaces, all public methods in the inheritance tree of the

interface are also considered. However, in an alternative embodiment, it would also ne possible to ignore the inheritance tree.

-when introspecting a dynamic MBean, the management interface may be given by a method call (e. g."getMBeanInfo ()").

Thus, in either case, the introspection algorithm determines the names of the attributes and operations that are exposed for the given resource.

An example of the introspection algorithm will now be described, with reference to the flow-chart shown in figures 5A and 5B. The example involves a given Java object (starting step 500), and intends to determine whether the Java object is"compliant", i. e. qualifies as an MBean in accordance with the JMX specification, thus being a JMX manageable resource.

In the flow chart: -Step 502 accesses the class of the object, using e. g. the getClass () method of Java. The returned class is noted <classname>. If any, superclasses, i. e. classes from which <classname> inherits, are also determined, e. g. from the keyword"extends"in Java. The name of a such superclass is generically noted <superclassname>.

-Step 504 determines whether <classname> is a concrete class, i. e. does not include the"abstract"modifier keyword. If <classname> is abstract, step 506 qualifies the object as non compliant (not an MBean), and goes to the End (the End steps are not labeled for simplification).

-If step 504 determines that <classname> is a concrete class, then step 506 scans the constructors available in <classname>, until finding a public constructor or having scanned all of them. If no public constructor is available, step 510 qualifies the object as non compliant, and goes to the End.

-If a public constructor is found, then step 512 determines if at least one of the following conditions is met, and, if not, step 514 qualifies the object as non compliant, and goes to the End. The conditions are:

* whether <classname> either has a <classname>MBean interface (f rst potentiai-1s-erface), or implements a Dynamic MBean interface (second potential interface); * whether a superclass of <classname> (if any) either has a <superclassname>MBean interface (first potential interface through a parent class), or implements a Dynamic MBean interface (second potential interface through a parent class).

The fact a class implements a Dynamic MBean interface may be tested e. g. by inspecting the"implements"keyword of Java in the class.

-If at least one of the conditions of step 514 is met, then, step 516 tests whether <classname> meets both the first potential interface and second potential interface conditions, e. g. is both implementing a dynamic MBean interface and a <classname>MBean interface. If so, step 518 qualifies the object as non compliant, and goes to the End. Thus, in the example, a class which would qualify as a Dynamic MBean from its <classname>, but as a standard MBean from its superclass is not compliant; similarly, a class which would qualify as a standard MBean from its <classname>, but as a Dynamic MBean from its superclass is not compliant.

-If only one interface is implemented, then step 530 tests whether <classname> implements the first potential interface, i. e. has a <classname>MBean interface (first potential interface). If not, then, in view of step 516, step 532 qualifies the object as a compliant Dynamic MBean, and goes to the End.

-at this point, the given object may only implement the first potential interface, either through a <classname>MBean interface, or through a <superclassname>MBean interface.

(In the drawing,"<classname>MBean interface"covers both cases). Turning to figure 5B, step 540 scans the <classname>MBean interface (or the <superclassname>MBean interface, if appropriate) to kno ; all its potential getter methods, having the form get<Myname> () or is<Myname> (). If two are found with the same <Myname> section, e. g. the interface contains both an isXX () method and a getXX () method, then step 542 qualifies the object as non compliant, and goes to the

End. Steps 540 and 542 are optional and may be omitted, since coexistence of an sXXr) method ar. d a getXX t) method might be acceptable as well.

-step 544 again scans the <classname>MBean interface (or the <superclassname>MBean interface, if appropriate) to know all its potential setter methods, having the form set<Myname> (). If two methods are found with the same <Myname> section, but with different types, then step 546 qualifies the object as non compliant, and goes to the End.

-now, step 548 again scans the <classname>MBean interface (or the <superclassname>MBean interface, if appropriate) to know all its potential getter and/or setter methods, having the form get<Myname> () or is<Myname> () or set<Myname> (). In fact, due to step 540 (if implemented), the only possibilities are a getXX ()/setXX () pair or an isXX ()/setXX () pair. If two such methods in the same pair (with same XX) have different types for XX, then step 550 qualifies the object as non compliant, and goes to the End.

-otherwise, step 552 qualifies the object as a compliant standard MBean, and goes to the End.

Several alternatives may be contemplated. For example: -a common scanning of the interface methods may be made before implementing steps 540,544 and 548; -in another system (different from JMX), where no Dynamic MBeans would be provided for, step 512 would be restricted to testing the implementation of a <classname>MBean interface, or of a <superclassname>MBean interface (if appropriate); steps 516,518,530 and 532 would be omitted.

The idea is as follows: <BR> -If the"MyClass"MBean implememts a"MyClassMBean"interface (first potential interface), then only the methods listed in the interface are considered among all the methods of the MBean. The methods of the MBean includes those it inherits, just as the"MyClassMBean"interface may extend another interface and inherit methods which are also considered. The design patterns are then used to identify the attributes and operations from the method names in"MyClassMBean". A

corresponding MBeanInfo object may be constructed, usine the "MyClassMBean"interface, e. g. when registering the MBean in the Mbean server.

-If"MyClass"implements the"DynamicMBean"interface (second potential interface), then the return value of its "getMBeanInfo"method will list the attributes and operations of the resource, in the form of an MbeanInfo object. The "getMBeanInfo"method may be prepared when designing the Dynamic MBean.

-If the MBean implements neither"MyClassMBean"nor "DynamicMBean", the inheritance tree of"MyClass"is examined, looking for any superclass that implements either its own "MBean"interface or"DynamicMBean".

-If there is an ancestor called"SuperClass"that implements "SuperClassMBean", the design patterns are used to derive the attributes and operations from"SuperClassMBean". In this case, the MBean"MyClass"then has the same management interface as the MBean"SuperClass".

-If there is an ancestor called"SuperClass"that implements the"DynamicMBean"interface, then its own getMBeanInfo () method will list the attributes and operations. In this case, the MBean"MyClass"also has the same management interface as the MBean"SuperClass".

-When there is no superclass implementing its own"MBean" interface or the"DynamicMBean"interface,"MyClass"is not an MBean.

In short, the introspection algorithm determines the management interface of an MBean from its inheritance scheme. For dynamic MBeans, the attributes and operations are fully defined by the information method of the class or of the nearest superclass which implements the DynamicMBean interface.

The management interface determined by the introspection algorithm will now be described for standard MBeans in accordance with this invention, with reference to Figures 6A to 6D. In these figures, the class fields al, a2,.. stand for

attributes or operations recognized by the design patterns for standard MBeans: -in the simples case (Fig. 6p.', ciass"A"implements class "AMBean", which therefore defines the management interface for A: {al, a2}; -if class"B"extends"A"without defining its own MBean interface (Fig. 6B), then"B"alsc has the same management interface: {al, a2}; -if class"B"does implement the"BMBean"interface (Fig.

6C), then this defines the only management interface considered for B: {b2}; -in the case of Fig. 6D, the"BMBean"interface and all interfaces it extends make up the management interface for the elements which"B"defines or inherits: {al, a2, b2}. Whether or not"A"implements"AMBean"makes no difference with regards to"B".

Various combinations of these example cases are also possible. In general, a standard MBean's management interface is defined by the closest implementation of an MBean interface in its class'inheritance tree. This definition includes all attributes and operations which the MBean interface itself inherits, provided that they are also present in, or inherited by the given MBean.

By using this invention, an MBeanServer in an agent may quickly and unequivocally analyze the objects being under its control, determine whether they qualify as MBeans, and register (or unregister) them as such.

Thus, an agent, e. g. a JMX agent, may be viewed as a management entity which runs in a JVM (or other object oriented software environment), composed of an MBeanServer, a set of MBeans representing managed resources, possibly some management services also implemented as MBeans, and at least one protocol adaptor or connector, for use by at least one management application.

Protocol adaptors and connectors provide a view through a specific protocol of the MBeans instantiated and registered in the MBean server, for remote management applications. They enable a management application outside the JVM to: -Get or set attributes of existing MBeans -Perform operaticns on existing MBeans -Instantiate and register new MBeans -Register for and receive notifications emitted by MBeans Connectors are used to connect an agent with a remote JMX- enabled management application; that is: a management application developed using JMX manager services, for example.

This kind of communication involves a pair of components: one connector server in the agent, and one peer entity in the manager. They are in charge of conveying management operations transparently point-to-point over a specific protocol.

Protocol adaptors are used to connect an agent with proprietary management applications which support a JMX agent, for example. They adapt the MBean server interface to a specific protocol and possibly to a different information model.

Both connector servers and protocol adaptors use the services of the MBean server in order to apply the management operation they receive to the MBeans, and in order to forward notifications to the management application.

For an agent to be manageable, it should include at least one protocol adaptor or connector server. However, an agent can include any number of these, allowing it to be managed remotely through different protocols simultaneously.

The adaptors and connectors are preferably implemented as standard or dynamic MBeans. This allows them to be managed as well as to be loaded and unloaded dynamically, as needed.

Although numerous other applications may be contemplated, this invention brings important advances, which are used in the

above mentioned JMX specification. Where used hereinafter for an entity, the qualifier JMX indicates an entity complying with the JMX specification. However, as noted earlier, the present invention is not limited to the JMX specification, and this discussion is merely exemplary.

A JMX compliant MBean is a standard MBean or a dynamic MBean, but not both, as above defined. A JMX Agent implementation should provide at least an MBean server, and, for optional use, Advanced Dynamic Loading services. The implementation of the other components is optional. However, when an optional component is implemented, it should be implemented in whole, and according to the JMX Specification.

Generally, a management application may be able to perform at least some of the following operations, using an agent (e. g. a JMX agent): -Manage existing MBeans by: . Getting their attribute values . Changing their attribute values . Performing operations on them -Get notifications emitted by MBeans.

-Instantiate and register new MBeans from: . Java classes already loaded into the agent JVM . New classes downloaded either from the local machine, or from the network.

When fully implemented, the JMX agent architecture may comprise, as shown in figure 4: -MBeans, which represent managed resources, -The MBeanServer, which is an important part of this architecture and the central registry for MBeans. All management operations applied to MBeans go through the MBeanServer.

-Management services implemented as MBeans, which can be either components defined in this Specification, or services developed by third parties. The management service MBeans defined by the JMX specification provide:

. Querying and filtering of all registered MBeans based upon dynamic attribute values . Advanced Dynamic Loading services which allow the agent to instantiate MBeans using java classes and native libraries dynamically downloaded from the network . Monitoring services responsible for monitoring attribute values in other MBeans and notifying their listeners upon detecting certain conditions . Timer services that can send notifications at pre- determined intervals -Protocol adaptors and connectors, which are the means by which management applications may access an agent, in particular when they are outside of its JVM.

When a management application needs to manage a new MBean (resource), it may obtain the MBeanInfo object for that resource in the MBean server in which the MBean is registered.

If the MBean is a standard one, the MBean server knows or builds the MBeanInfo object from the corresponding "<Myclass>MBean" ; if the MBean is a Dynamic one, the MBean server knows or builds the MBeanInfo object from a getMBeanInfo () call to the MBean.

As defined in the JMX specification, the Java Management extensions (JMX) intend to provide Java developers across all industries with the means to instrument Java code, create smart Java agents, implement distributed management middleware and managers, and smoothly integrate these solutions into existing management systems. The reference to JMX (and the corresponding JMX specification ! is for clarity of description; any and all inventive aspects may apply to other software environments as well.

Resources that provide instrumentation in conformance with JMX are qualified as JMX Manageable Resources. JMX manageable resources can be executed e. g. upon JDK 1.1. x, Embedded Java, Personal Java, or Java TM 2 Platform, Standard Edition, v 1.2.

Agents which comply with the JMX specification are aualified as JMX Agents. In fact, agents may include optional services.

Thus, for an agent, JMX compliance may be applied as follows: -the agent has all mandatory JMX components ; and -the optional components declared by the agent are fully implemented in accordance-with the JMX specification.

JMX Agents may run on any Java2 platform, e. g. the Java2 Platform Standard Edition, or smaller Java platforms, for example PersonalJava TM, and EmbeddedJava, once they are Java2 compatible. JMX agents are automatically integrated by JMX manager services. But they can also be used by any non-JMX compliant systems or applications that support JMX agents.

This invention is not restricted to the above described embodiment, and has several features of broader interest.

As proposed, MBeans do not require knowledge of the agent with which they operate, and are flexible, simple, and easy to implement. Developers of applications, services or devices, can make their products manageable in a standard way without having to understand or invest in complex management systems.

Conversely, an agent does not need to know which resources it will serve: any manageable resource may use any agent that offers the services it requires. In the example, JMX agents are implemented by developers of management systems, who can build their products in a standard way, without having to understand the semantics of the JMX manageable resources, or the functions of the management applications.

Developers of applications and devices are free to choose the granularity of objects that should be instrumented as MBeans.

An MBean might represent the smallest object in an application, or it could represent the entire application.

Application components designed with their management interface in mind may typically be written as MBeans. MBeans may also be used as wrappers for legacy code (pre-existing code) without a management interface or as proxies for code with a legacy (pre-existing) management interface.

In other words, this invention defines a framework for management components that can operate as a manager or agent.

These components can be replicated, and can cooperate with one another to provide distributed, scalable management functions.

Java-based pure management functions can be plugged into this framework, in order to: -Provide an interface for management applications to interact with the agent through what are called connectors; -Distribute management information from high-level management platforms to numerous JMX agents ; -Consolidate management information coming from numerous JMX agents into logical views that are relevant to the end user's business operations ; -Provide security.

It will be appreciated that the MBean technology, as proposed in this invention, brings unique facilities to the management level: portability, on-demand deployment of management functionality, dynamic and mobile management services, and security. Managers access an agent's MBeans through the communications adaptor and provided services. However, JMX agents do not require knowledge of the remote management applications that use them.

More generally, this invention provides an improved software management environment, a non limiting example of which is the Java management extensions (JMX), or Java Dynamic Management Kit (JDMK). The main improvements may be summed up as follows, referring to JMX and Java for ease in discussion only, and without limitation: * Enabling Java applications to be managed without heavy investment.

The JMX architecture relies on a core managed object server, that acts as a management agent'and can run on most Java-enabled devices. This allows Java applications to be manageable with little impact on their design. A Java application simply needs to embed a managed object server and make some of its functionality available as one or several Manageable Beans registered in the object

server; that is all it takes to benefit from the management infrastructure.

JMX provides a standard way to enable manageability for any Java based application, service or device. For example, Enterprise JavaBeans (EJB) applications can use JMX to be manageable-.

* Providing a scalable management architecture Every JMX management service is an independent module that can be plugged into the management agent, depending on the requirements. This component-based management architecture means that JMX solutions can scale from small footprint devices to large telecommunications switches and beyond.

JMX provides the specification of a set of core management services. Additional services will be developed by conformant implementations, as well as by the integrators of the management solutions. All of these services can be dynamically loaded, unloaded, or even updated in the management infrastructure, as needed.

* Integrating existing management solutions JMX smart agents are capable of being managed through HTML browsers or by various management protocols such as SNMP and WBEM. JMX includes an open interface that any management system vendor can leverage.

Additional manager APIs may be provided. For example: an SNMP Manager API may provide the services needed to write applications that manage SNMP agents or act as a Java/SNMP proxy; a CIM/WBEM Manager API; such a WBEM client API may allow the writing of Java applications that access a CIM Object Manager ; other management APIs, e. g. a TMN manager API may also be developed. Such Java APIs for existing standard management protocols are independent of the three-level model (manager, agent, instrumentation). They find interest in enabling JMX applications in the Java programming language to link with existing management technologies. In fact, this

invention offers tools for management, rather than the management techniques themselves.

* Leverages existing standard Java technologies Whenever needed, the JMX specification will reference existing Java specifications such as Java Naming and Directory Interface (JNDI), Java Database Connectivity API (JDBC), Java Transaction Services (JTS), or others.

* Can leverage future management concepts discovery of resources and services on the network, which can then be managed by the JMX application. The combination of these two capabilities is Spontaneous Management.

* Defines only the interfaces necessary for management JMX is not designed to be a general purpose distributed object system. Although it provides a number of distributed services, these are focused on providing functionality for managing networks, systems, and applications.

The invention inter alia enables the provision of managing software (JMX managers), which may have one or more of the following features : -Provide an interface for management applications to interact with the agent through connectors, -Distribute management information from high-level management platforms to numerous JMX-compliant agents, -Consolidate management information coming from numerous JMX- compliant agents into logical views that are relevant tc the end user's business operations, -Provide security.

Finally, this invention also permits that MBeans be manageable not only by any JMX agent, but also by non-JMX-compliant agents which support MBeans: an agent may not provide all services and behaviour as required to be JMX compliant ; it can

however manipulate MBeans, for example get/set attributes, create and register them.

As described, a computer system encompasses one or more machines, which may be real or virtual.

This invention also covers the proposed software code itself, especially when made available on any appropriate computer- readable medium. The expression"computer-readable medium" includes a storage medium such as magnetic or optic, as well as a transmission medium such as a digital or analog signal. The software code basically includes the so-called driver code and further code as described.

Figures 8 through 22 and code examples CE-3 through CE-11 are be discussed in the attached Exhibits.

Exhibit A. 1-Foundation classes The foundation classes describe objects which may be used e. g. as the type of arguments. or returned values in methods of various APIs. The foundation classes described in this Exhibit are: A-ObjectName B-Objectlnstance C-Attribute and AttributeList D-JMX exceptions Other classes may also be considered as foundation classes; they are described in"Attribute Change Notifications" (section B of Exhibit A. 2): MBeanInfo, MBeanDataDescriptor, MBeanMethodDescriptor.

MBeanNotificationDescriptor A.-Object name It uniquely identifies an MBean within an MBean server. Management applications use this object name to identify the MBean on which to perform management operations. The class"ObjectName"represents an object name which consists of two parts: -Domain name The domain name is a"String". It provides a structure for the naming space within a JMX agent or within a global management domain. The domain name part might be omitted in an object name, as the MBean server is able to manage a default domain When an exact match is required (in the"Pattern Matching", described below), omitting the domain name will have the same result as using the default domain defined by the MBean server. How the domain name is structured is implementation-dependent. The domain name string may contain any characters except those which are object name separators or wildcards, namely the colon, comma, equals sign, asterisk or question mark. JMX always handles the domain name as a whole, therefore any semantic sub-definitions within the string are opaque to JMX.

-Key property list The key property list enables the user to assign unique names to the MBeans of a given domain. A key property is a property-value pair, where the property does not need to correspond to an actual attribute of an MBean. The key property list must

contain at least one key property. and any number of key properties whose order is not significant.

The String Representation of Names is now discusssed. Object names are usually built and displayed using their string representation. which has the following syntax: [domainName]: property=value [, property=value] * where the domain name may be omitted to designate the default domain.

The canonical name of an object is a particular string representation of its name where the key properties are sorted in lexical order. This representation of the object name is used in lexicographic comparisons performed in order to select MBeans based on their object name.

The possibility of Pattern Matching is now discussed.

Most of the basic MBean operations (for example, create, get and set attribute) need to uniquely identify one MBean by its object name. In that case, exact matching of the name is performed. On the other hand, for query operations, it is possible to select a range of MBeans by providing an object name expression. The MBean server will use pattern matching on the names of the objects. The matching features for the name components may be as follows: Domain Name The matching syntax is consistent with file globing, in other words: * matches any character sequence ? matches a single character Key Property List If the key property list is replaced by an'*', this will match all the objects in the selected domain (s). Otherwise all objects having the given key property list will be selected. If the given key property list ends with', *', all objects having the given key property list as subsets of their key property list will be selected.

Pattern matching examples will now w be given, assuming that the MBeans with the following names are registered in the MBean server: MyDomain: description=Printer, type=laser MyDomain: description=Disk, capacity=2 DefaultDomain: description=Disk, capacity=1 DefaultDomain: description=Printer, type=ink DefaultDomain: description=Printer, type=laser, date=1993 Socrates: description=Printer, type=laser, date=1993

Here are some examples of queries that can be performed using pattern matching: "* : *"will match all the objects of the MBean server. A null or""object name is equivalent to"* : *".

" : *'' will match all the objects of the default domain "MyDomain: *'' will match all objects in MyDomain "99romain: *" will also match all objects in MyDomain "*Dom*: *'' will match all objects in MyDomain and DefaultDomain "*: description=Printer, type=laser, *" will match the following objects: MyDomain: description=Printer, type=laser DefaultDomain: description=Printer, type=laser, date=1993 Socrates: description=Printer, type=laser. date=1993 "*Domain: description=Printer, *" will match the following objects: MyDomain: description=Printer, type=laser DefaultDomain: description=Printer, type=ink DefaultDomain: description=Printer, type=laser, date=1993 B.-Objectlnstance The"Objectlnstance"class is used to represent the link between an MBean's object name and its Java class. It is the full description of an MBean within an MBean server, though does not allow you to access the MBean by reference.

The"Objectlnstance"class contains the following elements: -The Java class name of the corresponding MBean -The"ObjectName"registered for the corresponding MBean -A test for equality with another"ObjectInstance" An"Objectlnstance"is returned when an MBean is created and is used subsequently for querying.

C-Attribute and AttributeList

An Attribute represents a pair: attribute and its value. It contains the attribute name string and a value in an"Object"class.

The following classes may be defined: -Class"Attribute"represents a single attribute-value pair, -Class"AttributeList"represents a list of attribute-value pairs.

The"Attribute"and"AttributeList"objects are typically used for conveying the attribute values of an MBean. as the result of a get operation, or as the argument of a set operation.

D-JMX exceptions Exceptions may be thrown by different methods of the JMX interfaces. This section describes what error cases may be encapsulated by such exceptions.

Exceptions mainly occur: -while the MBeanServer or JMX services perform operations on MBeans, -when the MBean code raises user defined exceptions.

The organization of the defined exceptions may be based on the nature (runtime or not) of the error case and on the location where it was produced (manager, agent, communication).

Exceptions raised by the agent will be discussed in more detail.

An exemplary JMX exception object model is shown as a tree in Fig. 11.

The base exception defined is named"JMException". It may e. g. extend the "java. lang. Exception class". The"JMException"represents all the exceptions thrown by methods of a JMX implementation.

Preferably, in order to specialize the"JMException"and to give information for the location of the exception's source, some subclass exceptions are defined. The first division is among: -OperationsException, exceptions thrown while performing operations in general -ReflectionException exceptions thrown during the use of the reflection API for invoking MBean methods, and -MBeanException exceptions thrown by the MBean code.

The"ReflectionException"wraps the actual core Java exception thrown when using the reflection API of Java. The"MBeanException"may also wrap the actual user defined exception thrown by an MBean method (Exception).

An exemplary JMX RuntimeException Tree Diagram is shown in Figure 12.

The base JMX runtime exception defined is named"JMRuntimeException"and it extends the"java. lang. RuntimeException" class. The"JMRuntimeException"represents all the runtime exceptions thrown by methods of a JMX implementation. Like the "java. lang. RuntimeException". a method of a JMX implementation is not required to declare in its"throws"clause any subclasses of"JMRuntimeException"that might be thrown during the execution of the method but not caught.

The"JMRuntimeException"is specialized into: -"OperationsRuntimeException"for representing the runtime exceptions thrown while performing operations in the agent, -"MBeanRuntimeException"representing the runtime exceptions thrown by the MBean code. and -"RuntimeErrorException"representing errors thrown in the agent re-thrown as runtime exceptions.

The conditions resulting in throwing each one of the JMX exceptions defined in Figure 11, and/or in Figure 12 will now be discussed in more detail.

* JMException: This class represents exceptions thrown by JMX implementations. It does not include the runtime exceptions.

* OperationsException: This class represents exceptions thrown in the agent when performing operations on MBeans.

* ReflectionException: This class represents exceptions thrown in the agent when using the "java. lang. reflect" classes to invoke methods on MBeans. It"wraps"the actual "java. lang. Exception" thrown.

The following are the"java. lang. Exception" exceptions that may be"wrapped"in a "ReflectionException" : ."ClassNotFoundException" : Thrown when an application tries to load in a class through its string name using the"forName"method in class"Class".

."InstantiationException: thrown when an application tries to create an instance of a class using the"newlnstance"method in class"Class". but the specified class object cannot be instantiated because it is an interface or is an abstract class.

."IllegalAccessException": thrown when an application tries to load in a class through its string name using the"forName"method in class"Class".

."NoSuchMethodException" : thrown when a particular method cannot be found.

* MBeanException: This class represents"user defined'exceptions thrown by MBean methods in the agent. It"wraps"the actual"user defined''exception thrown. This exception will be built by the MBean server when a call to an MBean method results in an unknown exception.

* InstanceAlreadyExistsException: The MBean is already registered in the repository.

* InstanceNotFoundException: The specified MBean does not exist in the repository.

* InvalidAttributeValueException: The specified value is not a valid value for the attribute.

* AttributeNotFoundException: The specified attribute does not exist or cannot be retrieved.

*"IntrospectionException" : An exception occurred during introspection of the MBean, i. e. the inspection of its management interface.

* MalformedObjectNameException: The format or contents of the information passed to the constructor does not allow to build a valid ObjectName.

* NotCompliantMBeanException: This exception occurs when trying to register an object which is not a JMX compliant MBean, in the MBean server.

* ServiceNotFoundException: This class represents exceptions raised when a requested service is not supported.

* MBeanRegistrationException: This class wraps exceptions thrown by the"preRegister ()", "preDeregister ()"methods of the MBeanRegistration interface.

* JMRuntimeException: This class represents runtime exceptions emitted by JMX implementations.

* RuntimeOperationsException: This class represents runtime exceptions thrown in the agent when performing operations on MBeans. It wraps the actual "java. lang. RuntimeException" thrown. Here are the"java. lang. RuntimeException" exceptions that may be"wrapped"in a"RuntimeOperationsException" : . IllegalArgumentException : thrown to indicate that a method has been passed an illegal or inappropriate argument.

. IndexOutOfBoundsException: thrown to indicate that an index of some sort (such as to an array. to a string, or to a vector) is out of range.

. NuIlPointerException: thrown when an application attempts to use null in a case where an object is required.

* RuntimeMBeanException: This class represents runtime exceptions thrown by MBean methods in the agent. It"wraps"the actual"java. lang. RuntimeException" exception thrown.

This exception will be built bv the MBeanServer when a call to an MBean method throws a runtime exception.

* RuntimeErrorException: When a"java. lang. Error" occurs in the agent it should be caught and re-thrown as a"JruntimeErrorException".

Exhibit A. 2-Notifications A-MBean Notification Model The management interface of an MBean allows its agent to perform control and configuration operations on the managed resources.

It has been observed that such management interfaces provide only part of the functionality necessary to manage complex. distributed systems. Most often, management applications further need to react to"management events". like a state change, or a specific condition when it occurs in an underlying resource.

Tools to this effect will now be described.

An"MBean Notification Model"is defined, allowing MBeans to broadcast such management events, which are called notifications.

In the same spirit as the JavaBeans event model, this notification model is based on an event/listener pair. However, the MBean notification model enables a listener to register only once and still receive all different events that may occur.

The MBean notification model may rely on the following components: Al. a generic event type"Notification" It can signal any type of management event. The"Notification"event may be used directly. or may be sub-classed. depending on the information which needs to be conveyed with the event.

A2. a"NotificationListener"interface It needs to be implemented by objects requesting to receive notifications sent by MBeans. Objects which receive notification events are called notification consumers.

A3. a"NotificationFilter"interface It needs to be implemented by each MBean wanting to act as a notification filter. This interface lets notification consumers provide a filter to be applied to notifications emitted by an MBean.

A4. a"NotificationBroadcaster"interface This interface allows notification consumers to register their interest in the notifications emitted by an MBean. By using a generic event type, this notification model allows any one consumer to receive all types of events from a source. In this

way. a management application only needs to register once in order to receive all of the different events of an MBean.

-Al-The"Notification"class extends the"EventObject"base class and defines the minimal information contained in a notification. It contains the following fields: -a notification type (identifier). a string expressed in a dot notation similar to Java properties. e. g.

"network. alarm. router". Since many notifications are of the same Java event class. this type string characterizes the meaning of the notification.

-a sequence number, a serial number identifying a particular instance of notification in the context of the notification source, -a time stamp indicating when the notification was generated, -a message contained in a string, It may be e. g. the explanation of the notification for displaying to a user -userData an"Object"instance that is used for whatever other data the notification source wishes to communicate to its consumers.

Notification sources should use the identifier to indicate the nature of the notification to their consumers. When additional information needs to be transmitted to consumers, the source may place it in the message or userData fields. In most cases. this allows the sources and consumers to exchange instances of the"Notification"class. However, subclasses of the "Notification"class may be defined, e. g. when additional semantics are required within the notification object.

Notification identifiers are strings which should be interpreted as dot-separated components.

This allows some structure in the naming of notifications. Some prefix reservation may be made: for example, all strings prefixed by"jmx."may be reserved for the notifications emitted by the components of the JMX infrastructure, such as"jmx. mbean. registered". Otherwise. MBeans are free to define all identifiers they wish to use when naming the notifications they emit.

Usually, MBeans will use identifiers that reflect their types of notifications within the larger management structure in which they are involved. For example. a vendor who provides JMX manageable resources as part of a management product might prefix all notifications with "vendorName".

Figure 7 shows a tree representation of the structure induced by the dot notation in notification identifiers.

-A2-The"NotificationListener"Interface may be implemented by objects interested in receiving notifications sent by MBeans. It defines a unique call-back method.

"handleNotification''. which will be invoked by an MBean when it emits a notification.

Besides the"Notification"object, a hand-back object is passed as an argument to the "handleNotification''method. This object is opaque to the MBean: it is provided by the consumer upon registration, the MBean stores it and hands it back to the consumer with each notification. Each consumer registered as a listener for a given notification source has a separate hand-back object which is only sent back to the consumer which registered it. This hand-back object can allow the consumer to retrieve some context information for use while processing the notification.

-A3-The"NotificationFilter"Interface may be implemented by a MBean for acting as a notification filter. It defines a unique method,"isNotificationEnabled", which will be invoked by an MBean before it emits a notification.

Besides the"Notification"object and the"NotificationListener"object, a hand-back object is passed as an argument to the"isNotificationEnabled"method. This hand-back object is handled transparently by the MBean, and can allow the consumer to retrieve some context information.

-A4-The"NotificationBroadcaster"Interface may be implemented by any MBean for acting as a notification source. It provides a pair of methods: 1."addNotificationListener", which registers a consumer's interest in notifications sent by this MBean. This method takes a reference to a"NotificationListener"object, a reference to a "NotificationFilter"object as well as a hand-back object. The MBean has to maintain a table of listener, filter and hand-back triplets.

When the MBean emits a notification, it invokes the"handleNotification"method of all the registered"NotificationListener''objects, with their respective hand-back object. If a"NotificationFilter"has been specified when registering the "NotificationListener"object, the MBean will invoke the"isNotificationEnabled" method before handling the notification. The same listener object may be registered more than once, each time with a different hand-back object. This means that the

"handleNotification-method of this listener will be invoked several times. with different hand-back objects.

2."removeNotificationListener". which allows a consumer to unregister itself from a notification source. This method takes a reference to a"NotificationListener"object, as well as a hand-back object. If the hand-back object is provided. only the entry corresponding to this listener and hand-back pair will be removed. The same listener object mav still be registered with other hand-back objects. Otherwise. if the hand-back is not provided, all entries corresponding to the listener will be removed.

B-Attribute Change Notifications A specific family of notifications, the attribute change notifications, allows management services and applications to be notified whenever the value of a given MBean attribute is modified.

In this model, the MBean has the full responsibility of sending notifications when an attribute change occurs. The mechanism for detecting changes in attributes and triggering the notification of the event is not part of the JMX specification. The attribute change notification behavior is therefore dependent upon each MBean's class implementation.

The MBean attribute change notification model relies on the following components: B1. AttributeChangeNotification, A specific event type, which can signal any attribute change event.

B2. AttributeChangeNotificationF'ilter A specific filter support, which allows attribute change notification consumers to filter the notifications depending on the attributes of interest.

Like in the"MBean Notification Model", any MBean wishing to send attribute change notifications must implement the"NotificationBroadcaster"interface. Similarly, the "NotifjcationListener"interface has to be implemented by all objects interested in receiving attribute change notifications sent by an MBean.

-B1-The"AttributeChangeNotification"class extends the"Notification"class and defines additional fields concerning the attribute which has changed: name, type, old value and new value of the attribute

The notification type of attribute change notifications is preferably a special one. e. g.

"JMX. attribute. change".

-B2-The"AttributeChangeNotificationFilter''class implements the"NotificationFilter class and defines the following additional methods: -"enableAttribute()", It enables receiving notifications for the specified attribute name -"disableAnribute (), It disables receiving notifications for the specified attribute name.

Exhibit A. 3-MBeanInfo Classes The"MBeanlnfo"Classes allow the management interface of an MBean to be described, in terms of its attributes, operations, constructors and notifications. These classes may be used both for the introspection of standard MBeans and for the self-description of dynamic MBeans.

The MBeanInfo classes may be used to discover the management interface of an MBean at run-time, even from outside the JMX agent where the class of the MBean is registered, for example. from a remote Java management application.

The following classes define the information for an MBean's management interface: 1. MBeanInfo lists the attributes, operations. constructors and notifications 2. MBeanMethodDescriptor describes an operation or constructor 3. MBeanDataDescriptor describes an attribute or method parameter 4. MBeanNotificationDescriptor describes a notification The UML diagram of Figure 8A shows the relationship between these classes as well as the components of each. The classes will now be described.

1.-The"MBeanInfo"class (Fig. 8A) is used to describe an MBean, its attributes, operations and constructors. In addition, when the MBean is a notification source, its notification types are also described in this class.

Its operations and constructors are described using the"MBeanMethodDescriptor"class and its attributes are described using the"MBeanDataDescriptor"class. The methods that are essential to the open MBean patterns are the"getDescription"and"isOpenMBean"methods.

The"getDescription ()"method must be used to return a string describing the MBean that is suitable for displaying to a user in a GUI. It should describe the MBean's purpose and its functionality, if applicable.

The"isOpenMBean ()"method ndicates whether or not the MBean being described conforms to the open MBean specification, as described in"Open MBean Requirements".

MBeanInfo objects are either created or verified by the MBean server in such a way as to

guarantee that"isOpenMBean ()"returns the proper value: true if the MBean conforms to this open MBean specification andfalse otherwise.

The"MBeanDataDescriptor"class is used to describe an attribute, method return value, or method argument. This type may be used to generically describe any class.

The"getType ()"method returns a string which identifies the Java type of the object being described. The"getName ()'method returns the object's name, also as a string, e. g. as follows: -For attributes, it is the attribute name.

-For method returns this name serves as an abbreviated description.

-For method arguments, the name uniquely identifies an argument and also serves as an abbreviated descriptor.

A qualitative description of the parameter is provided the"getDescription ()"method. The "getDefaultValue ()"method may be used to indicate a default value for this parameter. This is particularly useful when describing a method argument since this value can be used as a default if the invoker has no particular preference for some argument.

The"getLegalValues ()"method may be used to return a list of permissible values. This is useful for writable attributes and method arguments so the user may be presented with a list of reasonable or legal choices when editing them. For readable attributes and method returns, this method provides a list of legal values that may be expected. If a set of legal values is supplied, then the MBean server will validate that the values exchanged are a member of this set.

The methods"getDefaultValue (!"and"getLegalValues ()"return either"Object"or "Object []" types. In order to support remotability, the actual types must be limited. These methods, therefore, should preferably only be used in the context of open MBeans, to insure that these methods return only basic data types for open MBeans.

The name returned by the"getName ()"method is required for identifying attributes, but it is not essential for return values and arguments of non-open MBeans. However, "getName ()"remains a required method of MBeanInfo for the sake of consistency and to promote class reuse. As such, it must always return a non-empty string.

When used for return values and method arguments, the MBean server introspection mechanism will use"return"and"argumentN'as names unless overridden by getMBeanInfo () of standard MBeans. In the name"argumentlV", N is a number indicating

the position of the argument. This provides the required uniqueness for method argument names.

The"MBeanDataDescriptor"class will be used to describe basic data types for open MBeans. Subclasses of"MBeanDataDescriptor"may be used to describe non basic data types for open MBeans. For example."Composite-DataDescriptor"or "TabuIarDataDescriptor"are suitable when describing"CompositeData"or"TabularData" classes, respectively.

2.-The"MBeanMethodDescriptor"class describes an individual method. either a constructor or an operation. The return value and argument parameters are described using the"MBeanDataDescriptor"class. The method arguments must all have unique names. that is the set of"MBeanDataDescriptor"objects describing the arguments of a single method must all have different names as returned by their"getName ()"method.

The"getDescription ()"method is used to return a string describing the operation performed by this method. It should be suitable for displaying to a user in a GUI. It should describe what this method does.

The"getImpact ()"method returns an integer that can be mapped using the static variables of this class. Its purpose is to communicate the impact this method (operation) will have on the managed entity represented by the MBean."INFO"is used to indicate the operation is a read-like in nature, and that it would return some information without modifying the MBean."ACTION"is used to indicate that the operation is write-like and would modify the MBean in some way, typically by writing some value or changing a configuration. "ACTIONINFO"indicates that this method is a read/write operation. Impact information is very useful for making decisions on which operations to expose to users at different times.

It can also be used by some security schemes.

3.-An"MBeanNotificationDescriptor"class is used to describe a notification that is sent by an MBean. A notification is identified by it type string and its class name, optionally, it may also have a description string. The"getType ()"method returns the string containing the notification's type. This the identifier of the notification, containing any number of elements in dot notation. The"getClassName ()"method returns the Java class name that implements the given notification object. The notification's class name may provide further information about the meaning of the triggering event. For example, it might be used when selecting notifications during filtering.

Figure 8B illustrates an alternative embodiment of the MBeanInfo class, having:

-a common class"MBeanFeatureInfo", which is extended to provide name and description to other classes.

-a single"getAttributes ()"in the main MBeanInfo class. with another class "MBeanAttributeInfo"for accessing details on attributes.

-an"MBeanParameterInfo"class, for details on"getSignature ()", which now contains the "getArguments ()"of figure 8A.

-more generally. a specific class for each of the methods in the main MBeanInfo class. while they shared"MBeanMethodDescriptor"or"MBeanDataDescriptor"in the embodiment of figure 8A.

Exhibit B. 1-Standard MBeans In order to be manageable through a JMX agent a standard MBean explicitly defines its management interface. In some cases the management interface may be the whole public interface of the Java class. but most of the time, it will only be a subset of the public interface.

To be a JMX manageable resource, the Java class of a standard MBean must implement a Java interface which is named after the class.

This constraint may also satisfied if one of the MBean's superclasses implements a Java interface named after itself (the superclass).

This interface defines the handles on the resource that are exposed for management. Only the public methods contained in this interface are exposed for management. Since interfaces may also extend parent interfaces, all public methods in the inheritance tree of the interface are also considered. All the methods of the Java class which are not listed in this interface are not accessible to a management application.

This mechanism is described in further detail in"Inheritance Patterns".

Standard MBeans rely on a set of naming rules, called design patterns, that should be observed when defining the interface of their Java object. These naming rules define the concepts of attributes and operations which are inspired by the JavaBeans component model.

However, the actual design patterns for JMX take into consideration the inheritance scheme of the MBean, as well as lexical design patterns to identify the management interface. As a result, the design patterns for MBeans are specific to the JMX specification.

The management interface of a standard MBean is composed of : -its attributes, i. e. the properties which are exposed through"getter"and"setter"methods, -its operations, i. e. the remaining methods exposed in the MBean interface.

The process of inspecting the MBean interface and applying these design patterns is called introspection. The JMX agent uses introspection to look at the methods and superclasses of a class, determine if it represents an MBean that follows the design patterns, and recognize the names of both attributes and operations.

The management interface of the MBean is specified by implementing a Java interface whose name is formed by adding the"MBean"suffix to the MBean's Java class name. For

example. the Java class"MyClass"would implement the"MyClassMBean"interface. This interface mentions the complete signatures of the methods exposed.

The"MyClassMBean"interface may list methods defined in"MyClass"as well as methods which"MyClass"inherits from its superclasses. This enables the user to subclass and to instrument certain classes whose Java source code is inaccessible.

MBeans also inherit instrumentation from their superclasses. If"MySuperClass"is an MBean and"MyClass"extends"MySuperClass"then"MyClass"is also an MBean. If "MyClass"does not implement a"MyClassMBean"interface, then it will have the same management interface as"MySuperClass". Otherwise,"MyClass"can re-define its management interface by implementing a"MyClassMBean"interface.

Having to implement an MBean interface is the main constraint put on an MBean to be a JMX manageable resource.

A"MyClass"Example MBean will now be described.

CODE EXAMPLE CE-2 gives a basic illustration of the explicit definition of the management interface for the MBean of class"MyClass". Among the public methods defined in its Java class, only"getHidden"and"setHidden"will not be part of the management interface of the"MyClass"MBean.

The lexical patterns for attribute and operation names rely on the names of methods in the MBean's Java code. They enable a JMX agent to identify which attributes and operations are exposed for management in a standard MBean. They also allow the agent to make the distinction between read-only, write-only and read-write attributes.

Attributes are the fields or properties of the MBean which are in its management interface.

Attributes are discrete, named characteristics of the MBean which define its appearance or its behavior, or are characteristics of the managed resource that the MBean instruments. For example, an attribute named"ipackets"in an MBean representing an Ethernet driver could be defined to represent the number of incoming packets.

Attributes are always accessed via method calls on the object that owns them. For readable attributes, there is a getter method to read the attribute value. For writable attributes, there is a setter method to allow the attribute value to be updated. By default, the following design pattern is used for identifying attributes:

-if a class definition contains a matching pair of"getAttributeName"and "setAttributeName"methods that take and return the same type. these methods define a read- write attribute called"AttributeName".

-if a class definition contains only one of these methods, the method defines either a read- only or write-only attribute.

However, another design pattern might supersede the above described default design pattern.

The non default design pattern may be defined e. g. in the MBean interface class.

The"AttributeType"may be any Java type. or an array of any Java type, provided that this type is valid in the MBean's run-time context or environment. When the type of an attribute is an array type, the getter and setter methods operate on the whole array. The design patterns for indexed attributes do not include any getter or setter method for accessing individual array elements. Such access methods must be implemented as MBean operations.

In addition, for boolean type attributes, it is possible to define a getter method using the following design pattern: public AttributeType getAttributeName (); public void setAttributeName (AttributeType value); public boolean isAttributeName ();.

Preferably, in order to reduce redundancy, only one of the two getter methods for boolean types is allowed. An attribute may have either an"isAttributeName"method or a "getAttributeName"method, but not both in the same MBean.

Operations are the actions that a JMX manageable resource makes available to management applications. These actions can be any computation which the resource wishes to expose, and they can also return a value.

In a standard MBean, an operation is a Java method specified in its interface and implemented in the class itself. Any method in the MBean interface which does not fit an attribute design pattern is considered to define an operation.

A typical usage is shown in CODE EXAMPLE CE-2 in Exhibit D, where the MBean exposes the"reset"method to re-initialize its exposed attributes and private fields. Simple operations can also be written to access individual elements of an indexed attribut.

It may be decided that all attribute and operation names derived from these design patterns are case-sensitive. For example. this means that the methods"getstate ()"and"setState ()" define two attributes. one read-only called"state". and one write-only called"State".

While case sensitivity applies directly to component names of standard MBeans. it is also applicable to all component names of all types of MBeans. standard or dynamic. In general all names of classes. attributes. operations. methods, and internal elements are case sensitive. whether they appear as data or as functional code when they are manipulated by management operations.

Exhibit B. 2-Dnamic MBeans A-Method signatures of a DynamicMBean The methods are as follows: -MBeanInfo getMBeanInfo () -Object getAttribute (String attribute) -AttributeList getAttributes (String [] attributes) -void setAttribute (Attribute attribute) -AttributeList setAttributes (AttributeList attributes) -Object invoke (String operationName. Object [] params. String [] signature).

The methods are defined in more detail as follows: -getMBeanInfo Method This method returns an"MBeanInfo"object which contains the definition of the MBean's management interface. Conceptually, dynamic MBeans have both attributes and operations, only they are not exposed through method names. Instead, dynamic MBeans expose attribute names and types and operation signatures through the return value of this method at runtime. This return value is of type"MBeanInfo", which contains a list of attribute names and their types, a list of operations and their parameters, and other management information. This type and its helper classes are further described in"MBeanlnfo Classes"in Exhibit A. 3.

-getAttribute and getAttributes Methods These methods take either an attribute name or a list of attribute names and return the value of the corresponding attribute (s). These are like a standard getter method, except the caller supplies the name of the attribute requested. It is up to the implementation of the dynamic MBean to properly map the exposed attributes names to their values through these methods. The classes which describe attribute names, values and lists of names and values are described in"Attribute and AttributeList"in Exhibit A. 1. These data types are also used by the"setAttribute"methods below.

-setAttribute and setAttributes A2ethods

These methods take attribute name-value pairs and. like standard setter methods, they write these values to the corresponding attribute. When setting several attributes at a time, the list of values is returned to indicate those for which the write operation succeeded. Again. it is up to the implementation of the dynamic MBean to properly map the new values to the internal representation of their intended attribute target.

-invoke Method The invoke method lets management applications call any of the operations exposed by the dynamic MBean. Here the caller must provide the name of the intended operation, the objects to be passed as parameters, and the types for these parameters. By including the operation signature, the dynamic MBean implementation may verify that the mapping is consistent between the requested operation and that which is exposed. If the requested operation is successfully mapped to its internal implementation, this method returns the result of the operation. The calling application will expect to receive the return type exposed for this operation in the"MBeanInfo"method.

B. Behavior of Dynamic MBeans When registered in an agent, a dynamic MBean is treated in exactly the same way as a standard MBean. Typically, a management application will first obtain the management interface through the"getMBeanInfo"method, in order to have the names of the attributes and operations. The application will then make calls to getters. setters and operations of the dynamic MBean.

In fact. the interface for dynamic MBeans is similar to that of the MBean server in the agent (see Exhibit C. 1). A dynamic MBean provides the management abstraction that the MBean server provides for standard MBeans. This is why management applications can manipulate both kinds of MBeans indifferently: the same management operations are applied to both. In the case of the standard MBean, the MBean server uses introspection to find the management interface and then call the operations requested by the manager. In the case of the dynamic MBean, these tasks are taken over by the dynamic MBean's implementation. This delegation entails both flexibi lity of the resource and mapping responsibilities to ensure coherence.

From the application's perspective, how the dynamic MBean implements the mapping between the declared management interface and the returned attribute values and operation results is not important, it only expects the advertised management interface to be available.

This gives much flexibility to the dynamic MBean to build more complex data structures. expose information which it can gather off-line. or simply provide a wrapper for resources not written in the Java programming language.

Exhibit B. 3-Open MBeans This section defines a way of instrumenting resources that MBeans should conform to, if they wish to be 'open"to the widest range of management applications. An MBean which fulfills this condition is termed an open MBean.

The goal of open MBeans is to provide a mechanism that will allow management applications and their human administrators to understand and use new managed objects as they are discovered at runtime. These MBeans are called"open"because they rely on small set of universal Java types and advertise their functionality.

Management applications and open MBeans are thus able to share and use management data and operations at runtime without requiring the recompilation, reassembly or expensive dynamic linking of management applications. In the same way, human operator to be able to intelligently use the newly discovered managed object without having to consult additional documentation. Thus, open MBeans contribute to the flexibility and scalability of management systems.

In an overview, Open MBeans are specified by the design patterns to which they must conform, not by inheritance. However. in order to provide its own desciption to management applications, an open MBean should also be a dynamic MBean. Beyond the DynamicMBean interface, there is no corresponding"open"interface that must be implemented. Instead, an MBean earns its"openness"by providing a descriptively rich MBeanInfo object and using only certain well-defined data types in its management interface.

The data type patterns are tested for at runtime by the MBean's JMX agent. The MBean server indicates whether a registered MBean is open or not as part the MBeanInfo object it returns. If an MBean is marked as open in this manner, then it is possible for a JMX- compliant management application to immediately make use of all attributes and operations without requiring recompilation.

However, these patterns mandate descriptive information for human operators for which conformance testing is a qualitative measure. An open MBean is guaranteed to provide this self-describing capability but the quality of it, and thus the ability of a human operator to intelligently use it, cannot be tested for in an automated way.

Qualitatively, the description provided by the various parts of an open MBean must be suitable for displaying to a user through a Graphical User Interface (GUI).

First, the basic data types for open MBeans are presented, followed by a description of all the JMX classes related to open MBeans. Once these types and classes have been defined, the complete rules for open MBean conformance are then explicited in the"Open MBean Requirements"section.

In order for management applications to immediately make use of MBeans without recompilation. re-assembly, or dynamic linking. all MBean attributes, method return values, and method arguments must be limited to a well known set of data types.

This set is termed the basic data types for open MBeans. This set is defined as: the wrapper objects that correspond to the Java primitive types (such as Integer, Long, Boolean, etc.), String, CompositeData, TabularData. and arrays of the aforementioned reference data types.

The CompositeData and TabularData classes may be used to form aggregates of the primitive data types and provide a mechanism with which to express complex data objects in a consistent manner. These two classes are specified by their UML representation in Figure 9A.

The following list indicates data types that are allowed in open MBeans.

'java. jmx. openmbean. CompositeData' javax. jmx. openmbean . CompositeData [] 'java. jmx. openmbean. TabularData m javax. jmx. openmbean . TabularData [] 'Java. lang. String java. lang. String [] 'Java. lang. Character java. lang. Character [] 'Java. lang. Boolean java. lang. Boolean [] 'Java. lang. Byte java. lang. Byte [] 'Java. lang. Short java. lang. Short [] 'Java. lang. Integer java. lang. Integer [] 'Java. lang. Long java. lang. Long [] * java. lang. Float * java. lang. Float [] 'Java. lang. Double java. lang. Double [].

Since CompositeData and TabularData are also basic data types, these structures can contain other composite or tabular structures and have arbitrary complexity. The"TabularData"class can be used to represent tables, a very common structure in the management domain. The

basic data types can therefore be used alone or in combination to satisfy most data representation requirements.

The benefit of using the composite and tabular data types in the context of open MBeans is that the complex data they represent can be completely described in an universal manner using MBeanInfo.

The Mandatory Classes comprise the non-primitive classes used to construct open MBeans.

This includes the complex data types used exclusively by open MBeans, as well as those parts of the standard MBeanInfo classes that relate to open MBeans.

The MBeanInfo classes which contain open MBean information are: -MBeanInfo -MBeanMethodDescriptor -MBeanDataDescriptor -MBeanNotificationDescriptor The classes which belong to the"OpenMBean"package are: -CompositeDataDescriptor -TabularDataDescriptor -CompositeData -TabularData The UML diagram of fig. 9A specifies the elements of the open MBean classes, as well as the parts of the MBeanInfo class which are mandatory in order to meet the design patterns for open MBeans.

The MBeanInfo Classes for open MBeans are now considered. Generally, the"MBeanInfo" class and its helpers are described elsewhere in this specification, in"Attribute Change Notifications". The present section discusses only those components which are mandatory for open MBeans.

Each component of an open MBean must use the"getDescription ()"method to provide a description of itself.

In the"MBeanInfo"class. this description should give the overall purpose and functionality of the MBean. In the other classes, the description should provide information about the component itself, for example the side-effects of an operation or the significance of an attribute. All descriptions should be suitable for displaying to a user in a GUI.

In the MBeanInfo class, the"isOpenMBean"method should always return true in open MBeans. The MBean server will check that all descriptions are non-empty and verify other open MBean requirements when this is the case.

For open MBeans. the"MBeanDataDescriptor"class will only be used to describe one of the basic data types for open MBeans. When either"CompositeData"or"TabularData" classes are being described, the corresponding subclasses of"MBeanDataDescriptor" (CompositeDataDescriptor or TabularDataDescriptor, respectively) are preferably used.

The methods"getDefaultValue ()"and"getLegalValues ()"both return Object types. In order to support remote management, the actual types must be limited to a well known set. These methods, therefore, will mostly be used in the context of open MBeans. This insures that these methods return only the basic data types for open MBeans which are universally recognizable.

These two methods are intended to provide additional information that would help a user interact with the MBean's attributes and operations: -"getDefaultValue ()" may be used to indicate a default value for a parameter. This is particularly useful when describing a method argument since this value can be used as a default if the invoker has no particular preference for some argument.

-"getLegalValues ()" may be used to return a list of permissible values. This is useful for writable attributes and method arguments so the user may be presented with a list of reasonable or legal choices when editing them. For readable attributes and method returns, this method can provide a list of legal values that may be expected. If a set of legal values is supplied, then the MBean server will validate that the values exchanged are a member of this set.

The"MBeanMethodDescriptor"class contains a method whose full implementation is only required of open MBeans. The''gellmpact ()''method must return one of the following values defined as static variables of this class: ACTION. INFO, or ACTION INFO. The value UNKNOWN may not be returned by any method descriptor of an open MBean.

The"impact"provides information about the method's effect, as a complement to its self- description. A method described as INFO will not modify the MBean, it is a read-only method which only returns data. An ACTION method has some effect on the MBean, usually a write operation or some other state modification. The ACTION INFO method has both read and write roles. It is the open MBean developer's responsibility to correctly assign

the impact of each method in its descriptor. Indeed, the difference between information and action is dependent on the design and usage of each MBean.

The Open MBean Classes are defined by their UML representation in Figure 9A. They are used only by open MBeans and the applications which manage them.

The"CompositeDataDescriptor"subclass of"MBeanDataDescriptor"is used to describe data objects of type"CompositeData"."CompositeData"objects are simply aggregates of other data objects, as described.

The method"getDataDescriptors ()"returns an MBeanDataDescriptor object for each aggregate member.

The"TabularDataDescriptor"subclass of"CompositeDataDescriptor"is used to describe "TabularData"objects which represent tables, as described.

The"getIndexNamesQ"method returns the column header names of the column (s) used to index a row of the table. This must be the name (s) of one or more of the components in the tabular data objects it describes.

The"CompositeData"class represents an aggregate of other data objects. Its semantics are similar to a hashtable with keys that are limited to strings. However, it is initialized at instantiation and that cannot be modified thereafter. The constructor requires a "CompositeDataDescriptor", and array of names and an array of values. Each element of the names array corresponds to the element of the values array at the same index. The "CompositeDataDescriptor"supplied to the constructor is used to validate the conformance of the supplied initialization data.

When used in the context of open MBeans, a"CompositeData"object must be composed of only basic data types for open MBeans. Since this set also includes"CompositeData", complex hierarchies may be represented by creating composite types which contain other composite types.

The"TabularData"class may be used to represent tables, a very common data structure in the systems management domain. These tables consist of rows of uniform CompositeData objects, that is, all objects conform to the same CompositeDataDescriptor. The columns of the table are the names of the components which make up a CompositeData row. Thus the component names in the common CompositeDataDescriptor are the column names for the corresponding component objects in the CompositeData. A single column or combination

of columns must uniquely index all rows. The columns used as indices are determined from the TabularDataDescriptor passed to the constructor. The constructor for the"TabularData"class takes a list of CompositeData objects and a TabularDataDescriptor. It insures that all rows are uniform (all CompositeData objects use the same descriptor) and that they can be uniquely indexed by the elements named in the given TabularDataDescriptor.

In order for an MBean to be considered an open MBean by the MBean server, it should possess the following properties: -All attributes, method arguments, and non-void returnvalues must be objects in the set of basic data types for open MBeans.

-All objects of type"CompositeData"that are described in MBeanInfo must be described using the"CompositeDataDescriptor"class. Using only the superclass "MBeanDataDescriptor"is insufficient.

-All objects oftype"TabularData"that are described in MBeanInfo must be described using the"TabularDataDescriptor"class. Using the superclasses"MBeanDataDescriptor"or "CompositeDataDescriptor"is insufficient.

-The following methods in the MBeanlnfo related classes must return valid, meaningful data (non-empty strings) suitable for display to users: . MBeanInfo. getDescription ()<BR> . MBeanMethodDescritpor. getDescription ()<BR> . MBeanDataDescriptor. getDescription ()<BR> . MBeanNotificationDescriptor. getDescription ()<BR> . MBeanMethodDescriptor. getImpact () must return one of the constant values ACTION, INFO, or ACTION-INFO.

The value UNKN () WN may not be used.

Figure 9B illustrates an alternative UML diagram specifying the elements of the open MBean classes, in connection with the MBeanInfo classes of figure 8B. The desired operation is substantially the same as in the case of figure 9A.

Generally, it is up to the MBean author to insure that all descriptors adequately describe their respective targets so as to allow the informed use of the MBean, method, or attribute at run time without further documentation. This qualitative requirement cannot be programmatically enforced.

Exhibit B. 4-Model MBeans A model MBean is a generic, configurable MBean which anyone can use to rapidly instrument almost any resource. Model MBeans are dynamic MBeans which also implement the"ModelMBean"interface specified in code example CE-3 in Exhibit D. This interface defines structures that, when implemented, provide a default behavior. Since an implementation is supplied as part of the JMX Reference Implementation, JMX developers can instrument their resources in as little as 3 to 5 lines of code.

Further. the Java Management extensions specify that a model MBean implementation must be supplied as part of all conforming JMX agents. This means that resources, services and applications can rely on the presence of a generic, template for creating manageable objects on-the-fly. Users only need to instantiate a model MBean, configure the exposure of the default behavior, and register it in a JMX agent.

Model MBeans are universal since they must be available in all JMX agent implementations.

This means that there will be a model MBean adapted to all environments which implement the Java Management extensions.

In an overview, the model MBean specification is an interface that provides a management template for managed resources. It is also a concrete class provided in conjunction with the JMX agent. The model MBean implementation is intended to provide ease of use and extensive default management behavior for the instrumentation. The MBean server is a repository and a factory for the model MBean, so the managed resource'creates'or'finds' its model MBean object from the JMX agent. Resources to be managed add custom attributes, operations, and notifications to the basic model MBean object by interfacing with the JMX agent and model MBeans that represent the resource.

There may be one or more instances of a model MBean for each instance of a resource (application, device, and so forth) to be managed in the system. The model MBean is a dynamic MBean, i. e. it implements the Dynamic MBean interface. As such, the JMX agent will delegate all management operations to the model MBean instances.

The model MBean has a descriptor for each Attribute, Operation, and Notification in its management interface. The descriptor contains behavior information for the attribute, operation, or notification. This includes logging policy, notification responses, persistence policy, value caching policy, and a mapping between the attributes and operations in its management interface and the actual methods that need to be called to satisfy the get, set, or invoke request.

So, a"getAttribute (myAppl Status)"call may actually invoke a method on another object that is part of the managed resource, like"myAppl. StatusChecker ()". The object"myAppl"may be in this JVM, or it may be in another JVM on this host or another host. In this way, distributed. component oriented applications are supported.

The model MBean instances are created and maintained by the JMX agent, like other MBean instances. Several implementations of a model MBean may be available, depending upon the needs of the environment in which the JMX agent is installed. The managed resource instantiating the model MBean does not have to be aware of the specifics of the implementation of the model MBean. Implementation differences between environments include the JVM. persistence. transactional behavior, caching, scalability, throughput, location transparency, remotability, etc.

For example, a JMX agent running in a pJava environment may use a model MBean with no persistence or remotability. A JMX agent running in an application server's JVM may use a model MBean that handles persistence, transactions, remote access, location transparency, and security. In either case, the instrumentation programmer's task is the same.

The MBean developer does not have to provide different versions of its MBeans for different Java environments, nor does he have to program to a specific Java environment.

The model MBean, in cooperation with its JMX agent, will be implemented to support its own persistence, transactionalism, location transparency, and locatability.

The instrumentation developer does not need to develop an MBean with its own transactional and persistence characteristics. He merely instantiates his model MBean in the JMX agent and trusts the implementation of the model MBean that the JMX agent has is appropriate for the environment in which the JMX agent currently exists.

Any implementation of the model MBean should implement the ModelMBean, DynamicMBean, and NotificationBroadcaster interfaces. The model MBean objects have attribute change notifications and generic notifications which can be registered for by the managed resource or the adaptor : ;. The JMX agent which supplies and creates the model MBean may be specifically designed to support a particular class implementation of the "ModelMBean"interface.

A view of the corresponding instrumentation will now be given.

Each managed resource uses the JMX Model MBean Interface to expose its management data, operations, and notifications for use by a management system. At initialization. the

managed resource obtains access to the JMX agent through the"findMBeanServer ()"static method. The managed resource then will create or find and reference one or more instances of the model MBean via the"createMBean ("ModelMBeanImpl"..)","getMBean ()", or "queryMBeans ()"methods. The predefined attributes that are part of the model MBean's name are meant to establish a unique managed resource identity.

Basic Model MBean Instrumentation The managed resource populates the model MBean object with its management interface. This includes the custom attributes, operations, and notifications that it wants management systems to access. The resource specific information can thus be dynamically determined at execution time. The managed resource sets and updates any type of data as an attribute in the model MBean at will with a single"setAttribute ()"method invocation. The attribute is now published for use by any management system. Maintaining values of fairly static attributes in the model MBean allows the model MBean to return that value without interrupting or calling an managed resource method. When the managed resource methods are invoked to satisfy a request, the managed resource returns the attribute values and command responses to the model MBean. In turn, the model MBean returns these values to the MBean server which returns them to the request originator, usually a management system's adaptor. Since the model MBean can be persistent and is locatable, critical but transient managed resources can retain any required counters or state information within the JMX agent. Likewise. the managed resource's data survives recycling of the JMX agent.

The model MBean supports the JMX NotificationBroadcaster interface. One 'sendNotification'API call on the model MBean by the managed resource sends notifications to all'interested'management systems. Predefined or unique notifications can be sent for any managed resource or management system defined significant event. Notifications are normally sent by a managed resource when operator intervention is required or the application's state is exceptional.

The model MBean sends attributeChangeNotifications whenever a custom attribute in the model MBean is set. The managed resource can capture change requests initiated by the management system by listening for the attributeChangeNotification as well.

The managed resource can then choose to implement the attribute change from the model MBean into the resource.

The Advanced Instrumentation wi ! ! now be described.

The model MBean's default behavior and simple APIs satisfies the management needs of most applications. However the model MBean interface also allows complex managed resource management scenarios. The model MBean APIs allow mapping of the application's model MBean attributes to existing management data models, i. e. specific MIBs or CIM objects. Conversely, the managed resource can take advantage of generic mappings to MIBs and CIM objects generated by tools interacting with the JMX agent. For example, a MIB generator can interact with the JMX agent and create a MIB file that is loaded by an SNMP management system.

The generated MIB file can represent the resources known by the JMX agent. The applications represented by those resources do not have to be cognizant of how the management data is mapped to the MIB. This scenario will also work for other definition files required by management systems.

A view from the Protocol Adaptor will now be given.

The adaptors will'find'the JMX agent and model MBean objects in the same manner as the managed resource. The adaptor will interact with the model MBean through the JMX agent.

It will find the managed resource provided attributes and operations through the MBeanInfo object. It will find out behavior details about supported attributes, operations, and notifications through the"ModelMBean"interface. To obtain the value for an managed resource provided attribute, it will ask the model MBean object for its attribute with the "getAttribute ()" method from the DynamicMBean Interface. Management operations for the managed resource are executed with the"invoke ()"method. Since the model MBean instruments the NotificationBroadcaster Interface to support any custom notifications from the managed resource, the protocol adaptor can register to receive all or some of the notifications. The model MBean also sends AttributeChangeNotifications for communication from the model MBean to adaptors interested in attribute changes which need to be relayed to the management system.

The Descriptors will now be discussed.

The MBeanInfo interface publishes metadata about the attributes, operations, and notifications in the management interface. The model MBean descriptors contain behavioral information about the same management interface. When the model MBean is created by the managed resource, the managed resource can define the method signatures executed by the model MBean that will satisfy the get and set of attributes, invoke of operations, or response to notifications. The descriptors used for this are the attributeDescriptorList,

operationDescriptorList and notificationDescriptorList. If an attribute has no method signature associated with it. then no managed resource method can be invoked to satisfy it.

This means that for"setAttribute"the value is simply recorde, and any AttributeChangeNotification listeners are sent a AttributeChangeNotification. For "getAttribute", the current value for the attribute in the model MBean is simply returned and its value cannot be refreshed from the managed resource. This can be useful to minimize managed resource interruption for static resource information. The attribute descriptor also include policy for managing its persistence. caching. and protocol mapping. For operations, the method signature must be defined. For notifications, type, severity, and a response operation are optionally defined. The managed resource can pass an MBeanInfo object, XML file name, or IDL file name to initialize the MBeanlnfo and descriptors instead of customizing them programmatically.

The AttributeChangeNotification Support is as follows.

The model MBean sends an AttributeChangeNotification to all registered NotificationListeners whenever a value change for the attribute in the MBean occurs. By default, no AttributeChangeNotification will be sent unless a listener is explicitly registered for them. Normally, the'setAttribute'on the model MBean invokes the setMethod defined for the attribute on the managed resource directly. Alternatively, managed resources can use the AttributeChangeNotification to trigger internal actions to implement the intended effect of changing the attribute.

Support for Persistence will now be described.

Persistence is handled within the model MBean. However, this does not mean that a model MBean must persist itself. It is foreseeable that some implementations of the JMX agent will be completely transient in nature. In a simple implementation the model MBean may be saved into a flat file. In a more complex environment persistence may be handled by the JMX agent in which the model MBean has been instantiated. If the JMX agent is not transient and the model MBean is persistable it should support persistence policy at the attribute level and model MBean level. The persistence policy may switch persistence off, force persistence on checkpoint intervals, allow it to occur whenever the model MBean is updated, or throttle the update persistence so that it does not write out the information any more frequently than a certain interval. If the model MBean is executing in an environment where management operations are transactional, this should be shielded from the managed resource. If the managed resource must be aware of the transaction, then this will mean that

the managed resource depends on a certain version of the JMX agent and model MBean to be accessible.

The ModelMBeanlmpl constructor will attempt to prime itself by calling the ModelMBeanlmpl"load ()"method. This method must determine if this model MBean has a persistent representation by invoking the"findInPersistent ()"method. Then the load method must determine where this data is located, retrieve it, and initialize the model MBean. The model MBean can, through JDBC (Java Database Connector) operations, persist data to and populate the model MBeans from any number of data storage options such as an LDAP server, a DB2 application, a flat file. an NFS file, an FAS file, or an internal high performance cache.

The"load ()"method allows the JMX agent to be independent and ignorant of data locale information and knowledge. This allows data location to vary from one installation to another depending on how the JMX agent and managed resource are installed and configured. It also permits managed resource configuration data to be defined within the directory service for use by multiple managed resource instances or JMX agent instances.

In this way, data locale has no impact on the interaction between the managed resource, its model MBean, the JMX agent, the adaptor or the management system. As with all data persistence issues, the platform data services characteristics may have an impact upon performance and security. Since persistence policy can be set at the model MBean Attribute level, all or some of the model MBean attributes can be persisted by the ModelMBeanlmpl.

The model MBean will detect that it has been updated and invoke its own"store ()"method. If the ModelMBean Service is cc, nfigured to periodically checkpoint model MBeans by invoking the ModelMBeanImpl's"store ()"method. Like the"load ()"method, the ModelMBeanImpl"store ()"method must determine where the data should reside and store it there appropriately.

The JMX agent's persistence setting would apply to all of its model MBeans unless a one of them defines overriding policies. The model MBean persistence policy provides a specified persistence event (update/checkpoint) and timing granularity concerning how the designated attributes, if any, are persisted. Model MBean persistence policy will allow persistence on a'whenever updateS'basis, a'periodic checkpoint'basis, or a'never persist' basis. If no persistence policy for a ModelMBeanlmpl is defined, it will use that which is currently in effect for its JMX agent instance.

The support of Cached Values is now considered.

In general. the adaptors access the application's ModelMBeanImpl as it is returned by the JMX agent. If the data requested by the adaptor is current, then the managed resource is not interrupted with a data retrieval request. Therefore. direct interaction with the managed resource is not required for each interaction with the management system. This helps minimize the impact of management activity on runtime application resources and performance. The attribute descriptor contains currencyTimeLimit and lastUpdatedTimeStamp fields. If the current time is past lastUpdateTimeStamp + currencyTimeLimit. then the attribute value is stale.

If a"getAttribute ()"is received for an attribute with a stale value (or no value), then the getMethod for the attribute will be invoked and the returned value will be recorded for the attribute, lastUpdatedTimeStamp will be reset, and the requester will be handed the new value. If there is not a getMethod defined, then the default value from MBeanInfo for the attribute will be returned.

A-Classes and Interfaces The implementation of the model MBean is the"ModeIMBeanImpl"class which implements the following interfaces: -NotificationBroadcaster -DynamicMBean -ModelMBean The implementation of the"NotificationBroadcaster"interface is similar to that for all MBeans and will not be discussed here in detail. The following defines how the model MBean implementation expresses the functionality of certain methods of the "DynamicMBean Interface". getMBeanInfo Returns the MBeanInfo object for the ModelMBeanImpl. Valid attributes, operations, and notifications defined by the managed resource can be retrieved from the MBeanInfo with the getOperations0, getAttributes0, and getNotifìcationO methods on the MBeanInfo. For each attribute, operation, and notification found in the MBeanInfo, the ModelMBeanlmpl will maintain an attributeDescriptor, operationDescriptor, or notificationDescriptor respectively. getAttribute (s) Invoked to get information from this instance of the ModelMBeanlmpl synchronously. The model MBean will do check for attribute value scaleness.

Staleness is determined from the CurrencyTimeLimit and LastUpdatedTime fields in the attributeDescriptor for the attribute. If CurrencyTimeLimit is 0, then the value will always be stale. If CurrencyTimeLimit is-1. then the value will never be stale.

If the value in the model MBean is set and not stale, then it will return this value without invoking any methods on the managed resource. If the attribute value is stale, then the model MBean will invoke the method defined in the'getMethod'field of the attributeDescriptor. The returned value from this invocation will be stored in the model MBean as the current value. LastUpdatedTime will be reset to the current time. If a'getMethod'is not defined and the value is stale, then the defaultValue from the MBeanInfo for the attribute will be returned. setAttribute (s) Invoked to set information for this instance ofthe ModelMBeanImpl synchronously.

Invocation of the method where the AttributeDescriptorList does not match the current AttributeDescriptorList causes an AttributeChangeNotification to be generated. invoke The model MBean imparts no special processing on this aspect of the Dynamic MBean Interface.

The following sections describe how the"ModeIMBean"interface is implemented by the "ModelMBeanImpl"class. This combines both the meaning of the methods and the implementation details.

The model MBean relies on a description of its components in XML (Extensible Markup Language). XML (for eXtended Markup Language) is a recent hypertext metalanguage standard, specified by the XML working group. For understanding the XML, reference is made to the XML recommendations, available on the INTERNET at http://www. w3. org/TR/REC-xml, or as hard copies.

Each component is described by a structured XML string containing its metadata. The XML string class is illustrated in code example CE-4 in Exhibit D.

These formats are described in"XML Descriptors"hereinafer. The descriptors are grouped together in list types when representing several of the same nature, for example all of the attributes of a model MBean. initialize (with descriptor lists)

Configures the management interface of the model MBean from list types which describe the attributes, operations and notifications. This can be done at anytime the interface needs to be modified when the model MBean is not registered with the JMX agent. Creates an MBeanInfo and initializes the descriptor lists for the ModelMBeanlmpl. initialize (with idlStrin, g, ^ Parses an IDL (Interface Definition Language) string that has been read in from a file and contains the management interface of the managed resource. Creates an MBeanInfo and initializes the descriptor lists for the model MBean. Can only be executed when the model MBean is not registered with the JMX agent. initialize (with xmlStringQ Parses an XML (extensible Markup Language) string that has been read in from a file and contains the descriptor lists for the management interface of the managed resource. Creates an MBeanInfo and initializes the descriptor lists for the model MBean. Can only be executed when the model MBean is not registered with the JMX agent. initialize (with MBeanlnfo) Creates the descriptor lists to reflect the given MBeanInfo interface. Sets the MBeanInfo object for the model MBean to the provided MBeanInfo object. Can only be executed when the model MBean is not registered with the JMX agent. getAttributeDescriptors Returns descriptors for attributes in a list of XML strings, one string per attribute.

If the attributeNames parameter is an empty list, then all attribute descriptors will be returned. If attributeNames has elements, then only the descriptors for attributes with those names will be returned. If an attribute does not exist, an empty descriptor will be returned at its position in the list. Additional metadata such as informative strings about the attribute may be retrieved from the model MBean's MBeanInfo. setAttributeDescriptors Sets the attribute descriptors from a descriptor list, replacing any current ones with the same name. The full list of attributes does not need to be defined in every set operation. Existing attributes that are not in the list will not be affected. Attribute descriptors may not be added or deleted after the model MBean has been registered with the JMX agent.

getOperationDescriptors Returns descriptors for operations in a list of XML strings, one string per operation.

If the operationNames parameter is an empty list. then all operation descriptors will be returned. If operationNames has elements, then only the descriptors for operations with those names will be returned. If an operation does not exist. an empty descriptor will be returned at its position in the list. Additional metadata such as informative strings about the operation may be retrieved from the model MBean's MBeanInfo. setOperationDescriptors Sets the operation descriptors from a descriptor list, replacing any current ones with the same name. The full list of operations does not need to be defined in every set operation. Existing operations that are not in the list will not be affected. Operation descriptors may not be added or deleted after the model MBean has been registered with the JMX agent. getNotificationDescriptors Returns descriptors for notifications in a list of XML strings, one string per notification. If the notificationNames is an empty list, then all notification descriptors will be returned. If notificationNames has elements, then only the descriptors for notifications with those name will be returned. If a notification does not exist, an empty descriptor will be returned at its position in the list. Applications can also issue notifications that are not predefined. Those that are not described in this list will be treated with a default behavior, advanced functionality such as response operation and severity mapping will be initiated. setNotificationDescriptors Sets the notification descriptors from a descriptor list, replacing any current ones with the same name. The full list of notifications does not need to be defined in every set operation. Existing notifications that are not in the list will not be affected. Notification descriptors may not be added or deleted after the model MBean has been registered with the JMX agent. getAlIDescriptors Returns all attribute, operation, and notification descriptors in a list of XML strings (one string per descriptor). setAlIDescriptors Sets all descriptors in the model MBean from the given descriptor lists. Replaces all descriptor lists in their entirety.

load Locates the MBean in a persistent store and primes this instance of the MBean with the stored values. Any currently set values are overwritten. Should only be called by the ModelMBeanImpl class implementation. and only in its constructor.

(optional) store Writes the MBean in a persistent store. Should only called by the ModelMBeanImpl class to store itself according to persistence policy for the MBean. When used, it may be called with every setAttribute or on a periodic basis. (optional) findPersistent Looks in the persistent store for this MBean to see if there is a persistent version of it. Should only called by the ModelMBeanImpl class implementation. In general, this should be done in the ModelMBeanImpl constructor to find an existing persistent version of the MBean that should be used to initialize this instance of the ModelMBeanlmpl. Returns the specific mBeanName found. (optional) The XML Descriptors will now be considered. An XMLString class encapsulates XML- encoded data representing the metadata of a model MBean. Any appropriately formatted string can be cast as an XMLString.

The constructors and methods of the XMLString Class are defined as follows.

XMLString (with plainString) Constructor that parses the plain String parameter and verifies it is a valid, known descriptorType and a vaiid XML syntax to support the descriptor type. The plainString parameter must already be an XML-encoded string. If the constructor cannot create an XMLString from the plain String, an exception will be thrown and XMLString will be null.

XMLString (with fìeld names and values) Constructor that verifies th at the field names include a descriptor type. It verifies that it is a valid, known descriptor type (attribute, operation or notification) and creates a valid XML string to support the type using the names and values supplied for each field.

XMLString (with field list) Constructor that verifies that the field are prefixed by a name and descriptor type. It also verifies that it is a valid. known descriptor type and creates a valid XML string to support the descriptor type using the names and values supplied in the list. getField Finds the given field name in a descriptor and returns the value. In this case the field representation of the descriptor is not XML-encoded, to prevent needless encoding and parsing when looking for a particular field value. setField Finds the given field name in a descriptor and sets its to the provided value. In this case the field representation of the descriptor is not be XML-encoded, to prevent needless encoding and parsing when handling a field value. getFields Parses the XML encoded string and returns an array of strings in "fieldName=fieldValue"format.

The fields defined in the XML format describe various information about MBean components. All fields for each of the XML descriptors are specified below.

The Attribute Descriptor Fields are now considered.

AttributeDescriptorString an instance of the XMLString which represents the metadata for attributes of a model MBean. These are its possible fields, with optional ones in italics: name-name of the attribute. descriptorType-constant with the value"attribute". type-type of the attribute, can be a base type or open data type. value-current value of attribute, if set. default-value to be returned if'value'is not set and the getMethod is not defined. readOnly-boolean value which indicates if the attribute is readable only, or readable and writable. displayName-displayable name of attribute. description-description of attribute. getMethod-operation name from OperationDescriptors to be used to retlieve the value of the attribute. The returned value is saved in the value field.

setMethod-operation name from OperationDescriptors to be used to set the value of the attribute in the managed resource. The new value will be saved in the value field. protocolMap-list of protocol. type. identifier triplets. This allows the attribute to be associated with a particular identifier (CIM schema, SNMP MIB Oid. etc.) for a particular protocol. This mapList should be set by the managed resource and used by the adaptors to management systems. persistPolicy-consists of one of the following values: -Never-the attribute is never persisted. This is useful for highly volatile data or data that only has meaning within the context of a session or execution period.

-OnTimer-the attribute is persisted whenever the ModelMBean service persistPeriod expires.

-OnUpdate-the attribute is persisted every time the attribute is updated.

-NoMoreOftenThan-the attribute is persisted every time it is updated unless the updates are closer together than the persistPeriod. This acts as an update throttling mechanism that helps prevent temporarily highly volatile data from impacting performance. persistPeriod-valid only if persistPolicy is OnTimer or NoMoreOftenThan. For OnTimer the attribute is persisted at the beginning of each persistPeriod starting from when the value is first set. For NoMoreOftenThan the attribute will be persisted every time it is updated as long as the updates are not closer together than the persistPeriod. currencyTimeLimit-time period in seconds from when a value is set that the value is'current'and not'stale'. If the value is current then the saved value is returned and the getMethod (if defined) is not invoked. If the currencyTimeLimit is 0, then the value must be retrieved on every request. If currencyTimeLimit is-I then the value is never stale.

IastUpdatedTimeStamp-time stamp from when the last time the value field was updated. iterable-boolean value. I rue indicates the value in enumerable. False indicates the value is not enumerable. presentationString-XML-encoded string which describes how the attribute should be presented.

The Operation Descriptor Fields comprise OperationDescriptorString, an instance of the XMLString which represents the metadata for operations of a model MBean. These are its possible fields, with optional ones in italics: name-

operation name. descriptorType- constant with the value 'operation". responseType- return type from operation. Can be a base type or openData type. arguments []- triplet of input parameter name (displayable name), type (base or openData). and value (which is optional) required to execute the method. If the value is set in the descriptor and the value is not set in the invoke () method, then the value in the descriptor for a parameter is used as the default. signature- method signature as used in the reflection API. displayName- display name of operation. description- description of operation. impact- contains values'info'or'action'. If the value is'info'then the operation does not affect the state of the managed resource or have any permanent side affects. If the value is'action'then the operation or a side affect of the operation changes the state of the managed resource. lastReturnedValue- the value that was returned from the operation the last time it was executed. This allows the caching of operation responses. Operation responses are only cached if the currencyTimeLimit is not 0. currencyTimeLimit- the period of time in seconds that the lastReturnedValue is'current'and not stale.

If the value is current then it is returned without actually invoking the method on the managed resource. If the value is stale then the method is invoked. If currencyTimeLimit is 0, then the value is always stale and is not cached. If the currencyTimeLimit is-1, then the value is never stale. lastReturnedTimeStamp- the time stamp of when the lastReturnedValue field was updated. presentationString- XML-encoded string that defines how to present the operation, parameters, and return type to a user.

Now turning to the Notification Descriptor Fields, they comprise a NotificationDescriptorString, an instance of the XMLString which represents the metadata

for the notifications of a model MBean. These are its possible fields, with optional ones in italics: name- name of the notification. type- type of the notification. severity- Range of 1-5 meaning: Info, Warn. Severe, Error, or Failure. messageId- ID for the notification. Usually used to retrieve text to match the ID to minimize message size or perform client side translation. messageText- text String describing the notification.

NotificationObjects []- list of objects that are passed with the notification in the userData attribute if the userData attribute is not already set.

NumberOfListeners- current number of listeners registered for this notification. The listeners are unique per listener object, handback object, and filter object.

PresentationString- XML-encoded string which describes how to present the notification to a user.

Code examples CE-9 through CE-11 respectively show examples of the XML grammar for: -the"AttributeDescriptorString"instance, -the"OperationDescriptorString"instance, -the"NotificationDescriptorString"instance.

Exhibit C. 1-Managed Bean Server (MBean Server) The Managed Bean Server, or MBean server. is an important component of the Agent infrastructure. The MBean server. which acts as a registry for MBeans in the agent, is the component which provides the services for manipulating MBeans. In fact, all management operations performed on the MBeans may be done through the MBeanServer interfaces.

In general, the following kinds of MBeans would be registered in an MBean server: -MBeans which represent managed resources for management purposes. These resources may be of any kind: application, system, or network resources which provide a Java interface or a Java wrapper.

-MBeans which add management functionality to the agent. This functionality may be fully generic, providing for instance a logging of a monitoring capability, or it may be specific to a technology or to a domain of application. Some of these MBeans are defined herein, others may be provided by management application developers.

-Some components of the infrastructure, for example, the protocol adaptors may be themselves implemented as MBeans. This allows such components to benefit from the dynamic management infrastructure.

A.-Registration of MBeans The MBean server is firstly a regtistr, in which MBeans may be registered either by a management application, or by other MBeans. The interface of the MBeanServer class may allow two different kinds of registration: -Registration of an MBean upon its instantiation of a new MBean In this case, the loading of the java class of the MBean can be done either by using a default class loader, or by explicitly specifying the class loader to use.

-Registration of an already existing MBean.

An object name is assigned to an MBean when it is registered. The object name is a string whose structure is defined in detail in ObjectName in Exhibit A. I. The object name allows an MBean to be identified uniquely in the context of the MBean server. This unicity is checked at registration time by the MBean server, which will refuse MBeans with duplicate names.

B.-MBean Registration Control

Optionally (if the MBean developer chooses it), the MBean server may implement the "MBeanRegistration"interface. comprising one or more of the following methods: -preRegister- this is a call-back method that the MBeanServer will invoke before registering the MBean. The MBean will not be registered if any exception is raised by this method.

This method may throw the"MBeanRegistrationException"which will be re-thrown as is by the MBean server. Any other exception will be caught by the MBean server, encapsulated in an"MBeanRegistrationException"and re-thrown. This method may be used to: . Allow an MBean to keep a reference on its MBean server.

. Perform any initialization that needs to be done before the MBean is exposed to management operations.

. Perform semantic checking on the object name, and possibly provide a name if the object was created without a name.

. Get information about the environment, for instance, check on the existence of services the MBean depends upon. When such required services are not available, the MBean might either try to instantiate them, or raise a "ServiceNotFoundException"exception.

-postRegister- this is a call-back method that the MBean server will invoke after registering the MBean. Its boolean parameter will be true if the registration was done successfully, andfalse if the MBean could not be registered.

-preDeregister- this is a call-back method that the MBean server will invoke before de-registering an MBean. This method may throw an"MBeanRegistrationException", which will be re-thrown as is by the MBean server. Any other exception will be caught by the MBean server, encapsulated in an"MBeanRegistrationException"and re-thrown.

The MBean will not be de-registered if any exception is raised by this method.

-postDeregister- this is a call-back method that the MBean server will invoke after de-registering the MBean.

Figures 13 and 14 describe the way the methods of the"MBeanRegistration"are called by the"MBeanServer"class when an MBean registration or a de-registration is performed. The methods illustrated with a thick border are MBeanServer methods, the others are implemented in the MBean.

Thus, by implementing the"MBeanRegistration"interface, the MBean developer may exercise some control upon the registering/unregistering of the MBean in the MBean server.

Before and after registering and deregistering an MBean, the MBean server checks dynamically whether the MBean implements the"MBeanRegistration"interface. If this is the case, the appropriate call-backs are invoked.

Implementing this interface is also the only means by which MBeans can get a reference to the MBeanServer with which they are registered. This means that they are aware of their management environment and become capable of performing management operations on other MBeans.

C.-Operations on MBeans The interface of the"MBeanServer"class allows the following management operations to be performed on registered MBeans: -Retrieve a specific MBean by its object name.

-Retrieve a collection of MBeans, by means of a pattern matching on their names, and optionally by means of a filter applied to their attribute values. Such a filter may be constructed by using the query expressions defined in Exhibit C-2.

-Get one or several attribute value (s) of an MBean.

-Invoke an operation on an MBean.

-Discover the management interface of an MBean, that is, its attributes and operations. This is what is called the introspection of the MBean.

-Register interest in the notifications emitted by an MBean.

D.-MBeanServer Delegate Object The MBeanServer defines a domain called"JMImplementation"in which one object of class MBeanDelegateObject is registered: This object identifies and describes the MBeanServer in which it is registered. It also allows handles the notifications emitted by the MBeanServer.

In other words, this MBean acts as a delegate for the MBeanServer which it represents.

The complete object name of this delegate object is specified by JMX, as follows: "JMImplementation: type = MBeanServerDelegate".

The delegate object provides the following information about the MBeanServer: -The MBeanServerId, which has a value of type String. It identifies the agent. The format of this string is not specified.

-The MBeanServerVersion, which has a value of type String. It identifies the version of the JMX Agent Specification on which this MBeanServer implementation is based. For this version of the Specification. the jmxVersion string is"2.0".

The MBeanDelegateObject class implements the NotificationBroadcaster interface and sends the MBeanServerNotifications that are emitted by the MBean server. Object wishing to receive these notifications must register with the delegate object (see"MBean Server Notifications'in this specification.

The"JMlmplementation"domain name may be reserved for use by JMX Agent implementations.

E.-Remote Operations on MBeans Using an appropriate protocol adaptor in the agent, a remote management application will be able to perform operations on the MBeans.

Figure 15 shows how a management operation can be propagated from a remote management application to the MBean on the agent side. The example illustrates the propagation of a method for getting the"State"attribute of an MBean, in the following cases: -The management application uses a static invocation interface, typically invoking a getState () method on a proxy object (in the case of a Java application).

-The management application uses a dynamic invocation interface, invoking a generic getValue () method. This type of dynamic invocation is typically used in conjunction with the MBean introspection functionality which allows to discover dynamically, even from a remote JVM, what the properties of a MBean are.

F.-MBean Server Notifications When specific management operations are performed, the MBeanServer will emit notifications. A specific sub-class of Notification is defined for this purpose: the MBeanServerNotification class which contains a list of object names. The MBean server emits the following two types of notifications: -jmx. mbean. created This notifications informs of the registration of one or several MBeans. The notification will convey the list of object names of these MBeans.

-jmx. mbean. deleted This notifications informs of the de-registration of one or several MBeans. The notification will convey the list of object names of these MBeans.

In the example, when attributes of registered MBeans change values, this type of notification is handled directly by the MBean, as described in"Attribute Change Notifications"in section B of Exhibit A. 2. However, such notifications might also be sent by the MBean server as well.

The MBean server delegate object is in charge of emitting the MBean server notifications.

This permits to use the same model for the MBean server notifications as was used for MBean notifications.

By implementing the NotificationListener interface, an event consumer may receive both MBean notifications, and MBeanServer notifications. To register for MBean server notifications, an event consumer will use the same MBean server interface as when registering for MBean notifications, but will provide the name of the MBean server delegate object.

Exhibit C. 2-Queries Query expressions are used as filters and allow to retrieve MBeans according to their attribute values within an MBean server.

A query expression is used in conjunction with an object name pattern in order to perform the selected retrieval. For example, the method: queryMBeans (ObjectName name, QueryExp query) will: -have a"scope"which is the set of MBeans whose object name satisfies the specified"name pattern" -"filter"the MBeans in this scope and retrieve only those that satisfy the specified"query expression" The filtering may be performed by the repository service, when it supports this functionality.

The"isFiltering ()"method of the repository service indicates whether it is able to perform filtering. The filtering is otherwise performed by the MBean server.

To construct a complete query, one needs to express the relational operators (like"and", "or","match"..) and the values that can be used as arguments to these operators ("string", "number","attribute"..). The agent or the manager should be able to express a query like: "Retrieve the MBeans for which the attribute"age"is greater than 10 and the attribute "name"starts with"G"and ends with"ling".

Three primary classes may be defined for developing query expressions: -"QueryExp"represents the relational operators.

-"ValueExp"represents the values that can be used as arguments to relational operators. -"Query"supports the construction of the query. It contains static methods that return the appropriate"QueryExp"and"ValueExp"objects.

The classes defined for expressing specific queries derive either from"QueryExp"or from "ValueExp"classes. The names of the classes deriving from"QueryExp"end e. g. with "QueryExp"and the names of the classes deriving from"ValueExp"end e. g. with "ValueExp".

With the classes defined in JMX, the above mentioned query will be built as shown in Code Example CE-5.

Using the"ValueExp"the agent or the manager can perform filtering asking for an attribute of an MBean to satisfy certain constraints. The attributes that can be used for filtering purposes are all the attributes exposed by the MBean for management. It is also possible to perform a query based on the Java implementation class of the MBean. allowing the selection of MBeans belonging to the same class.

CODE EXAMPLE CE-6 shows how to build a query for retrieving all the MBeans of Java class"managed. device. Printer".

Constructing or performing queries can result in some exceptions which are specific to the filter service. These exceptions are defined and described hereinafter.

The Interfaces and Classes for queries will now be discussed.

The"Query"class supports construction of query object constraints. The static methods provided return query expressions that may be used in listing and enumerating MBeans.

Individual constraint constructing methods allow only appropriate types as arguments.

Composition of calls can construct arbitrary nestings of constraints, as illustrated in code example CE-7.

The"QueryEval"class allows a query to be accessed in the context of a specific MBean server.

The"QueryExp"class represents relational constraints that can be used in database query "where clauses."Instances of"QueryExp"are returned by the static methods of the"Query" class.

The"ValueExp"class represents values that can be passed as arguments to relational expressions. Strings, numbers, attributes are valid values and are represented respectively by instances of"StringValueExp","AttributeValueExp","NumericValue"and "BooleanValueExp", all of which implement"ValueExp.

The"AttributeValueExp"class represents attributes used as arguments to relational constraints. An"AttributeValueExp"may be used anywhere a"ValueExp"is required.

A"StringValueExp"class represents strings that are arguments to relational constraints. A "StringValueExp"may be used anywhere a"ValueExp"is required.

The"BadAttributeValueExpException"is thrown when an invalid MBean attribute is passed to a query constructing method.

A"BadStringOperationException"is thrown when an invalid string operation is passed to a method for constructing a query.

A"BadBinaryOpValueExpException"is thrown when an invalid expression is passed to a method for constructing a query.

An"InvalidApplicationException"is thrown when an attempt is made to apply either of the following: . A subquery expression to an MBean . A qualified attribute expression to an MBean of the wrong class.

Exhibit C. 3-Advanced Dynamic Loading This chapter describes services which provide the ability to instantiate MBeans using new Java classes and possibly native libraries loaded dynamically from the network.

This chapter introduces the m-let service which is used to instantiate MBeans obtained from a remote URL (Universal Resource Locator) on the network. M-let is an abbreviation for management applet. This is a mandatory JMX component for all JMX compliant agents.

M-let Service The m-let Service allows you to instantiate and register in the MBeanServer, one or several MBeans coming from a remote URL. The m-let service does this by loading an m-let text file. which specifies information on the MBeans to be obtained. The information on each MBean is specified in a single instance of a tag, called the MLET tag. The location of the m-let text file is specified by a URL. When an m-let text file is loaded, an instance of each MBean specified in the file is created and registered. The m-let service is itself implemented as an MBean and registered in the MBeanServer, so it can be used either by other MBeans, or by management applications.

The operation of the m-let service is illustrated in Figure 16. The MLET tag has the syntax shown in Example CE-8 of Exhibit D, where: CODE = class This attribute specifies the full Java class name, including package name, of the MBean to be obtained. The compiled. class file of the MBean must be contained in one of the JAR files specified by the ARCHIVE attribute.

Either CODE or OBJECT attribute must be present.

OBJECT = serfile This attribute specifies the. ser file that contains a serialized representation of the MBean to be obtained. This file must be contained in one of the JAR files specified by the ARCHIVE attribute. If the JAR file contains a directory hierarchy, specify the path of the file within this hierarchy. Otherwise a match will not be found. Either CODE or OBJECT must be present.

ARCHIVE = archiveList This mandatory attribute specifies one or more JAR files containing MBeans or other resources used bv the MBean to be obtained. One of the JAR files must contain the file specified by the CODE or OBJECT attribute. If archivelist contains more than one file: -Each file must be separated from the one that follows it by a comma (,).

-archivelist must be enclosed in double quote marks.

All JAR files in archivelist must be stored in the directory specified by the code base URL.

CODEBASE = codebaseURL This optional attribute specifies the code base URL of the MBean to be obtained. It identifies the directory that contains the JAR files specified by the ARCHIVE attribute. Specify this attribute only if the JAR files are not in the same directory as the m-let text file. If this attribute is not specified, the base URL of the m- let text file is used.

NAME = MBeanName This optional attribute specifies the string format of an object name to be assigned to the MBean instance when the m-let service registers it.

VERSION = version This optional attribute specifies the version number of the MBean and associated JAR files to be obtained. This version number can be used to specify that the JAR files are loaded from the server to update those stored locally in the cache the next time the m-let text file is loaded. version must be a series of non-negative decimal integers each separated by a dot. arglist This optional attribute specifies a list of one or more arguments to pass to the constructor of the MBean to be

instantiated. A constructor with a signature that matches the types of the arguments specified in the arglist will be looked for in the interface of the MBean java class. This method for constructing object is limited to constructor arguments for which there is a string representation. Each item in the arglist corresponds to an argument in the constructor. Use the following syntax to specify argList: <ARG TYPE=argumentType VALUE=argumentValue> where: argumentType is the type of the argument (e. g.

String, Integer..) argumentValue is the string representation of the value of the argument The MLet class implements the MLetMBean, which contains the methods exposed for remote access. Figure 17 illustrates the implementation of the MLet service in the agent as an MBean.

Exhibit C. 4-Monitoring A specific family of MBeans. the monitor MBeans. allows to observe the variation over time of attributes values in other MBeans.

Using a monitor MBeans, the observed attribute of another MBean (the observed MBean) is monitored at intervals specified by the granularity period. The type of the observed attribute is one of the types supported by the specific monitor sub-class which is used. The monitor derives a value from this observation, called the derived gauge. This derived gauge is either the exact value of the observed attribute, or the difference between two consecutive observed values of this attribute.

Monitoring services are not mandatory parts of JMX-compliant agents, but they must be implement in full when offered.

A specific type of notification is sent by the monitor MBeans when the value of the derived gauge satisfies one of a set conditions. The conditions are specified when the monitor is initialized. Monitors may also send notifications when certain error cases are encountered during the observation.

Information on the value of an attribute within an MBean may be provided by three different types of monitor MBeans: -"CounterMonitor"-observes attributes with integer types (byte. int, short, long) which behave like a counter; that is: . their value is always positive or null . they can only be incremented.

. they may wrap, and in that case a modulus value is defined -"GaugeMonitor"-observes attributes with integer or floating point types (float, double) which behave as a gauge.

-"StringMonitor"-it observes an attribute of type String.

All types of monitors extend the abstract"Monitor"class, which defines common attributes and operations. Figure 20 provides the class diagram of the various monitor MBeans, with the interfaces they implement, in an example.

The"MonitorNotification"Class is a specific sub-class of the"Notification"class, defined for use by the monitor MBeans. The"MonitorNotification"is used to report one of the following cases: -One of the conditions explicitly monitored is detected-that is. a threshold is reached.

-An error occurs during an observation of the attribute, for example, the observed object is no longer registered.

The"MonitorNotification'contains the following information: -the observed object name, -the observed attribute name, -the derived gauge, that is, the last value computed from the observation, -the threshold value or string which triggered this notification The tree of notification types which may be generated by monitor MBeans is described in Figure 18.

Common Monitor Notification Types are Notifications from a set of types common to all kinds of monitors, which may be generated by monitor MBeans to reflect error cases: -jmx. monitor. error. mbean This type of notification is sent when the observed MBean is not registered in the MBean server. The observed object name is provided in the notification.

-jmx. monitor. error. attribute This type of notification is sent when the observed attribute does not exist in the observed object. The observed object name and observed attribute name are provided in the notification.

-jmx. monitor. error. type This type of notification is sent when the observed attribute is not of an appropriate type. The observed object name and observed attribute name are provided in the notification.

-jmx. monitor. error. runtime All exceptions (except the cases described above) when trying to get the value of the observed attribute are caught by the monitor and will be reported in a notification of this type.

-jmx. monitor. error. threshold This type of notification is sent in case of any incoherence in the configuration of the gauge thresholds: . the low threshold has a va lue greater than or equal to the value of the high threshold . the low threshold and high threshold are not of the same type . at least one of the thresholds is not of the same type as the observed attribute A"CounterMonitor"sends a notification when the value of the counter reaches or exceeds a threshold known as the comparison level. In addition, an offset mechanism enables particular counting intervals to be detected, as follows:

-If the offset value is not zero. whenever the threshold is triggered by the counter value reaching a comparison level. that comparison level is incremented by the offset value. This is regarded as taking place instantaneously. that is. before the count is incremented. Thus. for each level. the threshold triggers an event notification every time the count increases by an interval equal to the offset value.

-If the counter we are monitoring wraps around when it reaches its maximum value then the modulus value needs to be set to that maximum value. The modulus is the value at which the counter is reset to zero.

-If the counter difference option is used, then the value of the derived gauge is calculated as the difference between the observed counter values for two successive observations. If this difference is negative then the value of the derived gauge is incremented by the value of the modulus. The derived gauge value (V [t]) is calculated using the following method, where GP is the granularity period: . if (counter [t]-counter [t-GP]) is positive then V [t] = counter [t]-counter [t-GP] . if (counter [t]-counter [t-GP]) is negative then V [t] = counter [t]-counter [t-GP] + MODULUS The operation of the"CounterMonitor"is illustrated in Figure 19.

The monitor observes a counter C (t) which varies with time t. The granularity period is GP and the comparison level is T. A"CounterMonitor"sends a notification when the value of the counter reaches or exceeds the comparison (threshold) level.

After the notification has been sent, the comparison level is incremented by the offset value until the comparison level is greater than the current value of the counter.

In addition to the common monitor notification types, a"CounterMonitor"MBean may send the following type of Notification: jmx. monitor. counter. threshold This type of notification is sent when the derived gauge has reached the threshold value.

A"GaugeMonitor"Class permits to instanciate a"GaugeMonitor", i. e. a monitor which observes an attribute which behaves as a gauge. A hysteresis mechanism is provided to avoid the repeated triggering of notifications when the gauge makes small oscillations around the threshold value. This capability is provided by specifying threshold values in pairs; one being a high threshold value and the other being a low threshold value. The

difference between threshold values is the hysteresis interval. The gauge monitor has the following structure: -The threshold high value attribute defines the value that the gauge must reach or exceed in order to optionally generate a notification, together with a notify high on/off attribute, whose value controls the generation of the notification.

-The threshold low value attribute defines the value that the gauge must fall to or below in order to optionally generate a notification, together with a notify low on/off attribute, whose value controls the generation of the notification.

The gauge monitor has the following constraints: -The threshold high value and the threshold low value properties are of the same type as the observed attribute.

-The threshold high value is greater than or equal to the threshold low value.

The gauge monitor has the following behavior: -initially, if notify-high's on/off switch is true and the gauge value becomes equal to or greater than threshold high value, in a positive direction, then the defined notification is triggered; subsequent crossings of threshold high value will not cause further generation of event reports unless the gauge value becomes equal to or less than the threshold low value.

-initially, if notify-low's on/off switch is true and the gauge value becomes equal to or less than threshold low value, in a negative direction, then the defined notification is triggered; subsequent crossings of threshold low value will not cause further generation of event reports unless the gauge value becomes equal to or greater than the threshold high value.

If the gauge difference option is used, then the value of the derived gauge is calculated as the difference between the observed gauge values for two successive observations.

The derived gauge value (V [t]) is initially calculated using the following equation, where GP is the granularity period: V [t] = gauge [t]-gauge [t-GP] The operation of the"GaugeMonitor"is illustrated in Figure 22.

The monitor monitors an attribute P (t) that varies with time t. The granularity period is G, the lower threshold is TL, and the higher threshold is TH.

In addition to the common monitor notification types, a"GaugeMonitor"MBean may send the following types of Notifications (GaugeMonitor Notification Types): -jmx. monitor. gauge. high

This type of notification is sent when the derived gauge has exceeded the high threshold value.

-jmx. monitor. gauge. low This type of notification is sent when the derived gauge has exceeded the low threshold value.

A"StringMonitor"is a monitor which observes an attribute of type"String". The derived gauge in this case is exactly the value of the observed attribute. The"StringMonitor"is configured with a value for the string called string-to-compare, and is able to detect the following two conditions: -The derived gauge matches the string-to-compare. If the notify-match flag of the monitor is set, then a notification is sent. At the following observation points, no other notification will be sent while the attribute value matches the string-to-compare.

-The value of the derived gauge differs from the string-to-compare. If the notify-differ flag of the monitor is set, then a notification is sent. At the following observation points, no other notification will be sent, while the attribute value differs from the string-to-compare.

This mechanism ensures that matches and differs are strictly alternating, each occurring the first time the condition is observed.

The operation of the"StringMonitor"is illustrated in Figure 21. In this example, a "StringMonitor"monitors a String attribute that varies with time t. The granularity period is GP, and the string-to-compare is"XYZ".

In addition to the common monitor notification types, a StringMonitor MBean may send the following types of Notifications: -jmx. monitor. string. matches This type of notification is sent when the derived gauge matches the string to compare.

-jmx. monitor. string. differs This type of notification is sent when the derived gauge differs from the string to compare.

Exhibit C. 5-Timer services The"Timer Service''enables to send notifications at specific dates and times. The notifications are sent to all objects registered to receive notifications. An object is registered to receive notifications by adding a notification listener interface. There is no dedicated timer listener nor dedicated timer notifications.

Generally, the"Timer"class manages a list of dated notifications. A method is provided that allows to add/remove notifications into/from the list. If any of the notifications in the list have dates that have passed. the timer either sends them immediately or discards them. This behavior is defined by setting the"sendPastNotifications"flag.

In an example, the timer service may manage notifications in two different ways: -Notifications that occur only once, -Notifications that are repeated with a defined periodicity and/or number of occurrences.

This behavior is defined by the parameters passed to the timer when the notification is added into the list of notifications.

Notifications may be added to the list of notifications using the timer's"addNotification" method. The"addNotification"method is overloaded and, in addition to the notification and date, can take the following optional parameters: -periodlnMillis: the periodicity of the added notification.

-nbRepetitions: the number of times that the notification will occur. If the value of nbRepetitions is zero or is not defined. the notification repeats infinitely. If the notification to be inserted has a date that is before the current date, the"addNotification"method may attempts to update this entry as follows: . If the notification is added with a non-null periodicity, the method updates the notification date by adding the defined periodicity until the notification date is later than the current date. When the notification date is later than the current date, the method inserts the notification into the list of notifications.

. If a number of repetitions is specified with the periodicity, the method updates the notification date as before. The number of times that the method adds the periodicity is limited to the specified number of repetitions which is decreased in proportion. If the notification date remains earlier than the current date, a standard Java "IllegalArgumentException"is thrown.

. If the notification is added with a null periodicity, the notification date cannot be updated to a valid date and a standard Java"IllegalArgumentException"is thrown.

After a notification has been added to the list of notifications, its associated parameters cannot be updated.

Notifications may be removed from the list of notifications using the timer's "removeNotification'method. The"removeNotification method is overloaded and can take either the notification or its position in the list as parameters. If the notification specified is not in the list or the index is invalid, the method throws an"InstanceNotFoundException".

The timer is started using the timer"start"method and stopped using the"stop"method. If the list of notifications is empty when the timer is started. the timer waits for a notification to be added.

One can determine whether the timer is running or not by invoking the timer method "isActive". The"isActive'method returns true if the timer is running. If any of the notifications have associated dates that have passed when the timer is started, the notification is ignored or sent immediately. The action taken is defined by the "sendPastNotifications"flag.

-"sendPastNotifications"= true: all notifications with a date before the current date are handled; the notification date is updated and the notification is sent.

-"sendPastNotifications"= false: notifications with a date before the current date are ignored; the notification date is updated but no notification is sent.

Setting the"sendPastNotifications"flag to false can be used to suppress a flood of notifications being sent out when the timer is started. The default value for this flag is false.

Exhibit D CODE EXAMPLE CE-1 Constructors of the Simple MBean public class Simple{ private Integer state = new Integer (0); //Default constructor only accessible from sub-classes // protected Simple(){ } //Public constructor: this class may be considered an MBean // public Simple (Integer s){ state = s; } } CODE EXAMPLE CE-2 The"MyClass"MBean definition and associated"MyClassMBean" public interface MyClassMBean{ public Integer getState (); public void setState (Integer s); public void reset () ; } public class MyClass implements MyClassMBean { private Integer state = null; private String hidden = null; public Integer getState () { return (state) ; } public void setState (Integer s) { state = s;

) public String getHidden () { return (hidden); } public void setHidden (String h) { hidden = h ; } public void reset(){ state = null ; hidden = null ; } CODE EXAMPLE CE-3 public interface ModelMBean{ public void initialize (AttributeDescriptorList adl, OperationDescriptorList odl, NotificationDescriptorList ndl) ; public initialize (MBeanInfo mbi) ; public initialize (String idlString) ; public initialize (String xmlString) ; public AttributeDescriptorList getAttributeDescriptors (); public void setAttributeDescriptors ( AttributeDescriptorList adl); public OperationDescriptorList getOperationDescriptors () ; public void setOperationDescriptors ( <BR> <BR> <BR> OperationDescriptorList odl) ;<BR> <BR> <BR> <BR> p u b 1 i c N o t i f i c a t i o n D e s c r i p t o r L i s t<BR> <BR> <BR> <BR> getNotificationDeseriptorsO ; public void setNotificationDescriptors ( NotificationDescriptorList ndl); public DescriptorLisr_ getAllDescriptor () ; public void setAllDe : scriptors ( DescriptorList dl) ; protected void load (); protected void store () ; String findPersistenc (String mBeanName) ; }.

CODE EXAMPLE CE-4 public class XMLString{ /* fields are strings formatted as"fieldName=fieldValue" */ /* nested fields are named by "enclosingFieldName. fieldName" */ /* constructors public XMLString (String plainString); public XMLString (String [] fieldNames, String [ fieldValues); public XMLString (String [] fields); /* operations public String getField (String fieldName); public void setField (String fieldName, String fieldValue); public String [] getFields () ; }.

CODE EXAMPLE CE-5 QueryExp exp = Query. and ( Query. gt (Query. attr ("age"), Query. value (10)), Query. match (Query. attr ("name"), Query. value ("G*ling"))).

CODE EXAMPLE CE-6 QueryExp exp = Query. eq ( (Query. classattr (), Query. value ("managed. device. Printer"))) CODE EXAMPLE CE-7

QueryExp exp = Query. and.' Query. gt (Query. prop ("age"), Query. value (5)), Query. match (Query. prop ("name"), Query. value ("Smith"))) ; CODE EXAMPLE CE-8 <MLET CODE = class I OBJECT = serfile ARCHIVE ="archivelist" [CODEBASE = codebaseURL] [NAME = MBeanName] [VERSION = version] > [arglist] </MLET> CODE EXAMPLE CE-9 <attributeDescriptors> <attribute name="attr"descriptorType="ATTRIBUTE" type="attrType"readOn~Ly ="booleanValue" default="defaultValue"iterable="booleanValue" <BR> getMethod="getMethodSignature"<BR> setMethod="setMethodSignature" currencyTimeLimit="sss'lastUpdatedTime="systime" persistPolicy="Never#Update#NoMoreOftenThan#OnTimer"<BR&g t; persistPeriod="sss"di. splayName="attrNameString"<BR> description="attrDescriptionString" presentationString="xmLString"> <protocolMapname="pro ocolName"<BR> type="validValueTypeForProtocol"<BR> identifier="protocolElementToMapAttributeTo"><BR> </protocolMap> </attribute>

</attributeDescriptors> CODE EXAMPLE CE-10 <operationDescriptors> <operation name="operName"descriptorType="OPERATION" displayName="operDisplay"description="operDescr" impact="InfolAction"operResponseType="operType" lastReturnedValue="lastValue"currencyTimeLimit="sss" lastUpdatedTime="systime" <params> <param name="argName"type="argType" value="argValue"> </params> presentationString="xmlString"> </operation> </operationDescriptors> CODE EXAMPLE CE-11 <notificationDescriptors> <notification name="ntfyName"descriptorType="NOTIFICATION" type="ntfyClass"messageId="ntfyMsgId" messageText="ntfyMsgTxt"description="ntfyDescription" severity="InfolWarnISeverelErrorIFailure" numberListeners="intNumListenersReg" <BR> <BR> <BR> <notificationObjects><BR> <BR> <BR> <BR> <notificationObject narne="objName" type="objType"value="objValue"> </notificationObjects> presentationString="xm String"> </notification> </notificationDescriptions>