Converting from Joda-Time to java.time

What steps are needed to upgrade from Joda-Time to Java SE 8 date and time (JSR-310)?

From Joda-Time to java.time

Joda-Time has been a very successful date and time library, widely used and making a real difference to many applications over the past 12 years or so. But if you are moving your application to Java SE 8, its time to consider moving on to java.time, formerly known as JSR-310.

The java.time library contains many of the lessons learned from Joda-Time, including stricter null handling and a better approach to multiple calendar systems. I use the phraseology that java.time is "inspired by Joda-Time", rather than an exact derivation, however many concepts will be familiar.

Converting types

Classes not including a time-zone:

Joda-Time	java.time	Notes
LocalDate	LocalDate	Same concept - date without time or time-zone
YearMonthDay
LocalTime	LocalTime	Same concept - time without date or time-zone
TimeOfDay
LocalDateTime	LocalDateTime	Same concept - date and time without time-zone
MonthDay	MonthDay	Same concept - month and day without time-zone
YearMonth	YearMonth	Same concept - year and month without time-zone
-	Year	New concept - a value type for the year
-	Month	New concept - an enum for the month-of-year
-	DayOfWeek	New concept - an enum for the day-of-week
Partial	-	Not included in java.time

Classes including a time-zone or representing an instant:

Joda-Time	java.time	Notes
DateTime	ZonedDateTime	Same concept - Date and time with time-zone
	OffsetDateTime	New concept - Date and time with offset from Greenwich/UTC
MutableDateTime	-	Not included in java.time, use immutable ZonedDateTime instead
DateMidnight	-	Deprecated as a bad idea in Joda-Time, Use LocalDate or ZonedDateTime
-	OffsetTime	New concept - Time with offset from Greenwich/UTC
Instant	Instant	Same concept - Instantaneous point on timeline
DateTimeZone	ZoneId	Same concept - Identifier for a time-zone, such as Europe/Paris
	ZoneOffset	New concept - An offset from Greenwich/UTC, such as +02:00

Amounts of time:

