モジュール java.base

パッケージ java.util

クラスCalendar.Builder

java.lang.Object

java.util.Calendar.Builder

含まれているクラス:

Calendar

public static class Calendar.Builder
extends Object

Calendar.Builderは、各種の日付/時間パラメータからCalendarを作成するために使用されます。

Calendarを日付/時間値に設定する方法は2つあります。 1つは、インスタント・パラメータをエポックからのミリ秒単位のオフセットに設定する方法です。 もう1つは、個々のフィールド・パラメータ(YEARなど)をそれぞれの目的の値に設定する方法です。 これらの2つの方法を組み合せて使用することはできません。 インスタントと個々のフィールドの両方を設定しようとすると、IllegalStateExceptionがスローされます。 ただし、インスタントまたはフィールド・パラメータの以前の値をオーバーライドすることはできます。

日付または時間(あるいはその両方)を決めるのに十分なフィールド・パラメータが指定されない場合は、Calendarの作成時にカレンダ固有のデフォルト値が使用されます。 たとえば、グレゴリオ暦に対してYEAR値が指定されない場合は、1970が使用されます。 フィールド・パラメータ間でなんらかの競合が発生した場合は、解決ルールが適用されます。 このため、フィールド設定の順番は重要です。

日付/時間パラメータの他に、ロケール、タイムゾーン、週定義、および非厳密モードのパラメータも設定できます。

例

使用例を次に示します。 サンプル・コードでは、Calendarの定数が静的にインポートされるものと想定します。

ISO 8601準拠の週パラメータを使用すると月曜日が週の最初の曜日になるため、次のコードは2012-12-31という(グレゴリオ暦の)日付でCalendarを生成します。

   Calendar cal = new Calendar.Builder().setCalendarType("iso8601")
                        .setWeekDate(2013, 1, MONDAY).build();

次のコードは、デフォルトのERAがHeisei(1989年1月8日から始まる)であると仮定して、(グレゴリオ暦の)1989-01-08という日付で日本のCalendarを生成します。

   Calendar cal = new Calendar.Builder().setCalendarType("japanese")
                        .setFields(YEAR, 1, DAY_OF_YEAR, 1).build();

導入されたバージョン:

1.8

関連項目:

Calendar.getInstance(TimeZone, Locale), Calendar.fields

コンストラクタのサマリー

コンストラクタ

コンストラクタ	説明
Builder()	Calendar.Builderを作成します。

メソッドのサマリー

修飾子と型	メソッド	説明
Calendar	build()	setterメソッドによって設定されたパラメータで構成されるCalendarを返します。
Calendar.Builder	set(int field, int value)	fieldパラメータを指定されたvalueに設定します。
Calendar.Builder	setCalendarType(String type)	カレンダ・タイプ・パラメータを指定されたtypeに設定します。
Calendar.Builder	setDate(int year, int month, int dayOfMonth)	日付フィールドのパラメータをyear、monthおよびdayOfMonthで指定された値に設定します。
Calendar.Builder	setFields(int... fieldValuePairs)	フィールドのパラメータを、フィールドとその値のペアであるfieldValuePairsで指定された値に設定します。
Calendar.Builder	setInstant(long instant)	インスタント・パラメータを指定されたinstant値(Epochからのミリ秒単位のオフセット)に設定します。
Calendar.Builder	setInstant(Date instant)	インスタント・パラメータをDateで指定されたinstant値に設定します。
Calendar.Builder	setLenient(boolean lenient)	非厳密モード・パラメータをlenientで指定された値に設定します。
Calendar.Builder	setLocale(Locale locale)	ロケール・パラメータを指定されたlocaleに設定します。
Calendar.Builder	setTimeOfDay(int hourOfDay, int minute, int second)	時刻フィールドのパラメータを、hourOfDay、minuteおよびsecondで指定された値に設定します。
Calendar.Builder	setTimeOfDay(int hourOfDay, int minute, int second, int millis)	時刻フィールドのパラメータを、hourOfDay、minute、secondおよびmillisで指定された値に設定します。
Calendar.Builder	setTimeZone(TimeZone zone)	タイムゾーン・パラメータを指定されたzoneに設定します。
Calendar.Builder	setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)	週ベースの日付パラメータを、指定された日付指示子(暦週の基準年、年の何週目かを表す値および曜日)を含む値に設定します。
Calendar.Builder	setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek)	週定義パラメータを、年の最初の週を決定する際に使用されるfirstDayOfWeekとminimalDaysInFirstWeekで指定された値に設定します。

クラス java.lang.Objectから継承されたメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

コンストラクタの詳細

Builder

public Builder()

Calendar.Builderを作成します。

メソッドの詳細

setInstant

public Calendar.Builder setInstant(long instant)

インスタント・パラメータを指定されたinstant値(Epochからのミリ秒単位のオフセット)に設定します。

パラメータ:

instant - エポックからのミリ秒単位のオフセット

戻り値:

このCalendar.Builder

例外:

