org.clazzes.util.datetime
Class UtcTimestamp

java.lang.Object
  extended by org.clazzes.util.datetime.UtcTimestamp
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<UtcTimestamp>

public class UtcTimestamp
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<UtcTimestamp>, java.lang.Cloneable

A class to store UTC timestamps and timezone offset to database.

Author:
rbreuss
See Also:
Serialized Form

Field Summary
static long MILLISECONDS_PER_DAY
           
static long MILLISECONDS_PER_HOUR
           
static long MILLISECONDS_PER_MINUTE
           
static long MILLISECONDS_PER_SECOND
           
 
Constructor Summary
UtcTimestamp()
          Construct a new UtcTimestamp for the current time in the utc timezone (tzOffset=0).
UtcTimestamp(java.util.Calendar c)
          Construct a new UtcTimestamp for the passed Calendar object.
UtcTimestamp(long millis)
          Construct a new UtcTimestamp for the passed milliseconds with a tzOffset=0.
UtcTimestamp(long millis, int tzOffset)
          Construct a new UtcTimestamp for the passed milliseconds an timezone offset.
UtcTimestamp(java.lang.String s)
          Contruct an UtcTimestamp from an ISO8601-formatted string.
UtcTimestamp(java.util.TimeZone timeZone)
          Construct a new UtcTimestamp for the current time with a tzOffset for the given timezone at the current time.
UtcTimestamp(java.util.TimeZone timeZone, long millis)
          Construct a new UtcTimestamp for the passed milliseconds with a tzOffset for the given timezone at the given instance in time.
UtcTimestamp(UtcTimestamp a)
          Copy constructor.
 
Method Summary
 void add(int field, int amount)
          This method duplicates the funtionality of Calendar.add() in order to make the transition from Calendar database objects to UtcTimestamp object as easy as possible.
 void add(java.util.TimeZone timeZone, int field, int amount)
          This method duplicates the funtionality of Calendar.add() considering any change of the timezone offset of the given timezone.
 void addDays(long d)
           
 void addHours(long h)
           
 void addMilliSeconds(long ms)
           
 void addMinutes(long m)
           
 void addMonths(int m)
          Add m month to the given timestamp.
 void addSeconds(long s)
           
 void addYears(int y)
          Add m month to the given timestamp.
 boolean after(UtcTimestamp other)
          Test if this timestamp is after the passed second timestamp.
 boolean before(UtcTimestamp other)
          Test if this timestamp is before the passed second timestamp.
protected  java.lang.Object clone()
           
 UtcTimestamp cloneAdd(int field, int amount)
          Perform 'add' method to a clone of this.
 UtcTimestamp cloneAddDays(int amount)
           
 UtcTimestamp cloneAddHours(int amount)
           
 UtcTimestamp cloneAddMillis(int amount)
           
 UtcTimestamp cloneAddMinutes(int amount)
           
 UtcTimestamp cloneAddMonths(int amount)
           
 UtcTimestamp cloneAddSeconds(int amount)
           
 UtcTimestamp cloneAddYears(int amount)
           
 UtcTimestamp cloneToFirstDayOfWeek(int firstDayOfWeek, java.util.TimeZone timeZone)
          Return a deep copy of this timestamp, which is moved to the first day of the week.
 int compareTo(UtcTimestamp o)
           
static int daysBetween(UtcTimestamp t1, UtcTimestamp t2)
           
 boolean equals(java.lang.Object o)
           
 int getDay()
           
 int getDayOfWeek()
           
 int getDaysOfMonth()
           
static int getDaysOfMonth(int y, int m)
           
 int getHour()
           
 int getMilliSecond()
           
 int getMinute()
           
 int getMonth()
           
 int getSecond()
           
 java.lang.Integer getTzOffset()
           
 java.lang.Long getUtcMillis()
           
 int getYear()
           
 int hashCode()
           
 boolean isLeapYear()
           
static boolean isLeapYear(int y)
           
