1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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 * <code>{@link org.apache.commons.configuration.AbstractConfiguration}</code>):
52 * <dl>
53 * <dt>EVENT_ADD_PROPERTY</dt>
54 * <dd>This event is triggered for each call of the <code>addProperty()</code>
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()</code> 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()</code> 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://jakarta.apache.org/commons/configuration/team-list.html">Commons
74 * Configuration team</a>
75 * @version $Id: ConfigurationEvent.java 443105 2006-09-13 20:04:01Z 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</code> 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 }