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

   1 /*
   2  * SPDX-License-Identifier: LGPL-2.1-only
   3  *
   4  * Copyright (C) 2015 EfficiOS Inc.
   5  * Copyright (C) 2015 Alexandre Montplaisir <alexmonthy@efficios.com>
   6  */
   7
   8 package org.lttng.ust.agent.filter;
   9
  10 import org.lttng.ust.agent.session.EventRule;
  11
  12 /**
  13  * Filter notification listener interface.
  14  * <p>
  15  * Applications wanting to be notified of event filtering rule changes should
  16  * implement this interface, then register their listener using
  17  * {@link FilterChangeNotifier#registerListener}.
  18  * </p>
  19  * <p>
  20  * The callbacks defined in this interface will be called whenever an event rule
  21  * is added or removed. The manager will take care of the reference-counting in
  22  * case multiple tracing sessions enable the exact same rules. For example, the
  23  * {@link #eventRuleRemoved} callback is only called when there are no more
  24  * session interested into it.
  25  * </p>
  26  * <p>
  27  * Do not forget to unregister the listener after use, using
  28  * {@link FilterChangeNotifier#unregisterListener}. If you do not, or if
  29  * you use an anonymous listener for example, these will remain attached until
  30  * the complete shutdown of the application.
  31  * </p>
  32  * <p>
  33  * Only one thread is used to dispatch notifications, sequentially. This means
  34  * that if a callback hangs it will prevent other listeners from receiving
  35  * notifications. Please take care of not blocking inside the listener
  36  * callbacks, and use separate threads for potentially long or blocking
  37  * operations.
  38  * </p>
  39  *
  40  * @author Alexandre Montplaisir
  41  */
  42 public interface IFilterChangeListener {
  43
  44         /**
  45          * Notification that a new event rule is now enabled in the tracing
  46          * sessions.
  47          *
  48          * @param rule
  49          *            The event rule that was enabled
  50          */
  51         void eventRuleAdded(EventRule rule);
  52
  53         /**
  54          * Notification that an existing event rule is now disabled in the tracing
  55          * sessions.
  56          *
  57          * @param rule
  58          *            The event rule that was disabled
  59          */
  60         void eventRuleRemoved(EventRule rule);
  61 }