2.2 interface java.beans.beancontext.BeanContextChild¹

Simple JavaBeans that do not require any support or knowledge of their environment shall continue to function as they do today. However both JavaBeans that wish to utilize their containing BeanContext, and BeanContexts that may be nested, require to implement a mechanism that enables the propagation of the reference to the enclosing BeanContext through to cognizant JavaBeans and nested BeanContexts, the interface proposed is:

public interface java.beans.beancontext.BeanContextChild {
	void        setBeanContext(BeanContext bc)
				throws PropertyVetoException;

	BeanContext getBeanContext();

	void addPropertyChangeListener
		(String name, PropertyChangeListener pcl);

     void removePropertyChangeListener
		(String name, PropertyChangeListener pcl);

	void addVetoableChangeListener
		(String name, VetoableChangeListener pcl);

     void removeVetoableChangeListener
		(String name, VetoableChangeListener pcl);

}

The expected usage is that some 3rd party shall invoke one of the appropriate methods defined on BeanContext (by virtue of its inheritance from Collection) in order to add a BeanContextChild to the membership of the target BeanContext. As a consequence the BeanContext shall attempt to set the BeanContextChild's "beanContext" property by invoking its setter method, setBeanContext(). Only a BeanContext may call a BeanContextChild's setBeanContext() method, since this is the mechanism that a BeanContext uses to notify a child that it is now has a new BeanContext value. Since this property is not directly settable or customizable by a user in the context of an application construction tool the BeanInfo for a BeanContextChild should set the hidden state for this property in order for builder tools to avoid presenting the property to the user for customization.

A BeanContextChild object may throw a PropertyVetoException, to notify the nesting BeanContext that it is unable to function/be nested within that particular BeanContext. Such a veto shall be interpreted by a BeanContext as an indication that the BeanContextChild has determined that it is unable to function in that particular BeanContext and is final.

During the un-nesting of a BeanContextChild from its BeanContext, it is possible for the child, or a 3rd party listening to the child's "beanContext" property for PropertyVetoEvents, to throw a PropertyVetoException to notify the caller that it is not in a state to be un-nested. In order to bound this interaction a BeanContextChild, or 3rd party, may veto the initial un-nesting notification, but may not veto any subsequent notifications, and must, upon receipt of such notifications, amend its state accordingly to prepare itself to be subsequently un-nested.

Note that classes that implement this interface, also act as an Event Source for (sub)interface(s) of java.beans.PropertyChangeListener, and are required to update their state accordingly and subsequently fire the appropriate java.beans.PropertyChangeEvent with propertyName = "beanContext", oldValue = the reference to the previous nesting BeanContext, and newValue = the reference to the new nesting BeanContext, to notify any Listeners that its nesting BeanContext has changed value.

BeanContextChild instances, or nested BeanContexts in the process of terminating themselves, shall invoke the remove() method on their nesting BeanContext in order to withdraw themselves from the hierarchy prior to termination.

2.2.1 Important Persistence considerations

Instances of BeanContextChild nested within an BeanContext, will typically define fields or instance variables that will contain references to their nesting BeanContext instance, and possibly services obtained from that BeanContextServices instance via its getService() method.

In order to ensure that the act of making such an instance persistent does not erroneously persist objects from the instances nesting environment, such instances shall be required to define such fields, or instance variables as either transient, or to implement custom persistence methods that avoid persisting such state.

This requirement is crucial since operations such as cutting and pasting object instances through a clipboard via object serialization will not function correctly if the act of serializing the target object also serializes much of the entire source environment it is nested within.