モジュール java.base
パッケージ java.time.temporal

インタフェースTemporal

  • すべてのスーパー・インタフェース:
    TemporalAccessor
    既知のすべてのサブインタフェース:
    ChronoLocalDate, ChronoLocalDateTime<D>, ChronoZonedDateTime<D>
    既知のすべての実装クラス:
    HijrahDate, Instant, JapaneseDate, LocalDate, LocalDateTime, LocalTime, MinguoDate, OffsetDateTime, OffsetTime, ThaiBuddhistDate, Year, YearMonth, ZonedDateTime
    public interface Temporal
extends TemporalAccessor
    時間的オブジェクト(日付、時間、オフセット、またはそれらのなんらかの組合せなど)への読取り/書込みアクセスを定義するフレームワークレベルのインタフェースです。

    これは、plusとminusを使用して操作できる完全な日付、時間およびオフセット・オブジェクトのベース・インタフェース型です。 これは、情報をフィールドまたは問合せとして提供および操作できるクラスによって実装されます。 このインタフェースの読取り専用バージョンについては、TemporalAccessorを参照してください。

    ほとんどの日時情報は、数値として表されます。 これらは、大きな値を処理するためにlongで数値を保持するTemporalFieldを使用してモデル化されています。 年、月および「月の日」はフィールドの簡単な例ですが、これらにはインスタントとオフセットも含まれています。 フィールドの標準セットについては、ChronoFieldを参照してください。

    日付/時間情報の2つの部分(chronologyおよびtime-zone)を数値で表すことはできません。 これらには、TemporalQueryで定義されるstaticメソッドを使用する問合せを介してアクセスできます。

    このインタフェースはフレームワークレベルのインタフェースであり、アプリケーション・コードで広範囲にわたって使用しないようにしてください。 かわりに、LocalDateなどの具象型のインスタンスを作成して使い回してください。 これには様々な理由がありますが、その1つはこのインタフェースの実装がISO以外の暦体系になっている可能性があることです。 この問題の詳細は、ChronoLocalDateを参照してください。

    実装するケース

    3つの条件を満たすクラスでは、このインタフェースを実装する必要があります。

    • TemporalAccessorのように、日付/時間/オフセット情報へのアクセスを提供する
    • フィールドのセットが最大から最小まで連続している
    • フィールドのセットが完全であるため、他のフィールドを使用しなくても、表現されるフィールドの値の有効範囲を定義できる

    これを、4つの例で説明します。

    • LocalDateは、日から永遠まで連続し、外部情報がなくても各日付の有効性を判定できるフィールドのセットを表すため、このインタフェースを実装します。 したがって、plus/minusを正しく実装できます。
    • LocalTimeは、ナノ秒から日まで連続し、外部情報がなくても有効性を判定できるフィールドのセットを表すため、このインタフェースを実装します。 したがって、日を折り返すことにより、plus/minusを正しく実装できます。
    • MonthDay(月と「月の日」の組合せ)は、このインタフェースを実装しません。 この組合せは、年内の日から月まで連続していますが、「月の日」の値の有効範囲を定義するのに十分な情報を備えていません。 したがって、plus/minusを正しく実装できません。
    • 曜日と「月の日」の組合せ(「13日の金曜日」)は、このインタフェースを実装できません。 これは、週に対する日と月に対する日が重複しているため、連続したフィールドのセットを表していません。
    実装要件:
    このインタフェースは実装が可変であることを制限しませんが、不変にすることを強くお薦めします。 すべての実装はComparableである必要があります。
    導入されたバージョン:
    1.8

    • メソッドの詳細

      • isSupported

        boolean isSupported​(TemporalUnit unit)
        指定された単位がサポートされているかどうかをチェックします。

        これは、指定された単位をこの日付/時間に対して加算または減算できるかどうかをチェックします。 falseの場合、plus(long, TemporalUnit)およびminusメソッドの呼び出しは、例外をスローします。

        実装要件:
        実装は、ChronoUnitで定義されたすべての単位を確認して処理する必要があります。 単位がサポートされている場合はtrueを返し、それ以外の場合はfalseを返す必要があります。

        フィールドがChronoUnitでない場合、このメソッドの結果は、引数としてthisを渡してTemporalUnit.isSupportedBy(Temporal)を呼び出すことによって取得されます。

        実装は、この読取り専用メソッドが呼び出されたときに識別可能な状態が変更されていないことを確認する必要があります。

        パラメータ:
        unit - チェックする単位、nullはfalseを返す
        戻り値:
        単位を加算/減算できる場合はtrue、できない場合はfalse

      • with

        default Temporal with​(TemporalAdjuster adjuster)
        調整を行って、このオブジェクトと同じ型の調整済のオブジェクトを返します。

        これは、指定されたアジャスタのルールに従って、この日付/時間を調整します。 単純なアジャスタは、年フィールドなどの1つのフィールドだけを設定するなどです。 複雑なアジャスタは、日付を月の最後の日に設定するなどです。 一般的な調整の選択は、TemporalAdjustersで指定します。 これらには、「月の最後の日」や「次の水曜日」を見つけることが含まれます。 アジャスタは、さまざまな長さの月やうるう年などの特別なケースの処理を担当します。

        このメソッドを使用する方法と理由を示すいくつかのサンプル・コード: 

          date = date.with(Month.JULY);        // most key classes implement TemporalAdjuster
  date = date.with(lastDayOfMonth());  // static import from Adjusters
  date = date.with(next(WEDNESDAY));   // static import from Adjusters and DayOfWeek
        実装要件:

        実装は、このオブジェクトまたは指定された時間的オブジェクトのどちらも変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。

        デフォルト実装は、このコードと同等に動作する必要があります。 

          return adjuster.adjustInto(this);
        パラメータ:
        adjuster - 使用するアジャスタ、null以外
        戻り値:
        指定された調整を行った同じ型のオブジェクト、null以外
        例外:
        DateTimeException - 調整を実行できない場合
        ArithmeticException - 数値のオーバーフローが発生した場合

      • with

        Temporal with​(TemporalField field,
              long newValue)
        指定されたフィールドを変更して、このオブジェクトと同じ型のオブジェクトを返します。

        これは、指定されたフィールドの値を変更して、このオブジェクトに基づいて新しいオブジェクトを返します。 たとえば、LocalDateで、これは年、月、または「月の日」を設定するために使用できます。 返されるオブジェクトはこのオブジェクトと同じ識別可能な型を持ちます。

        フィールドの変更が完全には定義されていない場合もあります。 たとえば、ターゲット・オブジェクトが1月31日を表す日付である場合、月を2月に変更することは不明な場合があります。 このようなケースでは、フィールドは結果の解決を担当します。 通常は1つ前の有効な日付が選択され、この例の場合は2月の最後の有効な日になります。

        実装要件:
        実装は、ChronoFieldで定義されたすべてのフィールドを確認して処理する必要があります。 フィールドがサポートされている場合は、調整を行う必要があります。 サポートされていない場合は、UnsupportedTemporalTypeExceptionをスローする必要があります。

        フィールドがChronoFieldでない場合、このメソッドの結果は、第1引数としてthisを渡してTemporalField.adjustInto(Temporal, long)を呼び出すことによって取得されます。

        実装は、このオブジェクトを変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。

        パラメータ:
        field - 結果に設定するフィールド、null以外
        newValue - 結果のフィールドの新しい値
        戻り値:
        指定されたフィールドが設定された同じ型のオブジェクト、null以外
        例外:
        DateTimeException - フィールドを設定できない場合
        UnsupportedTemporalTypeException - フィールドがサポートされていない場合
        ArithmeticException - 数値のオーバーフローが発生した場合

      • plus

        default Temporal plus​(TemporalAmount amount)
        このオブジェクトと同じ型のオブジェクトにある時間を追加したものを返します。

        これは、このtemporal (一時)を調整し、指定された量のルールに従って加算します。 この量は通常Periodですが、Durationなど、TemporalAmountインタフェースを実装する他のどの型であってもかまいません。

        このメソッドを使用する方法と理由を示すいくつかのサンプル・コード: 

          date = date.plus(period);                // add a Period instance
  date = date.plus(duration);              // add a Duration instance
  date = date.plus(workingDays(6));        // example user-written workingDays method

        plusの後にminusを呼び出しても、同じ日付/時間が返されることは保証されません。

        実装要件:

        実装は、このオブジェクトまたは指定された時間的オブジェクトのどちらも変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。

        デフォルト実装は、このコードと同等に動作する必要があります。 

          return amount.addTo(this);
        パラメータ:
        amount - 追加する量、null以外
        戻り値:
        指定された調整を行った同じ型のオブジェクト、null以外
        例外:
        DateTimeException - 加算できない場合
        ArithmeticException - 数値のオーバーフローが発生した場合

      • plus

        Temporal plus​(long amountToAdd,
              TemporalUnit unit)
        このオブジェクトと同じ型のオブジェクトに指定された期間を追加したものを返します。

        このメソッドは、指定された期間を加算して、このオブジェクトに基づいて新しいオブジェクトを返します。 たとえば、LocalDateで、これは年、月、または日の数を加算するために使用できます。 返されるオブジェクトはこのオブジェクトと同じ識別可能な型を持ちます。

        フィールドの変更が完全には定義されていない場合もあります。 たとえば、ターゲット・オブジェクトが1月31日を表す日付である場合、1か月を加算することは不明な場合があります。 このようなケースでは、フィールドは結果の解決を担当します。 通常は1つ前の有効な日付が選択され、この例の場合は2月の最後の有効な日になります。

        実装要件:
        実装は、ChronoUnitで定義されたすべての単位を確認して処理する必要があります。 単位がサポートされている場合は、加算を行う必要があります。 サポートされていない場合は、UnsupportedTemporalTypeExceptionをスローする必要があります。

        単位がChronoUnitでない場合、このメソッドの結果は、第1引数としてthisを渡してTemporalUnit.addTo(Temporal, long)を呼び出すことによって取得されます。

        実装は、このオブジェクトを変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。

        パラメータ:
        amountToAdd - 加算する指定された単位の量、負の場合もある
        unit - 加算する量の単位、nullでない
        戻り値:
        指定された期間を加算した同じ型のオブジェクト、null以外
        例外:
        DateTimeException - 単位を加算できない場合
        UnsupportedTemporalTypeException - 単位がサポートされていない場合
        ArithmeticException - 数値のオーバーフローが発生した場合

      • minus

        default Temporal minus​(TemporalAmount amount)
        量を減算して、このオブジェクトと同じ型のオブジェクトを返します。

        これは、このtemporal (一時)を調整し、指定された量のルールに従って減算します。 この量は通常Periodですが、Durationなど、TemporalAmountインタフェースを実装する他のどの型であってもかまいません。

        このメソッドを使用する方法と理由を示すいくつかのサンプル・コード: 

          date = date.minus(period);               // subtract a Period instance
  date = date.minus(duration);             // subtract a Duration instance
  date = date.minus(workingDays(6));       // example user-written workingDays method

        plusの後にminusを呼び出しても、同じ日付/時間が返されることは保証されません。

        実装要件:

        実装は、このオブジェクトまたは指定された時間的オブジェクトのどちらも変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。

        デフォルト実装は、このコードと同等に動作する必要があります。 

          return amount.subtractFrom(this);
        パラメータ:
        amount - 減算する量、null以外
        戻り値:
        指定された調整を行った同じ型のオブジェクト、null以外
        例外:
        DateTimeException - 減算ができない場合
        ArithmeticException - 数値のオーバーフローが発生した場合

      • minus

        default Temporal minus​(long amountToSubtract,
                       TemporalUnit unit)
        指定された期間を減算して、このオブジェクトと同じ型のオブジェクトを返します。

        このメソッドは、指定された期間を減算して、このオブジェクトに基づいて新しいオブジェクトを返します。 たとえば、LocalDateで、これは年、月、または日の数を減算するために使用できます。 返されるオブジェクトはこのオブジェクトと同じ識別可能な型を持ちます。

        フィールドの変更が完全には定義されていない場合もあります。 たとえば、ターゲットオブジェクトが3月31日を表す日付である場合、1か月を減算することは不明な場合があります。 このようなケースでは、フィールドは結果の解決を担当します。 通常は1つ前の有効な日付が選択され、この例の場合は2月の最後の有効な日になります。

        実装要件:
        実装は、デフォルトのメソッド動作と同等の方法で動作する必要があります。

        実装は、このオブジェクトを変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。

        デフォルト実装は、このコードと同等に動作する必要があります。 

          return (amountToSubtract == Long.MIN_VALUE ?
      plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));
        パラメータ:
        amountToSubtract - 減算する指定された単位の量、負の場合もある
        unit - 減算する量の単位、nullでない
        戻り値:
        指定された期間が減算された同じ型のオブジェクト、null以外
        例外:
        DateTimeException - 単位を減算できない場合
        UnsupportedTemporalTypeException - 単位がサポートされていない場合
        ArithmeticException - 数値のオーバーフローが発生した場合

      • until

        long until​(Temporal endExclusive,
           TemporalUnit unit)
        別のtemporalまでの時間量を指定された単位で計算します。

        これは、1つのTemporalUnitの形で2つの時間的オブジェクト間の時間量を計算します。 開始点と終了点はthisと指定された時間的オブジェクトです。 終了点は、開始点と同じ型に変換されます(異なる場合)。 終了が開始より前である場合、結果は負になります。 たとえば、2つの時間的オブジェクト間の時間数は、startTime.until(endTime, HOURS)を使用して計算できます。

        計算では、2つの時間的オブジェクト間の完全な単位の数を表す整数を返します。 たとえば、時間11:30と13:29の間の量は、2時間には1分足りないため、時間数では1時間だけになります。

        このメソッドを使用する等価な方法が2つあります。 1つ目はこのメソッドを直接呼び出すことです。 2つ目はTemporalUnit.between(Temporal, Temporal)を使用することです。 

           // these two lines are equivalent
   temporal = start.until(end, unit);
   temporal = unit.between(start, end);
        この選択は、コードが読みやすくなるのはどちらかに基づいて行ってください。

        たとえば、このメソッドを使用すると、2つの日付間の日数を計算できます。 

          long daysBetween = start.until(end, DAYS);
  // or alternatively
  long daysBetween = DAYS.between(start, end);
        実装要件:
        実装は、入力の時間的オブジェクトが実装と同じ識別可能な型であることを確認することから始める必要があります。 次に、ChronoUnitのすべてのインスタンスの計算を実行する必要があります。 サポートされていないChronoUnitインスタンスに対しては、UnsupportedTemporalTypeExceptionをスローする必要があります。

        単位がChronoUnitでない場合、このメソッドの結果は、thisを1つ目の引数として、変換される入力temporal (一時)を2つ目の引数として渡してTemporalUnit.between(Temporal, Temporal)を呼び出すことによって取得します。

        要約すると、実装はこの擬似コードと同等の方法で動作する必要があります。 

          // convert the end temporal to the same type as this class
  if (unit instanceof ChronoUnit) {
    // if unit is supported, then calculate and return result
    // else throw UnsupportedTemporalTypeException for unsupported units
  }
  return unit.between(this, convertedEndTemporal);

        単位のbetweenメソッドは、2つの時間的オブジェクトがgetClass()によって評価されたまったく同じ型を持つ場合にのみ、呼び出す必要があります。

        実装は、この読取り専用メソッドが呼び出されたときに識別可能な状態が変更されていないことを確認する必要があります。

        パラメータ:
        endExclusive - このオブジェクトと同じ型に変換される、nullでない終了時間的オブジェクト(これを含まない)
        unit - 量を測定する単位、null以外
        戻り値:
        この時間的オブジェクトと指定されたオブジェクト間の、指定された単位での時間量(指定されたオブジェクトがこのオブジェクトより後の場合は正、このオブジェクトより前の場合は負)
        例外:
        DateTimeException - 量を計算できない場合、または終了時間的オブジェクトをこの時間的オブジェクトと同じ型に変換できない場合
        UnsupportedTemporalTypeException - 単位がサポートされていない場合
        ArithmeticException - 数値のオーバーフローが発生した場合