Chamber

A lightweight Android lifecycle-aware and thread-safe pipeline for communicating between components with custom scopes.

Android components are essential building blocks of an Android application.
These independent components are very loosely coupled. The benefit is that they are really independently reusable, but it makes to hard communicate with each other.

The goal of this library is making easier to communicate and flow data with each other component like Activity, Fragment, Services, etc. And we can deliver data on each component easily and clear data on memory automatically following lifecycles. Also using custom scopes that are lifecycle aware makes developers can designate scoped data holder on their taste.

When is useful?

When we need to hold some immutable data and it needs to be synchronized as the same data at each other components. For example, there is Activity A, Activity B, Activity C. And we need to use the same data in all Activity A~C that can be changed. Then we should pass a parcelable data A to B and B to C and getting the changed data reversely through onActivityResult.

Then how about the communication with fragments? We can solve it by implementing an interface, singleton pattern, observer pattern or etc, but the data flow would be quite complicated. Chamber helps to simplify those communications between Chamber scope owners.

Including in your project

Gradle

Add below codes to your root build.gradle file (not your module build.gradle file).

allprojects {
    repositories {
        mavenCentral()
    }
}

And add a dependency code to your module's build.gradle file.

dependencies {
    implementation "com.github.skydoves:chamber:1.0.3"
}

SNAPSHOT

Snapshots of the current development version of Chamber are available, which track the latest versions.

repositories {
   maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }
}

Usage

Chamber is a lightweight lifecycle-aware pipeline based on scopes.

ChamberScope

The basic usage is creating a customized scope annotation using a @ChamberScope annotation.
@ChamberScope is used to build custom scopes that are lifecycle aware. Each scope will be used as a pipeline via ChamberProperty and it will be managed by the lifecycle stack. It should be annotated on classes (activity, fragment, repository, or any classes) that has ChamberProperty fields.

@ChamberScope
@Retention(AnnotationRetention.RUNTIME)
annotation class UserScope

ChamberProperty

ChamberProperty is an interactive class to the internal Chamber data holder and a lifecycleObserver that can be observable. It should be used with @ShareProperty annotation that has a key name. If we want to use the same synchronized value on the same custom scope in different classes, we should use the same key.

@ShareProperty(key = "name") // name is a key name.
private var username = ChamberProperty("skydoves") // ChamberProperty can be initialized with any object.

setValue

Using the setValue method, we can change the ChamberProperty's value.

username.value = "user name is changed"

postValue

Posts a task to a main thread to set the given value. So if you have a following code executed in the main thread:

username.postValue("a")
username.value = "b"

The value b would be set at first and later the main thread would override it with the value a.
If you called this method multiple times before a main thread executed a posted task, only the last value would be dispatched.

observe

We can observe the value is changed using the observe method. There is only one observer that can be registered on the property. The events are dispatched on the main thread. If ChamberProperty already has data set, it will be delivered to the observer.

username.observe { 
  log("data is changed to $it")
}

ShareLifecycle

Chamber synchronizes and dispatches ChamberPropertys that are included in the same scope and had the same key thread-safety. We should pass two arguments; scopeOwner that is annotated with a custom scope, lifecycleOwner that manages ChamberPropertys lifecycles for destroying. Here is an example of MainActivity and SecondActivity.

MainActivity

If Chamber.shareLifecycle method is called, the name property that has nickname key will be managed by Chamber and Chamber will observe the MainActivity's lifecycle state.

@UserScope // custom scope
class MainActivity : AppCompatActivity() {

  @ShareProperty(key = "nickname")
  private var name = ChamberProperty("skydoves")

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    Chamber.shareLifecycle(scopeOwner = this, lifecycleOwner = this)

    name.observe { log($it) }

    name.value = "name value is changed"

    startActivity(SecondActivity::class.java)
  }
}

[output]:
=> skydoves
=> name value is changed

MainActivity -> SecondActivity

MainActivity starts SecondActivity using startActivity.
Chamber will observe the SecondActivity's lifecycle state. And the name property's value on the
SecondActivity will be synchronized by Chamber when shareLifecycle method is called.

@UserScope
class SecondActivity : AppCompatActivity() {

  @ShareProperty(key = "nickname")
  private var name = ChamberProperty("skydoves")

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_second)

    Chamber.shareLifecycle(scopeOwner = this, lifecycleOwner = this)

    name.observe { log($it) }

    name.value = "changed in SecondActivity"
  }
}

[output]:
=> name value is changed
=> changed in SecondActivity

The process of exiting scope

SeondActivity -> MainActivity

Following the about example, what if we call the finish() method in SecondActivity and we come back to the MainActivity.
when SecondActivity's lifecycle state is onDestroy, Chamber will not manage anymore with the SecondActivity's ChamberProperty and not observe lifecycle state.
And when MainActivity's lifecycle state is onResume, Chamber will dispatch the ChamberProperty's value in MainActivity.

@UserScope
class MainActivity : AppCompatActivity() {

  @ShareProperty(key = "nickname")
  private var name = ChamberProperty("skydoves")

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_second)

    Chamber.shareLifecycle(scopeOwner = this, lifecycleOwner = this)

    name.observe { log($it) }

    name.value = "name value is changed"

    startActivity(SecondActivity::class.java)
  }
}

[output]:
=> changed in SecondActivity

Destroying a scope

After all lifecycle owners are destroyed (All lifecycleOwners are popped from the Chamber's lifecycle stack), all of the custom scope data will be cleared in the internal Chamber.

Usage with ViewModel

Architecturally, UI components should do work relate to UI works.
So we can delegate the scope owner to other classes.

@UserScope // custom scope
class MainActivityViewModel : ViewModel() {

  @ShareProperty(key = UserScope.nickname)
  var username = ChamberProperty("skydoves")

  @PropertyObserver(key = UserScope.nickname)
  fun usernameObserver(value: String) {
    Log.d("MainActivityViewModel", "usernameObserver: $value")
  }
}

class MainActivity : AppCompatActivity() {

  private val viewModel = MainActivityViewModel()

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    Chamber.shareLifecycle(scopeOwner = viewModel, lifecycleOwner = this)
}

PropertyObserver

PropertyObserver annotation used to observe value changes by ChamberProperty that has the same key value. This annotation only works with a method that in a scoped class. A method that is annotated with PropertyObserver will be invoked, whenever the value changes and receive the value as a parameter. The method must have one parameter and the type must same as the generic of the ChamberProperty.

Here is an example of usages in a ViewModel.

@UserScope // custom scope
class MainActivityViewModel : ViewModel() {

  @ShareProperty(key = UserScope.nickname)
  var username = ChamberProperty("skydoves")

  @PropertyObserver(key = UserScope.nickname)
  fun usernameObserver(value: String) {
    Log.d("MainActivityViewModel", "usernameObserver: $value")
  }
}

Here is an example of usages in an Activity.

@UserScope
class MainActivity : AppCompatActivity() {

  @ShareProperty(key = UserScope.nickname)
  private var username = chamberProperty("skydoves")

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    shareLifecycle()

    username.observe { Log.d("SecondActivity", "observed data: $it") }

    username.value = "skydoves on SecondActivity"
  }

  @PropertyObserver(key = UserScope.nickname)
  fun nickNameObserver(nickname: String) {
    Log.d("MainActivity", "nickNameObserver: $nickname")
  }
}

Find this library useful? ❤️

Support it by joining stargazers for this repository. ⭐

Design License

I designed flowcharts using UXFlow, it is following Attribution 4.0 International (CC BY 4.0).

License

Copyright 2019 skydoves (Jaewoong Eum)

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.