libjava/java/beans/PropertyChangeEvent.java

   1 /* PropertyChangeEvent.java -- describes a change in a property
   2    Copyright (C) 1998, 2000, 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.beans;
  40
  41 import java.util.EventObject;
  42
  43 /**
  44  * PropertyChangeEvents are fired in the PropertyChange and VetoableChange
  45  * event classes.  They represent the old and new values as well as the
  46  * source Bean. If the old or new value is a primitive type, it must be
  47  * wrapped in the appropriate wrapper type (java.lang.Integer for int, etc.,
  48  * etc.).
  49  *
  50  * <p>If the old or new values are unknown (although why that would be I do
  51  * not know), they may be null. Also, if the set of properties itself has
  52  * changed, the name should be null, and the old and new values may also be
  53  * null. Right now Sun put in a propagationId, reserved for future use. Read
  54  * the comments on the constructor and on setPropagationId for more
  55  * information.
  56  *
  57  * @author John Keiser
  58  * @author Eric Blake (ebb9@email.byu.edu)
  59  * @since 1.1
  60  * @status udpated to 1.4
  61  */
  62 public class PropertyChangeEvent extends EventObject
  63 {
  64   /**
  65    * Compatible with JDK 1.1+.
  66    */
  67   private static final long serialVersionUID = 7042693688939648123L;
  68
  69   /**
  70    * The name of the property that changed, may be null. Package visible for
  71    * use by PropertyChangeSupport.
  72    *
  73    * @serial the changed property name
  74    */
  75   final String propertyName;
  76
  77   /**
  78    * The new value of the property, may be null. Package visible for use by
  79    * PropertyChangeSupport.
  80    *
  81    * @serial the new property value
  82    */
  83   final Object newValue;
  84
  85   /**
  86    * The old value of the property, may be null. Package visible for use by
  87    * PropertyChangeSupport.
  88    *
  89    * @serial the old property value
  90    */
  91   final Object oldValue;
  92
  93   /**
  94    * The propagation ID, reserved for future use. May be null.
  95    *
  96    * @see #getPropagationId()
  97    * @serial the Propagation ID
  98    */
  99   private Object propagationId;
 100
 101   /**
 102    * Create a new PropertyChangeEvent. Remember that if you received a
 103    * PropertyChangeEvent and are sending a new one, you should also set the
 104    * propagation ID from the old PropertyChangeEvent.
 105    *
 106    * @param source the Bean containing the property
 107    * @param propertyName the property's name
 108    * @param oldVal the old value of the property
 109    * @param newVal the new value of the property
 110    * @throws IllegalArgumentException if source is null
 111    */
 112   public PropertyChangeEvent(Object source, String propertyName,
 113                              Object oldVal, Object newVal)
 114   {
 115     super(source);
 116     this.propertyName = propertyName;
 117     oldValue = oldVal;
 118     newValue = newVal;
 119   }
 120
 121   /**
 122    * Get the property name. May be null if multiple properties changed.
 123    *
 124    * @return the property name
 125    */
 126   public String getPropertyName()
 127   {
 128     return propertyName;
 129   }
 130
 131   /**
 132    * Get the property's new value. May be null if multiple properties changed.
 133    *
 134    * @return the property's new value
 135    */
 136   public Object getNewValue()
 137   {
 138     return newValue;
 139   }
 140
 141   /**
 142    * Get the property's old value. May be null if multiple properties changed.
 143    *
 144    * @return the property's old value
 145    */
 146   public Object getOldValue()
 147   {
 148     return oldValue;
 149   }
 150
 151   /**
 152    * Set the propagation ID.  This is a way for the event to be passed from
 153    * hand to hand and retain a little extra state.  Right now it is unused,
 154    * but it should be propagated anyway so that future versions of JavaBeans
 155    * can use it, for God knows what.
 156    *
 157    * @param propagationId the propagation ID
 158    * @see #getPropagationId()
 159    */
 160   public void setPropagationId(Object propagationId)
 161   {
 162     this.propagationId = propagationId;
 163   }
 164
 165   /**
 166    * Get the propagation ID. Right now, it is not used for anything.
 167    *
 168    * @return the propagation ID
 169    * @see #setPropagationId(Object)
 170    */
 171   public Object getPropagationId()
 172   {
 173     return propagationId;
 174   }
 175
 176   /**
 177    * Utility method to rollback a change.
 178    *
 179    * @param event the event to rollback
 180    * @return a new event with old and new swapped
 181    */
 182   PropertyChangeEvent rollback()
 183   {
 184     PropertyChangeEvent result
 185       = new PropertyChangeEvent(source, propertyName, newValue, oldValue);
 186     result.propagationId = propagationId;
 187     return result;
 188   }
 189 } // class PropertyChangeEvent