DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

The software you build is only as secure as the code that powers it. Learn how malicious code creeps into your software supply chain.

Apache Cassandra combines the benefits of major NoSQL databases to support data management needs not covered by traditional RDBMS vendors.

Generative AI has transformed nearly every industry. How can you leverage GenAI to improve your productivity and efficiency?

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workloads.

Related

  • How to Merge HTML Documents in Java
  • The Future of Java and AI: Coding in 2025
  • Tired of Spring Overhead? Try Dropwizard for Your Next Java Microservice
  • Using Python Libraries in Java

Trending

  • Secrets Sprawl and AI: Why Your Non-Human Identities Need Attention Before You Deploy That LLM
  • Exploring Intercooler.js: Simplify AJAX With HTML Attributes
  • Cloud Security and Privacy: Best Practices to Mitigate the Risks
  • How To Introduce a New API Quickly Using Quarkus and ChatGPT
  1. DZone
  2. Coding
  3. Java
  4. Java 8 APIs: java.util.time - Instant, LocalDate, LocalTime, and LocalDateTime

Java 8 APIs: java.util.time - Instant, LocalDate, LocalTime, and LocalDateTime

An overview starting with some basic classes of the Java 8 package: Instant, LocalDate, LocalTime, and LocalDateTime.

By 
Eyal Lupu user avatar
Eyal Lupu
·
Jul. 19, 13 · Tutorial
Likes (7)
Comment
Save
Tweet
Share
214.9K Views

Join the DZone community and get the full member experience.

Join For Free

I started to experience the Java 8 new APIs (still Early Access at the moment of writing this post) and the first thing I looked into was the new date and time API (JSR 310). As there is much to cover in this new long awaited API I think it worth few posts with some examples. This post would be the first in a series, starting with some basic classes of the package: Instant, LocalDate, LocalTime, and LocalDateTime. 

Instant (java.time.Instant)

Probably the best place to start with the java.time package is the Instant class. An Instant represents a point in time (similar to java.util.Date) with nanoseconds precision (unlike the old Date which has milliseconds precision). Representing a point in time using nanoseconds precision requires more space than a Long can provide, therefore the internal representation is composed of two Long fields, the first holds the number of seconds since (or before) the standard Java epoch and the other the number of nanoseconds of the last seconds (so never larger than 999,999,999). Let's start with obtaining an Instant instance and print its value:

// Get the current time
Instant instant = Instant.now();

// Output format is ISO-8601
System.out.println(instant);


Instant.toString() returns a ISO8601 formatted string (such as: '2013-06-25T16:22:52.966Z'), a much more logical choice than the one used by the old Date class. Here are some other ways to create Instants:

// Convert a java.util.Date into an Instant
Instant instant = Instant.ofEpochMilli(new Date().getTime());

// Create from a String
instant = Instant.parse("1995-10-23T10:12:35Z");


