javax.xml.datatype
类 Duration

java.lang.Object
  javax.xml.datatype.Duration

public abstract class Duration
extends Object

W3C XML 模式 1.0 规范中定义的时间范围的不可变表示形式。

Duration 对象表示一段阳历时间，它由六个字段（years、months、days、hours、minutes 和 seconds）加上符号 (+/-) 字段组成。

前五个字段为非负 (>=0) 整数或 null（表示不设置字段），seconds 字段为非负小数或 null。负号指示负的持续时间。

此类提供大量的方法，使 XML 模式 1.0 及勘误中的 duration 数据类型的使用更简单。

顺序关系

Duration 对象只有部分顺序，其中值 A 和 B 可以是以下任一顺序：

1. A<B（A 比 B 短）
2. A>B（A 比 B 长）
3. A==B（A 和 B 的持续时间相同）
4. A<>B（A 和 B 之间的比较是不确定的）

例如，将 30 天与一个月比较没有意义。compare(Duration duration) 方法实现此关系。

有关 Duration 对象之间顺序关系的详细信息，请参阅 isLongerThan(Duration) 方法。

对 Duration 的操作

此类提供一组基本的算术运算，如加、减和乘。因为持续时间没有整体顺序，对一些组合操作，操作可能失败。例如，不能从 1 个月减去 15 天。有关发生此情形的详细情况，请参阅这些方法的 javadoc。

另外，不提供持续时间除以数字的除法，因为 Duration 类仅处理有限精度的十进制数字。例如，无法表示 1 秒除以 3。

但可以用乘以数字（如 0.3 或 0.333）替代除以 3 的除法。

允许值的范围

即使 Duration 可以保持非常大或非常小的值，因为某些 Duration 的操作依赖于 Calendar，所以一些方法不能在此类 Duration 上正常工作。受影响的方法记录其对 Calendar 的依赖。

从以下版本开始：

1.5

另请参见：

XMLGregorianCalendar.add(Duration)

Duration

public Duration()

默认的无参数构造方法。

注：总是使用 DatatypeFactory 来构造 Duration 实例。无法保证此类上的构造方法生成具有一致状态并可在以后移除的对象。

getXMLSchemaType

public QName getXMLSchemaType()

返回此实例映射到的 XML 模式日期/时间类型的名称。类型根据设置的字段来计算，即 isSet(DatatypeConstants.Field field) == true。

XML 模式 1.0 日期/时间数据类型的必需字段。 （对于所有日期/时间数据类型，时区是可选的）
数据类型	year	month	day	hour	minute	second
DatatypeConstants.DURATION	X	X	X	X	X	X
DatatypeConstants.DURATION_DAYTIME			X	X	X	X
DatatypeConstants.DURATION_YEARMONTH	X	X

返回：

以下常量之一：DatatypeConstants.DURATION、DatatypeConstants.DURATION_DAYTIME 或 DatatypeConstants.DURATION_YEARMONTH。

抛出：

IllegalStateException - 如果设置字段的组合与 XML 模式日期/时间数据类型之一不匹配。

getSign

public abstract int getSign()

以 -1、0 或 1 的形式返回此持续时间的符号。

返回：

如果此持续时间为负，则返回 -1；如果持续时间为零，则返回 0；如果持续时间为正，则返回 1。

getYears

public int getYears()

获取此 Duration 以 int 表示的 years 值，如果不存在，则值为 0。

getYears() 是 getField(DatatypeConstants.YEARS) 的一个便捷方法。

由于返回值是 int，所以对于具有超出 int 范围的年值的 Duration，返回不正确的值。使用 getField(DatatypeConstants.YEARS) 避免可能的精度丢失。

返回：

如果存在 years 字段，则返回以 int 表示的值，否则返回 0。

getMonths

public int getMonths()

获取整数值形式的 MONTHS 字段的值，如果不存在，则值为 0。 除了对 MONTHS 字段的作用之外，此方法的其他功能与 getYears() 相似。

返回：

