JarCastingTickTock
TickTock is a timezone data management library for the JVM and Android targeting java.time.* APIs in Java 8 or above. Use this library if you want to bundle timezone data directly with your application rather than rely on the current device timezones (Android) or the default <java.home>/lib version (JVM only).
Usage
Android
Simply add the android tzdb startup dependency:
implementation 'dev.zacsweers.ticktock:ticktock-android-tzdb:<version>'
This will automatically initialize it appropriately without any configuration needed using androidx.startup. If you don't want automatic initialization, you can disable it and do it manually.
<provider
android:name="androidx.startup.InitializationProvider"
android:authorities="${applicationId}.androidx-startup"
android:exported="false"
tools:node="merge">
<meta-data android:name="dev.zacsweers.ticktock.android.tzdb.startup.AndroidTzdbRulesInitializer"
tools:node="remove"/>
</provider>
AndroidTzdbZoneRules.init(<context>)
Note that Android usage assumes use of core library desugaring. If you are not using it and/or are minSdk 26+, this library is of no use to you!
JVM
Add the jvm tzdb dependency:
implementation 'dev.zacsweers.ticktock:ticktock-jvm-tzdb:<version>'
Then call its initializer as early as possible in your application.
JvmTzdbZoneRules.init()
This will make ZoneRulesProvider use TickTock's implementation with its bundled timezone data.
Advanced
Eager caching
TickTock's default behavior is to lazily load timezone data on-demand. If you want to eagerly load data (for instance - on a background thread), TickTock offers a convenience helper API:
// Synchronously load and cache all timezone rules
EagerZoneRulesLoading.cacheZones();
Custom Data Loading
By default, TickTock will try to load timezone data from Java resources via ResourcesZoneDataLoader. If you wish to customize this, you can provide your own loading mechanism via implementing a custom ZoneDataLoader and/or ZoneDataProvider and registering them via TickTockPlugins before using any time APIs that would cause the system ZoneRulesProvider to initialize.
Usually, you would only want to implement a custom ZoneDataLoader and instantiate one of the built-in ZoneRulesProvider implementations with it. TickTock comes with two: TzdbZoneDataProvider (the common case) and LazyZoneDataProvider. You can also implement your own provider on top of any ZoneDataLoader type as you see fit.
CustomZoneDataLoader loader = new CustomZoneDataLoader();
TzdbZoneDataProvider provider = new TzdbZoneDataProvider(loader);
TickTockPlugins.setZoneDataProvider(() -> provider);
The Android artifacts use a custom assets-based loader to avoid the cost of loading from Java resources.
Custom Regions
By default, TickTock's prepackaged timezone data supports all regions. You can define your own via implementing a custom ZoneIdsProvider and registering it via TickTockPlugins before using any time APIs that would cause the system ZoneRulesProvider to initialize.
TickTockPlugins.setZoneIdsProvider(CustomZoneIdsProvider::new);
If no provider is specified, TickTock will use TzdbZoneProvider.
Lazy Zone Rules
TickTock's default behavior is focused around using traditional tzdb.dat files for timezone data implemented via TzdbZoneDataProvider. Early adopters can try a custom, lazy-loading solution via LazyZoneDataProvider inspired by LazyThreeTenBp. In theory, this artifact would be lower overhead on startup for devices with slower IO and a lower application-lifetime memory impact by only keeping used zones in memory. We're seeking feedback on whether this is truly worth supporting though, so please let us know!
Compiler CLI
To manually compile lazy zone rules yourself, you can use the ticktock-compiler API.
Usage: ticktockc [OPTIONS]
Options:
--version TEXT Version of the time zone data, e.g. 2017b.
--srcdir DIRECTORY Directory containing the unpacked leapsecond and
tzdb files.
--tzdbfiles TEXT Names of the tzdb files to process.
--leapfile TEXT Name of the leapsecond file to process.
--codeoutdir DIRECTORY Output directory for the generated java code.
--tzdboutdir DIRECTORY Output directory for the generated tzdb files.
--verbose Verbose output.
--language [JAVA|KOTLIN] Language output (java or kotlin).
--packagename TEXT Package name to output with.
-h, --help Show this message and exit
Gradle coordinates:
implementation("dev.zacsweers.ticktock:ticktock-compiler:<version>")
If you want a fat jar binary, you can clone and run ./gradlew :ticktock-compiler:installDist. Binaries will be generated to ticktock-compiler/build/install/ticktock-compiler/bin. If there is interest, we may explore automatically uploading these as GitHub release artifacts.
Gradle Plugin
The Gradle plugin can be used to automatically download new TZ data, package it, and/or generate lazy zone rules if you want to manage data yourself.
plugins {
id("dev.zacsweers.ticktock")
}
To generate a standard tzdb.dat: run the generateTzdbDat task.
To generate lazy zone rules: run the generateLazyZoneRules task.
Extension and configuration:
ticktock {
/** The IANA timezone data version */
val tzVersion: Property<String> // default to '2020d'
/** The output directory to generate tz data to. Defaults to src/main/resources. */
val tzOutputDir: DirectoryProperty // defaults to src/main/resources
/** Output directory for generated code, if generating for lazy rules. */
val codeOutputDir: DirectoryProperty
/** The language to generate in if generating for lazy rules, either `java` or `kotlin`. */
val language: Property<String> // defaults to java
/** The package name to generate in if generating for lazy rules. */
val packageName: Property<String> // defaults to 'ticktock'
}
Download
// Core runtime artifact
implementation 'dev.zacsweers.ticktock:ticktock-runtime:<version>'
// TZDB artifacts
implementation 'dev.zacsweers.ticktock:ticktock-jvm-tzdb:<version>'
implementation 'dev.zacsweers.ticktock:ticktock-android-tzdb:<version>'
// Lazy zone rules artifacts
implementation 'dev.zacsweers.ticktock:ticktock-jvm-lazyzonerules:<version>'
implementation 'dev.zacsweers.ticktock:ticktock-android-lazyzonerules:<version>'
Snapshots of the development version are available in Sonatype's snapshots repository.
Versioning
Versions are semver + the current IANA TZ data version it's packaged with.
Example: 1.0.0-2020d
Note that while some artifacts don't contain TZ data, we use the same version for everything in the interest of simplicity.
Why?
https://www.zacsweers.dev/ticktock-desugaring-timezones/
License
Copyright (C) 2020 Zac Sweers & Gabriel Ittner
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.