joda-time-android

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

Warning: joda-time-android is no longer a recommended solution for datetime handling on Android. Instead, I recommend using java.time.* package (w/ desugaring if necessary).

joda-time-android will continue to get tzdb updates for the foreseeable future to support any project that doesn't want to switch datetime handling.

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

Add the following dependency to build.gradle:

dependencies {
    implementation 'net.danlew:android.joda:2.14.2'
}

Multi-Process Apps

Due to using App Startup, joda-time-android will not automatically initialize in non-main processes.

If you would like to automatically run App Startup in other processes, add this to your manifest:

<provider
    android:name="androidx.startup.InitializationProvider"
    android:authorities="${applicationId}.androidx-startup"
    android:exported="false"
    android:process="[your-process-name-here]"
    tools:node="merge" />

Alternatively, you can call AppInitializer directly to initialize just joda-time-android:

AppInitializer.getInstance(this).initializeComponent(JodaTimeInitializer::class.java)

Troubleshooting

Q: My build fails with an error about a duplicate file

Duplicate files copied in APK META-INF/LICENSE.txt

or

Duplicate files copied in APK META-INF/NOTICE.txt

A: We can safely exclude those files from our build. You need to specify these two excludes in your build.gradle file and you will be good to go:

android {
    ...
    packagingOptions {
        exclude 'META-INF/LICENSE.txt'
        exclude 'META-INF/NOTICE.txt'
    }
}

or

B: We can safely choose to add those files to our build. You need to specify these two merges in your build.gradle file and you will be good to go:

android {
    ...
    packagingOptions {
        merge '**/LICENSE.txt'
        merge '**/NOTICE.txt'
    }
}