net.degreedays.time
Class Day

java.lang.Object
  extended by net.degreedays.time.Day
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable

public final class Day
extends java.lang.Object
implements java.lang.Comparable, java.io.Serializable

A time-zone-independent representation of a YYYY-MM-DD date.

Note that, internally, this simple class uses the modern Gregorian calendar for all validation and calculations. This means that, although it is ideal for use within this degree-days framework, it is not really suitable for use with dates from before the point at which the Gregorian calendar was introduced (1582 in some countries, a little later in others).

Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.


Constructor Summary
Day(int year, int monthOfYearWithJanAs1, int dayOfMonth)
          Constructs a Day object representing a date with the specified year, month, and day.
 
Method Summary
 boolean after(Day comparisonDay)
          Tests whether this Day comes later in time than the specified comparison Day.
 DayRange asRange()
          Returns a non-null DayRange covering this Day only.
 boolean before(Day comparisonDay)
          Tests whether this Day comes earlier in time than the specified comparison Day.
 int compareTo(java.lang.Object anotherDay)
          Compares two Day objects for chronological ordering.
 int dayOfMonth()
          Returns a one-based number indicating the day-of-the-month component of this Day object.
 DayOfWeek dayOfWeek()
          Returns the non-null day-of-the-week of this Day object.
 int dayOfYear()
          Returns a number between 1 and 366 inclusive (365 for non-leap years) indicating the day-of-the-year of this Day object.
 int daysAfter(Day comparisonDay)
           
 int daysBefore(Day comparisonDay)
           
 boolean equals(java.lang.Object o)
          Two Day objects are equal if they represent the same date.
static Day fromCalendar(java.util.Calendar calendar)
           
static Day fromDateUtc(java.util.Date date)
           
