ariba.util.formatter
Class Formatter

java.lang.Object
  ariba.util.formatter.Formatter

All Implemented Interfaces:

Compare, StringParser

Direct Known Subclasses:

AWVFormatterFactory.NonBlankString, BooleanFormatter, DateFormatter, DecimalFormatterCommon, GenericChooser.FieldPathFormatter, GenericMoneyFormatter, IntegerArrayFormatter, IntegerFormatter, ListFormatter, LongFormatter, StringFormatter, SystemBooleanFormatter

public abstract class Formatter
extends Object
implements StringParser, Compare

Formatter and its subclasses (StringFormatter, IntegerFormatter, etc.) are responsible for formatting raw objects into strings and parsing strings back into objects. They also provide methods for comparing pairs of objects for sorting purposes. Formatter instances can be used with the Sort class, since all Formatters implement the Compare interface.

The simplest way to use a formatter is in code like:

String foo = Formatter.stringValue(object); Object bar = Formatter.parseString(string, type);

Clients may also get a specific formatter for a given object or type by calling one of the static methods formatterForObject or formatterForType.

For improved runtime performance, this class maintains a cache of formatter instances, keyed by type.

Field Summary

Fields inherited from interface ariba.util.core.Compare

EqualTo, GreaterThan, LessThan

Constructor Summary

Formatter()
Creates a new Formatter.

Method Summary

boolean	canFormatNulls() Check whether this formatter handles null values. Most formatters do not handle null values, and so the user of the formatter is expected to handle the null value themselves.
int	compare(Object o1, Object o2) Compares two objects for sorting purposes in the default locale.
int	compare(Object o1, Object o2, Locale locale) Compares two objects for sorting purposes in the given locale.
boolean	equal(Object o1, Object o2) Returns true if and only if the two objects should be considered equal in the default locale.
boolean	equal(Object o1, Object o2, Locale locale) Returns true if and only if the two objects should be considered equal in the given locale.
String	getFormat(Object object) Returns a string representation of the given object in the default locale.
String	getFormat(Object object, Locale locale) Returns a string representation of the given object in the given locale.
static String	getFormatterClassForType(String type) Returns the formatter class to use for the given type.
static Formatter	getFormatterForObject(Object object) Returns a formatter instance for the given object based on its type.
static Formatter	getFormatterForType(String type) Returns a formatter instance for the given type.
Locale	getLocale() Returns the locale associated with this formatter.
static String	getStringValue(Object object) Returns a formatted string for the given object in the default locale.
static String	getStringValue(Object object, Locale locale) Returns a formatted string for the given object in the given locale.
Object	getValue(Object object) Returns an object of the appropriate type for this formatter derived from the given object.
abstract Object	getValue(Object object, Locale locale) Returns an object of the appropriate type for this formatter based on the given object.
boolean	handlesNulls() Check whether this class handles null values.
boolean	isBidirectional() Check whether this formatter guarantees text->object conversion. All formatters can convert from object to string, but not all can do the reverse conversion.
static ParseException	makeParseException(String errorKey, int offset) Convenience routine to get a ParseException with a localized message.
static ParseException	makeParseException(String errorKey, String argument, int offset) Convenience routine to get a ParseException with a localized message.
static boolean	objectsAreEqual(Object o1, Object o2) Returns true if and only if the two objects should be considered equal in the default locale.
static boolean	objectsAreEqual(Object o1, Object o2, Locale locale) Returns true if and only if the two objects should be considered equal in the given locale.
Object	parse(String string) Tries to parse the given string into an object of the appropriate type for this formatter.
Object	parse(String string, Locale locale) Tries to parse the given string into an object of the appropriate type for this formatter.
static Object	parseString(String string, String type) Tries to parse a string to create an object of the given type using the default locale.
static Object	parseString(String string, String type, Locale locale) Tries to parse a string to create an object of the given type using the given locale.
int	quickCompare(Object o1, Object o2) Compares two objects for sorting purposes in the default locale.
int	quickCompare(Object o1, Object o2, Locale locale) Compares two objects for sorting purposes in the given locale.
Object	quickCompareValue(Object object, Object previous) Returns a converted value for the given object to be used by the quickCompare method above.
static void	registerFormatter(String type, String className) Registers the given formatter class name to be associated with the give type.

Methods inherited from class java.lang.Object

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

Constructor Detail

Formatter

public Formatter()

Creates a new Formatter. Formatters are stateless and thus can be cached for use on multiple values of the same type.

Method Detail

getStringValue

public static String getStringValue(Object object)

Returns a formatted string for the given object in the default locale. If a formatter instance for the given object can't be found, calls toString on the object and returns the resulting string.

Parameters:

object - the object to format into a string

Returns:

a string representation of the object

getStringValue

public static String getStringValue(Object object,
                                    Locale locale)

Returns a formatted string for the given object in the given locale. If a formatter instance for the given object can't be found, calls toString on the object and returns the resulting string.

Parameters:

object - the object to format into a string

locale - the Locale to use for formatting

Returns:

a string representation of the object

parseString

public static Object parseString(String string,
                                 String type)
                          throws ParseException

