com.neeve.util
Class UtlTime

java.lang.Object
  com.neeve.util.UtlTime

public final class UtlTime
extends Object

Utility class containing methods to work with time.

This class IS supported for use by end users.

Configuration

The following configuration properties are applicable to this class:

• UtlConstants.TIME_USENATIVE_PROPNAME
• UtlConstants.TIME_FORMAT_PROPNAME
• UtlConstants.TIME_TIMEZONEFORMAT_PROPNAME
• UtlConstants.TIME_USEEPOCHOFFSET_PROPNAME
• UtlConstants.TIME_FORMAT_PROPNAME

Field Summary

static String	PROP_TIME_FORMAT Deprecated. Use UtlConstants.TIME_FORMAT_PROPNAME instead.
static String	PROP_TIME_FORMAT_DEFAULT Deprecated. Use UtlConstants.TIME_FORMAT_DEFAULT instead.
static String	PROP_TIME_TIMEZONEFORMAT Deprecated. Use UtlConstants.TIME_TIMEZONEFORMAT_PROPNAME instead.
static String	PROP_TIME_TIMEZONEFORMAT_DEFAULT Deprecated. Use UtlConstants.TIME_TIMEZONEFORMAT_DEFAULT instead.
static String	PROP_TIME_USEEPOCHOFFSET Deprecated. Use UtlConstants.TIME_USEEPOCHOFFSET_PROPNAME instead.
static String	PROP_TIME_USENATIVE Deprecated. Use UtlConstants.TIME_USENATIVE_PROPNAME instead.
static boolean	PROP_TIME_USENATIVE_DEFAULT Deprecated. Use UtlConstants.TIME_USENATIVE_DEFAULT instead.

Constructor Summary

UtlTime()

Method Summary

static void	cleanupFormatter() Cleans up the calling thread's ThreadLocal DateFormat
static String	format(Date date) Formats the given date using the current default timestamp format via a ThreadLocal DateFormat instance.
static DateFormat	getCachedTimestampFormatter() Get's the thread local cached, timestamp formatter with the current timestamp formatting settings.
static String	getTimestampFormat() Returns the current default timestamp format string
static DateFormat	getTimestampFormatter() Constructs a new DateFormat using the getTimestampFormat() and and dateFormatTimeZone.
static TimeZone	getTimestampFormatTimeZone() Returns the current default timestamp format string
static boolean	isEpochOffset() Deprecated. Use isEpochOffsetTimeEnabled()
static boolean	isEpochOffsetTimeEnabled() Tests whether the time returned by now() is the number of microseconds from the epoch.
static boolean	isNativeTimeEnabled()
static long	now() Return the current time in microseconds.
static long	nowSinceEpoch() Return the current wall time in microseconds.
static Date	parse(String timestamp) Attempts to parse the provide timestamp as a Date using the current timezone format.
static void	setTimestampFormat(String dateFormat) Sets the default timestamp format which is used by various platform components.
static TimeZone	setTimestampFormatTimeZone(String timezone) Sets the default date format timezone which is used by various platform components Note, that this will not affect components that have already retrieved the a dateformat unless those components resample the timezoneFormat This method looks up the timezone using TimeZone.getTimeZone(String) which will default the timezone to 'GMT' if the given timezone is not valid.
static void	setTimestampFormatTimeZone(TimeZone timezone) Sets the default date format timezone which is used by various platform components Note, that this will not affect components that have already retrieved the a dateformat unless those components resample the timezoneFormat

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROP_TIME_USENATIVE

@Deprecated
public static final String PROP_TIME_USENATIVE

Deprecated. Use UtlConstants.TIME_USENATIVE_PROPNAME instead.

See Also:

Constant Field Values

PROP_TIME_USENATIVE_DEFAULT

@Deprecated
public static final boolean PROP_TIME_USENATIVE_DEFAULT

Deprecated. Use UtlConstants.TIME_USENATIVE_DEFAULT instead.

See Also:

Constant Field Values

PROP_TIME_FORMAT

@Deprecated
public static final String PROP_TIME_FORMAT

Deprecated. Use UtlConstants.TIME_FORMAT_PROPNAME instead.

See Also:

Constant Field Values

PROP_TIME_FORMAT_DEFAULT

@Deprecated
public static final String PROP_TIME_FORMAT_DEFAULT

Deprecated. Use UtlConstants.TIME_FORMAT_DEFAULT instead.

See Also:

Constant Field Values

PROP_TIME_TIMEZONEFORMAT

@Deprecated
public static final String PROP_TIME_TIMEZONEFORMAT

Deprecated. Use UtlConstants.TIME_TIMEZONEFORMAT_PROPNAME instead.

See Also:

Constant Field Values

PROP_TIME_TIMEZONEFORMAT_DEFAULT

@Deprecated
public static final String PROP_TIME_TIMEZONEFORMAT_DEFAULT

Deprecated. Use UtlConstants.TIME_TIMEZONEFORMAT_DEFAULT instead.

See Also:

Constant Field Values

PROP_TIME_USEEPOCHOFFSET

