What Java DateTime class should I use?

Question

We have a library used for generating reports. It reads from a data file (SQL, XML, JSON, etc.), the datetime may then be modified in a user written equation, and then it is formatted as specified for the report output.

The use in an equation can be add a timespan, get parts of the value as in "if date.month == 2", and pretty much all the datetime macros in Excel.

Because the data can be JSON (or XML with no schema) the datetime can be "2019-01-25", "2019-01-25T14:32:23", "2019-01-25T14:32:23.12345", "2019-01-25T14:32:23Z", or "2019-01-25T14:32:23Z-0500" (last two can have the ".12345" also).

If there's no timezone offset we assume the datetime is UTC. While that should be true, often it isn't and it's local time but the way it's used, it doesn't matter. So making it UTC unless a timezone offset is specified works (up till now we've used Date).

First question - what class should I use to hold this value? From what I've read I think ZonedDateTime, but maybe Instant?

Second question - what class should I use for timespan when I have to do something like add 3 days to the datetime?

Third question - is there some parser that can parse all the different strings as I listed above? Or do I need to call String.contains() to determine the format and then do an explicit pattern based on that? And if so, using what class?

Judgeship

There are no timezones in your examples, only timezone offsets, so OffsetDateTime would make more sense than ZonedDateTime. – Ariannaarianne

Have you considered Joda Time? It is my favourite class for working with time. If you could implement it, I could make an answer about it if you want. – Cheyenne

@S.Czop we're on Java 1.8 so we're going to use java.time. – Judgeship

@S.Czop why use an external library for something that's now covered in the standard runtime (unless you have to use Java 7). – Kagera

Re. your first Q. looking at your last example 2019-01-25T14:32:23Z-0500: do you need to know the offset of 5hrs? Or are you ok with only keeping the same instant in UTC, i.e. 2019-01-25T19:32:23Z? Or would you prefer having 2019-01-25T14:32:23Z (which is NOT the same instant but the same local time)? – Ariannaarianne

Re. you 2nd Q: once you have an OffsetDateTime (for example), you can write datetime.plusDays(3) to add 3 days. But there is no Timespan class in Java Time. You could easily write your own class or use ThreeTen Interval class which is an extension of Java Time. – Ariannaarianne

@Ariannaarianne - Good question. I think if they give us an offset, we need to keep it and work with it. For most uses the offset won't matter. But if it does, it would be an error if we converted them to UTC. Or am I missing something? – Judgeship

And for Q3: #36188928 – Ariannaarianne

@Ariannaarianne - if you put all that in an answer, I'm happy to mark that the answer. Also, should I use OffsetDateTime or LocalDateTime as my class to hold this? As I can get an offset, I'm thinking OffsetDateTime??? – Judgeship

Answer 1

Third question - is there some parser that can parse all the different strings as I listed above? Or do I need to call String.contains() to determine the format and then do an explicit pattern based on that? And if so, using what class?

I might be horrible wrong, but can you use DateTimeFormatter with optional parts on pattern and parseBest method:

List<String> dates = List.of(
    "2019-01-25", 
    "2019-01-25T14:32:23",
    "2019-01-25T14:32:23.12345", 
    "2019-01-25T14:32:23Z", 
    "2019-01-25T14:32:23Z-0500"
);

DateTimeFormatter formatter = DateTimeFormatter.ofPattern(
   "yyyy-MM-dd['T'[HH:mm:ss][.SSSSS]][z][x]"
); // all the possible combinations

dates.forEach( date -> {
            TemporalAccessor accessor = formatter.parseBest(date,                       
       OffsetDateTime::from, // going from most specific date
       LocalDateTime::from, 
       LocalDate::from); // to the less specific 

            System.out.println( accessor.getClass() + " " + accessor);
        }

);

// output for this is 
class java.time.LocalDate 2019-01-25
class java.time.LocalDateTime 2019-01-25T14:32:23
class java.time.LocalDateTime 2019-01-25T14:32:23.123450
class java.time.OffsetDateTime 2019-01-25T14:32:23Z
class java.time.OffsetDateTime 2019-01-25T14:32:23-05:00

Obmutescence

Answer 2

As to the 2nd question: Yes there is a "timespan" class in the Java JDK.

For a span-of-time not attached to the timeline:

Period

Represents a number of days/weeks/months/years. Can be used in date calculations, automatically accounting for Daylight Savings Time (DST).

For example, to subtract 3 days from a given date, you could do

ZonedDateTime threeDaysAgo = Period.ofDays(-3).addTo(ZonedDateTime.now());

Duration

Similar to Period but on the scale of days (as 24-hour chunks, not calendar days), hours, minutes, seconds, and fractional second.

ChronoUnit

If you need to do calculations on a wider scale (like include hours/minutes/secods etc) There is also the ChronoUnit enum:

ZonedDateTime threeHoursAgo = ChronoUnit.HOURS.addTo(ZonedDateTime.now(), -3);

Carinacarinate

Yes and know - It's not really a timespan in the sense that it doesn't hold the start and end date - not sure if that's an issue. And also doesn't have hour/minute/second precision. – Ariannaarianne

you meant yes and no. and regardless of the meaning of the term, it is exactly what OP requested - a container for something like "3 days" not range between specific days. – Carinacarinate

edited answer to include a solution for wider range of time units – Carinacarinate

For a span-of-time attached to the timeline, see the Interval & LocalDateRange classes in the ThreeTen-Extra library. – Dialogize