Joda-Time	java.time	Notes
Duration	Duration	Same concept - Amount of time, based on fractional seconds
Period	Period and/or Duration	Similar concept - Amount of time Joda-Time Period includes years to milliseconds, java.time only year/month/day (see also (ThreeTen-Extra PeriodDuration)
MutablePeriod	-	Not included in java.time, use immutable Period or Duration instead
Years	-	Not included in java.time, use Period instead (or ThreeTen-Extra)
Months
Weeks
Days
Hours	-	Not included in java.time, use Duration instead (or ThreeTen-Extra)
Minutes
Seconds
Interval	-	Not included in java.time (see ThreeTen-Extra)
MutableInterval	-	Not included in java.time

Formatting:

Joda-Time	java.time	Notes
DateTimeFormatter	DateTimeFormatter	Same concept - an immutable formatter
DateTimeFormatterBuilder	DateTimeFormatterBuilder	Same concept - a builder of the formatter
DateTimeFormat	DateTimeFormatter	Concepts exposed as static methods on DateTimeFormatter
ISODateTimeFormat
PeriodFormatter	-	Not included in java.time (see ThreeTen-Extra for limited support)
PeriodFormatterBuilder
PeriodFormat
ISOPeriodFormat

Other classes and interfaces:

Joda-Time	java.time	Notes
-	Clock	New concept - Standard way to pass around the current time
Chronology	Chronology	Similar concept - Very different API and implementation
ISOChronology	IsoChronology	Similar concept - Very different API and implementation
DateTimeFieldType	ChronoField	Similar concept - Very different API and implementation
DateTimeField
DurationFieldType	ChronoUnit	Similar concept - Very different API and implementation
DurationField
PeriodType	-	Not included in java.time
Readable*	Temporal*	The Readable* interfaces are most closely replaced by the Temporal* interfaces It is strongly recommended to use the value types, not the temporal interfaces

Odds and Ends

In most cases, the table above will be sufficient to identify the class to convert to. After that, in most cases the method needed will be obvious. Some special cases are noted below.

Rounding. Joda-Time has considerable support for rounding, java.time has less, based only on truncation. See the truncatedTo() methods.

End of month. Joda-Time has the withMaximumValue() method on the property object to change a field to the last day of the month. java.time has a more general mechanism, see TemporalAdjusters.lastDayOfMonth().

Nulls. Joda-Time accepts null as an input and handles it with a sensible default value. java.time rejects null on input.

Construction. Joda-Time has a constructor that accepts an Object and performs type conversion. java.time only has factory methods, so conversion is a user problem, although a parse() method is provided for strings.

Time between. Joda-Time provides methods on amount classes such as Days.between(a, b). java.time provides a similar method on the ChronoUnit classes - ChronoUnuit.DAYS.between(a, b).

Additional fields. Joda-Time provides a fixed set of fields in DateTimeFieldType. java.time allows the set of fields to be extended by implementing TemporalUnit, see IsoFields, JulianFields and WeekFields.

Summary

This blog post has outlined the key mappings between Joda-Time and java.time in Java SE 8. If you are writing code in Java SE 8, its time to migrate to java.time, perhaps using ThreeTen-Extra to fill any gaps.

ThreeTen-Backport vs Joda-Time

So which project should you choose? ThreeTen-Backport or Joda-Time?

Date and Time libarary pre-Java 8

Over the years, I have produced two libraries for Java date and time.

The first is Joda-Time, a library has become the de facto standard choice for many users.

The second is JSR-310, included as java.time in Java SE 8. Today I released v1.0 of ThreeTen-Backport, which makes the same JSR-310 API available in Java SE 6 and 7, although it is under a different package name.

So which should you choose?

If you are on Java SE 8 then you should use java.time (JSR-310). It tackles many issues with Joda-Time and is better integrated with the rest of the Java core libraries. Where necessary, consider using ThreeTen-Extra for any additional functionality that isn't in the JDK.

If you are on Java SE 6 or 7, then in general you should use Joda-Time. It is the standard option that other teams will be using, and it will be easier to interoperate if you stick to using Joda-Time.

The main use case for ThreeTen-Backport is if your team is using Java SE 6 or 7 but you are planning on moving to Java SE 8 in the near future. In this case, using the backport can smooth your future migration. However it will still require a package rename for your API users.

Another use case for the backport is to assist with backporting other Java SE 8 code to Java SE 7. See the retrolambda project (which could use ThreeTen-Backport but doesn't).

I hope that helps you to decide!

Time-zone database down

Today (2011-10-06), the time-zone database was closed down.

It is perhaps easy to read that line, think it doesn't affect you, and then move on. But thats just not the case.

Update 2011-10-07: A backup copy of the mailing list and subscribers has now swung into operation run by volunteer Robert Elz. Please only join this list to discuss changes to time-zones - its not a "fighting the lawsuit" list. New tz list

Update 2011-10-07: More details on the history of ACS, Astrolabe and how this came about from a competitor. Worth reading.

Update 2011-10-10: A new version of the time-zone database 2011l has been released. This news indicates how other members of the community have stepped up and continued the work, so the database can no longer be considered to be "down". However, we all need to ensure that we continue to support Olson and Eggert in their fight with the foolish people at Astrolabe. My blog about the rebooted database.

Update 2011-10-26: The situation has now stabilised. The database is now hosted by IANA after the succesful database reboot. Astrolabe also gave their opinion on the matter.

The time-zone database (sometimes referred to as the Olson database) is the computing world's principle source of time-zone data. It is embedded in every Unix and Java for starters, and will be used by many websites and probably by your iPhone. You may know it via the IDs, such as "Europe/London" or "America/New_York".

But, perhaps you're thinking that time-zones don't change? Well that may be true for America and the EU right now, but certainly isn't for the rest of the world. Governments change their time-zones all the time, and the decisions are frequently very political. I'd estimate there are between 20 and 100 separate changes made around the globe each year. And these can be at very short notice, triggered by earthquakes for example.

The time-zone database tracks all this information and creates a standard format file that describes it. I would show you an example of the file, but then perhaps I'd be sued....

The database itself was run as an open source project, led by Arthur David Olson, supported by many others. The data was published as a set of files about 15 times a year, and then picked up by users everywhere.

The complaint itself comes from Astrolabe, Inc, whose website looks like a company I would avoid doing business with.

The complaint is that Astrolabe produce a work, the "ACS Atlas", which is referenced by the time-zone database (some sources suggest that Astrolabe may have recently purchased the work). Astrolabe claim copyright over their work and thus believe that the time-zone databse should not have released their information to the public domain. The case is targetted at two private individuals - Arthur David Olson and Paul Eggert, who have hosted the website for many years.

The key passage in the time-zone database files is this:

# From Paul Eggert (2006-03-22):
# A good source for time zone historical data in the US is
# Thomas G. Shanks, The American Atlas (5th edition),
# San Diego: ACS Publications, Inc. (1991).
# Make sure you have the errata sheet; the book is somewhat useless without it.
# It is the source for most of the pre-1991 US entries below.

For obvious reasons, I'll refrain on commenting on the rights and wrongs of the case, although I will note that facts like the phonebook cannot be copyrighted. A detailed response from one site taken down is now available. Instead I'll focus on the impact.

The impact of this is severe for anyone that uses it - whether via Java, Unix or some other means. This really is the key tool used by everyone to tell the right time globally. We all owe a debt of gratitude to the database maintainers who have worked on this for many, many years at zero cost to the industry and for zero financial gain.

So, right now the global situation is that there is no longer a single central location for time-zone information for computing. I'm sure that each major user project (like the Unix distros) will patch their own versions as best they can, but the stricter ones might argue that the current data is tainted and want to remove even that. This could get very messy very quickly.

Both Joda-Time and ThreeTen/JSR-310 use the data to build timezone information. ThreeTen/JSR-310 in particular provides this information in huge detail to applications. The worst case scenario is that multiple groups start up to provide this data in the future, and applications are then responsible for handling multiple competing data sources.

This data is so key to the world at this point that it needs to be formalised and run by a group with more legal and financial backing. Efforts had been ongoing to achieve this, but they may now be in jeopardy - who would want to take on a project being legally attacked?.

I hereby call on the industry leaders to help sort this out - IBM, Oracle, Apple, Google, RedHat I'm looking at you.
Update: I didn't include Microsoft here because Windows has its own time-zone data files.

In the meantime, could I please ask that anyone thinking of patching the data on a temporary basis, or trying to recreate it from scratch, re-uses the existing file format. There is no reason to believe that the C code or file format is tainted by the lawsuit, just the data. So, lets all please try to minimise the mess that could happen if everyone starts to go their own way.

Add a comment or a rant below!

Update 2011-10-07: Alternatively you can rant on their Facebook page, Website contact us page or Amazon book review (note that the book may be by a different company - its a little unclear).

Joda-Time v2.0

Joda-Time version 2.0 is now released! Download. Release notes.

Firstly, Joda-Time 2.0 is NOT a re-write of Joda-Time. The major version number change signifies that there are some incompatibilities. However, these are as minor as I could make them.

A few methods on Chronology that were deprecated for years have been removed, but most other deprecated and classes methods remain as the benefits of removing them were lower than the damage caused.

The library has moved to JDK 1.5 compatibility, adding generics. Sadly, adding generics to Comparable in some cases caused issues for implementations. The choice was to aim for binary incompatibility at the expense of source incompatibility if the ReadableInstant or ReadableDuration interfaces were implemented directly. If you didn't implement these, or extended the supplied abstract class then you should have no problems. Similarly, ReadablePartial had Comparable added, but if you didn't implement it, or extended the supplied abstract class then again you should have no problems.

In summary, I hope there are no significant binary incompatibilities. If you do find a binary incompatibility that I didn't, I'd like to know, particularly if it affects another open source project. If it is in the next week or so, then perhaps the incompatibilty can be fixed and "jar hell" avoided.

There are a number of semantic changes as well in the corner cases. Again see the release notes.

• Parsing a month-day without a year now selects year 2000 rather than 1970 (so the 29th of February can be parsed)
• Edge cases with a week-based-year and a month are handled better
• Methods that handle daylight savings time (DST) are more consistent, retaining the offset wherever possible during calculations or consistently choosing summer time if not
• Some short time zone IDs have been changed
• DateTimeZone factory taking an ID is now case sensitive

And of course there are some enhancements:

• Static factories now() and parse() added to the main date-time classes
• New classes YearMonth and MonthDay
• API added to plugin to the Joda-Time clock
• Period formatting in multiple langauges
• Parsing of LocalDate/LocalTime/LocalDateTime directly supported (much better than previously)
• Parsing of time-zone IDs and some support for parsing time-zone names (via the builder)
• Better handling of 'Z' when parsing to mean +00:00
• Reliable way to get the start of day for a DateTime - withStartOfDay()
• Convenient way to handle DST, DateTime.withEarlierOffsetAtOverlap() .withLaterOffsetAtOverlap()
• Provide direct conversion from LocalDate and LocalDateTime to java.util.Date
• More constructors and methods for Duration
• More constructors for DateTime
• Support JDK 1.6 pluggable resource providers
• More compatible with the Java Memory Model in JDK 1.5 and higher
• Added support for Joda-Convert without adding a dependency

Hopefully, you can just drop Joda-Time into your application and you will not notice any change. However, you should definitely read the release notes first.

Finally, as I'm sure someone will ask, this doesn't affect ThreeTen/JSR-310. This release was necessary to finally release a lot of bugs and enhancements in Joda-Time.

PS. As a bonus, there is a re-release of the JSP tags library, as apparantly it wasn't in maven central correctly up until now.

PPS. For Hibernate 4.0 support, please use the usertype project.

Why JSR-310 isn't Joda-Time

One question that has been repeatedly asked is why JSR-310 wasn't simply the same as Joda-Time. I hope to expain some reasons here.

Joda-Time as JSR-310?

At its heart, JSR-310 is an effort to add a quality date and time library to the JDK. So, since most people consider Joda-Time to be a quality library, why not include it directly in the JDK?

Well, there is one key reason - Joda-Time has design flaws.

Now before everyone panics and abuses that line as a tweet, I need to say that Joda-Time is by far the best option curently available, and that most users won't appreciate the design flaws. But, I do want to document them, so the basis for the changes in JSR-310 is clear.

1) Human/Machine timelines

One element of clarity is a better understanding of the distinction between the two principle views of the timeline - Human and Machine.

Machines have one view - a single, ever increasing number. In Java we set zero as 1970-01-01T00:00Z and count in milliseconds from there.

Humans have a totally different view of time. We have multiple calendar systems (one primary, many others), which divide the timeline into years, months, days, hours, minutes and seconds. In addition, humans have time zones which cause the values to vary around the globe, and for there to be gaps and overlaps in the human timeline as DST starts and ends.

Much of the time, a conversion between the two timeline views is possible with a time zone, however in a DST gap or overlap, things are much less clear.

Joda-Time defines two key interfaces - ReadableInstant and ReadablePartial. Both the Instant class (simple instant in time) and the DateTime class (human view of an instant in time) are implementations of ReadableInstant. This is wrong.

DateTime is a human-timeline view of the world, not a machine-timeline view. As such, DateTime is much better thought of, and designed as, a LocalDateTime and a timezone rather than the projection of the machine timeline onto the human timeline. Thus, DateTime should not implement ReadableInstant.

2) Pluggable chronology

