| <?xml version="1.0" encoding="ISO-8859-1"?> | |
| <document> | |
| <properties> | |
| <title>Java date and time API - Instant</title> | |
| <author>Stephen Colebourne</author> | |
| </properties> | |
| <body> | |
| <section name="Instant"> | |
| <p> | |
| The most frequently used concept in Joda-Time is that of the <i>instant</i>. | |
| An Instant is defined as <i>an instant in the datetime continuum specified as a | |
| number of milliseconds from 1970-01-01T00:00Z</i>. | |
| This definition of milliseconds is consistent with that of the JDK in <code>Date</code> | |
| or <code>Calendar</code>. Interoperating between the two APIs is thus simple. | |
| </p> | |
| <p> | |
| The millisecond instant can be converted to any date time field using a | |
| <a href="key_chronology.html">Chronology</a>. | |
| To assist with this, methods are provided on <code>DateTime</code> that act as getters for | |
| the most common date and time fields. | |
| More powerful access to the field can be obtained via its property. | |
| <source> | |
| DateTime dt = new DateTime(); // current time | |
| int month = dt.getMonth(); // gets the current month | |
| int month = dt.month().get(); // alternative way to get value | |
| String monthStr = dt.month().getAsText(); // gets the month name | |
| </source> | |
| </p> | |
| <p> | |
| To deal with local times (no time zone), or with date only or time only concepts, | |
| you should use the <a href="key_partial.html">partial</a> classes. | |
| </p> | |
| </section> | |
| <section name="Using Instants in Joda-Time"> | |
| <p> | |
| Within Joda-Time an instant is represented by the | |
| <a href="apidocs/org/joda/time/ReadableInstant.html">ReadableInstant</a> interface. | |
| There are four implementations of the interface provided: | |
| <ul> | |
| <li><a href="apidocs/org/joda/time/Instant.html">Instant</a> - | |
| A simple immutable implementation which is restricted to the UTC time zone | |
| and is intended for time zone and calendar neutral data transfer</li> | |
| <li><a href="apidocs/org/joda/time/DateTime.html">DateTime</a> - | |
| The most commonly used class in the library, and an immutable representation of a | |
| date and time with calendar and time zone</li> | |
| <li><a href="apidocs/org/joda/time/DateMidnight.html">DateMidnight</a> - | |
| Similar to <code>DateTime</code> and also immutable but with the time component | |
| forced to be midnight (at the start of a day)</li> | |
| <li><a href="apidocs/org/joda/time/MutableDateTime.html">MutableDateTime</a> - | |
| A mutable representation of date and time with calendar and time zone</li> | |
| </ul> | |
| We recommend the immutable implementations for general usage. | |
| </p> | |
| <p> | |
| The code can be used in various ways: | |
| <source> | |
| // setup date object for midday on Christmas 2004 (ISO year 2004) | |
| DateTime dt = new DateTime(2004, 12, 25, 12, 0, 0, 0); | |
| // get the year, 2004 | |
| int year = dt.getYear(); | |
| // get the day of week index 1 (Monday) to 7 (Sunday) | |
| int dow = dt.getDayOfWeek(); | |
| // get the text, such as 'Tuesday' | |
| String dowStr = dt.dayOfWeek().getAsText(); | |
| </source> | |
| Compared to <code>GregorianCalendar</code> Joda-Time classes use 1-12 for months, and are | |
| immutable in the standard implementations. | |
| It is also easy to convert to and from the JDK classes. | |
| <source> | |
| // construct DateTime from JDK Date | |
| Date jdkDate = new Date(); | |
| DateTime dt = new DateTime(jdkDate); | |
| // construct Calendar from DateTime (could also construct a Date) | |
| GregorianCalendar cal = dt.toGregorianCalendar(); | |
| </source> | |
| </p> | |
| <p> | |
| Note that the interface <code>ReadableInstant</code> should not be used like the collections API. | |
| The interface only contains the core subset of the operations of <code>DateTime</code>. | |
| You should use the interface only when you feel the need to be flexible about future changes | |
| to the object passed into a method. | |
| You might also want to consider the <a href="apidocs/org/joda/time/ReadableDateTime.html">ReadableDateTime</a> | |
| interface which extends <code>ReadableInstant</code> to provide additional methods. | |
| </p> | |
| <subsection name="Nulls"> | |
| <p> | |
| Joda-Time defines a null instant as the current time. | |
| Thus, when a method is defined as taking a <code>ReadableInstant</code>, passing null in | |
| will be the same as passing in an instant set to the current time. | |
| </p> | |
| </subsection> | |
| </section> | |
| </body> | |
| </document> |