    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *     http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.configuration2.event;
    018
    019import java.util.Collection;
    020import java.util.Collections;
    021import java.util.LinkedList;
    022import java.util.List;
    023
    024/**
    025 * <p>
    026 * A base class for objects that can generate configuration events.
    027 * </p>
    028 * <p>
    029 * This class implements functionality for managing a set of event listeners
    030 * that can be notified when an event occurs. It can be extended by
    031 * configuration classes that support the event mechanism. In this case these
    032 * classes only need to call the {@code fireEvent()} method when an event is to
    033 * be delivered to the registered listeners.
    034 * </p>
    035 * <p>
    036 * Adding and removing event listeners can happen concurrently to manipulations
    037 * on a configuration that cause events. The operations are synchronized.
    038 * </p>
    039 * <p>
    040 * With the {@code detailEvents} property the number of detail events can be
    041 * controlled. Some methods in configuration classes are implemented in a way
    042 * that they call other methods that can generate their own events. One example
    043 * is the {@code setProperty()} method that can be implemented as a combination
    044 * of {@code clearProperty()} and {@code addProperty()}. With
    045 * {@code detailEvents} set to <b>true</b>, all involved methods will generate
    046 * events (i.e. listeners will receive property set events, property clear
    047 * events, and property add events). If this mode is turned off (which is the
    048 * default), detail events are suppressed, so only property set events will be
    049 * received. Note that the number of received detail events may differ for
    050 * different configuration implementations.
    051 * {@link org.apache.commons.configuration2.BaseHierarchicalConfiguration
    052 * BaseHierarchicalConfiguration} for instance has a custom implementation of
    053 * {@code setProperty()}, which does not generate any detail events.
    054 * </p>
    055 * <p>
    056 * In addition to &quot;normal&quot; events, error events are supported. Such
    057 * events signal an internal problem that occurred during access of properties.
    058 * They are handled via the regular {@link EventListener} interface, but there
    059 * are special event types defined by {@link ConfigurationErrorEvent}. The
    060 * {@code fireError()} method can be used by derived classes to send
    061 * notifications about errors to registered observers.
    062 * </p>
    063 *
    064 * @version $Id: BaseEventSource.java 1842194 2018-09-27 22:24:23Z ggregory $
    065 * @since 1.3
    066 */
    067public class BaseEventSource implements EventSource
    068{
    069    /** The list for managing registered event listeners. */
    070    private EventListenerList eventListeners;
    071
    072    /** A lock object for guarding access to the detail events counter. */
    073    private final Object lockDetailEventsCount = new Object();
    074
    075    /** A counter for the detail events. */
    076    private int detailEvents;
    077
    078    /**
    079     * Creates a new instance of {@code BaseEventSource}.
    080     */
    081    public BaseEventSource()
    082    {
    083        initListeners();
    084    }
    085
    086    /**
    087     * Returns a collection with all event listeners of the specified event type
    088     * that are currently registered at this object.
    089     *
    090     * @param eventType the event type object
    091     * @param <T> the event type
    092     * @return a collection with the event listeners of the specified event type
    093     *         (this collection is a snapshot of the currently registered
    094     *         listeners; it cannot be manipulated)
    095     */
    096    public <T extends Event> Collection<EventListener<? super T>> getEventListeners(
    097            final EventType<T> eventType)
    098    {
    099        final List<EventListener<? super T>> result =
    100                new LinkedList<>();
    101        for (final EventListener<? super T> l : eventListeners
    102                .getEventListeners(eventType))
    103        {
    104            result.add(l);
    105        }
    106        return Collections.unmodifiableCollection(result);
    107    }
    108
    109    /**
    110     * Returns a list with all {@code EventListenerRegistrationData} objects
    111     * currently contained for this event source. This method allows access to
    112     * all registered event listeners, independent on their type.
    113     *
    114     * @return a list with information about all registered event listeners
    115     */
    116    public List<EventListenerRegistrationData<?>> getEventListenerRegistrations()
    117    {
    118        return eventListeners.getRegistrations();
    119    }
    120
    121    /**
    122     * Returns a flag whether detail events are enabled.
    123     *
    124     * @return a flag if detail events are generated
    125     */
    126    public boolean isDetailEvents()
    127    {
    128        return checkDetailEvents(0);
    129    }
    130
    131    /**
    132     * Determines whether detail events should be generated. If enabled, some
    133     * methods can generate multiple update events. Note that this method
    134     * records the number of calls, i.e. if for instance
    135     * {@code setDetailEvents(false)} was called three times, you will
    136     * have to invoke the method as often to enable the details.
    137     *
    138     * @param enable a flag if detail events should be enabled or disabled
    139     */
    140    public void setDetailEvents(final boolean enable)
    141    {
    142        synchronized (lockDetailEventsCount)
    143        {
    144            if (enable)
    145            {
    146                detailEvents++;
    147            }
    148            else
    149            {
    150                detailEvents--;
    151            }
    152        }
    153    }
    154
    155    @Override
    156    public <T extends Event> void addEventListener(final EventType<T> eventType,
    157            final EventListener<? super T> listener)
    158    {
    159        eventListeners.addEventListener(eventType, listener);
    160    }
    161
    162    @Override
    163    public <T extends Event> boolean removeEventListener(
    164            final EventType<T> eventType, final EventListener<? super T> listener)
    165    {
    166        return eventListeners.removeEventListener(eventType, listener);
    167    }
    168
    169    /**
    170     * Removes all registered event listeners.
    171     */
    172    public void clearEventListeners()
    173    {
    174        eventListeners.clear();
    175    }
    176
    177    /**
    178     * Removes all registered error listeners.
    179     *
    180     * @since 1.4
    181     */
    182    public void clearErrorListeners()
    183    {
    184        for (final EventListenerRegistrationData<? extends ConfigurationErrorEvent> reg : eventListeners
    185                .getRegistrationsForSuperType(ConfigurationErrorEvent.ANY))
    186        {
    187            eventListeners.removeEventListener(reg);
    188        }
    189    }
    190
    191    /**
    192     * Copies all event listener registrations maintained by this object to the
    193     * specified {@code BaseEventSource} object.
    194     *
    195     * @param source the target source for the copy operation (must not be
    196     *        <b>null</b>)
    197     * @throws IllegalArgumentException if the target source is <b>null</b>
    198     * @since 2.0
    199     */
    200    public void copyEventListeners(final BaseEventSource source)
    201    {
    202        if (source == null)
    203        {
    204            throw new IllegalArgumentException(
    205                    "Target event source must not be null!");
    206        }
    207        source.eventListeners.addAll(eventListeners);
    208    }
    209
    210    /**
    211     * Creates an event object and delivers it to all registered event
    212     * listeners. The method checks first if sending an event is allowed (making
    213     * use of the {@code detailEvents} property), and if listeners are
    214     * registered.
    215     *
    216     * @param type the event's type
    217     * @param propName the name of the affected property (can be <b>null</b>)
    218     * @param propValue the value of the affected property (can be <b>null</b>)
    219     * @param before the before update flag
    220     * @param <T> the type of the event to be fired
    221     */
    222    protected <T extends ConfigurationEvent> void fireEvent(final EventType<T> type,
    223            final String propName, final Object propValue, final boolean before)
    224    {
    225        if (checkDetailEvents(-1))
    226        {
    227            final EventListenerList.EventListenerIterator<T> it =
    228                    eventListeners.getEventListenerIterator(type);
    229            if (it.hasNext())
    230            {
    231                final ConfigurationEvent event =
    232                        createEvent(type, propName, propValue, before);
    233                while (it.hasNext())
    234                {
    235                    it.invokeNext(event);
    236                }
    237            }
    238        }
    239    }
    240
    241    /**
    242     * Creates a {@code ConfigurationEvent} object based on the passed in
    243     * parameters. This method is called by {@code fireEvent()} if it decides
    244     * that an event needs to be generated.
    245     *
    246     * @param type the event's type
    247     * @param propName the name of the affected property (can be <b>null</b>)
    248     * @param propValue the value of the affected property (can be <b>null</b>)
    249     * @param before the before update flag
    250     * @param <T> the type of the event to be created
    251     * @return the newly created event object
    252     */
    253    protected <T extends ConfigurationEvent> ConfigurationEvent createEvent(
    254            final EventType<T> type, final String propName, final Object propValue, final boolean before)
    255    {
    256        return new ConfigurationEvent(this, type, propName, propValue, before);
    257    }
    258
    259    /**
    260     * Creates an error event object and delivers it to all registered error
    261     * listeners of a matching type.
    262     *
    263     * @param eventType the event's type
    264     * @param operationType the type of the failed operation
    265     * @param propertyName the name of the affected property (can be
    266     *        <b>null</b>)
    267     * @param propertyValue the value of the affected property (can be
    268     *        <b>null</b>)
    269     * @param cause the {@code Throwable} object that caused this error event
    270     * @param <T> the event type
    271     */
    272    public <T extends ConfigurationErrorEvent> void fireError(
    273            final EventType<T> eventType, final EventType<?> operationType,
    274            final String propertyName, final Object propertyValue, final Throwable cause)
    275    {
    276        final EventListenerList.EventListenerIterator<T> iterator =
    277                eventListeners.getEventListenerIterator(eventType);
    278        if (iterator.hasNext())
    279        {
    280            final ConfigurationErrorEvent event =
    281                    createErrorEvent(eventType, operationType, propertyName,
    282                            propertyValue, cause);
    283            while (iterator.hasNext())
    284            {
    285                iterator.invokeNext(event);
    286            }
    287        }
    288    }
    289
    290    /**
    291     * Creates a {@code ConfigurationErrorEvent} object based on the passed in
    292     * parameters. This is called by {@code fireError()} if it decides that an
    293     * event needs to be generated.
    294     *
    295     * @param type the event's type
    296     * @param opType the operation type related to this error
    297     * @param propName the name of the affected property (can be <b>null</b>)
    298     * @param propValue the value of the affected property (can be <b>null</b>)
    299     * @param ex the {@code Throwable} object that caused this error event
    300     * @return the event object
    301     */
    302    protected ConfigurationErrorEvent createErrorEvent(
    303            final EventType<? extends ConfigurationErrorEvent> type,
    304            final EventType<?> opType, final String propName, final Object propValue, final Throwable ex)
    305    {
    306        return new ConfigurationErrorEvent(this, type, opType, propName,
    307                propValue, ex);
    308    }
    309
    310    /**
    311     * Overrides the {@code clone()} method to correctly handle so far
    312     * registered event listeners. This implementation ensures that the clone
    313     * will have empty event listener lists, i.e. the listeners registered at an
    314     * {@code BaseEventSource} object will not be copied.
    315     *
    316     * @return the cloned object
    317     * @throws CloneNotSupportedException if cloning is not allowed
    318     * @since 1.4
    319     */
    320    @Override
    321    protected Object clone() throws CloneNotSupportedException
    322    {
    323        final BaseEventSource copy = (BaseEventSource) super.clone();
    324        copy.initListeners();
    325        return copy;
    326    }
    327
    328    /**
    329     * Initializes the collections for storing registered event listeners.
    330     */
    331    private void initListeners()
    332    {
    333        eventListeners = new EventListenerList();
    334    }
    335
    336    /**
    337     * Helper method for checking the current counter for detail events. This
    338     * method checks whether the counter is greater than the passed in limit.
    339     *
    340     * @param limit the limit to be compared to
    341     * @return <b>true</b> if the counter is greater than the limit,
    342     *         <b>false</b> otherwise
    343     */
    344    private boolean checkDetailEvents(final int limit)
    345    {
    346        synchronized (lockDetailEventsCount)
    347        {
    348            return detailEvents > limit;
    349        }
    350    }
    351}