What is the range of values returned by this method in Joda-Time?:
int month = dateTime.getMonthOfYear();
The answer is not 1 to 12, but could be 1 to 13! (yet January is still 1 and December is 12)

The answer to this puzzler is down to pluggable chronologies. Each date/time class in Joda-Time has a pluggable chronology. This defines the calendar system that is in use. But most users of the API never check to see if the chronology is the standard ISO/ chronology before calling getMonthOfYear(). Yet, the Coptic chronology has 13 months in a year, and thus can return a range of 1 to 13.

A better solution would be to keep the date/time classes restricted to a single calendar system. That way, the result from each method call is clear, and not dependent on any other state in the class, like the chronology.

3) Nulls

Joda-Time accepts null as a valid value in most of its methods. For date/times it means 1970-01-01T00:00Z. For durations it means zero. For peiods it means zero.

This approach causes random bugs if your code happens to provide a null to Joda-Time that you hadn't originally planned for. Instead of throwing an error, Joda-Time continues, and the resulting date/time is going to be different from what you want.

4) Internal implementation

Certain aspects of the internal implementation are complex, and the result of having pluggable chronologies and a misunderstanding of the machine/human divide in the timeline. Changing this is a big change to the code.

One particular area of trouble is managing DST overlaps. The behaviour in Joda-Time of these isn't that well defined.

