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 }