Joda: what's the difference between Period, Interval and Duration?

Question

1. Why do we need three classes?

2. Which one performs better?

3. Why is dividing a Period or Duration or Interval instance not implemented? E.g. p = p.divideBy(2);

Answer 1

3 classes are needed because they represent different concepts so it is a matter of picking the appropriate one for the job rather than of relative performance. From the documentation with comments added by me in italics:

---

An interval in Joda-Time represents an interval of time from one millisecond instant to another instant. Both instants are fully specified instants in the datetime continuum, complete with time zone. Specific times are defined e.g. this might be the interval between 20:00:00GMT and yesterday and 09:00:00GMT this morning.

A duration in Joda-Time represents a duration of time measured in milliseconds. The duration is often obtained from an interval. i.e. we can subtract start from end of an interval to derive a duration

A period in Joda-Time represents a period of time defined in terms of fields, for example, 3 years 5 months 2 days and 7 hours. This differs from a duration in that it is inexact in terms of milliseconds. A period can only be resolved to an exact number of milliseconds by specifying the instant (including chronology and time zone) it is relative to. e.g. consider the period of 1 year, if we add this to January 1st we will always arrive at the next January 1st but the duration will depend on whether the intervening year is a leap year or not. Similarly if we add 1 month to the 1st of a month then we will arrive at the 1st of the next month but the duration (in milliseconds) will vary based on the month in question

---

For question 3, A specific method to divide a duration is not really needed because we can always get the number of milliseconds from the duration as a long (using getMillis()), divide it and construct a new duration (using new Duration(long duration)).

Dividing a period doesn't really have a real meaning based on the definition of a period above. e.g. what is half a month? (its length would depend on which month).

Answer 2

To add to mikej's answer:

A Joda's duration is a "physical" time interval, eg: "12000 milliseconds"

A Joda's interval is actually a pair of instants (start instant - end instant), where "instants" are fully specified datetimes (civil and physical datetime). Eg: (2010/3/3 19:00:00.000 UTC - 2010/3/3 20:00:00.000 UTC) They can be converted to a duration, but not the reverse.

So, say, these two intervals: (2010/3/3 19:00:00.000 UTC - 2010/3/3 20:00:00.000 UTC) and (2010/3/3 21:00:00.000 UTC - 2010/3/3 22:00:00.000 UTC) are different, but if I convert them to durations, they are equal (3600000 millisenconds)

A period is a lapse of "civil time", expressed as a number of months, days, hours, etc. It does not -by itself- represent a "physical" interval, hence it can't be directly converted to a duration (months have variable lengths...).

This answers question 3: you can only "divide by two" a physical time (a duration).