Class BeanTag

  • All Implemented Interfaces:
    org.apache.commons.jelly.Tag

    public class BeanTag
    extends AbstractBeanTag

    The main tag of the tag library for the dependency injection framework: with this tag bean definitions can be created.

    There are several ways of defining a bean and determining where it is stored:

    • The most simple form is to specify a constant value for the bean. This value will then be directly returned by the constructed BeanProvider.
       <bean name="myBean" value="42"
         valueClassName="java.lang.Integer"/>
       
    • With the store attribute the name of the BeanStore, in which the constructed BeanProvider is stored, can be specified:
       <bean name="myBean" value="42"
         valueClassName="java.lang.Short" store="numericBeans"/>
       
    • If the bean tag is placed inside a BeanStoreTag, the bean definition will be stored in this bean store:
       <store name="specialBeans">
         <bean name="myBean" value="SpecialBean1"/>
       </store>
       
    • If only the class of the managed bean is provided, the default constructor will be called for creating an instance:
       <bean name="myBean"
         beanClassName="com.mycompany.mypckg.MyBean"/>
       
    • The singleton attribute has impact on the way the bean is created. If set to true (which is the default), only a single bean instance will be created on first access. Further access to this bean definition will always return the same bean. A value of false in contrast will create a new bean instance on each access:
       <bean name="myBean" beanClassName="com.mycompany.mypckg.MyBean"
         singleton="false"/>
       
    • If a bean is a singleton, the shutdownMethod attribute can be specified. Here the name of a method can be provided, which has to be called by the framework when the bean is no longer needed (i.e. when the BeanStore the BeanProvider is contained is closed):
       <bean name="myShutdownBean"
         beanClassName="com.mycompany.mypckg.MyBean"
         shutdownMethod="close"/>
       
      The method defined by the shutdownMethod attribute must have no parameters. If a more complex shutdown operation is desired or if multiple methods need to be called, consider using the ShutdownHandlerTag in the body of the bean tag. Note again that shutdown methods are only supported for singleton beans. If each access to the bean creates a new instance, the caller is responsible for releasing the bean instances correspondingly.
    • If a different constructor than the default one is to be used, a nested ConstructorTag tag can be used. Here the parameters to be passed to the constructor can be defined:
       <bean name="myBean"
         beanClass="net.sf.jguiraffe.di.ReflectionTestClass">
         <constructor>
           <param refName="anotherBean"/>
           <param value="42" valueClass="java.lang.Integer"
             parameterClass="java.lang.Integer"/>
         </constructor>
       </bean>
       
    • If the bean cannot be created directly, but a factory has to be used, a nested FactoryTag is appropriate. This can look as follows:
       <bean name="myBean"
         beanClass="net.sf.jguiraffe.di.ReflectionTestClass">
         <factory>
           <methodInvocation method="newInstance"
             targetClass="net.sf.jguiraffe.di.ReflectionTestClass">
             <param refName="anotherBean"/>
             <param value="42" valueClass="java.lang.Integer"
               parameterClass="java.lang.Integer"/>
           </methodInvocation>
         </factory>
       </bean>
       
    • It is also possible to use a <bean> tag everywhere a dependency is expected. This allows defining beans in-line as in the following example:
       <bean name="myBean"
         beanClass="net.sf.jguiraffe.di.ReflectionTestClass">
         <constructor>
           <param>
             <bean beanClass="net.sf.jguiraffe.di.TestBean"/>
           </param>
           <param value="42" valueClass="java.lang.Integer"
             parameterClass="java.lang.Integer"/>
         </constructor>
       </bean>
       
      Here the value of the first <param> tag is the bean defined by the nested <bean> tag. This is a bit similar to anonymous inner classes in Java. The result is effectively the same as if the bean was defined elsewhere with a specific name and the <param> tag would reference this bean.
    • No matter of how the bean is created, in the tag's body an arbitrary number of invocation tags can be placed. These are collected and added to a ChainedInvocation object, so that they form an initialization script. This script will be executed after the bean instance has been created:
       <bean name="myBean" beanClass="com.mypackage.MyBeanClass">
         <constructor>
           <param refName="anotherBean"/>
         </constructor>
         <methodInvocation method="initLocale">
           <param refClass="java.util.Locale"/>
         </methodInvocation>
         <setProperty property="count" value="10"/>
       </bean>
       

    The following table lists all attributes supported by this tag:

    Attribute Description Optional
    name Defines a name for the created bean definition. Using this name the bean can be queried from an bean context. no
    value If the parameter is to be set to a constant value, this attribute can be used. It allows to directly specify the value. yes
    valueClass If a constant value is to be used for the parameter value, it may be necessary to perform some type conversion. With this attribute the type of the parameter can be specified. The value will then be converted to this type. yes
    valueClassName Like valueClass, but the name of the property's data type class is specified. yes
    valueClassLoader If the data type class of the value is specified by its name only, with this attribute the class loader can be determined for resolving the class. yes
    beanClass With this attribute the class of the managed bean is determined. Explicitly specifying the bean class is required in some cases. For instance if no further creation parameters are provided, the bean will be created by invoking the default constructor of this class. yes
    beanClassName Like the beanClass attribute, but the bean class is specified by its name. yes
    beanClassLoader If the bean class is specified by name, with this attribute the symbolic name of a registered class loader can be provided for resolving the class. yes
    singleton This attribute determines whether the defined bean is a singleton. If set to true (which is the default value if the attribute is missing), only a single instance will be created on first access; later access to this bean will always return the same instance. A value of false will cause a new bean instance to be created on each access. yes
    store Here the name of the BeanStore, in which the created bean definition is to be put is defined. If the attribute is missing and this tag is placed in the body of a BeanStoreTag, the store defined by this tag will be used. If no bean store is defined at all, the root bean store of the current builder operation is used. yes
    resultVar This attribute provides an alternative way of defining a bean: as a result variable of an initializer script. When the initializer script is executed local variables can be created. The resultVar attribute instructs the tag to use one of these variables as the bean to be returned. With this mechanism, it is possible for instance to invoke a factory bean and return the object created by it. Note that the resultVar attribute takes precedence over other mechanisms to define the resulting bean. yes

    Version:
    $Id: BeanTag.java 207 2012-02-09 07:30:13Z oheger $
    Author:
    Oliver Heger
    • Constructor Detail

      • BeanTag

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

      • getName

        public String getName()
        Returns the name of the managed bean definition.
        Overrides:
        getName in class AbstractBeanTag
        Returns:
        the name of the bean definition
      • setName

        public void setName​(String name)
        Set method of the name attribute.
        Parameters:
        name - the attribute's name
      • getBeanClassDesc

        public ClassDescription getBeanClassDesc()
        Returns the class description for the managed bean.
        Returns:
        the class of the managed bean
      • setBeanClassDesc

        public void setBeanClassDesc​(ClassDescription beanClass)
        Sets the class description for the managed bean. Usually, this method will be called by the main processing method when the tag's attributes are evaluated. If the bean class is not defined by the tag's attributes, it can be indirectly defined by the BeanProvider used as creator.
        Parameters:
        beanClass - the class description for the managed bean
      • getBeanCreator

        public BeanProvider getBeanCreator()
        Returns the BeanProvider that will be used for creating the managed bean.
        Returns:
        the BeanProvider for creating the bean
      • setBeanCreator

        public void setBeanCreator​(BeanProvider beanCreator)
                            throws org.apache.commons.jelly.JellyTagException
        Sets the BeanProvider that will be used for creating the managed bean.
        Parameters:
        beanCreator - the creation bean provider
        Throws:
        org.apache.commons.jelly.JellyTagException - if a creator has already been set (only a single bean creator is allowed)
      • getValueData

        public ValueData getValueData()
        Returns the data object with information about the value.
        Returns:
        the value data object
      • isSingleton

        public boolean isSingleton()
        Returns a flag whether the created bean definition is for a singleton bean.
        Returns:
        the singleton flag
      • setSingleton

        public void setSingleton​(boolean singleton)
        Set method of the singleton attribute.
        Parameters:
        singleton - the attribute's value
      • setBeanClass

        public void setBeanClass​(Class<?> c)
        Set method of the beanClass attribute.
        Parameters:
        c - the attribute's value
      • setBeanClassName

        public void setBeanClassName​(String s)
        Set method of the beanClassName attribute.
        Parameters:
        s - the attribute's value
      • setBeanClassLoader

        public void setBeanClassLoader​(String s)
        Set method of the beanClassLoader attribute.
        Parameters:
        s - the attribute's value
      • setValue

        public void setValue​(Object value)
        Set method for the value attribute.
        Parameters:
        value - the attribute's value
      • setValueClass

        public void setValueClass​(Class<?> cls)
        Set method for the valueClass attribute.
        Parameters:
        cls - the attribute's value
      • setValueClassName

        public void setValueClassName​(String clsName)
        Set method for the valueClassName attribute.
        Parameters:
        clsName - the attribute's value
      • setValueClassLoader

        public void setValueClassLoader​(String loader)
        Set method for the valueClassLoader attribute.
        Parameters:
        loader - the attribute's value
      • setShutdownMethod

        public void setShutdownMethod​(String s)
        Set method for the shutdownMethod attribute.
        Parameters:
        s - the attribute's value
      • getResultVar

        public String getResultVar()
        Returns the name of the result variable in the initializer script.
        Returns:
        the name of the result variable
        Since:
        1.1
      • setResultVar

        public void setResultVar​(String resultVar)
        Set method of the resultVar attribute.
        Parameters:
        resultVar - the attribute's value
        Since:
        1.1
      • getShutdownHandler

        public Invokable getShutdownHandler()
        Returns the shutdown handler.
        Returns:
        the shutdown handler
      • setShutdownHandler

        public void setShutdownHandler​(Invokable inv)
                                throws org.apache.commons.jelly.JellyTagException
        Sets a shutdown handler. This handler will be set at the BeanProvider created by this tag if supported. This tag handler class allows multiple ways of defining a shutdown handler, but for a concrete tag instance only a single way can be used. Thus this method throws an exception when called more than once. This method is expected to be called by nested tags.
        Parameters:
        inv - the Invokable serving as shutdown handler
        Throws:
        org.apache.commons.jelly.JellyTagException - if already a shutdown handler is defined and the parameter is not null
      • processBeforeBody

        protected void processBeforeBody()
                                  throws org.apache.commons.jelly.JellyTagException
        Performs pre-processing before the body of this tag is evaluated. This method performs some initialization related to the value of this tag (if a constant value is set) and prepares storing invocations for an initializer script and a shutdown method.
        Overrides:
        processBeforeBody in class AbstractBeanTag
        Throws:
        org.apache.commons.jelly.JellyTagException - if the tag is incorrectly used
      • process

        protected void process()
                        throws org.apache.commons.jelly.JellyTagException
        Processes this tag after its body has been evaluated. This implementation performs some additional checks and cleanup at the end of this tag's execution.
        Overrides:
        process in class AbstractBeanTag
        Throws:
        org.apache.commons.jelly.JellyTagException - if the tag is incorrectly used
      • getInitializerScript

        protected ChainedInvocation getInitializerScript()
        Returns the ChainedInvocation for storing the initializer script.
        Returns:
        the initializer script
      • getBeanClassData

        protected ClassDescData getBeanClassData()
        Returns the data object with the definition of the bean class.
        Returns:
        the bean class data object
      • consumeShutdownHandler

        protected Invokable consumeShutdownHandler()
        Returns the Invokable serving as a shutdown handler and resets the field. Because not all variants of beans that can be created using this tag support shutdown handlers, the handler is reset when it could be processed. So the tag handler class can check whether a shutdown handler was provided in a scenario where this is not allowed and throw an exception. Note that only the first invocation of this method can return a value; subsequent invocations return null.
        Returns:
        the shutdown handler if one is defined; null otherwise
      • createShutdownHandlerForMethod

        protected Invokable createShutdownHandlerForMethod​(String methodName)
        Creates an Invokable for a shutdown handler for a shutdown method. This method is called by processBeforeBody() when the shutdownMethod attribute is set. It returns an Invokable, which calls exactly this method.
        Parameters:
        methodName - the name of the shutdown method
        Returns:
        the Invokable for the shutdown handler
      • createBeanProvider

        protected BeanProvider createBeanProvider()
                                           throws org.apache.commons.jelly.JellyTagException
        Creates the bean provider defined by this tag. This method is invoked by process() after validation of the attributes.
        Specified by:
        createBeanProvider in class AbstractBeanTag
        Returns:
        the bean provider defined by this tag
        Throws:
        org.apache.commons.jelly.JellyTagException - in case of an error