org.jfree.date

Class SerialDate

public abstract class SerialDate extends Object implements Comparable, Serializable, 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 : the date represented by the 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.

Author: David Gilbert

Field Summary
static DateFormatSymbolsDATE_FORMAT_SYMBOLS
Date format symbols.
static intFIRST_WEEK_IN_MONTH
A useful constant for referring to the first week in a month.
static intFOLLOWING
Useful constant for specifying a day of the week relative to a fixed date.
static intFOURTH_WEEK_IN_MONTH
A useful constant for referring to the fourth week in a month.
static intFRIDAY
Useful constant for Friday.
static intINCLUDE_BOTH
Useful range constant.
static intINCLUDE_FIRST
Useful range constant.
static intINCLUDE_NONE
Useful range constant.
static intINCLUDE_SECOND
Useful range constant.
static intLAST_WEEK_IN_MONTH
A useful constant for referring to the last week in a month.
static intMAXIMUM_YEAR_SUPPORTED
The highest year value supported by this date format.
static intMINIMUM_YEAR_SUPPORTED
The lowest year value supported by this date format.
static intMONDAY
Useful constant for Monday.
static intNEAREST
Useful constant for specifying a day of the week relative to a fixed date.
static intPRECEDING
Useful constant for specifying a day of the week relative to a fixed date.
static intSATURDAY
Useful constant for Saturday.
static intSECOND_WEEK_IN_MONTH
A useful constant for referring to the second week in a month.
static intSERIAL_LOWER_BOUND
The serial number for 1 January 1900.
static intSERIAL_UPPER_BOUND
The serial number for 31 December 9999.
static intSUNDAY
Useful constant for Sunday.
static intTHIRD_WEEK_IN_MONTH
A useful constant for referring to the third week in a month.
static intTHURSDAY
Useful constant for Thrusday.
static intTUESDAY
Useful constant for Tuesday.
static intWEDNESDAY
Useful constant for Wednesday.
Constructor Summary
protected SerialDate()
Default constructor.
Method Summary
static SerialDateaddDays(int days, SerialDate base)
Creates a new date by adding the specified number of days to the base date.
static SerialDateaddMonths(int months, SerialDate base)
Creates a new date by adding the specified number of months to the base date.
static SerialDateaddYears(int years, SerialDate base)
Creates a new date by adding the specified number of years to the base date.
abstract intcompare(SerialDate other)
Returns the difference (in days) between this date and the specified 'other' date.
static SerialDatecreateInstance(int day, int month, int yyyy)
Factory method that returns an instance of some concrete subclass of SerialDate.
static SerialDatecreateInstance(int serial)
Factory method that returns an instance of some concrete subclass of SerialDate.
static SerialDatecreateInstance(Date date)
Factory method that returns an instance of a subclass of SerialDate.
abstract intgetDayOfMonth()
Returns the day of the month.
abstract intgetDayOfWeek()
Returns the day of the week.
StringgetDescription()
Returns the description that is attached to the date.
SerialDategetEndOfCurrentMonth(SerialDate base)
Rolls the date forward to the last day of the month.
static SerialDategetFollowingDayOfWeek(int targetWeekday, SerialDate base)
Returns the earliest date that falls on the specified day-of-the-week and is AFTER the base date.
SerialDategetFollowingDayOfWeek(int targetDOW)
Returns the earliest date that falls on the specified day-of-the-week and is AFTER this date.
abstract intgetMonth()
Returns the month (January = 1, February = 2, March = 3).
static String[]getMonths()
Returns an array of month names.
static String[]getMonths(boolean shortened)
Returns an array of month names.
static SerialDategetNearestDayOfWeek(int targetDOW, SerialDate base)
Returns the date that falls on the specified day-of-the-week and is CLOSEST to the base date.
SerialDategetNearestDayOfWeek(int targetDOW)
Returns the nearest date that falls on the specified day-of-the-week.
static SerialDategetPreviousDayOfWeek(int targetWeekday, SerialDate base)
Returns the latest date that falls on the specified day-of-the-week and is BEFORE the base date.
SerialDategetPreviousDayOfWeek(int targetDOW)
Returns the latest date that falls on the specified day-of-the-week and is BEFORE this date.
abstract intgetYYYY()
Returns the year (assume a valid range of 1900 to 9999).
abstract booleanisAfter(SerialDate other)
Returns true if this SerialDate represents the same date as the specified SerialDate.
abstract booleanisBefore(SerialDate other)
Returns true if this SerialDate represents an earlier date compared to the specified SerialDate.
abstract booleanisInRange(SerialDate d1, SerialDate d2)
Returns true if this SerialDate is within the specified range (INCLUSIVE).
abstract booleanisInRange(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 booleanisLeapYear(int yyyy)
Determines whether or not the specified year is a leap year.
abstract booleanisOn(SerialDate other)
Returns true if this SerialDate represents the same date as the specified SerialDate.
abstract booleanisOnOrAfter(SerialDate other)
Returns true if this SerialDate represents the same date as the specified SerialDate.
abstract booleanisOnOrBefore(SerialDate other)
Returns true if this SerialDate represents the same date as the specified SerialDate.
static booleanisValidMonthCode(int code)
Returns true if the supplied integer code represents a valid month.
static booleanisValidWeekdayCode(int code)
Returns true if the supplied integer code represents a valid day-of-the-week, and false otherwise.
static booleanisValidWeekInMonthCode(int code)
Returns true if the supplied integer code represents a valid week-in-the-month, and false otherwise.
static intlastDayOfMonth(int month, int yyyy)
Returns the number of the last day of the month, taking into account leap years.
static intleapYearCount(int yyyy)
Returns the number of leap years from 1900 to the specified year INCLUSIVE.
static intmonthCodeToQuarter(int code)
Returns the quarter for the specified month.
static StringmonthCodeToString(int month)
Returns a string representing the supplied month.
static StringmonthCodeToString(int month, boolean shortened)
Returns a string representing the supplied month.
static StringrelativeToString(int relative)
Returns a string representing the supplied 'relative'.
voidsetDescription(String description)
Sets the description for the date.
static intstringToMonthCode(String s)
Converts a string to a month code.
static intstringToWeekdayCode(String s)
Converts the supplied string to a day of the week.
abstract DatetoDate()
Returns a java.util.Date.
abstract inttoSerial()
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).
StringtoString()
Converts the date to a string.
static StringweekdayCodeToString(int weekday)
Returns a string representing the supplied day-of-the-week.
static StringweekInMonthToString(int count)
Returns a string corresponding to the week-in-the-month code.

