Author: oheger Date: Sun Apr 16 10:54:22 2006 New Revision: 394528 URL: http://svn.apache.org/viewcvs?rev=394528&view=rev Log: Added new classes for supporting event listeners
Added: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationEvent.java (with props) jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationListener.java (with props) jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/EventSource.java (with props) Added: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationEvent.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationEvent.java?rev=394528&view=auto ============================================================================== --- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationEvent.java (added) +++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationEvent.java Sun Apr 16 10:54:22 2006 @@ -0,0 +1,132 @@ +/* + * Copyright 2006 The Apache Software Foundation. + * + * Licensed 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.EventObject; + +/** + * <p> + * An event class for reporting updates on a configuration object. + * </p> + * <p> + * Event objects of this type are used for "raw" events, i.e. + * unfiltered modifications of any kind. A level with semantically higher events + * (e.g. for property changes) may be built on top of this fundamental event + * mechanism. + * </p> + * <p> + * Each event can contain the following data: + * <ul> + * <li>A source object, which is usually the configuration object that was + * modified.</li> + * <li>The event's type. This is a numeric value that corresponds to constant + * declarations in concrete configuration classes. It describes what exactly has + * happended.</li> + * <li>If available, the name of the property whose modification caused the + * event.</li> + * <li>If available, the value of the property that caused this event.</li> + * <li>A flag whether this event was generated before or after the update of + * the source configuration. A modification of a configuration typically causes + * two events: one event before and one event after the modification is + * performed. This allows event listeners to react at the correct point of time.</li> + * </ul> + * </p> + * + * @version $Id$ + * @since 1.3 + */ +public class ConfigurationEvent extends EventObject +{ + /** + * The serial version UID. + */ + private static final long serialVersionUID = 3277238219073504136L; + + /** Stores the event type. */ + private int type; + + /** Stores the property name. */ + private String propertyName; + + /** Stores the property value. */ + private Object propertyValue; + + /** Stores the before update flag. */ + private boolean beforeUpdate; + + /** + * Creates a new instance of <code>ConfigurationEvent</code> and + * initializes it. + * + * @param source the event source + * @param type the event's type + * @param propertyName the name of the affected property + * @param propertyValue the value of the affected property + * @param beforeUpdate the before update flag + */ + public ConfigurationEvent(Object source, int type, String propertyName, + Object propertyValue, boolean beforeUpdate) + { + super(source); + this.type = type; + this.propertyName = propertyName; + this.propertyValue = propertyValue; + this.beforeUpdate = beforeUpdate; + } + + /** + * Returns the name of the affected property. This can be <b>null</b> if no + * property change has lead to this event. + * + * @return the name of the property + */ + public String getPropertyName() + { + return propertyName; + } + + /** + * Returns the value of the affected property if available. + * + * @return the value of the property; can be <b>null</b> + */ + public Object getPropertyValue() + { + return propertyValue; + } + + /** + * Returns the type of this event. This describes the update process that + * caused this event. + * + * @return the event's type + */ + public int getType() + { + return type; + } + + /** + * Returns a flag if this event was generated before or after an update. + * + * @return <b>true</b> if this event was generated before an update; + * <b>false</b> otherwise + */ + public boolean isBeforeUpdate() + { + return beforeUpdate; + } +} Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationEvent.java ------------------------------------------------------------------------------ svn:eol-style = native Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationEvent.java ------------------------------------------------------------------------------ svn:keywords = Date Author Id Revision HeadURL Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationEvent.java ------------------------------------------------------------------------------ svn:mime-type = text/plain Added: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationListener.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationListener.java?rev=394528&view=auto ============================================================================== --- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationListener.java (added) +++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationListener.java Sun Apr 16 10:54:22 2006 @@ -0,0 +1,41 @@ +/* + * Copyright 2006 The Apache Software Foundation. + * + * Licensed 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; + +/** + * <p> + * A simple event listener interface for configuration observers. + * </p> + * <p> + * This interface can be implemented by classes that are interested in + * "raw" events caused by configuration objects. Each manipulation on + * a configuration object will generate such an event. There is only a single + * method that is invoked when an event occurs. + * </p> + * + * @version $Id$ + * @since 1.3 + */ +public interface ConfigurationListener +{ + /** + * Notifies this listener about a manipulation on a monitored configuration + * object. + * + * @param event the event describing the manipulation + */ + void configurationChanged(ConfigurationEvent event); +} Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationListener.java ------------------------------------------------------------------------------ svn:eol-style = native Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationListener.java ------------------------------------------------------------------------------ svn:keywords = Date Author Id Revision HeadURL Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/ConfigurationListener.java ------------------------------------------------------------------------------ svn:mime-type = text/plain Added: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/EventSource.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/EventSource.java?rev=394528&view=auto ============================================================================== --- jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/EventSource.java (added) +++ jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/EventSource.java Sun Apr 16 10:54:22 2006 @@ -0,0 +1,213 @@ +/* + * Copyright 2006 The Apache Software Foundation. + * + * Licensed 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>[EMAIL PROTECTED] 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> + * + * @version $Id$ + * @since 1.3 + */ +public class EventSource +{ + /** A collection for the registered event listeners. */ + private Collection listeners; + + /** A counter for the detail events. */ + private int detailEvents; + + /** + * Creates a new instance of <code>EventSource</code>. + */ + public EventSource() + { + listeners = new LinkedList(); + } + + /** + * Adds a configuration listener to this object. + * + * @param l the listener to add + */ + public void addConfigurationListener(ConfigurationListener l) + { + if (l == null) + { + throw new IllegalArgumentException("Listener must not be null!"); + } + synchronized (listeners) + { + listeners.add(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) + { + synchronized (listeners) + { + return listeners.remove(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 cannot be + * changed) + */ + public Collection getConfigurationListeners() + { + synchronized (listeners) + { + return Collections.unmodifiableCollection(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--; + } + } + } + + /** + * 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); + } +} Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/EventSource.java ------------------------------------------------------------------------------ svn:eol-style = native Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/EventSource.java ------------------------------------------------------------------------------ svn:keywords = Date Author Id Revision HeadURL Propchange: jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event/EventSource.java ------------------------------------------------------------------------------ svn:mime-type = text/plain --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]