Initial commit

.gitignore

@@ -0,0 +1,16 @@
+.classpath
+.DS_Store
+.gradle
+.idea
+.project
+bin
+build
+captures
+gen
+local.properties
+
+*.apk
+*.ap_
+*.class
+*.dex
+*.iml

CHANGELOG.md

@@ -0,0 +1,7 @@
+Change Log
+==========
+
+Version 1.0.0 *(2017-06-22)*
+----------------------------
+
+Initial release.

README.md

@@ -0,0 +1,111 @@
+# Bridge
+
+A library for avoiding TransactionTooLargeException during state saving and restoration.
+
+## Contents
+
+* [Motivation](#motivation)
+* [Setup](#setup)
+* [Install](#install)
+* [How Does It Work](#how)
+* [Limitations](#limitations)
+* [Testing](#testing)
+* [License](#license)
+
+<a name="motivation"></a>
+## Motivation
+
+In 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).
+
+At 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:
+
+- saving and restoring data from memory across configuration changes
+- saving and restoring data from disk when restoring from a background state
+
+While 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.
+
+<a name="setup"></a>
+## Setup
+
+`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:
+
+```java
+@Override
+protected void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+    Bridge.restoreInstanceState(this, savedInstanceState);
+}
+
+@Override
+protected void onSaveInstanceState(Bundle outState) {
+    super.onSaveInstanceState(outState);
+    Bridge.saveInstanceState(this, outState);
+}
+```
+
+The only additional change to make is to initialize `Bridge` in your `Application.onCreate()` and specify `Icepick` as your "saved state handler":
+
+```java
+Bridge.initialize(getApplicationContext(), new SavedStateHandler() {
+    @Override
+    public void saveInstanceState(@NonNull Object target, @NonNull Bundle state) {
+        Icepick.saveInstanceState(target, state);
+    }
+
+    @Override
+    public void restoreInstanceState(@NonNull Object target, @Nullable Bundle state) {
+        Icepick.restoreInstanceState(target, state);
+    }
+});
+```
+
+That'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`.
+
+<a name="install"></a>
+## Install
+
+`Bridge` can be installed via gradle:
+
+```gradle
+repositories {
+    maven { url "https://jitpack.io" }
+}
+
+dependencies {
+    compile 'com.github.livefront:bridge:v1.0.0'
+}
+```
+
+<a name="how"></a>
+## How Does It Work
+
+`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.
+
+There 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.
+
+<a name="limitations"></a>
+## Limitations
+
+Trying to save a `Bitmap` with `Bridge` will result in a crash, as their `Parcelable` implementation is highly optimized in a way that prevents `Bridge` from writing them to disk.
+
+<a name="testing"></a>
+## Testing
+
+Typically 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.
+
+<a name="license"></a>
+## License
+
+    Copyright 2017 Livefront
+
+    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.

bridge/.gitignore

@@ -0,0 +1 @@
+/build

bridge/build.gradle

@@ -0,0 +1,24 @@
+apply plugin: 'com.android.library'
+
+android {
+    compileSdkVersion 25
+    buildToolsVersion "25.0.2"
+    defaultConfig {
+        minSdkVersion 12
+        targetSdkVersion 25
+        versionCode 1
+        versionName "1.0.0"
+        testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+}
+
+dependencies {
+    compile fileTree(dir: 'libs', include: ['*.jar'])
+    compile 'com.android.support:appcompat-v7:25.3.1'
+}

bridge/proguard-rules.pro

@@ -0,0 +1,25 @@
+# Add project specific ProGuard rules here.
+# By default, the flags in this file are appended to flags specified
+# in /Users/brianyencho/Library/Android/sdk/tools/proguard/proguard-android.txt
+# You can edit the include path and order by changing the proguardFiles
+# directive in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# Add any project specific keep options here:
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile

bridge/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest package="com.livefront.bridge"/>

bridge/src/main/java/com/livefront/bridge/Bridge.java

@@ -0,0 +1,57 @@
+package com.livefront.bridge;
+
+import android.content.Context;
+import android.os.Bundle;
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
+
+public class Bridge {
+
+    private static BridgeDelegate sDelegate;
+
+    private static void checkInitialization() {
+        if (sDelegate == null) {
+            throw new IllegalStateException(
+                    "You must first call initialize before calling any other methods");
+        }
+    }
+
+    /**
+     * Initializes the framework used to save and restore data and route it to a location free from
+     * {@link android.os.TransactionTooLargeException}. The actual state saving and restoration
+     * of each object will be performed by the provided {@link SavedStateHandler}.
+     *
+     * @param context           an application {@link Context} necessary for saving state to disk
+     * @param savedStateHandler used to do the actual state saving and restoring for a given object
+     */
+    public static void initialize(@NonNull Context context,
+                                  @NonNull SavedStateHandler savedStateHandler) {
+        sDelegate = new BridgeDelegate(context, savedStateHandler);
+    }
+
+    /**
+     * Restores the state of the given target object based on tracking information stored in the
+     * given {@link Bundle}. The actual saved data will be retrieved from a location in memory or
+     * stored on disk.
+     * <p>
+     * It is required to call {@link #initialize(Context, SavedStateHandler)} before calling this
+     * method.
+     */
+    public static void restoreInstanceState(@NonNull Object target, @Nullable Bundle state) {
+        checkInitialization();
+        sDelegate.restoreInstanceStateInternal(target, state);
+    }
+
+    /**
+     * Saves the state of the given target object to a location in memory and disk and stores
+     * tracking information in given {@link Bundle}.
+     * <p>
+     * It is required to call {@link #initialize(Context, SavedStateHandler)} before calling this
+     * method.
+     */
+    public static void saveInstanceState(@NonNull Object target, @NonNull Bundle state) {
+        checkInitialization();
+        sDelegate.saveInstanceStateInternal(target, state);
+    }
+
+}

bridge/src/main/java/com/livefront/bridge/BridgeDelegate.java

@@ -0,0 +1,118 @@
+package com.livefront.bridge;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.os.Bundle;
+import android.os.Parcel;
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
+import android.util.Base64;
+import android.view.View;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.UUID;
+import java.util.WeakHashMap;
+
+class BridgeDelegate {
+
+    private static final String TAG = BridgeDelegate.class.getName();
+
+    private static final String KEY_BUNDLE = "bundle_%s";
+    private static final String KEY_UUID = "uuid_%s";
+
+    private boolean mIsFirstRestoreCall = true;
+    private Map<String, Bundle> mUuidBundleMap = new HashMap<>();
+    private Map<Object, String> mObjectUuidMap = new WeakHashMap<>();
+    private SavedStateHandler mSavedStateHandler;
+    private SharedPreferences mSharedPreferences;
+
+    BridgeDelegate(@NonNull Context context,
+                   @NonNull SavedStateHandler savedStateHandler) {
+        mSharedPreferences = context.getSharedPreferences(TAG, Context.MODE_PRIVATE);
+        mSavedStateHandler = savedStateHandler;
+    }
+
+    private String getKeyForEncodedBundle(@NonNull String uuid) {
+        return String.format(KEY_BUNDLE, uuid);
+    }
+
+    private String getKeyForUuid(@NonNull Object target) {
+        String classId = target.getClass().getName();
+        if (target instanceof View) {
+            classId += ((View) target).getId();
+        }
+        return String.format(KEY_UUID, classId);
+    }
+
+    @Nullable
+    private Bundle readFromDisk(@NonNull String uuid) {
+        String encodedString = mSharedPreferences.getString(getKeyForEncodedBundle(uuid), null);
+        if (encodedString == null) {
+            return null;
+        }
+        byte[] parcelBytes = Base64.decode(encodedString, 0);
+        Parcel parcel = Parcel.obtain();
+        parcel.unmarshall(parcelBytes, 0, parcelBytes.length);
+        parcel.setDataPosition(0);
+        Bundle bundle = parcel.readBundle(BridgeDelegate.class.getClassLoader());
+        parcel.recycle();
+        return bundle;
+    }
+
+    void restoreInstanceStateInternal(@NonNull Object target, @Nullable Bundle state) {
+        boolean isFirstRestoreCall = mIsFirstRestoreCall;
+        mIsFirstRestoreCall = false;
+        if (state == null) {
+            if (isFirstRestoreCall) {
+                mSharedPreferences.edit()
+                        .clear()
+                        .apply();
+            }
+            return;
+        }
+        String uuid = mObjectUuidMap.containsKey(target)
+                ? mObjectUuidMap.get(target)
+                : state.getString(getKeyForUuid(target), null);
+        if (uuid == null) {
+            return;
+        }
+        mObjectUuidMap.put(target, uuid);
+        Bundle bundle = mUuidBundleMap.containsKey(uuid)
+                ? mUuidBundleMap.get(uuid)
+                : readFromDisk(uuid);
+        if (bundle == null) {
+            return;
+        }
+        mSavedStateHandler.restoreInstanceState(target, bundle);
+    }
+
+    void saveInstanceStateInternal(@NonNull Object target, @NonNull Bundle state) {
+        String uuid = mObjectUuidMap.get(target);
+        if (uuid == null) {
+            uuid = UUID.randomUUID().toString();
+            mObjectUuidMap.put(target, uuid);
+        }
+        state.putString(getKeyForUuid(target), uuid);
+        Bundle bundle = new Bundle();
+        mSavedStateHandler.saveInstanceState(target, bundle);
+        if (bundle.isEmpty()) {
+            // Don't bother saving empty bundles
+            return;
+        }
+        mUuidBundleMap.put(uuid, bundle);
+        writeToDisk(uuid, bundle);
+    }
+
+    private void writeToDisk(@NonNull String uuid,
+                             @NonNull Bundle bundle) {
+        Parcel parcel = Parcel.obtain();
+        parcel.writeBundle(bundle);
+        String encodedString = Base64.encodeToString(parcel.marshall(), 0);
+        mSharedPreferences.edit()
+                .putString(getKeyForEncodedBundle(uuid), encodedString)
+                .apply();
+        parcel.recycle();
+    }
+
+}

bridge/src/main/java/com/livefront/bridge/SavedStateHandler.java

@@ -0,0 +1,13 @@
+package com.livefront.bridge;
+
+import android.os.Bundle;
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
+
+public interface SavedStateHandler {
+
+    void saveInstanceState(@NonNull Object target, @NonNull Bundle state);
+
+    void restoreInstanceState(@NonNull Object target, @Nullable Bundle state);
+
+}