org.apache.beehive.controls.api.context
Interface ControlBeanContext

All Superinterfaces:
BeanContext, BeanContextChild, BeanContextServiceRevokedListener, BeanContextServices, BeanContextServicesListener, Collection, DesignMode, EventListener, Iterable, Visibility
All Known Subinterfaces:
ControlContainerContext
All Known Implementing Classes:
ControlBeanContext, ControlContainerContext, ServletBeanContext

public interface ControlBeanContext
extends BeanContextServices

The ControlBeanContext interface defines the basic set of contextual services and lifecycle events for Java ControlBean implementations.

ControlBeanContext also extends the java.beans.beancontext.BeanContextServices interface, so it also provide core Java Beans services for managing contained controls, looking up contextual services, and locating the parent BeanContext context.

A Control implementation class can obtain access to the ControlBeanContext associated with it by declaring an instance field of this type and annotating it with the org.apache.beehive.controls.api.context.Context annotation, as in the following example:

 import org.apache.beehive.controls.api.context.Context;
 import org.apache.beehive.controls.api.context.ControlBeanContext;

 @ControlImplementation
 public class MyControlImpl
 {
     @Context
     ControlBeanContext myContext;
 }
 
The Java Control runtime will automatically initialize this field to a reference to the ControlBeanContext associated with the implementation instance.


Nested Class Summary
static interface ControlBeanContext.LifeCycle
          The Lifecycle event interface defines a set of lifecycle events exposed by the ControlBeanContext to any registered listener.
 
Field Summary
 
Fields inherited from interface BeanContext
globalHierarchyLock
 
Fields inherited from interface DesignMode
PROPERTYNAME
 
Method Summary
 void addLifeCycleListener(ControlBeanContext.LifeCycle listener)
          Registers a new listener for LifeCycle events on the context.
 PropertyMap getAnnotationMap(AnnotatedElement annotElem)
          Returns the PropertyMap containing default properties for an AnnotatedElement in the current context.
 ControlBean getBean(String id)
          Returns any child ControlBean that is nested in the ControlBeanContext, or null if no matching child is found.
 ClassLoader getClassLoader()
          Returns the ClassLoader used to load the ControlBean class associated with the control implementation instance.
 ControlBean getControlBean()
          Returns the peer ControlBean associated with this ControlBeanContext.
 ControlHandle getControlHandle()
          Returns a ControlHandle instance that enables operations and events to be dispatched to the target control, if it is running inside of a container that supports external event dispatch.
 Class getControlInterface()
          Returns the public or extension interface associated with the context
 PropertyMap getControlPropertyMap()
          Returns the current set of properties (in PropertyMap format) for the control associated with the context.
<T extends Annotation>
T
getControlPropertySet(Class<T> propertySet)
          Returns the current value of PropertySet for the associated control, or null if the property set has not been bound.
<T extends Annotation>
T
getMethodPropertySet(Method m, Class<T> propertySet)
          Returns the current value of PropertySet for the provided method, or null if the property set has not been bound for this method.
 String[] getParameterNames(Method m)
          Returns an array containing the parameter names for the specified method
<T extends Annotation>
T
getParameterPropertySet(Method m, int i, Class<T> propertySet)
          Returns the current value of PropertySet for the selected (by index) method parameter, or null if the property set has not been bound for this method.
 Object getParameterValue(Method m, String parameterName, Object[] parameters)
          Returns the value of a named method parameter from the input parameter array.
<T> T
getService(Class<T> serviceClass, Object selector)
          Returns an instance of a contextual service based upon the local context.
 boolean isSingleThreadedContainer()
          Returns true if this container guarantees single-threaded behaviour.
 void removeLifeCycleListener(ControlBeanContext.LifeCycle listener)
          Removes a currently registered LifeCycle event listener on the context.
 
Methods inherited from interface BeanContextServices
addBeanContextServicesListener, addService, getCurrentServiceClasses, getCurrentServiceSelectors, getService, hasService, releaseService, removeBeanContextServicesListener, revokeService
 
Methods inherited from interface BeanContext
addBeanContextMembershipListener, getResource, getResourceAsStream, instantiateChild, removeBeanContextMembershipListener
 
Methods inherited from interface BeanContextChild
addPropertyChangeListener, addVetoableChangeListener, getBeanContext, removePropertyChangeListener, removeVetoableChangeListener, setBeanContext
 
Methods inherited from interface Collection
add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray
 
Methods inherited from interface DesignMode
isDesignTime, setDesignTime
 
Methods inherited from interface Visibility
avoidingGui, dontUseGui, needsGui, okToUseGui
 
Methods inherited from interface BeanContextServicesListener
serviceAvailable
 
Methods inherited from interface BeanContextServiceRevokedListener
serviceRevoked
 

Method Detail

getControlInterface