IllegalStateException - フィールド・パラメータのいずれかがすでに設定されている場合

関連項目:

Calendar.setTime(Date), Calendar.setTimeInMillis(long), Calendar.time

setInstant

public Calendar.Builder setInstant(Date instant)

インスタント・パラメータをDateで指定されたinstant値に設定します。 このメソッドは、setInstant(instant.getTime())の呼出しと同等です。

パラメータ:

instant - エポックからのミリ秒単位のオフセットを表すDate

戻り値:

このCalendar.Builder

例外:

NullPointerException - instantがnullである場合

IllegalStateException - フィールド・パラメータのいずれかがすでに設定されている場合

関連項目:

Calendar.setTime(Date), Calendar.setTimeInMillis(long), Calendar.time

set

public Calendar.Builder set(int field,
                            int value)

fieldパラメータを指定されたvalueに設定します。fieldは、DAY_OF_MONTHなどのCalendar.fieldsへのインデックスです。 このメソッドでは、フィールド値の検証は行われません。 範囲外の値は、Calendarの作成時に、非厳密モードで正規化されるか、厳密モードで無効な値として検出されます。

パラメータ:

field - Calendarフィールドのインデックス

value - フィールドの値

戻り値:

このCalendar.Builder

例外:

IllegalArgumentException - fieldが無効の場合

IllegalStateException - インスタント値がすでに設定されている場合、またはフィールドの設定回数が多すぎる(およそInteger.MAX_VALUE回)場合。

関連項目:

Calendar.set(int, int)

setFields

public Calendar.Builder setFields(int... fieldValuePairs)

フィールドのパラメータを、フィールドとその値のペアであるfieldValuePairsで指定された値に設定します。 次に例を示します。

   setFields(Calendar.YEAR, 2013,
             Calendar.MONTH, Calendar.DECEMBER,
             Calendar.DAY_OF_MONTH, 23);

これは、次の一連のset呼出しに相当します。

   set(Calendar.YEAR, 2013)
   .set(Calendar.MONTH, Calendar.DECEMBER)
   .set(Calendar.DAY_OF_MONTH, 23);

パラメータ:

fieldValuePairs - フィールドと値のペア

戻り値:

このCalendar.Builder

例外:

NullPointerException - fieldValuePairsがnullである場合

IllegalArgumentException - いずれかのフィールドが無効な場合、またはfieldValuePairs.lengthが奇数の場合。

IllegalStateException - インスタント値がすでに設定されている場合、またはフィールドの設定回数が多すぎる(およそInteger.MAX_VALUE回)場合。

setDate

public Calendar.Builder setDate(int year,
                                int month,
                                int dayOfMonth)

日付フィールドのパラメータをyear、monthおよびdayOfMonthで指定された値に設定します。 このメソッドは、次の呼出しと同等です。

   setFields(Calendar.YEAR, year,
             Calendar.MONTH, month,
             Calendar.DAY_OF_MONTH, dayOfMonth);

パラメータ:

year - YEARの値

month - MONTHの値(月の番号付けは0ベース)。

dayOfMonth - DAY_OF_MONTHの値

戻り値:

このCalendar.Builder

setTimeOfDay

public Calendar.Builder setTimeOfDay(int hourOfDay,
                                     int minute,
                                     int second)

時刻フィールドのパラメータを、hourOfDay、minuteおよびsecondで指定された値に設定します。 このメソッドは、次の呼出しと同等です。

   setTimeOfDay(hourOfDay, minute, second, 0);

パラメータ:

hourOfDay - HOUR_OF_DAYの値(24時間クロック)

minute - MINUTEの値

second - SECONDの値

戻り値:

このCalendar.Builder

setTimeOfDay

public Calendar.Builder setTimeOfDay(int hourOfDay,
                                     int minute,
                                     int second,
                                     int millis)

時刻フィールドのパラメータを、hourOfDay、minute、secondおよびmillisで指定された値に設定します。 このメソッドは、次の呼出しと同等です。

   setFields(Calendar.HOUR_OF_DAY, hourOfDay,
             Calendar.MINUTE, minute,
             Calendar.SECOND, second,
             Calendar.MILLISECOND, millis);

パラメータ:

hourOfDay - HOUR_OF_DAYの値(24時間クロック)

minute - MINUTEの値

second - SECONDの値

millis - MILLISECONDの値

戻り値:

このCalendar.Builder

setWeekDate

public Calendar.Builder setWeekDate(int weekYear,
                                    int weekOfYear,
                                    int dayOfWeek)

週ベースの日付パラメータを、指定された日付指示子(暦週の基準年、年の何週目かを表す値および曜日)を含む値に設定します。

指定されたカレンダが暦週日付をサポートしていない場合、buildメソッドはIllegalArgumentExceptionをスローします。

パラメータ:

weekYear - 暦週の基準年

weekOfYear - weekYearに基づく週番号

dayOfWeek - 曜日の値。DAY_OF_WEEKフィールドの定数(SUNDAY、...、SATURDAY)の1つ。

