モジュール java.xml
パッケージ javax.xml.datatype

クラスDuration

  • public abstract class Duration
extends Object

    W3C XML Schema 1.0仕様に定義された期間の不変の表現です。

    Durationオブジェクトはグレゴリオ時間の時間を表し、6つのフィールド(年、月、日、時間、分、秒)と記号(+/-)フィールドから構成されます。

    先頭の5つのフィールドには負以外(>=0)の整数またはnull (フィールドが設定されていないことを示す)が入り、2番目のフィールドには負以外の10進数またはnullが入ります。 負の記号は負のデュレーションを示します。

    このクラスは正誤表付きのXML Schema 1.0のデュレーション・データ型に簡単に使用できる多くのメソッドを提供しています。

    順序関係

    Durationオブジェクトは部分的な順序のみを持ち、AとBの2つの値は次のいずれかになります。

    1. A<B (AはBより短い)
    2. A>B (AはBより長い)
    3. A==B (AとBは同じデュレーション)
    4. A<>B (AとBの比較は判定不可)

    たとえば、30日と1か月は意味上比較できません。 compare(Duration duration)メソッドでこの関係を実装します。

    Durationオブジェクト間の順序関係の詳細は、isLongerThan(Duration)メソッドを参照してください。

    デュレーションの演算

    このクラスは、加算、減算、乗算などの一連の基本算術演算を実行します。 デュレーションには全体順序がないため、演算の組み合わせによっては、演算が失敗する可能性があります。 たとえば、1か月から15日を減算することはできません。 失敗する可能性のある詳しい状況については、これらのメソッドのJavadocを参照してください。

    さらに、Durationクラスが処理できるのは有限精度10進数にかぎられるため、数値によるデュレーションの除算は行われません。 たとえば、1秒割る3 (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オブジェクトがほかの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として取得します。値が存在しない場合は0を返します。
      abstract int hashCode()
      equalsメソッドの定義に一致するハッシュ・コードを返します。
      boolean isLongerThan​(Duration duration)
      このDurationオブジェクトがほかのDurationオブジェクトより確実に長いかどうかをチェックします。
      abstract boolean isSet​(DatatypeConstants.Field field)
      フィールドが設定されているかどうかをチェックします。
      boolean isShorterThan​(Duration 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()
        デフォルトの引数なしのコンストラクタです。

        注: Durationのインスタンスを構築するには、常にDatatypeFactoryを使用します。 このクラス上のコンストラクタは、一貫した状態のオブジェクトを生成するとは保証されておらず、将来削除される可能性があります。

    • メソッドの詳細

      • getSign

        public abstract int getSign()
        このデュレーションの記号を、-1、0、または1で返します。
        戻り値:
        このデュレーションが負の場合は -1、0の場合は0、正の場合は1。

      • getYears

        public int getYears()
        このDurationの年の値をintとして取得します。値が存在しない場合は0を返します。

        getYears()はgetField(DatatypeConstants.YEARS)の簡易メソッドです。

        戻り値がintの場合、intの範囲を超える年を含むDurationに対して不正な値が返されます。 精度の低下を防ぐため、getField(DatatypeConstants.YEARS)を使用してください。

        戻り値:
        年フィールドが存在する場合は、値をintとして返し、そうでない場合は0を返す。

      • getMonths

        public int getMonths()
        MONTHSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。 このメソッドの機能はMONTHSフィールドに有効であることを除けば、getYears()とまったく同じです。
        戻り値:
        このDurationの月。

      • getDays

        public int getDays()
        DAYSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。 このメソッドの機能はDAYSフィールドに有効であることを除けば、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)
        ミリ秒でデュレーションの長さを返します。

        秒フィールドの桁数がミリ秒の桁数より大きい場合、それらは単に破棄されます(つまり、0として切り捨てられます)。 たとえば、任意のCalendar値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)
        ミリ秒でデュレーションの長さを返します。

        秒フィールドの桁数がミリ秒の桁数より大きい場合、それらは単に破棄されます(つまり、0として切り捨てられます)。 たとえば、任意の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の場合、返される数値は負でない10進数値になります。
        パラメータ:
        field - 6つの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 - 6つのField定数(YEARS、MONTHS、DAYS、HOURS、MINUTES、またはSECONDS)のいずれか。
        戻り値:
        フィールドが存在する場合はtrue、そうでない場合はfalse。
        例外:
        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で演算が失敗する場合があります。

        形式上、計算は次のように定義されます。

        まず、加算する2つのDurationは、汎用性を失わずに、ともに正であるとします(つまり、(-X)+Y=Y-X、X+(-Y)=X-Y、(-X)+(-Y)=-(X+Y))

        2つの正のDurationの加算は、単にフィールドごとの加算として定義され、フィールドがない場合は0として扱われます。

        結果として得られるDurationのフィールドは、2つの入力Durationの各フィールドが設定されていない場合にのみ、設定されません。

        lhs.add(rhs)は、lhs.signum()*rhs.signum()!=-1またはそれらの両方とも正規化されている場合、常に成功します。

        パラメータ:
        rhs - このDurationに追加するDuration
        戻り値:
        null以外の有効なDurationオブジェクト。
        例外:
        NullPointerException - rhsパラメータがnullの場合。
        IllegalStateException - 2つのデュレーションを意味上追加できない場合。 たとえば、負の1日を1か月に追加すると、この例外が生成される。
        関連項目:
        subtract(Duration)

      • addTo

        public abstract void addTo​(Calendar calendar)
        この期間をCalendarオブジェクトに追加します。

        YEARS、MONTHS、DAYS、HOURS、MINUTES、SECONDS、およびMILLISECONDSフィールドが存在する場合、この順番で、Calendar.add(int,int)を呼び出します。 Calendarクラスではintを使用して値を保持するため、このメソッドが正常に機能しないことがあります(たとえば、フィールドの値がintの範囲を超える場合)。

        さらに、このDurationクラスはグレゴリオ・デュレーションであるため、指定されたCalendarオブジェクトがほかのカレンダ・システムに基づく場合、このメソッドは正しく機能しません。

        このDurationオブジェクトのミリ秒を超える小数部は単に無視されます。 たとえば、このデュレーションがP1.23456Sの場合、SECONDSに1が追加され、MILLISECONDSに234が追加されて、残りの部分は使用されません。

        Calendar.add(int, int)ではintを使用しているため、Durationのフィールドの値がintの範囲を超える場合に、指定したCalendarのオーバーフローやアンダーフローが発生します。 XMLGregorianCalendar.add(Duration)では、オーバーフローやアンダーフローの問題を回避しながら、このメソッドと同じ基本演算を実行できます。

        パラメータ:
        calendar - 値を変更するCalendarオブジェクト。
        例外:
        NullPointerException - calendarパラメータがnullの場合。

      • addTo

        public void addTo​(Date date)
        この期間をDateオブジェクトに追加します。

        指定した日付がまずGregorianCalendarに変換され、次にaddTo(Calendar)メソッドとまったく同じように、デュレーションが追加されます。

        更新された時点がふたたびDateオブジェクトに変換されて、指定した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で演算が失敗する場合があります。

        形式上、計算は次のように定義されます。 まず、2つのDurationは、汎用性を失わずに、ともに正であるとします。(つまり、(-X)-Y=-(X+Y)、X-(-Y)=X+Y、(-X)-(-Y)=-(X-Y))

        次に2つのデュレーションがフィールドごとに減算されます。 0以外のフィールドFの記号が最上位フィールドの記号と異なる場合、1 (Fが負の場合)または -1 (それ以外の場合)がFの隣の上位の単位から借りられます。

        このプロセスは、0以外のすべてのフィールドの記号が同じになるまで繰り返されます。

        日フィールドで借りが発生する場合(つまり、日を補正するために1か月または -1か月を借りる必要がある場合)、IllegalStateExceptionがスローされ、計算が失敗します。

        パラメータ:
        rhs - このDurationから減算するDuration。
        戻り値:
        このDurationからrhsを減算して作成される新しいDuration。
        例外:
        IllegalStateException - 2つのデュレーションを意味上減算できない場合。 たとえば、1か月から1日を減算すると、この例外が生成される。
        NullPointerException - rhsパラメータがnullの場合。
        関連項目:
        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がスローされます。 たとえば、1か月に0.5をかけた場合などです。

        IllegalStateExceptionを回避するには、normalizeWith(Calendar)メソッドを使用して、年および月フィールドを削除します。

        パラメータ:
        factor - かける数
        戻り値:
        null以外の有効なDurationオブジェクトを返す
        例外:
        IllegalStateException - 月フィールドの演算で小数が生成された場合。
        NullPointerException - factorパラメータがnullの場合。

      • negate

        public abstract Duration negate()
        値が-thisであるDurationを返します。

        Durationクラスは不変なため、このメソッドは、このオブジェクトの値を変更しません。 新しいDurationオブジェクトを計算して、それを返すだけです。

        戻り値:
        常にnull以外の有効なDurationオブジェクトを返す。

      • normalizeWith

        public abstract Duration normalizeWith​(Calendar startTimeInstant)
        特定の時点を参照点として使用して、年および月フィールドを日フィールドに変換します。

        たとえば、開始時間インスタンスを「July 8th 2003, 17:40:32」として、1か月のデュレーションを31日に正規化します。

        形式上、次のように計算されます。

        1. 指定したCalendarオブジェクトが複製される
        2. Calendar.add(int,int)メソッドを使用して、年、月、日フィールドがCalendarオブジェクトに追加される。
        3. 2つのCalendarの差がミリ秒で計算されてから日に変換される。サマー・タイムのために余剰が出た場合は、破棄される。
        4. 計算された日と、このDurationオブジェクトの時間、分、秒フィールドを使用して、新しいDurationオブジェクトが構築される。

        Calendarクラスではintを使用して、年および月の値を保持するため、このDurationオブジェクトの年または月フィールドに著しく大きな値を保持する場合に、このメソッドは予想しない結果を生成することがあります。

        パラメータ:
        startTimeInstant - Calendar参照点。
        戻り値:
        このDurationの年および月の、日としてのDuration。
        例外:
        NullPointerException - startTimeInstantパラメータがnullの場合。

      • isLongerThan

        public boolean isLongerThan​(Duration duration)
        このDurationオブジェクトがほかのDurationオブジェクトより確実に長いかどうかをチェックします。

        XMLスキーマ1.0仕様のセクション3.2.6.2で定義されているX> Yの場合に限り、継続時間XはYより"longer"です。

        たとえば、P1D(1日)>PT12H(12時間)、およびP2Y(2年)>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パラメータがDurationより短い場合はtrue、そうでない場合はfalse。
        例外:
        UnsupportedOperationException - W3C XML Schemaが大きい、小さい、あるいは正確な値を任意に許可するなど、実装が要求を適切に処理できない場合は、要求が実装能力を超えている可能性がある。
        NullPointerException - durationがnullの場合。
        関連項目:
        isLongerThan(Duration duration), compare(Duration duration)

      • equals

        public boolean equals​(Object duration)
        このDurationオブジェクトがほかのDurationオブジェクトと等しいかどうかをチェックします。

        たとえば、P1D (1日)はPT24H (24時間)と同じです。

        t+Xとt+Yの時点がXML Schema 1.0仕様のセクション3.2.6.2に指定されたすべてのテスト時点と同じ場合にのみ、Duration XはYと同じになります。

        たとえば、1か月と30日など、2つのDurationが「比較不可能」な場合があります。 次に例を示します。 

         !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と比較するオブジェクト。
        戻り値:
        このデュレーションがdurationと同じ長さの場合はtrue。durationがnullであるか、Durationオブジェクトでないか、またはこのデュレーションと長さが異なる場合はfalse。
        例外:
        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仕様に従ってフォーマットされており、あとでいつでもDatatypeFactory.newDuration(String lexicalRepresentation)によって、対応するDuration Objectに解析できます。

        形式上、以下は任意のDuration Object xを保持します。 

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

        オーバーライド:
        toString 、クラス:  Object
        戻り値:
        このDurationのnull以外の有効なString表現。