Calendar.Builder

java.lang.Object

|---java.util.Calendar.Builder

public static class Calendar.Builder
extends Object

Calendar.Builder 用于从各种日期时间参数创建日历。

有两种方法可以将日历设置为日期时间值。一种是将 Instant 参数设置为距 Epoch 的毫秒偏移量。另一种是将单个字段参数（例如 Calendar#YEAR）设置为所需的值。这两种方式不能混用。尝试同时设置即时字段和单个字段将导致抛出 IllegalStateException。但是，允许覆盖即时或字段参数的先前值。

如果没有为确定日期和/或时间提供足够的字段参数，则在构建日历时使用日历特定的默认值。例如，如果没有为公历指定 Calendar#YEAR 值，则将使用 1970。如果字段参数之间存在任何冲突，则应用解析规则。因此，字段设置的顺序很重要。

除了日期时间参数外，还可以设置语言环境、时区、星期定义和宽大模式参数。

例子

以下是示例用法。示例代码假定日历常量是静态导入的。

以下代码生成日期为 2012-12-31（公历）的日历，因为星期一是具有 ISO 8601 兼容周参数的一周的第一天。

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

以下代码生成日期为 1989-01-08（公历）的日本日历，假设默认 Calendar#ERA 是当天开始的平成。

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

构造函数摘要

构造函数	描述
Builder()	构造一个 Calendar.Builder。

方法总结

修饰符和类型	方法	描述
Calendar	build()	返回由 setter 方法设置的参数构建的 Calendar。
Calendar.Builder	set(int field, int value)	将字段参数设置为给定值。
Calendar.Builder	setCalendarType(String 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)	将 Instant 参数设置为由 Date 给出的瞬时值。
Calendar.Builder	setLenient(boolean lenient)	将 lenient 模式参数设置为 lenient 给出的值。
Calendar.Builder	setLocale(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)	将时区参数设置为给定的区域。
Calendar.Builder	setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)	将基于周的日期参数设置为具有给定日期说明符的值 - 周年、年周和周日。
Calendar.Builder	setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek)	将周定义参数设置为 firstDayOfWeek 和 minimumDaysInFirstWeek 给出的值，用于确定一年中的第一周。

从类 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	从 Epoch 的毫秒偏移量

返回:

这个 Calendar.Builder

Throws:

Throw名称	Throw描述
IllegalStateException	如果已经设置了任何字段参数

setInstant

public Calendar.Builder setInstant(Date instant)

将 Instant 参数设置为由 Date 给出的瞬时值。 此方法等效于调用 setInstant(instant.getTime())。

参数：

参数名称	参数描述
instant	表示从 Epoch 开始的毫秒偏移量的 Date

返回:

这个 Calendar.Builder

Throws:

Throw名称	Throw描述
NullPointerException	如果 instant 为空
IllegalStateException	如果已经设置了任何字段参数

set

public Calendar.Builder set(int field, int value)

将字段参数设置为给定值。 field 是 Calendar#fields 的索引，例如 Calendar#DAY_OF_MONTH。 此方法不执行字段值验证。 在构建日历时，任何超出范围的值要么在宽松模式下被标准化，要么在非宽松模式下被检测为无效值。

参数：

参数名称	参数描述
field	日历字段的索引
value	字段值

返回:

这个 Calendar.Builder

Throws:

Throw名称	Throw描述
IllegalArgumentException	如果字段无效
IllegalStateException	如果已经设置了即时值，或者如果字段设置太多（大约 Integer#MAX_VALUE）次。

setFields

public Calendar.Builder setFields(int... fieldValuePairs)

将字段参数设置为由 fieldValuePairs 给定的值，它们是字段及其值的对。 例如，

   setFeilds(Calendar.YEAR, 2013,
             Calendar.MONTH, Calendar.DECEMBER,
             Calendar.DAY_OF_MONTH, 23);

等价于以下集合调用的序列：

   set(Calendar.YEAR, 2013)
   .set(Calendar.MONTH, Calendar.DECEMBER)
   .set(Calendar.DAY_OF_MONTH, 23);

参数:

参数名称	参数描述
fieldValuePairs	字段值对

返回:

