net.sourceforge.stripes.validation
Class OneToManyTypeConverter

java.lang.Object
  extended by net.sourceforge.stripes.validation.OneToManyTypeConverter
All Implemented Interfaces:
TypeConverter<Object>

public class OneToManyTypeConverter
extends Object
implements TypeConverter<Object>

A specialized type converter for converting a single input field/parameter value into one or more Java objects contained in a List. Designed to handle the case where a user is allowed to enter more than one value into a single field, separated by certain characters, that should result in a number of Java objects being created.

For example imagine a search field where a user is allowed to enter one or more numbers. They might enter "2 4 8 16". In this case the OneToManyTypeConverter will convert this to a Collection of numbers with one entry for each of the four numbers shown above. The type of number created (Integer, Long etc.) is inferred from the declaration of the property on the ActionBean. For example:

@Validate(converter=OneToManyTypeConverter.class) private List<Long> numbers;

would result in the numbers being converted to Longs as opposed to any other numeric type.

The splitting of the input String is done using the String.split(String) method. The regular expression passed to split() is obtained by calling getSplitRegex(). By default the regular expression used will match an optional comma followed by one or spaces (e.g. " " or ", " or "   " etc.). This behaviour can easily be modified by subclassing and overriding getSplitRegex() to return a different regular expression string.

The individual components of the String are then converted using an appropriate TypeConverter which is looked up using the TypeConverterFactory. As a result the OneToManyTypeConverter can be used to convert to a list of any type fo which a TypeConverter has been registered. If a usable TypeConverter cannot be discovered then an Exception will be thrown! However, if you wish to use the OneToManyTypeConverter with a TypeConverter which is not registered as the default converter for it's type you can override this behaviour by subclassing this class and overriding getSingleItemTypeConverter(Class).

Strictly speaking the OneToManyTypeConverter returns a Collection of converted items. It does not have any way of inferring the collection type that should be used, and so by default it will always return an instance of List. This behaviour can easily be overriden by extending this class and overriding getCollectionInstance().

Note that the converter itself does not create any ValidationErrors, but that by using other TypeConverters internally it is possible to produce one or more errors per item split out of the input String!

Since:
Stripes 1.2.2
Author:
Tim Fennell

Constructor Summary
OneToManyTypeConverter()
           
 
Method Summary
 Collection<? extends Object> convert(String input, Class<? extends Object> targetType, Collection<ValidationError> errors)
          Converts the supplied String into one or more objects is the manner described in the class level JavaDoc.
 Collection getCollectionInstance()
          Instantiates and returns a Collection of a type that can be set on ActionBeans using this converter.
protected  TypeConverter getSingleItemTypeConverter(Class targetType)
          Fetches an instance of TypeConverter that can be used to convert the individual items split out of the input String.
protected  String getSplitRegex()
          Returns the String form of a regular expression that identifies the separator Strings in the input String.
 void setLocale(Locale locale)
          Sets the locale that the TypeConverter can expect incoming Strings to be in.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OneToManyTypeConverter

public OneToManyTypeConverter()
Method Detail

setLocale

public void setLocale(Locale locale)
Description copied from interface: TypeConverter
Sets the locale that the TypeConverter can expect incoming Strings to be in. This method will only be called once during a TypeConverter's lifetime, and will be called prior to any invocations of convert().

Specified by:
setLocale in interface TypeConverter<Object>
Parameters:
locale - the locale that the TypeConverter will be converting from.

convert

public Collection<? extends Object> convert(String input,
                                            Class<? extends Object> targetType,
                                            Collection<ValidationError> errors)
Converts the supplied String into one or more objects is the manner described in the class level JavaDoc. If any validation errors occur then null is returned regardless of whether any items were successfully converted or not.

Specified by:
convert in interface TypeConverter<Object>
Parameters:
input - an input String containing one or more items to be converted in a single String
targetType - the type that each individual item will be converted to
errors - a collection of ValidationErrors that can be added to
Returns:
a Collection containing one or more items of targetType, or null if any ValidationErrors occur.

getCollectionInstance

public Collection getCollectionInstance()
Instantiates and returns a Collection of a type that can be set on ActionBeans using this converter. By default returns an instance of List.

Returns:
an instance of List

getSplitRegex

protected String getSplitRegex()
Returns the String form of a regular expression that identifies the separator Strings in the input String. The default expression matches an optional comma followed by one or more spaces.

Returns:
a regular expression matching an optional comma followed by one or more spaces.

getSingleItemTypeConverter

protected TypeConverter getSingleItemTypeConverter(Class targetType)
Fetches an instance of TypeConverter that can be used to convert the individual items split out of the input String. By default uses the TypeConverterFactory to find an appropriate TypeConverter.

Parameters:
targetType - the type that each item should be converted to.
Returns:
a TypeConverter for use in converting each individual item.


? Copyright 2005-2006, Stripes Development Team.