org.parceler.Parcel Maven / Gradle / Ivy
/**
* Copyright 2011-2015 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.
*/
package org.parceler;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Identifies a class to be wrapped by a `Parcelable` wrapper.
* This wrapper will serialize an instance of the current class to and from a Parcelable representation based on the serialization technique `value` if no `ParcelConverter` value is specified.
* If a ParcelConverter is specified it will be used instead.
*
* 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`
* - `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`
* - `Serializable`
* - Array of any of the mapped types
* - Any other class annotated with `@Parcel`
*
* Parcel will error if the generic parameter is not mapped.
*
* Parceler also supports any of the above types directly.
* This is especially useful when dealing with collections of classes annotated with `@Parcel`:
*
* [source,java]
* ----
* Parcelable listParcelable = Parcels.wrap(new ArrayList());
* Parcelable mapParcelable = Parcels.wrap(new HashMap());
* ----
*
* Properties that should not be serialized can be annotated with the `@Transient` annotation on either the getter or setter.
* Parceler will ignore `@Transient` annotated properties during Parcelable serialization.
*
* @author John Ericksen
*/
@Target(TYPE)
@Retention(RUNTIME)
public @interface Parcel {
/**
* Specifies the technique for which Parceler will serialize.
*/
Serialization value() default Serialization.FIELD;
/**
* The concrete implementations that should be mapped to this class for use with the Parcels utility class.
*/
Class[] implementations() default {};
/**
* Identifies the types to include in analysis.
* Parceler will walk to inheritance extension hierarchy only including the classes specified, if the list of classes is non-empty.
*/
Class[] analyze() default {};
/**
* `ParcelConverter` to use when serializing this class.
* Parceler will attempt to generate serialization specifics if this converter is not specified.
*/
Class converter() default ParcelConverter.EmptyConverter.class;
/**
* Value to be returned by the generated `describeContents()` method.
*
* @return bitmask value indicating marshalled object types.
* @see https://developer.android.com/reference/android/os/Parcelable.html#describeContents()[Parcelable.describeContents()]
*/
int describeContents() default 0;
enum Serialization {
/**
* Read and write fields directly.
*/
FIELD,
/**
* Read and write via the Bean standard, public matching getter and setters.
*/
BEAN,
/**
* Read and write via value accessors and mutators.
*/
VALUE
}
}