001 /* java.beans.beancontext.BeanContextChildSupport 002 Copyright (C) 1999 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package java.beans.beancontext; 040 041 import java.beans.PropertyChangeEvent; 042 import java.beans.PropertyChangeListener; 043 import java.beans.PropertyChangeSupport; 044 import java.beans.PropertyVetoException; 045 import java.beans.VetoableChangeListener; 046 import java.beans.VetoableChangeSupport; 047 import java.io.Serializable; 048 049 /** 050 * Support for creating a <code>BeanContextChild</code>. 051 * This class contains the most common implementations of the methods in 052 * the <code>BeanContextChild</code> 053 * 054 * @specnote This class is not very well specified. I had to "fill in the 055 * blanks" in most places with what I thought was reasonable 056 * behavior. If there are problems, let me know. 057 * 058 * @author John Keiser 059 * @since 1.2 060 * @see java.beans.beancontext.BeanContextChild 061 */ 062 public class BeanContextChildSupport 063 implements BeanContextChild, BeanContextServicesListener, Serializable 064 { 065 static final long serialVersionUID = 6328947014421475877L; 066 067 /** 068 * The peer on which to perform <code>set</code> actions. 069 * This is here so that this class can be used as a peer. 070 * <P> 071 * 072 * When extending this class, this variable will be set to 073 * <code>this</code>. 074 */ 075 public BeanContextChild beanContextChildPeer; 076 077 /** 078 * The parent <code>BeanContext</code>. 079 */ 080 protected transient BeanContext beanContext; 081 082 /** 083 * If <code>setBeanContext()</code> was vetoed once before, this 084 * is set to <code>true</code> so that the next time, vetoes will 085 * be ignored. 086 */ 087 protected transient boolean rejectedSetBCOnce; 088 089 /** 090 * Listeners are registered here and events are fired through here. 091 */ 092 protected PropertyChangeSupport pcSupport; 093 094 /** 095 * Listeners are registered here and events are fired through here. 096 */ 097 protected VetoableChangeSupport vcSupport; 098 099 /** 100 * Create a new <code>BeanContextChildSupport</code> with itself as the peer. 101 * This is meant to be used when you subclass 102 * <code>BeanContextChildSupport</code> to create your child. 103 */ 104 public BeanContextChildSupport() 105 { 106 this (null); 107 } 108 109 /** 110 * Create a new <code>BeanContextChildSupport</code> with the specified peer. 111 * @param peer the peer to use, or <code>null</code> to specify 112 * <code>this</code>. 113 */ 114 public BeanContextChildSupport (BeanContextChild peer) 115 { 116 if (peer == null) 117 { 118 peer = this; 119 } 120 121 beanContextChildPeer = peer; 122 pcSupport = new PropertyChangeSupport (peer); 123 vcSupport = new VetoableChangeSupport (peer); 124 } 125 126 /** 127 * Set the parent <code>BeanContext</code>. 128 * <P> 129 * 130 * When this Object is being added to a new BeanContext or moved 131 * from an old one, a non-null value will be passed in. 132 * <P> 133 * 134 * When this Object is being removed from the current 135 * <code>BeanContext</code>, <code>setBeanContext()</code> will 136 * receive the parameter <code>null</code>. 137 * <P> 138 * 139 * Order of events: 140 * <OL> 141 * <LI> 142 * If the new <code>BeanContext</code> is the same as the old 143 * one, nothing happens. 144 * </LI> 145 * <LI> 146 * If the change has not been rejected or vetoed before, call 147 * <code>validatePendingSetBeanContext()</code>. If this call 148 * returns <code>false</code>, the change is rejected and a 149 * <code>PropertyVetoException</code> is thrown. 150 * </LI> 151 * <LI> 152 * If the change has not been rejected or vetoed before, 153 * <code>VetoableChangeEvent</code>s are fired with the name 154 * <code>"beanContext"</code>, using the 155 * <code>fireVetoableChange()</code> method. If a veto 156 * occurs, reversion events are fired using the same method, 157 * the change is rejected, and the veto is rethrown. 158 * </LI> 159 * <LI> 160 * <code>releaseBeanContextResources()</code> is called. 161 * </LI> 162 * <LI> 163 * The change is made. 164 * </LI> 165 * <LI> 166 * <code>PropertyChangeEvent</code>s are fired using the 167 * <code>firePropertyChange()</code> method. 168 * </LI> 169 * <LI> 170 * <code>initializeBeanContextResources()</code> is called. 171 * </LI> 172 * </OL> 173 * <P> 174 * 175 * @param newBeanContext the new parent for the 176 * <code>BeanContextChild</code>, or <code>null</code> to 177 * signify removal from a tree. 178 * @exception PropertyVetoException if the 179 * <code>BeanContextChild</code> implementor does not 180 * wish to have its parent changed. 181 */ 182 public void setBeanContext(BeanContext newBeanContext) 183 throws PropertyVetoException 184 { 185 synchronized (beanContextChildPeer) 186 { 187 if (newBeanContext == beanContext) 188 return; 189 190 if (!rejectedSetBCOnce) 191 { 192 if (!validatePendingSetBeanContext (newBeanContext)) 193 { 194 rejectedSetBCOnce = true; 195 throw new PropertyVetoException ("validatePendingSetBeanContext() rejected change", 196 new PropertyChangeEvent(beanContextChildPeer, "beanContext", beanContext, newBeanContext)); 197 } 198 199 try 200 { 201 fireVetoableChange ("beanContext", beanContext, newBeanContext); 202 } 203 catch (PropertyVetoException e) 204 { 205 rejectedSetBCOnce = true; 206 throw e; 207 } 208 } 209 210 releaseBeanContextResources (); 211 212 beanContext = newBeanContext; 213 rejectedSetBCOnce = false; 214 215 firePropertyChange ("beanContext", beanContext, newBeanContext); 216 217 initializeBeanContextResources (); 218 } 219 } 220 221 /** 222 * Get the parent <code>BeanContext</code>. 223 * @return the parent <code>BeanContext</code>. 224 */ 225 public BeanContext getBeanContext() 226 { 227 return beanContext; 228 } 229 230 /** 231 * Get the peer (or <code>this</code> if there is no peer). 232 * @return the peer, or <code>this</code> if there is no peer. 233 */ 234 public BeanContextChild getBeanContextChildPeer() { 235 return beanContextChildPeer; 236 } 237 238 /** 239 * Determine whether there is a peer. 240 * This is true iff <code>getBeanContextChildPeer() == this</code>. 241 * @return whether there is a peer. 242 */ 243 public boolean isDelegated() { 244 return beanContextChildPeer == this; 245 } 246 247 /** 248 * Add a listener that will be notified when a specific property changes. 249 * @param propertyName the name of the property to listen on. 250 * @param listener the listener to listen on the property. 251 */ 252 public void addPropertyChangeListener(String propertyName, PropertyChangeListener listener) { 253 pcSupport.addPropertyChangeListener(propertyName, listener); 254 } 255 256 /** 257 * Remove a listener to a certain property. 258 * 259 * @param propertyName the name of the property being listened on. 260 * @param listener the listener listening on the property. 261 */ 262 public void removePropertyChangeListener(String propertyName, PropertyChangeListener listener) { 263 pcSupport.removePropertyChangeListener(propertyName, listener); 264 } 265 266 /** 267 * Add a listener that will be notified when a specific property 268 * change is requested (a PropertyVetoException may be thrown) as 269 * well as after the change is successfully made. 270 * 271 * @param propertyName the name of the property to listen on. 272 * @param listener the listener to listen on the property. 273 */ 274 public void addVetoableChangeListener(String propertyName, VetoableChangeListener listener) { 275 vcSupport.addVetoableChangeListener(propertyName, listener); 276 } 277 278 /** 279 * Remove a listener to a certain property. 280 * 281 * @param propertyName the name of the property being listened on 282 * @param listener the listener listening on the property. 283 */ 284 public void removeVetoableChangeListener(String propertyName, VetoableChangeListener listener) { 285 vcSupport.removeVetoableChangeListener(propertyName, listener); 286 } 287 288 /** 289 * Fire a property change. 290 * 291 * @param propertyName the name of the property that changed 292 * @param oldVal the old value of the property 293 * @param newVal the new value of the property 294 */ 295 public void firePropertyChange(String propertyName, Object oldVal, Object newVal) { 296 pcSupport.firePropertyChange(propertyName, oldVal, newVal); 297 } 298 299 /** 300 * Fire a vetoable property change. 301 * 302 * @param propertyName the name of the property that changed 303 * @param oldVal the old value of the property 304 * @param newVal the new value of the property 305 * @exception PropertyVetoException if the change is vetoed. 306 */ 307 public void fireVetoableChange(String propertyName, Object oldVal, Object newVal) 308 throws PropertyVetoException { 309 vcSupport.fireVetoableChange(propertyName, oldVal, newVal); 310 } 311 312 /** 313 * Called by <code>BeanContextServices.revokeService()</code> to indicate that a service has been revoked. 314 * If you have a reference to such a service, it should be 315 * discarded and may no longer function properly. 316 * <code>getService()</code> will no longer work on the specified 317 * service class after this event has been fired. 318 * <P> 319 * 320 * <EM>This method is meant to be overriden.</EM> 321 * <code>BeanContextChildSupport</code>'s implementation does 322 * nothing. 323 * 324 * @param event the service revoked event. 325 * @see java.beans.beancontext.BeanContextServices#revokeService(java.lang.Class,java.beans.beancontext.BeanContextServiceProvider,boolean) 326 */ 327 public void serviceRevoked(BeanContextServiceRevokedEvent event) { 328 } 329 330 /** 331 * Called by <code>BeanContextServices</code> whenever a service is made available. 332 * <P> 333 * 334 * <EM>This method is meant to be overriden.</EM> 335 * <code>BeanContextChildSupport</code>'s implementation does 336 * nothing. 337 * 338 * @param event the service revoked event, with useful information 339 * about the new service. 340 */ 341 public void serviceAvailable(BeanContextServiceAvailableEvent event) { 342 } 343 344 /** 345 * Called by <code>setBeanContext()</code> to determine whether the set should be rejected. 346 * <P> 347 * 348 * <EM>This method is meant to be overriden.</EM> 349 * <code>BeanContextChildSupport</code>'s implementation simply 350 * returns <code>true</code>. 351 * 352 * @param newBeanContext the new parent. 353 * @return whether to allow the parent to be changed to the new 354 * value. 355 */ 356 public boolean validatePendingSetBeanContext(BeanContext newBeanContext) { 357 return true; 358 } 359 360 /** 361 * Called by <code>setBeanContext()</code> to release resources of a what will soon no longer be the parent. 362 * <P> 363 * 364 * <EM>This method is meant to be overriden.</EM> 365 * <code>BeanContextChildSupport</code>'s implementation does 366 * nothing. 367 */ 368 protected void releaseBeanContextResources() { 369 } 370 371 /** 372 * Called by <code>setBeanContext()</code> to grab resources when the parent has been set. 373 * <P> 374 * 375 * <EM>This method is meant to be overriden.</EM> 376 * <code>BeanContextChildSupport</code>'s implementation does 377 * nothing. 378 */ 379 protected void initializeBeanContextResources() { 380 } 381 }