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 }