Status (grpc-all 1.55.1 API)

java.lang.Object
- io.grpc.Status

```
@Immutable
 @CheckReturnValue
public final class Status
extends Object
```
Defines the status of an operation by providing a standard Status.Code in conjunction with an optional descriptive message. Instances of Status are created by starting with the template for the appropriate Status.Code and supplementing it with additional information: Status.NOT_FOUND.withDescription("Could not find 'important_file.txt'");
For clients, every remote call will return a status on completion. In the case of errors this status may be propagated to blocking stubs as a RuntimeException or to a listener as an explicit parameter.
Similarly servers can report a status by throwing StatusRuntimeException or by passing the status to a callback.
Utility functions are provided to convert a status to an exception and to extract them back out.
Extended descriptions, including a list of codes that should not be generated by the library, can be found at doc/statuscodes.md

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Status.Code
The set of canonical status codes.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Status.Code` The set of canonical status codes.

Field Summary

Fields
Modifier and Type	Field and Description
`static Status`	`ABORTED` The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.
`static Status`	`ALREADY_EXISTS` Some entity that we attempted to create (e.g., file or directory) already exists.
`static Status`	`CANCELLED` The operation was cancelled (typically by the caller).
`static Status`	`DATA_LOSS` Unrecoverable data loss or corruption.
`static Status`	`DEADLINE_EXCEEDED` Deadline expired before operation could complete.
`static Status`	`FAILED_PRECONDITION` Operation was rejected because the system is not in a state required for the operation's execution.
`static Status`	`INTERNAL` Internal errors.
`static Status`	`INVALID_ARGUMENT` Client specified an invalid argument.
`static Status`	`NOT_FOUND` Some requested entity (e.g., file or directory) was not found.
`static Status`	`OK` The operation completed successfully.
`static Status`	`OUT_OF_RANGE` Operation was attempted past the valid range.
`static Status`	`PERMISSION_DENIED` The caller does not have permission to execute the specified operation.
`static Status`	`RESOURCE_EXHAUSTED` Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
`static Status`	`UNAUTHENTICATED` The request does not have valid authentication credentials for the operation.
`static Status`	`UNAVAILABLE` The service is currently unavailable.
`static Status`	`UNIMPLEMENTED` Operation is not implemented or not supported/enabled in this service.
`static Status`	`UNKNOWN` Unknown error.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`StatusException`	`asException()` Convert this `Status` to an `Exception`.
`StatusException`	`asException(Metadata trailers)` Same as `asException()` but includes the provided trailers in the returned exception.
`StatusRuntimeException`	`asRuntimeException()` Convert this `Status` to a `RuntimeException`.
`StatusRuntimeException`	`asRuntimeException(Metadata trailers)` Same as `asRuntimeException()` but includes the provided trailers in the returned exception.
`Status`	`augmentDescription(String additionalDetail)` Create a derived instance of `Status` augmenting the current description with additional detail.
`boolean`	`equals(Object obj)` Equality on Statuses is not well defined.
`static Status`	`fromCode(Status.Code code)` Return a `Status` given a canonical error `Status.Code` object.
`static Status`	`fromCodeValue(int codeValue)` Return a `Status` given a canonical error `Status.Code` value.
`static Status`	`fromThrowable(Throwable t)` Extract an error `Status` from the causal chain of a `Throwable`.
`Throwable`	`getCause()` The underlying cause of an error.
`Status.Code`	`getCode()` The canonical status code.
`String`	`getDescription()` A description of this status for human consumption.
`int`	`hashCode()` Hash codes on Statuses are not well defined.
`boolean`	`isOk()` Is this status OK, i.e., not an error.
`String`	`toString()` A string representation of the status useful for debugging.
`static Metadata`	`trailersFromThrowable(Throwable t)` Extract an error trailers from the causal chain of a `Throwable`.
`Status`	`withCause(Throwable cause)` Create a derived instance of `Status` with the given cause.
`Status`	`withDescription(String description)` Create a derived instance of `Status` with the given description.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - OK
```
public static final Status OK
```
    The operation completed successfully.
  - CANCELLED
```
public static final Status CANCELLED
```
    The operation was cancelled (typically by the caller).
  - UNKNOWN
```
public static final Status UNKNOWN
```
    Unknown error. See Status.Code.UNKNOWN.
  - INVALID_ARGUMENT
```
public static final Status INVALID_ARGUMENT
```
    Client specified an invalid argument. See Status.Code.INVALID_ARGUMENT.
  - DEADLINE_EXCEEDED
```
public static final Status DEADLINE_EXCEEDED
```
    Deadline expired before operation could complete. See Status.Code.DEADLINE_EXCEEDED.
  - NOT_FOUND
```
public static final Status NOT_FOUND
```
    Some requested entity (e.g., file or directory) was not found.
  - ALREADY_EXISTS
```
public static final Status ALREADY_EXISTS
```
    Some entity that we attempted to create (e.g., file or directory) already exists.
  - PERMISSION_DENIED
```
public static final Status PERMISSION_DENIED
```
    The caller does not have permission to execute the specified operation. See Status.Code.PERMISSION_DENIED.
  - UNAUTHENTICATED
```
public static final Status UNAUTHENTICATED
```
    The request does not have valid authentication credentials for the operation.
  - RESOURCE_EXHAUSTED
```
public static final Status RESOURCE_EXHAUSTED
```
    Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
  - FAILED_PRECONDITION
```
public static final Status FAILED_PRECONDITION
```
    Operation was rejected because the system is not in a state required for the operation's execution. See Status.Code.FAILED_PRECONDITION.
  - ABORTED
```
public static final Status ABORTED
```
    The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc. See Status.Code.ABORTED.
  - OUT_OF_RANGE
```
public static final Status OUT_OF_RANGE
```
    Operation was attempted past the valid range. See Status.Code.OUT_OF_RANGE.
  - UNIMPLEMENTED
```
public static final Status UNIMPLEMENTED
```
    Operation is not implemented or not supported/enabled in this service.
  - INTERNAL
```
public static final Status INTERNAL
```
    Internal errors. See Status.Code.INTERNAL.
  - UNAVAILABLE
```
public static final Status UNAVAILABLE
```
    The service is currently unavailable. See Status.Code.UNAVAILABLE.
  - DATA_LOSS
```
public static final Status DATA_LOSS
```
    Unrecoverable data loss or corruption.
- Method Detail
  - fromCodeValue
```
public static Status fromCodeValue(int codeValue)
```
    Return a Status given a canonical error Status.Code value.
  - fromCode
```
public static Status fromCode(Status.Code code)
```
    Return a Status given a canonical error Status.Code object.
  - fromThrowable
```
public static Status fromThrowable(Throwable t)
```
    Extract an error Status from the causal chain of a Throwable. If no status can be found, a status is created with Status.Code.UNKNOWN as its code and t as its cause.
    
    Returns:
    
    non-null status
  - trailersFromThrowable
```
@Nullable
 @ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/4683")
