View Javadoc

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 &quot;raw&quot; 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 }