6252609: Two different default descriptor forms defined for ModelMBeanInfoSupport
6253137: Documentation for NotificationListener's handback parameter is confusing
6368691: javadoc for JMX Descriptors has bugs and is very hard to navigate.
6602699: support for async notification of mbeaninfo update
6759612: [javadoc] EventClient.NOTIFS_LOST has a garbled href to addEventClientListener
6759619: Clarify what EventClient.getEventClientNotificationInfo does
6759622: Clarify what EventClient.getListeners list does
Summary: Documentation fixes, plus simple bugfix for 6759619.
Reviewed-by: dfuchs
--- a/jdk/src/share/classes/javax/management/Descriptor.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/src/share/classes/javax/management/Descriptor.java Thu Oct 30 17:46:50 2008 +0100
@@ -101,7 +101,7 @@
*
* <tr><th>Name</th><th>Type</th><th>Used in</th><th>Meaning</th></tr>
*
- * <tr><td><a name="defaultValue"><i>defaultValue</i></a><td>Object</td>
+ * <tr id="defaultValue"><td><i>defaultValue</i><td>Object</td>
* <td>MBeanAttributeInfo<br>MBeanParameterInfo</td>
*
* <td>Default value for an attribute or parameter. See
@@ -144,7 +144,7 @@
* might be disabled if it cannot currently be emitted but could be in
* other circumstances.</td>
*
- * <tr><td><a name="immutableInfo"><i>immutableInfo</i></a><td>String</td>
+ * <tr id="immutableInfo"><td><i>immutableInfo</i><td>String</td>
* <td>MBeanInfo</td>
*
* <td>The string {@code "true"} or {@code "false"} according as this
@@ -153,20 +153,24 @@
* the lifetime of the MBean. Hence, a client can read it once and
* cache the read value. When this field is false or absent, there is
* no such guarantee, although that does not mean that the MBeanInfo
- * will necessarily change.</td>
+ * will necessarily change. See also the <a
+ * href="MBeanInfo.html#info-changed">{@code "jmx.mbean.info.changed"}</a>
+ * notification.</td>
*
* <tr><td>infoTimeout</td><td>String<br>Long</td><td>MBeanInfo</td>
*
- * <td>The time in milli-seconds that the MBeanInfo can reasonably be
- * expected to be unchanged. The value can be a {@code Long} or a
- * decimal string. This provides a hint from a DynamicMBean or any
+ * <td id="infoTimeout">The time in milli-seconds that the MBeanInfo can
+ * reasonably be expected to be unchanged. The value can be a {@code Long}
+ * or a decimal string. This provides a hint from a DynamicMBean or any
* MBean that does not define {@code immutableInfo} as {@code true}
* that the MBeanInfo is not likely to change within this period and
* therefore can be cached. When this field is missing or has the
* value zero, it is not recommended to cache the MBeanInfo unless it
- * has the {@code immutableInfo} set to {@code true}.</td></tr>
+ * has the {@code immutableInfo} set to {@code true} or it has <a
+ * href="MBeanInfo.html#info-changed">{@code "jmx.mbean.info.changed"}</a> in
+ * its {@link MBeanNotificationInfo} array.</td></tr>
*
- * <tr><td><a name="interfaceClassName"><i>interfaceClassName</i></a></td>
+ * <tr id="interfaceClassName"><td><i>interfaceClassName</i></td>
* <td>String</td><td>MBeanInfo</td>
*
* <td>The Java interface name for a Standard MBean or MXBean, as
@@ -175,19 +179,19 @@
* StandardMBean} class will have this field in its MBeanInfo
* Descriptor.</td>
*
- * <tr><td><a name="legalValues"><i>legalValues</i></a></td>
+ * <tr id="legalValues"><td><i>legalValues</i></td>
* <td>{@literal Set<?>}</td><td>MBeanAttributeInfo<br>MBeanParameterInfo</td>
*
* <td>Legal values for an attribute or parameter. See
* {@link javax.management.openmbean}.</td>
*
- * <tr><td><a name="maxValue"><i>maxValue</i></a><td>Object</td>
+ * <tr id="maxValue"><td><i>maxValue</i><td>Object</td>
* <td>MBeanAttributeInfo<br>MBeanParameterInfo</td>
*
* <td>Maximum legal value for an attribute or parameter. See
* {@link javax.management.openmbean}.</td>
*
- * <tr><td><a name="metricType">metricType</a><td>String</td>
+ * <tr id="metricType"><td>metricType</td><td>String</td>
* <td>MBeanAttributeInfo<br>MBeanOperationInfo</td>
*
* <td>The type of a metric, one of the strings "counter" or "gauge".
@@ -200,13 +204,13 @@
* that can increase or decrease. Examples might be the number of
* open connections or a cache hit rate or a temperature reading.
*
- * <tr><td><a name="minValue"><i>minValue</i></a><td>Object</td>
+ * <tr id="minValue"><td><i>minValue</i><td>Object</td>
* <td>MBeanAttributeInfo<br>MBeanParameterInfo</td>
*
* <td>Minimum legal value for an attribute or parameter. See
* {@link javax.management.openmbean}.</td>
*
- * <tr><td><a name="mxbean"><i>mxbean</i></a><td>String</td>
+ * <tr id="mxbean"><td><i>mxbean</i><td>String</td>
* <td>MBeanInfo</td>
*
* <td>The string {@code "true"} or {@code "false"} according as this
@@ -223,7 +227,7 @@
* MXBean, if it was not the {@linkplain MXBeanMappingFactory#DEFAULT default}
* one.</td>
*
- * <tr><td><a name="openType"><i>openType</i></a><td>{@link OpenType}</td>
+ * <tr id="openType"><td><i>openType</i><td>{@link OpenType}</td>
* <td>MBeanAttributeInfo<br>MBeanOperationInfo<br>MBeanParameterInfo</td>
*
* <td><p>The Open Type of this element. In the case of {@code
@@ -240,7 +244,7 @@
* which case it indicates the Open Type that the {@link
* Notification#getUserData() user data} will have.</td>
*
- * <tr><td><a name="originalType"><i>originalType</i></a><td>String</td>
+ * <tr id="originalType"><td><i>originalType</i><td>String</td>
* <td>MBeanAttributeInfo<br>MBeanOperationInfo<br>MBeanParameterInfo</td>
*
* <td><p>The original Java type of this element as it appeared in the
@@ -282,11 +286,132 @@
*
* </table>
*
- * <p>Some additional fields are defined by Model MBeans. See
- * {@link javax.management.modelmbean.ModelMBeanInfo ModelMBeanInfo}
- * and related classes and the chapter "Model MBeans" of the
- * <a href="http://java.sun.com/products/JavaManagement/download.html">
- * JMX Specification</a>.</p>
+ * <p>Some additional fields are defined by Model MBeans. See the
+ * information for <a href="modelmbean/ModelMBeanInfo.html#descriptor"><!--
+ * -->{@code ModelMBeanInfo}</a>,
+ * <a href="modelmbean/ModelMBeanAttributeInfo.html#descriptor"><!--
+ * -->{@code ModelMBeanAttributeInfo}</a>,
+ * <a href="modelmbean/ModelMBeanConstructorInfo.html#descriptor"><!--
+ * -->{@code ModelMBeanConstructorInfo}</a>,
+ * <a href="modelmbean/ModelMBeanNotificationInfo.html#descriptor"><!--
+ * -->{@code ModelMBeanNotificationInfo}</a>, and
+ * <a href="modelmbean/ModelMBeanOperationInfo.html#descriptor"><!--
+ * -->{@code ModelMBeanOperationInfo}</a>, as
+ * well as the chapter "Model MBeans" of the <a
+ * href="http://java.sun.com/products/JavaManagement/download.html">JMX
+ * Specification</a>. The following table summarizes these fields. Note
+ * that when the Type in this table is Number, a String that is the decimal
+ * representation of a Long can also be used.</p>
+ *
+ * <p>Nothing prevents the use of these fields in MBeans that are not Model
+ * MBeans. The <a href="#displayName">displayName</a>, <a href="#severity"><!--
+ * -->severity</a>, and <a href="#visibility">visibility</a> fields are of
+ * interest outside Model MBeans, for example. But only Model MBeans have
+ * a predefined behavior for these fields.</p>
+ *
+ * <table border="1" cellpadding="5">
+ *
+ * <tr><th>Name</th><th>Type</th><th>Used in</th><th>Meaning</th></tr>
+ *
+ * <tr><td>class</td><td>String</td><td>ModelMBeanOperationInfo</td>
+ * <td>Class where method is defined (fully qualified).</td></tr>
+ *
+ * <tr><td>currencyTimeLimit</td><td>Number</td>
+ * <td>ModelMBeanInfo<br>ModelMBeanAttributeInfo<br>ModelMBeanOperationInfo</td>
+ * <td>How long cached value is valid: <0 never, =0 always,
+ * >0 seconds.</td></tr>
+ *
+ * <tr><td>default</td><td>Object</td><td>ModelMBeanAttributeInfo</td>
+ * <td>Default value for attribute.</td></tr>
+ *
+ * <tr><td>descriptorType</td><td>String</td><td>Any</td>
+ * <td>Type of descriptor, "mbean", "attribute", "constructor", "operation",
+ * or "notification".</td></tr>
+ *
+ * <tr id="displayName"><td>displayName</td><td>String</td><td>Any</td>
+ * <td>Human readable name of this item.</td></tr>
+ *
+ * <tr><td>export</td><td>String</td><td>ModelMBeanInfo</td>
+ * <td>Name to be used to export/expose this MBean so that it is
+ * findable by other JMX Agents.</td></tr>
+ *
+ * <tr><td>getMethod</td><td>String</td><td>ModelMBeanAttributeInfo</td>
+ * <td>Name of operation descriptor for get method.</td></tr>
+ *
+ * <tr><td>lastUpdatedTimeStamp</td><td>Number</td>
+ * <td>ModelMBeanAttributeInfo<br>ModelMBeanOperationInfo</td>
+ * <td>When <a href="#value-field">value</a> was set.</td></tr>
+ *
+ * <tr><td>log</td><td>String</td><td>ModelMBeanInfo<br>ModelMBeanNotificationInfo</td>
+ * <td>t or T: log all notifications, f or F: log no notifications.</td></tr>
+ *
+ * <tr><td>logFile</td><td>String</td><td>ModelMBeanInfo<br>ModelMBeanNotificationInfo</td>
+ * <td>Fully qualified filename to log events to.</td></tr>
+ *
+ * <tr><td>messageID</td><td>String</td><td>ModelMBeanNotificationInfo</td>
+ * <td>Unique key for message text (to allow translation, analysis).</td></tr>
+ *
+ * <tr><td>messageText</td><td>String</td><td>ModelMBeanNotificationInfo</td>
+ * <td>Text of notification.</td></tr>
+ *
+ * <tr><td>name</td><td>String</td><td>Any</td>
+ * <td>Name of this item.</td></tr>
+ *
+ * <tr><td>persistFile</td><td>String</td><td>ModelMBeanInfo</td>
+ * <td>File name into which the MBean should be persisted.</td></tr>
+ *
+ * <tr><td>persistLocation</td><td>String</td><td>ModelMBeanInfo</td>
+ * <td>The fully qualified directory name where the MBean should be
+ * persisted (if appropriate).</td></tr>
+ *
+ * <tr><td>persistPeriod</td><td>Number</td>
+ * <td>ModelMBeanInfo<br>ModelMBeanAttributeInfo</td>
+ * <td>Frequency of persist cycle in seconds. Used when persistPolicy is
+ * "OnTimer" or "NoMoreOftenThan".</td></tr>
+ *
+ * <tr><td>persistPolicy</td><td>String</td>
+ * <td>ModelMBeanInfo<br>ModelMBeanAttributeInfo</td>
+ * <td>One of: OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never.
+ * See the section "MBean Descriptor Fields" in the JMX specification
+ * document.</td></tr>
+ *
+ * <tr><td>presentationString</td><td>String</td><td>Any</td>
+ * <td>XML formatted string to allow presentation of data.</td></tr>
+ *
+ * <tr><td>protocolMap</td><td>Descriptor</td><td>ModelMBeanAttributeInfo</td>
+ * <td>See the section "Protocol Map Support" in the JMX specification
+ * document. Mappings must be appropriate for the attribute and entries
+ * can be updated or augmented at runtime.</td></tr>
+ *
+ * <tr><td>role</td><td>String</td>
+ * <td>ModelMBeanConstructorInfo<br>ModelMBeanOperationInfo</td>
+ * <td>One of "constructor", "operation", "getter", or "setter".</td></tr>
+ *
+ * <tr><td>setMethod</td><td>String</td><td>ModelMBeanAttributeInfo</td>
+ * <td>Name of operation descriptor for set method.</td></tr>
+ *
+ * <tr id="severity"><td>severity</td><td>Number</td>
+ * <td>ModelMBeanNotificationInfo</td>
+ * <td>0-6 where 0: unknown; 1: non-recoverable;
+ * 2: critical, failure; 3: major, severe;
+ * 4: minor, marginal, error; 5: warning;
+ * 6: normal, cleared, informative</td></tr>
+ *
+ * <tr><td>targetObject</td><td>Object</td><td>ModelMBeanOperationInfo</td>
+ * <td>Object on which to execute this method.</td></tr>
+ *
+ * <tr><td>targetType</td><td>String</td><td>ModelMBeanOperationInfo</td>
+ * <td>type of object reference for targetObject. Can be:
+ * ObjectReference | Handle | EJBHandle | IOR | RMIReference.</td></tr>
+ *
+ * <tr id="value-field"><td>value</td><td>Object</td>
+ * <td>ModelMBeanAttributeInfo<br>ModelMBeanOperationInfo</td>
+ * <td>Current (cached) value for attribute or operation.</td></tr>
+ *
+ * <tr id="visibility"><td>visibility</td><td>Number</td><td>Any</td>
+ * <td>1-4 where 1: always visible, 4: rarely visible.</td></tr>
+ *
+ * </table>
*
* @since 1.5
*/
@@ -439,7 +564,7 @@
public boolean isValid() throws RuntimeOperationsException;
/**
- * Compares this descriptor to the given object. The objects are equal if
+ * <p>Compares this descriptor to the given object. The objects are equal if
* the given object is also a Descriptor, and if the two Descriptors have
* the same field names (possibly differing in case) and the same
* associated values. The respective values for a field in the two
--- a/jdk/src/share/classes/javax/management/MBeanInfo.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/src/share/classes/javax/management/MBeanInfo.java Thu Oct 30 17:46:50 2008 +0100
@@ -45,6 +45,17 @@
* management operations. Instances of this class are immutable.
* Subclasses may be mutable but this is not recommended.</p>
*
+ * <p id="info-changed">Usually the {@code MBeanInfo} for any given MBean does
+ * not change over the lifetime of that MBean. Dynamic MBeans can change their
+ * {@code MBeanInfo} and in that case it is recommended that they emit a {@link
+ * Notification} with a {@linkplain Notification#getType() type} of {@code
+ * "jmx.mbean.info.changed"} and a {@linkplain Notification#getUserData()
+ * userData} that is the new {@code MBeanInfo}. This is not required, but
+ * provides a conventional way for clients of the MBean to discover the change.
+ * See also the <a href="Descriptor.html#immutableInfo">immutableInfo</a> and
+ * <a href="Descriptor.html#infoTimeout">infoTimeout</a> fields in the {@code
+ * MBeanInfo} {@link Descriptor}.</p>
+ *
* <p>The contents of the <code>MBeanInfo</code> for a Dynamic MBean
* are determined by its {@link DynamicMBean#getMBeanInfo
* getMBeanInfo()} method. This includes Open MBeans and Model
@@ -62,27 +73,49 @@
* constructors in that object;
*
* <li>{@link #getAttributes()} returns the list of all attributes
- * whose existence is deduced from the presence in the MBean interface
- * of a <code>get<i>Name</i></code>, <code>is<i>Name</i></code>, or
- * <code>set<i>Name</i></code> method that conforms to the conventions
+ * whose existence is deduced as follows:
+ * <ul>
+ * <li>if the Standard MBean is defined with an MBean interface,
+ * from <code>get<i>Name</i></code>, <code>is<i>Name</i></code>, or
+ * <code>set<i>Name</i></code> methods that conform to the conventions
* for Standard MBeans;
+ * <li>if the Standard MBean is defined with the {@link MBean @MBean} or
+ * {@link MXBean @MXBean} annotation on a class, from methods with the
+ * {@link ManagedAttribute @ManagedAttribute} annotation;
+ * </ul>
*
- * <li>{@link #getOperations()} returns the list of all methods in
+ * <li>{@link #getOperations()} returns the list of all operations whose
+ * existence is deduced as follows:
+ * <ul>
+ * <li>if the Standard MBean is defined with an MBean interface, from methods in
* the MBean interface that do not represent attributes;
+ * <li>if the Standard MBean is defined with the {@link MBean @MBean} or
+ * {@link MXBean @MXBean} annotation on a class, from methods with the
+ * {@link ManagedOperation @ManagedOperation} annotation;
+ * </ul>
*
- * <li>{@link #getNotifications()} returns an empty array if the MBean
- * does not implement the {@link NotificationBroadcaster} interface,
- * otherwise the result of calling {@link
+ * <li>{@link #getNotifications()} returns:
+ * <ul>
+ * <li>if the MBean implements the {@link NotificationBroadcaster} interface,
+ * the result of calling {@link
* NotificationBroadcaster#getNotificationInfo()} on it;
+ * <li>otherwise, if there is a {@link NotificationInfo @NotificationInfo}
+ * or {@link NotificationInfos @NotificationInfos} annotation on the
+ * MBean interface or <code>@MBean</code> or <code>@MXBean</code>
+ * class, the array implied by those annotations;
+ * <li>otherwise an empty array;
+ * </ul>
*
* <li>{@link #getDescriptor()} returns a descriptor containing the contents
- * of any descriptor annotations in the MBean interface.
+ * of any descriptor annotations in the MBean interface (see
+ * {@link DescriptorFields @DescriptorFields} and
+ * {@link DescriptorKey @DescriptorKey}).
*
* </ul>
*
* <p>The description returned by {@link #getDescription()} and the
* descriptions of the contained attributes and operations are determined
- * by the corresponding <!-- link here --> Description annotations if any;
+ * by the corresponding {@link Description} annotations if any;
* otherwise their contents are not specified.</p>
*
* <p>The remaining details of the <code>MBeanInfo</code> for a
--- a/jdk/src/share/classes/javax/management/MBeanServer.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/src/share/classes/javax/management/MBeanServer.java Thu Oct 30 17:46:50 2008 +0100
@@ -377,19 +377,19 @@
* MBean will not be registered.
* @exception RuntimeMBeanException If the <CODE>postRegister</CODE>
* (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a
- * <CODE>RuntimeException</CODE>, the <CODE>registerMBean<CODE> method will
+ * <CODE>RuntimeException</CODE>, the <CODE>registerMBean</CODE> method will
* throw a <CODE>RuntimeMBeanException</CODE>, although the MBean
* registration succeeded. In such a case, the MBean will be actually
- * registered even though the <CODE>registerMBean<CODE> method
+ * registered even though the <CODE>registerMBean</CODE> method
* threw an exception. Note that <CODE>RuntimeMBeanException</CODE> can
* also be thrown by <CODE>preRegister</CODE>, in which case the MBean
* will not be registered.
* @exception RuntimeErrorException If the <CODE>postRegister</CODE>
* (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an
- * <CODE>Error</CODE>, the <CODE>registerMBean<CODE> method will
+ * <CODE>Error</CODE>, the <CODE>registerMBean</CODE> method will
* throw a <CODE>RuntimeErrorException</CODE>, although the MBean
* registration succeeded. In such a case, the MBean will be actually
- * registered even though the <CODE>registerMBean<CODE> method
+ * registered even though the <CODE>registerMBean</CODE> method
* threw an exception. Note that <CODE>RuntimeErrorException</CODE> can
* also be thrown by <CODE>preRegister</CODE>, in which case the MBean
* will not be registered.
@@ -411,6 +411,8 @@
* is sent as described <a href="#notif">above</a>.</p>
*
* @throws RuntimeOperationsException {@inheritDoc}
+ * @throws RuntimeMBeanException {@inheritDoc}
+ * @throws RuntimeErrorException {@inheritDoc}
*/
public void unregisterMBean(ObjectName name)
throws InstanceNotFoundException, MBeanRegistrationException;
--- a/jdk/src/share/classes/javax/management/NotificationListener.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/src/share/classes/javax/management/NotificationListener.java Thu Oct 30 17:46:50 2008 +0100
@@ -39,11 +39,10 @@
* blocking its notification broadcaster.
*
* @param notification The notification.
- * @param handback An opaque object which helps the listener to associate information
- * regarding the MBean emitter. This object is passed to the MBean during the
- * addListener call and resent, without modification, to the listener. The MBean object
- * should not use or modify the object.
- *
+ * @param handback An opaque object which helps the listener to associate
+ * information regarding the MBean emitter. This object is passed to the
+ * addNotificationListener call and resent, without modification, to the
+ * listener.
*/
- public void handleNotification(Notification notification, Object handback) ;
+ public void handleNotification(Notification notification, Object handback);
}
--- a/jdk/src/share/classes/javax/management/event/EventClient.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/src/share/classes/javax/management/event/EventClient.java Thu Oct 30 17:46:50 2008 +0100
@@ -117,12 +117,12 @@
public static final String NONFATAL = "jmx.event.service.nonfatal";
/**
- * <p>A notification string type used by an {@code EventClient} object to
- * inform a listener added by {@code #addEventClientListener} that it
- * has detected that notifications have been lost. The {@link
- * Notification#getUserData() userData} of the notification is a Long which
- * is an upper bound on the number of lost notifications that have just
- * been detected.</p>
+ * <p>A notification string type used by an {@code EventClient} object
+ * to inform a listener added by {@link #addEventClientListener
+ * addEventClientListener} that it has detected that notifications have
+ * been lost. The {@link Notification#getUserData() userData} of the
+ * notification is a Long which is an upper bound on the number of lost
+ * notifications that have just been detected.</p>
*
* @see #addEventClientListener
*/
@@ -577,8 +577,13 @@
}
/**
- * Returns the set of listeners that have been added through
- * this {@code EventClient} and not subsequently removed.
+ * <p>Returns the collection of listeners that have been added through
+ * this {@code EventClient} and not subsequently removed. The returned
+ * collection contains one entry for every listener added with
+ * {@link #addNotificationListener addNotificationListener} or
+ * {@link #subscribe subscribe} and not subsequently removed with
+ * {@link #removeNotificationListener removeNotificationListener} or
+ * {@link #unsubscribe unsubscribe}, respectively.</p>
*
* @return A collection of listener information. Empty if there are no
* current listeners or if this {@code EventClient} has been {@linkplain
@@ -927,8 +932,10 @@
private final static MBeanNotificationInfo[] myInfo =
new MBeanNotificationInfo[] {
new MBeanNotificationInfo(
- new String[] {FAILED, NOTIFS_LOST},
- Notification.class.getName(), "")};
+ new String[] {FAILED, NONFATAL, NOTIFS_LOST},
+ Notification.class.getName(),
+ "Notifications that can be sent to a listener added with " +
+ "EventClient.addEventClientListener")};
private final NotificationBroadcasterSupport broadcaster =
new NotificationBroadcasterSupport();
--- a/jdk/src/share/classes/javax/management/modelmbean/DescriptorSupport.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/src/share/classes/javax/management/modelmbean/DescriptorSupport.java Thu Oct 30 17:46:50 2008 +0100
@@ -884,9 +884,9 @@
* not a String with value "t", "f", "true", "false". These String
* values must not be case sensitive.
* <LI> visibility fieldName, if defined, is null, or not a
- * Numeric String or a not Numeric Value >= 1 and <= 4
+ * Numeric String or a not Numeric Value >= 1 and <= 4
* <LI> severity fieldName, if defined, is null, or not a Numeric
- * String or not a Numeric Value >= 0 and <= 6<br>
+ * String or not a Numeric Value >= 0 and <= 6<br>
* <LI> persistPolicy fieldName, if defined, is null, or not one of
* the following strings:<br>
* "OnUpdate", "OnTimer", "NoMoreOftenThan", "OnUnregister", "Always",
--- a/jdk/src/share/classes/javax/management/modelmbean/ModelMBeanAttributeInfo.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/src/share/classes/javax/management/modelmbean/ModelMBeanAttributeInfo.java Thu Oct 30 17:46:50 2008 +0100
@@ -39,7 +39,6 @@
import java.io.ObjectStreamField;
import java.lang.reflect.Method;
import java.security.AccessController;
-import java.security.PrivilegedAction;
import java.util.logging.Level;
import javax.management.Descriptor;
@@ -49,32 +48,56 @@
import javax.management.RuntimeOperationsException;
/**
- * The ModelMBeanAttributeInfo object describes an attribute of the ModelMBean.
+ * <p>The ModelMBeanAttributeInfo object describes an attribute of the ModelMBean.
* It is a subclass of MBeanAttributeInfo with the addition of an associated Descriptor
- * and an implementation of the DescriptorAccess interface.
- * <P>
- * The fields in the descriptor are defined, but not limited to, the following: <P>
- * <PRE>
- * name : attribute name
- * descriptorType : must be "attribute"
- * value : current value for attribute
- * default : default value for attribute
- * displayName : name of attribute to be used in displays
- * getMethod : name of operation descriptor for get method
- * setMethod : name of operation descriptor for set method
- * protocolMap : object which implements the Descriptor interface: mappings
- * must be appropriate for the attribute
- * and entries can be updated or augmented at runtime.
- * persistPolicy : OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never
- * persistPeriod : seconds - frequency of persist cycle. Used when persistPolicy
- * is "OnTimer" or "NoMoreOftenThan".
- * currencyTimeLimit : how long value is valid, <0 never, =0 always, >0 seconds
- * lastUpdatedTimeStamp : when value was set
- * visibility : 1-4 where 1: always visible, 4: rarely visible
- * presentationString : xml formatted string to allow presentation of data
- * </PRE>
- * The default descriptor contains the name, descriptorType and displayName fields.
- * The default value of the name and displayName fields is the name of the attribute.
+ * and an implementation of the DescriptorAccess interface.</p>
+ *
+ * <P id="descriptor">
+ * The fields in the descriptor are defined, but not limited to, the following.
+ * Note that when the Type in this table is Number, a String that is the decimal
+ * representation of a Long can also be used.</P>
+ *
+ * <table border="1" cellpadding="5">
+ * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr>
+ * <tr><td>name</td><td>String</td>
+ * <td>Attribute name.</td></tr>
+ * <tr><td>descriptorType</td><td>String</td>
+ * <td>Must be "attribute".</td></tr>
+ * <tr id="value-field"><td>value</td><td>Object</td>
+ * <td>Current (cached) value for attribute.</td></tr>
+ * <tr><td>default</td><td>Object</td>
+ * <td>Default value for attribute.</td></tr>
+ * <tr><td>displayName</td><td>String</td>
+ * <td>Name of attribute to be used in displays.</td></tr>
+ * <tr><td>getMethod</td><td>String</td>
+ * <td>Name of operation descriptor for get method.</td></tr>
+ * <tr><td>setMethod</td><td>String</td>
+ * <td>Name of operation descriptor for set method.</td></tr>
+ * <tr><td>protocolMap</td><td>Descriptor</td>
+ * <td>See the section "Protocol Map Support" in the JMX specification
+ * document. Mappings must be appropriate for the attribute and entries
+ * can be updated or augmented at runtime.</td></tr>
+ * <tr><td>persistPolicy</td><td>String</td>
+ * <td>One of: OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never.
+ * See the section "MBean Descriptor Fields" in the JMX specification
+ * document.</td></tr>
+ * <tr><td>persistPeriod</td><td>Number</td>
+ * <td>Frequency of persist cycle in seconds. Used when persistPolicy is
+ * "OnTimer" or "NoMoreOftenThan".</td></tr>
+ * <tr><td>currencyTimeLimit</td><td>Number</td>
+ * <td>How long <a href="#value=field">value</a> is valid: <0 never,
+ * =0 always, >0 seconds.</td></tr>
+ * <tr><td>lastUpdatedTimeStamp</td><td>Number</td>
+ * <td>When <a href="#value-field">value</a> was set.</td></tr>
+ * <tr><td>visibility</td><td>Number</td>
+ * <td>1-4 where 1: always visible, 4: rarely visible.</td></tr>
+ * <tr><td>presentationString</td><td>String</td>
+ * <td>XML formatted string to allow presentation of data.</td></tr>
+ * </table>
+ *
+ * <p>The default descriptor contains the name, descriptorType and displayName
+ * fields. The default value of the name and displayName fields is the name of
+ * the attribute.</p>
*
* <p><b>Note:</b> because of inconsistencies in previous versions of
* this specification, it is recommended not to use negative or zero
--- a/jdk/src/share/classes/javax/management/modelmbean/ModelMBeanConstructorInfo.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/src/share/classes/javax/management/modelmbean/ModelMBeanConstructorInfo.java Thu Oct 30 17:46:50 2008 +0100
@@ -49,22 +49,33 @@
import javax.management.RuntimeOperationsException;
/**
- * The ModelMBeanConstructorInfo object describes a constructor of the ModelMBean.
+ * <p>The ModelMBeanConstructorInfo object describes a constructor of the ModelMBean.
* It is a subclass of MBeanConstructorInfo with the addition of an associated Descriptor
- * and an implementation of the DescriptorAccess interface.
- * <P>
- * <PRE>
- * The fields in the descriptor are defined, but not limited to, the following: <P>
- * name : constructor name
- * descriptorType : must be "operation"
- * role : must be "constructor"
- * displayName : human readable name of constructor
- * visibility : 1-4 where 1: always visible 4: rarely visible
- * presentationString : xml formatted string to describe how to present operation
- *</PRE>
+ * and an implementation of the DescriptorAccess interface.</p>
+ *
+ * <P id="descriptor">
+ * The fields in the descriptor are defined, but not limited to, the following.
+ * Note that when the Type in this table is Number, a String that is the decimal
+ * representation of a Long can also be used.</P>
+ *
+ * <table border="1" cellpadding="5">
+ * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr>
+ * <tr><td>name</td><td>String</td>
+ * <td>Constructor name.</td></tr>
+ * <tr><td>descriptorType</td><td>String</td>
+ * <td>Must be "operation".</td></tr>
+ * <tr><td>role</td><td>String</td>
+ * <td>Must be "constructor".</td></tr>
+ * <tr><td>displayName</td><td>String</td>
+ * <td>Human readable name of constructor.</td></tr>
+ * <tr><td>visibility</td><td>Number</td>
+ * <td>1-4 where 1: always visible 4: rarely visible.</td></tr>
+ * <tr><td>presentationString</td><td>String</td>
+ * <td>XML formatted string to describe how to present operation</td></tr>
+ * </table>
*
* <p>The {@code persistPolicy} and {@code currencyTimeLimit} fields
- * are meaningless for constructors, but are not considered invalid.
+ * are meaningless for constructors, but are not considered invalid.</p>
*
* <p>The default descriptor will have the {@code name}, {@code
* descriptorType}, {@code displayName} and {@code role} fields. The
--- a/jdk/src/share/classes/javax/management/modelmbean/ModelMBeanInfo.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/src/share/classes/javax/management/modelmbean/ModelMBeanInfo.java Thu Oct 30 17:46:50 2008 +0100
@@ -156,29 +156,55 @@
/**
- * Returns the ModelMBean's descriptor which contains MBean wide policies. This descriptor contains
- * metadata about the MBean and default policies for persistence and caching.
- * <P>
- * The fields in the descriptor are defined, but not limited to, the following:
- * <PRE>
- * name : MBean name
- * descriptorType : must be "mbean"
- * displayName : name of attribute to be used in displays
- * persistPolicy : OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never
- * persistLocation : The fully qualified directory name where the MBean should be persisted (if appropriate)
- * persistFile : File name into which the MBean should be persisted
- * persistPeriod : seconds - frequency of persist cycle for OnTime and NoMoreOftenThan PersistPolicy
- * currencyTimeLimit : how long value is valid, <0 never, =0 always, >0 seconds
- * log : where t: log all notifications f: log no notifications
- * logfile : fully qualified filename to log events to
- * visibility : 1-4 where 1: always visible 4: rarely visible
- * export : name to be used to export/expose this MBean so that it is findable by
- * other JMX Agents.
- * presentationString : xml formatted string to allow presentation of data to be associated with the MBean.
- * </PRE>
+ * <p>Returns the ModelMBean's descriptor which contains MBean wide
+ * policies. This descriptor contains metadata about the MBean and default
+ * policies for persistence and caching.</p>
+ *
+ * <P id="descriptor">
+ * The fields in the descriptor are defined, but not limited to, the
+ * following. Note that when the Type in this table is Number, a String
+ * that is the decimal representation of a Long can also be used.</P>
+ *
+ * <table border="1" cellpadding="5">
+ * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr>
+ * <tr><td>name</td><td>String</td>
+ * <td>MBean name.</td></tr>
+ * <tr><td>descriptorType</td><td>String</td>
+ * <td>Must be "mbean".</td></tr>
+ * <tr><td>displayName</td><td>String</td>
+ * <td>Name of MBean to be used in displays.</td></tr>
+ * <tr><td>persistPolicy</td><td>String</td>
+ * <td>One of: OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never.
+ * See the section "MBean Descriptor Fields" in the JMX specification
+ * document.</td></tr>
+ * <tr><td>persistLocation</td><td>String</td>
+ * <td>The fully qualified directory name where the MBean should be
+ * persisted (if appropriate).</td></tr>
+ * <tr><td>persistFile</td><td>String</td>
+ * <td>File name into which the MBean should be persisted.</td></tr>
+ * <tr><td>persistPeriod</td><td>Number</td>
+ * <td>Frequency of persist cycle in seconds, for OnTime and
+ * NoMoreOftenThan PersistPolicy</td></tr>
+ * <tr><td>currencyTimeLimit</td><td>Number</td>
+ * <td>How long cached value is valid: <0 never, =0 always,
+ * >0 seconds.</td></tr>
+ * <tr><td>log</td><td>String</td>
+ * <td>t: log all notifications, f: log no notifications.</td></tr>
+ * <tr><td>logfile</td><td>String</td>
+ * <td>Fully qualified filename to log events to.</td></tr>
+ * <tr><td>visibility</td><td>Number</td>
+ * <td>1-4 where 1: always visible 4: rarely visible.</td></tr>
+ * <tr><td>export</td><td>String</td>
+ * <td>Name to be used to export/expose this MBean so that it is
+ * findable by other JMX Agents.</td></tr>
+ * <tr><td>presentationString</td><td>String</td>
+ * <td>XML formatted string to allow presentation of data to be
+ * associated with the MBean.</td></tr>
+ * </table>
+ *
* <P>
* The default descriptor is: name=className,descriptorType="mbean", displayName=className,
- * persistPolicy="never",log="F",export="F",visibility="1"
+ * persistPolicy="never",log="F",visibility="1"
* If the descriptor does not contain all these fields, they will be added with these default values.
*
* <p><b>Note:</b> because of inconsistencies in previous versions of
@@ -207,7 +233,7 @@
* does a complete replacement of the descriptor, no merging is done. If the descriptor to
* set to is null then the default descriptor will be created.
* The default descriptor is: name=className,descriptorType="mbean", displayName=className,
- * persistPolicy="never",log="F",export="F",visibility="1"
+ * persistPolicy="never",log="F",visibility="1"
* If the descriptor does not contain all these fields, they will be added with these default values.
*
* See {@link #getMBeanDescriptor getMBeanDescriptor} method javadoc for description of valid field names.
--- a/jdk/src/share/classes/javax/management/modelmbean/ModelMBeanNotificationInfo.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/src/share/classes/javax/management/modelmbean/ModelMBeanNotificationInfo.java Thu Oct 30 17:46:50 2008 +0100
@@ -46,34 +46,46 @@
import javax.management.RuntimeOperationsException;
/**
- * The ModelMBeanNotificationInfo object describes a notification emitted
+ * <p>The ModelMBeanNotificationInfo object describes a notification emitted
* by a ModelMBean.
* It is a subclass of MBeanNotificationInfo with the addition of an
- * associated Descriptor and an implementation of the Descriptor interface.
- * <P>
- * The fields in the descriptor are defined, but not limited to,
- * the following:
- * <PRE>
- * name : notification name
- * descriptorType : must be "notification"
- * severity : 0-6 where 0: unknown; 1: non-recoverable;
- * 2: critical, failure; 3: major, severe;
- * 4: minor, marginal, error; 5: warning;
- * 6: normal, cleared, informative
- * messageID : unique key for message text (to allow translation,
- * analysis)
- * messageText : text of notification
- * log : T - log message F - do not log message
- * logfile : string fully qualified file name appropriate for
- * operating system
- * visibility : 1-4 where 1: always visible 4: rarely visible
- * presentationString : xml formatted string to allow presentation of data
- * </PRE>
- * The default descriptor contains the name, descriptorType,
+ * associated Descriptor and an implementation of the Descriptor interface.</p>
+ *
+ * <P id="descriptor">
+ * The fields in the descriptor are defined, but not limited to, the following.
+ * Note that when the Type in this table is Number, a String that is the decimal
+ * representation of a Long can also be used.</P>
+ *
+ * <table border="1" cellpadding="5">
+ * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr>
+ * <tr><td>name</td><td>String</td>
+ * <td>Notification name.</td></tr>
+ * <tr><td>descriptorType</td><td>String</td>
+ * <td>Must be "notification".</td></tr>
+ * <tr><td>severity</td><td>Number</td>
+ * <td>0-6 where 0: unknown; 1: non-recoverable;
+ * 2: critical, failure; 3: major, severe;
+ * 4: minor, marginal, error; 5: warning;
+ * 6: normal, cleared, informative</td></tr>
+ * <tr><td>messageID</td><td>String</td>
+ * <td>Unique key for message text (to allow translation, analysis).</td></tr>
+ * <tr><td>messageText</td><td>String</td>
+ * <td>Text of notification.</td></tr>
+ * <tr><td>log</td><td>String</td>
+ * <td>T - log message, F - do not log message.</td></tr>
+ * <tr><td>logfile</td><td>String</td>
+ * <td>fully qualified file name appropriate for operating system.</td></tr>
+ * <tr><td>visibility</td><td>Number</td>
+ * <td>1-4 where 1: always visible 4: rarely visible.</td></tr>
+ * <tr><td>presentationString</td><td>String</td>
+ * <td>XML formatted string to allow presentation of data.</td></tr>
+ * </table>
+ *
+ * <p>The default descriptor contains the name, descriptorType,
* displayName and severity(=6) fields. The default value of the name
* and displayName fields is the name of the Notification class (as
* specified by the <code>name</code> parameter of the
- * ModelMBeanNotificationInfo constructor).
+ * ModelMBeanNotificationInfo constructor).</p>
*
* <p>The <b>serialVersionUID</b> of this class is <code>-7445681389570207141L</code>.
*
--- a/jdk/src/share/classes/javax/management/modelmbean/ModelMBeanOperationInfo.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/src/share/classes/javax/management/modelmbean/ModelMBeanOperationInfo.java Thu Oct 30 17:46:50 2008 +0100
@@ -49,27 +49,48 @@
import javax.management.RuntimeOperationsException;
/**
- * The ModelMBeanOperationInfo object describes a management operation of the ModelMBean.
- * It is a subclass of MBeanOperationInfo with the addition of an associated Descriptor
- * and an implementation of the DescriptorAccess interface.
- * <P>
- * <PRE>
- * The fields in the descriptor are defined, but not limited to, the following:
- * name : operation name
- * descriptorType : must be "operation"
- * class : class where method is defined (fully qualified)
- * role : must be "operation", "getter", or "setter
- * targetObject : object on which to execute this method
- * targetType : type of object reference for targetObject. Can be:
- * ObjectReference | Handle | EJBHandle | IOR | RMIReference.
- * value : cached value for operation
- * currencyTimeLimit : how long cached value is valid
- * lastUpdatedTimeStamp : when cached value was set
- * visibility : 1-4 where 1: always visible 4: rarely visible
- * presentationString : xml formatted string to describe how to present operation
- * </PRE>
- * The default descriptor will have name, descriptorType, displayName and role fields set.
- * The default value of the name and displayName fields is the operation name.
+ * <p>The ModelMBeanOperationInfo object describes a management operation of
+ * the ModelMBean. It is a subclass of MBeanOperationInfo with the addition
+ * of an associated Descriptor and an implementation of the DescriptorAccess
+ * interface.</p>
+ *
+ * <P id="descriptor">
+ * The fields in the descriptor are defined, but not limited to, the following.
+ * Note that when the Type in this table is Number, a String that is the decimal
+ * representation of a Long can also be used.</P>
+ *
+ * <table border="1" cellpadding="5">
+ * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr>
+ * <tr><td>name</td><td>String</td>
+ * <td>Operation name.</td></tr>
+ * <tr><td>descriptorType</td><td>String</td>
+ * <td>Must be "operation".</td></tr>
+ * <tr><td>class</td><td>String</td>
+ * <td>Class where method is defined (fully qualified).</td></tr>
+ * <tr><td>role</td><td>String</td>
+ * <td>Must be "operation", "getter", or "setter".</td></tr>
+ * <tr><td>targetObject</td><td>Object</td>
+ * <td>Object on which to execute this method.</td></tr>
+ * <tr><td>targetType</td><td>String</td>
+ * <td>type of object reference for targetObject. Can be:
+ * ObjectReference | Handle | EJBHandle | IOR | RMIReference.</td></tr>
+ * <tr><td>value</td><td>Object</td>
+ * <td>Cached value for operation.</td></tr>
+ * <tr><td>displayName</td><td>String</td>
+ * <td>Human readable display name of the operation.</td>
+ * <tr><td>currencyTimeLimit</td><td>Number</td>
+ * <td>How long cached value is valid.</td></tr>
+ * <tr><td>lastUpdatedTimeStamp</td><td>Number</td>
+ * <td>When cached value was set.</td></tr>
+ * <tr><td>visibility</td><td>Number</td>
+ * <td>1-4 where 1: always visible 4: rarely visible.</td></tr>
+ * <tr><td>presentationString</td><td>String</td>
+ * <td>XML formatted string to describe how to present operation</td></tr>
+ * </table>
+ *
+ * <p>The default descriptor will have name, descriptorType, displayName and
+ * role fields set. The default value of the name and displayName fields is
+ * the operation name.</p>
*
* <p><b>Note:</b> because of inconsistencies in previous versions of
* this specification, it is recommended not to use negative or zero
--- a/jdk/test/javax/management/eventService/CustomForwarderTest.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/test/javax/management/eventService/CustomForwarderTest.java Thu Oct 30 17:46:50 2008 +0100
@@ -23,7 +23,7 @@
/*
* @test CustomForwarderTest
- * @bug 5108776
+ * @bug 5108776 6759619
* @summary Test that a custom EventForwarder can be added
* @author Eamonn McManus
*/
@@ -45,6 +45,7 @@
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicLong;
+import javax.management.MBeanNotificationInfo;
import javax.management.MBeanServer;
import javax.management.MBeanServerInvocationHandler;
import javax.management.Notification;
@@ -107,6 +108,14 @@
socket.close();
}
+ void simulateNonFatal() {
+ receiver.nonFatal(new Exception("NonFatal"));
+ }
+
+ void simulateFailed() {
+ receiver.failed(new Error("Failed"));
+ }
+
private class Receiver implements Runnable {
public void run() {
byte[] buf = new byte[1024];
@@ -216,16 +225,26 @@
EventClientDelegateMBean.OBJECT_NAME,
EventClientDelegateMBean.class,
false);
- EventRelay relay = new UdpEventRelay(delegate);
+ UdpEventRelay relay = new UdpEventRelay(delegate);
EventClient client = new EventClient(delegate, relay, null, null, 0L);
final Semaphore lostCountSema = new Semaphore(0);
+ final BlockingQueue<Notification> nonFatalNotifs =
+ new ArrayBlockingQueue<Notification>(1);
+ final BlockingQueue<Notification> failedNotifs =
+ new ArrayBlockingQueue<Notification>(1);
NotificationListener lostListener = new NotificationListener() {
public void handleNotification(Notification notification, Object handback) {
if (notification.getType().equals(EventClient.NOTIFS_LOST)) {
System.out.println("Got lost-notifs notif: count=" +
notification.getUserData());
lostCountSema.release(((Long) notification.getUserData()).intValue());
+ } else if (notification.getType().equals(EventClient.NONFATAL)) {
+ System.out.println("Got nonFatal notif");
+ nonFatalNotifs.add(notification);
+ } else if (notification.getType().equals(EventClient.FAILED)) {
+ System.out.println("Got failed notif");
+ failedNotifs.add(notification);
} else
System.out.println("Mysterious EventClient notif: " + notification);
}
@@ -300,6 +319,35 @@
Thread.sleep(10);
assertEquals("Further lost-notifs", 0, lostCountSema.availablePermits());
+ System.out.println("Testing error notifs");
+ relay.simulateNonFatal();
+ n = nonFatalNotifs.poll(10, TimeUnit.SECONDS);
+ assertEquals("Exception message for non-fatal exception", "NonFatal",
+ ((Throwable) n.getSource()).getMessage());
+ relay.simulateFailed();
+ n = failedNotifs.poll(10, TimeUnit.SECONDS);
+ assertEquals("Exception message for failed exception", "Failed",
+ ((Throwable) n.getSource()).getMessage());
+
+ // 6759619
+ System.out.println("Test EventClient.getEventClientNotificationInfo");
+ MBeanNotificationInfo[] mbnis = client.getEventClientNotificationInfo();
+ final String[] expectedTypes = {
+ EventClient.NOTIFS_LOST, EventClient.NONFATAL, EventClient.FAILED
+ };
+ check:
+ for (String type : expectedTypes) {
+ for (MBeanNotificationInfo mbni : mbnis) {
+ for (String t : mbni.getNotifTypes()) {
+ if (type.equals(t)) {
+ System.out.println("...found " + type);
+ continue check;
+ }
+ }
+ }
+ throw new Exception("TEST FAILED: Did not find notif type " + type);
+ }
+
client.close();
System.out.println("TEST PASSED");
--- a/jdk/test/javax/management/mxbean/TypeNameTest.java Tue Oct 28 18:21:36 2008 +0100
+++ b/jdk/test/javax/management/mxbean/TypeNameTest.java Thu Oct 30 17:46:50 2008 +0100
@@ -23,7 +23,7 @@
/*
* @test
- * @bug 6757225
+ * @bug 6757225 6763051
* @summary Test that type names in MXBeans match their spec.
* @author Eamonn McManus
*/