001/**
002 * Copyright 2011-2015 John Ericksen
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *    http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.parceler;
017
018import java.lang.annotation.Retention;
019import java.lang.annotation.Target;
020
021import static java.lang.annotation.ElementType.TYPE;
022import static java.lang.annotation.RetentionPolicy.RUNTIME;
023
024/**
025 * Identifies a class to be wrapped by a `Parcelable` wrapper.
026 * 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.
027 * If a ParcelConverter is specified it will be used instead.
028 *
029 * Only a select number of types may be used as attributes of a `@Parcel` class.
030 * The following list includes the mapped types:
031 *
032 * - `byte`
033 * - `double`
034 * - `float`
035 * - `int`
036 * - `long`
037 * - `char`
038 * - `boolean`
039 * - `String`
040 * - `IBinder`
041 * - `Bundle`
042 * - `SparseArray` of any of the mapped types*
043 * - `SparseBooleanArray`
044 * - `List`, `ArrayList` and `LinkedList` of any of the mapped types*
045 * - `Map`, `HashMap`, `LinkedHashMap`, `SortedMap`, and `TreeMap` of any of the mapped types*
046 * - `Set`, `HashSet`, `SortedSet`, `TreeSet`, `LinkedHashSet` of any of the mapped types*
047 * - `Parcelable`
048 * - `Serializable`
049 * - Array of any of the mapped types
050 * - Any other class annotated with `@Parcel`
051 *
052 * Parcel will error if the generic parameter is not mapped.
053 *
054 * Parceler also supports any of the above types directly.
055 * This is especially useful when dealing with collections of classes annotated with `@Parcel`:
056 *
057 * [source,java]
058 * ----
059 * Parcelable listParcelable = Parcels.wrap(new ArrayList<Example>());
060 * Parcelable mapParcelable = Parcels.wrap(new HashMap<String, Example>());
061 * ----
062 *
063 * Properties that should not be serialized can be annotated with the `@Transient` annotation on either the getter or setter.
064 * Parceler will ignore `@Transient` annotated properties during Parcelable serialization.
065 *
066 * @author John Ericksen
067 */
068@Target(TYPE)
069@Retention(RUNTIME)
070public @interface Parcel {
071
072    /**
073     * Specifies the technique for which Parceler will serialize.
074     */
075    Serialization value() default Serialization.FIELD;
076
077    /**
078     * The concrete implementations that should be mapped to this class for use with the Parcels utility class.
079     */
080    Class[] implementations() default {};
081
082    /**
083     * Identifies the types to include in analysis.
084     * Parceler will walk to inheritance extension hierarchy only including the classes specified, if the list of classes is non-empty.
085     */
086    Class[] analyze() default {};
087
088    /**
089     * `ParcelConverter` to use when serializing this class.
090     * Parceler will attempt to generate serialization specifics if this converter is not specified.
091     */
092    Class<? extends TypeRangeParcelConverter> converter() default ParcelConverter.EmptyConverter.class;
093
094    /**
095     * Value to be returned by the generated `describeContents()` method.
096     *
097     * @return bitmask value indicating marshalled object types.
098     * @see https://developer.android.com/reference/android/os/Parcelable.html#describeContents()[Parcelable.describeContents()]
099     */
100    int describeContents() default 0;
101
102    enum Serialization {
103        /**
104         * Read and write fields directly.
105         */
106        FIELD,
107        /**
108         * Read and write via the Bean standard, public matching getter and setters.
109         */
110        BEAN,
111        /**
112         * Read and write via value accessors and mutators.
113         */
114        VALUE
115    }
116}