<commit_before>= Parceler

image:https://badges.gitter.im/johncarl81/parceler.svg[link="https://gitter.im/johncarl81/parceler?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]
image:https://travis-ci.org/johncarl81/parceler.png?branch=master["Build Status", link="https://travis-ci.org/johncarl81/parceler"]
image:https://maven-badges.herokuapp.com/maven-central/org.parceler/parceler-api/badge.svg["Maven Central", link="https://maven-badges.herokuapp.com/maven-central/org.parceler/parceler-api"]

Have a question?  http://stackoverflow.com/questions/ask?tags=parceler[Ask it on StackOverflow.]

Found an issue?  https://github.com/johncarl81/parceler/issues/new[Please report it.]

In Android, http://developer.android.com/reference/android/os/Parcelable.html[Parcelables] are a great way to serialize Java Objects between Contexts.
http://www.developerphil.com/parcelable-vs-serializable/[Compared] with traditional Serialization, Parcelables 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 static final 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, compile and you are finished.
By default, Parceler will serialize the fields of your instance directly:

[source,java]
----
@Parcel
public class Example {
    String name;
    int age;

    public Example() {}

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

    public String getName() { return name; }

    public int getAge() { return age; }
}
----

Be careful not to use private fields when using the default field serialization strategy as it will incur a performance penalty due to reflection.

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

[source,java]
----
Parcelable wrapped = Parcels.wrap(new Example("Andy", 42));
----

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

[source,java]
----
Example example = Parcels.unwrap(wrapped);
example.getName(); // Andy
example.getAge(); // 42
----

Of course, the wrapped `Parcelable` can be added to an Android Bundle to transfer from Activity to Activity:

[source,java]
----
Bundle bundle = new Bundle();
bundle.putParcelable("example", Parcels.wrap(example));
----

And dereferenced in the `onCreate()` method:

[source,java]
----
Example example = Parcels.unwrap(getIntent().getParcelableExtra("example"));
----

This wrapping and unwrapping technique plays well with the Intent Factory pattern.
In addition, Parceler is supported by the following libraries:

 * http://androidtransfuse.org/documentation.html#parcel[Transfuse] - Allows `@Parcel` annotated beans to be used with the `@Extra` injection.
 * https://github.com/MarcinMoskala/ActivityStarter/wiki/Parceler-Arg-Converter-usage[ActivityStarter] - Uses ParcelarArgConverter to allow to use Parceler objects as an arguments passed to Activities (Fragments, Services etc.).
 * https://github.com/sockeqwe/fragmentargs#argsbundler[FragmentArgs] - Uses the `ParcelerArgsBundler` adapter to wrap and unwrap `@Parcel` annotated beans with fragment parameters.
 * https://github.com/f2prateek/dart[Dart] - Autodetects `@Parcel` annotated beans and automatically unwraps them when using `@InjectExtra`.
 * http://androidannotations.org/[AndroidAnnotations] - Autodetects `@Parcel` annotated beans and https://github.com/excilys/androidannotations/wiki/ParcelerIntegration[automatically wraps/unwraps] them when using `@Extra`, `@FragmentArg`, `@InstanceState` and other `Bundle` related annotations.

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

 * `byte`
 * `double`
 * `float`
 * `int`
 * `long`
 * `char`
 * `boolean`
 * `String`
 * `IBinder`
 * `Bundle`
 * `SparseArray` of any of the mapped types*
 * `SparseBooleanArray`
 * `ObservableField`
 * `List`, `ArrayList` and `LinkedList` of any of the mapped types*
 * `Map`, `HashMap`, `LinkedHashMap`, `SortedMap`, and `TreeMap` of any of the mapped types*
 * `Set`, `HashSet`, `SortedSet`, `TreeSet`, `LinkedHashSet` of any of the mapped types*
 * `Parcelable`<commit_msg>Touched up README<commit_after>= Parceler

