モジュール 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にタイム・ゾーン・パラメータが指定されていない場合、default {@code 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用のdefault {@code 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()