Class JellyBuilder

  • All Implemented Interfaces:
    BeanBuilder, Builder

    public class JellyBuilder
    extends JellyBeanBuilder
    implements Builder

    An implementation of the Builder interface that uses Commons Jelly for processing build scripts and creating GUI components.

    This builder implementation will interpret Jelly build scripts that contain tags for creating bean definitions, form components, actions, and windows. To fulfill its purpose the builder object must be initialized with a couple of manager and factory interfaces, which will perform the real create operations for elements that comprise the generated GUI. Usually a client won't have to deal with these initialization stuff; instead this is handled by the dependency injection framework.

    Implementation note: This class is not thread-safe. The intended usage is that a new instance is created for each new builder operator.

    Version:
    $Id: JellyBuilder.java 211 2012-07-10 19:49:13Z oheger $
    Author:
    Oliver Heger
    • Field Detail

      • NSURI_COMPONENT_BUILDER

        public static final String NSURI_COMPONENT_BUILDER
        Constant for the default name space URI for the component builder tag library.
        See Also:
        Constant Field Values
      • NSURI_ACTION_BUILDER

        public static final String NSURI_ACTION_BUILDER
        Constant for the default name space URI for the action builder tag library.
        See Also:
        Constant Field Values
      • NSURI_WINDOW_BUILDER

        public static final String NSURI_WINDOW_BUILDER
        Constant for the default namespace URI for the window builder tag library.
        See Also:
        Constant Field Values
    • Constructor Detail

      • JellyBuilder

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

      • getName

        public String getName()
        Returns the name of this builder.
        Returns:
        the builder's name
      • setName

        public void setName​(String name)
        Sets the name of this builder. The name can be used in scripts to execute conditional code.
        Parameters:
        name - the builder's name
      • getActionBuilderNamespace

        public String getActionBuilderNamespace()
        Returns the name space used for the action builder tag library.
        Returns:
        the name space URI for the action builder tag library
      • setActionBuilderNamespace

        public void setActionBuilderNamespace​(String actionBuilderNamespace)
        Sets the name space used for the action builder tag library.
        Parameters:
        actionBuilderNamespace - the new name space URI
      • getComponentBuilderNamespace

        public String getComponentBuilderNamespace()
        Returns the name space used for the component builder tag library.
        Returns:
        the name space URI for the component builder tag library
      • setComponentBuilderNamespace

        public void setComponentBuilderNamespace​(String componentBuilderNamespace)
        Sets the name space used for the component builder tag library.
        Parameters:
        componentBuilderNamespace - the new name space
      • getWindowBuilderNamespace

        public String getWindowBuilderNamespace()
        Returns the name space used for the window builder tag library.
        Returns:
        the name space URI for the window builder tag library
      • setWindowBuilderNamespace

        public void setWindowBuilderNamespace​(String windowBuilderNamespace)
        Sets the name space used for the window builder tag library.
        Parameters:
        windowBuilderNamespace - the new name space
      • getActionManager

        public ActionManager getActionManager()
        Returns the action manager used by this builder.
        Returns:
        the action manager
      • setActionManager

        public void setActionManager​(ActionManager actionManager)
        Sets the action manager to be used by this builder. The action manager is responsible for the creation of actions, menus, toolbar items etc.
        Parameters:
        actionManager - the action manager
      • getComponentManager

        public ComponentManager getComponentManager()
        Returns the component manager used by this builder.
        Returns:
        the component manager
      • setComponentManager

        public void setComponentManager​(ComponentManager componentManager)
        Sets the component manager to be used by this builder. The component manager is responsible for creating all kinds of GUI components in forms.
        Parameters:
        componentManager - the component manager
      • getFieldHandlerFactory

        public FieldHandlerFactory getFieldHandlerFactory()
        Returns the field handler factory used by this builder.
        Returns:
        the field handler factory
      • setFieldHandlerFactory

        public void setFieldHandlerFactory​(FieldHandlerFactory fieldHandlerFactory)
        Sets the field handler factory to be used by this builder. The field handler factory will create handler objects that deal with form components.
        Parameters:
        fieldHandlerFactory - the field handler factory
      • getWindowManager

        public WindowManager getWindowManager()
        Returns the window manager used by this builder.
        Returns:
        the window manager
      • setWindowManager

        public void setWindowManager​(WindowManager windowManager)
        Sets the window manager to be used by this builder. The window manager is responsible for creating all kinds of windows.
        Parameters:
        windowManager - the window manager
      • getDefaultConverters

        public Map<Class<?>,​org.apache.commons.beanutils.Converter> getDefaultConverters()
        Returns a map with the default converters that have been registered so far.
        Returns:
        a map with the default converters; the map is unmodifiable
        See Also:
        addDefaultConverter(Converter, Class)
      • addDefaultConverter

        public void addDefaultConverter​(org.apache.commons.beanutils.Converter converter,
                                        Class<?> targetClass)
        Adds a new default converter to this builder. Default converters are stored internally. When a build operation is executed and a default ConversionHelper object has to be created, these default converters are automatically registered at the helper object. Normally client code does not have to call this method manually. This is done when this builder instance is created (per default the dependency injection framework is used to create new builder instances; when this happens the default converters are automatically initialized).
        Parameters:
        converter - the converter to be added (must not be null)
        targetClass - the target class of the conversion (must not be null)
        Throws:
        IllegalArgumentException - if a required parameter is missing
        See Also:
        ConversionHelper.registerConverter(Converter, Class)
      • addDefaultConverters

        public void addDefaultConverters​(Map<Class<?>,​? extends org.apache.commons.beanutils.Converter> converters)
        Adds all converters in the specified map as default converters to this object. Delegates to addDefaultConverter(Converter, Class) for each entry in the map.
        Parameters:
        converters - the map with the converters to be added (must not be null
        Throws:
        IllegalArgumentException - if the map is null or contains null entries
      • clearDefaultConverters

        public void clearDefaultConverters()
        Removes all default converters that have been added to this object so far.
      • getDefaultBaseClassConverters

        public Map<Class<?>,​org.apache.commons.beanutils.Converter> getDefaultBaseClassConverters()
        Returns a map with the default base class converters that have been registered so far.
        Returns:
        a map with the default base class converters; the map is unmodifiable
        See Also:
        addDefaultConverter(Converter, Class)
      • addDefaultBaseClassConverters

        public void addDefaultBaseClassConverters​(Map<Class<?>,​? extends org.apache.commons.beanutils.Converter> converters)
        Adds all converters in the specified map as default base class converters to this object. Delegates to addDefaultBaseClassConverter(Converter, Class) for each entry in the map.
        Parameters:
        converters - the map with the converters to be added (must not be null
        Throws:
        IllegalArgumentException - if the map is null or contains null entries
      • addDefaultBaseClassConverters

        public void addDefaultBaseClassConverters​(Map<String,​? extends org.apache.commons.beanutils.Converter> converters,
                                                  ClassLoaderProvider clp)
        Adds all converters in the specified map as default base class converters to this object using the specified ClassLoaderProvider to resolve class names. This method works like the method with the same name, but converter class are specified by name and resolved dynamically.
        Parameters:
        converters - the map with the converters to be added (must not be null
        clp - the ClassLoaderProvider (must not be null)
        Throws:
        IllegalArgumentException - if the map is null or contains null entries or the ClassLoaderProvider is null
        Since:
        1.2
      • clearDefaultBaseClassConverters

        public void clearDefaultBaseClassConverters()
        Removes all base class converters that have been added to this object before.
      • registerDefaultConverters

        public void registerDefaultConverters​(ConversionHelper conHlp)
        Registers default converters at the specified ConversionHelper instance. These are the converters added using the addDefaultConverter(Converter, Class) or addDefaultBaseClassConverter(Converter, Class) methods. If the BuilderData object passed to the build() methods does not contain an InvocationHelper instance, a new instance is automatically created, and the default converters are registered at the associated ConversionHelper instance. However, if a custom InvocationHelper is set, this registration is not done - the helper object is used as is. Using this method the default converters can be registered manually. Clients of the builder that need their own InvocationHelper can decide whether they call this method so that enhanced type conversion facilities are supported or not.
        Parameters:
        conHlp - the ConversionHelper to be initialized (must not be null)
        Throws:
        IllegalArgumentException - if the ConversionHelper is null
      • build

        public void build​(Locator script,
                          BuilderData data)
                   throws BuilderException
        A generic build method for executing a builder script. The specified Jelly script will be executed. Results are returned in properties of the parameter object.
        Specified by:
        build in interface Builder
        Parameters:
        script - specifies the script to be executed
        data - the parameter object
        Throws:
        BuilderException - if an error occurs
      • buildWindow

        public Window buildWindow​(Locator script,
                                  BuilderData data)
                           throws BuilderException
        A convenience method for building windows. Executes the specified Jelly script and returns the top level window created by this script.
        Specified by:
        buildWindow in interface Builder
        Parameters:
        script - specifies the script to be executed
        data - the parameter object
        Returns:
        the result window
        Throws:
        BuilderException - if an error occurs
      • buildContainer

        public void buildContainer​(Locator script,
                                   BuilderData data,
                                   Object container)
                            throws BuilderException
        A convenience method for building the content of a container object. Executes the specified Jelly script with the passed in container as root container.
        Specified by:
        buildContainer in interface Builder
        Parameters:
        script - specifies the script to be executed
        data - the parameter object
        container - the root container
        Throws:
        BuilderException - if an error occurs
      • release

        public void release​(BuilderData data)
        Frees all resources associated with the specified BuilderData object. The BuilderData object passed to this method must have been initialized by this builder. Especially the BeanContext and the BeanBuilderResult properties must have been set. Otherwise an exception is thrown.
        Specified by:
        release in interface Builder
        Parameters:
        data - the BuilderData object
        Throws:
        IllegalArgumentException - if the data object is null or is not fully initialized
      • performBuild

        protected void performBuild​(Locator script,
                                    BuilderData data,
                                    Object rootContainer)
                             throws BuilderException
        The main method for executing a builder script. This method is called by all public build() methods. It executes the specified script with a newly initialized context and collects all results afterwards.
        Parameters:
        script - specifies the build script
        data - the builder parameter object
        rootContainer - the root container object
        Throws:
        BuilderException - if an error occurs
      • setUpExtendedJellyContext

        protected org.apache.commons.jelly.JellyContext setUpExtendedJellyContext​(BuilderData data,
                                                                                  Object rootContainer)
        Creates and initializes the Jelly context to be used for executing the builder script. This method will perform all necessary initialization steps so that the context can be directly used hereafter. Extended in this context means that the context will be used for the more complex build operations (forms, actions, and windows) and not only for bean definitions.
        Parameters:
        data - the builder parameters
        rootContainer - the root container for the builder process
        Returns:
        the fully initialized context
      • createComponentBuilderData

        protected ComponentBuilderData createComponentBuilderData​(BuilderData data,
                                                                  Object rootContainer)
        Creates the component builder data object for the current builder process. This implementation first tries to obtain a ComponentBuilderData bean from the parent bean context. If such a bean cannot be found, a default bean is created.
        Parameters:
        data - the builder parameters
        rootContainer - the root container
        Returns:
        the component builder data object
      • initInvocationHelper

        protected InvocationHelper initInvocationHelper​(BuilderData data)
        Initializes the InvocationHelper to be used during the builder operation. This method is called before the builder script gets executed. If an InvocationHelper instance is provided in the specified BuilderData object, it is directly returned. Otherwise, a new instance is created with a specialized ConversionHelper whose parent is obtained from the parent bean store. That way all converters registered for the parent bean store are also available in the current builder script.
        Parameters:
        data - the builder parameters
        Returns:
        the InvocationHelper to use
      • initBuilderBeanContext

        protected MutableBeanStore initBuilderBeanContext​(BuilderData data,
                                                          org.apache.commons.jelly.JellyContext context,
                                                          InvocationHelper invHlp)
        Creates the root bean store for the current builder operation and initializes the BeanContext to be used. In this bean store the bean definitions defined by the builder script are stored (unless a different store is explicitly selected). A new BeanContext is created and initialized, so that it allows access to the following bean definitions (in this order):
        • the beans defined in the root store
        • the beans stored in this ComponentBuilderData instance
        • the beans defined in the parent context
        • the content of the Jelly context
        Parameters:
        data - the builder parameters
        context - the Jelly context
        invHlp - the current InvocationHelper
        Returns:
        the new root store for the builder operation
      • createActionBuilderData

        protected ActionBuilder createActionBuilderData​(BuilderData data)
        Creates the action builder data object for the current builder process. This implementation first tries to obtain a ActionBuilder bean from the parent bean context. If such a bean cannot be found, a new default instance is created.
        Parameters:
        data - the builder parameters
        Returns:
        the action builder data object
      • createWindowBuilderData

        protected WindowBuilderData createWindowBuilderData​(BuilderData data)
        Creates the window builder data object for the current builder process. This implementation first checks whether a WindowBuilderData bean can be obtained from the parent bean context. If such a bean cannot be found, a new default instance is created.
        Parameters:
        data - the builder parameters
        Returns:
        the window builder data object
      • registerExtendedTagLibraries

        protected void registerExtendedTagLibraries​(org.apache.commons.jelly.JellyContext context,
                                                    BuilderData data)
        Registers the builder tag libraries at the given context. This method is called by setUpExtendedJellyContext() before the builder script will be executed. "Extended" in this context means that all tag libraries for the more complex builders are registered.
        Parameters:
        context - the context
        data - the builder parameters
      • checkState

        protected void checkState()
        Checks the state of this builder. This method is called before a build operation starts. It checks whether all required properties have been initialized. If this is not the case, an exception is thrown.
        Throws:
        IllegalStateException - if initialization of this instance is incomplete
      • fetchResults

        protected void fetchResults​(org.apache.commons.jelly.JellyContext context,
                                    BuilderData data,
                                    BeanBuilderResult result,
                                    Locator script)
                             throws BuilderException
        Fetches all result variables from the context and stores them in the builder parameter object. This method is called after successful script execution. It also deals with invoking registered callback objects.
        Parameters:
        context - the context object
        data - the parameter object
        result - the result object from the bean builder
        script - the locator to the current build script
        Throws:
        BuilderException - if an error occurs
      • registerBeanCreationListeners

        protected void registerBeanCreationListeners​(BeanContext context,
                                                     BuilderData data)
        Registers the BeanCreationListener objects defined by the BuilderData object at the specified BeanContext. This method is called by initBuilderBeanContext(BuilderData, JellyContext, InvocationHelper) with the newly created BeanContext as parameter. If the BuilderData object contains bean creation listeners, these listeners have to be added to the context. (Note: this method is called in any case, even if the collection with creation listeners is null or empty.)
        Parameters:
        context - the BeanContext used by the builder
        data - the BuilderData object