hirondelle.web4j.request
Interface DateConverter

public interface DateConverter

Convert text into a DateTime or Date object, and vice versa.

See BuildImpl for important information on how this item is configured. BuildImpl.forDateConverter() returns the configured implementation of this interface.

This interface has methods which occur in pairs, one for a DateTime, and one for a Date. The term 'date' used below refers to generically to both of these classes. WEB4J recommeds DateTime as the preferred class for representing dates.

The application programmer's implementation of this interface is used when WEB4J needs to build a date from user input, or format an existing date. Here is an example implementation.

Design Notes
Here are some forces concerning dates in Java web applications :

• usually, users expect date input formats to be the same for all forms.
• an application may have only dates, only date-times, or a mixture of the two.
• user input of a date or date-time may be with a single control, or with many controls. For example, the date may be entered with one control, and the hours and minutes with a second and third control, respectively. (WEB4J works well with the one-control-only style. Using more than one control is still possible, since the application programmer always has access to the underlying request parameters. But, when using WEB4J, that style involves slightly more work for the application programmer.)
• the needs of the eye differ from the needs of the hand. That is, a date format which is easy to read is usually not easy to enter into a control. Thus, applications should support two formats for dates : a hand-friendly format (used for input), and an eye-friendly format, used for presentation and for input as well (allowing user input with an eye-friendly format is important for forms which change existing data).
• date formats may differ between Locales. For example, '01-31-2006' is natural for English speakers (January 31, 2006), while '31-01-2006' is more natural for French speakers (le 31 janvier 2006).
• for parsing tasks, SimpleDateFormat is mediocre, and perhaps even untrustworthy. It should be used with great care. One should also be aware that it's not thread-safe.
• if a new Locale is added to an application, then parsing and formatting of a date should not fail. Instead, reasonable defaults should be defined for unknown Locales.

Method Summary

String	formatEyeFriendly(Date aDate, Locale aLocale, TimeZone aTimeZone) Format a Date into an eye-friendly, legible format.
String	formatEyeFriendlyDateTime(DateTime aDateTime, Locale aLocale) Format a DateTime into an eye-friendly, legible format.
Date	parseEyeFriendly(String aInputValue, Locale aLocale, TimeZone aTimeZone) Parse textual user input of an "eye-friendly" format into a Date object.
DateTime	parseEyeFriendlyDateTime(String aInputValue, Locale aLocale) Parse textual user input of an "eye-friendly" format into a DateTime object.
Date	parseHandFriendly(String aInputValue, Locale aLocale, TimeZone aTimeZone) Parse textual user input of a "hand-friendly" format into a Date object.
DateTime	parseHandFriendlyDateTime(String aInputValue, Locale aLocale) Parse textual user input of a "hand-friendly" format into a DateTime object.

Method Detail

parseHandFriendly

Date parseHandFriendly(String aInputValue,
                       Locale aLocale,
                       TimeZone aTimeZone)

Parse textual user input of a "hand-friendly" format into a Date object.

A hand-friendly format might be '01312006', while an eye-friendly format might be 'Jan 31, 2006'.

The implementation must return null when the user input cannot be successfully parsed into a Date. It is recommended that the implementation have reasonable default behaviour for unexpected Locales.

This method is called by RequestParser.

Parameters:

aInputValue - user input value, as returned by ConvertParam.filter(String) (always has content).

aLocale - is obtained from the configured LocaleSource, and passed to this method by the framework.

aTimeZone - is obtained from the configured TimeZoneSource, and passed to this method by the framework.

parseEyeFriendly

Date parseEyeFriendly(String aInputValue,
                      Locale aLocale,
                      TimeZone aTimeZone)

Parse textual user input of an "eye-friendly" format into a Date object.

A hand-friendly format might be '01312006', while an eye-friendly format might be 'Jan 31, 2006'.

The implementation must return null when the user input cannot be successfully parsed into a Date. It is recommended that the implementation have reasonable default behaviour for unexpected Locales.

This method is called by RequestParser.

Parameters:

aInputValue - user input value, as returned by ConvertParam.filter(String) (always has content).

aLocale - is obtained from the configured LocaleSource, and passed to this method by the framework.

aTimeZone - is obtained from the configured TimeZoneSource, and passed to this method by the framework.

formatEyeFriendly

String formatEyeFriendly(Date aDate,
                         Locale aLocale,
                         TimeZone aTimeZone)

Format a Date into an eye-friendly, legible format.

The implementation must return an empty String when the Date is null. It is recommended that the implementation have reasonable default behaviour for unexpected Locales.

The framework will call this method when presenting listings using Report, and when presenting a Model Object in a form for a "change" operation.

This method is called by Formats.

Parameters:

aDate - to be presented to the user in a legible format

aLocale - is obtained from the configured LocaleSource, and passed to this method by the framework.

aTimeZone - is obtained from the configured TimeZoneSource, and passed to this method by the framework.

Returns:

text compatible with parseEyeFriendly(String, Locale, TimeZone)

parseHandFriendlyDateTime

DateTime parseHandFriendlyDateTime(String aInputValue,
                                   Locale aLocale)

Parse textual user input of a "hand-friendly" format into a DateTime object.

A hand-friendly format might be '01312006', while an eye-friendly format might be 'Jan 31, 2006'.

The implementation must return null when the user input cannot be successfully parsed into a DateTime. It is recommended that the implementation have reasonable default behaviour for unexpected Locales.

This method is called by RequestParser.

Parameters:

aInputValue - user input value, as returned by ConvertParam.filter(String) (always has content).

aLocale - is obtained from the configured LocaleSource, and passed to this method by the framework.

parseEyeFriendlyDateTime

DateTime parseEyeFriendlyDateTime(String aInputValue,
                                  Locale aLocale)

Parse textual user input of an "eye-friendly" format into a DateTime object.

A hand-friendly format might be '01312006', while an eye-friendly format might be 'Jan 31, 2006'.

The implementation must return null when the user input cannot be successfully parsed into a DateTime. It is recommended that the implementation have reasonable default behaviour for unexpected Locales.

This method is called by RequestParser.

Parameters:

aInputValue - user input value, as returned by ConvertParam.filter(String) (always has content).

aLocale - is obtained from the configured LocaleSource, and passed to this method by the framework.

formatEyeFriendlyDateTime

String formatEyeFriendlyDateTime(DateTime aDateTime,
                                 Locale aLocale)

Format a DateTime into an eye-friendly, legible format.

The implementation must return an empty String when the DateTime is null. It is recommended that the implementation have reasonable default behaviour for unexpected Locales.

The framework will call this method when presenting listings using Report, and when presenting a Model Object in a form for a "change" operation.

This method is called by Formats.

Parameters:

aDateTime - to be presented to the user in a legible format

aLocale - is obtained from the configured LocaleSource, and passed to this method by the framework.

Returns:

text compatible with parseEyeFriendlyDateTime(String, Locale)