public static Metadata trailersFromThrowable(Throwable t)
```
    Extract an error trailers from the causal chain of a Throwable.
    
    Returns:
    
    the trailers or null if not found.
  - withCause
```
public Status withCause(Throwable cause)
```
    Create a derived instance of Status with the given cause. However, the cause is not transmitted from server to client.
  - withDescription
```
public Status withDescription(String description)
```
    Create a derived instance of Status with the given description. Leading and trailing whitespace may be removed; this may change in the future.
  - augmentDescription
```
public Status augmentDescription(String additionalDetail)
```
    Create a derived instance of Status augmenting the current description with additional detail. Leading and trailing whitespace may be removed; this may change in the future.
  - getCode
```
public Status.Code getCode()
```
    The canonical status code.
  - getDescription
```
@Nullable
public String getDescription()
```
    A description of this status for human consumption.
  - getCause
```
@Nullable
public Throwable getCause()
```
    The underlying cause of an error. Note that the cause is not transmitted from server to client.
  - isOk
```
public boolean isOk()
```
    Is this status OK, i.e., not an error.
  - asRuntimeException
```
public StatusRuntimeException asRuntimeException()
```
    Convert this Status to a RuntimeException. Use fromThrowable(java.lang.Throwable) to recover this Status instance when the returned exception is in the causal chain.
  - asRuntimeException
```
@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/4683")
public StatusRuntimeException asRuntimeException(@Nullable
                                                                                                                         Metadata trailers)
```
    Same as asRuntimeException() but includes the provided trailers in the returned exception.
  - asException
```
public StatusException asException()
```
    Convert this Status to an Exception. Use fromThrowable(java.lang.Throwable) to recover this Status instance when the returned exception is in the causal chain.
  - asException
```
public StatusException asException(@Nullable
                                   Metadata trailers)
```
    Same as asException() but includes the provided trailers in the returned exception.
  - toString
```
public String toString()
```
    A string representation of the status useful for debugging.
    
    Overrides:
    
    toString in class Object
  - equals
```
public boolean equals(Object obj)
```
    Equality on Statuses is not well defined. Instead, do comparison based on their Code with getCode(). The description and cause of the Status are unlikely to be stable, and additional fields may be added to Status in the future.
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Hash codes on Statuses are not well defined.
    
    Overrides:
    
    hashCode in class Object
    
    See Also:
    
    equals(java.lang.Object)

Class Status

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

OK

CANCELLED

UNKNOWN

INVALID_ARGUMENT

DEADLINE_EXCEEDED

NOT_FOUND

ALREADY_EXISTS

PERMISSION_DENIED

UNAUTHENTICATED

RESOURCE_EXHAUSTED

FAILED_PRECONDITION

ABORTED

OUT_OF_RANGE

UNIMPLEMENTED

INTERNAL

UNAVAILABLE

DATA_LOSS

Method Detail

fromCodeValue

fromCode

fromThrowable

trailersFromThrowable

withCause

withDescription

augmentDescription

getCode

getDescription

getCause

isOk

asRuntimeException

asRuntimeException

asException

asException

toString

equals

hashCode