net.sf.collections15.functors.transformer
Class TransformerUtils

java.lang.Object
  net.sf.collections15.functors.transformer.TransformerUtils

public class TransformerUtils
extends java.lang.Object

TransformerUtils provides reference implementations and utilities for the Transformer functor interface. The supplied Transformers are:

• Invoker - returns the result of a method call on the input object
• Clone - returns a clone of the input object
• Constant - always returns the same object
• Closure - performs a Closure and returns the input object
• Predicate - returns the result of the predicate as a Boolean
• Factory - returns a new object from a factory
• Chained - chains two or more transformers together
• Switch - calls one transformer based on one or more predicates
• SwitchMap - calls one transformer looked up from a Map
• Instantiate - the Class input object is instantiated
• Map - returns an object from a supplied Map
• Null - always returns null
• NOP - returns the input object, which should be immutable
• Exception - always throws an exception
• StringValue - returns a java.lang.String representation of the input object

All the supplied Transformers are Serializable.

Since:

Collections15 1.0

Author:

Stephen Colebourne, James Carman, Chris Lambrou (port to Java 5.0)

Constructor Summary

protected

TransformerUtils() Protected constructor prevents direct instantiation, but allows users to extend this library to provide their own augmented static library class.

Method Summary

static <T> Transformer<T,T>	asTransformer(Closure<T> closure) Returns a Transformer that executes a Closure on the input, before returning it as output.
static <I,O> Transformer<I,O>	asTransformer(Factory<O> factory) Returns a Transformer implementation whose transform method uses a Factory to create the returned output object.
static <T> Transformer<T,java.lang.Boolean>	asTransformer(Predicate<T> predicate) Returns a Transformer that evaluates a Predicate each time the Transformer is used, with the result of the Predicate returned as output.
static <I,M,O> Transformer<I,O>	chainedTransformer(Transformer<? super I,? extends M> transformer1, Transformer<? super M,? extends O> transformer2) Returns a Transformer whose transform method chains together the transform methods of two existing Transformers If you need to chain together more than two Transformers, you can use ChainedTransformer.getInstance(net.sf.collections15.Transformer, net.sf.collections15.Transformer) and the convenience methods ChainedTransformer.append(net.sf.collections15.Transformer) and ChainedTransformer.prepend(net.sf.collections15.Transformer) instead.
static <T> Transformer<T,T>	cloneTransformer() Returns a Transformer that returns a clone of the input object.
static <I,O> Transformer<I,O>	constantTransformer(O constantToReturn) Returns a Transformer that returns the same object each time the transformer is used.
static <I,O> Transformer<I,O>	exceptionTransformer() Returns a Transformer that always throws an exception.
static <I,O> Transformer<I,O>	ifElseTransformer(Predicate<I> predicate, Transformer<I,O> trueTransformer, Transformer<I,O> falseTransformer) Returns a Transformer that delegates to one of two existing Transformers, depending on the result of a Predicate.
static <T> Transformer<java.lang.Class<? extends T>,T>	instantiateTransformer() Returns a Transformer that takes an input Class object and uses it to output an instance of that class, created by reflection using the parameterless constructor of the Class.
static <T> Transformer<java.lang.Class<? extends T>,T>	instantiateTransformer(java.lang.Class[] parameterTypes, java.lang.Object[] arguments) Returns a Transformer that takes an input Class object and uses it to output an instance of that class, created by reflection using the constructor of the Class specified by the parameterTypes argument, passing in the corresponding arguments to the constructor.
static <I,O> Transformer<I,O>	invokerTransformer(java.lang.String methodName) Returns a Transformer that invokes a specified method on the input object.
static <I,O> Transformer<I,O>	invokerTransformer(java.lang.String methodName, java.lang.Class[] parameterTypes, java.lang.Object[] arguments) Returns a Transformer that invokes a specified method on the input object.
static <I,O> Transformer<I,O>	mapTransformer(java.util.Map<? extends I,? extends O> map) Returns a Transformer that uses the specified map as a lookup to transform the input objects into the output objects.
static <T> Transformer<T,T>	nopTransformer() Returns a Transformer that simply returns the input object.
static <I,O> Transformer<I,O>	nullTransformer() Returns a Transformer that always returns null.
static <E> Transformer<E,java.lang.String>	stringValueTransformer() Returns a Transformer that outputs the string value of the input, using the String.valueOf method.
static <I,O> Transformer<I,O>	switchMapTransformer(java.util.Map<I,Transformer<I,O>> objectsAndTransformers) Returns a Transformer that uses the input object as a key to find the Transformer to delegate to.
static <I,O> Transformer<I,O>	switchTransformer(java.util.Map<Predicate<I>,Transformer<I,O>> predicatesAndTransformers) Returns a Transformer instance that uses the specified map of Predicates and Transformers, delegating to the Transformer whose corresponding Predicate evaluates to true.

