Immutable representation of a time span as defined in * the W3C XML Schema 1.0 specification. * *
A Duration object represents a period of Gregorian time, * which consists of six fields (years, months, days, hours, * minutes, and seconds) plus a sign (+/-) field. * *
The first five fields have non-negative ({@literal >=}0) integers or null * (which represents that the field is not set), * and the seconds field has a non-negative decimal or null. * A negative sign indicates a negative duration. * *
This class provides a number of methods that make it easy * to use for the duration datatype of XML Schema 1.0 with * the errata. * *
Duration objects only have partial order, where two values A and B * maybe either: *
For example, 30 days cannot be meaningfully compared to one month. * The {@link #compare(Duration duration)} method implements this * relationship. * *
See the {@link #isLongerThan(Duration)} method for details about * the order relationship among {@code Duration} objects. * *
This class provides a set of basic arithmetic operations, such * as addition, subtraction and multiplication. * Because durations don't have total order, an operation could * fail for some combinations of operations. For example, you cannot * subtract 15 days from 1 month. See the javadoc of those methods * for detailed conditions where this could happen. * *
Also, division of a duration by a number is not provided because * the {@code Duration} class can only deal with finite precision * decimal numbers. For example, one cannot represent 1 sec divided by 3. * *
However, you could substitute a division by 3 with multiplying * by numbers such as 0.3 or 0.333. * *
* Because some operations of {@code Duration} rely on {@link Calendar} * even though {@link Duration} can hold very large or very small values, * some of the methods may not work correctly on such {@code Duration}s. * The impacted methods document their dependency on {@link Calendar}. * * @author Joseph Fialli * @author Kohsuke Kawaguchi * @author Jeff Suttor * @author Sunitha Reddy * @see XMLGregorianCalendar#add(Duration) * @since 1.5 */ public abstract class Duration { /** * Debugging {@code true} or {@code false}. */ private static final boolean DEBUG = true; /** * Default no-arg constructor. * *
Note: Always use the {@link DatatypeFactory} to * construct an instance of {@code Duration}. * The constructor on this class cannot be guaranteed to * produce an object with a consistent state and may be * removed in the future. */ public Duration() { } /** * Return the name of the XML Schema date/time type that this instance * maps to. Type is computed based on fields that are set, * i.e. {@link #isSet(DatatypeConstants.Field field)} == {@code true}. * *
| Datatype | *year | *month | *day | *hour | *minute | *second | *
|---|---|---|---|---|---|---|
| {@link DatatypeConstants#DURATION} | *X | *X | *X | *X | *X | *X | *
| {@link DatatypeConstants#DURATION_DAYTIME} | ** | * | X | *X | *X | *X | *
| {@link DatatypeConstants#DURATION_YEARMONTH} | *X | *X | ** | * | * | * |
{@code getYears()} is a convenience method for * {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)}. * *
As the return value is an {@code int}, an incorrect value will be returned for {@code Duration}s * with years that go beyond the range of an {@code int}. * Use {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)} to avoid possible loss of precision. * * @return If the years field is present, return its value as an {@code int}, else return {@code 0}. */ public int getYears() { return getField(DatatypeConstants.YEARS).intValue(); } /** * Obtains the value of the MONTHS field as an integer value, * or 0 if not present. * * This method works just like {@link #getYears()} except * that this method works on the MONTHS field. * * @return Months of this {@code Duration}. */ public int getMonths() { return getField(DatatypeConstants.MONTHS).intValue(); } /** * Obtains the value of the DAYS field as an integer value, * or 0 if not present. * * This method works just like {@link #getYears()} except * that this method works on the DAYS field. * * @return Days of this {@code Duration}. */ public int getDays() { return getField(DatatypeConstants.DAYS).intValue(); } /** * Obtains the value of the HOURS field as an integer value, * or 0 if not present. * * This method works just like {@link #getYears()} except * that this method works on the HOURS field. * * @return Hours of this {@code Duration}. * */ public int getHours() { return getField(DatatypeConstants.HOURS).intValue(); } /** * Obtains the value of the MINUTES field as an integer value, * or 0 if not present. * * This method works just like {@link #getYears()} except * that this method works on the MINUTES field. * * @return Minutes of this {@code Duration}. * */ public int getMinutes() { return getField(DatatypeConstants.MINUTES).intValue(); } /** * Obtains the value of the SECONDS field as an integer value, * or 0 if not present. * * This method works just like {@link #getYears()} except * that this method works on the SECONDS field. * * @return seconds in the integer value. The fraction of seconds * will be discarded (for example, if the actual value is 2.5, * this method returns 2) */ public int getSeconds() { return getField(DatatypeConstants.SECONDS).intValue(); } /** * Returns the length of the duration in milli-seconds. * *
If the seconds field carries more digits than milli-second order, * those will be simply discarded (or in other words, rounded to zero.) * For example, for any Calendar value {@code x}, *
* {@code new Duration("PT10.00099S").getTimeInMills(x) == 10000}
* {@code new Duration("-PT10.00099S").getTimeInMills(x) == -10000}
*
*
* * Note that this method uses the {@link #addTo(Calendar)} method, * which may work incorrectly with {@code Duration} objects with * very large values in its fields. See the {@link #addTo(Calendar)} * method for details. * * @param startInstant * The length of a month/year varies. The {@code startInstant} is * used to disambiguate this variance. Specifically, this method * returns the difference between {@code startInstant} and * {@code startInstant+duration} * * @return milliseconds between {@code startInstant} and * {@code startInstant} plus this {@code Duration} * * @throws NullPointerException if {@code startInstant} parameter * is null. * */ public long getTimeInMillis(final Calendar startInstant) { Calendar cal = (Calendar) startInstant.clone(); addTo(cal); return getCalendarTimeInMillis(cal) - getCalendarTimeInMillis(startInstant); } /** * Returns the length of the duration in milli-seconds. * *
If the seconds field carries more digits than milli-second order, * those will be simply discarded (or in other words, rounded to zero.) * For example, for any {@code Date} value {@code x}, *
* {@code new Duration("PT10.00099S").getTimeInMills(x) == 10000}
* {@code new Duration("-PT10.00099S").getTimeInMills(x) == -10000}
*
*
* * Note that this method uses the {@link #addTo(Date)} method, * which may work incorrectly with {@code Duration} objects with * very large values in its fields. See the {@link #addTo(Date)} * method for details. * * @param startInstant * The length of a month/year varies. The {@code startInstant} is * used to disambiguate this variance. Specifically, this method * returns the difference between {@code startInstant} and * {@code startInstant+duration}. * * @throws NullPointerException * If the startInstant parameter is null. * * @return milliseconds between {@code startInstant} and * {@code startInstant} plus this {@code Duration} * * @see #getTimeInMillis(Calendar) */ public long getTimeInMillis(final Date startInstant) { Calendar cal = new GregorianCalendar(); cal.setTime(startInstant); this.addTo(cal); return getCalendarTimeInMillis(cal) - startInstant.getTime(); } /** * Gets the value of a field. * * Fields of a duration object may contain arbitrary large value. * Therefore this method is designed to return a {@link Number} object. * * In case of YEARS, MONTHS, DAYS, HOURS, and MINUTES, the returned * number will be a non-negative integer. In case of seconds, * the returned number may be a non-negative decimal value. * * @param field * one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, * MINUTES, or SECONDS.) * @return * If the specified field is present, this method returns * a non-null non-negative {@link Number} object that * represents its value. If it is not present, return null. * For YEARS, MONTHS, DAYS, HOURS, and MINUTES, this method * returns a {@link java.math.BigInteger} object. For SECONDS, this * method returns a {@link java.math.BigDecimal}. * * @throws NullPointerException If the {@code field} is {@code null}. */ public abstract Number getField(final DatatypeConstants.Field field); /** * Checks if a field is set. * * A field of a duration object may or may not be present. * This method can be used to test if a field is present. * * @param field * one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, * MINUTES, or SECONDS.) * @return * true if the field is present. false if not. * * @throws NullPointerException * If the field parameter is null. */ public abstract boolean isSet(final DatatypeConstants.Field field); /** * Computes a new duration whose value is {@code this+rhs}. * *
For example, *
* "1 day" + "-3 days" = "-2 days"
* "1 year" + "1 day" = "1 year and 1 day"
* "-(1 hour,50 minutes)" + "-20 minutes" = "-(1 hours,70 minutes)"
* "15 hours" + "-3 days" = "-(2 days,9 hours)"
* "1 year" + "-1 day" = IllegalStateException
*
*
* Since there's no way to meaningfully subtract 1 day from 1 month, * there are cases where the operation fails in * {@link IllegalStateException}. * *
* Formally, the computation is defined as follows. *
* Firstly, we can assume that two {@code Duration}s to be added * are both positive without losing generality (i.e., * {@code (-X)+Y=Y-X}, {@code X+(-Y)=X-Y}, * {@code (-X)+(-Y)=-(X+Y)}) * *
* Addition of two positive {@code Duration}s are simply defined as * field by field addition where missing fields are treated as 0. *
* A field of the resulting {@code Duration} will be unset if and * only if respective fields of two input {@code Duration}s are unset. *
* Note that {@code lhs.add(rhs)} will be always successful if * {@code lhs.signum()*rhs.signum()!=-1} or both of them are * normalized. * * @param rhs {@code Duration} to add to this {@code Duration} * * @return * non-null valid Duration object. * * @throws NullPointerException * If the rhs parameter is null. * @throws IllegalStateException * If two durations cannot be meaningfully added. For * example, adding negative one day to one month causes * this exception. * * * @see #subtract(Duration) */ public abstract Duration add(final Duration rhs); /** * Adds this duration to a {@link Calendar} object. * *
* Calls {@link java.util.Calendar#add(int,int)} in the * order of YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MILLISECONDS * if those fields are present. Because the {@link Calendar} class * uses int to hold values, there are cases where this method * won't work correctly (for example if values of fields * exceed the range of int.) * *
* Also, since this duration class is a Gregorian duration, this * method will not work correctly if the given {@link Calendar} * object is based on some other calendar systems. * *
* Any fractional parts of this {@code Duration} object * beyond milliseconds will be simply ignored. For example, if * this duration is "P1.23456S", then 1 is added to SECONDS, * 234 is added to MILLISECONDS, and the rest will be unused. * *
* Note that because {@link Calendar#add(int, int)} is using * {@code int}, {@code Duration} with values beyond the * range of {@code int} in its fields * will cause overflow/underflow to the given {@link Calendar}. * {@link XMLGregorianCalendar#add(Duration)} provides the same * basic operation as this method while avoiding * the overflow/underflow issues. * * @param calendar * A calendar object whose value will be modified. * @throws NullPointerException * if the calendar parameter is null. */ public abstract void addTo(Calendar calendar); /** * Adds this duration to a {@link Date} object. * *
* The given date is first converted into * a {@link java.util.GregorianCalendar}, then the duration * is added exactly like the {@link #addTo(Calendar)} method. * *
* The updated time instant is then converted back into a * {@link Date} object and used to update the given {@link Date} object. * *
* This somewhat redundant computation is necessary to unambiguously * determine the duration of months and years. * * @param date * A date object whose value will be modified. * @throws NullPointerException * if the date parameter is null. */ public void addTo(Date date) { // check data parameter if (date == null) { throw new NullPointerException( "Cannot call " + this.getClass().getName() + "#addTo(Date date) with date == null." ); } Calendar cal = new GregorianCalendar(); cal.setTime(date); this.addTo(cal); date.setTime(getCalendarTimeInMillis(cal)); } /** * Computes a new duration whose value is {@code this-rhs}. * *
For example: *
* "1 day" - "-3 days" = "4 days"
* "1 year" - "1 day" = IllegalStateException
* "-(1 hour,50 minutes)" - "-20 minutes" = "-(1hours,30 minutes)"
* "15 hours" - "-3 days" = "3 days and 15 hours"
* "1 year" - "-1 day" = "1 year and 1 day"
*
*
* Since there's no way to meaningfully subtract 1 day from 1 month, * there are cases where the operation fails in {@link IllegalStateException}. * *
Formally the computation is defined as follows. * First, we can assume that two {@code Duration}s are both positive * without losing generality. (i.e., * {@code (-X)-Y=-(X+Y)}, {@code X-(-Y)=X+Y}, * {@code (-X)-(-Y)=-(X-Y)}) * *
Then two durations are subtracted field by field. * If the sign of any non-zero field {@code F} is different from * the sign of the most significant field, * 1 (if {@code F} is negative) or -1 (otherwise) * will be borrowed from the next bigger unit of {@code F}. * *
This process is repeated until all the non-zero fields have * the same sign. * *
If a borrow occurs in the days field (in other words, if * the computation needs to borrow 1 or -1 month to compensate * days), then the computation fails by throwing an * {@link IllegalStateException}. * * @param rhs {@code Duration} to subtract from this {@code Duration}. * * @return New {@code Duration} created from subtracting {@code rhs} from this {@code Duration}. * * @throws IllegalStateException * If two durations cannot be meaningfully subtracted. For * example, subtracting one day from one month causes * this exception. * * @throws NullPointerException * If the rhs parameter is null. * * @see #add(Duration) */ public Duration subtract(final Duration rhs) { return add(rhs.negate()); } /** * Computes a new duration whose value is {@code factor} times * longer than the value of this duration. * *
This method is provided for the convenience. * It is functionally equivalent to the following code: *
* multiply(new BigDecimal(String.valueOf(factor)))
*
*
* @param factor Factor times longer of new {@code Duration} to create.
*
* @return New {@code Duration} that is {@code factor}times longer than this {@code Duration}.
*
* @see #multiply(BigDecimal)
*/
public Duration multiply(int factor) {
return multiply(new BigDecimal(String.valueOf(factor)));
}
/**
* Computes a new duration whose value is {@code factor} times
* longer than the value of this duration.
*
* * For example, *
* "P1M" (1 month) * "12" = "P12M" (12 months)
* "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds)
* "P1M" (1 month) * "1.5" = IllegalStateException
*
*
* * Since the {@code Duration} class is immutable, this method * doesn't change the value of this object. It simply computes * a new Duration object and returns it. * *
* The operation will be performed field by field with the precision * of {@link BigDecimal}. Since all the fields except seconds are * restricted to hold integers, * any fraction produced by the computation will be * carried down toward the next lower unit. For example, * if you multiply "P1D" (1 day) with "0.5", then it will be 0.5 day, * which will be carried down to "PT12H" (12 hours). * When fractions of month cannot be meaningfully carried down * to days, or year to months, this will cause an * {@link IllegalStateException} to be thrown. * For example if you multiple one month by 0.5. * *
* To avoid {@link IllegalStateException}, use * the {@link #normalizeWith(Calendar)} method to remove the years * and months fields. * * @param factor to multiply by * * @return * returns a non-null valid {@code Duration} object * * @throws IllegalStateException if operation produces fraction in * the months field. * * @throws NullPointerException if the {@code factor} parameter is * {@code null}. * */ public abstract Duration multiply(final BigDecimal factor); /** * Returns a new {@code Duration} object whose * value is {@code -this}. * *
* Since the {@code Duration} class is immutable, this method * doesn't change the value of this object. It simply computes * a new Duration object and returns it. * * @return * always return a non-null valid {@code Duration} object. */ public abstract Duration negate(); /** * Converts the years and months fields into the days field * by using a specific time instant as the reference point. * *
For example, duration of one month normalizes to 31 days * given the start time instance "July 8th 2003, 17:40:32". * *
Formally, the computation is done as follows: *
Note that since the Calendar class uses {@code int} to * hold the value of year and month, this method may produce * an unexpected result if this duration object holds * a very large value in the years or months fields. * * @param startTimeInstant {@code Calendar} reference point. * * @return {@code Duration} of years and months of this {@code Duration} as days. * * @throws NullPointerException If the startTimeInstant parameter is null. */ public abstract Duration normalizeWith(final Calendar startTimeInstant); /** * Partial order relation comparison with this {@code Duration} instance. * *
Comparison result must be in accordance with * W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, * Order relation on duration. * *
Return: *
Duration X is "longer" than Y if and only if X {@literal >} Y * as defined in the section 3.2.6.2 of the XML Schema 1.0 * specification. * *
For example, "P1D" (one day) {@literal >} "PT12H" (12 hours) and * "P2Y" (two years) {@literal >} "P23M" (23 months). * * @param duration {@code Duration} to test this {@code Duration} against. * * @throws UnsupportedOperationException If the underlying implementation * cannot reasonably process the request, e.g. W3C XML Schema allows for * arbitrarily large/small/precise values, the request may be beyond the * implementations capability. * @throws NullPointerException If {@code duration} is null. * * @return * true if the duration represented by this object * is longer than the given duration. false otherwise. * * @see #isShorterThan(Duration) * @see #compare(Duration duration) */ public boolean isLongerThan(final Duration duration) { return compare(duration) == DatatypeConstants.GREATER; } /** * Checks if this duration object is strictly shorter than * another {@code Duration} object. * * @param duration {@code Duration} to test this {@code Duration} against. * * @return {@code true} if {@code duration} parameter is shorter than this {@code Duration}, * else {@code false}. * * @throws UnsupportedOperationException If the underlying implementation * cannot reasonably process the request, e.g. W3C XML Schema allows for * arbitrarily large/small/precise values, the request may be beyond the * implementations capability. * @throws NullPointerException if {@code duration} is null. * * @see #isLongerThan(Duration duration) * @see #compare(Duration duration) */ public boolean isShorterThan(final Duration duration) { return compare(duration) == DatatypeConstants.LESSER; } /** * Checks if this duration object has the same duration * as another {@code Duration} object. * *
For example, "P1D" (1 day) is equal to "PT24H" (24 hours). * *
Duration X is equal to Y if and only if time instant * t+X and t+Y are the same for all the test time instants * specified in the section 3.2.6.2 of the XML Schema 1.0 * specification. * *
Note that there are cases where two {@code Duration}s are * "incomparable" to each other, like one month and 30 days. * For example, *
* !new Duration("P1M").isShorterThan(new Duration("P30D"))
* !new Duration("P1M").isLongerThan(new Duration("P30D"))
* !new Duration("P1M").equals(new Duration("P30D"))
*
*
* @param duration
* The object to compare this {@code Duration} against.
*
* @return
* {@code true} if this duration is the same length as
* {@code duration}.
* {@code false} if {@code duration} is {@code null},
* is not a
* {@code Duration} object,
* or its length is different from this duration.
*
* @throws UnsupportedOperationException If the underlying implementation
* cannot reasonably process the request, e.g. W3C XML Schema allows for
* arbitrarily large/small/precise values, the request may be beyond the
* implementations capability.
*
* @see #compare(Duration duration)
*/
public boolean equals(final Object duration) {
if (duration == null || !(duration instanceof Duration)) {
return false;
}
return compare((Duration) duration) == DatatypeConstants.EQUAL;
}
/**
* Returns a hash code consistent with the definition of the equals method.
*
* @see Object#hashCode()
*/
public abstract int hashCode();
/**
* Returns a {@code String} representation of this {@code Duration Object}.
*
* The result is formatted according to the XML Schema 1.0 spec * and can be always parsed back later into the * equivalent {@code Duration Object} by {@link DatatypeFactory#newDuration(String lexicalRepresentation)}. * *
Formally, the following holds for any {@code Duration} * {@code Object} x: *
* new Duration(x.toString()).equals(x)
*
*
* @return A non-{@code null} valid {@code String} representation of this {@code Duration}.
*/
public String toString() {
StringBuffer buf = new StringBuffer();
if (getSign() < 0) {
buf.append('-');
}
buf.append('P');
BigInteger years = (BigInteger) getField(DatatypeConstants.YEARS);
if (years != null) {
buf.append(years + "Y");
}
BigInteger months = (BigInteger) getField(DatatypeConstants.MONTHS);
if (months != null) {
buf.append(months + "M");
}
BigInteger days = (BigInteger) getField(DatatypeConstants.DAYS);
if (days != null) {
buf.append(days + "D");
}
BigInteger hours = (BigInteger) getField(DatatypeConstants.HOURS);
BigInteger minutes = (BigInteger) getField(DatatypeConstants.MINUTES);
BigDecimal seconds = (BigDecimal) getField(DatatypeConstants.SECONDS);
if (hours != null || minutes != null || seconds != null) {
buf.append('T');
if (hours != null) {
buf.append(hours + "H");
}
if (minutes != null) {
buf.append(minutes + "M");
}
if (seconds != null) {
buf.append(toString(seconds) + "S");
}
}
return buf.toString();
}
/**
* Turns {@link BigDecimal} to a string representation.
*
* Due to a behavior change in the {@link BigDecimal#toString()} * method in JDK1.5, this had to be implemented here. * * @param bd {@code BigDecimal} to format as a {@code String} * * @return {@code String} representation of {@code BigDecimal} */ private String toString(BigDecimal bd) { String intString = bd.unscaledValue().toString(); int scale = bd.scale(); if (scale == 0) { return intString; } /* Insert decimal point */ StringBuffer buf; int insertionPoint = intString.length() - scale; if (insertionPoint == 0) { /* Point goes right before intVal */ return "0." + intString; } else if (insertionPoint > 0) { /* Point goes inside intVal */ buf = new StringBuffer(intString); buf.insert(insertionPoint, '.'); } else { /* We must insert zeros between point and intVal */ buf = new StringBuffer(3 - insertionPoint + intString.length()); buf.append("0."); for (int i = 0; i < -insertionPoint; i++) { buf.append('0'); } buf.append(intString); } return buf.toString(); } /** * Calls the {@link Calendar#getTimeInMillis} method. * Prior to JDK1.4, this method was protected and therefore * cannot be invoked directly. * *
TODO: In future, this should be replaced by {@code cal.getTimeInMillis()}. * * @param cal {@code Calendar} to get time in milliseconds. * * @return Milliseconds of {@code cal}. */ private static long getCalendarTimeInMillis(final Calendar cal) { return cal.getTime().getTime(); } }