| <?xml version="1.0" encoding="ISO-8859-1"?> | |
| <document> | |
| <properties> | |
| <title>Java date and time API - Duration</title> | |
| <author>Stephen Colebourne</author> | |
| </properties> | |
| <body> | |
| <section name="Duration"> | |
| <p> | |
| A <i>duration</i> in Joda-Time represents a duration of time measured in milliseconds. | |
| The duration is often obtained from an <a href="key_interval.html">interval</a>. | |
| </p> | |
| <p> | |
| Durations are a very simple concept, and the implementation is also simple. | |
| They have no <a href="key_chronology.html">chronology</a> or time zone, and consist | |
| solely of the millisecond duration. | |
| </p> | |
| <p> | |
| Durations can be added to an <a href="key_instant.html">instant</a>, or to either | |
| end of an interval to change those objects. | |
| In datetime maths you could say: | |
| <source> | |
| instant + duration = instant | |
| </source> | |
| </p> | |
| <p> | |
| Durations implement <code>Comparable</code> which compares the lengths of the two durations. | |
| </p> | |
| </section> | |
| <section name="Using Durations in Joda-Time"> | |
| <p> | |
| Within Joda-Time a duration is represented by the | |
| <a href="apidocs/org/joda/time/ReadableDuration.html">ReadableDuration</a> interface. | |
| There is one implementation of the interface provided: | |
| <ul> | |
| <li><a href="apidocs/org/joda/time/Duration.html">Duration</a> - | |
| An immutable implementation</li> | |
| </ul> | |
| </p> | |
| <p> | |
| The code can be used in various ways: | |
| <source> | |
| DateTime start = new DateTime(2004, 12, 25, 0, 0, 0, 0); | |
| DateTime end = new DateTime(2005, 1, 1, 0, 0, 0, 0); | |
| // duration in ms between two instants | |
| Duration dur = new Duration(start, end); | |
| // calc will be the same as end | |
| DateTime calc = start.plus(dur); | |
| </source> | |
| </p> | |
| <p> | |
| Note that the interface <code>ReadableDuration</code> should not be used like the collections API. | |
| The interface only contains the core subset of the operations. | |
| Instead, you should usually refer directly to the implementation class in your APIs. | |
| </p> | |
| <subsection name="Nulls"> | |
| <p> | |
| Joda-Time defines a null duration as zero length. | |
| Thus, when a method is defined as taking a <code>ReadableDuration</code>, passing null in | |
| will be the same as passing in a zero length duration. | |
| </p> | |
| </subsection> | |
| </section> | |
| </body> | |
| </document> |