{"id":13604544,"url":"https://github.com/livefront/bridge","last_synced_at":"2025-04-12T02:30:53.654Z","repository":{"id":52782250,"uuid":"94903404","full_name":"livefront/bridge","owner":"livefront","description":"An Android library for avoiding TransactionTooLargeException during state saving and restoration","archived":false,"fork":false,"pushed_at":"2023-06-23T14:27:04.000Z","size":277,"stargazers_count":257,"open_issues_count":5,"forks_count":25,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-11-07T09:43:02.398Z","etag":null,"topics":["android","state-restoration","state-saving"],"latest_commit_sha":null,"homepage":"","language":"Java","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/livefront.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-06-20T14:58:32.000Z","updated_at":"2024-07-21T13:35:48.000Z","dependencies_parsed_at":"2024-01-16T23:30:05.693Z","dependency_job_id":"cb142fdb-70f1-4724-a99f-87dda584f3fc","html_url":"https://github.com/livefront/bridge","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/livefront%2Fbridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/livefront%2Fbridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/livefront%2Fbridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/livefront%2Fbridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/livefront","download_url":"https://codeload.github.com/livefront/bridge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248506901,"owners_count":21115503,"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","state-restoration","state-saving"],"created_at":"2024-08-01T19:00:47.578Z","updated_at":"2025-04-12T02:30:53.243Z","avatar_url":"https://github.com/livefront.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# Bridge\n\n![CI-Status](https://github.com/livefront/bridge/workflows/CI/badge.svg)\n[![Release](https://jitpack.io/v/Livefront/bridge.svg)](https://jitpack.io/#Livefront/bridge)\n\nA library for avoiding TransactionTooLargeException during state saving and restoration.\n\n## Contents\n\n* [Motivation](#motivation)\n* [Setup](#setup)\n* [Clearing Data](#clear)\n* [Bridge for Views](#views)\n* [Install](#install)\n* [How Does It Work](#how)\n* [Limitations](#limitations)\n* [Testing](#testing)\n* [License](#license)\n* [Javadoc](https://jitpack.io/com/github/livefront/bridge/v2.0.2/javadoc/index.html)\n\n\u003ca name=\"motivation\"\u003e\u003c/a\u003e\n## Motivation\n\nIn spite of warnings from the Android development team stating that the state restoration framework should only be used for small amounts of view-related data, many developers have found it very useful to save large amounts of network-related data to avoid unnecessary network requests across configuration changes and when restoring from a background state. There was always a limitation to this, but that limit resulted in a silent failure to save state. In Android Nougat, that was upgraded to a crash via a [TransactionTooLargeException](https://developer.android.com/reference/android/os/TransactionTooLargeException.html).\n\nAt Google I/O 2017, the Android development team gave a series of recommendations about app architecture that made clear that---rather than relying on the state restoration framework---the preferred method to save network data involves:\n\n- saving and restoring data from memory across configuration changes\n- saving and restoring data from disk when restoring from a background state\n\nWhile new tools are available to achieve these goals, many developers will not be able to quickly update their apps to take advantage of them and will still face the dreaded `TransactionTooLargeException`. `Bridge` was created as a way to keep your existing app architecture in place while avoiding crashes related to state saving and restoration by following those two main principles.\n\n\u003ca name=\"setup\"\u003e\u003c/a\u003e\n## Setup\n\n`Bridge` is intended as a simple wrapper for annotation-based state saving libraries like [Icepick](https://github.com/frankiesardo/icepick), [Android-State](https://github.com/evernote/android-state), and [Icekick](https://github.com/tinsukE/icekick). For example, if you are already using `Icepick`, simply replace all calls to `Icepick.restoreInstanceState()` and `Icepick.saveInstanceState()` with their `Bridge` equivalents:\n\n```java\n@Override\nprotected void onCreate(Bundle savedInstanceState) {\n    super.onCreate(savedInstanceState);\n    Bridge.restoreInstanceState(this, savedInstanceState);\n}\n\n@Override\nprotected void onSaveInstanceState(Bundle outState) {\n    super.onSaveInstanceState(outState);\n    Bridge.saveInstanceState(this, outState);\n}\n```\n\nThe only additional change to make is to initialize `Bridge` in your `Application.onCreate()` and specify `Icepick` as your \"saved state handler\":\n\n```java\nBridge.initialize(getApplicationContext(), new SavedStateHandler() {\n    @Override\n    public void saveInstanceState(@NonNull Object target, @NonNull Bundle state) {\n        Icepick.saveInstanceState(target, state);\n    }\n\n    @Override\n    public void restoreInstanceState(@NonNull Object target, @Nullable Bundle state) {\n        Icepick.restoreInstanceState(target, state);\n    }\n});\n```\n\nThat's it! You don't have to change any of your other code. If you are using any other `Icepick`-like library, simply swap out the library referred to in the `SavedStateHandler`.\n\nNote that if you use the [Android-State](https://github.com/evernote/android-state) library as your `SavedStateHandler`, do **not** use the global settings by calling `StateSaver.setEnabledForAllActivitiesAndSupportFragments(this, true)`; failure to omit this will defeat the purpose of using `Bridge` and you will still see `TransactionTooLargeException` in your application.\n\n\u003ca name=\"clear\"\u003e\u003c/a\u003e\n## Clearing Data\n\nBridge will clear all data written to disk each time the app is loaded and it detects that there is no saved state the system is trying to restore. It is recommended, however, to also manually clear data for objects that will no longer be needed, such as an `Activity` the user has finished. For this purpose, the `Bridge.clear()` method may be used:\n\n```java\n    @Override\n    public void onDestroy() {\n        super.onDestroy();\n        Bridge.clear(this);\n    }\n```\n\nThis method is typically safe to call without any additional logic, as it will only clear data when the current `Activity` is not undergoing a configuration change. Note that in some unique cases (such as when using a `FragmentStatePagerAdapter`) the OS will \"destroy\" a `Fragment` but retain its saved state `Bundle` in case it needs to reconstruct that `Fragment` from scratch later. In these cases calls to `Bridge.clear()` should be omitted.\n\nIn the event that you might like to migrate away from the use of `Bridge` but ensure that all associated data is cleared, `Bridge.clearAll` may be called at any time.\n\n\u003ca name=\"views\"\u003e\u003c/a\u003e\n## Bridge for Views\n\nIn addition to `Activity`, `Fragment`, presenter, etc. classes, `Bridge` can also be used to assist in saving the state of `View` classes using `View`-specific save and restore methods :\n\n```java\n    @Override\n    protected Parcelable onSaveInstanceState() {\n        return Bridge.saveInstanceState(this, super.onSaveInstanceState());\n    }\n\n    @Override\n    protected void onRestoreInstanceState(Parcelable state) {\n        super.onRestoreInstanceState(Bridge.restoreInstanceState(this, state));\n    }\n```\n\nIn order to enable this ability, a `ViewSavedStateHandler` must be passed to the `Bridge.initialize` method. For example:\n\n```java\n        Bridge.initialize(\n                getApplicationContext(),\n                new SavedStateHandler() {\n                    ...\n                },\n                new ViewSavedStateHandler() {\n                    @NonNull\n                    @Override\n                    public \u003cT extends View\u003e Parcelable saveInstanceState(\n                            @NonNull T target,\n                            @Nullable Parcelable parentState) {\n                        return Icepick.saveInstanceState(target, parentState);\n                    }\n\n                    @Nullable\n                    @Override\n                    public \u003cT extends View\u003e Parcelable restoreInstanceState(\n                            @NonNull T target,\n                            @Nullable Parcelable state) {\n                        return Icepick.restoreInstanceState(target, state);\n                    }\n                });\n```\n\n\u003ca name=\"install\"\u003e\u003c/a\u003e\n## Install\n\n`Bridge` can be installed via gradle:\n\n```gradle\nrepositories {\n    maven { url \"https://jitpack.io\" }\n}\n\ndependencies {\n    implementation 'com.github.livefront:bridge:v2.0.2'\n}\n```\n\n\u003ca name=\"how\"\u003e\u003c/a\u003e\n## How Does It Work\n\n`Bridge` uses the `SavedStateHandler` to load your object's state into the given `Bundle`, but rather than send that `Bundle` to the main process of the OS (where it is subject to the `TransactionTooLargeException`) it saves it to memory and disk in a way that can restored to the same objects later.\n\nThere is one main caveat here : in order to ensure that as little of your app's code needs to change as possible, `Bridge` will read its data from disk on the main thread. This is currently done in a way that may add a small amount of time to your app's startup process. Fortunately, `Bridge` leverages the compact nature of `Bundle` to store data as efficiently as possible, and even extremely large amounts of data well in excess of the `1MB` limit leading to `TransactionTooLargeException` should only add something on the order of 100ms to the startup time.\n\n\u003ca name=\"testing\"\u003e\u003c/a\u003e\n## Testing\n\nTypically state saving and restoration may be tested by simply testing device rotation. It is recommended that you also use tools that actually test full state restoration however, such as [Process Killer](https://github.com/livefront/process-killer-android) or the \"Don't Keep Activities\" developer option.\n\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n## License\n\n    Copyright 2017 Livefront\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flivefront%2Fbridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flivefront%2Fbridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flivefront%2Fbridge/lists"}