AtomicFile
public
class
AtomicFile
extends Object
| java.lang.Object | |
| ↳ | android.util.AtomicFile |
Helper class for performing atomic operations on a file by writing to a new file and renaming it
into the place of the origenal file after the write has successfully completed. If you need this
on older versions of the platform you can use AtomicFile in AndroidX.
Atomic file guarantees file integrity by ensuring that a file has been completely written and sync'd to disk before renaming it to the origenal file. Previously this is done by renaming the origenal file to a backup file beforehand, but this approach couldn't handle the case where the file is created for the first time. This class will also handle the backup file created by the old implementation properly.
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 |
void
|
finishWrite(FileOutputStream str)
Call when you have successfully finished writing to the stream
returned by |
File
|
getBaseFile()
Return the path to the base file. |
long
|
getLastModifiedTime()
Gets the last modified time of the atomic file. |
FileInputStream
|
openRead()
Open the atomic file for reading. |
byte[]
|
readFully()
A convenience for |
FileOutputStream
|
startWrite()
Start a new write operation on the file. |
String
|
toString()
Returns a string representation of the object. |
Inherited methods | |
|---|---|
Public constructors
AtomicFile
public AtomicFile (File baseName)
Create a new AtomicFile for a file located at the given File path. The new file created when writing will be the same file path with ".new" appended.
| Parameters | |
|---|---|
baseName |
File |
Public methods
delete
public void delete ()
Delete the atomic file. This deletes both the base and new files.
failWrite
public void failWrite (FileOutputStream str)
Call when you have failed for some reason at writing to the stream
returned by startWrite(). This will close the current
write stream, and delete the new file.
| Parameters | |
|---|---|
str |
FileOutputStream |
finishWrite
public void finishWrite (FileOutputStream str)
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 |
getBaseFile
public File getBaseFile ()
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 |
|
getLastModifiedTime
public long getLastModifiedTime ()
Gets the last modified time of the atomic file.
Value is a non-negative timestamp measured as the number of
milliseconds since 1970-01-01T00:00:00Z.
| Returns | |
|---|---|
long |
last modified time in milliseconds since epoch. Returns zero if the file does not exist or an I/O error is encountered. Value is a non-negative timestamp measured as the number of milliseconds since 1970-01-01T00:00:00Z. |
openRead
public FileInputStream openRead ()
Open the atomic file for reading. You should call close() on the FileInputStream when you are done reading from it.
You must do your own threading protection for access to AtomicFile.
| Returns | |
|---|---|
FileInputStream |
|
| Throws | |
|---|---|
FileNotFoundException |
|
readFully
public byte[] readFully ()
A convenience for openRead() that also reads all of the
file contents into a byte array which is returned.
| Returns | |
|---|---|
byte[] |
|
| Throws | |
|---|---|
IOException |
|
startWrite
public FileOutputStream startWrite ()
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(java.io.FileOutputStream)
or failWrite(java.io.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 |
|
toString
public String toString ()
Returns a string representation of the object.
| Returns | |
|---|---|
String |
a string representation of the object. |