此 Duration 的月。

getDays

public int getDays()

获取整数值形式的 DAYS 字段的值，如果不存在，则值为 0。 除了对 MONTHS 字段的作用之外，此方法的其他功能与 getYears() 相似。

返回：

此 Duration 的日。

getHours

public int getHours()

获取整数值形式的 HOURS 字段的值，如果不存在，则值为 0。 除了对 HOURS 字段的作用之外，此方法的其他功能与 getYears() 相似。

返回：

此 Duration 的时。

getMinutes

public int getMinutes()

获取整数值形式的 MINUTES 字段的值，如果不存在，则值为 0。 除了对 MINUTES 字段的作用之外，此方法的其他功能与 getYears() 相似。

返回：

此 Duration 的分。

getSeconds

public int getSeconds()

获取整数值形式的 SECONDS 字段的值，如果不存在，则值为 0。 除了对 SECONDS 字段的作用之外，此方法的其他功能与 getYears() 相似。

返回：

秒的整数值。将丢弃秒的小数部分（例如，如果实际值是 2.5，则此方法返回 2）

getTimeInMillis

public long getTimeInMillis(Calendar startInstant)

返回以毫秒为单位的持续时间的长度。

如果秒字段比毫秒字段带的位数更多，则丢弃多余的位数（即去尾舍入）。例如，对于任何日历值 x，

new Duration("PT10.00099S").getTimeInMills(x) == 10000。
new Duration("-PT10.00099S").getTimeInMills(x) == -10000。
 

注意，此方法使用 addTo(Calendar) 方法，使用在其字段中具有更大值的 Duration 对象可能无法正确工作。有关详细信息，请参阅 addTo(Calendar) 方法。

参数：

startInstant - 月/年的长度不同。使用 startInstant 确定此偏差。明确地说，此方法返回 startInstant 和 startInstant+duration 之间的差异

返回：

startInstant 和 startInstant 之间的毫秒加上此 Duration

抛出：

NullPointerException - 如果 startInstant 参数为 null。

getTimeInMillis

public long getTimeInMillis(Date startInstant)

返回以毫秒为单位的持续时间的长度。

如果秒字段比毫秒字段带的位数更多，则丢弃多余的位数（即去尾舍入）。例如，对于任何 Date 值 x，

new Duration("PT10.00099S").getTimeInMills(x) == 10000。
new Duration("-PT10.00099S").getTimeInMills(x) == -10000。
 

注意，此方法使用 addTo(Date) 方法，该方法对于具有较大字段值的 Duration 对象工作正常。有关详细信息，请参阅 addTo(Date) 方法。

参数：

startInstant - 月/年的长度不同。使用 startInstant 确定此偏差。明确地说，此方法返回 startInstant 和 startInstant+duration 之间的差异

返回：

startInstant 和 startInstant 之间的毫秒加上此 Duration

抛出：

NullPointerException - 如果 startInstant 参数为 null。

另请参见：

getTimeInMillis(Calendar)

getField

public abstract Number getField(DatatypeConstants.Field field)

获取字段的值。 duration 对象的字段可以包含任意大的值。因此，设计此方法的目的是返回 Number 对象。 就 YEARS、MONTHS、DAYS、HOURS 和 MINUTES 来说，返回的数字将是一个非负整数。就 seconds 来说，返回的数字可以是一个非负的十进制值。

参数：

field - 六个字段常量之一（YEARS、MONTHS、DAYS、HOURS、MINUTES 或 SECONDS。）

返回：

如果指定的字段存在，则此方法返回表示其值的非 null 的非负 Number 对象。如果不存在，则返回 null。对于 YEARS、MONTHS、DAYS、HOURS 和 MINUTES，此方法返回 BigInteger 对象。对于 SECONDS，此方法返回 BigDecimal。

抛出：

NullPointerException - 如果 field 为 null。

isSet

public abstract boolean isSet(DatatypeConstants.Field field)

检查是否设置了字段。 duration 对象的字段不一定存在。可以使用此方法测试字段是否存在。

