• Stars
    star
    862
  • Rank 52,908 (Top 2 %)
  • Language
    Java
  • License
    Eclipse Public Li...
  • Created almost 8 years ago
  • Updated about 5 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A utility library for Android to save objects in a Bundle without any boilerplate.

DEPRECATED

This library is not maintained anymore.

Android-State

A utility library for Android to save objects in a Bundle without any boilerplate. It uses an annotation processor to wire up all dependencies.

Download

Download the latest library and processor or grab via Gradle:

dependencies {
    implementation 'com.evernote:android-state:1.4.1'
    // Java only project
    annotationProcessor 'com.evernote:android-state-processor:1.4.1'

    // Kotlin with or without Java
    kapt 'com.evernote:android-state-processor:1.4.1'
}

You can read the JavaDoc here.

Usage

It's recommended to turn on a global setting in your Application class to save and restore the instance state of all activities and fragments from the support library. After that you only need to annotate your fields with @State inside of your fragments and activities. You can save any type which can be saved in a Bundle like the String, Serializable, and Parcelable data structures.

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        StateSaver.setEnabledForAllActivitiesAndSupportFragments(this, true);
    }
}

public class MainActivity extends Activity {

    @State
    public int mValue;

    // ...
}

class MainFragment : Fragment() {

    @State
    var title = "My fragment"
}

If you want to save the state of any other object or didn't turn on the global setting, then you need to use the StateSaver class for manually saving and restoring the instance state.

public class MainActivity extends Activity {

    @State
    public int mValue;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        StateSaver.restoreInstanceState(this, savedInstanceState);
    }

    @Override
    protected void onSaveInstanceState(Bundle outState) {
        super.onSaveInstanceState(outState);
        StateSaver.saveInstanceState(this, outState);
    }
}

Advanced

You can also save state in a View class.

public class TestView extends View {

    @State
    public int mState;

    public TestView(Context context) {
        super(context);
    }

    @Override
    protected Parcelable onSaveInstanceState() {
        return StateSaver.saveInstanceState(this, super.onSaveInstanceState());
    }

    @Override
    protected void onRestoreInstanceState(Parcelable state) {
        super.onRestoreInstanceState(StateSaver.restoreInstanceState(this, state));
    }
}

It is recommended that saved properties not be private. If a property is private, then a non-private getter and setter method are required. This is especially useful for Kotlin, because properties are private by default and the aforementioned methods are generated by the compiler.

If you want your getter and setter to be used rather than the field value being used directly, the field must be private.

class DemoPresenter : Presenter<DemoView>() {

    @State
    var counter = 0

    // ...
}

Of course, this also works in Java.

public class TitleUpdater {

    @State
    private String mTitle;

    public String getTitle() {
        return mTitle;
    }

    public void setTitle(String title) {
        mTitle = title;
    }
}

If you have a private field and don't want to provide a getter or setter method, then you can fallback to reflection. However, this method is not recommended.

public class ImageProcessor {

    @StateReflection
    private byte[] mImageData;

    // ...
}

A custom bundler can be useful, if a class doesn't implement the Parcelable or Serializable interface, which oftentimes happens with third party dependencies.

public class MappingProvider {

    @State(PairBundler.class)
    public Pair<String, Integer> mMapping;

    public static final class PairBundler implements Bundler<Pair<String, Integer>> {
        @Override
        public void put(@NonNull String key, @NonNull Pair<String, Integer> value, @NonNull Bundle bundle) {
            bundle.putString(key + "first", value.first);
            bundle.putInt(key + "second", value.second);
        }

        @Nullable
        @Override
        public Pair<String, Integer> get(@NonNull String key, @NonNull Bundle bundle) {
            if (bundle.containsKey(key + "first")) {
                return new Pair<>(bundle.getString(key + "first"), bundle.getInt(key + "second"));
            } else {
                return null;
            }
        }
    }
}

Lint

The library comes with Lint rules to verify a correct usage of the library. The lint checks work in Java and Kotlin files.

ProGuard

This library comes with a ProGuard config. No further steps are required, but all necessary rules can be found here.

This library is based on Icepick, a great library from Frankie Sardo. However, Icepick is missing some features important to us: it doesn't support properties which is a bummer for Kotlin. Also, Icepick does not support private fields which may break encapsulation. A tool shouldn't force you into this direction.

Since Icepick is implemented in Clojure, we decided that it's better for us to rewrite the annotation processor in Java. Unfortunately, that makes it hard to push our features into Icepick itself. That's why we decided to fork the project.

There are also alternatives for Kotlin like IceKick. We did not want to use two libraries to solve the same problem for two different languages; we wanted to have one solution for all scenarios.

Upgrading to this library from Icepick is easy. The API is the same; only the packages and the class name (i.e. from Icepick to StateSaver) have changed. If Icepick works well for you, then there's no need to upgrade.

License

Copyright (c) 2017 Evernote Corporation.
All rights reserved. This program and the accompanying materials
are made available under the terms of the Eclipse Public License v1.0
which accompanies this distribution, and is available at

http://www.eclipse.org/legal/epl-v10.html

Files produced by Android-State code generator are not subject to terms
of the Eclipse Public License 1.0 and can be used as set out in the
copyright notice included in the generated files.

More Repositories

1

android-job

Android library to handle jobs in the background.
Java
5,373
star
2

evernote-sdk-python

Evernote SDK for Python
Python
612
star
3

evernote-sdk-js

Evernote SDK for JavaScript
JavaScript
561
star
4

evernote-sdk-android

Evernote SDK for Android
Java
429
star
5

evernote-sdk-ios

Evernote SDK for iOS
Objective-C
398
star
6

evernote-sdk-python3

Testing the Evernote Cloud API for Python 3
Python
276
star
7

evernote-sdk-java

Evernote SDK for Java
Java
259
star
8

evernote-cloud-sdk-ios

Evernote Cloud SDK for iOS
Objective-C
256
star
9

evernote-sdk-php

Evernote SDK for PHP
PHP
248
star
10

serge

Continuous localization platform
Perl
231
star
11

evernote-sdk-ruby

Evernote SDK for Ruby
Ruby
163
star
12

evernote-cloud-sdk-php

PHP
149
star
13

evernote-sdk-csharp

Evernote SDK for C#
C#
125
star
14

evernote-thrift

Thrift IDL files for the Evernote Cloud API
Thrift
96
star
15

evernote-sdk-mac

Evernote SDK for Cocoa
Objective-C
89
star
16

evernote-sdk-cpp

Evernote SDK for C++
C++
78
star
17

evernote-cloud-sdk-windows

C#
78
star
18

evernote-oauth-ruby

Evernote OAuth / Thrift API client library for Ruby
Ruby
74
star
19

zing

Translation server for continuous localization.
Python
57
star
20

android-intent

A simple to use library for Android which helps to connect to the main Android app with Intents.
Java
42
star
21

evernote-sdk-as3

Evernote SDK for ActionScript
ActionScript
22
star
22

evernote-sdk-perl

Evernote SDK for Perl
Perl
19
star
23

Aquaman

TypeScript
18
star
24

serge-website

Source code for https://serge.io/ — documentation site for Serge
PHP
5
star
25

eslint-plugin-evernote

Evernote custom eslint plugin
JavaScript
5
star
26

eslint-config-evernote

eslint config rules for Evernote projects.
JavaScript
2
star