NetworkValidator
A lightweight module written in Kotlin for monitoring network state and airplane mode on native android.
Uses
NetworkValidator provides real-time network availability and airplane mode monitoring.
Installation
current-version: 1.0.0-SNAPSHOT
- Grab a JAR artefact from the Maven Central Repository:
- On Gradle
implementation 'io.github.iodevblue:networkvalidator:current-version'
- On Apache Maven
<dependency>
<groudId> io.github.iodevblue </groudId>
<artifactId> parallaxnavigationdrawer </artifactId>
<version> current-version </version>
</dependency>
If it is a snapshot version, add the snapshot Maven Nexus OSS repository:
maven {
url 'https://s01.oss.sonatype.org/content/repositories/snapshots/'
}
Then retrieve a copy:
implementation 'io.github.iodevblue:parallaxnavigationdrawer:current-version'
- Grab a JAR or AAR artifact from the release section.
- Place it in
libs
folder in your project module and install in your project.
implementation fileTree(dir:' libs', include:'*jar')
Usage
NOTE: Minimum supported Android SDK version = 23
Create a NetworkValidator
instance using a Context
:
val networkValidator = NetworkValidator(context)
Validate if there is internet connection on a device:
val isOnline = networkValidator.isOnline()
if(isOnline) {
retrieveFromRemoteRepo()
} else {
retrieveFromLocalCache()
}
Validate if there is internet connection through Wifi:
val isWifiAvail = networkValidator.isWifiAvailable()
if(isWifiAvail) {
startPackageDownloading()
} else {
informUser()
}
Validate if there is internet connection through mobile data:
val isMobileDataOn = networkValidator.isCellularAvailable()
if(isMobileDataOn) {
connectToServer()
} else {
disconnectFromServer()
}
Validate if airplane mode is turned on:
val isOnAirplane = networkValidator.isAirplaneModeActive()
if(isOnAirplane) {
disconnectFromServer()
} else {
doSomethingRemotely()
}
To listen for changes in internet availability on the device (both Wifi and Mobile Data), set an OnNetworkChangedListener
instance:
val networkValidator = NetworkValidator(context)
networkValidator.onNetworkChangedListener = object: NetworkValidator.OnNetworkChangedListener {
override fun onNetworkChanged(isOnline: Boolean, network: Network) {
if(isOnline) {
contactRemoteServer()
}
}
}
Or apply an OnNetworkChangedListener
using a Kotlin receiver function syntax:
networkValidator.setOnNetworkStateChangedListener { isOnline, _ ->
if(isOnline) {
contactRemoteServer()
}
}
NOTE: The onNetworkChanged()
callback and the setOnNetworkStateChangedListener {...}
receiver function all execute in a background Thread
. That means, User Interface functions that respond to network changes MUST be executed on a UI Thread
like so on an Android Activity
:
networkValidator.onNetworkChangedListener = object: NetworkValidator.OnNetworkChangedListener {
override fun onNetworkChanged(isOnline: Boolean, network: Network) {
runOnUiThread {
if(isOnline) {
contactRemoteServer()
}
}
}
}
To listen for airplane mode changes, set an OnAirplaneModeSwitchListener
instance:
networkValidator.onAirplaneModeSwitchListener = object: NetworkValidator.OnAirplaneModeSwitchListener {
override fun onChanged(turnedOn: Boolean) {
if(turnedOn) {
pauseRemoteConnection()
}
}
}
Or apply an OnAirplaneModeSwitchListener
using a Kotlin receiver function syntax:
networkValidator.setOnAirplaneModeSwitchListener { isOnline, _ ->
if(isOnline) {
contactRemoteServer()
}
}
Also, the onChanged()
callback and the setOnAirplaneModeSwitchListener {...}
receiver function all execute in a background Thread
therefore, User Interface functions that respond to airplane mode changes MUST be executed on a UI Thread
the same way as the OnNetworkChangedListener
.
NOTE: NetworkValidator
uses an internal BroadcastReceiver
that handles receiving airplane mode change events and it is automatically registered when an OnAirplaneModeSwitchListener
instance is defined. It is unregistered and nullified when the OnAirplaneModeSwitchListener
is nullified.
(see library code for more details)
However this internal BroadcastReceiver
needs to be unregistered when a NetworkValidator
is not in use to avoid memory leaks.
In an Android Activity
, it can be done like so:
override fun onResume() {
super.onResume()
networkValidator.registerAirplaneModeSwitchListener
}
override fun onPause() {
super.onPause()
networkValidator.unregisterAirplaneModeSwitchListener
}
Kotlin extension receiver functions (extensions on a Context
) are also included to assist in prompt setup:
networkValidator{}
returns a valid NetworkValidator instance:
networkValidator {
setOnNetworkStateChangedListener { b, _ ->
runOnUiThread {
tv.text = resources.getString(R.string.detect_network)
showProgress()
updateNetworkState(b)
}
}
}
listenForNetwork{}
internally creates a NetworkValidator and registers an OnNetworkChangedListener
that begins listening immediately:
listenForNetwork { b, network ->
if(b) {
updateNetworkState(b)
reInitializeRemoteConnection()
} else {
invalidateRemoteConnection()
informUser()
}
}
listenForAirplaneModeChanges{}
returns a NetworkValidator and registers an OnAirplaneModeSwitchListener
that begins listening immediately:
val networkValidator = listenForAirplaneModeChanges {
if(it) {
cancelRemoteConnection()
} else {
reInitializeRemoteConnection()
}
}
The returned NetworkValidator
instance can then be used to register()
and unregister()
the internal BroadcastReceiver
.
Java Interoperability
This module is completely interoperable with Java.
NOTE: Extension functions are not applicable in Java.
Create a NetworkValidator
instance:
NetworkValidator networkValidator = new NetworkValidator(this);
Validate if there is internet connection on a device:
boolean isOnline = networkValidator.isOnline();
if(isOnline) {
retrieveFromRemoteRepo();
} else {
retrieveFromLocalCache();
}
Validate if there is internet connection through Wifi:
boolean isWifiAvail = networkValidator.isWifiAvailable();
if(isWifiAvail) {
startPackageDownloading();
} else {
informUser();
}
Validate if there is internet connection through mobile data:
boolean isMobileDataOn = networkValidator.isCellularAvailable();
if(isMobileDataOn) {
connectToServer();
} else {
disconnectFromServer();
}
Validate if airplane mode is turned on:
boolean isOnAirplane = networkValidator.isAirplaneModeActive();
if(isOnAirplane) {
disconnectFromServer();
} else {
doSomethingRemotely();
}
To listen for changes in internet availability on the device (both Wifi and Mobile Data), set an OnNetworkChangedListener
instance:
NetworkValidator networkValidator = new NetworkValidator(this);
networkValidator.setOnNetworkChangedListener((isOnline, network) -> {
if(isOnline) {
contactRemoteServer();
}
}
To listen for airplane mode changes, set an OnAirplaneModeSwitchListener
instance:
networkValidator.setOnAirplaneModeSwitchListener(turnedOn -> {
if(turnedOn) {
pauseRemoteConnection();
}
}
Configurations:
Variable | Default | Use |
---|---|---|
onNetworkChangedListener | null | Listener for Network state changes. |
onAirplaneModeSwitchListener | null | Listener for airplane mode changes. |
Method | Returns | Use |
---|---|---|
isOnline() | Boolean | Validates if there is internet connection. |
isWifiAvailable() | Boolean | Validates if internet connection is available through Wifi. |
isCellularAvailable() | Boolean | Validates if internet connection is available through mobile data. |
isAirplaneModeActive() | Boolean | Validates is airplane mode is active. |
unregisterAirplaneModeSwitchListener() | Unit | Unregisters the onAirplaneModeSwitchListener from listening to airplane mode events. |
registerAirplaneModeSwitchListener() | Unit | Registers the onAirplaneModeSwitchListener to start listening for airplane mode events. |
setOnNetworkStateChangedListener(execute: OnNetworkChangedListener.(Boolean, Network) -> Unit) | Unit | Sets a network change listener. |
setOnAirplaneModeSwitchListener(execute: OnAirplaneModeSwitchListener.(Boolean) -> Unit) | Unit | Sets an airplane mode switch listener. |
Contributions
Contributors are welcome!
NOTE: This repository is split into two branches:
- main branch
- development branch
All developing implementations and proposed changes are pushed to the development branch and finalized updates are pushed to the main branch.
To note if current developments are being made, there would be more commits in the development branch than in the main branch.
Check the Contributing for more information.
Changelog
- 1.0.0-SNAPSHOT
- Initial release
More version history can be gotten from the Change log file.
License
Copyright 2023 IO DevBlue
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.