参数：

field - 六个字段常量之一（YEARS、MONTHS、DAYS、HOURS、MINUTES 或 SECONDS。）

返回：

如果字段存在，则返回 true，否则返回 false。

抛出：

NullPointerException - 如果字段参数为 null。

add

public abstract Duration add(Duration rhs)

计算值为 this+rhs 的新持续时间。

例如，

 "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
 

由于从 1 月减去 1 天没有意义，所以 IllegalStateException 中存在操作失败的情况。

正式地说，应按以下方法定义计算。

首先，在一般意义下，可以假设要添加的两个 Duration 是两个正数（即 (-X)+Y=Y-X、X+(-Y)=X-Y、(-X)+(-Y)=-(X+Y)）

根据逐字段相加定义两个正 Duration 的相加，其中缺少的字段视为 0。

当且仅当未设置两个输入 Duration 的各自字段时，将不设置产生的 Duration 的字段。

注意，如果 lhs.signum()*rhs.signum()!=-1，或将它们两个标准化，则 lhs.add(rhs) 将总是成功的。

参数：

rhs - 要添加到此 Duration 的 Duration

返回：

非 null 的有效 Duration 对象。

抛出：

NullPointerException - 如果 rhs 参数为 null。

IllegalStateException - 如果两个持续时间的相加没有意义。例如，将负的一天添加到一月将导致此异常。

另请参见：

subtract(Duration)

addTo

public abstract void addTo(Calendar calendar)

将此持续时间添加到 Calendar 对象。

按 YEARS、MONTHS、DAYS、HOURS、MINUTES、SECONDS 和 MILLISECONDS 的顺序调用 Calendar.add(int,int)，如果这些字段存在的话。因为 Calendar 类使用整数保持值，所以存在此方法不能正确工作的情况（例如，如果字段的值超出整数的范围。）

另外，由于此 duration 类是阳历持续时间，所以如果给定的 Calendar 对象基于一些其他日历系统，则此方法将不能正确工作。

对于此 Duration 对象的小数部分，只忽略毫秒之外的数字。例如，如果此持续时间是“P1.23456S”，那么将 1 添加到 SECONDS，将 234 添加到 MILLISECONDS，不使用其余部分。

注意，因为 Calendar.add(int, int) 正在使用 int，所以带有超出其字段中 int 范围值的 Duration 将导致给定 Calendar 的上溢/下溢。link XMLGregorianCalendar#add(Duration)} 提供与此方法相同的基本操作，同时避免上溢/下溢问题。

参数：

calendar - 值将被修改的日历对象。

抛出：

NullPointerException - 如果日历参数为 null。

addTo

public void addTo(Date date)

将此持续时间添加到 Date 对象。

将给定的数据首先转换为 GregorianCalendar，然后完全按照 addTo(Calendar) 方法添加持续时间。

然后将更新的时间点转换回 Date 对象，并用于更新给定的 Date 对象。

此冗余计算对明确地确定月和年的持续时间是必需的。

参数：

date - 值将被修改的日期对象。

抛出：

NullPointerException - 如果日期参数为 null。

subtract

public Duration subtract(Duration rhs)

计算值为 this-rhs 的新持续时间。

例如：

 "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"
 

由于从 1 月减去 1 天没有意义，所以 IllegalStateException 中存在操作失败的情形。

正式地说，应按以下方法定义计算。首先，在一般意义下，可以假设两个 Duration 都是两个正数。（即 (-X)-Y=-(X+Y)、X-(-Y)=X+Y、(-X)-(-Y)=-(X-Y)）

然后，逐字段减去两个持续时间。如果任何非零字段 F 的符号与最重要的字段的符号不同，则将从 F 的下一个较大单位借用 1（如果 F 为负）或 -1（如果为非负）。

重复此过程，直到所有的非零字段具有相同符号。

如果在 days 字段中发生借用（换句话说，如果计算需要借用 1 或 -1 月，以补偿 days），那么计算会失败，并抛出 IllegalStateException。

