Formatter (josef 3.2.5 API)

java.lang.Object
- org.josef.util.Formatter

All Implemented Interfaces:

Serializable
```
@Status(stage=DEVELOPMENT,
        unitTests=PARTIAL)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
public class Formatter
extends Object
implements Serializable
```
Formatter class that aids in formatting dates, date/times, decimals, integers, longs and times.
Usage: Normally you simply create a formatter and then use it to parse input and format output. To parse a date for example use:
```
 final Formatter formatter = new Formatter(Locale.US);
 final Date date = formatter.parseDate("3/14/1896");
```
When you have a date object, you can simply format it using: formatter.formatDate(date);
This formatter class uses default values a lot. In the example above a default date formatter is created using a factory method of FormatterFactory. This date formatter in turn is then used over and over again to parse and format dates. Naturally you can customize the way objects are parsed and formatted, for example using patterns. Lets assume you want to parse ISO 8601 dates. These dates are in the form yyyy-mm-dd. You can parse these dates with the formatter declared above, using the following code:
final Date date = formatter.parseDate("1896-03-14", "yyyy-MM-dd");
It will even parse the basic format like this: formatter.parseDateTime("18960314", "yyyy-MM-dd");
Formatting and parsing numbers work in similar fashion.
Note: This class supports parsing BigDecimal values. To format a BigDecimal you can use a formatDecimal(...) method as both Double and BigDecimal are of type Number.
Warning: Never get one of the default formatters and update its configuration, unless you actually want to change the default behavior of this formatter for your entire application. If your decimal grouping size for example is 4 instead of 3, you can get the default decimal formatter and adjust the grouping size. But if you need this setting only in part of your application, you are better of, creating a fresh formatter using the FormatterFactory, apply settings to this fresh formatter and then use this formatter to format or parse your data.
Version:

2.0 $Revision: 6492 $

Author:

Kees Schotanus

See Also:

FormatterFactory, Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`KEY_BOOLEAN_FALSE` Key to the default date pattern in the resource bundle.
`static String`	`KEY_BOOLEAN_TRUE` Key to the default date pattern in the resource bundle.
`static String`	`MSG_DATE_INVALID` Key to lookup: Invalid date.
`static String`	`MSG_DATE_INVALID_WITH_PATTERN` Key to lookup: Invalid date.
`static String`	`MSG_DATE_INVALID_YEAR` Key to lookup: Invalid year.
`static String`	`MSG_DATE_TIME_INVALID` Key to lookup: Invalid date/time.
`static String`	`MSG_DATE_TIME_INVALID_WITH_PATTERN` Key to lookup: Invalid date/time.
`static String`	`MSG_DECIMAL_INVALID` Key to lookup: Invalid decimal number.
`static String`	`MSG_DECIMAL_INVALID_GROUPING` Key to lookup: Invalid decimal number due to invalid grouping.
`static String`	`MSG_INTEGER_INVALID` Key to lookup: Invalid integer number.
`static String`	`MSG_INTEGER_OUT_OF_RANGE` Key to lookup: Integer out of range.
`static String`	`MSG_LONG_INVALID` Key to lookup: Invalid long number.
`static String`	`MSG_LONG_OUT_OF_RANGE` Key to lookup: Long number out of range.
`static String`	`MSG_TIME_INVALID` Key to lookup: Invalid time.
`static String`	`MSG_TIME_INVALID_WITH_PATTERN` Key to lookup: Invalid time.

Constructor Summary

Constructors
Constructor and Description

Formatter(Locale locale)
Constructs a formatter using the supplied locale.

