*
* The difference between a BeanContext and a
* BeanContextChild, mainly, is that a
* BeanContext may be a parent.
*
*
* BeanContextChild instances will be serialized at some
* point in their life, but you need to make sure your bean context does
* not contain a serializable reference (directly or indirectly) to the
* parent BeanContext, to any of the other
* BeanContexts in the tree, or to any resources obtained
* via the BeanContextServices interface. One way to do this
* is to mark any fields that contain such references as
* transient. Another way is to use a custom serializer.
*
*
* If you do not do this, when the BeanContext is serialized,
* all the other BeanContexts and other unnecessary things
* will be serialized along with it.
*
*
* Before dying, a BeanContextChild should call
* getBeanContext().remove(this) to detach from the
* hierarchy and exit cleanly.
*
* @author John Keiser
* @since JDK1.2
* @see java.beans.beancontext.BeanContext
*/
public interface BeanContextChild {
/**
* Set the parent BeanContext.
*
*
* This method is called from BeanContext.add() and
* should not be called directly.
*
* * When this Object is being added to a new BeanContext or moved * from an old one, a non-null value will be passed in. *
*
* When this Object is being removed from the current
* BeanContext, setBeanContext() will
* receive the parameter null.
*
*
* When being removed from the current BeanContext,
* it is the BeanContextChild's responsibility to
* release all services it has obtained.
*
*
* This change should generate PropertyChangeEvent
* and VetoableChangeEvents with the property name
* "beanContext". If the change is vetoed, it must re-throw the
* exception and not change anything. In this way, the parent
* BeanContextChild, who has registered himself with
* you, will have a chance to remove this child from its
* collection.
*
*
* If the Bean does not wish to change the parent or be removed
* from one, it may throw the PropertyVetoException.
* If you veto a setBeanContext(null) call, then you
* should try your hardest to remedy whatever problem is keeping
* you from being removed from the BeanContext so
* that you can not veto it the next time.
* Otherwise, nasty pathological recursion stuff could occur in
* certain situations.
*
* * If you do veto the change, you must first back out any changes * you made prior to the veto. Best not to make any such changes * prior to the veto in the first place. *
*
* This method is called from BeanContext.add() and
* should not be called directly.
*
* @param parent the new parent for the BeanContextChild,
* or null to signify removal from a tree.
* @exception PropertyVetoException if the
* BeanContextChild implementor does not
* wish to have its parent changed.
*/
void setBeanContext(BeanContext parent)
throws PropertyVetoException;
/**
* Get the parent BeanContext.
* @return the parent BeanContext.
*/
BeanContext getBeanContext();
/**
* Add a listener that will be notified when a specific property changes.
* @param prop the name of the property to listen on
* @param listener the listener to listen on the property.
*/
void addPropertyChangeListener(String prop, PropertyChangeListener listener);
/**
* Remove a listener to a certain property.
* @param prop the name of the property being listened on
* @param listener the listener listening on the property.
*/
void removePropertyChangeListener(String prop, PropertyChangeListener listener);
/**
* Add a listener that will be notified when a specific property
* change is requested (a PropertyVetoException may be thrown) as
* well as after the change is successfully made.
*
* @param prop the name of the property to listen on
* @param listener the listener to listen on the property.
*/
void addVetoableChangeListener(String prop, VetoableChangeListener listener);
/**
* Remove a listener to a certain property.
* @param prop the name of the property being listened on
* @param listener the listener listening on the property.
*/
void removeVetoableChangeListener(String prop, VetoableChangeListener listener);
}