java.beans.beancontext

Class BeanContextSupport

Implemented Interfaces:
BeanContext, BeanContextChild, BeanContextServiceRevokedListener, BeanContextServicesListener, Collection, DesignMode, EventListener, Iterable, PropertyChangeListener, Serializable, VetoableChangeListener, Visibility
Known Direct 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 lcle)
Construct a BeanContextSupport instance.
BeanContextSupport(BeanContext peer, Locale lcle, boolean dtime)
Construct a BeanContextSupport instance.
BeanContextSupport(BeanContext peer, Locale lcle, 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)
protected void
bcsPreSerializationHook(ObjectOutputStream oos)
protected void
childDeserializedHook(Object child, BeanContextSupport.BCSChild bcsc)
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)
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()
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)
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()
This method should tell whether it is design time or runtime.
boolean
isEmpty()
Returns true if this bean context has no children.
boolean
isSerializing()
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)
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)
void
setDesignTime(boolean dtime)
The environment will call this method on your BeanContextChild when it is registered in a parent BeanContext or when behavior needs to switch from design time to runtime behavior (or vice versa).
void
setLocale(Locale newLocale)
int
size()
Get the number of elements in this collection.
Object[]
toArray()
Copy the current contents of this collection into an array.
Object[]
toArray(Object[] array)
Copy the current contents of this collection into an array.
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)

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 Details

bcmListeners

protected ArrayList bcmListeners

children

protected HashMap children

designTime

protected boolean designTime

locale

protected Locale locale

okToUseGui

protected boolean okToUseGui

Constructor Details

BeanContextSupport

public BeanContextSupport()
Construct a BeanContextSupport instance.

BeanContextSupport

public BeanContextSupport(BeanContext peer)
Construct a BeanContextSupport instance.

BeanContextSupport

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

BeanContextSupport

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

BeanContextSupport

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

Method Details

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)
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.
Throws:
UnsupportedOperationException - if this collection does not support the addAll operation.
ClassCastException - if some element of c cannot be added to this collection due to its type.
NullPointerException - if some element of c is null and this collection does not support the addition of null values.
NullPointerException - if c itself is null.
IllegalArgumentException - if some element of c cannot be added to this collection for some other reason.

addBeanContextMembershipListener

public void addBeanContextMembershipListener(BeanContextMembershipListener listener)
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()
            throws NotImplementedException
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,
                   NotImplementedException

bcsPreSerializationHook

protected void bcsPreSerializationHook(ObjectOutputStream oos)
            throws IOException,
                   NotImplementedException

childDeserializedHook

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

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()
Clear the collection, such that a subsequent call to isEmpty() would return true.
Specified by:
clear in interface Collection
Throws:
UnsupportedOperationException - if this collection does not support the clear operation.

contains

public boolean contains(Object o)
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).
Throws:
ClassCastException - if the type of o is not a valid type for this collection.
NullPointerException - if o is null and this collection doesn't support null values.

containsAll

public boolean containsAll(Collection c)
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.
Throws:
ClassCastException - if the type of any element in c is not a valid type for this collection.
NullPointerException - if some element of c is null and this collection does not support null values.
NullPointerException - if c itself is null.

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,
                   NotImplementedException

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()
            throws NotImplementedException

getChildBeanContextChild

protected static final BeanContextChild getChildBeanContextChild(Object child)
            throws NotImplementedException

getChildBeanContextMembershipListener

protected static final BeanContextMembershipListener getChildBeanContextMembershipListener(Object child)
            throws NotImplementedException

getChildPropertyChangeListener

protected static final PropertyChangeListener getChildPropertyChangeListener(Object child)
            throws NotImplementedException

getChildSerializable

protected static final Serializable getChildSerializable(Object child)
            throws NotImplementedException

getChildVetoableChangeListener

protected static final VetoableChangeListener getChildVetoableChangeListener(Object child)
            throws NotImplementedException

getChildVisibility

protected static final Visibility getChildVisibility(Object child)
            throws NotImplementedException

getLocale

public Locale getLocale()

getResource

public URL getResource(String name,
                       BeanContextChild bcc)
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:
Returns:
a URL to the requested resource.

getResourceAsStream

public InputStream getResourceAsStream(String name,
                                       BeanContextChild bcc)
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:
Returns:
the requested resource as a stream.

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.
Throws:
IOException - if an I/O error occurs in loading the class.
ClassNotFoundException - if the class, beanName, can not be found.

isDesignTime

public boolean isDesignTime()
This method should tell whether it is design time or runtime.
Specified by:
isDesignTime in interface DesignMode
Returns:
true if design time, false if runtime.

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()
            throws NotImplementedException

iterator

public Iterator iterator()
Obtain an Iterator over this collection.
Specified by:
iterator in interface Collection
iterator in interface Iterable
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,
                   NotImplementedException

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.

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 add.
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)
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.
Throws:
UnsupportedOperationException - if this collection does not support the removeAll operation.
ClassCastException - if the type of any element in c is not a valid type for this collection.
NullPointerException - if some element of c is null and this collection does not support removing null values.
NullPointerException - if c itself is null.

removeBeanContextMembershipListener

public void removeBeanContextMembershipListener(BeanContextMembershipListener bcml)
Remove a listener on changes to the membership of this BeanContext object.
Specified by:
removeBeanContextMembershipListener in interface BeanContext
Parameters:

retainAll

public boolean retainAll(Collection c)
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.
Throws:
UnsupportedOperationException - if this collection does not support the retainAll operation.
ClassCastException - if the type of any element in c is not a valid type for this collection.
NullPointerException - if some element of c is null and this collection does not support retaining null values.
NullPointerException - if c itself is null.

serialize

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

setDesignTime

public void setDesignTime(boolean dtime)
The environment will call this method on your BeanContextChild when it is registered in a parent BeanContext or when behavior needs to switch from design time to runtime behavior (or vice versa).

BeanContexts are required to fire PropertyChangeEvents when properties change. designTime is a property, and therefore when you implement setDesignTime(), you need to fire a PropertyChangeEvent with the old value, the new value and using PROPERTYNAME as the property name.

Specified by:
setDesignTime in interface DesignMode
Parameters:
See Also:
java.util.PropertyChangeEvent, BeanContext, DesignMode.PROPERTYNAME

setLocale

public void setLocale(Locale newLocale)
            throws PropertyVetoException

size

public int size()
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()
Copy the current contents of this collection into an array.
Specified by:
toArray in interface Collection
Returns:
an array of type Object[] and length equal to the size of this collection, containing the elements currently in this collection, in any order.

toArray

public Object[] toArray(Object[] array)
            throws NotImplementedException
Copy the current contents of this collection into an array. If the array passed as an argument has length less than the size of this collection, an array of the same run-time type as a, and length equal to the size of this collection, is allocated using Reflection. Otherwise, a itself is used. The elements of this collection are copied into it, and if there is space in the array, the following element is set to null. The resultant array is returned. Note: The fact that the following element is set to null is only useful if it is known that this collection does not contain any null elements.
Specified by:
toArray in interface Collection
Parameters:
Returns:
an array containing the elements currently in this collection, in any order.
Throws:
ArrayStoreException - if the type of any element of the collection is not a subtype of the element type of a.

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.

writeChildren

public final void writeChildren(ObjectOutputStream oos)
            throws IOException,
                   NotImplementedException

BeanContextSupport.java -- Copyright (C) 2003, 2005, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.