com.marringtons.time
Class Date

java.lang.Object
  com.marringtons.time.Date

All Implemented Interfaces:

Comparable

public class Date

extends Object

implements Comparable

The Date class provides date and timestamp functionality as well as term and date maths. Date is in yyyymmdd order so that it sorts well. Date can be instantiated when you need a container for epoch time. It is used by the DAO to tag timestamps on records. It includes conversion from epochMilliseconds, a long, to epochSeconds, an integer. The Date object contains an elapsed time since the program started.

 // Date object with conversion to and from seconds
 Date now = new Date();
 int stamp = now.seconds();
 Date recreation = new Date( stamp);
 Calendar calendar = calendar.setTimeInMillis( recreation.timeInMilliseconds);
 
 // often used as part of a file name to record the date created.
 int today = Date.dateStamp( System.currentTimeInMillis());	// yyyymmdd ie 20031129
 today = Date.dateStamp( calendar);
 int dayStarted = Date.dateStamp( Date.getProgramStartTime());
 stamp = Date.seconds( System.currentTimeInMillis());
 
 // A full timestamp as used in logs and other readable text (yyyymmdd-hh:mm:ss.mmm)
 String timeStamp = Date.timeStamp( System.currentTimeInMillis()); 
 
 int month = calendar.get( Calendar.MONTH);
 int year = calendar.get( Calendar.YEAR);
 int days = Date.daysInMonth( year, month);
 String message = days + " days in the month of "+months[month]+", "+year;
 
 Calendar commencementDate, expiryDate;
 expiryDate.setTime( commencementDate.getTime());
 Date.add( expiryDate, termYears, termMonths, termDays);
 
 commencementDate.setTime( expiryDate.getTime());
 Date.subtract( commencementDate, termYears, termMonths, termDays);
 
 Date.YMD term = Date.difference( commencementDate, expiryDate);
 termYears = term.years;
 termMonths = term.months;
 termDays = term.days;
 

Author:

Paul Marrington

Nested Class Summary

static class

Date.YMD This class is used by the Date class for getting or working with terms - being the time between two date.

Field Summary

static int	secondsInDay Number of milliseconds in a day (for other calculations).
long	timeInMilliseconds Time object set to in milliseconds since 1/1/1970 (epoch time).

Constructor Summary

Date()
Default constructor sets object to current time.

Date(Calendar calendar)
Constructor, given a Calendar object.

Date(Date like)
Copy constructor.

Date(long timeInMilliseconds)
Set the date object from already available time.

Method Summary

Date	add(int years, int months, int days) Add a number of years, months and days to a date.
Date	add(Time interval) Add a time interval (days, hour, minutes, seconds) to the current date.
Calendar	calendar() Retrieve a Calendar object for this time.
int	compareTo(Object object)
int	dateStamp() returns datestamp for objects date (based on locale).
static int	daysInMonth(int year, int month) Return the number of days is a particular month.
boolean	equals(Object object)
static long	getProgramStartTime() Get the program start time in milliseconds since 1970.
Date.YMD	getTerm(Date to) Calculate the difference between 2 days and return it as a term in years, months and days.
int	hashCode()
Date	next(Time tod) Sets Date object to the next time of day that matches the time object provided.
int	seconds() Return the time as the number of seconds since January 1 1970.
static int	seconds(long currentTimeMillis) Get the time from the epoch - being the number of milliseconds since January 1 1970.
Date	subtract(int years, int months, int days) Remove a term in years, months and days from a date to get a starting date.
Time	timeOfDay() Retrieve time of day for this date.
String	timeStamp() Date/time stamp - typically used in logs.
Date.YMD	ymd() Retrieve year/month/day components of date.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

timeInMilliseconds

public final long timeInMilliseconds

Time object set to in milliseconds since 1/1/1970 (epoch time).

secondsInDay

public static final int secondsInDay

Number of milliseconds in a day (for other calculations).

See Also:

Constant Field Values

Constructor Detail

Date

public Date()

Default constructor sets object to current time.

Date