Constructors
Constructor and Description
`Formatter(Locale locale)` Constructs a formatter using the supplied locale.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static String`	`format(Locale locale, String messagePattern, Object... messageArguments)` Formats the supplied messagePattern with the optionally supplied messageArguments.
`static String`	`format(Object input)` Formats the supplied input object using the standard toString() method of the input object.
`static String`	`format(Object input, String defaultValue)` Formats the supplied input object using the standard toString() method of the input object.
`String`	`formatBoolean(Boolean value)` Formats the supplied Boolean value.
`String`	`formatDate(Date date)` Formats the supplied date using a cached formatter or in the absence of such a formatter with a newly created formatter that will be cached.
`String`	`formatDate(Date date, int style)` Formats the supplied date using the supplied style.
`String`	`formatDate(Date date, String pattern)` Formats the supplied date using the supplied pattern.
`String`	`formatDateTime(Date dateTime)` Formats the supplied dateTime using a cached formatter or in the absence of such a formatter with a newly created formatter that will be cached.
`String`	`formatDateTime(Date dateTime, int dateStyle, int timeStyle)` Formats the supplied dateTime using the supplied style.
`String`	`formatDateTime(Date dateTime, String pattern)` Formats the supplied dateTime using the supplied pattern.
`String`	`formatDecimal(Number number)` Formats the supplied decimal using a cached formatter or in the absence of such a formatter with a newly created formatter that will be cached.
`String`	`formatDecimal(Number number, int decimals)` Formats the supplied number using the supplied number of decimals.
`String`	`formatDecimal(Number number, String pattern)` Formats the supplied number using the supplied pattern.
`String`	`formatInteger(Number number)` Formats the supplied number using a cached formatter or in the absence of such a formatter with a newly created formatter that will be cached.
`String`	`formatInteger(Number number, String pattern)` Formats the supplied number using the supplied pattern.
`String`	`formatTime(Date time)` Formats the supplied time using a cached formatter or in the absence of such a formatter with a newly created formatter that will be cached.
`String`	`formatTime(Date time, int style)` Formats the supplied time using the supplied style.
`String`	`formatTime(Date time, String pattern)` Formats the supplied time using the supplied pattern.
`NumberFormat`	`getBigDecimalFormat()` Gets a formatter suitable for formatting BigDecimal numbers.
`DateFormat`	`getDateFormat()` Gets a formatter suitable for formatting `Dates`.
`DateFormat`	`getDateTimeFormat()` Gets a formatter suitable for formatting date/times.
`NumberFormat`	`getDecimalFormat()` Gets a formatter suitable for formatting decimal numbers.
`DecimalFormat`	`getIntegerFormat()` Gets a formatter suitable for formatting integer numbers.
`static String`	`getResourceBundleName()` Gets the name of the resource bundle that contains the localized descriptions for the messages.
`DateFormat`	`getShortDateFormat()` Gets a formatter suitable for formatting short `Dates`.
`DateFormat`	`getShortDateTimeFormat()` Gets a formatter suitable for formatting short date/times.
`DateFormat`	`getTimeFormat()` Gets a formatter suitable for formatting times.
`TimeZone`	`getTimeZone()` Gets the time zone.
`boolean`	`hasFourDigitYear()` Determines whether a parsed date, needs to have a year consisting of four digits.
`BigDecimal`	`parseBigDecimal(String bigDecimalNumber)` Parses a big decimal number that may not contain an exponent.
`BigDecimal`	`parseBigDecimal(String bigDecimalNumber, String pattern)` Parses a big decimal number using the supplied pattern.
`BigDecimal`	`parseBigDecimalAcceptingAnExponent(String bigDecimalNumber)` Parses a big decimal number that may include an exponent.
`Date`	`parseDate(String date)` Parses a date.
`Date`	`parseDate(String date, String pattern)` Parses a date using the supplied pattern.
`Date`	`parseDateTime(String dateTime)` Parses a date/time.
`Date`	`parseDateTime(String dateTime, String pattern)` Parses a date/time using the supplied pattern.
`Double`	`parseDecimal(String decimalNumber)` Parses a decimal number that may not contain an exponent.
`Double`	`parseDecimal(String decimalNumber, String pattern)` Parses a decimal number using the supplied pattern.
`Double`	`parseDecimalAcceptingAnExponent(String decimalNumber)` Parses a decimal number that may include an exponent.
`Integer`	`parseInteger(String integerNumber)` Parses an integer number.
`Long`	`parseLong(String longNumber)` Parses a long number.
`Date`	`parseTime(String time)` Parses a time.
`static String`	`removeSeparatorsFromDatePattern(String datePattern)` Removes all the separators from the supplied datePattern.
`void`	`setFourDigitYear(boolean fourDigitYear)` Forces a parsed date to have a year consisting of four digits or not.
`void`	`setTimeZone(String timeZone)` Sets the time zone.
`void`	`setTimeZone(TimeZone timeZone)` Sets the time zone.
`static void`	`validatePositionsOfGroupingSeparators(String decimalNumber, NumberFormat numberFormat)` Validates that if the supplied decimalNumber contains grouping separators, they appear at the proper positions.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - KEY_BOOLEAN_TRUE
```
public static final String KEY_BOOLEAN_TRUE
```
    Key to the default date pattern in the resource bundle.
    
    See Also:
    
    Constant Field Values
  - KEY_BOOLEAN_FALSE
```
public static final String KEY_BOOLEAN_FALSE
```
    Key to the default date pattern in the resource bundle.
    
    See Also:
    
    Constant Field Values
  - MSG_DATE_INVALID
```
public static final String MSG_DATE_INVALID
```
    Key to lookup: Invalid date.
    Arguments:
    - 0 = date
    See Also:
    
    Constant Field Values
  - MSG_DATE_INVALID_WITH_PATTERN
```
public static final String MSG_DATE_INVALID_WITH_PATTERN
```
    Key to lookup: Invalid date.
    Arguments:
    - 0 = date
    - 1 = valid date pattern
    See Also:
    
    Constant Field Values
  - MSG_DATE_TIME_INVALID
```
public static final String MSG_DATE_TIME_INVALID
```
    Key to lookup: Invalid date/time.
    Arguments:
    - 0 = date/time
    See Also:
    
    Constant Field Values
  - MSG_DATE_TIME_INVALID_WITH_PATTERN
```
public static final String MSG_DATE_TIME_INVALID_WITH_PATTERN
```
    Key to lookup: Invalid date/time.
    Arguments:
    - 0 = date/time
    - 1 = valid date/time pattern
    See Also:
    
    Constant Field Values
  - MSG_DATE_INVALID_YEAR
```
public static final String MSG_DATE_INVALID_YEAR
```
    Key to lookup: Invalid year.
    Arguments:
    - 0 = input date/time
    - 1 = parsed year
    See Also:
    
    Constant Field Values
  - MSG_DECIMAL_INVALID
```
public static final String MSG_DECIMAL_INVALID
```
    Key to lookup: Invalid decimal number.
    Arguments:
    - 0 = decimal number
    See Also:
    
    Constant Field Values
  - MSG_DECIMAL_INVALID_GROUPING
```
public static final String MSG_DECIMAL_INVALID_GROUPING
```
    Key to lookup: Invalid decimal number due to invalid grouping.
    Arguments:
    - 0 = decimal number
    See Also:
    
    Constant Field Values
  - MSG_INTEGER_INVALID
```
public static final String MSG_INTEGER_INVALID
```
    Key to lookup: Invalid integer number.
    Arguments:
    - 0 = integer number
    See Also:
    
    Constant Field Values
  - MSG_INTEGER_OUT_OF_RANGE
```
public static final String MSG_INTEGER_OUT_OF_RANGE
```
    Key to lookup: Integer out of range.
    Arguments:
    - 0 = integer number
    See Also:
    
    Constant Field Values
  - MSG_LONG_INVALID
```
public static final String MSG_LONG_INVALID
```
    Key to lookup: Invalid long number.
    Arguments:
    - 0 = long number
    See Also:
    
    Constant Field Values
  - MSG_LONG_OUT_OF_RANGE
```
public static final String MSG_LONG_OUT_OF_RANGE
```
    Key to lookup: Long number out of range.
    Arguments:
    - 0 = long number
    See Also:
    
    Constant Field Values
  - MSG_TIME_INVALID
```
public static final String MSG_TIME_INVALID
```
    Key to lookup: Invalid time.
    Arguments:
    - 0 = time
    See Also:
    
    Constant Field Values
  - MSG_TIME_INVALID_WITH_PATTERN
```
public static final String MSG_TIME_INVALID_WITH_PATTERN
```
    Key to lookup: Invalid time.
    Arguments:
    - 0 = time
    - 1 = valid time pattern
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Formatter
```
public Formatter(Locale locale)
```
    Constructs a formatter using the supplied locale.
    
    Parameters:
    
    locale - Locale to be used for this formatter.
    
    Throws:
    
    NullPointerException - When the supplied locale is null.
- Method Detail
  - hasFourDigitYear
```
public boolean hasFourDigitYear()
```
    Determines whether a parsed date, needs to have a year consisting of four digits.
    
    Returns:
    
    True for a four digit year, otherwise false.
  - setFourDigitYear
```
public void setFourDigitYear(boolean fourDigitYear)
```
    Forces a parsed date to have a year consisting of four digits or not.
    
    Parameters:
    
    fourDigitYear - True for a four digit year, false to accept years of other lengths.
  - formatBoolean
```
public String formatBoolean(Boolean value)
```
    Formats the supplied Boolean value.
    
    Parameters:
    
    value - Boolean value to format.
    
    Returns:
    
    Formatted boolean or an empty String when the supplied value is null.
  - formatDate
```
public String formatDate(Date date)
```
    Formats the supplied date using a cached formatter or in the absence of such a formatter with a newly created formatter that will be cached.
    
    Parameters:
    
    date - Date to format.
    
    Returns:
    
    Formatted date or an empty String when the supplied date is null.
    
    See Also:
    
    getDateFormat()
  - formatDate
```
public String formatDate(Date date,
                         int style)