Methods inherited from class java.lang.Object

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

Constructor Detail

TransformerUtils

protected TransformerUtils()

Protected constructor prevents direct instantiation, but allows users to extend this library to provide their own augmented static library class.

Method Detail

exceptionTransformer

public static <I,O> Transformer<I,O> exceptionTransformer()

Returns a Transformer that always throws an exception. This could be useful during testing as a placeholder.

Returns:

A Transformer that always throws an exception.

See Also:

ExceptionTransformer

nullTransformer

public static <I,O> Transformer<I,O> nullTransformer()

Returns a Transformer that always returns null.

Returns:

A Transformer that always returns null.

See Also:

ConstantTransformer

nopTransformer

public static <T> Transformer<T,T> nopTransformer()

Returns a Transformer that simply returns the input object. The input object should be immutable to maintain the contract of Transformer (although this is not checked).

Returns:

A Transformer that simply returns the input object.

See Also:

NOPTransformer

cloneTransformer

public static <T> Transformer<T,T> cloneTransformer()

Returns a Transformer that returns a clone of the input object. The input object will be cloned using one of these techniques (in order):

• public clone method
• public copy constructor
• serialization clone

  Returns:

  A Transformer that returns a clone of the input object.

  See Also:

  CloneTransformer

constantTransformer

public static <I,O> Transformer<I,O> constantTransformer(O constantToReturn)

Returns a Transformer that returns the same object each time the transformer is used.

Parameters:

constantToReturn - The constant object to be returned by the Transformer's transform method.

Returns:

A Transformer that returns the same object each time the transformer is used.

See Also:

ConstantTransformer

asTransformer

public static <T> Transformer<T,T> asTransformer(Closure<T> closure)

Returns a Transformer that executes a Closure on the input, before returning it as output.

Parameters:

closure - The Closure to execute in the transform.

Returns:

A Transformer that executes a Closure on the input, before returning it as output.

Throws:

java.lang.IllegalArgumentException - Throws if the Closure is null.

See Also:

ClosureTransformer

asTransformer

public static <T> Transformer<T,java.lang.Boolean> asTransformer(Predicate<T> predicate)

Returns a Transformer that evaluates a Predicate each time the Transformer is used, with the result of the Predicate returned as output.

Parameters:

predicate - The Predicate to execute in the transform.

Returns:

A Transformer that evaluates a Predicate each time the Transformer is used, with the result of the Predicate returned as output.

Throws:

java.lang.IllegalArgumentException - Thrown if the Predicate is null.

See Also:

PredicateTransformer

asTransformer

public static <I,O> Transformer<I,O> asTransformer(Factory<O> factory)

Returns a Transformer implementation whose transform method uses a Factory to create the returned output object.

Parameters:

factory - The factory used to create the transform output objects.

Returns:

A Transformer implementation whose transform method uses a Factory to create the returned output object.

Throws:

java.lang.IllegalArgumentException - Thrown if the Factory is null.

See Also:

FactoryTransformer

chainedTransformer

