NOW Hiring

Quick links

Java Data and Time API in Java 8 - Tutorial

Lars Vogel

Version 1.1


Java Date and Time API

This article explains the Java 8 API for using the Date and Time API.

Table of Contents

1. Java 8 Date and Time API introduction
2. Parsing and formatting Dates and Times
3. About this website
4. Links and Literature
4.1. Date and Time resources
4.2. vogella GmbH training and consulting support

1. Java 8 Date and Time API introduction

The Java language provides direct support for time-based objects. While early versions of Java already had support for Date and Time, the Java 8 release contained a new API based on immutable-value classes, which are thread-safe. These classes provide a fluent API for construction.

The java.time.LocalDate and the java.time.LocalTime classes provide a representation of date and time without timezones. They represent date and time from the context of an observer, such as a calendar on a desk or a clock on your wall.

java.time.LocalDateTime represents both a date and a time.

The following code snippet demonstrates the usage these objects.

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;
import java.time.Month;
import java.time.temporal.ChronoUnit;
import java.time.temporal.TemporalAdjusters;

public class ExampleLocalDateandTimeCreation {
  public static void main(String[] args) {
    // The current date and time
    LocalDateTime dateTime =;
    // from values
    LocalDate d1 = LocalDate.of(2015, Month.JULY, 13);

    // construct time object based on hours and minutes
    LocalTime t1 = LocalTime.of(17, 18);
    // create time object based on a String
    LocalTime t2 = LocalTime.parse("10:15:30");

    // Get the time or date from LocalDateTime
    LocalDate date = dateTime.toLocalDate();
    Month month = dateTime.getMonth();
    int day = dateTime.getDayOfMonth();
    int minute = dateTime.getMinute();
    // Perform operations on these objects will always return a new object
    // as these objects are immutable
    LocalDateTime updatedDate = dateTime.withDayOfMonth(13).withYear(2015);
    LocalDateTime plusYears = updatedDate.plusDays(25).plusYears(2);
    // the API also allow to use Adjusters for the API,
    // for example the following will set the day to the last day in the monthd
    LocalDateTime newDate = dateTime.with(TemporalAdjusters.lastDayOfMonth());
    // You can also truncate certain time units, e.g., remove the seconds from a time 
    // object
    LocalTime truncatedSeconds = t2.truncatedTo(ChronoUnit.SECONDS);

The java.time.Duration class can be used to describe durations.

import java.time.Duration;

public class ExampleDuration {
public static void main(String[] args) {
  // define a duration of 5 hours
  Duration duration = Duration.ofHours(5);
  // add 20 minutes
  Duration plusMinutes = duration.plusMinutes(20);

2. Parsing and formatting Dates and Times

To Date and Time classes of Java 8 provide a parse method for parsing a String that contains date and time information. They also provide the format method for formating Date and Time objects for output.

In both cases you create an instance of DateTimeFormatter which is passed to the parse or format method.

import java.time.LocalDate;
import java.time.Month;
import java.time.format.DateTimeFormatter;

public class ExampleFormatter {
  public static void main(String[] args) {
    DateTimeFormatter formatter = DateTimeFormatter.ofPattern("MMM d yyyy");
    // use this format to get always two digits for the day
    DateTimeFormatter f1 = DateTimeFormatter.ofPattern("MMM dd yyyy");
    LocalDate date = LocalDate.of(2015, Month.JULY, 1);
    LocalDate d2 = LocalDate.of(2015, Month.JULY, 15);

3. About this website

4. Links and Literature

4.1. Date and Time resources

Oracle blog post

4.2. vogella GmbH training and consulting support

The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”. The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.