com.jrefinery.date
Class SerialDate

java.lang.Object
  extended by com.jrefinery.date.SerialDate
All Implemented Interfaces:
MonthConstants
Direct Known Subclasses:
SpreadsheetDate

public abstract class SerialDate
extends java.lang.Object
implements MonthConstants

An abstract class that defines our requirements for manipulating dates, without tying down a particular implementation.

Requirement 1 : match at least what Excel does for dates; Requirement 2 : class is immutable;

Why not just use java.util.Date? We will, when it makes sense. At times, java.util.Date can be *too* precise - it represents an instant in time, accurate to 1/1000th of a second (with the date itself depending on the time-zone). Sometimes we just want to represent a particular day (e.g. 21 January 2015) without concerning ourselves about the time of day, or the time-zone, or anything else. That's what we've defined SerialDate for.

You can call getInstance() to get a concrete subclass of SerialDate, without worrying about the exact implementation.


Field Summary
static int[] AGGREGATE_DAYS_TO_END_OF_MONTH
          The number of days in a (non-leap) year up to the end of each month.
static int[] AGGREGATE_DAYS_TO_END_OF_PRECEDING_MONTH
          The number of days in a year up to the end of the preceding month.
static java.text.DateFormatSymbols DATE_FORMAT_SYMBOLS
           
protected  java.lang.String description
          A description for the date.
static int FIRST_WEEK_IN_MONTH
          A useful constant for referring to the first week in a month.
static int FOLLOWING
          Useful constant for specifying a day of the week relative to a fixed date.
static int FOURTH_WEEK_IN_MONTH
          A useful constant for referring to the fourth week in a month.
static int FRIDAY
          Useful constant for Friday.
static int INCLUDE_BOTH
          Useful range constant.
static int INCLUDE_FIRST
          Useful range constant.
static int INCLUDE_NONE
          Useful range constant.
static int INCLUDE_SECOND
          Useful range constant.
static int[] LAST_DAY_OF_MONTH
          The number of days in each month in non leap years.
static int LAST_WEEK_IN_MONTH
          A useful constant for referring to the last week in a month.
static int[] LEAP_YEAR_AGGREGATE_DAYS_TO_END_OF_MONTH
          The number of days in a leap year up to the end of each month.
static int[] LEAP_YEAR_AGGREGATE_DAYS_TO_END_OF_PRECEDING_MONTH
          The number of days in a leap year up to the end of the preceding month.
static int MAXIMUM_YEAR_SUPPORTED
          The highest year value supported by this date format.
static int MINIMUM_YEAR_SUPPORTED
          The lowest year value supported by this date format.
static int MONDAY
          Useful constant for Monday.
static int NEAREST
          Useful constant for specifying a day of the week relative to a fixed date.
static int PRECEDING
          Useful constant for specifying a day of the week relative to a fixed date.
static int SATURDAY
          Useful constant for Saturday.
static int SECOND_WEEK_IN_MONTH
          A useful constant for referring to the second week in a month.
static int SERIAL_LOWER_BOUND
          The serial number for 1 January 1900.
static int SERIAL_UPPER_BOUND
          The serial number for 31 December 9999.
static int SUNDAY
          Useful constant for Sunday.
static int THIRD_WEEK_IN_MONTH
          A useful constant for referring to the third week in a month.
static int THURSDAY
          Useful constant for Thrusday.
static int TUESDAY
          Useful constant for Tuesday.
static int WEDNESDAY
          Useful constant for Wednesday.
 
Fields inherited from interface com.jrefinery.date.MonthConstants
APRIL, AUGUST, DECEMBER, FEBRUARY, JANUARY, JULY, JUNE, MARCH, MAY, NOVEMBER, OCTOBER, SEPTEMBER
 
Constructor Summary
SerialDate()
           
 
Method Summary
static SerialDate addDays(int days, SerialDate base)
          Creates a new date by adding the specified number of days to the base date.
