Introduce APIs for dependency injection of TimeZone-related information

[dkhalanskyjb]

Fixes #17
Fixes #201
Fixes #435

#611 is a space for comments, questions, and suggestions. Since the PR is at the conceptual stage, some discussion threads may end up being quite long, so the PR format is not particularly well-suited for it.

The most interesting places in the code are:

• https://github.com/Kotlin/kotlinx-datetime/blob/dkhalanskyjb/deprecate-datetime-singletons/core/common/src/TimeZoneContext.kt the new APIs.
• https://github.com/Kotlin/kotlinx-datetime/blob/dkhalanskyjb/deprecate-datetime-singletons/core/common/src/TimeZone.kt how TimeZone will look like with its static functions now deprecated. Note the updated semantics of ==, which now takes the TimeZone's origin timezone databases into account.
• https://github.com/Kotlin/kotlinx-datetime/blob/dkhalanskyjb/deprecate-datetime-singletons/timezones/full/common/src/BundledTimeZoneContext.kt the API of a separate artifact published alongside kotlinx-datetime one will be able to depend on to obtain an up-to-date timezone database.

It's important to note that this is not a full-fledged solution for providing custom timezone databases, though! Constructing a custom TimeZone is still going to be non-viable, even with the proposed API, as there's no way to construct a custom TimeZone. To properly implement that, we would (most likely) need to expose the structure of a TimeZone object (historical data, recurring rules) and the additional logic that is likely going to be needed when implementing realistic timezone databases (see

kotlinx-datetime/timezones/full/common/src/BundledTimeZoneContext.kt

Lines 84 to 96 in e550556

	private val impl: TimeZoneDatabase = FixedOffsetTimeZoneDatabase(object: TimeZoneDatabase {
	override fun get(id: String): TimeZone = getOrNull(id)
	?: throw IllegalTimeZoneException(
	"Zone ID '$id' was not recognized by the bundled timezone database (version $timeZoneDatabaseVersion)."
	)
	override fun getOrNull(id: String): TimeZone? {
	val data = zoneDataByNameOrNull(id) ?: return null
	return RuleBasedTimeZoneCalculations(readTzFile(data).toTimeZoneRules(), id, this).asTimeZone()
	}
	override fun availableZoneIds(): Set<String> = timeZones
	})

). We wanted to start small for now and watch the community response to at least the dependency injection API as a whole. Then, we would like to tweak it if necessary, and only then collect the less common use cases and expose the rest of the pieces.

[swankjesse]

This is fantastic and I appreciate how much design effort went into this.

When I set up servers and CI environments and such I always set an environment variable TZ=UTC0 so the host machine’s zone doesn’t accidentally leak through to the application layer. For example, I don’t need to worry that payment scheduling will change due to DST.

Would you consider exposing a symbol similar to TimeZoneContext.System like TimeZoneContext.Universal that is locked to UTC?

[dkhalanskyjb]

TimeZoneContext.Universal looks very specific, so probably not in the form you propose. My guess is that the API would look something like TimeZoneContext.System.withFixedCurrentTimeZone(TimeZone.UTC), though we'd need to carefully study the use cases for custom TimeZoneContexts to arrive at a good orthogonal API.

[JakeWharton]

Since this is a new API, can it use the new mechanism of default function compilation which relies on JVM default methods? This old trampoline-based version is only needed for existing APIs targeted by old code.