java.beans.beancontext

Class BeanContextSupport

Implemented Interfaces:
BeanContext, BeanContextChild, BeanContextServiceRevokedListener, BeanContextServicesListener, Collection<E>, DesignMode, EventListener, Iterable<E>, 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<E>
bcmListeners
protected HashMap<K,V>
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<E> c)
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<E>
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<T> first, Class<T> 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<E> c)
boolean
containsKey(Object o)
protected Object[]
copyChildren()
protected BeanContextSupport.BCSChild
createBCSChild(Object targetChild, Object peer)
protected void
deserialize(ObjectInputStream ois, Collection<E> 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<E>
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)
Deerializes 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<E> c)
void
removeBeanContextMembershipListener(BeanContextMembershipListener bcml)
Remove a listener on changes to the membership of this BeanContext object.
boolean
retainAll(Collection<E> c)
protected void
serialize(ObjectOutputStream oos, Collection<E> 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, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

bcmListeners

protected ArrayList<E> bcmListeners

children

protected HashMap<K,V> 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.
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 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.

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<E> c)

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()
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<E> 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<T> first,
                                           Class<T> second)

clear

public void clear()
Clear the collection, such that a subsequent call to isEmpty() would return true.
Specified by:
clear in interface Collection<E>
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<E>
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<E> c)

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<E> 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).

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.

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)
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()
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.

isEmpty

public boolean isEmpty()
Returns true if this bean context has no children.
Specified by:
isEmpty in interface Collection<E>
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<E> iterator()
Obtain an Iterator over this collection.
Specified by:
iterator in interface Collection<E>
iterator in interface Iterable<E>
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
Deerializes the children using the deserialize(ObjectInputStream, Collection method and then calls childDeserializedHook(Object, BCSChild) for each child deserialized.
Parameters:
Throws:
IOException - if an I/O error occurs.

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<E>
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 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<E> c)

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<E> c)

serialize

protected final void serialize(ObjectOutputStream oos,
                               Collection<E> 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 -

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.

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<E>
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<E>
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.
Parameters:
array - an array to populate (null not permitted).

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
Serializes the children using the serialize(ObjectOutputStream, Collection method.
Parameters:
oos - the output stream.
Throws:
IOException - if an I/O error occurs.

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.