Skip to content

Using Parcelable

Jump to bottom
Roger Hu edited this page Apr 10, 2015 · 45 revisions

Overview

Due to Android's memory management scheme, you will often find yourself needing to communicate with different components of your application, system components, or other applications installed on the phone. Parcelable will help you pass data between these components.

Android uses what is called the Binder to facilitate such communication in a highly optimized way. The Binder communicates with Parcels, which is a message container. The Binder marshals the Parcel to be sent, sends and receives it, and then unmarshals it on the other side to reconstruct a copy of the original Parcel.

To allow for your class instances to be sent as a Parcel you must implement the Parcelable interface along with a static field called CREATOR, which itself requires a special constructor in your class.

Defining a Parcelable Object

Here is a typical implementation:

public class MyParcelable implements Parcelable {
    private int mData;
    private String mName;

    @Override
    public int describeContents() {
        return 0;
    }

    @Override
    public void writeToParcel(Parcel out, int flags) {
        out.writeInt(mData);
        out.writeString(mName);
    }

    public static final Parcelable.Creator<MyParcelable> CREATOR
            = new Parcelable.Creator<MyParcelable>() {
        @Override
        public MyParcelable createFromParcel(Parcel in) {
            return new MyParcelable(in);
        }

        @Override
        public MyParcelable[] newArray(int size) {
            return new MyParcelable[size];
        }
    };
     
    private MyParcelable(Parcel in) {
        mData = in.readInt();
        mName = in.readString();
    }

    public MyParcelable() {
        //normal actions performed by class, it's still a normal object!
    }
}

The Parcelable interface has two methods defined: int describeContents() and void writeToParcel(Parcel dest, int flags):

  • int describeContents()

In the vast majority of cases you can simply return 0 for this. There are cases where you need to use the constant CONTENTS_FILE_DESCRIPTOR, also defined in the interface, in combination with this method but it is very rare and out of the scope of this tutorial.

  • void writeToParcel(Parcel dest, int flags)

This is where you write the values you want to save to the Parcel. The Parcel class has methods defined to help you save all of your values. Note that there are only methods defined for primitive values (and String!), lists and arrays of primitive values, and other Parcelable objects. You may need to make several classes Parcelable to send the data you want.

After implementing the Parcelable interface, we need to create the Parcelable.Creator<MyParcelable> CREATOR constant for our class; notice how it has our class as its type. This CREATOR object also has two methods:

  • MyParcelable createFromParcel(Parcel in)

This simply calls our new constructor (typically private) and passes along the unmarshalled Parcel, and then returns the new object!

  • MyParcelable[] newArray(int size)

We just need to copy this and change the type to match our class.

Lastly, we have the private constructor that we created:

  • MyParcelable(Parcel in)

Using the in variable, we can retrieve the values that we originally wrote into the Parcel. This constructor is usually private so that only the CREATOR field can access it and to not clutter your exposed API.

Caveats

  • One very important thing to pay close attention to is the order that you write and read your values to and from the Parcel. They need to match up in both cases. In my example, I write the int and then the String to the Parcel. Afterwards, I read them in that same exact order. The mechanism that Android uses to read the Parcel is blind and completely trusts you to get the order correct, or else you will run into run-time crashes.

  • Another problem I have encountered is with ClassNotFound exceptions. This is an issue with the Classloader not finding your class. To fix this you can manually set the Classloader to use. If nothing is set, then it will try the default Classloader which leads to the exception.

  • As mentioned before you can only put primitives, lists and arrays, Strings, and other Parcelable objects into a Parcel. This means that you cannot store framework dependent objects that are not Parcelable. For example, you could not write a Drawable to a Parcel. To work around this problem, you can instead do something like writing the resource ID of the Drawable as an integer to the Parcel. On the receiving side you can try to rebuild the Drawable using that. Remember, Parcel is supposed to be fast and lightweight! (though it is interesting to see Bitmap implementing Parcelable)

  • Where is boolean!? For whatever odd reason there is no simple way to write a boolean to a Parcel. To do so, you can instead write a byte with the corresponding value like so:

out.writeByte((byte) (myBoolean ? 1 : 0));

And retrieve it similarly:

myBoolean = in.readByte() != 0;

What It Is Not

You may notice some similarities between Parcelable and Serializable. DO NOT, I repeat, DO NOT attempt to persist Parcel data. It is meant for high-performance transport and you could lose data by trying to persist it.

Using Parcelable compared to Serializable can achieve up to 10x performance increase in many cases for transport which is why it's the Android preferred method. :)

Passing Data Between Intents

We can now pass the parcelable data between activities within an intent:

