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

Documentation fixes, plus simple bugfix for 6759619.

Reviewed-by: dfuchs

jdk/src/share/classes/javax/management/Descriptor.java

@@ -101,7 +101,7 @@ import javax.management.openmbean.OpenType;
  *
  * <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 @@ import javax.management.openmbean.OpenType;
  * 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 @@ import javax.management.openmbean.OpenType;
  * 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
+ * <td id="infoTimeout">The time in milli-seconds that the MBeanInfo can
- * expected to be unchanged.  The value can be a {@code Long} or a
+ * reasonably be expected to be unchanged.  The value can be a {@code Long}
- * decimal string.  This provides a hint from a DynamicMBean or any
+ * 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 @@ import javax.management.openmbean.OpenType;
  * 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 @@ import javax.management.openmbean.OpenType;
  * 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 @@ import javax.management.openmbean.OpenType;
  * 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 @@ import javax.management.openmbean.OpenType;
  * 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 @@ import javax.management.openmbean.OpenType;
  *
  * </table>
  *
- * <p>Some additional fields are defined by Model MBeans.  See
+ * <p>Some additional fields are defined by Model MBeans.  See the
- * {@link javax.management.modelmbean.ModelMBeanInfo ModelMBeanInfo}
+ * information for <a href="modelmbean/ModelMBeanInfo.html#descriptor"><!--
- * and related classes and the chapter "Model MBeans" of the
+ * -->{@code ModelMBeanInfo}</a>,
- * <a href="http://java.sun.com/products/JavaManagement/download.html">
+ * <a href="modelmbean/ModelMBeanAttributeInfo.html#descriptor"><!--
- * JMX Specification</a>.</p>
+ * -->{@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: &lt;0 never, =0 always,
+ *         &gt;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 interface Descriptor extends Serializable, Cloneable
     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

jdk/src/share/classes/javax/management/MBeanInfo.java

@@ -45,6 +45,17 @@ import static javax.management.ImmutableDescriptor.nonNullDescriptor;
  * 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 @@ import static javax.management.ImmutableDescriptor.nonNullDescriptor;
  * constructors in that object;
  *
  * <li>{@link #getAttributes()} returns the list of all attributes
- * whose existence is deduced from the presence in the MBean interface
+ * whose existence is deduced as follows:
- * of a <code>get<i>Name</i></code>, <code>is<i>Name</i></code>, or
+ * <ul>
- * <code>set<i>Name</i></code> method that conforms to the conventions
+ * <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 &#64;MBean} or
+ * {@link MXBean &#64;MXBean} annotation on a class, from methods with the
+ * {@link ManagedAttribute &#64;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 &#64;MBean} or
+ * {@link MXBean &#64;MXBean} annotation on a class, from methods with the
+ * {@link ManagedOperation &#64;ManagedOperation} annotation;
+ * </ul>
  *
- * <li>{@link #getNotifications()} returns an empty array if the MBean
+ * <li>{@link #getNotifications()} returns:
- * does not implement the {@link NotificationBroadcaster} interface,
+ * <ul>
- * otherwise the result of calling {@link
+ * <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 &#64;NotificationInfo}
+ * or {@link NotificationInfos &#64;NotificationInfos} annotation on the
+ * MBean interface or <code>&#64;MBean</code> or <code>&#64;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 &#64;DescriptorFields} and
+ * {@link DescriptorKey &#64;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

jdk/src/share/classes/javax/management/MBeanServer.java

@@ -377,19 +377,19 @@ public interface MBeanServer extends MBeanServerConnection {
      * 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 @@ public interface MBeanServer extends MBeanServerConnection {
      * 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;

jdk/src/share/classes/javax/management/NotificationListener.java

@@ -39,11 +39,10 @@ public interface NotificationListener extends java.util.EventListener   {
     * blocking its notification broadcaster.
     *
     * @param notification The notification.
-    * @param handback An opaque object which helps the listener to associate information
+    * @param handback An opaque object which helps the listener to associate
-    * regarding the MBean emitter. This object is passed to the MBean during the
+    * information regarding the MBean emitter. This object is passed to the
-    * addListener call and resent, without modification, to the listener. The MBean object
+    * addNotificationListener call and resent, without modification, to the
-    * should not use or modify the object.
+    * listener.
-    *
     */
-    public void handleNotification(Notification notification, Object handback) ;
+    public void handleNotification(Notification notification, Object handback);
 }

jdk/src/share/classes/javax/management/event/EventClient.java

@@ -117,12 +117,12 @@ public class EventClient implements EventConsumer, NotificationManager {
     public static final String NONFATAL = "jmx.event.service.nonfatal";
 
     /**
-     * <p>A notification string type used by an {@code EventClient} object to
+     * <p>A notification string type used by an {@code EventClient} object
-     * inform a listener added by {@code #addEventClientListener} that it
+     * to inform a listener added by {@link #addEventClientListener
-     * has detected that notifications have been lost.  The {@link
+     * addEventClientListener} that it has detected that notifications have
-     * Notification#getUserData() userData} of the notification is a Long which
+     * been lost.  The {@link Notification#getUserData() userData} of the
-     * is an upper bound on the number of lost notifications that have just
+     * notification is a Long which is an upper bound on the number of lost
-     * been detected.</p>
+     * notifications that have just been detected.</p>
      *
      * @see #addEventClientListener
      */
@@ -577,8 +577,13 @@ public class EventClient implements EventConsumer, NotificationManager {
     }
 
     /**
-     * Returns the set of listeners that have been added through
+     * <p>Returns the collection of listeners that have been added through
-     * this {@code EventClient} and not subsequently removed.
+     * 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 @@ public class EventClient implements EventConsumer, NotificationManager {
     private final static MBeanNotificationInfo[] myInfo =
             new MBeanNotificationInfo[] {
         new MBeanNotificationInfo(
-                new String[] {FAILED, NOTIFS_LOST},
+                new String[] {FAILED, NONFATAL, NOTIFS_LOST},
-                Notification.class.getName(), "")};
+                Notification.class.getName(),
+                "Notifications that can be sent to a listener added with " +
+                "EventClient.addEventClientListener")};
 
     private final NotificationBroadcasterSupport broadcaster =
             new NotificationBroadcasterSupport();

jdk/src/share/classes/javax/management/modelmbean/DescriptorSupport.java

@@ -884,9 +884,9 @@ public class DescriptorSupport
      * 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 &lt;= 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 &lt;= 6<br>
      * <LI> persistPolicy fieldName, if defined, is null, or not one of
      * the following strings:<br>
      *   "OnUpdate", "OnTimer", "NoMoreOftenThan", "OnUnregister", "Always",

jdk/src/share/classes/javax/management/modelmbean/ModelMBeanAttributeInfo.java

@@ -39,7 +39,6 @@ import java.io.ObjectOutputStream;
 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.MBeanAttributeInfo;
 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.
+ * and an implementation of the DescriptorAccess interface.</p>
- * <P>
+ *
- * The fields in the descriptor are defined, but not limited to, the following: <P>
+ * <P id="descriptor">
- * <PRE>
+ * The fields in the descriptor are defined, but not limited to, the following.
- * name           : attribute name
+ * Note that when the Type in this table is Number, a String that is the decimal
- * descriptorType : must be "attribute"
+ * representation of a Long can also be used.</P>
- * value          : current value for attribute
+ *
- * default        : default value for attribute
+ * <table border="1" cellpadding="5">
- * displayName    : name of attribute to be used in displays
+ * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr>
- * getMethod      : name of operation descriptor for get method
+ * <tr><td>name</td><td>String</td>
- * setMethod      : name of operation descriptor for set method
+ *     <td>Attribute name.</td></tr>
- * protocolMap    : object which implements the Descriptor interface: mappings
+ * <tr><td>descriptorType</td><td>String</td>
- *                  must be appropriate for the attribute
+ *     <td>Must be "attribute".</td></tr>
- *                  and entries can be updated or augmented at runtime.
+ * <tr id="value-field"><td>value</td><td>Object</td>
- * persistPolicy  : OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never
+ *     <td>Current (cached) value for attribute.</td></tr>
- * persistPeriod  : seconds - frequency of persist cycle. Used when persistPolicy
+ * <tr><td>default</td><td>Object</td>
- *                  is "OnTimer" or "NoMoreOftenThan".
+ *     <td>Default value for attribute.</td></tr>
- * currencyTimeLimit : how long value is valid, &lt;0 never, =0 always, &gt;0 seconds
+ * <tr><td>displayName</td><td>String</td>
- * lastUpdatedTimeStamp : when value was set
+ *     <td>Name of attribute to be used in displays.</td></tr>
- * visibility     : 1-4 where 1: always visible, 4: rarely visible
+ * <tr><td>getMethod</td><td>String</td>
- * presentationString : xml formatted string to allow presentation of data
+ *     <td>Name of operation descriptor for get method.</td></tr>
- * </PRE>
+ * <tr><td>setMethod</td><td>String</td>
- * The default descriptor contains the name, descriptorType and displayName fields.
+ *     <td>Name of operation descriptor for set method.</td></tr>
- * The default value of the name and displayName fields is the name of the attribute.
+ * <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: &lt;0 never,
+ *         =0 always, &gt;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

jdk/src/share/classes/javax/management/modelmbean/ModelMBeanConstructorInfo.java

@@ -49,22 +49,33 @@ import javax.management.MBeanParameterInfo;
 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.
+ * and an implementation of the DescriptorAccess interface.</p>
- * <P>
+ *
- * <PRE>
+ * <P id="descriptor">
- * The fields in the descriptor are defined, but not limited to, the following: <P>
+ * The fields in the descriptor are defined, but not limited to, the following.
- * name           : constructor name
+ * Note that when the Type in this table is Number, a String that is the decimal
- * descriptorType : must be "operation"
+ * representation of a Long can also be used.</P>
- * role           : must be "constructor"
+ *
- * displayName    : human readable name of constructor
+ * <table border="1" cellpadding="5">
- * visibility            : 1-4 where 1: always visible 4: rarely visible
+ * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr>
- * presentationString :  xml formatted string to describe how to present operation
+ * <tr><td>name</td><td>String</td>
- *</PRE>
+ *     <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

jdk/src/share/classes/javax/management/modelmbean/ModelMBeanInfo.java

@@ -156,29 +156,55 @@ public interface ModelMBeanInfo
 
 
     /**
-     * Returns the ModelMBean's descriptor which contains MBean wide policies.  This descriptor contains
+     * <p>Returns the ModelMBean's descriptor which contains MBean wide
-     * metadata about the MBean and default policies for persistence and caching.
+     * policies.  This descriptor contains metadata about the MBean and default
-     * <P>
+     * policies for persistence and caching.</p>
-     * The fields in the descriptor are defined, but not limited to, the following:
+     *
-     * <PRE>
+     * <P id="descriptor">
-     * name           : MBean name
+     * The fields in the descriptor are defined, but not limited to, the
-     * descriptorType : must be "mbean"
+     * following.  Note that when the Type in this table is Number, a String
-     * displayName    : name of attribute to be used in displays
+     * that is the decimal representation of a Long can also be used.</P>
-     * persistPolicy  : OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never
+     *
-     * persistLocation : The fully qualified directory name where the MBean should be persisted (if appropriate)
+     * <table border="1" cellpadding="5">
-     * persistFile    : File name into which the MBean should be persisted
+     * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr>
-     * persistPeriod  : seconds - frequency of persist cycle for OnTime and NoMoreOftenThan PersistPolicy
+     * <tr><td>name</td><td>String</td>
-     * currencyTimeLimit : how long value is valid, &lt;0 never, =0 always, &gt;0 seconds
+     *     <td>MBean name.</td></tr>
-     * log            : where t: log all notifications f: log no notifications
+     * <tr><td>descriptorType</td><td>String</td>
-     * logfile        : fully qualified filename to log events to
+     *     <td>Must be "mbean".</td></tr>
-     * visibility     : 1-4 where 1: always visible 4: rarely visible
+     * <tr><td>displayName</td><td>String</td>
-     * export         : name to be used to export/expose this MBean so that it is findable by
+     *     <td>Name of MBean to be used in displays.</td></tr>
-     *                  other JMX Agents.
+     * <tr><td>persistPolicy</td><td>String</td>
-     * presentationString : xml formatted string to allow presentation of data to be associated with the MBean.
+     *     <td>One of: OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never.
-     * </PRE>
+     *         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: &lt;0 never, =0 always,
+     *         &gt;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 @@ public interface ModelMBeanInfo
      * 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.

jdk/src/share/classes/javax/management/modelmbean/ModelMBeanNotificationInfo.java

@@ -46,34 +46,46 @@ import javax.management.MBeanNotificationInfo;
 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.
+ * associated Descriptor and an implementation of the Descriptor interface.</p>
- * <P>
+ *
- * The fields in the descriptor are defined, but not limited to,
+ * <P id="descriptor">
- * the following:
+ * The fields in the descriptor are defined, but not limited to, the following.
- * <PRE>
+ * Note that when the Type in this table is Number, a String that is the decimal
- * name           : notification name
+ * representation of a Long can also be used.</P>
- * descriptorType : must be "notification"
+ *
- * severity       : 0-6 where 0: unknown; 1: non-recoverable;
+ * <table border="1" cellpadding="5">
- *                  2: critical, failure; 3: major, severe;
+ * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr>
- *                  4: minor, marginal, error; 5: warning;
+ * <tr><td>name</td><td>String</td>
- *                  6: normal, cleared, informative
+ *     <td>Notification name.</td></tr>
- * messageID      : unique key for message text (to allow translation,
+ * <tr><td>descriptorType</td><td>String</td>
- *                  analysis)
+ *     <td>Must be "notification".</td></tr>
- * messageText    : text of notification
+ * <tr><td>severity</td><td>Number</td>
- * log            : T - log message F - do not log message
+ *     <td>0-6 where 0: unknown; 1: non-recoverable;
- * logfile        : string fully qualified file name appropriate for
+ *         2: critical, failure; 3: major, severe;
- *                  operating system
+ *         4: minor, marginal, error; 5: warning;
- * visibility     : 1-4 where 1: always visible 4: rarely visible
+ *         6: normal, cleared, informative</td></tr>
- * presentationString : xml formatted string to allow presentation of data
+ * <tr><td>messageID</td><td>String</td>
- * </PRE>
+ *     <td>Unique key for message text (to allow translation, analysis).</td></tr>
- * The default descriptor contains the name, descriptorType,
+ * <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>.
  *

jdk/src/share/classes/javax/management/modelmbean/ModelMBeanOperationInfo.java

@@ -49,27 +49,48 @@ import javax.management.MBeanParameterInfo;
 import javax.management.RuntimeOperationsException;
 
 /**
- * The ModelMBeanOperationInfo object describes a management operation of the ModelMBean.
+ * <p>The ModelMBeanOperationInfo object describes a management operation of
- * It is a subclass of MBeanOperationInfo with the addition of an associated Descriptor
+ * the ModelMBean.  It is a subclass of MBeanOperationInfo with the addition
- * and an implementation of the DescriptorAccess interface.
+ * of an associated Descriptor and an implementation of the DescriptorAccess
- * <P>
+ * interface.</p>
- * <PRE>
+ *
- * The fields in the descriptor are defined, but not limited to, the following:
+ * <P id="descriptor">
- * name           : operation name
+ * The fields in the descriptor are defined, but not limited to, the following.
- * descriptorType : must be "operation"
+ * Note that when the Type in this table is Number, a String that is the decimal
- * class          : class where method is defined (fully qualified)
+ * representation of a Long can also be used.</P>
- * role           : must be "operation", "getter", or "setter
+ *
- * targetObject   : object on which to execute this method
+ * <table border="1" cellpadding="5">
- * targetType     : type of object reference for targetObject. Can be:
+ * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr>
- *                  ObjectReference | Handle | EJBHandle | IOR | RMIReference.
+ * <tr><td>name</td><td>String</td>
- * value          : cached value for operation
+ *     <td>Operation name.</td></tr>
- * currencyTimeLimit : how long cached value is valid
+ * <tr><td>descriptorType</td><td>String</td>
- * lastUpdatedTimeStamp : when cached value was set
+ *     <td>Must be "operation".</td></tr>
- * visibility            : 1-4 where 1: always visible 4: rarely visible
+ * <tr><td>class</td><td>String</td>
- * presentationString :  xml formatted string to describe how to present operation
+ *     <td>Class where method is defined (fully qualified).</td></tr>
- * </PRE>
+ * <tr><td>role</td><td>String</td>
- * The default descriptor will have name, descriptorType, displayName and role fields set.
+ *     <td>Must be "operation", "getter", or "setter".</td></tr>
- * The default value of the name and displayName fields is the operation name.
+ * <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

jdk/test/javax/management/eventService/CustomForwarderTest.java

@@ -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.TimeUnit;
 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 @@ public class CustomForwarderTest {
             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 @@ public class CustomForwarderTest {
                 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 @@ public class CustomForwarderTest {
         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");

jdk/test/javax/management/mxbean/TypeNameTest.java

@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug 6757225
+ * @bug 6757225 6763051
  * @summary Test that type names in MXBeans match their spec.
  * @author Eamonn McManus
  */