static Day fromString(java.lang.String dateString)
          Parses a string date in ISO YYYY-MM-DD format (the format used by XML schema's date type), or YYYYMMDD format.
 DayRange fullCalendarMonth()
           
 DayRange fullCalendarYear()
           
 DayRange fullMonth(StartOfMonth startOfMonth)
           
 DayRange fullWeek(DayOfWeek firstDayOfWeek)
           
 DayRange fullYear(StartOfYear startOfYear)
           
 int hashCode()
          Overridden to ensure consistency with equals.
 Day minusDays(int numberOfDays)
           
 Day minusMonths(int numberOfMonths)
           
 Day minusWeeks(int numberOfWeeks)
           
 Day minusYears(int numberOfYears)
           
 int monthOfYear()
          Returns a one-based number indicating the month-of-the-year component of this Day object.
 Day next()
          Returns the non-null Day that comes immediately after this Day in the calendar.
static Day of(int year, int monthOfYearWithJanAs1, int dayOfMonth)
          Returns a non-null Day object representing a date with the specified year, month, and day.
 Day plusDays(int numberOfDays)
           
 Day plusMonths(int numberOfMonths)
           
 Day plusWeeks(int numberOfWeeks)
           
 Day plusYears(int numberOfYears)
           
 Day previous()
          Returns the non-null Day that comes immediately before this Day in the calendar.
 DayRange to(Day firstOrLastDayInRange)
          Returns the non-null DayRange covering (inclusively) the days between this Day and firstOrLastDayInRange (which can be before, after, or equal to this Day).
static Day todayInSystemTimeZone()
           
static Day todayInUtc()
           
 java.lang.String toNumericString()
          Returns a non-null, non-empty string representation of this Day object in YYYYMMDD format.
 java.lang.String toString()
          Returns a non-null, non-empty string representation of this Day object in YYYY-MM-DD format.
 int year()
          Returns a number indicating the year component of this Day object.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Day

public Day(int year,
           int monthOfYearWithJanAs1,
           int dayOfMonth)
Constructs a Day object representing a date with the specified year, month, and day.

Parameters:
year - the year - a number greater than 0 and less than or equal to 9999.
monthOfYearWithJanAs1 - the month of the year - a number between 1 and 12 (inclusive), January being 1 and December being 12.
dayOfMonth - the day of the month - a number between 1 and 31, although the upper limit depends on the month (since different months have different numbers of days), and the year (since February has 29 days on leap years and 28 otherwise).
Throws:
java.lang.IllegalArgumentException - if any of the parameters are outside of their allowed ranges (i.e. the date doesn't correspond to a real calendar date, or it's a date that's too far into the future or past).
Method Detail

year

public int year()
Returns a number indicating the year component of this Day object.


monthOfYear

public int monthOfYear()
Returns a one-based number indicating the month-of-the-year component of this Day object.


dayOfMonth

public int dayOfMonth()
Returns a one-based number indicating the day-of-the-month component of this Day object.


dayOfYear

public int dayOfYear()
Returns a number between 1 and 366 inclusive (365 for non-leap years) indicating the day-of-the-year of this Day object.


of

public static Day of(int year,
                     int monthOfYearWithJanAs1,
                     int dayOfMonth)
Returns a non-null Day object representing a date with the specified year, month, and day.

Parameters:
year - the year - a number greater than 0 and less than or equal to 9999.
monthOfYearWithJanAs1 - the month of the year - a number between 1 and 12 (inclusive), January being 1 and December being 12.
dayOfMonth - the day of the month - a number between 1 and 31, although the upper limit depends on the month (since different months have different numbers of days), and the year (since February has 29 days on leap years and 28 otherwise).
Throws:
java.lang.IllegalArgumentException - if any of the parameters are outside of their allowed ranges (i.e. the date doesn't correspond to a real calendar date, or it's a date that's too far into the future or past).

fromString

public static Day fromString(java.lang.String dateString)
                      throws java.lang.NumberFormatException
Parses a string date in ISO YYYY-MM-DD format (the format used by XML schema's date type), or YYYYMMDD format. Both formats can optionally have a '+' in front - XML schema doesn't allow the '+', but ISO does.

Returns:
a non-null Day object corresponding to the date represented by dateString.
Throws:
java.lang.NullPointerException - if dateString is null.
java.lang.NumberFormatException - if dateString has an invalid format, or represents a non-existent date.

fromCalendar

public static Day fromCalendar(java.util.Calendar calendar)

fromDateUtc

public static Day fromDateUtc(java.util.Date date)

todayInSystemTimeZone

public static Day todayInSystemTimeZone()

todayInUtc

public static Day todayInUtc()

equals

public boolean equals(java.lang.Object o)
Two Day objects are equal if they represent the same date.

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Overridden to ensure consistency with equals.

Overrides:
hashCode in class java.lang.Object

compareTo

public int compareTo(java.lang.Object anotherDay)
Compares two Day objects for chronological ordering.

Specified by:
compareTo in interface java.lang.Comparable
Parameters:
anotherDay - the Day to be compared (the declared type is Object but it must be an object that can be casted to Day). Cannot be null.
Returns:
Zero if anotherDay is equal to this Day ; a value less than zero if this Day is before anotherDay; and a value greater than zero if this Day is after anotherDay.
Throws:
java.lang.NullPointerException - if anotherDay is null..
java.lang.ClassCastException - if anotherDay is not a Day object.

before

public boolean before(Day comparisonDay)
Tests whether this Day comes earlier in time than the specified comparison Day.

Parameters:
comparisonDay - the non-null day to compare with this one.
Returns:
true if this Day object is earlier in time than comparisonDay; false otherwise (including if both Day objects represent the same date).
Throws:
java.lang.NullPointerException - if comparisonDay is null.

after

public boolean after(Day comparisonDay)
Tests whether this Day comes later in time than the specified comparison Day.

Parameters:
comparisonDay - the non-null day to compare with this one.
Returns:
true if this Day object is later in time than comparisonDay; false otherwise (including if both Day objects represent the same date).
Throws:
java.lang.NullPointerException - if comparisonDay is null.

next

public Day next()
Returns the non-null Day that comes immediately after this Day in the calendar. Will happily cross the borders between months and years.

Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

previous

public Day previous()
Returns the non-null Day that comes immediately before this Day in the calendar. Will happily cross the borders between months and years.

Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

plusDays

public Day plusDays(int numberOfDays)
Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

minusDays

public Day minusDays(int numberOfDays)
Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

plusWeeks

public Day plusWeeks(int numberOfWeeks)
Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

minusWeeks

public Day minusWeeks(int numberOfWeeks)
Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

plusMonths

public Day plusMonths(int numberOfMonths)
Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

minusMonths

public Day minusMonths(int numberOfMonths)
Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

plusYears

public Day plusYears(int numberOfYears)
Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

minusYears

public Day minusYears(int numberOfYears)
Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

to

public DayRange to(Day firstOrLastDayInRange)
Returns the non-null DayRange covering (inclusively) the days between this Day and firstOrLastDayInRange (which can be before, after, or equal to this Day).

Parameters:
firstOrLastDayInRange - the non-null Day that the returned DayRange should extend from this Day to. Can be before, after, or equal to this Day.
Returns:
a non-null DayRange object that extends from the earlier of this Day and firstOrLastDayInRange to the later of those two Day objects.
Throws:
java.lang.NullPointerException - if firstOrLastDayInRange is null.

asRange

public DayRange asRange()
Returns a non-null DayRange covering this Day only.

This is essentially a convenience method. Instead of typing

 Day.of(2011, 1, 1).to(Day.of(2011, 1, 1))
 

you can type

 Day.of(2011, 1, 1).asRange()
 


daysAfter

public int daysAfter(Day comparisonDay)

daysBefore

public int daysBefore(Day comparisonDay)

dayOfWeek

public DayOfWeek dayOfWeek()
Returns the non-null day-of-the-week of this Day object.


fullMonth

public DayRange fullMonth(StartOfMonth startOfMonth)
Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

fullCalendarMonth

public DayRange fullCalendarMonth()

fullYear

public DayRange fullYear(StartOfYear startOfYear)
Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

fullCalendarYear

public DayRange fullCalendarYear()

fullWeek

public DayRange fullWeek(DayOfWeek firstDayOfWeek)
Throws:
java.lang.IllegalStateException - in the unlikely event of this method requiring a Day object with a year less than 1 or greater than 9999.

toNumericString

public java.lang.String toNumericString()
Returns a non-null, non-empty string representation of this Day object in YYYYMMDD format.

See Also:
toString()

toString

public java.lang.String toString()
Returns a non-null, non-empty string representation of this Day object in YYYY-MM-DD format.

Overrides:
toString in class java.lang.Object
See Also:
toNumericString()


www.degreedays.net/api/