Duration (Java 2 Platform SE 5.0) - JavaTM 2 Platform Standard Edition 5.0 API 规范中文版
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
| 上一个类 下一个类 | 框架 无框架 | |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | |||||||||
javax.xml.datatype
类 Duration
java.lang.Objectjavax.xml.datatype.Duration
public abstract class Duration
- 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.DURATIONX X X X X X DatatypeConstants.DURATION_DAYTIMEX X X X DatatypeConstants.DURATION_YEARMONTHX 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- 要比较的持续时间- 返回：
thisDuration和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"))- 参数：
duration- 非 null 的有效Duration对象。- 返回：
- 如果此持续时间与
duration长度相同，则返回true。如果duration不是Duration对象，或者其长度与此持续时间不同，则返回false。 - 抛出：
UnsupportedOperationException- 如果底层实现无法合理处理该请求，即 W3C XML Schema 允许任意大/小/精确的值，该请求可能超出实现功能。NullPointerException- 如果参数为 null。- 另请参见：
compare(Duration duration)
hashCode
public abstract int hashCode()
- 返回与 equals 方法的定义一致的哈希码。
- 返回：
- 此对象的一个哈希码值。
- 另请参见：
Object.hashCode()
toString
public String toString()
返回此
DurationObject的String表示形式。根据 XML Schema 1.0 规范格式化该结果，之后始终可以通过
DatatypeFactory.newDuration(String lexicalRepresentation)将其解析为等效的DurationObject。正式地说，以下内容保持任何
DurationObjectx：new Duration(x.toString()).equals(x)
- 返回：
- 此
Duration的非null有效String表示形式。
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
| 上一个类 下一个类 | 框架 无框架 | |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | |||||||||
提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。
版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。