static SerialDate addMonths(int months, SerialDate base)
          Creates a new date by adding the specified number of months to the base date.
static SerialDate addYears(int years, SerialDate base)
          Creates a new date by adding the specified number of years to the base date.
abstract  int compare(SerialDate other)
          Returns the difference (in days) between this date and the specified 'other' date.
static SerialDate createInstance(java.util.Date date)
          Factory method that returns an instance of a subclass of SerialDate.
static SerialDate createInstance(int serial)
          Factory method that returns an instance of some concrete subclass of SerialDate.
static SerialDate createInstance(int day, int month, int yyyy)
          Factory method that returns an instance of some concrete subclass of SerialDate.
abstract  int getDayOfMonth()
          Returns the day of the month.
abstract  int getDayOfWeek()
          Returns the day of the week.
 java.lang.String getDescription()
          Returns a description of the date.
 SerialDate getEndOfCurrentMonth(SerialDate base)
          Rolls the date forward to the last day of the month.
 SerialDate getFollowingDayOfWeek(int targetDOW)
          Returns the earliest date that falls on the specified day-of-the-week and is AFTER this date.
static SerialDate getFollowingDayOfWeek(int targetWeekday, SerialDate base)
          Returns the earliest date that falls on the specified day-of-the-week and is AFTER the base date.
abstract  int getMonth()
          Returns the month (January = 1, February = 2, March = 3).
static java.lang.String[] getMonths()
           
static java.lang.String[] getMonths(boolean shortened)
           
 SerialDate getNearestDayOfWeek(int targetDOW)
          Returns the nearest date that falls on the specified day-of-the-week.
static SerialDate getNearestDayOfWeek(int targetDOW, SerialDate base)
          Returns the date that falls on the specified day-of-the-week and is CLOSEST to the base date.
 SerialDate getPreviousDayOfWeek(int targetDOW)
          Returns the latest date that falls on the specified day-of-the-week and is BEFORE this date.
static SerialDate getPreviousDayOfWeek(int targetWeekday, SerialDate base)
          Returns the latest date that falls on the specified day-of-the-week and is BEFORE the base date.
abstract  int getYYYY()
          Returns the year (assume a valid range of 1900 to 9999).
abstract  boolean isAfter(SerialDate other)
          Returns true if this SerialDate represents the same date as the specified SerialDate.
abstract  boolean isBefore(SerialDate other)
          Returns true if this SerialDate represents an earlier date compared to the specified SerialDate.
abstract  boolean isInRange(SerialDate d1, SerialDate d2)
          Returns true if this SerialDate is within the specified range (INCLUSIVE).
abstract  boolean isInRange(SerialDate d1, SerialDate d2, int include)
          Returns true if this SerialDate is within the specified range (caller specifies whether or not the end-points are included).
static boolean isLeapYear(int yyyy)
          Determines whether or not the specified year is a leap year.
abstract  boolean isOn(SerialDate other)
          Returns true if this SerialDate represents the same date as the specified SerialDate.
abstract  boolean isOnOrAfter(SerialDate other)
          Returns true if this SerialDate represents the same date as the specified SerialDate.
abstract  boolean isOnOrBefore(SerialDate other)
          Returns true if this SerialDate represents the same date as the specified SerialDate.
static boolean isValidMonthCode(int code)
          Returns true if the supplied integer code represents a valid month, and false otherwise.
static boolean isValidWeekdayCode(int code)
          Returns true if the supplied integer code represents a valid day-of-the-week, and false otherwise.
static boolean isValidWeekInMonthCode(int code)
          Returns true if the supplied integer code represents a valid week-in-the-month, and false otherwise.
static int lastDayOfMonth(int month, int yyyy)
          Returns the number of the last day of the month, taking into account leap years.
static int leapYearCount(int yyyy)
          Returns the number of leap years from 1900 to the specified year INCLUSIVE.
static int monthCodeToQuarter(int code)
           
static java.lang.String monthCodeToString(int month)
          Returns a string representing the supplied month.
