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();

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.

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.

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!

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.

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'
}