Summary

Joda-Time isn't broken!

It does the job it was designed for, and does it much better than the JDK. And it is widely used and without too many major issues. However, after a few years, it is now clear where it could be designed better.

I took the decision that I didn't want to add an API to the JDK that had known design flaws. And the changes required weren't just minor. As a result, JSR-310 started from scratch, but with an API 'inspired by Joda-Time'.

I hope that explains the thought process behind the creation of a new API in JSR-310.

Joda-Time 1.5 released

Finally released today, after a long wait, is Joda-Time version 1.5. This release fixes a number of bugs, and contains a raft of enhancements, which should make it a desirable upgrade for most users.

One enhancement is to provide a way to handle awkward time zones where midnight disappears. In these zones, the daylight savings time (DST) spring cutover results in there being no midnight. Unfortunately, the LocalDate.toDateTimeAtMidnight() method required midnight to exist and throws an exception if it doesn't. Version 1.5 adds a LocalDate.toDateTimeAtStartOfDay() method which handles this case by returning the first valid time on the date.

The Period class has also received a lot of new methods. You can now easily convert to a Duration and other periods using the standard ISO definitions of seconds/minutes/hours/days. You can also normalize using these definitions, converting "1 year 15 months" to "2 years 3 months".

Finally, it is now easier to tell if a given instant is in summer or winter time. This uses the new DateTimeZone.isStandardOffset() method.

