net.sf.jguiraffe.gui.builder.impl

Class JellyBuilder

java.lang.Object

net.sf.jguiraffe.gui.builder.impl.JellyBeanBuilder

net.sf.jguiraffe.gui.builder.impl.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 Summary

Fields

Modifier and Type	Field and Description
static String	NSURI_ACTION_BUILDER Constant for the default name space URI for the action builder tag library.
static String	NSURI_COMPONENT_BUILDER Constant for the default name space URI for the component builder tag library.
static String	NSURI_WINDOW_BUILDER Constant for the default namespace URI for the window builder tag library.

Constructor Summary

Constructors

Constructor and Description
JellyBuilder() Creates a new instance of JellyBuilder.

Method Summary

Modifier and Type	Method and Description
void	addDefaultBaseClassConverter(org.apache.commons.beanutils.Converter converter, Class<?> targetClass) Adds a new default base class converter to this builder.
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.
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.
void	addDefaultConverter(org.apache.commons.beanutils.Converter converter, Class<?> targetClass) Adds a new default converter to this builder.
void	addDefaultConverters(Map<Class<?>,? extends org.apache.commons.beanutils.Converter> converters) Adds all converters in the specified map as default converters to this object.
void	build(Locator script, BuilderData data) A generic build method for executing a builder script.
void	buildContainer(Locator script, BuilderData data, Object container) A convenience method for building the content of a container object.
Window	buildWindow(Locator script, BuilderData data) A convenience method for building windows.
protected void	checkState() Checks the state of this builder.
void	clearDefaultBaseClassConverters() Removes all base class converters that have been added to this object before.
void	clearDefaultConverters() Removes all default converters that have been added to this object so far.
protected ActionBuilder	createActionBuilderData(BuilderData data) Creates the action builder data object for the current builder process.
protected ComponentBuilderData	createComponentBuilderData(BuilderData data, Object rootContainer) Creates the component builder data object for the current builder process.
protected WindowBuilderData	createWindowBuilderData(BuilderData data) Creates the window builder data object for the current builder process.
protected void	fetchResults(org.apache.commons.jelly.JellyContext context, BuilderData data, BeanBuilderResult result, Locator script) Fetches all result variables from the context and stores them in the builder parameter object.
String	getActionBuilderNamespace() Returns the name space used for the action builder tag library.
ActionManager	getActionManager() Returns the action manager used by this builder.
String	getComponentBuilderNamespace() Returns the name space used for the component builder tag library.
ComponentManager	getComponentManager() Returns the component manager used by this builder.
Map<Class<?>,org.apache.commons.beanutils.Converter>	getDefaultBaseClassConverters() Returns a map with the default base class converters that have been registered so far.
Map<Class<?>,org.apache.commons.beanutils.Converter>	getDefaultConverters() Returns a map with the default converters that have been registered so far.
FieldHandlerFactory	getFieldHandlerFactory() Returns the field handler factory used by this builder.
String	getName() Returns the name of this builder.
String	getWindowBuilderNamespace() Returns the name space used for the window builder tag library.
WindowManager	getWindowManager() Returns the window manager used by this builder.
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.
protected InvocationHelper	initInvocationHelper(BuilderData data) Initializes the InvocationHelper to be used during the builder operation.
protected void	performBuild(Locator script, BuilderData data, Object rootContainer) The main method for executing a builder script.
protected void	registerBeanCreationListeners(BeanContext context, BuilderData data) Registers the BeanCreationListener objects defined by the BuilderData object at the specified BeanContext.
void	registerDefaultConverters(ConversionHelper conHlp) Registers default converters at the specified ConversionHelper instance.
protected void	registerExtendedTagLibraries(org.apache.commons.jelly.JellyContext context, BuilderData data) Registers the builder tag libraries at the given context.
void	release(BuilderData data) Frees all resources associated with the specified BuilderData object.
void	setActionBuilderNamespace(String actionBuilderNamespace) Sets the name space used for the action builder tag library.
void	setActionManager(ActionManager actionManager) Sets the action manager to be used by this builder.
void	setComponentBuilderNamespace(String componentBuilderNamespace) Sets the name space used for the component builder tag library.
void	setComponentManager(ComponentManager componentManager) Sets the component manager to be used by this builder.
void	setFieldHandlerFactory(FieldHandlerFactory fieldHandlerFactory) Sets the field handler factory to be used by this builder.
void	setName(String name) Sets the name of this builder.
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.
void	setWindowBuilderNamespace(String windowBuilderNamespace) Sets the name space used for the window builder tag library.
void	setWindowManager(WindowManager windowManager) Sets the window manager to be used by this builder.

Methods inherited from class net.sf.jguiraffe.gui.builder.impl.JellyBeanBuilder

build, build, createBuilderData, createJellyContext, createReleaseDependencyProvider, executeScript, fetchClassLoaderProvider, getDiBuilderNameSpaceURI, prepareInputSource, registerTagLibraries, release, setDiBuilderNameSpaceURI, setUpJellyContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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)

addDefaultBaseClassConverter

public void addDefaultBaseClassConverter(org.apache.commons.beanutils.Converter converter,
                                         Class<?> targetClass)

Adds a new default base class converter to this builder. This method works exactly like addDefaultConverter(Converter, Class), but the Converter passed to this method is registered as a base class converter at the ConversionHelper object created for a new builder operation.

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.registerBaseClassConverter(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