static int monthsBetween(UtcTimestamp t1, UtcTimestamp t2)
           
 void moveToFirstDayOfWeek(int firstDayOfWeek, java.util.TimeZone timeZone)
          Move this timestamp to the first day of the week.
static UtcTimestamp now()
           
static UtcTimestamp now(int tzOffset)
           
static UtcTimestamp now(java.util.TimeZone timeZone)
          This method duplicates the functionality of UtcTimestamp(TimeZone) for convenience reasons.
 void setDate(int year, int month, int day)
          Set the day relative to the currently effective timezone.
 void setDateTime(int year, int month, int day, int hour, int minute, int second, int ms, java.util.TimeZone timeZone)
          Set the date, time and timezone offset the given instance in time in the given timezone considering daylight savings time.
 void setDateTime(int year, int month, int day, int hour, int minute, int second, java.util.TimeZone timeZone)
          Set the date, time and timezone offset the given instance in time in the given timezone considering daylight savings time.
 void setDateTime(int year, int month, int day, int millisOfDay, java.util.TimeZone timeZone)
          Set the date, time and timezone offset the given instance in time in the given timezone considering daylight savings time.
 void setFromCalendar(java.util.Calendar c)
          Convert the passed Calendar object to UtcTimestamp.
 void setString(java.lang.String s)
          Set an ISO8601 formatted timestamp to this object.
 void setTimeOfDay(int hour, int minute, int second)
           
 void setTimeOfDay(int hour, int minute, int second, int millis)
           
 void setTzOffset(java.lang.Integer tzOffset)
           
 void setUtcMillis(java.lang.Long utcMillis)
           
 java.util.Calendar toCalendar()
          Convert this UtcTimestamp to java.util.Calendar.
 java.lang.String toString()
           
 java.lang.String toString(int format)
           
static int weeksBetween(UtcTimestamp t1, UtcTimestamp t2, int firstDayOfWeek)
           
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

MILLISECONDS_PER_SECOND

public static final long MILLISECONDS_PER_SECOND
See Also:
Constant Field Values

MILLISECONDS_PER_MINUTE

public static final long MILLISECONDS_PER_MINUTE
See Also:
Constant Field Values

MILLISECONDS_PER_HOUR

public static final long MILLISECONDS_PER_HOUR
See Also:
Constant Field Values

MILLISECONDS_PER_DAY

public static final long MILLISECONDS_PER_DAY
See Also:
Constant Field Values
Constructor Detail

UtcTimestamp

public UtcTimestamp()
Construct a new UtcTimestamp for the current time in the utc timezone (tzOffset=0). If you need the current time in your default timezone, consider using now().

See Also:
now()

UtcTimestamp

public UtcTimestamp(UtcTimestamp a)
Copy constructor.

Parameters:
a - The timestamp to be copied.

UtcTimestamp

public UtcTimestamp(java.util.Calendar c)
Construct a new UtcTimestamp for the passed Calendar object.

Parameters:
c -

UtcTimestamp

public UtcTimestamp(long millis)
Construct a new UtcTimestamp for the passed milliseconds with a tzOffset=0.

Parameters:
millis -

UtcTimestamp

public UtcTimestamp(java.util.TimeZone timeZone,
                    long millis)
Construct a new UtcTimestamp for the passed milliseconds with a tzOffset for the given timezone at the given instance in time.

Parameters:
timeZone - The Timezone for which to determine the timezone offset.
millis - The milliseconds since 1970-01-01 00:00:00 GMT.

UtcTimestamp

public UtcTimestamp(java.util.TimeZone timeZone)
Construct a new UtcTimestamp for the current time with a tzOffset for the given timezone at the current time.

Parameters:
timeZone - The Timezone for which to determine the timezone offset.

UtcTimestamp

public UtcTimestamp(long millis,
                    int tzOffset)
Construct a new UtcTimestamp for the passed milliseconds an timezone offset.

Parameters:
millis -
tzOffset - in minutes

UtcTimestamp

public UtcTimestamp(java.lang.String s)
             throws java.text.ParseException
