构造方法详细信息

• Duration

  public Duration()

  默认的no-arg构造函数。

  注意：始终使用DatatypeFactory构造的一个实例Duration 。 无法保证此类上的构造函数生成具有一致状态的对象，并且将来可能会将其删除。

方法详细信息

• getXMLSchemaType

  public QName getXMLSchemaType()

  返回此实例映射到的XML Schema日期/时间类型的名称。 类型是根据设置的字段计算的，即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 - 如果set字段的组合与XML Schema日期/时间数据类型之一不匹配。

• 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)可以避免可能的精度损失。

  结果

  如果存在years字段， int其值返回为 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)

  以毫秒为单位返回持续时间的长度。

  如果秒字段携带的数字多于毫秒级，那么这些数字将被简单地丢弃（换句话说，舍入为零。）例如，对于任何日历值x ，

    new Duration("PT10.00099S").getTimeInMills(x) == 10000
   new Duration("-PT10.00099S").getTimeInMills(x) == -10000 

  请注意，此方法使用addTo(Calendar)方法，该方法可能Duration正常使用Duration在其字段中具有非常大值的对象。 有关详细信息，请参阅addTo(Calendar)方法。

  参数

  startInstant - 一个月/一年的长度各不相同。 startInstant用于消除此差异的歧义。 具体来说，此方法返回startInstant和startInstant+duration之间的差异

  结果

  startInstant和 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正常使用Duration在其字段中具有非常大值的对象。 有关详细信息，请参阅addTo(Date)方法。

  参数

  startInstant - 一个月/一年的长度各不相同。 startInstant用于消除此差异的歧义。 具体来说，此方法返回startInstant和startInstant+duration之间的差异。

  结果

  startInstant和 startInstant加上此 Duration之间的毫秒 Duration

  异常

  NullPointerException - 如果startInstant参数为null。

  另请参见：

  getTimeInMillis(Calendar)

• getField

  public abstract Number getField​(DatatypeConstants.Field field)

  获取字段的值。 持续时间对象的字段可以包含任意大值。 因此，此方法旨在返回Number对象。 在YEARS，MONTHS，DAYS，HOURS和MINUTES的情况下，返回的数字将是非负整数。 在秒的情况下，返回的数字可以是非负十进制值。

  参数

  字段 - 六个场常数之一（YEARS，MONTHS，DAYS，HOURS，MINUTES或SECONDS。）

  结果

  如果指定的字段存在，则此方法返回表示其值的非null非负Number对象。 如果不存在，则返回null。 对于YEARS，MONTHS，DAYS，HOURS和MINUTES，此方法返回BigInteger对象。 对于SECONDS，此方法返回BigDecimal 。

  异常

  NullPointerException - 如果 字段是 null 。

• isSet

  public abstract boolean isSet​(DatatypeConstants.Field field)

  检查是否设置了字段。 持续时间对象的字段可能存在也可能不存在。 此方法可用于测试是否存在字段。

  参数

  字段 - 六个场常数之一（年，月，日，小时，分钟或秒）。

  结果

  如果该字段存在，则为true。 如果不是假的。

  异常

  NullPointerException - 如果field参数为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类使用int来保存值，所以在某些情况下此方法将无法正常工作（例如，如果字段的值超出int的范围。）

  此外，由于此持续时间类是格里高利持续时间，因此如果给定的Calendar对象基于某些其他日历系统，则此方法将无法正常工作。

  将忽略此Duration对象超过毫秒的任何小数部分。 例如，如果此持续时间为“P1.23456S”，则将1添加到SECONDS，将234添加到MILLISECONDS，其余的将不使用。

  需要注意的是，因为Calendar.add(int, int)是使用int ， Duration与超越的范围值int在其领域会造成溢/下溢给定Calendar 。 XMLGregorianCalendar.add(Duration)提供与此方法相同的基本操作，同时避免上溢/下溢问题。

  参数

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

  异常

  NullPointerException - 如果calendar参数为null。

• 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 。

  重复该过程直到所有非零字段具有相同的符号。

  如果借用发生在days字段中（换句话说，如果计算需要借用1或-1个月来补偿天数），则计算失败，抛出IllegalStateException 。

  参数

  rhs - Duration从这个减去 Duration 。

  结果

  新增 Duration从这个 Duration减去 rhs得到。

  异常

  IllegalStateException - 如果无法有效地减去两个持续时间。 例如，从一个月减去一天会导致此异常。

  NullPointerException - 如果rhs参数为null。

  另请参见：

  add(Duration)

• multiply

  public Duration multiply​(int factor)

  计算一个新的持续时间，其值比此持续时间的值长factor倍。

  提供该方法是为了方便起见。 它在功能上等同于以下代码：

    multiply(new BigDecimal(String.valueOf(factor))) 

  参数

  factor - 创建新 Duration因子乘以更长时间。

  结果

  新 Duration比 Duration长 factor倍。

  另请参见：

  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 - 要乘以

  结果

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

  异常

  IllegalStateException - 如果操作在月份字段中生成分数。

  NullPointerException - 如果 factor参数为 null 。

• negate

  public abstract Duration negate()

  返回一个新的Duration对象，其值为-this 。

  由于Duration类是不可变的，因此此方法不会更改此对象的值。 它只是计算一个新的Duration对象并返回它。

  结果

  始终返回非null有效的 Duration对象。

• normalizeWith

  public abstract Duration normalizeWith​(Calendar startTimeInstant)

  通过使用特定时间点作为参考点，将年和月字段转换为日期字段。

  例如，在给定开始时间实例“2003年7月8日，17：40：32”的情况下，一个月的持续时间归一化为31天。

  形式上，计算如下：

  1. 克隆给定的Calendar对象
  2. 使用Calendar.add(int,int)方法将年，月和日字段添加到Calendar对象
  3. 两个日历之间的差异以毫秒为单位计算并转换为天数，如果由于夏令时间而出现余数，则将其丢弃
  4. 此持续时间对象的计算天数以及小时，分钟和秒字段用于构造新的Duration对象。

  请注意，由于Calendar类使用int来保存年份和月份的值，因此如果此持续时间对象在年份或月份字段中保持非常大的值，则此方法可能会产生意外结果。

  参数

  startTimeInstant - Calendar参考点。

  结果

  Duration的年，这几个月 Duration为天。

  异常

  NullPointerException - 如果startTimeInstant参数为null。

• 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比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()

  返回此Duration Object的String表示。

  其结果是根据XML模式1.0规范格式化的，并且可以总是解析稍后成等效Duration Object通过DatatypeFactory.newDuration(String lexicalRepresentation) 。

  正式地，以下适用于任何Duration Object x：

    new Duration(x.toString()).equals(x) 

  重写：

  toString在类 Object

  结果

  非 null此 Duration有效 String表示 Duration 。