Full details are available in the release notes or just go ahead and download! Maven jar, sources and javadoc are also available.

Days.daysBetween(today, christmas);

Using Java, how many days are there between now and Christmas? Its actually quite a tricky calculation to get reliably right (Did you forget to handle daylight savings?).

Now you no longer need to write it yourself if you use version 1.4 of Joda-Time:

LocalDate today = new LocalDate();
LocalDate christmas = new LocalDate(2006, 12, 25);
Days daysToChristmas = Days.daysBetween(today, christmas);

So what's going on here? Well its pretty readable really, but we are (a) creating two date objects (no time, no timezone) and (b) calculating the days between the dates. The calculation effectively includes the start date and excludes the end date. Issues with daylight savings time are avoided by using the no timezone LocalDate objects. But what if you want to calculate the number of days considering time, lets say 08:00 on christmas morning?

DateTime now = new DateTime();
DateTime christmas = new DateTime(2006, 12, 25, 8, 0, 0, 0);
Days daysToChristmas = Days.daysBetween(today, christmas);

Well, that's pretty similar! Internally, the code will count the number of whole days between the datetimes. Or put another way, how many 24 hours units are there between the two datetimes (except that it handles 23/25 hours DST dates too!). So, 08:01 on christmas eve returns zero days, but 07:59 returns one day.

And what's the other noticeable feature about the code above? Well, the result is being returned as an object, Days, not as an int. This allows your application to store a value in days, and actually know it is days and not some random int.

Up until now in Joda-Time, we have used the Period class for this. But that allowed you flexibility in storing a period such as "3 days, 12 hours and 32 minutes" - fine if you want that flexibility, but not if you don't. Days on the other hand can only store a number of days.

Now, you may be asking what is so special about days? Why can't I calculate the difference between months or hours. Well, of course you can! The new classes are Years, Months, Weeks, Days, Hours, Minutes and Seconds. They all operate in a similar manor, and they all implement the relevant interface, ReadablePeriod so they can interoperate.

Oh, and one last point. the factory method have a naming style that allows them to be statically imported on Java SE 5. Still not sure if I really like static imports, but at least the API supports the coding style!

As always, any feedback on Joda-Time is welcomed, here, mailing list or forum. With your help, the library can improve still further!

Which days of the week are the weekend in Egypt?

Do you know? Or more precisely, does your Java application know?

Well, yesterday I released a 0.1 version of a new project Joda-Time-I18N. This provides four lookups at present:

• Time zone by territory
• First day of week by territory
• Business days by territory
• Weekend days by territory

The data comes from the Unicode CLDR project, so should be pretty accurate (its backed by IBM and Sun).