Contruct an UtcTimestamp from an ISO8601-formatted string.

Parameters:
s - The string to parse.
Throws:
java.text.ParseException - If the timestmap is not in the ISO8601 format.
Method Detail

isLeapYear

public static boolean isLeapYear(int y)
Parameters:
y - The year in the range from 1759 to 9999.
Returns:
Whether the given year is a leap year in the gregorian calendar.

getDaysOfMonth

public static int getDaysOfMonth(int y,
                                 int m)
Parameters:
y - The year to consider.
m - The month to consider.
Returns:
The number of days in the given month.

now

public static UtcTimestamp now()
Returns:
The current timestamp with the timezone offset of the default timezone. This method is in contrast to the default constructor, which generated the current timestamp with a time zone offset of zero.
See Also:
UtcTimestamp()

now

public static UtcTimestamp now(int tzOffset)
Parameters:
tzOffset - in minutes
Returns:
The current timestamp with the given timezone offset.

now

public static UtcTimestamp now(java.util.TimeZone timeZone)
This method duplicates the functionality of UtcTimestamp(TimeZone) for convenience reasons.

Parameters:
tzOffset - in minutes
Returns:
The current timestamp with the timezone offset of the given timezone.

toCalendar

public java.util.Calendar toCalendar()
Convert this UtcTimestamp to java.util.Calendar.

Returns:

setFromCalendar

public void setFromCalendar(java.util.Calendar c)
Convert the passed Calendar object to UtcTimestamp.

Parameters:
c -

getTzOffset

public java.lang.Integer getTzOffset()
Returns:
Returns the tzOffset.

setTzOffset

public void setTzOffset(java.lang.Integer tzOffset)
Parameters:
tzOffset - The tzOffset to set.

getUtcMillis

public java.lang.Long getUtcMillis()
Returns:
Returns the utcMillis.

setUtcMillis

public void setUtcMillis(java.lang.Long utcMillis)
Parameters:
utcMillis - The utcMillis to set.

setDate

public void setDate(int year,
                    int month,
                    int day)
Set the day relative to the currently effective timezone.

Parameters:
year - The year in the range from 1759 to 9999.
month - The month in the range from 1 to 12.
day - The month in the range from 1 to 31.

setDateTime

public void setDateTime(int year,
                        int month,
                        int day,
                        int millisOfDay,
                        java.util.TimeZone timeZone)
Set the date, time and timezone offset the given instance in time in the given timezone considering daylight savings time.

Parameters:
year - The year in the range from 1759 to 9999.
month - The month in the range from 1 to 12.
day - The month in the range from 1 to 31.
millisOfDay - The milliseconds since midnight of the given day.
timeZone - The timezone to consider.

setDateTime

public void setDateTime(int year,
                        int month,
                        int day,
                        int hour,
                        int minute,
                        int second,
                        int ms,
                        java.util.TimeZone timeZone)
Set the date, time and timezone offset the given instance in time in the given timezone considering daylight savings time.

Parameters:
year - The year in the range from 1759 to 9999.
month - The month in the range from 1 to 12.
day - The month in the range from 1 to 31.
hour - The hour of the day in the range from 0 to 23.
minute - The minute of the hour in the range from 0 to 59.
second - The second of the minute in the range from 0 to 59.
ms - The millisecond of the second in the range from 0 to 999.
timeZone - The timezone to consider.

setDateTime

public void setDateTime(int year,
                        int month,
                        int day,
                        int hour,
                        int minute,
                        int second,
                        java.util.TimeZone timeZone)
Set the date, time and timezone offset the given instance in time in the given timezone considering daylight savings time.

Parameters:
year - The year in the range from 1759 to 9999.
month - The month in the range from 1 to 12.
day - The month in the range from 1 to 31.
hour - The hour of the day in the range from 0 to 23.
minute - The minute of the hour in the range from 0 to 59.
second - The second of the minute in the range from 0 to 59.
timeZone - The timezone to consider.

setTimeOfDay

public void setTimeOfDay(int hour,
                         int minute,
                         int second)
