1 /* 2 * Copyright (c) 1996, 2010, 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 /** 29 * A "PropertyChange" event gets delivered whenever a bean changes a "bound" 30 * or "constrained" property. A PropertyChangeEvent object is sent as an 31 * argument to the PropertyChangeListener and VetoableChangeListener methods. 32 * <P> 33 * Normally PropertyChangeEvents are accompanied by the name and the old 34 * and new value of the changed property. If the new value is a primitive 35 * type (such as int or boolean) it must be wrapped as the 36 * corresponding java.lang.* Object type (such as Integer or Boolean). 37 * <P> 38 * Null values may be provided for the old and the new values if their 39 * true values are not known. 40 * <P> 41 * An event source may send a null object as the name to indicate that an 42 * arbitrary set of if its properties have changed. In this case the 43 * old and new values should also be null. 44 */ 45 46 public class PropertyChangeEvent extends java.util.EventObject { 47 private static final long serialVersionUID = 7042693688939648123L; 48 49 /** 50 * Constructs a new <code>PropertyChangeEvent</code>. 51 * 52 * @param source The bean that fired the event. 53 * @param propertyName The programmatic name of the property 54 * that was changed. 55 * @param oldValue The old value of the property. 56 * @param newValue The new value of the property. 57 */ PropertyChangeEvent(Object source, String propertyName, Object oldValue, Object newValue)58 public PropertyChangeEvent(Object source, String propertyName, 59 Object oldValue, Object newValue) { 60 super(source); 61 this.propertyName = propertyName; 62 this.newValue = newValue; 63 this.oldValue = oldValue; 64 } 65 66 /** 67 * Gets the programmatic name of the property that was changed. 68 * 69 * @return The programmatic name of the property that was changed. 70 * May be null if multiple properties have changed. 71 */ getPropertyName()72 public String getPropertyName() { 73 return propertyName; 74 } 75 76 /** 77 * Gets the new value for the property, expressed as an Object. 78 * 79 * @return The new value for the property, expressed as an Object. 80 * May be null if multiple properties have changed. 81 */ getNewValue()82 public Object getNewValue() { 83 return newValue; 84 } 85 86 /** 87 * Gets the old value for the property, expressed as an Object. 88 * 89 * @return The old value for the property, expressed as an Object. 90 * May be null if multiple properties have changed. 91 */ getOldValue()92 public Object getOldValue() { 93 return oldValue; 94 } 95 96 /** 97 * Sets the propagationId object for the event. 98 * 99 * @param propagationId The propagationId object for the event. 100 */ setPropagationId(Object propagationId)101 public void setPropagationId(Object propagationId) { 102 this.propagationId = propagationId; 103 } 104 105 /** 106 * The "propagationId" field is reserved for future use. In Beans 1.0 107 * the sole requirement is that if a listener catches a PropertyChangeEvent 108 * and then fires a PropertyChangeEvent of its own, then it should 109 * make sure that it propagates the propagationId field from its 110 * incoming event to its outgoing event. 111 * 112 * @return the propagationId object associated with a bound/constrained 113 * property update. 114 */ getPropagationId()115 public Object getPropagationId() { 116 return propagationId; 117 } 118 119 /** 120 * name of the property that changed. May be null, if not known. 121 * @serial 122 */ 123 private String propertyName; 124 125 /** 126 * New value for property. May be null if not known. 127 * @serial 128 */ 129 private Object newValue; 130 131 /** 132 * Previous value for property. May be null if not known. 133 * @serial 134 */ 135 private Object oldValue; 136 137 /** 138 * Propagation ID. May be null. 139 * @serial 140 * @see #getPropagationId 141 */ 142 private Object propagationId; 143 144 /** 145 * Returns a string representation of the object. 146 * 147 * @return a string representation of the object 148 * 149 * @since 1.7 150 */ toString()151 public String toString() { 152 StringBuilder sb = new StringBuilder(getClass().getName()); 153 sb.append("[propertyName=").append(getPropertyName()); 154 appendTo(sb); 155 sb.append("; oldValue=").append(getOldValue()); 156 sb.append("; newValue=").append(getNewValue()); 157 sb.append("; propagationId=").append(getPropagationId()); 158 sb.append("; source=").append(getSource()); 159 return sb.append("]").toString(); 160 } 161 appendTo(StringBuilder sb)162 void appendTo(StringBuilder sb) { 163 } 164 } 165