| /* |
| * Copyright 2007-2008 Sun Microsystems, Inc. All Rights Reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Sun designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Sun in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| * CA 95054 USA or visit www.sun.com if you need additional information or |
| * have any questions. |
| */ |
| |
| package javax.management.event; |
| |
| import com.sun.jmx.mbeanserver.Util; |
| import java.io.IOException; |
| import javax.management.InstanceNotFoundException; |
| import javax.management.ListenerNotFoundException; |
| import javax.management.MBeanException; |
| import javax.management.NotificationFilter; |
| import javax.management.ObjectName; |
| import javax.management.remote.NotificationResult; |
| |
| /** |
| * <p>This interface specifies necessary methods on the MBean server |
| * side for a JMX remote client to manage its notification listeners as |
| * if they are local. |
| * Users do not usually work directly with this MBean; instead, the {@link |
| * EventClient} class is designed to be used directly by the user.</p> |
| * |
| * <p>A default implementation of this interface can be added to an MBean |
| * Server in one of several ways.</p> |
| * |
| * <ul> |
| * <li><p>The most usual is to insert an {@link |
| * javax.management.remote.MBeanServerForwarder MBeanServerForwarder} between |
| * the {@linkplain javax.management.remote.JMXConnectorServer Connector Server} |
| * and the MBean Server, that will intercept accesses to the Event Client |
| * Delegate MBean and treat them as the real MBean would. This forwarder is |
| * inserted by default with the standard RMI Connector Server, and can also |
| * be created explicitly using {@link EventClientDelegate#newForwarder()}. |
| * |
| * <li><p>A variant on the above is to replace the MBean Server that is |
| * used locally with a forwarder as described above. Since |
| * {@code MBeanServerForwarder} extends {@code MBeanServer}, you can use |
| * a forwarder anywhere you would have used the original MBean Server. The |
| * code to do this replacement typically looks something like this:</p> |
| * |
| * <pre> |
| * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); // or whatever |
| * MBeanServerForwarder mbsf = EventClientDelegate.newForwarder(); |
| * mbsf.setMBeanServer(mbs); |
| * mbs = mbsf; |
| * // now use mbs just as you did before, but it will have an EventClientDelegate |
| * </pre> |
| * |
| * <li><p>The final way is to create an instance of {@link EventClientDelegate} |
| * and register it in the MBean Server under the standard {@linkplain |
| * #OBJECT_NAME name}:</p> |
| * |
| * <pre> |
| * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); // or whatever |
| * EventClientDelegate ecd = EventClientDelegate.getEventClientDelegate(mbs); |
| * mbs.registerMBean(ecd, EventClientDelegateMBean.OBJECT_NAME); |
| * <pre> |
| * </ul> |
| * |
| * @since JMX 2.0 |
| */ |
| public interface EventClientDelegateMBean { |
| /** |
| * The string representation of {@link #OBJECT_NAME}. |
| */ |
| // This shouldn't really be necessary but an apparent javadoc bug |
| // meant that the {@value} tags didn't work if this was a |
| // field in EventClientDelegate, even a public field. |
| public static final String OBJECT_NAME_STRING = |
| "javax.management.event:type=EventClientDelegate"; |
| |
| /** |
| * The standard <code>ObjectName</code> used to register the default |
| * <code>EventClientDelegateMBean</code>. The name is |
| * <code>{@value #OBJECT_NAME_STRING}</code>. |
| */ |
| public final static ObjectName OBJECT_NAME = |
| ObjectName.valueOf(OBJECT_NAME_STRING); |
| |
| /** |
| * A unique listener identifier specified for an EventClient. |
| * Any notification associated with this id is intended for |
| * the EventClient which receives the notification, rather than |
| * a listener added using that EventClient. |
| */ |
| public static final int EVENT_CLIENT_LISTENER_ID = -100; |
| |
| /** |
| * Adds a new client to the <code>EventClientDelegateMBean</code> with |
| * a user-specified |
| * {@link EventForwarder} to forward notifications to the client. The |
| * <code>EventForwarder</code> is created by calling |
| * {@link javax.management.MBeanServer#instantiate(String, Object[], |
| * String[])}. |
| * |
| * @param className The class name used to create an |
| * {@code EventForwarder}. |
| * @param params An array containing the parameters of the constructor to |
| * be invoked. |
| * @param sig An array containing the signature of the constructor to be |
| * invoked |
| * @return A client identifier. |
| * @exception IOException Reserved for a remote call to throw on the client |
| * side. |
| * @exception MBeanException An exception thrown when creating the user |
| * specified <code>EventForwarder</code>. |
| */ |
| public String addClient(String className, Object[] params, String[] sig) |
| throws IOException, MBeanException; |
| |
| /** |
| * Adds a new client to the <code>EventClientDelegateMBean</code> with |
| * a user-specified |
| * {@link EventForwarder} to forward notifications to the client. The |
| * <code>EventForwarder</code> is created by calling |
| * {@link javax.management.MBeanServer#instantiate(String, ObjectName, |
| * Object[], String[])}. A user-specified class loader is used to create |
| * this <code>EventForwarder</code>. |
| * |
| * @param className The class name used to create an |
| * {@code EventForwarder}. |
| * @param classLoader An ObjectName registered as a |
| * <code>ClassLoader</code> MBean. |
| * @param params An array containing the parameters of the constructor to |
| * be invoked. |
| * @param sig An array containing the signature of the constructor to be |
| * invoked |
| * @return A client identifier. |
| * @exception IOException Reserved for a remote call to throw on the client |
| * side. |
| * @exception MBeanException An exception thrown when creating the user |
| * specified <code>EventForwarder</code>. |
| */ |
| public String addClient(String className, |
| ObjectName classLoader, |
| Object[] params, |
| String[] sig) throws IOException, MBeanException; |
| |
| /** |
| * Removes an added client. Calling this method will remove all listeners |
| * added with the client. |
| * |
| * @exception EventClientNotFoundException If the {@code clientId} is |
| * not found. |
| * @exception IOException Reserved for a remote call to throw on the client |
| * side. |
| */ |
| public void removeClient(String clientID) |
| throws EventClientNotFoundException, IOException; |
| |
| /** |
| * Returns the identifiers of listeners added or subscribed to with the |
| * specified client identifier. |
| * <P> If no listener is currently registered with the client, an empty |
| * array is returned. |
| * @param clientID The client identifier with which the listeners are |
| * added or subscribed to. |
| * @return An array of listener identifiers. |
| * @exception EventClientNotFoundException If the {@code clientId} is |
| * not found. |
| * @exception IOException Reserved for a remote call to throw on the client |
| * side. |
| */ |
| public Integer[] getListenerIds(String clientID) |
| throws EventClientNotFoundException, IOException; |
| |
| /** |
| * Adds a listener to receive notifications from an MBean and returns |
| * a non-negative integer as the identifier of the listener. |
| * <P>This method is called by an {@link EventClient} to implement the |
| * method {@link EventClient#addNotificationListener(ObjectName, |
| * NotificationListener, NotificationFilter, Object)}. |
| * |
| * @param name The name of the MBean onto which the listener should be added. |
| * @param filter The filter object. If {@code filter} is null, |
| * no filtering will be performed before handling notifications. |
| * @param clientId The client identifier with which the listener is added. |
| * @return A listener identifier. |
| * @throws EventClientNotFoundException Thrown if the {@code clientId} is |
| * not found. |
| * @throws InstanceNotFoundException Thrown if the MBean is not found. |
| * @throws IOException Reserved for a remote call to throw on the client |
| * side. |
| */ |
| public Integer addListener(String clientId, |
| ObjectName name, |
| NotificationFilter filter) |
| throws InstanceNotFoundException, EventClientNotFoundException, |
| IOException; |
| |
| |
| /** |
| * <p>Subscribes a listener to receive notifications from an MBean or a |
| * set of MBeans represented by an {@code ObjectName} pattern. (It is |
| * not an error if no MBeans match the pattern at the time this method is |
| * called.)</p> |
| * |
| * <p>Returns a non-negative integer as the identifier of the listener.</p> |
| * |
| * <p>This method is called by an {@link EventClient} to execute its |
| * method {@link EventClient#subscribe(ObjectName, NotificationListener, |
| * NotificationFilter, Object)}.</p> |
| * |
| * @param clientId The remote client's identifier. |
| * @param name The name of an MBean or an {@code ObjectName} pattern |
| * representing a set of MBeans to which the listener should listen. |
| * @param filter The filter object. If {@code filter} is null, no |
| * filtering will be performed before notifications are handled. |
| * |
| * @return A listener identifier. |
| * |
| * @throws IllegalArgumentException If the {@code name} or |
| * {@code listener} is null. |
| * @throws EventClientNotFoundException If the client ID is not found. |
| * @throws IOException Reserved for a remote client to throw if |
| * an I/O error occurs. |
| * |
| * @see EventConsumer#subscribe(ObjectName, NotificationListener, |
| * NotificationFilter,Object) |
| * @see #removeListenerOrSubscriber(String, Integer) |
| */ |
| public Integer addSubscriber(String clientId, ObjectName name, |
| NotificationFilter filter) |
| throws EventClientNotFoundException, IOException; |
| |
| /** |
| * Removes a listener, to stop receiving notifications. |
| * <P> This method is called by an {@link EventClient} to execute its |
| * methods {@link EventClient#removeNotificationListener(ObjectName, |
| * NotificationListener, NotificationFilter, Object)}, |
| * {@link EventClient#removeNotificationListener(ObjectName, |
| * NotificationListener)}, and {@link EventClient#unsubscribe}. |
| * |
| * @param clientId The client identifier with which the listener was added. |
| * @param listenerId The listener identifier to be removed. This must be |
| * an identifier returned by a previous {@link #addListener addListener} |
| * or {@link #addSubscriber addSubscriber} call. |
| * |
| * @throws InstanceNotFoundException if the MBean on which the listener |
| * was added no longer exists. |
| * @throws ListenerNotFoundException if there is no listener with the |
| * given {@code listenerId}. |
| * @throws EventClientNotFoundException if the {@code clientId} is |
| * not found. |
| * @throws IOException Reserved for a remote call to throw on the client |
| * side. |
| */ |
| public void removeListenerOrSubscriber(String clientId, Integer listenerId) |
| throws InstanceNotFoundException, ListenerNotFoundException, |
| EventClientNotFoundException, IOException; |
| |
| /** |
| * Called by a client to fetch notifications that are to be sent to its |
| * listeners. |
| * |
| * @param clientId The client's identifier. |
| * @param startSequenceNumber The first sequence number to |
| * consider. |
| * @param timeout The maximum waiting time. |
| * @param maxNotifs The maximum number of notifications to return. |
| * |
| * @throws EventClientNotFoundException Thrown if the {@code clientId} is |
| * not found. |
| * @throws IllegalArgumentException if the client was {@linkplain |
| * #addClient(String, Object[], String[]) added} with an {@link |
| * EventForwarder} that is not a {@link FetchingEventForwarder}. |
| * @throws IOException Reserved for a remote call to throw on the client |
| * side. |
| */ |
| public NotificationResult fetchNotifications(String clientId, |
| long startSequenceNumber, |
| int maxNotifs, |
| long timeout) |
| throws EventClientNotFoundException, IOException; |
| |
| /** |
| * An {@code EventClient} calls this method to keep its {@code clientId} |
| * alive in this MBean. The client will be removed if the lease times out. |
| * |
| * @param clientId The client's identifier. |
| * @param timeout The time in milliseconds by which the lease is to be |
| * extended. The value zero has no special meaning, so it will cause the |
| * lease to time out immediately. |
| * |
| * @return The new lifetime of the lease in milliseconds. This may be |
| * different from the requested time. |
| * |
| * @throws EventClientNotFoundException if the {@code clientId} is |
| * not found. |
| * @throws IOException reserved for a remote call to throw on the client |
| * side. |
| * @throws IllegalArgumentException if {@code clientId} is null or |
| * {@code timeout} is negative. |
| */ |
| public long lease(String clientId, long timeout) |
| throws IOException, EventClientNotFoundException; |
| } |