Duration (Java Platform SE 8 )

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

```
public abstract class Duration
extends Object
```
一个时间跨度不变表示在W3C XML Schema 1规范定义。

一时间对象代表一个时期公历时间，其中包括六场（年，月，日，小时，分钟和秒，）加上符号（+ / -）领域。

前五个字段有非负（> = 0）整数或零（代表该字段是不设置），和秒字段有一个非负的十进制或零。负符号表示负时。

这个类提供了一些方法，使它易于使用的XML Schema的勘误表1持续时间数据类型。

序关系

持续时间的对象只有部分顺序，其中两个值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类只能处理有限精度的小数。例如，一个不能代表3秒除以1。

然而，你可以用乘以0.333，如0.3或3。

允许值范围

因为Duration一些操作依赖于Calendar即使Duration可以容纳非常大或非常小的值，有些方法可能无法正常工作在这样的Durations。受影响的方法记录他们的依赖Calendar。
从以下版本开始：

一点五

另请参见：

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()` 获得天字段的值作为一个整数值，或0如果不存在。
`abstract Number`	`getField(DatatypeConstants.Field field)` 获取字段的值。
`int`	`getHours()` 获得小时字段的值作为一个整数值，或0如果不存在。
`int`	`getMinutes()` 获得几分钟字段的值作为一个整数值，或0的值，如果不存在。
`int`	`getMonths()` 获得作为一个整数值的月字段的值，或不存在的0。
`int`	`getSeconds()` 获得秒字段的值作为一个整数值，或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()` 返回与等于方法的定义一致的哈希代码。
`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()` 返回一个新的 `Duration`对象的价值 `-this`。
`abstract Duration`	`normalizeWith(Calendar startTimeInstant)` 以某一特定时间点为参考点，将数年数和数月转换为天场。
`Duration`	`subtract(Duration rhs)` 计算出一个新的时间的价值是 `this-rhs`。
`String`	`toString()` 返回该 `Duration` `Object`一 `String`表示。

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

Constructor Detail
- 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 Schema的日期/时间数据类型。

getSign
```
public abstract int getSign()
```
返回当前时间的标志1,0，或1。

结果

如果持续时间为0，如果持续时间为零，如果持续时间为1，则为1，如果持续时间为零，则为。

getYears
```
public int getYears()
```
得到这个Duration年价值为int或0如果不存在。

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

作为返回值是一个int，一个不正确的值将返回与年超越一个int范围Durations。使用getField(DatatypeConstants.YEARS)避免丢失精度。

结果

如果年场是存在的，作为一个 int返回值，否则返回 0。

getMonths
```
public int getMonths()
```
获得作为一个整数值的月字段的值，或不存在的0。这种方法就像 getYears()除了这几个月的野外工作方法。

结果

这 Duration月。

getDays
```
public int getDays()
```
获得天字段的值作为一个整数值，或0如果不存在。这种方法就像 getYears()除了这个方法在天的野外工作。

结果

这 Duration天。

getHours
```
public int getHours()
```
获得小时字段的值作为一个整数值，或0如果不存在。这种方法就像 getYears()除了这个方法在时间领域。

结果

这 Duration小时。

getMinutes
```
public int getMinutes()
```
获得几分钟字段的值作为一个整数值，或0的值，如果不存在。这种方法就像 getYears()除了这个方法在分钟现场工作。

结果

这 Duration分钟。

getSeconds
```
public int getSeconds()
```
获得秒字段的值作为一个整数值，或0如果不存在。这种方法就像 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参数为空。

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参数为空。

另请参见：

getTimeInMillis(Calendar)

getField
```
public abstract Number getField(DatatypeConstants.Field field)
```
获取字段的值。持续对象的字段可以包含任意的大值。因此该方法返回一个 Number对象设计。以年、月、日、小时和分钟为例，返回的数字将是一个非负整数。在秒的情况下，返回的数字可能是一个非负的十进制值。

参数

field -一个六场常数（年，月，日，小时，分钟，秒。）

结果

如果指定的字段存在，该方法返回一个非空非负 Number表示其价值。如果它不存在，返回空。年，月，日，小时，分钟，此方法返回一个 BigInteger对象。秒，此方法返回一个 BigDecimal。

异常

NullPointerException -如果 field是 null。

isSet
```
public abstract boolean isSet(DatatypeConstants.Field field)
```
检查字段是否设置。一个持续时间对象的字段可能或可能不存在。这种方法可以用来测试是否存在一个字段。

