- java.lang.Object
-
- java.util.Calendar.Builder
-
- Enclosing class:
- Calendar
public static class Calendar.Builder extends Object
Calendar.Builder
用于从各种日期时间参数创建Calendar
。有两种方法可将
Calendar
设置为日期时间值。 一种是将instant参数设置为距离Epoch的毫秒偏移量。 另一种是将各个字段参数(例如YEAR
)设置为其所需的值。 这两种方式不能混为一谈。 尝试设置即时和单个字段将导致IllegalStateException
被抛出。 但是,允许覆盖即时或字段参数的先前值。如果没有给出足够的字段参数来确定日期和/或时间,则在构建
Calendar
时将使用日历特定的默认值。 例如,如果没有为公历提供YEAR
值,则将使用1970。 如果字段参数之间存在任何冲突,则应用resolution rules 。 因此,场设置的顺序很重要。除了日期时间参数,该locale , time zone , week definition和leniency mode参数进行设置。
例子
以下是示例用法。 示例代码假定静态导入
Calendar
常量。以下代码生成
Calendar
,日期为2012-12-31(格里高利),因为星期一是ISO 8601 compatible week parameters的一周的第一天。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();
- 从以下版本开始:
- 1.8
- 另请参见:
-
Calendar.getInstance(TimeZone, Locale)
,Calendar.fields
-
-
构造方法摘要
构造方法 构造器 描述 Builder()
构造一个Calendar.Builder
。
-
方法摘要
所有方法 实例方法 具体的方法 变量和类型 方法 描述 Calendar
build()
返回根据setter方法设置的参数构建的Calendar
。Calendar.Builder
set(int field, int value)
将字段
参数设置为给定的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参数设置为给定的instant
值,该值是从 the Epoch开始的毫秒偏移量。Calendar.Builder
setInstant(Date instant)
将即时参数设置为instant
给出的值为instant 。Calendar.Builder
setLenient(boolean lenient)
将lenient
模式参数设置为lenient
给出的值。Calendar.Builder
setLocale(Locale 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)
-
-
-
方法详细信息
-
setInstant
public Calendar.Builder setInstant(long instant)
将instant参数设置为给定的instant
值,该值是从 the Epoch开始的毫秒偏移量。- 参数
-
instant
- 与Epochinstant
毫秒的偏移量 - 结果
-
这
Calendar.Builder
- 异常
-
IllegalStateException
- 如果已设置任何字段参数 - 另请参见:
-
Calendar.setTime(Date)
,Calendar.setTimeInMillis(long)
,Calendar.time
-
setInstant
public Calendar.Builder setInstant(Date instant)
将即时参数设置为instant
给出的值为instant 。 此方法相当于对setInstant(instant.getTime())
的调用。- 参数
-
instant
-Date
表示距离Epoch的毫秒偏移量 - 结果
-
这
Calendar.Builder
- 异常
-
NullPointerException
- 如果instant
是null
-
IllegalStateException
- 如果已设置任何字段参数 - 另请参见:
-
Calendar.setTime(Date)
,Calendar.setTimeInMillis(long)
,Calendar.time
-
set
public Calendar.Builder set(int field, int value)
将字段
参数设置为给定的value
。字段
是一个索引到Calendar.fields
,如DAY_OF_MONTH
。 在此方法中不执行字段值验证。 在构建Calendar
时,任何超出范围的值都在宽松模式下标准化或在非宽松模式下检测为无效值。- 参数
-
字段
-Calendar
字段的索引 -
value
- 字段值 - 结果
-
这
Calendar.Builder
- 异常
-
IllegalArgumentException
- 如果字段
无效 -
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
,该defaultTimeZone
将在使用build
方法。- 参数
-
zone
-TimeZone
- 结果
-
这
Calendar.Builder
- 异常
-
NullPointerException
- 如果zone
是null
- 另请参见:
-
Calendar.setTimeZone(TimeZone)
-
setLenient
public Calendar.Builder setLenient(boolean lenient)
将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参数设置为给定的locale
。 如果没有给出此Calendar.Builder
区域设置,将使用defaultLocale
forLocale.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
参数设置为firstDayOfWeek
和minimalDaysInFirstWeek
给出的值,用于确定一年的first week 。 此方法给出的参数优先于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"
,该Gregorian change date一个的GregorianCalendar
设置为Date(Long.MIN_VALUE)
成为proleptic公历。 其周定义参数也设置为compatible with the ISO 8601 standard 。 请注意,使用GregorianCalendar
创建的"iso8601"
的getCalendarType
方法返回"gregory"
。如果未明确指定这些参数,则默认值用于区域设置和时区。
如果区域设置包含时区“tz” Unicode extension ,并且未明确指定时区,则使用区域设置中的时区。
任何超出范围的字段值都在宽松模式下标准化或在非宽松模式下检测为无效值。
- 结果
-
Calendar
,其参数为Calendar.Builder
- 异常
-
IllegalArgumentException
- 如果日历类型未知,或者在非宽松模式下给出任何无效字段值,或者为不支持周日期的日历类型指定了周日期。 - 另请参见:
-
Calendar.getInstance(TimeZone, Locale)
,Locale.getDefault(Locale.Category)
,TimeZone.getDefault()
-
-