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 019/** 020 * <p> 021 * An event class for reporting updates on a configuration object. 022 * </p> 023 * <p> 024 * Event objects of this type are used for "raw" events, i.e. 025 * unfiltered modifications of any kind. A level with semantically higher events 026 * (e.g. for property changes) may be built on top of this fundamental event 027 * mechanism. 028 * </p> 029 * <p> 030 * Each event can contain the following data: 031 * </p> 032 * <ul> 033 * <li>A source object, which is usually the configuration object that was 034 * modified.</li> 035 * <li>The event's type. This is an object that corresponds to constant 036 * declarations in specific event classes. It describes what exactly has 037 * happened.</li> 038 * <li>If available, the name of the property whose modification caused the 039 * event.</li> 040 * <li>If available, the value of the property that caused this event.</li> 041 * <li>A flag whether this event was generated before or after the update of 042 * the source configuration. A modification of a configuration typically causes 043 * two events: one event before and one event after the modification is 044 * performed. This allows event listeners to react at the correct point of time.</li> 045 * </ul> 046 * <p> 047 * The following standard events are generated by typical configuration 048 * implementations (the constants for the event types are defined in 049 * this class: 050 * </p> 051 * <dl> 052 * <dt>ADD_PROPERTY</dt> 053 * <dd>This event is triggered for each call of the {@code addProperty()} 054 * method of a configuration object. It contains the name of the property, to 055 * which new data is added, and the value object that is added to this property 056 * (this may be an array or a list if multiple values are added).</dd> 057 * <dt>SET_PROPERTY</dt> 058 * <dd>Calling the {@code setProperty()} method triggers this event. The 059 * event object stores the name of the affected property and its new value.</dd> 060 * <dt>CLEAR_PROPERTY</dt> 061 * <dd>If a property is removed from a configuration (by calling the 062 * {@code clearProperty()} method), an event of this type is fired. In 063 * this case the event object only stores the name of the removed property, the 064 * value is <b>null</b>.</dd> 065 * <dt>CLEAR</dt> 066 * <dd>This event is fired when the whole configuration is cleared. The 067 * corresponding event object contains no additional data.</dd> 068 * </dl> 069 * 070 * @version $Id: ConfigurationEvent.java 1790899 2017-04-10 21:56:46Z ggregory $ 071 * @since 1.3 072 */ 073public class ConfigurationEvent extends Event 074{ 075 /** 076 * Constant for the common super type of all configuration update events. 077 * 078 * @since 2.0 079 */ 080 public static final EventType<ConfigurationEvent> ANY = 081 new EventType<>(Event.ANY, "CONFIGURATION_UPDATE"); 082 083 /** 084 * Constant for the event type for an add property operation. 085 * 086 * @since 2.0 087 */ 088 public static final EventType<ConfigurationEvent> ADD_PROPERTY = 089 new EventType<>(ANY, "ADD_PROPERTY"); 090 091 /** 092 * Constant for the event type for a set property operation. 093 * 094 * @since 2.0 095 */ 096 public static final EventType<ConfigurationEvent> SET_PROPERTY = 097 new EventType<>(ANY, "SET_PROPERTY"); 098 099 /** 100 * Constant for the event type for a clear property operation. 101 * 102 * @since 2.0 103 */ 104 public static final EventType<ConfigurationEvent> CLEAR_PROPERTY = 105 new EventType<>(ANY, "CLEAR_PROPERTY"); 106 107 /** 108 * Constant for the event type for a clear operation. 109 * 110 * @since 2.0 111 */ 112 public static final EventType<ConfigurationEvent> CLEAR = 113 new EventType<>(ANY, "CLEAR"); 114 115 /** 116 * Constant for the common base event type for all hierarchical update 117 * events. Events derived from this type are generated by some specific 118 * methods of hierarchical configurations. 119 * 120 * @since 2.0 121 */ 122 public static final EventType<ConfigurationEvent> ANY_HIERARCHICAL = 123 new EventType<>(ANY, "HIERARCHICAL"); 124 125 /** 126 * Constant for the event type for an add nodes operation. 127 * 128 * @since 2.0 129 */ 130 public static final EventType<ConfigurationEvent> ADD_NODES = 131 new EventType<>(ANY_HIERARCHICAL, "ADD_NODES"); 132 133 /** 134 * Constant for the event type for a clear tree operation. 135 * 136 * @since 2.0 137 */ 138 public static final EventType<ConfigurationEvent> CLEAR_TREE = 139 new EventType<>(ANY_HIERARCHICAL, "CLEAR_TREE"); 140 141 /** 142 * Constant for the event type indicating a change on a sub configuration. 143 * 144 * @since 2.0 145 */ 146 public static final EventType<ConfigurationEvent> SUBNODE_CHANGED = 147 new EventType<>(ANY_HIERARCHICAL, 148 "SUBNODE_CHANGED"); 149 150 /** 151 * The serial version UID. 152 */ 153 private static final long serialVersionUID = 20140703L; 154 155 /** Stores the property name. */ 156 private final String propertyName; 157 158 /** Stores the property value. */ 159 private final Object propertyValue; 160 161 /** Stores the before update flag. */ 162 private final boolean beforeUpdate; 163 164 /** 165 * Creates a new instance of {@code ConfigurationEvent} and 166 * initializes it. 167 * 168 * @param source the event source 169 * @param type the event's type 170 * @param propertyName the name of the affected property 171 * @param propertyValue the value of the affected property 172 * @param beforeUpdate the before update flag 173 */ 174 public ConfigurationEvent(Object source, 175 EventType<? extends ConfigurationEvent> type, String propertyName, 176 Object propertyValue, boolean beforeUpdate) 177 { 178 super(source, type); 179 this.propertyName = propertyName; 180 this.propertyValue = propertyValue; 181 this.beforeUpdate = beforeUpdate; 182 } 183 184 /** 185 * Returns the name of the affected property. This can be <b>null</b> if no 186 * property change has lead to this event. 187 * 188 * @return the name of the property 189 */ 190 public String getPropertyName() 191 { 192 return propertyName; 193 } 194 195 /** 196 * Returns the value of the affected property if available. 197 * 198 * @return the value of the property; can be <b>null</b> 199 */ 200 public Object getPropertyValue() 201 { 202 return propertyValue; 203 } 204 205 /** 206 * Returns a flag if this event was generated before or after an update. 207 * 208 * @return <b>true</b> if this event was generated before an update; 209 * <b>false</b> otherwise 210 */ 211 public boolean isBeforeUpdate() 212 { 213 return beforeUpdate; 214 } 215}