Featured White Papers

• Measuring Risk to Improve Java Software Quality
• Do You Really Get Classloaders?
• Pragmatic Continuous Delivery with Jenkins, Nexus, and LiveRebel
• Your Next Java Web App: Less XML, No Long Restarts, Fewer Hassles
• Coding with JRebel, Java Forever Changed
• 2012 Developer Productivity Report: Java Tools, Tech, Devs, and Data

Sponsored Links

• Graph databases are 1000x faster than relational.

  Learn More!

• Career opportunities at Harman- Careers That'll Rock Your Socks Off.

  Learn More!

• Developer-friendly Java PDF libraries by Qoppa Software

  Live Demos

• Stop blaming your app! Diagnose Java performance issues.

  Free tool >

• UrbanCode: Go From Continuous Integration to
  Continuous Delivery

  Learn More!

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

Java 101: The next generation: It's time for a change

Catching up with the Java Date and Time API

By Jeff Friesen, JavaWorld.com, 04/08/13

Page 2 of 7

Java Date and Time API overview

JSR 310: Date and Time API was developed to overcome numerous problems with Java's previous date and time APIs. As a result, it has been architected around a number of important design principles:

• Immutability and thread safety: All of the Date and Time API's core classes are immutable, which ensures that you don't have to worry about threading issues caused by lack of thread synchronization. Immutable objects are simple to construct, use, and test, they make for good hash keys, and so on.
• Fluency: Date and Time presents a fluent interface, which should make its methods more readable and easier to learn, especially when chained together. Fluent factory methods (e.g., now(), from(), and of-prefixed methods) are used as an alternative to constructors. You'll also be able to use with-prefixed methods if you need to return a copy of the current instance with additional information.
• Clarity: Each method in the Date and Time API is well-defined and clear about what it accomplishes. Additionally, Date and Time rejects null arguments early. Unless otherwise noted, passing a null argument to a method in any class or interface will cause a NullPointerException to be thrown. Validation methods that take object arguments and return Boolean values are an exception: they generally return false when null is passed.
• Extensibility: The Strategy design pattern is used throughout the API to allow for extension while avoiding confusion. For example, although Date and Time's classes are based on the ISO-8601 calendar system, you can also work with the non-ISO calendars (such as Japanese Imperial) that are included in the API, or you could even introduce your own calendar.

Date and Time is described by some 60 types (at the time of this writing) that are organized into a main package and four subpackages:

• java.time presents classes that represent the principal date-time concepts: instants, durations, dates, times, time zones, partials, and periods. All of this package's classes are immutable and thread-safe.
  • java.time.chrono provides a generic API that describes calendar systems other than the default ISO-8601 calendar system.
  • java.time.format presents classes for formatting and parsing date-time objects.
  • java.time.temporal offers field, unit, or adjustment access to a temporal object such as a date.
  • java.time.zone presents classes that support time zones and their rules.

The types in the java.time package should serve most of your needs. You'll work directly with the types in the other four packages only when you need to go beyond java.time's default ISO-8601 calendar system.

Touring the Date and Time API

Date and Time's many types can seem overwhelming. However, you'll often work with only a subset of the types in the java.time package. The remainder of the article will be a tour of the java.time types that you are most likely to use: classes used to store and manipulate machine time, local date and time, and international time zones in your Java applications. For each of the API types I'll include a brief overview followed by one or more working applications that demonstrate how classes are instantiated, how instances are accessed, and how instances are manipulated to obtain new instances.