<?xml version="1.0" encoding="ISO-8859-1"?>

<document>
 <properties>
  <title>Java date and time API - Upgrade from 1.1 to 1.2</title>
  <author>Stephen Colebourne</author>
 </properties>

<body>

<section name="Upgrade">
<p>
These are the release notes and advice for upgrading Joda-Time from
version 1.1 to version 1.2.
<source>
Joda-Time version 1.2
---------------------

Joda-Time is a date and time handling library that seeks to replace the JDK
Date and Calendar classes.

This is the third full release of Joda-Time.
This release focuses on bug fixes, with a few new features.

We recommend JDK 1.3 or later, and have performed no testing on earlier JDKs.

Joda-Time is licensed under the business-friendly Apache License Version 2.
This is the same license as all of Apache, plus other open source projects such as Spring.
The intent is to make the code available to the Java community with the minimum
of restrictions. If the license causes you problems please contact the mailing list.

** Please also check out the JSP and Hibernate contributed projects **


Incompatible changes since 1.1
------------------------------
Binary compatible - Yes, except
  - The internal classes BaseGJChronology and CommonGJChronology have been removed
    They were implementation classes and you should not have been using them
    Please contact the mailing list if this causes you problems

Source compatible - Yes
  - v1.1 and v1.2 are source compatible in their public and protected API

Serialization compatible - Yes
  - Chronology serialization has changed, however the two formats are compatible
  - v1.1 did not serialize the Chronology minimum days in first week field properly, v1.2 does

Data compatible - Yes
  - DateTimeZone data updated to version 2005q


Deprecations since 1.1
----------------------
- Chronology factory methods, such as getISO() and getCopticUTC()
  You should now use the chrono package directly:
    Chronology.getCoptic(zone)   is replaced by
    CopticChronology.getInstance(zone)
  These factory methods have been removed as they were unable to scale
  suitably as more and more chronologies are added


Bug fixes since 1.1
-------------------
- ZonedChronology
  getMaximumValue(ReadablePartial)/getMinimumValue(ReadablePartial)
  Methods returned incorrect result

- ZonedChronology
  Better detection and handling of offset calculation overflow, throwing
  an ArithmeticException.

- DateTimeZone
  Handles offset calculation overflow errors for instants near Long.MAX_VALUE,
  ending the offset transition sequence.

- DateTimeFormatter
  Reverts to UTC if time zone offset calculation causes overflow. This allows at least
  the time of day fields to be printed for instants near Long.MIN_VALUE or Long.MAX_VALUE.

- CopticChronology
  Fixed regression in month of year calculation which affected getMaximumValue
  on dayOfMonth field.

- CopticChronology
  Fixed month duration field to handle short 13th month correctly.

- ZonedChronology
  Fixed getting text values for fields from getAs[Short]Text(int value, Locale locale).

- Gregorian, Julian, GJ and Coptic
  These Chronology classes did not correctly store the minimum days in first week
  during serialization

- DateTimeFormatter
  Fixed printing of time zone name near DST transition

- YearMonthDay
  Fixed addition where date starts on a leap day
  Fixed addition in the GJChronology

- DateTimeFormat
  Pattern letter 'K' was using the wrong underlying implementation


Enhancements since 1.1
----------------------
- IslamicChronology
- EthiopicChronology
  New Chronologies

- DateTime.Property.withMaximumValue() (also DateMidnight/YearMonthDay etc)
- DateTime.Property.withMinimumValue()
  Returns a copy of the base datetime with the specified field set to
  the maximum or minimum value. This is useful to get the last day of the month.
  - DateTime lastDayOfMonth = dt.dayOfMonth().withMaximumValue();

- DateTime.Property.toInterval() (also DateMidnight/MutableDateTime)
  New method to convert return an Interval object over the span of the property
  Thus dt.monthOfYear().toInterval() returns an interval from the start to
  the end of the month

- MutableDateTime.property(DateTimeFieldType)
  Gets the property by type. Complements the method already on DateTime/DateMidnight.

- YearMonthDay.fromCalendarFields()
- YearMonthDay.fromDateFields()
- TimeOfDay.fromCalendarFields()
- TimeOfDay.fromDateFields()
  New factory methods to create a YearMonthDay/TimeOfDay using exactly the same
  field values as the JDK objects, thus ignoring time zone effects

- FieldUtils
  Performance optimization when adding by scalars of one or negative one. The
  overflow detecting multiplication skips the multiply and divide check for
  these values.
</source>
</p>
</section>

</body>
</document>