The code is released now to get some feedback, and to allow early users access. The 0.1 version refers to the chance of the API changing (high), not the quality of the data (which is good). Oh, and the weekend in Egypt?

  Territory t = Territory.forID("EG");
  int weekendStartDay = t.getWeekendStart();
  int weekendEndDay = t.getWeekendEnd();

Anyway, I'd love to here any feedback on the API, data or proposed enhancements.

Joda-Time 1.3 released

Well, it took a while, but the next release of Joda-Time is finally here. Version 1.3 includes two main enhancements in addition to the bug fixes:

Three new datetime classes have been added - LocalDate, LocalTime and LocalDateTime. These represent a date, time or datetime without a time zone. As such LocalDate is a direct replacement for YearMonthDay, whilst LocalTime replaces TimeOfDay. Neither of the replaced classes has been deprecated yet however, due to their widespread adoption.

The new Local* classes use a more standard and reliable implementation internally, and fix some weird external semantics of the older classes. For example, it was not possible to query the dayOfWeek on a YearMonthDay (because it only holds year, month and day!). LocalDate uses a different implementation, so that restriction no longer applies.

The second major enhancement is the addition of convenience methods to change each field value - immutable equivalent of set methods. Here is how to set the day to the first day of the month, constrasting before and after:

// previously
firstOfMonth = dt.dayOfMonth().setCopy(1);

// version 1.3
firstOfMonth = dt.withDayOfMonth(1);

Clearly, the new code is more readable and understandable. Note that as Joda-Time objects are immutable, the methods return a new instance with that field value changed. This is emphasised by the use of the verb 'with' rather than 'set'

As always, feedback is welcomed - whether bugs or reviews, good or bad! Only with input from the community can the library improve.

A better datetime library JSR?

Do you hate the JDK Date and Calendar classes? Would you like to see an alternative in the JDK? Or are you happy with the JDK classes? Maybe you are happy with pulling in a jar file?

I ask because I get asked from time to time whether Joda-Time is going to get a JSR. Each time this comes up I point out that its a lot of work to do in my free time, and there are infrequent enough releases as is!

So, this blog is an open question - is it worth it? Should JDK7 contain a better datetime library? Please add a comment with your views, postive and negative so I can get some idea of peoples thoughts!

Joda-Time subprojects released

I've just finished releasing the Joda-Time hibernate support (0.8) and Joda-Time JSP tags (0.9) subprojects.

Both these projects are still officially pre a 1.0 release, however its good to have them available properly. I had intended to release the jsptags project as 1.0, but a cunning plan ensued which caused me to go to 0.9 instead. Hopefully I can confess what I've been up to soon, its really very useful!

Joda-Time 1.2 is released

I had hoped it might have been released before Javapolis, but time pressures came into play (no pun intended!) Anyway, Joda-Time 1.2, the replacement for JDK Date and Calendar, is now released!

This release fixes a few bugs and upgrades to the latest time zone information. It also includes two new calendar systems, Ethiopic and Islamic. I am still looking to expand the range of calendar systems though, there are numerous ones still to add.

Also added were convenience methods on properties to create an interval for a whole month/week etc (toInterval), and to set a date to the last day in a month (withMaximumValue).

The feedback from Joshua Bloch and the rest of the audience at Javapolis was useful, and I expect to enhance and clarify the API over the coming year.

Full details can be found on the website. As always, feedback welcome!

Joda-Time 1.1 is released

It took a while, but version 1.1 of Joda-Time, the replacement for JDK Date and Calendar, has been released!

This release does fix a few bugs, however these were mostly relatively minor. It does however include a number of useful new methods and usability enhancements. For example:

• a new Partial class, allowing any group of datetime fields to be defined. A typical use might be to create a YearMonth object for a credit card
• new convenience methods for adding periods, such as plusDays(n) or minusHours(n)
• YearMonthDay and TimeOfDay are now comparable
• new methods to create a Period from two YearMonthDay or two TimeOfDay objects
• new methods on Interval - gap, abuts and overlap
• better handling of two digit years in formatting/parsing
• added ISO formats for ordinal (dayOfYear) dates

And stay tuned for announcements about Hibernate and JSP integration!

Full details can be found on the website.

Oh, and if anyone wants to help develop another calendar systems, such as Hebrew, Islamic, Chinese, etc. then please contact me!!!