Parameters:
hour -
minute -
second -

setTimeOfDay

public void setTimeOfDay(int hour,
                         int minute,
                         int second,
                         int millis)
Parameters:
hour -
minute -
second -
millis -

getYear

public int getYear()
Returns:
The year in the range from 1759 to 9999. The returned month is relative to the local timezone, if a timezone offset is set. Zero is returned, if the thimestamp has been set to an illegal value.

getMonth

public int getMonth()
Returns:
The month in the range from 1 to 12. The returned month is relative to the local timezone, if a timezone offset is set.

getDay

public int getDay()
Returns:
The day of month in the range from 1 to 31. The returned day is relative to the local timezone, if a timezone offset is set.

getDayOfWeek

public int getDayOfWeek()
Returns:
The day of the week represented by this timestamp in the timezone designated by tzOffset.
See Also:
Calendar.SUNDAY, Calendar.MONDAY, Calendar.TUESDAY, Calendar.WEDNESDAY, Calendar.THURSDAY, Calendar.FRIDAY, Calendar.SATURDAY

getDaysOfMonth

public int getDaysOfMonth()
Returns:
The number of day in the month corresponding to the timestamp in the local timezone.

isLeapYear

public boolean isLeapYear()
Returns:
Whther the year corresponding to the timestamp in the local timezone is a leap year.

getHour

public int getHour()
Returns:
The hour of the day in the range from 0 to 23. The returned hour is relative to the local timezone, if a timezone offset is set.

getMinute

public int getMinute()
Returns:
The minutes in the range from 0 to 59.

getSecond

public int getSecond()
Returns:
The seconds in the range from 0 to 59.

getMilliSecond

public int getMilliSecond()
Returns:
The milliseconds in the ragne from 0 to 999.

addMilliSeconds

public void addMilliSeconds(long ms)
Parameters:
ms - The number of milliseconds to add.

addSeconds

public void addSeconds(long s)
Parameters:
s - The number of seconds to add.

addMinutes

public void addMinutes(long m)
Parameters:
m - The number of minutes to add.

addHours

public void addHours(long h)
Parameters:
h - The number of hours to add.

addDays

public void addDays(long d)
Parameters:
d - The number of days to add.

addMonths

public void addMonths(int m)
Add m month to the given timestamp. This method keeps the return timestamp on the last day in month, so UtcTimestamp("2007-02-28").addMonths(3) == UtcTimestamp("2007-05-31")

Parameters:
m - The number of month to add.

addYears

public void addYears(int y)
Add m month to the given timestamp. This method keeps the return timestamp on the last day in month, so UtcTimestamp("2007-02-28").addYear(-7) == UtcTimestamp("2000-02-29").

Parameters:
y - The number of years to add.

add

public void add(int field,
                int amount)
This method duplicates the funtionality of Calendar.add() in order to make the transition from Calendar database objects to UtcTimestamp object as easy as possible.

Parameters:
field - The field to increment, one of Calendar.YEAR, Calendar.MONTH, Calendar.DAY_OF_YEAR, Calendar.DAY_OF_MONTH, Calendar.HOUR, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND or Calendar.MILLISECOND.
amount - The amount to increment the given field.
See Also:
Calendar.add(int, int)

cloneAdd

public UtcTimestamp cloneAdd(int field,
                             int amount)
Perform 'add' method to a clone of this.

Parameters:
field -
amount -
Returns:

cloneAddYears

public UtcTimestamp cloneAddYears(int amount)

cloneAddMonths

public UtcTimestamp cloneAddMonths(int amount)

cloneAddDays

public UtcTimestamp cloneAddDays(int amount)

cloneAddHours

public UtcTimestamp cloneAddHours(int amount)

cloneAddMinutes

public UtcTimestamp cloneAddMinutes(int amount)

cloneAddSeconds

public UtcTimestamp cloneAddSeconds(int amount)

cloneAddMillis

public UtcTimestamp cloneAddMillis(int amount)

add

