jdk/src/share/classes/javax/management/event/EventClientDelegateMBean.java
changeset 1004 5ba8217eb504
child 1225 6ef6227d36eb
equal deleted inserted replaced
1003:b2f6b7e00c29 1004:5ba8217eb504
       
     1 /*
       
     2  * Copyright 2007 Sun Microsystems, Inc.  All Rights Reserved.
       
     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
       
     4  *
       
     5  * This code is free software; you can redistribute it and/or modify it
       
     6  * under the terms of the GNU General Public License version 2 only, as
       
     7  * published by the Free Software Foundation.  Sun designates this
       
     8  * particular file as subject to the "Classpath" exception as provided
       
     9  * by Sun in the LICENSE file that accompanied this code.
       
    10  *
       
    11  * This code is distributed in the hope that it will be useful, but WITHOUT
       
    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
       
    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
       
    14  * version 2 for more details (a copy is included in the LICENSE file that
       
    15  * accompanied this code).
       
    16  *
       
    17  * You should have received a copy of the GNU General Public License version
       
    18  * 2 along with this work; if not, write to the Free Software Foundation,
       
    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
       
    20  *
       
    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
       
    22  * CA 95054 USA or visit www.sun.com if you need additional information or
       
    23  * have any questions.
       
    24  */
       
    25 
       
    26 package javax.management.event;
       
    27 
       
    28 import com.sun.jmx.mbeanserver.Util;
       
    29 import java.io.IOException;
       
    30 import javax.management.InstanceNotFoundException;
       
    31 import javax.management.ListenerNotFoundException;
       
    32 import javax.management.MBeanException;
       
    33 import javax.management.NotificationFilter;
       
    34 import javax.management.ObjectName;
       
    35 import javax.management.remote.NotificationResult;
       
    36 
       
    37 /**
       
    38  * <p>This interface specifies necessary methods on the MBean server
       
    39  * side for a JMX remote client to manage its notification listeners as
       
    40  * if they are local.
       
    41  * Users do not usually work directly with this MBean; instead, the {@link
       
    42  * EventClient} class is designed to be used directly by the user.</p>
       
    43  *
       
    44  * <p>A default implementation of this interface can be added to an MBean
       
    45  * Server in one of several ways.</p>
       
    46  *
       
    47  * <ul>
       
    48  * <li><p>The most usual is to insert an {@link
       
    49  * javax.management.remote.MBeanServerForwarder MBeanServerForwarder} between
       
    50  * the {@linkplain javax.management.remote.JMXConnectorServer Connector Server}
       
    51  * and the MBean Server, that will intercept accesses to the Event Client
       
    52  * Delegate MBean and treat them as the real MBean would. This forwarder is
       
    53  * inserted by default with the standard RMI Connector Server, and can also
       
    54  * be created explicitly using {@link EventClientDelegate#newForwarder()}.
       
    55  *
       
    56  * <li><p>A variant on the above is to replace the MBean Server that is
       
    57  * used locally with a forwarder as described above.  Since
       
    58  * {@code MBeanServerForwarder} extends {@code MBeanServer}, you can use
       
    59  * a forwarder anywhere you would have used the original MBean Server.  The
       
    60  * code to do this replacement typically looks something like this:</p>
       
    61  *
       
    62  * <pre>
       
    63  * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();  // or whatever
       
    64  * MBeanServerForwarder mbsf = EventClientDelegate.newForwarder();
       
    65  * mbsf.setMBeanServer(mbs);
       
    66  * mbs = mbsf;
       
    67  * // now use mbs just as you did before, but it will have an EventClientDelegate
       
    68  * </pre>
       
    69  *
       
    70  * <li><p>The final way is to create an instance of {@link EventClientDelegate}
       
    71  * and register it in the MBean Server under the standard {@linkplain
       
    72  * #OBJECT_NAME name}:</p>
       
    73  *
       
    74  * <pre>
       
    75  * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();  // or whatever
       
    76  * EventClientDelegate ecd = EventClientDelegate.getEventClientDelegate(mbs);
       
    77  * mbs.registerMBean(ecd, EventClientDelegateMBean.OBJECT_NAME);
       
    78  * <pre>
       
    79  * </ul>
       
    80  *
       
    81  * @since JMX 2.0
       
    82  */
       
    83 public interface EventClientDelegateMBean {
       
    84     /**
       
    85      * The string representation of {@link #OBJECT_NAME}.
       
    86      */
       
    87     // This shouldn't really be necessary but an apparent javadoc bug
       
    88     // meant that the {@value} tags didn't work if this was a
       
    89     // field in EventClientDelegate, even a public field.
       
    90     public static final String OBJECT_NAME_STRING =
       
    91             "javax.management.event:type=EventClientDelegate";
       
    92 
       
    93     /**
       
    94      * The standard <code>ObjectName</code> used to register the default
       
    95      * <code>EventClientDelegateMBean</code>.  The name is
       
    96      * <code>{@value #OBJECT_NAME_STRING}</code>.
       
    97      */
       
    98     public final static ObjectName OBJECT_NAME =
       
    99             Util.newObjectName(OBJECT_NAME_STRING);
       
   100 
       
   101     /**
       
   102      * A unique listener identifier specified for an EventClient.
       
   103      * Any notification associated with this id is intended for
       
   104      * the EventClient which receives the notification, rather than
       
   105      * a listener added using that EventClient.
       
   106      */
       
   107     public static final int EVENT_CLIENT_LISTENER_ID = -100;
       
   108 
       
   109     /**
       
   110      * Adds a new client to the <code>EventClientDelegateMBean</code> with
       
   111      * a user-specified
       
   112      * {@link EventForwarder} to forward notifications to the client. The
       
   113      * <code>EventForwarder</code> is created by calling
       
   114      * {@link javax.management.MBeanServer#instantiate(String, Object[],
       
   115      * String[])}.
       
   116      *
       
   117      * @param className The class name used to create an
       
   118      * {@code EventForwarder}.
       
   119      * @param params An array containing the parameters of the constructor to
       
   120      * be invoked.
       
   121      * @param sig An array containing the signature of the constructor to be
       
   122      * invoked
       
   123      * @return A client identifier.
       
   124      * @exception IOException Reserved for a remote call to throw on the client
       
   125      * side.
       
   126      * @exception MBeanException An exception thrown when creating the user
       
   127      * specified <code>EventForwarder</code>.
       
   128      */
       
   129     public String addClient(String className, Object[] params, String[] sig)
       
   130     throws IOException, MBeanException;
       
   131 
       
   132     /**
       
   133      * Adds a new client to the <code>EventClientDelegateMBean</code> with
       
   134      * a user-specified
       
   135      * {@link EventForwarder} to forward notifications to the client. The
       
   136      * <code>EventForwarder</code> is created by calling
       
   137      * {@link javax.management.MBeanServer#instantiate(String, ObjectName,
       
   138      * Object[], String[])}. A user-specified class loader is used to create
       
   139      * this <code>EventForwarder</code>.
       
   140      *
       
   141      * @param className The class name used to create an
       
   142      * {@code EventForwarder}.
       
   143      * @param classLoader An ObjectName registered as a
       
   144      *        <code>ClassLoader</code> MBean.
       
   145      * @param params An array containing the parameters of the constructor to
       
   146      * be invoked.
       
   147      * @param sig An array containing the signature of the constructor to be
       
   148      * invoked
       
   149      * @return A client identifier.
       
   150      * @exception IOException Reserved for a remote call to throw on the client
       
   151      * side.
       
   152      * @exception MBeanException An exception thrown when creating the user
       
   153      * specified <code>EventForwarder</code>.
       
   154      */
       
   155     public String addClient(String className,
       
   156             ObjectName classLoader,
       
   157             Object[] params,
       
   158             String[] sig) throws IOException, MBeanException;
       
   159 
       
   160     /**
       
   161      * Removes an added client. Calling this method will remove all listeners
       
   162      * added with the client.
       
   163      *
       
   164      * @exception EventClientNotFoundException If the {@code clientId} is
       
   165      * not found.
       
   166      * @exception IOException Reserved for a remote call to throw on the client
       
   167      * side.
       
   168      */
       
   169     public void removeClient(String clientID)
       
   170     throws EventClientNotFoundException, IOException;
       
   171 
       
   172     /**
       
   173      * Returns the identifiers of listeners added or subscribed to with the
       
   174      * specified client identifier.
       
   175      * <P> If no listener is currently registered with the client, an empty
       
   176      * array is returned.
       
   177      * @param clientID The client identifier with which the listeners are
       
   178      * added or subscribed to.
       
   179      * @return An array of listener identifiers.
       
   180      * @exception EventClientNotFoundException If the {@code clientId} is
       
   181      * not found.
       
   182      * @exception IOException Reserved for a remote call to throw on the client
       
   183      * side.
       
   184      */
       
   185     public Integer[] getListenerIds(String clientID)
       
   186     throws EventClientNotFoundException, IOException;
       
   187 
       
   188     /**
       
   189      * Adds a listener to receive notifications from an MBean and returns
       
   190      * a non-negative integer as the identifier of the listener.
       
   191      * <P>This method is called by an {@link EventClient} to implement the
       
   192      * method  {@link EventClient#addNotificationListener(ObjectName,
       
   193      * NotificationListener, NotificationFilter, Object)}.
       
   194      *
       
   195      * @param name The name of the MBean onto which the listener should be added.
       
   196      * @param filter The filter object. If  {@code filter} is null,
       
   197      *        no filtering will be performed before handling notifications.
       
   198      * @param clientId The client identifier with which the listener is added.
       
   199      * @return A listener identifier.
       
   200      * @throws EventClientNotFoundException Thrown if the {@code clientId} is
       
   201      * not found.
       
   202      * @throws InstanceNotFoundException Thrown if the MBean is not found.
       
   203      * @throws IOException Reserved for a remote call to throw on the client
       
   204      * side.
       
   205      */
       
   206     public Integer addListener(String clientId,
       
   207             ObjectName name,
       
   208             NotificationFilter filter)
       
   209             throws InstanceNotFoundException, EventClientNotFoundException,
       
   210             IOException;
       
   211 
       
   212 
       
   213     /**
       
   214      * <p>Subscribes a listener to receive notifications from an MBean or a
       
   215      * set of MBeans represented by an {@code ObjectName} pattern.  (It is
       
   216      * not an error if no MBeans match the pattern at the time this method is
       
   217      * called.)</p>
       
   218      *
       
   219      * <p>Returns a non-negative integer as the identifier of the listener.</p>
       
   220      *
       
   221      * <p>This method is called by an {@link EventClient} to execute its
       
   222      * method {@link EventClient#subscribe(ObjectName, NotificationListener,
       
   223      * NotificationFilter, Object)}.</p>
       
   224      *
       
   225      * @param clientId The remote client's identifier.
       
   226      * @param name The name of an MBean or an {@code ObjectName} pattern
       
   227      * representing a set of MBeans to which the listener should listen.
       
   228      * @param filter The filter object. If {@code filter} is null, no
       
   229      * filtering will be performed before notifications are handled.
       
   230      *
       
   231      * @return A listener identifier.
       
   232      *
       
   233      * @throws IllegalArgumentException If the {@code name} or
       
   234      * {@code listener} is null.
       
   235      * @throws EventClientNotFoundException If the client ID is not found.
       
   236      * @throws IOException Reserved for a remote client to throw if
       
   237      * an I/O error occurs.
       
   238      *
       
   239      * @see EventConsumer#subscribe(ObjectName, NotificationListener,
       
   240      * NotificationFilter,Object)
       
   241      * @see #removeListenerOrSubscriber(String, Integer)
       
   242      */
       
   243     public Integer addSubscriber(String clientId, ObjectName name,
       
   244             NotificationFilter filter)
       
   245             throws EventClientNotFoundException, IOException;
       
   246 
       
   247     /**
       
   248      * Removes a listener, to stop receiving notifications.
       
   249      * <P> This method is called by an {@link EventClient} to execute its
       
   250      * methods {@link EventClient#removeNotificationListener(ObjectName,
       
   251      * NotificationListener, NotificationFilter, Object)},
       
   252      * {@link EventClient#removeNotificationListener(ObjectName,
       
   253      * NotificationListener)}, and {@link EventClient#unsubscribe}.
       
   254      *
       
   255      * @param clientId The client identifier with which the listener was added.
       
   256      * @param listenerId The listener identifier to be removed. This must be
       
   257      * an identifier returned by a previous {@link #addListener addListener}
       
   258      * or {@link #addSubscriber addSubscriber} call.
       
   259      *
       
   260      * @throws InstanceNotFoundException if the MBean on which the listener
       
   261      * was added no longer exists.
       
   262      * @throws ListenerNotFoundException if there is no listener with the
       
   263      * given {@code listenerId}.
       
   264      * @throws EventClientNotFoundException if the {@code clientId} is
       
   265      * not found.
       
   266      * @throws IOException Reserved for a remote call to throw on the client
       
   267      * side.
       
   268      */
       
   269     public void removeListenerOrSubscriber(String clientId, Integer listenerId)
       
   270     throws InstanceNotFoundException, ListenerNotFoundException,
       
   271             EventClientNotFoundException, IOException;
       
   272 
       
   273     /**
       
   274      * Called by a client to fetch notifications that are to be sent to its
       
   275      * listeners.
       
   276      *
       
   277      * @param clientId The client's identifier.
       
   278      * @param startSequenceNumber The first sequence number to
       
   279      * consider.
       
   280      * @param timeout The maximum waiting time.
       
   281      * @param maxNotifs The maximum number of notifications to return.
       
   282      *
       
   283      * @throws EventClientNotFoundException Thrown if the {@code clientId} is
       
   284      * not found.
       
   285      * @throws IllegalArgumentException if the client was {@linkplain
       
   286      * #addClient(String, Object[], String[]) added} with an {@link
       
   287      * EventForwarder} that is not a {@link FetchingEventForwarder}.
       
   288      * @throws IOException Reserved for a remote call to throw on the client
       
   289      * side.
       
   290      */
       
   291     public NotificationResult fetchNotifications(String clientId,
       
   292             long startSequenceNumber,
       
   293             int maxNotifs,
       
   294             long timeout)
       
   295             throws EventClientNotFoundException, IOException;
       
   296 
       
   297     /**
       
   298      * An {@code EventClient} calls this method to keep its {@code clientId}
       
   299      * alive in this MBean. The client will be removed if the lease times out.
       
   300      *
       
   301      * @param clientId The client's identifier.
       
   302      * @param timeout The time in milliseconds by which the lease is to be
       
   303      * extended.  The value zero has no special meaning, so it will cause the
       
   304      * lease to time out immediately.
       
   305      *
       
   306      * @return The new lifetime of the lease in milliseconds.  This may be
       
   307      * different from the requested time.
       
   308      *
       
   309      * @throws EventClientNotFoundException if the {@code clientId} is
       
   310      * not found.
       
   311      * @throws IOException reserved for a remote call to throw on the client
       
   312      * side.
       
   313      * @throws IllegalArgumentException if {@code clientId} is null or
       
   314      * {@code timeout} is negative.
       
   315      */
       
   316     public long lease(String clientId, long timeout)
       
   317     throws IOException, EventClientNotFoundException;
       
   318 }