TimeUnit

A TimeUnit represents time durations at a given unit of granularity and provides utility methods to convert across units, and to perform timing and delay operations in these units. A TimeUnit does not maintain time information, but only helps organize and use time representations that may be maintained separately across various contexts. A nanosecond is defined as one thousandth of a microsecond, a microsecond as one thousandth of a millisecond, a millisecond as one thousandth of a second, a minute as sixty seconds, an hour as sixty minutes, and a day as twenty four hours.

A TimeUnit is mainly used to inform time-based methods how a given timing parameter should be interpreted. For example, the following code will timeout in 50 milliseconds if the lock is not available:

  Lock lock = ...;
  if ( lock.tryLock(50L, TimeUnit.MILLISECONDS) ) ...

while this code will timeout in 50 seconds:

  Lock lock = ...;
  if ( lock.tryLock(50L, TimeUnit.SECONDS) ) ...

Note however, that there is no guarantee that a particular timeout implementation will be able to notice the passage of time at the same granularity as the given TimeUnit.

Since: 1.5

Author: Doug Lea

Field Summary
static TimeUnit	DAYS
static TimeUnit	HOURS
static TimeUnit	MICROSECONDS
static TimeUnit	MILLISECONDS
static TimeUnit	MINUTES
static TimeUnit	NANOSECONDS
static TimeUnit	SECONDS

Method Summary
abstract long	convert(long sourceDuration, TimeUnit sourceUnit) Convert the given time duration in the given unit to this unit.
String	name() Returns the name of this enum constant, exactly as declared in its enum declaration.
int	ordinal() Returns the ordinal of this enumeration constant (its position in its enum declaration, where the initial constant is assigned an ordinal of zero).
protected Object	readResolve()
void	sleep(long timeout) Performs a `Thread.sleep` using this unit.
void	timedJoin(Thread thread, long timeout) Performs a timed `Thread.join` using this time unit.
void	timedWait(Object obj, long timeout) Performs a timed `Object.wait` using this time unit.
abstract long	toDays(long duration) Equivalent to `DAYS.convert(duration, this)`.
abstract long	toHours(long duration) Equivalent to `HOURS.convert(duration, this)`.
abstract long	toMicros(long duration) Equivalent to `MICROSECONDS.convert(duration, this)`.
abstract long	toMillis(long duration) Equivalent to `MILLISECONDS.convert(duration, this)`.
abstract long	toMinutes(long duration) Equivalent to `MINUTES.convert(duration, this)`.
abstract long	toNanos(long duration) Equivalent to `NANOSECONDS.convert(duration, this)`.
abstract long	toSeconds(long duration) Equivalent to `SECONDS.convert(duration, this)`.
String	toString()
static TimeUnit	valueOf(String name) Returns the enum constant of this type with the specified name.
static TimeUnit[]	values()

Convert the given time duration in the given unit to this unit. Conversions from finer to coarser granularities truncate, so lose precision. For example converting 999 milliseconds to seconds results in 0. Conversions from coarser to finer granularities with arguments that would numerically overflow saturate to Long.MIN_VALUE if negative or Long.MAX_VALUE if positive.

For example, to convert 10 minutes to milliseconds, use: TimeUnit.MILLISECONDS.convert(10L, TimeUnit.MINUTES)

Parameters: sourceDuration the time duration in the given sourceUnit sourceUnit the unit of the sourceDuration argument

Returns: the converted duration in this unit, or Long.MIN_VALUE if conversion would negatively overflow, or Long.MAX_VALUE if it would positively overflow.

name

Returns the name of this enum constant, exactly as declared in its enum declaration. Most programmers should use the toString method in preference to this one, as the toString method may return a more user-friendly name. This method is designed primarily for use in specialized situations where correctness depends on getting the exact name, which will not vary from release to release.

Returns: the name of this enum constant

ordinal

Returns the ordinal of this enumeration constant (its position in its enum declaration, where the initial constant is assigned an ordinal of zero). Most programmers will have no use for this method. It is designed for use by sophisticated enum-based data structures, such as EnumSet and EnumMap.

Returns: the ordinal of this enumeration constant

readResolve

sleep

Performs a Thread.sleep using this unit. This is a convenience method that converts time arguments into the form required by the Thread.sleep method.

Parameters: timeout the maximum time to sleep. If less than or equal to zero, do not sleep at all.

Throws: InterruptedException if interrupted while sleeping.

See Also: TimeUnit

toHours

Equivalent to HOURS.convert(duration, this).

Parameters: duration the duration