Home | History | Annotate | Download | only in os 
      1 /*
      2  * Copyright (C) 2006 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package android.os;
     18 
     19 /**
     20  * Interface for classes whose instances can be written to
     21  * and restored from a {@link Parcel}.  Classes implementing the Parcelable
     22  * interface must also have a static field called <code>CREATOR</code>, which
     23  * is an object implementing the {@link Parcelable.Creator Parcelable.Creator}
     24  * interface.
     25  *
     26  * <p>A typical implementation of Parcelable is:</p>
     27  *
     28  * <pre>
     29  * public class MyParcelable implements Parcelable {
     30  *     private int mData;
     31  *
     32  *     public int describeContents() {
     33  *         return 0;
     34  *     }
     35  *
     36  *     public void writeToParcel(Parcel out, int flags) {
     37  *         out.writeInt(mData);
     38  *     }
     39  *
     40  *     public static final Parcelable.Creator&lt;MyParcelable&gt; CREATOR
     41  *             = new Parcelable.Creator&lt;MyParcelable&gt;() {
     42  *         public MyParcelable createFromParcel(Parcel in) {
     43  *             return new MyParcelable(in);
     44  *         }
     45  *
     46  *         public MyParcelable[] newArray(int size) {
     47  *             return new MyParcelable[size];
     48  *         }
     49  *     };
     50  *
     51  *     private MyParcelable(Parcel in) {
     52  *         mData = in.readInt();
     53  *     }
     54  * }</pre>
     55  */
     56 public interface Parcelable {
     57     /**
     58      * Flag for use with {@link #writeToParcel}: the object being written
     59      * is a return value, that is the result of a function such as
     60      * "<code>Parcelable someFunction()</code>",
     61      * "<code>void someFunction(out Parcelable)</code>", or
     62      * "<code>void someFunction(inout Parcelable)</code>".  Some implementations
     63      * may want to release resources at this point.
     64      */
     65     public static final int PARCELABLE_WRITE_RETURN_VALUE = 0x0001;
     66 
     67     /**
     68      * Bit masks for use with {@link #describeContents}: each bit represents a
     69      * kind of object considered to have potential special significance when
     70      * marshalled.
     71      */
     72     public static final int CONTENTS_FILE_DESCRIPTOR = 0x0001;
     73 
     74     /**
     75      * Describe the kinds of special objects contained in this Parcelable's
     76      * marshalled representation.
     77      *
     78      * @return a bitmask indicating the set of special object types marshalled
     79      * by the Parcelable.
     80      */
     81     public int describeContents();
     82 
     83     /**
     84      * Flatten this object in to a Parcel.
     85      *
     86      * @param dest The Parcel in which the object should be written.
     87      * @param flags Additional flags about how the object should be written.
     88      * May be 0 or {@link #PARCELABLE_WRITE_RETURN_VALUE}.
     89      */
     90     public void writeToParcel(Parcel dest, int flags);
     91 
     92     /**
     93      * Interface that must be implemented and provided as a public CREATOR
     94      * field that generates instances of your Parcelable class from a Parcel.
     95      */
     96     public interface Creator<T> {
     97         /**
     98          * Create a new instance of the Parcelable class, instantiating it
     99          * from the given Parcel whose data had previously been written by
    100          * {@link Parcelable#writeToParcel Parcelable.writeToParcel()}.
    101          *
    102          * @param source The Parcel to read the object's data from.
    103          * @return Returns a new instance of the Parcelable class.
    104          */
    105         public T createFromParcel(Parcel source);
    106 
    107         /**
    108          * Create a new array of the Parcelable class.
    109          *
    110          * @param size Size of the array.
    111          * @return Returns an array of the Parcelable class, with every entry
    112          * initialized to null.
    113          */
    114         public T[] newArray(int size);
    115     }
    116 
    117     /**
    118      * Specialization of {@link Creator} that allows you to receive the
    119      * ClassLoader the object is being created in.
    120      */
    121     public interface ClassLoaderCreator<T> extends Creator<T> {
    122         /**
    123          * Create a new instance of the Parcelable class, instantiating it
    124          * from the given Parcel whose data had previously been written by
    125          * {@link Parcelable#writeToParcel Parcelable.writeToParcel()} and
    126          * using the given ClassLoader.
    127          *
    128          * @param source The Parcel to read the object's data from.
    129          * @param loader The ClassLoader that this object is being created in.
    130          * @return Returns a new instance of the Parcelable class.
    131          */
    132         public T createFromParcel(Parcel source, ClassLoader loader);
    133     }
    134 }
    135