public static <I,M,O> Transformer<I,O> chainedTransformer(Transformer<? super I,? extends M> transformer1,
                                                          Transformer<? super M,? extends O> transformer2)

Returns a Transformer whose transform method chains together the transform methods of two existing Transformers

If you need to chain together more than two Transformers, you can use ChainedTransformer.getInstance(net.sf.collections15.Transformer, net.sf.collections15.Transformer) and the convenience methods ChainedTransformer.append(net.sf.collections15.Transformer) and ChainedTransformer.prepend(net.sf.collections15.Transformer) instead.

Parameters:

transformer1 - The first Transformer.

transformer2 - the second Transformer.

Returns:

A Transformer whose transform method chains together the transform methods of two existing Transformers

Throws:

java.lang.IllegalArgumentException - Thrown if either Transformer is null.

See Also:

ChainedTransformer

ifElseTransformer

public static <I,O> Transformer<I,O> ifElseTransformer(Predicate<I> predicate,
                                                       Transformer<I,O> trueTransformer,
                                                       Transformer<I,O> falseTransformer)

Returns a Transformer that delegates to one of two existing Transformers, depending on the result of a Predicate.

Parameters:

predicate - The Predicate evaluated to determine which of the Transformers to delegate to.

trueTransformer - The Transformer used if the Predicate evaluates true.

falseTransformer - The Transformer used if the Predicate evaluates false.

Returns:

A Transformer that delegates to one of two existing Transformers, depending on the result of a Predicate.

Throws:

java.lang.IllegalArgumentException - Thrown if any argument is null.

See Also:

SwitchTransformer

switchTransformer

public static <I,O> Transformer<I,O> switchTransformer(java.util.Map<Predicate<I>,Transformer<I,O>> predicatesAndTransformers)

Returns a Transformer instance that uses the specified map of Predicates and Transformers, delegating to the Transformer whose corresponding Predicate evaluates to true.

Parameters:

predicatesAndTransformers - A map of Predicates to Transformers. Each non-null Predicate key defines a single switch case, with the corresponding Transformer being used to transform an input object if it matches the Predicate.

Predicates are evaluated in the iteration order of the map's key set, with the exception of the null Predicate key. If a null Predicate key is specified in the set, it's corresponding Transformer is treated as the default case, used to transform an input object if it doesn't satisfy any of the non-null Predicate cases. If there is no default Transformer, an IllegalArgumentException will be thrown by the transform method.

Note that the map is not modified by this method.

Returns:

A new instance that uses the specified map of Predicates and Transformers.

Throws:

java.lang.IllegalArgumentException - Thrown if the map is null.

java.lang.IllegalArgumentException - Thrown if any Transformer in the map is null.

switchMapTransformer

public static <I,O> Transformer<I,O> switchMapTransformer(java.util.Map<I,Transformer<I,O>> objectsAndTransformers)

Returns a Transformer that uses the input object as a key to find the Transformer to delegate to.

Parameters:

objectsAndTransformers - A map consisting of object keys and Transformer values. The map is used to obtain a Transformer for an input object, which is then used to tansform the input object. If there is no matching Transformer, the default Transformer is used instead (specified in the map using a null key). If there is no default Transformer, an IllegalArgumentException will be thrown by the transform method.

Returns:

A Transformer that uses the input object as a key to find the Transformer to delegate to.

Throws:

java.lang.IllegalArgumentException - Thrown if the map is null, empty, or any Transformer in the map is null.

See Also:

SwitchTransformer

instantiateTransformer

public static <T> Transformer<java.lang.Class<? extends T>,T> instantiateTransformer()

Returns a Transformer that takes an input Class object and uses it to output an instance of that class, created by reflection using the parameterless constructor of the Class.

Returns:

A Transformer that takes an input Class object and uses it to output an instance of that class, created by reflection using the parameterless constructor of the Class.

See Also:

InstantiateTransformer, InstantiateTransformer.transform(java.lang.Class)

