java.beans.beancontext
Class BeanContextSupport

java.lang.Object
  |
  +--java.beans.beancontext.BeanContextChildSupport
        |
        +--java.beans.beancontext.BeanContextSupport

Direct Known Subclasses:

BeanContextServicesSupport

public class BeanContextSupport

extends BeanContextChildSupport

implements BeanContext, Serializable, PropertyChangeListener, VetoableChangeListener

This helper class provides a utility implementation of the java.beans.beancontext.BeanContext interface.

Since this class directly implements the BeanContext interface, the class can, and is intended to be used either by subclassing this implementation, or via ad-hoc delegation of an instance of this class from another.

Since:

JDK1.2

See Also:

Serialized Form

Inner Class Summary

protected class	BeanContextSupport.BCSChild
protected static class	BeanContextSupport.BCSIterator protected final subclass that encapsulates an iterator but implements a noop remove() method.

Field Summary

protected ArrayList	bcmListeners all accesses to the protected ArrayList bcmListeners field shall be synchronized on that object.
protected HashMap	children all accesses to the protected HashMap children field shall be synchronized on that object.
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()
Create an instance that is not a delegate of another object

BeanContextSupport(BeanContext peer)
Create an instance using with a default locale

BeanContextSupport(BeanContext peer, Locale lcle)
Create an instance using the specified locale

BeanContextSupport(BeanContext peer, Locale lcle, boolean dtime)
Create an instance using the specified Locale and design mode.

BeanContextSupport(BeanContext peer, Locale lcle, boolean dTime, boolean visible)
Construct a BeanContextSupport instance

Method Summary

boolean	add(Object targetChild) Adds/nests a child within this BeanContext
boolean	addAll(Collection c) add Collection to set of Children (Unsupported) implementations must synchronized on the hierarchy lock and "children" protected field
void	addBeanContextMembershipListener(BeanContextMembershipListener bcml) Adds a BeanContextMembershipListener
boolean	avoidingGui() Determines whether this bean is avoiding using a GUI.
protected Iterator	bcsChildren()
protected void	bcsPreDeserializationHook(ObjectInputStream ois) called by readObject after defaultReadObject() but prior to deserialization of any children.
protected void	bcsPreSerializationHook(ObjectOutputStream oos) called by writeObject after defaultWriteObject() but prior to serialization of currently serializable children.
protected void	childDeserializedHook(Object child, BeanContextSupport.BCSChild bcsc) called by readObject with the newly deserialized child and BCSChild
protected void	childJustAddedHook(Object child, BeanContextSupport.BCSChild bcsc) subclasses may override this method to simply extend add() semantics after the child has been added and before the event notification has occurred.
protected void	childJustRemovedHook(Object child, BeanContextSupport.BCSChild bcsc) subclasses may override this method to simply extend remove() semantics after the child has been removed and before the event notification has occurred.
protected static boolean	classEquals(Class first, Class second)
void	clear() clear the children (Unsupported) implementations must synchronized on the hierarchy lock and "children" protected field
boolean	contains(Object o) Returns true if this collection contains the specified element.
boolean	containsAll(Collection c) Returns true if this collection contains all of the elements in the specified collection.
boolean	containsKey(Object o)
protected Object[]	copyChildren()
protected BeanContextSupport.BCSChild	createBCSChild(Object targetChild, Object peer) Subclasses can override this method to insert their own subclass of Child without having to override add() or the other Collection methods that add children to the set.
protected void	deserialize(ObjectInputStream ois, Collection coll) used by readObject to deserialize a collection
void	dontUseGui() notify this instance that it may no longer render a GUI.
protected void	fireChildrenAdded(BeanContextMembershipEvent bcme) Fire a BeanContextshipEvent on the BeanContextMembershipListener interface
protected void	fireChildrenRemoved(BeanContextMembershipEvent bcme) Fire a BeanContextshipEvent on the BeanContextMembershipListener interface
BeanContext	getBeanContextPeer()
protected static BeanContextChild	getChildBeanContextChild(Object child)
protected static BeanContextMembershipListener	getChildBeanContextMembershipListener(Object child)
protected static PropertyChangeListener	getChildPropertyChangeListener(Object child)
protected static Serializable	getChildSerializable(Object child)
protected static VetoableChangeListener	getChildVetoableChangeListener(Object child)
protected static Visibility	getChildVisibility(Object child)
Locale	getLocale()
URL	getResource(String name, BeanContextChild bcc)
InputStream	getResourceAsStream(String name, BeanContextChild bcc)
protected void	initialize() protected method called from constructor and readObject to initialize transient state of BeanContextSupport instance.
Object	instantiateChild(String beanName) The instantiateChild method is a convenience hook in BeanContext to simplify the task of instantiating a Bean, nested, into a BeanContext.
boolean	isDesignTime() A value of true denotes that JavaBeans should behave in design time mode, a value of false denotes runtime behavior.
boolean	isEmpty() Returns true if this collection contains no elements.
boolean	isSerializing()
Iterator	iterator() Returns an iterator over the elements in this collection.
boolean	needsGui() Determines whether this bean needs a GUI.
void	okToUseGui() Notify this instance that it may now render a GUI
void	propertyChange(PropertyChangeEvent pce) subclasses may envelope to monitor child property changes.
void	readChildren(ObjectInputStream ois) When an instance of this class is used as a delegate for the implementation of the BeanContext protocols (and its subprotocols) there exists a 'chicken and egg' problem during deserialization
boolean	remove(Object targetChild) Removes a single instance of the specified element from this collection, if it is present (optional operation).
protected boolean	remove(Object targetChild, boolean callChildSetBC)
boolean	removeAll(Collection c) remove all specified children (Unsupported) implementations must synchronized on the hierarchy lock and "children" protected field
void	removeBeanContextMembershipListener(BeanContextMembershipListener bcml) Removes a BeanContextMembershipListener
boolean	retainAll(Collection c) retain only specified children (Unsupported) implementations must synchronized on the hierarchy lock and "children" protected field
protected void	serialize(ObjectOutputStream oos, Collection coll)
void	setDesignTime(boolean dTime) Sets the "value" of the "designTime" property.
void	setLocale(Locale newLocale)
int	size() Returns the number of elements in this collection.
Object[]	toArray() Returns an array containing all of the elements in this collection.
Object[]	toArray(Object[] arry) Returns an array containing all of the elements in this collection whose runtime type is that of the specified array.
protected boolean	validatePendingAdd(Object targetChild) Subclasses of this class may override, or envelope, this method to add validation behavior for the BeanContext to examine child objects immediately prior to their being added to the BeanContext.
protected boolean	validatePendingRemove(Object targetChild) Subclasses of this class may override, or envelope, this method to add validation behavior for the BeanContext to examine child objects immediately prior to their being removed from the BeanContext.
void	vetoableChange(PropertyChangeEvent pce) subclasses may envelope to monitor veto child property changes.
void	writeChildren(ObjectOutputStream oos)

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

