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.configuration.event; 18 19 import java.util.EventObject; 20 21 /** 22 * <p> 23 * An event class for reporting updates on a configuration object. 24 * </p> 25 * <p> 26 * Event objects of this type are used for "raw" events, i.e. 27 * unfiltered modifications of any kind. A level with semantically higher events 28 * (e.g. for property changes) may be built on top of this fundamental event 29 * mechanism. 30 * </p> 31 * <p> 32 * Each event can contain the following data: 33 * <ul> 34 * <li>A source object, which is usually the configuration object that was 35 * modified.</li> 36 * <li>The event's type. This is a numeric value that corresponds to constant 37 * declarations in concrete configuration classes. It describes what exactly has 38 * happended.</li> 39 * <li>If available, the name of the property whose modification caused the 40 * event.</li> 41 * <li>If available, the value of the property that caused this event.</li> 42 * <li>A flag whether this event was generated before or after the update of 43 * the source configuration. A modification of a configuration typically causes 44 * two events: one event before and one event after the modification is 45 * performed. This allows event listeners to react at the correct point of time.</li> 46 * </ul> 47 * </p> 48 * <p> 49 * The following standard events are generated by typical configuration 50 * implementations (the constants for the event types are defined in 51 * {@link org.apache.commons.configuration.AbstractConfiguration}): 52 * <dl> 53 * <dt>EVENT_ADD_PROPERTY</dt> 54 * <dd>This event is triggered for each call of the {@code addProperty()} 55 * method of a configuration object. It contains the name of the property, to 56 * which new data is added, and the value object that is added to this property 57 * (this may be an array or a list if multiple values are added).</dd> 58 * <dt>EVENT_SET_PROPERTY</dt> 59 * <dd>Calling the {@code setProperty()} method triggers this event. The 60 * event object stores the name of the affected property and its new value.</dd> 61 * <dt>EVENT_CLEAR_PROPERTY</dt> 62 * <dd>If a property is removed from a configuration (by calling the 63 * {@code clearProperty()} method), an event of this type is fired. In 64 * this case the event object only stores the name of the removed property, the 65 * value is <b>null</b>.</dd> 66 * <dt>EVENT_CLEAR</dt> 67 * <dd>This event is fired when the whole configuration is cleared. The 68 * corresponding event object contains no additional data.</dd> 69 * </dl> 70 * </p> 71 * 72 * @author <a 73 * href="http://commons.apache.org/configuration/team-list.html">Commons 74 * Configuration team</a> 75 * @version $Id: ConfigurationEvent.java 1207610 2011-11-28 21:06:22Z oheger $ 76 * @since 1.3 77 */ 78 public class ConfigurationEvent extends EventObject 79 { 80 /** 81 * The serial version UID. 82 */ 83 private static final long serialVersionUID = 3277238219073504136L; 84 85 /** Stores the event type. */ 86 private int type; 87 88 /** Stores the property name. */ 89 private String propertyName; 90 91 /** Stores the property value. */ 92 private Object propertyValue; 93 94 /** Stores the before update flag. */ 95 private boolean beforeUpdate; 96 97 /** 98 * Creates a new instance of {@code ConfigurationEvent} and 99 * initializes it. 100 * 101 * @param source the event source 102 * @param type the event's type 103 * @param propertyName the name of the affected property 104 * @param propertyValue the value of the affected property 105 * @param beforeUpdate the before update flag 106 */ 107 public ConfigurationEvent(Object source, int type, String propertyName, 108 Object propertyValue, boolean beforeUpdate) 109 { 110 super(source); 111 this.type = type; 112 this.propertyName = propertyName; 113 this.propertyValue = propertyValue; 114 this.beforeUpdate = beforeUpdate; 115 } 116 117 /** 118 * Returns the name of the affected property. This can be <b>null</b> if no 119 * property change has lead to this event. 120 * 121 * @return the name of the property 122 */ 123 public String getPropertyName() 124 { 125 return propertyName; 126 } 127 128 /** 129 * Returns the value of the affected property if available. 130 * 131 * @return the value of the property; can be <b>null</b> 132 */ 133 public Object getPropertyValue() 134 { 135 return propertyValue; 136 } 137 138 /** 139 * Returns the type of this event. This describes the update process that 140 * caused this event. 141 * 142 * @return the event's type 143 */ 144 public int getType() 145 { 146 return type; 147 } 148 149 /** 150 * Returns a flag if this event was generated before or after an update. 151 * 152 * @return <b>true</b> if this event was generated before an update; 153 * <b>false</b> otherwise 154 */ 155 public boolean isBeforeUpdate() 156 { 157 return beforeUpdate; 158 } 159 }