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
FormEventManagerclass. 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 theActionInvokerclass).Actions can be defined in the builder script or are obtained from the action store maintained by the current
BuilderDataobject. This tag handler class is passed anactionNameattribute that identifies the action to be invoked. It also supports the definition of anEventFilterobject, which can be specified either through theeventFilterattribute or by nestingEventFilterTagtags in the body of this tag.The basic idea is that a concrete sub class of
EventListenerTagregisters 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
ActionInvokerobject. 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 EventFilteris 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 targetBeanattribute, an arbitrary object available in the currentBeanContextcan be defined as target of the registration. The tag will obtain a bean with the name specified here from the currentBeanContextand 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 protectedEventListenerTag()Creates a new instance ofEventListenerTag.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description protected voidaddBeanRegistrationCallbacks(EventListener listener, String beanName, Object params)Creates callbacks for the registration of all event listener types at the specified bean.protected voidaddComponentRegistrationCallbacks(EventListener listener, String compName)Creates callbacks for the registration of all event listener types at the specified component.voidaddListenerType(String typeName, Class<?> listenerClass)Adds another listener type specified by the type name and the listener class.voidaddListenerType(FormListenerType lt)Adds another listener type in form of aFormListenerTypeobject.protected EventListenercreateEventListener()Creates an event listener object for all listener types that have been added to this tag.protected EventListenercreateEventListener(Class<?>[] listenerClasses)Creates an event listener proxy for all event listener classes in the specified array.protected FormActionfetchAction()Tries to obtain the action that is to be invoked by the event listener.protected EventFilterfetchFilter()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 ActionBuildergetActionBuilder()Returns a reference to the currentActionBuilderinstance.protected ActionManagergetActionManager()Convenience method for obtaining a reference to the currentActionManager.StringgetActionName()Returns the name of the action to be invoked.StringgetEventFilter()Returns the name of the filter to be used.StringgetTargetBean()Returns the name of the target bean.StringgetVar()Returns a variable name for storing the event listener created by this tag.protected voidprocess()Executes this tag.protected voidprocessBeforeBody()Performs processing before the tag's body is evaluated.protected abstract booleanregisterListener(EventListener listener)Registers the event listener.voidsetActionName(String actionName)Setter method for the actionName attribute.voidsetEventFilter(String filterName)Setter method for the eventFilter attribute.voidsetTargetBean(String targetBean)Set method of thetargetBeanattribute.voidsetVar(String var)Set method of thevarattribute.-
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 thetargetBeanattribute.- 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 thevarattribute.- Parameters:
var- the attribute's value
-
addListenerType
public final void addListenerType(FormListenerType lt)
Adds another listener type in form of aFormListenerTypeobject. 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, FormBuilderExceptionPerforms 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:
processBeforeBodyin 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, FormBuilderExceptionExecutes 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:
processin 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 anActionInvokerobject 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 theeventFilterattribute 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 thetargetBeanattribute). The return value indicates whether a registration was possible. If it is false and notargetBeanattribute 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 currentActionBuilderinstance. 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
-
-