instantiateTransformer

public static <T> Transformer<java.lang.Class<? extends T>,T> instantiateTransformer(java.lang.Class[] parameterTypes,
                                                                                     java.lang.Object[] arguments)

Returns a Transformer that takes an input Class object and uses it to output an instance of that class, created by reflection using the constructor of the Class specified by the parameterTypes argument, passing in the corresponding arguments to the constructor.

Parameters:

parameterTypes - The parameter types of the constructer to invoke on an input Class. May be null or empty if arguments is also null or empty, in which case the parameterless constructor will be used to create an output object from an input Class. The contents of this array are defensively copied.

arguments - The arguments to pass to the constructor invoked on an input Class.

Returns:

A Transformer that takes an input Class object and uses it to output an instance of that class, created by reflection using the constructor of the Class specified by the parameterTypes argument, passing in the corresponding arguments to the constructor.

Throws:

java.lang.IllegalArgumentException - Thrown if either of parameterTypes or arguments is null, but the other is not.

java.lang.IllegalArgumentException - Thrown if any element in parameterTypes is null.

java.lang.IllegalArgumentException - Thrown if any none-null element in arguments is not an instance of its corresponding parameterTypes class.

See Also:

InstantiateTransformer, InstantiateTransformer.transform(java.lang.Class)

mapTransformer

public static <I,O> Transformer<I,O> mapTransformer(java.util.Map<? extends I,? extends O> map)

Returns a Transformer that uses the specified map as a lookup to transform the input objects into the output objects.

Parameters:

map - The map used as a lookup to transform the input objects into output objects.

Returns:

A Transformer that uses the specified map as a lookup to transform the input objects into the output objects.

Throws:

java.lang.IllegalArgumentException - if the map is null.

See Also:

MapTransformer

invokerTransformer

public static <I,O> Transformer<I,O> invokerTransformer(java.lang.String methodName)

Returns a Transformer that invokes a specified method on the input object. The method must have no parameters.

For example, TransformerUtils.invokerTransformer("getName"); will call the getName/code> method on the input object and output the return value.

If a null Class is input to the Transformer it will throw an IllegalArgumentException.

Parameters:

methodName - the method name to call on the input object, may not be null. The return type of the method must be assignable to the generic type <O>

Returns:

ATransformer that invokes a specified method on the input object. The method must have no parameters.

Throws:

java.lang.IllegalArgumentException - if methodName is null.

See Also:

InvokerTransformer, InvokerTransformer.transform(I)

invokerTransformer

public static <I,O> Transformer<I,O> invokerTransformer(java.lang.String methodName,
                                                        java.lang.Class[] parameterTypes,
                                                        java.lang.Object[] arguments)

Returns a Transformer that invokes a specified method on the input object.

Parameters:

methodName - the method name to call on the input object, may not be null. The return type of the method must be assignable to the generic type <O>

parameterTypes - The parameter types of the method to invoke on an input object. May be null or empty if arguments is also null or empty, in which case the parameterless mehod of the specified name will be used. The contents of this array are defensively copied.

arguments - The arguments to pass to the method invoked on an input Class.

Returns:

A Transformer that invokes a specified method on the input object.

Throws:

java.lang.IllegalArgumentException - Thrown if the method name argument is null.

java.lang.IllegalArgumentException - Thrown if either of parameterTypes or arguments is null, but the other is not.

java.lang.IllegalArgumentException - Thrown if any element in parameterTypes is null.

java.lang.IllegalArgumentException - Thrown if any none-null element in arguments is not an instance of its corresponding parameterTypes class.

See Also:

InvokerTransformer, InvokerTransformer.transform(I)

stringValueTransformer

public static <E> Transformer<E,java.lang.String> stringValueTransformer()

Returns a Transformer that outputs the string value of the input, using the String.valueOf method. null returns 'null'.

Returns:

A Transformer that outputs the string value of the input, using the String.valueOf method.

See Also:

StringValueTransformer