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 * <p>
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 * <p>
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 the name of the property in standard JavaBean syntax
79 * (e.g. for setName(), property="name")
80 * @param l listener
81 */
82 void addPropertyChangeListener(
83 String propertyName, PropertyChangeListener l);
84
85 /**
86 * Adds a PropertyChangeListener that will be notified of all property
87 * changes.
88 *
89 * @param l The listener to add.
90 */
91 void addPropertyChangeListener(PropertyChangeListener l);
92
93 /**
94 * Removes a specific PropertyChangeListener from this instances
95 * registry that has been mapped to be notified of all property
96 * changes.
97 *
98 * @param l The listener to remove.
99 */
100 void removePropertyChangeListener(PropertyChangeListener l);
101
102 /**
103 * Removes a specific PropertyChangeListener from this instance's
104 * registry which has been previously registered to be notified
105 * of only a specific property change.
106 *
107 * @param propertyName property name, may not be null.
108 * @param l listener to be removed.
109 */
110 void removePropertyChangeListener(
111 String propertyName, PropertyChangeListener l);
112
113 /**
114 * True if the plugin is active and running.
115 *
116 * @return boolean true if the plugin is currently active.
117 */
118 boolean isActive();
119
120 /**
121 * Returns true if the testPlugin is considered to be "equivalent" to the
122 * this plugin.
123 * <p>
124 * <p>The equivalency test is at the discretion of the plugin
125 * implementation. The PluginRegistry will use this method when starting
126 * new plugins to see if a given plugin is considered equivalent to an
127 * already running plugin with the same name. If they are considered to
128 * be equivalent, the currently running plugin will be left in place, and
129 * the new plugin will not be started.</p>
130 * <p>
131 * <p>It is possible to override the equals() method, however this has
132 * more meaning than is required for this simple test and would also
133 * require the overriding of the hashCode() method as well. All of this
134 * is more work than is needed, so this simple method is used instead.</p>
135 *
136 * @param testPlugin The plugin to test equivalency against.
137 * @return Returns true if testPlugin is considered to be equivelent.
138 */
139 boolean isEquivalent(Plugin testPlugin);
140
141 /**
142 * Call when the plugin should be stopped.
143 */
144 void shutdown();
145 }