| <?xml version="1.0" encoding="ISO-8859-1"?> | |
| <document> | |
| <properties> | |
| <title>Java date and time API - Upgrade from 1.2 to 1.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 1.2 to version 1.3. | |
| <source> | |
| 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 | |
| </source> | |
| </p> | |
| </section> | |
| </body> | |
| </document> |