在 Java 8 之前,日期与时间的 API (java.util.Date)一直存在着几个问题。以往的 Date 对象同时包含了日期以及时间(如时、分、秒)的信息,因此如果只是要使用到日期的信息,通常还需要将 Date 对象的时间设置在 00:00:00 或者是其他固定的时刻,避免在运算时会有一些差异。同样地,如果只是要使用到时间的信息,也需要将 Date 对象的日期设置在固定的日子,这些都让 Date 对象在使用上变得不太方便。此外,Date 对象所使用的年、月数值也十分不直觉,前者是以 1900 年为基准来增加或是减少的年数,后者则是以 0~11 来表示 1~12 月。
内核概念
Java 8 之后,添加了一组日期和时间相关的 API,都包含在 java.time 这个 Package 内。相较于之前的 java.util.Date,java.time 所提供的类别与对象,拥有以下几点特性:
- 对象的值不会被改变:
java.time套件底下的对象都是 Immutable Object,设计师只能够通过一些类别或是对象方法来产生新的不同数值的对象。也因此这些对象都可以同时在不同的线程下被使用(thread-safe)。 - 领域驱动设计(Domain-driven design):
java.time套件将日期与时间依据不同的使用案例,区分成不同的类别,不像以前的java.util.Date是同时结合了时间与日期和时区的大杂烩。 - 支持多种历法:
java.time套件除了能支持国际通用的 ISO 8601 日期与时间的表示方式外,还支持一些 non-ISO 的历法(如日本常会使用纪年年号),都放置在java.time.chrono套件内。
常用的 LocalDate、LocalTime 与 LocalDateTime
LocalDate 和 LocalTime 都位于 java.time 套件下,这两个应该是学习 java.time 套件最先用到的类别。它们代表着纯粹地(本地端的)日期与时间,没有时区的影响。另外如果要同时使用到日期与时间的话,可以使用 LocalDateTime 这个类别,它直接把 LocalDate 和 LocalTime 集成在一起了。
如果有用到时区,可以使用 java.time 套件下的 ZonedDateTime 类别,这在稍后会有比较详细的介绍。
Instant、Duration 与 Period
java.time 套件下的 Instant、Duration 和 Period 类别分别定义了一个瞬间的时间点、一个时间区段和一个时间周期。虽然都是时间,但概念有点不太相同。
Instant
Instant 类别用来定义一个瞬间的时间点,譬如说:「现在 UTC 的时间是公元 2015 年 4 月 3 日凌晨 0 点整。」这就是一个瞬间时间点的描述。Instant 只能够表示 UTC 的时间,并没有时区概念。如果要用 Instant 类别产生出符合上述句子的对象,可以写成程序如下:
final Instant instant = Instant.parse("2015-04-03T00:00:00Z");
也可以使用 Instant 类别的 ofEpochMilli 或是 ofEpochSecond 方法来代入 UTC 的「公元 2015 年 4 月 3 日凌晨 0 点整」与「公元 1970 年 1 月 1 日凌晨 0 点整」(Epoch Time)所差距的秒数,单位分别为毫秒与秒。这个差距的数值通常为 64 比特的长整数(long)型态,就是我们常说与常用的「时间戳记(Timestamp)」啦!
UTC 的「公元 2015 年 4 月 3 日凌晨 0 点整」与「公元 1970 年 1 月 1 日凌晨 0 点整」共相差了 1428019200000 毫秒,因此也可以写成以下程序来产生 Instant 对象:
final Instant instant = Instant.ofEpochMilli(1428019200000L);
如果要取得目前的时间点(或时间戳记),可以使用 Instant 类别的 now 方法,用法将在介绍创建 LocalDate 与 LocalTime 时提到。
Duration
Duration 类别用来定义一个时间区段,譬如说:「从甲地到乙地,开车开了 20 分钟。」这就是一个时间区段的描述。如果要用 Duration 类别产生出符合上述句子的对象,可以写成程序如下:
final Duration duration = Duration.parse("PT20M");
或是使用 Duration 类别提供的 of、ofXXXX 方法,如下:
final Duration duration = Duration.ofMinutes(20);
Duration 对象也可以和 Instant 对象一同使用,进行时间的加减运算,比如说要计算在 UTC 的「公元 2015 年 4 月 3 日凌晨 0 点整」时,「从甲地到乙地,开车开了 20 分钟」,那么到达乙地的时间点为何?
final Instant instant = Instant.parse("2015-04-03T00:00:00Z");
final Duration duration = Duration.parse("PT20M");
final Instant newInstant = instant.plus(duration); //会再产生出新的「2015-04-03T00:20:00Z」之Instant对象
也可以使用 Duration 的 between 来计算两个 Instant 对象的时间差,如下:
final Instant instant1 = Instant.parse("2015-04-03T00:00:00Z");
final Instant instant2 = Instant.parse("2015-04-03T00:20:00Z");
final Duration duration12 = Duration.between(instant1, instant2); //注意参数的顺序!
Period
Period 类别用来定义一个时间周期,有点类似 Duration,比较不同的是,Duration 最小的单位可到奈秒(Nanosecond),而 Period 最小的单位则是天(day)。两者的用法其实差不多,只是在使用到年、月等需要历法支持的单位时,应该使用 Period 类别,因为一年或是一个月的时间区段不是固定的!以 ISO 8601 的日期表示法来说,一年可能有 365 天或是 366 天、一个月则可能有 28~31 天,此时如果使用 Duration 类别会有很多问题。
ZoneId
ZoneId 类别与时区有关,ZoneId 对象可用来定义 Instant 和 LocalDateTime 对象如何互相转换。产生 ZoneId 对象可以使用 ZoneId 类别所提供的 systemDefault、of、ofXXXX 方法,举例如下:
final ZoneId zoneidDefault = ZoneId.systemDefault(); //系统预设时区
final ZoneId zoneidPlus8 = ZoneId.of("UTC+8"); //UTC时间+8
ZoneId 对象可以配合 LocalDateTime 类别所提供的 ofInstant 方法来将 Instant 对象转成 LocalDateTime 对象,作法如下:
final LocalDateTime nowLocalDateTime = LocalDateTime.ofInstant(nowInstant, zoneidPlus8);
为什么需要将 Instant 转成 LocalDateTime?那是因为 Instant 对象只有单纯时间的概念,虽然可以知道该点时间与「公元 1970 年 1 月 1 日凌晨 0 点整」(Epoch Time)所差距的秒数,但因 Instant 本身缺乏日期/历法的功能,因此无法直接用它来取得我们常会需要的年、月、日等独立消息(使用 Instant 对象的 toString 方法会自动使用 DateTimeFormatter 将其转为 ISO 8601 的日期与时间格式之字符串)。但是透过 LocalDateTime 类别,可以将其轻易转成我们熟知的历法格式,并能轻易地取出各时间单位的值。只不过在这里,由于 LocalDateTime 本身并不含有时区信息,因此若要将 LocalDateTime 转回 Instant 对象,也还是需要提供一个时区给它。
透过 LocalDateTime 对象的 toInstant 方法,可以将现有的 LocalDateTime 对象转为 Instant 对象,参数部份要代入 ZoneOffset 对象,而不是 ZoneId 对象。ZoneOffset 对象继承 ZoneId,但它只专注在时间的位移上,而没有地区与标准时间的概念。如果在使用 ZoneId 的 of 方法时,只传入时间的位移,那么产生出来的对象将会是 ZoneOffset 对象。当然,ZoneOffset 类别本身也是有提供 of 或是 ofXXXX 方法来创建 ZoneOffset 对象。创建 ZoneOffset 对象的方式如下:
final ZoneOffset zoneid8hr1 = (ZoneOffset)ZoneId.of("+8");
final ZoneOffset zoneid8hr2 = ZoneOffset.of("+8");
final ZoneOffset zoneid8hr3 = ZoneOffset.ofHours(8);
将 LocalDateTime 对象转为 Instant 对象的方式如下:
final Instant nowLocalDateTimeToInstant = nowLocalDateTime.toInstant(zoneid8hr1);
Clock
java.time.Clock 对象可用来找出目前指定时区的时间点,使用 Clock 类别提供的 systemUTC、systemDefaultZone 或是 system 方法来取得不同时区的 Clock 对象实体。Clock 的实际应用将在创建 LocalDate 与 LocalTime 对象时一同介绍。Clock 和 ZoneId 可能很容易被混淆在一起,简单来说,Clock 所表示的是一个已调整好时区的「时钟」,因此可以借由直接查看这个「时钟」来得知现在的时间(时钟是一直在跑的,只有观察它时才会得到该观察时间点的结果);而 ZoneId 只表示一个时区,或者说是一个时间位移,并不能用来查看时间,但 ZoneId 对象可以用来调整 Clock 对象的时区,或是其它已知时间的时区。
创建 LocalDate、LocalTime 与 LocalDateTime 对象
由于 LocalDate、LocalTime 和 LocalDateTime 对象的构造器都被声明为 private,因此无法直接使用 new 来实体化出它们。如果要创建出它们的对象,必须透过它们的类别方法来达成,常用的几种方法以下分别一一介绍。
now
now 是类别方法,可以使用现在系统的时间来创建出 LocalDate、LocalTime 和 LocalDateTime 对象。参数可以代入 Clock 对象来指定时区,但若不传入任何参数,则会预设代入 Clock.systemDefaultZone(),使用操作系统预设的时区。
举个例子,取得目前系统的日期与时间,并显示出来:
final LocalDateTime currentPoint = LocalDateTime.now(); //直接使用LocalDateTime类别来取得日期与时间
System.out.println(currentPoint);
印出结果为:
如果要指定时区,可以在调用 now 方法时自行传入 Clock 对象。作法如下:
final LocalDateTime currentPointUTC = LocalDateTime.now(Clock.systemUTC());
final LocalDateTime currentPointDefault = LocalDateTime.now(Clock.systemDefaultZone()); //同LocalDateTime.now();
final LocalDateTime currentPointPlus8 = LocalDateTime.now(Clock.system(ZoneId.of("+8")));
of
of 是类别方法,可以直接传入年、月、日、小时、分钟、秒等时间数值来产生 LocalDate、LocalTime 和 LocalDateTime 对象。这里要注意的是 LocalDate 和 LocalTime 这两个类别都已经定义好它们运用的领域(文章一开始有提到 Domain-driven design),因此,LocalDate 是无法使用 of 方法指定时间的,LocalTime 也无法使用 of 方法指定日期,如果要同时使用 of 方法指定日期与时间,需得用 LocalDateTime。
举个例子,创建出「2015 年 4 月 5 日下午 12 点 30 分 30 秒」的对象:
final LocalDateTime qingming = LocalDateTime.of(2015, 4, 5, 12, 30, 30);
final LocalDate qingmingDate = LocalDate.of(2015, 4, 5); //同qingming.toLocalDate()
final LocalTime qingmingTime = LocalTime.of(12, 30, 30); //同qingming.toLocalTime()
parse
parse 是类别方法,可以直接传入字符串来产生 LocalDate、LocalTime 和 LocalDateTime 对象。传入的字符串格式可由 DateTimeFormatter 来决定,预设分别是使用 DateTimeFormatter.ISO_LOCAL_DATE、DateTimeFormatter.ISO_LOCAL_TIME 和 DateTimeFormatter.ISO_LOCAL_DATE_TIME,用法如下:
final LocalDateTime qingmingParsed = LocalDateTime.parse("2015-04-05T12:30:30");
使用 DateTimeFormatter 类别提供的 ofPattern 方法,可以自订日期与时间字符串格式化的方式,至于 Pattern 的写法可以参考 DateTimeFormatter 的 Java 文档。上面程序,可以使用自订的 DateTimeFormatter,改写如下:
final LocalDateTime qingmingParsed = LocalDateTime.parse("2015/04/05 12:30:30", DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss"));
活用 LocalDate、LocalTime 与 LocalDateTime 对象
取得年、月、日、小时、分钟、秒、星期
java.time 套件提供的取得日期与时间之功能,不像以往的 java.util.Date 会用一些奇怪的数值来表示,像是用 0 表示 1 月,用 70 表示公元 1970 年,java.time 套件将这些数值都改成大家习惯的方式来表示了,有专有名词的单位(如:月、星期)还用了枚举来表示,方便了很多。
final LocalDateTime currentDateTime = LocalDateTime.now();
final int year = currentDateTime.getYear();
final int month = currentDateTime.getMonthValue();
final Month m = currentDateTime.getMonth();
final int day = currentDateTime.getDayOfMonth();
final DayOfWeek w = currentDateTime.getDayOfWeek();
final int hour = currentDateTime.getHour();
final int minute = currentDateTime.getMinute();
final int second = currentDateTime.getSecond();
修改日期或时间
以往的 java.util.Date 有提供 setter 方法让设计师可以直接修改 Date 对象所代表的日期与时间,这个情形在 java.time 套件下并不会出现,前面有提到过,java.time 套件底下的对象都是 Immutable Object,一旦被创建后,就只能读取,不能再被改变。虽然是说不能被改变,却也并不是说 java.time 套件下的对象创建完成后,如果要修改它的值只能再从头使用类别方法产生一个新的对象出来。这些 Immutable Object 还是有提供一些方法来指定新的数值,只是会产生出新的对象。
final LocalDate currentDate = LocalDate.now();
final LocalDate thisMonth = currentDate.withDayOfMonth(1); //将日期指定为该月1号。注意这里currentDate并没有被改变!
LocalDate、LocalTime 与 LocalDateTime 对象也和 Instant 等对象一样可以做一些时间的运算。例如,计算出下个礼拜的时间,程序如下:
final LocalDateTime nextWeekDateTime = LocalDateTime.now().plusWeeks(1);
final LocalDateTime next7DaysDateTime = LocalDateTime.now().plusDays(7);
时间点的转换
TemporalAdjusters 提供了许多类别方法来从某一时间点下跳到其他的时间点,不需要设计师自己多写程序来实作。以下举几个例子:
取得目前这个月的最后一天
西历每个月的天数都不同,在以前,如果要取得该月的最后一天是几号,还需要去判断其是否为 2 月,若是,还要判断其是否为闰年;若不是,还要判断其为大月还是小月,十分麻烦。有了 TemporalAdjusters 后,程序就可以这样写:
final LocalDateTime lastDayOfMonthDateTime = LocalDateTime.now().with(TemporalAdjusters.lastDayOfMonth());
取得距离目前最近的星期三
TemporalAdjusters 提供了 next 和 nextOrSame 与 previous 和 previousOrSame 方法,可以快速找出某一时间点往前或是往后距离最近的星期日子。
final LocalDateTime previousWednesdayDateTime = LocalDateTime.now().with(TemporalAdjusters.previousOrSame(DayOfWeek.WEDNESDAY));
final LocalDateTime nextWednesdayDateTime = LocalDateTime.now().with(TemporalAdjusters.next(DayOfWeek.WEDNESDAY));
减少时间精确度(Truncation)
在进行时间运算的时候,常常会因为时间的精确度而造成一些误差。例如在以往使用 Date 对象做日期计算的时候,都必须特意将时间设为 00:00:00 或者是其他固定的时刻。在 java.time 套件下,已有内置减少时间精确度的相关实作,就不必再由设计师自行手动调整了!
只有 LocalTime 与 LocalDateTime 对象有 truncatedTo 方法可以使用,使用方式如下:
final LocalDateTime hourDateTime = LocalDateTime.now().truncatedTo(ChronoUnit.HOURS); //舍弃比小时小的单位
ZonedDateTime 的创建与使用
前面提到的 LocalDate、LocalTime 与 LocalDateTime 都没有时区的概念,如果有要使用到时区的话,应该要使用 ZonedDateTime 这个类别。ZonedDateTime 对象的创建方式和 LocalDateTime 挺像的,只不过 ZonedDateTime 需要在创建时多代入 ZoneId 对象来指定时间的时区。
举个例子,取得目前系统的日期与时间,并显示出来:
final ZonedDateTime currentPoint = ZonedDateTime.now(); //同ZonedDateTime.now(Clock.systemDefaultZone())。直接使用ZonedDateTime类别来取得日期与时间,由于Clock对象已有时区信息,故不用再代入时区
System.out.println(currentPoint);
印出结果为:
除了使用 ZonedDateTime 类别来创建 ZonedDateTime 对象之外,也可以直接用 LocalDateTime 对象的 atZone 方法,参数传入 ZoneId 对象,就能转成 ZonedDateTime 对象,如下:
final LocalDateTime currentDateTime = LocalDateTime.now();
final ZonedDateTime zonedCurrentDateTime = currentDateTime.atZone(ZoneId.of("+8"));
ZonedDateTime 对象因为已经包含了时区信息,因此可以直接使用 toInstant 方法,不用代入任何时区参数,就可以转成 Instant 对象。
final Instant zonedCurrentInstant = ZonedDateTime.now().toInstant();
年表/历法(Chronology)
java.time 套件除了能支持国际通用的 ISO 8601 日期与时间的表示方式外,还支持一些 non-ISO 的历法,相关 API 都在 java.time.chrono 套件内。举例来说,如果要使用日本昭和或是平成年号来纪年的话,可以使用 java.time.chrono 里的 JapaneseChronology、JapaneseDate 与 JapaneseEra(日本年号枚举)类别,程序如下:
final JapaneseChronology japaneseChronology = JapaneseChronology.INSTANCE;
final JapaneseDate japaneseDate = japaneseChronology.dateNow();
System.out.println(japaneseDate);
印出结果为:
YearMonth 与 MonthDay
有时我们只会需要年月(如信用卡的有效日期)或是月日(如生日)等数据,java.time 套件里也有这样的类别存在,分别就是 YearMonth 和 MonthDay。如下:
final MonthDay birthday = MonthDay.of(8, 10);
final YearMonth creditCard = YearMonth.of(2015, 4);
由于 YearMonth 和 MonthDay 所含的信息比较少,因此若要转成 LocalDate 对象,还需要再提供更多的信息,如以下程序:
final LocalDate birthdayLocalDate = birthday.atYear(1993);
final LocalDate creditCardLocalDate = creditCard.atDay(5);
农历(Chinese Calendar)
原先以为这次 Java 8 的 Date-Time API 更新应该会支持农历,但很可惜的还是没有。如果想在 Java 上使用农历的话,可以参考底下这篇文章:
