|
|
Java example source code file (key_period.xml)
This example Java source code file (key_period.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_period.xml Java example source code
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Java date and time API - Period
<author>Stephen Colebourne
</properties>
<body>
<section name="Period">
<p>
A <i>period in Joda-Time represents a period of time defined in terms of fields,
for example, 3 years 5 months 2 days and 7 hours.
This differs from a <a href="key_duration.html">duration in that it is inexact in terms of milliseconds.
A period can only be resolved to an exact number of milliseconds by specifying the
<a href="key_instant.html">instant (including chronology and time zone) it is relative to.
</p>
<p>
Periods do not have a <a href="key_chronology.html">chronology or time zone.
They can be added to an <a href="key_instant.html">instant, or to either
end of an interval to change those objects.
In datetime maths you could say:
<source>
instant + period = instant
</source>
</p>
<p>
For example, consider a period of 1 month.
If you add this period to the 1st February (ISO) then you will get the 1st March.
If you add the same period to the 1st March you will get the 1st April.
But the duration added (in milliseconds) in these two cases is very different.
</p>
<p>
As a second example, consider adding 1 day at the daylight savings boundary.
If you use a period to do the addition then either 23 or 25 hours will be added as appropriate.
If you had created a duration equal to 24 hours, then you would end up with the wrong result.
</p>
<p>
The Joda-Time library defines two types of implementation of the period concept.
The first type can only store a single-field, such as days or hours, but not both.
The second type can store any-field, expressing a value such as 5 months 8 days and 7 hours.
</p>
<subsection name="Single field Periods">
<p>
The first type, single-field periods, is new to version 1.4 of Joda-Time.
These classes - <code>Years, Months, Weeks,
<code>Days, Hours, Minutes, Seconds -
all follow a very similar design, and only store the single field as implied by
their name. Thus a <code>Days object can only store a number of days.
</p>
<p>
These classes can be useful when you want to write an API that must specifically take
in a period measured in a particular unit. For example, a travel website where you are
given the option of travelling ±1 days or ±3 days could store this
information in a <code>Days object.
</p>
<p>
These classes provide static factory methods rather than constructors.
For <code>Days these include daysBetween(startDate, endDate) to
obtain the number of whole days between two dates or datetimes, and
<code>daysIn(interval) to obtain the number of whole days in an interval.
In addition, there are a range of constants, such as <code>Days.ZERO and
<code>Days.ONE. The factory method days(int) either returns
a constant, or creates a new instance as appropriate.
</p>
<p>
The single-field classes include basic mathemaical operator support.
For <code>Days this includes plus(int), plus(Days),
<code>multipliedBy(int), dividedBy(int) and negated().
All operations return a new instance, as <code>Days is immutable.
The single-field classes are also comparable.
</p>
<p>
Converting between different types of period is a difficult problem.
One day is not always equal to 24 hours. (It might be 23 or 25 at daylight savings time change.)
However, many applications have business rules that assume a 24 hour day and so on.
To support this, <code>Days has methods named toStandardHours() and
so on which convert the number of days to a number of hours assuming a 24 hour day.
The word 'standard' is being specifically used in the method name to remind users of the assumption.
</p>
</subsection>
<subsection name="Any field Periods">
<p>
The second type of period is the any-field period.
These are implemented by the <code>Period and MutablePeriod classes.
Internally, they store a set of <code>int fields, one for each field.
The standard set of fields in a period are years, months, weeks, days, hours, minutes, seconds and millis.
The <a href="apidocs/org/joda/time/PeriodType.html">PeriodType class allows this set
of fields to be restricted, for example to elimate weeks.
This is significant when converting a duration or interval to a period, as the calculation
needs to know which period fields it should populate.
</p>
<p>
The <code>Period class is useful when you want to write an API that can take
a period that probably contains more than one field. However, to be even more general,
your API could define itself to accept a <code>ReadablePeriod, and then the
calling code could pass in either a <code>Period or a single field period like
<code>Days.
</p>
<p>
Methods exist on <code>Period to obtain each field value.
There are also methods to change a field value, such as <code>withDays(int).
They are named 'with' as they return a new <code>Period object, due to immutability.
</p>
<p>
You cannot compare any-field periods for order, as there is no sensible comparison strategy.
Instead, you need to convert the period to a <code>Duration based on a specific date
and then compare the duration.
</p>
</subsection>
</section>
<section name="Using Periods in Joda-Time">
<p>
Within Joda-Time a period is represented by the
<a href="apidocs/org/joda/time/ReadablePeriod.html">ReadablePeriod interface.
There are nine implementations of the interface provided:
<ul>
<li>Period -
An immutable implementation</li>
<li>MutablePeriod -
A mutable implementation</li>
<li>Years -
An immutable years-only implementation</li>
<li>Months -
An immutable months-only implementation</li>
<li>Weeks -
An immutable weeks-only implementation</li>
<li>Days -
An immutable days-only implementation</li>
<li>Hours -
An immutable hours-only implementation</li>
<li>Minutes -
An immutable minutes-only implementation</li>
<li>Seconds -
An immutable seconds-only implementation</li>
</ul>
We recommend the immutable implementation for general usage.
</p>
<p>
The code can be used in various ways:
<source>
DateTime start = new DateTime(2004, 12, 25, 0, 0, 0, 0);
DateTime end = new DateTime(2006, 1, 1, 0, 0, 0, 0);
// period of 1 year and 7 days
Period period = new Period(start, end);
// calc will equal end
DateTime calc = start.plus(period);
// able to calculate whole days between two dates easily
Days days = Days.daysBetween(start, end);
// able to calculate whole months between two dates easily
Months months = Months.monthsBetween(start, end);
</source>
</p>
<p>
Note that the interface <code>ReadablePeriod should not be used like the collections API.
The interface only contains the core subset of the operations.
Instead, you should usually refer directly to the implementation classes in your APIs.
</p>
<subsection name="Nulls">
<p>
Joda-Time defines a null period as a zero length period.
Thus, when a method is defined as taking a <code>ReadablePeriod, passing null in
will be the same as passing in a zero length period.
</p>
</subsection>
</section>
</body>
</document>
Other Java examples (source code examples)
Here is a short list of links related to this Java key_period.xml source code file:
|
The search page
Other Java source code examples at this package level
Click here to learn more about this project