参数

field -一个六场常数（年，月，日，小时，分钟，秒。）

结果

如果字段是真实的。虚假如果不是。

异常

NullPointerException如果场参数为空。

add
```
public abstract Duration add(Duration rhs)
```
计算出一个新的时间的价值是this+rhs。

例如,
```
“1天”+“- 3天”=“- 2天”“1年”+“1天”=“1年1天”“-（1小时，50分钟）“+”- 20分钟“=”（1小时，70分钟）“15小时”+“- 3天”=“-（2天，9小时）”“1年”+“1天”=时
```
因为没有办法有效地减去1天1个月，在有些情况下，在IllegalStateException操作失败。

形式上，计算定义如下。

首先，我们可以假设两Durations要增加正面不失一般性（即，(-X)+Y=Y-X，X+(-Y)=X-Y，(-X)+(-Y)=-(X+Y)）

两正Durations加法是简单地定义为字段的字段添加缺少的字段为0。

一场导致Duration将撤消当且仅当两输入Durations各自领域设置。

注意，lhs.add(rhs)永远成功如果lhs.signum()*rhs.signum()!=-1或者两者的归一化。
参数

rhs - Duration添加到这 Duration

结果

非空有效持续时间对象。

异常

NullPointerException -如果该参数为空。

IllegalStateException -如果两时间不能进行有意义的补充。例如，将负一天添加到一个月会导致这个异常。

另请参见：

subtract(Duration)

addTo
```
public abstract void addTo(Calendar calendar)
```
这一 Calendar对象添加时间。
电话里，为了Calendar.add(int,int)月，日，小时，分钟，秒和毫秒，如果这些领域都存在。因为Calendar类使用int持有价值，在有些情况下，这种方法不正确的工作（例如如果价值领域超过int范围）

另外，由于本期班是一个公历时间，这种方法不会给Calendar对象是基于一些其他的日历系统正常工作。

任何分数的这部分Duration对象超出毫秒会被忽略。例如，如果这个时间是“p1.23456s”，然后被加1秒，则增加234毫秒，而其余的将未使用的。

注意，因为Calendar.add(int, int)使用int，值超出范围int在其领域Duration会溢出到给定的Calendar。XMLGregorianCalendar.add(Duration)提供相同的基本操作方法，避免了溢出问题。

参数

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

异常

NullPointerException -如果日历参数为空。

addTo
```
public void addTo(Date date)
```
这一 Date对象添加时间。
给定的日期是先转换成一个GregorianCalendar，然后持续时间增加addTo(Calendar)方法完全一样。

更新的时间然后再转换成Date对象和用于更新了Date对象。

这种有点重复的计算是必要的，明确地确定了几个月和几年的持续时间。

参数

date -约会对象的值将被修改。

异常

NullPointerException -如果日期参数为空。

subtract
```
public Duration subtract(Duration rhs)
```
计算出一个新的时间的价值是this-rhs。

例如:
```
“1天”-“- 3天”=“4天”“1年”“1天”=时”（1小时，50分钟）”，“20分钟”=“（1小时，30分钟）”“15小时”-“- 3天”=“3天15小时”“1年”-“- 1天”=“1年1天”
```
因为没有办法有效地减去1天1个月，在有些情况下，在IllegalStateException操作失败。

