ezralazuardy / orb

Orb is a lifecycle-aware asynchronous network monitoring library to simplify the needs of network state monitoring in Android. This library can help you monitor (observe) the current network state of Android device. It can give you the current connection status, and connection type in realtime change events without blocking the main thread. Orb really works well with the MVVM architecture pattern in Android.

How it works

Orb is an implementation of Android Live Data that use an observable pattern to get the network state data in realtime. This is what makes Orb lifecycle-aware. Since the lifecycle of Live Data object is already handled automatically by Android lifecycle, you don't need to handle the Orb lifecycle manually. It's guarantee you to be flexible and no memory leak. You can just start Orb and forget about it, it'll handle the lifecycle based on your Activity lifecycle automatically.

How Orb determine the current network state and type is by using ConnectivityManager. And due to some Android ConnectivityManager API deprecation, applying network managing algorithm can be a little bit hard and tricky. Here's come Orb to the rescue. Orb is simple, powerful, sweet, and the most important, idiomatic!. It's written in pure Kotlin.

Latest version

See the latest released Orb version here.

✍️ Installation

Gradle setup

// project level gradle
allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

// module level gradle
dependencies {
    implementation 'com.github.ezralazuardy:orb:$version' //replace '$version' with the latest version of orb
}

Maven setup

<!-- <repositories> section of pom.xml -->
<repository>
    <id>jitpack.io</id>
   <url>https://jitpack.io</url>
</repository>

<!-- <dependencies> section of pom.xml -->
<dependency>
    <groupId>com.github.ezralazuardy</groupId>
    <artifactId>orb</artifactId>
    <version>version</version> <!-- replace 'version' with the latest version of orb -->
</dependency>

🚀️ Getting Started

Manifest permission settings

Since Orb API need to access and change the current network status of the device, you need to add the following permissions in you App manifest.

<manifest>
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
    ...
</manifest>

Using Orb

Orb usage is pretty simple, you just need to initialize it in your current context (view), and the rest will be handled by Orb.

Orb.with(this).observe { response ->
    Log.d(this::javaClass.simpleName, response.toString())
    // do something awesome..
}

All the action defined inside observe function will be converted into an observer. Make sure you've initialize the Orb only in the onCreate() function of your activity. Why?, because Orb only can observe a single observer and that need to be happened in the creation process of your activity.

What if you want to change the observer?, like changing the observer action after you observing the Orb? or changing the observer action when each time Orb detecting network changes? to do that, please read more about Orb advanced usage in the documentation.

If you don't want to use a direct written observer, you can use the Orb observer function builder, and pass the observer to observe function parameter.

// use the Orb observer function builder
val observer = orbObserver { response ->
  Log.d(this::javaClass.simpleName, response.toString())
  // do something awesome..
}

Orb.with(this).observe(observer)

Orb observer will be called each time Orb is detecting network changes in the device. The observe function also gives you an OrbResponse that hold the network state information, so that you can interact with it.

Please note that Orb will observing the network asynchronously. It's mean that Orb will not blocking your main thread, resulting in hang and stuttering effect on Android screen. And Orb is also lifecycle-aware. You don't need to worry about memory leak, all already handled by Orb. You just need to focus on functionality of your app, and let Orb do all the network monitoring stuff.

The OrbResponse

The observe method will return an OrbResponse object (accessible by keyword it by default) when each time Orb detecting a change in device network state. This object hold some properties as follows:

📖️ Documentation

Read the Orb documentation here.

🤔️ Sample Implementation

You can try the sample implementation of Orb by cloning this repository to your local, and run the sample module.

👷️ Contributing

All contributions are welcomed. Please make a pull request so that I can review your changes.

Before start making contributions to Orb, please read the contribution guidelines and code of conduct.

🛡️ Security Policy

Read the current Orb's security policy here.

🗒️ Side Note

Orb is at it's early stage. If you experiencing an error or bug, please report it by creating a new issues.

📜 License