org.apache.beehive.controls.runtime.bean
Class ControlBean

Object
  extended by ControlBean
All Implemented Interfaces:
BeanContextProxy, Serializable, ControlBean

public abstract class ControlBean
extends Object
implements ControlBean

The ControlBean class is an abstract base class for the JavaBean classes generated to support Beehive Controls.

The ControlBean class indirectly implements BeanContextProxy; the ControlBeanContext that it contains/scopes acts as that proxy.

All support APIs (which may be called from derived subclasses or contextual services) are generally marked as protected and have names that start with an underscore. This avoids the possibility that the name might conflict with a user-defined method on a control's public or extended Control interfaces.

NOTE: Adding public methods should be done with great care; any such method becomes part of the public API, and occupies the method namespace for all controls.

See Also:
Serialized Form

Field Summary
protected  Class _implClass
          The control implementation class bound to this ControlBean
 
Fields inherited from interface ControlBean
IDSeparator
 
Constructor Summary
protected ControlBean(ControlBeanContext context, String id, PropertyMap initProperties, Class controlIntf)
           
 
Method Summary
 void decodeImpl(Object impl)
          Called during XMLDecoder reconstruction of a ControlBean.
protected static void enforceVersionRequired(String intfName, Version version, VersionRequired versionRequired)
          Enforces the VersionRequired annotation at runtime (called from each ControlBean).
 Object ensureControl()
          Returns the target control instance associated with this ControlBean, performing lazy instantiation and initialization of the instance.
protected  Interceptor ensureInterceptor(String n)
          Retrieves interceptor instances, creates them lazily.
protected  void firePropertyChange(PropertyKey propertyKey, Object oldValue, Object newValue)
          Delivers a PropertyChangeEvent to any registered PropertyChangeListeners associated with the property referenced by the specified key.
protected  void fireVetoableChange(PropertyKey propertyKey, Object oldValue, Object newValue)
          Delivers a PropertyChangeEvent to any registered VetoableChangeListeners associated with the property referenced by the specified key.
protected  PropertyMap getAnnotationMap(AnnotatedElement annotElem)
          Returns the PropertyMap containing values associated with an AnnotatedElement.
 BeanContext getBeanContext()
          Returns the nesting BeanContext for this ControlBean.
 ControlBeanContext getBeanContextProxy()
          Return the BeanContextService proxy associated with this bean instance
 ControlBeanContext getControlBeanContext()
          Returns the bean context instance associated with the this bean, as opposed to the parent context returned by the public getBeanContext() API.
 String getControlID()
          Returns the control ID for this control
 Class getControlInterface()
          Returns the public interface for this control.
protected  Object getControlProperty(PropertyKey key)
          Returns a property on the ControlBean instance.
protected  Object getControlService(Class serviceClass, Object selector)
          Locates and obtains a context service from the BeanContextServices instance supporting this bean.
protected
<T> T
getEventNotifier(Class<T> eventSet)
          Returns an EventNotifier/UnicastEventNotifier for this ControlBean for the target event set
protected  ImplInitializer getImplInitializer()
          Obtains an instance of the appropriate ImplInitializer class
protected  String getLocalID()
          Returns the local (parent-relative) ID for this ControlBean
static Class getMostDerivedInterface(Class controlIntf)
          Computes the most derived ControlInterface for the specified ControlExtension.
protected  String[] getParameterNames(Method m)
          Returns the parameter names for a method on the ControlBean.
protected  PropertyChangeSupport getPropertyChangeSupport()
          This protected version is only available to concrete subclasses that expose bound property support.
protected abstract  Map getPropertyMapCache()
          Returns the local cache for ControlBean property maps.
protected  Object getRawControlProperty(PropertyKey key)
          Returns a property on the ControlBean instance.
protected  VetoableChangeSupport getVetoableChangeSupport()
          This protected version is only available to concrete subclasses that expose bound property support.
protected  void postInvoke(Method m, Object[] args, Object retval, Throwable t)
          The postInvoke method is called after all operations on the control.
protected  void postInvoke(Method m, Object[] args, Object retval, Throwable t, String[] interceptorNames, String pivotedInterceptor)
          The postInvoke method is called after all operations on the control.