static java.lang.String monthCodeToString(int month, boolean shortened)
          Returns a string representing the supplied month.
static java.lang.String relativeToString(int relative)
          Returns a string representing the supplied 'relative'.
 void setDescription(java.lang.String description)
          Sets the description for the date.
static int stringToMonthCode(java.lang.String s)
          Converts a string to a month code.
static int stringToWeekdayCode(java.lang.String s)
          Converts the supplied string to a day of the week.
abstract  java.util.Date toDate()
          Returns a java.util.Date.
abstract  int toSerial()
          Returns the serial number for the date, where 1 January 1900 = 2 (this corresponds, almost, to the numbering system used in Microsoft Excel for Windows and Lotus 1-2-3).
 java.lang.String toString()
          Converts the date to a string.
static java.lang.String weekdayCodeToString(int weekday)
          Returns a string representing the supplied day-of-the-week.
static java.lang.String weekInMonthToString(int code)
          Returns a string corresponding to the week-in-the-month code.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DATE_FORMAT_SYMBOLS

public static final java.text.DateFormatSymbols DATE_FORMAT_SYMBOLS

SERIAL_LOWER_BOUND

public static int SERIAL_LOWER_BOUND
The serial number for 1 January 1900.


SERIAL_UPPER_BOUND

public static int SERIAL_UPPER_BOUND
The serial number for 31 December 9999.


MINIMUM_YEAR_SUPPORTED

public static final int MINIMUM_YEAR_SUPPORTED
The lowest year value supported by this date format.

See Also:
Constant Field Values

MAXIMUM_YEAR_SUPPORTED

public static final int MAXIMUM_YEAR_SUPPORTED
The highest year value supported by this date format.

See Also:
Constant Field Values

MONDAY

public static final int MONDAY
Useful constant for Monday. Equivalent to java.util.Calendar.MONDAY.

See Also:
Constant Field Values

TUESDAY

public static final int TUESDAY
Useful constant for Tuesday. Equivalent to java.util.Calendar.TUESDAY.

See Also:
Constant Field Values

WEDNESDAY

public static final int WEDNESDAY
Useful constant for Wednesday. Equivalent to java.util.Calendar.WEDNESDAY.

See Also:
Constant Field Values

THURSDAY

public static final int THURSDAY
Useful constant for Thrusday. Equivalent to java.util.Calendar.THURSDAY.

See Also:
Constant Field Values

FRIDAY

public static final int FRIDAY
Useful constant for Friday. Equivalent to java.util.Calendar.FRIDAY.

See Also:
Constant Field Values

SATURDAY

public static final int SATURDAY
Useful constant for Saturday. Equivalent to java.util.Calendar.SATURDAY.

See Also:
Constant Field Values

SUNDAY

public static final int SUNDAY
Useful constant for Sunday. Equivalent to java.util.Calendar.SUNDAY.

See Also:
Constant Field Values

LAST_DAY_OF_MONTH

public static final int[] LAST_DAY_OF_MONTH
The number of days in each month in non leap years.


AGGREGATE_DAYS_TO_END_OF_MONTH

public static final int[] AGGREGATE_DAYS_TO_END_OF_MONTH
The number of days in a (non-leap) year up to the end of each month.


AGGREGATE_DAYS_TO_END_OF_PRECEDING_MONTH

public static final int[] AGGREGATE_DAYS_TO_END_OF_PRECEDING_MONTH
The number of days in a year up to the end of the preceding month.


LEAP_YEAR_AGGREGATE_DAYS_TO_END_OF_MONTH

public static final int[] LEAP_YEAR_AGGREGATE_DAYS_TO_END_OF_MONTH
The number of days in a leap year up to the end of each month.


LEAP_YEAR_AGGREGATE_DAYS_TO_END_OF_PRECEDING_MONTH

public static final int[] LEAP_YEAR_AGGREGATE_DAYS_TO_END_OF_PRECEDING_MONTH
The number of days in a leap year up to the end of the preceding month.


