java.beans.beancontext
Interface BeanContext

All Superinterfaces:
BeanContextChild, Collection, DesignMode, Iterable, Visibility
All Known Subinterfaces:
BeanContextServices
All Known Implementing Classes:
BeanContextServicesSupport, BeanContextSupport

public interface BeanContext
extends Collection, BeanContextChild, Visibility, DesignMode

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

  1. 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.
  2. Must synchronize on BeanContext.globalHierarchyLock.
  3. Don't add the Object if it's already there (only once per BeanContext).
  4. 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.
  5. 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.
  6. 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).
  7. 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.
  8. 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():

  1. Must synchronize on BeanContext.globalHierarchyLock.
  2. If the specified Object is not a child of this BeanContext, just exit without performing any actions.
  3. Remove the Object from your collection of children.
  4. 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.
  5. 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.
  6. 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
static Object globalHierarchyLock
          The global lock on changing any BeanContext hierarchy.
 
Fields inherited from interface java.beans.DesignMode
PROPERTYNAME
 
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.
 
Methods inherited from interface java.util.Collection
add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray
 
Methods inherited from interface java.beans.beancontext.BeanContextChild
addPropertyChangeListener, addVetoableChangeListener, getBeanContext, removePropertyChangeListener, removeVetoableChangeListener, setBeanContext
 
Methods inherited from interface java.beans.Visibility
avoidingGui, dontUseGui, needsGui, okToUseGui
 
Methods inherited from interface java.beans.DesignMode
isDesignTime, setDesignTime
 

Field Detail

globalHierarchyLock

static final 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:

Method Detail

instantiateChild

Object instantiateChild(String beanName)
                        throws IOException,
                               ClassNotFoundException
Instantiate a Bean using this Bean's ClassLoader and this BeanContext as the parent.

This method exists mainly so that BeanContext implementations can perform extra actions on Beans that are created within them.

Parameters:
beanName - the name of the bean to instantiate
Returns:
the created Bean
Throws:
IOException - if there is an I/O problem during instantiation.
ClassNotFoundException - if a serialized Bean's class is not found.
See Also:
Beans.instantiate(java.lang.ClassLoader,java.lang.String), Beans.instantiate(java.lang.ClassLoader,java.lang.String,java.beans.beancontext.BeanContext)

getResource

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.
See Also:
ClassLoader.getResource(java.lang.String)

getResourceAsStream

InputStream getResourceAsStream(String resourceName,
                                BeanContextChild requestor)
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.

Parameters:
resourceName - the name of the resource requested.
requestor - a reference to the child requesting the resource.
Returns:
the requested resource as a stream.
See Also:
ClassLoader.getResourceAsStream(java.lang.String)

addBeanContextMembershipListener

void addBeanContextMembershipListener(BeanContextMembershipListener listener)
Add a listener on changes to the membership of this BeanContext object.

Parameters:
listener - the listener to add.

removeBeanContextMembershipListener

void removeBeanContextMembershipListener(BeanContextMembershipListener listener)
Remove a listener on changes to the membership of this BeanContext object.

Parameters:
listener - the listener to remove.