protected  void preInvoke(Method m, Object[] args)
          The preinvoke method is called before all operations on the control.
protected  void preInvoke(Method m, Object[] args, String[] interceptorNames)
          The preinvoke method is called before all operations on the control.
 void setBeanContext(BeanContext bc)
          Called by the BeanContextProxy (_cbc) whenever the _parent_ context containing this control bean is changed.
protected  void setControlProperty(PropertyKey key, Object o)
          Sets a property on the ControlBean instance.
protected
<T> void
setEventNotifier(Class<T> eventSet, T notifier)
          Sets the EventNotifier for this ControlBean
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_implClass

protected Class _implClass
The control implementation class bound to this ControlBean

Constructor Detail

ControlBean

protected ControlBean(ControlBeanContext context,
                      String id,
                      PropertyMap initProperties,
                      Class controlIntf)
Parameters:
context - the containing ControlBeanContext. May be null, in which case the bean will attempt to associate with an active context at runtime (via thread-locals).
id - the local ID for the control, scoped to the control bean context.
initProperties - a PropertyMap containing initial properties for the control
controlIntf - the control interface or extension directly implemented by the control bean
Method Detail

getBeanContextProxy

public final ControlBeanContext getBeanContextProxy()
Return the BeanContextService proxy associated with this bean instance

Specified by:
getBeanContextProxy in interface BeanContextProxy

getBeanContext

public final BeanContext getBeanContext()
Returns the nesting BeanContext for this ControlBean. This is thread-safe even though it is not synchronized.

Specified by:
getBeanContext in interface ControlBean
Returns:
the containing BeanContext for the Java ControlBean.
See Also:
BeanContext

setBeanContext

public final void setBeanContext(BeanContext bc)
Called by the BeanContextProxy (_cbc) whenever the _parent_ context containing this control bean is changed. This is the place to do any initialization (or reinitialization) that is dependent upon attributes of the container for the ControlBean. Note: this is called in the ControlBean ctor, when a parent context calls add() on the nascent bean.

Parameters:
bc - the new parent context containing this control bean (not _cbc)

getControlID

public final String getControlID()
Returns the control ID for this control

Specified by:
getControlID in interface ControlBean
Returns:
the control ID

getControlInterface

public final Class getControlInterface()
Returns the public interface for this control.

Specified by:
getControlInterface in interface ControlBean
Returns:
the control public interface

getImplInitializer

protected ImplInitializer getImplInitializer()
Obtains an instance of the appropriate ImplInitializer class


ensureControl

public Object ensureControl()
Returns the target control instance associated with this ControlBean, performing lazy instantiation and initialization of the instance. REVIEW: could probably improve the granularity of locking here, but start w/ just synchronizing the entire fn.


preInvoke

protected void preInvoke(Method m,
                         Object[] args,
                         String[] interceptorNames)
                  throws InterceptorPivotException
The preinvoke method is called before all operations on the control. In addition to providing a basic hook for logging, context initialization, resource management, and other common services, it also provides a hook for interceptors.

Throws:
InterceptorPivotException

preInvoke

protected void preInvoke(Method m,
                         Object[] args)
The preinvoke method is called before all operations on the control. It is the basic hook for logging, context initialization, resource management, and other common services


postInvoke

protected void postInvoke(Method m,
                          Object[] args,
                          Object retval,
                          Throwable t,
                          String[] interceptorNames,
                          String pivotedInterceptor)
The postInvoke method is called after all operations on the control. In addition to providing the basic hook for logging, context initialization, resource management, and other common services, it also provides a hook for interceptors. During preInvoke, interceptors will be called in the order that they are in the list. During postInvoke, they will be called in the reverse order. Here is an example of the call sequence with I1, I2, and I3 being interceptors in the list: I1.preInvoke() -> I2.preInvoke() -> I3.preInvoke() -> invoke method | I1.postInvoke() <- I2.postInvoke() <- I3.postInvoke() <--- In the event that an interceptor in the list pivoted during preInvoke, the "pivotedInterceptor" parameter indicates the interceptor that had pivoted, and the interceptors succeeding it in the list will not be called during postInvoke.


postInvoke

protected void postInvoke(Method m,
                          Object[] args,
                          Object retval,
                          Throwable t)
