These are the release notes and advice for upgrading Joda-Time from version 1.4 to version 1.5.
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 * * https://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  - 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  - DateTimeZone names were incorrect when abbreviation is the same in winter and summer, notably in Australia  - Avoid compilation issue reported by Apache Harmony  - 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  - 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.  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.