参数：

rhs - 从 Duration 减去的 Duration。

返回：

通过从此 Duration 减去 rhs 创建的新 Duration。

抛出：

IllegalStateException - 如果两个持续时间的相减没有意义。例如，从一月减去一天会导致此异常。

NullPointerException - 如果 rhs 参数为 null。

另请参见：

add(Duration)

multiply

public Duration multiply(int factor)

计算新的持续时间，值为此持续时间值的 factor 倍。

提供此方法是为了方便使用。它在功能上等同于以下代码：

 multiply(new BigDecimal(String.valueOf(factor)))
 

参数：

factor - 要创建的新 Duration 的 Factor 倍数。

返回：

作为此 Duration 的 factor 倍的新 Duration。

另请参见：

multiply(BigDecimal)

multiply

public abstract Duration multiply(BigDecimal factor)

计算新的持续时间，其值是此持续时间值的 factor 倍。

例如，

 "P1M" (1 month) * "12" = "P12M" (12 months)
 "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds)
 "P1M" (1 month) * "1.5" = IllegalStateException
 

由于 Duration 类是不可变的，所以此方法不更改此对象的值。它仅计算新的 Duration 对象，并返回它。

将通过 BigDecimal 的精度逐字段执行操作。由于除 seconds 外的所有字段限于保持整数，计算产生的任何小数向下进位到下一个低单位。例如，如果 "P1D"（1 天）乘 "0.5"，那么将得到 0.5 天，它将向下进位到 "PT12H"（12 小时）。当月的小数向下进位到日或年的小数向下进位到月没有意义时，将导致抛出 IllegalStateException。例如，将一个月乘以 0.5 时将抛出上述异常。

要避免 IllegalStateException，请使用 normalizeWith(Calendar) 方法移除 years 和 months 字段。

参数：

factor - 相乘的因子

返回：

返回非 null 的有效 Duration 对象

抛出：

IllegalStateException - 如果操作在 months 字段中生成小数。

NullPointerException - 如果 factor 参数为 null。

negate

public abstract Duration negate()

返回值为 -this 的新 Duration 对象。

由于 Duration 类是不可变的，所以此方法不更改此对象的值。它仅计算新的 Duration 对象，并返回它。

返回：

总是返回非 null 的有效 Duration 对象。

normalizeWith

public abstract Duration normalizeWith(Calendar startTimeInstant)

通过使用特定的时间点作为参考点，将 years 和 months 字段转换为 days 字段。

例如，一个月的持续时间可以标准化为 31 天，给出的时间点是 "July 8th 2003, 17:40:32"。

正式地说，应按以下方法进行计算：

1. 复制给定的 Calendar 对象
2. 使用 Calendar.add(int,int) 方法将 years、months 和 days 字段添加到 Calendar 对象
3. 两个 Calendar 在以毫秒计算并转换为天数上存在差异，如果由于夏令时 (Daylight Savings Time) 而发生余数，则丢弃该余数。
4. 计算的 days 以及此持续时间对象的 hours、minutes 和 seconds 字段用于构造新的持续时间对象。

注意，由于 Calendar 类使用 int 保持年和月的值，所以如果此持续时间对象在 years 或 months 字段中保持非常大的值，则此方法可能产生不可预料的结果。

参数：

startTimeInstant - Calendar 引用点。

返回：

以日为单位返回此 Duration 的年和月的 Duration。

抛出：

NullPointerException - 如果 startTimeInstant 参数为 null。

compare

public abstract int compare(Duration duration)

与此 Duration 实例的部分顺序关系比较。

比较结果必须依照 W3C XML 模式 1.0 第二部分 3.2.7.6.2 节 Order relation on duration。

返回：

• DatatypeConstants.LESSER 如果此 Duration 比 duration 参数短
• DatatypeConstants.EQUAL 如果此 Duration 等于 duration 参数
• DatatypeConstants.GREATER 如果此 Duration 比 duration 参数长
• DatatypeConstants.INDETERMINATE 如果无法确定最终的部分顺序关系

