nakamuuu / retainer

An Android library that helps you retain objects in an Activity / Fragment during configuration changes.

Retainer

Retainer is an Android library that helps you retain objects in an Activity / Fragment during configuration changes.

It auto-generates container objects by using annotation processing, and this objects will be internally preserved in a Fragment. setRetainInstance(true) is called for this fragment, so that stateful objects are preserved during configuration changes.

If you need more information about the handling of configuration changes, check the following document.

https://developer.android.com/guide/topics/resources/runtime-changes.html

NOTE: When your activity or application process have been destroyed, Fragment in which setRetainInstance(true) is called is also destroyed. Therefore, this approach doesn't replace the method using onSaveInstanceState().

How to use

Retainer also provides you static methods that bundle a procedure related to Fragment's lifecycle. So you can simply retain objects by following the steps and examples below.

1. Add @Retain to a field you want to retain.
2. Call Retainer.bind(this) in your activity or fragment.

IMPORTANT: You should never add @Retain to an object that is tied to the activity context, such as a Drawable, an Adapter, or a View. If you do, it will cause serious memory leaks.

Activity

Supports only androidx.fragment.app.FragmentActivity or its subclasses.

import net.divlight.retainer.Retainer;
import net.divlight.retainer.annotation.Retain;

public class ExampleActivity extends AppCompatActivity {
    // This field will be automatically preserved by Retainer.
    @Retain
    int retainedValue;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Retainer.bind(this);
    }
}

Fragment

Supports only androidx.fragment.app.Fragment or its subclasses.

import net.divlight.retainer.Retainer;
import net.divlight.retainer.annotation.Retain;

public class ExampleFragment extends Fragment {
    // This field will be automatically preserved by Retainer.
    @Retain
    int retainedValue;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Retainer.bind(this);
    }
}

Download

Gradle

Add it in your root build.gradle at the end of repositories:

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

Add the dependency in your module's build.gradle:

implementation "com.github.nakamuuu.retainer:library:${latest_version}"
annotationProcessor "com.github.nakamuuu.retainer:processor:${latest_version}"

Requirements

Android 4.0.3+ (API Level: 15+)

License

Copyright 2017 Keita Nakamura

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.

retainer's Issues

IllegalStateException occurs when used in Fragment

Fatal Exception: java.lang.IllegalStateException: Can not perform this action after onSaveInstanceState
       at android.support.v4.app.FragmentManagerImpl.checkStateLoss(FragmentManager.java:1842)
       at android.support.v4.app.FragmentManagerImpl.enqueueAction(FragmentManager.java:1860)
       at android.support.v4.app.BackStackRecord.commitInternal(BackStackRecord.java:649)
       at android.support.v4.app.BackStackRecord.commit(BackStackRecord.java:609)
       at net.divlight.retainer.Retainer.onCreate(Retainer.java:31)

It should be modified to use FragmentTransaction#commitAllowingStateLoss() instead of commit().
RetainerFragment has no fields saved by using onSavedInstanceState() . So It seems that this change won't cause any side effects 🤔

The generated object's name may be improper

Example

public class TestActivity {
   public class InnerClass1 {
        public class InnerClass2 {
            @Retain int value;
        }
   }
}

The auto-generated object name is expected to TestActivity$InnerClass1$InnerClass2_Retainer , but the actual is InnerClass1$TestActivity$InnerClass2_Retainer 😢

AndroidX Support

https://developer.android.com/jetpack/androidx/migrate

Package name is misspelled in ProGuard configuration

net.divlight.retainer.annotations.Retain
↓
net.divlight.retainer.annotation.Retain

https://github.com/nakamuuu/retainer/blob/master/library/proguard-rules.pro#L4

Restored uninitialized objects after the activity is killed

After the activity is killed, added fragment's instance will be recreated. Currently, this lifecycle don't cared in a following code. So it will restore uninitialized objects.
https://github.com/nakamuuu/retainer/blob/0.1.0/library/src/main/android/net/divlight/retainer/Retainer.java#L27