モジュール java.base

パッケージ java.time.chrono

インタフェースEra

すべてのスーパー・インタフェース:

TemporalAccessor, TemporalAdjuster

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

HijrahEra, IsoEra, JapaneseEra, MinguoEra, ThaiBuddhistEra

public interface Era extends TemporalAccessor, TemporalAdjuster

時系列の紀元。

ほとんどの暦体系には、時系列を2つの紀元に分割する1つのエポックがあります。 ただし、一部の暦体系には各指導者の統治期間ごとに1つなど、複数の紀元があります。 すべての場合に、紀元は概念上、時系列の最大の区分です。 各暦は有効な紀元を取得するためのErasおよびChronology.erasと呼ばれる紀元を定義します。

たとえば、タイ仏暦体系では、時間をある1つの日付の前後で2つの紀元に分割しています。 それに対して、和暦体系では、各天皇の在位期間ごとに1つずつの紀元があります。

Eraのインスタンスは==演算子を使用して比較できます。

実装要件:

このインタフェースは、他のクラスが正常に動作するように、注意して実装する必要があります。 すべての実装はシングルトン(final、不変、スレッドセーフ)である必要があります。 可能な限り、列挙を使用することをお薦めします。

導入されたバージョン:

1.8

メソッドのサマリー

修飾子と型	メソッド	説明
default Temporal	adjustInto(Temporal temporal)	指定された時間的オブジェクトをこのオブジェクトと同じ紀元になるように調整します。
default int	get(TemporalField field)	この紀元から指定されたフィールドの値をintとして取得します。
default String	getDisplayName(TextStyle style, Locale locale)	この紀元のテキスト表現を取得します。
default long	getLong(TemporalField field)	この紀元から指定されたフィールドの値をlongとして取得します。
int	getValue()	暦によって定義された、紀元に関連付けられている数値を取得します。
default boolean	isSupported(TemporalField field)	指定されたフィールドがサポートされているかどうかをチェックします。
default <R> R	query(TemporalQuery<R> query)	指定された問合せを使用してこの紀元を問い合わせます。
default ValueRange	range(TemporalField field)	指定されたフィールドの有効な値の範囲を取得します。

メソッドの詳細

getValue

int getValue()

暦によって定義された、紀元に関連付けられている数値を取得します。 各暦は、事前定義された紀元と、暦の紀元を一覧表示するメソッドを定義します。

紀元を含むすべてのフィールドに、関連付けられた数値があります。 紀元の数値の意味は、これらの原則に従って、暦によって決定されます。

• エポック1970-01-01 (ISO)で使用される紀元の値は1になります。
• 以降の紀元は、値が順に大きくなります。
• 以前の紀元は、値が順に小さくなります。

戻り値:

紀元の数値

isSupported

default boolean isSupported(TemporalField field)

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

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

フィールドがChronoFieldの場合、ここに問合せを実装します。 ERAフィールドはtrueを返します。 他のすべてのChronoFieldインスタンスはfalseを返します。

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

定義:

インタフェースTemporalAccessorのisSupported

パラメータ:

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

戻り値:

フィールドがこの紀元でサポートされている場合はtrue、そうでない場合はfalse

range

default ValueRange range(TemporalField field)

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

範囲オブジェクトはフィールドの有効な最小値と最大値を表します。 この紀元は、返される範囲の精度を向上するために使われます。 範囲を返せない場合は、フィールドがサポートされていないか他のなんらかの理由で、例外がスローされます。

フィールドがChronoFieldの場合、ここに問合せを実装します。 ERAフィールドは範囲を返します。 他のすべてのChronoFieldインスタンスはUnsupportedTemporalTypeExceptionをスローします。

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

デフォルトの実装は、ISOなどの2つの紀元の暦体系に適した、ゼロから1のERAの範囲を返す必要があります。

定義:

インタフェースTemporalAccessorのrange

パラメータ:

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

戻り値:

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

例外:

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

UnsupportedTemporalTypeException - 単位がサポートされていない場合

get

default int get(TemporalField field)

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

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

フィールドがChronoFieldの場合、ここに問合せを実装します。 ERAフィールドは紀元の値を返します。 他のすべてのChronoFieldインスタンスはUnsupportedTemporalTypeExceptionをスローします。

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

定義:

インタフェースTemporalAccessorのget

パラメータ:

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

戻り値:

フィールドの値

例外:

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

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

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

getLong

default long getLong(TemporalField field)

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

これは、指定されたフィールドの値についてこの紀元に問い合せます。 値を返せない場合は、フィールドがサポートされていないか他のなんらかの理由で、例外がスローされます。

フィールドがChronoFieldの場合、ここに問合せを実装します。 ERAフィールドは紀元の値を返します。 他のすべてのChronoFieldインスタンスはUnsupportedTemporalTypeExceptionをスローします。

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

定義:

インタフェースTemporalAccessorのgetLong

パラメータ:

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

戻り値:

フィールドの値

例外:

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

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

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

query

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

指定された問合せを使用してこの紀元を問い合わせます。

これは指定された問合せ方法オブジェクトを使用して、この紀元を問い合わせます。 TemporalQueryオブジェクトは結果を取得するために使用するロジックを定義します。 このメソッドの結果を理解するには、問合せのドキュメントをお読みください。

このメソッドの結果は、thisを引数として渡して、指定した問合せでTemporalQuery.queryFrom(TemporalAccessor)メソッドを呼び出すことによって取得します。

定義:

インタフェースTemporalAccessorのquery

型パラメータ:

R - 結果の型

パラメータ:

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

戻り値:

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

例外:

DateTimeException - 問い合わせできない場合(問合せによって定義される)

ArithmeticException - 数値のオーバーフローが発生した場合(問合せによって定義される)

adjustInto

default Temporal adjustInto(Temporal temporal)

指定された時間的オブジェクトをこのオブジェクトと同じ紀元になるように調整します。

これは、紀元をこれと同じになるように変更して、入力と同じ識別可能な型の時間的オブジェクトを返します。

調整は、ChronoField.ERAをフィールドとして渡してTemporal.with(TemporalField, long)を使用する場合と同等です。

ほとんどのケースで、Temporal.with(TemporalAdjuster)を使用して、呼び出しパターンを逆にすると明確になります。

   // these two lines are equivalent, but the second approach is recommended
   temporal = thisEra.adjustInto(temporal);
   temporal = temporal.with(thisEra);
 

このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

定義:

インタフェースTemporalAdjusterのadjustInto

パラメータ:

temporal - 調整するターゲット・オブジェクト、null以外

戻り値:

調整されるオブジェクト、null以外

例外:

DateTimeException - 調整を実行できない場合

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

getDisplayName

default String getDisplayName(TextStyle style, Locale locale)

この紀元のテキスト表現を取得します。

これは、紀元の識別に使用され、ユーザーへの表示に適したテキストの名前を返します。 パラメータは返されるテキストとロケールのスタイルを制御します。

テキスト・マッピングが見つからない場合、数値が返されます。

APIのノート:

このデフォルト実装はほとんどの実装に適しています。

パラメータ:

style - 必要なテキストのスタイル、null以外

locale - 使用するロケール。null以外

戻り値:

紀元のテキスト値、null以外