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.