Duration (Java Platform SE 8 )

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

```
public abstract class Duration
extends Object
```
W3C XML Schema 1.0规范中定义的时间跨度的不可变表示。

持续时间对象表示公历时间，由六个字段（年，月，日，小时，分钟和秒）加上一个符号（+/-）字段组成。

前五个字段具有非负（> = 0）整数或空（表示未设置字段），秒字段具有非负数十进制或零。负号表示负持续时间。

该类提供了许多方法，使其易于使用具有勘误的XML Schema 1.0的持续时间数据类型。

订单关系

持续时间对象只有部分顺序，其中两个值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)方法。

持续时间操作

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

另外，由于Duration类只能处理有限精度的十进制数，所以不提供持续时间除数。例如，不能代表1秒除以3。

但是，您可以用乘数乘以3除以0.3或0.333。

允许值范围

由于一些操作Duration依靠Calendar尽管Duration可以容纳非常大或非常小的值，某些方法可能无法正常在这样的工作Duration秒。受影响的方法记录了他们对Calendar的依赖。
从以下版本开始：

1.5

另请参见：

XMLGregorianCalendar.add(Duration)

构造方法摘要

构造方法
Constructor and Description
`Duration()` 默认的无参数构造函数。

方法摘要

所有方法接口方法抽象方法具体的方法
Modifier and Type	Method and Description
`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模式日期/时间类型的名称。
`int`	`getYears()` 如果不存在，请将此 `Duration`的年份值作为 `int`或 `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)` 通过使用特定的时刻作为参考点，将几个月和几个字段转换为日期字段。
`Duration`	`subtract(Duration rhs)` 计算值为 `this-rhs`的新持续时间。
`String`	`toString()` 返回此 `String` Object的 `Duration` `Object` 。

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- 构造方法详细信息
  - Duration
```
public Duration()
```
    默认的无参数构造函数。
    注意：始终使用DatatypeFactory构造的一个实例Duration 。此类的构造函数无法保证产生一致状态的对象，并可能在将来被删除。
- 方法详细信息
  - getXMLSchemaType
```
public QName getXMLSchemaType()
```
    返回此实例映射到的XML模式日期/时间类型的名称。类型是基于设置的字段计算的，即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 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或0 。
    
    getYears()为方便方法getField(DatatypeConstants.YEARS) 。
    
    由于返回值是int ，不正确的值将被退回Duration多年超越的的范围S int 。使用getField(DatatypeConstants.YEARS)避免可能的精度损失。
    
    结果
    
    如果年份字段存在，则返回值为 int ，否则返回 0 。
  - getMonths
```
public int getMonths()
```
    获取MONTHS字段的值作为整数值，如果不存在，则为0。此方法的工作原理就像getYears()，除了该方法适用于MONTHS字段。
    
    结果
    
    几个月这 Duration 。
  - getDays
```
public int getDays()
```
    获取DAYS字段的值作为整数值，如果不存在则取为0。该方法的工作原理就像getYears()，除了该方法在DAYS字段上工作。
    
    结果
    
    这天 Duration 。
  - getHours
```
public int getHours()
```
    获取HOURS字段的值作为整数值，如果不存在，则为0。此方法的工作方式与getYears()类似，除了该方法适用于HOURS字段。
    
    结果
    
    小时这 Duration 。
  - getMinutes
```
public int getMinutes()
```
    获取MINUTES字段的值作为整数值，如果不存在，则为0。此方法的工作原理就像getYears()，除了该方法适用于MINUTES字段。
    
    结果
    
    这个 Duration分钟。
  - getSeconds
```
public int getSeconds()
```
    获取SECONDS字段的值作为整数值，如果不存在则取为0。此方法的工作方式与getYears()类似，除了该方法适用于SECONDS字段。
    
    结果
    
    秒的整数值。秒的分数将被丢弃（例如，如果实际值为2.5，则此方法返回2）
  - getTimeInMillis
```
public long getTimeInMillis(Calendar startInstant)
```
    以毫秒为单位返回持续时间的长度。
    
    如果秒字段的数字比毫秒级数更多，那么它们将被简单地丢弃（或换句话说，四舍五入为零）。例如，对于任何Calendar值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+duration
    
    结果
    
    之间的毫秒 startInstant和 startInstant加上这个 Duration
    
    异常
    
    NullPointerException - 如果 startInstant参数为空。
  - 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+duration 。
    
    结果
    
    之间的毫秒 startInstant和 startInstant加上这个 Duration
    
    异常
    
    NullPointerException - 如果startInstant参数为空。
    
    另请参见：
    
    getTimeInMillis(Calendar)
  - getField
```
public abstract Number getField(DatatypeConstants.Field field)
```
    获取字段的值。持续时间对象的字段可能包含任意大的值。因此，此方法旨在返回一个Number对象。在YEARS，MONTHS，DAYS，HOURS和MINUTES的情况下，返回的数字将为非负整数。在秒的情况下，返回的数字可能是非负十进制值。
    
    参数
    
    field - 六个字段常量之一（YEARS，MONTHS，DAYS，HOURS，MINUTES或SECONDS）。
    
    结果
    
    如果指定的字段存在，则此方法返回一个表示其值的非空非负Number对象。如果不存在，返回null。对于YEARS，MONTHS，DAYS，HOURS和MINUTES，此方法返回一个BigInteger对象。对于SECONDS，此方法返回BigDecimal 。
    
    异常
    
    NullPointerException - 如果 field是 null 。
  - isSet
```
public abstract boolean isSet(DatatypeConstants.Field field)
```
    检查是否设置了一个字段。持续时间对象的字段可能存在或可能不存在。该方法可用于测试字段是否存在。
    
    参数
    
    field - 六个字段常量之一（YEARS，MONTHS，DAYS，HOURS，MINUTES或SECONDS）。
    
    结果
    
    如果现场存在，则为真。假如不是。
    
    异常
    
    NullPointerException - 如果字段参数为空。
  - 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 s被简单地定义为字段添加，其中缺少的字段被视为0。
    
    所得的场Duration当且仅当两个输入相应字段将被取消设置Duration s为未设定。
    
    请注意， lhs.add(rhs)将始终成功，如果lhs.signum()*rhs.signum()!=-1或它们都被归一化。
    参数
    
    rhs - Duration加入这个 Duration
    
    结果
    
    非空的有效持续时间对象。
    
    异常
    
    NullPointerException - 如果rhs参数为空。
    
    IllegalStateException - 如果两个持续时间无法有意义地添加。例如，将负一天添加到一个月会导致此异常。
    
    另请参见：
    
    subtract(Duration)
  - addTo
```
public abstract void addTo(Calendar calendar)
```
    将此持续时间添加到Calendar对象。
    电话Calendar.add(int,int)以年，月，日，时，分，秒和毫秒的量级，如果这些字段存在。因为Calendar类使用int来保存值，所以存在这种方法不能正常工作的情况（例如，如果字段的值超过int的范围）
    
    另外，由于这个持续时间类是公历，所以如果给定的Calendar对象是基于其他一些日历系统的，则该方法将无法正常工作。
    
    这个Duration对象超过毫秒的任何小数部分将被简单地忽略。例如，如果此持续时间为“P1.23456S”，则将1添加到SECONDS，将234添加到MILLISECONDS，其余将不被使用。
    
    需要注意的是，因为Calendar.add(int, int)是使用int ， Duration与超出范围值int在其领域会造成溢/下溢给定Calendar 。 XMLGregorianCalendar.add(Duration)提供与此方法相同的基本操作，同时避免溢出/下溢问题。
    
    参数
    
    calendar - 其值将被修改的日历对象。
    
    异常
    
    NullPointerException - 如果日历参数为空。
  - addTo
```
public void addTo(Date date)
```
    将此持续时间添加到Date对象。
    给定日期首先转换为GregorianCalendar ，则持续时间与addTo(Calendar)方法完全相同。
    
    然后更新的时刻转换回Date对象，并用于更新给定的Date对象。
    
    这个有点冗余的计算是明确确定月和年的持续时间所必需的。
    
    参数
    
    date - 值将被修改的日期对象。
    
    异常
    
    NullPointerException - 如果date参数为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的符号与最高有效字段的符号不同，则1（如果F为负）或-1（否则）将从下一个更大的单位F 。
    
    重复此过程，直到所有非零字段具有相同的符号。
    
    如果在日期领域发生借款（换句话说，如果计算需要借用1个月或-1个月来补偿日子），那么计算失败的是投掷IllegalStateException 。
    参数
    
    rhs - Duration减去 Duration 。
    
    结果
    
    新建 Duration创建从减去 rhs从这 Duration 。
    
    异常
    
    IllegalStateException - 如果无法有意义地减去两个持续时间。例如，从一个月减去一天会导致此异常。
    
    NullPointerException - 如果rhs参数为空。
    
    另请参见：
    
    add(Duration)
  - multiply
```
public Duration multiply(int factor)
```
    计算一个新的持续时间，其值比此持续时间的值高factor倍。
    
    为方便起见，提供了这种方法。它在功能上等同于以下代码：
```
  multiply(new BigDecimal(String.valueOf(factor))) 
