<?xml version="1.0" encoding="ISO-8859-1"?>

<document>
 <properties>
  <title>Java date and time API - Upgrade from 1.0 to 1.1</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.0 to version 1.1.
<source>
Joda-Time version 1.1
---------------------

Joda-Time is a date and time handling library that seeks to replace the JDK
Date and Calendar classes.

This is the second full release of Joda-Time.

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 cause you problems please contact the mailing list.


Incompatible changes since 1.0
------------------------------
Binary compatible - Yes
  - v1.0 and v1.1 are binary compatible in their public and protected API

Source compatible - Yes
  - v1.0 and v1.1 are source compatible in their public and protected API

Serialization compatible - Yes, except:
  - DateTime.Property, DateMidnight.Property and MutableDateTime.Property
   serialization formats have changed to fix a bug.
    Please note that this only affects the property classes, and not DateTime,
   DateMidnight or MutableDateTime themselves
    It is unlikely that you serialized one of these classes

Data compatible - Yes, except:
  - Removed time zones Asia/Riyadh87, Asia/Riyadh88 and Asia/Riyadh89.
   These should not have been included in the 1.0 release, and do not represent
   genuine time zones. It is unlikely that you used them.
   If you do want to use them, please contact the joda-interest mailing list


Warnings since 1.0
------------------
ReadablePartial now has a comment recommending that all implementations
should also implement Comparable.
This is most easily achieved by extending AbstractPartial.


Deprecations since 1.0
----------------------
None


Bug fixes since 1.0
-------------------
- Date and Time (ZoneInfoCompiler)
  Greek summer time was incorrect due to a comment parsing bug.
  This disabled DST (summer time) for Europe/Athens after 1980.

- DateTimeFormat
  Parsing of two digit year by DateTimeFormat supports parsing of more or less
  than two digits, for compatibility with java.text.SimpleDateFormat. If not
  two digits or if sign character is present, then year is parsed as absolute.

- GJChronology
  Range duration field of dayOfMonth was not consistent with monthOfYear. This
  bug manifested itself when adding/subtracting periods to partials.

- DateTimeParserBucket
  Fixed parsing date where format includes era. Era must be set and rounded
  before any other fields.

- PeriodFormatterBuilder
  Formatters that had fields which required a zero to be printed were not being
  parsed.

- DateTime.Property, DateMidnight.Property and MutableDateTime.Property
  Could previously only be serialized in UTC.
  The serialization format has been changed to be simpler and more reliable.
  Unfortunately, this was an incompatible change to the serialization format.

- DateTimeFormatterBuilder/PeriodFormatterBuilder
  Number parser would accept multiple sign characters as valid.

- YearMonthDay/TimeOfDay.withChronologyRetainFields
  Previously, switching chronology did not validate the fields, so you could
  end up with an object in an invalid state, such as a YearMonthDay where
  dayOfMonth=31 with Coptic.
  This method can now throw an IllegalArgumentException

- Chronologies
  Overflowed calculations involving year throw ArithmeticException rather than
  produce a bogus result.

- DateTimeFormatterBuilder.canBuildFormatter()
  Previously this method always returned false.


Enhancements since 1.0
----------------------
- Partial
  New immutable implementation of ReadablePartial.
  This implementation is flexible as to the fields that it stores.
  Thus, if you want a partial holding just a year and monthOfYear (perhaps
  for a credit card expiry date), then this class can be used.
  Full support for almost all truncated and reduced precision ISO output
  formats is available via use of this class.

- DateTime/DateMidnight/MutableDateTime/YearMonthDay/TimeOfDay
  Added convenience plusXxx() and minusXxx() methods to add/subtract a period
  For example, dt.plus(Period.days(6)) can now be replaced by dt.plusDays(6)

- DateTime/DateMidnight/MutableDateTime/YearMonthDay/TimeOfDay
  Added convenience toString() method that takes a DateTimeFormatter
  For example, dt.toString(DateTimeFormat.shortDateTime())

- YearMonthDay/TimeOfDay/AbstractPartial
  Enabled comparisons using Comparable interface
  Added compareTo/isEqual/isAfter/isBefore methods
  These methods were added to AbstractPartial, and are thus available to
  all implementations of ReadablePartial

- YearMonthDay/TimeOfDay
  Extra time zone constructor
  Allows current date and time to be accurately obtained

- DateTime/DateMidnight/MutableDateTime/YearMonthDay/TimeOfDay Property
  Added new method to property class - getAsString()
  Gets the value as a string, not using text values like 'Monday' or 'January'

- Period
  Added constructors to create a Period from two ReadablePartials, such as
  YearMonthDay or TimeOfDay

- Period
  Added factory to create a Period from two ReadablePartials using an
  alternative, field-based, calculation

- DateTimeUtils
  Added isContiguous(ReadablePartial) to test if a partial is contiguous
  (see the method for the definition)

- PeriodType
  Added factory method forFields() to allow a PeriodType to be obtained
  from any set of DurationFieldType objects

- PeriodType
  Added three new period types - YearMonthDay, YearWeekDay and YearDay
  These complement the existing ones but exclude the time fields.

- DateTimeFormatter
  Method withPivotYear added to allow the two digit pivot year to be controlled.
  This is most useful after creating a format from a string pattern.

- DateTimeFormatter
  Added lenient parse option to appendTwoDigitYear and appendTwoDigitWeekyear.

- Interval
  Added overlap method that returns the actual overlap between two intervals.
  Added gap method that returns the gap between two intervals.
  Added abuts method that returns true if two intervals abut.

- DateTimeUtils
  Added getReadableInterval(ReadableInterval) method to handle null intervals

- IllegalFieldValueException
  Added new exception subclass of IllegalArgumentException to capture more
  context when a field is set to an illegal value. This can be helpful in
  interactive applications.

- GJLocaleSymbols
  Supports parsing "CE" and "BCE" as era if locale language is English.

- ISODateTimeFormat
  New method, forFields(), which gets an ISO format for a set of fields.
  This is useful for more unusual formats such as DayHour.

- ISODateTimeFormat
  New methods to output ordinal style dates, such as 2005-161.

- DateTimeZone classes updated to latest data from the Olson time zone database
</source>
</p>
</section>

</body>
</document>