org.kuali.rice.kns.web.format
Class Formatter

java.lang.Object
  org.kuali.rice.kns.web.format.Formatter

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

ArrayFormatter, BigDecimalFormatter, BooleanFormatter, CollectionFormatter, CurrencyFormatter, DateFormatter, DelegationTypeFormatter, EncryptionFormatter, IntegerFormatter, LittleBooleanFormatter, LongFormatter, NoOpStringFormatter, PercentageFormatter, PhoneNumberFormatter, SimpleBooleanFormatter, TimestampAMPMFormatter, TypeFormatter

public class Formatter
extends Object
implements Serializable

It provides default formatting and conversion behavior for most value types, including primitives, arrays, and instances of most Collectiontypes. Formatter and its subclasses were designed primarily to be used by web app framework components, though they can also be used in other contexts.

During request processing, the PojoActionFormuses Formatter instances to convert inbound request values to JavaBean property types. Whenever a given value cannot be converted to its target type, the conversion method PropertyUtils.getProperty(Object, String)throws a FormatExceptionto signal this condition to the calling code.

During the response phase, Struts tags make calls to the PojoRequestProcessorin order to access bean property values. The PojoRequestProcessor then uses Formatter instances to format the bean values for presentation in the user interface.

In either case, Formatter instances are obtained by calling getFormatter(Class), which looks in an internal registry to determine which Formatter class to instantiate, and returns a new instance. The StrutsLive framework includes a number of Formatter classes that are registered statically; additional Formatter classes can be registered at compile time or at run time.

Subclasses of Formatter typically override the callback methods convertToObject(String) and formatObject(Object), which otherwise provide default conversion and formmating behavior needed for atomic values (i.e., an ordinary bean property such as a String or Integer, or else an element of a property typed as array or Collection).

See Also:

PojoActionForm#populate(HttpServletRequest), PojoPropertyUtilsBean#getProperty(Object, String), Serialized Form

Field Summary

(package private) static String	CREATE_MSG
protected Class	propertyType
private static Map	registry
protected Map	settings

Constructor Summary

Formatter()

Method Summary

Object	convertFromPresentationFormat(Object value) Returns an object representation of the provided string after first removing any extraneous formatting characters.
protected Object	convertToArray(String[] strings) Converts an array of strings to an array of objects by calling convertToObject(String)on each element of the provided array in turn, using instances of a Formatter class that corresponds to this Formatter's property type.
protected Collection	convertToCollection(String[] strings) Converts an array of strings to a Collection type corresponding to the value of propertyType.
protected Object	convertToObject(String string) May be orverridden by subclasses to customize its behavior.
static Class	findFormatter(Class type)
Object	format(Object value)
Object	formatArray(Object value)
protected Object	formatBean(Object bean) If an element of the Collection isn't a supported type, assume it's a JavaBean, and format each of its properties.
Object	formatCollection(Collection value)
Object	formatForPresentation(Object value) begin Kuali Foundation modification Returns a String representation of the given value.
protected Object	formatNull() May be overridden by subclasses to provide special handling for null values when formatting a bean property value for presentation.
Object	formatObject(Object value) May be overridden by subclasses to provide custom formatting behavior.
static Class	formatterForType(Class type) Return the Formatter associated with the given type, by consulting an internal registry.
static Formatter	getFormatter(Class aType)
static Formatter	getFormatter(Class aType, Map settings) Returns an instance of the Formatter class to be used to format the provided value type.
String	getImplementationClass()
protected Object	getNullObjectValue() May be overridden by subclasses to provide special handling for null values when converting from presentation format to a bean property type.
Class	getPropertyType()
Map	getSettings()
protected boolean	isBlank(String string) Deprecated. in favor of StringUtils#isEmptyString(String)
static boolean	isEmptyValue(Object obj)
static boolean	isNullValue(Object obj)
static boolean	isSupportedType(Class type) Returns true if the provided class is an array type, implements either the Listor Set interfaces, or is one of the Formatter classes currently registered.
static void	registerFormatter(Class type, Class formatterType) Binds the provided value type to a Formatter type.
void	setPropertyType(Class propertyType)
void	setSettings(Map settings)
protected String	trimString(Object target)
static String	unwrapString(Object target)

Methods inherited from class java.lang.Object

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

Field Detail

CREATE_MSG

static final String CREATE_MSG

See Also:

Constant Field Values

registry

private static Map registry

settings

protected Map settings

propertyType

protected Class propertyType

Constructor Detail

Formatter

public Formatter()

Method Detail

getFormatter

public static Formatter getFormatter(Class aType)

getFormatter

public static Formatter getFormatter(Class aType,
                                     Map settings)

