commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r394528 - in /jakarta/commons/proper/configuration/trunk/src/java/org/apache/commons/configuration/event: ./ ConfigurationEvent.java ConfigurationListener.java EventSource.java
Date Sun, 16 Apr 2006 17:54:25 GMT
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 &quot;raw&quot; 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
+ * &quot;raw&quot; 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>{@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>
+ *
+ * @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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message