Class Status
- java.lang.Object
-
- io.grpc.Status
-
@Immutable @CheckReturnValue public final class Status extends java.lang.Object
Defines the status of an operation by providing a standardStatus.Code
in conjunction with an optional descriptive message. Instances ofStatus
are created by starting with the template for the appropriateStatus.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 Description static class
Status.Code
The set of canonical status codes.private static class
Status.StatusCodeMarshaller
private static class
Status.StatusMessageMarshaller
-
Field Summary
Fields Modifier and Type Field 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).private java.lang.Throwable
cause
private Status.Code
code
(package private) static Metadata.Key<Status>
CODE_KEY
Key to bind status code to trailing metadata.static Status
DATA_LOSS
Unrecoverable data loss or corruption.static Status
DEADLINE_EXCEEDED
Deadline expired before operation could complete.private java.lang.String
description
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.(package private) static Metadata.Key<java.lang.String>
MESSAGE_KEY
Key to bind status message to trailing metadata.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.private static java.util.List<Status>
STATUS_LIST
private static Metadata.TrustedAsciiMarshaller<java.lang.String>
STATUS_MESSAGE_MARSHALLER
Marshals status messages for (MESSAGE_KEY
.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.
-
Constructor Summary
Constructors Modifier Constructor Description private
Status(Status.Code code)
private
Status(Status.Code code, java.lang.String description, java.lang.Throwable cause)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description StatusException
asException()
Convert thisStatus
to anException
.StatusException
asException(Metadata trailers)
Same asasException()
but includes the provided trailers in the returned exception.StatusRuntimeException
asRuntimeException()
Convert thisStatus
to aRuntimeException
.StatusRuntimeException
asRuntimeException(Metadata trailers)
Same asasRuntimeException()
but includes the provided trailers in the returned exception.Status
augmentDescription(java.lang.String additionalDetail)
Create a derived instance ofStatus
augmenting the current description with additional detail.private static java.util.List<Status>
buildStatusList()
boolean
equals(java.lang.Object obj)
Equality on Statuses is not well defined.(package private) static java.lang.String
formatThrowableMessage(Status status)
static Status
fromCode(Status.Code code)
Return aStatus
given a canonical errorStatus.Code
object.private static Status
fromCodeValue(byte[] asciiCodeValue)
static Status
fromCodeValue(int codeValue)
Return aStatus
given a canonical errorStatus.Code
value.private static Status
fromCodeValueSlow(byte[] asciiCodeValue)
static Status
fromThrowable(java.lang.Throwable t)
Extract an errorStatus
from the causal chain of aThrowable
.java.lang.Throwable
getCause()
The underlying cause of an error.Status.Code
getCode()
The canonical status code.java.lang.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.java.lang.String
toString()
A string representation of the status useful for debugging.static Metadata
trailersFromThrowable(java.lang.Throwable t)
Extract an error trailers from the causal chain of aThrowable
.Status
withCause(java.lang.Throwable cause)
Create a derived instance ofStatus
with the given cause.Status
withDescription(java.lang.String description)
Create a derived instance ofStatus
with the given description.
-
-
-
Field Detail
-
STATUS_LIST
private static final java.util.List<Status> STATUS_LIST
-
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. SeeStatus.Code.UNKNOWN
.
-
INVALID_ARGUMENT
public static final Status INVALID_ARGUMENT
Client specified an invalid argument. SeeStatus.Code.INVALID_ARGUMENT
.
-
DEADLINE_EXCEEDED
public static final Status DEADLINE_EXCEEDED
Deadline expired before operation could complete. SeeStatus.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. SeeStatus.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. SeeStatus.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. SeeStatus.Code.ABORTED
.
-
OUT_OF_RANGE
public static final Status OUT_OF_RANGE
Operation was attempted past the valid range. SeeStatus.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. SeeStatus.Code.INTERNAL
.
-
UNAVAILABLE
public static final Status UNAVAILABLE
The service is currently unavailable. SeeStatus.Code.UNAVAILABLE
.
-
DATA_LOSS
public static final Status DATA_LOSS
Unrecoverable data loss or corruption.
-
CODE_KEY
static final Metadata.Key<Status> CODE_KEY
Key to bind status code to trailing metadata.
-
STATUS_MESSAGE_MARSHALLER
private static final Metadata.TrustedAsciiMarshaller<java.lang.String> STATUS_MESSAGE_MARSHALLER
Marshals status messages for (MESSAGE_KEY
. gRPC does not use binary coding of status messages by default, which makes sending arbitrary strings difficult. This marshaller uses ASCII printable characters by default, and percent encodes (e.g. %0A) all non ASCII bytes. This leads to normal text being mostly readable (especially useful for debugging), and special text still being sent.By default, the HTTP spec says that header values must be encoded using a strict subset of ASCII (See RFC 7230 section 3.2.6). HTTP/2 HPACK allows use of arbitrary binary headers, but we do not use them for interoperating with existing HTTP/1.1 code. Since the grpc-message is encoded to such a header, it needs to not use forbidden characters.
This marshaller works by converting the passed in string into UTF-8, checking to see if each individual byte is an allowable byte, and then either percent encoding or passing it through. When percent encoding, the byte is converted into hexadecimal notation with a '%' prepended.
When unmarshalling, bytes are passed through unless they match the "%XX" pattern. If they do match, the unmarshaller attempts to convert them back into their original UTF-8 byte sequence. After the input header bytes are converted into UTF-8 bytes, the new byte array is reinterpretted back as a string.
-
MESSAGE_KEY
static final Metadata.Key<java.lang.String> MESSAGE_KEY
Key to bind status message to trailing metadata.
-
code
private final Status.Code code
-
description
private final java.lang.String description
-
cause
private final java.lang.Throwable cause
-
-
Constructor Detail
-
Status
private Status(Status.Code code)
-
Status
private Status(Status.Code code, @Nullable java.lang.String description, @Nullable java.lang.Throwable cause)
-
-
Method Detail
-
buildStatusList
private static java.util.List<Status> buildStatusList()
-
fromCodeValue
public static Status fromCodeValue(int codeValue)
Return aStatus
given a canonical errorStatus.Code
value.
-
fromCodeValue
private static Status fromCodeValue(byte[] asciiCodeValue)
-
fromCodeValueSlow
private static Status fromCodeValueSlow(byte[] asciiCodeValue)
-
fromCode
public static Status fromCode(Status.Code code)
Return aStatus
given a canonical errorStatus.Code
object.
-
fromThrowable
public static Status fromThrowable(java.lang.Throwable t)
Extract an errorStatus
from the causal chain of aThrowable
. If no status can be found, a status is created withStatus.Code.UNKNOWN
as its code andt
as its cause.- Returns:
- non-
null
status
-
trailersFromThrowable
@Nullable public static Metadata trailersFromThrowable(java.lang.Throwable t)
Extract an error trailers from the causal chain of aThrowable
.- Returns:
- the trailers or
null
if not found.
-
formatThrowableMessage
static java.lang.String formatThrowableMessage(Status status)
-
withCause
public Status withCause(java.lang.Throwable cause)
Create a derived instance ofStatus
with the given cause. However, the cause is not transmitted from server to client.
-
withDescription
public Status withDescription(java.lang.String description)
Create a derived instance ofStatus
with the given description. Leading and trailing whitespace may be removed; this may change in the future.
-
augmentDescription
public Status augmentDescription(java.lang.String additionalDetail)
Create a derived instance ofStatus
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 java.lang.String getDescription()
A description of this status for human consumption.
-
getCause
@Nullable public java.lang.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 thisStatus
to aRuntimeException
. UsefromThrowable(java.lang.Throwable)
to recover thisStatus
instance when the returned exception is in the causal chain.
-
asRuntimeException
public StatusRuntimeException asRuntimeException(@Nullable Metadata trailers)
Same asasRuntimeException()
but includes the provided trailers in the returned exception.
-
asException
public StatusException asException()
Convert thisStatus
to anException
. UsefromThrowable(java.lang.Throwable)
to recover thisStatus
instance when the returned exception is in the causal chain.
-
asException
public StatusException asException(@Nullable Metadata trailers)
Same asasException()
but includes the provided trailers in the returned exception.
-
toString
public java.lang.String toString()
A string representation of the status useful for debugging.- Overrides:
toString
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object obj)
Equality on Statuses is not well defined. Instead, do comparison based on their Code withgetCode()
. 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 classjava.lang.Object
-
hashCode
public int hashCode()
Hash codes on Statuses are not well defined.- Overrides:
hashCode
in classjava.lang.Object
- See Also:
equals(java.lang.Object)
-
-