<?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> |