这个 Calendar.Builder

Throws:

Throw名称	Throw描述
NullPointerException	如果 fieldValuePairs 为空
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	Calendar#MONTH 值（月份编号从 0 开始）。
dayOfMonth	Calendar#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	Calendar#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	Calendar#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	星期几值：Calendar#DAY_OF_WEEK 字段的常量之一：Calendar#SUNDAY, ..., Calendar#SATURDAY。

返回:

这个 Calendar.Builder

setTimeZone

public Calendar.Builder setTimeZone(TimeZone zone)

将时区参数设置为给定的区域。 如果没有为此 Caledar.Builder 提供时区参数，则 TimeZone#getDefault() 将在构建方法中使用。

参数：

参数名称	参数描述
zone	时区

返回:

这个 Calendar.Builder

Throws:

Throw名称	Throw描述
NullPointerException	如果区域为空

setLenient

public Calendar.Builder setLenient(boolean lenient)

将 lenient 模式参数设置为 lenient 给出的值。 如果此 Calendar.Builder 没有给出 lenient 参数，则在 build 方法中将使用 lenient 模式。

参数：

参数名称	参数描述
lenient	宽松模式下为true； 非宽松模式为 false

返回:

这个 Calendar.Builder

setCalendarType

public Calendar.Builder setCalendarType(String type)

将日历类型参数设置为给定类型。 此方法给出的日历类型优先于语言环境给出的任何显式或隐式日历类型。

除了 Calendar#getAvailableCalendarTypes() 方法返回的可用日历类型之外，作为“gregory”的别名的“gregorian”和“iso8601”可以与此方法一起使用。

参数：

参数名称	参数描述
type	日历类型

返回:

这个 Calendar.Builder

Throws:

Throw名称	Throw描述
NullPointerException	如果类型为空
IllegalArgumentException	如果类型未知
IllegalStateException	如果已经设置了另一种日历类型

setLocale

public Calendar.Builder setLocale(Locale locale)

将语言环境参数设置为给定的语言环境。 如果没有为此 Calendar.Builder 指定区域设置，则将使用 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

如果调用 setCalendarType 方法没有明确给出日历类型，则使用 Locale 值来确定要构建的日历类型。

如果调用 setWeekDefinition 方法没有明确给出周定义参数，则使用区域设置的默认值。

参数：

参数名称	参数描述
locale	语言环境

返回:

这个 Calendar.Builder

Throws:

Throw名称	Throw描述
NullPointerException	如果语言环境为空

setWeekDefinition

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

将周定义参数设置为 firstDayOfWeek 和 minimumDaysInFirstWeek 给出的值，用于确定一年中的第一周。 此方法给出的参数优先于语言环境给出的默认值。

参数：

参数名称	参数描述
firstDayOfWeek	一周的第一天； Calendar#SUNDAY 到 Calendar#SATURDAY 之一
minimalDaysInFirstWeek	第一周的最少天数 (1..7)

返回:

这个 Calendar.Builder

Throws:

Throw名称	Throw描述
IllegalArgumentException	如果 firstDayOfWeek 或 minimumDaysInFirstWeek 无效

build

public Calendar build()

返回由 setter 方法设置的参数构建的 Calendar。 setCalendarType 方法或语言环境给出的日历类型用于确定要创建的日历。 如果没有给出明确的日历类型，则创建区域设置的默认日历。

如果日历类型为“iso8601”，则将 GregorianCalendar 的 GregorianCalendar#setGregorianChange(Date) 设置为 Date(Long.MIN_VALUE) 以作为预想的公历。 其周定义参数也设置为与 ISO 8601 标准兼容。 请注意，使用“iso8601”创建的 GregorianCalendar#getCalendarType() 方法返回“gregory”。

如果没有明确给出这些参数，则默认值用于区域设置和时区。

任何超出范围的字段值要么在宽松模式下被规范化，要么在非宽松模式下被检测为无效值。

返回:

使用此 Calendar.Builder 的参数构建的日历

Throws:

Throw名称	Throw描述
IllegalArgumentException	如果日历类型未知，或者在非宽松模式下提供了任何无效字段值，或者为不支持星期日期的日历类型提供了星期日期。