image:https://badges.gitter.im/johncarl81/parceler.svg[link="https://gitter.im/johncarl81/parceler?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]
image:https://travis-ci.org/johncarl81/parceler.png?branch=master["Build Status", link="https://travis-ci.org/johncarl81/parceler"]
image:https://maven-badges.herokuapp.com/maven-central/org.parceler/parceler-api/badge.svg["Maven Central", link="https://maven-badges.herokuapp.com/maven-central/org.parceler/parceler-api"]

Have a question?  http://stackoverflow.com/questions/ask?tags=parceler[Ask it on StackOverflow.]

Found an issue?  https://github.com/johncarl81/parceler/issues/new[Please report it.]

In Android, http://developer.android.com/reference/android/os/Parcelable.html[Parcelables] are a great way to serialize Java Objects between Contexts.
http://www.developerphil.com/parcelable-vs-serializable/[Compared] with traditional Serialization, Parcelables 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 static final 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, compile and you are finished.
By default, Parceler will serialize the fields of your instance directly:

[source,java]
----
@Parcel
public class Example {
    String name;
    int age;

    public Example() {}

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

    public String getName() { return name; }

    public int getAge() { return age; }
}
----

Be careful not to use private fields when using the default field serialization strategy as it will incur a performance penalty due to reflection.

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

[source,java]
----
Parcelable wrapped = Parcels.wrap(new Example("Andy", 42));
----

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

[source,java]
----
Example example = Parcels.unwrap(wrapped);
example.getName(); // Andy
example.getAge(); // 42
----

Of course, the wrapped `Parcelable` can be added to an Android Bundle to transfer from Activity to Activity:

[source,java]
----
Bundle bundle = new Bundle();
bundle.putParcelable("example", Parcels.wrap(example));
----

And dereferenced in the `onCreate()` method:

[source,java]
----
Example example = Parcels.unwrap(getIntent().getParcelableExtra("example"));
----

This wrapping and unwrapping technique plays well with the Intent Factory pattern.
In addition, Parceler is supported by the following libraries:

 * http://androidtransfuse.org/documentation.html#parcel[Transfuse] - Allows `@Parcel` annotated beans to be used with the `@Extra` injection.
 * https://github.com/sockeqwe/fragmentargs#argsbundler[FragmentArgs] - Uses the `ParcelerArgsBundler` adapter to wrap and unwrap `@Parcel` annotated beans with fragment parameters.
 * https://github.com/f2prateek/dart[Dart] - Autodetects `@Parcel` annotated beans and automatically unwraps them when using `@InjectExtra`.
 * http://androidannotations.org/[AndroidAnnotations] - Autodetects `@Parcel` annotated beans and https://github.com/excilys/androidannotations/wiki/ParcelerIntegration[automatically wraps/unwraps] them when using `@Extra`, `@FragmentArg`, `@InstanceState` and other `Bundle` related annotations.
 * https://github.com/MarcinMoskala/ActivityStarter/wiki/Parceler-Arg-Converter-usage[ActivityStarter] - Uses `ParcelarArgConverter` to allow use Parceler objects as arguments passed to Activities,  Fragments, Services, etc.

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

 * `byte`
 * `double`
 * `float`
 * `int`
 * `long`
 * `char`
 * `boolean`
 * `String`
 * `IBinder`
 * `Bundle`
 * `SparseArray` of any of the mapped types*
 * `SparseBooleanArray`
 * `ObservableField`
 * `List`, `ArrayList` and `LinkedList` of any of the mapped types*
 * `Map`, `HashMap`, `LinkedHashMap`, `SortedMap`, and `TreeMap` of any of the mapped types*
 * `Set`, `HashSet`, `SortedSet`, `TreeSet`, `LinkedHashSet` of any of the mapped types*
 * `Parcelable`
{'fraction_non_alphanumeric': 0.11021665672828464, 'fraction_numerical': 0.0039753528125621145, 'mean_word_length': 4.867638483965014, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 22, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '568735', 'n_tokens_mistral': 3116, 'n_tokens_neox': 2972, 'n_words': 1023}