Class getControlInterface()
Returns the public or extension interface associated with the context


getControlPropertySet

<T extends Annotation> T getControlPropertySet(Class<T> propertySet)
Returns the current value of PropertySet for the associated control, or null if the property set has not been bound. Actual bindings for property values may be the result of annotations on the control field or class, property setting via factory arguments or setter APIs, or external configuration.

Parameters:
propertySet - the PropertySet to return
Returns:
the requested PropertySet instance, or null if not bound
See Also:
PropertySet

getMethodPropertySet

<T extends Annotation> T getMethodPropertySet(Method m,
                                              Class<T> propertySet)
                                          throws IllegalArgumentException
Returns the current value of PropertySet for the provided method, or null if the property set has not been bound for this method.

Parameters:
m - the Method to check for properties.
propertySet - the PropertySet to return
Returns:
the requested PropertySet instance, or null if not bound
Throws:
IllegalArgumentException
See Also:
PropertySet

getParameterPropertySet

<T extends Annotation> T getParameterPropertySet(Method m,
                                                 int i,
                                                 Class<T> propertySet)
                                             throws IllegalArgumentException,
                                                    IndexOutOfBoundsException
Returns the current value of PropertySet for the selected (by index) method parameter, or null if the property set has not been bound for this method.

Parameters:
m - the Method to check for properties
i - the index of the method parameter to check for the request PropertySet
propertySet - the PropertySet to return
Returns:
the request PropertySet instance, or null if not bound
Throws:
IllegalArgumentException
IndexOutOfBoundsException

getParameterNames

String[] getParameterNames(Method m)
                           throws IllegalArgumentException
Returns an array containing the parameter names for the specified method

Parameters:
m - the Method whose parameter names should be returned.
Returns:
the array of parameter names (or an empty array if no parameters)
Throws:
IllegalArgumentException

getParameterValue

Object getParameterValue(Method m,
                         String parameterName,
                         Object[] parameters)
                         throws IllegalArgumentException
Returns the value of a named method parameter from the input parameter array.

Parameters:
m - the Method associated with the input parameter list
parameterName - the name of the requested parameter
parameters - the array of method parameters
Returns:
the element in the input parameter array that corresponds to the requested parameter
Throws:
IllegalArgumentException

getControlPropertyMap

PropertyMap getControlPropertyMap()
Returns the current set of properties (in PropertyMap format) for the control associated with the context. The return map will contain the values for all bound properties for the control.

Returns:
the PropertyMap containing properties of the control. This map is read-only; any changes to it will not effect the local bean instance.
See Also:
PropertyMap

getService

<T> T getService(Class<T> serviceClass,
                 Object selector)
Returns an instance of a contextual service based upon the local context. If no provider for this service is available, then null will be returned.

Parameters:
serviceClass - the class of the requested service
selector - the service dependent parameter
Returns:
an instance of the request service, or null if unavailable
See Also:
BeanContextServices.getService(java.beans.beancontext.BeanContextChild, java.lang.Object, java.lang.Class, java.lang.Object, java.beans.beancontext.BeanContextServiceRevokedListener)

getControlHandle

ControlHandle getControlHandle()
Returns a ControlHandle instance that enables operations and events to be dispatched to the target control, if it is running inside of a container that supports external event dispatch. If the runtime container for the control does not support this functionality, a value of null will be returned.

Returns:
a ControlHandle instance for the control, or null.
See Also:
ControlHandle

getAnnotationMap

PropertyMap getAnnotationMap(AnnotatedElement annotElem)
Returns the PropertyMap containing default properties for an AnnotatedElement in the current context.


getClassLoader

ClassLoader getClassLoader()
Returns the ClassLoader used to load the ControlBean class associated with the control implementation instance. This is useful for loading other classes or resources that may have been packaged with the public interfaces of the Control type (since they may not necessarily have been packaged directly with the implementation class).


isSingleThreadedContainer

boolean isSingleThreadedContainer()
Returns true if this container guarantees single-threaded behaviour.


getControlBean

ControlBean getControlBean()
Returns the peer ControlBean associated with this ControlBeanContext. If the context represents a top-level container (i.e. not a Control containing other controls), null will be returned.


getBean

ControlBean getBean(String id)
Returns any child ControlBean that is nested in the ControlBeanContext, or null if no matching child is found. The id parameter is relative to the current nesting context, not an absolute control id.


addLifeCycleListener

void addLifeCycleListener(ControlBeanContext.LifeCycle listener)
Registers a new listener for LifeCycle events on the context.

See Also:
ControlBeanContext.LifeCycle

removeLifeCycleListener

void removeLifeCycleListener(ControlBeanContext.LifeCycle listener)
Removes a currently registered LifeCycle event listener on the context.

See Also:
ControlBeanContext.LifeCycle