Module java.base

Package java.util

Class Calendar.Builder

java.lang.Object

java.util.Calendar.Builder

封装类:

Calendar

       public static class Calendar.Builder extends Object
      

Calendar.Builder 用于根据各种日期时间参数创建一个 Calendar。

有两种方法可以将 Calendar 设置为日期时间值。一种是将即时参数设置为从 纪元 的毫秒偏移量。另一种是将各个字段参数，如 YEAR，设置为它们所需的值。这两种方法不能混合使用。尝试同时设置即时和各个字段将导致抛出 IllegalStateException。但是，允许覆盖先前的即时或字段参数值。

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

除了日期时间参数外，还可以设置 区域设置、时区、周定义 和 宽松模式 参数。

示例

以下是示例用法。示例代码假定已静态导入了 Calendar 常量。

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

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

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

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

自 JDK 版本:

1.8

参见:

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

Constructor Summary

Constructors

Constructor	Description
Builder()	构造一个 Calendar.Builder。

Method Summary

Modifier and Type	Method	Description
Calendar	build()	返回通过setter方法设置的参数构建的 Calendar。
Calendar.Builder	set(int field, int value)	将 field 参数设置为给定的 value。
Calendar.Builder	setCalendarType(String type)	将日历类型参数设置为给定的 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 值。
Calendar.Builder	setInstant(Date instant)	将即时参数设置为由 Date 给出的 instant 值。
Calendar.Builder	setLenient(boolean lenient)	将宽松模式参数设置为给定的 lenient 值。
Calendar.Builder	setLocale(Locale 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)	将时区参数设置为给定的 zone。
Calendar.Builder	setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)	将基于周的日期参数设置为给定日期标识符的值 - 周年、周数和星期几。
Calendar.Builder	setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek)	将周定义参数设置为给定的用于确定一年中的 第一周 的 firstDayOfWeek 和 minimalDaysInFirstWeek 的值。

Methods declared in class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Builder

             public Builder()
            

构造一个 Calendar.Builder。

Method Details

setInstant

             public Calendar.Builder setInstant(long instant)
            

将即时参数设置为给定的从 纪元 的毫秒偏移量的 instant 值。

参数:

instant - 从纪元的毫秒偏移量

返回:

此 Calendar.Builder

抛出:

IllegalStateException - 如果已经设置了任何字段参数

参见:

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

setInstant

             public Calendar.Builder setInstant(Date instant)
            

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

参数:

instant - 表示从纪元的毫秒偏移量的 Date

返回:

此 Calendar.Builder

抛出:

NullPointerException - 如果 instant 为 null

IllegalStateException - 如果已经设置了任何字段参数

参见:

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

set

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

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

参数:

field - Calendar 字段的索引

value - 字段值

返回:

此 Calendar.Builder

抛出:

IllegalArgumentException - 如果 field 无效

IllegalStateException - 如果已经设置了即时值，或者如果字段已经设置了太多次（大约 Integer.MAX_VALUE 次）。

参见:

• Calendar.set(int, int)

setFields

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

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

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

等效于以下 set 调用序列：

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

参数:

fieldValuePairs - 字段-值对

返回:

此 Calendar.Builder

抛出:

NullPointerException - 如果 fieldValuePairs 为 null

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 - MONTH 值（月份编号是 基于0的）。

dayOfMonth - 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 - 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 - 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 - 星期几的值：在DAY_OF_WEEK字段的常量之一：SUNDAY，...，SATURDAY。

返回:

此Calendar.Builder

参见:

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

setTimeZone

             public Calendar.Builder setTimeZone(TimeZone zone)
            

将时区参数设置为给定的zone。如果没有为此Calendar.Builder提供时区参数，则在build方法中将使用默认的TimeZone。

参数:

zone - TimeZone

返回:

此Calendar.Builder

抛出:

NullPointerException - 如果zone为null

参见:

• Calendar.setTimeZone(TimeZone)

setLenient

             public Calendar.Builder setLenient(boolean lenient)
            

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

参数:

lenient - true表示宽松模式；false表示非宽松模式

返回:

此Calendar.Builder

参见:

• Calendar.setLenient(boolean)

setCalendarType

             public Calendar.Builder setCalendarType(String type)
            

将日历类型参数设置为给定的type。此方法给定的日历类型优先于由locale明确或隐式给定的任何日历类型。

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

参数:

type - 日历类型

返回:

此Calendar.Builder

抛出:

NullPointerException - 如果type为null

IllegalArgumentException - 如果type未知

IllegalStateException - 如果已经设置了另一个日历类型

参见:

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

setLocale

             public Calendar.Builder setLocale(Locale locale)
            

将区域设置参数设置为给定的locale。如果没有为此Calendar.Builder提供区域设置，则将使用默认的Locale用于Locale.Category.FORMAT。

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

如果没有通过调用setWeekDefinition方法显式给出周定义参数，则使用Locale的默认值。

参数:

locale - Locale

返回:

此Calendar.Builder

抛出:

NullPointerException - 如果locale为null

参见:

• Calendar.getInstance(Locale)

setWeekDefinition

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

将周定义参数设置为由firstDayOfWeek和minimalDaysInFirstWeek给定的值，用于确定一年中的第一周。此方法给定的参数优先于由locale给出的默认值。

参数:

firstDayOfWeek - 一周的第一天；Calendar.SUNDAY到Calendar.SATURDAY之一

minimalDaysInFirstWeek - 第一周中的最小天数（1..7）

返回:

此Calendar.Builder

抛出:

IllegalArgumentException - 如果firstDayOfWeek或minimalDaysInFirstWeek无效

参见:

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

build

             public Calendar build()
            

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

如果日历类型为"iso8601"，则将GregorianCalendar的Gregorian change date设置为Date(Long.MIN_VALUE)以成为proleptic Gregorian日历。其周定义参数也设置为与ISO 8601标准兼容。请注意，使用"iso8601"创建的GregorianCalendar的getCalendarType方法返回"gregory"。

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

如果区域设置包含带有"tz"的Unicode扩展的时区，并且时区没有明确给出，则使用区域设置中的时区。

任何超出范围的字段值在宽松模式下将被归一化，或在非宽松模式下被检测为无效值。

返回:

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

抛出:

IllegalArgumentException - 如果日历类型未知，或者在非宽松模式下给出任何无效字段值，或者为不支持周日期的日历类型给出周日期。

参见:

• Calendar.getInstance(TimeZone, Locale)
• Locale.getDefault(Locale.Category)
• TimeZone.getDefault()