org.apache.cocoon.forms.util
Class WidgetFinder

java.lang.Object
  org.apache.cocoon.forms.util.WidgetFinder

public class WidgetFinder
extends Object

An utility class to manage list of widgets.

The Widget.lookupWidget(String) method is able to only return one widget, while this class returns a list of widgets. It uses a path syntax containing a /./, repeater/./foo, which repreesents all the instances of the foo widget inside the repeater, one per row. Note that it also supports finding a widgets inside multi level repeaters, something like invoices/./movements/./amount or courseYears/./exams/./preparatoryCourses/./title .

Class has been designed to offer good performances, since the widget list is built only once and is automatically updated when a repeater row is added or removed. RepeaterListeners can be attached directly to receive notifications of widget additions or removals.

This class is used in CalculatedFields and CalculatedFieldAlgorithms.

Version:

$Id: WidgetFinder.html 1304258 2012-03-23 10:09:27Z ilgrosso $

Constructor Summary

WidgetFinder(Widget context, Iterator paths, boolean keepUpdated)
Searches for widgets.

WidgetFinder(Widget context, String path, boolean keepUpdated)
Searches for widgets.

Method Summary

void	addRepeaterListener(RepeaterListener listener) Adds a repeater listener.
List	getNewAdditions() Gets the new widgets that has been added to the list, as a consequence of new repeater rows additions, since last time this method was called or the finder was initialized.
Collection	getWidgets() Return all widgets found for the given paths.
boolean	hasNewAdditions()
boolean	hasRepeaterListeners()
boolean	isMutable()
protected void	refreshForAdd(Repeater repeater, int index) Called when a new row addition event is received from a monitored repeater.
protected void	refreshForClear(Repeater repeater) Called when a repeater clear event is received from a monitored repeater.
protected void	refreshForDelete(Repeater repeater, int index) Called when a row deletion event is received from a monitored repeater.
void	removeRepeaterListener(RepeaterListener listener) Removes a listener.

Methods inherited from class java.lang.Object

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

Constructor Detail

WidgetFinder

public WidgetFinder(Widget context,
                    Iterator paths,
                    boolean keepUpdated)

Searches for widgets. It will iterate on the given paths and find all corresponding widgets. If a path is in the forms repeater/* /widget then all the rows of the repeater will be iterated and subwidgets will be fetched.

Parameters:

context - The context widget to start from.

paths - An iterator of Strings containing the paths.

keepUpdated - If true, listeners will be installed on repeaters to keep lists updated without polling.

WidgetFinder

public WidgetFinder(Widget context,
                    String path,
                    boolean keepUpdated)

Searches for widgets. If path is in the forms repeater/* /widget then all the rows of the repeater will be iterated and subwidgets will be fetched.

Parameters:

context - The context widget to start from.

path - Path to search for..

keepUpdated - If true, listeners will be installed on repeaters to keep lists updated without polling.

Method Detail

refreshForAdd

protected void refreshForAdd(Repeater repeater,
                             int index)

Called when a new row addition event is received from a monitored repeater.

Parameters:

repeater - The repeated that generated the event.

index - The new row index.

refreshForDelete

protected void refreshForDelete(Repeater repeater,
                                int index)

Called when a row deletion event is received from a monitored repeater.

Parameters:

repeater - The repeated that generated the event.

index - The deleted row index.

refreshForClear

protected void refreshForClear(Repeater repeater)

Called when a repeater clear event is received from a monitored repeater.

Parameters:

repeater - The repeated that generated the event.

getWidgets

public Collection getWidgets()

Return all widgets found for the given paths.

Returns:

A Collection of Widgets.

isMutable

public boolean isMutable()

Returns:

true if this finder is mutable (i.e. it's monitoring some repeaters) or false if getWidgets() will always return the same list (i.e. it's not monitoring any widget).

hasNewAdditions

public boolean hasNewAdditions()

Returns:

true if new widgets have been added to this list (i.e. new repeater rows have been created) since last time getNewAdditions() was called.

getNewAdditions

public List getNewAdditions()

Gets the new widgets that has been added to the list, as a consequence of new repeater rows additions, since last time this method was called or the finder was initialized.

Returns:

A List of Widgets.

addRepeaterListener

public void addRepeaterListener(RepeaterListener listener)

Adds a repeater listener. New widget additions or deletions will be notified thru this listener (events received from monitored repeaters will be forwarded, use getNewAdditions() to retrieve new widgets).

Parameters:

listener - The listener to add.

removeRepeaterListener

public void removeRepeaterListener(RepeaterListener listener)

Removes a listener. See addRepeaterListener(RepeaterListener).

Parameters:

listener - The listener to remove.

hasRepeaterListeners

public boolean hasRepeaterListeners()

Returns:

true if there are listeners registered on this instance. See addRepeaterListener(RepeaterListener).