{@code Calendar.Builder} is used for creating a {@code Calendar} fromvarious date-time parameters.
There are two ways to set a {@code Calendar} to a date-time value. Oneis to set the instant parameter to a millisecond offset from the Epoch. The other is to set individual field parameters, such as {@link Calendar#YEAR YEAR}, to their desired values. These two ways can't be mixed. Trying to set both the instant and individual fields will cause an {@link IllegalStateException} to bethrown. 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 {@code Calendar}. For example, if the {@link Calendar#YEAR YEAR} valueisn'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 {@linkplain #setLocale(Locale) locale}, {@linkplain #setTimeZone(TimeZone) time zone}, {@linkplain #setWeekDefinition(int,int) week definition}, and {@linkplain #setLenient(boolean) leniency mode} parameters can be set.
Examples
The following are sample usages. Sample code assumes that the {@code Calendar} constants are statically imported.
The following code produces a {@code 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 {@code Calendar} with date1989-01-08 (Gregorian), assuming that the default {@link Calendar#ERA 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 Calendar#getInstance(TimeZone,Locale)
@see Calendar#fields