@Immutable @CheckReturnValue public final class Status extends Object
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
Modifier and Type | Class and Description |
---|---|
static class |
Status.Code
The set of canonical status codes.
|
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.
|
Modifier and Type | Method and Description |
---|---|
StatusException |
asException()
|
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)
|
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. |
public static final Status OK
public static final Status CANCELLED
public static final Status UNKNOWN
Status.Code.UNKNOWN
.public static final Status INVALID_ARGUMENT
Status.Code.INVALID_ARGUMENT
.public static final Status DEADLINE_EXCEEDED
Status.Code.DEADLINE_EXCEEDED
.public static final Status NOT_FOUND
public static final Status ALREADY_EXISTS
public static final Status PERMISSION_DENIED
Status.Code.PERMISSION_DENIED
.public static final Status UNAUTHENTICATED
public static final Status RESOURCE_EXHAUSTED
public static final Status FAILED_PRECONDITION
Status.Code.FAILED_PRECONDITION
.public static final Status ABORTED
Status.Code.ABORTED
.public static final Status OUT_OF_RANGE
Status.Code.OUT_OF_RANGE
.public static final Status UNIMPLEMENTED
public static final Status INTERNAL
Status.Code.INTERNAL
.public static final Status UNAVAILABLE
Status.Code.UNAVAILABLE
.public static final Status DATA_LOSS
public static Status fromCodeValue(int codeValue)
Status
given a canonical error Status.Code
value.public static Status fromCode(Status.Code code)
Status
given a canonical error Status.Code
object.public static Status fromThrowable(Throwable t)
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.null
status@Nullable @ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/4683") public static Metadata trailersFromThrowable(Throwable t)
Throwable
.null
if not found.public Status withCause(Throwable cause)
Status
with the given cause.
However, the cause is not transmitted from server to client.public Status withDescription(String description)
Status
with the given description. Leading and trailing
whitespace may be removed; this may change in the future.public Status augmentDescription(String additionalDetail)
Status
augmenting the current description with
additional detail. Leading and trailing whitespace may be removed; this may change in the
future.public Status.Code getCode()
@Nullable public String getDescription()
@Nullable public Throwable getCause()
public boolean isOk()
public StatusRuntimeException asRuntimeException()
Status
to a RuntimeException
. Use fromThrowable(java.lang.Throwable)
to recover this Status
instance when the returned exception is in the causal chain.@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/4683") public StatusRuntimeException asRuntimeException(@Nullable Metadata trailers)
asRuntimeException()
but includes the provided trailers in the returned
exception.public StatusException asException()
Status
to an Exception
. Use fromThrowable(java.lang.Throwable)
to recover this Status
instance when the returned exception is in the causal chain.public StatusException asException(@Nullable Metadata trailers)
asException()
but includes the provided trailers in the returned exception.public String toString()
public boolean equals(Object obj)
getCode()
. The description and cause of the Status are unlikely to be stable, and
additional fields may be added to Status in the future.public int hashCode()
hashCode
in class Object
equals(java.lang.Object)