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.configuration2.event; 18 19 /** 20 * <p> 21 * An event class for reporting updates on a configuration object. 22 * </p> 23 * <p> 24 * Event objects of this type are used for "raw" events, i.e. unfiltered modifications of any kind. A level 25 * with semantically higher events (e.g. for property changes) may be built on top of this fundamental event mechanism. 26 * </p> 27 * <p> 28 * Each event can contain the following data: 29 * </p> 30 * <ul> 31 * <li>A source object, which is usually the configuration object that was modified.</li> 32 * <li>The event's type. This is an object that corresponds to constant declarations in specific event classes. It 33 * describes what exactly has happened.</li> 34 * <li>If available, the name of the property whose modification caused the event.</li> 35 * <li>If available, the value of the property that caused this event.</li> 36 * <li>A flag whether this event was generated before or after the update of the source configuration. A modification of 37 * a configuration typically causes two events: one event before and one event after the modification is performed. This 38 * allows event listeners to react at the correct point of time.</li> 39 * </ul> 40 * <p> 41 * The following standard events are generated by typical configuration implementations (the constants for the event 42 * types are defined in this class: 43 * </p> 44 * <dl> 45 * <dt>ADD_PROPERTY</dt> 46 * <dd>This event is triggered for each call of the {@code addProperty()} method of a configuration object. It contains 47 * the name of the property, to which new data is added, and the value object that is added to this property (this may 48 * be an array or a list if multiple values are added).</dd> 49 * <dt>SET_PROPERTY</dt> 50 * <dd>Calling the {@code setProperty()} method triggers this event. The event object stores the name of the affected 51 * property and its new value.</dd> 52 * <dt>CLEAR_PROPERTY</dt> 53 * <dd>If a property is removed from a configuration (by calling the {@code clearProperty()} method), an event of this 54 * type is fired. In this case the event object only stores the name of the removed property, the value is 55 * <b>null</b>.</dd> 56 * <dt>CLEAR</dt> 57 * <dd>This event is fired when the whole configuration is cleared. The corresponding event object contains no 58 * additional data.</dd> 59 * </dl> 60 * 61 * @since 1.3 62 */ 63 public class ConfigurationEvent extends Event { 64 /** 65 * Constant for the common super type of all configuration update events. 66 * 67 * @since 2.0 68 */ 69 public static final EventType<ConfigurationEvent> ANY = new EventType<>(Event.ANY, "CONFIGURATION_UPDATE"); 70 71 /** 72 * Constant for the event type for an add property operation. 73 * 74 * @since 2.0 75 */ 76 public static final EventType<ConfigurationEvent> ADD_PROPERTY = new EventType<>(ANY, "ADD_PROPERTY"); 77 78 /** 79 * Constant for the event type for a set property operation. 80 * 81 * @since 2.0 82 */ 83 public static final EventType<ConfigurationEvent> SET_PROPERTY = new EventType<>(ANY, "SET_PROPERTY"); 84 85 /** 86 * Constant for the event type for a clear property operation. 87 * 88 * @since 2.0 89 */ 90 public static final EventType<ConfigurationEvent> CLEAR_PROPERTY = new EventType<>(ANY, "CLEAR_PROPERTY"); 91 92 /** 93 * Constant for the event type for a clear operation. 94 * 95 * @since 2.0 96 */ 97 public static final EventType<ConfigurationEvent> CLEAR = new EventType<>(ANY, "CLEAR"); 98 99 /** 100 * Constant for the common base event type for all hierarchical update events. Events derived from this type are 101 * generated by some specific methods of hierarchical configurations. 102 * 103 * @since 2.0 104 */ 105 public static final EventType<ConfigurationEvent> ANY_HIERARCHICAL = new EventType<>(ANY, "HIERARCHICAL"); 106 107 /** 108 * Constant for the event type for an add nodes operation. 109 * 110 * @since 2.0 111 */ 112 public static final EventType<ConfigurationEvent> ADD_NODES = new EventType<>(ANY_HIERARCHICAL, "ADD_NODES"); 113 114 /** 115 * Constant for the event type for a clear tree operation. 116 * 117 * @since 2.0 118 */ 119 public static final EventType<ConfigurationEvent> CLEAR_TREE = new EventType<>(ANY_HIERARCHICAL, "CLEAR_TREE"); 120 121 /** 122 * Constant for the event type indicating a change on a sub configuration. 123 * 124 * @since 2.0 125 */ 126 public static final EventType<ConfigurationEvent> SUBNODE_CHANGED = new EventType<>(ANY_HIERARCHICAL, "SUBNODE_CHANGED"); 127 128 /** 129 * The serial version UID. 130 */ 131 private static final long serialVersionUID = 20140703L; 132 133 /** Stores the property name. */ 134 private final String propertyName; 135 136 /** Stores the property value. */ 137 private final Object propertyValue; 138 139 /** Stores the before update flag. */ 140 private final boolean beforeUpdate; 141 142 /** 143 * Creates a new instance of {@code ConfigurationEvent} and initializes it. 144 * 145 * @param source the event source 146 * @param type the event's type 147 * @param propertyName the name of the affected property 148 * @param propertyValue the value of the affected property 149 * @param beforeUpdate the before update flag 150 */ 151 public ConfigurationEvent(final Object source, final EventType<? extends ConfigurationEvent> type, final String propertyName, final Object propertyValue, 152 final boolean beforeUpdate) { 153 super(source, type); 154 this.propertyName = propertyName; 155 this.propertyValue = propertyValue; 156 this.beforeUpdate = beforeUpdate; 157 } 158 159 /** 160 * Gets the name of the affected property. This can be <b>null</b> if no property change has lead to this event. 161 * 162 * @return the name of the property 163 */ 164 public String getPropertyName() { 165 return propertyName; 166 } 167 168 /** 169 * Gets the value of the affected property if available. 170 * 171 * @return the value of the property; can be <b>null</b> 172 */ 173 public Object getPropertyValue() { 174 return propertyValue; 175 } 176 177 /** 178 * Returns a flag if this event was generated before or after an update. 179 * 180 * @return <b>true</b> if this event was generated before an update; <b>false</b> otherwise 181 */ 182 public boolean isBeforeUpdate() { 183 return beforeUpdate; 184 } 185 }