Internet DRAFT - draft-harold-jmxp
draft-harold-jmxp
Network Working Group W. Harold
Internet-Draft IBM Tivoli Software
Expires: November 6, 2003 May 8, 2003
Java(tm) Management Extensions Protocol
draft-harold-jmxp-00
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http://
www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on November 6, 2003.
Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved.
Abstract
This document describes a protocol, composed of a set of BEEP
profiles [9], that provides access to the attributes, operations, and
notifications supported by the MBeans registered with a JMX Agent.
Harold Expires November 6, 2003 [Page 1]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Notation and Terminology . . . . . . . . . . . . . . . . . . 5
3. JMXP Overview . . . . . . . . . . . . . . . . . . . . . . . 6
4. JMXP Profiles . . . . . . . . . . . . . . . . . . . . . . . 9
4.1 MBEANSERVER Profile . . . . . . . . . . . . . . . . . . . . 9
4.1.1 MBEANSERVER Profile Overview . . . . . . . . . . . . . . . . 9
4.1.2 MBEANSERVER Profile Identification and Initialization . . . 10
4.1.3 MBEANSERVER Profile Message Syntax . . . . . . . . . . . . . 10
4.1.4 MBEANSERVER Profile Message Semantics . . . . . . . . . . . 10
4.2 MBEAN Profile . . . . . . . . . . . . . . . . . . . . . . . 16
4.2.1 MBEAN Profile Overview . . . . . . . . . . . . . . . . . . . 16
4.2.2 MBEAN Profile Identification and Initialization . . . . . . 17
4.2.3 MBEAN Profile Message Syntax . . . . . . . . . . . . . . . . 17
4.2.4 MBEAN Profile Message Semantics . . . . . . . . . . . . . . 17
4.3 NOTIFICATION Profile . . . . . . . . . . . . . . . . . . . . 24
4.3.1 NOTIFICATION Profile Overview . . . . . . . . . . . . . . . 25
4.3.2 NOTIFICATION Profile Identification and Initialization . . . 25
4.3.3 NOTIFICATION Profile Message Syntax . . . . . . . . . . . . 25
4.3.4 NOTIFICATION Profile Message Semantics . . . . . . . . . . . 26
5. Common Profile Elements . . . . . . . . . . . . . . . . . . 28
5.1 The ARGUMENTS Element . . . . . . . . . . . . . . . . . . . 28
5.2 The RESPONSE Element . . . . . . . . . . . . . . . . . . . . 28
5.2.1 The EXCEPTION Element . . . . . . . . . . . . . . . . . . . 29
5.3 The VALUE Element . . . . . . . . . . . . . . . . . . . . . 29
5.3.1 Scalar Values . . . . . . . . . . . . . . . . . . . . . . . 30
5.3.2 Structured Values . . . . . . . . . . . . . . . . . . . . . 30
6. URL Schemes . . . . . . . . . . . . . . . . . . . . . . . . 39
6.1 The jmxp URL Scheme . . . . . . . . . . . . . . . . . . . . 39
6.1.1 Resolving IP/TCP Address Information . . . . . . . . . . . 39
6.2 The jmxps URL Scheme . . . . . . . . . . . . . . . . . . . . 40
7. Initial Registrations . . . . . . . . . . . . . . . . . . . 43
7.1 Registration: The MBEANSERVER Profile . . . . . . . . . . . 43
7.2 Registration: The MBEAN Profile . . . . . . . . . . . . . . 43
7.3 Registration: The NOTIFICATION Profile . . . . . . . . . . . 44
7.4 Registration: The jmxp URL Scheme . . . . . . . . . . . . . 44
7.5 Registration: The jmxps URL Scheme . . . . . . . . . . . . . 45
7.6 Registration: The System (Well-Known) TCP port number
for JMXP . . . . . . . . . . . . . . . . . . . . . . . . . . 45
8. Security Considerations . . . . . . . . . . . . . . . . . . 46
9. Reply Codes . . . . . . . . . . . . . . . . . . . . . . . . 47
10. The JMXP Schema . . . . . . . . . . . . . . . . . . . . . . 48
10.1 MBEANSERVER Element Schema . . . . . . . . . . . . . . . . . 48
10.2 MBEAN Element Schema . . . . . . . . . . . . . . . . . . . . 49
10.3 NOTIFICATION Element Schema . . . . . . . . . . . . . . . . 50
10.4 Common Element Schema . . . . . . . . . . . . . . . . . . . 50
References . . . . . . . . . . . . . . . . . . . . . . . . . 62
Harold Expires November 6, 2003 [Page 2]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
Author's Address . . . . . . . . . . . . . . . . . . . . . . 63
Intellectual Property and Copyright Statements . . . . . . . 64
Harold Expires November 6, 2003 [Page 3]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
1. Introduction
The Java(tm) Management Extensions (JMX) specification [14] defines a
Java technology based architecture for instrumenting and managing
applications and devices. The JMX architecture has three layers:
o Instrumentation
o Agent
o Distributed Services
The instrumentation layer is composed of "Managed Beans", or MBeans,
that represent JMX manageable resources that management applications
monitor and manipulate. The agent layer is made up of an MBeanServer
and a set of management services. The MBeanServer's purpose is
two-fold: it serves as a registry for MBeans, and it provides a
common interface to those MBeans. The agent layer's management
services, which are themselves MBeans, include monitoring,
relationship management, primitive scheduling, and component loading.
As of version 1.2 of the specification the content of the distributed
services layer is undefined. It's stated intent, however, is to
define the management interfaces and components that can operate on
agents or heirarchies of agents.
One essential requirement of the distributed services layer is remote
access to elements of the agent and instrumentation layers. The JMX
Protocol (JMXP) presented here defines a simple, language independent
mechanism that satisfies the remote access requirement. This
specification does not define any specific language bindings to JMXP.
Such bindings are clearly important since management applications and
consoles written in a variety of programming languages will need
remote access to management information supplied by new
JMX-instrumented applications and devices. Future documents will
specify JMXP bindings for particular programming languages as the
need arises.
Harold Expires November 6, 2003 [Page 4]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
2. Notation and Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [3]
Refer to [9]'s section 2.1 for a discussion of the roles that a BEEP
peer may play, including definitions of the terms "listener",
"initiator", "client", and "server".
<< Open issues/editorial notes are in brackets, like this. >>
Harold Expires November 6, 2003 [Page 5]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
3. JMXP Overview
JMXP is an application protocol that provides access to information
about a JMX Agent's MBeanServer and the MBeans registered with that
MBeanServer. JMXP also provides a mechanism for transmitting the
Notifications emitted by a JMX Agent's MBeans to remote clients.
According to On the Design of Application Protocols [10] an
application protocol can be defined by the formula:
application protocol = BEEP + 1 or more profiles
+ authorization policies
+ provisioning rules
JMXP defines three profiles: MBEANSERVER, MBEAN, and NOTIFICATION,
and uses standard Java 2 Platform Security mechanisms for
authorization. See Section 8 for a discussion of JMXP's approach to
remote authentication.
The MBEANSERVER profile provides information about the MBeanServer
and its MBeans. The MBEANSERVER profile is also responsible for
managing JMX Notification subscriptions. The MBEAN profile provides
access to individual MBeans. The NOTIFICATION profile delivers JMX
Notifications to JMXP clients. The MBEANSERVER and MBEAN profiles use
the familiar client/server exchange model. The NOTIFICATION profile
uses a server/client exchange model as described in [13] to deliver a
stream of Notifications to a client.
The figure below illustrates a simple MBEANSERVER profile interaction
between a client and a JMXP server.
Client JMXP Server
| |
| establish BEEP session |
|<------------------------------------------------------------->|
| security tuning |
|-------------------------------------------------------------->|
| |
| start MBEANSERVER channel (ch#1) |
|-------------------------------------------------------------->|
| |
|ch#1 ------- server-invocation method="queryMBeans" ---------->|
|<-------------------- response code="200" -----------------ch#1|
| |
| start MBEAN channel (ch#3) |
|-------------------------------------------------------------->|
| |
|ch#3 --- mbean-attributes mbean=":id=foo" action="set" ------->|
Harold Expires November 6, 2003 [Page 6]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
|<-------------------- response code="200" -----------------ch#3|
| |
| . |
| . |
| . |
| |
After the BEEP session is established and, optionally, tuned for
security the client starts an MBEANSERVER channel. The client then
sends a server-invocation request to the server which invokes the
queryMBeans() method on the MBeanServer associated with the JMXP
Server to select a set of MBeans, the names of those MBeans are
returned to the client in the server's query response. Individual
MBeans are accessed via an MBEAN channel; here the client starts an
MBEAN channel and uses it to set one or more attributes of an MBean
whose name was returned by the the server-invocation request. Note,
the same MBEAN channel can be used to access any of the MBeanServer's
MBeans; clients needn't open a separate MBEAN channel for each MBean
they access.
The next figure illustrates the use of the MBEANSERVER and
NOTIFICATION profiles to subscribe to JMX Notifications and
subsequently deliver them.
Client JMXP Server
| |
| establish BEEP session |
|<------------------------------------------------------------->|
| security tuning |
|-------------------------------------------------------------->|
| |
| start MBEANSERVER channel (ch#1) |
|-------------------------------------------------------------->|
| |
|ch#1 -------- notification-listener action="add" ------------->|
| |
| start NOTIFICATION channel (ch#2) |
|<--------------------------------------------------------------|
|ch#2 ----------------------- ready --------------------------->|
| |
|<-------------------- response code="200" -----------------ch#1|
| . |
| . |
| . |
|<----------------------- notification -------------------- ch#2|
| . |
|<----------------------- notification -------------------- ch#2|
| |
Harold Expires November 6, 2003 [Page 7]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
After the BEEP session is established and, optionally, tuned for
security the client starts an MBEANSERVER channel. Next the client
adds listeners for JMX Notifications from one or more MBeans
registered with the MBeanServer. The server responds by starting a
NOTIFICATION channel. The client sends a greeting over the
NOTIFICATION channel to start the server/client exchange and then the
JMXP Server sends a response to the add listener request. When JMX
Notifications that the client is listening for occur they are
delivered over the NOTIFICATION channel.
Harold Expires November 6, 2003 [Page 8]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
4. JMXP Profiles
4.1 MBEANSERVER Profile
4.1.1 MBEANSERVER Profile Overview
The MBEANSERVER profile is used to invoke methods on the MBeanServer.
The "server-invocation" element identifies the method to be invoked
and the arguments to be used in the invocation.
Only the following subset of the methods defined by the
javax.management.MBeanServer interface are available to JMXP clients:
o createMBean
o getDefaultDomain
o getMBeanCount
o getObjectInstance
o isInstanceOf
o isRegistered
o queryMBeans
o queryNames
o unregisterMBean
The MBEANSERVER profile also allows clients to express interest in
JMX Notifications emitted by MBeans registered with the MBeanServer.
The "notification-listener" element identifies a set of MBeans from
which the client would like to receive notifications.
<< The "notification-listener" element only supports remote
notification. Should the "server-invocation" element support
invocation of add/removeNotificationListener, with an ObjectName
second parameter? >>
<< The "notification-listener" element could include a "filter
string" that identified the Notification types the client is
interested in, should that be included in the element specification?
>>
Harold Expires November 6, 2003 [Page 9]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
4.1.2 MBEANSERVER Profile Identification and Initialization
The MBEANSERVER profile is identified as
http://iana.org/beep/transient/jmxp/MBEANSERVER
No data is piggybacked during channel creation
4.1.3 MBEANSERVER Profile Message Syntax
All BEEP messages in this profile have a MIME CONTENT-TYPE [2] of
application/beep+xml. The syntax of the individual elements is
specified in Section 10.
4.1.4 MBEANSERVER Profile Message Semantics
4.1.4.1 The NOTIFICATION-LISTENER Element
Clients send "notification-listener" elements over an MBEANSERVER
channel to express interest, or the lack thereof, in JMX
Notifications emitted by MBeans registered with an MBeanServer.
C:MSG 1 5 . 821 42
C:Content-Type: application/beep+xml
C:
C:<notification-listener action="add">
C: <arguments>
C: <value>
C: <ObjectName>JMImplementation:type=MBeanServerDelegate</ObjectName>
C: </value>
C: <value>
C: <ObjectName>timers:id=alarms</ObjectName>
C: </value>
C: </arguments>
C:</notification-listener>
C:END
The "notication-listener" element has a single attribute, "action",
which indicates the client's intent
o if the action attribute's value is "add" the request will add
listeners for JMX Notifications emitted by one or more MBeans
o if the action attribute's value is "remove" the request will
remove listeners associated with one or more MBeans
The "notification-listener" element also requires an arguments
(Section 5.1) element. The "arguments" element contains one or more
value (Section 5.3) elements that identify, by their ObjectNames, the
MBeans to which listeners should be added or from which listeners
Harold Expires November 6, 2003 [Page 10]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
should be removed.
The server communicates the result of the requested action to the
client by returning a response (Section 5.2) element. The "response"
element must contain an array of "value" elements. Each element of
the array represents an MBean for which a listener has been
successfully added/removed.
When the JMXP Server receives a "notification-listener" element it:
1. checks to see if a NOTIFICATION (Section 4.3) channel to the
client exists
* if not it attempts to start one; any errors encountered in the
process are reflected to the client in a response (Section
5.2) element
2. calls the MBeanServer's addNotificationListener(), or
removeNotificationListener() as appropriate, using each of the
given ObjectNames as the first parameter to the call
3. returns the set of ObjectNames for which listeners were
successfully added/removed in a response (Section 5.2) element
Here's an illustration of successfully adding a listener:
C:MSG 1 19 . 215 562
C:Content-Type: application/beep+xml
C:
C:<notification-listener action="add">
C: <arguments>
C: <value>
C: <ObjectName>JMImplementation:type=MBeanServerDelegate</ObjectName>
C: </value>
C: <value>
C: <ObjectName>timers:id=alarms</ObjectName>
C: </value>
C: </arguments>
C:</notification-listener>
C:END
... The JMXP Server hasn't started a NOTIFICATION channel yet ...
S:MSG 0 91 . 281 96
S:Content-Type: application/beep+xml
S:
S:<start number="2">
S: <profile uri="http://iana.org/beep/transient/jmxp/NOTIFICATION"/>
Harold Expires November 6, 2003 [Page 11]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
S:</start>
S:END
C:RPY 0 1 . 0 64
C:Content-Type: application/beep+xml
C:
C:<profile uri="http://iana.org/beep/transient/jmxp/NOTIFICATION">
C: <![CDATA[ready]]>
C:</profile>
C:END
... The JMXP Server calls addNotificationListener() ...
S:RPY 1 21 . 142 82
S:Content-Type: application/beep+xml
S:
S:<response code="200">
S: <value>
S: <array>
S: <value>
S: <ObjectName>JMImplementation:type=MBeanServerDelegate</ObjectName>
S: </value>
S: <value>
S: <ObjectName>timers:id=alarms</ObjectName>
S: </value>
S: </array>
S: </value>
S:</response>
S:END
Note: the client's "ready" message, which in the example above is
piggybacked on the response's "profile" element, to the server's
starting a NOTIFICATION channel kicks off the server/client exchange
that delivers subsequent JMX Notifications to the client.
Similarly, removing a listener might look like:
C:MSG 1 19 . 215 562
C:Content-Type: application/beep+xml
C:
C:<notification-listener action="remove">
C: <arguments>
C: <value>
C: <ObjectName>JMImplementation:type=MBeanServerDelegate</ObjectName>
C: </value>
C: </arguments>
C:</notification-listener>
C:END
Harold Expires November 6, 2003 [Page 12]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
... The JMXP Server has already started a NOTIFICATION channel ...
... The JMXP Server calls removeNotificationListener() ...
S:RPY 1 21 . 142 82
S:Content-Type: application/beep+xml
S:
S:<response code="200">
S: <value>
S: <array>
S: <value>
S: <ObjectName>JMImplementation:type=MBeanServerDelegate</ObjectName>
S: </value>
S: </array>
S: </value>
S:</response>
S:END
If this is the JMXP Server's last listener the server may choose to
close the NOTIFICATION channel at this point.
Attempting to add a listener for a non-existent MBean might look
like:
C:MSG 1 19 . 215 562
C:Content-Type: application/beep+xml
C:
C:<notification-listener action="add">
C: <arguments>
C: <value>
C: <ObjectName>JMImplementation:type=MBeanServerDelegate</ObjectName>
C: </value>
C: <value>
C: <ObjectName>timers:id=bogus</ObjectName>
C: </value>
C: </arguments>
C:</notification-listener>
C:END
... The JMXP Server has already started a NOTIFICATION channel ...
... The JMXP Server calls addNotificationListener() for each value ...
S:RPY 1 21 . 142 82
S:Content-Type: application/beep+xml
S:
S:<response code="200">
S: <value>
Harold Expires November 6, 2003 [Page 13]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
S: <array>
S: <value>
S: <ObjectName>JMImplementation:type=MBeanServerDelegate</ObjectName>
S: </value>
S: </array>
S: </value>
S:</response>
S:END
Finally, this exchange illustrates a NOTIFICATION channel start
failure:
C:MSG 1 19 . 215 562
C:Content-Type: application/beep+xml
C:
C:<notification-listener action="add">
C: <arguments>
C: <value>
C: <ObjectName>JMImplementation:type=MBeanServerDelegate</ObjectName>
C: </value>
C: </arguments>
C:</notification-listener>
C:END
... The JMXP Server hasn't started a NOTIFICATION channel yet ...
S:MSG 0 91 . 281 96
S:Content-Type: application/beep+xml
S:
S:<start number="2">
S: <profile url="http://iana.org/beep/transient/jmxp/NOTIFICATION"/>
S:</start>
S:END
C:ERR 0 8 . 0 64
C:Content-Type: application/beep+xml
C:
C:<error code="421">I want to be left alone</error>
C:END
S:RPY 1 21 . 142 82
S:Content-Type: application/beep+xml
S:
S:<response code="450"/>
S:END
Harold Expires November 6, 2003 [Page 14]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
4.1.4.2 The SERVER-INVOCATION Element
When a client wants to invoke one of the MBeanServer's methods it
sends a "server-invocation" element over an MBEANSERVER channel,
e.g.,
C:MSG 1 1 . 52 120
C:Content-Type: application/beep+xml
C:
C:<server-invocation method="createMBean">
C: <arguments>
C: <value><String>javax.management.timer.Timer</String></value>
C: <value><ObjectName>timers:id=alarms</ObjectName></value>
C: </arguments>
C:</server-invocation>
C:END
The "server-invocation" element has a single attribute, "method",
which identifies the MBeanServer method to client wants to invoke.
The "server-invocation" element also requires an arguments (Section
5.1) element. The "arguments" element contains a value (Section 5.3)
element for each of the specified method's parameters.
When the JMXP Server receives a "server-invocation" element on an
MBEANSERVER channel it attempts to invoke the specified method with
the arguments provided. The server communicates the result of its
invocation attempt to the client by returning a response (Section
5.2).
A successful MBeanServer method invocation might look like:
C:MSG 1 1 . 52 120
C:Content-Type: application/beep+xml
C:
C:<server-invocation method="createMBean">
C: <arguments>
C: <value><String>javax.management.timer.Timer</String></value>
C: <value><ObjectName>timers:id=alarms</ObjectName></value>
C: </arguments>
C:</server-invocation>
C:END
... JMXP Server invokes createMBean() with the given arguments ...
S:RPY 1 1 . 221 87
S:Content-Type: application/beep+xml
S:
S:<response code="200">
Harold Expires November 6, 2003 [Page 15]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
S: <value>
S: <ObjectInstance classname="javax.management.timer.Timer">
S: <ObjectName>timers:id=alarm</ObjectName>
S: </ObjectInstance>
S: </value>
S:</response>
S:END
Alternatively, an unsuccessful invocation might look like:
C:MSG 1 1 . 52 120
C:Content-Type: application/beep+xml
C:
C:<server-invocation method="createMBean">
C: <arguments>
C: <value><String>javax.management.Timer</String></value>
C: <value><ObjectName>timers:id=alarms</ObjectName></value>
C: </arguments>
C:</server-invocation>
C:END
... JMXP Server invokes createMBean() with the given arguments ...
S:RPY 1 1 . 221 87
S:Content-Type: application/beep+xml
S:
S:<response code="451">
S: <exception class="javax.management.ReflectionException">
S: <message>Class not found</message>
S: <target-exception class="java.lang.ClassNotFoundException"/>
S: </exception>
S:</response>
S:END
4.2 MBEAN Profile
4.2.1 MBEAN Profile Overview
The MBEAN profile is used to retrieve information about MBeans
registered with the MBeanServer, invoke operations on individual
MBeans, and to get/set individual MBean's attributes. The MBEAN
profile provides an element for each of these purposes.
o The "mbean-attributes" element identifies an mbean and the
attribute-related action to be taken. The possible actions are
"get", and "set". If the action is "get" the mbean-attributes
element includes the set of attribute names to be retreived. If
Harold Expires November 6, 2003 [Page 16]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
the action is "set" the mbean-attributes element includes a set of
attribute names paired with the values they are to receive.
o The "mbean-info" element indentifies an mbean whose MBeanInfo
metadata the client wishes to retreive.
o The "mbean-invocation" element identifies an mbean, the operation
to be invoked on that mbean, and the arguments to be used in the
invocation.
4.2.2 MBEAN Profile Identification and Initialization
The MBEAN profile is identified as
http://iana.org/beep/transient/jmxp/MBEAN
No data is piggybacked during channel creation
4.2.3 MBEAN Profile Message Syntax
All BEEP messages in this profile have a MIME CONTENT-TYPE [2] of
application/beep+xml. The syntax of the individual elements is
specified in Section 10.
4.2.4 MBEAN Profile Message Semantics
4.2.4.1 The MBEAN-ATTRIBUTES Element
When a client wants to get or set the value of one or more attributes
of a specific MBean it sends an "mbean-attributes" element on an
MBEAN channel, e.g.,
C:MSG 1 1 . 52 120
C:Content-Type: application/beep+xml
C:
C:<mbean-attributes mbean="JMImplementation:type=MBeanServerDelegate"
C: action="get">
C: <arguments>
C: <value><Attribute name="ImplementationVersion" /></value>
C: <value><Attribute name="MBeanServerId" /></value>
C: <value><Attribute name="SpecificationVersion" /></value>
C: </arguments>
C:</mbean-attributes>
C:END
The "mbean-attributes" element has two attributes
1. the "mbean" attribute is the string representation of the JMX
Harold Expires November 6, 2003 [Page 17]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
ObjectName associated with the target MBean
2. the "action" attribute indicates what the client wants to do to
the MBean's attributes
* if the action attribute's value is "get" then the request will
retreive the values of one or more of the MBean's attributes
* if the action attribute's value is "set" the the request will
update the values of one or more of the MBean's attributes
The "mbean-attributes" element also requires an arguments (Section
5.1) element. The "arguments" element contains an Attribute (Section
5.3.2.2) value for each attribute to which the request's action will
be applied.
When the JMXP Server receives an "mbean-attributes" element on an
MBEAN channel it invokes either the MBeanServer's getAttributes() or
its setAttributes() method depending on the value of the
"mbean-attributes" element's "action" attribute. The invocation's
ObjectName parameter is constructed using the value of the
"mbean-attributes" element's "mbean" attribute. The "Attribute"
elements are used to build the second parameter, an array of
java.lang.Strings in the case of getAttributes() or an AttributeList
in the case of setAttributes().
The server communicates the result of the invocation to the client by
returning a response (Section 5.2) element. Both getAttributes() and
setAttributes() return a javax.management.AttributeList. The server
translates this structure into an array of "Attribute" elements. This
"Attribute" array is included in the "response" element.
A successful attribute retrevial might look like:
C:MSG 1 1 . 52 120
C:Content-Type: application/beep+xml
C:
C:<mbean-attributes mbean="montiors:type=BeanCounter"
C: action="get">
C: <arguments>
C: <value><Attribute name="Modulus"/></value>
C: <value><Attribute name="Offset"/></value>
C: <value><Attribute name="Threshold"/></value>
C: </arguments>
C:</mbean-attributes>
C:END
... JMXP Server retrieves the requested attributes ...
Harold Expires November 6, 2003 [Page 18]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
S:RPY 1 1 . 221 87
S:Content-Type: application/beep+xml
S:
S:<response code="200">
S: <value>
S: <array>
S: <value>
S: <Attribute name="Modulus"><Integer>1024</Integer></Attribute>
S: </value>
S: <value>
S: <Attribute name="Offset"><Integer>256</Integer></Attribute>
S: </value>
S: <value>
S: <Attribute name="Threshold"><Integer>512</Integer></Attribute>
S: </value>
S: </array>
S: </value>
S:</response>
S:END
Similarly, a successful attribute update might look like this:
C:MSG 1 1 . 52 120
C:Content-Type: application/beep+xml
C:
C:<mbean-attributes mbean="montiors:type=BeanCounter"
C: action="set">
C: <arguments>
C: <value>
C: <Attribute name="Modulus"><Integer>2048</Integer></Attribute>
C: </value>
C: <value>
C: <Attribute name="Offset"><Integer>128</Integer></Attribute>
C: </value>
C: <value>
C: <Attribute name="Threshold"><Integer>192</Integer></Attribute>
C: </value>
C: </arguments>
C:</mbean-attributes>
C:END
... JMXP Server updates the specified attributes ...
S:RPY 1 1 . 221 87
S:Content-Type: application/beep+xml
S:
S:<response code="200">
S: <value>
Harold Expires November 6, 2003 [Page 19]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
S: <array>
S: <value>
S: <Attribute name="Modulus"><Integer>2048</Integer></Attribute>
S: </value>
S: <value>
S: <Attribute name="Offset"><Integer>128</Integer></Attribute>
S: </value>
S: <value>
S: <Attribute name="Threshold"><Integer>192</Integer></Attribute>
S: </value>
S: </array>
S: </value>
S:</response>
S:END
Finally, here's an illustration of an unsuccessful attribute update:
C:MSG 1 1 . 52 120
C:Content-Type: application/beep+xml
C:
C:<mbean-attributes mbean="montiors:type=bogus"
C: action="set">
C: <arguments>
C: <value>
C: <Attribute name="Threshold"><Integer>-2048</Integer></Attribute>
C: </value>
C: </arguments>
C:</mbean-attributes>
C:END
... JMXP Server attempts and fails to update the specified attribute ...
S:RPY 1 1 . 221 87
S:Content-Type: application/beep+xml
S:
S:<response code="451">
S: <exception class="java.lang.InstanceNotFoundException">
S: <message lang="en">
S: The specified MBean is not registered witht he MBeanServer
S: </message>
S: </exception>
S:</response>
S:END
4.2.4.2 The MBEAN-INFO Element
When a client wants to retreive the MBeanInfo metadata associated
Harold Expires November 6, 2003 [Page 20]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
with a specific MBean it sends an "mbean-info" element over an MBEAN
channel, e.g.,
C:MSG 1 1 . 52 120
C:Content-Type: application/beep+xml
C:
C:<mbean-info mbean="JMImplementation:type=MBeanServerDelegate"/>
C:END
The "mbean-info" element has a single attribute, "mbean", which is
the string representation of the JMX ObjectName associated with the
target MBean.
When a JMXP Server receives an "mbean-info" element on an MBEAN
channel it invokes the MBeanServer's getMBeanInfo() method with the
ObjectName specified in the "mbean" attribute. The server
communicates the result of the invocation to the client by returning
a response (Section 5.2) element containing an mbean-info-data value
(Section 5.3.2.5).
A successful MBeanInfo exchange might look like:
C:MSG 1 17 . 152 77
C:Content-Type: application/beep+xml
C:
C:<mbean-info mbean="monitors:id=BeanCounterMonitor"/>
C:END
... JMXP Server calls getMBeanInfo() ...
S:RPY 1 11 . 281 265
S:Content-Type: application/beep+xml
S:
S:<response code="200">
S: <value>
S: <mbean-info-data name="javax.management.monitor.CounterMonitor"
S: description="Monitor the number of beans">
S: <notifications>
S: <notification-info
S: name="javax.management.monitor.MonitorNotification"
S: description="A MonitorNotification">
S: <notification-type>
S: jmx.monitor.counter.threshold
S: </notification-type>
S: <notification-type>
S: jmx.monitor.error.runtime
S: </notification-type>
Harold Expires November 6, 2003 [Page 21]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
S: <notification-type>
S: jmx.monitor.error.threshold
S: </notification-type>
S: </notification-info>
S: </notifications>
S: <attributes>
S: <attribute-info name="Modulus"
S: description="The monitor's modulus value"
S: type="Number"
S: readable="true"
S: writeable="true"
S: is="false"/>
S: <attribute-info name="Threshold"
S: description="The monitor's threshold value"
S: type="Number"
S: readable="true"
S: writeable="true"
S: is="false"/>
S: ... remaining CounterMonitor attributes ...
S: </attributes>
S: <constructors>
S: <constructor-info name="CounterMonitor"
S: description="Default constructor"/>
S: </constructors>
S: <operations/>
S: </mbean-info-data>
S: </value>
S:</response>
Here's an illustration of an unsuccessful MBeanInfo request:
C:MSG 1 17 . 152 77
C:Content-Type: application/beep+xml
C:
C:<mbean-info mbean="monitors:id=bogus"/>
C:END
... JMXP Server calls getMBeanInfo() ...
S:RPY 1 11 . 281 265
S:Content-Type: application/beep+xml
S:
S:<response code="451">
S: <exception class="javax.management.InstanceNotFoundException">
S: <message lang="en">
S: The MBean specified was not found
S: </message>
S: </exception>
Harold Expires November 6, 2003 [Page 22]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
S:</response>
4.2.4.3 The MBEAN-INVOCATION Element
When a client wants to invoke an operation on a specific MBean it
sends an "mbean-invocation" element over an MBEAN channel, e.g.,
C:MSG 1 1 . 52 120
C:Content-Type: application/beep+xml
C:
C:<mbean-invocation mbean="timers:id=alarms" operation="getPeriod">
C: <arguments>
C: <value><Integer>42</Integer></value>
C: </arguments>
C:</mbean-invocation>
C:END
The "mbean-invocation" element has two attributes:
1. the "mbean" attribute is the string representation of the JMX
ObjectName associated with the target MBean
2. the "operation" attribute indicates which of the target MBean's
operations is to be invoked.
The "mbean-invocation" element also requires an arguments (Section
5.1) element. The "arguments" element contains a value (Section 5.3)
element for each of the MBean operation's parameters.
When the JMXP Server receives an "mbean-invocation" element on an
MBean channel it attempts to invoke the specified operation with the
arguments provided. The server communicates the result of its
invocation attempt to the client by returning a response (Section
5.2) element.
A successful operation invocation might look like:
C:MSG 1 1 . 52 120
C:Content-Type: application/beep+xml
C:
C:<mbean-invocation mbean="timers:id=alarms" operation="addNotification">
C: <arguments>
C: <value><String>timers.alarm</String></value>
C: <value><String>Wake Up!</String></value>
C: <value><String>It's time for school</String></value>
C: <value><Date>1038722400000</Date></value>
Harold Expires November 6, 2003 [Page 23]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
C: </arguments>
C:</mbean-invocation>
C:END
... JMXP Server invokes addNotification() with the given arguments ...
S:RPY 1 1 . 221 87
S:Content-Type: application/beep+xml
S:
S:<response code="200">
S: <value><Integer>13</Integer></value>
S:</response>
S:END
The following exchange illustrates an unsuccessful invocation:
C:MSG 1 1 . 52 120
C:Content-Type: application/beep+xml
C:
C:<mbean-invocation mbean="timers:id=alarms" operation="addNotification">
C: <arguments>
C: <value><String>timers.alarm</String></value>
C: <value><String>Wake Up!</String></value>
C: <value><String>It's time for school</String></value>
C: <value><Date>1021352400000</Date></value>
C: </arguments>
C:</mbean-invocation>
C:END
... JMXP Server invokes addNotification() with the given arguments ...
S:RPY 1 1 . 221 87
S:Content-Type: application/beep+xml
S:
S:<response code="202">
S: <exception class="java.lang.IllegalArgumentException>
S: <message>
S: The notification date is before the current date
S: </message>
S: </exception>
S:</response>
S:END
4.3 NOTIFICATION Profile
Harold Expires November 6, 2003 [Page 24]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
4.3.1 NOTIFICATION Profile Overview
The NOTIFICATION profile is used to deliver JMX Notifications that
are emitted by an MBeanServer's MBeans to interested clients. Clients
express interest in a particular MBean's Notifications by adding
listeners via the MBEANSERVER channel's notification-listener
(Section 4.1.4.1) element.
When a client adds a listener the JMXP Server starts a NOTIFICATION
channel to the client, unless one already exists. After the
NOTIFICATION channel is started the client sends a message over it
indicating that it is ready to receive "notification" elements. The
"ready message" can be piggybacked on the client's response to the
server's NOTIFICATION channel "start" message as illustrated in
Section 4.1.4.1. Alternatively, the client may send a "ready message"
after the NOTIFICATION channel is started, e.g.
S:MSG 0 91 . 281 96
S:Content-Type: application/beep+xml
S:
S:<start number="2">
S: <profile uri="http://iana.org/beep/transient/jmxp/NOTIFICATION"/>
S:</start>
S:END
C:RPY 0 1 . 0 64
C:Content-Type: application/beep+xml
C:
C:<profile uri="http://iana.org/beep/transient/jmxp/NOTIFICATION"/>
C:END
C:MSG 2 1 . 0 49
C:Content-Type: application/beep+xml
C:
C:ready
C:END
In either case after the client sends its ready message the server
will begin delivering JMX Notifications via ANS messages containing
"notification" elements as described below.
4.3.2 NOTIFICATION Profile Identification and Initialization
The NOTFICATION profile is identified as
http://iana.org/beep/transient/jmxp/NOTIFICATION
No data is piggybacked during channel creation
4.3.3 NOTIFICATION Profile Message Syntax
All BEEP messages in this profile have a MIME CONTENT-TYPE [2] of
Harold Expires November 6, 2003 [Page 25]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
application/beep+xml. The syntax of the individual elements is
specified in Section 10.
4.3.4 NOTIFICATION Profile Message Semantics
4.3.4.1 The NOTIFICATION Element
When a JMXP Server needs to deliver a JMX Notification to a listening
client it sends a "notification" element over a NOTIFICATION channel,
e.g.,
S:ANS 2 23 . 652 98
S:Content-Type: application/beep+xml
S:
S:<notification type="timers.alarm">
S: <value>
S: <composite-data>
S: <structured-type name="TimerNotification">
S: <item name="message" description="human readable text">
S: <scalar-type>String</scalar-type>
S: </item>
S: <item name="sequenceNumber">
S: <scalar-type>Long</scalar-type>
S: </item>
S: <item name="timeStamp">
S: <scalar-type>Long</scalar-type>
S: </item>
S: <item name="type">
S: <scalar-type>String</scalar-type>
S: </item>
S: <item name="userData">
S: <scalar-type>String</scalar-type>
S: </item>
S: <item name="notificationID">
S: <scalar-type>Integer</scalar-type>
S: </item>
S: </structured-type>
S: <member key="value">
S: <String>Wake Up!</String>
S: <Long>42</Long>
S: <Long>1043474400000</Long>
S: <String>timers.alarm</String>
S: <Integer>11</Integer>
S: </member>
S: </composite-data>
S: </value>
S:</notification>
S:END
Harold Expires November 6, 2003 [Page 26]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
Note that a "notification" element is tranmitted in an ANS message.
This is because, unlike the client/server model supported by the
MBEANSERVER and MBEAN profiles, the NOTIFICATION profile uses a
server/client model which leverages BEEP [9]'s support for a
"one-to-many" exchange style, see section 2.1.1 of [9]
A "notification" element has a single attribute, "type", which
identifies the type associated with the JMX Notification carried by
the element.
The "notification" element also requires a value (Section 5.3). The
"value" element contains the serialized form of the JMX Notification
being delievered. The serialized form is encoded in a
"composite-data" element.
A client's reaction to a "notification" element is implementation
specific. For example, a JMX MBeanServerConnector might unmarshall
the "notification" element's value into an instance of the specified
JMX Notification class and forward it to local listeners.
Alternatively, a non-Java client might transform the "notification"
element's value into an event suitable for an enterprise system
management event mechanism. In any case, no client response is sent
to the JMXP Server.
Clients that are no longer interested in JMX Notifications must
either:
1. send as many "notification-listener" elements as necessary to
remove the listeners added by the client
2. close the NOTIFICATION channel
The latter approach should only be used in emergency situations where
the application cannot wait for an orderly removal of its listeners.
Harold Expires November 6, 2003 [Page 27]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
5. Common Profile Elements
5.1 The ARGUMENTS Element
An "arguments" element is a container for a set of values that are to
be passed to an MBeanServer method or an MBean operation. Each of the
"arguments" element values is encoded as a value (Section 5.3)
element.
For example, here are some arguments for an invocation of the
GaugeMonitor's setThresholds() operation:
<arguments>
<value>
<array>
<value><Integer>42</Integer></value>
<value><Integer>69</Integer></value>
</array>
</value>
<value>
<array>
<value><String>java.lang.Integer</String></value>
<value><String>java.lang.Integer</String></value>
</array>
</value>
</arguments>
The JMXP Schema (Section 10) provides a formal definition of the
"arguments" element.
5.2 The RESPONSE Element
A "response" element is used to encode the information a JMXP Server
returns in response to a client request, e.g.,
<response code="200">
<value><Integer>42</Integer></value>
</response>
or, in the case of an exception:
<response code="451">
<exception class="javax.management.MalformedObjectNameException">
<message lang="en">
Unable to parse key property list
</message>
</exception>
</response>
Harold Expires November 6, 2003 [Page 28]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
The "response" element has a single attribute, "code", and may
contain either a:
1. value (Section 5.3) element that encodes the return value, or an
2. exception (Section 5.2.1) element
The "code" attribute indicates the outcome of the request. Reply
Codes (Section 9) describes the JMXP reply code scheme in detail.
An empty "response" element is returned for "server-invocation" or
"mbean-invocation" requests whose target method has a return type of
'void'. In this case the "code" attribute indicates the success or
failure of the request.
Section 5.3 (Section 5.3) describes the "value" element in detail
The JMXP Schema (Section 10) provides a formal definition of the
"response" element.
5.2.1 The EXCEPTION Element
An "exception" element represents an exception thrown in the course
of executing a request.
An "exception" element has a single attribute, class, which
identifies the Java class of the exception that was thrown and may
contain a message element.
<< Should the "exception" element also include a "cause" element to
support the notion of "chained exceptions" introduced in J2SE 1.4? If
so, should the "cause" element allow nested exceptions? To what
depth? >>
A "message" element represents the message text associated with an
exception.
A "message" element has a single attribute, lang, which identifies
the language the element's content is written in.
5.3 The VALUE Element
A "value" element is used to encode the values exchanged between JMXP
peers. A "value" element must contain either a scalar element, a
structured element, or an array.
The JMXP Schema (Section 10) provides a formal definition of the
syntax of the "value" element and its subelements.
Harold Expires November 6, 2003 [Page 29]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
5.3.1 Scalar Values
A scalar value is represented by one of these elements:
o <Void> always empty, i.e., <Void/>, represents the return value of
a 'void' method
o <Boolean> may be either 'true' or 'false'
o <Byte> a value from -128 to 127 inclusive
o <Character> a value from '\u0000' to '\uffff' inclusive
o <String> a sequence of Unicode characters
o <Short> a value from -32768 to 32767 inclusive
o <Integer> a value from -2147483648 to 2147483647 inclusive
o <Long> a value from -9223372036854775808 to 9223372036854775807
inclusive
o <Float> a single-precision 32-bit format IEEE 754 floating point
value
o <Double> a double-precision 64-bit format IEEE 754 floating point
value
o <Date> a 'long' value representing the number of milliseconds
since January 1, 1970, 00:00:00 GMT
o <ObjectName> the string representation of an instance of a JMX
object name
Each of these elements constrains a string of characters that
represents the scalar value. The element tag indicates how those
characters are to be interpreted.
For example, the "value" element for the java.lang.String "xyzzy" is:
<value><String>xyzzy</String></value>
5.3.2 Structured Values
A structured value encodes an aggregate structure built up from
scalars and/or other structured values. JMXP defines two generic
structured value encoding schemes, an encoding scheme for arrays, and
Harold Expires November 6, 2003 [Page 30]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
three encoding schemes for specific structured values.
The generic encoding schemes are modeled after the Open MBean complex
data representations: CompositeData and TabularData, defined in
Chapter 3 of [14]
Specific encoding schemes are defined for JMX Attributes, MBeanInfo,
and ObjectInstances.
5.3.2.1 Array Values
An "array" element represents an array of values. It contains one or
more value (Section 5.3) elements. For example, an array of Integers
would look like:
<value>
<array>
<value><Integer>2</Integer></value>
<value><Integer>4</Integer></value>
<value><Integer>8</Integer></value>
<value><Integer>16</Integer></value>
<value><Integer>32</Integer></value>
<value><Integer>64</Integer></value>
</array>
</value>
Note that since an "array" element is a value it is possible to
create arrays-of-arrays.
5.3.2.2 Attribute Values
An "Attribute" element represents a JMX attribute, e.g.,
<value>
<Attribute name="CpuLoad">
<Float>0.32112</Float>
</Attribute>
</value>
represents an attribute named "CpuLoad" whose current value is
0.32112.
An "Attribute" element has a single attribute, "name", which
identifies an MBean attribute. The "Attribute" element may contain a
scalar, structured, or array element, that indicates either the
attribute's current value, when the attribute is part of the response
to a "get" request, or its intended value, when the attribute is part
of a "set" request.
Harold Expires November 6, 2003 [Page 31]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
5.3.2.3 Composite Data Values
A "composite-data" element represents a hash table with an arbitrary
number of elements. Each element must be of the same type; element
types may be scalar or structured. For example, here is a
"composite-data" representation of a set of ObjectNames:
<value>
<composite-data>
<scalar-type>ObjectName</scalar-type>
<member key="MBeanServerDelegate">
<ObjectName>JMImplementation:type=MBeanServerDelegate</ObjectName>
</member>
<member key="JmxpConnector">
<ObjectName>connectors:id=jmxp,port=3006</ObjectName>
</member>
<member key="MasterTimer">
<ObjectName>timers:id=master</ObjectName>
</member>
</composite-data>
</value>
A "composite-data" representation of a NetworkCard object might look
like:
<value>
<composite-data>
<structured-type name="NetworkCard">
<item name="Maker">
<scalar-type>String</scalar-type>
</item>
<item name="Model">
<scalar-type>String</scalar-type>
<item name="slot">
<scalar-type>Integer</scalar-type>
</item>
<item name="IPAddress">
<scalar-type>String</scalar-type>
</item>
</structured-type>
<member key="value">
<String>LinkSys</String>
<String>LNE 100M</String>
<Integer>3</Integer>
<String>127.0.0.2</String>
</member>
</composite-data>
</value>
Harold Expires November 6, 2003 [Page 32]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
A "composite-data" element has no attributes. The "composite-data"
element must contain a single type element, either scalar or
structured, followed by one or more "member" elements.
A type element is one of:
1. <scalar-type>
2. <structured-type>
A "scalar-type" element contains the name of one of the JMXP scalar
value elements.
A "structured-type" element has two optional attributes:
1. the "name" attribute identifies the structured type
2. the "description" attribute is a human readable description of
the structured type
The "structured-type" element must contain one or more "item"
elements.
An "item" attribute has two optional attributes:
1. the "name" attribute identifies the item
2. the "description" attribute is a human readable description of
the item
The "item" element must contain a single type element. The type
element may be scalar or structured. Allowing the "item" element to
contain another "structured-type" element makes it possible to
specify structured values of arbitrary complexity. Note, however,
that JMXP is not designed to be a generic distributed object protocol
and no support is provided for representing recursive or
self-referential structures.
A "member" element has a single attribute, "key", which uniquely
identifies the member within the "composite-data" element. If the
"composite-data" element specified a "scalar-type" type the "member"
element must contain a single scalar value element; that scalar value
element's name must match the one specified by the type element. When
the "composite-data" element specifies a "structured-type" the
"member" element must contain an appropriate element for each of the
"item" elements in the "structured-type" element.
Harold Expires November 6, 2003 [Page 33]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
5.3.2.4 Tabular Data Values
A "tabular-data" element represents a table structure with an
arbitrary number of rows. Each row is composed of a set of columns. A
"structured-type" element defines the columns of each of the table
structure's rows. Here is a "tabular-data" structure whose rows
consist of a GaugeMonitor object name and its associated threshold
values:
<value>
<tabular-data>
<structured-type name="GaugeTable"
description="GaugeMonitor object names and thresholds>
<item name="monitor"
<scalar-type>ObjectName</scalar-type>
</item>
<item name="lowThreshold">
<scalar-type>Float</scalar-type>
</item>
<item name="highThreshold">
<scalar-type>Float</scalar-type>
</item>
</structured-type>
<row>
<ObjectName>monitors:id=HitRate,type=gauge</ObjectName>
<Float>12.8</Float>
<Float>204.8</Float>
</row>
<row>
<ObjectName>monitors:id=TransferRate,type=gauge</ObjectName>
<Float>25.6</Float>
<Float>409.6</Float>
</row>
</tabular-data>
</value>
A "tabular-data" element has no attributes. The "tabular-data"
element must contain a single structured-type element, followed by
one or more "row" elements.
5.3.2.5 MBeanInfo Values
An "mbean-info-data" element represents an instance of
javax.management.MBeanInfo, e.g.,
<value>
<mbean-info-data name="net.jmx.Simple"
description="A simple demo MBean">
Harold Expires November 6, 2003 [Page 34]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
<notifications>
<notification-info name="javax.management.Notification"
description="Simple notification">
<notification-type>simple.error</notification-type>
<notification-type>simple.alert</notification-type>
</notification-info>
</notifications>
<attributes>
<attribute-info name="Creator"
description="Name of the instance's creator"
type="java.lang.String"
readable="true"
writeable="false"
is="false"/>
<attribute-info name="Owner"
description="Name of the instance's owner"
type="java.lang.String"
readable="true"
writeable="false"
is="false"/>
<attribute-info name="Age"
description="Age of the MBean in milliseconds"
type="long"
readable="true"
writeable="false"
is="false"/>
</attributes>
<constructors>
<constructor-info name="Simple"
descriptor="Simple MBean constructor">
<parameter-info name="creatorName"
description="Name of the MBean's creator"
type="java.lang.String"/>
</constructor-info>
</constructors>
<operations>
<operation-info name="sell"
description="Simple MBean sell() operation"
returnType="boolean"
impact="1">
<parameter-info name="newOwener"
description="Name of the new MBean owner"
type="java.lang.String"/>
<parameter-info name="price"
description="The MBean's sale price"
type="float"/>
</operation-info>
</operations>
Harold Expires November 6, 2003 [Page 35]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
</mbean-info-data>
</value>
represents the MBeanInfo metadata associated with a SimpleMBean.
The "mbean-info-data" element has two attributes:
1. the "name" attribute identifies the Java class of the MBean
described by the mbean-info-data
2. the "description" attribute is a human readable description of
the MBean
The "mbean-info-data" element also requires "notifications",
"attributes", "constructors", and "operations" elements. These
elements correspond to the javax.management.MBeanNotificationInfo,
javax.management.MBeanAttributeInfo,
javax.management.MBeanConstructorInfo, and
javax.management.MBeanOperationInfo arrays that comprise a
javax.management.MBeanInfo instance.
A "notifications" element contains zero or more "notification-info"
elements. Each "notification-info" element has two attributes:
1. the "name" attribute identifies the Java class of the
Notification represented by the notifiction-info
2. the "description" attribute is a human readable description of
the Notification
The "notification-info" element also requires one or more
"notification-type" elements. Each "notification-type" element
identifies a JMX Notification type string.
An "attributes" element contains zero or more "attribute-info"
elements. Each "attribute-info" element has six attributes:
1. the "name" attribute identifies the MBean attributes' name
2. the "description" attribute is a human readable description of
the MBean attribute
3. the "type" attribute identifies the Java class of the MBean
attribute's values
4. the "readable" attribute indicates whether or not the MBean
attribute's values are readable
Harold Expires November 6, 2003 [Page 36]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
5. the "writeable" attribute indicates whether or not the MBean
attribute's values are writeable
6. the "is" attribute indicates whehter or not the MBean provides an
'is' getter, e.g., isRunning() for a boolean-valued attribute
named 'Running'
A "constructors" element contains zero or more "constructor-info"
elements. Each "constructor-info" element has two attributes:
1. the "name" attribute is the fully qualified name of the MBean's
constructor
2. the "description" attribute is a human readable description of
the MBean constructor
The "constructor-info" element may also have one or more
"parameter-info" elements which describe the MBean constructor's
parameters.
An "operations" element contains zero or more "operation-info"
elements. Each "operation-info" element has four attributes:
1. the "name" attribute is the name of the MBean operation
2. the "description" attribute is a human readable description of
the MBean operation
3. the "returnType" attribute identifies the Java class of the value
returned by the MBean operation
4. the "impact" attribute indicates the MBean operation's impact,
i.e., it's effect on the MBean
The "operation-info" element may also have one or more
"parameter-info" elements which describe the MBean operation's
parameters.
Finally, the "parameter-info" element has three attributes:
1. the "name" attribute is the parameter's name
2. the "description" attribute is a human readable description of
the parameter
3. the "type" attribute identifies the Java class of the parameter's
values
Harold Expires November 6, 2003 [Page 37]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
5.3.2.6 ObjectInstance Values
An "ObjectInstance" element represents a JMX ObjectInstance, e.g.,
<value>
<ObjectInstance classname="javax.management.monitor.CounterMonitor">
<ObjectName>monitors:id=hits</ObjectName>
</ObjectInstance>
represents a CounterMonitor instance whose object name is
"monitors:id=hits"
An "ObjectInstance" element has a single attribute, "classname",
which identifies the Java class of the instance. The "ObjectInstance"
element must contain an "ObjectName" element. The "ObjectName"
element specifies the JMX ObjectName associated with this particular
MBean instance.
Harold Expires November 6, 2003 [Page 38]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
6. URL Schemes
This memo defines two URL schemes, "jmxp" and "jmxps", which identify
the use of JMXP over TCP. Note that, at present, a "generic" URL
scheme for JMXP is not defined.
6.1 The jmxp URL Scheme
The "jmxp" URL scheme uses the "generic URI" syntax defined in
Section 3 of [4], specifically:
o the value "jmxp" is used for the scheme component; and,
o the server-based naming authority defined in Section 3.2.2 of [4]
is used for the authority component.
o the path component determines which profile, MBEANSERVER, or MBEAN
is started when a session is successfully established. If absent,
it defaults to MBEANSERVER.
The values of both the scheme and authority components are
case-insensitive.
For example, the URL
jmxp://agent.jmx.net/mbeanserver
would result in the establishment of a session with the JMXP server
at agent.jmx.net; once the session was established an MBEANSERVER
channel would be started.
6.1.1 Resolving IP/TCP Address Information
The "jmxp" URL scheme indicates the use of one of the the JMXP
specified BEEP profiles running over TCP/IP.
If the authority component contains a domain name and a port number,
e.g.,
jmxp://agent.jmx.net:1026
then the DNS is queried for the A RRs corresponding to the domain
name, and the port number is used directly.
If the authority component contains a domain name and no port number,
e.g.,
jmxp://agent.jmx.net
Harold Expires November 6, 2003 [Page 39]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
the SRV algorithm [8] is used with a service parameter of "jmxp" and
a protocol parameter of "tcp" to determine the IP/TCP addressing
information. If no appropriate SRV RRs are found (e.g., for
"_jmxp._tcp.agent.jmx.net"), then the DNS is queried for the A RRs
corresponding to the domain name and the port number used is assigned
by the IANA for the registration in Section 7.6.
If the authority component contains an IP address, e.g.,
jmxp://10.0.0.2:1026
then the DNS is not queried, and the IP address is used directly. If
a port number is present, it is used directly; otherwise, the port
number used is assigned by the IANA for the registration in Section
7.6.
While the use of literal IPv6 addresses in URLs is discouraged, if a
literal IPv6 address is used in a "jmxp" URL, it must conform to the
syntax specified in [7].
6.2 The jmxps URL Scheme
The "jmxps" URL scheme is identical, in all ways, to the "jmxp" URL
scheme specified in Section 6.1, with the exception that prior to
starting the any BEEP profile for JMXP, the BEEP session must be
tuned for privacy. In particular, note that both URL schemes use the
identical algorithms and parameters for address resolution as
specified in Section 6.1.1 (e.g., the same service name for SRV
lookups, the same port number for TCP, and so on).
There are two ways to perform privacy tuning on a BEEP session,
either:
o a transport security profile may be successfully started; or,
o a user authentication profile that supports transport security may
be successfully started.
In either case the client must present the authority component of the
URL in the "serverName" attribute of the "start" element it uses to
tune the session for privacy.
When TLS is used for privacy the client must verify that the
authority component of the URL matches the server's identity as
presented in the server's certificate. Section 2.4 of [5] describes
the matching process.
For the URL:
Harold Expires November 6, 2003 [Page 40]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
jmxps://agent.jmx.net
the whole process might look like:
S: <wait for incoming connection @ agent.jmx.net>
C: <open connection to agent.jmx.net>
C: RPY 0 0 . 0 52
C: Content-Type: application/xml
C:
C: <greeting>
C: <profile uri='http://iana.org/transient/jmxp/NOTIFICATION' />
C: </greeting>
C: END
S: RPY 0 0 . 0 110
S: Content-Type: application/xml
S:
S: <greeting>
S: <profile uri='http://iana.org/beep/TLS' />
S: <profile uri='http://iana.org/beep/SASL/DIGEST-MD5' />
S: </greeting>
S: END
C: MSG 0 1 . 52 158
C: Content-Type: application/xml
C:
C: <start number='1' serverName='agent.jmx.net'>
C: <profile uri='http://iana.org/beep/TLS'>
C: <![CDATA[<ready />]]>
C: </profile>
C: </start>
C: END
S: RPY 0 1 . 110 121
S: Content-Type: application/xml
S:
S: <profile uri='http://iana.org/beep/TLS'>
S: <![CDATA[<proceed />]]>
S: </profile>
S: END
... TLS negotiations ...
S: RPY 0 0 . 0 88
S: Content-Type: application/xml
S:
S: <greeting>
S: <profile uri='http://iana.org/beep/transient/jmxp/MBEANSERVER'/>
S: <profile uri='http://iana.org/beep/transient/jmxp/MBEAN'/>
S: </greeting>
Harold Expires November 6, 2003 [Page 41]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
S: END
C: RPY 0 0 . 0 52
C: Content-Type: application/xml
C:
C: <greeting>
C: <profile uri='http://iana.org/transient/jmxp/NOTIFICATION' />
C: </greeting>
C: END
... use the server's certificate to verify that it is
in fact agent.jmx.net ...
C: MSG 0 1 . 112 211
C: Content-Type: application/xml
C:
C: <start number='3' serverName='agent.jmx.net'>
C: <profile uri='http://iana.org/beep/transient/jmxp/MBEANSERVER'/>
C: </start>
C: END
S: RPY 0 2 . 341 402
S: Content-Type: application/xml
S:
S: <profile uri='http://iana.org/beep/transient/MBEANSERVER'/>
S: END
Harold Expires November 6, 2003 [Page 42]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
7. Initial Registrations
7.1 Registration: The MBEANSERVER Profile
Profile Identification http://iana.org/beep/transient/jmxp/
MBEANSERVER
Messages exchanged during Channel Creation none
Messages starting one-to-one exchanges server-invocation,
notification-listener
Messages in positive replies ok, response
Messages in negative replies error
Messages in one-to-many exchanges none
Message Syntax See Section 4.1.3
Message Semantics See Section 4.1.4
Contact Information Ward Harold <wharold@us.ibm.com>
7.2 Registration: The MBEAN Profile
Profile Identification http://iana.org/beep/transient/jmxp/MBEAN
Messages exchanged during Channel Creation none
Messages starting one-to-one exchanges mbean-attributes, mbean-info,
mbean-invocation
Messages in positive replies ok, response
Messages in negative replies error
Messages in one-to-many exchanges none
Message Syntax See Section 4.2.3
Message Semantics See Section 4.2.4
Contact Information Ward Harold <wharold@us.ibm.com>
Harold Expires November 6, 2003 [Page 43]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
7.3 Registration: The NOTIFICATION Profile
Profile Identification http://iana.org/beep/transient/jmxp/
NOTIFICATION
Messages exchanged during Channel Creation anything
Messages starting one-to-one exchanges anything
Messages in positive replies ok
Messages in negative replies error
Messages in one-to-many exchanges notification
Message Syntax See Section 4.3.3
Message Semantics See Section 4.3.4
Contact Information Ward Harold <wharold@us.ibm.com>
7.4 Registration: The jmxp URL Scheme
URL scheme name: jmxp
URL scheme syntax: c.f., Section 6.1
Character encoding considerations: c.f., the "generic URI" syntax
defined in Section 3 of [4]
Intended usage: identifies a JMX Agent made available using the
Java(tm) Management Extensions Protocol
Applications using this scheme: c.f., "Intended usage", above
Interoperability considerations: n/a
Security Considerations: c.f., Section 8
Relevant Publications: c.f., [9]
Contact Information: Ward Harold <wharold@us.ibm.com>
Author/Change controller: the IESG
Harold Expires November 6, 2003 [Page 44]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
7.5 Registration: The jmxps URL Scheme
URL scheme name: jmxps
URL scheme syntax: c.f., Section 6.2
Character encoding considerations: c.f., the "generic URI" syntax
defined in Section 3 of [4]
Intended usage: identifies a JMX Agent made available using the
Java(tm) Management Extensions Protocol after the BEEP session has
been tuned for privacy
Applications using this scheme: c.f., "Intended usage", above
Interoperability considerations: n/a
Security Considerations: c.f., Section 8
Relevant Publications: c.f., [9]
Contact Information: Ward Harold <wharold@us.ibm.com>
Author/Change controller: the IESG
7.6 Registration: The System (Well-Known) TCP port number for JMXP
Protocol Number: TCP
Message Formats, Types, Opcodes, and Sequences: c.f.,JMXP Overview
(Section 3)
Functions: c.f.,JMX Specification v1.1 [15]
Use of Broadcast/Multicast: none
Proposed Name: Java(tm) Management Extensions Protocol
Short name: jmxp
Contact Information: Ward Harold <wharold@us.ibm.com>
Harold Expires November 6, 2003 [Page 45]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
8. Security Considerations
Although service provisioning is a policy matter, at a minimum, all
implementations must provide the followin tuning profiles:
for authentication http://iana.org/beep/SASL/DIGEST-MD5
for confidentiality http://iana.org/beep/TLS (using the
TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher)
for both http://iana.org/beep/TLS (using the
TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side
certificates)
Further, implementations may choose to offer MIME-based security
services providing message integrity and confidentiality, such as
Open PGP [11] or S/MIME [6].
Regardless, consult [9]'s Section 9 for a discussion of BEEP-specific
security issues.
<< This section was copied directly from IETF RFC 3288 [12] the Open
PGP and S/MIME comment may or may not apply. >>
Harold Expires November 6, 2003 [Page 46]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
9. Reply Codes
JMXP reply codes are derived from the "Theory of Reply Codes"
described in RFC 821 [1]. They also borrow heavily from the set of
reply codes define in Section 8 of [9].
code meaning
==== =======
200 success
450 requested action not taken
451 requested action aborted
500 general syntax error
(e.g., poorly-formed XML)
530 authentication required
535 authentication failure
537 action not authorized for user
Harold Expires November 6, 2003 [Page 47]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
10. The JMXP Schema
10.1 MBEANSERVER Element Schema
The MBEANSERVER profile elements are defined by the following XML
Schema fragment:
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="http://ietf.org/jmxp/1.0/base"
xmlns:jmxp="http://ietf.org/jmxp/1.0/base"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="unqualified">
<!--
MBEANSERVER profile element definitions
-->
<xsd:element name="notification-listener">
<xsd:annotation>
<xsd:documentation>
Used to express interest, or lack thereof, in JMX
Notifications emitted by MBeans registered with an
MBeanServer
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:arguments"/>
</xsd:sequence>
<xsd:attribute name="action" type="jmxp:listenerAction"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="server-invocation">
<xsd:annotation>
<xsd:documentation>
Used to invoke methods on the MBeanServer itself.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:arguments"/>
</xsd:sequence>
<xsd:attribute name="method" type="jmxp:serverMethod"/>
</xsd:complexType>
</xsd:element>
Harold Expires November 6, 2003 [Page 48]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
10.2 MBEAN Element Schema
The MBEAN profile elements are defined by the following XML Schema
fragment:
<!--
MBEAN profile element definitions
-->
<xsd:element name="mbean-attributes">
<xsd:annotation>
<xsd:documentation>
Used to retrieve or update the value of one or more attributes
associated with an MBean
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:arguments"/>
</xsd:sequence>
<xsd:attribute name="mbean" type="xsd:string"/>
<xsd:attribute name="action" type="jmxp:attributeAction"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="mbean-info">
<xsd:annotation>
<xsd:documentation>
Used to retreive the MBeanInfo metadata for an MBean
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:attribute name="mbean" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="mbean-invocation">
<xsd:annotation>
<xsd:documentation>
Used to invoke an operation on an MBean
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:arguments"/>
</xsd:sequence>
<xsd:attribute name="mbean" type="xsd:string"/>
<xsd:attribute name="operation" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
Harold Expires November 6, 2003 [Page 49]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
10.3 NOTIFICATION Element Schema
The NOTIFICATION profile elements are defined by the following XML
Schema fragment:
<!--
NOTIFICATION profile element definitions
-->
<xsd:element name="notification">
<xsd:annotation>
<xsd:documentation>
Used to deliver a JMX Notification emitted by an MBean to a JMXP
client listening for such notifications
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:value"/>
</xsd:sequence>
<xsd:attribute name="type" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
10.4 Common Element Schema
The "arguments" element is defined by the XML Schema fragment:
<xsd:element name="arguments">
<xsd:annotation>
<xsd:documentation>
Container element for values passed as arguments to an MBeanServer
method, an MBean operation, or a notification-listener request.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:value" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
The "response" and "exception" elements are defined by the XML Schema
fragment:
<xsd:element name="response">
<xsd:annotation>
<xsd:documentation>
Harold Expires November 6, 2003 [Page 50]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
Container element for values returned by a JMXP request
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:exception"/>
</xsd:sequence>
<xsd:attribute name="code" type="xsd:int"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="exception">
<xsd:annotation>
<xsd:documentation>
JMXP representation of a Java exception
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="message">
<xsd:annotation>
<xsd:documentation>
The text of the message associated with a Java exception
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="lang" type="xsd:string"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="class" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
The base "value" element definition is:
<xsd:element name="value">
<xsd:annotation>
<xsd:documentation>
Represents values of various types that are exchanged by JMXP peers
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:choice>
<xsd:element ref="jmxp:Void"/>
Harold Expires November 6, 2003 [Page 51]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
<xsd:element ref="jmxp:Boolean"/>
<xsd:element ref="jmxp:Byte"/>
<xsd:element ref="jmxp:Character"/>
<xsd:element ref="jmxp:String"/>
<xsd:element ref="jmxp:Integer"/>
<xsd:element ref="jmxp:Long"/>
<xsd:element ref="jmxp:Float"/>
<xsd:element ref="jmxp:Double"/>
<xsd:element ref="jmxp:Date"/>
<xsd:element ref="jmxp:ObjectName"/>
<xsd:element ref="jmxp:array"/>
<xsd:element ref="jmxp:Attribute"/>
<xsd:element ref="jmxp:composite-data"/>
<xsd:element ref="jmxp:tabular-data"/>
<xsd:element ref="jmxp:mbean-info-data"/>
<xsd:element ref="jmxp:ObjectInstance"/>
</xsd:choice>
</xsd:complexType>
</xsd:element>
The scalar "value" elements are defined by the XML Schema fragment:
<!--
Scalar "value" element definitions
-->
<xsd:element name="Void" type="xsd:string"/>
<xsd:element name="Boolean" type="xsd:boolean"/>
<xsd:element name="Byte" type="xsd:byte"/>
<xsd:element name="Character" type="xsd:string"/>
<xsd:element name="String" type="xsd:string"/>
<xsd:element name="Integer" type="xsd:int"/>
<xsd:element name="Long" type="xsd:long"/>
<xsd:element name="Float" type="xsd:float"/>
<xsd:element name="Double" type="xsd:double"/>
<xsd:element name="Date" type="xsd:dateTime"/>
<xsd:element name="ObjectName" type="xsd:string"/>
The structured "value" elements are defined by the XML Schema
fragment:
<!--
Composite "value" element definitions
-->
<xsd:element name="array">
<xsd:annotation>
<xsd:documentation>
Represents an array of values
</xsd:documentation>
Harold Expires November 6, 2003 [Page 52]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:value" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="Attribute">
<xsd:annotation>
<xsd:documentation>
Represents a JMX Attribute instance
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:choice>
<xsd:element ref="jmxp:Boolean"/>
<xsd:element ref="jmxp:Byte"/>
<xsd:element ref="jmxp:Character"/>
<xsd:element ref="jmxp:String"/>
<xsd:element ref="jmxp:Integer"/>
<xsd:element ref="jmxp:Long"/>
<xsd:element ref="jmxp:Float"/>
<xsd:element ref="jmxp:Double"/>
<xsd:element ref="jmxp:Date"/>
<xsd:element ref="jmxp:ObjectName"/>
<xsd:element ref="jmxp:array"/>
<xsd:element ref="jmxp:composite-data"/>
<xsd:element ref="jmxp:tabular-data"/>
</xsd:choice>
<xsd:attribute name="name" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="scalar-type" type="jmxp:scalarType"/>
<xsd:element name="structured-type">
<xsd:annotation>
<xsd:documentation>
Defines a JMXP structured type
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="item">
<xsd:complexType>
<xsd:choice>
<xsd:element ref="jmxp:scalar-type"/>
<xsd:element ref="jmxp:structured-type"/>
</xsd:choice>
<xsd:attribute name="name" type="xsd:string"/>
Harold Expires November 6, 2003 [Page 53]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
<xsd:attribute name="description" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string"/>
<xsd:attribute name="descrption" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="composite-data">
<xsd:annotation>
<xsd:documentation>
Represents a composite data value transfered by JMXP
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:choice>
<xsd:element ref="jmxp:scalar-type"/>
<xsd:element ref="jmxp:structured-type"/>
</xsd:choice>
<xsd:element name="member" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:choice maxOccurs="1">
<xsd:element ref="jmxp:Boolean"/>
<xsd:element ref="jmxp:Byte"/>
<xsd:element ref="jmxp:Character"/>
<xsd:element ref="jmxp:String"/>
<xsd:element ref="jmxp:Integer"/>
<xsd:element ref="jmxp:Long"/>
<xsd:element ref="jmxp:Float"/>
<xsd:element ref="jmxp:Double"/>
<xsd:element ref="jmxp:Date"/>
<xsd:element ref="jmxp:ObjectName"/>
<xsd:element ref="jmxp:array"/>
<xsd:element ref="jmxp:composite-data"/>
<xsd:element ref="jmxp:tabular-data"/>
</xsd:choice>
</xsd:sequence>
<xsd:attribute name="key" type="xsd:int"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="tabular-data">
<xsd:annotation>
<xsd:documentation>
Harold Expires November 6, 2003 [Page 54]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
Represents a tabular data value transfered by JMXP
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:structured-type"/>
<xsd:element name="row" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:choice>
<xsd:element ref="jmxp:Boolean"/>
<xsd:element ref="jmxp:Byte"/>
<xsd:element ref="jmxp:Character"/>
<xsd:element ref="jmxp:String"/>
<xsd:element ref="jmxp:Integer"/>
<xsd:element ref="jmxp:Long"/>
<xsd:element ref="jmxp:Float"/>
<xsd:element ref="jmxp:Double"/>
<xsd:element ref="jmxp:Date"/>
<xsd:element ref="jmxp:ObjectName"/>
<xsd:element ref="jmxp:array"/>
<xsd:element ref="jmxp:composite-data"/>
<xsd:element ref="jmxp:tabular-data"/>
</xsd:choice>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
The structured "value" element "mbean-info-data" provides a more
compact representation of an MBean's MBeanInfo metadata. The top
level element is defined as:
<xsd:element name="mbean-info-data">
<xsd:annotation>
<xsd:documentation>
Represents the MBeanInfo metadata for an MBean
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:notifications" minOccurs="0"/>
<xsd:element ref="jmxp:attributes" minOccurs="0"/>
<xsd:element ref="jmxp:constructors" minOccurs="0"/>
<xsd:element ref="jmxp:operations" minOccurs="0"/>
</xsd:sequence>
Harold Expires November 6, 2003 [Page 55]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
<xsd:attribute name="class" type="xsd:string"/>
<xsd:attribute name="description" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
The elements representing the arrays of notificaiton, attribute,
constructor, and operation metadata info are defined by the following
XML Schema fragment:
<!-- mbean-info-data arrays -->
<xsd:element name="notifications">
<xsd:annotation>
<xsd:documentation>
Represents an array of MBeanNotificationInfo instances in
the mbean-info-data
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:notification-info"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="attributes">
<xsd:annotation>
<xsd:documentation>
Represents the array of MBeanAttributeInfo instances in
the mbean-info-data
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:attribute-info"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="constructors">
<xsd:annotation>
<xsd:documentation>
Represents the array of MBeanConstructorInfo instances in
the mbean-info-data
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:constructor-info"/>
</xsd:sequence>
</xsd:complexType>
Harold Expires November 6, 2003 [Page 56]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
</xsd:element>
<xsd:element name="operations">
<xsd:annotation>
<xsd:documentation>
Represents the array of MBeanOperationInfo instances in
the mbean-info-data
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="jmxp:operation-info"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
Elements representing the notification, attribute, constructor,
operation, and parameter metadata instances in the corresponding
arrays are defined by the following XML Schema fragment:
<!-- mbean-info-data *-info elements -->
<xsd:complexType name="feature-info">
<xsd:annotation>
<xsd:documentation>
The base type for all of the mbean-info-data's *-info elements
</xsd:documentation>
</xsd:annotation>
<xsd:attribute name="name" type="xsd:string"/>
<xsd:attribute name="description" type="xsd:string"/>
</xsd:complexType>
<xsd:element name="notification-info">
<xsd:annotation>
<xsd:documentation>
Represents an individual MBeanNotificationInfo instance
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="jmxp:feature-info">
<xsd:sequence>
<xsd:element name="notification-type"
type="xsd:string"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="attribute-info">
Harold Expires November 6, 2003 [Page 57]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
<xsd:annotation>
<xsd:documentation>
Represents an individual MBeanAttributeInfo instance
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="jmxp:feature-info">
<xsd:attribute name="type" type="xsd:string"/>
<xsd:attribute name="readable" type="xsd:boolean"/>
<xsd:attribute name="writeable" type="xsd:boolean"/>
<xsd:attribute name="is" type="xsd:boolean"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="constructor-info">
<xsd:annotation>
<xsd:documentation>
Represents an individual MBeanConstructorInfo instance
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="jmxp:feature-info">
<xsd:sequence>
<xsd:element ref="jmxp:parameter-info"
minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="operation-info">
<xsd:annotation>
<xsd:documentation>
Represents an individual MBeanOperationInfo instance
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="jmxp:feature-info">
<xsd:sequence>
<xsd:element ref="jmxp:parameter-info"
minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
Harold Expires November 6, 2003 [Page 58]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
<xsd:attribute name="returnType" type="xsd:string"/>
<xsd:attribute name="impact" type="xsd:int"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="parameter-info">
<xsd:annotation>
<xsd:documentation>
Represents an individual MBeanParameterInfo instance
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="jmxp:feature-info">
<xsd:attribute name="type" type="xsd:string"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
An ObjectInstance value is defined by the schema fragment:
<xsd:element name="ObjectInstance">
<xsd:annotation>
<xsd:documentation>
Represents a JMX ObjectInstance instance
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence maxOccurs="1">
<xsd:element ref="jmxp:ObjectName"/>
</xsd:sequence>
<xsd:attribute name="classname" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
Finally, the restricted string types required by the JMXP profile
elements are defined in the following XML Schema fragment:
<!--
Restricted string types for various profile element attributes
-->
<xsd:simpleType name="attributeAction">
<xsd:annotation>
<xsd:documentation>
The legal values for the "mbean-attributes" element's
"action" attribute
Harold Expires November 6, 2003 [Page 59]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="get"/>
<xsd:enumeration value="set"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="listenerAction">
<xsd:annotation>
<xsd:documentation>
The legal values for the "notification-listener" element's
"action" attribute
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="add"/>
<xsd:enumeration value="remove"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="serverMethod">
<xsd:annotation>
<xsd:documentation>
The legal values for the "server-invocation" element's
"method" attribute
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="createMBean"/>
<xsd:enumeration value="getDefaultDomain"/>
<xsd:enumeration value="getMBeanCount"/>
<xsd:enumeration value="getObjectInstance"/>
<xsd:enumeration value="isInstanceOf"/>
<xsd:enumeration value="isRegistered"/>
<xsd:enumeration value="queryMBeans"/>
<xsd:enumeration value="queryNames"/>
<xsd:enumeration value="unregisterMBean"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="scalarType">
<xsd:annotation>
<xsd:documentation>
The legal values for a "scalar-type" element
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Boolean"/>
<xsd:enumeration value="Byte"/>
<xsd:enumeration value="Character"/>
Harold Expires November 6, 2003 [Page 60]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
<xsd:enumeration value="String"/>
<xsd:enumeration value="Integer"/>
<xsd:enumeration value="Long"/>
<xsd:enumeration value="Float"/>
<xsd:enumeration value="Double"/>
<xsd:enumeration value="Date"/>
<xsd:enumeration value="ObjectName"/>
</xsd:restriction>
</xsd:simpleType>
Harold Expires November 6, 2003 [Page 61]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
References
[1] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821,
August 1982.
[2] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, November
1996.
[3] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[4] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC 2396, August
1998.
[5] Newman, C., "Using TLS with IMAP, POP3 and ACAP", RFC 2595,
June 1999.
[6] Ramsdell, B., "S/MIME Version 3 Message Specification", RFC
2633, June 1999.
[7] Hinden, R., Carpenter, B. and L. Masinter, "Format for Literal
IPv6 Addresses in URL's", RFC 2732, December 1999.
[8] Gulbrandsen, A., Vixie, P. and L. Esibov, "A DNS RR for
specifying the location of services (DNS SRV)", RFC 2782,
February 2000.
[9] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC
3080, March 2001.
[10] Rose, M., "On the Design of Application Protocols", RFC 3117,
November 2001.
[11] Elkins, M., Del Torto, D., Levien, R. and T. Roessler, "MIME
Security with OpenPGP", RFC 3156, August 2001.
[12] O'Tuathail, E. and M. Rose, "Using the Simple Object Access
Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP)",
RFC 3288, June 2002.
[13] Rose, M., "BEEP The Definitive Guide", March 2002.
[14] Sun Microsystems, Inc., "Java(tm) Management Extensions
Instrumentation and Agent Specification, v1.2", March 2002.
[15] <http://jcp.org/aboutJava/communityprocess/final/jsr003/
Harold Expires November 6, 2003 [Page 62]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
index2.html>
Author's Address
Ward K Harold
IBM Tivoli Software
11400 Burnet Rd
Austin, TX 78758
US
Phone: +1 512 838 3022
EMail: wharold@us.ibm.com
Harold Expires November 6, 2003 [Page 63]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on the
IETF's procedures with respect to rights in standards-track and
standards-related documentation can be found in BCP-11. Copies of
claims of rights made available for publication and any assurances of
licenses to be made available, or the result of an attempt made to
obtain a general license or permission for the use of such
proprietary rights by implementors or users of this specification can
be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive
Director.
Full Copyright Statement
Copyright (C) The Internet Society (2003). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assignees.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
Harold Expires November 6, 2003 [Page 64]
Internet-Draft Java(tm) Management Extensions Protocol May 2003
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Harold Expires November 6, 2003 [Page 65]