Returns an instance of the Formatter class to be used to format the provided value type.

Parameters:

type - the class of the value to be formatted

settings - parameters used by subclasses to customize behavior

Returns:

an instance of Formatter or one of its subclasses

registerFormatter

public static void registerFormatter(Class type,
                                     Class formatterType)

Binds the provided value type to a Formatter type. Note that a single Formatter class can be associated with more than one type.

Parameters:

type - a value type

formatterType - a Formatter type

isSupportedType

public static boolean isSupportedType(Class type)

Returns true if the provided class is an array type, implements either the Listor Set interfaces, or is one of the Formatter classes currently registered.

See Also:

registerFormatter(Class, Class)

formatterForType

public static Class formatterForType(Class type)

Return the Formatter associated with the given type, by consulting an internal registry. Additional associations can be made by calling registerFormatter(Class, Class).

Returns:

a new Formatter instance

findFormatter

public static Class findFormatter(Class type)

getImplementationClass

public String getImplementationClass()

getPropertyType

public Class getPropertyType()

setPropertyType

public void setPropertyType(Class propertyType)

getSettings

public Map getSettings()

setSettings

public void setSettings(Map settings)

formatForPresentation

public Object formatForPresentation(Object value)

begin Kuali Foundation modification Returns a String representation of the given value. May be overridden by subclasses to provide customized behavior for different types, though generally the callback method format(Object)provides a better customization hook.

Provides default handling for properties typed as array or Collection. Subclass implementations of this method must invoke super.formatForPresentation() to take advantage of this built-in behavior.

Delegates to callback method formatObjectfor all other types. This method in turn invokes the callback method format, which serves as an extension point for subclasses; the default implementation simply returns its argument. Overriding format allows subclasses to take advantage of all of the array, primitive type, and Collection handling functionality provided by the base class.

Parameters:

value - the object to be formatted

Returns:

a formatted string representation of the given object

See Also:

end Kuali Foundation modification

formatNull

protected Object formatNull()

May be overridden by subclasses to provide special handling for null values when formatting a bean property value for presentation. The default implementation simply returns null

formatObject

public Object formatObject(Object value)

May be overridden by subclasses to provide custom formatting behavior. Provides default formatting implementation for primitive types. (Note that primitive types are will always be wrapped in an array in order to be passed as an argument of type Object).

formatBean

protected Object formatBean(Object bean)

If an element of the Collection isn't a supported type, assume it's a JavaBean, and format each of its properties. Returns a Map containing the formatted properties keyed by property name.

format

public Object format(Object value)

formatArray

public Object formatArray(Object value)

formatCollection

public Object formatCollection(Collection value)

convertFromPresentationFormat

public Object convertFromPresentationFormat(Object value)

Returns an object representation of the provided string after first removing any extraneous formatting characters. If the argument is a native array wrapping the actual value, the value is removed (unwrapped) from the array prior to invoking the callback method convertToObject(String), which performs the actual conversion.

If the provided object is null, a blank String, or a String[] of length 0 or that has null or a blank String in the first position, returns null. Otherwise, If the destination property is a Collection, returns an instance of that type containing the string values of the array elements.

If the provided object is an array, uses a Formatter corresponding to the array's component type to convert each of its elements, and returns a new array containing the converted values. May be overidden by subclasses to customize conversion, though ordinarily convertToObject(String)is a better choice since it takes advantage of convertFromPresentationFormat's built-in behavior.

Parameters:

value - the string value to be converted

Returns:

the object value corresponding to the provided string value

See Also:

convertToObject(String)

getNullObjectValue

protected Object getNullObjectValue()

May be overridden by subclasses to provide special handling for null values when converting from presentation format to a bean property type. The default implementation simply returns null

convertToObject

protected Object convertToObject(String string)

May be orverridden by subclasses to customize its behavior. The default implementation simply trims and returns the provided string.

convertToCollection

protected Collection convertToCollection(String[] strings)

Converts an array of strings to a Collection type corresponding to the value of propertyType. Since we don't have type information for the elements of the collection, no attempt is made to convert the elements from String to other types. However, subclasses can override this method if they need to provide the ability to convert the elements to a given type.

convertToArray

protected Object convertToArray(String[] strings)

Converts an array of strings to an array of objects by calling convertToObject(String)on each element of the provided array in turn, using instances of a Formatter class that corresponds to this Formatter's property type.

See Also:

propertyType

unwrapString

public static String unwrapString(Object target)

isNullValue

public static boolean isNullValue(Object obj)

isEmptyValue

public static boolean isEmptyValue(Object obj)

trimString

protected String trimString(Object target)

isBlank

protected boolean isBlank(String string)

Deprecated. in favor of StringUtils#isEmptyString(String)