Using Parceler

Overview

Although creating Android Parcelables is usually at least 10x faster than using Serializable, creating Parcelable objects requires creating a lot of boilerplate code in defining exactly the stream of data that should be serialized and deserialized as documented in this section.

While there are IDE plugins to help facilitate the creating of these objects, another option is to leverage a third-party library called Parceler that will help automate this work. Underneath the surface this library generates the necessary wrapper classes for you at compile time automatically, saving you the repetitive steps required for leveraging the performance benefits of Parcelables.

Setup

To setup, we need to add the android-apt plugin to our classpath in our root build.gradle file. This plugin enables the Parceler library to be used for annotation processing but not added to the final build.

dependencies {
  classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8'
}

Inside the app/build.gradle file, we should apply the plugin before the Parceler dependencies are added. This way, the apt keyword can be used, which is primarily used for annotation processing and keeps the libraries from being added to the classpath.

apply plugin: 'com.neenbedankt.android-apt'

dependencies {
  compile 'org.parceler:parceler-api:1.1.1'
  apt 'org.parceler:parceler:1.1.1'
}

Usage

Converting a model from Serializable objects

Suppose we have an User object that implements the Serializable interface:

public class User implements Serializable {
    private String firstName;
    private String lastName;

    public User(String firstName, String lastName) {
       this.firstName = firstName;
       this.lastName = lastName;
    }
}

There are several requirements to convert this object to one that can be used by this library:

1. Remove the Serializable interface back to its original form.
2. Annotate the class with the @Parcel decorator.
3. Use only public fields (private fields cannot be detected during annotation) that need to be serialized.
4. Create a public constructor with no arguments for the annotation library.

@Parcel
public class User {
    // fields must be public
    String firstName;
    String lastName;

    // empty constructor needed by the Parceler library 
    public User() {
    }

    public User(String firstName, String lastName) {
       this.firstName = firstName;
       this.lastName = lastName;
    }
}

Wrapping Up a Parcel

Next, simply wrap your objects with Parcels.wrap():

User user = new User("John", "Doe");
Intent intent = new Intent(this, MyActivity.class);
intent.putExtra("user", Parcels.wrap(user));
startActivity(intent);

Unwrapping a Parcel

On the receiving side, we need to unwrap the object:

User user = (User) Parcels.unwrap(getIntent().getParcelableExtra("user"));

The Parceler library works by using the @Parcel annotation to generate the wrapper classes for you. It works with many of the most standard Java types, including the ones defined here.

How it works

You can also look at your app/build/generated/source/apt directory to see how it generates these wrapper classes. Parceler essentially handles the steps described in this section.

Using with ORM libraries

Some ORM libraries require extending the Java object with fields that Parceler is unable to serialize or deserialize. In these cases, you should limit what fields should be analyzed in the inheritance using the @Parcel(analyze={}) decorator:

@Parcel(analyze={User.class})   // add Parceler annotation here
public class User extends BaseModel {
}

• DBFlow
• Realm.IO

Troubleshooting

• Getting java.lang.ClassCastException: SomeObject$$Parcelable cannot be cast to SomeObject when extracting a Parcel from a Bundle?

  • Be sure to call Parcels.unwrap when extracting the parcel from the Bundle:

    User user = (User) Parcels.unwrap(someIntent.getParcelableExtra("user"));

• Getting a null exception when accessing a member instance stored within a Parceler object?

  • Be sure that all custom java objects stored as fields within a Parceler object are themselves also Parcels.
  • Make sure that every parceled field is properly converted into a Parceler object.

References

• http://parceler.org/