Field Detail

children

protected transient HashMap children

all accesses to the protected HashMap children field shall be synchronized on that object.

bcmListeners

protected transient ArrayList bcmListeners

all accesses to the protected ArrayList bcmListeners field shall be synchronized on that object.

locale

protected Locale locale

okToUseGui

protected boolean okToUseGui

designTime

protected boolean designTime

Constructor Detail

BeanContextSupport

public BeanContextSupport(BeanContext peer,
                          Locale lcle,
                          boolean dTime,
                          boolean visible)

Construct a BeanContextSupport instance

Parameters:

peer - The peer BeanContext we are supplying an implementation for, if null the this object is its own peer

lcle - The current Locale for this BeanContext. If lcle is null, the default locale is assigned to the BeanContext instance.

dtime - The initial state, true if in design mode, false if runtime.

visible - The initial visibility.

See Also:

Locale.getDefault(),

BeanContextSupport

public BeanContextSupport(BeanContext peer,
                          Locale lcle,
                          boolean dtime)

Create an instance using the specified Locale and design mode.

Parameters:

peer - The peer BeanContext we are supplying an implementation for, if null the this object is its own peer

lcle - The current Locale for this BeanContext. If lcle is null, the default locale is assigned to the BeanContext instance.

dtime - The initial state, true if in design mode, false if runtime.

See Also:

Locale.getDefault(),

BeanContextSupport

public BeanContextSupport(BeanContext peer,
                          Locale lcle)

Create an instance using the specified locale

Parameters:

peer - The peer BeanContext we are supplying an implementation for, if null the this object is its own peer

