Due to limitations on Android's mainline update mechanism for TZ data (which prohibits loading custom TZ data), this library is now deprecated and archived. Unfortunately it's only really useful for apps that use library desugaring, and is essentually pointless on apps with minSdk 24+.
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).
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!
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.
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'
}
// 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.
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.
https://www.zacsweers.dev/ticktock-desugaring-timezones/
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.