org.openorb.time

Class TimeUtil

public final class TimeUtil extends Object

This class provides static methods for using the TimeBase::UtcT structure. Besides, it also supports convertions between the time value used by TimeBase::UtcT and the time value used by Java. Both Java and the TimeBase::UtcT module use the Coordinated Universal Time (UTC), but with a different time base and precision.

A time value represents a time difference, in the number of precision units, between a time and its time base. Java adapts the POSIX standard of time, which uses 1 January 1970 00:00:00 GMT as the time base and has a precision of milliseconds. The TimeBase module adapts the DCE standard of time, which uses 15 October 1582 00:00:00 GMT as the time base and POSIX and has a precision of 100 nanoseconds. (See Time Service Specification for details.)

The implementation of this class makes a short cut. The type of TimeBase::TimeT is unsigned long long, which has 64 bits. However, Java does not have native support for unsigned 64-bit integers. The implementation of this class simply uses the signed 64-bit integers. This approach has a stricter limitation on the maximum time value that can be represented than what the DCE standard specifies. Even so, this approach can still give us the ability to date to year 30810, which should be enough for most of applications.

Author: Joncheng Kuo

Field Summary
static StringDEFAULT_TIME_FORMAT
This field defines the default date/time format used in the timeToString method.
static longMAX_UTC_TIME
The maximum UTC time that can be represented in this implementation.
Method Summary
static UtcTcreateUtcT(long utcTime)
This method creates and returns a TimeBase::UtcT object from the given time with the default inaccuracy and time zone.
static UtcTcreateUtcT(long utcTime, long inaccuracy, short tdf)
This method creates and returns a TimeBase::UtcT object from the given elements.
static UtcTcurrentTimeUtcT()
This method returns a TimeBase::UtcT representing the current time.
static longgetDefaultInaccuracy()
This method returns the default inaccuracy of the current system in units of 100 ns.
static shortgetDefaultTdf()
This method returns the time displace between the current local time and the GMT in minutes.
static longgetInaccuracy(UtcT utc)
This method retrieves the inaccuracy from a TimeBase::UtcT object.
static shortgetTdf(Calendar cal)
This method returns the time displacement between a local time specified in a Calendar and the GMT in minutes.
static booleanisBefore(UtcT utc1, UtcT utc2)
This method compares the value of two UtcT.
static UtcTjavaDateToUtcT(Date date)
This method returns a TimeBase::UtcT from the given Java java.util.Date with the default inaccuracy and time zone.
static longjavaTimeToUtcTime(long time)
This method converts a POSIX UTC time value, used by Java, to a UTC time value as defined in the TimeBase module.
static StringtimeToString(UtcT utc_time)
This method returns a date/time string for the given UTC time in the default (ISO) format
static StringtimeToString(UtcT utc_time, String format_str)
This method returns a date/time string for the given UTC time in the specified format.
static StringtimeToString(long time)
This method returns a date/time string for the given time value.
static StringtimeToString(long time, String format_str)
This method returns a date/time string for the given time value.
static StringtimeToString(long time, TimeZone time_zone, String format_str)
This method derives a date/time string from the given UTC time in the format returned by Java's System.currentTimeMillis method.
static longutcTimeToJavaTime(long time)
This method converts a UTC time value, as defined in the TimeBase module, to a POSIX UTC time value, used by Java.

Field Detail

DEFAULT_TIME_FORMAT

public static final String DEFAULT_TIME_FORMAT
This field defines the default date/time format used in the timeToString method. It is defined as close as possible to the format recommended by W3C. (See http://www.w3.org/TR/NOTE-datetime). An example of the standard format is: 2003-05-08T10:08:02.00-04:00. The same time in this default format is: 2003-05-08T10:08:02.00-0400.

MAX_UTC_TIME

public static final long MAX_UTC_TIME
The maximum UTC time that can be represented in this implementation.

Method Detail

createUtcT

public static UtcT createUtcT(long utcTime)
This method creates and returns a TimeBase::UtcT object from the given time with the default inaccuracy and time zone.

Parameters: utcTime UTC time in 100 ns units

Returns: time in UtcT

createUtcT

public static UtcT createUtcT(long utcTime, long inaccuracy, short tdf)
This method creates and returns a TimeBase::UtcT object from the given elements.

Parameters: utcTime UTC time in 100 ns units inaccuracy inaccuracy time in 100 ns units tdf difference between the time zone and GMT in minutes

Returns: time in UtcT

currentTimeUtcT

public static UtcT currentTimeUtcT()
This method returns a TimeBase::UtcT representing the current time. The returned UtcT has the default inaccuracy and time zone displacement.

Returns: current time in UtcT

getDefaultInaccuracy

public static long getDefaultInaccuracy()
This method returns the default inaccuracy of the current system in units of 100 ns. Many Unix systems have inaccuracy 1 ms while Windows has 10 ms. We may need a system property to define it.

getDefaultTdf

public static short getDefaultTdf()
This method returns the time displace between the current local time and the GMT in minutes.

getInaccuracy

public static long getInaccuracy(UtcT utc)
This method retrieves the inaccuracy from a TimeBase::UtcT object.

getTdf

public static short getTdf(Calendar cal)
This method returns the time displacement between a local time specified in a Calendar and the GMT in minutes.

isBefore

public static boolean isBefore(UtcT utc1, UtcT utc2)
This method compares the value of two UtcT. It returns true if the time represented by utc1 is definitely before the time represented by utc2; false otherwise.

javaDateToUtcT

public static UtcT javaDateToUtcT(Date date)
This method returns a TimeBase::UtcT from the given Java java.util.Date with the default inaccuracy and time zone.

Parameters: date time as Java java.util.Date

Returns: time in UtcT

javaTimeToUtcTime

public static long javaTimeToUtcTime(long time)
This method converts a POSIX UTC time value, used by Java, to a UTC time value as defined in the TimeBase module.

Parameters: time a time value in the POSIX format

Returns: a time value in the TimeBase UTC format

timeToString

public static String timeToString(UtcT utc_time)
This method returns a date/time string for the given UTC time in the default (ISO) format

Parameters: utc_time time in UtcT format

Returns: a date/time string using the ISO format

timeToString

public static String timeToString(UtcT utc_time, String format_str)
This method returns a date/time string for the given UTC time in the specified format.

Parameters: utc_time time in UtcT format format_str a string specifying the date/time format

Returns: a date/time string using the given format

timeToString

public static String timeToString(long time)
This method returns a date/time string for the given time value. This time value is in milliseconds according to the POSIX standard of time. This method uses the default time zone and the default date/time format (ISO).

Parameters: time time in milliseconds; the current time zone is assumed.

Returns: a date/time string using the ISO format

timeToString

public static String timeToString(long time, String format_str)
This method returns a date/time string for the given time value. This time value is in milliseconds according to the POSIX standard of time. This method uses the default time zone.

Parameters: time time in milliseconds; the current time zone is assumed. format_str a string specifying the date/time format

Returns: a date/time string using the given format

timeToString

public static String timeToString(long time, TimeZone time_zone, String format_str)
This method derives a date/time string from the given UTC time in the format returned by Java's System.currentTimeMillis method.

Parameters: time time in milliseconds time_zone the time zone to be used in the date/time string format_str a string specifying the date/time format

Returns: a date/time string using the given format

utcTimeToJavaTime

public static long utcTimeToJavaTime(long time)
This method converts a UTC time value, as defined in the TimeBase module, to a POSIX UTC time value, used by Java.

Parameters: time a time value in the TimeBase UTC format

Returns: a time value in the POSIX format