lcle - The current Locale for this BeanContext. If lcle is null, the default locale is assigned to the BeanContext instance.

See Also:

Locale.getDefault(),

BeanContextSupport

public BeanContextSupport(BeanContext peer)

Create an instance using with a default locale

Parameters:

peer - The peer BeanContext we are supplying an implementation for, if null the this object is its own peer

BeanContextSupport

public BeanContextSupport()

Create an instance that is not a delegate of another object

Method Detail

getBeanContextPeer

public BeanContext getBeanContextPeer()

Returns:

the instance of BeanContext this object is providing the implemen tation for.

instantiateChild

public Object instantiateChild(String beanName)
                        throws IOException,
                               ClassNotFoundException

The instantiateChild method is a convenience hook in BeanContext to simplify the task of instantiating a Bean, nested, into a BeanContext.

The semantics of the beanName parameter are defined by java.beans.Beans.instantate.

Specified by:

instantiateChild in interface BeanContext

Parameters:

beanName - the name of the Bean to instantiate within this BeanContext

size

public int size()

Description copied from interface: Collection

Returns the number of elements in this collection. If this collection contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:

number of children

isEmpty

public boolean isEmpty()

Description copied from interface: Collection

Returns true if this collection contains no elements.

Returns:

if there are not children

contains

public boolean contains(Object o)

Description copied from interface: Collection

Returns true if this collection contains the specified element. More formally, returns true if and only if this collection contains at least one element e such that (o==null ? e==null : o.equals(e)).

Returns:

if this object is a child

containsKey

public boolean containsKey(Object o)

Returns:

if this object is a child

iterator

public Iterator iterator()

Description copied from interface: Collection

Returns an iterator over the elements in this collection. There are no guarantees concerning the order in which the elements are returned (unless this collection is an instance of some class that provides a guarantee).

Returns:

the iterator

toArray

public Object[] toArray()

Description copied from interface: Collection

Returns an array containing all of the elements in this collection. If the collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

The returned array will be "safe" in that no references to it are maintained by this collection. (In other words, this method must allocate a new array even if this collection is backed by an array). The caller is thus free to modify the returned array.

This method acts as bridge between array-based and collection-based APIs.

Returns:

an array of children

toArray

public Object[] toArray(Object[] arry)

Description copied from interface: Collection

Returns an array containing all of the elements in this collection whose runtime type is that of the specified array. If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection.

If this collection fits in the specified array with room to spare (i.e., the array has more elements than this collection), the element in the array immediately following the end of the collection is set to null. This is useful in determining the length of this collection only if the caller knows that this collection does not contain any null elements.)

If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

Like the toArray method, this method acts as bridge between array-based and collection-based APIs. Further, this method allows precise control over the runtime type of the output array, and may, under certain circumstances, be used to save allocation costs

Suppose l is a List known to contain only strings. The following code can be used to dump the list into a newly allocated array of String:

     String[] x = (String[]) v.toArray(new String[0]);
 

Note that toArray(new Object[0]) is identical in function to toArray().

Returns:

an array of children

createBCSChild

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

Subclasses can override this method to insert their own subclass of Child without having to override add() or the other Collection methods that add children to the set.

Parameters:

targetChild - the child to create the Child on behalf of

peer - the peer if the tragetChild and the peer are related by an implementation of BeanContextProxy

add

public boolean add(Object targetChild)

Adds/nests a child within this BeanContext

Invoked as a side effect of java.beans.Beans.instantiate().

Parameters:

targetChildren - The child objects to nest within this BeanContext

remove

public boolean remove(Object targetChild)

Description copied from interface: Collection

Removes a single instance of the specified element from this collection, if it is present (optional operation). More formally, removes an element e such that (o==null ? e==null : o.equals(e)), if this collection contains one or more such elements. Returns true if this collection contained the specified element (or equivalently, if this collection changed as a result of the call).

Parameters:

targetChildren - The child objects to remove

remove

protected boolean remove(Object targetChild,
                         boolean callChildSetBC)

containsAll

public boolean containsAll(Collection c)

Description copied from interface: Collection

Returns true if this collection contains all of the elements in the specified collection.

Returns:

if all object objects in specified Collection are children.

addAll

public boolean addAll(Collection c)

add Collection to set of Children (Unsupported) implementations must synchronized on the hierarchy lock and "children" protected field

