liblttng-ust-java-agent/java/lttng-ust-agent-common/org/lttng/ust/agent/filter/IFilterChangeListener.java

   1 /*
   2  * Copyright (C) 2015 - EfficiOS Inc., Alexandre Montplaisir <alexmonthy@efficios.com>
   3  *
   4  * This library is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License, version 2.1 only,
   6  * as published by the Free Software Foundation.
   7  *
   8  * This library is distributed in the hope that it will be useful, but WITHOUT
   9  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
  11  * for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this library; if not, write to the Free Software Foundation,
  15  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  16  */
  17
  18 package org.lttng.ust.agent.filter;
  19
  20 import org.lttng.ust.agent.session.EventRule;
  21
  22 /**
  23  * Filter notification listener interface.
  24  * <p>
  25  * Applications wanting to be notified of event filtering rule changes should
  26  * implement this interface, then register their listener using
  27  * {@link FilterChangeNotifier#registerListener}.
  28  * </p>
  29  * <p>
  30  * The callbacks defined in this interface will be called whenever an event rule
  31  * is added or removed. The manager will take care of the reference-counting in
  32  * case multiple tracing sessions enable the exact same rules. For example, the
  33  * {@link #eventRuleRemoved} callback is only called when there are no more
  34  * session interested into it.
  35  * </p>
  36  * <p>
  37  * Do not forget to unregister the listener after use, using
  38  * {@link FilterChangeNotifier#unregisterListener}. If you do not, or if
  39  * you use an anonymous listener for example, these will remain attached until
  40  * the complete shutdown of the application.
  41  * </p>
  42  * <p>
  43  * Only one thread is used to dispatch notifications, sequentially. This means
  44  * that if a callback hangs it will prevent other listeners from receiving
  45  * notifications. Please take care of not blocking inside the listener
  46  * callbacks, and use separate threads for potentially long or blocking
  47  * operations.
  48  * </p>
  49  *
  50  * @author Alexandre Montplaisir
  51  */
  52 public interface IFilterChangeListener {
  53
  54         /**
  55          * Notification that a new event rule is now enabled in the tracing
  56          * sessions.
  57          *
  58          * @param rule
  59          *            The event rule that was enabled
  60          */
  61         void eventRuleAdded(EventRule rule);
  62
  63         /**
  64          * Notification that an existing event rule is now disabled in the tracing
  65          * sessions.
  66          *
  67          * @param rule
  68          *            The event rule that was disabled
  69          */
  70         void eventRuleRemoved(EventRule rule);
  71 }