libjava/java/beans/beancontext/BeanContextChildSupport.java

   1 /* java.beans.beancontext.BeanContextChildSupport
   2    Copyright (C) 1999 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.beancontext;
  40
  41 import java.beans.PropertyChangeListener;
  42 import java.beans.VetoableChangeListener;
  43 import java.beans.PropertyVetoException;
  44 import java.beans.PropertyChangeEvent;
  45 import java.beans.PropertyChangeSupport;
  46 import java.beans.VetoableChangeSupport;
  47 import java.io.Serializable;
  48
  49 /**
  50  * Support for creating a <code>BeanContextChild</code>.
  51  * This class contains the most common implementations of the methods in
  52  * the <code>BeanContextChild</code>
  53  *
  54  * @specnote This class is not very well specified.  I had to "fill in the
  55  *           blanks" in most places with what I thought was reasonable
  56  *           behavior.  If there are problems, let me know.
  57  *
  58  * @author John Keiser
  59  * @since JDK1.2
  60  * @see java.beans.beancontext.BeanContextChild
  61  */
  62
  63 public class BeanContextChildSupport
  64   implements BeanContextChild, BeanContextServicesListener, Serializable
  65 {
  66   static final long serialVersionUID = 6328947014421475877L;
  67
  68         /**
  69          * The peer on which to perform <code>set</code> actions.
  70          * This is here so that this class can be used as a peer.
  71          * <P>
  72          *
  73          * When extending this class, this variable will be set to
  74          * <code>this</code>.
  75          */
  76         public BeanContextChild beanContextChildPeer;
  77
  78         /**
  79          * The parent <code>BeanContext</code>.
  80          */
  81         protected transient BeanContext beanContext;
  82
  83         /**
  84          * If <code>setBeanContext()</code> was vetoed once before, this
  85          * is set to <code>true</code> so that the next time, vetoes will
  86          * be ignored.
  87          */
  88         protected transient boolean rejectedSetBCOnce;
  89
  90         /**
  91          * Listeners are registered here and events are fired through here.
  92          */
  93         protected PropertyChangeSupport pcSupport;
  94
  95         /**
  96          * Listeners are registered here and events are fired through here.
  97          */
  98         protected VetoableChangeSupport vcSupport;
  99
 100
 101         /**
 102          * Create a new <code>BeanContextChildSupport</code> with itself as the peer.
 103          * This is meant to be used when you subclass
 104          * <code>BeanContextChildSupport</code> to create your child.
 105          */
 106         public BeanContextChildSupport() {
 107                 this(null);
 108         };
 109
 110         /**
 111          * Create a new <code>BeanContextChildSupport</code> with the specified peer.
 112          * @param peer the peer to use, or <code>null</code> to specify
 113          *        <code>this</code>.
 114          */
 115         public BeanContextChildSupport(BeanContextChild peer) {
 116                 if(peer == null) {
 117                         peer = this;
 118                 }
 119
 120                 beanContextChildPeer = peer;
 121                 pcSupport = new PropertyChangeSupport(peer);
 122                 vcSupport = new VetoableChangeSupport(peer);
 123         }
 124
 125         /**
 126          * Set the parent <code>BeanContext</code>.
 127          * <P>
 128          *
 129          * When this Object is being added to a new BeanContext or moved
 130          * from an old one, a non-null value will be passed in.
 131          * <P>
 132          *
 133          * When this Object is being removed from the current
 134          * <code>BeanContext</code>, <code>setBeanContext()</code> will
 135          * receive the parameter <code>null</code>.
 136          * <P>
 137          *
 138          * Order of events:
 139          * <OL>
 140          *   <LI>
 141          *     If the new <code>BeanContext</code> is the same as the old
 142          *     one, nothing happens.
 143          *   </LI>
 144          *   <LI>
 145          *     If the change has not been rejected or vetoed before, call
 146          *     <code>validatePendingSetBeanContext()</code>.  If this call
 147          *     returns <code>false</code>, the change is rejected and a
 148          *     <code>PropertyVetoException</code> is thrown.
 149          *   </LI>
 150          *   <LI>
 151          *     If the change has not been rejected or vetoed before,
 152          *     <code>VetoableChangeEvent</code>s are fired with the name
 153          *     <code>"beanContext"</code>, using the
 154          *     <code>fireVetoableChange()</code> method.  If a veto
 155          *     occurs, reversion events are fired using the same method,
 156          *     the change is rejected, and the veto is rethrown.
 157          *   </LI>
 158          *   <LI>
 159          *     <code>releaseBeanContextResources()</code> is called.
 160          *   </LI>
 161          *   <LI>
 162          *     The change is made.
 163          *   </LI>
 164          *   <LI>
 165          *     <code>PropertyChangeEvent</code>s are fired using the
 166          *     <code>firePropertyChange()</code> method.
 167          *   </LI>
 168          *   <LI>
 169          *     <code>initializeBeanContextResources()</code> is called.
 170          *   </LI>
 171          * </OL>
 172          * <P>
 173          *
 174          * @param newBeanContext the new parent for the
 175          *        <code>BeanContextChild</code>, or <code>null</code> to
 176          *        signify removal from a tree.
 177          * @exception PropertyVetoException if the
 178          *            <code>BeanContextChild</code> implementor does not
 179          *            wish to have its parent changed.
 180          */
 181         public void setBeanContext(BeanContext newBeanContext)
 182                 throws PropertyVetoException {
 183                 synchronized(beanContextChildPeer) {
 184                         if(newBeanContext == beanContext)
 185                                 return;
 186
 187                         if(!rejectedSetBCOnce) {
 188                                 if(!validatePendingSetBeanContext(newBeanContext)) {
 189                                         rejectedSetBCOnce = true;
 190                                         throw new PropertyVetoException("validatePendingSetBeanContext() rejected change",
 191                                                 new PropertyChangeEvent(beanContextChildPeer, "beanContext", beanContext, newBeanContext));
 192                                 }
 193                                 try {
 194                                         fireVetoableChange("beanContext", beanContext, newBeanContext);
 195                                 } catch(PropertyVetoException e) {
 196                                         rejectedSetBCOnce = true;
 197                                         throw e;
 198                                 }
 199                         }
 200
 201                         releaseBeanContextResources();
 202
 203                         beanContext = newBeanContext;
 204                         rejectedSetBCOnce = false;
 205
 206                         firePropertyChange("beanContext", beanContext, newBeanContext);
 207
 208                         initializeBeanContextResources();
 209                 }
 210         }
 211
 212         /**
 213          * Get the parent <code>BeanContext</code>.
 214          * @return the parent <code>BeanContext</code>.
 215          */
 216         public BeanContext getBeanContext() {
 217                 return beanContext;
 218         }
 219
 220         /**
 221          * Get the peer (or <code>this</code> if there is no peer).
 222          * @return the peer, or <code>this</code> if there is no peer.
 223          */
 224         public BeanContextChild getBeanContextChildPeer() {
 225                 return beanContextChildPeer;
 226         }
 227
 228         /**
 229          * Determine whether there is a peer.
 230          * This is true iff <code>getBeanContextChildPeer() == this</code>.
 231          * @return whether there is a peer.
 232          */
 233         public boolean isDelegated() {
 234                 return beanContextChildPeer == this;
 235         }
 236
 237         /**
 238          * Add a listener that will be notified when a specific property changes.
 239          * @param propertyName the name of the property to listen on.
 240          * @param listener the listener to listen on the property.
 241          */
 242         public void addPropertyChangeListener(String propertyName, PropertyChangeListener listener) {
 243                 pcSupport.addPropertyChangeListener(propertyName, listener);
 244         }
 245
 246         /**
 247          * Remove a listener to a certain property.
 248          *
 249          * @param propertyName the name of the property being listened on.
 250          * @param listener the listener listening on the property.
 251          */
 252         public void removePropertyChangeListener(String propertyName, PropertyChangeListener listener) {
 253                 pcSupport.removePropertyChangeListener(propertyName, listener);
 254         }
 255
 256         /**
 257          * Add a listener that will be notified when a specific property
 258          * change is requested (a PropertyVetoException may be thrown) as
 259          * well as after the change is successfully made.
 260          *
 261          * @param propertyName the name of the property to listen on.
 262          * @param listener the listener to listen on the property.
 263          */
 264         public void addVetoableChangeListener(String propertyName, VetoableChangeListener listener) {
 265                 vcSupport.addVetoableChangeListener(propertyName, listener);
 266         }
 267
 268         /**
 269          * Remove a listener to a certain property.
 270          *
 271          * @param propertyName the name of the property being listened on
 272          * @param listener the listener listening on the property.
 273          */
 274         public void removeVetoableChangeListener(String propertyName, VetoableChangeListener listener) {
 275                 vcSupport.removeVetoableChangeListener(propertyName, listener);
 276         }
 277
 278         /**
 279          * Fire a property change.
 280          *
 281          * @param propertyName the name of the property that changed
 282          * @param oldVal the old value of the property
 283          * @param newVal the new value of the property
 284          */
 285         public void firePropertyChange(String propertyName, Object oldVal, Object newVal) {
 286                 pcSupport.firePropertyChange(propertyName, oldVal, newVal);
 287         }
 288
 289         /**
 290          * Fire a vetoable property change.
 291          *
 292          * @param propertyName the name of the property that changed
 293          * @param oldVal the old value of the property
 294          * @param newVal the new value of the property
 295          * @exception PropertyVetoException if the change is vetoed.
 296          */
 297         public void fireVetoableChange(String propertyName, Object oldVal, Object newVal)
 298                         throws PropertyVetoException {
 299                 vcSupport.fireVetoableChange(propertyName, oldVal, newVal);
 300         }
 301
 302         /**
 303          * Called by <code>BeanContextServices.revokeService()</code> to indicate that a service has been revoked.
 304          * If you have a reference to such a service, it should be
 305          * discarded and may no longer function properly.
 306          * <code>getService()</code> will no longer work on the specified
 307          * service class after this event has been fired.
 308          * <P>
 309          *
 310          * <EM>This method is meant to be overriden.</EM>
 311          * <code>BeanContextChildSupport</code>'s implementation does
 312          * nothing.
 313          *
 314          * @param event the service revoked event.
 315          * @see java.beans.beancontext.BeanContextServices#revokeService(java.lang.Class,java.beans.beancontext.BeanContextServiceProvider,boolean)
 316          */
 317         public void serviceRevoked(BeanContextServiceRevokedEvent event) {
 318         }
 319
 320         /**
 321          * Called by <code>BeanContextServices</code> whenever a service is made available.
 322          * <P>
 323          *
 324          * <EM>This method is meant to be overriden.</EM>
 325          * <code>BeanContextChildSupport</code>'s implementation does
 326          * nothing.
 327          *
 328          * @param event the service revoked event, with useful information
 329          *        about the new service.
 330          */
 331         public void serviceAvailable(BeanContextServiceAvailableEvent event) {
 332         }
 333
 334         /**
 335          * Called by <code>setBeanContext()</code> to determine whether the set should be rejected.
 336          * <P>
 337          *
 338          * <EM>This method is meant to be overriden.</EM>
 339          * <code>BeanContextChildSupport</code>'s implementation simply
 340          * returns <code>true</code>.
 341          *
 342          * @param newBeanContext the new parent.
 343          * @return whether to allow the parent to be changed to the new
 344          *         value.
 345          */
 346         public boolean validatePendingSetBeanContext(BeanContext newBeanContext) {
 347                 return true;
 348         }
 349
 350         /**
 351          * Called by <code>setBeanContext()</code> to release resources of a what will soon no longer be the parent.
 352          * <P>
 353          *
 354          * <EM>This method is meant to be overriden.</EM>
 355          * <code>BeanContextChildSupport</code>'s implementation does
 356          * nothing.
 357          */
 358         protected void releaseBeanContextResources() {
 359         }
 360
 361         /**
 362          * Called by <code>setBeanContext()</code> to grab resources when the parent has been set.
 363          * <P>
 364          *
 365          * <EM>This method is meant to be overriden.</EM>
 366          * <code>BeanContextChildSupport</code>'s implementation does
 367          * nothing.
 368          */
 369         protected void initializeBeanContextResources() {
 370         }
 371 }