net.rim.device.api.util
Class DateTimeUtilities

java.lang.Object
  extended by net.rim.device.api.util.DateTimeUtilities

public final class DateTimeUtilities
extends Object

Provides access to date/time operations.

Note that time keeping on the Device uses one millisecond ticks as the base increment. The Device maintains absolute time keeping in ticks since the origin time (or midnight Jan 1, 1970).


Field Summary
static String GMT
          String used for obtaining the base GMT timezone via TimeZone.getTimeZone().
static long GUID_DATE_CHANGED
          GUID for the global event sent when the date changes.
static long GUID_TIMEZONE_CHANGED
          GUID for the global event sent when the timezone changes.
static int ONEDAY
          Number of ticks in one day.
static int ONEHOUR
          Number of ticks in one hour.
static int ONEMINUTE
          Number of ticks in one minute.
static long ONEMONTH
          Number of ticks in one one month or 4 weeks.
static int ONESECOND
          Number of ticks in one second.
static int ONEWEEK
          Number of ticks in one week.
static long ONEYEAR
          Number of ticks in one year or 365 days.
 
Method Summary
static long copyCalendar(Calendar source, Calendar destination)
          Copies a date from one calendar to another.
static void formatElapsedTime(long time, StringBuffer sb, boolean reset)
          Retrieves string representation of duration into buffer.
static int[] getCalendarFields(Calendar cal, int[] fields)
          Extracts fields from a calendar object.
static Calendar getDate(int millisSinceMidnight)
          Retrieves date relative to midnight on current day.
static Calendar getNextDate(int millisSinceMidnight)
          Retrieves future date relative to midnight on current day.
static int getNumberOfDaysInMonth(int month, int year)
          Returns the number of days in the month specified
static int getWeekOfYear(Calendar calendar, long date, int firstDayofWeek)
          Returns the number of the week in the year of the specified date.
static boolean isSameDate(long date1, long date2)
          Determine if two dates fall on the same calendar date using default TimeZone
static boolean isSameDate(long date1, long date2, TimeZone tz1, TimeZone tz2)
          Determine if two dates fall on the same calendar date
static boolean isSameDate(long date1, long date2, TimeZone tz1, TimeZone tz2, Calendar cal)
          Determine if two dates fall on the same calendar date
static boolean isWeekend()
          Determines if the current day is a weekend day.
static boolean isWeekend(Calendar cal)
          Determines if provided date falls on a weekend.
static boolean isWeekend(long date)
          Determines if the specified long integer date falls on a weekend.
static void setCalendarFields(Calendar cal, int[] fields)
          Sets field values for a calendar object.
static void zeroCalendarTime(Calendar calendar)
          Resets the calendar object to the start of its day. (00:00:00:00, hh:mm:ss:mm)
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

GUID_DATE_CHANGED

public static final long GUID_DATE_CHANGED
GUID for the global event sent when the date changes.

See Also:
Constant Field Values

GUID_TIMEZONE_CHANGED

public static final long GUID_TIMEZONE_CHANGED
GUID for the global event sent when the timezone changes.

See Also:
Constant Field Values

ONESECOND

public static final int ONESECOND
Number of ticks in one second.

See Also:
Constant Field Values

ONEMINUTE

public static final int ONEMINUTE
Number of ticks in one minute.

See Also:
Constant Field Values

ONEHOUR

public static final int ONEHOUR
Number of ticks in one hour.

See Also:
Constant Field Values

ONEDAY

public static final int ONEDAY
Number of ticks in one day.

See Also:
Constant Field Values

ONEWEEK

public static final int ONEWEEK
Number of ticks in one week.

See Also:
Constant Field Values
Since:
BlackBerry API 4.5.0

ONEMONTH

public static final long ONEMONTH
Number of ticks in one one month or 4 weeks.

See Also:
Constant Field Values
Since:
BlackBerry API 4.5.0

ONEYEAR

public static final long ONEYEAR
Number of ticks in one year or 365 days.

See Also:
Constant Field Values
Since:
BlackBerry API 4.5.0

GMT

public static String GMT
String used for obtaining the base GMT timezone via TimeZone.getTimeZone().



Method Detail

isWeekend

public static boolean isWeekend()
Determines if the current day is a weekend day.

Returns:
True if the current day is a weekend day (Saturday or Sunday, in most locales); otherwise, false.

isWeekend

public static boolean isWeekend(long date)
Determines if the specified long integer date falls on a weekend.

Parameters:
date - Date to test, measured in ticks since the origin.
Returns:
True if the provided date falls on a weekend (Saturday or Sunday, in most locales); otherwise, false.
Throws:
IllegalArgumentException - Thrown if the specified date value is less than 0.

isWeekend

public static boolean isWeekend(Calendar cal)
Determines if provided date falls on a weekend.

Parameters:
cal - Date to test.
Returns:
True if the provided date falls on a weekend (Saturday or Sunday, in most locales); otherwise, false.

getNextDate

public static Calendar getNextDate(int millisSinceMidnight)
Retrieves future date relative to midnight on current day.

Provided a number of ticks, this method returns either a time today (if the time would still be in the future relative to the current time), or a time tomorrow.

For example, if you provide the value 4 x ONEHOUR to this method, then it returns either 0400hrs on the current day (if that time is still in the future), or 0400hrs tomorrow.

