wicket.util.time
Class Duration

java.lang.Object
  wicket.util.value.LongValue
      wicket.util.time.Duration

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable

public class Duration
extends LongValue

A duration is an immutable length of time stored as a number of milliseconds. Various factory and conversion methods are available for convenience.

These static factory methods allow easy construction of value objects using either long values like seconds(2034) or hours(3):

• Duration.milliseconds(long)
• Duration.seconds(int)
• Duration.minutes(int)
• Duration.hours(int)
• Duration.days(int)

or double precision floating point values like days(3.2):

• Duration.milliseconds(double)
• Duration.seconds(double)
• Duration.minutes(double)
• Duration.hours(double)
• Duration.days(double)

In the case of milliseconds(double), the value will be rounded off to the nearest integral millisecond using Math.round().

The precise number of milliseconds represented by a Duration object can be retrieved by calling the milliseconds() method. The value of a Duration object in a given unit like days or hours can be retrieved by calling one of the following unit methods, each of which returns a double precision floating point number:

• seconds()
• minutes()
• hours()
• days()

Values can be added and subtracted using the add() and subtract() methods, each of which returns a new immutable Duration object.

String values can be converted to Duration objects using the static valueOf factory methods. The string format is the opposite of the one created by toString(), which converts a Duration object to a readable form, such as "3.2 hours" or "32.5 minutes". Valid units are: milliseconds, seconds, minutes hours and days. Correct English plural forms are used in creating string values and are parsed as well. The Locale is respected and "," will be used instead of "." in the Eurozone.

The benchmark method will "benchmark" a Runnable or an ICode implementing object, returning a Duration object that represents the amount of time elapsed in running the code.

Finally, the sleep() method will sleep for the value of a Duration.

Author:

Jonathan Locke

See Also:

Serialized Form

Field Summary

static Duration	MAXIMUM Constant for maximum duration
static Duration	NONE Constant for no duration.
static Duration	ONE_DAY Constant for one day.
static Duration	ONE_HOUR Constant for one hour.
static Duration	ONE_MINUTE Constant for on minute.
static Duration	ONE_SECOND Constant for one second.
static Duration	ONE_WEEK Constant for one week.

Fields inherited from class wicket.util.value.LongValue

value

Constructor Summary

protected

Duration(long milliseconds) Private constructor forces use of static factory methods.

Method Summary

Duration	add(Duration duration) Adds a given duration to this duration.
static Duration	benchmark(ICode code, org.apache.commons.logging.Log log)
static Duration	benchmark(java.lang.Runnable code) Benchmark the given command.
double	days() Gets number of days of the current duration.
static Duration	days(double days) Gets the duration based on days.
static Duration	days(int days) Gets the duration based on days.
static Duration	elapsed(Time start) The amount of time elapsed since start time
long	getMilliseconds()
double	hours() Gets number of hours of the current duration.
static Duration	hours(double hours) Gets the duration based on hours.
static Duration	hours(int hours) Gets the duration based on hours.
static Duration	milliseconds(double milliseconds) Gets the duration based on milliseconds.
static Duration	milliseconds(long milliseconds) Gets the duration based on miliseconds.
double	minutes() Gets number of minutes of the current duration.
static Duration	minutes(double minutes) Gets the duration based on minutes.
static Duration	minutes(int minutes) Gets the duration based on minutes.
double	seconds() Gets number of seconds of the current duration.
static Duration	seconds(double seconds) Gets the duration based on seconds.
static Duration	seconds(int seconds) Gets the duration based on seconds.
void	sleep() Sleep for the current duration.
Duration	subtract(Duration that) Subtract a given duration from this duration.
java.lang.String	toString() Gets the string representation of this duration in days, hours, minutes, seconds or milliseconds, as appropriate.
java.lang.String	toString(java.util.Locale locale) Gets the string representation of this duration in days, hours, minutes, seconds or milliseconds, as appropriate.
static Duration	valueOf(long time) Gets the given long as a duration.
static Duration	valueOf(java.lang.String string) Converts the given string to a new duration object.
static Duration	valueOf(java.lang.String string, java.util.Locale locale) Converts the given string to a new Duration object.

Methods inherited from class wicket.util.value.LongValue

compareTo, equals, greaterThan, greaterThan, hashCode, lessThan, lessThan

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MAXIMUM

public static final Duration MAXIMUM

Constant for maximum duration

NONE

public static final Duration NONE

Constant for no duration.

ONE_DAY

public static final Duration ONE_DAY

Constant for one day.

ONE_HOUR

public static final Duration ONE_HOUR

Constant for one hour.

