com.ls.util.threading
Class ObjectBuilder

java.lang.Object
  |
  +--com.ls.util.threading.ObjectBuilder
Direct Known Subclasses:
StaticThreadPoolBuilder

public abstract class ObjectBuilder
extends Object

An object builder constructs java objects out of a given set of properties. To do this an instance of a concrete object builder has to be created. Then the particular properties can be set either by calling setXXX(...) methods directly (which are not defined in this class but should be in subclasses of this one) or by calling setProperties(Properties). The argument of that method is a Properties object containing the properties that should be set. After setting the properties a call to newInstance() will create the actual java object. You can call newInstance() serveral times to create java objects using the same properties.

Object builder instances can be reused by calling reset() which deletes all previously set property values.

Version:
$Revision: 1.1 $
Author:
Last modified by $Author: MFehrenbach $

Constructor Summary
ObjectBuilder()
          Constructs a new object builder instance and calls reset() to put it in a defined state.
 
Method Summary
 void check()
          Performes a check if all set properites are correct.
protected  void clearPropertyError(String property)
          Resets a previously set property error.
protected abstract  void doCheck()
          This method has to be overwritten by subclasses to perform specific operations when the method check() is called.
protected abstract  Object doNewInstance()
          This method has to be overwritten by subclasses to perform the actual instantiation of the java object.
protected abstract  void doReset()
          This method has to be overwritten by subclasses to perform specific operations when the method reset() is called, e.g. resetting of subclass specific properties.
protected  boolean hasPropertyError()
          Checks if there are errors associated with any properties.
protected  boolean hasPropertyError(String property)
          Checks if an error was set on the given property.
static ObjectBuilder newBuilderInstance(String className)
          Utility method which allowed to quickly instantiate an object builder by class name.
 Object newInstance()
          Builds a new java object according to the properties set on this object builder.
 void reset()
          Resets all properties that are already set on this object builder.
 void setProperties(Properties props)
          Sets all properties defined in the argument 'props' at once.
 void setProperties(Properties props, String basePath)
          Behaves similar to setProperties(Properties), except that only those entries in 'props' will be processed, whose property name starts with the given 'basePath' argument.
 void setProperty(String key, Object value)
          Sets a single property with the given name and value.
protected  void setPropertyError(String property, String message)
          Associates the given property name with the given error message.
protected  void setPropertyError(String property, Throwable error)
          Behaves similar to setPropertyError(String, String) except that a throwable object can be associated with the property name instead of an error message (as string).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ObjectBuilder

public ObjectBuilder()
Constructs a new object builder instance and calls reset() to put it in a defined state.
Method Detail

setProperty

public final void setProperty(String key,
                              Object value)
Sets a single property with the given name and value. This method searches for a method defined at the current class matching the following pattern:

    public void set[property name with first letter upper case](
              [to value compatible parameter type]
          )   

If such a method is found, it is called with the given property value as argument. Otherwise it is ignored.

Parameters:
key - The name of the property.
value - The value of the property.

setProperties

public final void setProperties(Properties props)
Sets all properties defined in the argument 'props' at once. For each entry in 'props' the method setProperty(String, Object) is called.

Parameters:
props - The properties that should be set on this object builder at once.

setProperties

public final void setProperties(Properties props,
                                String basePath)
Behaves similar to setProperties(Properties), except that only those entries in 'props' will be processed, whose property name starts with the given 'basePath' argument.

Parameters:
props - The properties that should be set on this object builder at once.
basePath - substring of properties

check

public final void check()
                 throws BuildException
Performes a check if all set properites are correct. If not, a build exception is raised.

Throws:
BuildException - If some properties are invalid.

newInstance

public final Object newInstance()
                         throws BuildException
Builds a new java object according to the properties set on this object builder. This method calls check() first to make sure that all properties are valid. If not, the build process is interrupted and a build exception is raised.

Returns:
The newly created java object.
Throws:
BuildException - If an error occured during the build process.

reset

public final void reset()
Resets all properties that are already set on this object builder. This method is usefull to reuse a object builder for creating a java object of the same type but with different properties.


newBuilderInstance

public static final ObjectBuilder newBuilderInstance(String className)
                                              throws BuildException
Utility method which allowed to quickly instantiate an object builder by class name. If the given class name is invalid or the specific class cannot be found or cannot be instantiated because of any other reason a build exception is thrown.

Parameters:
className - The name of the object builder class, that should be instantiated.
Returns:
The object builder instance created of the class name.
Throws:
BuildException - If the class could not be instantiated.

doCheck

protected abstract void doCheck()
                         throws BuildException
This method has to be overwritten by subclasses to perform specific operations when the method check() is called. If this method returns a build exception, the same exception will also be returned by check().

Throws:
BuildException - If some properties set are not valid.

doNewInstance

protected abstract Object doNewInstance()
                                 throws Throwable
This method has to be overwritten by subclasses to perform the actual instantiation of the java object. It is called by method newInstance(). Every exception thrown by this method is catched by newInstance(), encapsulated in a build exception and thrown again (as a build exception).
Returns:
The newly created java object.
Throws:
Throwable - If something goes wrong during instantiation.

doReset

protected abstract void doReset()
This method has to be overwritten by subclasses to perform specific operations when the method reset() is called, e.g. resetting of subclass specific properties.

setPropertyError

protected final void setPropertyError(String property,
                                      String message)
Associates the given property name with the given error message. This method is called if a property cannot be set because of an invalid value.
Parameters:
property - The name of the property, whose value cannot be set.
message - The error message.

setPropertyError

protected final void setPropertyError(String property,
                                      Throwable error)
Behaves similar to setPropertyError(String, String) except that a throwable object can be associated with the property name instead of an error message (as string).
Parameters:
property - The name of the property, whose value cannot be set.
error - The throwable object.

clearPropertyError

protected final void clearPropertyError(String property)
Resets a previously set property error.
Parameters:
property - The name of the property, whose error state should be reset.

hasPropertyError

protected final boolean hasPropertyError(String property)
Checks if an error was set on the given property.

Parameters:
property - The name of the property.
Returns:
True, if an error is set, otherwise false.

hasPropertyError

protected final boolean hasPropertyError()
Checks if there are errors associated with any properties.

Returns:
True, if there are errors, otherwise false.