Class 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 the ActionInvoker 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 an actionName attribute that identifies the action to be invoked. It also supports the definition of an EventFilter object, which can be specified either through the eventFilter attribute or by nesting EventFilterTag 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 the process() 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 current BeanContext can be defined as target of the registration. The tag will obtain a bean with the name specified here from the current BeanContext 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 Detail

      • EventListenerTag

        protected EventListenerTag()
        Creates a new instance of EventListenerTag.
    • 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 the targetBean 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 the var attribute.
        Parameters:
        var - the attribute's value
      • addListenerType

        public final void addListenerType​(FormListenerType lt)
        Adds another listener type in form of a FormListenerType object. The event listener produced by this tag will also support this listener interface.
        Parameters:
        lt - the FormListenerType
      • 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 type
        listenerClass - 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 class FormBaseTag
        Throws:
        org.apache.commons.jelly.JellyTagException - if an error occurs
        FormBuilderException - 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 to registerListener(EventListener), which does tag-specific listener registration.
        Specified by:
        process in class FormBaseTag
        Throws:
        org.apache.commons.jelly.JellyTagException - if an error occurs
        FormBuilderException - 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 an ActionInvoker object and initialize it with the specified action and filter. Note: This implementation expects that the resulting listener can be cast to java.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 used
        FormBuilderException - 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 calling fetchListenerClasses(). Then it delegates to createEventListener(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 used
        FormBuilderException - 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 used
        FormBuilderException - 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 the eventFilter 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 object
        compName - 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 object
        beanName - the name of the target bean
        params - 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 the createEventListener() 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 the targetBean attribute). The return value indicates whether a registration was possible. If it is false and no targetBean 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 occurs
        FormBuilderException - if the tag is incorrectly used
      • getActionBuilder

        protected ActionBuilder getActionBuilder()
        Returns a reference to the current ActionBuilder 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 current ActionManager.
        Returns:
        the current action manager