<?xml version="1.0" encoding="ISO-8859-1"?> | |
<document> | |
<properties> | |
<title>Java date and time API - Partial</title> | |
<author>Stephen Colebourne</author> | |
</properties> | |
<body> | |
<section name="Partial"> | |
<p> | |
A <i>partial</i> in Joda-Time is a partial date and time representation. | |
All implementations represent local dates and times, and do not reference a time zone. | |
As such, they only <i>partially</i> represent a date or time in the datetime continuum. | |
</p> | |
<p> | |
The main implementations changed in version 1.3. | |
This was to address implementation issues with the original design. | |
The previous classes - <code>TimeofDay</code> and <code>YearMonthDay</code> - are now effectively deprecated. | |
The new implementations are <code>LocalDate</code>, <code>LocalTime</code> and <code>LocalDateTime</code>. | |
</p> | |
<p> | |
It is not possible to directly interoperate between a partial and an <a href="key_instant.html">instant</a>. | |
A partial does not fully specify a single point in the datetime continuum, but instead may match | |
multiple points. For example, a <code>LocalTime</code> occurs one per day on the datetime continuum. | |
</p> | |
<p> | |
A partial can be converted to a full instant by specifying the missing values. | |
At a minimum the time zone must be specified. It may be necessary to specify other missing fields. | |
For example, to convert a <code>LocalDate</code> to a <code>DateTime</code> requires | |
filling in the time fields and the time zone. | |
</p> | |
<p> | |
In terms of datetime maths, you could write: | |
<source> | |
partial + missing fields + time zone = instant | |
</source> | |
</p> | |
<subsection name="Date representations"> | |
<p> | |
Two classes represent a date in Joda-Time - <code>DateMidnight</code> and <code>LocalDate</code>. | |
These have different meanings. | |
<code>DateMidnight</code> is a fully specified instant, with a time zone. | |
It is defined as the milliseond instant at exactly mignight (00:00) at the start of a day. | |
<code>LocalDate</code> defines a day using the year, monthOfYear and dayOfMonth fields and no time zone. | |
It can be thought of as a local date that covers the whole of the day from 00:00 to 23:59. | |
</p> | |
</subsection> | |
</section> | |
<section name="Using Partials in Joda-Time"> | |
<p> | |
Within Joda-Time a partial is represented by the | |
<a href="apidocs/org/joda/time/ReadablePartial.html">ReadablePartial</a> interface. | |
There are six implementations of the interface provided: | |
<ul> | |
<li><a href="apidocs/org/joda/time/LocalDate.html">LocalDate</a> - | |
An immutable implementation that represents a date without a time or time zone.</li> | |
<li><a href="apidocs/org/joda/time/LocalTime.html">LocalTime</a> - | |
An immutable implementation that represents a time without a date or time zone.</li> | |
<li><a href="apidocs/org/joda/time/LocalDateTime.html">LocalDateTime</a> - | |
An immutable implementation that represents a datetime without a time zone.</li> | |
<li><a href="apidocs/org/joda/time/YearMonth.html">YearMonth</a> - | |
An immutable implementation that represents a year and month, useful for credit card expiry dates.</li> | |
<li><a href="apidocs/org/joda/time/MonthDay.html">MonthDay</a> - | |
An immutable implementation that represents a month and day, useful for birthdays without years.</li> | |
<li><a href="apidocs/org/joda/time/Partial.html">Partial</a> - | |
An immutable implementation that can store any combination of datetime fields. | |
For example, using this class you could create a YearMonth or DayOfWeekDayOfMonth partial.</li> | |
<li><a href="apidocs/org/joda/time/YearMonthDay.html">YearMonthDay</a> - | |
Effectively deprecated - only supports the year, monthOfYear and dayOfMonth fields.</li> | |
<li><a href="apidocs/org/joda/time/TimeOfDay.html">TimeOfDay</a> - | |
Effectively deprecated - only supports the hour, minute, second and millisecond fields.</li> | |
</ul> | |
</p> | |
<p> | |
The code can be used in various ways: | |
<source> | |
// setup objects | |
LocalDate date = new LocalDate(2004, 12, 25); | |
LocalTime time = new LocalTime(12, 20); | |
int year = date.getYear(); // returns 2004 | |
int hour = time.getHour(); // returns 12 | |
String monthStr = date.month().getAsText(); // returns 'December' | |
</source> | |
Conversion to and from instants is easy: | |
<source> | |
LocalDate date = new LocalDate(2004, 12, 25); | |
LocalTime time = new LocalTime(12, 20); | |
// merge, resulting in 2004-25-12T12:20 (default time zone) | |
DateTime dt = date.toDateTime(time); | |
// extract the date fields from someDT | |
DateTime someDT = ... | |
LocalDate date = new LocalDate(someDT); | |
</source> | |
</p> | |
<p> | |
Note that the interface <code>ReadablePartial</code> should not be used like the collections API. | |
The interface only contains the core subset of the operations. | |
Instead, you should refer directly to the implementation classes in your APIs. | |
</p> | |
<subsection name="Nulls"> | |
<p> | |
Joda-Time defines a null partial as the current time. | |
Thus, when a method is defined as taking a <code>ReadablePartial</code>, passing null in | |
will be the same as passing in a partial set to the current time. | |
</p> | |
</subsection> | |
</section> | |
</body> | |
</document> |