The postInvoke method is called after all operations on the control. It is the basic hook for logging, context initialization, resource management, and other common services.


setEventNotifier

protected <T> void setEventNotifier(Class<T> eventSet,
                                    T notifier)
Sets the EventNotifier for this ControlBean


getEventNotifier

protected <T> T getEventNotifier(Class<T> eventSet)
Returns an EventNotifier/UnicastEventNotifier for this ControlBean for the target event set


getLocalID

protected String getLocalID()
Returns the local (parent-relative) ID for this ControlBean


getControlBeanContext

public ControlBeanContext getControlBeanContext()
Returns the bean context instance associated with the this bean, as opposed to the parent context returned by the public getBeanContext() API.

Specified by:
getControlBeanContext in interface ControlBean

getControlService

protected Object getControlService(Class serviceClass,
                                   Object selector)
                            throws TooManyListenersException
Locates and obtains a context service from the BeanContextServices instance supporting this bean. The base design for the BeanContextServicesSupport is that it will delegate up to peers in a nesting context, so a nested control bean will look 'up' to find a service provider.

Throws:
TooManyListenersException

setControlProperty

protected void setControlProperty(PropertyKey key,
                                  Object o)
Sets a property on the ControlBean instance. All generated property setter methods will delegate down to this method.


getRawControlProperty

protected Object getRawControlProperty(PropertyKey key)
Returns a property on the ControlBean instance. This version does not coerce an annotation type property from a PropertyMap to a proxy instance of the type.


getControlProperty

protected Object getControlProperty(PropertyKey key)
Returns a property on the ControlBean instance. All generated property getter methods will delegate down to this method


getPropertyMapCache

protected abstract Map getPropertyMapCache()
Returns the local cache for ControlBean property maps.


getAnnotationMap

protected PropertyMap getAnnotationMap(AnnotatedElement annotElem)
Returns the PropertyMap containing values associated with an AnnotatedElement. Elements that are associated with the bean's Control interface will be locally cached.


getPropertyChangeSupport

protected PropertyChangeSupport getPropertyChangeSupport()
This protected version is only available to concrete subclasses that expose bound property support. This method is synchronized to enable lazy instantiation, in the belief that is a bigger win to avoid allocating when there are no listeners than it is to introduce synchronization overhead on access.


firePropertyChange

protected void firePropertyChange(PropertyKey propertyKey,
                                  Object oldValue,
                                  Object newValue)
Delivers a PropertyChangeEvent to any registered PropertyChangeListeners associated with the property referenced by the specified key. This method *should not* be synchronized, as the PropertyChangeSupport has its own built in synchronization mechanisms.


getVetoableChangeSupport

protected VetoableChangeSupport getVetoableChangeSupport()
This protected version is only available to concrete subclasses that expose bound property support. This method is synchronized to enable lazy instantiation, in the belief that is a bigger win to avoid allocating when there are no listeners than it is to introduce synchronization overhead on access.


fireVetoableChange

protected void fireVetoableChange(PropertyKey propertyKey,
                                  Object oldValue,
                                  Object newValue)
                           throws PropertyVetoException
Delivers a PropertyChangeEvent to any registered VetoableChangeListeners associated with the property referenced by the specified key. This method *should not* be synchronized, as the VetoableChangeSupport has its own built in synchronization mechanisms.

Throws:
PropertyVetoException

getParameterNames

protected String[] getParameterNames(Method m)
Returns the parameter names for a method on the ControlBean. Actual mapping is done by generated subclasses, so if we reach the base ControlBean implementation, then no parameter names are available for the target method.


getMostDerivedInterface

public static Class getMostDerivedInterface(Class controlIntf)
Computes the most derived ControlInterface for the specified ControlExtension.

Parameters:
controlIntf -
Returns:
the most derived ControlInterface

enforceVersionRequired

protected static void enforceVersionRequired(String intfName,
                                             Version version,
                                             VersionRequired versionRequired)
Enforces the VersionRequired annotation at runtime (called from each ControlBean).

Parameters:
intfName -
version -
versionRequired -

decodeImpl

public void decodeImpl(Object impl)
Called during XMLDecoder reconstruction of a ControlBean.


ensureInterceptor

protected Interceptor ensureInterceptor(String n)
Retrieves interceptor instances, creates them lazily.