Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.configuration.event; import java.util.ArrayList; import java.util.Collection; import java.util.Collections; import java.util.Iterator; import java.util.LinkedList; /** * <p> * A base class for objects that can generate configuration events. * </p> * <p> * This class implements functionality for managing a set of event listeners * that can be notified when an event occurs. It can be extended by * configuration classes that support the event machanism. In this case these * classes only need to call the <code>fireEvent()</code> method when an event * is to be delivered to the registered listeners. * </p> * <p> * Adding and removing event listeners can happen concurrently to manipulations * on a configuration that cause events. The operations are synchronized. * </p> * <p> * With the <code>detailEvents</code> property the number of detail events can * be controlled. Some methods in configuration classes are implemented in a way * that they call other methods that can generate their own events. One example * is the <code>setProperty()</code> method that can be implemented as a * combination of <code>clearProperty()</code> and <code>addProperty()</code>. * With <code>detailEvents</code> set to <b>true</b>, all involved methods * will generate events (i.e. listeners will receive property set events, * property clear events, and property add events). If this mode is turned off * (which is the default), detail events are suppressed, so only property set * events will be received. Note that the number of received detail events may * differ for different configuration implementations. * <code>{@link org.apache.commons.configuration.HierarchicalConfiguration HierarchicalConfiguration}</code> * for instance has a custom implementation of <code>setProperty()</code>, * which does not generate any detail events. * </p> * <p> * In addition to "normal" events, error events are supported. Such * events signal an internal problem that occurred during access of properties. * For them a special listener interface exists: * <code>{@link ConfigurationErrorListener}</code>. There is another set of * methods dealing with event listeners of this type. The * <code>fireError()</code> method can be used by derived classes to send * notifications about errors to registered observers. * </p> * * @author <a href="http://commons.apache.org/configuration/team-list.html">Commons Configuration team</a> * @version $Id: EventSource.java 561230 2007-07-31 04:17:09Z rahul $ * @since 1.3 */ public class EventSource { /** A collection for the registered event listeners. */ private Collection listeners; /** A collection for the registered error listeners.*/ private Collection errorListeners; /** A counter for the detail events. */ private int detailEvents; /** * Creates a new instance of <code>EventSource</code>. */ public EventSource() { initListeners(); } /** * Adds a configuration listener to this object. * * @param l the listener to add */ public void addConfigurationListener(ConfigurationListener l) { doAddListener(listeners, l); } /** * Removes the specified event listener so that it does not receive any * further events caused by this object. * * @param l the listener to be removed * @return a flag whether the event listener was found */ public boolean removeConfigurationListener(ConfigurationListener l) { return doRemoveListener(listeners, l); } /** * Returns a collection with all configuration event listeners that are * currently registered at this object. * * @return a collection with the registered * <code>ConfigurationListener</code>s (this collection is a snapshot * of the currently registered listeners; manipulating it has no effect * on this event source object) */ public Collection getConfigurationListeners() { return doGetListeners(listeners); } /** * Removes all registered configuration listeners. */ public void clearConfigurationListeners() { doClearListeners(listeners); } /** * Returns a flag whether detail events are enabled. * * @return a flag if detail events are generated */ public boolean isDetailEvents() { synchronized (listeners) { return detailEvents > 0; } } /** * Determines whether detail events should be generated. If enabled, some * methods can generate multiple update events. Note that this method * records the number of calls, i.e. if for instance * <code>setDetailEvents(false)</code> was called three times, you will * have to invoke the method as often to enable the details. * * @param enable a flag if detail events should be enabled or disabled */ public void setDetailEvents(boolean enable) { synchronized (listeners) { if (enable) { detailEvents++; } else { detailEvents--; } } } /** * Adds a new configuration error listener to this object. This listener * will then be notified about internal problems. * * @param l the listener to register (must not be <b>null</b>) * @since 1.4 */ public void addErrorListener(ConfigurationErrorListener l) { doAddListener(errorListeners, l); } /** * Removes the specified error listener so that it does not receive any * further events caused by this object. * * @param l the listener to remove * @return a flag whether the listener could be found and removed * @since 1.4 */ public boolean removeErrorListener(ConfigurationErrorListener l) { return doRemoveListener(errorListeners, l); } /** * Removes all registered error listeners. * * @since 1.4 */ public void clearErrorListeners() { doClearListeners(errorListeners); } /** * Returns a collection with all configuration error listeners that are * currently registered at this object. * * @return a collection with the registered * <code>ConfigurationErrorListener</code>s (this collection is a * snapshot of the currently registered listeners; it cannot be manipulated) * @since 1.4 */ public Collection getErrorListeners() { return doGetListeners(errorListeners); } /** * Creates an event object and delivers it to all registered event * listeners. The method will check first if sending an event is allowed * (making use of the <code>detailEvents</code> property), and if * listeners are registered. * * @param type the event's type * @param propName the name of the affected property (can be <b>null</b>) * @param propValue the value of the affected property (can be <b>null</b>) * @param before the before update flag */ protected void fireEvent(int type, String propName, Object propValue, boolean before) { Collection listenersToCall = null; synchronized (listeners) { if (detailEvents >= 0 && listeners.size() > 0) { // Copy listeners to another collection so that manipulating // the listener list during event delivery won't cause problems listenersToCall = new ArrayList(listeners); } } if (listenersToCall != null) { ConfigurationEvent event = createEvent(type, propName, propValue, before); for (Iterator it = listenersToCall.iterator(); it.hasNext();) { ((ConfigurationListener) it.next()).configurationChanged(event); } } } /** * Creates a <code>ConfigurationEvent</code> object based on the passed in * parameters. This is called by <code>fireEvent()</code> if it decides * that an event needs to be generated. * * @param type the event's type * @param propName the name of the affected property (can be <b>null</b>) * @param propValue the value of the affected property (can be <b>null</b>) * @param before the before update flag * @return the newly created event object */ protected ConfigurationEvent createEvent(int type, String propName, Object propValue, boolean before) { return new ConfigurationEvent(this, type, propName, propValue, before); } /** * Creates an error event object and delivers it to all registered error * listeners. * * @param type the event's type * @param propName the name of the affected property (can be <b>null</b>) * @param propValue the value of the affected property (can be <b>null</b>) * @param ex the <code>Throwable</code> object that caused this error event * @since 1.4 */ protected void fireError(int type, String propName, Object propValue, Throwable ex) { Collection listenersToCall = null; synchronized (errorListeners) { if (errorListeners.size() > 0) { // Copy listeners to another collection so that manipulating // the listener list during event delivery won't cause problems listenersToCall = new ArrayList(errorListeners); } } if (listenersToCall != null) { ConfigurationErrorEvent event = createErrorEvent(type, propName, propValue, ex); for (Iterator it = listenersToCall.iterator(); it.hasNext();) { ((ConfigurationErrorListener) it.next()).configurationError(event); } } } /** * Creates a <code>ConfigurationErrorEvent</code> object based on the * passed in parameters. This is called by <code>fireError()</code> if it * decides that an event needs to be generated. * * @param type the event's type * @param propName the name of the affected property (can be <b>null</b>) * @param propValue the value of the affected property (can be <b>null</b>) * @param ex the <code>Throwable</code> object that caused this error * event * @return the event object * @since 1.4 */ protected ConfigurationErrorEvent createErrorEvent(int type, String propName, Object propValue, Throwable ex) { return new ConfigurationErrorEvent(this, type, propName, propValue, ex); } /** * Overrides the <code>clone()</code> method to correctly handle so far * registered event listeners. This implementation ensures that the clone * will have empty event listener lists, i.e. the listeners registered at an * <code>EventSource</code> object will not be copied. * * @return the cloned object * @throws CloneNotSupportedException if cloning is not allowed * @since 1.4 */ protected Object clone() throws CloneNotSupportedException { EventSource copy = (EventSource) super.clone(); copy.initListeners(); return copy; } /** * Adds a new listener object to a listener collection. This is done in a * synchronized block. The listener must not be <b>null</b>. * * @param listeners the collection with the listeners * @param l the listener object */ private static void doAddListener(Collection listeners, Object l) { if (l == null) { throw new IllegalArgumentException("Listener must not be null!"); } synchronized (listeners) { listeners.add(l); } } /** * Removes an event listener from a listener collection. This is done in a * synchronized block. * * @param listeners the collection with the listeners * @param l the listener object * @return a flag whether the listener could be found and removed */ private static boolean doRemoveListener(Collection listeners, Object l) { synchronized (listeners) { return listeners.remove(l); } } /** * Removes all entries from the given list of event listeners. * * @param listeners the collection with the listeners */ private static void doClearListeners(Collection listeners) { synchronized (listeners) { listeners.clear(); } } /** * Returns an unmodifiable snapshot of the given event listener collection. * * @param listeners the collection with the listeners * @return a snapshot of the listeners collection */ private static Collection doGetListeners(Collection listeners) { synchronized (listeners) { return Collections.unmodifiableCollection(new ArrayList(listeners)); } } /** * Initializes the collections for storing registered event listeners. */ private void initListeners() { listeners = new LinkedList(); errorListeners = new LinkedList(); } }