Calendar.Builder

AI-generated Key Takeaways

• Calendar.Builder provides a flexible way to construct Calendar instances by setting various date and time parameters like instant, individual fields, time zone, and locale.

• The builder offers methods to set date and time components using different approaches like instant, individual fields, or specific combinations for date, time, and week date.

• Calendar.Builder allows customization of week definitions, time zones, and leniency mode, giving control over calendar behavior and data validation.

• Using set() methods, specific fields can be individually configured, while methods like setDate() or setTimeOfDay() offer convenient shortcuts for common date-time settings.

• The build() method finalizes the configuration and returns a Calendar instance based on the accumulated settings.

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 {@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 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();

See Also

• Calendar.getInstance(TimeZone, Locale)
• Calendar.fields

Public Constructor Summary

Builder() Constructs a Calendar.Builder.

Public Method Summary

Calendar	build() Returns a Calendar built from the parameters set by the setter methods.
Calendar.Builder	set(int field, int value) Sets the field parameter to the given value.
Calendar.Builder	setCalendarType(String type) Sets the calendar type parameter to the given type.
Calendar.Builder	setDate(int year, int month, int dayOfMonth) Sets the date field parameters to the values given by year, month, and dayOfMonth.
Calendar.Builder	setFields(int... fieldValuePairs) Sets field parameters to their values given by fieldValuePairs that are pairs of a field and its value.
Calendar.Builder	setInstant(Date instant) Sets the instant parameter to the instant value given by a Date.
Calendar.Builder	setInstant(long instant) Sets the instant parameter to the given instant value that is a millisecond offset from the Epoch.
Calendar.Builder	setLenient(boolean lenient) Sets the lenient mode parameter to the value given by lenient.
Calendar.Builder	setLocale(Locale locale) Sets the locale parameter to the given locale.
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.
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.
Calendar.Builder	setTimeZone(TimeZone zone) Sets the time zone parameter to the given zone.
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.
Calendar.Builder	setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek) Sets the week definition parameters to the values given by firstDayOfWeek and minimalDaysInFirstWeek that are used to determine the first week of a year.

Inherited Method Summary

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

Public Constructors

public Builder ()

Constructs a Calendar.Builder.

Public Methods

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 {@linkplain #setLocale(Locale) 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 {@linkplain GregorianCalendar#setGregorianChange(Date) 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.

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

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)

public Calendar.Builder setCalendarType (String type)

Sets the calendar type parameter to the given type. The calendar type given by this method has precedence over any explicit or implicit calendar type given by the {@linkplain #setLocale(Locale) locale}.

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

Parameters

type	the calendar type

Returns

• this Calendar.Builder

Throws

NullPointerException	if type is null
IllegalArgumentException	if type is unknown
IllegalStateException	if another calendar type has already been set

See Also

• Calendar.getCalendarType()
• Calendar.getAvailableCalendarTypes()

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

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.

public Calendar.Builder setInstant (Date instant)

Sets the instant parameter to the instant value given by a Date. This method is equivalent to a call to setInstant(instant.getTime()).

Parameters

instant	a Date representing a millisecond offset from the Epoch

Returns

• this Calendar.Builder

Throws

NullPointerException	if instant is null
IllegalStateException	if any of the field parameters have already been set

See Also

• Calendar.setTime(Date)
• Calendar.setTimeInMillis(long)
• Calendar.time

public Calendar.Builder setInstant (long instant)

Sets the instant parameter to the given instant value that is a millisecond offset from the Epoch.

Parameters

instant	a millisecond offset from the Epoch

Returns

• this Calendar.Builder

Throws

IllegalStateException	if any of the field parameters have already been set

See Also

• Calendar.setTime(Date)
• Calendar.setTimeInMillis(long)
• Calendar.time

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)

public Calendar.Builder setLocale (Locale locale)

Sets the locale parameter to the given locale. If no locale is given to this Calendar.Builder, the {@linkplain Locale#getDefault(Locale.Category) default Locale} for Locale.Category.FORMAT will be used.

If no calendar type is explicitly given by a call to the setCalendarType method, the Locale value is used to determine what type of Calendar to be built.

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

Parameters

locale	the Locale

Returns

• this Calendar.Builder

Throws

NullPointerException	if locale is null

See Also

• Calendar.getInstance(Locale)

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

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

public Calendar.Builder setTimeZone (TimeZone zone)

Sets the time zone parameter to the given zone. If no time zone parameter is given to this Caledar.Builder, the {@linkplain TimeZone#getDefault() default TimeZone} will be used in the build method.

Parameters

zone	the TimeZone

Returns

• this Calendar.Builder

Throws

NullPointerException	if zone is null

See Also

• Calendar.setTimeZone(TimeZone)

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, the build method will throw an IllegalArgumentException.

Parameters

weekYear	the week year
weekOfYear	the week number based on weekYear
dayOfWeek	the day of week value: one of the constants for the DAY_OF_WEEK field: SUNDAY, ..., SATURDAY.

Returns

• this Calendar.Builder

See Also

• Calendar.setWeekDate(int, int, int)
• Calendar.isWeekDateSupported()

public Calendar.Builder setWeekDefinition (int firstDayOfWeek, int minimalDaysInFirstWeek)

Sets the week definition parameters to the values given by firstDayOfWeek and minimalDaysInFirstWeek that are used to determine the first week of a year. The parameters given by this method have precedence over the default values given by the {@linkplain #setLocale(Locale) locale}.

Parameters

firstDayOfWeek	the first day of a week; one of Calendar.SUNDAY to Calendar.SATURDAY
minimalDaysInFirstWeek	the minimal number of days in the first week (1..7)

Returns

• this Calendar.Builder

Throws

IllegalArgumentException	if firstDayOfWeek or minimalDaysInFirstWeek is invalid

See Also

• Calendar.getFirstDayOfWeek()
• Calendar.getMinimalDaysInFirstWeek()