org.openorb.time
Class TimeUtil

java.lang.Object
  extended by org.openorb.time.TimeUtil

public final class TimeUtil
extends java.lang.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 java.lang.String DEFAULT_TIME_FORMAT
          This field defines the default date/time format used in the timeToString method.
static long MAX_UTC_TIME
          The maximum UTC time that can be represented in this implementation.
 
Method Summary
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.
static UtcT createUtcT(long utcTime, long inaccuracy, short tdf)
          This method creates and returns a TimeBase::UtcT object from the given elements.
static UtcT currentTimeUtcT()
          This method returns a TimeBase::UtcT representing the current time.
static long getDefaultInaccuracy()
          This method returns the default inaccuracy of the current system in units of 100 ns.
static short getDefaultTdf()
          This method returns the time displace between the current local time and the GMT in minutes.
static long getInaccuracy(UtcT utc)
          This method retrieves the inaccuracy from a TimeBase::UtcT object.
static short getTdf(java.util.Calendar cal)
          This method returns the time displacement between a local time specified in a Calendar and the GMT in minutes.
static boolean isBefore(UtcT utc1, UtcT utc2)
          This method compares the value of two UtcT.
static UtcT javaDateToUtcT(java.util.Date date)
          This method returns a TimeBase::UtcT from the given Java Date with the default inaccuracy and time zone.
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.
static java.lang.String timeToString(long time)
          This method returns a date/time string for the given time value.
static java.lang.String timeToString(long time, java.lang.String format_str)
          This method returns a date/time string for the given time value.
static java.lang.String timeToString(long time, java.util.TimeZone time_zone, java.lang.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 java.lang.String timeToString(UtcT utc_time)
          This method returns a date/time string for the given UTC time in the default (ISO) format
static java.lang.String timeToString(UtcT utc_time, java.lang.String format_str)
          This method returns a date/time string for the given UTC time in the specified format.
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.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_UTC_TIME

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

See Also:
Constant Field Values

DEFAULT_TIME_FORMAT

public static final java.lang.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.

See Also:
Constant Field Values
Method Detail

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

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

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.


getTdf

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


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

javaDateToUtcT

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

Parameters:
date - time as Java Date
Returns:
time in UtcT

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

getInaccuracy

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


timeToString

public static java.lang.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 java.lang.String timeToString(UtcT utc_time,
                                            java.lang.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 java.lang.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 java.lang.String timeToString(long time,
                                            java.lang.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 java.lang.String timeToString(long time,
                                            java.util.TimeZone time_zone,
                                            java.lang.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

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.