# AtomicFile

Artifact: [androidx.core:core](https://developer.android.com/jetpack/androidx/releases/core) [View Source](https://cs.android.com/search?q=file:androidx/core/util/AtomicFile.java+class:androidx.core.util.AtomicFile) Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/core#1.1.0)

*** ** * ** ***


```
public class AtomicFile
```

<br />

*** ** * ** ***

Static library support version of the framework's `https://developer.android.com/reference/android/util/AtomicFile.html`, a helper class for performing atomic operations on a file by writing to a new file and renaming it into the place of the original file after the write has successfully completed.

Atomic file guarantees file integrity by ensuring that a file has been completely written and sync'd to disk before renaming it to the original file. Previously this was done by renaming the original 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 |
|---|
| `https://developer.android.com/reference/androidx/core/util/AtomicFile#AtomicFile(java.io.File)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/File.html baseName)` Create a new AtomicFile for a file located at the given File path. |

| ### Public methods |
|---|---|
| `void` | `https://developer.android.com/reference/androidx/core/util/AtomicFile#delete()()` Delete the atomic file. |
| `void` | `https://developer.android.com/reference/androidx/core/util/AtomicFile#failWrite(java.io.FileOutputStream)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/io/FileOutputStream.html str)` Call when you have failed for some reason at writing to the stream returned by `https://developer.android.com/reference/androidx/core/util/AtomicFile#startWrite()`. |
| `void` | `https://developer.android.com/reference/androidx/core/util/AtomicFile#finishWrite(java.io.FileOutputStream)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/io/FileOutputStream.html str)` Call when you have successfully finished writing to the stream returned by `https://developer.android.com/reference/androidx/core/util/AtomicFile#startWrite()`. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/File.html` | `https://developer.android.com/reference/androidx/core/util/AtomicFile#getBaseFile()()` Return the path to the base file. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/FileInputStream.html` | `https://developer.android.com/reference/androidx/core/util/AtomicFile#openRead()()` Open the atomic file for reading. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html byte[]` | `https://developer.android.com/reference/androidx/core/util/AtomicFile#readFully()()` A convenience for `https://developer.android.com/reference/androidx/core/util/AtomicFile#openRead()` that also reads all of the file contents into a byte array which is returned. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/FileOutputStream.html` | `https://developer.android.com/reference/androidx/core/util/AtomicFile#startWrite()()` Start a new write operation on the file. |

## Public constructors

### AtomicFile

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/core#1.1.0)

```
public AtomicFile(@NonNull 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.

## Public methods

### delete

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/core#1.1.0)

```
public void delete()
```

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

### failWrite

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/core#1.1.0)

```
public void failWrite(@Nullable FileOutputStream str)
```

Call when you have failed for some reason at writing to the stream returned by `https://developer.android.com/reference/androidx/core/util/AtomicFile#startWrite()`. This will close the current write stream, and delete the new file.

### finishWrite

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/core#1.1.0)

```
public void finishWrite(@Nullable FileOutputStream str)
```

Call when you have successfully finished writing to the stream returned by `https://developer.android.com/reference/androidx/core/util/AtomicFile#startWrite()`. This will close, sync, and commit the new data. The next attempt to read the atomic file will return the new file stream.

### getBaseFile

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/core#1.1.0)

```
public @NonNull 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.

### openRead

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/core#1.1.0)

```
public @NonNull 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.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/io/FileNotFoundException.html` |   |

### readFully

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/core#1.1.0)

```
public @NonNull byte[] readFully()
```

A convenience for `https://developer.android.com/reference/androidx/core/util/AtomicFile#openRead()` that also reads all of the file contents into a byte array which is returned.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/io/IOException.html` |   |

### startWrite

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/core#1.1.0)

```
public @NonNull 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 `https://developer.android.com/reference/androidx/core/util/AtomicFile#finishWrite(java.io.FileOutputStream)` or `https://developer.android.com/reference/androidx/core/util/AtomicFile#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.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/io/IOException.html` |   |