org.apache.wicket.util.time
Class Duration

java.lang.Object
  org.apache.wicket.util.value.LongValue
      org.apache.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 getMilliseconds 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(Duration) and subtract(Duration) 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.

Since:

1.2.6

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 org.apache.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.slf4j.Logger log) Benchmark the given command.
static Duration	benchmark(java.lang.Runnable code) Benchmark the given command.
double	days() Retrieves the number of days of the current Duration.
static Duration	days(double days) Retrieves the Duration based on days.
static Duration	days(int days) Retrieves the Duration based on days.
static Duration	elapsed(Time start) Calculates the amount of time elapsed since start time.
long	getMilliseconds() Retrieves the number of milliseconds in this Time value.
double	hours() Retrieves the number of hours of the current Duration.
static Duration	hours(double hours) Retrieves the Duration based on hours.
static Duration	hours(int hours) Retrieves the Duration based on hours.
static Duration	milliseconds(double milliseconds) Retrieves the Duration based on milliseconds.
static Duration	milliseconds(long milliseconds) Retrieves the Duration based on milliseconds.
double	minutes() Retrieves the number of minutes of the current Duration.
static Duration	minutes(double minutes) Retrieves the Duration based on minutes.
static Duration	minutes(int minutes) Retrieves the Duration based on minutes.
double	seconds() Retrieves the number of seconds of the current Duration.
static Duration	seconds(double seconds) Retrieves the Duration based on seconds.
static Duration	seconds(int seconds) Retrieves the Duration based on seconds.
void	sleep() Sleeps for the current Duration.
Duration	subtract(Duration that) Subtracts a given Duration from this Duration.
java.lang.String	toString() Retrieves the String representation of this Duration in days, hours, minutes, seconds or milliseconds, as appropriate.
java.lang.String	toString(java.util.Locale locale) Retrieves the String representation of this Duration in days, hours, minutes, seconds or milliseconds, as appropriate.
static Duration	valueOf(long time) Retrieves 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 org.apache.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.slf4j.Logger log)

Benchmark the given command.

Parameters:

code - an ICode

log - optional logger to use with errors and exceptions

Returns:

the Time value it took to run the code

benchmark

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

Benchmark the given command.

Parameters:

code - a Runnable

Returns:

the Time value it took to run the code

days

public static Duration days(double days)

Retrieves the Duration based on days.

Parameters:

days - days double value

Returns:

the Duration based on days

days

public static Duration days(int days)

Retrieves the Duration based on days.

Parameters:

days - days int value

Returns:

the Duration based on days

elapsed

public static Duration elapsed(Time start)

Calculates the amount of time elapsed since start time.

Parameters:

start - the start Time

Returns:

the elapsed period as a Duration

Throws:

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

hours

public static Duration hours(double hours)

Retrieves the Duration based on hours.

Parameters:

hours - hours double value

Returns:

the Duration based on hours

hours

public static Duration hours(int hours)

Retrieves the Duration based on hours.

Parameters:

hours - hours int value

Returns:

the Duration based on hours

milliseconds

public static Duration milliseconds(double milliseconds)

Retrieves the Duration based on milliseconds.

Parameters:

milliseconds - milliseconds double value

Returns:

the Duration based on milliseconds

milliseconds

public static Duration milliseconds(long milliseconds)

Retrieves the Duration based on milliseconds.

Parameters:

milliseconds - milliseconds long value

Returns:

the Duration based on milliseconds

minutes

public static Duration minutes(double minutes)

Retrieves the Duration based on minutes.

Parameters:

minutes - minutes double value

Returns:

the Duration based on minutes

minutes

public static Duration minutes(int minutes)

Retrieves the Duration based on minutes.

Parameters:

minutes - minutes int value

Returns:

the Duration based on minutes

seconds

public static Duration seconds(double seconds)

Retrieves the Duration based on seconds.

Parameters:

seconds - seconds double value

Returns:

the Duration based on seconds

seconds

public static Duration seconds(int seconds)

Retrieves the Duration based on seconds.

Parameters:

seconds - seconds int value

Returns:

the Duration based on seconds

valueOf

public static Duration valueOf(long time)

Retrieves the given long as a Duration.

Parameters:

time - the duration long value in milliseconds

Returns:

the 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 - a 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 - a String to parse

locale - the 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()

Retrieves the number of days of the current Duration.

Returns:

number of days of the current Duration

hours

public final double hours()

Retrieves the number of hours of the current Duration.

Returns:

number of hours of the current Duration

minutes

public final double minutes()

Retrieves the number of minutes of the current Duration.

Returns:

number of minutes of the current Duration

seconds

public final double seconds()

Retrieves the number of seconds of the current Duration.

Returns:

number of seconds of the current Duration

sleep

public final void sleep()

Sleeps for the current Duration.

subtract

public Duration subtract(Duration that)

Subtracts a given Duration from this Duration.

Parameters:

that - the Duration to subtract

Returns:

this Duration minus that Duration

toString

public java.lang.String toString()

Retrieves 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:

a String representation

toString

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

Retrieves the String representation of this Duration in days, hours, minutes, seconds or milliseconds, as appropriate.

Parameters:

locale - a Locale

Returns:

a String representation

getMilliseconds

public final long getMilliseconds()

Retrieves the number of milliseconds in this Time value.

Returns:

the number of milliseconds in this Time value