net.sourceforge.calendardate
Class CalendarDate

java.lang.Object
  net.sourceforge.calendardate.CalendarDate

All Implemented Interfaces:

java.lang.Comparable, java.io.Serializable

public final class CalendarDate

extends java.lang.Object

implements java.lang.Comparable, java.io.Serializable

This class represents a date in the Gregorian calendar (for example, December 20, 1998). It is designed to be a simpler, immutable version of java.util.GregorianCalendar.

Don't confuse this class with java.util.Date! They represent two separate things:

• CalendarDate represents a 'date in the calendar' (e.g. "John Smith's birthday") while
• java.util.Date represent an 'instant in time' (e.g. "When order 23711 was received"). A better name for this class would have been 'DateTime'.

These two ways of recording time are not directly related: For any given 'instant in time' the corresponding 'date in the calendar' depends on the timezone. Similiarly the 'instant in time' when a 'date in the calendar' begins depends on the timezone. (This is why you must supply a java.util.TimeZone when converting between instances of CalendarDate and Date.)

This class is thread-safe and immutable.

See Also:

Date, GregorianCalendar, Serialized Form

Field Summary

static int	APRIL The value returned by getMonth() representing April
static int	AUGUST The value returned by getMonth() representing August
static int	DECEMBER The value returned by getMonth() representing December
static CalendarDate	EARLIEST The earliest date that can be represented by this class (Januray 1, 1600 A.D.)
static int	FEBRUARY The value returned by getMonth() representing February
static int	FRIDAY The value returned by getDayOfWeek() representing Friday
static int	JANUARY The value returned by getMonth() representing January
static int	JULY The value returned by getMonth() representing July
static int	JUNE The value returned by getMonth() representing June
static CalendarDate	LATEST The latest date that can be represented by this class (December 31, 2999 A.D.)
static int	MARCH The value returned by getMonth() representing March
static int	MAY The value returned by getMonth() representing May
static int	MONDAY The value returned by getDayOfWeek() representing Monday
static int	NOVEMBER The value returned by getMonth() representing November
static int	OCTOBER The value returned by getMonth() representing October
static int	SATURDAY The value returned by getDayOfWeek() representing Saturday
static int	SEPTEMBER The value returned by getMonth() representing September
static int	SUNDAY The value returned by getDayOfWeek() representing Sunday
static int	THURSDAY The value returned by getDayOfWeek() representing Thursday
static int	TUESDAY The value returned by getDayOfWeek() representing Tuesday
static int	WEDNESDAY The value returned by getDayOfWeek() representing Wednesday

Constructor Summary

CalendarDate(int year, int month, int dayOfMonth)
Creates a date represented by the given year, month and day.

CalendarDate(java.util.TimeZone tzone)
Creates a CalendarDate representing the current date in the given timezone.

CalendarDate(java.util.TimeZone tzone, java.util.Date instantInTime)
Creates a CalendarDate representing the date in the given timezone at the given instant in time.

Method Summary

CalendarDate	addDays(int numDays) Returns a new date which is this date offset by numDays.
CalendarDate	addMonths(int numMonths) Adds a given number of months to the date while attempting to keep the day of the month.
int	compareTo(java.lang.Object other) If the given object is a CalendarDate: returns less than 0 if this date is before the given date returns 0 if this date is equal to the given date returns more than 0 if this date is after the given date
static int	daysInMonth(int year, int month) Returns the number of days in the given month.
int	daysUntil(CalendarDate otherDay) Returns the number of days until the given date
boolean	equals(java.lang.Object other) Returns true if the given object is a CalendarDate representing the same date as this object
int	getDayOfMonth() The day of the month
int	getDayOfWeek() The day of the week for this date
int	getMonth() The month of this date
int	getYear() The year of this date
int	hashCode()
boolean	isAfter(CalendarDate other) Returns true if this date is after the given date
boolean	isBefore(CalendarDate other) Returns true if this date is before the given date
static boolean	isLeapYear(int year) Returns true if the year is a leap year in the Gregorian calendar
static boolean	isOutsideRange(java.util.TimeZone tzone, java.util.Date instantInTime) Returns true if the given instant in time is before EARLIEST or after LATEST in the given timezone.
int	monthsUntil(CalendarDate otherDay) Returns the number of month changes until the given day.
java.util.Date	toDate(java.util.TimeZone timezone) Returns the instant in time when this day begins in the given timezone.
java.util.Date	toDate(java.util.TimeZone timezone, int hour, int min, int sec) Returns the instant in time when the given time of day is reached in the given timezone.
java.lang.String	toString() Returns a string form of this date in the form "2004-9-23"

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

