BeanContext (GNU Classpath 0.94-pre Documentation)

Interface BeanContext

Acts as a container for sub-beans and as a sub-bean, so that an entire hierarchy of beans can be made up of BeanContexts.

Since I can't sprinkle the Collections interface documentation with special information for BeanContext implementors, I'll have to document special requirements for implementors of those functions here.

add() or addAll():

May add any Object into the hierarchy as well as a BeanContextChild, BeanContext or BeanContextProxy object. This way, any Bean can be in the hierarchy.
Must synchronize on BeanContext.globalHierarchyLock.
Don't add the Object if it's already there (only once per BeanContext).
If it is a BeanContextChild implementor, call setBeanContext() on it. If it's a BeanContextProxy implementor, call getBeanContextProxy().setBeanContext() on it. If setBeanContext() vetoes the change, back out all changes so far and throw IllegalStateException.
If it (or its proxy) implements Visibility, call dontUseGui() or okToUseGui() on it, depending on whether you (the BeanContext) feel like allowing it to use the GUI or not.
If it implements BeanContextChild or BeanContextProxy, register yourself (the BeanContext) as both a PropertyChangeListener and VetoableChangeListener on the "beanContext" property (it may also add itself on any other properties it wishes to).
If it is a listener or event source that you (the BeanContext) are interested in, you may register yourself to it or register it to you.
Fire a java.beans.beancontext.BeanContextMembershipEvent before exiting. addAll() should wait until everything is done changing before firing the event (or events) so that if a failure occurs, the backing-out process can proceed without any events being fired at all.

remove() or removeAll():

Must synchronize on BeanContext.globalHierarchyLock.
If the specified Object is not a child of this BeanContext, just exit without performing any actions.
Remove the Object from your collection of children.
If it is a BeanContextChild implementor, call setBeanContext(null) on it. If it's a BeanContextProxy implementor, call getBeanContextProxy().setBeanContext(null) on it. If setBeanContext() vetoes the change, back out all changes so far and throw IllegalStateException.
If you registered the Object to listen to you or registered yourself as a listener on the Object during add() or addAll(), undo the registration bycalling the appropriate removeListener() method.
Fire a java.beans.beancontext.BeanContextMembershipEvent before exiting. removeAll() should wait until everything is done changing before firing the event (or events) so that if a failure occurs, the backing-out process can proceed without any events being fired at all.

addAll(), removeAll(), retainAll() and clear() do not need to be implemented, but may be if so desired.

Similarly, Visibility and DesignMode methods should propagate changed values to children that implement interfaces of the same name.

A hierarchy of beans is mainly useful so that different sets of beans can be established, each with their own set of resources.

Since: JDK1.2

Field Summary
Object	globalHierarchyLock The global lock on changing any BeanContext hierarchy.

Field Summary

Object

globalHierarchyLock

The global lock on changing any BeanContext hierarchy.

Method Summary
void	addBeanContextMembershipListener(BeanContextMembershipListener listener) Add a listener on changes to the membership of this `BeanContext` object.
URL	getResource(String resourceName, BeanContextChild requestor) Get a resource.
InputStream	getResourceAsStream(String resourceName, BeanContextChild requestor) Get a resource as a stream.
Object	instantiateChild(String beanName) Instantiate a Bean using this Bean's `ClassLoader` and this `BeanContext` as the parent.
void	removeBeanContextMembershipListener(BeanContextMembershipListener listener) Remove a listener on changes to the membership of this `BeanContext` object.

Method Summary

void

addBeanContextMembershipListener(BeanContextMembershipListener listener)

Add a listener on changes to the membership of this BeanContext object.

URL

getResource(String resourceName, BeanContextChild requestor)

Get a resource.

InputStream

getResourceAsStream(String resourceName, BeanContextChild requestor)

Get a resource as a stream.

Object

instantiateChild(String beanName)

Instantiate a Bean using this Bean's ClassLoader and this BeanContext as the parent.

void

removeBeanContextMembershipListener(BeanContextMembershipListener listener)

Remove a listener on changes to the membership of this BeanContext object.

Field Detail

public Object globalHierarchyLock

The global lock on changing any BeanContext hierarchy. It kinda sucks that there is only one lock, since there can be multiple hierarchies. Oh well, I didn't design, I just code.

Methods that must (or do) synchronize on the global lock:

Implementors of BeanContext.add() and addAll()

UNKNOWN: fill in the rest of the methods which use the global lock.

Method Detail

public void addBeanContextMembershipListener(BeanContextMembershipListener listener)

Add a listener on changes to the membership of this BeanContext object.

Parameters: listener the listener to add.

public URL getResource(String resourceName, BeanContextChild requestor)

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.

Parameters: resourceName the name of the resource requested. requestor a reference to the child requesting the resource.

Returns: a URL to the requested resource.