So where next with Joda-Time? A JSR?

Releasing a v1.0 can be a strange experience. Once its done, the stress can just disappear, and you take a bit of a rest (assuming there was no great heap of new bugs discovered, which there wasn't).

And its a bit like that with Joda-Time. v1.0 is done and out in the wild. There was quite a bit of positive feedback, but I've no idea how popular it really was because Sourceforge statistics are up the spout.

The main question then becomes well what next? v1.1 would be the obvious answer, but I need to gather some energy to add more code. And until and unless I get feedback on Joda-Time in use its difficult to know what people are missing.

The other possible direction is a JSR. Various people have suggested this, but I am a little skeptical. JDOM, Jade (scientific units) and Groovy haven't exactly been good indicators of what JSRs do to open source projects.

So, what do people reading this think. Are you not using Joda-Time because its not in the JDK? Is a JSR a good direction to go? Have you got your own ideas for what java.time should look like?

Joda-Time 1.0 released

Yes, its finally here! Joda-Time, the replacement for JDK Date and Calendar (and much more) has reached 1.0!

Full details can be found on the website. However, let me draw out a few key features:

- Easy to Use - Calendar makes accessing 'normal' dates difficult, due to the lack of simple methods. Joda-Time has straightforward field accessors. And the index of January is 1!

- Extensible - Joda-Time supports multiple calendar systems via a plugin mechanism, which is much more extensible than the subclasses of Calendar. Currently supported calendars are ISO8601, GregorianJulian, Buddhist (Thai) and Coptic.

- Comprehensive - Joda-Time includes classes for datetimes, dates without times, times without dates, intervals and time periods.

- Advanced formatting - An advanced and extensible formatting mechanism is included, allowing input and output to string in a thread-safe manner.

- Well documented. There is documentation in the form of a quick and full user guide, plus reference pages, FAQs and javadoc.

- Tested. There is good test coverage, see the website, providing an assurance of quality.

- Built in security. Advanced operations that could prove a security risk (like changing the current time) are protected by standard JDK security.

And if you learn best by an example:

public boolean isRentalOverdue(DateTime datetimeRented) {
  Period rentalPeriod = Period.days(2);
  return datetimeRented.plus(rentalPeriod).isBeforeNow()
}
public boolean isJoinedInLastThreeMonths(DateTime datetimeJoined) {
  Interval last3Months = new Interval(Period.months(3), new DateTime());
  return last3Months.contains(datetimeJoined);
}
public boolean isBirthdayInLeapYear(YearMonthDay dateOfBirth) {
  return dateOfBirth.year().isLeap();
}

So, now its released, what next? Well I hope that some of you reading this will want to help add some other calendar systems, such as Hebrew, Islamic, Chinese, etc. Any takers?

Joda-Time 0.99 done, 1.0 on its way...

Yes, after lots of late nights, version 0.99 of Joda-Time (the replacement for JDK Date and Calendar, and much much more) is out in the wild.

The plan is to get a few days feedback on 0.99, remove the deprecated methods, then release as 1.0 next week (and definitely before the end of February).

By the way, if you used version 0.98, you'll need to read the release notes, as there were a few last minute changes between 0.98 and 0.99. But I'm determined to let nothing stop 1.0 ;-)

Oh, and if you want to help out by developing another calendar system, Hebrew, Islamic, Chinese, Thai, Japanese,... just drop me a line !

Joda-Time 0.98 released

Well, it took long enough, but finally its here. The new release of Joda-Time , the cleanroom replacement to JDK Date and Calendar. So whats in it?

• DateTime - a millisecond based datetime + timezone
• DateMidnight - a millisecond based date + timezone
• YearMonthDay - a field based date without zone
• TimeOfDay - a field based time without zone
• Duration - a millisecond based length of time (23456 ms)
• Period - a field based length of time (5 months, 2 days and 4 hours)
• Interval - a time interval between two exact points in time

Those who've played with Joda-Time before will spot that some classes have changed. TimeOnly became TimeOfDay, DateOnly became DateMidnight or YearMonthDay depending on your requirements. This was all necessary to solve issues that only became apparant during testing. This is one project where test driven development might actually have produced a better design earlier, not just bug free code. Ah well, isn't hindsight great...