1 /*

     2  * Copyright 2007-2008 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 java.io.IOException;

    29 import javax.management.ListenerNotFoundException;

    30 import javax.management.NotificationFilter;

    31 import javax.management.NotificationListener;

    32 import javax.management.ObjectName;

    33 

    34 /**

    35  * This interface specifies methods to subscribe a listener to receive events

    36  * from an MBean or a set of MBeans. The MBeans can already be registered in

    37  * an MBean server, or they can be pending registration, or they can be MBeans

    38  * that will never be registered, or they can be MBeans that will be registered

    39  * then unregistered.

    40  * @since JMX 2.0

    41  */

    42 public interface EventConsumer {

    43     /**

    44      * <p>Subscribes a listener to receive events from an MBean or a set

    45      * of MBeans represented by an {@code ObjectName} pattern.</p>

    46      *

    47      * <P> An event emitted by an MBean is forwarded to every listener that was

    48      * subscribed with the name of that MBean, or with a pattern that matches

    49      * that name.</p>

    50      *

    51      * @param name The name of an MBean or an {@code ObjectName} pattern

    52      * representing a set of MBeans to which the listener should listen.

    53      * @param listener The listener object that will handle the

    54      * notifications emitted by the MBeans.

    55      * @param filter The filter object. If {@code filter} is null, no

    56      * filtering will be performed before notification handling.

    57      * @param handback The context to be sent to the listener when a

    58      * notification is emitted.

    59      *

    60      * @throws IllegalArgumentException If the {@code name} or

    61      * {@code listener} is null.

    62      * @throws IOException for a remote client, thrown if

    63      * an I/O error occurs.

    64      * @see #unsubscribe(ObjectName, NotificationListener)

    65      */

    66     public void subscribe(ObjectName name,

    67             NotificationListener listener,

    68             NotificationFilter filter,

    69             Object handback)

    70             throws IOException;

    71 

    72     /**

    73      * <p>Unsubscribes a listener which is listening to an MBean or a set of

    74      * MBeans represented by an {@code ObjectName} pattern.</p>

    75      *

    76      * <p>The listener to be removed must have been added by the {@link

    77      * #subscribe subscribe} method with the given {@code name}. If the {@code

    78      * name} is a pattern, then the {@code subscribe} must have used the same

    79      * pattern. If the same listener has been subscribed more than once to the

    80      * {@code name}, perhaps with different filters or handbacks, then all such

    81      * listeners are removed.</p>

    82      *

    83      * @param name The name of the MBean or an {@code ObjectName} pattern

    84      * representing a set of MBeans to which the listener was subscribed.

    85      * @param listener A listener that was previously subscribed to the

    86      * MBean(s).

    87      *

    88      * @throws ListenerNotFoundException The given {@code listener} was not

    89      * subscribed to the given {@code name}.

    90      * @throws IOException for a remote client, thrown if

    91      * an I/O error occurs.

    92      *

    93      * @see #subscribe

    94      */

    95     public void unsubscribe(ObjectName name,

    96             NotificationListener listener)

    97             throws ListenerNotFoundException, IOException;

    98 }