```
    Formats the supplied date using the supplied style.
    A new formatter is created upon every call.
    
    Parameters:
    
    date - Date to format.
    
    style - Style to apply to the output.
    For valid styles see: SimpleDateFormat.
    
    Returns:
    
    Formatted date or an empty String when the supplied date is null.
    
    Throws:
    
    IllegalArgumentException - When no valid date style is supplied.
  - formatDate
```
public String formatDate(Date date,
                         String pattern)
```
    Formats the supplied date using the supplied pattern.
    A new formatter is created upon every call.
    
    Parameters:
    
    date - Date to format.
    
    pattern - Date pattern.
    For valid patterns see: SimpleDateFormat.
    
    Returns:
    
    Formatted date or an empty String when the supplied date is null.
    
    Throws:
    
    IllegalArgumentException - When the supplied pattern is empty or contains illegal data (does not form a valid pattern).
    
    NullPointerException - When the supplied pattern is null.
  - getDateFormat
```
public DateFormat getDateFormat()
```
    Gets a formatter suitable for formatting Dates.
    A previously created formatter will be reused. In the absence of such a formatter, a new formatter will be created and cached.
    
    Returns:
    
    DateFormat object suitable for formatting Dates.
    
    See Also:
    
    FormatterFactory.createDefaultDateFormat(Locale)
  - getShortDateFormat
```
public DateFormat getShortDateFormat()
```
    Gets a formatter suitable for formatting short Dates.
    A previously created formatter will be reused. In the absence of such a formatter, a new formatter will be created and cached.
    
    Returns:
    
    DateFormat object suitable for formatting short dates.
    
    See Also:
    
    FormatterFactory.createDefaultShortDateFormat(Locale)
  - parseDate
```
public Date parseDate(String date)
               throws InvalidArgumentException