正式的计算定义如下。首先，我们可以假设两Durations都正不失一般性。（即，(-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 -如果该参数为空。

另请参见：

add(Duration)

multiply
```
public Duration multiply(int factor)
```
计算出一个新的时间的价值比这更长时间的价值factor倍。

提供了这种方法的方便性。它在功能上相当于下面的代码：
```
乘（新BigDecimal（字符串值（因子）））
```
参数

factor因子倍的新 Duration创造。

结果

新的 Duration， factortimes比这 Duration更长。

另请参见：

multiply(BigDecimal)

multiply
```
public abstract Duration multiply(BigDecimal factor)
```
计算出一个新的时间的价值超过这个时间的价值 factor倍。
例如,
```
“岭”（1个月）*“12”=“P12M”（12个月）“pt1m”（1分钟）*“0.3”=“pt18s”（18秒）“岭”（1个月）* 1.5 =时
```
由于Duration类是不可变的，这种方法不改变该对象的值。它只计算一个新的持续时间对象并返回它。

该操作将进行现场实地与BigDecimal精度。由于除秒以外的所有字段都被限制为保持整数，计算所产生的任何分数都将向下执行到下一个较低的单元。例如，如果你把“PID”（1天）和“0.5”，那么这将是0.5天，它将被带到“pt12h”（12小时）。当分数月不能进行有意义的进行下去的日子，或一个月，这将导致一个IllegalStateException被。例如，如果你多个一个月0.5。

为了避免IllegalStateException，使用normalizeWith(Calendar)法去除的年和月的领域。
参数

factor -乘

结果

返回一个非空的有效 Duration对象

异常

IllegalStateException如果运行在月场产生的分数。

NullPointerException -如果 factor参数 null。

negate
```
public abstract Duration negate()
```
返回一个新的 Duration对象的价值 -this。
由于Duration类是不可变的，这种方法不改变该对象的值。它只计算一个新的持续时间对象并返回它。

结果

总是返回一个非空的有效 Duration对象。

normalizeWith
```
public abstract Duration normalizeWith(Calendar startTimeInstant)
```
以某一特定时间点为参考点，将数年数和数月转换为天场。

例如，一个月的时间对31天的开始时间实例“7月8日2003，17:40:32”。

形式上，计算完成如下：
1. 给定的日历对象被克隆
2. 年，月和日的领域将利用Calendar.add(int,int)方法添加到Calendar对象
3. 在计算的两个日历之间的差异在几毫秒内，并转换为天，如果一个剩余的发生是由于日光节约时间，它被丢弃
4. 计算的天，以及这个持续时间对象的小时，分和秒字段被用来构造一个新的持续时间对象。
请注意，由于日历类使用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 Durationand duration参数之间的关系， DatatypeConstants.LESSER， DatatypeConstants.EQUAL， DatatypeConstants.GREATER或 DatatypeConstants.INDETERMINATE。

异常

UnsupportedOperationException如果底层的实现不能合理地处理请求，例如W3C XML Schema允许任意大/小/精确值，请求可能无法实现的能力。

如果是 null duration NullPointerException。

另请参见：

isShorterThan(Duration)， isLongerThan(Duration)

isLongerThan
```
public boolean isLongerThan(Duration duration)
```
如果这个检查时间比另一个对象是Duration对象严格更长。

时间是“长”X比Y的当且仅当x > y在XML Schema规范1 3.2.6.2部分定义。

例如，“PID”（有一天）>“pt12h”（12小时）和“2Y”（两年）>“p23m”（23个月）。

参数

duration - Duration测试这 Duration反对。

结果

如果此对象表示的持续时间比给定的持续时间长。否则为假。

异常

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对象。

例如，“PID”（1天）等于“pt24h”（24小时）。

时间x等于y当且仅当时间t + X和T + Y是相同的所有测试时间在XML Schema 1规范的3.2.6.2部分指定的时刻。

值得注意的是，在两Durations“无与伦比”对方的情况下，如一个月30天。例如,
```
！新的时间（“岭”），isShorterThan（新时间（“P30d”））！新的时间（“岭”），isLongerThan（新时间（“P30d”））！新的时间（“岭”）。等于（新时间（“P30d”））
```
重写：

equals 方法重写，继承类 Object

参数

duration的对象比较 Duration反对。

结果

true如果这时间长度为 duration相同。 false如果 duration是 null，不是 Duration对象，或其长度不同，这个时间。

异常

UnsupportedOperationException如果底层的实现不能合理地处理请求，例如W3C XML Schema允许任意大/小/精确值，请求可能无法实现的能力。

另请参见：

compare(Duration duration)

hashCode
```
public abstract int hashCode()
```
返回与等于方法的定义一致的哈希代码。

重写：

hashCode 方法重写，继承类 Object

结果

此对象的哈希代码值。

另请参见：

Object.hashCode()

toString
```
public String toString()
```
返回该Duration Object一String表示。

结果是根据XML Schema 1规格的格式化和总可以解析回来为等价的Duration Object DatatypeFactory.newDuration(String lexicalRepresentation)。

正式，以下适用于任何Duration Object X：
```
新的持续时间（X tostring()）等于（X）。
```
重写：

toString 方法重写，继承类 Object

结果

非 null有效 String表示这 Duration。

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.

Class Duration

序关系

操作结束时间

允许值范围

构造方法摘要

方法摘要

Methods inherited from class java.lang.Object

Constructor Detail

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