/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.wicket.util.time;
import java.util.Locale;
import java.util.Locale.Category;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.apache.wicket.util.string.StringValue;
import org.apache.wicket.util.string.StringValueConversionException;
import org.apache.wicket.util.thread.ICode;
import org.slf4j.Logger;
/**
* A <code>Duration</code> is an immutable length of time stored as a number of milliseconds.
* Various factory and conversion methods are available for convenience.
* <p>
* These static factory methods allow easy construction of value objects using either long values
* like <code>seconds(2034)</code> or <code>hours(3)</code>:
* <p>
* <ul>
* <li><code>Duration.milliseconds(long)</code>
* <li><code>Duration.seconds(int)</code>
* <li><code>Duration.minutes(int)</code>
* <li><code>Duration.hours(int)</code>
* <li><code>Duration.days(int)</code>
* </ul>
* <p>
* ...or double-precision floating point values like <code>days(3.2)</code>:
* <p>
* <ul>
* <li><code>Duration.milliseconds(double)</code>
* <li><code>Duration.seconds(double)</code>
* <li><code>Duration.minutes(double)</code>
* <li><code>Duration.hours(double)</code>
* <li><code>Duration.days(double)</code>
* </ul>
* <p>
* In the case of <code>milliseconds(double)</code>, the value will be rounded off to the nearest
* integral millisecond using <code>Math.round()</code>.
* <p>
* The precise number of milliseconds represented by a <code>Duration</code> object can be retrieved
* by calling the <code>getMilliseconds</code> method. The value of a <code>Duration</code> 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:
* <p>
* <ul>
* <li><code>seconds()</code>
* <li><code>minutes()</code>
* <li><code>hours()</code>
* <li><code>days()</code>
* </ul>
* <p>
* Values can be added and subtracted using the <code>add(Duration)</code> and
* <code>subtract(Duration)</code> methods, each of which returns a new immutable
* <code>Duration</code> object.
* <p>
* <code>String</code> values can be converted to <code>Duration</code> objects using the static
* <code>valueOf</code> factory methods. The <code>String</code> format is the opposite of the one
* created by <code>toString()</code>, which converts a <code>Duration</code> 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 <code>String</code> values and
* are parsed as well. The <code>Locale</code> is respected and "," will be used instead of "." in
* the Eurozone.
* <p>
* The benchmark method will "benchmark" a <code>Runnable</code> or an {@link ICode} implementing
* object, returning a <code>Duration</code> object that represents the amount of time elapsed in
* running the code.
* <p>
* Finally, the <code>sleep</code> method will sleep for the value of a <code>Duration</code>.
*
* @author Jonathan Locke
* @since 1.2.6
*/
public class Duration extends AbstractTimeValue
{
private static final long serialVersionUID = 1L;
/** Constant for maximum duration. */
public static final Duration MAXIMUM = milliseconds(Long.MAX_VALUE);
/** Constant for no duration. */
public static final Duration NONE = milliseconds(0);
/** Constant for one day. */
public static final Duration ONE_DAY = days(1);
/** Constant for one hour. */
public static final Duration ONE_HOUR = hours(1);
/** Constant for on minute. */
public static final Duration ONE_MINUTE = minutes(1);
/** Constant for one second. */
public static final Duration ONE_SECOND = seconds(1);
/** Constant for one week. */
public static final Duration ONE_WEEK = days(7);
/** pattern to match strings */
private static final Pattern pattern = Pattern.compile(
"([0-9]+([.,][0-9]+)?)\\s+(millisecond|second|minute|hour|day)s?", Pattern.CASE_INSENSITIVE);
/**
* Benchmark the given command.
*
* @param code
* an <code>ICode</code>
* @param log
* optional logger to use with errors and exceptions
* @return the <code>Time</code> value it took to run the code
*/
public static Duration benchmark(final ICode code, final Logger log)
{
// Get time before running code
final Time start = Time.now();
// Run the code
code.run(log);
// Return the difference
return Time.now().subtract(start);
}
/**
* Benchmark the given command.
*
* @param code
* a <code>Runnable</code>
* @return the <code>Time</code> value it took to run the code
*/
public static Duration benchmark(final Runnable code)
{
// Get time before running code
final Time start = Time.now();
// Run code
code.run();
// Return the difference
return Time.now().subtract(start);
}
/**
* Retrieves the <code>Duration</code> based on days.
*
* @param days
* days <code>double</code> value
* @return the <code>Duration</code> based on days
*/
public static Duration days(final double days)
{
return hours(24.0 * days);
}
/**
* Retrieves the <code>Duration</code> based on days.
*
* @param days
* days <code>int</code> value
* @return the <code>Duration</code> based on days
*/
public static Duration days(final int days)
{
return hours(24 * days);
}
/**
* Calculates the amount of time elapsed since start time.
*
* @param start
* the start <code>Time</code>
* @return the elapsed period as a <code>Duration</code>
* @throws IllegalStateException
* if start <code>Time</code> is in the future
*/
public static Duration elapsed(final Time start)
{
return start.elapsedSince();
}
/**
* Retrieves the <code>Duration</code> based on hours.
*
* @param hours
* hours <code>double</code> value
* @return the <code>Duration</code> based on hours
*/
public static Duration hours(final double hours)
{
return minutes(60.0 * hours);
}
/**
* Retrieves the <code>Duration</code> based on hours.
*
* @param hours
* hours <code>int</code> value
* @return the <code>Duration</code> based on hours
*/
public static Duration hours(final int hours)
{
return minutes(60 * hours);
}
/**
* Retrieves the <code>Duration</code> based on milliseconds.
*
* @param milliseconds
* milliseconds <code>double</code> value
* @return the <code>Duration</code> based on milliseconds
*/
public static Duration milliseconds(final double milliseconds)
{
return milliseconds(Math.round(milliseconds));
}
/**
* Retrieves the <code>Duration</code> based on milliseconds.
*
* @param milliseconds
* milliseconds <code>long</code> value
* @return the <code>Duration</code> based on milliseconds
*/
public static Duration milliseconds(final long milliseconds)
{
return new Duration(milliseconds);
}
/**
* Retrieves the <code>Duration</code> based on minutes.
*
* @param minutes
* minutes <code>double</code> value
* @return the <code>Duration</code> based on minutes
*/
public static Duration minutes(final double minutes)
{
return seconds(60.0 * minutes);
}
/**
* Retrieves the <code>Duration</code> based on minutes.
*
* @param minutes
* minutes <code>int</code> value
* @return the <code>Duration</code> based on minutes
*/
public static Duration minutes(final int minutes)
{
return seconds(60 * minutes);
}
/**
* Retrieves the <code>Duration</code> based on seconds.
*
* @param seconds
* seconds <code>double</code> value
* @return the <code>Duration</code> based on seconds
*/
public static Duration seconds(final double seconds)
{
return milliseconds(seconds * 1000.0);
}
/**
* Retrieves the <code>Duration</code> based on seconds.
*
* @param seconds
* seconds <code>int</code> value
* @return the <code>Duration</code> based on seconds
*/
public static Duration seconds(final int seconds)
{
return milliseconds(seconds * 1000L);
}
/**
* Retrieves the given <code>long</code> as a <code>Duration</code>.
*
* @param time
* the duration <code>long</code> value in milliseconds
* @return the <code>Duration</code> value
*/
public static Duration valueOf(final long time)
{
return new Duration(time);
}
/**
* Converts the given <code>String</code> to a new <code>Duration</code> 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.
*
* @param string
* a <code>String</code> to parse
* @return the <code>Duration</code> value of the given <code>String</code>
* @throws StringValueConversionException
*/
public static Duration valueOf(final String string) throws StringValueConversionException
{
return valueOf(string, Locale.getDefault(Locale.Category.FORMAT));
}
/**
* Converts the given <code>String</code> to a new <code>Duration</code> 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.
*
* @param string
* a <code>String</code> to parse
* @param locale
* the <code>Locale</code> used for parsing
* @return the <code>Duration</code> value of the given <code>String</code>
* @throws StringValueConversionException
*/
public static Duration valueOf(final String string, final Locale locale)
throws StringValueConversionException
{
final Matcher matcher = pattern.matcher(string);
if (matcher.matches())
{
final double value = StringValue.valueOf(matcher.group(1), locale).toDouble();
final String units = matcher.group(3);
if (units.equalsIgnoreCase("millisecond"))
{
return milliseconds(value);
}
else if (units.equalsIgnoreCase("second"))
{
return seconds(value);
}
else if (units.equalsIgnoreCase("minute"))
{
return minutes(value);
}
else if (units.equalsIgnoreCase("hour"))
{
return hours(value);
}
else if (units.equalsIgnoreCase("day"))
{
return days(value);
}
else
{
throw new StringValueConversionException("Unrecognized units: " + string);
}
}
else
{
throw new StringValueConversionException("Unable to parse duration: " + string);
}
}
/**
* Private constructor forces use of static factory methods.
*
* @param milliseconds
* number of milliseconds in this <code>Duration</code>
*/
protected Duration(final long milliseconds)
{
super(milliseconds);
}
/**
* Adds a given <code>Duration</code> to this <code>Duration</code>.
*
* @param duration
* the <code>Duration</code> to add
* @return the sum of the <code>Duration</code>s
*/
public Duration add(final Duration duration)
{
return valueOf(getMilliseconds() + duration.getMilliseconds());
}
/**
* Retrieves the number of days of the current <code>Duration</code>.
*
* @return number of days of the current <code>Duration</code>
*/
public final double days()
{
return hours() / 24.0;
}
/**
* Retrieves the number of hours of the current <code>Duration</code>.
*
* @return number of hours of the current <code>Duration</code>
*/
public final double hours()
{
return minutes() / 60.0;
}
/**
* Retrieves the number of minutes of the current <code>Duration</code>.
*
* @return number of minutes of the current <code>Duration</code>
*/
public final double minutes()
{
return seconds() / 60.0;
}
/**
* Retrieves the number of seconds of the current <code>Duration</code>.
*
* @return number of seconds of the current <code>Duration</code>
*/
public final double seconds()
{
return getMilliseconds() / 1000.0;
}
/**
* Sleeps for the current <code>Duration</code>.
*/
public final void sleep()
{
if (getMilliseconds() > 0)
{
try
{
Thread.sleep(getMilliseconds());
}
catch (InterruptedException e)
{
// Ignored
}
}
}
/**
* Subtracts a given <code>Duration</code> from this <code>Duration</code>.
*
* @param that
* the <code>Duration</code> to subtract
* @return this <code>Duration</code> minus that <code>Duration</code>
*/
public Duration subtract(final Duration that)
{
return valueOf(getMilliseconds() - that.getMilliseconds());
}
/**
* Wait for this duration on the given monitor
*
* @param object
* The monitor to wait on
*/
public void wait(final Object object)
{
try
{
object.wait(getMilliseconds());
}
catch (InterruptedException e)
{
throw new RuntimeException(e);
}
}
/**
* Retrieves the <code>String</code> representation of this <code>Duration</code> in days,
* hours, minutes, seconds or milliseconds, as appropriate. Uses the default <code>Locale</code>
* .
*
* @return a <code>String</code> representation
*/
@Override
public String toString()
{
return toString(Locale.getDefault(Category.FORMAT));
}
/**
* Retrieves the <code>String</code> representation of this <code>Duration</code> in days,
* hours, minutes, seconds or milliseconds, as appropriate.
*
* @param locale
* a <code>Locale</code>
* @return a <code>String</code> representation
*/
public String toString(final Locale locale)
{
if (getMilliseconds() >= 0)
{
if (days() >= 1.0)
{
return unitString(days(), "day", locale);
}
if (hours() >= 1.0)
{
return unitString(hours(), "hour", locale);
}
if (minutes() >= 1.0)
{
return unitString(minutes(), "minute", locale);
}
if (seconds() >= 1.0)
{
return unitString(seconds(), "second", locale);
}
return unitString(getMilliseconds(), "millisecond", locale);
}
else
{
return "N/A";
}
}
/**
* Converts a value to a unit-suffixed value, taking care of English singular/plural suffix.
*
* @param value
* a <code>double</code> value to format
* @param units
* the units to apply singular or plural suffix to
* @param locale
* the <code>Locale</code>
* @return a <code>String</code> representation
*/
private String unitString(final double value, final String units, final Locale locale)
{
return StringValue.valueOf(value, locale) + " " + units + ((value > 1.0) ? "s" : "");
}
}