Action and Direct listeners

The Action, Direct and Form components (which make use of the action and direct services) inform the application when they have been triggered using listeners.

A listener is an object that implements one of two listener interfaces.

For Direct, the listener is specified by the IDirectListener interface:

public void directTriggered(IDirect component, String[] context,
  IRequestCycle cycle)
  throws RequestCycleException;

For Action and Form, the listener is specified by the IActionListener interface.

public void actionTriggered(IComponent component, IRequestCycle cycle)
  throws RequestCycleException;

Prior to release 1.0.2, it was necessary to create an object to be notified by the component; this was almost always an annonymous inner class:

public IActionListener getFormListener()
{
  return new IActionListener()
  {
    public void actionTriggered(IComponent component, IRequestCycle cycle)
      throws RequestCycleException
    {
      // perform some operation ...
    }
  };
}

Although elegant in theory, that's simply too much Java code for too little effect. Starting with Tapestry 1.0.2, it is possible to create a listener method instead.

A listener method takes one of two forms:

public void method-name(IRequestCycle cycle)
throws RequestCycleException;

Or:

public void method-name(String[] context, IRequestCycle cycle)
throws RequestCycleException;

The first option can act as either kind of listener. The second option is always a IDirectListener. In both cases, the method may omit the throws clause.

In reality, listener objects have not gone away. Instead, there's a mechanism whereby the appropriate listener object is created automatically when needed. Each component includes a property, listeners, that is a collection of listener objects for the component, synthesized from the available public methods. The listeners objects are properties, with the names corresponding to the method names.

Note

The class AbstractEngine (the baseclass for SimpleEngine) also implements a listeners property. This allows you to easily add listener methods to your application engine.

The earlier example is much simpler:

public void formSubmit(IRequestCycle cycle)
{
  // perform some operation ...
}

However, the property path for the listener binding must be changed, from formListener to listeners.formSubmit.