参数：

duration - 要比较的持续时间

返回：

此 Duration 和 duration 参数之间的关系：DatatypeConstants.LESSER、DatatypeConstants.EQUAL、DatatypeConstants.GREATER 或 DatatypeConstants.INDETERMINATE。

抛出：

UnsupportedOperationException - 如果底层实现无法合理处理该请求，例如，W3C XML 模式允许任意大/小/精确的值，该请求可能超出实现功能。

NullPointerException - 如果 duration 为 null。

另请参见：

isShorterThan(Duration), isLongerThan(Duration)

isLongerThan

public boolean isLongerThan(Duration duration)

检查此持续时间对象是否严格长于另一个 Duration 对象。

根据 XML 模式 1.0 规范的第 3.2.6.2 节中的定义，当且仅当 X>Y 时，持续时间 X 比 Y“长”。

例如，"P1D"（一天）> "PT12H"（12 小时），并且 "P2Y"（两年）>"P23M"（23 月）。

参数：

duration - 测试此 Duration 的 Duration。

返回：

如果此对象表示的持续时间比给定的持续时间长，则返回 true，否则返回 false。

抛出：

UnsupportedOperationException - 如果底层实现无法合理处理该请求，例如，W3C XML 模式允许任意大/小/精确的值，该请求可能超出实现功能。

NullPointerException - 如果 duration 为 null。

另请参见：

isShorterThan(Duration), compare(Duration duration)

isShorterThan

public boolean isShorterThan(Duration duration)

检查此持续时间对象是否严格短于另一个 Duration 对象。

参数：

duration - 测试此 Duration 的 Duration。

返回：

如果 duration 参数比此 Duration 短，则返回 true，否则返回 false。

抛出：

UnsupportedOperationException - 如果底层实现无法合理处理该请求，例如，W3C XML 模式允许任意大/小/精确的值，该请求可能超出实现功能。

NullPointerException - 如果 duration 为 null。

另请参见：

isLongerThan(Duration duration), compare(Duration duration)

equals

public boolean equals(Object duration)

检查此持续时间对象是否与另一个 Duration 对象具有相同的持续时间。

例如，"P1D"（1 天）等于 "PT24H"（24 小时）。

当且仅当时间点 t+X 和 t+Y 对 XML 模式 1.0 规范的第 3.2.6.2 节中指定的所有测试时间点都相同时，持续时间 X 才等于 Y。

注意，存在两个 Duration 互相“不能比较”的情况，如一个月和 30 天。例如，

 !new Duration("P1M").isShorterThan(new Duration("P30D"))
 !new Duration("P1M").isLongerThan(new Duration("P30D"))
 !new Duration("P1M").equals(new Duration("P30D"))
 

覆盖：

类 Object 中的 equals

参数：

duration - 用来对照比较此 Duration 的对象。

返回：

如果此持续时间与 duration 长度相同，则返回 true。如果 duration 是 null，而不是 Duration 对象，或者其长度与此持续时间不同，则返回 false。

抛出：

UnsupportedOperationException - 如果底层实现无法合理处理该请求，例如，W3C XML 模式允许任意大/小/精确的值，该请求可能超出实现功能。

另请参见：

compare(Duration duration)

hashCode

public abstract int hashCode()

返回与 equals 方法的定义一致的哈希码。

覆盖：

类 Object 中的 hashCode

返回：

此对象的一个哈希码值。

另请参见：

Object.hashCode()

toString

public String toString()

返回此 Duration Object 的 String 表示形式。

根据 XML 模式 1.0 规范格式化该结果，之后始终可以通过 DatatypeFactory.newDuration(String lexicalRepresentation) 将其解析为等效的 Duration Object。

正式地说，以下内容保持任何 Duration Object x：

 new Duration(x.toString()).equals(x)
 

覆盖：

类 Object 中的 toString

返回：

此 Duration 的非 null 有效 String 表示形式。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。