java.beans.beancontext
Class BeanContextSupport

java.lang.Object
  extended by java.beans.beancontext.BeanContextChildSupport
      extended by java.beans.beancontext.BeanContextSupport
All Implemented Interfaces:
BeanContext, BeanContextChild, BeanContextServiceRevokedListener, BeanContextServicesListener, DesignMode, PropertyChangeListener, VetoableChangeListener, Visibility, Serializable, Iterable, Collection, EventListener
Direct Known Subclasses:
BeanContextServicesSupport

public class BeanContextSupport
extends BeanContextChildSupport
implements BeanContext, Serializable, PropertyChangeListener, VetoableChangeListener

This is a helper class for implementing a bean context. It is intended to be used either by subclassing or by calling methods of this implementation from another.

Since:
1.2
See Also:
Serialized Form

Nested Class Summary
protected  class BeanContextSupport.BCSChild
           
protected static class BeanContextSupport.BCSIterator
           
 
Field Summary
protected  ArrayList bcmListeners
           
protected  HashMap children
           
protected  boolean designTime
           
protected  Locale locale
           
protected  boolean okToUseGui
           
 
Fields inherited from class java.beans.beancontext.BeanContextChildSupport
beanContext, beanContextChildPeer, pcSupport, rejectedSetBCOnce, vcSupport
 
Fields inherited from interface java.beans.beancontext.BeanContext
globalHierarchyLock
 
Fields inherited from interface java.beans.DesignMode
PROPERTYNAME
 
Constructor Summary
BeanContextSupport()
          Construct a BeanContextSupport instance.
BeanContextSupport(BeanContext peer)
          Construct a BeanContextSupport instance.
BeanContextSupport(BeanContext peer, Locale locale)
          Construct a BeanContextSupport instance.
BeanContextSupport(BeanContext peer, Locale locale, boolean dtime)
          Construct a BeanContextSupport instance.
BeanContextSupport(BeanContext peer, Locale locale, boolean dtime, boolean visible)
          Construct a BeanContextSupport instance.
 
Method Summary
 boolean add(Object targetChild)
           Add a child to the bean context.
 boolean addAll(Collection c)
          Add the contents of a given collection to this collection.
 void addBeanContextMembershipListener(BeanContextMembershipListener listener)
          Add a listener on changes to the membership of this BeanContext object.
 boolean avoidingGui()
          Returns true if this bean needs a GUI but is being prevented from using one.
protected  Iterator bcsChildren()
           
protected  void bcsPreDeserializationHook(ObjectInputStream ois)
          Subclasses may use this method to perform their own deserialization after the default deserialization process has taken place, but prior to the deserialization of the children.
protected  void bcsPreSerializationHook(ObjectOutputStream oos)
          Subclasses may use this method to perform their own serialization after the default serialization process has taken place, but prior to the serialization of the children.
protected  void childDeserializedHook(Object child, BeanContextSupport.BCSChild bcsc)
          Called when a child is deserialized.
protected  void childJustAddedHook(Object child, BeanContextSupport.BCSChild bcsc)
           
protected  void childJustRemovedHook(Object child, BeanContextSupport.BCSChild bcsc)
           
protected static boolean classEquals(Class first, Class second)
           
 void clear()
          Clear the collection, such that a subsequent call to isEmpty() would return true.
 boolean contains(Object o)
          Test whether this collection contains a given object as one of its elements.
 boolean containsAll(Collection c)
          Test whether this collection contains every element in a given collection.
 boolean containsKey(Object o)
           
protected  Object[] copyChildren()
           
protected  BeanContextSupport.BCSChild createBCSChild(Object targetChild, Object peer)
           
protected  void deserialize(ObjectInputStream ois, Collection coll)
          Deserializes objects (written by serialize(ObjectOutputStream, Collection)) and adds them to the specified collection.
 void dontUseGui()
          Informs this bean that is should not make use of the GUI.
protected  void fireChildrenAdded(BeanContextMembershipEvent bcme)
           
protected  void fireChildrenRemoved(BeanContextMembershipEvent bcme)
           
 BeanContext getBeanContextPeer()
          Returns the bean context peer.
protected static BeanContextChild getChildBeanContextChild(Object child)
          Returns the BeanContextChild implementation for the given child.
