org.apache.click
Class ActionEventDispatcher

java.lang.Object
  extended by org.apache.click.ActionEventDispatcher

public class ActionEventDispatcher
extends Object

Provides a control ActionListener event dispatcher.

Please note: this class is meant for component development and can be ignored otherwise.

When registering an ActionListener you can specify the callback to occur for a specific event. For example ActionListeners can be registered to fire after the onProcess event. This event can be specified through the constant POST_ON_PROCESS_EVENT.

The ClickServlet will notify the ActionEventDispatcher which ActionListeners to fire. For example, after the onProcess event, the ClickServlet will notify the dispatcher to fire ActionListeners registered for the POST_ON_PROCESS_EVENT (this is the default event when listeners are fired).

Out of the box ActionEventDispatcher only supports the event POST_ON_PROCESS_EVENT (the default).

Example Usage

The following example shows how to register an ActionListener with a custom Control:
 public class MyLink extends AbstractControl {
     ...

     public boolean onProcess() {
         bindRequestValue();

         if (isClicked()) {
             // Dispatch an action listener event for invocation after
             // control processing has finished
             dispatchActionEvent();
         }

         return true;
     }
 } 
In this example if the link is clicked, it then calls AbstractControl.dispatchActionEvent(). This method registers the Control's action listener with ActionEventDispatcher. The ClickServlet will subsequently invoke the registered ActionListener.onAction(Control) method after all the Page controls onProcess() method have been invoked.


Nested Class Summary
 class ActionEventDispatcher.EventHolder
          Holds the list of listeners and event sources.
 
Field Summary
static int POST_ON_PROCESS_EVENT
          Indicates the listener should fire AFTER the onProcess event.
 
Constructor Summary
ActionEventDispatcher()
           
 
Method Summary
protected  void clearEvents()
          Clear the event list.
protected  ActionEventDispatcher.EventHolder createEventHolder(int event)
          Create a new EventHolder instance.
static void dispatchActionEvent(Control source, ActionListener listener)
          Register the event source and event ActionListener to be fired by the ClickServlet once all the controls have been processed.
static void dispatchActionEvent(Control source, ActionListener listener, int event)
          Register the event source and event ActionListener to be fired by the ClickServlet in the specified event.
protected  void errorOccurred(Throwable throwable)
          Allow the dispatcher to handle the error that occurred.
protected  boolean fireActionEvent(Context context, Control source, ActionListener listener, int event)
          Fire the action for the given listener and event source which return true if the page should continue processing.
protected  boolean fireActionEvents(Context context)
          Fire all the registered action events after the Page Controls have been processed and return true if the page should continue processing.
protected  boolean fireActionEvents(Context context, int event)
          Fire all the registered action events for the specified event and return true if the page should continue processing.
protected  boolean fireActionEvents(Context context, List<Control> eventSourceList, List<ActionListener> eventListenerList, int event)
          Fire the actions for the given listener list and event source list which return true if the page should continue processing.
protected  ActionEventDispatcher.EventHolder getEventHolder(int event)
          Return the EventHolder for the specified event.
protected static ActionEventDispatcher getThreadLocalDispatcher()
          Return the thread local dispatcher instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

POST_ON_PROCESS_EVENT

public static final int POST_ON_PROCESS_EVENT
Indicates the listener should fire AFTER the onProcess event. The POST_ON_PROCESS_EVENT is the event during which control listeners will fire.

See Also:
Constant Field Values
Constructor Detail

ActionEventDispatcher

public ActionEventDispatcher()
Method Detail

dispatchActionEvent

public static void dispatchActionEvent(Control source,
                                       ActionListener listener)
Register the event source and event ActionListener to be fired by the ClickServlet once all the controls have been processed.

Listeners registered by this method will be fired in the POST_ON_PROCESS_EVENT.

Parameters:
source - the action event source
listener - the event action listener
See Also:
dispatchActionEvent(org.apache.click.Control, org.apache.click.ActionListener, int)

dispatchActionEvent

public static void dispatchActionEvent(Control source,
                                       ActionListener listener,
                                       int event)
Register the event source and event ActionListener to be fired by the ClickServlet in the specified event.

Parameters:
source - the action event source
listener - the event action listener
event - the specific event to trigger the action event

errorOccurred

protected void errorOccurred(Throwable throwable)
Allow the dispatcher to handle the error that occurred.

Parameters:
throwable - the error which occurred during processing

clearEvents

protected void clearEvents()
Clear the event list.


getThreadLocalDispatcher

protected static ActionEventDispatcher getThreadLocalDispatcher()
Return the thread local dispatcher instance.

Returns:
the thread local dispatcher instance.
Throws:
RuntimeException - if a ActionEventDispatcher is not available on the thread.

fireActionEvents

protected boolean fireActionEvents(Context context,
                                   List<Control> eventSourceList,
                                   List<ActionListener> eventListenerList,
                                   int event)
Fire the actions for the given listener list and event source list which return true if the page should continue processing.

This method will be passed the listener list and event source list of a specific event e.g. POST_ON_PROCESS_EVENT. event.

This method can be overridden if you need to customize the way events are fired.

Parameters:
context - the request context
eventSourceList - the list of source controls
eventListenerList - the list of listeners to fire
event - the specific event which events to fire
Returns:
true if the page should continue processing or false otherwise

fireActionEvents

protected boolean fireActionEvents(Context context)
Fire all the registered action events after the Page Controls have been processed and return true if the page should continue processing.

Parameters:
context - the request context
Returns:
true if the page should continue processing or false otherwise
See Also:
fireActionEvents(org.apache.click.Context, int)

fireActionEvents

protected boolean fireActionEvents(Context context,
                                   int event)
Fire all the registered action events for the specified event and return true if the page should continue processing.

Parameters:
context - the request context
event - the event which listeners to fire
Returns:
true if the page should continue processing or false otherwise

fireActionEvent

protected boolean fireActionEvent(Context context,
                                  Control source,
                                  ActionListener listener,
                                  int event)
Fire the action for the given listener and event source which return true if the page should continue processing.

This method will be passed a listener and source of a specific event e.g. POST_ON_PROCESS_EVENT.

This method can be overridden if you need to customize the way events are fired.

Parameters:
context - the request context
source - the source control
listener - the listener to fire
event - the specific event which events to fire
Returns:
true if the page should continue processing or false otherwise

getEventHolder

protected ActionEventDispatcher.EventHolder getEventHolder(int event)
Return the EventHolder for the specified event.

Parameters:
event - the event which EventHolder to retrieve
Returns:
the EventHolder for the specified event

createEventHolder

protected ActionEventDispatcher.EventHolder createEventHolder(int event)
Create a new EventHolder instance.

Parameters:
event - the EventHolder's event
Returns:
new EventHolder instance