Listener Methods
Jakarta > Tapestry
Jakarta
 
Font size:      

Listener Methods

Listener methods are the main approach by which you add application-specific behavior to your application.

Listener methods are a kind of call back; when a form is submitted, or a link is clicked. The listener methods exist within your page and component classes. Components such as DirectLink and Form take a listener parameter, and you can use a listener: binding reference to use a listener method in your class as the listener.

Note
The parameter type for listeners is IActionListener. Internally, Tapestry creates an object that implements that interface and uses reflection to invoke the corrsponding method on your page or component instance. On rare occasions, it is useful to create objects that implement the interface directly. For pages, components and the engine, there is a listeners property whose keys are the names of listener methods, but the listener: binding reference is easier to use.

A listener method is a public void method. It may take parameters, or may not ... the rules are discussed below. A simple listener method take no parameters, or takes a single parameter of type IRequestCycle. When using the DirectLink component, you may specify additional listener parameters. The listener parameters are encoded into the URL and will be available in a later request, when the listener is triggered.

Note
In Tapestry 3.0 and earlier, listener parameters were known as service parameters. In addition, listener methods had to be in a very fixed form, taking exactly one parameter of type IRequestCycle.

The listener can gain access these parameters in one of two ways:

Using the second method is usually the best way. The link parameter values are not simply converted into strings, they are encoded as strings but maintain their type; therefore, the listener method parameters must be of the correct type.

For example, suppose that the link encoded a String objectId and an integer index. The component in the template names the listener method, and the two parameters are passed into the DirectLink as an OGNL list expression:

<a jwcid="@DirectLink" listener="doClick" parameters="{ objectId, index }"> . . . </a>

In the Java class, the listener method might look like:

public void doClick(String objectId, int index)
{
  . . .
}

Alternately, the listener method could look like:

public void doClick(IRequestCycle cycle)
{
  Object[] parameters = cycle.getListenerParameters();
  String objectId = (String)parameters[0];
  int index = ((Integer)parameters[1]).intValue();
  
  . . .
}

This second case is maintained in Tapestry 4.0 mostly for backwards compatibility, or to handle the case where a single listener method must handle an indeterminate number of listener parameters.

In fact, Tapestry does a search for the most appropriate method, given the number of listener parameters:

Tapestry 3.0 and earlier only accepted the final variation. Don't get too tricky with multiple overloadings of the method; Tapestry doesn't attempt to match the listener parameter types to the method parameter types (it works just by comparing the number of parameters). However, you can count on Java boxing and autoboxing the parameter values (so you can use int and java.lang.Integer interchangeably).