org.apache.click
Class ControlRegistry

java.lang.Object
  org.apache.click.ControlRegistry

public class ControlRegistry
extends Object

Provides a centralized registry where Controls can be registered and interact with the Click runtime.

The primary use of the ControlRegistry is for Controls to register themselves as potential targets of Ajax requests (If a control is an Ajax request target, it's onProcess() method is invoked while other controls are not processed).

Registering controls as Ajax targets serves a dual purpose. In addition to being potential Ajax targets, these controls will have all their Behaviors processed by the Click runtime.

Thus the ControlRegistry provides the Click runtime with easy access to Controls that want to be processed for Ajax requests. It also provides quick access to Controls that have Behaviors, and particularly AjaxBehaviors that want to handle and respond to Ajax requests.

Register Control as an Ajax Target

Below is an example of a Control registering itself as an Ajax target:

 public class AbstractControl implements Control {

     public void addBehavior(Behavior behavior) {
         getBehaviors().add(behavior);
         // Adding a behavior also registers the Control as an Ajax target
         ControlRegistry.registerAjaxTarget(this);
     }
 } 

Register Interceptor

Below is an example of a Container registering a Behavior in order to intercept and decorate its child controls:

 public class MyContainer extends AbstractContainer {

     public void onInit() {
         Behavior controlInterceptor = getInterceptor();
         ControlRegistry.registerInterceptor(this, controlInterceptor);
     }

     private Behavior getInterceptor() {
         Behavior controlInterceptor = new Behavior() {

             // This method is invoked before the controls are rendered to the client
             public void preResponse(Control source) {
                 // Here we can add a CSS class attribute to each child control
                 addCssClassToChildControls();
             }

             // This method is invoked before the HEAD elements are retrieved for each Control
             public void preRenderHeadElements(Control source) {
             }

             // This method is invoked before the Control onDestroy event
             public void preDestroy(Control source) {
             }
         };
         return controlInterceptor;
     }
 } 

Constructor Summary

ControlRegistry(ConfigService configService)
Construct the ControlRegistry with the given ConfigService.

Method Summary

protected void	errorOccurred(Throwable throwable) Allow the registry to handle the error that occurred.
static ControlRegistry	getThreadLocalRegistry() Return the thread local ControlRegistry instance.
static boolean	hasThreadLocalRegistry() Returns true if a ControlRegistry instance is available on the current thread, false otherwise.
static void	registerAjaxTarget(Control control) Register the control to be processed by the Click runtime if the control is the Ajax target.
static void	registerInterceptor(Control control, Behavior controlInterceptor) Register a control event interceptor for the given Control and Behavior.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ControlRegistry

public ControlRegistry(ConfigService configService)

Construct the ControlRegistry with the given ConfigService.

Parameters:

configService - the click application configuration service

Method Detail

getThreadLocalRegistry

public static ControlRegistry getThreadLocalRegistry()

Return the thread local ControlRegistry instance.

Returns:

the thread local ControlRegistry instance.

Throws:

RuntimeException - if a ControlRegistry is not available on the thread

hasThreadLocalRegistry

public static boolean hasThreadLocalRegistry()

Returns true if a ControlRegistry instance is available on the current thread, false otherwise.

Unlike getThreadLocalRegistry() this method can safely be used and will not throw an exception if a ControlRegistry is not available on the current thread.

Returns:

true if an ControlRegistry instance is available on the current thread, false otherwise

registerAjaxTarget

public static void registerAjaxTarget(Control control)

Register the control to be processed by the Click runtime if the control is the Ajax target. A control is an Ajax target if the Control.isAjaxTarget(org.apache.click.Context) method returns true. Once a target control is identified, Click invokes its Control.onProcess() method.

This method serves a dual purpose as all controls registered here will also have their Behaviors (if any) processed. Processing Behaviors means their interceptor methods will be invoked during the request life cycle, passing the control as the argument.

Parameters:

control - the control to register as an Ajax target

registerInterceptor

public static void registerInterceptor(Control control,
                                       Behavior controlInterceptor)

Register a control event interceptor for the given Control and Behavior. The control will be passed as the source control to the Behavior interceptor methods: preRenderHeadElements(Control), preResponse(Control) and preDestroy(Control).

Parameters:

control - the interceptor source control

controlInterceptor - the control interceptor to register

errorOccurred

protected void errorOccurred(Throwable throwable)

Allow the registry to handle the error that occurred.

Parameters:

throwable - the error which occurred during processing