protected static BeanContextMembershipListener getChildBeanContextMembershipListener(Object child)
          Returns child as an instance of BeanContextMembershipListener, or null if child does not implement that interface.
protected static PropertyChangeListener getChildPropertyChangeListener(Object child)
          Returns child as an instance of PropertyChangeListener, or null if child does not implement that interface.
protected static Serializable getChildSerializable(Object child)
          Returns child as an instance of Serializable, or null if child does not implement that interface.
protected static VetoableChangeListener getChildVetoableChangeListener(Object child)
          Returns child as an instance of VetoableChangeListener, or null if child does not implement that interface.
protected static Visibility getChildVisibility(Object child)
          Returns child as an instance of Visibility, or null if child does not implement that interface.
 Locale getLocale()
           
 URL getResource(String name, BeanContextChild bcc)
          Get a resource.
 InputStream getResourceAsStream(String name, BeanContextChild bcc)
          Get a resource as a stream.
protected  void initialize()
           
 Object instantiateChild(String beanName)
          This is a convenience method for instantiating a bean inside this context.
 boolean isDesignTime()
          Returns true if the BeanContext is in design time mode, and false if it is in runtime mode.
 boolean isEmpty()
          Returns true if this bean context has no children.
 boolean isSerializing()
          Returns true if the bean context is in the process of being serialized.
 Iterator iterator()
          Obtain an Iterator over this collection.
 boolean needsGui()
          Returns false as this bean does not a GUI for its operation.
 void okToUseGui()
          Informs this bean that it is okay to make use of the GUI.
 void propertyChange(PropertyChangeEvent pce)
          Subclasses may use this method to catch property changes arising from the children of this context.
 void readChildren(ObjectInputStream ois)
          Deserializes the children using the #deserialize(ObjectInputStream, Collection method and then calls childDeserializedHook(Object, BCSChild) for each child deserialized.
 boolean remove(Object targetChild)
          Remove the specified child from the context.
protected  boolean remove(Object targetChild, boolean callChildSetBC)
           Removes a child from the bean context.
 boolean removeAll(Collection c)
          Remove all elements of a given collection from this collection.
 void removeBeanContextMembershipListener(BeanContextMembershipListener bcml)
          Remove a listener on changes to the membership of this BeanContext object.
 boolean retainAll(Collection c)
          Remove all elements of this collection that are not contained in a given collection.
protected  void serialize(ObjectOutputStream oos, Collection coll)
          Writes the items in the collection to the specified output stream.
 void setDesignTime(boolean dtime)
          Sets the flag that indicates whether or not the BeanContext is in design mode.
 void setLocale(Locale newLocale)
           
 int size()
          Get the number of elements in this collection.
 Object[] toArray()
          Returns an array containing the children of this BeanContext.
 Object[] toArray(Object[] array)
          Populates, then returns, the supplied array with the children of this BeanContext.
protected  boolean validatePendingAdd(Object targetChild)
           
protected  boolean validatePendingRemove(Object targetChild)
           
 void vetoableChange(PropertyChangeEvent pce)
          Subclasses may use this method to veto changes arising from the children of this context.
 void writeChildren(ObjectOutputStream oos)
          Serializes the children using the #serialize(ObjectOutputStream, Collection method.
 
Methods inherited from class java.beans.beancontext.BeanContextChildSupport
addPropertyChangeListener, addVetoableChangeListener, firePropertyChange, fireVetoableChange, getBeanContext, getBeanContextChildPeer, initializeBeanContextResources, isDelegated, releaseBeanContextResources, removePropertyChangeListener, removeVetoableChangeListener, serviceAvailable, serviceRevoked, setBeanContext, validatePendingSetBeanContext
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.util.Collection
equals, hashCode
 
Methods inherited from interface java.beans.beancontext.BeanContextChild
addPropertyChangeListener, addVetoableChangeListener, getBeanContext, removePropertyChangeListener, removeVetoableChangeListener, setBeanContext
 

Field Detail

bcmListeners

protected transient ArrayList bcmListeners

children

protected transient HashMap children

designTime

protected transient boolean designTime

locale

protected transient Locale locale

okToUseGui

protected transient boolean okToUseGui
Constructor Detail

BeanContextSupport

