# BackupDeviceActionResult

Artifact: [androidx.test.backup:backup](https://developer.android.com/jetpack/androidx/releases/test-backup) [View Source](https://cs.android.com/search?q=file:androidx/test/backup/BackupDeviceAction.kt+class:androidx.test.backup.BackupDeviceActionResult) Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

*** ** * ** ***


```
public final class BackupDeviceActionResult
```

<br />

*** ** * ** ***

Results returned from a `https://developer.android.com/reference/androidx/test/backup/BackupDeviceAction` back to the host orchestrator.

`https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys` documents every key the actions bundled with this library produce. Actions built with `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#success(kotlin.collections.Map)` and `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#failure(kotlin.String,kotlin.collections.Map)` always report `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#STATUS()`, and report `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#ERROR()` only alongside a failure. Additional keys may be returned to carry data back to the host, which forwards the whole payload to the caller.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#BackupDeviceActionResult(kotlin.collections.Map)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Map.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html> payload )` |

| ### Public methods |
|---|---|
| `boolean` | `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#equals(kotlin.Any)(https://developer.android.com/reference/java/lang/Object.html other)` |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult` | `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#failure(kotlin.String,kotlin.collections.Map)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html errorMessage, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Map.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html> payload )` Returns a result reporting `https://developer.android.com/reference/androidx/test/backup/BackupActionValues#STATUS_FAILURE()` together with `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult.Companion#failure(kotlin.String,kotlin.collections.Map)`. |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#get(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html key)` Returns the result stored under `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#get(kotlin.String)`, or `null` when the action did not produce it. |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#getErrorMessage()()` The reported `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#ERROR()`, or `null` when the action did not fail. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Map.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html>` | `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#getPayload()()` key-value results produced by the action, keyed by `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys` |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#getStatus()()` The reported `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#STATUS()`, or `null` for an action that does not report one. |
| `int` | `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#hashCode()()` |
| `final boolean` | `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#isSuccess()()` Whether the action completed its work. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult` | `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#success(kotlin.collections.Map)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Map.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html> payload)` Returns a result reporting `https://developer.android.com/reference/androidx/test/backup/BackupActionValues#STATUS_SUCCESS()`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#toString()()` |

## Public constructors

### BackupDeviceActionResult

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
public BackupDeviceActionResult(
    @NonNull Map<@NonNull String, @NonNull String> payload
)
```

## Public methods

### equals

```
public boolean equals(Object other)
```

### failure

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
public static final @NonNull BackupDeviceActionResult failure(
    @NonNull String errorMessage,
    @NonNull Map<@NonNull String, @NonNull String> payload
)
```

Returns a result reporting `https://developer.android.com/reference/androidx/test/backup/BackupActionValues#STATUS_FAILURE()` together with `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult.Companion#failure(kotlin.String,kotlin.collections.Map)`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html errorMessage` | human-readable description of the failure, surfaced to the host as `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#ERROR()` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Map.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html> payload` | additional data to return to the host; `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#STATUS()` and `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#ERROR()` entries it contains are overwritten |

### get

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
public final String get(@NonNull String key)
```

Returns the result stored under `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#get(kotlin.String)`, or `null` when the action did not produce it.

Any key may be read, so a custom `https://developer.android.com/reference/androidx/test/backup/BackupDeviceAction` can return keys of its own alongside the `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys` constants.

### getErrorMessage

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
public final String getErrorMessage()
```

The reported `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#ERROR()`, or `null` when the action did not fail.

Reported only for a result that `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#isSuccess()` rejects. A successful action may legitimately carry a `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#ERROR()` entry of its own --- an empty string, or a diagnostic unrelated to the outcome --- and surfacing that as a failure message would be misleading. This mirrors the host, which reads the key under exactly the same conditions.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#isSuccess()` |   |

### getPayload

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
public final @NonNull Map<@NonNull String, @NonNull String> getPayload()
```

key-value results produced by the action, keyed by `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys`

### getStatus

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
public final String getStatus()
```

The reported `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#STATUS()`, or `null` for an action that does not report one.

Value is one of the following:

- `success`
- `failure`

<br />

### hashCode

```
public int hashCode()
```

### isSuccess

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
public final boolean isSuccess()
```

Whether the action completed its work.

Resolved in two steps:

- A reported `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#STATUS()` decides on its own. Only `https://developer.android.com/reference/androidx/test/backup/BackupActionValues#STATUS_FAILURE()`, compared without regard to case, means failure; `status` is a generic key that custom actions also use to publish their own vocabulary, so an unrecognized value is reported as successful rather than being guessed at.

- With no `status` at all, a non-empty `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#ERROR()` means failure. An action that reports only an error would otherwise be read as passing.

Use `https://developer.android.com/reference/androidx/test/backup/BackupDeviceActionResult#failure(kotlin.String,kotlin.collections.Map)` to report a failure that callers and the host will honor.

### success

Added in [1.0.0-alpha04](https://developer.android.com/jetpack/androidx/releases/test-backup#1.0.0-alpha04)

```
public static final @NonNull BackupDeviceActionResult success(@NonNull Map<@NonNull String, @NonNull String> payload)
```

Returns a result reporting `https://developer.android.com/reference/androidx/test/backup/BackupActionValues#STATUS_SUCCESS()`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Map.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html> payload` | additional data to return to the host; a `https://developer.android.com/reference/androidx/test/backup/BackupActionOutputKeys#STATUS()` entry it contains is overwritten |

### toString

```
public @NonNull String toString()
```