Akatsuki

Akatsuki is a light weight Android library that handles state restoration and argument passing via annotations. The library automatically generates source files through JSR269 to ensure almost¹ zero performance impact.

###Key features:

State restoration

• Retain state with @Retained
• Supports all types allowed in Bundle and a few more
• Supports inheritance
• Supports generic parameters
• Custom type support with TypeConverter and @TransformationTemplate
• Compatible with other parcel and binding libraries
• Per class and global configuration via @RetainConfig

Argument passing

• Pass arguments with @Arg
• Supports inheritance, builders will be generated for all subclasses
• Supports Activity, Fragment, and Service
• Custom builder support with ArgConcludingBuilder
• Supports chained, checked, unchecked, and type safe builders
• Per class and global configuration via @ArgConfig

Good to know

• @Retained and @Arg can be used together
• Annotation based configuration via @AkatsukiConfig

In short, this library handles most Android IPC boilerplate that would otherwise be tedious to write and maintain.

Example usage:

public class MainActivity extends Activity {

    @Retained String myString;
    @Retained int myInt;
    @Retained android.accounts.Account account; // implements Parcelable

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        Akatsuki.restore(this, savedInstanceState);
        //everything restored!   
        
        // you want to start AnotherActivity and pass some stuff:
        Builders.AnotherActivity().theAnswer("42").startActivity(this);
    }

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

// in another activity class
public class AnotherActivity extends Activity {

    // @Args and @Retained can be used together
    @Arg @Retained String theAnswer; 
  
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        Akatsuki.restore(this, savedInstanceState);
        // theAnswer is retrieved from the intent and persisted in case of any change
    }

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

¹Reflection is used only once to locate the generated classes.

For documentation and additional information see the wiki

Download

The compiler is written in Java 8 so make sure you have JDK8 or higher installed(use java -version to check)

Gradle dependencies:

dependencies {
 compile 'com.sora.util.akatsuki:akatsuki-api:0.2.0'
 apt 'com.sora.util.akatsuki:akatsuki-compiler:0.2.0'
}

Optional parceler support:

compile 'com.sora.util.akatsuki:akatsuki-parceler:0.2.0@aar'

Please pay special attention to the build script:

// your source/target compatibility remains 1_7, do NOT change it to 1_8
compileOptions {
 sourceCompatibility JavaVersion.VERSION_1_7
 targetCompatibility JavaVersion.VERSION_1_7
}
// exception: do keep 1_8 if you happen to be using retrolambda

Sample app(.apk)

Showcasing (Fragment + NumberPicker/EditText)

Snapshot builds

Snapshot builds are released on JitPack:

repositories {
    //...
    maven { url "https://jitpack.io" }
}
dependencies {
    compile 'com.github.tom91136.akatsuki:akatsuki-api:<commit>'
    apt 'com.github.tom91136.akatsuki:akatsuki-compiler:<commit>'
}

Substitute <commit> with the latest commit hash, you can look them up in the commit history here

The first sync/build will take a long time, be patient.

Proguard

Please use the following rules if you have proguard enabled in your build script:

-dontwarn com.sora.util.akatsuki.**
-keep class com.sora.util.akatsuki.** { *; }
-keep class **$$BundleRetainer { *; }
-keepclasseswithmembernames class * {
    @com.sora.util.akatsuki.* <fields>;
}

Special thanks

Special thanks to ersin-ertan for testing the library and reporting bugs

License

Copyright 2015 WEI CHEN LIN

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.