View Javadoc
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  public class PropertyChangeEvent extends EventObject {
48      private static final long serialVersionUID = 7042693688939648123L;
49  
50      /**
51       * Constructs a new {@code PropertyChangeEvent}.
52       *
53       * @param source        the bean that fired the event
54       * @param propertyName  the programmatic name of the property that was changed
55       * @param oldValue      the old value of the property
56       * @param newValue      the new value of the property
57       *
58       * @throws IllegalArgumentException if {@code source} is {@code null}
59       */
60      public PropertyChangeEvent(Object source, String propertyName,
61                                 Object oldValue, Object newValue) {
62          super(source);
63          this.propertyName = propertyName;
64          this.newValue = newValue;
65          this.oldValue = oldValue;
66      }
67  
68      /**
69       * Gets the programmatic name of the property that was changed.
70       *
71       * @return  The programmatic name of the property that was changed.
72       *          May be null if multiple properties have changed.
73       */
74      public String getPropertyName() {
75          return propertyName;
76      }
77  
78      /**
79       * Gets the new value for the property, expressed as an Object.
80       *
81       * @return  The new value for the property, expressed as an Object.
82       *          May be null if multiple properties have changed.
83       */
84      public Object getNewValue() {
85          return newValue;
86      }
87  
88      /**
89       * Gets the old value for the property, expressed as an Object.
90       *
91       * @return  The old value for the property, expressed as an Object.
92       *          May be null if multiple properties have changed.
93       */
94      public Object getOldValue() {
95          return oldValue;
96      }
97  
98      /**
99       * Sets the propagationId object for the event.
100      *
101      * @param propagationId  The propagationId object for the event.
102      */
103     public void setPropagationId(Object propagationId) {
104         this.propagationId = propagationId;
105     }
106 
107     /**
108      * The "propagationId" field is reserved for future use.  In Beans 1.0
109      * the sole requirement is that if a listener catches a PropertyChangeEvent
110      * and then fires a PropertyChangeEvent of its own, then it should
111      * make sure that it propagates the propagationId field from its
112      * incoming event to its outgoing event.
113      *
114      * @return the propagationId object associated with a bound/constrained
115      *          property update.
116      */
117     public Object getPropagationId() {
118         return propagationId;
119     }
120 
121     /**
122      * name of the property that changed.  May be null, if not known.
123      * @serial
124      */
125     private String propertyName;
126 
127     /**
128      * New value for property.  May be null if not known.
129      * @serial
130      */
131     private Object newValue;
132 
133     /**
134      * Previous value for property.  May be null if not known.
135      * @serial
136      */
137     private Object oldValue;
138 
139     /**
140      * Propagation ID.  May be null.
141      * @serial
142      * @see #getPropagationId
143      */
144     private Object propagationId;
145 
146     /**
147      * Returns a string representation of the object.
148      *
149      * @return a string representation of the object
150      *
151      * @since 1.7
152      */
153     public String toString() {
154         StringBuilder sb = new StringBuilder(getClass().getName());
155         sb.append("[propertyName=").append(getPropertyName());
156         appendTo(sb);
157         sb.append("; oldValue=").append(getOldValue());
158         sb.append("; newValue=").append(getNewValue());
159         sb.append("; propagationId=").append(getPropagationId());
160         sb.append("; source=").append(getSource());
161         return sb.append("]").toString();
162     }
163 
164     void appendTo(StringBuilder sb) {
165     }
166 }