public BeanContextSupport()
Construct a BeanContextSupport instance.


BeanContextSupport

public BeanContextSupport(BeanContext peer)
Construct a BeanContextSupport instance.

Parameters:
peer - the bean context peer (null permitted).

BeanContextSupport

public BeanContextSupport(BeanContext peer,
                          Locale locale)
Construct a BeanContextSupport instance.

Parameters:
peer - the bean context peer (null permitted).
locale - the locale (null permitted, equivalent to the default locale).

BeanContextSupport

public BeanContextSupport(BeanContext peer,
                          Locale locale,
                          boolean dtime)
Construct a BeanContextSupport instance.

Parameters:
peer - the bean context peer (null permitted).
locale - the locale (null permitted, equivalent to the default locale).
dtime - a flag indicating whether or not the bean context is in design time mode.

BeanContextSupport

public BeanContextSupport(BeanContext peer,
                          Locale locale,
                          boolean dtime,
                          boolean visible)
Construct a BeanContextSupport instance.

Parameters:
peer - the bean context peer (null permitted).
locale - the locale (null permitted, equivalent to the default locale).
dtime - a flag indicating whether or not the bean context is in design time mode.
visible - initial value of the okToUseGui flag.
Method Detail

add

public boolean add(Object targetChild)

Add a child to the bean context. A child can be a simple Object, a BeanContextChild or another BeanContext.

The children of a BeanContext form a set. As a result, this method returns false if the given object is already a child of this context.

If the child is a BeanContextChild, or a proxy for such a child, the setBeanContext() method is invoked on the child. If this operation is vetoed by the child, via throwing a PropertyVetoException, then the current completion state of the add() operation is rolled back and a IllegalStateException is thrown. If the BeanContextChild is successfully added, then the context registers with its PropertyChangeListener and VetoableChangeListener for "beanContext" events.

If the child implements java.beans.Visibility, then its ability to use a GUI is set based on that of this context.

A BeanContextMembershipEvent is fired when the child is successfully added to the bean context.

This method is synchronized over the global hierarchy lock.

Specified by:
add in interface Collection
Parameters:
targetChild - the child to add.
Returns:
false if the child has already been added.
Throws:
IllegalArgumentException - if the child is null.
IllegalStateException - if the child vetos the setting of its context.

addAll

public boolean addAll(Collection c)
Description copied from interface: Collection
Add the contents of a given collection to this collection.

Specified by:
addAll in interface Collection
Parameters:
c - the collection to add.
Returns:
true if the collection was modified as a result of this action.

addBeanContextMembershipListener

public void addBeanContextMembershipListener(BeanContextMembershipListener listener)
Description copied from interface: BeanContext
Add a listener on changes to the membership of this BeanContext object.

Specified by:
addBeanContextMembershipListener in interface BeanContext
Parameters:
listener - the listener to add.

avoidingGui

public boolean avoidingGui()
Returns true if this bean needs a GUI but is being prevented from using one.

Specified by:
avoidingGui in interface Visibility
Returns:
true if needsGui() is true but the bean has been told not to use it.

bcsChildren

protected Iterator bcsChildren()

bcsPreDeserializationHook

protected void bcsPreDeserializationHook(ObjectInputStream ois)
                                  throws ClassNotFoundException,
                                         IOException
Subclasses may use this method to perform their own deserialization after the default deserialization process has taken place, but prior to the deserialization of the children. It should not be used to replace the implementation of readObject in the subclass.

Parameters:
ois - the input stream.
Throws:
ClassNotFoundException - if the class of an object being deserialized could not be found.
IOException - if an I/O error occurs.

bcsPreSerializationHook

protected void bcsPreSerializationHook(ObjectOutputStream oos)
                                throws IOException
Subclasses may use this method to perform their own serialization after the default serialization process has taken place, but prior to the serialization of the children. It should not be used to replace the implementation of writeObject in the subclass.

Parameters:
oos - the output stream.
Throws:
IOException - if an I/O error occurs.

childDeserializedHook

protected void childDeserializedHook(Object child,
                                     BeanContextSupport.BCSChild bcsc)
Called when a child is deserialized.

Parameters:
child - the deserialized child.
bcsc - the deserialized context wrapper for the child.

childJustAddedHook

