public class BackupDataOutput extends Object
BackupAgent
commits
information to the backup data set, via its onBackup()
method. Data written for backup is presented
as a set of "entities," key/value pairs in which each binary data record "value" is
named with a string "key."
To commit a data record to the backup transport, the agent's
onBackup()
method first writes an "entity header" that supplies the key string for the record
and the total size of the binary value for the record. After the header has been
written, the agent then writes the binary entity value itself. The entity value can
be written in multiple chunks if desired, as long as the total count of bytes written
matches what was supplied to writeEntityHeader()
.
Entity key strings are considered to be unique within a given application's backup
data set. If a backup agent writes a new entity under an existing key string, its value will
replace any previous value in the transport's remote data store. You can remove a record
entirely from the remote data set by writing a new entity header using the
existing record's key, but supplying a negative dataSize
parameter.
When you do so, the agent does not need to call writeEntityData(byte[], int)
.
Here is an example illustrating a way to back up the value of a String variable
called mStringToBackUp
:
static final String MY_STRING_KEY = "storedstring";
public void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data, ParcelFileDescriptor newState)
throws IOException {
...
byte[] stringBytes = mStringToBackUp.getBytes();
data.writeEntityHeader(MY_STRING_KEY, stringBytes.length);
data.writeEntityData(stringBytes, stringBytes.length);
...
}
BackupAgent
Constructor and Description |
---|
BackupDataOutput(FileDescriptor fd) |
Modifier and Type | Method and Description |
---|---|
protected void |
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
void |
setKeyPrefix(String keyPrefix) |
int |
writeEntityData(byte[] data,
int size)
Write a chunk of data under the current entity to the backup transport.
|
int |
writeEntityHeader(String key,
int dataSize)
Mark the beginning of one record in the backup data stream.
|
public BackupDataOutput(FileDescriptor fd)
public int writeEntityHeader(String key, int dataSize) throws IOException
writeEntityData(byte[], int)
.key
- A string key that uniquely identifies the data record within the application.
Keys whose first character is ? or higher are not valid.dataSize
- The size in bytes of this record's data. Passing a dataSize
of -1 indicates that the record under this key should be deleted.IOException
- if the write failedpublic int writeEntityData(byte[] data, int size) throws IOException
data
- A raw data buffer to sendsize
- The number of bytes to be sent in this chunkIOException
- if the write failedpublic void setKeyPrefix(String keyPrefix)
protected void finalize() throws Throwable
Object
finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the JavaTM virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.