rmiconnection.java

JAVA的一些源码 JAVA2 STANDARD EDITION DEVELOPMENT KIT 5.0

     * ObjectName, NotificationFilter, Object)}.  The
     * <code>NotificationFilter</code> parameter is wrapped in a
     * <code>MarshalledObject</code>.  The <code>Object</code>
     * (handback) parameter is also wrapped in a
     * <code>MarshalledObject</code>.
     *
     * @param name The name of the MBean on which the listener should
     * be added.
     * @param listener The object name of the listener which will
     * handle the notifications emitted by the registered MBean.
     * @param filter The filter object, encapsulated into a
     * <code>MarshalledObject</code>. If filter encapsulated in the
     * <code>MarshalledObject</code> has a null value, no filtering
     * will be performed before handling notifications.
     * @param handback The context to be sent to the listener when a
     * notification is emitted, encapsulated into a
     * <code>MarshalledObject</code>.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @throws InstanceNotFoundException The MBean name of the
     * notification listener or of the notification broadcaster does
     * not match any of the registered MBeans.
     * @throws RuntimeOperationsException Wraps an {@link
     * IllegalArgumentException}.  The MBean named by
     * <code>listener</code> exists but does not implement the {@link
     * NotificationListener} interface, or <code>name</code> or
     * <code>listener</code> is null.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     *
     * @see #removeNotificationListener(ObjectName, ObjectName, Subject)
     * @see #removeNotificationListener(ObjectName, ObjectName,
     * MarshalledObject, MarshalledObject, Subject)
     */
    public void addNotificationListener(ObjectName name,
                                        ObjectName listener,
                                        MarshalledObject filter,
                                        MarshalledObject handback,
					Subject delegationSubject)
	throws InstanceNotFoundException, IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,
     * ObjectName)}.
     *
     * @param name The name of the MBean on which the listener should
     * be removed.
     * @param listener The object name of the listener to be removed.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @throws InstanceNotFoundException The MBean name provided
     * does not match any of the registered MBeans.
     * @throws ListenerNotFoundException The listener is not
     * registered in the MBean.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     * @throws RuntimeOperationsException Wraps an {@link
     * IllegalArgumentException} when <code>name</code> or
     * <code>listener</code> is null.
     *
     * @see #addNotificationListener
     */
    public void removeNotificationListener(ObjectName name,
                                           ObjectName listener,
					   Subject delegationSubject)
	throws
	InstanceNotFoundException,
	ListenerNotFoundException,
	IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,
     * ObjectName, NotificationFilter, Object)}.  The
     * <code>NotificationFilter</code> parameter is wrapped in a
     * <code>MarshalledObject</code>.  The <code>Object</code>
     * parameter is also wrapped in a <code>MarshalledObject</code>.
     *
     * @param name The name of the MBean on which the listener should
     * be removed.
     * @param listener A listener that was previously added to this
     * MBean.
     * @param filter The filter that was specified when the listener
     * was added, encapsulated into a <code>MarshalledObject</code>.
     * @param handback The handback that was specified when the
     * listener was added, encapsulated into a <code>MarshalledObject</code>.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @throws InstanceNotFoundException The MBean name provided
     * does not match any of the registered MBeans.
     * @throws ListenerNotFoundException The listener is not
     * registered in the MBean, or it is not registered with the given
     * filter and handback.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     * @throws RuntimeOperationsException Wraps an {@link
     * IllegalArgumentException} when <code>name</code> or
     * <code>listener</code> is null.
     *
     * @see #addNotificationListener
     */
    public void removeNotificationListener(ObjectName name,
                                           ObjectName listener,
                                           MarshalledObject filter,
                                           MarshalledObject handback,
					   Subject delegationSubject)
	throws
	InstanceNotFoundException,
	ListenerNotFoundException,
	IOException;
   
    // Special Handling of Notifications -------------------------------------

    /**
     * <p>Handles the method {@link
     * javax.management.MBeanServerConnection#addNotificationListener(ObjectName,
     * NotificationListener, NotificationFilter, Object)}.</p>
     *
     * <p>Register for notifications from the given MBeans that match
     * the given filters.  The remote client can subsequently retrieve
     * the notifications using the {@link #fetchNotifications
     * fetchNotifications} method.</p>
     *
     * <p>For each listener, the original
     * <code>NotificationListener</code> and <code>handback</code> are
     * kept on the client side; in order for the client to be able to
     * identify them, the server generates and returns a unique
     * <code>listenerID</code>.  This <code>listenerID</code> is
     * forwarded with the <code>Notifications</code> to the remote
     * client.</p>
     *
     * <p>If any one of the given (name, filter) pairs cannot be
     * registered, then the operation fails with an exception, and no
     * names or filters are registered.</p>
     *
     * @param names the <code>ObjectNames</code> identifying the
     * MBeans emitting the Notifications.
     * @param filters an array of marshalled representations of the
     * <code>NotificationFilters</code>.  Elements of this array can
     * be null.
     * @param delegationSubjects the <code>Subjects</code> on behalf
     * of which the listeners are being added.  Elements of this array
     * can be null.  Also, the <code>delegationSubjects</code>
     * parameter itself can be null, which is equivalent to an array
     * of null values with the same size as the <code>names</code> and
     * <code>filters</code> arrays.
     *
     * @return an array of <code>listenerIDs</code> identifying the
     * local listeners.  This array has the same number of elements as
     * the parameters.
     *
     * @throws IllegalArgumentException if <code>names</code> or
     * <code>filters</code> is null, or if <code>names</code> contains
     * a null element, or if the three arrays do not all have the same
     * size.
     * @throws ClassCastException if one of the elements of
     * <code>filters</code> unmarshalls as a non-null object that is
     * not a <code>NotificationFilter</code>.
     * @throws InstanceNotFoundException if one of the
     * <code>names</code> does not correspond to any registered MBean.
     * @throws SecurityException if, for one of the MBeans, the
     * client, or the delegated Subject if any, does not have
     * permission to add a listener.
     * @throws IOException if a general communication exception occurred.
     */
    public Integer[] addNotificationListeners(ObjectName[] names,
					      MarshalledObject[] filters,
					      Subject[] delegationSubjects)
	throws InstanceNotFoundException, IOException;

    /**
     * <p>Handles the
     * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener)
     * removeNotificationListener(ObjectName, NotificationListener)} and
     * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener,NotificationFilter,Object)
     * removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)} methods.</p>
     *
     * <p>This method removes one or more
     * <code>NotificationListener</code>s from a given MBean in the
     * MBean server.</p>
     *
     * <p>The <code>NotificationListeners</code> are identified by the
     * IDs which were returned by the {@link
     * #addNotificationListeners(ObjectName[], MarshalledObject[],
     * Subject[])} method.</p>
     *
     * @param name the <code>ObjectName</code> identifying the MBean 
     * emitting the Notifications.
     * @param listenerIDs the list of the IDs corresponding to the
     * listeners to remove.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @throws InstanceNotFoundException if the given
     * <code>name</code> does not correspond to any registered MBean.
     * @throws ListenerNotFoundException if one of the listeners was
     * not found on the server side.  This exception can happen if the
     * MBean discarded a listener for some reason other than a call to
     * <code>MBeanServer.removeNotificationListener</code>.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to remove the listeners.
     * @throws IOException if a general communication exception occurred.
     * @throws IllegalArgumentException if <code>ObjectName</code> or
     * <code>listenerIds</code> is null or if <code>listenerIds</code>
     * contains a null element.
     */
    public void removeNotificationListeners(ObjectName name,
					    Integer[] listenerIDs,
					    Subject delegationSubject)
	throws
	InstanceNotFoundException,
	ListenerNotFoundException,
	IOException;

    /**
     * <p>Retrieves notifications from the connector server.  This
     * method can block until there is at least one notification or
     * until the specified timeout is reached.  The method can also
     * return at any time with zero notifications.</p>
     *
     * <p>A notification can be included in the result if its sequence
     * number is no less than <code>clientSequenceNumber</code> and
     * this client has registered at least one listener for the MBean
     * generating the notification, with a filter that accepts the
     * notification.  Each listener that is interested in the
     * notification is identified by an Integer ID that was returned
     * by {@link #addNotificationListeners(ObjectName[],
     * MarshalledObject[], Subject[])}.</p>
     *
     * @param clientSequenceNumber the first sequence number that the
     * client is interested in.  If negative, it is interpreted as
     * meaning the sequence number that the next notification will
     * have.
     *
     * @param maxNotifications the maximum number of different
     * notifications to return.  The <code>TargetedNotification</code>
     * array in the returned <code>NotificationResult</code> can have
     * more elements than this if the same notification appears more
     * than once.  The behavior is unspecified if this parameter is
     * negative.
     *
     * @param timeout the maximum time in milliseconds to wait for a
     * notification to arrive.  This can be 0 to indicate that the
     * method should not wait if there are no notifications, but
     * should return at once.  It can be <code>Long.MAX_VALUE</code>
     * to indicate that there is no timeout.  The behavior is
     * unspecified if this parameter is negative.
     *
     * @return A <code>NotificationResult</code>.
     *
     * @throws IOException if a general communication exception occurred.
     */
    public NotificationResult fetchNotifications(long clientSequenceNumber,
						 int maxNotifications,
						 long timeout)
	    throws IOException;
}