java.lang.Object javax.xml.datatype.Duration
public abstract class Duration
W3C XML 模式 1.0 规范中定义的时间范围的不可变表示形式。
Duration 对象表示一段阳历时间,它由六个字段(years、months、days、hours、minutes 和 seconds)加上符号 (+/-) 字段组成。
前五个字段为非负 (>=0) 整数或 null(表示不设置字段),seconds 字段为非负小数或 null。负号指示负的持续时间。
此类提供大量的方法,使 XML 模式 1.0 及勘误中的 duration 数据类型的使用更简单。
Duration 对象只有部分顺序,其中值 A 和 B 可以是以下任一顺序:
例如,将 30 天与一个月比较没有意义。compare(Duration duration)
方法实现此关系。
有关 Duration
对象之间顺序关系的详细信息,请参阅 isLongerThan(Duration)
方法。
此类提供一组基本的算术运算,如加、减和乘。因为持续时间没有整体顺序,对一些组合操作,操作可能失败。例如,不能从 1 个月减去 15 天。有关发生此情形的详细情况,请参阅这些方法的 javadoc。
另外,不提供持续时间除以数字的除法,因为 Duration
类仅处理有限精度的十进制数字。例如,无法表示 1 秒除以 3。
但可以用乘以数字(如 0.3 或 0.333)替代除以 3 的除法。
即使 Duration
可以保持非常大或非常小的值,因为某些 Duration
的操作依赖于 Calendar
,所以一些方法不能在此类 Duration
上正常工作。受影响的方法记录其对 Calendar
的依赖。
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 模式日期/时间类型的名称。 |
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 |
构造方法详细信息 |
---|
public Duration()
注:总是使用 DatatypeFactory
来构造 Duration
实例。无法保证此类上的构造方法生成具有一致状态并可在以后移除的对象。
方法详细信息 |
---|
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 模式日期/时间数据类型之一不匹配。
public abstract int getSign()
public int getYears()
获取此 Duration
以 int
表示的 years 值,如果不存在,则值为 0
。
getYears()
是 getField(DatatypeConstants.YEARS)
的一个便捷方法。
由于返回值是 int
,所以对于具有超出 int
范围的年值的 Duration
,返回不正确的值。使用 getField(DatatypeConstants.YEARS)
避免可能的精度丢失。
int
表示的值,否则返回
0
。
public int getMonths()
getYears()
相似。
Duration
的月。
public int getDays()
getYears()
相似。
Duration
的日。
public int getHours()
getYears()
相似。
Duration
的时。
public int getMinutes()
getYears()
相似。
Duration
的分。
public int getSeconds()
getYears()
相似。
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。
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)
public abstract Number getField(DatatypeConstants.Field field)
Number
对象。 就 YEARS、MONTHS、DAYS、HOURS 和 MINUTES 来说,返回的数字将是一个非负整数。就 seconds 来说,返回的数字可以是一个非负的十进制值。
field
- 六个字段常量之一(YEARS、MONTHS、DAYS、HOURS、MINUTES 或 SECONDS。)
Number
对象。如果不存在,则返回 null。对于 YEARS、MONTHS、DAYS、HOURS 和 MINUTES,此方法返回
BigInteger
对象。对于 SECONDS,此方法返回
BigDecimal
。
NullPointerException
- 如果
field
为
null
。
public abstract boolean isSet(DatatypeConstants.Field field)
field
- 六个字段常量之一(YEARS、MONTHS、DAYS、HOURS、MINUTES 或 SECONDS。)
NullPointerException
- 如果字段参数为 null。
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
NullPointerException
- 如果 rhs 参数为 null。
IllegalStateException
- 如果两个持续时间的相加没有意义。例如,将负的一天添加到一月将导致此异常。
subtract(Duration)
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。
public void addTo(Date date)
Date
对象。
将给定的数据首先转换为 GregorianCalendar
,然后完全按照 addTo(Calendar)
方法添加持续时间。
然后将更新的时间点转换回 Date
对象,并用于更新给定的 Date
对象。
此冗余计算对明确地确定月和年的持续时间是必需的。
date
- 值将被修改的日期对象。
NullPointerException
- 如果日期参数为 null。
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)
public Duration multiply(int factor)
计算新的持续时间,值为此持续时间值的 factor
倍。
提供此方法是为了方便使用。它在功能上等同于以下代码:
multiply(new BigDecimal(String.valueOf(factor)))
factor
- 要创建的新
Duration
的 Factor 倍数。
Duration
的
factor
倍的新
Duration
。
multiply(BigDecimal)
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
- 相乘的因子
Duration
对象
IllegalStateException
- 如果操作在 months 字段中生成小数。
NullPointerException
- 如果
factor
参数为
null
。
public abstract Duration negate()
-this
的新
Duration
对象。
由于 Duration
类是不可变的,所以此方法不更改此对象的值。它仅计算新的 Duration 对象,并返回它。
Duration
对象。
public abstract Duration normalizeWith(Calendar startTimeInstant)
通过使用特定的时间点作为参考点,将 years 和 months 字段转换为 days 字段。
例如,一个月的持续时间可以标准化为 31 天,给出的时间点是 "July 8th 2003, 17:40:32"。
正式地说,应按以下方法进行计算:
Calendar.add(int,int)
方法将 years、months 和 days 字段添加到 Calendar
对象注意,由于 Calendar 类使用 int
保持年和月的值,所以如果此持续时间对象在 years 或 months 字段中保持非常大的值,则此方法可能产生不可预料的结果。
startTimeInstant
-
Calendar
引用点。
Duration
的年和月的
Duration
。
NullPointerException
- 如果 startTimeInstant 参数为 null。
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)
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
。
UnsupportedOperationException
- 如果底层实现无法合理处理该请求,例如,W3C XML 模式允许任意大/小/精确的值,该请求可能超出实现功能。
NullPointerException
- 如果
duration
为 null。
isShorterThan(Duration)
,
compare(Duration duration)
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)
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"))
duration
- 用来对照比较此
Duration
的对象。
duration
长度相同,则返回
true
。如果
duration
是
null
,而不是
Duration
对象,或者其长度与此持续时间不同,则返回
false
。
UnsupportedOperationException
- 如果底层实现无法合理处理该请求,例如,W3C XML 模式允许任意大/小/精确的值,该请求可能超出实现功能。
compare(Duration duration)
public abstract int hashCode()
Object.hashCode()
public String toString()
返回此 Duration
Object
的 String
表示形式。
根据 XML 模式 1.0 规范格式化该结果,之后始终可以通过 DatatypeFactory.newDuration(String lexicalRepresentation)
将其解析为等效的 Duration
Object
。
正式地说,以下内容保持任何 Duration
Object
x:
new Duration(x.toString()).equals(x)
Duration
的非
null
有效
String
表示形式。