Why is org.joda.time.LocalDate a date without a timezone?

Question

I think the name org.joda.time.LocalDate is kind of confusing. The documentation says:

LocalDate is an immutable datetime class representing a date without a time zone.

In comparison org.joda.time.DateTime says:

A DateTime calculates its fields with respect to a time zone.

I am always confusing those two so I hope somebody can tell me why those names are supposed to make sense.

---

Here is my intuition: A local date or time object would represent a point in time but with regards to a location. Hence it should contain the time zone information since the time zone also gives you some sort of location information. In any case you know a little more about somebodies location than without that time zone.

A date-time, at least as it sounds like, should only represent a date and a time. In this sense it is just the long value since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970.

---

So why is it actually the other way around? This naming bugs me every time I have something to do with time stamps. Can somebody explain?

Update:

Interesting link posted by a user: https://sourceforge.net/p/threeten/mailman/message/29962542/

Answer 1

Terminology

Your intuition is the opposite of the terminology used by both Joda-Time and java.time.

Both frameworks have a class named LocalDate to represent a date-only value without time-of-day and without time zone. The ”local“ means ”could be any locality, not any particular locality“.

The ”Local…“ classes are just a rough idea of a time. They are not on the timeline. They have no real meaning until you apply a time zone or offset-from-UTC to get actual moments on the timeline. When you see ”Local“ think: ”this value does not really make sense until we apply a time zone“.

For example, we say that Christmas is on 2016-12-25 this year. But the date is not the same around the world at any given moment. A new day dawns earlier in Paris than in Montréal for example. So to get the moment when Christmas starts in Paris, you must apply the Europe/Paris time zone and get the first moment of that day. That first moment will be represented by DateTime in Joda-Time and by ZonedDateTime (or OffsetDateTime) in java.time.

For example, in java.time:

LocalDate xmas2016 = LocalDate.of( 2016 , 12 , 25 );
ZonedDateTime xmas2016FirstMomentMontreal = xmas2016.atStartOfDay( ZoneId.of( "America/Montreal" ) );

java.time

In the java.time framework, a moment on the timeline in UTC is represented by the Instant class.

Instant now = Instant.now();

Apply a time zone, ZoneId, to get a ZonedDateTime.

ZoneId zoneId = ZoneId.of( "America/Montreal" );
ZonedDateTime zdt = ZonedDateTime.ofInstant( instant , zoneId );

If all you have is an offset-from-UTC rather than a full time zone, than use OffsetDateTime rather than ZonedDateTime.

You can think of this way:

Instant + ZoneId -> ZonedDateTime

Instant + ZoneOffset ->OffsetDateTime

This information has been covered many hundreds of times already on StackOverflow. Please search to learn more and see many pieces of example code.