protected void childJustAddedHook(Object child,
                                  BeanContextSupport.BCSChild bcsc)

childJustRemovedHook

protected void childJustRemovedHook(Object child,
                                    BeanContextSupport.BCSChild bcsc)

classEquals

protected static final boolean classEquals(Class first,
                                           Class second)

clear

public void clear()
Description copied from interface: Collection
Clear the collection, such that a subsequent call to isEmpty() would return true.

Specified by:
clear in interface Collection

contains

public boolean contains(Object o)
Description copied from interface: Collection
Test whether this collection contains a given object as one of its elements.

Specified by:
contains in interface Collection
Parameters:
o - the element to look for.
Returns:
true if this collection contains at least one element e such that o == null ? e == null : o.equals(e).

containsAll

public boolean containsAll(Collection c)
Description copied from interface: Collection
Test whether this collection contains every element in a given collection.

Specified by:
containsAll in interface Collection
Parameters:
c - the collection to test for.
Returns:
true if for every element o in c, contains(o) would return true.

containsKey

public boolean containsKey(Object o)

copyChildren

protected final Object[] copyChildren()

createBCSChild

protected BeanContextSupport.BCSChild createBCSChild(Object targetChild,
                                                     Object peer)

deserialize

protected final void deserialize(ObjectInputStream ois,
                                 Collection coll)
                          throws ClassNotFoundException,
                                 IOException
Deserializes objects (written by serialize(ObjectOutputStream, Collection)) and adds them to the specified collection.

Parameters:
ois - the input stream (null not permitted).
coll - the collection to add the objects to (null not permitted).
Throws:
ClassNotFoundException
IOException
See Also:
serialize(ObjectOutputStream, Collection)

dontUseGui

public void dontUseGui()
Informs this bean that is should not make use of the GUI.

Specified by:
dontUseGui in interface Visibility

fireChildrenAdded

protected final void fireChildrenAdded(BeanContextMembershipEvent bcme)

fireChildrenRemoved

protected final void fireChildrenRemoved(BeanContextMembershipEvent bcme)

getBeanContextPeer

public BeanContext getBeanContextPeer()
Returns the bean context peer.

Returns:
The bean context peer.
See Also:
BeanContextChildSupport.beanContextChildPeer

getChildBeanContextChild

protected static final BeanContextChild getChildBeanContextChild(Object child)
Returns the BeanContextChild implementation for the given child.

Parameters:
child - the child (null permitted).
Returns:
The bean context child.
Throws:
IllegalArgumentException - if child implements both the BeanContextChild and BeanContextProxy interfaces.

getChildBeanContextMembershipListener

protected static final BeanContextMembershipListener getChildBeanContextMembershipListener(Object child)
Returns child as an instance of BeanContextMembershipListener, or null if child does not implement that interface.

Parameters:
child - the child (null permitted).
Returns:
The child cast to BeanContextMembershipListener.

getChildPropertyChangeListener

protected static final PropertyChangeListener getChildPropertyChangeListener(Object child)
Returns child as an instance of PropertyChangeListener, or null if child does not implement that interface.

Parameters:
child - the child (null permitted).
Returns:
The child cast to PropertyChangeListener.

getChildSerializable

protected static final Serializable getChildSerializable(Object child)
Returns child as an instance of Serializable, or null if child does not implement that interface.

Parameters:
child - the child (null permitted).
Returns:
The child cast to Serializable.

getChildVetoableChangeListener

protected static final VetoableChangeListener getChildVetoableChangeListener(Object child)
Returns child as an instance of VetoableChangeListener, or null if child does not implement that interface.

Parameters:
child - the child (null permitted).
Returns:
The child cast to VetoableChangeListener.

getChildVisibility

protected static final Visibility getChildVisibility(Object child)
Returns child as an instance of Visibility, or null if child does not implement that interface.

Parameters:
child - the child (null permitted).
Returns:
The child cast to Visibility.

getLocale

public Locale getLocale()

getResource

public URL getResource(String name,
                       BeanContextChild bcc)
Description copied from interface: BeanContext
Get a resource. The BeanContext will typically call ClassLoader.getResource(), but may do it any way it wants to. This allows a BeanContext to have its own set of resources separate from the rest of the system.

