Class EventListenerTag
- java.lang.Object
-
- org.apache.commons.jelly.TagSupport
-
- net.sf.jguiraffe.gui.builder.components.tags.FormBaseTag
-
- net.sf.jguiraffe.gui.builder.action.tags.EventListenerTag
-
- All Implemented Interfaces:
ConditionalTag
,org.apache.commons.jelly.Tag
- Direct Known Subclasses:
FormEventListenerTag
,WindowListenerTag
public abstract class EventListenerTag extends FormBaseTag
A base class for event listener tags.
This tag handler class provides basic functionality for declarative event listener support. Per default, event listeners are registered manually at the corresponding components (e.g. by calling methods of the
FormEventManager
class. With the event listener tag family it is now possible to declare event listeners in a builder script. This is done by delegating events to actions (making use of theActionInvoker
class).Actions can be defined in the builder script or are obtained from the action store maintained by the current
BuilderData
object. This tag handler class is passed anactionName
attribute that identifies the action to be invoked. It also supports the definition of anEventFilter
object, which can be specified either through theeventFilter
attribute or by nestingEventFilterTag
tags in the body of this tag.The basic idea is that a concrete sub class of
EventListenerTag
registers an event listener of a specific type at a component defined by a tag this tag is nested inside. This event listener will use the specified event filter (if any) to determine, for which event types the action is to be invoked. If the filter matches an event, the associated action is invoked.An advantage of this concept is that events can be treated as actions. So typical functionality of an application can be completely defined in action objects and is then also available for reacting on events. One example where this is useful is an action that terminates an application (of course only after asking the user whether unsaved changes should be stored). This action is per default associated with a menu item and maybe with a tool bar icon. With the mapping from event listeners to actions it is also possible to invoke this action when the close icon of the application's main window is clicked - without having to write any glue code.
This base class provides a simple framework for dealing with filters and creating an
ActionInvoker
object. Concrete sub classes have to implement the#createAndRegisterListener()
method, which will be invoked by the implementation of theprocess()
method. The following attributes are supported:Attribute Description Optional actionName Here the name of the action that is to be called by the generated event handler must be specified. An action with this name is looked up in the current context. No eventFilter With this attribute the tag can be associated with an already existing filter. This attribute is only evaluated if no EventFilter
is specified by a nested tag.Yes var If this attribute is specified, the tag stores the event listener that it has created under this name in the current context. This is useful if the listener should be added to other components, too. In this case it can be referenced by an <eventListener>
tag for instance.Yes targetBean Typically the target object the event listener is to be registered at is determined by the parent tag this tag is nested inside. Using the targetBean
attribute, an arbitrary object available in the currentBeanContext
can be defined as target of the registration. The tag will obtain a bean with the name specified here from the currentBeanContext
and delegate to the event manager to register the listener at this bean. It is possible to register a listener at both the object determined by the parent tag and the target object specified by this attribute. Only if the tag is not nested inside an appropriate tag and this attribute is not provided, an exception is thrown.Yes - Version:
- $Id: EventListenerTag.java 205 2012-01-29 18:29:57Z oheger $
- Author:
- Oliver Heger
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
EventListenerTag()
Creates a new instance ofEventListenerTag
.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description protected void
addBeanRegistrationCallbacks(EventListener listener, String beanName, Object params)
Creates callbacks for the registration of all event listener types at the specified bean.protected void
addComponentRegistrationCallbacks(EventListener listener, String compName)
Creates callbacks for the registration of all event listener types at the specified component.void
addListenerType(String typeName, Class<?> listenerClass)
Adds another listener type specified by the type name and the listener class.void
addListenerType(FormListenerType lt)
Adds another listener type in form of aFormListenerType
object.protected EventListener
createEventListener()
Creates an event listener object for all listener types that have been added to this tag.protected EventListener
createEventListener(Class<?>[] listenerClasses)
Creates an event listener proxy for all event listener classes in the specified array.protected FormAction
fetchAction()
Tries to obtain the action that is to be invoked by the event listener.protected EventFilter
fetchFilter()
Fetches the event filter if one is defined.protected Class<?>[]
fetchListenerClasses()
Returns an array with the classes of the event listeners this tag has to support.protected ActionBuilder
getActionBuilder()
Returns a reference to the currentActionBuilder
instance.protected ActionManager
getActionManager()
Convenience method for obtaining a reference to the currentActionManager
.String
getActionName()
Returns the name of the action to be invoked.String
getEventFilter()
Returns the name of the filter to be used.String
getTargetBean()
Returns the name of the target bean.String
getVar()
Returns a variable name for storing the event listener created by this tag.protected void
process()
Executes this tag.protected void
processBeforeBody()
Performs processing before the tag's body is evaluated.protected abstract boolean
registerListener(EventListener listener)
Registers the event listener.void
setActionName(String actionName)
Setter method for the actionName attribute.void
setEventFilter(String filterName)
Setter method for the eventFilter attribute.void
setTargetBean(String targetBean)
Set method of thetargetBean
attribute.void
setVar(String var)
Set method of thevar
attribute.-
Methods inherited from class net.sf.jguiraffe.gui.builder.components.tags.FormBaseTag
canProcess, canProcess, convertToClass, convertToNumberWithUnit, convertToNumberWithUnit, doTag, findContainer, getBuilderData, getBuilderData, getIfName, getResourceText, getResourceText, getUnlessName, setIfName, setUnlessName
-
Methods inherited from class org.apache.commons.jelly.TagSupport
findAncestorWithClass, findAncestorWithClass, findAncestorWithClass, findAncestorWithClass, findAncestorWithClass, findAncestorWithClass, getBody, getBodyText, getBodyText, getContext, getParent, invokeBody, isEscapeText, isTrim, setBody, setContext, setEscapeText, setParent, setTrim, trimBody
-
-
-
-
Method Detail
-
getActionName
public String getActionName()
Returns the name of the action to be invoked.- Returns:
- the action's name
-
setActionName
public void setActionName(String actionName)
Setter method for the actionName attribute.- Parameters:
actionName
- the attribute's value
-
getEventFilter
public String getEventFilter()
Returns the name of the filter to be used.- Returns:
- the filter's name
-
setEventFilter
public void setEventFilter(String filterName)
Setter method for the eventFilter attribute.- Parameters:
filterName
- the attribute's value
-
getTargetBean
public String getTargetBean()
Returns the name of the target bean.- Returns:
- the target bean
-
setTargetBean
public void setTargetBean(String targetBean)
Set method of thetargetBean
attribute.- Parameters:
targetBean
- the attribute's value
-
getVar
public String getVar()
Returns a variable name for storing the event listener created by this tag.- Returns:
- the name of a variable for the event listener
-
setVar
public void setVar(String var)
Set method of thevar
attribute.- Parameters:
var
- the attribute's value
-
addListenerType
public final void addListenerType(FormListenerType lt)
Adds another listener type in form of aFormListenerType
object. The event listener produced by this tag will also support this listener interface.- Parameters:
lt
- theFormListenerType
-
addListenerType
public final void addListenerType(String typeName, Class<?> listenerClass)
Adds another listener type specified by the type name and the listener class. The event listener produced by this tag will also support this listener interface. This method can be used for non-standard event types.- Parameters:
typeName
- the name of the listener typelistenerClass
- the class of the listener interface- See Also:
FormEventManager.addEventListener(String, String, java.util.EventListener)
-
processBeforeBody
protected void processBeforeBody() throws org.apache.commons.jelly.JellyTagException, FormBuilderException
Performs processing before the tag's body is evaluated. This implementation resets the current filter variable. If an event filter tag is placed in this tag's body, the variable will be set again.- Overrides:
processBeforeBody
in classFormBaseTag
- Throws:
org.apache.commons.jelly.JellyTagException
- if an error occursFormBuilderException
- if the tag is incorrectly used
-
process
protected void process() throws org.apache.commons.jelly.JellyTagException, FormBuilderException
Executes this tag. This implementation creates the event listener and handles its registration at a bean if necessary. Then it delegates toregisterListener(EventListener)
, which does tag-specific listener registration.- Specified by:
process
in classFormBaseTag
- Throws:
org.apache.commons.jelly.JellyTagException
- if an error occursFormBuilderException
- if the tag is incorrectly used
-
createEventListener
protected EventListener createEventListener(Class<?>[] listenerClasses) throws org.apache.commons.jelly.JellyTagException, FormBuilderException
Creates an event listener proxy for all event listener classes in the specified array. This method creates anActionInvoker
object and initialize it with the specified action and filter. Note: This implementation expects that the resulting listener can be cast tojava.util.EventListener
.- Parameters:
listenerClasses
- an array with the event listener classes- Returns:
- the event listener proxy
- Throws:
org.apache.commons.jelly.JellyTagException
- if the tag is incorrectly usedFormBuilderException
- if an error occurs
-
createEventListener
protected EventListener createEventListener() throws org.apache.commons.jelly.JellyTagException, FormBuilderException
Creates an event listener object for all listener types that have been added to this tag. This method obtains the classes for the event listener interfaces by callingfetchListenerClasses()
. Then it delegates tocreateEventListener(Class[])
to create the listener object. The listener object returned by this method is added to the target object.- Returns:
- the event listener object.
- Throws:
org.apache.commons.jelly.JellyTagException
- if the tag is incorrectly usedFormBuilderException
- if an error occurs
-
fetchAction
protected FormAction fetchAction() throws org.apache.commons.jelly.JellyTagException, FormBuilderException
Tries to obtain the action that is to be invoked by the event listener. This action is fetched from the current action store. If this fails, an exception will be thrown.- Returns:
- the action to be invoked
- Throws:
org.apache.commons.jelly.JellyTagException
- if the tag is incorrectly usedFormBuilderException
- if a required attribute is missing
-
fetchFilter
protected EventFilter fetchFilter() throws org.apache.commons.jelly.JellyTagException
Fetches the event filter if one is defined. Filters defined in the tag's body take precedence. If a filter in the tag's body is defined, it is used. Otherwise the value of theeventFilter
attribute is checked. If it is defined, a filter with this name is fetched from the Jelly context.- Returns:
- the filter to be used (can be null)
- Throws:
org.apache.commons.jelly.JellyTagException
- if a filter name is specified, which cannot be resolved
-
addComponentRegistrationCallbacks
protected void addComponentRegistrationCallbacks(EventListener listener, String compName)
Creates callbacks for the registration of all event listener types at the specified component.- Parameters:
listener
- the listener objectcompName
- the name of the component
-
addBeanRegistrationCallbacks
protected void addBeanRegistrationCallbacks(EventListener listener, String beanName, Object params)
Creates callbacks for the registration of all event listener types at the specified bean.- Parameters:
listener
- the listener objectbeanName
- the name of the target beanparams
- the parameters for the callback
-
fetchListenerClasses
protected Class<?>[] fetchListenerClasses()
Returns an array with the classes of the event listeners this tag has to support.- Returns:
- the specified event listener classes
-
registerListener
protected abstract boolean registerListener(EventListener listener) throws org.apache.commons.jelly.JellyTagException, FormBuilderException
Registers the event listener. This method is called during execution of this tag with the listener object created by thecreateEventListener()
method. Its task is to perform tag-specific listener registration (this base class already takes about registration of the event listener at a bean that may be specified using thetargetBean
attribute). The return value indicates whether a registration was possible. If it is false and notargetBean
attribute is defined, tag execution throws an exception because no target could be determined.- Parameters:
listener
- the listener to be registered- Returns:
- a flag whether registration was successful
- Throws:
org.apache.commons.jelly.JellyTagException
- if an error occursFormBuilderException
- if the tag is incorrectly used
-
getActionBuilder
protected ActionBuilder getActionBuilder()
Returns a reference to the currentActionBuilder
instance. This instance is expected to be placed in the Jelly context.- Returns:
- the current action builder
-
getActionManager
protected ActionManager getActionManager()
Convenience method for obtaining a reference to the currentActionManager
.- Returns:
- the current action manager
-
-