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