net.sf.jguiraffe.gui.builder
Interface Builder

All Known Implementing Classes:

JellyBuilder

public interface Builder

The main builder interface.

A builder is an object that can produce artifacts of the GUI from builder scripts. So the GUI is no longer constructed in the application's code, but can be defined in external resources, which are easier to maintain. This also allows for dynamic GUIs, e.g. when different builder scripts are processed based on some condition or even when builder scripts are generated at runtime.

The builder interface itself is not too complex. There is one very generic build() method that can be used to build arbitrary GUI elements. Then there are a few convenience methods that are suitable for specific elements like windows.

Version:

$Id: Builder.java 152 2009-01-23 21:20:46Z oheger $

Author:

Oliver Heger

Method Summary

void	build(Locator script, BuilderData data) A generic builder method.
void	buildContainer(Locator script, BuilderData data, java.lang.Object container) A convenience method for constructing the GUI of the given passed in container.
Window	buildWindow(Locator script, BuilderData data) A convenience method for building windows like top-level frames or dialogs.
void	release(BuilderData data) Releases the specified BuilderData object.

Method Detail

build

void build(Locator script,
           BuilderData data)
           throws BuilderException

A generic builder method. This method initializes the builder with the passed in parameter object and then executes the given builder script. Results of the builder operation are stored in the parameter object, from which they can be obtained using the BuilderData#getProperty(String) method with appropriate keys.

Parameters:

script - the script to be executed

data - the parameter object

Throws:

BuilderException - if an error occurs

buildWindow

Window buildWindow(Locator script,
                   BuilderData data)
                   throws BuilderException

A convenience method for building windows like top-level frames or dialogs. This method behaves similar to the generic build() method, but directly returns the resulting window object.

Parameters:

script - the script to be executed

data - the parameter object

Returns:

the result window of the builder operation

Throws:

BuilderException - if an error occurs

buildContainer

void buildContainer(Locator script,
                    BuilderData data,
                    java.lang.Object container)
                    throws BuilderException

A convenience method for constructing the GUI of the given passed in container. This method is useful if an application already has a reference to an (empty) window or panel, which now should be filled. It sets the container as the builder's root container and then invokes the specified script.

Parameters:

script - the script to be executed

data - the parameter object

container - the container to be filled with components

Throws:

BuilderException - if an error occurs

release

void release(BuilderData data)

Releases the specified BuilderData object. This will free all resources associated with this data object. Especially the BeanContext created by the Builder will be closed, and on all BeanProvider objects found in the BeanStores that are part of the BeanBuilderResult the shutdown() method is invoked. Clients of the builder should call this method when the results of a builder operation are no more needed, e.g. when closing a window created by a builder.

Parameters:

data - the BuilderData object used for a builder operation (must not be null)

Throws:

java.lang.IllegalArgumentException - if the passed in object is null or invalid