com.ccg.text
Class Formats

java.lang.Object
  com.ccg.text.Formats

public class Formats
extends Object

Repository of Format objects to aid a application in providing consistent text input/output.

The java.text package is very handy in creating specialized parsing/formatting objects. Unfortunately, during development, one often finds themselves repeatedly building and constructing these format objects within their application. It can become quite frustrating trying to maintain some consistency. This class provides a mechanism to create and/or share common formats to aid the application developer in maintaining consistency throughout their application.

The easiest way to make use of this class is to use the singleton available via the getInstance method.

Since:

1.0

Version:

$Revision: 1.1 $

Author:

$Author: pkb $

Field Summary

static int

NONE A constant value which is different from the SHORT, MEDIUM, LONG, and FULL constants defined in the DateFormat class.

Constructor Summary

Formats()
Fully constructions and intializes the object.

Method Summary

static DateFormat	createDateFormat(Lookup l) Creates a DateFormat object based upon values in a Lookup object.
static NumberFormat	createDecimalFormat(int fdigits) Create a standard NumberFormat which displays real numbers with a fixed number of digits after the decimal point.
static NumberFormat	createIntegerFormat() Create a standard NumberFormat suitable for integer values.
static NumberFormat	createNumberFormat(Lookup l) Creates a NumberFormat object based upon values in a Lookup object.
static int	getDateFormatConstant(String s) Converts a string value into one of the standard DateFormat integer constants or NONE.
static Formats	getInstance() Get the shared global instance of a Formats object.
NumberFormat	getInteger() Get the NumberFormat to format suitable for working with integers.
DateFormat	getToDay() Get the DateFormat to format a date to day precision.
DateFormat	getToMilli() Get the DateFormat to format a date to millisecond precision.
DateFormat	getToMinute() Get the DateFormat to format a date to minute precision.
DateFormat	getToSecond() Get the DateFormat to format a date to second precision.
(package private) void	loadConfig(String name)
protected static void	setInstance(Formats val) Set the shared global instance of a Formats object.
protected void	setInteger(NumberFormat val) Set the NumberFormat to be used for integer values.
protected void	setToDay(DateFormat val) Set the DateFormat to format a date to day precision.
protected void	setToMilli(DateFormat val) Set the DateFormat to format a date to millisecond precision.
protected void	setToMinute(DateFormat val) Set the DateFormat to format a date to minute precision.
protected void	setToSecond(DateFormat val) Set the DateFormat to format a date to second precision.

Methods inherited from class java.lang.Object

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

Field Detail

NONE

public static final int NONE

A constant value which is different from the SHORT, MEDIUM, LONG, and FULL constants defined in the DateFormat class.

Since:

1.0

See Also:

getDateFormatConstant(java.lang.String), Constant Field Values

Constructor Detail

Formats

public Formats()

Fully constructions and intializes the object.

This method fully constructs and initializes the object. It will honor any of the overrides found in the $HOME/.etc/com/ccg/text/default.Formats file - if found.

NOTE: This is a fairly expensive constructor - a configuration file is loaded and many formats are created. It is recommended that one hangs onto a common reference, or uses the getInstance method to share the "global" settings.

Since:

1.0

Method Detail

getDateFormatConstant

public static int getDateFormatConstant(String s)

Converts a string value into one of the standard DateFormat integer constants or NONE.