Tags copied from interface: Collection

Parameters:

c - elements to be inserted into this collection.

Returns:

true if this collection changed as a result of the call

Throws:

UnsupportedOperationException - if this collection does not support the addAll method.

ClassCastException - if the class of an element of the specified collection prevents it from being added to this collection.

IllegalArgumentException - some aspect of an element of the specified collection prevents it from being added to this collection.

See Also:

Collection.add(Object)

removeAll

public boolean removeAll(Collection c)

remove all specified children (Unsupported) implementations must synchronized on the hierarchy lock and "children" protected field

Tags copied from interface: Collection

Parameters:

c - elements to be removed from this collection.

Returns:

true if this collection changed as a result of the call

Throws:

UnsupportedOperationException - if the removeAll method is not supported by this collection.

See Also:

Collection.remove(Object), Collection.contains(Object)

retainAll

public boolean retainAll(Collection c)

retain only specified children (Unsupported) implementations must synchronized on the hierarchy lock and "children" protected field

Tags copied from interface: Collection

Parameters:

c - elements to be retained in this collection.

Returns:

true if this collection changed as a result of the call

Throws:

UnsupportedOperationException - if the retainAll method is not supported by this Collection.

See Also:

Collection.remove(Object), Collection.contains(Object)

clear

public void clear()

clear the children (Unsupported) implementations must synchronized on the hierarchy lock and "children" protected field

Tags copied from interface: Collection

Throws:

UnsupportedOperationException - if the clear method is not supported by this collection.

addBeanContextMembershipListener

public void addBeanContextMembershipListener(BeanContextMembershipListener bcml)

Adds a BeanContextMembershipListener

Specified by:

addBeanContextMembershipListener in interface BeanContext

Parameters:

bcml - the BeanContextMembershipListener to add

removeBeanContextMembershipListener

public void removeBeanContextMembershipListener(BeanContextMembershipListener bcml)

Removes a BeanContextMembershipListener

Specified by:

removeBeanContextMembershipListener in interface BeanContext

Parameters:

bcml - the BeanContextMembershipListener to remove

getResourceAsStream

public InputStream getResourceAsStream(String name,
                                       BeanContextChild bcc)

Specified by:

getResourceAsStream in interface BeanContext

Parameters:

name - the name of the resource requested.

child - the child object making the request.

Returns:

the requested resource as an InputStream

getResource

public URL getResource(String name,
                       BeanContextChild bcc)

Specified by:

getResource in interface BeanContext

Parameters:

name - the name of the resource requested.

child - the child object making the request.

Returns:

the requested resource as an InputStream

setDesignTime

public void setDesignTime(boolean dTime)

Description copied from interface: DesignMode

Sets the "value" of the "designTime" property.

Parameters:

dTime - the new designTime value

isDesignTime

public boolean isDesignTime()

Description copied from interface: DesignMode

A value of true denotes that JavaBeans should behave in design time mode, a value of false denotes runtime behavior.

Returns:

Design time

setLocale

public void setLocale(Locale newLocale)
               throws PropertyVetoException

Parameters:

newLocale - the new locale

getLocale

public Locale getLocale()

Returns:

the current Locale of the BeanContext

needsGui

public boolean needsGui()

Description copied from interface: Visibility

Determines whether this bean needs a GUI.

Tags copied from interface: Visibility

Returns:

True if the bean absolutely needs a GUI available in order to get its work done.

dontUseGui

public void dontUseGui()

notify this instance that it may no longer render a GUI.

okToUseGui

public void okToUseGui()

Notify this instance that it may now render a GUI

avoidingGui

public boolean avoidingGui()

Description copied from interface: Visibility

Determines whether this bean is avoiding using a GUI.

Returns:

is this instance avoiding using its GUI?

isSerializing

public boolean isSerializing()

Returns:

if this BeanContext is currently being serialized

bcsChildren

protected Iterator bcsChildren()

Returns:

an iterator for all the current BCSChild values

bcsPreSerializationHook

protected void bcsPreSerializationHook(ObjectOutputStream oos)
                                throws IOException

called by writeObject after defaultWriteObject() but prior to serialization of currently serializable children. This method may be overridden by subclasses to perform custom serialization of their state prior to this superclass serializing the children. This method should not however be used by subclasses to replace their own implementation (if any) of writeObject().