Field Detail

DATE_FORMAT_SYMBOLS

public static final DateFormatSymbols DATE_FORMAT_SYMBOLS
Date format symbols.

FIRST_WEEK_IN_MONTH

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

FOLLOWING

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

FOURTH_WEEK_IN_MONTH

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

FRIDAY

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

INCLUDE_BOTH

public static final int INCLUDE_BOTH
Useful range constant.

INCLUDE_FIRST

public static final int INCLUDE_FIRST
Useful range constant.

INCLUDE_NONE

public static final int INCLUDE_NONE
Useful range constant.

INCLUDE_SECOND

public static final int INCLUDE_SECOND
Useful range constant.

LAST_WEEK_IN_MONTH

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

MAXIMUM_YEAR_SUPPORTED

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

MINIMUM_YEAR_SUPPORTED

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

MONDAY

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

NEAREST

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

PRECEDING

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

SATURDAY

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

SECOND_WEEK_IN_MONTH

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

SERIAL_LOWER_BOUND

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

SERIAL_UPPER_BOUND

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

SUNDAY

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

THIRD_WEEK_IN_MONTH

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

THURSDAY

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

TUESDAY

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

WEDNESDAY

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

Constructor Detail

SerialDate

protected SerialDate()
Default constructor.

Method Detail

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.

Returns: a new 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.

Returns: a new 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.

Returns: A new date.

compare

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

The result is positive if this date is after the 'other' date and negative if it is before the 'other' date.

Parameters: other the date being compared to.

Returns: the difference between this and the other date.

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).

Returns: An instance of SerialDate.

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).

Returns: a instance of SerialDate.

createInstance

public static SerialDate createInstance(Date date)
Factory method that returns an instance of a subclass of SerialDate.

Parameters: date A Java date object.

Returns: a instance of SerialDate.

getDayOfMonth

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

Returns: the day of the month.

getDayOfWeek

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

Returns: the day of the week.

getDescription

public String getDescription()
Returns the description that is attached to the date. It is not required that a date have a description, but for some applications it is useful.

Returns: The description (possibly null).

getEndOfCurrentMonth

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

Parameters: base the base date.

Returns: a new serial 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.

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.

getMonth

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

Returns: the month of the year.

getMonths

public static String[] getMonths()
Returns an array of month names.

Returns: an array of month names.

getMonths

public static String[] getMonths(boolean shortened)
Returns an array of month names.

Parameters: shortened a flag indicating that shortened month names should be returned.

Returns: an array of month names.

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.

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.

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.

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.

getYYYY

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

Returns: the year.

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.

Returns: true if this SerialDate represents the same date as the specified SerialDate.

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.

Returns: true if this SerialDate represents an earlier date compared to the specified SerialDate.

isInRange

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

Parameters: d1 a boundary date for the range. d2 the other boundary date for the range.

Returns: A boolean.

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 date order of d1 and d2 is not important.

Parameters: d1 a boundary date for the range. d2 the other boundary date for the range. include a code that controls whether or not the start and end dates are included in the range.

Returns: A boolean.

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).

Returns: true if the specified year is a leap year.

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.

Returns: true if this SerialDate represents the same date as the specified SerialDate.

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.

Returns: true if this SerialDate represents the same date as the specified SerialDate.

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.

Returns: true if this SerialDate represents the same date as the specified SerialDate.

isValidMonthCode

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

Parameters: code the code being checked for validity.

Returns: true if the supplied integer code represents a valid month.

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.

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.

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).

Returns: the number of the last day of the month.

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).

Returns: the number of leap years from 1900 to the specified year.

monthCodeToQuarter

public static int monthCodeToQuarter(int code)
Returns the quarter for the specified month.

Parameters: code the month code (1-12).

Returns: the quarter that the month belongs to.

monthCodeToString

public static 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.

Returns: a string representing the supplied month.

monthCodeToString

public static 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. shortened if true return the abbreviation of the month.

Returns: a string representing the supplied month.

relativeToString

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

Need to find a better approach.

Parameters: relative a constant representing the 'relative'.

Returns: a string representing the supplied 'relative'.

setDescription

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

Parameters: description the description for this date (null permitted).

stringToMonthCode

public static int stringToMonthCode(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.

Parameters: s the string to parse.

Returns: -1 if the string is not parseable, the month of the year otherwise.

stringToWeekdayCode

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

Parameters: s a string representing the day of the week.

Returns: -1 if the string is not convertable, the day of the week otherwise.

toDate

public abstract 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'.

Returns: this as java.util.Date.

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).

Returns: the serial number for the date.

toString

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

Returns: a string representation of the date.

weekdayCodeToString

public static 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.

Returns: a string representing the supplied day-of-the-week.

weekInMonthToString

public static String weekInMonthToString(int count)
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.