モジュール java.base
パッケージ 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で指定された値に設定します。

    • コンストラクタの詳細

      • Builder

        public Builder()
        Calendar.Builderを作成します。

    • メソッドの詳細

      • 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()

      • setLenient

        public Calendar.Builder setLenient​(boolean lenient)
        非厳密モード・パラメータをlenientで指定された値に設定します。 このCalendar.Builderに非厳密パラメータが指定されていない場合は、非厳密モードがbuildメソッドで使用されます。
        パラメータ:
        lenient - 非厳密モードの場合はtrue。厳密モードの場合はfalse
        戻り値:
        このCalendar.Builder
        関連項目:
        Calendar.setLenient(boolean)

      • 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"を返すことに注意してください。

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

        ロケールに"tz" 「Unicode拡張」のタイムゾーンが含まれていて、タイムゾーンが明示的に指定されていない場合は、ロケールのタイムゾーンが使用されます。

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

        戻り値:
        この Calendar.Builderのパラメータを使って作成されたCalendar
        例外:
        IllegalArgumentException - カレンダ・タイプが不明の場合、無効なフィールド値が厳密モードで指定されている場合、または暦週日付をサポートしていないカレンダ・タイプに対して暦週日付が指定されている場合。
        関連項目:
        Calendar.getInstance(TimeZone, Locale), Locale.getDefault(Locale.Category), TimeZone.getDefault()