Tries to parse a string to create an object of the given type using the default locale. Returns the original string if a formatter instance for the given type cannot be created.

Parameters:

string - the string to parse into an object

type - the Java type of the resulting object

Returns:

an object of the given type

Throws:

ParseException - if the string can't be parsed to create an object of the given type

parseString

public static Object parseString(String string,
                                 String type,
                                 Locale locale)
                          throws ParseException

Tries to parse a string to create an object of the given type using the given locale. Returns the original string if a formatter instance for the given type cannot be created.

Parameters:

string - the string to parse into an object

type - the Java type of the resulting object

locale - the Locale to use for parsing

Returns:

an object of the given type

Throws:

ParseException - if the string can't be parsed to create an object of the given type

objectsAreEqual

public static boolean objectsAreEqual(Object o1,
                                      Object o2)

Returns true if and only if the two objects should be considered equal in the default locale.

If the first object is non-null, retrieves a formatter instance based on its type; otherwise, uses the second object. If a formatter can't be found for either object, or the types of the two objects don't match, resorts to the equals method on the first non-null object. If both objects are null, returns true.

Parameters:

o1 - the first object to test for equality

o2 - the second object to test for equality

Returns:

true if the two objects are equal; false otherwise.

objectsAreEqual

public static boolean objectsAreEqual(Object o1,
                                      Object o2,
                                      Locale locale)

Returns true if and only if the two objects should be considered equal in the given locale.

If the first object is non-null, retrieves a formatter instance based on its type; otherwise, uses the second object. If a formatter can't be found for either object, or the types of the two objects don't match, resorts to the equals method on the first non-null object. If both objects are null, returns true.

Parameters:

o1 - the first object to test for equality

o2 - the second object to test for equality

locale - the Locale to use for equality testing

Returns:

true if the two objects are equal; false otherwise.

getFormatterForObject

public static Formatter getFormatterForObject(Object object)

Returns a formatter instance for the given object based on its type.

Parameters:

object - the object for which a formatter is required

Returns:

the appropriate formatter instance, or null if a formatter instance can't be created for the given type

getFormatterForType

public static Formatter getFormatterForType(String type)

Returns a formatter instance for the given type. Returns a cached instance if one exists for the given type. Otherwise a new formatter instance is created and cached based on the given type.

Parameters:

type - the type for which a formatter is required

Returns:

the appropriate formatter instance, or null if a formatter instance can't be created for the given type

getFormatterClassForType

public static String getFormatterClassForType(String type)

Returns the formatter class to use for the given type. We first check the class map for a perfect match with the type name. If that fails, we then check the map against any interfaces implemented by the type. If that fails, we then call ourselves recursively with the super-type of the given type. Returns null if a formatter class couldn't be determined for the given type, or if the type is invalid.

Parameters:

type - The fully qualified type name whose formatter we are finding

Returns:

The class name of the formatter, or null if there isn't any

registerFormatter

public static void registerFormatter(String type,
                                     String className)

Registers the given formatter class name to be associated with the give type. This allows clients of the formatter class to extend the set of formatters that are available. For example, the procurement module registers procure-specific formatter classes for types that are specific to that module.

Parameters:

type - the object type for the given formatter class

className - the class of formatter to use for the given type

makeParseException

public static ParseException makeParseException(String errorKey,
                                                int offset)

Convenience routine to get a ParseException with a localized message.

Parameters:

errorKey - - the key to the error message

offset - - the offset in the string being parsed

Returns:

a newly constructed ParseException

makeParseException

public static ParseException makeParseException(String errorKey,
                                                String argument,
                                                int offset)

Convenience routine to get a ParseException with a localized message.

Parameters:

errorKey - - the key to the error message

argument - - an argument to the error key

offset - - the offset in the string being parsed

Returns:

a newly constructed ParseException

getLocale

public Locale getLocale()

Returns the locale associated with this formatter. Uses the locale from the current resource service by default.

Returns:

the locale associated with this formatter

isBidirectional

public boolean isBidirectional()

Check whether this formatter guarantees text->object conversion.
All formatters can convert from object to string, but not all can do the reverse conversion. This method checks whether this formatter does the reverse conversion. By default we assume that the formatter can do the text -> object conversion, subclasses should override if this is not true.

Returns:

true if the formatter can do text to object conversion

canFormatNulls

public boolean canFormatNulls()

Check whether this formatter handles null values.
Most formatters do not handle null values, and so the user of the formatter is expected to handle the null value themselves. Formatters which handle nulls should override this method, returning true, to indicate that they do handle null values.

Returns:

true if the formatter expectes to handle null values

getFormat

public final String getFormat(Object object)

Returns a string representation of the given object in the default locale. Returns an empty string if the object is null.

Parameters:

object - the object to format as a string

Returns:

a string representation of the object

getFormat

public final String getFormat(Object object,
                              Locale locale)

Returns a string representation of the given object in the given locale. Returns an empty string if the object is null.

Parameters:

object - the object to format as a string

locale - the Locale to use for formatting

Returns:

a string representation of the object

handlesNulls

public final boolean handlesNulls()

