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 "normal" 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 /** 075 * Gets a collection with all event listeners of the specified event type that are currently registered at this 076 * object. 077 * 078 * @param eventType the event type object 079 * @param <T> the event type 080 * @return a collection with the event listeners of the specified event type (this collection is a snapshot of the 081 * currently registered listeners; it cannot be manipulated) 082 */ 083 public <T extends Event> Collection<EventListener<? super T>> getEventListeners(final EventType<T> eventType) { 084 final List<EventListener<? super T>> result = new LinkedList<>(); 085 eventListeners.getEventListeners(eventType).forEach(result::add); 086 return Collections.unmodifiableCollection(result); 087 } 088 089 /** 090 * Gets a list with all {@code EventListenerRegistrationData} objects currently contained for this event source. This 091 * method allows access to all registered event listeners, independent on their type. 092 * 093 * @return a list with information about all registered event listeners 094 */ 095 public List<EventListenerRegistrationData<?>> getEventListenerRegistrations() { 096 return eventListeners.getRegistrations(); 097 } 098 099 /** 100 * Returns a flag whether detail events are enabled. 101 * 102 * @return a flag if detail events are generated 103 */ 104 public boolean isDetailEvents() { 105 return checkDetailEvents(0); 106 } 107 108 /** 109 * Determines whether detail events should be generated. If enabled, some methods can generate multiple update events. 110 * Note that this method records the number of calls, i.e. if for instance {@code setDetailEvents(false)} was called 111 * three times, you will have to invoke the method as often to enable the details. 112 * 113 * @param enable a flag if detail events should be enabled or disabled 114 */ 115 public void setDetailEvents(final boolean enable) { 116 synchronized (lockDetailEventsCount) { 117 if (enable) { 118 detailEvents++; 119 } else { 120 detailEvents--; 121 } 122 } 123 } 124 125 @Override 126 public <T extends Event> void addEventListener(final EventType<T> eventType, final EventListener<? super T> listener) { 127 eventListeners.addEventListener(eventType, listener); 128 } 129 130 @Override 131 public <T extends Event> boolean removeEventListener(final EventType<T> eventType, final EventListener<? super T> listener) { 132 return eventListeners.removeEventListener(eventType, listener); 133 } 134 135 /** 136 * Removes all registered event listeners. 137 */ 138 public void clearEventListeners() { 139 eventListeners.clear(); 140 } 141 142 /** 143 * Removes all registered error listeners. 144 * 145 * @since 1.4 146 */ 147 public void clearErrorListeners() { 148 eventListeners.getRegistrationsForSuperType(ConfigurationErrorEvent.ANY).forEach(eventListeners::removeEventListener); 149 } 150 151 /** 152 * Copies all event listener registrations maintained by this object to the specified {@code BaseEventSource} object. 153 * 154 * @param source the target source for the copy operation (must not be <b>null</b>) 155 * @throws IllegalArgumentException if the target source is <b>null</b> 156 * @since 2.0 157 */ 158 public void copyEventListeners(final BaseEventSource source) { 159 if (source == null) { 160 throw new IllegalArgumentException("Target event source must not be null!"); 161 } 162 source.eventListeners.addAll(eventListeners); 163 } 164 165 /** 166 * Creates an event object and delivers it to all registered event listeners. The method checks first if sending an 167 * event is allowed (making use of the {@code detailEvents} property), and if listeners are registered. 168 * 169 * @param type the event's type 170 * @param propName the name of the affected property (can be <b>null</b>) 171 * @param propValue the value of the affected property (can be <b>null</b>) 172 * @param before the before update flag 173 * @param <T> the type of the event to be fired 174 */ 175 protected <T extends ConfigurationEvent> void fireEvent(final EventType<T> type, final String propName, final Object propValue, final boolean before) { 176 if (checkDetailEvents(-1)) { 177 final EventListenerList.EventListenerIterator<T> it = eventListeners.getEventListenerIterator(type); 178 if (it.hasNext()) { 179 final ConfigurationEvent event = createEvent(type, propName, propValue, before); 180 while (it.hasNext()) { 181 it.invokeNext(event); 182 } 183 } 184 } 185 } 186 187 /** 188 * Creates a {@code ConfigurationEvent} object based on the passed in parameters. This method is called by 189 * {@code fireEvent()} if it decides that an event needs to be generated. 190 * 191 * @param type the event's type 192 * @param propName the name of the affected property (can be <b>null</b>) 193 * @param propValue the value of the affected property (can be <b>null</b>) 194 * @param before the before update flag 195 * @param <T> the type of the event to be created 196 * @return the newly created event object 197 */ 198 protected <T extends ConfigurationEvent> ConfigurationEvent createEvent(final EventType<T> type, final String propName, final Object propValue, 199 final boolean before) { 200 return new ConfigurationEvent(this, type, propName, propValue, before); 201 } 202 203 /** 204 * Creates an error event object and delivers it to all registered error listeners of a matching type. 205 * 206 * @param eventType the event's type 207 * @param operationType the type of the failed operation 208 * @param propertyName the name of the affected property (can be <b>null</b>) 209 * @param propertyValue the value of the affected property (can be <b>null</b>) 210 * @param cause the {@code Throwable} object that caused this error event 211 * @param <T> the event type 212 */ 213 public <T extends ConfigurationErrorEvent> void fireError(final EventType<T> eventType, final EventType<?> operationType, final String propertyName, 214 final Object propertyValue, final Throwable cause) { 215 final EventListenerList.EventListenerIterator<T> iterator = eventListeners.getEventListenerIterator(eventType); 216 if (iterator.hasNext()) { 217 final ConfigurationErrorEvent event = createErrorEvent(eventType, operationType, propertyName, propertyValue, cause); 218 while (iterator.hasNext()) { 219 iterator.invokeNext(event); 220 } 221 } 222 } 223 224 /** 225 * Creates a {@code ConfigurationErrorEvent} object based on the passed in parameters. This is called by 226 * {@code fireError()} if it decides that an event needs to be generated. 227 * 228 * @param type the event's type 229 * @param opType the operation type related to this error 230 * @param propName the name of the affected property (can be <b>null</b>) 231 * @param propValue the value of the affected property (can be <b>null</b>) 232 * @param ex the {@code Throwable} object that caused this error event 233 * @return the event object 234 */ 235 protected ConfigurationErrorEvent createErrorEvent(final EventType<? extends ConfigurationErrorEvent> type, final EventType<?> opType, 236 final String propName, final Object propValue, final Throwable ex) { 237 return new ConfigurationErrorEvent(this, type, opType, propName, propValue, ex); 238 } 239 240 /** 241 * Overrides the {@code clone()} method to correctly handle so far registered event listeners. This implementation 242 * ensures that the clone will have empty event listener lists, i.e. the listeners registered at an 243 * {@code BaseEventSource} object will not be copied. 244 * 245 * @return the cloned object 246 * @throws CloneNotSupportedException if cloning is not allowed 247 * @since 1.4 248 */ 249 @Override 250 protected Object clone() throws CloneNotSupportedException { 251 final BaseEventSource copy = (BaseEventSource) super.clone(); 252 copy.initListeners(); 253 return copy; 254 } 255 256 /** 257 * Initializes the collections for storing registered event listeners. 258 */ 259 private void initListeners() { 260 eventListeners = new EventListenerList(); 261 } 262 263 /** 264 * Helper method for checking the current counter for detail events. This method checks whether the counter is greater 265 * than the passed in limit. 266 * 267 * @param limit the limit to be compared to 268 * @return <b>true</b> if the counter is greater than the limit, <b>false</b> otherwise 269 */ 270 private boolean checkDetailEvents(final int limit) { 271 synchronized (lockDetailEventsCount) { 272 return detailEvents > limit; 273 } 274 } 275}