戻り値:

このCalendar.Builder

関連項目:

Calendar.setWeekDate(int, int, int), Calendar.isWeekDateSupported()

setTimeZone

public Calendar.Builder setTimeZone(TimeZone zone)

タイムゾーン・パラメータを指定されたzoneに設定します。 このCalendar.Builderにタイムゾーン・パラメータが指定されていない場合、「デフォルトTimeZone」はbuildメソッドで使用されます。

パラメータ:

zone - TimeZone

戻り値:

このCalendar.Builder

例外:

NullPointerException - zoneがnullである場合

関連項目:

Calendar.setTimeZone(TimeZone)

setLenient

public Calendar.Builder setLenient(boolean lenient)

非厳密モード・パラメータをlenientで指定された値に設定します。 このCalendar.Builderに非厳密パラメータが指定されていない場合は、非厳密モードがbuildメソッドで使用されます。

パラメータ:

lenient - 非厳密モードの場合はtrue。厳密モードの場合はfalse

戻り値:

このCalendar.Builder

関連項目:

Calendar.setLenient(boolean)

setCalendarType

public Calendar.Builder setCalendarType(String type)

カレンダ・タイプ・パラメータを指定されたtypeに設定します。 このメソッドで指定されるカレンダ・タイプは、localeで指定される明示的または暗黙的などのカレンダ・タイプよりも優先されます。

Calendar.getAvailableCalendarTypesメソッドによって返される使用可能なカレンダ・タイプの他に、「gregory」の別名として"gregorian"および"iso8601"もこのメソッドで使用できます。

パラメータ:

type - カレンダ・タイプ

戻り値:

このCalendar.Builder

例外:

NullPointerException - typeがnullである場合

IllegalArgumentException - typeが不明の場合

IllegalStateException - 別のカレンダ・タイプがすでに設定されている場合

関連項目:

Calendar.getCalendarType(), Calendar.getAvailableCalendarTypes()

setLocale

public Calendar.Builder setLocale(Locale locale)

ロケール・パラメータを指定されたlocaleに設定します。 このCalendar.Builderにロケールが指定されていない場合は、Locale.Category.FORMATのデフォルトのLocaleが使用されます。

setCalendarTypeメソッドの呼出しによってカレンダ・タイプが明示的に指定されない場合は、Localeの値を使って、作成されるCalendarのタイプが決められます。

setWeekDefinitionメソッドの呼出しによって週定義パラメータが明示的に指定されない場合は、Localeのデフォルト値が使用されます。

パラメータ:

locale - Locale

戻り値:

このCalendar.Builder

例外:

NullPointerException - localeがnullである場合

関連項目:

Calendar.getInstance(Locale)

setWeekDefinition

public Calendar.Builder setWeekDefinition(int firstDayOfWeek,
                                          int minimalDaysInFirstWeek)

週定義パラメータを、年の最初の週を決定する際に使用されるfirstDayOfWeekとminimalDaysInFirstWeekで指定された値に設定します。 このメソッドで指定されるパラメータは、localeで指定されるデフォルト値よりも優先されます。

パラメータ:

firstDayOfWeek - 週の最初の曜日。Calendar.SUNDAYからCalendar.SATURDAYのいずれか

minimalDaysInFirstWeek - 最初の週の最小日数(1..7)

戻り値:

このCalendar.Builder

例外:

IllegalArgumentException - firstDayOfWeekまたはminimalDaysInFirstWeekが無効な場合

関連項目:

Calendar.getFirstDayOfWeek(), Calendar.getMinimalDaysInFirstWeek()

build

public Calendar build()

setterメソッドによって設定されたパラメータで構成されるCalendarを返します。 setCalendarTypeメソッドまたはlocaleによって指定されたカレンダ・タイプを使って、作成されるCalendarが決められます。 明示的なカレンダ・タイプが指定されない場合は、そのロケールのデフォルト・カレンダが作成されます。

カレンダ・タイプが「iso8601」である場合は、先発グレゴリオ暦になるように、GregorianCalendarのグレゴリオ暦切換え日がDate(Long.MIN_VALUE)に設定されます。 その週定義パラメータも、ISO 8601標準に準拠するように設定されます。 "iso8601"で作成されたGregorianCalendarのgetCalendarTypeメソッドが"gregory"を返すことに注意してください。

ロケールおよびタイムゾーンのパラメータが明示的に指定されなかった場合は、デフォルト値が使用されます。

範囲外のフィールド値があれば、非厳密モードで正規化されるか、厳密モードで無効な値として検出されます。

戻り値:

この Calendar.Builderのパラメータを使って作成されたCalendar

例外:

IllegalArgumentException - カレンダ・タイプが不明の場合、無効なフィールド値が厳密モードで指定されている場合、または暦週日付をサポートしていないカレンダ・タイプに対して暦週日付が指定されている場合。

関連項目:

Calendar.getInstance(TimeZone, Locale), Locale.getDefault(Locale.Category), TimeZone.getDefault()