TODO:Remove me when github upgrades asciidoctor

Parceler

In Android, Parcelables are a great way to serialize Java Objects between Contexts. Compared with traditional Serialization Percelables take on the order of 10x less time to both serialize and deserialize. There is a major flaw with Parcelables, however. Parcelables contain a ton of boilerplate code. To implement a Parcelable, you must mirror the writeToParcel() and createFromParcel() methods such that they read and write to the Parcel in the same order. Also, a Parcelable must define a public final static Parcelable.Creator CREATOR in order for the Android infrastructure to be able to leverage the serialization code.

Parceler is a code generation library that generates the Android Parcelable boilerplate source code. No longer do you have to implement the Parcelable interface, the writeToParcel or createFromParcel() or the public static final CREATOR. You simply annotate a POJO with @Parcel and Parceler does the rest. Because Parceler uses the Java JSR-269 Annotation Processor, there is no need to run a tool manually to generate the Parcelable code. Just annotate your Java Bean and you are finished:

@Parcel
public class Example {
    private String name;
    private int age;

    public Example(){ /*Required empty bean constructor*/ }

    public Example(int age, String name) {
        this.age = age;
        this.name = name;
    }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public int getAge() { return age; }
    public void setAge(int age) { this.age = age; }
}

To use the generated code, you may reference the generated class directly, or via the Parcels utility class:

    Parcelable wrapped = Parcels.wrap(new Example("Andy", 42);

To dereference the @Parcel, just call the Parcels.unwrap() method:

    Example example = Parcels.unwrap(wrapped);
    example.getName(); // Andy
    example.getAge(); // 42

Of course, the ParcelWrapper can be added to an Android Bundle to transfer from Activity to Activity:

    Bundle bundle = new Bundle();
    bundle.putParcelable("example", Parcels.wrap(example));

And dereferenced in the onCreate() method:

    Example example = Parcels.unwrap(this.getIntent().getExtras().get("example"));

Only a select number of types may be used as attributes of a @Parcel class. The following list includes the mapped types:

byte
byte[]
double
double[]
float
float[]
int
int[]
long
long[]
String
String[]
IBinder
Bundle
Object[]
SparseArray
SparseBooleanArray
Exception
Other classes annotated with @Parcel

Each attribute must have a Java Bean standard getter and setter. For attributes that should not be serialized with Parceler, the attribute getter or setter may be annotated by @Transient.

@Parcel includes an optional parameter to include a manual serializer ParcelConverter for the case where special serialization is necessary. Ths provides a still cleaner option for using Parcelable classes than implementing them by hand.

For classes whose corresponding Java source is not available, one may include the class as a Parcel by using the @ParcelClass annotation. This annotation may be declared anywhere in the compiled source that is convenient. For instance, one could include the @ParcelClass along with the Android Application:

@ParcelClass(LibraryParcel.class)
public class AndroidApplication extends Application{

}

Multiple @ParcelClass annotations may be declared using the @ParcelClasses annotation.

Getting Parceler

You may download Parceler as a Maven dependency:

<dependency>
    <groupId>org.parceler</groupId>
    <artifactId>parceler</artifactId>
    <version>${parceler.version}</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.parceler</groupId>
    <artifactId>parceler-api</artifactId>
    <version>${parceler.version}</version>
</dependency>

Or from Maven Central.

License

Copyright 2013 John Ericksen

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.

gogoranger / parceler

TODO:Remove me when github upgrades asciidoctor

Parceler

Getting Parceler

About