jdk-sandbox: comparison jdk/src/share/classes/javax/management/MBeanServerConnection.java

equal deleted inserted replaced

-:460e37d40f12
+:acaa49a2768a
 // java import
 import java.io.IOException;
 import java.util.Set;
-import javax.management.event.NotificationManager;
 /**
 * This interface represents a way to talk to an MBean server, whether
 * local or remote.  The {@link MBeanServer} interface, representing a
 * local MBean server, extends this interface.
 *
 *
 * @since 1.5
 */
-public interface MBeanServerConnection extends NotificationManager {
+public interface MBeanServerConnection {
 /**
 * <p>Instantiates and registers an MBean in the MBean server.  The
 * MBean server will use its {@link
 * javax.management.loading.ClassLoaderRepository Default Loader
 * Repository} to load the class of the MBean.  An object name is
 * associated with the MBean.  If the object name given is null, the
-* MBean must provide its own name in one or both of two ways: by implementing the {@link
+* MBean must provide its own name by implementing the {@link
 * javax.management.MBeanRegistration MBeanRegistration} interface
 * and returning the name from the {@link
-* MBeanRegistration#preRegister preRegister} method; or by defining
+* MBeanRegistration#preRegister preRegister} method.</p>
-* an {@code objectNameTemplate} field in its {@link Descriptor},
-* typically using the {@link ObjectNameTemplate &#64;ObjectNameTemplate}
-* annotation.</p>
 *
 * <p>This method is equivalent to {@link
 * #createMBean(String,ObjectName,Object[],String[])
 * createMBean(className, name, (Object[]) null, (String[])
 * null)}.</p>
 /**
 * <p>Instantiates and registers an MBean in the MBean server.  The
 * class loader to be used is identified by its object name. An
 * object name is associated with the MBean. If the object name of
 * the loader is null, the ClassLoader that loaded the MBean
-* server will be used.  If the object name given is null, the
+* server will be used.  If the MBean's object name given is null,
-* MBean must provide its own name in one or both of two ways: by implementing the {@link
+* the MBean must provide its own name by implementing the {@link
 * javax.management.MBeanRegistration MBeanRegistration} interface
 * and returning the name from the {@link
-* MBeanRegistration#preRegister preRegister} method; or by defining
+* MBeanRegistration#preRegister preRegister} method.</p>
-* an {@code objectNameTemplate} field in its {@link Descriptor},
-* typically using the {@link ObjectNameTemplate &#64;ObjectNameTemplate}
-* annotation.</p>
 *
 * <p>This method is equivalent to {@link
 * #createMBean(String,ObjectName,ObjectName,Object[],String[])
 * createMBean(className, name, loaderName, (Object[]) null,
 * (String[]) null)}.</p>
 * Instantiates and registers an MBean in the MBean server.  The
 * MBean server will use its {@link
 * javax.management.loading.ClassLoaderRepository Default Loader
 * Repository} to load the class of the MBean.  An object name is
 * associated with the MBean.  If the object name given is null, the
-* MBean must provide its own name in one or both of two ways: by implementing the {@link
+* MBean must provide its own name by implementing the {@link
 * javax.management.MBeanRegistration MBeanRegistration} interface
 * and returning the name from the {@link
-* MBeanRegistration#preRegister preRegister} method; or by defining
+* MBeanRegistration#preRegister preRegister} method.
-* an {@code objectNameTemplate} field in its {@link Descriptor},
-* typically using the {@link ObjectNameTemplate &#64;ObjectNameTemplate}
-* annotation.</p>
 *
 * @param className The class name of the MBean to be instantiated.
 * @param name The object name of the MBean. May be null.
 * @param params An array containing the parameters of the
 * constructor to be invoked.
 /**
 * <p>Instantiates and registers an MBean in the MBean server.  The
 * class loader to be used is identified by its object name. An
 * object name is associated with the MBean. If the object name of
 * the loader is not specified, the ClassLoader that loaded the
-* MBean server will be used.  If the object name given is null, the
+* MBean server will be used.  If the MBean object name given is
-* MBean must provide its own name in one or both of two ways: by implementing the {@link
+* null, the MBean must provide its own name by implementing the
-* javax.management.MBeanRegistration MBeanRegistration} interface
+* {@link javax.management.MBeanRegistration MBeanRegistration}
-* and returning the name from the {@link
+* interface and returning the name from the {@link
-* MBeanRegistration#preRegister preRegister} method; or by defining
+* MBeanRegistration#preRegister preRegister} method.
-* an {@code objectNameTemplate} field in its {@link Descriptor},
-* typically using the {@link ObjectNameTemplate &#64;ObjectNameTemplate}
-* annotation.</p>
 *
 * @param className The class name of the MBean to be instantiated.
 * @param name The object name of the MBean. May be null.
 * @param params An array containing the parameters of the
 * constructor to be invoked.
 * @param name The object name pattern identifying the MBeans to
 * be retrieved. If null or no domain and key properties are
 * specified, all the MBeans registered will be retrieved.
 * @param query The query expression to be applied for selecting
 * MBeans. If null no query expression will be applied for
-* selecting MBeans.  ObjectName patterns that may be contained in the
+* selecting MBeans.
-* query expression will be
-* <a href="namespace/package-summary.html#NamespaceAndQueries"><!--
-* -->evaluated</a> in the context of the
-* {@link javax.management.namespace namespace}
-* in which the MBeans selected by {@code name} are registered.
-* Thus, in the {@code query} parameter, no ObjectName pattern containing a
-* namespace path can match any of the MBean names selected by {@code name}.
-* See the
-* <a href="namespace/package-summary.html#RejectedNamespacePatterns"><!--
-* -->namespaces documentation</a> for more details.
 *
 * @return A set containing the <CODE>ObjectInstance</CODE>
 * objects for the selected MBeans.  If no MBean satisfies the
 * query an empty list is returned.
 *
 * @exception IOException A communication problem occurred when
 * talking to the MBean server.
-* @exception RuntimeOperationsException Wraps a
-* <CODE>java.lang.IllegalArgumentException</CODE>: The <em>name</em>
-* parameter contains an invalid pattern. See the
-* <a href="namespace/package-summary.html#RejectedNamespacePatterns"><!--
-* -->namespaces documentation</a> for more details.
 */
 public Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query)
 throws IOException;
 /**
 * @param name The object name pattern identifying the MBean names
 * to be retrieved. If null or no domain and key properties are
 * specified, the name of all registered MBeans will be retrieved.
 * @param query The query expression to be applied for selecting
 * MBeans. If null no query expression will be applied for
-* selecting MBeans. ObjectName patterns that may be contained in the
+* selecting MBeans.
-* query expression will be
-* <a href="namespace/package-summary.html#NamespaceAndQueries"><!--
-* -->evaluated</a> in the context of the
-* {@link javax.management.namespace namespace}
-* in which the MBeans slected by {@code name} are registered.
-* Thus, in the {@code query} parameter, no ObjectName pattern containing a
-* namespace path can match any of the MBean names selected by {@code name}.
-* See the
-* <a href="namespace/package-summary.html#RejectedNamespacePatterns"><!--
-* -->namespaces documentation</a> for more details.
 *
 * @return A set containing the ObjectNames for the MBeans
 * selected.  If no MBean satisfies the query, an empty list is
 * returned.
 *
 * @exception IOException A communication problem occurred when
 * talking to the MBean server.
-* @exception RuntimeOperationsException Wraps a
-* <CODE>java.lang.IllegalArgumentException</CODE>: The <em>name</em>
-* parameter contains an invalid pattern. See the
-* <a href="namespace/package-summary.html#RejectedNamespacePatterns"><!--
-* -->namespaces documentation</a> for more details.
 */
 public Set<ObjectName> queryNames(ObjectName name, QueryExp query)
 throws IOException;
 * if (list.size() == attrNames.length)
 *     System.out.println("All attributes were retrieved successfully");
 * else {
 *     {@code List<String>} missing = new {@code ArrayList<String>}(<!--
 * -->{@link java.util.Arrays#asList Arrays.asList}(attrNames));
-*     missing.removeAll(list.toMap().keySet());
+*     for (Attribute a : list.asList())
+*         missing.remove(a.getName());
 *     System.out.println("Did not retrieve: " + missing);
 * }
 * </pre>
 *
 * @param name The object name of the MBean from which the
 * AttributeList outputAttrs = mbeanServerConnection.setAttributes(<!--
 * -->objectName, inputAttrs);
 * if (inputAttrs.size() == outputAttrs.size())
 *     System.out.println("All attributes were set successfully");
 * else {
-*     {@code List<String>} missing = new {@code ArrayList<String>}(<!--
+*     {@code List<String>} missing = new {@code ArrayList<String>}();
-* -->inputAttrs.toMap().keySet());
+*     for (Attribute a : inputAttrs.asList())
-*     missing.removeAll(outputAttrs.toMap().keySet());
+*         missing.add(a.getName());
+*     for (Attribute a : outputAttrs.asList())
+*         missing.remove(a.getName());
 *     System.out.println("Did not set: " + missing);
 * }
 * </pre>
 *
 * @param name The object name of the MBean within which the
 *
 */
 public String[] getDomains()
 throws IOException;
-// doc inherited from NotificationManager
+/**
+* <p>Adds a listener to a registered MBean.
+* Notifications emitted by the MBean will be forwarded to the listener.</p>
+*
+* @param name The name of the MBean on which the listener should
+* be added.
+* @param listener The listener object which will handle the
+* notifications emitted by the registered MBean.
+* @param filter The filter object. If filter is null, no
+* filtering will be performed before handling notifications.
+* @param handback The context to be sent to the listener when a
+* notification is emitted.
+*
+* @exception InstanceNotFoundException The MBean name provided
+* does not match any of the registered MBeans.
+* @exception IOException A communication problem occurred when
+* talking to the MBean server.
+*
+* @see #removeNotificationListener(ObjectName, NotificationListener)
+* @see #removeNotificationListener(ObjectName, NotificationListener,
+* NotificationFilter, Object)
+*/
 public void addNotificationListener(ObjectName name,
 NotificationListener listener,
 NotificationFilter filter,
 Object handback)
 throws InstanceNotFoundException, IOException;
 NotificationFilter filter,
 Object handback)
 throws InstanceNotFoundException, ListenerNotFoundException,
 IOException;
-// doc inherited from NotificationManager
+/**
+* <p>Removes a listener from a registered MBean.</p>
+*
+* <P> If the listener is registered more than once, perhaps with
+* different filters or callbacks, this method will remove all
+* those registrations.
+*
+* @param name The name of the MBean on which the listener should
+* be removed.
+* @param listener The listener to be removed.
+*
+* @exception InstanceNotFoundException The MBean name provided
+* does not match any of the registered MBeans.
+* @exception ListenerNotFoundException The listener is not
+* registered in the MBean.
+* @exception IOException A communication problem occurred when
+* talking to the MBean server.
+*
+* @see #addNotificationListener(ObjectName, NotificationListener,
+* NotificationFilter, Object)
+*/
 public void removeNotificationListener(ObjectName name,
 NotificationListener listener)
 throws InstanceNotFoundException, ListenerNotFoundException,
 IOException;
-// doc inherited from NotificationManager
+/**
+* <p>Removes a listener from a registered MBean.</p>
+*
+* <p>The MBean must have a listener that exactly matches the
+* given <code>listener</code>, <code>filter</code>, and
+* <code>handback</code> parameters.  If there is more than one
+* such listener, only one is removed.</p>
+*
+* <p>The <code>filter</code> and <code>handback</code> parameters
+* may be null if and only if they are null in a listener to be
+* removed.</p>
+*
+* @param name The name of the MBean on which the listener should
+* be removed.
+* @param listener The listener to be removed.
+* @param filter The filter that was specified when the listener
+* was added.
+* @param handback The handback that was specified when the
+* listener was added.
+*
+* @exception InstanceNotFoundException The MBean name provided
+* does not match any of the registered MBeans.
+* @exception ListenerNotFoundException The listener is not
+* registered in the MBean, or it is not registered with the given
+* filter and handback.
+* @exception IOException A communication problem occurred when
+* talking to the MBean server.
+*
+* @see #addNotificationListener(ObjectName, NotificationListener,
+* NotificationFilter, Object)
+*
+*/
 public void removeNotificationListener(ObjectName name,
 NotificationListener listener,
 NotificationFilter filter,
 Object handback)
 throws InstanceNotFoundException, ListenerNotFoundException,
 * <code>className</code>, and the second class is assignable from
 * the first, the result is true.</p>
 *
 * <p>Otherwise, the result is false.</p>
 *
-* <p>If the MBean implements the {@link DynamicWrapperMBean}
-* interface, then in the above rules X is the result of the MBean's {@link
-* DynamicWrapperMBean#getWrappedObject() getWrappedObject()} method and L
-* is the result of its {@link DynamicWrapperMBean#getWrappedClassLoader()
-* getWrappedClassLoader()} method.
-*
 * @param name The <CODE>ObjectName</CODE> of the MBean.
 * @param className The name of the class.
 *
 * @return true if the MBean specified is an instance of the
 * specified class according to the rules above, false otherwise.

changeset 4156	acaa49a2768a
parent 1709	392dd6db361a
child 5506	202f599c92aa