1 /*
2 * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.beans;
27
28 import java.util.EventObject;
29
30 /**
31 * A "PropertyChange" event gets delivered whenever a bean changes a "bound"
32 * or "constrained" property. A PropertyChangeEvent object is sent as an
33 * argument to the PropertyChangeListener and VetoableChangeListener methods.
34 * <P>
35 * Normally PropertyChangeEvents are accompanied by the name and the old
36 * and new value of the changed property. If the new value is a primitive
37 * type (such as int or boolean) it must be wrapped as the
38 * corresponding java.lang.* Object type (such as Integer or Boolean).
39 * <P>
40 * Null values may be provided for the old and the new values if their
41 * true values are not known.
42 * <P>
43 * An event source may send a null object as the name to indicate that an
44 * arbitrary set of if its properties have changed. In this case the
45 * old and new values should also be null.
46 *
47 * @since 1.1
48 */
49 public class PropertyChangeEvent extends EventObject {
50 private static final long serialVersionUID = 7042693688939648123L;
51
52 /**
53 * Constructs a new {@code PropertyChangeEvent}.
54 *
55 * @param source the bean that fired the event
56 * @param propertyName the programmatic name of the property that was changed
57 * @param oldValue the old value of the property
58 * @param newValue the new value of the property
59 *
60 * @throws IllegalArgumentException if {@code source} is {@code null}
61 */
62 public PropertyChangeEvent(Object source, String propertyName,
63 Object oldValue, Object newValue) {
64 super(source);
65 this.propertyName = propertyName;
66 this.newValue = newValue;
67 this.oldValue = oldValue;
68 }
69
70 /**
71 * Gets the programmatic name of the property that was changed.
72 *
73 * @return The programmatic name of the property that was changed.
74 * May be null if multiple properties have changed.
75 */
76 public String getPropertyName() {
77 return propertyName;
78 }
79
80 /**
81 * Gets the new value for the property, expressed as an Object.
82 *
83 * @return The new value for the property, expressed as an Object.
84 * May be null if multiple properties have changed.
85 */
86 public Object getNewValue() {
87 return newValue;
88 }
89
90 /**
91 * Gets the old value for the property, expressed as an Object.
92 *
93 * @return The old value for the property, expressed as an Object.
94 * May be null if multiple properties have changed.
95 */
96 public Object getOldValue() {
97 return oldValue;
98 }
99
100 /**
101 * Sets the propagationId object for the event.
102 *
103 * @param propagationId The propagationId object for the event.
104 */
105 public void setPropagationId(Object propagationId) {
106 this.propagationId = propagationId;
107 }
108
109 /**
110 * The "propagationId" field is reserved for future use. In Beans 1.0
111 * the sole requirement is that if a listener catches a PropertyChangeEvent
112 * and then fires a PropertyChangeEvent of its own, then it should
113 * make sure that it propagates the propagationId field from its
114 * incoming event to its outgoing event.
115 *
116 * @return the propagationId object associated with a bound/constrained
117 * property update.
118 */
119 public Object getPropagationId() {
120 return propagationId;
121 }
122
123 /**
124 * name of the property that changed. May be null, if not known.
125 * @serial
126 */
127 private String propertyName;
128
129 /**
130 * New value for property. May be null if not known.
131 * @serial
132 */
133 private Object newValue;
134
135 /**
136 * Previous value for property. May be null if not known.
137 * @serial
138 */
139 private Object oldValue;
140
141 /**
142 * Propagation ID. May be null.
143 * @serial
144 * @see #getPropagationId
145 */
146 private Object propagationId;
147
148 /**
149 * Returns a string representation of the object.
150 *
151 * @return a string representation of the object
152 *
153 * @since 1.7
154 */
155 public String toString() {
156 StringBuilder sb = new StringBuilder(getClass().getName());
157 sb.append("[propertyName=").append(getPropertyName());
158 appendTo(sb);
159 sb.append("; oldValue=").append(getOldValue());
160 sb.append("; newValue=").append(getNewValue());
161 sb.append("; propagationId=").append(getPropagationId());
162 sb.append("; source=").append(getSource());
163 return sb.append("]").toString();
164 }
165
166 void appendTo(StringBuilder sb) {
167 }
168 }