Duration

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 5.0

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

javax.xml.datatype
类 Duration

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

public abstract class Duration
extends Object
extends Object

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

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

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

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

顺序关系

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

A<B（A 比 B 短）
A>B（A 比 B 长）
A==B（A 和 B 的持续时间相同）
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()`

方法摘要
`abstract Duration`	`add(Duration rhs)` 计算其值为 `this+rhs` 的新持续时间。
`abstract void`	`addTo(Calendar calendar)` 将此持续时间添加到 `Calendar` 对象。
`void`	`addTo(Date date)` 将此持续时间添加到 `Date` 对象。
`abstract int`	`compare(Duration duration)` 与此 `Duration` 实例的部分顺序关系比较。
`boolean`	`equals(Object duration)` 检查此持续时间对象是否与另一个 `Duration` 对象具有相同的持续时间。
`int`	`getDays()` 获取整数值形式的 DAYS 字段的值，如果不存在，则其值为 0。
`abstract Number`	`getField(DatatypeConstants.Field field)` 获取字段的值。
`int`	`getHours()` 获取整数值形式的 HOURS 字段的值，如果不存在，则其值为 0。
`int`	`getMinutes()` 获取整数值形式的 MINUTES 字段的值，如果不存在，则其值为 0。
`int`	`getMonths()` 获取整数值形式的 MONTHS 字段的值，如果不存在，则其值为 0。
`int`	`getSeconds()` 获取整数值形式的 SECONDS 字段的值，如果不存在，则其值为 0。
`abstract int`	`getSign()` 以 -1、0 或 1 的形式返回此持续时间的符号。
`long`	`getTimeInMillis(Calendar startInstant)` 返回以毫秒为单位的持续时间的长度。
`long`	`getTimeInMillis(Date startInstant)` 返回以毫秒为单位的持续时间的长度。
`QName`	`getXMLSchemaType()` 返回此实例映射到的 XML Schema 日期/时间类型的名称。
`int`	`getYears()` 获取此 `Duration` 以 `int` 表示的 years 值，如果不存在，则其值为 `0`。
`abstract int`	`hashCode()` 返回与 equals 方法的定义一致的哈希码。
`boolean`	`isLongerThan(Duration duration)` 检查此持续时间对象是否严格长于另一个 `Duration` 对象。
`abstract boolean`	`isSet(DatatypeConstants.Field field)` 检查是否设置了字段。
`boolean`	`isShorterThan(Duration duration)` 检查此持续时间对象是否严格短于另一个 `Duration` 对象。
`abstract Duration`	`multiply(BigDecimal factor)` 计算其值是此持续时间的 `factor` 倍的新持续时间。
`Duration`	`multiply(int factor)` 计算新的持续时间，其值是此持续时间值的 `factor` 倍。
`abstract Duration`	`negate()` 返回其值是 `-this` 的新 `Duration` 对象。
`abstract Duration`	`normalizeWith(Calendar startTimeInstant)` 通过使用特定的时间点作为参考点，将 years 和 months 字段转换为 days 字段。
`Duration`	`subtract(Duration rhs)` 计算其值是 `this-rhs` 的新持续时间。
`String`	`toString()` 返回此 `Duration` `Object` 的 `String` 表示形式。

从类 java.lang.Object 继承的方法
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

构造方法详细信息

Duration

public Duration()

方法详细信息

getXMLSchemaType

public QName getXMLSchemaType()

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

XML Schema 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 Schema 日期/时间数据类型之一不匹配。

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 的上溢/下溢。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 月，以补偿日），那么计算会失败，并抛出 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"。

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

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

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

参数：: startTimeInstant - Calendar 引用点。
返回：: 以日为单位返回此 Duration 的年和月的 Duration。
抛出：: NullPointerException - 如果 startTimeInstant 参数为 null。

compare

public abstract int compare(Duration duration)

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

比较结果必须依照 W3C XML Schema 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 - 要比较的持续时间
返回：: this Duration 和 duration 参数之间的关系作为 DatatypeConstants.LESSER、DatatypeConstants.EQUAL、DatatypeConstants.GREATER 或 DatatypeConstants.INDETERMINATE。
抛出：: UnsupportedOperationException - 如果底层实现无法合理处理该请求，即 W3C XML Schema 允许任意大/小/精确的值，该请求可能超出实现功能。; NullPointerException - 如果 duration 为 null。
另请参见：: isShorterThan(Duration), isLongerThan(Duration)

isLongerThan

public boolean isLongerThan(Duration duration)

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

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

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

参数：: duration - 测试此 Duration 的 Duration。
返回：: 如果此对象表示的持续时间比给定的持续时间长，则返回 true，否则返回 false。
抛出：: UnsupportedOperationException - 如果底层实现无法合理处理该请求，即 W3C XML Schema 允许任意大/小/精确的值，该请求可能超出实现功能。; 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 Schema 允许任意大/小/精确的值，该请求可能超出实现功能。; 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 Schema 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 - 非 null 的有效 Duration 对象。
返回：: 如果此持续时间与 duration 长度相同，则返回 true。如果 duration 不是 Duration 对象，或者其长度与此持续时间不同，则返回 false。
抛出：: UnsupportedOperationException - 如果底层实现无法合理处理该请求，即 W3C XML Schema 允许任意大/小/精确的值，该请求可能超出实现功能。; NullPointerException - 如果参数为 null。
另请参见：: compare(Duration duration)