ONE_MINUTE

public static final Duration ONE_MINUTE

Constant for on minute.

ONE_SECOND

public static final Duration ONE_SECOND

Constant for one second.

ONE_WEEK

public static final Duration ONE_WEEK

Constant for one week.

Constructor Detail

Duration

protected Duration(long milliseconds)

Private constructor forces use of static factory methods.

Parameters:

milliseconds - Number of milliseconds in this duration

Method Detail

benchmark

public static Duration benchmark(ICode code,
                                 org.apache.commons.logging.Log log)

Parameters:

code - The code

log - Optional log to use with errors and exceptions

Returns:

The duration it took to run the code

benchmark

public static Duration benchmark(java.lang.Runnable code)

Benchmark the given command.

Parameters:

code - The code

Returns:

The duration it took to run the code

days

public static Duration days(double days)

Gets the duration based on days.

Parameters:

days -

Returns:

duration

days

public static Duration days(int days)

Gets the duration based on days.

Parameters:

days -

Returns:

duration

elapsed

public static Duration elapsed(Time start)

The amount of time elapsed since start time

Parameters:

start - The start time

Returns:

The elapsed period

Throws:

java.lang.IllegalStateException - Thrown if start is in the future

hours

public static Duration hours(double hours)

Gets the duration based on hours.

Parameters:

hours -

Returns:

duration

hours

public static Duration hours(int hours)

Gets the duration based on hours.

Parameters:

hours -

Returns:

duration

milliseconds

public static Duration milliseconds(double milliseconds)

Gets the duration based on milliseconds.

Parameters:

milliseconds -

Returns:

duration

milliseconds

public static Duration milliseconds(long milliseconds)

Gets the duration based on miliseconds.

Parameters:

milliseconds -

Returns:

duration

minutes

public static Duration minutes(double minutes)

Gets the duration based on minutes.

Parameters:

minutes -

Returns:

duration

minutes

public static Duration minutes(int minutes)

Gets the duration based on minutes.

Parameters:

minutes -

Returns:

duration

seconds

public static Duration seconds(double seconds)

Gets the duration based on seconds.

Parameters:

seconds -

Returns:

duration

seconds

public static Duration seconds(int seconds)

Gets the duration based on seconds.

Parameters:

seconds -

Returns:

duration

valueOf

public static Duration valueOf(long time)

Gets the given long as a duration.

Parameters:

time - The duration value in milliseconds

Returns:

Duration value

valueOf

public static Duration valueOf(java.lang.String string)
                        throws StringValueConversionException

Converts the given string to a new duration object. The string can take the form of a floating point number followed by a number of milliseconds, seconds, minutes, hours or days. For example "6 hours" or "3.4 days". Parsing is case insensitive.

Parameters:

string - The string to parse

Returns:

The duration value of the given string

Throws:

StringValueConversionException

valueOf

public static Duration valueOf(java.lang.String string,
                               java.util.Locale locale)
                        throws StringValueConversionException

Converts the given string to a new Duration object. The string can take the form of a floating point number followed by a number of milliseconds, seconds, minutes, hours or days. For example "6 hours" or "3.4 days". Parsing is case insensitive.

Parameters:

string - The string to parse

locale - Locale used for parsing

Returns:

The duration value of the given string

Throws:

StringValueConversionException

add

public Duration add(Duration duration)

Adds a given duration to this duration.

Parameters:

duration - The duration to add

Returns:

The sum of the durations

days

public final double days()

Gets number of days of the current duration.

Returns:

number of days of the current duration

hours

public final double hours()

Gets number of hours of the current duration.

Returns:

number of hours of the current duration

minutes

public final double minutes()

Gets number of minutes of the current duration.

Returns:

number of minutes of the current duration

seconds

public final double seconds()

Gets number of seconds of the current duration.

Returns:

number of seconds of the current duration

sleep

public final void sleep()

Sleep for the current duration.

subtract

public Duration subtract(Duration that)

Subtract a given duration from this duration.

Parameters:

that - The duration to subtract

Returns:

This duration minus that duration

toString

public java.lang.String toString()

Gets the string representation of this duration in days, hours, minutes, seconds or milliseconds, as appropriate. Uses the default locale.

Overrides:

toString in class LongValue

Returns:

String representation

toString

public java.lang.String toString(java.util.Locale locale)

Gets the string representation of this duration in days, hours, minutes, seconds or milliseconds, as appropriate.

Parameters:

locale - the locale

Returns:

String representation

getMilliseconds

public final long getMilliseconds()

Returns:

Number of milliseconds in this abstract time value