View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17
    18  package org.apache.log4j.plugins;
    19
    20  import org.apache.log4j.spi.LoggerRepository;
    21  import org.apache.log4j.spi.OptionHandler;
    22
    23  import java.beans.PropertyChangeListener;
    24
    25
    26  /**
    27   * Defines the required interface for all Plugin objects.
    28   *
    29   * <p>A plugin implements some specific functionality to extend
    30   * the log4j framework.  Each plugin is associated with a specific
    31   * LoggerRepository, which it then uses/acts upon.  The functionality
    32   * of the plugin is up to the developer.</p>
    33   *
    34   * <p>Examples of plugins are Receiver and Watchdog. Receiver plugins
    35   * allow for remote logging events to be received and processed by
    36   * a repository as if the event was sent locally. Watchdog plugins
    37   * allow for a repository to be reconfigured when some "watched"
    38   * configuration data changes.</p>
    39   *
    40   * @author Mark Womack (mwomack@apache.org)
    41   * @author Nicko Cadell
    42   * @author Paul Smith (psmith@apache.org)
    43   */
    44  public interface Plugin extends OptionHandler {
    45      /**
    46       * Gets the name of the plugin.
    47       *
    48       * @return String the name of the plugin.
    49       */
    50      String getName();
    51
    52      /**
    53       * Sets the name of the plugin.
    54       *
    55       * @param name the name of the plugin.
    56       */
    57      void setName(String name);
    58
    59      /**
    60       * Gets the logger repository for this plugin.
    61       *
    62       * @return the logger repository to which this plugin is attached.
    63       */
    64      LoggerRepository getLoggerRepository();
    65
    66      /**
    67       * Sets the logger repository used by this plugin. This
    68       * repository will be used by the plugin functionality.
    69       *
    70       * @param repository the logger repository to attach this plugin to.
    71       */
    72      void setLoggerRepository(LoggerRepository repository);
    73
    74      /**
    75       * Adds a PropertyChangeListener to this instance which is
    76       * notified only by changes of the property with name propertyName.
    77       *
    78       * @param propertyName
    79       *    the name of the property in standard JavaBean syntax
    80       *    (e.g. for setName(), property="name")
    81       * @param l listener
    82       */
    83      void addPropertyChangeListener(
    84              String propertyName, PropertyChangeListener l);
    85
    86      /**
    87       * Adds a PropertyChangeListener that will be notified of all property
    88       * changes.
    89       *
    90       * @param l The listener to add.
    91       */
    92      void addPropertyChangeListener(PropertyChangeListener l);
    93
    94      /**
    95       * Removes a specific PropertyChangeListener from this instances
    96       * registry that has been mapped to be notified of all property
    97       * changes.
    98       *
    99       * @param l The listener to remove.
    100      */
    101     void removePropertyChangeListener(PropertyChangeListener l);
    102
    103     /**
    104      * Removes a specific PropertyChangeListener from this instance's
    105      * registry which has been previously registered to be notified
    106      * of only a specific property change.
    107      *
    108      * @param propertyName property name, may not be null.
    109      * @param l listener to be removed.
    110      */
    111     void removePropertyChangeListener(
    112             String propertyName, PropertyChangeListener l);
    113
    114     /**
    115      * True if the plugin is active and running.
    116      *
    117      * @return boolean true if the plugin is currently active.
    118      */
    119     boolean isActive();
    120
    121     /**
    122      * Returns true if the testPlugin is considered to be "equivalent" to the
    123      * this plugin.
    124      *
    125      * <p>The equivalency test is at the discretion of the plugin
    126      * implementation.  The PluginRegistry will use this method when starting
    127      * new plugins to see if a given plugin is considered equivalent to an
    128      * already running plugin with the same name.  If they are considered to
    129      * be equivalent, the currently running plugin will be left in place, and
    130      * the new plugin will not be started.</p>
    131      *
    132      * <p>It is possible to override the equals() method, however this has
    133      * more meaning than is required for this simple test and would also
    134      * require the overriding of the hashCode() method as well.  All of this
    135      * is more work than is needed, so this simple method is used instead.</p>
    136      *
    137      * @param testPlugin The plugin to test equivalency against.
    138      * @return Returns true if testPlugin is considered to be equivelent.
    139      */
    140     boolean isEquivalent(Plugin testPlugin);
    141
    142     /**
    143      * Call when the plugin should be stopped.
    144      */
    145     void shutdown();
    146 }