Check whether this class handles null values.

Returns:

true if this formatter class handles null values itself

parse

public final Object parse(String string)
                   throws ParseException

Tries to parse the given string into an object of the appropriate type for this formatter. Uses the default locale to parse the string.

Specified by:

parse in interface StringParser

Parameters:

string - the string to parse

Returns:

an object of the appropriate type for this formatter

Throws:

ParseException - if the string can't be parsed to create an object the appropriate type

parse

public final Object parse(String string,
                          Locale locale)
                   throws ParseException

Tries to parse the given string into an object of the appropriate type for this formatter. Uses the given locale to parse the string.

Specified by:

parse in interface StringParser

Parameters:

string - the string to parse

locale - the Locale to use for parsing

Returns:

an object of the appropriate type for this formatter

Throws:

ParseException - if the string can't be parsed to create an object the appropriate type

getValue

public final Object getValue(Object object)

Returns an object of the appropriate type for this formatter derived from the given object. The default locale is used for any conversion that may be done.

The type of the given object can by anything; it is up to each specific implementation to do the appropriate conversion, parsing, etc. to create a value of the appropriate type.

The return value may be null depending on the specific implementation for a given formatter.

Specified by:

getValue in interface StringParser

Parameters:

object - the object to convert to the type for this formatter

Returns:

an object of the appropriate type for this formatter

getValue

public abstract Object getValue(Object object,
                                Locale locale)

Returns an object of the appropriate type for this formatter based on the given object. The given locale is used for any conversion that may be done.

The type of the given object can by anything; it is up to each specific implementation to do the appropriate conversion, parsing, etc. to create a value of the appropriate type.

The return value may be null depending on the specific implementation for a given formatter.

Subclasses must define this method to provide type-specific conversion.

Parameters:

object - the object to convert to the type for this formatter

locale - the locale used when converting the object

Returns:

an object of the appropriate type for this formatter

equal

public final boolean equal(Object o1,
                           Object o2)

Returns true if and only if the two objects should be considered equal in the default locale. Returns true if the two objects are, in fact, the same object or both are null. Otherwise, returns false if exactly one of the objects is null. Otherwise, calls the protected method objectsEqual to determine if the two (non-null) objects are equal.

Parameters:

o1 - the first object to test for equality

o2 - the second object to test for equality

Returns:

true if the two objects are equal; false otherwise.

equal

public final boolean equal(Object o1,
                           Object o2,
                           Locale locale)

Returns true if and only if the two objects should be considered equal in the given locale. Returns true if the two objects are, in fact, the same object or both are null. Otherwise, returns false if exactly one of the objects is null. Otherwise, calls the protected method objectsEqual to determine if the two (non-null) objects are equal.

Parameters:

o1 - the first object to test for equality

o2 - the second object to test for equality

locale - the Locale to use for equality testing

Returns:

true if the two objects are equal; false otherwise.

compare

public final int compare(Object o1,
                         Object o2)

Compares two objects for sorting purposes in the default locale. Returns an int value which is less than, equal to, or greater than zero depending on whether the first object sorts before, the same, or after the second object.

Returns zero if the two objects are, in fact, the same object or both are null. Otherwise, arbitrarily returns -1 if the first object is null, or 1 if the second is null. Otherwise, calls the protected method compareObjects to compare the two (non-null) objects.

Specified by:

compare in interface Compare

Parameters:

o1 - the first object to compare

o2 - the second object to compare

Returns:

int value which determines how the two objects should be ordered

compare

public final int compare(Object o1,
                         Object o2,
                         Locale locale)

Compares two objects for sorting purposes in the given locale. Returns an int value which is less than, equal to, or greater than zero depending on whether the first object sorts before, the same, or after the second object.

Returns zero if the two objects are, in fact, the same object or both are null. Otherwise, arbitrarily returns -1 if the first object is null, or 1 if the second is null. Otherwise, calls the protected method compareObjects to compare the two (non-null) objects.

Parameters:

o1 - the first object to compare

o2 - the second object to compare

locale - the Locale to use for comparison

Returns:

int value which determines how the two objects should be ordered

quickCompare

public final int quickCompare(Object o1,
                              Object o2)

Compares two objects for sorting purposes in the default locale.

This method is a performance optimzation for sorting. If comparing two values of a given type involves some conversion or processing that is too expensive to do for each comparison, this method and the quickCompareValue method below can be used to precompute the values to use for sorting. Any code which needs to sort these types should call this method rather than compare

quickCompare

public final int quickCompare(Object o1,
                              Object o2,
                              Locale locale)

Compares two objects for sorting purposes in the given locale.

This method is a performance optimzation for sorting. If comparing two values of a given type involves some conversion or processing that is too expensive to do for each comparison, this method and the quickCompareValue method below can be used to precompute the values to use for sorting. Any code which needs to sort these types should call this method rather than compare

quickCompareValue

public Object quickCompareValue(Object object,
                                Object previous)

Returns a converted value for the given object to be used by the quickCompare method above. The previous object is the previous value that was passed to quickCompareValue (pre-converted).

The default implementation is to just return object itself.