xdev.util

Class XdevDate

java.lang.Object

java.util.Calendar

java.util.GregorianCalendar

xdev.util.XdevDate

All Implemented Interfaces:

Serializable, Cloneable, Comparable<Calendar>, Copyable<XdevDate>

public class XdevDate
extends GregorianCalendar
implements Copyable<XdevDate>

The class XdevDate represents a specific instant in time, with millisecond precision.

The XdevDate class provides common methods for date / time manipulation, comparison and formatting.

Since:

2.0

Author:

XDEV Software

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.Calendar

Calendar.Builder

Field Summary

Fields inherited from class java.util.GregorianCalendar

AD, BC

Fields inherited from class java.util.Calendar

ALL_STYLES, AM, AM_PM, APRIL, areFieldsSet, AUGUST, DATE, DAY_OF_MONTH, DAY_OF_WEEK, DAY_OF_WEEK_IN_MONTH, DAY_OF_YEAR, DECEMBER, DST_OFFSET, ERA, FEBRUARY, FIELD_COUNT, fields, FRIDAY, HOUR, HOUR_OF_DAY, isSet, isTimeSet, JANUARY, JULY, JUNE, LONG, LONG_FORMAT, LONG_STANDALONE, MARCH, MAY, MILLISECOND, MINUTE, MONDAY, MONTH, NARROW_FORMAT, NARROW_STANDALONE, NOVEMBER, OCTOBER, PM, SATURDAY, SECOND, SEPTEMBER, SHORT, SHORT_FORMAT, SHORT_STANDALONE, SUNDAY, THURSDAY, time, TUESDAY, UNDECIMBER, WEDNESDAY, WEEK_OF_MONTH, WEEK_OF_YEAR, YEAR, ZONE_OFFSET

Constructor Summary

Constructors

Constructor and Description
XdevDate() Constructs a new XdevDate using the current time in the default time zone with the default locale.
XdevDate(Calendar c) Constructs a new XdevDate using the date and time from the given Calendar d.
XdevDate(Date d) Constructs a new XdevDate using the date and time from the given Date d.
XdevDate(int year, int month, int day) Constructs a new XdevDate with the given date set in the default time zone with the default locale.
XdevDate(int year, int month, int day, int hour, int minute) Constructs a new XdevDate with the given date set in the default time zone with the default locale.
XdevDate(int year, int month, int day, int hour, int minute, int second) Constructs a new XdevDate with the given date set in the default time zone with the default locale.
XdevDate(Locale locale) Constructs a XdevDate based on the current time in the default time zone with the given locale.
XdevDate(long currentTimeMillis) Constructs a new XdevDate using the time from the given long value.
XdevDate(TimeZone zone) Constructs a XdevDate based on the current time in the given time zone with the default locale.
XdevDate(TimeZone zone, Locale locale) Constructs a XdevDate based on the current time in the given time zone with the given locale.

Method Summary