The second example above creates an Instant by parsing a String, this string must by a valid representation of a UTC Instant (NB: Instant is a point of time, it doesn't store any TimeZone information and as such it supports only UTC formatted strings). Instant API provides some useful methods to allow calculations using Instants and other classes in the package, below is a first example:

// Adding 5 hours and 4 minutes to an Instant
instant.plus(Duration.ofHours(5).plusMinutes(4));


How many instances of java.time.Instant are used in the example above? Two. The java.time package is planned to be thread safe and as such most of its classes are immutable, Instant is not an exception to that rule and as such the plus() method creates a new instance.

Instant instant1 = instant.plus(Duration.ofHours(5).plusMinutes(4));
System.out.println("Instant is immutable, so instant==instant returns: " + (instant == instant1));

The output would be: 
Instant is immutable, so instant==instant returns: false


Here are few more examples of Instant calculations:

// Substract 5 days of an instant
instant.minus(5, ChronoUnit.DAYS); // Option 1
instant.minus(Duration.ofDays(5)); // Option 2

// How many minutes are between to Instants?
long diffAsMinutes = instant.periodUntil(instant1, ChronoUnit.MINUTES); // Option 1
long diffAsMinutes = ChronoUnit.MINUTES.between(instant, instant1); // Option 2


Instants are Comparable which means they can be used in any place a Comparable is expected (such as collections). Instant also provides the isAfter() and isBefore() methods which can make a more readable code:

// Compare the two
System.out.format("instant1.compareTo(instant)=%d.%n", instant1.compareTo(instant));

// We can check to see which Instant is before/after the other
System.out.format("instant1.isAfter(instant)=%b, instant1.isBefore(instant)=%b.%n", 
 instant1.isAfter(instant), instant1.isBefore(instant));

The output would be:
instant1.compareTo(instant)=1.
instant1.isAfter(instant)=true, instant1.isBefore(instant)=false.

LocalDate and LocalTime

LocalDate represents a date without a time zone, such as 1-1-2000. LocalTime represents time without a time zone, such as 04:44:59.12 - unlike Instant which is an offset from the Java epoch and as such can be calculated into a precise point of time these two are just date or time without any relation to the epoch - a human readable date and time. There are several ways to obtain LocalTime and LocalDate instances, here are few:

LocalDate localDate = LocalDate.now();
localDate = LocalDate.ofYearDay(2005, 86); // The 86th day of 2005 (27-Mar-2005)
localDate = LocalDate.of(2013, Month.AUGUST, 10); //10th of Aug 2013

LocalTime localTime = LocalTime.of(22, 33); //10:33 PM
localTime = LocalTime.now();
localTime = LocalTime.ofSecondOfDay(4503); // The 4,503 second in a day (1:15:30 AM)


LocalDate and Local time follow the same general concept of multithreading as Instant does - and as such their instances are immutable. LocalDate and LocalTime have calculation and comparison methods similar to the ones Instant has (some of the methods are defined by the java.time.temporal.Temporal interface which implemented by all of these classes):

LocalDate localDate1 = localDate.plus(5, ChronoUnit.HOURS);
localDate.isBefore(localDate1);

LocalDateTime

The last important player in the simple date and time classes is LocalDateTime - this is a combination of LocalDate and LocalTime representing a date and the time within that date, again no time zone. LocalDateTime seems to be very similar to Instant, a reminder: "an Instant is point in time without time zone” and one could say that a point in time is nothing more than a date and time within that date. But there is a difference: LocalDateTime is not a point on the time line as Instant is, LocalDateTime is just a date and time as a person would write on a note. Consider the following example: two persons which were born at 11am, July the 2nd 2013. The first was born in the UK while the second in California. If we ask any of them for their birth date it will look that they were born on the same time (this is the LocalDateTime) but if we align the dates on the timeline (using Instant) we will find out that the one born in California is few hours younger than the one born in the UK (NB: to create the appropriate Instant we have to convert the time to UTC, this is where the difference lays). Beside of that LocalDateTime behaves very similar to the other classes illustrated above:

LocalDateTime localDateTime = LocalDateTime.now();

// Jump to 25 hours and 3 minutes into the future
LocalDateTime inTheFuture = localDateTime.plusHours(25).plusMinutes(3);

// We could do the same on localTime or localDate
System.out.println(localDateTime.toLocalTime().plusHours(25).plusMinutes(3));
System.out.println(localDateTime.toLocalDate().plusMonths(2));

// We could also use TemportalAmount (in this case a Duration and Period)
System.out.println(localDateTime.toLocalTime().plus(Duration.ofHours(25).plusMinutes(3)));
System.out.println(localDateTime.toLocalDate().plus(Period.ofMonths(2)));



Java (programming language)

Published at DZone with permission of Eyal Lupu, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • How to Merge HTML Documents in Java
  • The Future of Java and AI: Coding in 2025
  • Tired of Spring Overhead? Try Dropwizard for Your Next Java Microservice
  • Using Python Libraries in Java

Partner Resources

×

Comments

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends: