Class Calendar.Builder

java.lang.Object
java.util.Calendar.Builder
Enclosing class:
Calendar
public static classCalendar.BuilderextendsObject
Calendar.Builder is used for creating aCalendar from various date-time parameters.

There are two ways to set aCalendar to a date-time value. One is to set the instant parameter to a millisecond offset from theEpoch. The other is to set individual field parameters, such asYEAR, to their desired values. These two ways can't be mixed. Trying to set both the instant and individual fields will cause anIllegalStateException to be thrown. However, it is permitted to override previous values of the instant or field parameters.

If no enough field parameters are given for determining date and/or time, calendar specific default values are used when building aCalendar. For example, if theYEAR value isn't given for the Gregorian calendar, 1970 will be used. If there are any conflicts among field parameters, the resolution rules are applied. Therefore, the order of field setting matters.

In addition to the date-time parameters, thelocale,time zone,week definition, andleniency mode parameters can be set.

Examples

The following are sample usages. Sample code assumes that theCalendar constants are statically imported.

The following code produces aCalendar with date 2012-12-31 (Gregorian) because Monday is the first day of a week with the ISO 8601 compatible week parameters.

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

The following code produces a JapaneseCalendar with date 1989-01-08 (Gregorian), assuming that the defaultERA isHeisei that started on that day.

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

