From b63c2fa8765c1e723ed1b519c00d09168b00174f Mon Sep 17 00:00:00 2001 From: emcmanus Date: Thu, 30 Oct 2008 17:46:50 +0100 Subject: [PATCH] 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 --- .../classes/javax/management/Descriptor.java | 167 +++++++++++++++--- .../classes/javax/management/MBeanInfo.java | 51 +++++- .../classes/javax/management/MBeanServer.java | 10 +- .../management/NotificationListener.java | 11 +- .../javax/management/event/EventClient.java | 27 +-- .../modelmbean/DescriptorSupport.java | 4 +- .../modelmbean/ModelMBeanAttributeInfo.java | 75 +++++--- .../modelmbean/ModelMBeanConstructorInfo.java | 37 ++-- .../management/modelmbean/ModelMBeanInfo.java | 70 +++++--- .../ModelMBeanNotificationInfo.java | 58 +++--- .../modelmbean/ModelMBeanOperationInfo.java | 63 ++++--- .../eventService/CustomForwarderTest.java | 52 +++++- .../javax/management/mxbean/TypeNameTest.java | 2 +- 13 files changed, 467 insertions(+), 160 deletions(-) diff --git a/src/share/classes/javax/management/Descriptor.java b/src/share/classes/javax/management/Descriptor.java index 70c17f2ee..a74fb11cd 100644 --- a/src/share/classes/javax/management/Descriptor.java +++ b/src/share/classes/javax/management/Descriptor.java @@ -101,7 +101,7 @@ import javax.management.openmbean.OpenType; * * NameTypeUsed inMeaning * - * defaultValueObject + * defaultValueObject * MBeanAttributeInfo
MBeanParameterInfo * * 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. * - * immutableInfoString + * immutableInfoString * MBeanInfo * * 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. + * will necessarily change. See also the {@code "jmx.mbean.info.changed"} + * notification. * * infoTimeoutString
LongMBeanInfo * - * 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 + * 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}. + * has the {@code immutableInfo} set to {@code true} or it has {@code "jmx.mbean.info.changed"} in + * its {@link MBeanNotificationInfo} array. * - * interfaceClassName + * interfaceClassName * StringMBeanInfo * * 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. * - * legalValues + * legalValues * {@literal Set}MBeanAttributeInfo
MBeanParameterInfo * * Legal values for an attribute or parameter. See * {@link javax.management.openmbean}. * - * maxValueObject + * maxValueObject * MBeanAttributeInfo
MBeanParameterInfo * * Maximum legal value for an attribute or parameter. See * {@link javax.management.openmbean}. * - * metricTypeString + * metricTypeString * MBeanAttributeInfo
MBeanOperationInfo * * 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. * - * minValueObject + * minValueObject * MBeanAttributeInfo
MBeanParameterInfo * * Minimum legal value for an attribute or parameter. See * {@link javax.management.openmbean}. * - * mxbeanString + * mxbeanString * MBeanInfo * * 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. * - * openType{@link OpenType} + * openType{@link OpenType} * MBeanAttributeInfo
MBeanOperationInfo
MBeanParameterInfo * *

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. * - * originalTypeString + * originalTypeString * MBeanAttributeInfo
MBeanOperationInfo
MBeanParameterInfo * *

The original Java type of this element as it appeared in the @@ -282,11 +286,132 @@ import javax.management.openmbean.OpenType; * * * - *

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 - * - * JMX Specification.

+ *

Some additional fields are defined by Model MBeans. See the + * information for {@code ModelMBeanInfo}, + * {@code ModelMBeanAttributeInfo}, + * {@code ModelMBeanConstructorInfo}, + * {@code ModelMBeanNotificationInfo}, and + * {@code ModelMBeanOperationInfo}, as + * well as the chapter "Model MBeans" of the JMX + * Specification. 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.

+ * + *

