org.osesb.utilities.language
Class CalendarDate

java.lang.Object
  org.osesb.utilities.language.CalendarDate

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable

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
protected java.lang.String	thisClassName The full name of this class.
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()
Creates a CalendarDate representing the current date in the default timezone.

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

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) Returns a new date which is this date offset by numMonths.
CalendarDate	addYears(int numYears) Returns a new date which is this date offset by numYears.
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
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
CalendarDate	getNextDay(int dayOfTheWeek) Returns a CalendarDate that represents the first day after this CalendarDate that matches the specified dayOfTheWeek.
int	getYear() The year of this date
int	hashCode()
boolean	isAfter(CalendarDate other) Returns true if this date is after the given date.
boolean	isAfterOrEqualTo(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
boolean	isBeforeOrEqualTo(CalendarDate other) Returns true if this date is before or equal to the given date.
boolean	isBetweenExclusive(CalendarDate startDate, CalendarDate endDate) Returns true if this date is between the given dates, NOT including the startDate and endDate..
boolean	isBetweenInclusive(CalendarDate startDate, CalendarDate endDate) Returns true if this date is between the given dates, including the startDate and endDate.
static boolean	isLeapYear(int year) Returns true if the year is a leap year in the Gregorian calendar
static void	main(java.lang.String[] args) main() For testing.
int	monthsUntil(CalendarDate otherDay) Returns the number of month changes until the given day.
java.util.Date	toDate() Returns the instant in time when this day begins in the default timeZone.
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

clone, finalize, 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.)

thisClassName

protected java.lang.String thisClassName

The full name of this class.

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

CalendarDate

public CalendarDate()

Creates a CalendarDate representing the current date in the default timezone.

CalendarDate

public CalendarDate(java.util.Date instantInTime)

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

Parameters:

instantInTime - The instant in time to be considered

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

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)

addMonths

public CalendarDate addMonths(int numMonths)

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

Parameters:

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

Returns:

A new date offset by numMonths

Throws:

java.lang.IllegalArgumentException - if the resulting day would be before EARLIEST or after LATEST.

addYears

public CalendarDate addYears(int numYears)

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

Parameters:

numYears - the number of years to be added to this date (can be negative)

Returns:

A new date offset by numMonths

Throws:

java.lang.IllegalArgumentException - if the resulting day would be before EARLIEST or after 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)
              throws java.lang.ClassCastException

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.

isBeforeOrEqualTo

public boolean isBeforeOrEqualTo(CalendarDate other)

Returns true if this date is before or equal to the given date.

Parameters:

other - The date to consider

Returns:

true if this date is before or equal to 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.

isAfterOrEqualTo

public boolean isAfterOrEqualTo(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.

isBetweenInclusive

public boolean isBetweenInclusive(CalendarDate startDate,
                                  CalendarDate endDate)

Returns true if this date is between the given dates, including the startDate and endDate.

Parameters:

startDate - The start of the date range.

endDate - The end of the date range.

Returns:

true if this date lies between the given dates, inclusuvely.

isBetweenExclusive

public boolean isBetweenExclusive(CalendarDate startDate,
                                  CalendarDate endDate)

Returns true if this date is between the given dates, NOT including the startDate and endDate..

Parameters:

startDate - The start of the date range.

endDate - The end of the date range.

Returns:

true if this date lies between the given dates, including the startDate and endDate.

getNextDay

public CalendarDate getNextDay(int dayOfTheWeek)

Returns a CalendarDate that represents the first day after this CalendarDate that matches the specified dayOfTheWeek. For example, if this CalendarDate represnets a Tuesday, then getNextDay(Calendar.THURSDAY) returns a CalendarDate that represents the next Thurswday.

Parameters:

dayOfTheWeek - Calendar.SUNDAY, Calendar.TUESDAY,...

Returns:

a CalendarDate that represents the first day after the current CalendarDate that matches the specified dayOfTheWeek.

equals

public boolean equals(java.lang.Object other)

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

Overrides:

equals in class java.lang.Object

Parameters:

other - The date to test against

Returns:

true if this is the same date as other

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

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

Overrides:

toString in class java.lang.Object

Returns:

A string form of this date

toDate

public java.util.Date toDate()

Returns the instant in time when this day begins in the default timeZone.

Returns:

the instant in time when this day begins

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 bounds of the above

main

public static void main(java.lang.String[] args)

main() For testing.

Parameters:

args - commandline arguments