<?xml version="1.0" encoding="ISO-8859-1"?> | |
<document> | |
<properties> | |
<title>Java date and time API - Upgrade from 0.98 to 0.99</title> | |
<author>Stephen Colebourne</author> | |
</properties> | |
<body> | |
<section name="Upgrade"> | |
<p> | |
These are the release notes and advice for upgrading Joda-Time from | |
version 0.98 to version 0.99. | |
<source> | |
Joda-Time version 0.99 | |
---------------------- | |
Joda-Time is a date and time handling library that seeks to replace the JDK | |
Date and Calendar classes. | |
This is the last pre-beta release of Joda-Time. | |
We now recommend JDK 1.3 or later, and have performed no testing on earlier JDKs. | |
****************************************** | |
* The license of Joda-Time has changed * | |
* * | |
* Previous license: BSD-style * | |
* New license: Apache License v2 * | |
****************************************** | |
This change should have no impact on users of the code, as the licenses both have the | |
same intent - that is to make the code freely available with a minimum of restrictions. | |
Incompatible changes since 0.98 | |
------------------------------- | |
Please contact the joda-interest mailing list if you have difficulties upgrading | |
This release is both source and binary incompatible with 0.98 | |
- Formatting package reworked | |
This mainly affects those doing low level formatting work. | |
A deprecated interface has been added for 0.99 for some methods. | |
DateTimeFormatter/PeriodFormatter changed from interface to class. | |
These classes are now the main formatting API. | |
You still create them via the same factory classes, such as DateTimeFormat. | |
Most methods, and all functionality, have been retained, but some are deprecated (see below). | |
DateTimePrinter/DateTimeParser/PeriodPrinter/PeriodParser are now internal classes. | |
Applications will use DateTimeFormatter/PeriodFormatter. | |
Any references to DateTimePrinter/DateTimeParser/PeriodPrinter/PeriodParser in | |
your application should be changed to DateTimeFormatter/PeriodFormatter. | |
(Unless you are implementing your own printer/parser) | |
DateTimeFormatterBuilder usage changes | |
DateTimeFormatterBuilder.toPrinter() --> DateTimeFormatterBuilder.toFormatter() | |
DateTimeFormatterBuilder.toParser() --> DateTimeFormatterBuilder.toFormatter() | |
The isPrinter() and isParser() methods on DateTimeFormatter tell you about the status of the formatter. | |
Make similar changes for PeriodFormatterBuilder. | |
Format factory classes now define static methods | |
DateTimeFormat.getInstance().xxx() --> DateTimeFormat.xxx() | |
DateTimeFormat.getInstance(locale).xxx() --> DateTimeFormat.xxx().withLocale() | |
and so on for ISODateFormat, PeriodFormat and ISOPeriodFormat | |
DateTimeFormat.appendPatternTo(formatter, pattern) --> f.appendPattern(pattern) | |
DateTimeFormat.getPatternForStyle --> Removed, please contact mailing list | |
BaseDateTimeFormatter/BasePeriodFormatter | |
Classes removed, behaviour moved into DateTimeFormatter/PeriodFormatter | |
- DateTimeFormat pattern change | |
The time zone pattern 'ZZZZ' previously output a time zone offset like '+08:00'. | |
Now you need a pattern of 'ZZ' to output the offset. | |
The pattern 'ZZZZ' will now output the time zone id, such as 'Europe/London'. | |
- ReadablePartial | |
- removed methods toDateTime(), toDateTime(DateTimeZone zone), as their meaning was confused. | |
Implementations on YearMonthDay/TimeOfDay are deprecated. | |
- DateTime/DateMidnight/MutableDateTime | |
- removed getReadableInstant() from the property classes | |
On DateTime.Property, use getDateTime(). | |
On DateMidnight.Property, use getDateMidnight(). | |
On MutableDateTime.Property, use getMutableDateTime(). | |
- ReadableInstant | |
- added method isSupported(DateTimeFieldType field) | |
Implemented in DateTime/DateMidnight/MutableDateTime | |
- YearMonthDay/TimeOfDay | |
- removed getReadablePartial() from the property classes | |
On YearMonthDay.Property, use getYearMonthDay(). | |
On TimeOfDay.Property, use getTimeOfDay(). | |
- TimeOfDay | |
- semantic change to TimeOfDay.Property.addToCopy() | |
Previously, add threw an exception if the 23:59/00:00 boundary was broken. | |
Now it wraps to the next 'day', as this is the more typical use case. | |
Change to the method TimeOfDay.Property.addNoWrapToCopy() to restore the old behaviour. | |
Deprecations since 0.98 | |
----------------------- | |
** ALL deprecated methods will be removed in 1.0 ** | |
Please contact the joda-interest mailing list if you have difficulties upgrading | |
- Formatting package reworked | |
Factory classes now no longer have a static getInstance() method. | |
DateTimeFormat.getInstance().xxx() --> DateTimeFormat.xxx() | |
ISODateTimeFormat.getInstance().xxx() --> ISODateTimeFormat.xxx() | |
PeriodFormat.getInstance().xxx() --> PeriodFormat.xxx() | |
PeriodFormat.getInstance(locale).xxx() --> PeriodFormat.xxx().withLocale() | |
ISOPeriodFormat.getInstance().xxx() --> ISOPeriodFormat.xxx() | |
Some DateTimeFormatter methods deprecated. | |
f.print(millis, DateTimeZone) --> f.withZone(zone).print(millis) | |
f.print(millis, Chronology) --> f.withChronology(chrono).print(millis) | |
f.parseMillis(str, Chronology) --> f.withChronology(chrono).parseMillis(str) | |
f.parseDateTime(str, Chronology) --> f.withChronology(chrono).parseDateTime(str) | |
f.parseMutableDateTime(str, Chronology) --> f.withChronology(chrono).parseMutableDateTime(str) | |
Some PeriodFormatter methods deprecated. | |
f.parsePeriod(type, str) --> f.withType(type).parsePeriod(str) | |
f.parseMutablePeriod(type, str) --> f.withType(type).parseMutablePeriod(str) | |
- DateTimeZone - factory methods changed: | |
getInstance() -> forID/forOffsetHours/forOffsetHoursMinutes/forTimeZone | |
Aim to clarify meaning of each method | |
- YearMonthDay/TimeOfDay | |
- deprecated methods toDateTime(), toDateTime(DateTimeZone zone), as their meaning was confused. | |
On YearMonthDay, use toDateTimeAtCurrentTime() or toDateTimeAtMidnight(). | |
On TimeOfDay, use toDateTimeToday(). | |
Bug fixes since 0.98 | |
-------------------- | |
- Interval/MutableInterval isAfter(ReadableInterval) - fixed bug when intervals abutted | |
- Parsing periods of the form PT... - fixed bug that prevented parsing | |
- Period parsing now more strict - 'T' character required to separate date and | |
time in ISO periods | |
- Fixed parsing of fractional seconds in Periods | |
- Default time zone based on offset was being interpreted as UTC | |
- Fixed NullPointerException in DateTimeFormat | |
- DateTimeFormat would use date style for time style | |
- DateTimeFormatterBuilder was using wrong time zone for text fields | |
- Avoid NPE in property(DateTimeFieldType) methods | |
- Parsing two digit years using a pattern now follows JDK definition | |
Enhancements since 0.98 | |
----------------------- | |
- Formatting package much more powerful, and has potential to grow after 1.0 release | |
- YearMonthDay/TimeOfDay | |
- add toString variants that take a pattern | |
- add withField(), withFieldAdded(), withPeriodAdded(), plus() and minus() | |
- DateTimeField | |
- Add methods getAsText(int, Locale) and getAsShortText(int, Locale) for | |
simple access to text values | |
- Period | |
- Added support to create periods from a duration and an end instant | |
- Periods can be converted to durations by end instant too | |
- Duration | |
- Durations can be converted to periods by end instant too | |
- Durations can be converted to intervals by end instant too | |
</source> | |
</p> | |
</section> | |
</body> | |
</document> |