FIRST_WEEK_IN_MONTH

public static final int FIRST_WEEK_IN_MONTH
A useful constant for referring to the first week in a month.

See Also:
Constant Field Values

SECOND_WEEK_IN_MONTH

public static final int SECOND_WEEK_IN_MONTH
A useful constant for referring to the second week in a month.

See Also:
Constant Field Values

THIRD_WEEK_IN_MONTH

public static final int THIRD_WEEK_IN_MONTH
A useful constant for referring to the third week in a month.

See Also:
Constant Field Values

FOURTH_WEEK_IN_MONTH

public static final int FOURTH_WEEK_IN_MONTH
A useful constant for referring to the fourth week in a month.

See Also:
Constant Field Values

LAST_WEEK_IN_MONTH

public static final int LAST_WEEK_IN_MONTH
A useful constant for referring to the last week in a month.

See Also:
Constant Field Values

INCLUDE_NONE

public static final int INCLUDE_NONE
Useful range constant.

See Also:
Constant Field Values

INCLUDE_FIRST

public static final int INCLUDE_FIRST
Useful range constant.

See Also:
Constant Field Values

INCLUDE_SECOND

public static final int INCLUDE_SECOND
Useful range constant.

See Also:
Constant Field Values

INCLUDE_BOTH

public static final int INCLUDE_BOTH
Useful range constant.

See Also:
Constant Field Values

PRECEDING

public static final int PRECEDING
Useful constant for specifying a day of the week relative to a fixed date.

See Also:
Constant Field Values

NEAREST

public static final int NEAREST
Useful constant for specifying a day of the week relative to a fixed date.

See Also:
Constant Field Values

FOLLOWING

public static final int FOLLOWING
Useful constant for specifying a day of the week relative to a fixed date.

See Also:
Constant Field Values

description

protected java.lang.String description
A description for the date.

Constructor Detail

SerialDate

public SerialDate()
Method Detail

isValidWeekdayCode

public static boolean isValidWeekdayCode(int code)
Returns true if the supplied integer code represents a valid day-of-the-week, and false otherwise.

Parameters:
code - The code being checked for validity.
Returns:
True if the supplied integer code represents a valid day-of-the-week, and false otherwise.

stringToWeekdayCode

public static int stringToWeekdayCode(java.lang.String s)
Converts the supplied string to a day of the week.

Parameters:
dayOfWeek - A string representing the day of the week.

weekdayCodeToString

public static java.lang.String weekdayCodeToString(int weekday)
Returns a string representing the supplied day-of-the-week.

Need to find a better approach.

Parameters:
weekday - The day of the week.

getMonths

public static java.lang.String[] getMonths()

getMonths

public static java.lang.String[] getMonths(boolean shortened)

isValidMonthCode

public static boolean isValidMonthCode(int code)
Returns true if the supplied integer code represents a valid month, and false otherwise.

Parameters:
code - The code being checked for validity.
Returns:
True if the supplied integer code represents a valid month, and false otherwise.

monthCodeToQuarter

public static int monthCodeToQuarter(int code)

monthCodeToString

public static java.lang.String monthCodeToString(int month)
Returns a string representing the supplied month.

The string returned is the long form of the month name taken from the default locale.

Parameters:
month - The month.

monthCodeToString

public static java.lang.String monthCodeToString(int month,
                                                 boolean shortened)
Returns a string representing the supplied month.

The string returned is the long or short form of the month name taken from the default locale.

Parameters:
month - The month.

stringToMonthCode

public static int stringToMonthCode(java.lang.String s)
Converts a string to a month code.

This method will return one of the constants JANUARY, FEBRUARY, ..., DECEMBER that corresponds to the string. If the string is not recognised, this method returns -1.


isValidWeekInMonthCode

public static boolean isValidWeekInMonthCode(int code)
Returns true if the supplied integer code represents a valid week-in-the-month, and false otherwise.