bcsPreDeserializationHook

protected void bcsPreDeserializationHook(ObjectInputStream ois)
                                  throws IOException,
                                         ClassNotFoundException

called by readObject after defaultReadObject() but prior to deserialization of any children. This method may be overridden by subclasses to perform custom deserialization of their state prior to this superclass deserializing the children. This method should not however be used by subclasses to replace their own implementation (if any) of readObject().

childDeserializedHook

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

called by readObject with the newly deserialized child and BCSChild

serialize

protected final void serialize(ObjectOutputStream oos,
                               Collection coll)
                        throws IOException

deserialize

protected final void deserialize(ObjectInputStream ois,
                                 Collection coll)
                          throws IOException,
                                 ClassNotFoundException

used by readObject to deserialize a collection

writeChildren

public final void writeChildren(ObjectOutputStream oos)
                         throws IOException

readChildren

public final void readChildren(ObjectInputStream ois)
                        throws IOException,
                               ClassNotFoundException

When an instance of this class is used as a delegate for the implementation of the BeanContext protocols (and its subprotocols) there exists a 'chicken and egg' problem during deserialization

vetoableChange

public void vetoableChange(PropertyChangeEvent pce)
                    throws PropertyVetoException

subclasses may envelope to monitor veto child property changes.

Specified by:

vetoableChange in interface VetoableChangeListener

Tags copied from interface: VetoableChangeListener

Parameters:

evt - a PropertyChangeEvent object describing the event source and the property that has changed.

Throws:

PropertyVetoException - if the recipient wishes the property change to be rolled back.

propertyChange

public void propertyChange(PropertyChangeEvent pce)

subclasses may envelope to monitor child property changes.

Specified by:

propertyChange in interface PropertyChangeListener

Tags copied from interface: PropertyChangeListener

Parameters:

evt - A PropertyChangeEvent object describing the event source and the property that has changed.

validatePendingAdd

protected boolean validatePendingAdd(Object targetChild)

Subclasses of this class may override, or envelope, this method to add validation behavior for the BeanContext to examine child objects immediately prior to their being added to the BeanContext.

validatePendingRemove

protected boolean validatePendingRemove(Object targetChild)

Subclasses of this class may override, or envelope, this method to add validation behavior for the BeanContext to examine child objects immediately prior to their being removed from the BeanContext.

childJustAddedHook

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

subclasses may override this method to simply extend add() semantics after the child has been added and before the event notification has occurred. The method is called with the child synchronized.

childJustRemovedHook

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

subclasses may override this method to simply extend remove() semantics after the child has been removed and before the event notification has occurred. The method is called with the child synchronized.

getChildVisibility

protected static final Visibility getChildVisibility(Object child)

Returns:

the Component (if any) associated with the specified Child

getChildSerializable

protected static final Serializable getChildSerializable(Object child)

Returns:

the Serializable (if any) associated with the specified Child

getChildPropertyChangeListener

protected static final PropertyChangeListener getChildPropertyChangeListener(Object child)

Returns:

the PropertyChangeListener (if any) of the specified child

getChildVetoableChangeListener

protected static final VetoableChangeListener getChildVetoableChangeListener(Object child)

Returns:

the VetoableChangeListener (if any) of the specified child

getChildBeanContextMembershipListener

protected static final BeanContextMembershipListener getChildBeanContextMembershipListener(Object child)

Returns:

the BeanContextMembershipListener (if any) of the specified child

getChildBeanContextChild

protected static final BeanContextChild getChildBeanContextChild(Object child)

Returns:

the BeanContextChild (if any) of the specified child

fireChildrenAdded

protected final void fireChildrenAdded(BeanContextMembershipEvent bcme)

Fire a BeanContextshipEvent on the BeanContextMembershipListener interface

fireChildrenRemoved

protected final void fireChildrenRemoved(BeanContextMembershipEvent bcme)

Fire a BeanContextshipEvent on the BeanContextMembershipListener interface

initialize

protected void initialize()

protected method called from constructor and readObject to initialize transient state of BeanContextSupport instance. This class uses this method to instantiate inner class listeners used to monitor PropertyChange and VetoableChange events on children. subclasses may envelope this method to add their own initialization behavior

copyChildren

protected final Object[] copyChildren()

classEquals

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

Returns:

if two class objects, or their names are equal.