SUNDAY

public static final int SUNDAY

The value returned by getDayOfWeek() representing Sunday

See Also:

Constant Field Values

MONDAY

public static final int MONDAY

The value returned by getDayOfWeek() representing Monday

See Also:

Constant Field Values

TUESDAY

public static final int TUESDAY

The value returned by getDayOfWeek() representing Tuesday

See Also:

Constant Field Values

WEDNESDAY

public static final int WEDNESDAY

The value returned by getDayOfWeek() representing Wednesday

See Also:

Constant Field Values

THURSDAY

public static final int THURSDAY

The value returned by getDayOfWeek() representing Thursday

See Also:

Constant Field Values

FRIDAY

public static final int FRIDAY

The value returned by getDayOfWeek() representing Friday

See Also:

Constant Field Values

SATURDAY

public static final int SATURDAY

The value returned by getDayOfWeek() representing Saturday

See Also:

Constant Field Values

JANUARY

public static final int JANUARY

The value returned by getMonth() representing January

See Also:

Constant Field Values

FEBRUARY

public static final int FEBRUARY

The value returned by getMonth() representing February

See Also:

Constant Field Values

MARCH

public static final int MARCH

The value returned by getMonth() representing March

See Also:

Constant Field Values

APRIL

public static final int APRIL

The value returned by getMonth() representing April

See Also:

Constant Field Values

MAY

public static final int MAY

The value returned by getMonth() representing May

See Also:

Constant Field Values

JUNE

public static final int JUNE

The value returned by getMonth() representing June

See Also:

Constant Field Values

JULY

public static final int JULY

The value returned by getMonth() representing July

See Also:

Constant Field Values

AUGUST

public static final int AUGUST

The value returned by getMonth() representing August

See Also:

Constant Field Values

SEPTEMBER

public static final int SEPTEMBER

The value returned by getMonth() representing September

See Also:

Constant Field Values

OCTOBER

public static final int OCTOBER

The value returned by getMonth() representing October

See Also:

Constant Field Values

NOVEMBER

public static final int NOVEMBER

The value returned by getMonth() representing November

See Also:

Constant Field Values

DECEMBER

public static final int DECEMBER

The value returned by getMonth() representing December

See Also:

Constant Field Values

EARLIEST

public static final CalendarDate EARLIEST

The earliest date that can be represented by this class (Januray 1, 1600 A.D.)

Note: This date may change to before 1600 in later releases of CalendarDate.

LATEST

public static final CalendarDate LATEST

The latest date that can be represented by this class (December 31, 2999 A.D.)

Note: This date may change to after 2999 in later releases of CalendarDate.

Constructor Detail

CalendarDate

public CalendarDate(int year,
                    int month,
                    int dayOfMonth)

Creates a date represented by the given year, month and day.

Parameters:

year - The year of the date to create

month - The month of the date to create (1 = January, 12 = December)

dayOfMonth - The day of the month of the date to create.

Throws:

java.lang.IllegalArgumentException - if the year, month and dayOfMonth combination are not valid in a Gregorian calendar.

CalendarDate

public CalendarDate(java.util.TimeZone tzone,
                    java.util.Date instantInTime)

Creates a CalendarDate representing the date in the given timezone at the given instant in time.

Think carefully about what timezone to use! Often you will want to use the timezone of the 'user' - which is not always represented by TimeZone.getDefault()

Parameters:

tzone - The timezone to be considered

instantInTime - The instant in time to be considered

Throws:

java.lang.IllegalArgumentException - if the instant in time is out of range in the given timezone

See Also:

isOutsideRange(TimeZone, Date)

CalendarDate

public CalendarDate(java.util.TimeZone tzone)

Creates a CalendarDate representing the current date in the given timezone. Equivalent to CalendarDate(tzone, new Date())

Parameters:

tzone - The timezone to be considered

Method Detail

isOutsideRange