// somewhere inside an Activity
MyParcelable dataToSend = new MyParcelable();
Intent i = new Intent(this, NewActivity.class);
i.putExtra("myData", dataToSend); // using the (String name, Parcelable value) overload!
startActivity(i); // dataToSend is now passed to the new Activity

and then access the data in the NewActivity using:

public class NewActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        MyParcelable object = (MyParcelable) getIntent().getParcelableExtra("myData");
    }
}

Now we can access the parcelable data from within the launched activity.

Creating a Parcelable, The Easier Way ( using Eclipse)

Generate your normal class like so:

public class MyCustomObject {
	
	private int num1;
	private String string1;
	private boolean bool1;
	
	public MyCustomObject() {
		
	}

	public MyCustomObject(int num1, String string1, boolean bool1) {
		super();
		this.num1 = num1;
		this.string1 = string1;
		this.bool1 = bool1;
	}

	public int getNum1() {
		return num1;
	}

	public void setNum1(int num1) {
		this.num1 = num1;
	}

	public String getString1() {
		return string1;
	}

	public void setString1(String string1) {
		this.string1 = string1;
	}

	public boolean isBool1() {
		return bool1;
	}

	public void setBool1(boolean bool1) {
		this.bool1 = bool1;
	}
	
}

Then go to the site Parcelabler designed by Dallas Gutauckis. Paste your object into the "Code" text box provided. Then watch the magic happen as this site turns your once plain and non-passable object into.

public class MyCustomObject implements Parcelable {
	
	private int num1;
	private String string1;
	private boolean bool1;
	
	public MyCustomObject() {
		
	}

	public MyCustomObject(int num1, String string1, boolean bool1) {
		super();
		this.num1 = num1;
		this.string1 = string1;
		this.bool1 = bool1;
	}

	public int getNum1() {
		return num1;
	}

	public void setNum1(int num1) {
		this.num1 = num1;
	}

	public String getString1() {
		return string1;
	}

	public void setString1(String string1) {
		this.string1 = string1;
	}

	public boolean isBool1() {
		return bool1;
	}

	public void setBool1(boolean bool1) {
		this.bool1 = bool1;
	}
	

    protected MyCustomObject(Parcel in) {
        num1 = in.readInt();
        string1 = in.readString();
        bool1 = in.readByte() != 0x00;
    }

    @Override
    public int describeContents() {
        return 0;
    }

    @Override
    public void writeToParcel(Parcel dest, int flags) {
        dest.writeInt(num1);
        dest.writeString(string1);
        dest.writeByte((byte) (bool1 ? 0x01 : 0x00));
    }

    @SuppressWarnings("unused")
    public static final Parcelable.Creator<MyCustomObject> CREATOR = new Parcelable.Creator<MyCustomObject>() {
        @Override
        public MyCustomObject createFromParcel(Parcel in) {
            return new MyCustomObject(in);
        }

        @Override
        public MyCustomObject[] newArray(int size) {
            return new MyCustomObject[size];
        }
    };
}

A very pretty Parcelable object that you can copy and paste back into your project. The site is also able to handle all of the primitives and Java object I didn't include in this tutorial. On top of that it also can handle your own custom parcelable objects and objects that extend other objects that you have already created. This is a util that I stumbled upon searching for a easier way to create Parcelable objects that I can use in my projects. Hope you enjoy.

Creating a Parcelable, The Easier Way (using IntelliJ or Android Studio)

There is a Parcelable plugin that can be imported directly into IntelliJ or Android Studio, which enables you to generate the boilerplate code for creating Parcelables. You can install this plugin by going to Android Studio -> Preferences -> Plugins -> Browse repositories:

Here are all the Java types it supports:

  • Types implementing Parcelable
  • Custom support (avoids Serializable/Parcelable implementation) for: Date, Bundle
  • Types implementing Serializable
  • List of Parcelable objects
  • Enumerations
  • Primitive types: long, int, float, double, boolean, byte, String
  • Primitive type wrappers (written with Parcel.writeValue(Object)): Integer, Long, Float, Double, Boolean, Byte
  • Primitive type arrays: boolean[], byte[], char[], double[], float[], int[], long[]
  • List type of any object (Warning: validation is not performed)

References

Created by CodePath with much help from the community. Contributed content licensed under cc-wiki with attribution required. You are free to remix and reuse, as long as you attribute and use a similar license.

Finding these guides helpful?

We need help from the broader community to improve these guides, add new topics and keep the topics up-to-date. See our contribution guidelines here and our topic issues list for great ways to help out.

Check these same guides through our standalone viewer for a better browsing experience and an improved search. Follow us on twitter @codepath for access to more useful Android development resources.

Clone this wiki locally