joda-time-android

This library is a version of Joda-Time built with Android in mind.

Why Joda-Time?

Android has built-in date and time handling - why bother with a library? If you've worked with Java's Date and Calendar classes you can probably answer this question yourself, but if not, check out Joda-Time's list of benefits.

For Android developers Joda-Time solves one critical problem: stale timezone data. Built-in timezone data is only updated when the OS is updated, and we all know how often that happens. Countries modify their timezones all the time; being able to update your own tz data keeps your app up-to-date and accurate.

Why This Library?

I know what you are thinking: Joda-Time is a great library and it's just a single JAR, so why make things more complex by wrapping it in an Android library?

There is a particular problem with the JAR setup on Android: due to its usage of ClassLoader.getResourceAsStream(), it greatly inflates its memory footprint on apps. (For more details, see this blog post.) This library avoids the problem for Android by loading from resources instead of a JAR.

This library also has extra utilities designed for Android. For example, see DateUtils, a port of Android's DateUtils.

Usage

You can either import this project as a plain old library project, or you can use it as an AAR from Maven Central.

If you're using gradle:

dependencies {
    compile 'com.onefootball.android:jodatime:2.5.0-TZ-2014-11-07@aar'
}

Once the project is imported, you must initialize the timezone provider and TIMEZONE_CHANGED broadcast receiver with a Context (via JodaTimeAndroid.init()) before you can start using this library. I suggest putting this code in Application.onCreate():

public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
      
        JodaTimeAndroid.init(this);
    }
}

Updating the TimeZone database

1. Download the latest Time Zone Data package from IANA. You will need only the tzdata package.

2. Unzip/untar the tzdata package and copy files from the package into the tzdata/ folder in this repository.

3. Run the following command

    ./gradlew updateTzData
   

4. Re-compile the library

Files Modified from Joda-Time

This is more of a reference for anyone wanting to later update the version of joda-time this is based off of:

DateTimeZone - Points to ResourceZoneInfoProvider instead of joda-time's ZoneInfoProvider.

ZoneInfoCompiler - Outputs Android-friendly zone info files.

TestDateTimeZone - Update tests to work with joda-time-android just make sure all this still works.