net.sf.jguiraffe.gui.builder.enablers

Class EnablerBuilder

java.lang.Object

net.sf.jguiraffe.gui.builder.enablers.EnablerBuilder

public class EnablerBuilder
extends Object

A helper class for the convenient creation of standard ElementEnabler objects.

This class supports the creation of ElementEnabler objects based on textual specifications. It is intended to be used where a compact notation of enabler objects is required. One example are bean declarations for the dependency injection framework: Action tasks that issue commands can be associated with an ElementEnabler to disable certain elements while the action task is running. The XML-based declaration of complex enabler can be pretty inconvenient - especially if a ChainElementEnabler with multiple child elements is used. Here a shorter form for declaring enablers is helpful.

The basic usage of EnablerBuilder is to call the addSpecification(String) method an arbitrary number of times. Each invocation adds a string with the specification for a concrete ElementEnabler. When all specifications have been added the build() method is called which creates the resulting ElementEnabler. The result of this method depends on the number of specifications that have been added:

• If there is no specification, a NullEnabler is returned.
• If there is exactly one specification, an ElementEnabler corresponding to the specification is returned.
• In all other cases result is a ChainElementEnabler with corresponding child ElementEnabler objects.

A valid specification for an ElementEnabler has the following form: It starts with a prefix (see below), followed by a colon. After the colon a parameter to be passed to the ElementEnabler's constructor is expected. The support prefix values are shown in the following table:

Prefix	Element enabler class
action	ActionEnabler
actiongroup	ActionGroupEnabler
comp	ComponentEnabler

The prefix is not case sensitive. Whitespace are ignored. Multiple specifications can be concatenated to a single one using a comma (","). So the following are valid examples for ElementEnabler specifications:

action:testAction

defines an ActionEnabler for an action named testAction

ActionGroup : testGroup

defines an ActionGroupEnabler for an action group named testGroup

COMP : myButton

defines an ComponentEnabler for the myButton component

action:action1, action:action2,comp:button1, comp:button2

defines multiple enablers, two action enablers and two component enablers

This class only supports the standard ElementEnabler implementations. There is no extension mechanism. This is because this class exists only for convenience. If access to other ElementEnabler implementations is needed, the objects have to be created directly.

Implementation note: This class is not thread-safe.

Version:

$Id: EnablerBuilder.java 205 2012-01-29 18:29:57Z oheger $

Author:

Oliver Heger

Constructor Summary

Constructors

Constructor and Description
EnablerBuilder()

Method Summary

Modifier and Type	Method and Description
EnablerBuilder	addSpecification(String spec) Adds the given specification to this builder.
ElementEnabler	build() Creates an ElementEnabler based on the specifications that have been added to this builder.
protected ElementEnabler	createEnabler(String prefix, String name) Creates an ElementEnabler for the specified prefix.
protected ElementEnabler	processSpecification(String spec) Processes the specified specification and creates a corresponding ElementEnabler.
void	reset() Resets this builder.

Methods inherited from class java.lang.Object

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

Constructor Detail

EnablerBuilder

public EnablerBuilder()

Method Detail

addSpecification

public EnablerBuilder addSpecification(String spec)

Adds the given specification to this builder. The specification must conform to the format defined in the class comment. It must not be null or empty.

Parameters:

spec - the specification to add

Returns:

a reference to this builder for method chaining

Throws:

IllegalArgumentException - if the specification is undefined

build

public ElementEnabler build()

Creates an ElementEnabler based on the specifications that have been added to this builder. This method also resets the state of this builder; all specifications are removed, so that this instance can be used for defining another ElementEnabler.

Returns:

an ElementEnabler based on the so far added specifications

Throws:

IllegalArgumentException - if an invalid specification is encountered

reset

public void reset()

Resets this builder. All specifications that have been added so far are removed. Note: This method is also invoked by build(), so it is not necessary to reset the builder after an object was created.

processSpecification

protected ElementEnabler processSpecification(String spec)

Processes the specified specification and creates a corresponding ElementEnabler. This method is called for each specification that was added to this builder.

Parameters:

spec - the specification for a single ElementEnabler (already trimmed)

Returns:

the corresponding ElementEnabler

Throws:

IllegalArgumentException - if the specification is invalid

createEnabler

protected ElementEnabler createEnabler(String prefix,
                                       String name)

Creates an ElementEnabler for the specified prefix. This method is called by processSpecification(String) after the specification was passed. It creates the actual enabler.

Parameters:

prefix - the prefix indicating the enabler type

name - the name of the element to be enabled

Returns:

the corresponding ElementEnabler

Throws:

IllegalArgumentException - if no enabler can be created for this prefix