| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
|
| <!--NewPage-->
|
| <HTML>
|
| <HEAD>
|
| <!-- Generated by javadoc on Thu Nov 22 17:12:53 EST 2007 -->
|
| <TITLE>
|
| Xalan-Java 2.7.1: Class Duration
|
| </TITLE>
|
| <LINK REL ="stylesheet" TYPE="text/css" HREF="../../../stylesheet.css" TITLE="Style">
|
| </HEAD>
|
| <BODY BGCOLOR="white">
|
|
|
| <!-- ========== START OF NAVBAR ========== -->
|
| <A NAME="navbar_top"><!-- --></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
|
| <TR>
|
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
|
| <A NAME="navbar_top_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
|
| <TR ALIGN="center" VALIGN="top">
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
|
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/Duration.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
|
| </TR>
|
| </TABLE>
|
| </TD>
|
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
|
| </EM>
|
| </TD>
|
| </TR>
|
|
|
| <TR>
|
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
| <A HREF="../../../javax/xml/datatype/DatatypeFactory.html"><B>PREV CLASS</B></A>
|
| <A HREF="../../../javax/xml/datatype/XMLGregorianCalendar.html"><B>NEXT CLASS</B></A></FONT></TD>
|
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
| <A HREF="../../../index.html" TARGET="_top"><B>FRAMES</B></A>
|
| <A HREF="Duration.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
|
| </TR>
|
| <TR>
|
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
|
| SUMMARY: INNER | FIELD | <A HREF="#constructor_summary">CONSTR</A> | <A HREF="#method_summary">METHOD</A></FONT></TD>
|
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
|
| DETAIL: FIELD | <A HREF="#constructor_detail">CONSTR</A> | <A HREF="#method_detail">METHOD</A></FONT></TD>
|
| </TR>
|
| </TABLE>
|
| <!-- =========== END OF NAVBAR =========== -->
|
|
|
| <HR>
|
| <!-- ======== START OF CLASS DATA ======== -->
|
| <H2>
|
| <FONT SIZE="-1">
|
| javax.xml.datatype</FONT>
|
| <BR>
|
| Class Duration</H2>
|
| <PRE>
|
| java.lang.Object
|
| |
|
| +--<B>javax.xml.datatype.Duration</B>
|
| </PRE>
|
| <HR>
|
| <DL>
|
| <DT>public abstract class <B>Duration</B><DT>extends java.lang.Object</DL>
|
|
|
| <P>
|
| <p>Immutable representation of a time span as defined in |
| the W3C XML Schema 1.0 specification.</p> |
| |
| <p>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.</p> |
| |
| <p>The first five fields have non-negative (>=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.</p> |
| |
| <p>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.</p> |
| |
| <h2>Order relationship</h2> |
| <p>Duration objects only have partial order, where two values A and B |
| maybe either:</p> |
| <ol> |
| <li>A<B (A is shorter than B) |
| <li>A>B (A is longer than B) |
| <li>A==B (A and B are of the same duration) |
| <li>A<>B (Comparison between A and B is indeterminate) |
| </ol> |
| |
| <p>For example, 30 days cannot be meaningfully compared to one month. |
| The <A HREF="../../../javax/xml/datatype/Duration.html#compare(javax.xml.datatype.Duration)"><CODE>compare(Duration duration)</CODE></A> method implements this |
| relationship.</p> |
| |
| <p>See the <A HREF="../../../javax/xml/datatype/Duration.html#isLongerThan(javax.xml.datatype.Duration)"><CODE>isLongerThan(Duration)</CODE></A> method for details about |
| the order relationship among <code>Duration</code> objects.</p> |
| |
| <h2>Operations over Duration</h2> |
| <p>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.</p> |
| |
| <p>Also, division of a duration by a number is not provided because |
| the <code>Duration</code> class can only deal with finite precision |
| decimal numbers. For example, one cannot represent 1 sec divided by 3.</p> |
| |
| <p>However, you could substitute a division by 3 with multiplying |
| by numbers such as 0.3 or 0.333.</p> |
| |
| <h2>Range of allowed values</h2> |
| <p> |
| Because some operations of <code>Duration</code> rely on <CODE>Calendar</CODE> |
| even though <A HREF="../../../javax/xml/datatype/Duration.html"><CODE>Duration</CODE></A> can hold very large or very small values, |
| some of the methods may not work correctly on such <code>Duration</code>s. |
| The impacted methods document their dependency on <CODE>Calendar</CODE>.
|
| <P>
|
| <DL>
|
| <DT><B>Since: </B><DD>1.5</DD>
|
| <DT><B>See Also: </B><DD><A HREF="../../../javax/xml/datatype/XMLGregorianCalendar.html#add(javax.xml.datatype.Duration)"><CODE>XMLGregorianCalendar.add(Duration)</CODE></A></DL>
|
| <HR>
|
|
|
| <P>
|
| <!-- ======== INNER CLASS SUMMARY ======== -->
|
|
|
|
|
| <!-- =========== FIELD SUMMARY =========== -->
|
|
|
|
|
| <!-- ======== CONSTRUCTOR SUMMARY ======== -->
|
|
|
| <A NAME="constructor_summary"><!-- --></A> |
| <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
|
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
|
| <TD COLSPAN=2><FONT SIZE="+2">
|
| <B>Constructor Summary</B></FONT></TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#Duration()">Duration</A></B>()</CODE>
|
|
|
| <BR>
|
| </TD>
|
| </TR>
|
| </TABLE>
|
|
|
| <!-- ========== METHOD SUMMARY =========== -->
|
|
|
| <A NAME="method_summary"><!-- --></A> |
| <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
|
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
|
| <TD COLSPAN=2><FONT SIZE="+2">
|
| <B>Method Summary</B></FONT></TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE>abstract <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A></CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#add(javax.xml.datatype.Duration)">add</A></B>(<A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> rhs)</CODE>
|
|
|
| <BR>
|
| Computes a new duration whose value is <code>this+rhs</code>.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE>abstract void</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#addTo(java.util.Calendar)">addTo</A></B>(java.util.Calendar calendar)</CODE>
|
|
|
| <BR>
|
| Adds this duration to a <CODE>Calendar</CODE> object.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> void</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#addTo(java.util.Date)">addTo</A></B>(java.util.Date date)</CODE>
|
|
|
| <BR>
|
| Adds this duration to a <CODE>Date</CODE> object.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE>abstract int</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#compare(javax.xml.datatype.Duration)">compare</A></B>(<A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> duration)</CODE>
|
|
|
| <BR>
|
| Partial order relation comparison with this <code>Duration</code> instance.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> boolean</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#equals(java.lang.Object)">equals</A></B>(java.lang.Object duration)</CODE>
|
|
|
| <BR>
|
| Checks if this duration object has the same duration |
| as another <code>Duration</code> object.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> int</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#getDays()">getDays</A></B>()</CODE>
|
|
|
| <BR>
|
| Obtains the value of the DAYS field as an integer value, |
| or 0 if not present.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE>abstract java.lang.Number</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#getField(javax.xml.datatype.DatatypeConstants.Field)">getField</A></B>(<A HREF="../../../javax/xml/datatype/DatatypeConstants.Field.html">DatatypeConstants.Field</A> field)</CODE>
|
|
|
| <BR>
|
| Gets the value of a field.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> int</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#getHours()">getHours</A></B>()</CODE>
|
|
|
| <BR>
|
| Obtains the value of the HOURS field as an integer value, |
| or 0 if not present.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> int</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#getMinutes()">getMinutes</A></B>()</CODE>
|
|
|
| <BR>
|
| Obtains the value of the MINUTES field as an integer value, |
| or 0 if not present.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> int</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#getMonths()">getMonths</A></B>()</CODE>
|
|
|
| <BR>
|
| Obtains the value of the MONTHS field as an integer value, |
| or 0 if not present.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> int</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#getSeconds()">getSeconds</A></B>()</CODE>
|
|
|
| <BR>
|
| Obtains the value of the SECONDS field as an integer value, |
| or 0 if not present.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE>abstract int</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#getSign()">getSign</A></B>()</CODE>
|
|
|
| <BR>
|
| Returns the sign of this duration in -1,0, or 1.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> long</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#getTimeInMillis(java.util.Calendar)">getTimeInMillis</A></B>(java.util.Calendar startInstant)</CODE>
|
|
|
| <BR>
|
| Returns the length of the duration in milli-seconds.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> long</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#getTimeInMillis(java.util.Date)">getTimeInMillis</A></B>(java.util.Date startInstant)</CODE>
|
|
|
| <BR>
|
| Returns the length of the duration in milli-seconds.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> <A HREF="../../../javax/xml/namespace/QName.html">QName</A></CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#getXMLSchemaType()">getXMLSchemaType</A></B>()</CODE>
|
|
|
| <BR>
|
| Return the name of the XML Schema date/time type that this instance |
| maps to.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> int</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#getYears()">getYears</A></B>()</CODE>
|
|
|
| <BR>
|
| Get the years value of this <code>Duration</code> as an <code>int</code> or <code>0</code> if not present.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE>abstract int</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#hashCode()">hashCode</A></B>()</CODE>
|
|
|
| <BR>
|
| Returns a hash code consistent with the definition of the equals method.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> boolean</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#isLongerThan(javax.xml.datatype.Duration)">isLongerThan</A></B>(<A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> duration)</CODE>
|
|
|
| <BR>
|
| Checks if this duration object is strictly longer than |
| another <code>Duration</code> object.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE>abstract boolean</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#isSet(javax.xml.datatype.DatatypeConstants.Field)">isSet</A></B>(<A HREF="../../../javax/xml/datatype/DatatypeConstants.Field.html">DatatypeConstants.Field</A> field)</CODE>
|
|
|
| <BR>
|
| Checks if a field is set.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> boolean</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#isShorterThan(javax.xml.datatype.Duration)">isShorterThan</A></B>(<A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> duration)</CODE>
|
|
|
| <BR>
|
| Checks if this duration object is strictly shorter than |
| another <code>Duration</code> object.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE>abstract <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A></CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#multiply(java.math.BigDecimal)">multiply</A></B>(java.math.BigDecimal factor)</CODE>
|
|
|
| <BR>
|
| Computes a new duration whose value is <code>factor</code> times |
| longer than the value of this duration.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A></CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#multiply(int)">multiply</A></B>(int factor)</CODE>
|
|
|
| <BR>
|
| Computes a new duration whose value is <code>factor</code> times |
| longer than the value of this duration.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE>abstract <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A></CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#negate()">negate</A></B>()</CODE>
|
|
|
| <BR>
|
| Returns a new <code>Duration</code> object whose |
| value is <code>-this</code>.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE>abstract <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A></CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#normalizeWith(java.util.Calendar)">normalizeWith</A></B>(java.util.Calendar startTimeInstant)</CODE>
|
|
|
| <BR>
|
| Converts the years and months fields into the days field |
| by using a specific time instant as the reference point.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A></CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#subtract(javax.xml.datatype.Duration)">subtract</A></B>(<A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> rhs)</CODE>
|
|
|
| <BR>
|
| Computes a new duration whose value is <code>this-rhs</code>.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> java.lang.String</CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../javax/xml/datatype/Duration.html#toString()">toString</A></B>()</CODE>
|
|
|
| <BR>
|
| Returns a <code>String</code> representation of this <code>Duration</code> <code>Object</code>.</TD>
|
| </TR>
|
| </TABLE>
|
| <A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A> |
| <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
|
| <TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
|
| <TD><B>Methods inherited from class java.lang.Object</B></TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD><CODE>getClass,
|
| notify,
|
| notifyAll,
|
| wait,
|
| wait,
|
| wait</CODE></TD>
|
| </TR>
|
| </TABLE>
|
|
|
| <P>
|
|
|
| <!-- ============ FIELD DETAIL =========== -->
|
|
|
|
|
| <!-- ========= CONSTRUCTOR DETAIL ======== -->
|
|
|
| <A NAME="constructor_detail"><!-- --></A> |
| <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
|
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
|
| <TD COLSPAN=1><FONT SIZE="+2">
|
| <B>Constructor Detail</B></FONT></TD>
|
| </TR>
|
| </TABLE>
|
|
|
| <A NAME="Duration()"><!-- --></A><H3>
|
| Duration</H3>
|
| <PRE>
|
| public <B>Duration</B>()</PRE>
|
| <DL>
|
| </DL>
|
|
|
| <!-- ============ METHOD DETAIL ========== -->
|
|
|
| <A NAME="method_detail"><!-- --></A> |
| <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
|
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
|
| <TD COLSPAN=1><FONT SIZE="+2">
|
| <B>Method Detail</B></FONT></TD>
|
| </TR>
|
| </TABLE>
|
|
|
| <A NAME="getXMLSchemaType()"><!-- --></A><H3>
|
| getXMLSchemaType</H3>
|
| <PRE>
|
| public <A HREF="../../../javax/xml/namespace/QName.html">QName</A> <B>getXMLSchemaType</B>()</PRE>
|
| <DL>
|
| <DD><p>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. <A HREF="../../../javax/xml/datatype/Duration.html#isSet(javax.xml.datatype.DatatypeConstants.Field)"><CODE>isSet(DatatypeConstants.Field field)</CODE></A> == <code>true</code>.</p> |
| |
| <table border="2" rules="all" cellpadding="2"> |
| <thead> |
| <tr> |
| <th align="center" colspan="7"> |
| Required fields for XML Schema 1.0 Date/Time Datatypes.<br/> |
| <i>(timezone is optional for all date/time datatypes)</i> |
| </th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>Datatype</td> |
| <td>year</td> |
| <td>month</td> |
| <td>day</td> |
| <td>hour</td> |
| <td>minute</td> |
| <td>second</td> |
| </tr> |
| <tr> |
| <td><A HREF="../../../javax/xml/datatype/DatatypeConstants.html#DURATION"><CODE>DatatypeConstants.DURATION</CODE></A></td> |
| <td>X</td> |
| <td>X</td> |
| <td>X</td> |
| <td>X</td> |
| <td>X</td> |
| <td>X</td> |
| </tr> |
| <tr> |
| <td><A HREF="../../../javax/xml/datatype/DatatypeConstants.html#DURATION_DAYTIME"><CODE>DatatypeConstants.DURATION_DAYTIME</CODE></A></td> |
| <td></td> |
| <td></td> |
| <td>X</td> |
| <td>X</td> |
| <td>X</td> |
| <td>X</td> |
| </tr> |
| <tr> |
| <td><A HREF="../../../javax/xml/datatype/DatatypeConstants.html#DURATION_YEARMONTH"><CODE>DatatypeConstants.DURATION_YEARMONTH</CODE></A></td> |
| <td>X</td> |
| <td>X</td> |
| <td></td> |
| <td></td> |
| <td></td> |
| <td></td> |
| </tr> |
| </tbody> |
| </table><DD><DL>
|
| <DT><B>Returns:</B><DD>one of the following constants: |
| <A HREF="../../../javax/xml/datatype/DatatypeConstants.html#DURATION"><CODE>DatatypeConstants.DURATION</CODE></A>, |
| <A HREF="../../../javax/xml/datatype/DatatypeConstants.html#DURATION_DAYTIME"><CODE>DatatypeConstants.DURATION_DAYTIME</CODE></A> or |
| <A HREF="../../../javax/xml/datatype/DatatypeConstants.html#DURATION_YEARMONTH"><CODE>DatatypeConstants.DURATION_YEARMONTH</CODE></A>.<DT><B>Throws:</B><DD>java.lang.IllegalStateException - If the combination of set fields does not match one of the XML Schema date/time datatypes.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="getSign()"><!-- --></A><H3>
|
| getSign</H3>
|
| <PRE>
|
| public abstract int <B>getSign</B>()</PRE>
|
| <DL>
|
| <DD>Returns the sign of this duration in -1,0, or 1.<DD><DL>
|
| <DT><B>Returns:</B><DD>-1 if this duration is negative, 0 if the duration is zero, |
| and 1 if the duration is positive.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="getYears()"><!-- --></A><H3>
|
| getYears</H3>
|
| <PRE>
|
| public int <B>getYears</B>()</PRE>
|
| <DL>
|
| <DD><p>Get the years value of this <code>Duration</code> as an <code>int</code> or <code>0</code> if not present.</p> |
| |
| <p><code>getYears()</code> is a convenience method for |
| <A HREF="../../../javax/xml/datatype/Duration.html#getField(javax.xml.datatype.DatatypeConstants.Field)">getField(DatatypeConstants.YEARS)</A>.</p> |
| |
| <p>As the return value is an <code>int</code>, an incorrect value will be returned for <code>Duration</code>s |
| with years that go beyond the range of an <code>int</code>. |
| Use <A HREF="../../../javax/xml/datatype/Duration.html#getField(javax.xml.datatype.DatatypeConstants.Field)">getField(DatatypeConstants.YEARS)</A> to avoid possible loss of precision.</p><DD><DL>
|
| <DT><B>Returns:</B><DD>If the years field is present, return its value as an <code>int</code>, else return <code>0</code>.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="getMonths()"><!-- --></A><H3>
|
| getMonths</H3>
|
| <PRE>
|
| public int <B>getMonths</B>()</PRE>
|
| <DL>
|
| <DD>Obtains the value of the MONTHS field as an integer value, |
| or 0 if not present. |
| |
| This method works just like <A HREF="../../../javax/xml/datatype/Duration.html#getYears()"><CODE>getYears()</CODE></A> except |
| that this method works on the MONTHS field.<DD><DL>
|
| <DT><B>Returns:</B><DD>Months of this <code>Duration</code>.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="getDays()"><!-- --></A><H3>
|
| getDays</H3>
|
| <PRE>
|
| public int <B>getDays</B>()</PRE>
|
| <DL>
|
| <DD>Obtains the value of the DAYS field as an integer value, |
| or 0 if not present. |
| |
| This method works just like <A HREF="../../../javax/xml/datatype/Duration.html#getYears()"><CODE>getYears()</CODE></A> except |
| that this method works on the DAYS field.<DD><DL>
|
| <DT><B>Returns:</B><DD>Days of this <code>Duration</code>.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="getHours()"><!-- --></A><H3>
|
| getHours</H3>
|
| <PRE>
|
| public int <B>getHours</B>()</PRE>
|
| <DL>
|
| <DD>Obtains the value of the HOURS field as an integer value, |
| or 0 if not present. |
| |
| This method works just like <A HREF="../../../javax/xml/datatype/Duration.html#getYears()"><CODE>getYears()</CODE></A> except |
| that this method works on the HOURS field.<DD><DL>
|
| <DT><B>Returns:</B><DD>Hours of this <code>Duration</code>.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="getMinutes()"><!-- --></A><H3>
|
| getMinutes</H3>
|
| <PRE>
|
| public int <B>getMinutes</B>()</PRE>
|
| <DL>
|
| <DD>Obtains the value of the MINUTES field as an integer value, |
| or 0 if not present. |
| |
| This method works just like <A HREF="../../../javax/xml/datatype/Duration.html#getYears()"><CODE>getYears()</CODE></A> except |
| that this method works on the MINUTES field.<DD><DL>
|
| <DT><B>Returns:</B><DD>Minutes of this <code>Duration</code>.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="getSeconds()"><!-- --></A><H3>
|
| getSeconds</H3>
|
| <PRE>
|
| public int <B>getSeconds</B>()</PRE>
|
| <DL>
|
| <DD>Obtains the value of the SECONDS field as an integer value, |
| or 0 if not present. |
| |
| This method works just like <A HREF="../../../javax/xml/datatype/Duration.html#getYears()"><CODE>getYears()</CODE></A> except |
| that this method works on the SECONDS field.<DD><DL>
|
| <DT><B>Returns:</B><DD>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)</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="getTimeInMillis(java.util.Calendar)"><!-- --></A><H3>
|
| getTimeInMillis</H3>
|
| <PRE>
|
| public long <B>getTimeInMillis</B>(java.util.Calendar startInstant)</PRE>
|
| <DL>
|
| <DD><p>Returns the length of the duration in milli-seconds.</p> |
| |
| <p>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>,</p> |
| <pre> |
| <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>. |
| <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>. |
| </pre> |
| |
| <p> |
| Note that this method uses the <A HREF="../../../javax/xml/datatype/Duration.html#addTo(java.util.Calendar)"><CODE>addTo(Calendar)</CODE></A> method, |
| which may work incorrectly with <code>Duration</code> objects with |
| very large values in its fields. See the <A HREF="../../../javax/xml/datatype/Duration.html#addTo(java.util.Calendar)"><CODE>addTo(Calendar)</CODE></A> |
| method for details.<DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>startInstant</CODE> - The length of a month/year varies. The <code>startInstant</code> is |
| used to disambiguate this variance. Specifically, this method |
| returns the difference between <code>startInstant</code> and |
| <code>startInstant+duration</code><DT><B>Returns:</B><DD>milliseconds between <code>startInstant</code> and |
| <code>startInstant</code> plus this <code>Duration</code><DT><B>Throws:</B><DD>java.lang.NullPointerException - if <code>startInstant</code> parameter |
| is null.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="getTimeInMillis(java.util.Date)"><!-- --></A><H3>
|
| getTimeInMillis</H3>
|
| <PRE>
|
| public long <B>getTimeInMillis</B>(java.util.Date startInstant)</PRE>
|
| <DL>
|
| <DD><p>Returns the length of the duration in milli-seconds.</p> |
| |
| <p>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</code> value <code>x</code>,</p> |
| <pre> |
| <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>. |
| <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>. |
| </pre> |
| |
| <p> |
| Note that this method uses the <A HREF="../../../javax/xml/datatype/Duration.html#addTo(java.util.Date)"><CODE>addTo(Date)</CODE></A> method, |
| which may work incorrectly with <code>Duration</code> objects with |
| very large values in its fields. See the <A HREF="../../../javax/xml/datatype/Duration.html#addTo(java.util.Date)"><CODE>addTo(Date)</CODE></A> |
| method for details.<DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>startInstant</CODE> - The length of a month/year varies. The <code>startInstant</code> is |
| used to disambiguate this variance. Specifically, this method |
| returns the difference between <code>startInstant</code> and |
| <code>startInstant+duration</code>.<DT><B>Returns:</B><DD>milliseconds between <code>startInstant</code> and |
| <code>startInstant</code> plus this <code>Duration</code><DT><B>Throws:</B><DD>java.lang.NullPointerException - If the startInstant parameter is null.<DT><B>See Also: </B><DD><A HREF="../../../javax/xml/datatype/Duration.html#getTimeInMillis(java.util.Calendar)"><CODE>getTimeInMillis(Calendar)</CODE></A></DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="getField(javax.xml.datatype.DatatypeConstants.Field)"><!-- --></A><H3>
|
| getField</H3>
|
| <PRE>
|
| public abstract java.lang.Number <B>getField</B>(<A HREF="../../../javax/xml/datatype/DatatypeConstants.Field.html">DatatypeConstants.Field</A> field)</PRE>
|
| <DL>
|
| <DD>Gets the value of a field. |
| |
| Fields of a duration object may contain arbitrary large value. |
| Therefore this method is designed to return a <CODE>Number</CODE> 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.<DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>field</CODE> - one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, |
| MINUTES, or SECONDS.)<DT><B>Returns:</B><DD>If the specified field is present, this method returns |
| a non-null non-negative <CODE>Number</CODE> object that |
| represents its value. If it is not present, return null. |
| For YEARS, MONTHS, DAYS, HOURS, and MINUTES, this method |
| returns a <CODE>BigInteger</CODE> object. For SECONDS, this |
| method returns a <CODE>BigDecimal</CODE>.<DT><B>Throws:</B><DD>java.lang.NullPointerException - If the <code>field</code> is <code>null</code>.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="isSet(javax.xml.datatype.DatatypeConstants.Field)"><!-- --></A><H3>
|
| isSet</H3>
|
| <PRE>
|
| public abstract boolean <B>isSet</B>(<A HREF="../../../javax/xml/datatype/DatatypeConstants.Field.html">DatatypeConstants.Field</A> field)</PRE>
|
| <DL>
|
| <DD>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.<DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>field</CODE> - one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, |
| MINUTES, or SECONDS.)<DT><B>Returns:</B><DD>true if the field is present. false if not.<DT><B>Throws:</B><DD>java.lang.NullPointerException - If the field parameter is null.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="add(javax.xml.datatype.Duration)"><!-- --></A><H3>
|
| add</H3>
|
| <PRE>
|
| public abstract <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> <B>add</B>(<A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> rhs)</PRE>
|
| <DL>
|
| <DD><p>Computes a new duration whose value is <code>this+rhs</code>.</p> |
| |
| <p>For example,</p> |
| <pre> |
| "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 |
| </pre> |
| |
| <p>Since there's no way to meaningfully subtract 1 day from 1 month, |
| there are cases where the operation fails in |
| <CODE>IllegalStateException</CODE>.</p> |
| |
| <p> |
| Formally, the computation is defined as follows.</p> |
| <p> |
| Firstly, we can assume that two <code>Duration</code>s to be added |
| are both positive without losing generality (i.e., |
| <code>(-X)+Y=Y-X</code>, <code>X+(-Y)=X-Y</code>, |
| <code>(-X)+(-Y)=-(X+Y)</code>) |
| |
| <p> |
| Addition of two positive <code>Duration</code>s are simply defined as |
| field by field addition where missing fields are treated as 0. |
| <p> |
| A field of the resulting <code>Duration</code> will be unset if and |
| only if respective fields of two input <code>Duration</code>s are unset. |
| <p> |
| Note that <code>lhs.add(rhs)</code> will be always successful if |
| <code>lhs.signum()*rhs.signum()!=-1</code> or both of them are |
| normalized.</p><DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>rhs</CODE> - <code>Duration</code> to add to this <code>Duration</code><DT><B>Returns:</B><DD>non-null valid Duration object.<DT><B>Throws:</B><DD>java.lang.NullPointerException - If the rhs parameter is null.<DD>java.lang.IllegalStateException - If two durations cannot be meaningfully added. For |
| example, adding negative one day to one month causes |
| this exception.<DT><B>See Also: </B><DD><A HREF="../../../javax/xml/datatype/Duration.html#subtract(javax.xml.datatype.Duration)"><CODE>subtract(Duration)</CODE></A></DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="addTo(java.util.Calendar)"><!-- --></A><H3>
|
| addTo</H3>
|
| <PRE>
|
| public abstract void <B>addTo</B>(java.util.Calendar calendar)</PRE>
|
| <DL>
|
| <DD>Adds this duration to a <CODE>Calendar</CODE> object. |
| |
| <p> |
| Calls <CODE>Calendar.add(int,int)</CODE> in the |
| order of YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MILLISECONDS |
| if those fields are present. Because the <CODE>Calendar</CODE> 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.) |
| </p> |
| |
| <p> |
| Also, since this duration class is a Gregorian duration, this |
| method will not work correctly if the given <CODE>Calendar</CODE> |
| object is based on some other calendar systems. |
| </p> |
| |
| <p> |
| Any fractional parts of this <code>Duration</code> 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. |
| </p> |
| |
| <p> |
| Note that because <CODE>Calendar.add(int, int)</CODE> is using |
| <tt>int</tt>, <code>Duration</code> with values beyond the |
| range of <tt>int</tt> in its fields |
| will cause overflow/underflow to the given <CODE>Calendar</CODE>. |
| <A HREF="../../../javax/xml/datatype/XMLGregorianCalendar.html#add(javax.xml.datatype.Duration)"><CODE>XMLGregorianCalendar.add(Duration)</CODE></A> provides the same |
| basic operation as this method while avoiding |
| the overflow/underflow issues.<DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>calendar</CODE> - A calendar object whose value will be modified.<DT><B>Throws:</B><DD>java.lang.NullPointerException - if the calendar parameter is null.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="addTo(java.util.Date)"><!-- --></A><H3>
|
| addTo</H3>
|
| <PRE>
|
| public void <B>addTo</B>(java.util.Date date)</PRE>
|
| <DL>
|
| <DD>Adds this duration to a <CODE>Date</CODE> object. |
| |
| <p> |
| The given date is first converted into |
| a <CODE>GregorianCalendar</CODE>, then the duration |
| is added exactly like the <A HREF="../../../javax/xml/datatype/Duration.html#addTo(java.util.Calendar)"><CODE>addTo(Calendar)</CODE></A> method. |
| |
| <p> |
| The updated time instant is then converted back into a |
| <CODE>Date</CODE> object and used to update the given <CODE>Date</CODE> object. |
| |
| <p> |
| This somewhat redundant computation is necessary to unambiguously |
| determine the duration of months and years.<DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>date</CODE> - A date object whose value will be modified.<DT><B>Throws:</B><DD>java.lang.NullPointerException - if the date parameter is null.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="subtract(javax.xml.datatype.Duration)"><!-- --></A><H3>
|
| subtract</H3>
|
| <PRE>
|
| public <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> <B>subtract</B>(<A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> rhs)</PRE>
|
| <DL>
|
| <DD><p>Computes a new duration whose value is <code>this-rhs</code>.</p> |
| |
| <p>For example:</p> |
| <pre> |
| "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" |
| </pre> |
| |
| <p>Since there's no way to meaningfully subtract 1 day from 1 month, |
| there are cases where the operation fails in <CODE>IllegalStateException</CODE>.</p> |
| |
| <p>Formally the computation is defined as follows. |
| First, we can assume that two <code>Duration</code>s are both positive |
| without losing generality. (i.e., |
| <code>(-X)-Y=-(X+Y)</code>, <code>X-(-Y)=X+Y</code>, |
| <code>(-X)-(-Y)=-(X-Y)</code>)</p> |
| |
| <p>Then two durations are subtracted field by field. |
| If the sign of any non-zero field <tt>F</tt> is different from |
| the sign of the most significant field, |
| 1 (if <tt>F</tt> is negative) or -1 (otherwise) |
| will be borrowed from the next bigger unit of <tt>F</tt>.</p> |
| |
| <p>This process is repeated until all the non-zero fields have |
| the same sign.</p> |
| |
| <p>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 |
| <CODE>IllegalStateException</CODE>.</p><DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>rhs</CODE> - <code>Duration</code> to subtract from this <code>Duration</code>.<DT><B>Returns:</B><DD>New <code>Duration</code> created from subtracting <code>rhs</code> from this <code>Duration</code>.<DT><B>Throws:</B><DD>java.lang.IllegalStateException - If two durations cannot be meaningfully subtracted. For |
| example, subtracting one day from one month causes |
| this exception.<DD>java.lang.NullPointerException - If the rhs parameter is null.<DT><B>See Also: </B><DD><A HREF="../../../javax/xml/datatype/Duration.html#add(javax.xml.datatype.Duration)"><CODE>add(Duration)</CODE></A></DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="multiply(int)"><!-- --></A><H3>
|
| multiply</H3>
|
| <PRE>
|
| public <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> <B>multiply</B>(int factor)</PRE>
|
| <DL>
|
| <DD><p>Computes a new duration whose value is <code>factor</code> times |
| longer than the value of this duration.</p> |
| |
| <p>This method is provided for the convenience. |
| It is functionally equivalent to the following code:</p> |
| <pre> |
| multiply(new BigDecimal(String.valueOf(factor))) |
| </pre><DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>factor</CODE> - Factor times longer of new <code>Duration</code> to create.<DT><B>Returns:</B><DD>New <code>Duration</code> that is <code>factor</code>times longer than this <code>Duration</code>.<DT><B>See Also: </B><DD><A HREF="../../../javax/xml/datatype/Duration.html#multiply(java.math.BigDecimal)"><CODE>multiply(BigDecimal)</CODE></A></DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="multiply(java.math.BigDecimal)"><!-- --></A><H3>
|
| multiply</H3>
|
| <PRE>
|
| public abstract <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> <B>multiply</B>(java.math.BigDecimal factor)</PRE>
|
| <DL>
|
| <DD>Computes a new duration whose value is <code>factor</code> times |
| longer than the value of this duration. |
| |
| <p> |
| For example, |
| <pre> |
| "P1M" (1 month) * "12" = "P12M" (12 months) |
| "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds) |
| "P1M" (1 month) * "1.5" = IllegalStateException |
| </pre> |
| |
| <p> |
| Since the <code>Duration</code> class is immutable, this method |
| doesn't change the value of this object. It simply computes |
| a new Duration object and returns it. |
| |
| <p> |
| The operation will be performed field by field with the precision |
| of <CODE>BigDecimal</CODE>. 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 |
| <CODE>IllegalStateException</CODE> to be thrown. |
| For example if you multiple one month by 0.5.</p> |
| |
| <p> |
| To avoid <CODE>IllegalStateException</CODE>, use |
| the <A HREF="../../../javax/xml/datatype/Duration.html#normalizeWith(java.util.Calendar)"><CODE>normalizeWith(Calendar)</CODE></A> method to remove the years |
| and months fields.<DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>factor</CODE> - to multiply by<DT><B>Returns:</B><DD>returns a non-null valid <code>Duration</code> object<DT><B>Throws:</B><DD>java.lang.IllegalStateException - if operation produces fraction in |
| the months field.<DD>java.lang.NullPointerException - if the <code>factor</code> parameter is |
| <code>null</code>.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="negate()"><!-- --></A><H3>
|
| negate</H3>
|
| <PRE>
|
| public abstract <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> <B>negate</B>()</PRE>
|
| <DL>
|
| <DD>Returns a new <code>Duration</code> object whose |
| value is <code>-this</code>. |
| |
| <p> |
| Since the <code>Duration</code> class is immutable, this method |
| doesn't change the value of this object. It simply computes |
| a new Duration object and returns it.<DD><DL>
|
| <DT><B>Returns:</B><DD>always return a non-null valid <code>Duration</code> object.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="normalizeWith(java.util.Calendar)"><!-- --></A><H3>
|
| normalizeWith</H3>
|
| <PRE>
|
| public abstract <A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> <B>normalizeWith</B>(java.util.Calendar startTimeInstant)</PRE>
|
| <DL>
|
| <DD><p>Converts the years and months fields into the days field |
| by using a specific time instant as the reference point.</p> |
| |
| <p>For example, duration of one month normalizes to 31 days |
| given the start time instance "July 8th 2003, 17:40:32".</p> |
| |
| <p>Formally, the computation is done as follows:</p> |
| <ol> |
| <li>the given Calendar object is cloned</li> |
| <li>the years, months and days fields will be added to the <CODE>Calendar</CODE> object |
| by using the <CODE>Calendar.add(int,int)</CODE> method</li> |
| <li>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</li> |
| <li>the computed days, along with the hours, minutes and seconds |
| fields of this duration object is used to construct a new |
| Duration object.</li> |
| </ol> |
| |
| <p>Note that since the Calendar class uses <code>int</code> 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.</p><DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>startTimeInstant</CODE> - <code>Calendar</code> reference point.<DT><B>Returns:</B><DD><code>Duration</code> of years and months of this <code>Duration</code> as days.<DT><B>Throws:</B><DD>java.lang.NullPointerException - If the startTimeInstant parameter is null.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="compare(javax.xml.datatype.Duration)"><!-- --></A><H3>
|
| compare</H3>
|
| <PRE>
|
| public abstract int <B>compare</B>(<A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> duration)</PRE>
|
| <DL>
|
| <DD><p>Partial order relation comparison with this <code>Duration</code> instance.</p> |
| |
| <p>Comparison result must be in accordance with |
| <a href="http://www.w3.org/TR/xmlschema-2/#duration-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, |
| <i>Order relation on duration</i></a>.</p> |
| |
| <p>Return:</p> |
| <ul> |
| <li><A HREF="../../../javax/xml/datatype/DatatypeConstants.html#LESSER"><CODE>DatatypeConstants.LESSER</CODE></A> if this <code>Duration</code> is shorter than <code>duration</code> parameter</li> |
| <li><A HREF="../../../javax/xml/datatype/DatatypeConstants.html#EQUAL"><CODE>DatatypeConstants.EQUAL</CODE></A> if this <code>Duration</code> is equal to <code>duration</code> parameter</li> |
| <li><A HREF="../../../javax/xml/datatype/DatatypeConstants.html#GREATER"><CODE>DatatypeConstants.GREATER</CODE></A> if this <code>Duration</code> is longer than <code>duration</code> parameter</li> |
| <li><A HREF="../../../javax/xml/datatype/DatatypeConstants.html#INDETERMINATE"><CODE>DatatypeConstants.INDETERMINATE</CODE></A> if a conclusive partial order relation cannot be determined</li> |
| </ul><DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>duration</CODE> - to compare<DT><B>Returns:</B><DD>the relationship between <code>this</code> <code>Duration</code>and <code>duration</code> parameter as |
| <A HREF="../../../javax/xml/datatype/DatatypeConstants.html#LESSER"><CODE>DatatypeConstants.LESSER</CODE></A>, <A HREF="../../../javax/xml/datatype/DatatypeConstants.html#EQUAL"><CODE>DatatypeConstants.EQUAL</CODE></A>, <A HREF="../../../javax/xml/datatype/DatatypeConstants.html#GREATER"><CODE>DatatypeConstants.GREATER</CODE></A> |
| or <A HREF="../../../javax/xml/datatype/DatatypeConstants.html#INDETERMINATE"><CODE>DatatypeConstants.INDETERMINATE</CODE></A>.<DT><B>Throws:</B><DD>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.<DD>java.lang.NullPointerException - if <code>duration</code> is <code>null</code>.<DT><B>See Also: </B><DD><A HREF="../../../javax/xml/datatype/Duration.html#isShorterThan(javax.xml.datatype.Duration)"><CODE>isShorterThan(Duration)</CODE></A>,
|
| <A HREF="../../../javax/xml/datatype/Duration.html#isLongerThan(javax.xml.datatype.Duration)"><CODE>isLongerThan(Duration)</CODE></A></DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="isLongerThan(javax.xml.datatype.Duration)"><!-- --></A><H3>
|
| isLongerThan</H3>
|
| <PRE>
|
| public boolean <B>isLongerThan</B>(<A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> duration)</PRE>
|
| <DL>
|
| <DD><p>Checks if this duration object is strictly longer than |
| another <code>Duration</code> object.</p> |
| |
| <p>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.</p> |
| |
| <p>For example, "P1D" (one day) > "PT12H" (12 hours) and |
| "P2Y" (two years) > "P23M" (23 months).</p><DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>duration</CODE> - <code>Duration</code> to test this <code>Duration</code> against.<DT><B>Returns:</B><DD>true if the duration represented by this object |
| is longer than the given duration. false otherwise.<DT><B>Throws:</B><DD>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.<DD>java.lang.NullPointerException - If <code>duration</code> is null.<DT><B>See Also: </B><DD><A HREF="../../../javax/xml/datatype/Duration.html#isShorterThan(javax.xml.datatype.Duration)"><CODE>isShorterThan(Duration)</CODE></A>,
|
| <A HREF="../../../javax/xml/datatype/Duration.html#compare(javax.xml.datatype.Duration)"><CODE>compare(Duration duration)</CODE></A></DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="isShorterThan(javax.xml.datatype.Duration)"><!-- --></A><H3>
|
| isShorterThan</H3>
|
| <PRE>
|
| public boolean <B>isShorterThan</B>(<A HREF="../../../javax/xml/datatype/Duration.html">Duration</A> duration)</PRE>
|
| <DL>
|
| <DD><p>Checks if this duration object is strictly shorter than |
| another <code>Duration</code> object.</p><DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>duration</CODE> - <code>Duration</code> to test this <code>Duration</code> against.<DT><B>Returns:</B><DD><code>true</code> if <code>duration</code> parameter is shorter than this <code>Duration</code>, |
| else <code>false</code>.<DT><B>Throws:</B><DD>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.<DD>java.lang.NullPointerException - if <code>duration</code> is null.<DT><B>See Also: </B><DD><A HREF="../../../javax/xml/datatype/Duration.html#isLongerThan(javax.xml.datatype.Duration)"><CODE>isLongerThan(Duration duration)</CODE></A>,
|
| <A HREF="../../../javax/xml/datatype/Duration.html#compare(javax.xml.datatype.Duration)"><CODE>compare(Duration duration)</CODE></A></DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="equals(java.lang.Object)"><!-- --></A><H3>
|
| equals</H3>
|
| <PRE>
|
| public boolean <B>equals</B>(java.lang.Object duration)</PRE>
|
| <DL>
|
| <DD><p>Checks if this duration object has the same duration |
| as another <code>Duration</code> object.</p> |
| |
| <p>For example, "P1D" (1 day) is equal to "PT24H" (24 hours).</p> |
| |
| <p>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.</p> |
| |
| <p>Note that there are cases where two <code>Duration</code>s are |
| "incomparable" to each other, like one month and 30 days. |
| For example,</p> |
| <pre> |
| !new Duration("P1M").isShorterThan(new Duration("P30D")) |
| !new Duration("P1M").isLongerThan(new Duration("P30D")) |
| !new Duration("P1M").equals(new Duration("P30D")) |
| </pre><DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>duration</CODE> - A non-null valid <code>Duration</code> object.<DT><B>Returns:</B><DD><code>true</code> if this duration is the same length as |
| <code>duration</code>. |
| <code>false</code> if <code>duration</code> is not a |
| <code>Duration</code> object |
| or its length is different from this duration.<DT><B>Throws:</B><DD>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.<DD>java.lang.NullPointerException - if parameter is null.<DT><B>Overrides:</B><DD>equals in class java.lang.Object<DT><B>See Also: </B><DD><A HREF="../../../javax/xml/datatype/Duration.html#compare(javax.xml.datatype.Duration)"><CODE>compare(Duration duration)</CODE></A></DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="hashCode()"><!-- --></A><H3>
|
| hashCode</H3>
|
| <PRE>
|
| public abstract int <B>hashCode</B>()</PRE>
|
| <DL>
|
| <DD>Returns a hash code consistent with the definition of the equals method.<DD><DL>
|
| <DT><B>Overrides:</B><DD>hashCode in class java.lang.Object<DT><B>See Also: </B><DD><CODE>Object.hashCode()</CODE></DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="toString()"><!-- --></A><H3>
|
| toString</H3>
|
| <PRE>
|
| public java.lang.String <B>toString</B>()</PRE>
|
| <DL>
|
| <DD><p>Returns a <code>String</code> representation of this <code>Duration</code> <code>Object</code>.</p> |
| |
| <p>The result is formatted according to the XML Schema 1.0 spec and can be always parsed back later into the |
| equivalent <code>Duration</code> <code>Object</code> by <A HREF="../../../javax/xml/datatype/DatatypeFactory.html#newDuration(java.lang.String)"><CODE>DatatypeFactory.newDuration(String lexicalRepresentation)</CODE></A>.</p> |
| |
| <p>Formally, the following holds for any <code>Duration</code> |
| <code>Object</code> x:</p> |
| <pre> |
| new Duration(x.toString()).equals(x) |
| </pre><DD><DL>
|
| <DT><B>Returns:</B><DD>A non-<code>null</code> valid <code>String</code> representation of this <code>Duration</code>.<DT><B>Overrides:</B><DD>toString in class java.lang.Object</DL>
|
| </DD>
|
| </DL>
|
| <!-- ========= END OF CLASS DATA ========= -->
|
| <HR>
|
|
|
| <!-- ========== START OF NAVBAR ========== -->
|
| <A NAME="navbar_bottom"><!-- --></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
|
| <TR>
|
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
|
| <A NAME="navbar_bottom_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
|
| <TR ALIGN="center" VALIGN="top">
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
|
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/Duration.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
|
| </TR>
|
| </TABLE>
|
| </TD>
|
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
|
| </EM>
|
| </TD>
|
| </TR>
|
|
|
| <TR>
|
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
| <A HREF="../../../javax/xml/datatype/DatatypeFactory.html"><B>PREV CLASS</B></A>
|
| <A HREF="../../../javax/xml/datatype/XMLGregorianCalendar.html"><B>NEXT CLASS</B></A></FONT></TD>
|
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
| <A HREF="../../../index.html" TARGET="_top"><B>FRAMES</B></A>
|
| <A HREF="Duration.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
|
| </TR>
|
| <TR>
|
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
|
| SUMMARY: INNER | FIELD | <A HREF="#constructor_summary">CONSTR</A> | <A HREF="#method_summary">METHOD</A></FONT></TD>
|
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
|
| DETAIL: FIELD | <A HREF="#constructor_detail">CONSTR</A> | <A HREF="#method_detail">METHOD</A></FONT></TD>
|
| </TR>
|
| </TABLE>
|
| <!-- =========== END OF NAVBAR =========== -->
|
|
|
| <HR>
|
| Copyright © 2006 Apache XML Project. All Rights Reserved.
|
| </BODY>
|
| </HTML>
|
