    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 that can be notified when an event occurs.
    030 * It can be extended by configuration classes that support the event mechanism. In this case these classes only need to
    031 * call the {@code fireEvent()} method when an event is to be delivered to the registered listeners.
    032 * </p>
    033 * <p>
    034 * Adding and removing event listeners can happen concurrently to manipulations on a configuration that cause events.
    035 * The operations are synchronized.
    036 * </p>
    037 * <p>
    038 * With the {@code detailEvents} property the number of detail events can be controlled. Some methods in configuration
    039 * classes are implemented in a way that they call other methods that can generate their own events. One example is the
    040 * {@code setProperty()} method that can be implemented as a combination of {@code clearProperty()} and
    041 * {@code addProperty()}. With {@code detailEvents} set to <b>true</b>, all involved methods will generate events (i.e.
    042 * listeners will receive property set events, property clear events, and property add events). If this mode is turned
    043 * off (which is the default), detail events are suppressed, so only property set events will be received. Note that the
    044 * number of received detail events may differ for different configuration implementations.
    045 * {@link org.apache.commons.configuration2.BaseHierarchicalConfiguration BaseHierarchicalConfiguration} for instance
    046 * has a custom implementation of {@code setProperty()}, which does not generate any detail events.
    047 * </p>
    048 * <p>
    049 * In addition to &quot;normal&quot; events, error events are supported. Such events signal an internal problem that
    050 * occurred during access of properties. They are handled via the regular {@link EventListener} interface, but there are
    051 * special event types defined by {@link ConfigurationErrorEvent}. The {@code fireError()} method can be used by derived
    052 * classes to send notifications about errors to registered observers.
    053 * </p>
    054 *
    055 * @since 1.3
    056 */
    057public class BaseEventSource implements EventSource {
    058    /** The list for managing registered event listeners. */
    059    private EventListenerList eventListeners;
    060
    061    /** A lock object for guarding access to the detail events counter. */
    062    private final Object lockDetailEventsCount = new Object();
    063
    064    /** A counter for the detail events. */
    065    private int detailEvents;
    066
    067    /**
    068     * Creates a new instance of {@code BaseEventSource}.
    069     */
    070    public BaseEventSource() {
    071        initListeners();
    072    }
    073
    074    @Override
    075    public <T extends Event> void addEventListener(final EventType<T> eventType, final EventListener<? super T> listener) {
    076        eventListeners.addEventListener(eventType, listener);
    077    }
    078
    079    /**
    080     * Helper method for checking the current counter for detail events. This method checks whether the counter is greater
    081     * than the passed in limit.
    082     *
    083     * @param limit the limit to be compared to
    084     * @return <b>true</b> if the counter is greater than the limit, <b>false</b> otherwise
    085     */
    086    private boolean checkDetailEvents(final int limit) {
    087        synchronized (lockDetailEventsCount) {
    088            return detailEvents > limit;
    089        }
    090    }
    091
    092    /**
    093     * Removes all registered error listeners.
    094     *
    095     * @since 1.4
    096     */
    097    public void clearErrorListeners() {
    098        eventListeners.getRegistrationsForSuperType(ConfigurationErrorEvent.ANY).forEach(eventListeners::removeEventListener);
    099    }
    100
    101    /**
    102     * Removes all registered event listeners.
    103     */
    104    public void clearEventListeners() {
    105        eventListeners.clear();
    106    }
    107
    108    /**
    109     * Overrides the {@code clone()} method to correctly handle so far registered event listeners. This implementation
    110     * ensures that the clone will have empty event listener lists, i.e. the listeners registered at an
    111     * {@code BaseEventSource} object will not be copied.
    112     *
    113     * @return the cloned object
    114     * @throws CloneNotSupportedException if cloning is not allowed
    115     * @since 1.4
    116     */
    117    @Override
    118    protected Object clone() throws CloneNotSupportedException {
    119        final BaseEventSource copy = (BaseEventSource) super.clone();
    120        copy.initListeners();
    121        return copy;
    122    }
    123
    124    /**
    125     * Copies all event listener registrations maintained by this object to the specified {@code BaseEventSource} object.
    126     *
    127     * @param source the target source for the copy operation (must not be <b>null</b>)
    128     * @throws IllegalArgumentException if the target source is <b>null</b>
    129     * @since 2.0
    130     */
    131    public void copyEventListeners(final BaseEventSource source) {
    132        if (source == null) {
    133            throw new IllegalArgumentException("Target event source must not be null!");
    134        }
    135        source.eventListeners.addAll(eventListeners);
    136    }
    137
    138    /**
    139     * Creates a {@code ConfigurationErrorEvent} object based on the passed in parameters. This is called by
    140     * {@code fireError()} if it decides that an event needs to be generated.
    141     *
    142     * @param type the event's type
    143     * @param opType the operation type related to this error
    144     * @param propName the name of the affected property (can be <b>null</b>)
    145     * @param propValue the value of the affected property (can be <b>null</b>)
    146     * @param ex the {@code Throwable} object that caused this error event
    147     * @return the event object
    148     */
    149    protected ConfigurationErrorEvent createErrorEvent(final EventType<? extends ConfigurationErrorEvent> type, final EventType<?> opType,
    150        final String propName, final Object propValue, final Throwable ex) {
    151        return new ConfigurationErrorEvent(this, type, opType, propName, propValue, ex);
    152    }
    153
    154    /**
    155     * Creates a {@code ConfigurationEvent} object based on the passed in parameters. This method is called by
    156     * {@code fireEvent()} if it decides that an event needs to be generated.
    157     *
    158     * @param type the event's type
    159     * @param propName the name of the affected property (can be <b>null</b>)
    160     * @param propValue the value of the affected property (can be <b>null</b>)
    161     * @param before the before update flag
    162     * @param <T> the type of the event to be created
    163     * @return the newly created event object
    164     */
    165    protected <T extends ConfigurationEvent> ConfigurationEvent createEvent(final EventType<T> type, final String propName, final Object propValue,
    166        final boolean before) {
    167        return new ConfigurationEvent(this, type, propName, propValue, before);
    168    }
    169
    170    /**
    171     * Creates an error event object and delivers it to all registered error listeners of a matching type.
    172     *
    173     * @param eventType the event's type
    174     * @param operationType the type of the failed operation
    175     * @param propertyName the name of the affected property (can be <b>null</b>)
    176     * @param propertyValue the value of the affected property (can be <b>null</b>)
    177     * @param cause the {@code Throwable} object that caused this error event
    178     * @param <T> the event type
    179     */
    180    public <T extends ConfigurationErrorEvent> void fireError(final EventType<T> eventType, final EventType<?> operationType, final String propertyName,
    181        final Object propertyValue, final Throwable cause) {
    182        final EventListenerList.EventListenerIterator<T> iterator = eventListeners.getEventListenerIterator(eventType);
    183        if (iterator.hasNext()) {
    184            final ConfigurationErrorEvent event = createErrorEvent(eventType, operationType, propertyName, propertyValue, cause);
    185            while (iterator.hasNext()) {
    186                iterator.invokeNext(event);
    187            }
    188        }
    189    }
    190
    191    /**
    192     * Creates an event object and delivers it to all registered event listeners. The method checks first if sending an
    193     * event is allowed (making use of the {@code detailEvents} property), and if listeners are registered.
    194     *
    195     * @param type the event's type
    196     * @param propName the name of the affected property (can be <b>null</b>)
    197     * @param propValue the value of the affected property (can be <b>null</b>)
    198     * @param before the before update flag
    199     * @param <T> the type of the event to be fired
    200     */
    201    protected <T extends ConfigurationEvent> void fireEvent(final EventType<T> type, final String propName, final Object propValue, final boolean before) {
    202        if (checkDetailEvents(-1)) {
    203            final EventListenerList.EventListenerIterator<T> it = eventListeners.getEventListenerIterator(type);
    204            if (it.hasNext()) {
    205                final ConfigurationEvent event = createEvent(type, propName, propValue, before);
    206                while (it.hasNext()) {
    207                    it.invokeNext(event);
    208                }
    209            }
    210        }
    211    }
    212
    213    /**
    214     * Gets a list with all {@code EventListenerRegistrationData} objects currently contained for this event source. This
    215     * method allows access to all registered event listeners, independent on their type.
    216     *
    217     * @return a list with information about all registered event listeners
    218     */
    219    public List<EventListenerRegistrationData<?>> getEventListenerRegistrations() {
    220        return eventListeners.getRegistrations();
    221    }
    222
    223    /**
    224     * Gets a collection with all event listeners of the specified event type that are currently registered at this
    225     * object.
    226     *
    227     * @param eventType the event type object
    228     * @param <T> the event type
    229     * @return a collection with the event listeners of the specified event type (this collection is a snapshot of the
    230     *         currently registered listeners; it cannot be manipulated)
    231     */
    232    public <T extends Event> Collection<EventListener<? super T>> getEventListeners(final EventType<T> eventType) {
    233        final List<EventListener<? super T>> result = new LinkedList<>();
    234        eventListeners.getEventListeners(eventType).forEach(result::add);
    235        return Collections.unmodifiableCollection(result);
    236    }
    237
    238    /**
    239     * Initializes the collections for storing registered event listeners.
    240     */
    241    private void initListeners() {
    242        eventListeners = new EventListenerList();
    243    }
    244
    245    /**
    246     * Returns a flag whether detail events are enabled.
    247     *
    248     * @return a flag if detail events are generated
    249     */
    250    public boolean isDetailEvents() {
    251        return checkDetailEvents(0);
    252    }
    253
    254    @Override
    255    public <T extends Event> boolean removeEventListener(final EventType<T> eventType, final EventListener<? super T> listener) {
    256        return eventListeners.removeEventListener(eventType, listener);
    257    }
    258
    259    /**
    260     * Determines whether detail events should be generated. If enabled, some methods can generate multiple update events.
    261     * Note that this method records the number of calls, i.e. if for instance {@code setDetailEvents(false)} was called
    262     * three times, you will have to invoke the method as often to enable the details.
    263     *
    264     * @param enable a flag if detail events should be enabled or disabled
    265     */
    266    public void setDetailEvents(final boolean enable) {
    267        synchronized (lockDetailEventsCount) {
    268            if (enable) {
    269                detailEvents++;
    270            } else {
    271                detailEvents--;
    272            }
    273        }
    274    }
    275}