BeanContext

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> java >> beans >> [ beancontext overview ]

PREV CLASS NEXT CLASS

SUMMARY:

JAVADOC |

Sourc code of java.beans.beancontext.BeanContext

SOURCE |

Download java.beans.beancontext.BeanContext

DOWNLOAD | NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

java.beans.beancontext
Interface BeanContext

All Superinterfaces:: BeanContextChild, java.util.Collection, java.beans.DesignMode, java.lang.Iterable, java.beans.Visibility

All Known Subinterfaces:: BeanContextServices

All Known Implementing Classes:: BeanContextServicesSupport, BeanContextSupport

public interface BeanContext
extends java.util.Collection, BeanContextChild, java.beans.Visibility, java.beans.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():

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

static java.lang.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.

java.net.URL getResource(java.lang.String resourceName, BeanContextChild requestor)
          Get a resource.

java.io.InputStream getResourceAsStream(java.lang.String resourceName, BeanContextChild requestor)
          Get a resource as a stream.

java.lang.Object instantiateChild(java.lang.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

public static final java.lang.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()

Method Detail

instantiateChild

public java.lang.Object instantiateChild(java.lang.String beanName)
                                  throws java.io.IOException,
                                         java.lang.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.

getResource

public java.net.URL getResource(java.lang.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.

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.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.