6319823: new mbean register/unregister notification for groups of mbeans

6779698: Merge error caused duplicate example code in MBeanServerNotification
Reviewed-by: emcmanus

src/share/classes/javax/management/MBeanServerNotification.java

@@ -57,15 +57,55 @@ package javax.management;
  *             what = "Unknown type " + n.getType();
  *         System.out.println("Received MBean Server notification: " + what + ": " +
  *                 mbsn.getMBeanName());
+ *     }
  * };
  *
  * ...
  *     mbeanServer.addNotificationListener(
  *             MBeanServerDelegate.DELEGATE_NAME, printListener, null, null);
  * </pre>
- *
- * <p>The following code prints a message every time an MBean is registered
- * or unregistered in the MBean Server {@code mbeanServer}:</p>
+ * <p id="group">
+ * An MBean which is not an {@link MBeanServerDelegate} may also emit
+ * MBeanServerNotifications. In particular, a custom subclass of the
+ * {@link javax.management.namespace.JMXDomain JMXDomain} MBean or a custom
+ * subclass of the {@link javax.management.namespace.JMXNamespace JMXNamespace}
+ * MBean may emit an MBeanServerNotification for a group of MBeans.<br>
+ * An MBeanServerNotification emitted to denote the registration or
+ * unregistration of a group of MBeans has the following characteristics:
+ * <ul><li>Its {@linkplain Notification#getType() notification type} is
+ *     {@code "JMX.mbean.registered.group"} or
+ *     {@code "JMX.mbean.unregistered.group"}, which can also be written {@link
+ *     MBeanServerNotification#REGISTRATION_NOTIFICATION}{@code + ".group"} or
+ *     {@link
+ *     MBeanServerNotification#UNREGISTRATION_NOTIFICATION}{@code + ".group"}.
+ * </li>
+ * <li>Its {@linkplain #getMBeanName() MBean name} is an ObjectName pattern
+ *     that selects the set (or a superset) of the MBeans being registered
+ *     or unregistered</li>
+ * <li>Its {@linkplain Notification#getUserData() user data} can optionally
+ *     be set to an array of ObjectNames containing the names of all MBeans
+ *     being registered or unregistered.</li>
+ * </ul>
+ * </p>
+ * <p>
+ * MBeans which emit these group registration/unregistration notifications will
+ * declare them in their {@link MBeanInfo#getNotifications()
+ * MBeanNotificationInfo}.
+ * </p>
+ * <P>
+ * To receive a group MBeanServerNotification, you need to register a listener
+ * with the MBean that emits it. For instance, assuming that the {@link
+ * javax.management.namespace.JMXNamespace JMXNamespace} MBean handling
+ * namespace {@code "foo"} has declared that it emits such a notification,
+ * you will need to register your notification listener with that MBean, which
+ * will be named {@link
+ * javax.management.namespace.JMXNamespaces#getNamespaceObjectName(java.lang.String)
+ * foo//:type=JMXNamespace}.
+ * </p>
+ * <p>The following code prints a message every time a group of MBean is
+ * registered or unregistered in the namespace {@code "foo"}, assumimg its
+ * {@link javax.management.namespace.JMXNamespace handler} supports
+ * group MBeanServerNotifications:</p>
  *
  * <pre>
  * private static final NotificationListener printListener = new NotificationListener() {
@@ -76,19 +116,33 @@ package javax.management;
  *         }
  *         MBeanServerNotification mbsn = (MBeanServerNotification) n;
  *         String what;
- *         if (n.getType().equals(MBeanServerNotification.REGISTRATION_NOTIFICATION))
+ *         ObjectName[] names = null;
+ *         if (n.getType().equals(MBeanServerNotification.REGISTRATION_NOTIFICATION)) {
  *             what = "MBean registered";
- *         else if (n.getType().equals(MBeanServerNotification.UNREGISTRATION_NOTIFICATION))
+ *         } else if (n.getType().equals(MBeanServerNotification.UNREGISTRATION_NOTIFICATION)) {
  *             what = "MBean unregistered";
- *         else
+ *         } else if (n.getType().equals(MBeanServerNotification.REGISTRATION_NOTIFICATION+".group")) {
+ *             what = "Group of MBeans registered matching";
+ *             if (mbsn.getUserData() instanceof ObjectName[])
+ *                names =  (ObjectName[]) mbsn.getUserData();
+ *         } else if (n.getType().equals(MBeanServerNotification.UNREGISTRATION_NOTIFICATION+".group")) {
+ *             what = "Group of MBeans unregistered matching";
+ *             if (mbsn.getUserData() instanceof ObjectName[])
+ *                names = (ObjectName[]) mbsn.getUserData();
+ *         } else
  *             what = "Unknown type " + n.getType();
  *         System.out.println("Received MBean Server notification: " + what + ": " +
  *                 mbsn.getMBeanName());
+ *         if (names != null) {
+ *              for (ObjectName mb : names)
+ *                  System.out.println("\t"+mb);
+ *         }
+ *     }
  * };
  *
  * ...
  *     mbeanServer.addNotificationListener(
- *             MBeanServerDelegate.DELEGATE_NAME, printListener, null, null);
+ *             JMXNamespaces.getNamespaceObjectName("foo"), printListener, null, null);
  * </pre>
  *
  * @since 1.5