<?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> |