{"id":15631462,"url":"https://github.com/skydoves/chamber","last_synced_at":"2025-04-13T18:40:30.331Z","repository":{"id":37715294,"uuid":"198399441","full_name":"skydoves/Chamber","owner":"skydoves","description":"⚖️ A lightweight Android lifecycle-aware and thread-safe pipeline for communicating between components with custom scopes.","archived":false,"fork":false,"pushed_at":"2021-05-17T10:50:30.000Z","size":261,"stargazers_count":187,"open_issues_count":1,"forks_count":14,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-13T04:37:45.320Z","etag":null,"topics":["android","architecture","chamber","dataflow","kotlin","lifecycle-aware","scope","skydoves"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skydoves.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null},"funding":{"github":"skydoves","custom":["https://www.paypal.me/skydoves","https://www.buymeacoffee.com/skydoves"]}},"created_at":"2019-07-23T09:36:47.000Z","updated_at":"2025-03-02T07:56:50.000Z","dependencies_parsed_at":"2022-09-26T16:20:32.392Z","dependency_job_id":null,"html_url":"https://github.com/skydoves/Chamber","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydoves%2FChamber","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydoves%2FChamber/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydoves%2FChamber/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydoves%2FChamber/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skydoves","download_url":"https://codeload.github.com/skydoves/Chamber/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248764194,"owners_count":21158040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","architecture","chamber","dataflow","kotlin","lifecycle-aware","scope","skydoves"],"created_at":"2024-10-03T10:40:30.713Z","updated_at":"2025-04-13T18:40:30.309Z","avatar_url":"https://github.com/skydoves.png","language":"Kotlin","readme":"# Chamber\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://android-arsenal.com/api?level=15\"\u003e\u003cimg alt=\"API\" src=\"https://img.shields.io/badge/API-15%2B-brightgreen.svg?style=flat\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.codacy.com/app/skydoves/Chamber?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=skydoves/Chamber\u0026amp;utm_campaign=Badge_Grade\"\u003e\u003cimg alt=\"API\" src=\"https://api.codacy.com/project/badge/Grade/ad561fa4877b4f04ac65cb5bf162ad0d\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/skydoves/Chamber/actions/workflows/android.yml\"\u003e\u003cimg alt=\"API\" src=\"https://github.com/skydoves/Chamber/actions/workflows/android.yml/badge.svg\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://androidweekly.net/issues/issue-372\"\u003e\u003cimg alt=\"Android Weekly\" src=\"https://img.shields.io/badge/Android%20Weekly-%23372-orange\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://skydoves.github.io/libraries/chamber/javadoc/chamber/index.html\"\u003e\u003cimg alt=\"API\" src=\"https://img.shields.io/badge/Javadoc-Chamber-yellow.svg\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\nA lightweight Android lifecycle-aware and thread-safe pipeline for communicating between components with custom scopes.\n\u003c/p\u003e\n\n\u003e \u003cp align=\"center\"\u003eAndroid components are essential building blocks of an Android application. \u003cbr\u003eThese independent components are very loosely coupled. The benefit is that they are really independently reusable, but it makes to hard communicate with each other. \u003c/p\u003e\n\n\u003e\u003cp align=\"center\"\u003e 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.\u003c/p\u003e\n\n## When is useful?\n\u003eWhen 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. \n\n\u003eThen 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.\n\n\u003cp align=\"center\"\u003e\n\u003cimg width=\"859\" alt=\"chamber01\" src=\"https://user-images.githubusercontent.com/24237865/61701682-86756780-ad79-11e9-9520-f6ed9003204a.png\"\u003e\n\u003c/p\u003e\n\n## Including in your project\n[![Maven Central](https://img.shields.io/maven-central/v/com.github.skydoves/chamber.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.github.skydoves%22%20AND%20a:%chamber%22)\n[![Jitpack](https://jitpack.io/v/skydoves/chamber.svg)](https://jitpack.io/#skydoves/chamber)\n\n### Gradle \nAdd below codes to your **root** `build.gradle` file (not your module build.gradle file).\n```Gradle\nallprojects {\n    repositories {\n        mavenCentral()\n    }\n}\n```\nAnd add a dependency code to your module's build.gradle file.\n```gradle\ndependencies {\n    implementation \"com.github.skydoves:chamber:1.0.3\"\n}\n```\n\n## SNAPSHOT \n[![Chamber](https://img.shields.io/static/v1?label=snapshot\u0026message=chamber\u0026logo=apache%20maven\u0026color=C71A36)](https://oss.sonatype.org/content/repositories/snapshots/com/github/skydoves/chamber/) \u003cbr\u003e\nSnapshots of the current development version of Chamber are available, which track [the latest versions](https://oss.sonatype.org/content/repositories/snapshots/com/github/skydoves/chamber/).\n```Gradle\nrepositories {\n   maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }\n}\n```\n\n## Usage\nChamber is a lightweight lifecycle-aware pipeline based on scopes.\n\n### ChamberScope\nThe basic usage is creating a customized scope annotation using a `@ChamberScope` annotation. \u003cbr\u003e\n`@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.\n\n```kotlin\n@ChamberScope\n@Retention(AnnotationRetention.RUNTIME)\nannotation class UserScope\n```\n\n### ChamberProperty\nChamberProperty is an interactive class to the internal Chamber data holder and a lifecycleObserver that can be observable.\nIt 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.\n\n```kotlin\n@ShareProperty(key = \"name\") // name is a key name.\nprivate var username = ChamberProperty(\"skydoves\") // ChamberProperty can be initialized with any object.\n```\n\n#### setValue\nUsing the `setValue` method, we can change the `ChamberProperty`'s value.\n```kotlin\nusername.value = \"user name is changed\"\n```\n#### postValue\nPosts a task to a main thread to set the given value. So if you have a following code executed in the main thread:\n```kotlin\nusername.postValue(\"a\")\nusername.value = \"b\"\n```\nThe value `b` would be set at first and later the main thread would override it with the value `a`.\u003cbr\u003e\nIf you called this method multiple times before a main thread executed a posted task, only the last value would be dispatched.\n\n#### observe\nWe 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.\n```kotlin\nusername.observe { \n  log(\"data is changed to $it\")\n}\n```\n\n### ShareLifecycle\nChamber synchronizes and dispatches `ChamberProperty`s 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 `ChamberProperty`s lifecycles for destroying. Here is an example of _MainActivity_ and _SecondActivity_.\n\n#### MainActivity\nIf `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.\n\n```kotlin\n@UserScope // custom scope\nclass MainActivity : AppCompatActivity() {\n\n  @ShareProperty(key = \"nickname\")\n  private var name = ChamberProperty(\"skydoves\")\n\n  override fun onCreate(savedInstanceState: Bundle?) {\n    super.onCreate(savedInstanceState)\n    setContentView(R.layout.activity_main)\n\n    Chamber.shareLifecycle(scopeOwner = this, lifecycleOwner = this)\n\n    name.observe { log($it) }\n\n    name.value = \"name value is changed\"\n\n    startActivity(SecondActivity::class.java)\n  }\n}\n```\n```gradle\n[output]:\n=\u003e skydoves\n=\u003e name value is changed\n```\n\n#### MainActivity -\u003e SecondActivity\n_MainActivity_ starts _SecondActivity_ using startActivity. \u003cbr\u003e__Chamber__ will observe the _SecondActivity_'s lifecycle state. And the `name` property's value on the \u003cbr\u003e_SecondActivity_ will be synchronized by __Chamber__ when `shareLifecycle` method is called.\n```kotlin\n@UserScope\nclass SecondActivity : AppCompatActivity() {\n\n  @ShareProperty(key = \"nickname\")\n  private var name = ChamberProperty(\"skydoves\")\n\n  override fun onCreate(savedInstanceState: Bundle?) {\n    super.onCreate(savedInstanceState)\n    setContentView(R.layout.activity_second)\n\n    Chamber.shareLifecycle(scopeOwner = this, lifecycleOwner = this)\n\n    name.observe { log($it) }\n\n    name.value = \"changed in SecondActivity\"\n  }\n}\n```\n```gradle\n[output]:\n=\u003e name value is changed\n=\u003e changed in SecondActivity\n```\n\n### The process of exiting scope\n\u003cp align=\"center\"\u003e\n\u003cimg width=\"859\" alt=\"chamber02\" src=\"https://user-images.githubusercontent.com/24237865/61709290-d5c39400-ad89-11e9-8008-3466280439ec.png\"\u003e\n\u003c/p\u003e\n\n#### SeondActivity -\u003e MainActivity\nFollowing the about example, what if we call the `finish()` method in _SecondActivity_ and we come back to the _MainActivity_. \u003cbr\u003ewhen _SecondActivity_'s lifecycle state is `onDestroy`, __Chamber__ will not manage anymore with the _SecondActivity_'s `ChamberProperty` and not observe lifecycle state. \u003cbr\u003eAnd when _MainActivity_'s lifecycle state is `onResume`, __Chamber__ will dispatch the `ChamberProperty`'s value in _MainActivity_.\n\n```kotlin\n@UserScope\nclass MainActivity : AppCompatActivity() {\n\n  @ShareProperty(key = \"nickname\")\n  private var name = ChamberProperty(\"skydoves\")\n\n  override fun onCreate(savedInstanceState: Bundle?) {\n    super.onCreate(savedInstanceState)\n    setContentView(R.layout.activity_second)\n\n    Chamber.shareLifecycle(scopeOwner = this, lifecycleOwner = this)\n\n    name.observe { log($it) }\n\n    name.value = \"name value is changed\"\n\n    startActivity(SecondActivity::class.java)\n  }\n}\n```\n```gradle\n[output]:\n=\u003e changed in SecondActivity\n```\n#### Destroying a scope\nAfter 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.\n\n### Usage with ViewModel\nArchitecturally, UI components should do work relate to UI works.\u003cbr\u003eSo we can delegate the scope owner to other classes.\n\n```kotlin\n@UserScope // custom scope\nclass MainActivityViewModel : ViewModel() {\n\n  @ShareProperty(key = UserScope.nickname)\n  var username = ChamberProperty(\"skydoves\")\n\n  @PropertyObserver(key = UserScope.nickname)\n  fun usernameObserver(value: String) {\n    Log.d(\"MainActivityViewModel\", \"usernameObserver: $value\")\n  }\n}\n```\n```kotlin\nclass MainActivity : AppCompatActivity() {\n\n  private val viewModel = MainActivityViewModel()\n\n  override fun onCreate(savedInstanceState: Bundle?) {\n    super.onCreate(savedInstanceState)\n\n    Chamber.shareLifecycle(scopeOwner = viewModel, lifecycleOwner = this)\n}\n```\n\n### PropertyObserver\n`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`. \u003cbr\u003e\n\nHere is an example of usages in a ViewModel.\n```kotlin\n@UserScope // custom scope\nclass MainActivityViewModel : ViewModel() {\n\n  @ShareProperty(key = UserScope.nickname)\n  var username = ChamberProperty(\"skydoves\")\n\n  @PropertyObserver(key = UserScope.nickname)\n  fun usernameObserver(value: String) {\n    Log.d(\"MainActivityViewModel\", \"usernameObserver: $value\")\n  }\n}\n```\nHere is an example of usages in an Activity.\n```kotlin\n@UserScope\nclass MainActivity : AppCompatActivity() {\n\n  @ShareProperty(key = UserScope.nickname)\n  private var username = chamberProperty(\"skydoves\")\n\n  override fun onCreate(savedInstanceState: Bundle?) {\n    super.onCreate(savedInstanceState)\n\n    shareLifecycle()\n\n    username.observe { Log.d(\"SecondActivity\", \"observed data: $it\") }\n\n    username.value = \"skydoves on SecondActivity\"\n  }\n\n  @PropertyObserver(key = UserScope.nickname)\n  fun nickNameObserver(nickname: String) {\n    Log.d(\"MainActivity\", \"nickNameObserver: $nickname\")\n  }\n}\n\n```\n\n## Find this library useful? :heart:\nSupport it by joining __[stargazers](https://github.com/skydoves/chamber/stargazers)__ for this repository. :star:\n\n## Design License\nI designed flowcharts using [UXFlow](https://uxflow.co/), it is following [Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/legalcode).\n\n# License\n```xml\nCopyright 2019 skydoves (Jaewoong Eum)\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","funding_links":["https://github.com/sponsors/skydoves","https://www.paypal.me/skydoves","https://www.buymeacoffee.com/skydoves"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskydoves%2Fchamber","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskydoves%2Fchamber","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskydoves%2Fchamber/lists"}