Modifier and Type	Method and Description
void	add(int field, int amount)
boolean	after(Object date) Returns whether this XdevDate represents a date/time after the date/time represented by the specified Object date.
boolean	before(Object date) Returns whether this XdevDate represents a date/time before the date/time represented by the specified Object date.
boolean	between(Object startDate, Object endDate) This method is a alias for isBetween(Object, Object).
XdevDate	clone() Returns a field-for-field copy of this instance.
XdevDate	copy() Creates a (defensive) copy of this XdevDate.
boolean	equals(Calendar other) Indicates whether some other Calendar object's date and time is "equal to" this one.
boolean	equals(Date other) Indicates whether some other Date object's date and time is "equal to" this one.
boolean	equals(Object other) Indicates whether some other XdevDate object's date and time is "equal to" this one.
boolean	equalsDate(Object other) Indicates whether some other Date or Calendar object's date is "equal to" this one.
boolean	equalsTime(Object other) Indicates whether some other Date or Calendar object's time is "equal to" this one.
String	format(String pattern) Returns a String representation of this XdevDate.
int	get(int field)
int	getDay() Returns the day of the month of this date.
Duration	getDurationBetween(Object date) Computes the duraction between date and this XdevDate.
Duration	getDurationSince(Object sooner) Computes the duraction between sooner and this XdevDate.
Duration	getDurationUntil(Object later) Computes the duraction between this XdevDate and later.
DateFormat	getFormat() Returns the DateFormat for this XdevDate.
int	getHour() Returns the hour of this time using the 24-hour clock.
int	getMinute() Returns the minute of this time.
int	getMonth() Returns the month of this date.
int	getSecond() Returns the second of this time.
int	getYear() Returns the year of this date.
boolean	isAfter(Object date) This method is a alias for after(Object).
boolean	isBefore(Object date) This method is a alias for before(Object).
boolean	isBetween(Object startDate, Object endDate) Returns whether this XdevDate represents a date/time between the date/time represented by the specified Object startDate and endDate.
boolean	isLeapYear() Determines if the year of this XdevDate is a leap year.
XdevDate	minus(Duration duration) Creates a new XdevDate whith this moment of time minus the duration's time.
static XdevDate	now() Returns a new XdevDate using the current time in the default time zone with the default locale.
XdevDate	plus(Duration duration) Creates a new XdevDate whith this moment of time plus the duration's time.
void	roll(int field, int amount)
XdevDate	rollBack(Duration duration) Rolls this time to the past.
XdevDate	rollForward(Duration duration) Rolls this time to the future.
void	set(int field, int value)
void	setFormat(DateFormat format) Sets the DateFormat for this XdevDate.
long	timeStamp() Returns this XdevDate's time value in milliseconds.
Date	toDate() Returns a Date object representing this XdevDate's time value (millisecond offset from the Epoch").
String	toString()

Methods inherited from class java.util.GregorianCalendar

computeFields, computeTime, from, getActualMaximum, getActualMinimum, getCalendarType, getGreatestMinimum, getGregorianChange, getLeastMaximum, getMaximum, getMinimum, getTimeZone, getWeeksInWeekYear, getWeekYear, hashCode, isLeapYear, isWeekDateSupported, roll, setGregorianChange, setTimeZone, setWeekDate, toZonedDateTime

Methods inherited from class java.util.Calendar

clear, clear, compareTo, complete, getAvailableCalendarTypes, getAvailableLocales, getDisplayName, getDisplayNames, getFirstDayOfWeek, getInstance, getInstance, getInstance, getInstance, getMinimalDaysInFirstWeek, getTime, getTimeInMillis, internalGet, isLenient, isSet, set, set, set, setFirstDayOfWeek, setLenient, setMinimalDaysInFirstWeek, setTime, setTimeInMillis, toInstant

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

XdevDate

public XdevDate()

Constructs a new XdevDate using the current time in the default time zone with the default locale.

XdevDate

public XdevDate(long currentTimeMillis)

Constructs a new XdevDate using the time from the given long value.

Parameters:

currentTimeMillis - the time in UTC milliseconds from the epoch.

See Also:

Calendar.setTime(Date), Calendar.getTimeInMillis()

XdevDate

public XdevDate(int year,
                int month,
                int day)

Constructs a new XdevDate with the given date set in the default time zone with the default locale.

Parameters:

year - the value used to set the year of this date.

month - the value used to set the month of this date. Month value is 0-based. e.g., 0 for January.

day - the value used to set the day of this date.

XdevDate

public XdevDate(int year,
                int month,
                int day,
                int hour,
                int minute)

Constructs a new XdevDate with the given date set in the default time zone with the default locale.

Parameters:

year - the value used to set the year of this date.

month - the value used to set the month of this date. Month value is 0-based. e.g., 0 for January.

day - the value used to set the day of this date.

hour - the value used to set the hour of this date.

minute - the value used to set the minute of this date.

XdevDate

public XdevDate(int year,
                int month,
                int day,
                int hour,
                int minute,
                int second)

Constructs a new XdevDate with the given date set in the default time zone with the default locale.

Parameters:

year - the value used to set the year of this date.

month - the value used to set the month of this date. Month value is 0-based. e.g., 0 for January.

day - the value used to set the day of this date.

hour - the value used to set the hour of this date.

minute - the value used to set the minute of this date.