Nothing prevents the use of these fields in MBeans that are not Model + * MBeans. The displayName, severity, and visibility fields are of + * interest outside Model MBeans, for example. But only Model MBeans have + * a predefined behavior for these fields.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
NameTypeUsed inMeaning
classStringModelMBeanOperationInfoClass where method is defined (fully qualified).
currencyTimeLimitNumberModelMBeanInfo
ModelMBeanAttributeInfo
ModelMBeanOperationInfo		How long cached value is valid: <0 never, =0 always, + * >0 seconds.
defaultObjectModelMBeanAttributeInfoDefault value for attribute.
descriptorTypeStringAnyType of descriptor, "mbean", "attribute", "constructor", "operation", + * or "notification".
displayNameStringAnyHuman readable name of this item.
exportStringModelMBeanInfoName to be used to export/expose this MBean so that it is + * findable by other JMX Agents.
getMethodStringModelMBeanAttributeInfoName of operation descriptor for get method.
lastUpdatedTimeStampNumberModelMBeanAttributeInfo
ModelMBeanOperationInfo		When value was set.
logStringModelMBeanInfo
ModelMBeanNotificationInfo		t or T: log all notifications, f or F: log no notifications.
logFileStringModelMBeanInfo
ModelMBeanNotificationInfo		Fully qualified filename to log events to.
messageIDStringModelMBeanNotificationInfoUnique key for message text (to allow translation, analysis).
messageTextStringModelMBeanNotificationInfoText of notification.
nameStringAnyName of this item.
persistFileStringModelMBeanInfoFile name into which the MBean should be persisted.
persistLocationStringModelMBeanInfoThe fully qualified directory name where the MBean should be + * persisted (if appropriate).
persistPeriodNumberModelMBeanInfo
ModelMBeanAttributeInfo		Frequency of persist cycle in seconds. Used when persistPolicy is + * "OnTimer" or "NoMoreOftenThan".
persistPolicyStringModelMBeanInfo
ModelMBeanAttributeInfo		One of: OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never. + * See the section "MBean Descriptor Fields" in the JMX specification + * document.
presentationStringStringAnyXML formatted string to allow presentation of data.
protocolMapDescriptorModelMBeanAttributeInfoSee 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.
roleStringModelMBeanConstructorInfo
ModelMBeanOperationInfo		One of "constructor", "operation", "getter", or "setter".
setMethodStringModelMBeanAttributeInfoName of operation descriptor for set method.
severityNumberModelMBeanNotificationInfo0-6 where 0: unknown; 1: non-recoverable; + * 2: critical, failure; 3: major, severe; + * 4: minor, marginal, error; 5: warning; + * 6: normal, cleared, informative
targetObjectObjectModelMBeanOperationInfoObject on which to execute this method.
targetTypeStringModelMBeanOperationInfotype of object reference for targetObject. Can be: + * ObjectReference | Handle | EJBHandle | IOR | RMIReference.
valueObjectModelMBeanAttributeInfo
ModelMBeanOperationInfo		Current (cached) value for attribute or operation.
visibilityNumberAny1-4 where 1: always visible, 4: rarely visible.
* * @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 + *

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 diff --git a/src/share/classes/javax/management/MBeanInfo.java b/src/share/classes/javax/management/MBeanInfo.java index 722e96fed..3561e3cfc 100644 --- a/src/share/classes/javax/management/MBeanInfo.java +++ b/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.

* + *

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 immutableInfo and + * infoTimeout fields in the {@code + * MBeanInfo} {@link Descriptor}.

+ * *

