ARCHIVED

This repository is archived. No more development will be taking place.

Lyra is an open source library for Android that simplifies the save and the restore of Android components' state. Lyra supports automatic save/restore, base coders to serialize/deserialize values in Bundle, caching and retrieval of fields. Lyra includes a flexible API that allows developers to customize any aforementioned behavior.

By default, Lyra uses an internal serializer/deserializer for fields, but also provides a utility library to add serialization/deserialization capabilities of Gson.

Integration

You can download a jar from GitHub's releases page or grab it from jcenter() or mavenCentral(). You can optionally use the dependency lyra-coder-gson if you want to include the Gson coder.

Gradle

dependencies {
    compile 'com.github.fondesa:lyra:1.0.1'
    // Use this dependency if you want to include the Gson coder.
    compile 'com.github.fondesa:lyra-coder-gson:1.0.1'
}

Maven

<dependency>
  <groupId>com.github.fondesa</groupId>
  <artifactId>lyra</artifactId>
  <version>1.0.1</version>
  <type>pom</type>
</dependency>

ProGuard

If you are using ProGuard, you need to include the following lines to your proguard configuration file.

-keepclassmembers class * implements com.fondesa.lyra.coder.StateCoder {
    <init>(...);
}
-keepclassmembers class ** {
    @com.fondesa.lyra.annotation.SaveState <fields>;
}

Usage

You have to initialize the Lyra instance in your Application. You can use the short version with only required options:

@Override
public void onCreate() {
    super.onCreate();
    // Pass the Application's Context to the instance.
    Lyra.with(this).build();
}

Or the full version to customize each component:

@Override
public void onCreate() {
    super.onCreate();
    // Create the builder and pass the Application's Context.
    Lyra.Builder builder = Lyra.with(this)
            // Optional, the default is: DefaultCoderRetriever.
            .coderRetriever(new CustomCoderRetriver())
            // Optional, the default is: DefaultFieldsRetriever.
            .fieldsRetriever(new CustomFieldsRetriever());
    
    // Automatic save state is available only above api 14.
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH) {
        // Optional, the default will not save the state of the Activities automatically.
        builder.autoSaveActivities();
    }
    // Build the instance.
    builder.build();
}

You have to annotate the fields that you want to save with the annotation @SaveState and, if needed, you have to call the methods saveState() and restoreState():

public class MainActivity extends Activity {
    @SaveState
    private int mCount;

    @SaveState
    ParcelableModel mModel;

    // If you want to use a custom coder, you can specify the class.
    @SaveState(CustomStringCoder.class)
    private String mText;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        /* Necessary only if you aren't in an Activity or you 
        haven't specified to auto save Activities in the Lyra instance. */
        Lyra.instance().restoreState(this, savedInstanceState);
    }
    
    @Override
    protected void onSaveInstanceState(Bundle outState) {
        super.onSaveInstanceState(outState);
        /* Necessary only if you aren't in an Activity or you 
        haven't specified to auto save Activities in the Lyra instance. */
        Lyra.instance().saveState(this, outState);
    }
}

The save/restore of the state is supported also in a custom View. For example:

public class AutoSaveEditText extends AppCompatEditText {
    @SaveState
    CharSequence mText;

    @Override
    public Parcelable onSaveInstanceState() {
        return Lyra.instance().saveState(this, super.onSaveInstanceState());
    }

    @Override
    public void onRestoreInstanceState(Parcelable state) {
        super.onRestoreInstanceState(Lyra.instance().restoreState(this, state));
    }
}

As shown above, you can create your own custom StateCoder. For example, this coder will save/restore a String in Base64:

public class CustomStringCoder implements StateCoder<String> {
    @Override
    public void serialize(@NonNull Bundle state, @NonNull String key, @NonNull String fieldValue) {
        try {
            byte[] data = fieldValue.getBytes("UTF-8");
            String base64 = Base64.encodeToString(data, Base64.DEFAULT);
            state.putString(key, base64);
        } catch (UnsupportedEncodingException ignored) {}
    }

    @Override
    public String deserialize(@NonNull Bundle state, @NonNull String key) {
        String base64 = state.getString(key);
        if (base64 == null)
            return null;
            
        byte[] data = Base64.decode(base64, Base64.DEFAULT);
        try {
            return new String(data, "UTF-8");
        } catch (UnsupportedEncodingException ignored) {
            return null;
        }
    }
}

Compatibility

Android SDK: Lyra requires a minimum API level of 9.