模块  java.xml
软件包  javax.xml.datatype

Class Duration

  • public abstract class Duration
extends Object

    W3C XML Schema 1.0规范中定义的时间跨度的不可变表示。

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

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

    此类提供了许多方法，可以使用勘误表轻松地使用XML Schema 1.0的duration数据类型。

    订单关系

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

    • 构造方法摘要

      构造方法  
      构造器 描述
      Duration()
      默认的no-arg构造函数。

    • 构造方法详细信息

      • Duration

        public Duration()
        默认的no-arg构造函数。

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

    • 方法详细信息

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

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