<?xml version="1.0" encoding="ISO-8859-1"?>

<document>
 <properties>
  <title>Java date and time API - Upgrade from 1.4 to 1.5</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.4 to version 1.5.
<source>
Joda-Time version 1.5
---------------------

Joda-Time is a date and time handling library that seeks to replace the JDK
Date and Calendar classes.

This is the sixth full release of Joda-Time.
This release focuses on new features, but also include some bug fixes.

We recommend JDK 1.4 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 our related projects   *
* http://www.joda.org/joda-time/related.html *


Enhancements since 1.4
----------------------
- LocalDate
  - add toDateTimeAtStartOfDay(), toDateTimeAtStartOfDay(DateTimeZone)
  methods to replace toDateTimeAtMidnight() which avoid issues with time zones
  that do not have midnight at spring DST cutover

- LocalDate
  - add toLocalDateTime()
    provide mechanism to create LocalDateTime from LocalDate and LocalTime

- Performance enhancement for LocalDate, LocalTime and LocalDateTime
  - equals, compareTo, Period construction

- Partial
  - add isMatch(ReadablePartial)
    provide mechanism to match a Partial, such as 'Friday the Thirteenth' to
    another partial, such as a LocalDate

- Period
  - add toStandardDuration()
  - add toStandardWeeks(), toStandardDays(), toStandardHours(),
    toStandardMinutes(), toStandardSeconds()
  methods to convert a period to other types using the standard
  conversions (7 day week, 24 hour day, ...)

- Period
  - add plus(ReadablePeriod), minus(ReadablePeriod)
  methods to add and subtract whole periods rather than just single fields

- Period
  - add normalizedStandard(), normalizedStandard(PeriodType)
  methods to normalize the period back to standard field ranges, such as
  normalizing 1 year 15 months to 2 years 3 months

- Period.toString(PeriodFormatter), MutablePeriod.toString(PeriodFormatter)
  - allow periods to be directly formatted, as with datetimes

- DateTimeZone
  - add isStandardOffset()
  assists in determining if DST applies

- Interval
  - add (long,long,DateTimeZone) constructor
  constructor emphasises that intervals include a time zone

- DateTimeFormatterBuilder
  - add appendFixedDecimal(DateTimeFieldType,int),
        appendFixedSignedDecimal(DateTimeFieldType,int)
  methods for printing and parsing fields which must have a fixed number of digits


Compatibility with 1.4
----------------------
Binary compatible - Yes, except
  - Internal class LenientDateTimeField has an incompatible change to
    getInstance() and the constructor
  - Internal class DateTimeZoneBuilder has an incompatible change to
    toDateTime() and writeTo()

Source compatible - Yes, except
  - Internal class LenientDateTimeField has an incompatible change to
    getInstance() and the constructor
  - Internal class DateTimeZoneBuilder has an incompatible change to
    toDateTime() and writeTo()

Serialization compatible - Yes

Data compatible - Yes, except
  - Format of time zone data files changed slightly to fix bug
    This mainly affects Australia
  - DateTimeZone data updated to version 2007h

Semantic compatible - Yes


Deprecations since 1.4
----------------------
- YearMonthDay
  - use LocalDate
- TimeOfDay
  - use LocalTime
  - LocalDate and LocalTime have a much better internal implementation and have
    been available since v1.3. Both have been effectively deprecated in the javadoc
    for over a year to enable a gentle transition. In this release, they are now
    formally deprecated, however they won't be removed until a v2.0 which won't
    occur until 2009 at the earliest.

- LocalDate.toDateTimeAtMidnight()
  LocalDate.toDateTimeAtMidnight(DateTimeZone)
  - use toDateTimeAtStartOfDay() instead because it avoids exceptions


Bug fixes since 1.4
-------------------
- Daylight savings cutover in Spring incorrect
  A problem with DST cutover in Spring meant that the result of many
  methods would be different depending on whether the time zone was in the
  Eastern or Western hemisphere. Now, the DST cutover is consistent, such
  that if a time is requested within the cutover, it will be pushed forwards
  into summer time. [1710316, 1747219, 1755158]

- LenientChronology and time zones
  LenientChronology could throw exceptions when the time being created
  didn't exist dies to the time zone [1755161]

- LocalDate/LocalTime constructors did not set internal state correctly
  This problem was exposed when Days.daysBetween() and similar methods
  failed to give the right results

- Period.plusXxx(), minusXxx(), withXxx()
  Fix to throw correct exception as per javadoc (UnsupportedOperationException) when
  changing an unsupported field

- ZoneInfoProvider now returns a copy of its internal state on getAvailableIDs
  This avoids race conditions on some JVMs

- Period formating threw NegativeArraySizeException during formatting
  This happened for certain period values, notably zero

- Period formatting could end up in an infinite loop on IBM JDK 1.4.2
  This appears to be an IBM JDK issue, not a Joda-Time issue, but we should
  not have ended up in an infinite loop whatever happens

- DateTimeZone did not properly convert fixed offset zones to java.util.TimeZone [1682152]

- DateTimeZone names were incorrect when abbreviation is the same in winter
  and summer, notably in Australia [1716305]

- Avoid compilation issue reported by Apache Harmony [1699760]

- LenientChronology might incorrectly adjust a valid hour field near DST transition

- DateTimeFormat javadoc now explains time zone parsing restriction better [OpenDiscussion 1721909]

- Period javadoc now explains toDurationFrom() and toDurationTo() better

- DateTime/Instant/LocalDateTime javadoc improved

- DateTimeZone
  Clarify javadoc of forTimeZone to indicate that application created
  SimpleTimeZone rules are not parsed [1705180]

- Defect in localized Gregorian/Julian symbol cache severely impacted formatting
  performance when using null (default) locale.

- DateTimeFormatter specified with locale of null could produce mismatched
  symbols if default locale changed concurrently.

- DateTime parsing of text failed when the text for the locale contained characters
  other than letters. [1788282]
  For French, the short text for months ends with '.'.
  For Korean, the text for months contains a number.
  The parser was also too greedy, and would absorb all letters it found, preventing
  parsing a format such as '23JunSat' (month followed by day of week, or any other text).
  The parser has been rewritten to only match the text that can be produced by the
  formatter.
</source>
</p>
</section>

</body>
</document>