This method attempts to translate a string value (case doesn't matter) into one of the constants defined in the DateFormat class. Any of the following may be returned:

DateFormat.SHORT

This is returned if the string passed starts with the letter "s" (for example: "Short", "short" or "s").

DateFormat.MEDIUM

This is returned if the string passed starts with the letter "m" (for example: "Medium", "MEDIUM" or "m").

DateFormat.LONG

This is returned if the string passed starts with the letter "l" (for example: "long", "LoNg" or "L").

DateFormat.FULL

This is returned if the string passed starts with the letter "f" (for example: "Full", "full" or "f").

Formats.NONE

This is returned in all other cases (string passed is null, zero length or doesn't meet any of the rules outlined above).

Parameters:

s - String to convert (you can pass null).

Returns:

One of the constant values described above.

Since:

1.0

createDateFormat

public static DateFormat createDateFormat(Lookup l)
                                   throws IllegalArgumentException,
                                          ParseException

Creates a DateFormat object based upon values in a Lookup object.

This method looks for values to specific keys in the Lookup object passed to form a DateFormat object. At a minimum, at least one of the following keys MUST have a value set: "date", "time", "template".

The following keys are supported:

template=yyyy-MMM-dd HH:mm:ss.SSS

This option allows one to specify the date format via a "template". See the SimpleDateFormat documentation for full details on how to form the template string. If this value is set, then the "date"/"time" keys are ignored.

date=short|medium|long|full

This option allows one to indicate how much date information is required in the format. The valid values correspond to the SHORT, MEDIUM, LONG, and FULL constants defined in the DateFormat class. This setting is ignored if the template=TEXT setting is present. If this setting is omitted, or incorrectly set, then date information is omitted from the output format.

time=short|medium|long|full

This option allows one to indicate how much time information is required in the format. The valid values correspond to the SHORT, MEDIUM, LONG, and FULL constants defined in the DateFormat class. This setting is ignored if the template=TEXT setting is present. If this setting is omitted, or incorrectly set, then time information is omitted from the output format.

tz=NAME

You can specify a time zone if you don't want the system default (typically omitted).

lenient=true|false

You can set this value to true if you want strict parsing rules (if you'll be using the format object to parse input strings). If false, omitted or invalid, then lenient rules will be enforced.

Parameters:

props - Properties to get the information from (as described above)

Returns:

New DateFormat object which was created - never returns null.

Throws:

IllegalArgumentException - If the properties passed were invalid (no template, date or time set).

ParseException - If a unrecoverable error was found trying to parse one of the values.

Since:

1.0

createIntegerFormat

public static NumberFormat createIntegerFormat()

Create a standard NumberFormat suitable for integer values.

Returns:

A generic (system default) NumberFormat suitable for working with integer values.

Since:

1.0

createDecimalFormat

public static NumberFormat createDecimalFormat(int fdigits)

Create a standard NumberFormat which displays real numbers with a fixed number of digits after the decimal point.

Parameters:

fdigits - Number of fractional digits to be displayed.

Returns:

A appropriate NumberFormat.

Since:

1.0

createNumberFormat

public static NumberFormat createNumberFormat(Lookup l)
                                       throws IllegalArgumentException,
                                              ParseException

Creates a NumberFormat object based upon values in a Lookup object.

This method looks for values to specific keys in the Lookup object passed to form a NumberFormat object. At a minimum, at least one of the following keys MUST have a value set: "type" or "template".

The following keys are supported:

template=TEXT

This option allows one to specify the date format via a "template". See the DecimalFormat documentation for full details on how to form the template string. If this value is set, then all other values are ignored.

type=g|i|p|c

This option allows one to indicate the "type" of number format you want to create. We only look at the first lowercase value of the first character when we interpret this value (hence "i" is same as "int" or "Integer"). If you omit or specify a invalid value, we assume 'g'. The value specified corresponds to the type of NumberFormat instance which we start with (and the optionally adjust with the other parameters you might specify). The general (g) type results in a NumberFormat.getInstance() starting point. The integer (i) type results in a NumberFormat.getInstance() starting point except that it is set to parse only integers and not display any fractional digits. The general (c) type results in a NumberFormat.getCurrencyInstance() starting point. The percent (p) type results in a NumberFormat.getPercentInstance() starting point.

time=short|medium|long|full

This option allows one to indicate how much time information is required in the format. The valid values correspond to the SHORT, MEDIUM, LONG, and FULL constants defined in the DateFormat class. This setting is ignored if the template=TEXT setting is present. If this setting is omitted, or incorrectly set, then time information is omitted from the output format.

frac.min=N

If specified, the integer value N controls the minimum number of fractional digits shown.

frac.max=N

If specified, the integer value N controls the maximum number of fractional digits shown.

int.min=N

If specified, the integer value N controls the minimum number of integer digits shown.

int.max=N

If specified, the integer value N controls the maximum number of integer digits shown.

grouping=true|false

This option can be used to turn on/off the grouping feature. If omitted - we leave it at the system default.

Parameters:

props - Properties to get the information from (as described above)

Returns:

New DateFormat object which was created - never returns null.

Throws:

IllegalArgumentException - If the properties passed were invalid (no template, date or time set).

ParseException - If a unrecoverable error was found trying to parse one of the values.

Since:

1.0

setToDay

protected void setToDay(DateFormat val)

Set the DateFormat to format a date to day precision.

Parameters:

val - New DateFormat value to assign - or null if you want us to reload the default.

See Also:

getToDay()

getToDay

public final DateFormat getToDay()

Get the DateFormat to format a date to day precision.

Returns:

Current DateFormat value assigned.

See Also:

setToDay(java.text.DateFormat)

setToMinute

protected void setToMinute(DateFormat val)

Set the DateFormat to format a date to minute precision.

Parameters:

val - New DateFormat value to assign - or null if you want us to reload the default.

See Also:

getToMinute()

getToMinute

public final DateFormat getToMinute()

Get the DateFormat to format a date to minute precision.

Returns:

Current DateFormat value assigned.

See Also:

setToMinute(java.text.DateFormat)

setToSecond

protected void setToSecond(DateFormat val)

Set the DateFormat to format a date to second precision.

Parameters:

val - New DateFormat value to assign - or null if you want us to reload the default.

See Also:

getToSecond()

getToSecond

public final DateFormat getToSecond()

Get the DateFormat to format a date to second precision.

Returns:

Current DateFormat value assigned.

See Also:

setToSecond(java.text.DateFormat)

setToMilli

protected void setToMilli(DateFormat val)

Set the DateFormat to format a date to millisecond precision.

Parameters:

val - New DateFormat value to assign - or null if you want us to reload the default.

See Also:

getToMilli()

getToMilli

public final DateFormat getToMilli()

Get the DateFormat to format a date to millisecond precision.

Returns:

Current DateFormat value assigned.

See Also:

setToMilli(java.text.DateFormat)

setInteger

protected void setInteger(NumberFormat val)

Set the NumberFormat to be used for integer values.

Parameters:

val - New NumberFormat value to assign - or null if you want us to reload the default.

See Also:

getInteger()

getInteger

public final NumberFormat getInteger()

Get the NumberFormat to format suitable for working with integers.

Returns:

Current NumberFormat value assigned.

See Also:

setInteger(java.text.NumberFormat)

loadConfig

void loadConfig(String name)
          throws ConfigException,
                 IOException

Throws:

ConfigException

IOException

setInstance

protected static void setInstance(Formats val)

Set the shared global instance of a Formats object.

Parameters:

val - New instance to use as the global default.

See Also:

getInstance()

getInstance

public static Formats getInstance()

Get the shared global instance of a Formats object.

Returns:

Reference to the globally shared Formats object.

See Also:

setInstance(com.ccg.text.Formats)