@Deprecated
public static final String PROP_TIME_USEEPOCHOFFSET

Deprecated. Use UtlConstants.TIME_USEEPOCHOFFSET_PROPNAME instead.

See Also:

Constant Field Values

Constructor Detail

UtlTime

public UtlTime()

Method Detail

isEpochOffset

@Deprecated
public static final boolean isEpochOffset()

Deprecated. Use isEpochOffsetTimeEnabled()

isNativeTimeEnabled

public static final boolean isNativeTimeEnabled()

Returns:

true if native time is enabled.

isEpochOffsetTimeEnabled

public static final boolean isEpochOffsetTimeEnabled()

Tests whether the time returned by now() is the number of microseconds from the epoch.

If the system is configured with UtlConstants.TIME_USEEPOCHOFFSET_PROPNAME set to true the returned timestamp will represent the number of microseconds since the epoch. In such cases one can do new Date(UtlTime.now() / 1000) and arrive at a valid date. See UtlConstants.TIME_USEEPOCHOFFSET_PROPNAME for information on the provided resolution of the timestamp.

Returns:

true if the returned time is epoch offset.

now

public static final long now()

Return the current time in microseconds.

In general the time returned by the method can only be used to measure elapsed time and is not related to any other notion of system or wall-clock time.

The timestamp returned depends on how the system is configured.

• If the UtlTime is configured with UtlConstants.TIME_USEEPOCHOFFSET_PROPNAME set to true (e.g. == true, then this method returns nowSinceEpoch().
• If platform native time is enabled then the platform may use platform specific native apis to return the time.
• Otherwise this class returns System.nanoTime() / 1000.

nowSinceEpoch

public static final long nowSinceEpoch()

Return the current wall time in microseconds.

This method returns a wall clock adjusted number of microseconds since the epoch with microsecond precision, but with an accuracy limited to that of System.currentTimeMillis().

Subsequent calls to to this method can be used to compute the elapsed number of microseconds between the 2 calls, but the value returned here cannot be reliable compared to values obtained in another process even on the same host with anything but millisecond precision.

Unlike a timestamp returned by something like System.nanoTime() / 1000 one can do new Date(UtlTime.now() / 1000) and arrive at a valid date. This makes this method useful for recording timestamps that are persisted in historical log files the wall clock nature of the timestamp is useful for correlating with general wall time, but can still be used to measure elapsed time between events at microsecond precision.

See Also:

UtlConstants.TIME_USEEPOCHOFFSET_PROPNAME for more information on the provided resolution of the timestamp return by this method.

setTimestampFormat

public static final void setTimestampFormat(String dateFormat)

Sets the default timestamp format which is used by various platform components. The timestamp format is intended to include both date and time. This timestamp format is intended for use in human readable strings and would not be used in places that have an impact on encoding.

Parameters:

dateFormat - The date format to be used by getTimestampFormatter()

Throws:

IllegalArgumentException - if the dateFormat is not valid

getTimestampFormat

public static final String getTimestampFormat()

Returns the current default timestamp format string

Returns:

the current default timestamp format string

setTimestampFormatTimeZone

public static final void setTimestampFormatTimeZone(TimeZone timezone)

Sets the default date format timezone which is used by various platform components Note, that this will not affect components that have already retrieved the a dateformat unless those components resample the timezoneFormat

Parameters:

timezone - The time zone to be used by getTimestampFormat()

setTimestampFormatTimeZone

public static final TimeZone setTimestampFormatTimeZone(String timezone)

Sets the default date format timezone which is used by various platform components Note, that this will not affect components that have already retrieved the a dateformat unless those components resample the timezoneFormat

This method looks up the timezone using TimeZone.getTimeZone(String) which will default the timezone to 'GMT' if the given timezone is not valid.

Parameters:

timezone - The time zone to be used by getTimestampFormatter()

Returns:

the TimeZone that was set.

getTimestampFormatTimeZone

public static final TimeZone getTimestampFormatTimeZone()

Returns the current default timestamp format string

Returns:

the current default timestamp format string

getTimestampFormatter

public static final DateFormat getTimestampFormatter()

Constructs a new DateFormat using the getTimestampFormat() and and dateFormatTimeZone.

Returns:

A new DateFormat.

format

public static final String format(Date date)

Formats the given date using the current default timestamp format via a ThreadLocal DateFormat instance. Callers of this mehod should call cleanupFormatter() before the the calling thread is stopped.

Parameters:

date - The date to format.

Returns:

The date formatted as a timestamp.

parse

public static Date parse(String timestamp)
                  throws ParseException

Attempts to parse the provide timestamp as a Date using the current timezone format.

Parameters:

timestamp - The timestamp to parse

Returns:

The parsed date

Throws:

ParseException - if there is an error parsing the timestamp

getCachedTimestampFormatter

public static final DateFormat getCachedTimestampFormatter()

Get's the thread local cached, timestamp formatter with the current timestamp formatting settings.

Returns:

The current timestamp format for the calling thread.

cleanupFormatter

public static final void cleanupFormatter()

Cleans up the calling thread's ThreadLocal DateFormat