second - the value used to set the second of this date.

XdevDate

public XdevDate(Locale locale)

Constructs a XdevDate based on the current time in the default time zone with the given locale.

Parameters:

locale - the given locale.

XdevDate

public XdevDate(TimeZone zone,
                Locale locale)

Constructs a XdevDate based on the current time in the given time zone with the given locale.

Parameters:

zone - the given time zone.

locale - the given locale.

XdevDate

public XdevDate(TimeZone zone)

Constructs a XdevDate based on the current time in the given time zone with the default locale.

Parameters:

zone - the given time zone.

XdevDate

public XdevDate(Date d)

Constructs a new XdevDate using the date and time from the given Date d.

Parameters:

d - the Date to take time and date from.

XdevDate

public XdevDate(Calendar c)

Constructs a new XdevDate using the date and time from the given Calendar d.

Parameters:

c - the Calendar to take time and date from.

Method Detail

now

public static XdevDate now()

Returns a new XdevDate using the current time in the default time zone with the default locale.

Returns:

a new XdevDate

See Also:

XdevDate()

add

public void add(int field,
                int amount)

Overrides:

add in class GregorianCalendar

roll

public void roll(int field,
                 int amount)

Overrides:

roll in class GregorianCalendar

getYear

public int getYear()

Returns the year of this date.

This is a convenience method for get(XdevDate.YEAR).

Returns:

The year of this date

getMonth

public int getMonth()

Returns the month of this date.

This is a convenience method for get(XdevDate.MONTH).

Returns:

The month of this date

getDay

public int getDay()

Returns the day of the month of this date.

This is a convenience method for get(XdevDate.DAY_OF_MONTH).

Returns:

The day of the month of this date

getHour

public int getHour()

Returns the hour of this time using the 24-hour clock.

This is a convenience method for get(XdevDate.HOUR_OF_DAY).

Returns:

The hour of this time

getMinute

public int getMinute()

Returns the minute of this time.

This is a convenience method for get(XdevDate.MINUTE).

Returns:

The minute of this time

getSecond

public int getSecond()

Returns the second of this time.

This is a convenience method for get(XdevDate.SECOND).

Returns:

The second of this time

get

public int get(int field)

Overrides:

get in class Calendar

set

public void set(int field,
                int value)

Overrides:

set in class Calendar

equals

public boolean equals(Object other)

Indicates whether some other XdevDate object's date and time is "equal to" this one.

 XdevDate       christmas       = new XdevDate(2000,12,25,12,00);
 XdevDate       newYearsEve     = new XdevDate(2000,12,31,12,00);
 
 christmas.equals(newYearsEve) returns false
 christmas.equals(christmas)   returns true
 

Overrides:

equals in class GregorianCalendar

Parameters:

other - the reference object with which to compare.

Returns:

true if this object's date and time is the same as the other argument's date; false otherwise.

See Also:

equalsTime(Object), equalsDate(Object)

equals

public boolean equals(Date other)

Indicates whether some other Date object's date and time is "equal to" this one.

 XdevDate       christmas       = new XdevDate(2000,12,25,12,00);
 XdevDate       newYearsEve     = new XdevDate(2000,12,31,12,00);
 
 christmas.equals(newYearsEve) returns false
 christmas.equals(christmas)   returns true
 

Parameters:

other - the reference object with which to compare.

Returns:

true if this object's date and time is the same as the other argument's date; false otherwise.

See Also:

equalsTime(Object), equalsDate(Object)

equals

public boolean equals(Calendar other)

Indicates whether some other Calendar object's date and time is "equal to" this one.

 XdevDate       christmas       = new XdevDate(2000,12,25,12,00);
 XdevDate       newYearsEve     = new XdevDate(2000,12,31,12,00);
 
 christmas.equals(newYearsEve) returns false
 christmas.equals(christmas)   returns true
 

Parameters:

other - the reference object with which to compare.

Returns:

true if this object's date and time is the same as the other argument's date; false otherwise.

See Also:

equalsTime(Object), equalsDate(Object)

equalsDate

public boolean equalsDate(Object other)
                   throws IllegalArgumentException