```
    Parses a date.
    This method tries to parse a date with both the default date and the default short date. In contrast to Sun's implementation, this method will not allow illegal characters in a date. For example: "12/12/200-" would result in the year 200 when parsed by Sun, but this method refuses it as input.
    Note: By default this method only accepts 4 digit years. To change this behavior, call @{link setFourDigitYear(boolean).
    
    Parameters:
    
    date - Date to parse.
    
    Returns:
    
    Date created from parsed date or null when the supplied date is empty when trimmed or when the supplied date is null.
    Note: The returned date is a Date since this type is most often used in database applications.
    
    Throws:
    
    InvalidArgumentException - When the supplied date does not represent a valid date.
  - parseDate
```
public Date parseDate(String date,
                      String pattern)
               throws InvalidArgumentException
```
    Parses a date using the supplied pattern.
    This method tries to parse a date with the supplied pattern. If this fails a short date pattern is used to parse the supplied date.
    In contrast to Sun's implementation, this method will not allow illegal characters in a date. For example: "12/12/2000x" would result in 12/12/2000 when parsed by Sun, but this method simply refuses it as valid input.
    Note: A new formatter is created upon every call.
    Note: By default this method only accepts 4 digit years. To change this behavior, call @{link setFourDigitYear(boolean).
    
    Parameters:
    
    date - The date to parse.
    
    pattern - The date pattern to use for parsing the supplied date.
    This pattern may either be a localized or non localized pattern.
    
    Returns:
    
    Date created from parsed date or null when the supplied dateTime is empty when trimmed or when the supplied date is null.
    Note: The returned date is a Date since this type is most often used in database applications.
    
    Throws:
    
    InvalidArgumentException - When the supplied date does not represent a valid date or when the supplied pattern is empty.
  - formatDateTime
```
public String formatDateTime(Date dateTime)
```
    Formats the supplied dateTime using a cached formatter or in the absence of such a formatter with a newly created formatter that will be cached.
    
    Parameters:
    
    dateTime - Date containing both date and time information to format.
    
    Returns:
    
    Formatted date/time or an empty String when the supplied dateTime is null.
    
    See Also:
    
    getDateTimeFormat()
  - formatDateTime
```
public String formatDateTime(Date dateTime,
                             int dateStyle,
                             int timeStyle)
```
    Formats the supplied dateTime using the supplied style.
    A new formatter is created upon every call.
    
    Parameters:
    
    dateTime - Date containing both date and time information to format.
    
    dateStyle - Date style to apply to the output.
    For valid styles see: SimpleDateFormat.
    
    timeStyle - Time style to apply to the output.
    For valid styles see: SimpleDateFormat.
    
    Returns:
    
    Formatted date/time or an empty String when the supplied dateTime is null.
    
    Throws:
    
    IllegalArgumentException - When no valid date/time style is supplied.
  - formatDateTime
```
public String formatDateTime(Date dateTime,
                             String pattern)
```
    Formats the supplied dateTime using the supplied pattern.
    A new formatter is created upon every call.
    
    Parameters:
    
    dateTime - Date containing both date and time information to format.
    
    pattern - Date/Time pattern.
    For valid patterns see: SimpleDateFormat.
    
    Returns:
    
    Formatted date/time or an empty String when the supplied dateTime is null.
    
    Throws:
    
    IllegalArgumentException - When the supplied pattern is empty or contains illegal data (does not form a valid pattern).
    
    NullPointerException - When the supplied pattern is null.
  - getDateTimeFormat
```
public DateFormat getDateTimeFormat()
```
    Gets a formatter suitable for formatting date/times.
    A previously created formatter will be reused. In the absence of such a formatter, a new formatter will be created and cached.
    
    Returns:
    
    DateFormat object suitable for formatting date/times.
    
    See Also:
    
    FormatterFactory.createDefaultDateTimeFormat(Locale, TimeZone)
  - getShortDateTimeFormat
```
public DateFormat getShortDateTimeFormat()
```
    Gets a formatter suitable for formatting short date/times.
    A previously created formatter will be reused. In the absence of such a formatter, a new formatter will be created and cached.
    
    Returns:
    
    DateFormat object suitable for formatting short date/times.
    
    See Also:
    
    FormatterFactory.createDefaultShortDateTimeFormat(Locale, TimeZone)
  - parseDateTime
```
public Date parseDateTime(String dateTime)
                   throws InvalidArgumentException
```
    Parses a date/time.
    This method tries to parse a date/time with both the default date/time and the default short date/time. It will even accept a date/time without the time information. Using 00:00 as a default.
    In contrast to Sun's implementation, this method will not allow illegal characters in a date/time. For example: "12/12/2009- 12:1-" would result in 12/12/2009 12:01 when parsed by Sun, but this method refuses it as input.
    Note: By default this method only accepts 4 digit years. To change this behavior, call @{link setFourDigitYear(boolean).
    
    Parameters:
    
    dateTime - Date containing date/time information to parse.
    
    Returns:
    
    Date created from parsed dateTime or null when the supplied date/time is empty when trimmed or when the supplied dateTime is null.
    Note: The returned date is a Date since this type is most often used in database applications.
    
    Throws:
    
    InvalidArgumentException - When the supplied dateTime does not represent a valid date/time.
  - parseDateTime
```
public Date parseDateTime(String dateTime,
                          String pattern)
                   throws InvalidArgumentException
