Period and Duration in Java

by

In this post, we will discuss Period and Duration classes introduced in Java 8.

Introduction

In the previous article, we discussed Java 8 Date and Time API.In this post, we will look into two important classes introduced in Java 8 Date Time API: Period and Duration. 

Period and Duration in Java can be used to the represented amount of time or difference between two dates.Below are important characteristics and differences between these two classes.

  • The Duration class represents the time-based amount of time.
  • The Period class represents a date-based amount of time.

[pullquote align=”normal”]Both Duration and Period classes are immutable which ensure thread safety and a constant domain model [/pullquote]

 

1.Duration class

The Duration class represents an amount of quantity of time in terms of seconds and nanoseconds.Duration class is most suitable for the machine level time representation.

Let’s take a look at few examples of understand this class more clearly. We will find the difference between two Temporal objects using static between method provided by Duration class

Duration duration = Duration.between(time1, time2);
Duration duration = Duration.between(instance1, instance2);

Let’s find Duration between 2 LocaleDateTime instances.

LocalDateTime currentTime=LocalDateTime.now();
LocalDateTime oldTime= LocalDateTime.of(2017, 03, 23,8,10,23);

System.out.println(Duration.between(oldTime,currentTime));

We can use various methods available in the Duration class to find the value of time in units.

LocalDateTime currentTime=LocalDateTime.now();
LocalDateTime oldTime= LocalDateTime.of(2017, 03, 23,8,10,23);

System.out.println(Duration.between(oldTime,currentTime).getSeconds());
System.out.println(Duration.between(oldTime,currentTime).getNano());
System.out.println(Duration.between(oldTime,currentTime).toDays());

Output

30632813
204000000
354

 

Duration class provides a number of convenient factory methods to create Duration object.

Duration fiveMinutes = Duration.ofMinutes(5);
Duration fiveMinutes = Duration.of(5, ChronoUnit.MINUTES);
Duration days = Duration.ofDays(4);

 

1.1 Other Unit Conversion

The duration class provides a number of convenient methods to convert it to other time units.

Duration fiveMinutes = Duration.ofMinutes(5);
fiveMinutes.toDays()
fiveMinutes.toHours();
fiveMinutes.toDays()

 

Duration class represents the amount of time in seconds and nanoseconds.We can not use LocalDate with between method.

LocalDate date=LocalDate.now();
LocalDate date2= LocalDate.of(2017, 03, 23);

System.out.println(Duration.between(date2,date));

Output

Exception in thread "main" java.time.temporal.UnsupportedTemporalTypeException: Unsupported unit: Seconds
	at java.time.LocalDate.until(LocalDate.java:1614)
	at java.time.Duration.between(Duration.java:475)
	at TimeAPI.main(TimeAPI.java:15)

 

2. Period class

This class represents a quantity or amount of time in terms of years, months and days.We can get Period instance between two date objects by using between() method 

LocalDate date=LocalDate.now();
LocalDate date2= LocalDate.of(2017, 03, 23);

System.out.println(Period.between(date2,date));
System.out.println(Period.between(date2,date).getYears());
System.out.println(Period.between(date2,date).getMonths());
System.out.println(Period.between(date2,date).getDays());

The Period class provides a number of convenient factory methods to create a Period object.

Period.of(2017, 3, 5);
Period.ofDays(5);
Period.ofMonths(1);
Period.ofWeeks(3);
Period.ofYears(10);

 

For all method with signature ofXX(), the value of other units set to 0. Let’s take the example of  Period.ofDays(5);, Duration class will set values of year and month as 0.

public static Period ofDays(int days) {
    return create(0, 0, days);
}

In the case of Period.ofWeeks(3);, the parameter value is used to set number days by multiplying it by 7.

public static Period ofWeeks(int weeks) {
   return create(0, 0, Math.multiplyExact(weeks, 7));
}

 

[pullquote align=”normal”]Both Duration and Period classes are immutable which make sure thread safety, consistent domain model. [/pullquote]

 

Summary

In this post, we discussed Period and Duration classes in Java. We discussed the use cases and some of the methods provided by these classes.