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
26package java.beans;
27
28import 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 */
49public 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}
169