These are the release notes and advice for upgrading Joda-Time from version 1.2 to version 1.3.
Joda-Time version 1.3 --------------------- Joda-Time is a date and time handling library that seeks to replace the JDK Date and Calendar classes. This is the fourth full release of Joda-Time. This release focuses on new features, but also include some bug fixes. 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 ** Enhancements since 1.2 ---------------------- - LocalDate/LocalTime/LocalDateTime New classes representing date, time and datetime without a time zone. LocalDate is the recommended replacement for YearMonthDay. LocalTime is the recommended replacement for TimeOfDay. These classes are implemented more flexibly than YearMonthDay and TimeOfDay and thus solve the problem where you couldn't query or format fields such as dayOfWeek on a YearMonthDay or millisOfDay on a TimeOfDay. Neither YearMonthDay or TimeOfDay will be immediately deprecated as they are in widespread use. The API of the new classes has been kept as similar to YearMonthDay/TimeOfDay as possible to aid migration, so this should be a search and replace change. - DateTime/DateMidnight/YearMonthDay/TimeOfDay - toLocalXxx() Added methods that allow conversion to the new classes, for example: LocalDate date = today.toLocalDate(); - DateTime/DateMidnight/YearMonthDay/TimeOfDay - withXxx() Added methods that allow an individul field to be changed, for example: DateTime firstOfMonth = today.withDayOfMonth(1); These methods are the immutable equivalent of set methods. These are convenince methods for the methods on the property API. - DateTimeFormatter/DateTimeParserBucket If a parsed datetime is illegal due to field range or time zone offset transition, thrown exception includes text of datetime being parsed. - DateTimeFormat - patternForStyle() Added method to retrieve the format pattern for a given style and locale. - ISODateTimeFormat - localDateParser() - localTimeParser() - localDateOptionalTimeParser() - dateOptionalTimeParser() New formats for parsing a datetime/date/time without a time zone, and for parsing a date (mandatory) with an optional time Compatibility with 1.2 ---------------------- Binary compatible - Yes, except - PartialConverter interface has had two new methods added. This is an internal interface and thus it is unlikely that you have implementations that will break. If you did create your own implementation and extended AbstractConverter then your code will not break. Source compatible - Yes, except - PartialConverter interface, see above Serialization compatible - Yes Data compatible - Yes - DateTimeZone data updated to version 2006g Semantic compatible - Yes, except - YearMonthDay constructor no longer accepts time only strings - TimeOfDay constructor no longer accepts strings including a date Deprecations since 1.2 ---------------------- - Instant.toDateTimeISO - Instant.toMutableDateTimeISO These were identical to the methods without the ISO suffix Bug fixes since 1.2 ------------------- - YearMonthDay Constructing with String value no longer accepts a time only string - TimeOfDay Constructing with String value no longer accepts date fields Constructing with String now treats 'T' prefix as optional - DateTime/DateMidnight/MutableDateTime/AbstractInstant Conversion methods toDateTime, toDateTimeISO, toMutableDateTime, and toMutableDateTimeISO now preserve the time zone. Previously calling any of these four methods would convert the result to the default time zone. This was incorrect. The methods have been changed to preserve the time zone. The similarly named methods on Instant have not changed behaviour. - Interval.overlap/Interval.gap Previously these methods returned intervals in the default time zone Now, they return intervals in the time zone of the original interval - Interval/MutableInterval.overlaps(ReadableInterval) Previously, these methods did not handle null correctly Now, if the current millisecond instant is at the start of the interval the method returns false (as defined, even if its a little unexpected) - DateTimeFormatterBuilder.MatchingParser Previously didn't estimate parsed length correctly - YearMonthDay/TimeOfDay/Partial.Property Hashcode was not defined - FixedDateTimeZone Hashcode was not defined - ISO/Gregorian/Julian/Coptic/EthiopicChronology Fixed overflow when getting year field from instants at Long.MAX_VALUE and LONG.MIN_VALUE - DayOfYear field Better error messages