BeanContextChildSupport


1   /*
2    * @(#)BeanContextChildSupport.java 1.16 04/03/04
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.beans.beancontext;
9   
10  import java.beans.PropertyChangeEvent  ;
11  import java.beans.PropertyChangeListener  ;
12  import java.beans.PropertyChangeSupport  ;
13  
14  import java.beans.VetoableChangeListener  ;
15  import java.beans.VetoableChangeSupport  ;
16  
17  import java.beans.PropertyVetoException  ;
18  
19  import java.io.IOException  ;
20  import java.io.ObjectInputStream  ;
21  import java.io.ObjectOutputStream  ;
22  import java.io.Serializable  ;
23  
24  /**
25   * <p>
26   * This is a general support class to provide support for implementing the
27   * BeanContextChild protocol.
28   * 
29   * This class may either be directly subclassed, or encapsulated and delegated
30   * to in order to implement this interface for a given component.
31   * </p>
32   *
33   * @author  Laurence P. G. Cable
34   * @version 1.16, 03/04/04
35   * @since   1.2
36   * 
37   * @see java.beans.beancontext.BeanContext
38   * @see java.beans.beancontext.BeanContextServices
39   * @see java.beans.beancontext.BeanContextChild
40   */
41  
42  public class BeanContextChildSupport implements BeanContextChild  , BeanContextServicesListener  , Serializable   {
43  
44      static final long serialVersionUID = 6328947014421475877L;
45  
46      /**
47       * construct a BeanContextChildSupport where this class has been 
48       * subclassed in order to implement the JavaBean component itself.
49       */
50  
51      public BeanContextChildSupport() {
52      super();
53  
54      beanContextChildPeer = this;
55  
56      pcSupport = new PropertyChangeSupport  (beanContextChildPeer);
57      vcSupport = new VetoableChangeSupport  (beanContextChildPeer);
58      }
59  
60      /**
61       * construct a BeanContextChildSupport where the JavaBean component
62       * itself implements BeanContextChild, and encapsulates this, delegating
63       * that interface to this implementation
64       */
65  
66      public BeanContextChildSupport(BeanContextChild   bcc) {
67      super();
68  
69      beanContextChildPeer = (bcc != null) ? bcc : this;
70  
71      pcSupport = new PropertyChangeSupport  (beanContextChildPeer);
72      vcSupport = new VetoableChangeSupport  (beanContextChildPeer);
73      }
74  
75      /**
76       * Sets the <code>BeanContext</code> for 
77       * this <code>BeanContextChildSupport</code>.
78       * @param bc the new value to be assigned to the <code>BeanContext</code> 
79       * property
80       * @throws <code>PropertyVetoException</code> if the change is rejected
81       */
82      public synchronized void setBeanContext(BeanContext   bc) throws PropertyVetoException   {
83      if (bc == beanContext) return;
84  
85      BeanContext   oldValue = beanContext;
86      BeanContext   newValue = bc;
87  
88      if (!rejectedSetBCOnce) {
89          if (rejectedSetBCOnce = !validatePendingSetBeanContext(bc)) {
90          throw new PropertyVetoException  (
91              "setBeanContext() change rejected:",
92              new PropertyChangeEvent  (beanContextChildPeer, "beanContext", oldValue, newValue)
93          );
94          }
95  
96          try {
97          fireVetoableChange("beanContext",
98                     oldValue,
99                     newValue
100         );
101         } catch (PropertyVetoException   pve) {
102         rejectedSetBCOnce = true;
103 
104         throw pve; // re-throw
105         }
106     }
107 
108     if (beanContext != null) releaseBeanContextResources();
109 
110     beanContext       = newValue;
111     rejectedSetBCOnce = false;
112 
113     firePropertyChange("beanContext", 
114                oldValue,
115                newValue
116     );
117 
118     if (beanContext != null) initializeBeanContextResources();
119     }
120 
121     /**
122      * Gets the nesting <code>BeanContext</code> 
123      * for this <code>BeanContextChildSupport</code>.
124      * @return the nesting <code>BeanContext</code> for 
125      * this <code>BeanContextChildSupport</code>.
126      */
127     public synchronized BeanContext   getBeanContext() { return beanContext; }
128 
129     /**
130      * Add a PropertyChangeListener for a specific property.
131      * The same listener object may be added more than once.  For each
132      * property,  the listener will be invoked the number of times it was added
133      * for that property.
134      * If <code>name</code> or <code>pcl</code> is null, no exception is thrown
135      * and no action is taken.
136      *
137      * @param name The name of the property to listen on
138      * @param pcl The <code>PropertyChangeListener</code> to be added
139      */
140     public void addPropertyChangeListener(String   name, PropertyChangeListener   pcl) {
141     pcSupport.addPropertyChangeListener(name, pcl);
142     }
143 
144     /**
145      * Remove a PropertyChangeListener for a specific property.
146      * If <code>pcl</code> was added more than once to the same event
147      * source for the specified property, it will be notified one less time
148      * after being removed.
149      * If <code>name</code> is null, no exception is thrown
150      * and no action is taken.
151      * If <code>pcl</code> is null, or was never added for the specified
152      * property, no exception is thrown and no action is taken.
153      *
154      * @param name The name of the property that was listened on
155      * @param pcl The PropertyChangeListener to be removed
156      */
157     public void removePropertyChangeListener(String   name, PropertyChangeListener   pcl) {
158     pcSupport.removePropertyChangeListener(name, pcl);
159     }
160 
161     /**
162      * Add a VetoableChangeListener for a specific property.
163      * The same listener object may be added more than once.  For each
164      * property,  the listener will be invoked the number of times it was added
165      * for that property.
166      * If <code>name</code> or <code>vcl</code> is null, no exception is thrown
167      * and no action is taken.
168      *
169      * @param name The name of the property to listen on
170      * @param vcl The <code>VetoableChangeListener</code> to be added
171      */
172     public void addVetoableChangeListener(String   name, VetoableChangeListener   vcl) {
173     vcSupport.addVetoableChangeListener(name, vcl);
174     }
175 
176     /**
177      * Removes a <code>VetoableChangeListener</code>.
178      * If <code>pcl</code> was added more than once to the same event
179      * source for the specified property, it will be notified one less time
180      * after being removed.
181      * If <code>name</code> is null, no exception is thrown
182      * and no action is taken.
183      * If <code>vcl</code> is null, or was never added for the specified
184      * property, no exception is thrown and no action is taken.
185      *
186      * @param name The name of the property that was listened on
187      * @param vcl The <code>VetoableChangeListener</code> to be removed
188      */
189     public void removeVetoableChangeListener(String   name, VetoableChangeListener   vcl) {
190     vcSupport.removeVetoableChangeListener(name, vcl);
191     }
192 
193     /**
194      * A service provided by the nesting BeanContext has been revoked.
195      * 
196      * Subclasses may override this method in order to implement their own
197      * behaviors.
198      * @param bcsre The <code>BeanContextServiceRevokedEvent</code> fired as a 
199      * result of a service being revoked
200      */
201     public void serviceRevoked(BeanContextServiceRevokedEvent   bcsre) { }
202 
203     /**
204      * A new service is available from the nesting BeanContext.
205      * 
206      * Subclasses may override this method in order to implement their own
207      * behaviors 
208      * @param bcsae The BeanContextServiceAvailableEvent fired as a
209      * result of a service becoming available
210      * 
211      */
212     public void serviceAvailable(BeanContextServiceAvailableEvent   bcsae) { }
213 
214     /**
215      * Gets the <tt>BeanContextChild</tt> associated with this 
216      * <tt>BeanContextChildSupport</tt>.
217      *
218      * @return the <tt>BeanContextChild</tt> peer of this class
219      */
220     public BeanContextChild   getBeanContextChildPeer() { return beanContextChildPeer; }
221 
222     /**
223      * Reports whether or not this class is a delegate of another.
224      * 
225      * @return true if this class is a delegate of another
226      */
227     public boolean isDelegated() { return !this.equals(beanContextChildPeer); }
228 
229     /**
230      * Report a bound property update to any registered listeners. No event is
231      * fired if old and new are equal and non-null.
232      * @param name The programmatic name of the property that was changed
233      * @param oldValue  The old value of the property
234      * @param newValue  The new value of the property
235      */
236     public void firePropertyChange(String   name, Object   oldValue, Object   newValue) {
237     pcSupport.firePropertyChange(name, oldValue, newValue);
238     }
239 
240     /**
241      * Report a vetoable property update to any registered listeners. 
242      * If anyone vetos the change, then fire a new event 
243      * reverting everyone to the old value and then rethrow 
244      * the PropertyVetoException. <P>
245      *
246      * No event is fired if old and new are equal and non-null.
247      * <P>
248      * @param name The programmatic name of the property that is about to
249      * change
250      * 
251      * @param oldValue The old value of the property
252      * @param newValue - The new value of the property
253      * 
254      * @throws PropertyVetoException if the recipient wishes the property
255      * change to be rolled back.
256      */
257     public void fireVetoableChange(String   name, Object   oldValue, Object   newValue) throws PropertyVetoException   {
258     vcSupport.fireVetoableChange(name, oldValue, newValue);
259     }
260 
261     /**
262      * Called from setBeanContext to validate (or otherwise) the
263      * pending change in the nesting BeanContext property value.
264      * Returning false will cause setBeanContext to throw
265      * PropertyVetoException.
266      * @param newValue the new value that has been requested for 
267      *  the BeanContext property
268      * @return <code>true</code> if the change operation is to be vetoed
269      */
270     public boolean validatePendingSetBeanContext(BeanContext   newValue) {
271     return true;
272     }
273 
274     /**
275      * This method may be overridden by subclasses to provide their own
276      * release behaviors. When invoked any resources held by this instance
277      * obtained from its current BeanContext property should be released
278      * since the object is no longer nested within that BeanContext.
279      */
280 
281     protected  void releaseBeanContextResources() {
282     // do nothing
283     }
284 
285     /**
286      * This method may be overridden by subclasses to provide their own
287      * initialization behaviors. When invoked any resources requried by the
288      * BeanContextChild should be obtained from the current BeanContext.
289      */
290 
291     protected void initializeBeanContextResources() {
292     // do nothing
293     }
294 
295     /**
296      * Write the persistence state of the object.
297      */
298 
299     private void writeObject(ObjectOutputStream   oos) throws IOException   {
300 
301     /*
302      * dont serialize if we are delegated and the delegator isnt also
303      * serializable.
304      */
305 
306     if (!equals(beanContextChildPeer) && !(beanContextChildPeer instanceof Serializable  ))
307         throw new IOException  ("BeanContextChildSupport beanContextChildPeer not Serializable");
308 
309     else 
310             oos.defaultWriteObject();
311         
312     }
313 
314 
315     /**
316      * Restore a persistent object, must wait for subsequent setBeanContext()
317      * to fully restore any resources obtained from the new nesting 
318      * BeanContext
319      */
320 
321     private void readObject(ObjectInputStream   ois) throws IOException  , ClassNotFoundException   {
322     ois.defaultReadObject();
323     }
324 
325     /*
326      * fields
327      */
328 
329     /**
330      * The <code>BeanContext</code> in which 
331      * this <code>BeanContextChild</code> is nested.
332      */
333     public    BeanContextChild        beanContextChildPeer;
334 
335    /** 
336     * The <tt>PropertyChangeSupport</tt> associated with this
337     * <tt>BeanContextChildSupport</tt>.
338     */
339     protected PropertyChangeSupport   pcSupport;
340 
341    /**
342     * The <tt>VetoableChangeSupport</tt> associated with this
343     * <tt>BeanContextChildSupport</tt>.
344     */
345     protected VetoableChangeSupport   vcSupport;
346 
347     protected transient BeanContext         beanContext;
348 
349    /**
350     * A flag indicating that there has been
351     * at least one <code>PropertyChangeVetoException</code>
352     * thrown for the attempted setBeanContext operation.
353     */
354     protected transient boolean               rejectedSetBCOnce;
355 
356 }
357
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags