View Javadoc

    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  package org.apache.commons.configuration.event;
    18
    19  import java.util.ArrayList;
    20  import java.util.Collection;
    21  import java.util.Collections;
    22  import java.util.Iterator;
    23  import java.util.LinkedList;
    24
    25  /***
    26   * <p>
    27   * A base class for objects that can generate configuration events.
    28   * </p>
    29   * <p>
    30   * This class implements functionality for managing a set of event listeners
    31   * that can be notified when an event occurs. It can be extended by
    32   * configuration classes that support the event machanism. In this case these
    33   * classes only need to call the <code>fireEvent()</code> method when an event
    34   * is to be delivered to the registered listeners.
    35   * </p>
    36   * <p>
    37   * Adding and removing event listeners can happen concurrently to manipulations
    38   * on a configuration that cause events. The operations are synchronized.
    39   * </p>
    40   * <p>
    41   * With the <code>detailEvents</code> property the number of detail events can
    42   * be controlled. Some methods in configuration classes are implemented in a way
    43   * that they call other methods that can generate their own events. One example
    44   * is the <code>setProperty()</code> method that can be implemented as a
    45   * combination of <code>clearProperty()</code> and <code>addProperty()</code>.
    46   * With <code>detailEvents</code> set to <b>true</b>, all involved methods
    47   * will generate events (i.e. listeners will receive property set events,
    48   * property clear events, and property add events). If this mode is turned off
    49   * (which is the default), detail events are suppressed, so only property set
    50   * events will be received. Note that the number of received detail events may
    51   * differ for different configuration implementations.
    52   * <code>{@link org.apache.commons.configuration.HierarchicalConfiguration HierarchicalConfiguration}</code>
    53   * for instance has a custom implementation of <code>setProperty()</code>, which
    54   * does not generate any detail events.
    55   * </p>
    56   *
    57   * @author <a
    58   * href="http://jakarta.apache.org/commons/configuration/team-list.html">Commons
    59   * Configuration team</a>
    60   * @version $Id: EventSource.java 439648 2006-09-02 20:42:10Z oheger $
    61   * @since 1.3
    62   */
    63  public class EventSource
    64  {
    65      /*** A collection for the registered event listeners. */
    66      private Collection listeners;
    67
    68      /*** A counter for the detail events. */
    69      private int detailEvents;
    70
    71      /***
    72       * Creates a new instance of <code>EventSource</code>.
    73       */
    74      public EventSource()
    75      {
    76          clearConfigurationListeners();
    77      }
    78
    79      /***
    80       * Adds a configuration listener to this object.
    81       *
    82       * @param l the listener to add
    83       */
    84      public void addConfigurationListener(ConfigurationListener l)
    85      {
    86          if (l == null)
    87          {
    88              throw new IllegalArgumentException("Listener must not be null!");
    89          }
    90          synchronized (listeners)
    91          {
    92              listeners.add(l);
    93          }
    94      }
    95
    96      /***
    97       * Removes the specified event listener so that it does not receive any
    98       * further events caused by this object.
    99       *
    100      * @param l the listener to be removed
    101      * @return a flag whether the event listener was found
    102      */
    103     public boolean removeConfigurationListener(ConfigurationListener l)
    104     {
    105         synchronized (listeners)
    106         {
    107             return listeners.remove(l);
    108         }
    109     }
    110
    111     /***
    112      * Returns a collection with all configuration event listeners that are
    113      * currently registered at this object.
    114      *
    115      * @return a collection with the registered
    116      * <code>ConfigurationListener</code>s (this collection cannot be
    117      * changed)
    118      */
    119     public Collection getConfigurationListeners()
    120     {
    121         synchronized (listeners)
    122         {
    123             return Collections.unmodifiableCollection(listeners);
    124         }
    125     }
    126
    127     /***
    128      * Removes all registered configuration listeners.
    129      */
    130     public void clearConfigurationListeners()
    131     {
    132         listeners = new LinkedList();
    133     }
    134
    135     /***
    136      * Returns a flag whether detail events are enabled.
    137      *
    138      * @return a flag if detail events are generated
    139      */
    140     public boolean isDetailEvents()
    141     {
    142         synchronized (listeners)
    143         {
    144             return detailEvents > 0;
    145         }
    146     }
    147
    148     /***
    149      * Determines whether detail events should be generated. If enabled, some
    150      * methods can generate multiple update events. Note that this method
    151      * records the number of calls, i.e. if for instance
    152      * <code>setDetailEvents(false)</code> was called three times, you will
    153      * have to invoke the method as often to enable the details.
    154      *
    155      * @param enable a flag if detail events should be enabled or disabled
    156      */
    157     public void setDetailEvents(boolean enable)
    158     {
    159         synchronized (listeners)
    160         {
    161             if (enable)
    162             {
    163                 detailEvents++;
    164             }
    165             else
    166             {
    167                 detailEvents--;
    168             }
    169         }
    170     }
    171
    172     /***
    173      * Creates an event object and delivers it to all registered event
    174      * listeners. The method will check first if sending an event is allowed
    175      * (making use of the <code>detailEvents</code> property), and if
    176      * listeners are registered.
    177      *
    178      * @param type the event's type
    179      * @param propName the name of the affected property (can be <b>null</b>)
    180      * @param propValue the value of the affected property (can be <b>null</b>)
    181      * @param before the before update flag
    182      */
    183     protected void fireEvent(int type, String propName, Object propValue,
    184             boolean before)
    185     {
    186         Collection listenersToCall = null;
    187
    188         synchronized (listeners)
    189         {
    190             if (detailEvents >= 0 && listeners.size() > 0)
    191             {
    192                 // Copy listeners to another collection so that manipulating
    193                 // the listener list during event delivery won't cause problems
    194                 listenersToCall = new ArrayList(listeners);
    195             }
    196         }
    197
    198         if (listenersToCall != null)
    199         {
    200             ConfigurationEvent event = createEvent(type, propName, propValue,
    201                     before);
    202             for (Iterator it = listenersToCall.iterator(); it.hasNext();)
    203             {
    204                 ((ConfigurationListener) it.next()).configurationChanged(event);
    205             }
    206         }
    207     }
    208
    209     /***
    210      * Creates a <code>ConfigurationEvent</code> object based on the passed in
    211      * parameters. This is called by <code>fireEvent()</code> if it decides
    212      * that an event needs to be generated.
    213      *
    214      * @param type the event's type
    215      * @param propName the name of the affected property (can be <b>null</b>)
    216      * @param propValue the value of the affected property (can be <b>null</b>)
    217      * @param before the before update flag
    218      * @return the newly created event object
    219      */
    220     protected ConfigurationEvent createEvent(int type, String propName,
    221             Object propValue, boolean before)
    222     {
    223         return new ConfigurationEvent(this, type, propName, propValue, before);
    224     }
    225 }