org.apache.myfaces.dateformat
Class SimpleDateFormatter

java.lang.Object
  org.apache.myfaces.dateformat.SimpleDateFormatter

public class SimpleDateFormatter
extends Object

A reimplementation of the java.text.SimpleDateFormat class.

This class has been created for use with the tomahawk InputCalendar component. It exists for the following reasons:

• The java.text.SimpleDateFormat class is simply broken with respect to "week of year" functionality.
• The inputCalendar needs a javascript equivalent of SimpleDateFormat in order to process data in the popup calendar. But it is hard to unit-test javascript code. By maintaining a version in Java that is unit-tested, then making the javascript version a direct "port" of that code the javascript gets improved reliability.
• Documentation is necessary for this code, but it is not desirable to add lots of docs to a javascript file that is downloaded. The javascript version can simply reference the documentation here.

Note that the JODA project also provides a SimpleDateFormat implementation, but that does not support firstDayOfWeek functionality. In any case, it is not desirable to add a dependency from tomahawk on JODA just for the InputCalendar.

This implementation does extend the SimpleDateFormat class by adding the JODA "xxxx" yearOfWeekYear format option, as this is missing in the standard SimpleDateFormat class.

The parse methods also return null on error rather than throw an exception.

The code here was originally written in javascript (date.js), and has been ported to java.

At the current time, the following format options are NOT supported: DFkKSzZ.

Week Based Calendars

ISO standard ISO-8601 defines a calendaring system based not upon year/month/day_in_month but instead year/week/day_in_week. This is particularly popular in embedded systems as date arithmetic is much simpler; there are no irregular month lengths to handle.

The only tricky part is mapping to and from year/month/day formats. Unfortunately, while java.text.SimpleDateFormat does support a "ww" week format character, it has a number of flaws.

Weeks are always complete and discrete, ie week yyyy-ww always has 7 days in it, and never "shares" days with yyyy-(ww+1). However to achieve this, the last week of a year might include a few days of the next year, or the last few days of a year might be counted as part of the first week of the following year. The decision is made depending on which year the "majority" of days in that week belong to.

With ISO-8601, a week always starts on a monday. However many countries use a different convention, starting weeks on saturday, sunday or monday. This class supports setting the firstDayOfWeek.

Since:

1.1.7

Version:

$Revision: 472638 $ $Date: 2006-11-08 15:54:13 -0500 (Wed, 08 Nov 2006) $

Author:

Simon Kitching (latest modification by $Author: grantsmith $)

Constructor Summary

SimpleDateFormatter(String pattern, DateFormatSymbols symbols)
Constructor that sets the firstDayOfWeek to the ISO standard (1=monday).

SimpleDateFormatter(String pattern, DateFormatSymbols symbols, int firstDayOfWeek)
Constructor.

Method Summary

String	format(Date date)
Date	getDateForWeekDate(WeekDate wdate)
static WeekDate	getIsoWeekDate(Date date) Return the ISO week# represented by the specified date (1..53).
WeekDate	getWeekDate(Date date)
static WeekDate	getWeekDate(Date date, int firstDayOfWeek) Return the (year, week) representation of the given date.
Date	parse(String dateStr)
void	setFirstDayOfWeek(int dow)

Methods inherited from class java.lang.Object

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

Constructor Detail

SimpleDateFormatter

public SimpleDateFormatter(String pattern,
                           DateFormatSymbols symbols,
                           int firstDayOfWeek)

Constructor.

Parameters:

firstDayOfWeek - uses java.util.Date convention, ie 0=sun, 1=mon, 6=sat.

SimpleDateFormatter

public SimpleDateFormatter(String pattern,
                           DateFormatSymbols symbols)

Constructor that sets the firstDayOfWeek to the ISO standard (1=monday).

Method Detail

getIsoWeekDate

public static WeekDate getIsoWeekDate(Date date)

Return the ISO week# represented by the specified date (1..53). This implements the ISO-8601 standard for week numbering, as documented in Klaus Tondering's Calendar document, version 2.8: http://www.tondering.dk/claus/calendar.html For dates in January and February, calculate: a = year-1 b = a/4 - a/100 + a/400 c = (a-1)/4 - (a-1)/100 + (a-1)/400 s = b-c e = 0 f = day - 1 + 31*(month-1) For dates in March through December, calculate: a = year b = a/4 - a/100 + a/400 c = (a-1)/4 - (a-1)/100 + (a-1)/400 s = b-c e = s+1 f = day + (153*(month-3)+2)/5 + 58 + s Then, for any month continue thus: g = (a + b) mod 7 d = (f + g - e) mod 7 n = f + 3 - d We now have three situations: If n<0, the day lies in week 53-(g-s)/5 of the previous year. If n>364+s, the day lies in week 1 of the coming year. Otherwise, the day lies in week n/7 + 1 of the current year. This algorithm gives you a couple of additional useful values: d indicates the day of the week (0=Monday, 1=Tuesday, etc.) f+1 is the ordinal number of the date within the current year. Note that ISO-8601 specifies that week1 of a year is the first week in which the majority of days lie in that year. An equivalent description is that it is the first week including the 4th of january. This means that the 1st, 2nd and 3rd of January might lie in the last week of the previous year, and that the last week of a year may include the first few days of the following year. ISO-8601 also specifies that the first day of the week is always Monday. This function returns the week number regardless of which year it lies in. That means that asking for the week# of 01/01/yyyy might return 52 or 53, and asking for the week# of 31/12/yyyy might return 1.

getWeekDate

public static WeekDate getWeekDate(Date date,
                                   int firstDayOfWeek)

Return the (year, week) representation of the given date.

This is exactly like getIsoWeekNumber, except that a firstDayOfWeek can be specified; ISO-8601 hard-wires "monday" as first day of week.

TODO: support minimumDaysInWeek property. Currently, assumes this is set to 4 (the ISO standard).

Parameters:

firstDayOfWeek - is: 0=sunday, 1=monday, 6=sat. This is the convention used by java.util.Date. NOTE: java.util.Calendar uses 1=sunday, 2=monday, 7=saturday.

setFirstDayOfWeek

public void setFirstDayOfWeek(int dow)

parse

public Date parse(String dateStr)

format

public String format(Date date)

getWeekDate

public WeekDate getWeekDate(Date date)

getDateForWeekDate

public Date getDateForWeekDate(WeekDate wdate)