Module  java.xml
软件包  javax.xml.datatype

Class Duration


  • public abstract class Duration
extends Object

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

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

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

    该类提供了许多方法，使其易于使用具有勘误的XML Schema 1.0的持续时间数据类型。

    订单关系

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

    但是，您可以用乘数乘以3除以0.3或0.333。

    允许值范围

    由于Duration一些操作依赖于Calendar，即使Duration可以容纳非常大或非常小的值，某些方法可能无法在这样的Duration上正常工作。 受影响的方法记录了它们对Calendar的依赖。

    从以下版本开始：
    1.5
    另请参见：
    XMLGregorianCalendar.add(Duration)

    • 构造方法摘要

      构造方法  
      Constructor 描述
      Duration​()
      默认的无参数构造函数。

    • 方法摘要

      所有方法  接口方法  抽象方法  具体的方法 
      Modifier and Type 方法 描述
      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或 0 。
      abstract int hashCode​()
      返回与equals方法的定义一致的哈希码。
      boolean isLongerThan​(Duration duration)
      检查此持续时间对象是否严格超过另一个 Duration对象。
      abstract boolean isSet​(DatatypeConstants.Field field)
      检查是否设置了一个字段。
      boolean isShorterThan​(Duration duration)
      检查此持续时间对象是否严格短于另一个 Duration对象。
      Duration multiply​(int factor)
      计算一个新的持续时间，其值是该持续时间的值的 factor倍。
      abstract Duration multiply​(BigDecimal factor)
      计算一个新的持续时间，其值是该持续时间的值的 factor倍。
      abstract Duration negate​()
      返回值为 -this的新的 Duration对象。
      abstract Duration normalizeWith​(Calendar startTimeInstant)
      通过使用特定的时刻作为参考点，将几个月和几个字段转换为日期字段。
      Duration subtract​(Duration rhs)
      计算一个新的持续时间，值为 this-rhs 。
      String toString​()
      返回此 Duration Object的 String表示。

    • 构造方法详细信息

      • Duration

        public Duration​()
        默认的无参数构造函数。

        注意：始终使用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秒，将超过int的范围，将返回不正确的值。 使用getField(DatatypeConstants.YEARS)避免可能的精度损失。

        结果
        如果年份字段存在，则返回值为 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对象中正常工作。 有关详细信息，请参阅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之间的毫秒 startInstant加上此 Duration
        异常
        NullPointerException - 如果startInstant参数为空。
        另请参见：
        getTimeInMillis(Calendar)

      • getField

        public abstract Number getField​(DatatypeConstants.Field field)
        获取字段的值。 持续时间对象的字段可能包含任意大的值。 因此，此方法旨在返回一个Number对象。 在YEARS，MONTHS，DAYS，HOURS和MINUTES的情况下，返回的数字将为非负整数。 在秒的情况下，返回的数字可能是非负十进制值。
        参数
        field - 六个字段常量之一（YEARS，MONTHS，DAYS，HOURS，MINUTES或SECONDS）。
        结果
        如果指定的字段存在，则此方法返回一个表示其值的非空的非负Number对象。 如果不存在，返回null。 对于YEARS，MONTHS，DAYS，HOURS和MINUTES，此方法返回一个BigInteger对象。 对于SECONDS，此方法返回一个BigDecimal 。
        异常
        NullPointerException - 如果 field是 null 。

      • isSet

        public abstract boolean isSet​(DatatypeConstants.Field field)
        检查是否设置了一个字段。 持续时间对象的字段可能存在或可能不存在。 该方法可用于测试字段是否存在。
        参数
        field - 六个字段常量之一（YEARS，MONTHS，DAYS，HOURS，MINUTES或SECONDS）。
        结果
        如果现场存在，则为真。 假如不是。
        异常
        NullPointerException - 如果字段参数为空。

      • 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
        结果
        非空的有效持续时间对象。
        异常
        NullPointerException - 如果rhs参数为空。
        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 - 如果日历参数为空。

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

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

        如果在日期领域发生借款（换句话说，如果计算需要借用1个月或-1个月来补偿日子），则计算失败，则抛出一个IllegalStateException 。

        参数
        rhs - Duration减去 Duration 。
        结果
        新的 Duration创建从这 rhs减去 Duration 。
        异常
        IllegalStateException - 如果不能有意义地减去两个持续时间。 例如，从一个月减去一天会导致此异常。
        NullPointerException - 如果rhs参数为空。
        另请参见：
        add(Duration)

      • multiply

        public Duration multiply​(int factor)
        计算一个新的持续时间，其值是该持续时间的值的factor倍。

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

          multiply(new BigDecimal(String.valueOf(factor)))
        参数
        factor - 创建新的 Duration因子倍数。
        结果
        新的 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 。 由于除秒之外的所有字段都被限制为保持整数，所以计算产生的任何分数将被转移到下一个下一个单元。 例如，如果您将“P1D”（1天）乘以“0.5”，则将为0.5天，将其转入“PT12H”（12小时）。 当月份的几个月不能有意义地运转到几天，或一年到几个月，这将导致IllegalStateException被抛出。 例如，如果你多一个月0.5。

        为避免IllegalStateException ，请使用normalizeWith(Calendar)方法去除年和月的字段。

        参数
        factor - 乘以
        结果
        返回一个非空的有效 Duration对象
        异常
        IllegalStateException - 如果操作在月份字段中生成分数。
        NullPointerException - 如果 factor参数是 null 。

      • negate

        public abstract Duration negate​()
        返回值为-this的新的Duration对象。

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

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

      • normalizeWith

        public abstract Duration normalizeWith​(Calendar startTimeInstant)
        通过使用特定的时刻作为参考点，将几个月和几个字段转换为日期字段。

        例如，“开始时间”例如“2003年7月8日17:40:32”，一个月的持续时间正常化到31天。

        正式地，计算完成如下：

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

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

        参数
        startTimeInstant - Calendar参考点。
        结果
        Duration的这个 Duration几个月的日子。
        异常
        NullPointerException - 如果startTimeInstant参数为空。

      • isLongerThan

        public boolean isLongerThan​(Duration duration)
        检查此持续时间对象是否严格超过另一个Duration对象。

        当且仅当X> Y在XML Schema 1.0规范的3.2.6.2节定义时，X的持续时间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 Schema 1.0规范进行格式化，并且可以随时解析为Duration Object （ DatatypeFactory.newDuration(String lexicalRepresentation)） 。

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

          new Duration(x.toString()).equals(x)
        重写：
        toString在 Object
        结果
        A null有效 String表示此 Duration 。