Parameters:
code - The code being checked for validity.
Returns:
True if the supplied integer code represents a valid week-in-the-month, and false otherwise.

isLeapYear

public static boolean isLeapYear(int yyyy)
Determines whether or not the specified year is a leap year.

Parameters:
yyyy - The year (in the range 1900 to 9999).

leapYearCount

public static int leapYearCount(int yyyy)
Returns the number of leap years from 1900 to the specified year INCLUSIVE.

Note that 1900 is not a leap year.

Parameters:
yyyy - The year (in the range 1900 to 9999).

lastDayOfMonth

public static int lastDayOfMonth(int month,
                                 int yyyy)
Returns the number of the last day of the month, taking into account leap years.

Parameters:
month - The month.
yyyy - The year (in the range 1900 to 9999). *

addDays

public static SerialDate addDays(int days,
                                 SerialDate base)
Creates a new date by adding the specified number of days to the base date.

Parameters:
days - The number of days to add (can be negative).
base - The base date.

addMonths

public static SerialDate addMonths(int months,
                                   SerialDate base)
Creates a new date by adding the specified number of months to the base date.

If the base date is close to the end of the month, the day on the result may be adjusted slightly: 31 May + 1 month = 30 June.

Parameters:
months - The number of months to add (can be negative).
base - The base date.

addYears

public static SerialDate addYears(int years,
                                  SerialDate base)
Creates a new date by adding the specified number of years to the base date.

Parameters:
years - The number of years to add (can be negative).
base - The base date.

getPreviousDayOfWeek

public static SerialDate getPreviousDayOfWeek(int targetWeekday,
                                              SerialDate base)
Returns the latest date that falls on the specified day-of-the-week and is BEFORE the base date.

Parameters:
targetWeekday - A code for the target day-of-the-week.
base - The base date.
Returns:
The latest date that falls on the specified day-of-the-week and is BEFORE the base date.

getFollowingDayOfWeek

public static SerialDate getFollowingDayOfWeek(int targetWeekday,
                                               SerialDate base)
Returns the earliest date that falls on the specified day-of-the-week and is AFTER the base date.

Parameters:
targetWeekday - A code for the target day-of-the-week.
base - The base date.
Returns:
The earliest date that falls on the specified day-of-the-week and is AFTER the base date.

getNearestDayOfWeek

public static SerialDate getNearestDayOfWeek(int targetDOW,
                                             SerialDate base)
Returns the date that falls on the specified day-of-the-week and is CLOSEST to the base date.

Parameters:
targetDOW - A code for the target day-of-the-week.
base - The base date.
Returns:
The date that falls on the specified day-of-the-week and is CLOSEST to the base date.

getEndOfCurrentMonth

public SerialDate getEndOfCurrentMonth(SerialDate base)
Rolls the date forward to the last day of the month.

Parameters:
base - The base date.

weekInMonthToString

public static java.lang.String weekInMonthToString(int code)
Returns a string corresponding to the week-in-the-month code.

Need to find a better approach.

Parameters:
count - An integer code representing the week-in-the-month.
Returns:
A string corresponding to the week-in-the-month code.

relativeToString

public static java.lang.String relativeToString(int relative)
Returns a string representing the supplied 'relative'.

Need to find a better approach.

Parameters:
A - constant representing the 'relative'.

createInstance

public static SerialDate createInstance(int day,
                                        int month,
                                        int yyyy)
Factory method that returns an instance of some concrete subclass of SerialDate.

Parameters:
day - The day (1-31).
month - The month (1-12).
yyyy - The year (in the range 1900 to 9999).

createInstance

public static SerialDate createInstance(int serial)
Factory method that returns an instance of some concrete subclass of SerialDate.

Parameters:
serial - The serial number for the day (1 January 1900 = 2).

createInstance

public static SerialDate createInstance(java.util.Date date)
Factory method that returns an instance of a subclass of SerialDate. NOT YET IMPLEMENTED.

Parameters:
date - A Java date object.

toSerial