The contents of the MBeanInfo 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; * *

  • {@link #getAttributes()} returns the list of all attributes - * whose existence is deduced from the presence in the MBean interface - * of a getName, isName, or - * setName method that conforms to the conventions + * whose existence is deduced as follows: + * * - *
  • {@link #getOperations()} returns the list of all methods in + *
  • {@link #getOperations()} returns the list of all operations whose + * existence is deduced as follows: + * * - *
  • {@link #getNotifications()} returns an empty array if the MBean - * does not implement the {@link NotificationBroadcaster} interface, - * otherwise the result of calling {@link + *
  • {@link #getNotifications()} returns: + * * *
  • {@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}). * * * *

    The description returned by {@link #getDescription()} and the * descriptions of the contained attributes and operations are determined - * by the corresponding Description annotations if any; + * by the corresponding {@link Description} annotations if any; * otherwise their contents are not specified.

    * *

    The remaining details of the MBeanInfo for a diff --git a/src/share/classes/javax/management/MBeanServer.java b/src/share/classes/javax/management/MBeanServer.java index 90d42d2df..e6d79e5bd 100644 --- a/src/share/classes/javax/management/MBeanServer.java +++ b/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 postRegister * (MBeanRegistration interface) method of the MBean throws a - * RuntimeException, the registerMBean method will + * RuntimeException, the registerMBean method will * throw a RuntimeMBeanException, although the MBean * registration succeeded. In such a case, the MBean will be actually - * registered even though the registerMBean method + * registered even though the registerMBean method * threw an exception. Note that RuntimeMBeanException can * also be thrown by preRegister, in which case the MBean * will not be registered. * @exception RuntimeErrorException If the postRegister * (MBeanRegistration interface) method of the MBean throws an - * Error, the registerMBean method will + * Error, the registerMBean method will * throw a RuntimeErrorException, although the MBean * registration succeeded. In such a case, the MBean will be actually - * registered even though the registerMBean method + * registered even though the registerMBean method * threw an exception. Note that RuntimeErrorException can * also be thrown by preRegister, in which case the MBean * will not be registered. @@ -411,6 +411,8 @@ public interface MBeanServer extends MBeanServerConnection { * is sent as described above.

    * * @throws RuntimeOperationsException {@inheritDoc} + * @throws RuntimeMBeanException {@inheritDoc} + * @throws RuntimeErrorException {@inheritDoc} */ public void unregisterMBean(ObjectName name) throws InstanceNotFoundException, MBeanRegistrationException; diff --git a/src/share/classes/javax/management/NotificationListener.java b/src/share/classes/javax/management/NotificationListener.java index eb29f8bd0..1e7b26c10 100644 --- a/src/share/classes/javax/management/NotificationListener.java +++ b/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 - * 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); } diff --git a/src/share/classes/javax/management/event/EventClient.java b/src/share/classes/javax/management/event/EventClient.java index cfce77b08..96c4017e4 100644 --- a/src/share/classes/javax/management/event/EventClient.java +++ b/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"; /** - *

    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.

    + *

    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.

    * * @see #addEventClientListener */ @@ -577,8 +577,13 @@ public class EventClient implements EventConsumer, NotificationManager { } /** - * Returns the set of listeners that have been added through - * this {@code EventClient} and not subsequently removed. + *

    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.

    * * @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}, - 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(); diff --git a/src/share/classes/javax/management/modelmbean/DescriptorSupport.java b/src/share/classes/javax/management/modelmbean/DescriptorSupport.java index 4e9db9dcd..ee8e3030e 100644 --- a/src/share/classes/javax/management/modelmbean/DescriptorSupport.java +++ b/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. *
  • 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 *
  • severity fieldName, if defined, is null, or not a Numeric - * String or not a Numeric Value >= 0 and <= 6
    + * String or not a Numeric Value >= 0 and <= 6
    *
  • persistPolicy fieldName, if defined, is null, or not one of * the following strings:
    * "OnUpdate", "OnTimer", "NoMoreOftenThan", "OnUnregister", "Always", diff --git a/src/share/classes/javax/management/modelmbean/ModelMBeanAttributeInfo.java b/src/share/classes/javax/management/modelmbean/ModelMBeanAttributeInfo.java index cc2ec0b7a..9ee9a6b46 100644 --- a/src/share/classes/javax/management/modelmbean/ModelMBeanAttributeInfo.java +++ b/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. + *

    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. - *

    - * The fields in the descriptor are defined, but not limited to, the following:

    - * 

    - * 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
- *
    - * 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.

    + * + *

    + * 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.

    + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
    NameTypeMeaning
    nameStringAttribute name.
    descriptorTypeStringMust be "attribute".
    valueObjectCurrent (cached) value for attribute.
    defaultObjectDefault value for attribute.
    displayNameStringName of attribute to be used in displays.
    getMethodStringName of operation descriptor for get method.
    setMethodStringName of operation descriptor for set method.
    protocolMapDescriptorSee 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.
    persistPolicyStringOne of: OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never. + * See the section "MBean Descriptor Fields" in the JMX specification + * document.
    persistPeriodNumberFrequency of persist cycle in seconds. Used when persistPolicy is + * "OnTimer" or "NoMoreOftenThan".
    currencyTimeLimitNumberHow long value is valid: <0 never, + * =0 always, >0 seconds.
    lastUpdatedTimeStampNumberWhen value was set.
    visibilityNumber1-4 where 1: always visible, 4: rarely visible.
    presentationStringStringXML formatted string to allow presentation of data.
    + * + *

    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.

    * *

    Note: because of inconsistencies in previous versions of * this specification, it is recommended not to use negative or zero diff --git a/src/share/classes/javax/management/modelmbean/ModelMBeanConstructorInfo.java b/src/share/classes/javax/management/modelmbean/ModelMBeanConstructorInfo.java index 89948d5c9..ecf8ecf00 100644 --- a/src/share/classes/javax/management/modelmbean/ModelMBeanConstructorInfo.java +++ b/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. + *

    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. - *

    - * 

    - * The fields in the descriptor are defined, but not limited to, the following: 
    
- * 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
- *
    + * and an implementation of the DescriptorAccess interface.

    + * + *

    + * 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.

    + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
    NameTypeMeaning
    nameStringConstructor name.
    descriptorTypeStringMust be "operation".
    roleStringMust be "constructor".
    displayNameStringHuman readable name of constructor.
    visibilityNumber1-4 where 1: always visible 4: rarely visible.
    presentationStringStringXML formatted string to describe how to present operation
    * *

    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.

    * *

    The default descriptor will have the {@code name}, {@code * descriptorType}, {@code displayName} and {@code role} fields. The diff --git a/src/share/classes/javax/management/modelmbean/ModelMBeanInfo.java b/src/share/classes/javax/management/modelmbean/ModelMBeanInfo.java index 367e616eb..70c0e74f9 100644 --- a/src/share/classes/javax/management/modelmbean/ModelMBeanInfo.java +++ b/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 - * metadata about the MBean and default policies for persistence and caching. - *

    - * The fields in the descriptor are defined, but not limited to, the following: - * 

    -     * 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.
-     *
    + *

    Returns the ModelMBean's descriptor which contains MBean wide + * policies. This descriptor contains metadata about the MBean and default + * policies for persistence and caching.

    + * + *

    + * 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.

    + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
    NameTypeMeaning
    nameStringMBean name.
    descriptorTypeStringMust be "mbean".
    displayNameStringName of MBean to be used in displays.
    persistPolicyStringOne of: OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never. + * See the section "MBean Descriptor Fields" in the JMX specification + * document.
    persistLocationStringThe fully qualified directory name where the MBean should be + * persisted (if appropriate).
    persistFileStringFile name into which the MBean should be persisted.
    persistPeriodNumberFrequency of persist cycle in seconds, for OnTime and + * NoMoreOftenThan PersistPolicy
    currencyTimeLimitNumberHow long cached value is valid: <0 never, =0 always, + * >0 seconds.
    logStringt: log all notifications, f: log no notifications.
    logfileStringFully qualified filename to log events to.
    visibilityNumber1-4 where 1: always visible 4: rarely visible.
    exportStringName to be used to export/expose this MBean so that it is + * findable by other JMX Agents.
    presentationStringStringXML formatted string to allow presentation of data to be + * associated with the MBean.
    + * *

    * 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. * *

    Note: 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. diff --git a/src/share/classes/javax/management/modelmbean/ModelMBeanNotificationInfo.java b/src/share/classes/javax/management/modelmbean/ModelMBeanNotificationInfo.java index 52f1317db..4b637ee08 100644 --- a/src/share/classes/javax/management/modelmbean/ModelMBeanNotificationInfo.java +++ b/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 + *

    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. - *

    - * The fields in the descriptor are defined, but not limited to, - * the following: - * 

    - * 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
- *
    - * The default descriptor contains the name, descriptorType, + * associated Descriptor and an implementation of the Descriptor interface.

    + * + *

    + * 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.

    + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
    NameTypeMeaning
    nameStringNotification name.
    descriptorTypeStringMust be "notification".
    severityNumber0-6 where 0: unknown; 1: non-recoverable; + * 2: critical, failure; 3: major, severe; + * 4: minor, marginal, error; 5: warning; + * 6: normal, cleared, informative
    messageIDStringUnique key for message text (to allow translation, analysis).
    messageTextStringText of notification.
    logStringT - log message, F - do not log message.
    logfileStringfully qualified file name appropriate for operating system.
    visibilityNumber1-4 where 1: always visible 4: rarely visible.
    presentationStringStringXML formatted string to allow presentation of data.
    + * + *

    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 name parameter of the - * ModelMBeanNotificationInfo constructor). + * ModelMBeanNotificationInfo constructor).

    * *

    The serialVersionUID of this class is -7445681389570207141L. * diff --git a/src/share/classes/javax/management/modelmbean/ModelMBeanOperationInfo.java b/src/share/classes/javax/management/modelmbean/ModelMBeanOperationInfo.java index 2ed992240..6ebea4995 100644 --- a/src/share/classes/javax/management/modelmbean/ModelMBeanOperationInfo.java +++ b/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. - * It is a subclass of MBeanOperationInfo with the addition of an associated Descriptor - * and an implementation of the DescriptorAccess interface. - *

    - * 

    - * 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
- *
    - * 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. + *

    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.

    + * + *

    + * 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.

    + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
    NameTypeMeaning
    nameStringOperation name.
    descriptorTypeStringMust be "operation".
    classStringClass where method is defined (fully qualified).
    roleStringMust be "operation", "getter", or "setter".
    targetObjectObjectObject on which to execute this method.
    targetTypeStringtype of object reference for targetObject. Can be: + * ObjectReference | Handle | EJBHandle | IOR | RMIReference.
    valueObjectCached value for operation.
    displayNameStringHuman readable display name of the operation.
    currencyTimeLimitNumberHow long cached value is valid.
    lastUpdatedTimeStampNumberWhen cached value was set.
    visibilityNumber1-4 where 1: always visible 4: rarely visible.
    presentationStringStringXML formatted string to describe how to present operation
    + * + *

    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.

    * *

    Note: because of inconsistencies in previous versions of * this specification, it is recommended not to use negative or zero diff --git a/test/javax/management/eventService/CustomForwarderTest.java b/test/javax/management/eventService/CustomForwarderTest.java index 22238b375..c9c866aae 100644 --- a/test/javax/management/eventService/CustomForwarderTest.java +++ b/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 nonFatalNotifs = + new ArrayBlockingQueue(1); + final BlockingQueue failedNotifs = + new ArrayBlockingQueue(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"); diff --git a/test/javax/management/mxbean/TypeNameTest.java b/test/javax/management/mxbean/TypeNameTest.java index ede7fdc69..b8189691c 100644 --- a/test/javax/management/mxbean/TypeNameTest.java +++ b/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 */ -- GitLab