Class ConverterTag

  • All Implemented Interfaces:
    ConditionalTag, PropertySupport, org.apache.commons.jelly.DynaTag, org.apache.commons.jelly.impl.BeanSource, org.apache.commons.jelly.Tag

    public class ConverterTag
    extends UseBeanBaseTag

    A specialized tag handler class for adding custom data type converters in a builder script.

    The dependency injection framework supports data type converters that are automatically invoked when methods on beans are invoked or properties are set to convert data to the target types required by the method signatures. There are multiple ways to extent the default converters provided by the framework. Using this tag it is possible to define custom type converters directly in a builder script. This is pretty convenient because it does not require any specific glue code when invoking the builder.

    The basic idea is that custom data type converters are defined as regular beans using variants of the <di:bean> tag. Then this tag is used to register these beans as converters at the current builder context. Because ConverterTag extends UseBeanBaseTag multiple ways for referencing beans are supported; it is even possible to create new bean instances by calling their standard constructor.

    The scope of the data type converters defined by this tag should determine the scripts in which to place the tag. If the converters are very basic and used in many builder scripts of the application, they should be already registered in the script defining the main window - i.e. the first builder script executed by the application. There is a kind of an inheritance mechanism: data type converters registered for a root BeanStore are also available in builder scripts defining children of this root store. Specialized converters that are only required for a single builder script can be defined locally in this script.

    Of course, all attributes supported by the base class are also available for ConverterTag. The following table lists the additional attributes introduced by this class:

    Attribute Description Optional
    converterTargetClass With this attribute the target class of the converter can be specified (either as a java.lang.Class object or as a string that will be converted to a class. Yes
    converterTargetClassName Using this attribute the name of the target class can be specified. While the targetClass attribute requires that the class specified can be loaded using the default class loader, this attribute - together with the targetClassLoader attribute - supports loading the class from an alternative class loader. Yes
    converterTargetClassLoader This attribute is only evaluated if the targetClassName attribute is set. In this case it references the class loader to be used for resolving the class name. A class loader with the given name is queried from the current ClassLoaderProvider. Yes
    isBaseClassConverter Determines whether the converter should be registered as a normal or a base class converter. If this attribute has an arbitrary value, it is registered as base class converter. Yes

    The target class must have been specified in one of the supported ways, otherwise an exception is thrown. The following example shows a typical usage scenario for this tag:

     <!-- Definition of the bean for the converter.-->
     <di:bean name="converterBean" beanClass="com.mypackage.MyConverter">
       ...
     </di:bean>
    
     <!-- Register the bean as converter.-->
     <f:converter beanName="converterBean"
       converterTargetClass="com.mypackage.MyDataClass"/>
     
    After this declaration bean definitions can be placed in the Jelly script with properties or method parameters of the type com.mypackage.MyDataClass. The newly registered converter will be automatically called to perform the data conversion to this type.

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

      • ATTR_CONVERTER_TARGET_CLASS

        protected static final String ATTR_CONVERTER_TARGET_CLASS
        Constant for the name of the converter target class attribute.
        See Also:
        Constant Field Values
      • ATTR_CONVERTER_TARGET_CLASS_NAME

        protected static final String ATTR_CONVERTER_TARGET_CLASS_NAME
        Constant for the name of the converter target class name attribute.
        See Also:
        Constant Field Values
      • ATTR_CONVERTER_TARGET_CLASS_LOADER

        protected static final String ATTR_CONVERTER_TARGET_CLASS_LOADER
        Constant for the name of the converter target class loader attribute.
        See Also:
        Constant Field Values
      • ATTR_BASE_CLASS_CONVERTER

        protected static final String ATTR_BASE_CLASS_CONVERTER
        Constant for the name of the base class converter attribute.
        See Also:
        Constant Field Values
    • Constructor Detail

      • ConverterTag

        public ConverterTag()
        Creates a new instance of ConverterTag.
    • Method Detail

      • passResults

        protected boolean passResults​(Object bean)
                               throws org.apache.commons.jelly.JellyTagException
        Processes the bean created by this tag. This implementation registers the specified bean as a converter at the central ConversionHelper object. A target class for the converter must have been provided, otherwise an exception is thrown.
        Overrides:
        passResults in class UseBeanBaseTag
        Parameters:
        bean - the newly created bean
        Returns:
        a flag whether the bean could be processed
        Throws:
        org.apache.commons.jelly.JellyTagException - if an error occurs
      • createTargetClassDescription

        protected ClassDescData createTargetClassDescription()
        Creates a ClassDescData object for the target class of the converter. This method evaluates the several attributes that can be used to specify the converter's target class. From these attributes the ClassDescData object is populated.
        Returns:
        the initialized ClassDescData object
      • fetchTargetClass

        protected Class<?> fetchTargetClass​(ClassDescData cdd)
                                     throws org.apache.commons.jelly.JellyTagException
        Obtains the target class of the converter from the specified ClassDescData object. This method is called by passResults(Object).
        Parameters:
        cdd - the description object populated from the attributes of this tag
        Returns:
        the target class of the converter
        Throws:
        org.apache.commons.jelly.JellyTagException - if the class cannot be resolved