Class UseBeanBaseTag

  • All Implemented Interfaces:
    ConditionalTag, PropertySupport, org.apache.commons.jelly.DynaTag, org.apache.commons.jelly.impl.BeanSource, org.apache.commons.jelly.Tag
    Direct Known Subclasses:
    ActionTaskTag, ComponentHandlerTag, ConverterTag, EventFilterTag, EventRegistrationTag, FormControllerListenerTag, PopupHandlerTag, TableEditorValidationHandlerTag, TableSelectionHandlerTag, TransformerBaseTag, WindowControllerTag

    public class UseBeanBaseTag
    extends org.apache.commons.jelly.tags.core.UseBeanTag
    implements ConditionalTag, PropertySupport

    A tag handler base class for tags that deal with the creation of service beans.

    The purpose of this tag is to make beans available to the currently running builder script. Beans can either be newly created, fetched from existing variables in the Jelly context or obtained from the current BeanContext (basically allowing builder scripts access to the dependency injection framework). The beans fetched in one of these ways can then be stored in variables in the Jelly context and/or passed to parent tags.

    This tag handler base class is a thin wrapper around Jelly's core <useBean> tag. From its super class it inherits the ability of creating and initializing new beans. This should only be used for very simple beans, which do not need a sophisticated initialization. For complex objects to be created the dependency injection framework should be used.

    After the resulting bean has been obtained the passResults() method is invoked. This method is intended to perform some post processing and eventually pass the result bean to an enclosing tag. The base implementation provided by this class is left empty.

    It is possible to define a base class; the tag handler class will then check whether the involved bean is an instance of this class and throw a JellyTagException if this is not the case.

    The typical attributes for conditional execution of tags (ifName and unlessName) are supported. Further attributes can be specified to initialize the bean to be created/accessed.

    The following attributes are supported by this tag:

    Attribute Description Optional
    class Defines the class of the bean to be created by this tag. This is the same as used for the original Jelly UseBean base tag. If this attribute is defined, arbitrary other attributes can be set defining properties of the new bean. Exactly one of these
    ref This attribute can be used for accessing a bean from the Jelly context (that way service beans can be shared between tags).
    beanName Here the name of a bean managed by the dependency injection framework can be specified. The bean will be looked up and obtained from the current BeanContext.
    beanClass The same as beanName, except that the bean is looked up in the current BeanContext using the class specified here.
    var Here the name of a variable in the Jelly context can be specified, which will be assigned the involved bean. It is then available for other parts of the running script. Yes

    This tag also implements the PropertySupport interface. This means that property tags can appear in its body. The properties defined by these tags will be set on the bean created by the tag. Together with the LocalizedTag tag handler class it is possible to use resources for setting properties.

    Version:
    $Id: UseBeanBaseTag.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static String ATTR_BEAN_CLASS
      Constant for the name of the beanClass attribute.
      protected static String ATTR_BEAN_NAME
      Constant for the name of the beanName attribute.
      protected static String ATTR_CLASS
      Constant for the name of the class attribute.
      protected static String ATTR_IF_NAME
      Constant for the name of the ifName attribute.
      protected static String ATTR_REF
      Constant for the name of the ref attribute.
      protected static String ATTR_UNLESS_NAME
      Constant for the name of the unlessName attribute.
      protected static String ATTR_VAR
      Constant for the name of the var attribute.
      • Fields inherited from class org.apache.commons.jelly.TagSupport

        body, context, hasTrimmed, parent, shouldTrim
    • Constructor Summary

      Constructors 
      Constructor Description
      UseBeanBaseTag()
      Creates a new instance of UseBeanBaseTag.
      UseBeanBaseTag​(Class<?> defaultClass)
      Creates an instance of UseBeanBaseTag and sets the default class for newly created beans.
      UseBeanBaseTag​(Class<?> defaultClass, Class<?> baseClass)
      Creates an instance of UseBeanBaseTag and sets the default class for newly created beans and the base class for new beans as well.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void addIgnoreProperties​(String... props)
      A convenience method for adding multiple properties that should be ignored.
      void doTag​(org.apache.commons.jelly.XMLOutput output)
      Executes this tag.
      protected Object fetchBean()
      Obtains the bean for this tag.
      protected Map<String,​Object> getAdditionalProperties()
      Returns additional properties that have been added by tags in the body.
      protected String getAttributeStr​(String attr)
      Helper method for returning an attribute as string.
      Class<?> getBaseClass()
      Returns the bean's base class.
      String getIfName()
      Returns the value of the ifName attribute.
      String getUnlessName()
      Returns the value of the unlessName attribute.
      protected boolean isOptional()
      This method can be overridden in a derived class to indicate that the bean creation operation is optional.
      protected boolean passResults​(Object bean)
      This method is called after the result bean is fully initialized.
      protected void processBean​(String var, Object bean)
      Processes the newly created bean.
      void setBaseClass​(Class<?> baseClass)
      Sets the bean's base class.
      void setProperty​(String name, Object value)
      Sets a property.
      protected void useExistingBean​(org.apache.commons.jelly.XMLOutput output)
      This method gets called if an existing bean should be used rather than creating a new one.
      • Methods inherited from class org.apache.commons.jelly.tags.core.UseBeanTag

        addIgnoreProperty, convertToClass, getBean, getDefaultClass, getIgnorePropertySet, isIgnoreUnknownProperties, loadClass, newInstance, setBean, setBeanProperties, setIgnoreUnknownProperties, validateBeanProperties
      • Methods inherited from class org.apache.commons.jelly.MapTagSupport

        createAttributes, getAttributes, setAttribute
      • Methods inherited from class org.apache.commons.jelly.DynaTagSupport

        getAttributeType
      • 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
      • Methods inherited from interface org.apache.commons.jelly.Tag

        getBody, getContext, getParent, invokeBody, setBody, setContext, setParent
    • Constructor Detail

      • UseBeanBaseTag

        public UseBeanBaseTag()
        Creates a new instance of UseBeanBaseTag.
      • UseBeanBaseTag

        public UseBeanBaseTag​(Class<?> defaultClass)
        Creates an instance of UseBeanBaseTag and sets the default class for newly created beans. This class will be used when the class attribute is missing.
        Parameters:
        defaultClass - the default class
      • UseBeanBaseTag

        public UseBeanBaseTag​(Class<?> defaultClass,
                              Class<?> baseClass)
        Creates an instance of UseBeanBaseTag and sets the default class for newly created beans and the base class for new beans as well.
        Parameters:
        defaultClass - the default class; this class will be used if the class attribute is not specified
        baseClass - the base class for the obtained beans; if defined, the tag will check if the bean is an instance of this class
    • Method Detail

      • getBaseClass

        public Class<?> getBaseClass()
        Returns the bean's base class.
        Returns:
        the base class of the bean
      • setBaseClass

        public void setBaseClass​(Class<?> baseClass)
        Sets the bean's base class. If this class is set, the tag will ensure whether the obtained bean is an instance of this class.
        Parameters:
        baseClass - the bean's base class
      • getIfName

        public String getIfName()
        Returns the value of the ifName attribute.
        Specified by:
        getIfName in interface ConditionalTag
        Returns:
        the ifName attribute
      • getUnlessName

        public String getUnlessName()
        Returns the value of the unlessName attribute.
        Specified by:
        getUnlessName in interface ConditionalTag
        Returns:
        the unlessName attribute
      • setProperty

        public void setProperty​(String name,
                                Object value)
        Sets a property. This method can be called by tags in the body. The properties added through this method will be set on the bean created by this tag.
        Specified by:
        setProperty in interface PropertySupport
        Parameters:
        name - the name of the property
        value - the value of the property
      • doTag

        public void doTag​(org.apache.commons.jelly.XMLOutput output)
                   throws org.apache.commons.jelly.JellyTagException
        Executes this tag. Tests if execution is allowed and whether a new bean should be created or an existing should be fetched from the context.
        Specified by:
        doTag in interface org.apache.commons.jelly.Tag
        Overrides:
        doTag in class org.apache.commons.jelly.tags.core.UseBeanTag
        Parameters:
        output - the output object
        Throws:
        org.apache.commons.jelly.JellyTagException - if an error occurs
      • processBean

        protected void processBean​(String var,
                                   Object bean)
                            throws org.apache.commons.jelly.JellyTagException
        Processes the newly created bean. This method is called when a new bean instance was created. This implementation invokes the passResults() method after correct bean processing.
        Overrides:
        processBean in class org.apache.commons.jelly.tags.core.UseBeanTag
        Parameters:
        var - the value of the var attribute
        bean - the newly created bean
        Throws:
        org.apache.commons.jelly.JellyTagException - if an error occurs
      • useExistingBean

        protected void useExistingBean​(org.apache.commons.jelly.XMLOutput output)
                                throws org.apache.commons.jelly.JellyTagException
        This method gets called if an existing bean should be used rather than creating a new one. This implementation tries to obtain the bean either from the jelly context or the current bean context.
        Parameters:
        output - the current output object
        Throws:
        org.apache.commons.jelly.JellyTagException - if the bean cannot be found
      • fetchBean

        protected Object fetchBean()
        Obtains the bean for this tag. This method is called when one of the reference attributes is set.
        Returns:
        the referenced bean (can be null, then an exception will be thrown in later processing
      • passResults

        protected boolean passResults​(Object bean)
                               throws org.apache.commons.jelly.JellyTagException
        This method is called after the result bean is fully initialized. Sub classes can perform arbitrary post processing. The return value indicates whether the bean could be passed to a target object. If here false is returned and no var attribute is specified, the tag will throw an exception (because the bean is obviously of no use). This base implementation is empty and only returns true.
        Parameters:
        bean - the bean to be passed
        Returns:
        a flag whether the bean could be passed to a target
        Throws:
        org.apache.commons.jelly.JellyTagException - if an error occurs
      • isOptional

        protected boolean isOptional()
        This method can be overridden in a derived class to indicate that the bean creation operation is optional. If no class and no ref attribute are provided and this method returns true, no error is issued, but passResults() is called with a null argument. The default implementation of this method returns always false.
        Returns:
        a flag whether the bean creation operation is optional
      • getAdditionalProperties

        protected Map<String,​Object> getAdditionalProperties()
        Returns additional properties that have been added by tags in the body. These properties will also be set on the current bean. The result may be null if no additional properties have been added.
        Returns:
        a map with additional properties
      • getAttributeStr

        protected String getAttributeStr​(String attr)
        Helper method for returning an attribute as string. If the attribute is present, its string representation is returned. Otherwise result is null.
        Parameters:
        attr - the name of the attribute
        Returns:
        the attribute value
      • addIgnoreProperties

        protected void addIgnoreProperties​(String... props)
        A convenience method for adding multiple properties that should be ignored. This implementation calls addIgnoreProperty() for each property name passed in.
        Parameters:
        props - the names of the properties to be ignored