com.github.wuic.context

Class ContextBuilder

java.lang.Object

java.util.Observable

com.github.wuic.context.ContextBuilder

Direct Known Subclasses:

WuicFacadeBuilder.ContextBuilderFacade

public class ContextBuilder
extends Observable

This builder can be configured to build contexts in an expected state by the user. It is designed to be used in a multi-threaded environment.

The builder tracks all settings by associated to them a tag. With that tag, the user is able to delete all settings defined at a moment. Example:

     final ContextBuilder contextBuilder = new ContextBuilder();

     try {
         // Create a context with some settings tagged as "custom"
         final Context ctx = contextBuilder.tag("custom")
                      .contextNutDaoBuilder("FtpNutDaoBuilder", "FtpNutDaoBuilder")
                      .property("c.g.wuic.dao.basePath", "/statics)"
                      .toContext()
                      .heap("heap", "FtpNutDaoBuilder", "darth.js", "vader.js")
                      .contextNutDaoBuilder("engineId", "TextAggregatorEngineBuilder")
                      .toContext()
                      .contextNutFilterBuilder("filterId", "RegexRemoveNutFilterBuilder")
                      .property(ApplicationConfig.REGEX_EXPRESSION, "(.*)?reload.*")
                      .toContext()
                      .template("tpl", new String[]{"engineId"}, null, false)
                      .workflow("starwarsWorkflow", true, "heap", "tpl")
                      .releaseTag()
                      .build();
         ctx.isUpToDate(); // returns true

         // Clear settings
         contextBuilder.clearTag("custom");
         ctx.isUpToDate(); // returns false
     } finally {
         contextBuilder.releaseTag();
     }
 

If any operation is performed without any tag, then an exception will be thrown. Moreover, when the tag(Object) method is called, the current threads holds a lock on the object. It will be released when the releaseTag() will be called. Consequently, it is really important to always call this last method in a finally block.

Since:

0.4.0

Version:

1.3

Author:

Guillaume DROUET

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	ContextBuilder.ContextEngineBuilder Inner class to configure a engine builder.
class	ContextBuilder.ContextGenericBuilder Inner class to configure a generic component.
class	ContextBuilder.ContextNutDaoBuilder Inner class to configure a DAO builder.
class	ContextBuilder.ContextNutFilterBuilder Inner class to configure a filter builder.

Constructor Summary

Constructors

Constructor and Description
ContextBuilder(ContextBuilder b, URL properties, ObjectBuilderInspector... inspectors) Creates a new instance with the builder factories of a context and additional inspectors.
ContextBuilder(ObjectBuilderFactory<Engine> engineBuilderFactory, ObjectBuilderFactory<NutDao> nutDaoBuilderFactory, ObjectBuilderFactory<NutFilter> nutFilterBuilderFactory, ObjectBuilderInspector... inspectors) Creates a new instance with specific builder factories.
ContextBuilder(ObjectBuilderInspector... inspectors) Creates a new instance.

Method Summary

Methods

Modifier and Type	Method and Description
Context	build() Builds the context.
ContextBuilder	clearTag(Object tag) Clears all configurations associated to the given tag.
ContextBuilder.ContextNutDaoBuilder	cloneContextNutDaoBuilder(String id, String userId) Returns a new context DAO builder associated to a particular ID and based on an existing context DAO builder.
ContextBuilder	configureDefault() Configures for each type provided by the engine builder factory and nut dao builder factory a default instance identified with an id starting by BUILDER_ID_PREFIX and followed by the type name itself.
ContextBuilder.ContextEngineBuilder	contextEngineBuilder(Class<?> type) Returns a new context default engine builder.
ContextBuilder.ContextEngineBuilder	contextEngineBuilder(String id, Class<?> type) Returns a new default context engine builder associated to a particular ID.
ContextBuilder.ContextEngineBuilder	contextEngineBuilder(String id, String type) Returns a new context engine builder.
ContextBuilder.ContextNutDaoBuilder	contextNutDaoBuilder(Class<?> type) Returns a new default context DAO builder.
ContextBuilder.ContextNutDaoBuilder	contextNutDaoBuilder(String id, Class<?> type) Returns a new default context DAO builder associated to a particular ID.
ContextBuilder.ContextNutDaoBuilder	contextNutDaoBuilder(String userId, String type) Returns a new context DAO builder.
ContextBuilder.ContextNutFilterBuilder	contextNutFilterBuilder(String id, Class<? extends NutFilter> type) Returns a new context filter builder.
ContextBuilder.ContextNutFilterBuilder	contextNutFilterBuilder(String id, String type) Returns a new context filter builder.
ContextBuilder	disposableHeap(String id, String ndbId, String[] path, HeapListener... listeners) Creates a new disposable heap as specified by heap(boolean, String, String, String[], String[], HeapListener...)
ContextBuilder	engineBuilder(String id, ObjectBuilder<Engine> engine) Add a new Engine builder identified by the specified ID.
static String	getDefaultBuilderId() Gets the default builder ID.
static String	getDefaultBuilderId(Class<?> component) Gets the default builder name for the given component class.
static String	getDefaultBuilderId(String builderName) Gets the default builder ID for the given builder name.
List<NutFilter>	getFilters() Gets the filters currently configured in this builder.
ContextBuilder	heap(boolean disposable, String id, String nutDaoId, String[] heapIds, String[] path, HeapListener... listeners) Defines a new heap in this context.
ContextBuilder	heap(String id, String ndbId, String[] path, HeapListener... listeners) Creates a new heap as specified by heap(boolean, String, String, String[], String[], HeapListener...)
ContextBuilder	interceptor(ContextInterceptor interceptor) Adds a ContextInterceptor to the builder.
ContextBuilder	mergeSettings(ContextBuilder other) Merges all the settings of the given ContextBuilder to the current setting of this object.
ObjectBuilder<NutDao>	newNutDaoBuilder(String type) Builds a new NutDao builder.
ContextBuilder	nutFilter(String id, ObjectBuilder<NutFilter> filter) Add a new NutFilter builder identified by the specified ID.
ContextBuilder	processContext(ProcessContext processContext) Sets the process context for the setting associated to the current tag.
ContextBuilder	releaseTag() Releases the current tag of this context.
ContextBuilder	tag(Object tag) Decorates the current builder with a new builder associated to a specified tag.
ContextBuilder	template(String id, String[] ebIds, String... daos) Builds a new template with no exclusion and default engine usages.
ContextBuilder	template(String id, String[] ebIds, String[] ebIdsExclusion, Boolean includeDefaultEngines, String... ndbIds) Creates a new workflow template.
ContextBuilder	workflow(String identifier, Boolean forEachHeap, String heapIdPattern, String workflowTemplateId) Creates a new workflow.

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

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

Constructor Detail

ContextBuilder

public ContextBuilder(ContextBuilder b,
              URL properties,
              ObjectBuilderInspector... inspectors)

Creates a new instance with the builder factories of a context and additional inspectors.

Parameters:

b - the builder providing the components factories (engine, dao, filter)

properties - the property set to apply to all components

inspectors - the inspectors to add to the factories

ContextBuilder

public ContextBuilder(ObjectBuilderFactory<Engine> engineBuilderFactory,
              ObjectBuilderFactory<NutDao> nutDaoBuilderFactory,
              ObjectBuilderFactory<NutFilter> nutFilterBuilderFactory,
              ObjectBuilderInspector... inspectors)

Creates a new instance with specific builder factories.

Parameters:

engineBuilderFactory - the engine builder factory, null if default should be created

nutDaoBuilderFactory - the DAO builder factory, null if default should be created

nutFilterBuilderFactory - the filter builder factory, null if default should be created

inspectors - the inspectors to add to the factories

ContextBuilder

public ContextBuilder(ObjectBuilderInspector... inspectors)

Creates a new instance.

Parameters:

inspectors - the inspectors

Method Detail

getDefaultBuilderId

public static String getDefaultBuilderId(Class<?> component)

Gets the default builder name for the given component class.

Parameters:

component - the component class

Returns:

the default ID

getDefaultBuilderId

public static String getDefaultBuilderId(String builderName)

Gets the default builder ID for the given builder name.

Parameters:

builderName - the builder name

Returns:

the default builder ID

getDefaultBuilderId

public static String getDefaultBuilderId()

Gets the default builder ID.

Returns:

the default ID

configureDefault

public ContextBuilder configureDefault()
                                throws IOException

Configures for each type provided by the engine builder factory and nut dao builder factory a default instance identified with an id starting by BUILDER_ID_PREFIX and followed by the type name itself.

Returns:

the current builder

Throws:

IOException - if configuration fails

newNutDaoBuilder

public ObjectBuilder<NutDao> newNutDaoBuilder(String type)

Builds a new NutDao builder.

Parameters:

type - the type of DAO

Returns:

the builder

tag

public ContextBuilder tag(Object tag)

Decorates the current builder with a new builder associated to a specified tag. Tagging the context allows to isolate a set of configurations that could be erased by calling clearTag(Object). This way, this feature is convenient when you need to poll the configurations to reload it.

All configurations will be associated to the tag until the releaseTag() method is called. If tag is currently set, then it is released when this method is called with a new tag.

Parameters:

tag - an arbitrary object which represents the current tag

Returns:

the current builder which will associates all configurations to the tag

See Also:

clearTag(Object), releaseTag()

processContext

public ContextBuilder processContext(ProcessContext processContext)

Sets the process context for the setting associated to the current tag.

Parameters:

processContext - the ProcessContext

Returns:

this builder

clearTag

public ContextBuilder clearTag(Object tag)

Clears all configurations associated to the given tag.

Parameters:

tag - the tag

Returns:

this ContextBuilder

releaseTag

public ContextBuilder releaseTag()

Releases the current tag of this context. When the configurations associated to a tag are finished, it could be released by calling this method to not tag next configurations.

Returns:

this current builder without tag

contextNutDaoBuilder

public ContextBuilder.ContextNutDaoBuilder contextNutDaoBuilder(String userId,
                                                       String type)

Returns a new context DAO builder.

Parameters:

userId - the final builder's ID, default ID if null

type - the final builder's type

Returns:

the specific context builder

contextNutDaoBuilder

public ContextBuilder.ContextNutDaoBuilder contextNutDaoBuilder(Class<?> type)

Returns a new default context DAO builder.

Parameters:

type - the component to build

Returns:

the specific context builder

contextNutDaoBuilder

public ContextBuilder.ContextNutDaoBuilder contextNutDaoBuilder(String id,
                                                       Class<?> type)

Returns a new default context DAO builder associated to a particular ID.

Parameters:

id - the specific ID

type - the component to build

Returns:

the specific context builder

cloneContextNutDaoBuilder

public ContextBuilder.ContextNutDaoBuilder cloneContextNutDaoBuilder(String id,
                                                            String userId)

Returns a new context DAO builder associated to a particular ID and based on an existing context DAO builder.

Parameters:

id - the specific ID

userId - the ID of the existing builder to clone, if null then the default DAO is used

Returns:

the specific context builder

contextNutFilterBuilder

public ContextBuilder.ContextNutFilterBuilder contextNutFilterBuilder(String id,
                                                             String type)

Returns a new context filter builder.

Parameters:

id - the final builder's ID

type - the final builder's type

Returns:

the specific context builder

contextNutFilterBuilder

public ContextBuilder.ContextNutFilterBuilder contextNutFilterBuilder(String id,
                                                             Class<? extends NutFilter> type)

Returns a new context filter builder.

Parameters:

id - the final builder's ID

type - the final builder's type

Returns:

the specific context builder

contextEngineBuilder

public ContextBuilder.ContextEngineBuilder contextEngineBuilder(String id,
                                                       String type)

Returns a new context engine builder.

Parameters:

id - the final builder's ID

type - the final builder's type

Returns:

the specific context builder

contextEngineBuilder

public ContextBuilder.ContextEngineBuilder contextEngineBuilder(Class<?> type)

Returns a new context default engine builder.

Parameters:

type - the component to build

Returns:

the specific context builder

contextEngineBuilder

public ContextBuilder.ContextEngineBuilder contextEngineBuilder(String id,
                                                       Class<?> type)

Returns a new default context engine builder associated to a particular ID.

Parameters:

id - the specific ID, if null then the default ID is used

type - the component to build

Returns:

the specific context builder

interceptor

public ContextBuilder interceptor(ContextInterceptor interceptor)

Adds a ContextInterceptor to the builder.

Parameters:

interceptor - the interceptor

Returns:

this ContextBuilder

nutFilter

public ContextBuilder nutFilter(String id,
                       ObjectBuilder<NutFilter> filter)

Add a new NutFilter builder identified by the specified ID.

Parameters:

id - the ID which identifies the builder in the context

filter - the filter builder associated to its ID

Returns:

this ContextBuilder

engineBuilder

public ContextBuilder engineBuilder(String id,
                           ObjectBuilder<Engine> engine)

Add a new Engine builder identified by the specified ID.

Parameters:

id - the ID which identifies the builder in the context

engine - the engine builder associated to its ID

Returns:

this ContextBuilder

heap

public ContextBuilder heap(String id,
                  String ndbId,
                  String[] path,
                  HeapListener... listeners)
                    throws IOException

Creates a new heap as specified by heap(boolean, String, String, String[], String[], HeapListener...) without any composition and which is not disposable.

Parameters:

id - the heap ID

ndbId - the NutDao builder the heap is based on

path - the path

listeners - some listeners for this heap

Returns:

this ContextBuilder

Throws:

IOException - if the HEAP could not be created

disposableHeap

public ContextBuilder disposableHeap(String id,
                            String ndbId,
                            String[] path,
                            HeapListener... listeners)
                              throws IOException

Creates a new disposable heap as specified by heap(boolean, String, String, String[], String[], HeapListener...) without any composition.

Parameters:

id - the heap ID

ndbId - the NutDao builder the heap is based on

path - the path

listeners - some listeners for this heap

Returns:

this ContextBuilder

Throws:

IOException - if the HEAP could not be created

heap

public ContextBuilder heap(boolean disposable,
                  String id,
                  String nutDaoId,
                  String[] heapIds,
                  String[] path,
                  HeapListener... listeners)
                    throws IOException

Defines a new heap in this context. A heap is always identified by an ID and is associated to NutDao builder to use to convert paths into Nut. A list of paths needs also to be specified to know which underlying nuts compose the heap.

The heap could be composed in part or totally of other heaps.

If the ObjectBuilder ID is not known, a IllegalArgumentException will be thrown.

Parameters:

disposable - if the heap is disposable or not (see NutDaoListener.isDisposable()

id - the heap ID

heapIds - the heaps composition

nutDaoId - the NutDao builder the heap is based on, default is used if null

path - the path

listeners - some listeners for this heap

Returns:

this ContextBuilder

Throws:

IOException - if the HEAP could not be created

template

public ContextBuilder template(String id,
                      String[] ebIds,
                      String... daos)
                        throws IOException

Builds a new template with no exclusion and default engine usages.

Parameters:

id - the template's id

ebIds - the set of Engine builder to use

daos - the DAO

Returns:

this ContextBuilder

Throws:

IOException - if an I/O error occurs

See Also:

template(String, String[], String[], Boolean, String...)

template

public ContextBuilder template(String id,
                      String[] ebIds,
                      String[] ebIdsExclusion,
                      Boolean includeDefaultEngines,
                      String... ndbIds)
                        throws IOException

Creates a new workflow template.

The template consists to chain a set of engines produced by the specified Engine builders. There is a chain for each possible NutType. A chain that processes a particular NutType of Nut is composed of engines ordered by type. All engines specified in parameter as array are simply organized following those two criteria to create the chains. Moreover, default engines could be injected in the chain to perform common operations to be done on nuts. If an Engine builder is specified in a chain while it is injected by default, then the configuration of the given builder will overrides the default one.

A set of NutDao builder could be specified to store processed nuts. When the client will retrieve the nuts, it will access it through a proxy URI configured in the protocol. This URI corresponds to a server in front of the location where nuts have been stored. For that reason the NutDao must support NutDao.save(com.github.wuic.nut.Nut) operation.

If the context builder should include engines by default, then a set of default engine to be excluded could be specified.

An IllegalStateException will be thrown if the context is not correctly configured. Bad settings are :

• Unknown ObjectBuilder ID
• A NutDao does not supports NutDao.save(com.github.wuic.nut.Nut) method

Parameters:

id - the template's id

ebIds - the set of Engine builder to use

ebIdsExclusion - some default builder to be excluded in the chain

ndbIds - the set of NutDao builder where to eventually upload processed nuts

includeDefaultEngines - include or not default engines

Returns:

this ContextBuilder

Throws:

IOException - if an I/O error occurs

workflow

public ContextBuilder workflow(String identifier,
                      Boolean forEachHeap,
                      String heapIdPattern,
                      String workflowTemplateId)
                        throws IOException,
                               WorkflowTemplateNotFoundException

Creates a new workflow. Any nut processing will be done through an existing workflow.

A workflow is based on a WorkflowTemplate with a specified ID.

The heap to be used is represented by a regex. The forEachHeap parameter indicates if only one workflow should be created having as heap a composition of all heaps matching the pattern. If the parameter is false, then a workflow is created for each matching NutsHeap. In this case, the workflow ID will be the concatenation if the given identifier and the heap's ID.

An IllegalStateException will be thrown if the context is not correctly configured. Bad settings are :

• Unknown NutsHeap ID

Parameters:

identifier - the identifier used to build the workflow ID, is the prefix if create one for each heap

forEachHeap - true if a dedicated workflow must be created for each matching heap, false for a composition

heapIdPattern - the regex matching the heap IDs that needs to be processed

workflowTemplateId - a template ID to initialize the workflow

Returns:

this ContextBuilder

Throws:

IOException - if an I/O error occurs

WorkflowTemplateNotFoundException - if the specified template ID does not exists

getFilters

public List<NutFilter> getFilters()

Gets the filters currently configured in this builder.

Returns:

the filters

mergeSettings

public ContextBuilder mergeSettings(ContextBuilder other)

Merges all the settings of the given ContextBuilder to the current setting of this object.

Parameters:

other - the object to merge

Returns:

this

build

public Context build()
              throws WuicException

Builds the context. Should throws an IllegalStateException if the context is not correctly configured. For instance: associate a heap to an undeclared NutDao builder ID.

Returns:

the new Context

Throws:

WuicException - if context construction fails