<?xml version="1.0" encoding="ISO-8859-1"?>

<document>
 <properties>
  <title>Java date and time API - Upgrade from 2.2 to 2.3</title>
  <author>Stephen Colebourne</author>
 </properties>

<body>

<section name="Upgrade">
<p>
These are the release notes and advice for upgrading Joda-Time from version 2.2 to version 2.3.
<source>
Joda-Time version 2.3
---------------------

Joda-Time is a date and time handling library that seeks to replace the JDK
Date and Calendar classes.

This release contains enhancements, bug fixes and a time zone update.
The release runs on JDK 5 or later.

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 2.2
----------------------
- Interval/MutableInterval .isEqual() [#20]
  Add method to compare intervals ignoring the chronology
  https://github.com/JodaOrg/joda-time/issues/20

- Chronology classes now define equals methods [#36]
  Previously, the Chronology classes relied on caching in factory methods
  to guarantee instances were singletons
  Now, there are dedicated, normal, equals methods
  This will aid weird cases where deserialization or similar avoids the caches
  It will make no difference to most users

- Maximum size for pattern cache [#49]
  Sets a maximum size for the cache to avoid memory issues

- Add LocalDateTime.toDate(TimeZone) [#48]
  Provides an alternate way to create a java.util.Date that avoids some synchronization

- Home page moved
  http://www.joda.org/joda-time


Compatibility with 2.2
----------------------
Build system - Yes

Binary compatible - Yes

Source compatible - Yes

Serialization compatible - Yes

Data compatible - Yes, except
 - DateTimeZone data updated to version 2013d

Semantic compatible - Yes, except
 - DateTimeZone is now limited to offsets from -23:59:59.999 to +23:59:59.999

 - BasicChronology now defines an equals method
   This which would affect you if you subclassed it (unlikely)

 - GJChronology now has a minimum cutover instant of 0001-01-01 (Gregorian)
   Its unlikely you have it set earlier than this
   If you did your code was broken anyway


Deprecations since 2.2
----------------------
- DateMidnight [#41]
  This class is flawed in concept
  The time of midnight occasionally does not occur in some time-zones
  This is a result of a daylight savings time from 00:00 to 01:00
  DateMidnight is essentially a DateTime with a time locked to midnight
  Such a concept is more generally a poor one to use, given LocalDate
  Replace DateMidnight with LocalDate
  Or replace it with DateTime, perhaps using the withTimeAtStartOfDay() method


Bug fixes since 2.2
-------------------
- ZoneInfoCompiler and DateTimeZoneBuilder multi-threading [#18]
  A thread local variable was previously only initialised in one thread causing NPE
  https://github.com/JodaOrg/joda-time/issues/18

- Short time-zone name parsing failed to match the longest name
  This affected two short names where one is a short form of the second such as "UT" and "UTC"

- Days.daysBetween fails for MonthDay [#22]
  Incorrect calculation around leap years

- DateTimeZone failed to validate offsets [#43]
  Previously, there was little validation, resulting in the ability to create large offsets
  Those offsets could fail in other parts of the library
  Now, it is limited to -23:59:59.999 to +23:59:59.999

- DateTimeZone.forOffsetHoursMinutes failed to allow offsets from -00:01 to -00:59 [#42]
  The forOffsetHoursMinutes() method could not create an offset  from -00:01 to -00:59
  This was due to an inappropriate design
  A backwards compatible change to the input handling has been made
  forOffsetHoursMinutes(0, -15) now creates -00:15

- DateTimeFormatter.parseInto [#21]
  Fix parseInto() where it obtains the default year for parsing from the ReadWritableInstant
  Previously, the wrong year could be obtained at the start or end of the year in non UTC zones
  Now obtains the year from the ReadWritableInstant using the chronology of the ReadWritableInstant

- Better thread-safety in ISODateTimeFormat [#45]

- Fix GJChronology.plus/minus across cutover and year zero [#28]
  When subtracting a number of years from a date in the GJChronology there are two considerations
  The cutover date might be crossed, and year zero might be crossed (there is no year zero in GJ)
  Previously, each were handled separately, but not together. Now it is fixed
  As part of this change, the minimum cutover instant was set to 0001-01-01 (Gregorian)


Scala
--------
Joda-Time uses annotations from Joda-Convert.
In the Java programming language, this dependency is optional, however in Scala it is not.
Scala users must manually add the Joda-Convert v1.2 dependency.
</source>
</p>
</section>

</body>
</document>