<?xml version="1.0" encoding="ISO-8859-1"?> | |
<document> | |
<properties> | |
<title>Java date and time API - Home</title> | |
<author>Stephen Colebourne</author> | |
<author>Al Major</author> | |
</properties> | |
<body> | |
<section name="Joda Time - Java date and time API"> | |
<p> | |
Joda-Time provides a quality replacement for the Java <em>date</em> | |
and <em>time</em> classes. The design allows for multiple <em>calendar</em> | |
systems, while still providing a simple API. | |
The 'default' calendar is the <a href="cal_iso.html">ISO8601</a> standard which | |
is used by XML. The Gregorian, Julian, Buddhist, Coptic, Ethiopic and Islamic systems | |
are also included, and we welcome further additions. Supporting classes include | |
time zone, duration, format and parsing. | |
</p> | |
<p> | |
As a flavour of Joda-Time, here's some example code: | |
<source> | |
public boolean isAfterPayDay(<a href="apidocs/org/joda/time/DateTime.html"><b>DateTime</b></a> datetime) { | |
if (datetime.getMonthOfYear() == 2) { // February is month 2!! | |
return datetime.getDayOfMonth() > 26; | |
} | |
return datetime.getDayOfMonth() > 28; | |
} | |
public <a href="apidocs/org/joda/time/Days.html"><b>Days</b></a> daysToNewYear(<a href="apidocs/org/joda/time/LocalDate.html"><b>LocalDate</b></a> fromDate) { | |
<a href="apidocs/org/joda/time/LocalDate.html"><b>LocalDate</b></a> newYear = fromDate.plusYears(1).withDayOfYear(1); | |
return <a href="apidocs/org/joda/time/Days.html"><b>Days</b></a>.daysBetween(fromDate, newYear); | |
} | |
public boolean isRentalOverdue(<a href="apidocs/org/joda/time/DateTime.html"><b>DateTime</b></a> datetimeRented) { | |
<a href="apidocs/org/joda/time/Period.html"><b>Period</b></a> rentalPeriod = new <a href="apidocs/org/joda/time/Period.html"><b>Period</b></a>().withDays(2).withHours(12); | |
return datetimeRented.plus(rentalPeriod).isBeforeNow(); | |
} | |
public String getBirthMonthText(<a href="apidocs/org/joda/time/LocalDate.html"><b>LocalDate</b></a> dateOfBirth) { | |
return dateOfBirth.monthOfYear().getAsText(Locale.ENGLISH); | |
} | |
</source> | |
<!-- | |
public boolean isDoubleShift(<a href="apidocs/org/joda/time/LocalTime.html"><b>LocalTime</b></a> startTime, <a href="apidocs/org/joda/time/LocalTime.html"><b>LocalTime</b></a> endTime) { | |
<a href="apidocs/org/joda/time/Hours.html"><b>Hours</b></a> hoursBetween = <a href="apidocs/org/joda/time/Hours.html"><b>Hours</b></a>.hoursBetween(time1, time2); | |
return hoursBetween.isGreaterThan(<a href="apidocs/org/joda/time/Hours.html"><b>Hours</b></a>.EIGHT); | |
} | |
public boolean isJoinedInLastThreeMonths(<a href="apidocs/org/joda/time/DateTime.html"><b>DateTime</b></a> datetimeJoined) { | |
<a href="apidocs/org/joda/time/Interval.html"><b>Interval</b></a> last3Months = new <a href="apidocs/org/joda/time/Interval.html"><b>Interval</b></a>(<a href="apidocs/org/joda/time/Months.html"><b>Months</b></a>.THREE, new <a href="apidocs/org/joda/time/DateTime.html"><b>DateTime</b></a>()); | |
return last3Months.contains(datetimeJoined); | |
} | |
--> | |
Version 2.3 was released on 2013-08-16 - | |
<a href="download.html">Download now</a> | |
</p> | |
</section> | |
<section name="Why Joda Time?"> | |
<p> | |
Joda-Time has been created to radically change date and time handling in Java. | |
The JDK classes Date and Calendar are very badly designed, have had numerous bugs | |
and have odd performance effects. | |
Here are some of our reasons for developing and using Joda-Time: | |
<ul> | |
<li><b>Easy to Use</b>. | |
Calendar makes accessing 'normal' dates difficult, due to the lack of simple methods. | |
Joda-Time has straightforward <a href="field.html">field accessors</a> such as | |
<code>getYear()</code> or <code>getDayOfWeek()</code>.</li> | |
<li><b>Easy to Extend</b>. | |
The JDK supports multiple calendar systems via subclasses of <code>Calendar</code>. | |
This is clunky, and in practice it is very difficult to write another calendar system. | |
Joda-Time supports multiple calendar systems via a pluggable system based on the | |
<code>Chronology</code> class.</li> | |
<li><b>Comprehensive Feature Set</b>. | |
The library is intended to provide all the functionality that is required for date-time | |
calculations. It already provides out-of-the-box features, such as support for oddball | |
date formats, which are difficult to replicate with the JDK.</li> | |
<li><b>Up-to-date Time Zone calculations</b>. | |
The <a href="timezones.html">time zone implementation</a> is based on | |
the public <a href="http://www.iana.org/time-zones">tz database</a>, which is | |
updated several times a year. New Joda-Time releases incorporate all changes | |
made to this database. Should the changes be needed earlier, | |
<a href="tz_update.html">manually updating the zone data</a> is easy.</li> | |
<li><b>Calendar support</b>. | |
The library currently provides 8 calendar systems. More will be added in the future.</li> | |
<li><b>Easy interoperability</b>. | |
The library internally uses a millisecond instant which is identical to the JDK and similar | |
to other common time representations. This makes interoperability easy, and Joda-Time comes | |
with out-of-the-box JDK interoperability.</li> | |
<li><b>Better Performance Characteristics</b>. | |
Calendar has strange performance characteristics as it recalculates fields at unexpected moments. | |
Joda-Time does only the minimal calculation for the field that is being accessed.</li> | |
<li><b>Good Test Coverage</b>. | |
Joda-Time has a comprehensive set of developer tests, providing assurance of the library's quality.</li> | |
<li><b>Complete Documentation</b>. | |
There is a full <a href="userguide.html">User Guide</a> which provides an overview and covers | |
common usage scenarios. The <a href="apidocs/index.html">javadoc</a> | |
is extremely detailed and covers the rest of the API.</li> | |
<li><b>Maturity</b>. | |
The library has been under active development since 2002. | |
Although it continues to be improved with the addition of new features and | |
bug-fixes, it is a mature and reliable code base. | |
A number of <a href="related.html">related projects</a> are now available.</li> | |
<li><b>Open Source</b>. | |
Joda-Time is licenced under the business friendly <a href="license.html">Apache License Version 2.0</a>.</li> | |
</ul> | |
</p> | |
</section> | |
<section name="Documentation"> | |
<p> | |
Various documentation is available: | |
<ul> | |
<li>Two user guides - <a href="quickstart.html">quick</a> and <a href="userguide.html">full</a></li> | |
<li>The key concepts and chronology documents in the left navigation area</li> | |
<li>The <a href="apidocs/index.html">Javadoc</a></li> | |
<li>Information on <a href="installation.html">downloading and installing</a> Joda-Time</li> | |
<li>The <a href="faq.html">FAQ</a> list</li> | |
<li>The <a href="https://github.com/JodaOrg/joda-time">GitHub</a> source repository</li> | |
</ul> | |
</p> | |
</section> | |
<section name="Releases"> | |
<p> | |
<a href="download.html">Release 2.3</a> | |
is the current latest release. | |
This release is an evolution of the 1.x codebase, not a major rewrite. | |
It is considered stable and worthy of the 2.x tag. | |
</p> | |
<p> | |
Version 2.3 is a bugfix release compatible with version 2.2. | |
See the <a href="upgradeto230.html">upgrade notes</a> for full details. | |
</p> | |
<p> | |
Version 2.x is almost completely source and binary compatible with version 1.x. | |
Key changes include the use of JDK 1.5 or later, generics, and the removal of some (but not all) | |
deprecated methods. See the <a href="upgradeto200.html">upgrade notes</a> for full details | |
including information on the corner cases that are not compatible. | |
</p> | |
<p> | |
We will support the 2.x product line using standard Java mechanisms. | |
The main public API will remain backwards compatible for both source and binary in the 2.x stream. | |
The version number will change to 3.0 to indicate a significant change in compatibility. | |
</p> | |
<p> | |
Available in <a href="http://search.maven.org/#artifactdetails|joda-time|joda-time|2.3|jar">Maven Central</a>. | |
</p> | |
<p> | |
<a href="https://sourceforge.net/projects/joda-time/files/joda-time/1.6.2/">Release 1.6.2</a> | |
is the last v1.x release. | |
It is compatible with JDK 1.4. | |
Given that v2.x is essentially compatible with v1.6.2, there are no current plans for further | |
releases in the v1.x product line. | |
</p> | |
</section> | |
<section name="Support"> | |
<p> | |
Support on bugs, library usage or enhancement requests is available on a best efforts basis. | |
</p> | |
<p> | |
To suggest enhancements or contribute, please <a href="https://github.com/JodaOrg/joda-time">fork the source code</a> on GitHub. | |
Alternatively, use GitHub <a href="https://github.com/JodaOrg/joda-time/issues">issues</a>. | |
</p> | |
<p> | |
The older mechanisms of the joda-interest <a href="mail-lists.html">mailing list</a> | |
and the joda-time <a href="http://sourceforge.net/projects/joda-time/forums/forum/337835">forums</a> | |
do still exist, but are deprecated. | |
</p> | |
<p> | |
<br /> | |
</p> | |
<p> | |
<br /> | |
</p> | |
<p> | |
<br /> | |
</p> | |
</section> | |
</body> | |
</document> |