```
    Parses a date/time using the supplied pattern.
    This method tries to parse a date/time with the supplied pattern. If this fails a short date/time pattern is used to parse the supplied dateTime. If this fails as well, this method will try to parse the supplied dateTime as a date, without the time information. Using 00:00 as a default.
    In contrast to Sun's implementation, this method will not allow illegal characters in a date/time. For example: "12/12/2009- 12:1-" would result in 12/12/2009 12:01 when parsed by Sun, but this method simply refuses it as valid input.
    Note: A new formatter is created upon every call.
    Note: By default this method only accepts 4 digit years. To change this behavior, call @{link setFourDigitYear(boolean).
    
    Parameters:
    
    dateTime - Date containing date/time information to parse.
    
    pattern - The date/time pattern to use for parsing the supplied dateTime.
    This pattern may either be a localized or non localized pattern.
    
    Returns:
    
    Date created from parsed dateTime or null when the supplied dateTime is empty when trimmed or when the supplied dateTime is null.
    Note: The returned date is a Date since this type is most often used in database applications.
    
    Throws:
    
    InvalidArgumentException - When the supplied dateTime does not represent a valid date/time or when the supplied pattern is empty.
  - formatDecimal
```
public String formatDecimal(Number number)
```
    Formats the supplied decimal using a cached formatter or in the absence of such a formatter with a newly created formatter that will be cached.
    
    Parameters:
    
    number - Number to format.
    
    Returns:
    
    Formatted decimal number or an empty String when the supplied number is null.
    
    See Also:
    
    getDecimalFormat()
  - formatDecimal
```
public String formatDecimal(Number number,
                            String pattern)
```
    Formats the supplied number using the supplied pattern.
    A new formatter is created upon every call.
    In contrast with Sun's default decimal formatting, this instance uses RoundingMode.HALF_UP rounding.
    
    Parameters:
    
    number - Number to format.
    
    pattern - Number pattern.
    For valid patterns see: DecimalFormat.
    
    Returns:
    
    Formatted decimal number or an empty String when the supplied number is null.
    
    Throws:
    
    IllegalArgumentException - When the supplied pattern is empty or contains illegal data (does not form a valid pattern).
    
    NullPointerException - When the supplied pattern is null.
  - formatDecimal
```
public String formatDecimal(Number number,
                            int decimals)
```
    Formats the supplied number using the supplied number of decimals.
    A new formatter is created upon every call.
    In contrast with Sun's default decimal formatting, this instance uses RoundingMode.HALF_UP rounding.
    
    Parameters:
    
    number - Number to format.
    
    decimals - Number of decimals to show in the formatted result.
    
    Returns:
    
    Formatted decimal number or an empty String when the supplied number is null.
  - getDecimalFormat
```
public NumberFormat getDecimalFormat()
```
    Gets a formatter suitable for formatting decimal numbers.
    A previously created formatter will be reused. In the absence of such a formatter, a new formatter will be created and cached.
    In contrast with Sun's default decimal formatting, this instance uses RoundingMode.HALF_UP rounding.
    
    Returns:
    
    NumberFormat object suitable for formatting decimal numbers.
    
    See Also:
    
    FormatterFactory.createDefaultDecimalFormat(Locale)
  - parseDecimal
```
public Double parseDecimal(String decimalNumber)
                    throws InvalidArgumentException
```
    Parses a decimal number that may not contain an exponent.
    Note: Sun's implementation will gladly accept a String like "5.3K" and will return the value 5.3. This method however will throw an exception when "5.3K" is passed as a parameter. Additionally a number like "1,1" is also accepted by Sun's implementation and returns a value of "11". Again: this method will throw an InvalidArgumentException in this case.
    This method does not accept "2E6" as valid input since it could be that the user meant to type 236 for example.
    
    Parameters:
    
    decimalNumber - The decimal number to parse.
    
    Returns:
    
    Double created from parsed decimalNumber or null when the supplied decimalNumber is empty when trimmed or when the decimalNumber is null.
    
    Throws:
    
    InvalidArgumentException - When the supplied decimalNumber does not represent a valid decimal number.
    This includes the case where the input contains the exponent symbol 'E'.
    
    See Also:
    
    parseDecimalAcceptingAnExponent(String)
  - parseDecimal
```
public Double parseDecimal(String decimalNumber,
                           String pattern)
                    throws InvalidArgumentException
