Module java.base
Package java.util

Class Calendar.Builder

  • Enclosing class:
    Calendar
    public static class Calendar.Builder
extends Object
    Calendar.Builder is used for creating a Calendar from various date-time parameters.

    There are two ways to set a Calendar to a date-time value. One is to set the instant parameter to a millisecond offset from the Epoch. The other is to set individual field parameters, such as YEAR, to their desired values. These two ways can't be mixed. Trying to set both the instant and individual fields will cause an IllegalStateException 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 a Calendar. For example, if the YEAR 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, the locale, time zone, week definition, and leniency mode parameters can be set.

    Examples

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

    The following code produces a Calendar 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 Japanese Calendar with date 1989-01-08 (Gregorian), assuming that the default ERA is Heisei 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:
    Calendar.getInstance(TimeZone, Locale), Calendar.fields

    • Constructor Detail

      • Builder

        public Builder()
        Constructs a Calendar.Builder.

    • Method Detail

      • set

        public Calendar.Builder set​(int field,
                            int value)
        Sets the field parameter to the given value. field is an index to the Calendar.fields, such as DAY_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 a Calendar.
        Parameters:
        field - an index to the Calendar fields
        value - the field value
        Returns:
        this Calendar.Builder
        Throws:
        IllegalArgumentException - if field is invalid
        IllegalStateException - if the instant value has already been set, or if fields have been set too many (approximately Integer.MAX_VALUE) times.
        See Also:
        Calendar.set(int, int)

      • setFields

        public Calendar.Builder setFields​(int... fieldValuePairs)
        Sets field parameters to their values given by fieldValuePairs 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 following set calls: 
           set(Calendar.YEAR, 2013)
   .set(Calendar.MONTH, Calendar.DECEMBER)
   .set(Calendar.DAY_OF_MONTH, 23);
        Parameters:
        fieldValuePairs - field-value pairs
        Returns:
        this Calendar.Builder
        Throws:
        NullPointerException - if fieldValuePairs is null
        IllegalArgumentException - if any of fields are invalid, or if fieldValuePairs.length is an odd number.
        IllegalStateException - if the instant value has been set, or if fields have been set too many (approximately Integer.MAX_VALUE) times.

      • setDate

        public Calendar.Builder setDate​(int year,
                                int month,
                                int dayOfMonth)
        Sets the date field parameters to the values given by year, month, and dayOfMonth. This method is equivalent to a call to: 
           setFields(Calendar.YEAR, year,
             Calendar.MONTH, month,
             Calendar.DAY_OF_MONTH, dayOfMonth);
        Parameters:
        year - the YEAR value
        month - the MONTH value (the month numbering is 0-based).
        dayOfMonth - the DAY_OF_MONTH value
        Returns:
        this Calendar.Builder

      • setTimeOfDay

        public Calendar.Builder setTimeOfDay​(int hourOfDay,
                                     int minute,
                                     int second)
        Sets the time of day field parameters to the values given by hourOfDay, minute, and second. This method is equivalent to a call to: 
           setTimeOfDay(hourOfDay, minute, second, 0);
        Parameters:
        hourOfDay - the HOUR_OF_DAY value (24-hour clock)
        minute - the MINUTE value
        second - the SECOND value
        Returns:
        this Calendar.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 by hourOfDay, minute, second, and millis. 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 - the HOUR_OF_DAY value (24-hour clock)
        minute - the MINUTE value
        second - the SECOND value
        millis - the MILLISECOND value
        Returns:
        this Calendar.Builder

      • setLenient

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

      • build

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

        If the calendar type is "iso8601", the Gregorian change date of a GregorianCalendar is set to Date(Long.MIN_VALUE) to be the proleptic Gregorian calendar. Its week definition parameters are also set to be compatible with the ISO 8601 standard. Note that the getCalendarType method of a GregorianCalendar 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:
        a Calendar 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:
        Calendar.getInstance(TimeZone, Locale), Locale.getDefault(Locale.Category), TimeZone.getDefault()