Android Reference

Parcel

Class Parcel

Container for a message (data and object references) that can
be sent through an IBinder. A Parcel can contain both flattened data
that will be unflattened on the other side of the IPC (using the various
methods here for writing specific types, or the general
Parcelable interface), and references to live IBinder
objects that will result in the other side receiving a proxy IBinder
connected with the original IBinder in the Parcel.

Parcel is not a general-purpose
serialization mechanism. This class (and the corresponding
Parcelable API for placing arbitrary objects into a Parcel) is
designed as a high-performance IPC transport. As such, it is not
appropriate to place any Parcel data in to persistent storage: changes
in the underlying implementation of any of the data in the Parcel can
render older data unreadable.

The bulk of the Parcel API revolves around reading and writing data
of various types. There are six major classes of such functions available.

Primitive Arrays

There are a variety of methods for reading and writing raw arrays
of primitive objects, which generally result in writing a 4-byte length
followed by the primitive data items. The methods for reading can either
read the data into an existing array, or create and return a new array.
These available types are:

Bundles

A special type-safe container, called Bundle, is available
for key/value maps of heterogeneous values. This has many optimizations
for improved performance when reading and writing data, and its type-safe
API avoids difficult to debug type errors when finally marshalling the
data contents into a Parcel. The methods to use are
writeBundle(Bundle), readBundle(), and
readBundle(ClassLoader).

Active Objects

An unusual feature of Parcel is the ability to read and write active
objects. For these objects the actual contents of the object is not
written, rather a special token referencing the object is written. When
reading the object back from the Parcel, you do not get a new instance of
the object, but rather a handle that operates on the exact same object that
was originally written. There are two forms of active objects available.

FileDescriptor objects, representing raw Linux file descriptor identifiers,
can be written and ParcelFileDescriptor objects returned to operate
on the original file descriptor. The returned file descriptor is a dup
of the original file descriptor: the object and fd is different, but
operating on the same underlying file stream, with the same position, etc.
The methods to use are writeFileDescriptor(FileDescriptor),
readFileDescriptor().

dataAvail

dataPosition

public final int dataPosition()

Returns the current position in the parcel data. Never
more than dataSize().

dataCapacity

public final int dataCapacity()

Returns the total amount of space in the parcel. This is always
>= dataSize(). The difference between it and dataSize() is the
amount of room left until the parcel needs to re-allocate its
data buffer.

setDataSize

public final void setDataSize(int size)

Change the amount of data in the parcel. Can be either smaller or
larger than the current size. If larger than the current capacity,
more memory will be allocated.

setDataCapacity

size - The new capacity of the parcel, in bytes. Can not be
less than dataSize() -- that is, you can not drop existing data
with this method.

pushAllowFds

public final boolean pushAllowFds(boolean allowFds)

restoreAllowFds

public final void restoreAllowFds(boolean lastValue)

marshall

public final byte[] marshall()

Returns the raw bytes of the parcel.

The data you retrieve here must not
be placed in any kind of persistent storage (on local disk, across
a network, etc). For that, you should use standard serialization
or another kind of general serialization mechanism. The Parcel
marshalled representation is highly optimized for local IPC, and as
such does not attempt to maintain compatibility with data created
in different versions of the platform.

It is strongly recommended to use writeBundle(android.os.Bundle) instead of
this method, since the Bundle class provides a type-safe API that
allows you to avoid mysterious type errors at the point of marshalling.

writeArray

Flatten an Object array into the parcel at the current dataPosition(),
growing dataCapacity() if needed. The array values are written using
writeValue(java.lang.Object) and must follow the specification there.

writeSparseArray

Flatten a generic SparseArray into the parcel at the current
dataPosition(), growing dataCapacity() if needed. The SparseArray
values are written using writeValue(java.lang.Object) and must follow the
specification there.

createBinderArray

readBinderArray

writeTypedList

Flatten a List containing a particular object type into the parcel, at
the current dataPosition() and growing dataCapacity() if needed. The
type of the objects in the list must be one that implements Parcelable.
Unlike the generic writeList() method, however, only the raw data of the
objects is written and not their type, so you must use the corresponding
readTypedList() to unmarshall them.

writeTypedArray

Flatten a heterogeneous array containing a particular object type into
the parcel, at
the current dataPosition() and growing dataCapacity() if needed. The
type of the objects in the array must be one that implements Parcelable.
Unlike the writeParcelableArray(T[], int) method, however, only the
raw data of the objects is written and not their type, so you must use
readTypedArray(T[], android.os.Parcelable.Creator<T>) with the correct corresponding
Parcelable.Creator implementation to unmarshall them.

