|
|
Java example source code file (key_partial.xml)
This example Java source code file (key_partial.xml) is included in the alvinalexander.com
"Java Source Code
Warehouse" project. The intent of this project is to help you "Learn
Java by Example" TM.
Learn more about this Java project at its project page.
The key_partial.xml Java example source code
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Java date and time API - Partial
<author>Stephen Colebourne
</properties>
<body>
<section name="Partial">
<p>
A <i>partial 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 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 and YearMonthDay - are now effectively deprecated.
The new implementations are <code>LocalDate, LocalTime and LocalDateTime.
</p>
<p>
It is not possible to directly interoperate between a partial and an <a href="key_instant.html">instant.
A partial does not fully specify a single point in the datetime continuum, but instead may match
multiple points. For example, a <code>LocalTime 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 to a DateTime 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 and LocalDate.
These have different meanings.
<code>DateMidnight 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 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 interface.
There are six implementations of the interface provided:
<ul>
<li>LocalDate -
An immutable implementation that represents a date without a time or time zone.</li>
<li>LocalTime -
An immutable implementation that represents a time without a date or time zone.</li>
<li>LocalDateTime -
An immutable implementation that represents a datetime without a time zone.</li>
<li>YearMonth -
An immutable implementation that represents a year and month, useful for credit card expiry dates.</li>
<li>MonthDay -
An immutable implementation that represents a month and day, useful for birthdays without years.</li>
<li>Partial -
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>YearMonthDay -
Effectively deprecated - only supports the year, monthOfYear and dayOfMonth fields.</li>
<li>TimeOfDay -
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 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, passing null in
will be the same as passing in a partial set to the current time.
</p>
</subsection>
</section>
</body>
</document>
Other Java examples (source code examples)
Here is a short list of links related to this Java key_partial.xml source code file:
|
The search page
Other Java source code examples at this package level
Click here to learn more about this project
