The "containment" portion of the Extensible Runtime Containment and Services Protocol is defined by the
BeanContext
interface. In its most basic form, aBeanContext
is used to logically group a set of related java beans, bean contexts, or arbitrary objects. JavaBeans nested into aBeanContext
are known as "child" beans. Once nested, a child bean can query itsBeanContext
for various membership information, as illustrated in the following examples.Here are some possible
BeanContext
containment scenarios:
The sample code presented in this chapter uses instances of the
BeanContextSupport
helper class to provide the basicBeanContext
functionality. ABeanContextSupport
object is simply a concrete implementation of theBeanContext
interface.With a
BeanContextSupport
instance, it is possible to:
- Add an object, bean, or
BeanContext
:boolean add(Object o)
- Remove an object, bean, or
BeanContext
:boolean remove(Object o)
- Add a
BeanContextMembershipListener
:void addBeanContextMembershipListener(BeanContextMembershipListener bcml)
- Remove a
BeanContextMembershipListener
:void removeBeanContextMembershipListener(BeanContextMembershipListener bcml)
- Get all JavaBean or
BeanContext
instances currently nested in thisBeanContext
as an array or as an Iterator:Object[] toArray()
,Object[] toArray(Object[] a)
, andIterator iterator()
- Determine whether or not a specified object is currently a child of the
BeanContext
:boolean contains(Object o)
- Get the number of children currently nested in this
BeanContext
:int size()
- Determine whether or not the
BeanContext
currently has zero children:boolean isEmpty()
- Instantiate a new JavaBean instance as a child of the target
BeanContext
:Object instantiateChild(String beanName)
The following test programs, which are run from the command line, illustrate the use of these methods.
The comments in the source code explain the purpose of each.
File:Example1.java
Output:import java.beans.beancontext.*; /** * A test program that adds a bean to a beancontext, and * reports on various aspects of the context's membership state. * This program also shows that a bean's getBeanContext() method * can be called to get a reference to its enclosing context. */ public class Example1 { private static BeanContextSupport context = new BeanContextSupport(); // The BeanContext private static BeanContextChildSupport bean = new BeanContextChildSupport(); // The JavaBean public static void main(String[] args) { report(); // Add the bean to the context System.out.println("Adding bean to context..."); context.add(bean); report(); } private static void report() { // Print out a report of the context's membership state. System.out.println("============================================="); // Is the context empty? System.out.println("Is the context empty? " + context.isEmpty()); // Has the context been set for the child bean? boolean result = (bean.getBeanContext()!=null); System.out.println("Does the bean have a context yet? " + result); // Number of children in the context System.out.println("Number of children in the context: " + context.size()); // Is the specific bean a member of the context? System.out.println("Is the bean a member of the context? " + context.contains(bean)); // Equality test if (bean.getBeanContext() != null) { boolean isEqual = (bean.getBeanContext()==context); // true means both references point to the same object System.out.println("Contexts are the same? " + isEqual); } System.out.println("============================================="); } }File:============================================= Is the context empty? true Does the bean have a context yet? false Number of children in the context: 0 Is the bean a member of the context? false ============================================= Adding bean to context... ============================================= Is the context empty? false Does the bean have a context yet? true Number of children in the context: 1 Is the bean a member of the context? true Contexts are the same? true =============================================Example2.java
Output:import java.beans.beancontext.*; /** * Test program that adds 100 beans to a context, * and calls size() to report the number of beans * currently nested. Finally, * this test calls toArray() to get references to * all child beans. */ public class Example2 { public static void main(String[] args) { // A BeanContext BeanContextSupport context = new BeanContextSupport(); // Many JavaBeans BeanContextChildSupport[] beans = new BeanContextChildSupport[100]; System.out.println("Number of children in the context: " + context.size()); // Create the beans and add them to the context for (int i = 0; i < beans.length; i++) { beans[i] = new BeanContextSupport(); context.add(beans[i]); } System.out.println("Number of children in the context: " + context.size()); // Context now has 100 beans in it, get references to them all Object[] children = context.toArray(); System.out.println("Number of objects retrieved from the context: " + children.length); } }File:Number of children in the context: 0 Number of children in the context: 100 Number of objects retrieved from the context: 100Example3.java
Output:import java.beans.beancontext.*; import java.io.*; /** * An example of how to use the instantiateChild() convenience method * to create a bean automatically nested into a bean context. */ public class Example3 { public static void main(String[] args) { BeanContextSupport context = new BeanContextSupport(); System.out.println("Number of children nested into the context: " + context.size()); BeanContextChildSupport child = null; try { child = (BeanContextChildSupport)context.instantiateChild("java.beans.beancontext.BeanContextChildSupport"); } catch(IOException e){ System.out.println("IOException occurred: " + e.getMessage()); } catch(ClassNotFoundException e){ System.out.println("Class not found: " + e.getMessage()); } System.out.println("Number of children nested into the context: " + context.size()); } }Number of children nested into the context: 0 Number of children nested into the context: 1BeanContextMembershipEvent Notification
The
BeanContext
API uses the standard Java event model to register listeners and deliver events. For an overview of this standard event model, refer to Handling Events. For details about handling specific events, see Writing Event Listeners.In a basic
BeanContext
, the event classes and interfaces involved are:
java.beans.beancontext.BeanContextMembershipEvent
: Encapsulates the list of children added to, or removed from, the membership of a particularBeanContext
. An instance of this event is fired whenever a successful add(), remove(), retainAll(), removeAll(), or clear() is invoked on a givenBeanContext
instance.java.beans.BeanContextMembershipListener
: Objects wishing to receive BeanContextMembershipEvents implement this interface. It defines methodsvoid childrenAdded(BeanContextMembershipEvent bcme)
andvoid childrenRemoved(BeanContextMembershipEvent bcme)
, which are called when a child is added to or removed from a givenBeanContext
instance.BeanContextMembershipEvent Notification: Sample Code
File:MembershipTest.java
Output:import java.beans.beancontext.*; /** * A simple test program to illustrate delivery * of the BeanContextMembershipEvent. */ public class MembershipTest { public static void main(String[] args) { BeanContextSupport context = new BeanContextSupport(); // the context MyMembershipListener listener = new MyMembershipListener(); BeanContextChildSupport bean = new BeanContextChildSupport(); // a JavaBean context.addBeanContextMembershipListener(listener); // now listening! context.add(bean); context.remove(bean); } } /** * A custom implementation of the BeanContextMembershipListener interface. */ class MyMembershipListener implements BeanContextMembershipListener { public void childrenAdded(BeanContextMembershipEvent bcme) { System.out.println("Another bean has been added to the context."); } public void childrenRemoved(BeanContextMembershipEvent bcme) { System.out.println("A bean has been removed from the context."); } }Another bean has been added to the context. A bean has been removed from the context.The same example, implemented using an anonymous inner class
Output:import java.beans.beancontext.*; public class MembershipTest { public static void main(String[] args) { BeanContextSupport context = new BeanContextSupport(); context.addBeanContextMembershipListener(new BeanContextMembershipListener() { public void childrenAdded(BeanContextMembershipEvent bcme) { System.out.println("Another bean has been added to the context."); } public void childrenRemoved(BeanContextMembershipEvent bcme) { System.out.println("A bean has been removed from the context."); } }); BeanContextChildSupport bean = new BeanContextChildSupport(); context.add(bean); context.remove(bean); } }Another bean has been added to the context. A bean has been removed from the context.