Since:
1.8
See Also:

  • Constructor Details

    • Builder

      public Builder()
      Constructs aCalendar.Builder.

  • Method Details

    • setInstant

      public Calendar.Builder setInstant(long instant)
      Sets the instant parameter to the giveninstant value that is a millisecond offset fromthe Epoch.
      Parameters:
      instant - a millisecond offset from the Epoch
      Returns:
      thisCalendar.Builder
      Throws:
      IllegalStateException - if any of the field parameters have already been set
      See Also:

    • setInstant

      public Calendar.Builder setInstant(Date instant)
      Sets the instant parameter to theinstant value given by aDate. This method is equivalent to a call tosetInstant(instant.getTime()).
      Parameters:
      instant - aDate representing a millisecond offset from the Epoch
      Returns:
      thisCalendar.Builder
      Throws:
      NullPointerException - ifinstant isnull
      IllegalStateException - if any of the field parameters have already been set
      See Also:

    • set

      public Calendar.Builder set(int field, int value)
      Sets thefield parameter to the givenvalue.field is an index to theCalendar.fields, such asDAY_OF_MONTH. Field value validation is not performed in this method. Any out of range values are either normalized in lenient mode or detected as an invalid value in non-lenient mode when building aCalendar.
      Parameters:
      field - an index to theCalendar fields
      value - the field value
      Returns:
      thisCalendar.Builder
      Throws:
      IllegalArgumentException - iffield is invalid
      IllegalStateException - if the instant value has already been set, or if fields have been set too many (approximatelyInteger.MAX_VALUE) times.
      See Also:

    • setFields

      public Calendar.Builder setFields(int... fieldValuePairs)
      Sets field parameters to their values given byfieldValuePairs that are pairs of a field and its value. For example,
         setFields(Calendar.YEAR, 2013,             Calendar.MONTH, Calendar.DECEMBER,             Calendar.DAY_OF_MONTH, 23);
      is equivalent to the sequence of the followingset calls:
         set(Calendar.YEAR, 2013)   .set(Calendar.MONTH, Calendar.DECEMBER)   .set(Calendar.DAY_OF_MONTH, 23);
      Parameters:
      fieldValuePairs - field-value pairs
      Returns:
      thisCalendar.Builder
      Throws:
      NullPointerException - iffieldValuePairs isnull
      IllegalArgumentException - if any of fields are invalid, or iffieldValuePairs.length is an odd number.
      IllegalStateException - if the instant value has been set, or if fields have been set too many (approximatelyInteger.MAX_VALUE) times.

    • setDate

      public Calendar.Builder setDate(int year, int month, int dayOfMonth)
      Sets the date field parameters to the values given byyear,month, anddayOfMonth. This method is equivalent to a call to:
         setFields(Calendar.YEAR, year,             Calendar.MONTH, month,             Calendar.DAY_OF_MONTH, dayOfMonth);
      Parameters:
      year - theYEAR value
      month - theMONTH value (the month numbering is0-based).
      dayOfMonth - theDAY_OF_MONTH value
      Returns:
      thisCalendar.Builder

    • setTimeOfDay

      public Calendar.Builder setTimeOfDay(int hourOfDay, int minute, int second)
      Sets the time of day field parameters to the values given byhourOfDay,minute, andsecond. This method is equivalent to a call to:
         setTimeOfDay(hourOfDay, minute, second, 0);
      Parameters:
      hourOfDay - theHOUR_OF_DAY value (24-hour clock)
      minute - theMINUTE value
      second - theSECOND value
      Returns:
      thisCalendar.Builder

    • setTimeOfDay

      public Calendar.Builder setTimeOfDay(int hourOfDay, int minute, int second, int millis)
      Sets the time of day field parameters to the values given byhourOfDay,minute,second, andmillis. This method is equivalent to a call to:
         setFields(Calendar.HOUR_OF_DAY, hourOfDay,             Calendar.MINUTE, minute,             Calendar.SECOND, second,             Calendar.MILLISECOND, millis);
      Parameters:
      hourOfDay - theHOUR_OF_DAY value (24-hour clock)
      minute - theMINUTE value
      second - theSECOND value
      millis - theMILLISECOND value
      Returns:
      thisCalendar.Builder

    • setWeekDate

      public Calendar.Builder setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)
      Sets the week-based date parameters to the values with the given date specifiers - week year, week of year, and day of week.

      If the specified calendar doesn't support week dates, thebuild method will throw anIllegalArgumentException.

      Parameters:
      weekYear - the week year
      weekOfYear - the week number based onweekYear
      dayOfWeek - the day of week value: one of the constants for theDAY_OF_WEEK field:SUNDAY, ...,SATURDAY.
      Returns:
      thisCalendar.Builder
      See Also:

    • setTimeZone

      public Calendar.Builder setTimeZone(TimeZone zone)
      Sets the time zone parameter to the givenzone. If no time zone parameter is given to thisCalendar.Builder, thedefaultTimeZone will be used in thebuild method.
      Parameters:
      zone - theTimeZone
      Returns:
      thisCalendar.Builder
      Throws:
      NullPointerException - ifzone isnull
      See Also:

    • setLenient

      public Calendar.Builder setLenient(boolean lenient)
      Sets the lenient mode parameter to the value given bylenient. If no lenient parameter is given to thisCalendar.Builder, lenient mode will be used in thebuild method.
      Parameters:
      lenient -true for lenient mode;false for non-lenient mode
      Returns:
      thisCalendar.Builder
      See Also:

    • setCalendarType

      public Calendar.Builder setCalendarType(String type)
      Sets the calendar type parameter to the giventype. The calendar type given by this method has precedence over any explicit or implicit calendar type given by thelocale.

      In addition to the available calendar types returned by theCalendar.getAvailableCalendarTypes method,"gregorian" and"iso8601" as aliases of"gregory" can be used with this method.

      Parameters:
      type - the calendar type
      Returns:
      thisCalendar.Builder
      Throws:
      NullPointerException - iftype isnull
      IllegalArgumentException - iftype is unknown
      IllegalStateException - if another calendar type has already been set
      See Also:

    • setLocale

      public Calendar.Builder setLocale(Locale locale)
      Sets the locale parameter to the givenlocale. If no locale is given to thisCalendar.Builder, thedefaultLocale forLocale.Category.FORMAT will be used.

      If no calendar type is explicitly given by a call to thesetCalendarType method, theLocale value is used to determine what type ofCalendar to be built.

      If no week definition parameters are explicitly given by a call to thesetWeekDefinition method, theLocale's default values are used.

      Parameters:
      locale - theLocale
      Returns:
      thisCalendar.Builder
      Throws:
      NullPointerException - iflocale isnull
      See Also:

    • setWeekDefinition

      public Calendar.Builder setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek)
      Sets the week definition parameters to the values given byfirstDayOfWeek andminimalDaysInFirstWeek that are used to determine thefirst week of a year. The parameters given by this method have precedence over the default values given by thelocale.
      Parameters:
      firstDayOfWeek - the first day of a week; one ofCalendar.SUNDAY toCalendar.SATURDAY
      minimalDaysInFirstWeek - the minimal number of days in the first week (1..7)
      Returns:
      thisCalendar.Builder
      Throws:
      IllegalArgumentException - iffirstDayOfWeek orminimalDaysInFirstWeek is invalid
      See Also:

    • build

      public Calendar build()
      Returns aCalendar built from the parameters set by the setter methods. The calendar type given by thesetCalendarType method or thelocale is used to determine whatCalendar to be created. If no explicit calendar type is given, the locale's default calendar is created.

      If the calendar type is"iso8601", theGregorian change date of aGregorianCalendar is set toDate(Long.MIN_VALUE) to be theproleptic Gregorian calendar. Its week definition parameters are also set to becompatible with the ISO 8601 standard. Note that thegetCalendarType method of aGregorianCalendar created with"iso8601" returns"gregory".

      The default values are used for locale and time zone if these parameters haven't been given explicitly.

      If the locale contains the time zone with "tz"Unicode extension, and time zone hasn't been given explicitly, time zone in the locale is used.

      Any out of range field values are either normalized in lenient mode or detected as an invalid value in non-lenient mode.

      Returns:
      aCalendar built with parameters of this Calendar.Builder
      Throws:
      IllegalArgumentException - if the calendar type is unknown, or if any invalid field values are given in non-lenient mode, or if a week date is given for the calendar type that doesn't support week dates.
      See Also: