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

java.lang.Object
  extended by org.kuali.rice.core.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

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:
Serialized Form

Nested Class Summary
protected static class Formatter.ArrayUtils
          begin Kuali Foundation modification This class sets the value of an element of an array of primitives at the supplied index.
 
Field Summary
protected  Class propertyType
           
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()
           
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)
           
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

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)


Copyright © 2005-2013 The Kuali Foundation. All Rights Reserved.