From: http://www.ietf.org/internet-drafts/draft-harold-jmxp-00.txt Java Management Extensions Protocol ------------------------------------------------------------------------ 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: C: C: C: JMImplementation:type=MBeanServerDelegate C: C: C: timers:id=alarms C: C: C: 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: C: C: C: JMImplementation:type=MBeanServerDelegate C: C: C: timers:id=alarms C: C: C: 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: S: Harold Expires November 6, 2003 [Page 11] Internet-Draft Java(tm) Management Extensions Protocol May 2003 S: S:END C:RPY 0 1 . 0 64 C:Content-Type: application/beep+xml C: C: C: C: C:END ... The JMXP Server calls addNotificationListener() ... S:RPY 1 21 . 142 82 S:Content-Type: application/beep+xml S: S: S: S: S: S: JMImplementation:type=MBeanServerDelegate S: S: S: timers:id=alarms S: S: S: S: 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: C: C: C: JMImplementation:type=MBeanServerDelegate C: C: C: 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: S: S: S: S: JMImplementation:type=MBeanServerDelegate S: S: S: S: 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: C: C: C: JMImplementation:type=MBeanServerDelegate C: C: C: timers:id=bogus C: C: C: 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: S: Harold Expires November 6, 2003 [Page 13] Internet-Draft Java(tm) Management Extensions Protocol May 2003 S: S: S: JMImplementation:type=MBeanServerDelegate S: S: S: S: 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: C: C: C: JMImplementation:type=MBeanServerDelegate C: C: C: 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: S: S: S:END C:ERR 0 8 . 0 64 C:Content-Type: application/beep+xml C: C:I want to be left alone C:END S:RPY 1 21 . 142 82 S:Content-Type: application/beep+xml S: S: 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: C: C: javax.management.timer.Timer C: timers:id=alarms C: C: 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: C: C: javax.management.timer.Timer C: timers:id=alarms C: C: C:END ... JMXP Server invokes createMBean() with the given arguments ... S:RPY 1 1 . 221 87 S:Content-Type: application/beep+xml S: S: Harold Expires November 6, 2003 [Page 15] Internet-Draft Java(tm) Management Extensions Protocol May 2003 S: S: S: timers:id=alarm S: S: S: S:END Alternatively, an unsuccessful invocation might look like: C:MSG 1 1 . 52 120 C:Content-Type: application/beep+xml C: C: C: C: javax.management.Timer C: timers:id=alarms C: C: C:END ... JMXP Server invokes createMBean() with the given arguments ... S:RPY 1 1 . 221 87 S:Content-Type: application/beep+xml S: S: S: S: Class not found S: S: S: 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: C: C: C: C: C: C: 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: C: C: C: C: C: C: 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: S: S: S: S: 1024 S: S: S: 256 S: S: S: 512 S: S: S: S: 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: C: C: C: 2048 C: C: C: 128 C: C: C: 192 C: C: C: C:END ... JMXP Server updates the specified attributes ... S:RPY 1 1 . 221 87 S:Content-Type: application/beep+xml S: S: S: Harold Expires November 6, 2003 [Page 19] Internet-Draft Java(tm) Management Extensions Protocol May 2003 S: S: S: 2048 S: S: S: 128 S: S: S: 192 S: S: S: S: 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: C: C: C: -2048 C: C: C: 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: S: S: S: The specified MBean is not registered witht he MBeanServer S: S: S: 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: 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: C:END ... JMXP Server calls getMBeanInfo() ... S:RPY 1 11 . 281 265 S:Content-Type: application/beep+xml S: S: S: S: S: S: S: S: jmx.monitor.counter.threshold S: S: S: jmx.monitor.error.runtime S: Harold Expires November 6, 2003 [Page 21] Internet-Draft Java(tm) Management Extensions Protocol May 2003 S: S: jmx.monitor.error.threshold S: S: S: S: S: S: S: ... remaining CounterMonitor attributes ... S: S: S: S: S: S: S: S: Here's an illustration of an unsuccessful MBeanInfo request: C:MSG 1 17 . 152 77 C:Content-Type: application/beep+xml C: C: C:END ... JMXP Server calls getMBeanInfo() ... S:RPY 1 11 . 281 265 S:Content-Type: application/beep+xml S: S: S: S: S: The MBean specified was not found S: S: Harold Expires November 6, 2003 [Page 22] Internet-Draft Java(tm) Management Extensions Protocol May 2003 S: 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: C: C: 42 C: C: 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: C: C: timers.alarm C: Wake Up! C: It's time for school C: 1038722400000 Harold Expires November 6, 2003 [Page 23] Internet-Draft Java(tm) Management Extensions Protocol May 2003 C: C: C:END ... JMXP Server invokes addNotification() with the given arguments ... S:RPY 1 1 . 221 87 S:Content-Type: application/beep+xml S: S: S: 13 S: S:END The following exchange illustrates an unsuccessful invocation: C:MSG 1 1 . 52 120 C:Content-Type: application/beep+xml C: C: C: C: timers.alarm C: Wake Up! C: It's time for school C: 1021352400000 C: C: C:END ... JMXP Server invokes addNotification() with the given arguments ... S:RPY 1 1 . 221 87 S:Content-Type: application/beep+xml S: S: S: S: S: S:END C:RPY 0 1 . 0 64 C:Content-Type: application/beep+xml C: C: 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: S: S: S: S: S: String S: S: S: Long S: S: S: Long S: S: S: String S: S: S: String S: S: S: Integer S: S: S: S: Wake Up! S: 42 S: 1043474400000 S: timers.alarm S: 11 S: S: S: S: 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: 42 69 java.lang.Integer java.lang.Integer 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., 42 or, in the case of an exception: Unable to parse key property list 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 always empty, i.e., , represents the return value of a 'void' method o may be either 'true' or 'false' o a value from -128 to 127 inclusive o a value from '\u0000' to '\uffff' inclusive o a sequence of Unicode characters o a value from -32768 to 32767 inclusive o a value from -2147483648 to 2147483647 inclusive o a value from -9223372036854775808 to 9223372036854775807 inclusive o a single-precision 32-bit format IEEE 754 floating point value o a double-precision 64-bit format IEEE 754 floating point value o a 'long' value representing the number of milliseconds since January 1, 1970, 00:00:00 GMT o 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: xyzzy 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: 2 4 8 16 32 64 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., 0.32112 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: ObjectName JMImplementation:type=MBeanServerDelegate connectors:id=jmxp,port=3006 timers:id=master A "composite-data" representation of a NetworkCard object might look like: String String Integer String LinkSys LNE 100M 3 127.0.0.2 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. 2. 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: ObjectName Float Float monitors:id=HitRate,type=gauge 12.8 204.8 monitors:id=TransferRate,type=gauge 25.6 409.6 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., Harold Expires November 6, 2003 [Page 34] Internet-Draft Java(tm) Management Extensions Protocol May 2003 simple.error simple.alert Harold Expires November 6, 2003 [Page 35] Internet-Draft Java(tm) Management Extensions Protocol May 2003 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., monitors:id=hits 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: C: C: RPY 0 0 . 0 52 C: Content-Type: application/xml C: C: C: C: C: END S: RPY 0 0 . 0 110 S: Content-Type: application/xml S: S: S: S: S: S: END C: MSG 0 1 . 52 158 C: Content-Type: application/xml C: C: C: C: ]]> C: C: C: END S: RPY 0 1 . 110 121 S: Content-Type: application/xml S: S: S: ]]> S: S: END ... TLS negotiations ... S: RPY 0 0 . 0 88 S: Content-Type: application/xml S: S: S: S: S: 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: C: C: 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: C: C: C: END S: RPY 0 2 . 341 402 S: Content-Type: application/xml S: S: 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 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 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 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 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 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 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: Used to express interest, or lack thereof, in JMX Notifications emitted by MBeans registered with an MBeanServer Used to invoke methods on the MBeanServer itself. 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: Used to retrieve or update the value of one or more attributes associated with an MBean Used to retreive the MBeanInfo metadata for an MBean Used to invoke an operation on an MBean 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: Used to deliver a JMX Notification emitted by an MBean to a JMXP client listening for such notifications 10.4 Common Element Schema The "arguments" element is defined by the XML Schema fragment: Container element for values passed as arguments to an MBeanServer method, an MBean operation, or a notification-listener request. The "response" and "exception" elements are defined by the XML Schema fragment: 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 JMXP representation of a Java exception The text of the message associated with a Java exception The base "value" element definition is: Represents values of various types that are exchanged by JMXP peers Harold Expires November 6, 2003 [Page 51] Internet-Draft Java(tm) Management Extensions Protocol May 2003 The scalar "value" elements are defined by the XML Schema fragment: The structured "value" elements are defined by the XML Schema fragment: Represents an array of values Harold Expires November 6, 2003 [Page 52] Internet-Draft Java(tm) Management Extensions Protocol May 2003 Represents a JMX Attribute instance Defines a JMXP structured type Harold Expires November 6, 2003 [Page 53] Internet-Draft Java(tm) Management Extensions Protocol May 2003 Represents a composite data value transfered by JMXP Harold Expires November 6, 2003 [Page 54] Internet-Draft Java(tm) Management Extensions Protocol May 2003 Represents a tabular data value transfered by JMXP 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: Represents the MBeanInfo metadata for an MBean Harold Expires November 6, 2003 [Page 55] Internet-Draft Java(tm) Management Extensions Protocol May 2003 The elements representing the arrays of notificaiton, attribute, constructor, and operation metadata info are defined by the following XML Schema fragment: Represents an array of MBeanNotificationInfo instances in the mbean-info-data Represents the array of MBeanAttributeInfo instances in the mbean-info-data Represents the array of MBeanConstructorInfo instances in the mbean-info-data Harold Expires November 6, 2003 [Page 56] Internet-Draft Java(tm) Management Extensions Protocol May 2003 Represents the array of MBeanOperationInfo instances in the mbean-info-data Elements representing the notification, attribute, constructor, operation, and parameter metadata instances in the corresponding arrays are defined by the following XML Schema fragment: The base type for all of the mbean-info-data's *-info elements Represents an individual MBeanNotificationInfo instance Harold Expires November 6, 2003 [Page 57] Internet-Draft Java(tm) Management Extensions Protocol May 2003 Represents an individual MBeanAttributeInfo instance Represents an individual MBeanConstructorInfo instance Represents an individual MBeanOperationInfo instance Harold Expires November 6, 2003 [Page 58] Internet-Draft Java(tm) Management Extensions Protocol May 2003 Represents an individual MBeanParameterInfo instance An ObjectInstance value is defined by the schema fragment: Represents a JMX ObjectInstance instance Finally, the restricted string types required by the JMXP profile elements are defined in the following XML Schema fragment: 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 The legal values for the "notification-listener" element's "action" attribute The legal values for the "server-invocation" element's "method" attribute The legal values for a "scalar-type" element Harold Expires November 6, 2003 [Page 60] Internet-Draft Java(tm) Management Extensions Protocol May 2003 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] 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]