org.hackystat.utilities.time.period
Class Day

java.lang.Object
  extended by org.hackystat.utilities.time.period.Day
All Implemented Interfaces:
java.lang.Comparable<java.lang.Object>, TimePeriod

public final class Day
extends java.lang.Object
implements TimePeriod

Provides a "cousin" of Date that represents only year, month, and day information. Many Hackystat facilities need date information only at the precision of year/month/day. This abstraction represents a single 24 hour time period.

All Day constructors are private or package private. Clients of this class must use the static getInstance() methods to obtain Day instances.

The Calendar is forced to Locale.US to ensure constant week boundaries.

Day instances are immutable.

Author:
Philip M. Johnson

Method Summary
 int compareTo(java.lang.Object o)
          Compares two Day objects.
static int daysBetween(Day day1, Day day2)
          Returns the number of days (positive or negative) between day1 and day2.
 boolean equals(java.lang.Object obj)
          Two Day instances are equal() iff they have equal year, month, and day fields.
 java.util.Date getDate()
          Returns a freshly created Date object that corresponds to the current day.
 java.lang.String getDayString()
          Returns a two character string representing this Day's day (00-31).
 Day getFirstDay()
          Returns the "first" day in the TimePeriod.
 long getFirstTickOfTheDay()
          Gets the first tick of the day.
static Day getInstance()
          Returns a Day instance corresponding to today.
static Day getInstance(java.util.Date date)
          Returns a Day instance corresponding to the passed Date.
static Day getInstance(int year, int month, int day)
          Returns a Day instance corresponding to the passed year, month, and day.
static Day getInstance(long timestamp)
          Returns a Day instance corresponding to the day associated with timestamp.
static Day getInstance(java.lang.String dayString)
          Returns a Day instance corresponding to the passed date in dd-MMM-yyyy format.
static Day getInstance(javax.xml.datatype.XMLGregorianCalendar xmlDay)
          Returns a Day instance associated with this passed XMLGregorianCalendar.
 long getLastTickOfTheDay()
          Gets the last tick of the day.
 java.lang.String getMediumMonthString()
          Returns a three character string representing this Day's month, e.g.
 java.lang.String getMonthString()
          Returns a two character string representing this Day's month (01-12).
 java.lang.String getSimpleDayString()
          Gets the simple date string in 2004-03-25 format.
 java.lang.String getYearString()
          Returns a four character string representing this Day's year (2000, etc.).
 int hashCode()
          Compute the hashcode following recommendations in "Effective Java".
 Day inc(int increment)
          Returns a Day instance corresponding to a day plus or minus increment days in the future or past.
 boolean isBefore(Day day)
          Returns true if this Day preceeds the passed Day, false if the two Days are equal or this day comes after the passed Day.
 java.lang.String toString()
          Returns this Day instance in YYYY-MM-DD format.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

getInstance

public static Day getInstance()
Returns a Day instance corresponding to today.

Returns:
A Day instance corresponding to today.

getInstance

public static Day getInstance(long timestamp)
Returns a Day instance corresponding to the day associated with timestamp.

Parameters:
timestamp - A UTC time from which a Day instance will be returned.
Returns:
A Day instance corresponding to timestamp.

getInstance

public static Day getInstance(java.util.Date date)
Returns a Day instance corresponding to the passed Date.

Parameters:
date - A date from which a Day instance will be returned.
Returns:
The Day instance corresponding to Date.

getInstance

public static Day getInstance(int year,
                              int month,
                              int day)
Returns a Day instance corresponding to the passed year, month, and day. Historically used for testing, although getInstance(dayString) should be used instead for clarity's sake unless numeric values are being manipulated directly.

Parameters:
year - Year, such as 2003.
month - Month, such as 0. Note that January is 0!
day - Day, such as 1. The first day is 1.
Returns:
The Day instance associated with this date.

getInstance

public static Day getInstance(java.lang.String dayString)
                       throws java.lang.Exception
Returns a Day instance corresponding to the passed date in dd-MMM-yyyy format. This creates a temporary SimpleDateFormat, so it shouldn't be used when efficiency is important, but it's a nice method for test cases where dates are being supplied manually.

Parameters:
dayString - A string in dd-MMM-yyyy US Locale format, such as "01-Jan-2004".
Returns:
The Day instance associated with this date.
Throws:
java.lang.Exception - If problems occur parsing dayString.

getInstance

public static Day getInstance(javax.xml.datatype.XMLGregorianCalendar xmlDay)
Returns a Day instance associated with this passed XMLGregorianCalendar.

Parameters:
xmlDay - The date.
Returns:
The corresponding day.

inc

public Day inc(int increment)
Returns a Day instance corresponding to a day plus or minus increment days in the future or past.

Parameters:
increment - A positive or negative integer.
Returns:
A Day corresponding to the increment from this day.

getDate

public java.util.Date getDate()
Returns a freshly created Date object that corresponds to the current day. Note that this Date object may not correspond to the same time of day as was used to create this Day instance!

Returns:
A Date object corresponding to this day.

getFirstDay

public Day getFirstDay()
Returns the "first" day in the TimePeriod. For Days, that's just this day.

Specified by:
getFirstDay in interface TimePeriod
Returns:
The current day.

daysBetween

public static int daysBetween(Day day1,
                              Day day2)
Returns the number of days (positive or negative) between day1 and day2.

Parameters:
day1 - A Day instance.
day2 - A Day instance.
Returns:
The interval in days between day1 and day2.

compareTo

public int compareTo(java.lang.Object o)
Compares two Day objects.

Specified by:
compareTo in interface java.lang.Comparable<java.lang.Object>
Parameters:
o - A Day instance.
Returns:
The standard compareTo values.

isBefore

public boolean isBefore(Day day)
Returns true if this Day preceeds the passed Day, false if the two Days are equal or this day comes after the passed Day.

Parameters:
day - The day to be compared.
Returns:
True if the passed day comes after this Day.

equals

public boolean equals(java.lang.Object obj)
Two Day instances are equal() iff they have equal year, month, and day fields.

Overrides:
equals in class java.lang.Object
Parameters:
obj - Any object.
Returns:
True if obj is a Day and it's equal to this Day.

hashCode

public int hashCode()
Compute the hashcode following recommendations in "Effective Java".

Overrides:
hashCode in class java.lang.Object
Returns:
The hashcode.

toString

public java.lang.String toString()
Returns this Day instance in YYYY-MM-DD format.

Overrides:
toString in class java.lang.Object
Returns:
The day as a string.

getSimpleDayString

public java.lang.String getSimpleDayString()
Gets the simple date string in 2004-03-25 format.

Returns:
Simply date format.

getDayString

public java.lang.String getDayString()
Returns a two character string representing this Day's day (00-31).

Returns:
The day as a string.

getMonthString

public java.lang.String getMonthString()
Returns a two character string representing this Day's month (01-12).

Returns:
The month as a string.

getMediumMonthString

public java.lang.String getMediumMonthString()
Returns a three character string representing this Day's month, e.g. Jan, Feb.

Returns:
The month as a string.

getYearString

public java.lang.String getYearString()
Returns a four character string representing this Day's year (2000, etc.).

Returns:
The year as a string.

getFirstTickOfTheDay

public long getFirstTickOfTheDay()
Gets the first tick of the day.

Returns:
The first tick of the day in millis.

getLastTickOfTheDay

public long getLastTickOfTheDay()
Gets the last tick of the day.

Returns:
The last tick of the day in millis.