A Kotlin library for Android to get the current time from multiple sources: SNTP, GPS; or your own time source.
Why is it important?
System.currentTimeMillis() [...] can be set by the user [...] so the time may jump backwards or forwards unpredictably.
-- https://developer.android.com/reference/android/os/SystemClock.html. July, 2017.
You can check how Tempo works in this blog post.
Initialize the library in your Application
class:
class MyApp : Application {
override fun onCreate() {
Tempo.initialize(this)
...
}
}
After the library is initialized, you can get the time with:
val timeNowInMs = Tempo.now()
Tempo::now()
will return either a Long
or a null
. A null
is returned when Tempo has not been
initialized yet. When initialized, Tempo::now()
returns the current
unix epoch time in milliseconds.
You can observe all the events emitted by the library:
Tempo.observeEvents().subscribe {
if (it is Tempo.Initialized) {
Log.i("Tempo", "Initialized!")
}
}
Add the snippet below in your root build.gradle at the end of repositories:
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
Then, add the dependency to your module:
dependencies {
compile 'com.github.AllanHasegawa.Tempo:tempo:x.y.z'
}
Tempo comes with two sources for time: SlackSntpTimeSource
and AndroidGPSTimeSource
.
Tempo will request the current time from each time source. Once the requests are completed, the library will pick the best time. The best time is defined by the source's priority score.
When a request fails, the next successful request with highest priority score is picked.
If all requests fails, then Tempo will adopt a strategy (see io.tempo.SyncRetryStrategy
) to
keep retrying.
The SlackSntpTimeSource
is the default time source. It implements a loose version of the
SNTP protocol. While it doesn't guarantee an accurate time, it should be accurate enough for most use cases.
This time source requires an active internet connection to work.
The AndroidGPSTimeSource
uses the device's GPS to get the current time. The accuracy will
vary depending on the GPS.
This time source is in a separated module because it adds the ACCESS_FINE_LOCATION
permission.
Only use this module if you need this functionality.
To include it in your project, include the dependency:
compile 'com.github.AllanHasegawa.Tempo:tempo-android-gps-time-source:x.y.z'
Then, add it during initialization:
Tempo.initialize(this,
timeSources = listOf(SlackSntpTimeSource(), AndroidGPSTimeSource(this))
Warning: If you are targeting Android SDK 23 or higher, you will have to request for the GPS permission at runtime.
You can create your own time source. For that, implement the io.tempo.TimeSource
interface and then add it during initialization:
val customTs = MyCustomTs()
Tempo.initialize(this,
timeSources = listOf(customTs)
A device's clock slowly drifts away from an accurate time. Therefore, Tempo also offers an scheduler to automatically sync its time.
To add, first add its module to your gradle build file:
compile 'com.github.AllanHasegawa.Tempo:tempo-android-job-scheduler:x.y.z'
Then, add it during initialization:
Tempo.initialize(this,
scheduler = AndroidJobScheduler(this, periodicIntervalMinutes = 60L))
This module uses the awesome android-job library.
Unfortunately it also means we are also using the GcmNetworkManager
dependency–a really heavy
dependency. That's why you have to add it manually if you want it.
- What happens if the application gets destroyed?
By default, Tempo survives an application's process death. It accomplishes it by saving its state in the app's shared preference storage.
- What happens if the user reboots the device?
We invalidate all cache and a complete sync is required.
- What happens if the user has no internet access, no GPS, and rebooted his phone?
Then you should use a fallback strategy, like System.currentTimeMillis()
.
- Will Tempo ever support Java?
If there's enough interest. Open an issue if you would like to use it with Java.
Copyright (c) 2017 Allan Yoshio Hasegawa
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
http://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.