Indicates whether some other Date or Calendar object's date is "equal to" this one.

 XdevDate       christmas        = new XdevDate(2000,12,25,12,00);
 XdevDate       christmasEve = new XdevDate(2000,12,24,18,00);
 
 christmas.equalsDate(christmasEve) returns false
 christmas.equalsDate(christmas)    returns true
 

Parameters:

other - the reference object with which to compare.

Returns:

true if this object's date is the same as the other argument's date; false otherwise.

Throws:

IllegalArgumentException - if other is not a instance of Calendar or Date.

See Also:

equalsTime(Object), equals(Object)

equalsTime

public boolean equalsTime(Object other)
                   throws IllegalArgumentException

Indicates whether some other Date or Calendar object's time is "equal to" this one.

 XdevDate       christmas        = new XdevDate(2000,12,25,12,00);
 XdevDate       christmasEve = new XdevDate(2000,12,24,18,00);
 XdevDate       newYearsEve      = new XdevDate(2000,12,31,12,00);
 
 christmas.equalsDate(newYearsEve)  returns true
 christmas.equalsDate(christmas)    returns true
 christmas.equalsDate(christmasEve) returns false
 

Parameters:

other - the reference object with which to compare.

Returns:

true if this object's time is the same as the other argument's time; false otherwise.

Throws:

IllegalArgumentException - if other is not a instance of Calendar or Date.

See Also:

equalsDate(Object), equalsTime(Object)

isAfter

public boolean isAfter(Object date)
                throws IllegalArgumentException

This method is a alias for after(Object).

Parameters:

date - the Object to be compared.

Returns:

true if the time of this XdevDate is after the time represented by when; false otherwise.

Throws:

IllegalArgumentException - if other is not a instance of Calendar or Date.

See Also:

after(Object), before(Object), isBefore(Object), between(Object, Object), isBetween(Object, Object)

after

public boolean after(Object date)
              throws IllegalArgumentException

Returns whether this XdevDate represents a date/time after the date/time represented by the specified Object date.

 XdevDate       christmas       = new XdevDate(2000,12,25,12,00);
 XdevDate       newYearsEve     = new XdevDate(2000,12,31,12,00);
 
 christmas.after(newYearsEve) returns false
 christmas.after(christmas)   returns false
 newYearsEve.after(christmas) returns true
 

Overrides:

after in class Calendar

Parameters:

date - the Object to be compared.

Returns:

true if the time of this XdevDate is after the time represented by when; false otherwise.

Throws:

IllegalArgumentException - if other is not a instance of Calendar or Date.

See Also:

before(Object), isBefore(Object), between(Object, Object), isBetween(Object, Object)

isBefore

public boolean isBefore(Object date)
                 throws IllegalArgumentException

This method is a alias for before(Object).

Parameters:

date - the Object to be compared.

Returns:

true if the time of this XdevDate is before the time represented by when; false otherwise.

Throws:

IllegalArgumentException - if other is not a instance of Calendar or Date.

See Also:

before(Object), after(Object), isAfter(Object), between(Object, Object), isBetween(Object, Object)

before

public boolean before(Object date)
               throws IllegalArgumentException

Returns whether this XdevDate represents a date/time before the date/time represented by the specified Object date.

 XdevDate       christmas       = new XdevDate(2000,12,25,12,00);
 XdevDate       newYearsEve     = new XdevDate(2000,12,31,12,00);
 
 christmas.before(newYearsEve) returns ture
 christmas.before(christmas)   returns false
 newYearsEve.before(christmas) returns false
 

Overrides:

before in class Calendar

Parameters:

date - the Object to be compared.

Returns:

true if the time of this XdevDate is before the time represented by when; false otherwise.

Throws:

IllegalArgumentException - if other is not a instance of Calendar or Date.

See Also:

after(Object), isAfter(Object), between(Object, Object), isBetween(Object, Object)

between

public boolean between(Object startDate,
                       Object endDate)
                throws IllegalArgumentException

This method is a alias for isBetween(Object, Object).

Parameters:

startDate - the Object to be compared.

endDate - the Object to be compared.

Returns:

true if the time of this XdevDate is before the time represented by when; false otherwise.

