hirondelle.web4j.request
Interface DateConverter

public interface DateConverter

Convert text into a Date object, and Date objects into text.

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

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 object. Here is an example implementation.

Using SimpleDateFormat is not recommended, since its behavior when parsing items does not seem trustworthy, and it is not thread-safe.

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.
• the Date class is often used to model items which are different from the point of view of the user : dates '01-31-2006', and date-times '01-31-2006 08:00:00'
• 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 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.
• if a new Locale is added to an application, then parsing and formatting of 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.
Date	parseEyeFriendly(String aInputValue, Locale aLocale, TimeZone aTimeZone) Parse textual user input of an "eye-friendly" format into a Date object.
Date	parseHandFriendly(String aInputValue, Locale aLocale, TimeZone aTimeZone) Parse textual user input of a "hand-friendly" format into a Date 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)