Any object that implements Serializable (but see
writeSerializable(java.io.Serializable) for caveats). Note that all of the
previous types have relatively efficient implementations for
writing to a Parcel; having to rely on the generic serialization
approach is much less efficient and should be avoided whenever
possible.

writeSerializable

Write a generic serializable object in to a Parcel. It is strongly
recommended that this method be avoided, since the serialization
overhead is extremely large, and this approach will be much slower than
using the other approaches to writing data in to a Parcel.

writeException

Special function for writing an exception result at the header of
a parcel, to be used when returning an exception from a transaction.
Note that this currently only supports a few exception types; any other
exception will be re-thrown by this function as a RuntimeException
(to be caught by the system's last-resort exception handling when
dispatching a transaction).

readException

public final void readException()

Special function for reading an exception result from the header of
a parcel, to be used after receiving the result of a transaction. This
will throw the exception for you if it had been written to the Parcel,
otherwise return and let you read the normal result data from the Parcel.

readExceptionCode

public final int readExceptionCode()

Parses the header of a Binder call's response Parcel and
returns the exception code. Deals with lite or fat headers.
In the common successful case, this header is generally zero.
In less common cases, it's a small negative number and will be
followed by an error string.
This exists purely for android.database.DatabaseUtils and
insulating it from having to handle fat headers as returned by
e.g. StrictMode-induced RPC responses.

readHashMap

Please use readBundle(ClassLoader) instead (whose data must have
been written with writeBundle(android.os.Bundle). Read and return a new HashMap
object from the parcel at the current dataPosition(), using the given
class loader to load any enclosed Parcelables. Returns null if
the previously written map object was null.

readBundle

Read and return a new Bundle object from the parcel at the current
dataPosition(), using the given class loader to initialize the class
loader of the Bundle for later retrieval of Parcelable objects.
Returns null if the previously written Bundle object was null.

createByteArray

public final byte[] createByteArray()

Read and return a byte[] object from the parcel.

readByteArray

public final void readByteArray(byte[] val)

Read a byte[] object from the parcel and copy it into the
given byte array.

readCharSequenceArray

readArrayList

Read and return a new ArrayList object from the parcel at the current
dataPosition(). Returns null if the previously written list object was
null. The given class loader will be used to load any enclosed
Parcelables.

readArray

Read and return a new Object array from the parcel at the current
dataPosition(). Returns null if the previously written array was
null. The given class loader will be used to load any enclosed
Parcelables.

readSparseArray

Read and return a new SparseArray object from the parcel at the current
dataPosition(). Returns null if the previously written list object was
null. The given class loader will be used to load any enclosed
Parcelables.

createTypedArrayList

Read and return a new ArrayList containing a particular object type from
the parcel that was written with writeTypedList(java.util.List<T>) at the
current dataPosition(). Returns null if the
previously written list object was null. The list must have
previously been written via writeTypedList(java.util.List<T>) with the same object
type.

Returns:

A newly created ArrayList containing objects with the same data
as those that were previously written.

createTypedArray

Read and return a new array containing a particular object type from
the parcel at the current dataPosition(). Returns null if the
previously written array was null. The array must have
previously been written via writeTypedArray(T[], int) with the same
object type.

Returns:

A newly created array containing objects with the same data
as those that were previously written.

readTypedArray

writeParcelableArray

Write a heterogeneous array of Parcelable objects into the Parcel.
Each object in the array is written along with its class name, so
that the correct class can later be instantiated. As a result, this
has significantly more overhead than writeTypedArray(T[], int), but will
correctly handle an array containing more than one type of object.

obtain

finalize

Invoked when the garbage collector has detected that this instance is no longer reachable.
The default implementation does nothing, but this method can be overridden to free resources.

Note that objects that override finalize are significantly more expensive than
objects that don't. Finalizers may be run a long time after the object is no longer
reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup.
Note also that finalizers are run on a single VM-wide finalizer thread,
so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary
for a class that has a native peer and needs to call a native method to destroy that peer.
Even then, it's better to provide an explicit close method (and implement
Closeable), and insist that callers manually dispose of instances. This
works well for something like files, but less well for something like a BigInteger
where typical calling code would have to deal with lots of temporaries. Unfortunately,
code that creates lots of temporaries is the worst kind of code from the point of view of
the single finalizer thread.

If you must use finalizers, consider at least providing your own
ReferenceQueue and having your own thread process that queue.

Unlike constructors, finalizers are not automatically chained. You are responsible for
calling super.finalize() yourself.

Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer
thread.
See Effective Java Item 7, "Avoid finalizers" for more.

RFC (best current practice status)

RFC (historic status)

RFC (unknown status)

IT dictionary

All information of this service is derived from the free sources and is provided solely in the form of quotations.
This service provides information and interfaces solely for the familiarization (not ownership) and under the "as is" condition.