net.rim.device.api.util
Class DateTimeUtilities

java.lang.Object
  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	isLeapYear(int year) Determines if a year is a leap year using the rules defined in Wikipedia.
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

isLeapYear

public static boolean isLeapYear(int year)

Determines if a year is a leap year using the rules defined in Wikipedia.

Note: Unlike GregorianCalendar, this does not handle dates prior to the Gregorian cutover year, which is 1582. If year values less than 1582, including negative values, are passed in to this method, it will still return corresponding boolean return values without throwing an exception, but the results are invalid.

Parameters:

year - the year to check. It should be greater than or equal to 1582.

Returns:

true if and only if year is a leap year.

See Also:

http://en.wikipedia.org/wiki/Leap_year

Since:

BlackBerry API 7.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:

• Weeks start on a Monday.
• Week 1 of a given year is the one that includes the first Thursday of that year. (or, equivalently, week 1 is the week that includes 4 January.) This means that the days before week 1 in a given year are attributed to the last week of the previous year. Also the days that come after the last week of a given year are attributed to the first week of the next year.

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