public abstract int toSerial()
Returns the serial number for the date, where 1 January 1900 = 2 (this corresponds, almost, to the numbering system used in Microsoft Excel for Windows and Lotus 1-2-3).


toDate

public abstract java.util.Date toDate()
Returns a java.util.Date. Since java.util.Date has more precision than SerialDate, we need to define a convention for the 'time of day'.


getDescription

public java.lang.String getDescription()
Returns a description of the date.

Returns:
A description of the date.

setDescription

public void setDescription(java.lang.String description)
Sets the description for the date.

Parameters:
description - The new description for the date.

toString

public java.lang.String toString()
Converts the date to a string.

Overrides:
toString in class java.lang.Object
Returns:
A string representation of the date.

getYYYY

public abstract int getYYYY()
Returns the year (assume a valid range of 1900 to 9999).


getMonth

public abstract int getMonth()
Returns the month (January = 1, February = 2, March = 3).


getDayOfMonth

public abstract int getDayOfMonth()
Returns the day of the month.


getDayOfWeek

public abstract int getDayOfWeek()
Returns the day of the week.


compare

public abstract int compare(SerialDate other)
Returns the difference (in days) between this date and the specified 'other' date.

Parameters:
other - The date being compared to.

isOn

public abstract boolean isOn(SerialDate other)
Returns true if this SerialDate represents the same date as the specified SerialDate.

Parameters:
other - The date being compared to.

isBefore

public abstract boolean isBefore(SerialDate other)
Returns true if this SerialDate represents an earlier date compared to the specified SerialDate.

Parameters:
other - The date being compared to.

isOnOrBefore

public abstract boolean isOnOrBefore(SerialDate other)
Returns true if this SerialDate represents the same date as the specified SerialDate.

Parameters:
other - The date being compared to.

isAfter

public abstract boolean isAfter(SerialDate other)
Returns true if this SerialDate represents the same date as the specified SerialDate.

Parameters:
other - The date being compared to.

isOnOrAfter

public abstract boolean isOnOrAfter(SerialDate other)
Returns true if this SerialDate represents the same date as the specified SerialDate.

Parameters:
other - The date being compared to.

isInRange

public abstract boolean isInRange(SerialDate d1,
                                  SerialDate d2)
Returns true if this SerialDate is within the specified range (INCLUSIVE). The order of d1 d2 is not important.

Parameters:
d1 - One boundary date for the range.
d2 - A second boundary date for the range.

isInRange

public abstract boolean isInRange(SerialDate d1,
                                  SerialDate d2,
                                  int include)
Returns true if this SerialDate is within the specified range (caller specifies whether or not the end-points are included). The order of d1 and d2 is not important.

Parameters:
d1 - One boundary date for the range.
d2 - A second boundary date for the range.

getPreviousDayOfWeek

public SerialDate getPreviousDayOfWeek(int targetDOW)
Returns the latest date that falls on the specified day-of-the-week and is BEFORE this date.

Parameters:
targetDOW - A code for the target day-of-the-week.
Returns:
The latest date that falls on the specified day-of-the-week and is BEFORE this date.

getFollowingDayOfWeek

public SerialDate getFollowingDayOfWeek(int targetDOW)
Returns the earliest date that falls on the specified day-of-the-week and is AFTER this date.

Parameters:
targetDOW - A code for the target day-of-the-week.
Returns:
The earliest date that falls on the specified day-of-the-week and is AFTER this date.

getNearestDayOfWeek

public SerialDate getNearestDayOfWeek(int targetDOW)
Returns the nearest date that falls on the specified day-of-the-week.

Parameters:
targetDOW - A code for the target day-of-the-week.
Returns:
The nearest date that falls on the specified day-of-the-week.


Copyright © 2003 MBARI.

The Monterey Bay Aquarium Research Institute (MBARI) provides this documentation and code "as is", with no warranty, express or implied, of its quality or consistency. It is provided without support and without obligation on the part of MBARI to assist in its use, correction, modification, or enhancement.