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: */
017: package org.apache.commons.configuration.event;
018:
019: import java.util.EventObject;
020:
021: /**
022: * <p>
023: * An event class for reporting updates on a configuration object.
024: * </p>
025: * <p>
026: * Event objects of this type are used for "raw" events, i.e.
027: * unfiltered modifications of any kind. A level with semantically higher events
028: * (e.g. for property changes) may be built on top of this fundamental event
029: * mechanism.
030: * </p>
031: * <p>
032: * Each event can contain the following data:
033: * <ul>
034: * <li>A source object, which is usually the configuration object that was
035: * modified.</li>
036: * <li>The event's type. This is a numeric value that corresponds to constant
037: * declarations in concrete configuration classes. It describes what exactly has
038: * happended.</li>
039: * <li>If available, the name of the property whose modification caused the
040: * event.</li>
041: * <li>If available, the value of the property that caused this event.</li>
042: * <li>A flag whether this event was generated before or after the update of
043: * the source configuration. A modification of a configuration typically causes
044: * two events: one event before and one event after the modification is
045: * performed. This allows event listeners to react at the correct point of time.</li>
046: * </ul>
047: * </p>
048: * <p>
049: * The following standard events are generated by typical configuration
050: * implementations (the constants for the event types are defined in
051: * <code>{@link org.apache.commons.configuration.AbstractConfiguration}</code>):
052: * <dl>
053: * <dt>EVENT_ADD_PROPERTY</dt>
054: * <dd>This event is triggered for each call of the <code>addProperty()</code>
055: * method of a configuration object. It contains the name of the property, to
056: * which new data is added, and the value object that is added to this property
057: * (this may be an array or a list if multiple values are added).</dd>
058: * <dt>EVENT_SET_PROPERTY</dt>
059: * <dd>Calling the <code>setProperty()</code> method triggers this event. The
060: * event object stores the name of the affected property and its new value.</dd>
061: * <dt>EVENT_CLEAR_PROPERTY</dt>
062: * <dd>If a property is removed from a configuration (by calling the
063: * <code>clearProperty()</code> method), an event of this type is fired. In
064: * this case the event object only stores the name of the removed property, the
065: * value is <b>null</b>.</dd>
066: * <dt>EVENT_CLEAR</dt>
067: * <dd>This event is fired when the whole configuration is cleared. The
068: * corresponding event object contains no additional data.</dd>
069: * </dl>
070: * </p>
071: *
072: * @author <a
073: * href="http://jakarta.apache.org/commons/configuration/team-list.html">Commons
074: * Configuration team</a>
075: * @version $Id: ConfigurationEvent.java 443105 2006-09-13 20:04:01Z oheger $
076: * @since 1.3
077: */
078: public class ConfigurationEvent extends EventObject {
079: /**
080: * The serial version UID.
081: */
082: private static final long serialVersionUID = 3277238219073504136L;
083:
084: /** Stores the event type. */
085: private int type;
086:
087: /** Stores the property name. */
088: private String propertyName;
089:
090: /** Stores the property value. */
091: private Object propertyValue;
092:
093: /** Stores the before update flag. */
094: private boolean beforeUpdate;
095:
096: /**
097: * Creates a new instance of <code>ConfigurationEvent</code> and
098: * initializes it.
099: *
100: * @param source the event source
101: * @param type the event's type
102: * @param propertyName the name of the affected property
103: * @param propertyValue the value of the affected property
104: * @param beforeUpdate the before update flag
105: */
106: public ConfigurationEvent(Object source, int type,
107: String propertyName, Object propertyValue,
108: boolean beforeUpdate) {
109: super (source);
110: this .type = type;
111: this .propertyName = propertyName;
112: this .propertyValue = propertyValue;
113: this .beforeUpdate = beforeUpdate;
114: }
115:
116: /**
117: * Returns the name of the affected property. This can be <b>null</b> if no
118: * property change has lead to this event.
119: *
120: * @return the name of the property
121: */
122: public String getPropertyName() {
123: return propertyName;
124: }
125:
126: /**
127: * Returns the value of the affected property if available.
128: *
129: * @return the value of the property; can be <b>null</b>
130: */
131: public Object getPropertyValue() {
132: return propertyValue;
133: }
134:
135: /**
136: * Returns the type of this event. This describes the update process that
137: * caused this event.
138: *
139: * @return the event's type
140: */
141: public int getType() {
142: return type;
143: }
144:
145: /**
146: * Returns a flag if this event was generated before or after an update.
147: *
148: * @return <b>true</b> if this event was generated before an update;
149: * <b>false</b> otherwise
150: */
151: public boolean isBeforeUpdate() {
152: return beforeUpdate;
153: }
154: }
|