Beans should call this method on their parent rather than the associated ClassLoader method.

I am assuming, but am not entirely sure, that if a BeanContext cannot find a resource, its responsibility is to call the getResource method of its parent BeanContext.

Specified by:
getResource in interface BeanContext
Parameters:
name - the name of the resource requested.
bcc - a reference to the child requesting the resource.
Returns:
a URL to the requested resource.
See Also:
ClassLoader.getResource(java.lang.String)

getResourceAsStream

public InputStream getResourceAsStream(String name,
                                       BeanContextChild bcc)
Description copied from interface: BeanContext
Get a resource as a stream. The BeanContext will typically call ClassLoader.getResourceAsStream(), but may do it any way it wants to. This allows a BeanContext's children to have their own set of resources separate from the rest of the system.

Beans should call this method on their parent rather than the associated ClassLoader method.

I am assuming, but am not entirely sure, that if a BeanContext cannot find a resource, its responsibility is to call the getResourceAsStream method of its parent BeanContext.

Specified by:
getResourceAsStream in interface BeanContext
Parameters:
name - the name of the resource requested.
bcc - a reference to the child requesting the resource.
Returns:
the requested resource as a stream.
See Also:
ClassLoader.getResourceAsStream(java.lang.String)

initialize

protected void initialize()

instantiateChild

public Object instantiateChild(String beanName)
                        throws IOException,
                               ClassNotFoundException
This is a convenience method for instantiating a bean inside this context. It delegates to the appropriate method in java.beans.Beans using the context's classloader.

Specified by:
instantiateChild in interface BeanContext
Parameters:
beanName - the name of the class of bean to instantiate.
Returns:
the created Bean
Throws:
IOException - if an I/O error occurs in loading the class.
ClassNotFoundException - if the class, beanName, can not be found.
See Also:
Beans.instantiate(java.lang.ClassLoader,java.lang.String), Beans.instantiate(java.lang.ClassLoader,java.lang.String,java.beans.beancontext.BeanContext)

isDesignTime

public boolean isDesignTime()
Returns true if the BeanContext is in design time mode, and false if it is in runtime mode.

Specified by:
isDesignTime in interface DesignMode
Returns:
A boolean.
See Also:
setDesignTime(boolean)

isEmpty

public boolean isEmpty()
Returns true if this bean context has no children.

Specified by:
isEmpty in interface Collection
Returns:
true if there are no children.

isSerializing

public boolean isSerializing()
Returns true if the bean context is in the process of being serialized.

Returns:
true if the context is being serialized.

iterator

public Iterator iterator()
Description copied from interface: Collection
Obtain an Iterator over this collection.

Specified by:
iterator in interface Iterable
Specified by:
iterator in interface Collection
Returns:
an Iterator over the elements of this collection, in any order.

needsGui

public boolean needsGui()
Returns false as this bean does not a GUI for its operation.

Specified by:
needsGui in interface Visibility
Returns:
false

okToUseGui

public void okToUseGui()
Informs this bean that it is okay to make use of the GUI.

Specified by:
okToUseGui in interface Visibility

propertyChange

public void propertyChange(PropertyChangeEvent pce)
Subclasses may use this method to catch property changes arising from the children of this context. At present, we just listen for the beans being assigned to a different context and remove them from here if such an event occurs.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
pce - the property change event.

readChildren

public final void readChildren(ObjectInputStream ois)
                        throws IOException,
                               ClassNotFoundException
Deserializes the children using the #deserialize(ObjectInputStream, Collection method and then calls childDeserializedHook(Object, BCSChild) for each child deserialized.

Parameters:
ois - the input stream.
Throws:
IOException - if an I/O error occurs.
ClassNotFoundException

remove

public boolean remove(Object targetChild)
Remove the specified child from the context. This is the same as calling remove(Object,boolean) with a request for the setBeanContext() method of the child to be called (i.e. the second argument is true).

Specified by:
remove in interface Collection
Parameters:
targetChild - the child to remove.
Returns:
true if the collection changed as a result of this call, that is, if the collection contained at least one occurrence of o.

remove

protected boolean remove(Object targetChild,
                         boolean callChildSetBC)

Removes a child from the bean context. A child can be a simple Object, a BeanContextChild or another BeanContext. If the given child is not a child of this context, this method returns false.