```
    Parses a decimal number using the supplied pattern.
    Note: This method will accept an exponent in the supplied decimalNumber, whether the pattern contains an exponent or not. It will also happily parse the value "123" when the pattern is just a single "#". Grouping symbols however are properly handled. You can't for example parse the value "1.234.567,89" with this pattern that is lacking grouping symbols.
    
    Parameters:
    
    decimalNumber - The decimal number to parse.
    
    pattern - The pattern to parse the supplied decimalNumber.
    The pattern should always be the US pattern.
    
    Returns:
    
    Double created from parsed decimalNumber or null when the supplied decimalNumber is empty when trimmed or when the decimalNumber is null.
    
    Throws:
    
    InvalidArgumentException - When the supplied decimalNumber does not represent a valid decimal number.
  - parseDecimalAcceptingAnExponent
```
public Double parseDecimalAcceptingAnExponent(String decimalNumber)
                                       throws InvalidArgumentException
```
    Parses a decimal number that may include an exponent.
    Note: Sun's implementation will gladly accept a String like "5.3K" and will return the value 5.3. This method however will throw an exception when "5.3K" is passed as a parameter. Additionally a number like "1,1" is also accepted and returns a value of "11". Again: this method will throw an InvalidArgumentException in this case.
    
    Parameters:
    
    decimalNumber - The decimal number to parse.
    
    Returns:
    
    Double created from parsed decimalNumber or null when the supplied decimalNumber is empty when trimmed or when the decimalNumber is null.
    
    Throws:
    
    InvalidArgumentException - When the supplied decimalNumber does not represent a valid decimal number.
  - getBigDecimalFormat
```
public NumberFormat getBigDecimalFormat()
```
    Gets a formatter suitable for formatting BigDecimal numbers.
    A previously created formatter will be reused. In the absence of such a formatter, a new formatter will be created and cached.
    In contrast with Sun's default decimal formatting, this instance uses RoundingMode.HALF_UP rounding.
    
    Returns:
    
    NumberFormat object suitable for formatting BigDecimal numbers.
    
    See Also:
    
    FormatterFactory.createDefaultBigDecimalFormat(Locale)
  - parseBigDecimal
```
public BigDecimal parseBigDecimal(String bigDecimalNumber)
                           throws InvalidArgumentException
```
    Parses a big decimal number that may not contain an exponent.
    Note: Sun's implementation will gladly accept a String like "5.3K" and will return the value 5.3. This method however will throw an exception when "5.3K" is passed as a parameter. Additionally a number like "1,1" is also accepted by Sun's implementation and returns a value of "11". Again: this method will throw an InvalidArgumentException in this case.
    This method does not accept "2E6" as valid input since it could be that the user meant to type 236 for example.
    
    Parameters:
    
    bigDecimalNumber - The big decimal number to parse.
    
    Returns:
    
    BigDecimal created from parsed bigDecimalNumber or null when the supplied bigDecimalNumber is empty when trimmed or when the bigDecimalNumber is null.
    
    Throws:
    
    InvalidArgumentException - When the supplied bigDecimalNumber does not represent a valid decimal number.
    This includes the case where the input contains the exponent symbol 'E'.
    
    See Also:
    
    parseBigDecimalAcceptingAnExponent(String)
  - parseBigDecimal
```
public BigDecimal parseBigDecimal(String bigDecimalNumber,
                                  String pattern)
                           throws InvalidArgumentException
```
    Parses a big decimal number using the supplied pattern.
    Note: This method will accept an exponent in the supplied decimalNumber, whether the pattern contains an exponent or not. It will also happily parse the value "123" when the pattern is just a single "#".
    
    Parameters:
    
    bigDecimalNumber - The big decimal number to parse.
    
    pattern - The pattern to parse the supplied bigDecimalNumber.
    The pattern should always use the standard US pattern symbols like a decimal point for example.
    
    Returns:
    
    BigDecimal created from the parsed bigDcimalNumber or null when the supplied bigDecimalNumber is empty when trimmed or when the bigDecimalNumber is null.
    
    Throws:
    
    InvalidArgumentException - When the supplied bigDecimalNumber does not represent a valid big decimal number.
  - parseBigDecimalAcceptingAnExponent
```
public BigDecimal parseBigDecimalAcceptingAnExponent(String bigDecimalNumber)
                                              throws InvalidArgumentException
```
    Parses a big decimal number that may include an exponent.
    Note: Sun's implementation will gladly accept a String like "5.3K" and will return the value 5.3. This method however will throw an exception when "5.3K" is passed as a parameter. Additionally a number like "1,1" is also accepted and returns a value of "11". Again: this method will throw an InvalidArgumentException in this case.
    
    Parameters:
    
    bigDecimalNumber - The big decimal number to parse.
    
    Returns:
    
    BigDecimal created from parsed bigDecimalNumber or null when the supplied bigDecimalNumber is empty when trimmed or when the bigDecimalNumber is null.
    
    Throws:
    
    InvalidArgumentException - When the supplied decimalNumber does not represent a valid decimal number.
  - validatePositionsOfGroupingSeparators
```
public static void validatePositionsOfGroupingSeparators(String decimalNumber,
                                                         NumberFormat numberFormat)
                                                  throws InvalidArgumentException