public static boolean isOutsideRange(java.util.TimeZone tzone,
                                     java.util.Date instantInTime)

Returns true if the given instant in time is before EARLIEST or after LATEST in the given timezone.

getDayOfMonth

public int getDayOfMonth()

The day of the month

Returns:

The day of the month (in range 1 to 31)

getDayOfWeek

public int getDayOfWeek()

The day of the week for this date

Returns:

Day of week in range 1 (Sunday) to 7 (Saturday)

getMonth

public int getMonth()

The month of this date

Returns:

Month in range 1 to 12

getYear

public int getYear()

The year of this date

Returns:

The year

addDays

public CalendarDate addDays(int numDays)

Returns a new date which is this date offset by numDays.

Parameters:

numDays - the number of days to be added to this date (can be negative)

Returns:

A new date offset by numDays

Throws:

java.lang.IllegalArgumentException - if the resulting day would be before EARLIEST or after LATEST. That is, if numDays < this.daysUntil(EARLIEST) or numDays > this.daysUntil(LATEST)

daysUntil

public int daysUntil(CalendarDate otherDay)

Returns the number of days until the given date

Parameters:

otherDay - The date to compare to

Returns:

The number of days until otherDay (can be negative)

monthsUntil

public int monthsUntil(CalendarDate otherDay)

Returns the number of month changes until the given day. Note that this means there is just one 'month' between 1 November and 31 December.

Parameters:

otherDay - The date to compare to

Returns:

The number of month changes until the given day

isLeapYear

public static boolean isLeapYear(int year)

Returns true if the year is a leap year in the Gregorian calendar

Parameters:

year - The year to consider

Returns:

True if year is a leap year

compareTo

public int compareTo(java.lang.Object other)

If the given object is a CalendarDate:

1. returns less than 0 if this date is before the given date
2. returns 0 if this date is equal to the given date
3. returns more than 0 if this date is after the given date

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

other - the date to compare this one to

Throws:

java.lang.ClassCastException - if other is not an instance of CalendarDate

See Also:

Comparable.compareTo(java.lang.Object)

isBefore

public boolean isBefore(CalendarDate other)

Returns true if this date is before the given date

Parameters:

other - The date to consider

Returns:

true if this date is before the given date

isAfter

public boolean isAfter(CalendarDate other)

Returns true if this date is after the given date

Parameters:

other - The date to consider

Returns:

true if this date is after the given date

equals

public boolean equals(java.lang.Object other)

Returns true if the given object is a CalendarDate representing the same date as this object

Parameters:

other - The date to test against

Returns:

true if this is the same date as other

hashCode

public int hashCode()

toString

public java.lang.String toString()

Returns a string form of this date in the form "2004-9-23"

Returns:

A string form of this date

toDate

public java.util.Date toDate(java.util.TimeZone timezone)

Returns the instant in time when this day begins in the given timezone.

Parameters:

timezone - The timezone to consider

Returns:

the instant in time when this day begins

toDate

public java.util.Date toDate(java.util.TimeZone timezone,
                             int hour,
                             int min,
                             int sec)

Returns the instant in time when the given time of day is reached in the given timezone. If the time occurs twice on this date (as may happen when coming out of daylight savings time) the second occurrence will be returned.

Parameters:

timezone - The timezone to for which the date applies

hour - The hour of the day in range 0 - 23

min - The minute of the day in range 0 - 59

sec - The second of the day in range 0 - 60 (60 is for leap-seconds)

Returns:

The instant in time when the given time of day is reached in the given timezone

Throws:

java.lang.IllegalArgumentException - if the hour, min or sec parameters are outside the correct range

daysInMonth

public static int daysInMonth(int year,
                              int month)

Returns the number of days in the given month.

Parameters:

year - The year

month - The month in range 1 - 12

Returns:

The number of days in the given month

addMonths

public CalendarDate addMonths(int numMonths)

Adds a given number of months to the date while attempting to keep the day of the month. Note that this method is NOT transitive. For example:

• new CalendarDate(2005, 12, 31).addMonths(2).addMonths(1) results in "March 28, 2006"; but,
• new CalendarDate(2005, 12, 31).addMonths(3) results in "March 31, 2006"

Parameters:

numMonths - the number of months to be added (can be negative)

Returns:

A new date representing an offset of months from this date