If the child is a BeanContextChild, or a proxy for such a child, the setBeanContext() method is invoked on the child (if specified). If this operation is vetoed by the child, via throwing a PropertyVetoException, then the current completion state of the remove() operation is rolled back and a IllegalStateException is thrown. If the BeanContextChild is successfully removed, then the context deregisters with its PropertyChangeListener and VetoableChangeListener for "beanContext" events.

A BeanContextMembershipEvent is fired when the child is successfully removed from the bean context.

This method is synchronized over the global hierarchy lock.

Parameters:
targetChild - the child to remove.
callChildSetBC - true if the setBeanContext() method of the child should be called.
Returns:
false if the child doesn't exist.
Throws:
IllegalArgumentException - if the child is null.
IllegalStateException - if the child vetos the setting of its context.

removeAll

public boolean removeAll(Collection c)
Description copied from interface: Collection
Remove all elements of a given collection from this collection. That is, remove every element e such that c.contains(e).

Specified by:
removeAll in interface Collection
Parameters:
c - The collection of objects to be removed.
Returns:
true if this collection was modified as a result of this call.

removeBeanContextMembershipListener

public void removeBeanContextMembershipListener(BeanContextMembershipListener bcml)
Description copied from interface: BeanContext
Remove a listener on changes to the membership of this BeanContext object.

Specified by:
removeBeanContextMembershipListener in interface BeanContext
Parameters:
bcml - the listener to remove.

retainAll

public boolean retainAll(Collection c)
Description copied from interface: Collection
Remove all elements of this collection that are not contained in a given collection. That is, remove every element e such that !c.contains(e).

Specified by:
retainAll in interface Collection
Parameters:
c - The collection of objects to be retained.
Returns:
true if this collection was modified as a result of this call.

serialize

protected final void serialize(ObjectOutputStream oos,
                               Collection coll)
                        throws IOException
Writes the items in the collection to the specified output stream. Items in the collection that are not instances of Serializable (this includes null) are simply ignored.

Parameters:
oos - the output stream (null not permitted).
coll - the collection (null not permitted).
Throws:
IOException
See Also:
deserialize(ObjectInputStream, Collection)

setDesignTime

public void setDesignTime(boolean dtime)
Sets the flag that indicates whether or not the BeanContext is in design mode. If the flag changes value, a PropertyChangeEvent (with the property name 'designMode') is sent to registered listeners. Note that the property name used here does NOT match the specification in the DesignMode interface, we match the reference implementation instead - see bug parade entry 4295174.

Specified by:
setDesignTime in interface DesignMode
Parameters:
dtime - the new value for the flag.
See Also:
isDesignTime()

setLocale

public void setLocale(Locale newLocale)
               throws PropertyVetoException
Throws:
PropertyVetoException

size

public int size()
Description copied from interface: Collection
Get the number of elements in this collection.

Specified by:
size in interface Collection
Returns:
the number of elements in the collection.

toArray

public Object[] toArray()
Returns an array containing the children of this BeanContext.

Specified by:
toArray in interface Collection
Returns:
An array containing the children.

toArray

public Object[] toArray(Object[] array)
Populates, then returns, the supplied array with the children of this BeanContext. If the array is too short to hold the children, a new array is allocated and returned. If the array is too long, it is padded with null items at the end.

Specified by:
toArray in interface Collection
Parameters:
array - an array to populate (null not permitted).
Returns:
an array containing the elements currently in this collection, in any order.

validatePendingAdd

protected boolean validatePendingAdd(Object targetChild)

validatePendingRemove

protected boolean validatePendingRemove(Object targetChild)

vetoableChange

public void vetoableChange(PropertyChangeEvent pce)
                    throws PropertyVetoException
Subclasses may use this method to veto changes arising from the children of this context.

Specified by:
vetoableChange in interface VetoableChangeListener
Parameters:
pce - the vetoable property change event fired.
Throws:
PropertyVetoException - if the change is vetoed by the listener

writeChildren

public final void writeChildren(ObjectOutputStream oos)
                         throws IOException
Serializes the children using the #serialize(ObjectOutputStream, Collection method.

Parameters:
oos - the output stream.
Throws:
IOException - if an I/O error occurs.