File	Doc	Category	Size	Date	Package
Duration.java	API Doc	Java SE 6 API	37130	Tue Jun 10 00:27:08 BST 2008	javax.xml.datatype

Duration

• java.lang.Object

Fields Summary
private static final boolean	DEBUG Debugging true or false.

Constructors Summary
public Duration() Default no-arg constructor. Note: Always use the {@link DatatypeFactory} to construct an instance of Duration. The constructor on this class cannot be guaranteed to produce an object with a consistent state and may be removed in the future.

Methods Summary
public abstract javax.xml.datatype.Duration	add(javax.xml.datatype.Duration rhs) Computes a new duration whose value is 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 Durations to be added are both positive without losing generality (i.e., (-X)+Y=Y-X, X+(-Y)=X-Y, (-X)+(-Y)=-(X+Y)) Addition of two positive Durations are simply defined as field by field addition where missing fields are treated as 0. A field of the resulting Duration will be unset if and only if respective fields of two input Durations are unset. Note that lhs.add(rhs) will be always successful if lhs.signum()*rhs.signum()!=-1 or both of them are normalized. param rhs Duration to add to this 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 void	addTo(java.util.Calendar calendar) 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 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 int, Duration with values beyond the range of 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 void	addTo(java.util.Date date) 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. // 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));
public abstract int	compare(javax.xml.datatype.Duration duration) Partial order relation comparison with this 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: {@link DatatypeConstants#LESSER} if this Duration is shorter than duration parameter {@link DatatypeConstants#EQUAL} if this Duration is equal to duration parameter {@link DatatypeConstants#GREATER} if this Duration is longer than duration parameter {@link DatatypeConstants#INDETERMINATE} if a conclusive partial order relation cannot be determined param duration to compare return the relationship between this Durationand duration parameter as {@link DatatypeConstants#LESSER}, {@link DatatypeConstants#EQUAL}, {@link DatatypeConstants#GREATER} or {@link DatatypeConstants#INDETERMINATE}. 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 duration is null. see #isShorterThan(Duration) see #isLongerThan(Duration)
public boolean	equals(java.lang.Object duration) Checks if this duration object has the same duration as another 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 Durations 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 Duration against. return true if this duration is the same length as duration. false if duration is null, is not a 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) if (duration == null || !(duration instanceof Duration)) { return false; } return compare((Duration) duration) == DatatypeConstants.EQUAL;
private static long	getCalendarTimeInMillis(java.util.Calendar cal) 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 cal.getTimeInMillis(). param cal Calendar to get time in milliseconds. return Milliseconds of cal. return cal.getTime().getTime();
public int	getDays() 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 Duration. return getField(DatatypeConstants.DAYS).intValue();
public abstract java.lang.Number	getField(javax.xml.datatype.DatatypeConstants$Field field) 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 field is null.
public int	getHours() 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 Duration. return getField(DatatypeConstants.HOURS).intValue();
public int	getMinutes() 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 Duration. return getField(DatatypeConstants.MINUTES).intValue();
public int	getMonths() 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 Duration. return getField(DatatypeConstants.MONTHS).intValue();
public int	getSeconds() 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) return getField(DatatypeConstants.SECONDS).intValue();
public abstract int	getSign() Returns the sign of this duration in -1,0, or 1. return -1 if this duration is negative, 0 if the duration is zero, and 1 if the duration is positive.
public long	getTimeInMillis(java.util.Calendar 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 Calendar value x, new Duration("PT10.00099S").getTimeInMills(x) == 10000. new Duration("-PT10.00099S").getTimeInMills(x) == -10000. Note that this method uses the {@link #addTo(Calendar)} method, which may work incorrectly with 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 startInstant is used to disambiguate this variance. Specifically, this method returns the difference between startInstant and startInstant+duration return milliseconds between startInstant and startInstant plus this Duration throws NullPointerException if startInstant parameter is null. Calendar cal = (Calendar) startInstant.clone(); addTo(cal); return getCalendarTimeInMillis(cal) - getCalendarTimeInMillis(startInstant);
public long	getTimeInMillis(java.util.Date 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 Date value x, new Duration("PT10.00099S").getTimeInMills(x) == 10000. new Duration("-PT10.00099S").getTimeInMills(x) == -10000. Note that this method uses the {@link #addTo(Date)} method, which may work incorrectly with 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 startInstant is used to disambiguate this variance. Specifically, this method returns the difference between startInstant and startInstant+duration. throws NullPointerException If the startInstant parameter is null. return milliseconds between startInstant and startInstant plus this Duration see #getTimeInMillis(Calendar) Calendar cal = new GregorianCalendar(); cal.setTime(startInstant); this.addTo(cal); return getCalendarTimeInMillis(cal) - startInstant.getTime();
public javax.xml.namespace.QName	getXMLSchemaType() 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)} == true. Required fields for XML Schema 1.0 Date/Time Datatypes. (timezone is optional for all date/time datatypes) 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 return one of the following constants: {@link DatatypeConstants#DURATION}, {@link DatatypeConstants#DURATION_DAYTIME} or {@link DatatypeConstants#DURATION_YEARMONTH}. throws IllegalStateException If the combination of set fields does not match one of the XML Schema date/time datatypes. boolean yearSet = isSet(DatatypeConstants.YEARS); boolean monthSet = isSet(DatatypeConstants.MONTHS); boolean daySet = isSet(DatatypeConstants.DAYS); boolean hourSet = isSet(DatatypeConstants.HOURS); boolean minuteSet = isSet(DatatypeConstants.MINUTES); boolean secondSet = isSet(DatatypeConstants.SECONDS); // DURATION if (yearSet && monthSet && daySet && hourSet && minuteSet && secondSet) { return DatatypeConstants.DURATION; } // DURATION_DAYTIME if (!yearSet && !monthSet && daySet && hourSet && minuteSet && secondSet) { return DatatypeConstants.DURATION_DAYTIME; } // DURATION_YEARMONTH if (yearSet && monthSet && !daySet && !hourSet && !minuteSet && !secondSet) { return DatatypeConstants.DURATION_YEARMONTH; } // nothing matches throw new IllegalStateException( "javax.xml.datatype.Duration#getXMLSchemaType():" + " this Duration does not match one of the XML Schema date/time datatypes:" + " year set = " + yearSet + " month set = " + monthSet + " day set = " + daySet + " hour set = " + hourSet + " minute set = " + minuteSet + " second set = " + secondSet );
public int	getYears() Get the years value of this Duration as an int or 0 if not present. getYears() is a convenience method for {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)}. As the return value is an int, an incorrect value will be returned for Durations with years that go beyond the range of an 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 int, else return 0. return getField(DatatypeConstants.YEARS).intValue();
public abstract int	hashCode() Returns a hash code consistent with the definition of the equals method. see Object#hashCode()
public boolean	isLongerThan(javax.xml.datatype.Duration duration) Checks if this duration object is strictly longer than another Duration object. Duration X is "longer" than Y if and only if X>Y as defined in the section 3.2.6.2 of the XML Schema 1.0 specification. For example, "P1D" (one day) > "PT12H" (12 hours) and "P2Y" (two years) > "P23M" (23 months). param duration Duration to test this 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 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) return compare(duration) == DatatypeConstants.GREATER;
public abstract boolean	isSet(javax.xml.datatype.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 boolean	isShorterThan(javax.xml.datatype.Duration duration) Checks if this duration object is strictly shorter than another Duration object. param duration Duration to test this Duration against. return true if duration parameter is shorter than this Duration, else 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 duration is null. see #isLongerThan(Duration duration) see #compare(Duration duration) return compare(duration) == DatatypeConstants.LESSER;
public javax.xml.datatype.Duration	multiply(int factor) Computes a new duration whose value is 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 Duration to create. return New Duration that is factortimes longer than this Duration. see #multiply(BigDecimal) return multiply(new BigDecimal(String.valueOf(factor)));
public abstract javax.xml.datatype.Duration	multiply(java.math.BigDecimal factor) Computes a new duration whose value is 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 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 Duration object throws IllegalStateException if operation produces fraction in the months field. throws NullPointerException if the factor parameter is null.
public abstract javax.xml.datatype.Duration	negate() Returns a new Duration object whose value is -this. Since the 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 Duration object.
public abstract javax.xml.datatype.Duration	normalizeWith(java.util.Calendar startTimeInstant) 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: the given Calendar object is cloned the years, months and days fields will be added to the {@link Calendar} object by using the {@link Calendar#add(int,int)} method the difference between the two Calendars in computed in milliseconds and converted to days, if a remainder occurs due to Daylight Savings Time, it is discarded the computed days, along with the hours, minutes and seconds fields of this duration object is used to construct a new Duration object. Note that since the Calendar class uses 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 Calendar reference point. return Duration of years and months of this Duration as days. throws NullPointerException If the startTimeInstant parameter is null.
public javax.xml.datatype.Duration	subtract(javax.xml.datatype.Duration rhs) Computes a new duration whose value is 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 Durations are both positive without losing generality. (i.e., (-X)-Y=-(X+Y), X-(-Y)=X+Y, (-X)-(-Y)=-(X-Y)) Then two durations are subtracted field by field. If the sign of any non-zero field F is different from the sign of the most significant field, 1 (if F is negative) or -1 (otherwise) will be borrowed from the next bigger unit of 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 Duration to subtract from this Duration. return New Duration created from subtracting rhs from this 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) return add(rhs.negate());
public java.lang.String	toString() Returns a String representation of this Duration Object. The result is formatted according to the XML Schema 1.0 spec and can be always parsed back later into the equivalent Duration Object by {@link DatatypeFactory#newDuration(String lexicalRepresentation)}. Formally, the following holds for any Duration Object x: new Duration(x.toString()).equals(x) return A non-null valid String representation of this Duration. 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();
private java.lang.String	toString(java.math.BigDecimal bd) 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 BigDecimal to format as a String return String representation of BigDecimal 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();