public void add(java.util.TimeZone timeZone,
                int field,
                int amount)
This method duplicates the funtionality of Calendar.add() considering any change of the timezone offset of the given timezone. If the timeZone argument is null, this method is equivalent to add(int, int).

Parameters:
timeZone - The timezone to account for or null.
field - The field to increment, one of Calendar.YEAR, Calendar.MONTH, Calendar#DAY, Calendar.DAY_OF_MONTH, Calendar.HOUR, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND or Calendar.MILLISECOND.
amount - The amount to increment the given field.
See Also:
Calendar.add(int, int)

cloneToFirstDayOfWeek

public UtcTimestamp cloneToFirstDayOfWeek(int firstDayOfWeek,
                                          java.util.TimeZone timeZone)
Return a deep copy of this timestamp, which is moved to the first day of the week. The timestamp object itself is not altered.

Parameters:
firstDayOfWeek - The first day in the week as one of the constants Calendar.SUNDAY, ..., Calendar.SATURDAY.
timeZone - The timezone used to correct the timestamp when the timezone offset changes between this day and the first day in the week.

moveToFirstDayOfWeek

public void moveToFirstDayOfWeek(int firstDayOfWeek,
                                 java.util.TimeZone timeZone)
Move this timestamp to the first day of the week.

Parameters:
firstDayOfWeek - The first day in the week as one of the constants Calendar.SUNDAY, ..., Calendar.SATURDAY.
timeZone - The timezone used to correct the timestamp when the timezone offset changes between this day and the first day in the week.

daysBetween

public static int daysBetween(UtcTimestamp t1,
                              UtcTimestamp t2)
Parameters:
t1 - The first timestamp.
t2 - The second timestamp.
Returns:
The number of day between the two timestamps.

weeksBetween

public static int weeksBetween(UtcTimestamp t1,
                               UtcTimestamp t2,
                               int firstDayOfWeek)
Parameters:
t1 - The first timestamp.
t2 - The second timestamp.
firstDayOfWeek - The first day of the week as one of the constants Calendar.SUNDAY, ..., Calendar.SATURDAY..
Returns:
The number of week between the two timestamps.

monthsBetween

public static int monthsBetween(UtcTimestamp t1,
                                UtcTimestamp t2)
Parameters:
t1 - The first timestamp.
t2 - The second timestamp.
Returns:
The number of months between the two timestamps.

toString

public java.lang.String toString(int format)
Parameters:
format - One of ISO8601Format.DATE_FORMAT, ISO8601Format.DATETIME_FORMAT, ISO8601Format.MILLISECOND_FORMAT, ISO8601Format.MILLISECOND_FORMAT_NO_TZ, or ISO8601Format.DATETIME_FORMAT_NO_TZ.
Returns:
The formatted timestamp cf. to ISO8601.

setString

public void setString(java.lang.String s)
               throws java.text.ParseException
Set an ISO8601 formatted timestamp to this object.

Throws:
java.text.ParseException - If the given string is not formatted like ISO8601.

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object
Returns:
The result of toString(ISO8601Format.MILLISECOND_FORMAT).
See Also:
toString(int), ISO8601Format.DATE_FORMAT, ISO8601Format.DATETIME_FORMAT, ISO8601Format.MILLISECOND_FORMAT

compareTo

public int compareTo(UtcTimestamp o)
Specified by:
compareTo in interface java.lang.Comparable<UtcTimestamp>

before

public boolean before(UtcTimestamp other)
Test if this timestamp is before the passed second timestamp.

Parameters:
other - the second timestamp to test against.
Returns:
true if this timestamp is before the second, false otherwise and if the second timestamp is null.

after

public boolean after(UtcTimestamp other)
Test if this timestamp is after the passed second timestamp.

Parameters:
other - the second timestamp to test against.
Returns:
true if this timestamp is after the second and if the second timestamp is null, false otherwise.

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

clone

protected java.lang.Object clone()
Overrides:
clone in class java.lang.Object

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object


Copyright © 2010. All Rights Reserved.