Throws:

IllegalArgumentException - if startDate or endDate is not a instance of Calendar or Date.

See Also:

after(Object), isAfter(Object), between(Object, Object)

isBetween

public boolean isBetween(Object startDate,
                         Object endDate)
                  throws IllegalArgumentException

Returns whether this XdevDate represents a date/time between the date/time represented by the specified Object startDate and endDate.

 XdevDate       christmasEve = new XdevDate(2000,12,24,18,00);
 XdevDate       christmas       = new XdevDate(2000,12,25,12,00);
 XdevDate       newYearsEve     = new XdevDate(2000,12,31,12,00);
 
 christmas.isBetween(christmasEve, newYearsEve) returns ture
 christmasEve.isBetween(christmas, newYearsEve) returns false
 

Parameters:

startDate - the Object to be compared.

endDate - the Object to be compared.

Returns:

true if the time of this XdevDate is before the time represented by when; false otherwise.

Throws:

IllegalArgumentException - if startDate or endDate is not a instance of Calendar or Date.

See Also:

after(Object), isAfter(Object), between(Object, Object)

isLeapYear

public boolean isLeapYear()

Determines if the year of this XdevDate is a leap year. Returns true if this year is a leap year.

Returns:

true if the year this XdevDate is a leap year; false otherwise.

setFormat

public void setFormat(DateFormat format)

Sets the DateFormat for this XdevDate.

Parameters:

format - DateFormat to be set.

getFormat

public DateFormat getFormat()

Returns the DateFormat for this XdevDate.

Returns:

DateFormat of this XdevDate.

toString

public String toString()

Overrides:

toString in class Calendar

toDate

public Date toDate()

Returns a Date object representing this XdevDate's time value (millisecond offset from the Epoch").

Returns:

a Date representing the time value.

See Also:

Calendar.setTime(Date), Calendar.getTimeInMillis()

format

public String format(String pattern)
              throws NullPointerException,
                     IllegalArgumentException

Returns a String representation of this XdevDate. Formatted according to the given pattern.

Parameters:

pattern - SimpleDateFormat pattern to format the String.

Returns:

a a String representation of this XdevDate.

Throws:

NullPointerException - if the given pattern is null

IllegalArgumentException - if the given pattern is invalid

See Also:

SimpleDateFormat

timeStamp

public long timeStamp()

Returns this XdevDate's time value in milliseconds.

Returns:

the current time as UTC milliseconds from the epoch.

See Also:

Calendar.getTime(), Calendar.setTimeInMillis(long)

getDurationUntil

public Duration getDurationUntil(Object later)

Computes the duraction between this XdevDate and later.

Parameters:

later - A future time

Returns:

The duration between this and later

getDurationSince

public Duration getDurationSince(Object sooner)

Computes the duraction between sooner and this XdevDate.

Parameters:

sooner - A past time

Returns:

The duration between sooner and this

getDurationBetween

public Duration getDurationBetween(Object date)

Computes the duraction between date and this XdevDate.

It doesn't matter if date is before this or vice versa.

Parameters:

date - A date

Returns:

The duration between date and this

rollForward

public XdevDate rollForward(Duration duration)

Rolls this time to the future.

Parameters:

duration - The duration to be added

Returns:

this

rollBack

public XdevDate rollBack(Duration duration)

Rolls this time to the past.

Parameters:

duration - The duration to be removed

Returns:

this

plus

public XdevDate plus(Duration duration)

Creates a new XdevDate whith this moment of time plus the duration's time.

Parameters:

duration - The duration to be added

Returns:

A new future XdevDate

minus

public XdevDate minus(Duration duration)

Creates a new XdevDate whith this moment of time minus the duration's time.

Parameters:

duration - The duration to be removed

Returns:

A new past XdevDate

copy

public XdevDate copy()

Creates a (defensive) copy of this XdevDate.

Returns:

a (defensive) copy of this XdevDate.

clone

public XdevDate clone()

Returns a field-for-field copy of this instance.

Specified by:

clone in interface Copyable<XdevDate>

Overrides:

clone in class GregorianCalendar

Returns:

a field-for-field copy of this instance.