```
    Validates that if the supplied decimalNumber contains grouping separators, they appear at the proper positions.
    By default, grouping separators are allowed at every 4th position (counted from the right), provided the grouping size = 3 and you only consider the integer part of the decimal number.. For example "12,345,678.1" has an integer part equal to "12,345,678" and the comma's occur at every 4th position.
    Limitation: This code does NOT take the pattern into account, only the grouping in the supplied decimalNumber.
    
    Parameters:
    
    decimalNumber - The decimal number to validate.
    The decimalNumber should already have been parsed successfully since this method only checks grouping separators, not the occurrence of multiple decimal separators for example.
    
    numberFormat - The NumberFormat object used to parse the supplied decimalNumber.
    As noted the decimalNumber must have been parsed with the supplied numberFormat.
    
    Throws:
    
    InvalidArgumentException - When the supplied decimalNumber contains grouping characters at incorrect positions.
  - formatInteger
```
public String formatInteger(Number number)
```
    Formats the supplied number using a cached formatter or in the absence of such a formatter with a newly created formatter that will be cached.
    
    Parameters:
    
    number - Number to format.
    
    Returns:
    
    Formatted integer number or an empty String when the supplied number is null.
    
    See Also:
    
    getIntegerFormat()
  - formatInteger
```
public String formatInteger(Number number,
                            String pattern)
```
    Formats the supplied number using the supplied pattern.
    Normal rounding is performed when necessary.
    A new formatter is created upon every call.
    
    Parameters:
    
    number - Number to format.
    
    pattern - Number pattern.
    For valid patterns see: DecimalFormat.
    
    Returns:
    
    Formatted integer number or an empty String when the supplied number is null.
    
    Throws:
    
    IllegalArgumentException - When the supplied pattern is empty or contains illegal data, (does not form a valid pattern).
    
    NullPointerException - When the supplied pattern is null.
  - getIntegerFormat
```
public DecimalFormat getIntegerFormat()
```
    Gets a formatter suitable for formatting integer numbers.
    A previously created formatter will be reused. In the absence of such a formatter, a new formatter will be created and cached.
    
    Returns:
    
    NumberFormat object suitable for formatting an integer number.
    
    See Also:
    
    FormatterFactory.createDefaultIntegerFormat(Locale)
  - parseInteger
```
public Integer parseInteger(String integerNumber)
                     throws InvalidArgumentException
```
    Parses an integer number.
    Note: Sun's implementation will gladly accept a String like "5K" and will return the value 5. This method however will throw an exception when "5K" is passed as a parameter.
    
    Parameters:
    
    integerNumber - The integer number to parse.
    
    Returns:
    
    Integer created from parsed integerNumber or null when the supplied integerNumber is empty when trimmed or when the supplied integerNumber is null.
    
    Throws:
    
    InvalidArgumentException - When the supplied integerNumber does not represent a valid integer number.
  - parseLong
```
public Long parseLong(String longNumber)
               throws InvalidArgumentException
```
    Parses a long number.
    Note: Sun's implementation will gladly accept a String like "5K" and will return the value 5. This method however will throw an exception when "5K" is passed as a parameter.
    
    Parameters:
    
    longNumber - The long number to parse.
    
    Returns:
    
    Long created from parsed integerNumber or null when the supplied longNumber is empty when trimmed or when the supplied longNumber is null.
    
    Throws:
    
    InvalidArgumentException - When the supplied longNumber does not represent a valid long number.
  - formatTime
```
public String formatTime(Date time)
```
    Formats the supplied time using a cached formatter or in the absence of such a formatter with a newly created formatter that will be cached.
    
    Parameters:
    
    time - Date containing time information to format.
    
    Returns:
    
    Formatted time or an empty String when the supplied time is null.
    
    See Also:
    
    getTimeFormat()
  - formatTime
```
public String formatTime(Date time,
                         int style)
```
    Formats the supplied time using the supplied style.
    A new formatter is created upon every call.
    
    Parameters:
    
    time - Date containing time information to format.
    
    style - Style to apply to the output.
    For valid styles see: SimpleDateFormat.
    
    Returns:
    
    Formatted time or an empty String when the supplied time is null.
    
    Throws:
    
    IllegalArgumentException - When no valid time style is supplied.
  - formatTime
```
public String formatTime(Date time,
                         String pattern)
```
    Formats the supplied time using the supplied pattern.
    A new formatter is created upon every call.
    
    Parameters:
    
    time - Date containing time information to format.
    
    pattern - Time pattern.
    For valid patterns see: SimpleDateFormat.
    
    Returns:
    
    Formatted time or an empty String when the supplied time is null.
    
    Throws:
    
    IllegalArgumentException - When the supplied pattern is empty or contains illegal data (does not form a valid pattern).
    
    NullPointerException - When the supplied pattern is null.
  - getTimeFormat
```
public DateFormat getTimeFormat()
```
    Gets a formatter suitable for formatting times.
    A previously created formatter will be reused. In the absence of such a formatter, a new formatter will be created and cached.
    
    Returns:
    
    DateFormat object suitable for formatting times.
    
    See Also:
    
    FormatterFactory.createDefaultTimeFormat(Locale)
  - parseTime
```
public Date parseTime(String time)
               throws InvalidArgumentException