public Date(long timeInMilliseconds)

Set the date object from already available time.

Parameters:

timeInMilliseconds - since 1970 (epoch time).

Date

public Date(Date like)

Copy constructor.

Parameters:

like - Date to copy.

Date

public Date(Calendar calendar)

Constructor, given a Calendar object.

Parameters:

calendar -

Method Detail

seconds

public int seconds()

Return the time as the number of seconds since January 1 1970.

Returns:

the number of seconds since 1970 (dies in 2038).

add

public Date add(Time interval)

Add a time interval (days, hour, minutes, seconds) to the current date.

 Date tomorrow5pm = new Date().add( new Time( 1, 17, 0, 0));
 

Parameters:

interval - Time object containing the interval.

Returns:

Updated date object.

next

public Date next(Time tod)

Sets Date object to the next time of day that matches the time object provided. If the day component of the time is 0 it will be the same day or the next depending on whether the time of day is earlier or later. If the day component is non-zero it will be the time of day that number of days in the future. If the time has the isInterval flag set (starts with +) then add() is called instead to add an interval.

 Date tomorrow5pm = new Date().setTOD(new Time(1, 17, 0, 0));
 

Parameters:

tod - Time object containing the time of day (or interval if set).

Returns:

Updated date object.

timeOfDay

public Time timeOfDay()

Retrieve time of day for this date.

Returns:

Time of Day.

calendar

public Calendar calendar()

Retrieve a Calendar object for this time.

Returns:

Calendar object - lazy loaded on need.

dateStamp

public int dateStamp()

returns datestamp for objects date (based on locale).

Returns:

yyyymmdd as in 20030219 - great for sorting

timeStamp

public String timeStamp()

Date/time stamp - typically used in logs.

Returns:

yyyymmdd-hh:mm.sss as in 20030219-12:01.318

getProgramStartTime

public static long getProgramStartTime()

Get the program start time in milliseconds since 1970.

Returns:

long - program start time in milliseconds since 1970

seconds

public static int seconds(long currentTimeMillis)

Get the time from the epoch - being the number of milliseconds since January 1 1970.

Parameters:

currentTimeMillis - time since 1970 (epoch time)

Returns:

seconds since 1970 (epoch time)

daysInMonth

public static int daysInMonth(int year,
                              int month)

Return the number of days is a particular month.

Parameters:

year - to calculate for (needed for leap years) - as in 2004.

month - to return number of days in (0-11).

Returns:

days in the month asked for (28, 29, 30 or 31).

 assertTrue( Date.daysInMonth( 2004, 1) == 29);
 assertTrue( Date.daysInMonth( 1900, 1) == 28);
 

add

public Date add(int years,
                int months,
                int days)

Add a number of years, months and days to a date. It does not use the internal Calendar add as this uses a different algorithm to difference() - so that the procedure cannot be reversed.

Parameters:

years - to add.

months - to add.

days - to add.

Returns:

The new date - being the addition of the old and the interval.

subtract

public Date subtract(int years,
                     int months,
                     int days)

Remove a term in years, months and days from a date to get a starting date. Due to the vagaries of date arithmetic, this is not a reversable operation. Adding the same number of days, months and years may differ by as much as 3 days from the original date if the from date is early in the month (1st for most months and up to 3rd for March).

Parameters:

years - to remove.

months - to remove.

days - to remove.

Returns:

The new date - being the subtraction of the interval from the old.

ymd

public Date.YMD ymd()

Retrieve year/month/day components of date.

Returns:

Year/Month/Day object.

getTerm

public Date.YMD getTerm(Date to)

Calculate the difference between 2 days and return it as a term in years, months and days.

Parameters:

to - later date

Returns:

years, months and days between the 2 dates.

equals

public boolean equals(Object object)

See Also:

Object.equals(java.lang.Object)

hashCode

public int hashCode()

See Also:

Object.hashCode()

compareTo

public int compareTo(Object object)

Specified by:

compareTo in interface Comparable

See Also:

Comparable.compareTo(java.lang.Object)