モジュール java.base

パッケージ java.time.temporal

インタフェースTemporalAccessor

既知のすべてのサブインタフェース:

ChronoLocalDate, ChronoLocalDateTime<D>, ChronoZonedDateTime<D>, Era, Temporal

既知のすべての実装クラス:

DayOfWeek, HijrahDate, HijrahEra, Instant, IsoEra, JapaneseDate, JapaneseEra, LocalDate, LocalDateTime, LocalTime, MinguoDate, MinguoEra, Month, MonthDay, OffsetDateTime, OffsetTime, ThaiBuddhistDate, ThaiBuddhistEra, Year, YearMonth, ZonedDateTime, ZoneOffset

public interface TemporalAccessor

時間的オブジェクト(日付、時間、オフセット、またはそれらのなんらかの組合せなど)への読取り専用アクセスを定義するフレームワークレベルのインタフェースです。

これは、日付、時間およびオフセット・オブジェクトのベース・インタフェース型です。 これは、情報をフィールドまたは問合せとして提供できるクラスによって実装されます。

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

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

サブインタフェースTemporalは、この定義を、より完全な時間的オブジェクトに対する調整と操作もサポートするインタフェースに拡張します。

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

実装要件:

このインタフェースは実装が可変であることを制限しませんが、不変にすることを強くお薦めします。

導入されたバージョン:

1.8

メソッドのサマリー

修飾子と型	メソッド	説明
default int	get(TemporalField field)	指定されたフィールドの値をintとして取得します。
long	getLong(TemporalField field)	指定されたフィールドの値をlongとして取得します。
boolean	isSupported(TemporalField field)	指定されたフィールドがサポートされているかどうかをチェックします。
default <R> R	query(TemporalQuery<R> query)	この日付/時間を問い合せます。
default ValueRange	range(TemporalField field)	指定されたフィールドの有効な値の範囲を取得します。

メソッドの詳細

isSupported

boolean isSupported(TemporalField field)

指定されたフィールドがサポートされているかどうかをチェックします。

これは、指定されたフィールドに対して日付/時間を問合せできるかどうかをチェックします。 falseの場合、rangeメソッドとgetメソッドを呼び出すと例外がスローされます。

実装要件:

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

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

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

パラメータ:

field - チェックするフィールド、nullはfalseを返す

戻り値:

フィールドに対して日付/時間を問合せできる場合はtrue、そうでない場合はfalse

range

default ValueRange range(TemporalField field)

指定されたフィールドの有効な値の範囲を取得します。

すべてのフィールドはlong整数で表現できます。 このメソッドは、その値の有効範囲を記述するオブジェクトを返します。 この時間的オブジェクトの値は、返される範囲の精度を向上するために使われます。 フィールドがサポートされていないか、他の何らかの理由で、日付/時間で範囲を返すことができない場合、例外がスローされます。

結果は有効な最小値と最大値を記述しているだけなので、それらを深く解釈しすぎないことが重要です。 たとえば、範囲内の値であっても、フィールドに対して無効な場合があります。

実装要件:

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

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

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

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

  if (field instanceof ChronoField) {
    if (isSupported(field)) {
      return field.range();
    }
    throw new UnsupportedTemporalTypeException("Unsupported field: " + field);
  }
  return field.rangeRefinedBy(this);
 

パラメータ:

field - 範囲を問い合わせるフィールド、null以外

戻り値:

フィールドの有効値の範囲。null以外

例外:

DateTimeException - フィールドの範囲を取得できない場合

UnsupportedTemporalTypeException - フィールドがサポートされていない場合

get

default int get(TemporalField field)

指定されたフィールドの値をintとして取得します。

これは、指定されたフィールドの値について日付/時間に問い合せます。 返される値は常にフィールドの値の有効な範囲内になります。 フィールドがサポートされていないか、他の何らかの理由で、日付/時間で値を返すことができない場合、例外がスローされます。

実装要件:

実装は、ChronoFieldで定義されたすべてのフィールドを確認して処理する必要があります。 フィールドがサポートされており、intの範囲を持っている場合は、フィールドの値を返す必要があります。 サポートされていない場合は、UnsupportedTemporalTypeExceptionをスローする必要があります。

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

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

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

  if (range(field).isIntValue()) {
    return range(field).checkValidIntValue(getLong(field), field);
  }
  throw new UnsupportedTemporalTypeException("Invalid field " + field + " + for get() method, use getLong() instead");
 

パラメータ:

field - 取得するフィールド、null以外

戻り値:

フィールドの値、値の有効な範囲内

例外:

DateTimeException - フィールドの値を取得できない場合、または値がフィールドの有効な値の範囲外の場合

UnsupportedTemporalTypeException - フィールドがサポートされていない場合、または値の範囲がintを超えている場合

ArithmeticException - 数値のオーバーフローが発生した場合

getLong

long getLong(TemporalField field)

指定されたフィールドの値をlongとして取得します。

これは、指定されたフィールドの値について日付/時間に問い合せます。 返される値はフィールドに有効な値の範囲外になることがあります。 フィールドがサポートされていないか、他の何らかの理由で、日付/時間で値を返すことができない場合、例外がスローされます。

実装要件:

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

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

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

パラメータ:

field - 取得するフィールド、null以外

戻り値:

フィールドの値

例外:

DateTimeException - フィールドの値を取得できない場合

UnsupportedTemporalTypeException - フィールドがサポートされていない場合

ArithmeticException - 数値のオーバーフローが発生した場合

query

default <R> R query(TemporalQuery<R> query)

この日付/時間を問い合せます。

これは指定された問合せ方法オブジェクトを使用してこの日付/時間を問い合わせます。

問合せは、日付/時間から情報を抽出するための主要なツールです。 それらは、戦略デザイン・パターンのように、問合せのプロセスを外部化して異なるアプローチを可能にするために存在します。 例として、日付がうるう年の2月29日の前日かどうかを確認する問合せや、次の誕生日までの日数を計算する問合せなどがあります。

もっとも一般的な問合せの実装は、LocalDate::fromやZoneId::fromなどのメソッド参照です。 その他の実装は、TemporalQuery上のstaticメソッドとして提供されます。

実装要件:

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

  if (query == TemporalQueries.zoneId() ||
        query == TemporalQueries.chronology() || query == TemporalQueries.precision()) {
    return null;
  }
  return query.queryFrom(this);
 

将来のバージョンでは、if文にさらに詳しい問合せを追加できます。

このインタフェースを実装し、このメソッドをオーバーライドするすべてのクラスは、TemporalAccessor.super.query(query)を呼び出す必要があります。 JDKクラスがデフォルト動作と同等の動作を提供する場合、JDKクラスはsuperの呼び出しを回避できますが、JDK以外のクラスはこの最適化を利用できないため、superを呼び出す必要があります。

実装は、デフォルト実装のif文に列挙されたいずれかの問合せの値を提供できる場合、それを提供する必要があります。 たとえば、時と分を格納するアプリケーション定義のHourMinクラスは、このメソッドを次のようにオーバーライドする必要があります。

  if (query == TemporalQueries.precision()) {
    return MINUTES;
  }
  return TemporalAccessor.super.query(query);
 

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

型パラメータ:

R - 結果の型

パラメータ:

query - 呼び出す問合せ、null以外

戻り値:

問合せ結果、nullが返されることがある(問合せによって定義される)

例外:

DateTimeException - 問合せできない場合

ArithmeticException - 数値のオーバーフローが発生した場合