```
    Parses a time.
    In contrast to Sun's implementation, this method will not allow illegal characters in a time. For example: "12:1-" would result in the time 12:01 when parsed by Sun, but this method refuses "12:1-" as input.
    
    Parameters:
    
    time - Date containing time information to parse.
    
    Returns:
    
    Date created from parsed time or null when the supplied time is empty when trimmed or when the supplied time is null.
    Note: The returned date is a Date since this type is most often used in database applications.
    
    Throws:
    
    InvalidArgumentException - When the supplied time does not represent a valid time.
  - format
```
public static String format(Object input)
```
    Formats the supplied input object using the standard toString() method of the input object.
    
    Parameters:
    
    input - Input object to format.
    
    Returns:
    
    String representation of the supplied object or an empty String when the supplied input object is null.
  - format
```
public static String format(Object input,
                            String defaultValue)
```
    Formats the supplied input object using the standard toString() method of the input object.
    
    Parameters:
    
    input - Input object to format.
    
    defaultValue - Default value to use when the supplied input object is null.
    
    Returns:
    
    String representation of the supplied object or the supplied defaultValue when the supplied input object is null.
  - format
```
public static String format(Locale locale,
                            String messagePattern,
                            Object... messageArguments)
```
    Formats the supplied messagePattern with the optionally supplied messageArguments.
    
    Parameters:
    
    locale - The locale to format the message.
    When null, the default locale is used.
    
    messagePattern - The message pattern.
    For example: Processing record {0} of {1}.
    
    messageArguments - The arguments that must be inserted into the supplied messagePattern.
    Message arguments may contain objects of type Localizable that will be localized before being inserted into the supplied messagePattern.
    
    Returns:
    
    The localized message or simply the supplied messagePattern when no messageArguments have been supplied.
    
    Throws:
    
    IllegalArgumentException - When the supplied messagePattern is empty or is not valid for the supplied messagePattern.
    
    NullPointerException - When the supplied messagePattern is null.
  - removeSeparatorsFromDatePattern
```
public static String removeSeparatorsFromDatePattern(String datePattern)
```
    Removes all the separators from the supplied datePattern.
    When the datePattern for example is: "MM/dd/yyyy", this method will return MMddyyyy. When the supplied datePattern does not contain separators, the datePattern will be returned as-is.
    Note: This method assumes that separators are non alphabetic.
    
    Parameters:
    
    datePattern - The date pattern to remove separators from.
    See: SimpleDateFormat for examples of valid patterns.
    
    Returns:
    
    The supplied datePattern without separators or the supplied datePattern when the datePattern does not contain any separators.
    
    Throws:
    
    NullPointerException - When the supplied datePattern is null.
  - getResourceBundleName
```
public static String getResourceBundleName()
```
    Gets the name of the resource bundle that contains the localized descriptions for the messages.
    
    Returns:
    
    The name of the resource bundle.
  - getTimeZone
```
public TimeZone getTimeZone()
```
    Gets the time zone.
    
    Returns:
    
    The tie zone.
  - setTimeZone
```
public void setTimeZone(String timeZone)
```
    Sets the time zone.
    The set time zone will be used to format and parse date/time objects.
    
    Parameters:
    
    timeZone - The time zone to set.
    Note: When the supplied timeZone is invalid, the GMT zone will be used.
    
    See Also:
    
    TimeZone.getTimeZone(String)
  - setTimeZone
```
public void setTimeZone(TimeZone timeZone)
```
    Sets the time zone.
    The set time zone will be used to format and parse date/time objects.
    
    Parameters:
    
    timeZone - The time zone to set.
    When null, the default time zone (of the server) will be used.

Class Formatter

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

KEY_BOOLEAN_TRUE

KEY_BOOLEAN_FALSE

MSG_DATE_INVALID

MSG_DATE_INVALID_WITH_PATTERN

MSG_DATE_TIME_INVALID

MSG_DATE_TIME_INVALID_WITH_PATTERN

MSG_DATE_INVALID_YEAR

MSG_DECIMAL_INVALID

MSG_DECIMAL_INVALID_GROUPING

MSG_INTEGER_INVALID

MSG_INTEGER_OUT_OF_RANGE

MSG_LONG_INVALID

MSG_LONG_OUT_OF_RANGE

MSG_TIME_INVALID

MSG_TIME_INVALID_WITH_PATTERN

Constructor Detail

Formatter

Method Detail

hasFourDigitYear

setFourDigitYear

formatBoolean

formatDate

formatDate

formatDate

getDateFormat

getShortDateFormat

parseDate

parseDate

formatDateTime

formatDateTime

formatDateTime

getDateTimeFormat

getShortDateTimeFormat

parseDateTime

parseDateTime

formatDecimal

formatDecimal

formatDecimal

getDecimalFormat

parseDecimal

parseDecimal

parseDecimalAcceptingAnExponent

getBigDecimalFormat

parseBigDecimal

parseBigDecimal

parseBigDecimalAcceptingAnExponent

validatePositionsOfGroupingSeparators

formatInteger

formatInteger

getIntegerFormat

parseInteger

parseLong

formatTime

formatTime

formatTime

getTimeFormat

parseTime

format

format

format

removeSeparatorsFromDatePattern

getResourceBundleName

getTimeZone

setTimeZone

setTimeZone