```
    参数
    
    factor - 创建新的 Duration因子倍数。
    
    结果
    
    新 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 。由于除秒之外的所有字段都被限制为保持整数，所以计算产生的任何分数将被转移到下一个下一个单元。例如，如果您将“P1D”（1天）乘以“0.5”，则将为0.5天，将其转入“PT12H”（12小时）。如果几个月的时间不能有意义地转移到日子，或者一年到几个月，这将导致IllegalStateException被抛出。例如，如果你多一个月0.5。
    
    为了避免IllegalStateException ，使用normalizeWith(Calendar)方法去除年和月的字段。
    参数
    
    factor - 乘以
    
    结果
    
    返回一个非空的有效 Duration对象
    
    异常
    
    IllegalStateException - 如果操作在月份字段中产生分数。
    
    NullPointerException - 如果 factor参数是 null 。
  - negate
```
public abstract Duration negate()
```
    返回值为-this的新的Duration对象。
    由于Duration类是不可变的，所以此方法不会更改此对象的值。它只是计算一个新的Duration对象并返回它。
    
    结果
    
    总是返回一个非空的有效 Duration对象。
  - normalizeWith
```
public abstract Duration normalizeWith(Calendar startTimeInstant)
```
    通过使用特定的时刻作为参考点，将几个月和几个字段转换为日期字段。
    
    例如，“开始时间”例如“2003年7月8日17:40:32”，一个月的持续时间正常化到31天。
    
    正式地，计算完成如下：
    1. 给定的Calendar对象被克隆
    2. 年份，月份和日期字段将被添加到Calendar对象中使用Calendar.add(int,int)方法
    3. 两个日历之间的差异以毫秒计算并转换为天数，如果由于夏令时间而发生余数，则它将被丢弃
    4. 计算的天数以及此持续时间对象的小时，分钟和秒字段用于构建新的“持续时间”对象。
    请注意，由于Calendar类使用int来保存年份和月份的值，因此如果该持续时间对象在几个月或几个字段中保持非常大的值，则此方法可能会产生意外结果。
    参数
    
    startTimeInstant - Calendar参考点。
    
    结果
    
    Duration的这个 Duration几个月的日子。
    
    异常
    
    NullPointerException - 如果startTimeInstant参数为空。
  - compare
```
public abstract int compare(Duration duration)
```
    与Duration实例的部分顺序关系比较。
    
    比较结果必须符合W3C XML Schema 1.0 Part 2, Section 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对象。
    
    当且仅当X> Y在XML Schema 1.0规范的3.2.6.2节定义时，X的持续时间X将比Y更长。
    
    例如，“P1D”（一天）>“PT12H”（12小时）和“P2Y”（两年）>“P23M”（23个月）。
    
    参数
    
    duration - Duration测试这个 Duration对。
    
    结果
    
    如果此对象所表示的持续时间长于给定持续时间，则为true。否则为假。
    
    异常
    
    UnsupportedOperationException - 如果底层实现不能合理地处理请求，例如，W3C XML Schema允许任意大/小/精确的值，请求可能超出实现能力。
    
    NullPointerException - 如果 duration为空。
    
    另请参见：
    
    isShorterThan(Duration) ， compare(Duration duration)
  - isShorterThan
```
public boolean isShorterThan(Duration duration)
```
    检查这个持续时间对象是否严格短于另一个Duration对象。
    
    参数
    
    duration - Duration以测试此 Duration对。
    
    结果
    
    true如果 duration参数比这更短 Duration别的， false 。
    
    异常
    
    UnsupportedOperationException - 如果底层实现不能合理地处理请求，例如，W3C XML Schema允许任意大/小/精确的值，请求可能超出实现能力。
    
    NullPointerException - 如果 duration为空。
    
    另请参见：
    
    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")) 
```
    重写：
    
    equals在 Object
    
    参数
    
    duration - 对比这个 Duration的对象。
    
    结果
    
    true如果此持续时间与duration长度相同。 false如果duration是null ，不是一个Duration对象，或者其长度与此持续时间不同。
    
    异常
    
    UnsupportedOperationException - 如果底层实现不能合理地处理请求，例如，W3C XML Schema允许任意大/小/精确的值，请求可能超出实现能力。
    
    另请参见：
    
    compare(Duration duration)
  - hashCode
```
public abstract int hashCode()
```
    返回与equals方法的定义一致的哈希码。
    
    重写：
    
    hashCode在 Object
    
    结果
    
    该对象的哈希码值。
    
    另请参见：
    
    Object.hashCode()
  - toString
```
public String toString()
```
    返回此String Object的Duration Object 。
    
    结果根据XML Schema 1.0规范进行格式化，并且可以随时解析为等效的Duration Object by DatatypeFactory.newDuration(String lexicalRepresentation) 。
    
    正式地，以下适用于任何Duration Object x：
```
  new Duration(x.toString()).equals(x) 
```
    重写：
    
    toString在类 Object
    
    结果
    
    A null有效 String表示此 Duration 。

Class Duration

订单关系

持续时间操作

允许值范围

构造方法摘要

方法摘要

Methods inherited from class java.lang.Object

构造方法详细信息

Duration

方法详细信息

getXMLSchemaType

getSign

getYears

getMonths

getDays

getHours

getMinutes

getSeconds

getTimeInMillis

getTimeInMillis

getField

isSet

add

addTo

addTo

subtract

multiply

multiply

negate

normalizeWith

compare

isLongerThan

isShorterThan

equals

hashCode

toString