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.

IODevBlue / NetworkValidator