Parameters:
millisSinceMidnight - Ticks since midnight.
Returns:
Future date relative to midnight.
Throws:
IllegalArgumentException - Thrown if the specified date value is less than 0.

getDate

public static Calendar getDate(int millisSinceMidnight)
Retrieves date relative to midnight on current day.

Parameters:
milisSinceMidnight - Ticks since midnight.
Returns:
Date relative to midnight on the current day; this could be a date in the past or in the future.
Throws:
IllegalArgumentException - Thrown if the specified date value is less than 0.

formatElapsedTime

public static void formatElapsedTime(long time,
                                     StringBuffer sb,
                                     boolean reset)
Retrieves string representation of duration into buffer.

This method prints out a formatted version of a duration into a buffer, providing a string like this d:hh:mm:ss if the duration involves at least one day, h:mm:ss if the duration involves at least one hour, and m:ss otherwise.

Single letters in the formats mean that the value is printed with no leading zeros; double letters in the formats mean that the value includes leading zeros padding single digit values. For example, one day, four hours, fifteen minutes, and zero seconds would appear like this: 1:04:15:00.

Parameters:
time - Length of duration in seconds.
sb - Buffer to hold the formatted duration.
reset - If true, this method truncates the buffer before appending the formatted results; if false, this method appends the results preserving the buffer's current contents.
Throws:
IllegalArgumentException - Thrown if the specified date value is less than 0.

getCalendarFields

public static int[] getCalendarFields(Calendar cal,
                                      int[] fields)
Extracts fields from a calendar object.

Invoke this method to extract the various date/time fields from a calendar object (year, month, day, hour, minute, second, tick) as integers, and store the results in an integer array.

Parameters:
cal - Source calendar object.
fields - Array to fill with the field values. If this is null, then this method allocates (and returns) a new array; if this array is too small, then this method resizes the array as needed.
Returns:
The array of fields extracted from the calendar object.

setCalendarFields

public static void setCalendarFields(Calendar cal,
                                     int[] fields)
Sets field values for a calendar object.

Invoke this method to set the various date/time fields in a calendar object (year, month, day, hour, minute, second, tick) with integers.

Parameters:
cal - Calendar object to modify.
fields - Field values; if you provide a null array, or one with less than seven elements, this method does nothing.

isSameDate

public static boolean isSameDate(long date1,
                                 long date2,
                                 TimeZone tz1,
                                 TimeZone tz2)
Determine if two dates fall on the same calendar date

Parameters:
date1 - The first date in milliseconds.
date2 - The second date in milliseconds.
tz1 - The Timezone for date1.
tz2 - The Timezone for date2 - null if tz1 is to be used as the default Timezone for both dates.
Returns:
true if it is the two dates are the same Calendar Date; false if it is not.

isSameDate

public static boolean isSameDate(long date1,
                                 long date2)
Determine if two dates fall on the same calendar date using default TimeZone

Parameters:
date1 - The first date in milliseconds.
date2 - The second date in milliseconds.
Returns:
true if it is the two dates are the same Calendar Date; false if it is not.
Since:
BlackBerry API 4.0.0

isSameDate

public static boolean isSameDate(long date1,
                                 long date2,
                                 TimeZone tz1,
                                 TimeZone tz2,
                                 Calendar cal)
Determine if two dates fall on the same calendar date

Parameters:
date1 - The first date in milliseconds.
date2 - The second date in milliseconds.
tz1 - The Timezone for date1 - if null the default timezone is used.
tz2 - The Timezone for date2 - null if tz1 is to be used as the default Timezone for both dates.
cal - Calendar object to perform date calculations, if none is provide, one is created.
Returns:
true if it is the two dates are the same Calendar Date; false if it is not.
Since:
BlackBerry API 3.6.0

copyCalendar

public static long copyCalendar(Calendar source,
                                Calendar destination)
Copies a date from one calendar to another.

Parameters:
source - The source calendar
destination - The destination calendar
Returns:
The date of the destination calendar
Since:
BlackBerry API 3.7.0

zeroCalendarTime

public static void zeroCalendarTime(Calendar calendar)
Resets the calendar object to the start of its day. (00:00:00:00, hh:mm:ss:mm)

Parameters:
source - Calendar to reset to 12am
Since:
BlackBerry API 4.0.0

getWeekOfYear

public static int getWeekOfYear(Calendar calendar,
                                long date,
                                int firstDayofWeek)
Returns the number of the week in the year of the specified date. In [ISO8601], the week number is defined by:

Parameters:
calendar - Calendar object to use for calculation - doesn't need to be initalized to the date.
date - GMT time of date you wish to obtain the week number for.
firstDayofWeek - One of Calendar.DAY_OF_WEEK, a day representing the first day of the week. For example Calendar.MONDAY. At the present time, the value of this argument is ignored. This method uses Calendar.MONDAY as the first day of the week regardless of the value specified for the firstDayofWeek parameter.
Returns:
week number defined by ISO8601
Throws:
NullPointerException - Thrown if calendar is null.
Since:
BlackBerry API 4.0.0

getNumberOfDaysInMonth

public static int getNumberOfDaysInMonth(int month,
                                         int year)
Returns the number of days in the month specified

Parameters:
month - The month to check. A valid month is between 0 and 11.
year - The year the month is in.
Returns:
The number of days in the month. If an invalid month has been specified, the return value will be -1.
Since:
BlackBerry API 4.2.1





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.