Android APIs
public class

AtomicFile

extends Object
java.lang.Object
   ↳ android.util.AtomicFile

Class Overview

Helper class for performing atomic operations on a file by creating a backup file until a write has successfully completed. If you need this on older versions of the platform you can use AtomicFile in the v4 support library.

Atomic file guarantees file integrity by ensuring that a file has been completely written and sync'd to disk before removing its backup. As long as the backup file exists, the original file is considered to be invalid (left over from a previous attempt to write the file).

Atomic file does not confer any file locking semantics. Do not use this class when the file may be accessed or modified concurrently by multiple threads or processes. The caller is responsible for ensuring appropriate mutual exclusion invariants whenever it accesses the file.

Summary

Public Constructors
AtomicFile(File baseName)
Create a new AtomicFile for a file located at the given File path.
Public Methods
void delete()
Delete the atomic file.
void failWrite(FileOutputStream str)
Call when you have failed for some reason at writing to the stream returned by startWrite().
void finishWrite(FileOutputStream str)
Call when you have successfully finished writing to the stream returned by startWrite().
File getBaseFile()
Return the path to the base file.
FileInputStream openRead()
Open the atomic file for reading.
byte[] readFully()
A convenience for openRead() that also reads all of the file contents into a byte array which is returned.
FileOutputStream startWrite()
Start a new write operation on the file.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public AtomicFile (File baseName)

Added in API level 17

Create a new AtomicFile for a file located at the given File path. The secondary backup file will be the same file path with ".bak" appended.

Parameters
baseName File

Public Methods

public void delete ()

Added in API level 17

Delete the atomic file. This deletes both the base and backup files.

public void failWrite (FileOutputStream str)

Added in API level 17

Call when you have failed for some reason at writing to the stream returned by startWrite(). This will close the current write stream, and roll back to the previous state of the file.

Parameters
str FileOutputStream

public void finishWrite (FileOutputStream str)

Added in API level 17

Call when you have successfully finished writing to the stream returned by startWrite(). This will close, sync, and commit the new data. The next attempt to read the atomic file will return the new file stream.

Parameters
str FileOutputStream

public File getBaseFile ()

Added in API level 17

Return the path to the base file. You should not generally use this, as the data at that path may not be valid.

Returns
File

public FileInputStream openRead ()

Added in API level 17

Open the atomic file for reading. If there previously was an incomplete write, this will roll back to the last good data before opening for read. You should call close() on the FileInputStream when you are done reading from it.

Note that if another thread is currently performing a write, this will incorrectly consider it to be in the state of a bad write and roll back, causing the new data currently being written to be dropped. You must do your own threading protection for access to AtomicFile.

Returns
FileInputStream
Throws
FileNotFoundException

public byte[] readFully ()

Added in API level 17

A convenience for openRead() that also reads all of the file contents into a byte array which is returned.

Returns
byte[]
Throws
IOException

public FileOutputStream startWrite ()

Added in API level 17

Start a new write operation on the file. This returns a FileOutputStream to which you can write the new file data. The existing file is replaced with the new data. You must not directly close the given FileOutputStream; instead call either finishWrite(FileOutputStream) or failWrite(FileOutputStream).

Note that if another thread is currently performing a write, this will simply replace whatever that thread is writing with the new file being written by this thread, and when the other thread finishes the write the new write operation will no longer be safe (or will be lost). You must do your own threading protection for access to AtomicFile.

Returns
FileOutputStream
Throws
IOException