Class Status
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 ClassesModifier and TypeClassDescriptionstatic enum
The set of canonical status codes.private static final class
private static final class
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final Status
The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.static final Status
Some entity that we attempted to create (e.g., file or directory) already exists.static final Status
The operation was cancelled (typically by the caller).private final Throwable
private final Status.Code
(package private) static final Metadata.Key
<Status> Key to bind status code to trailing metadata.static final Status
Unrecoverable data loss or corruption.static final Status
Deadline expired before operation could complete.private final String
static final Status
Operation was rejected because the system is not in a state required for the operation's execution.static final Status
Internal errors.static final Status
Client specified an invalid argument.(package private) static final Metadata.Key
<String> Key to bind status message to trailing metadata.static final Status
Some requested entity (e.g., file or directory) was not found.static final Status
The operation completed successfully.static final Status
Operation was attempted past the valid range.static final Status
The caller does not have permission to execute the specified operation.static final Status
Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.private static final Metadata.TrustedAsciiMarshaller
<String> Marshals status messages for (MESSAGE_KEY
.static final Status
The request does not have valid authentication credentials for the operation.static final Status
The service is currently unavailable.static final Status
Operation is not implemented or not supported/enabled in this service.static final Status
Unknown error. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Status
(Status.Code code) private
Status
(Status.Code code, String description, Throwable cause) -
Method Summary
Modifier and TypeMethodDescriptionasException
(Metadata trailers) Same asasException()
but includes the provided trailers in the returned exception.Convert thisStatus
to aRuntimeException
.asRuntimeException
(Metadata trailers) Same asasRuntimeException()
but includes the provided trailers in the returned exception.augmentDescription
(String additionalDetail) Create a derived instance ofStatus
augmenting the current description with additional detail.boolean
Equality on Statuses is not well defined.(package private) static 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
getCause()
The underlying cause of an error.getCode()
The canonical status code.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.toString()
A string representation of the status useful for debugging.static Metadata
Extract an error trailers from the causal chain of aThrowable
.Create a derived instance ofStatus
with the given cause.withDescription
(String description) Create a derived instance ofStatus
with the given description.
-
Field Details
-
STATUS_LIST
-
OK
The operation completed successfully. -
CANCELLED
The operation was cancelled (typically by the caller). -
UNKNOWN
Unknown error. SeeStatus.Code.UNKNOWN
. -
INVALID_ARGUMENT
Client specified an invalid argument. SeeStatus.Code.INVALID_ARGUMENT
. -
DEADLINE_EXCEEDED
Deadline expired before operation could complete. SeeStatus.Code.DEADLINE_EXCEEDED
. -
NOT_FOUND
Some requested entity (e.g., file or directory) was not found. -
ALREADY_EXISTS
Some entity that we attempted to create (e.g., file or directory) already exists. -
PERMISSION_DENIED
The caller does not have permission to execute the specified operation. SeeStatus.Code.PERMISSION_DENIED
. -
UNAUTHENTICATED
The request does not have valid authentication credentials for the operation. -
RESOURCE_EXHAUSTED
Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. -
FAILED_PRECONDITION
Operation was rejected because the system is not in a state required for the operation's execution. SeeStatus.Code.FAILED_PRECONDITION
. -
ABORTED
The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc. SeeStatus.Code.ABORTED
. -
OUT_OF_RANGE
Operation was attempted past the valid range. SeeStatus.Code.OUT_OF_RANGE
. -
UNIMPLEMENTED
Operation is not implemented or not supported/enabled in this service. -
INTERNAL
Internal errors. SeeStatus.Code.INTERNAL
. -
UNAVAILABLE
The service is currently unavailable. SeeStatus.Code.UNAVAILABLE
. -
DATA_LOSS
Unrecoverable data loss or corruption. -
CODE_KEY
Key to bind status code to trailing metadata. -
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
Key to bind status message to trailing metadata. -
code
-
description
-
cause
-
-
Constructor Details
-
Status
-
Status
-
-
Method Details
-
buildStatusList
-
fromCodeValue
Return aStatus
given a canonical errorStatus.Code
value. -
fromCodeValue
-
fromCodeValueSlow
-
fromCode
Return aStatus
given a canonical errorStatus.Code
object. -
fromThrowable
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
Extract an error trailers from the causal chain of aThrowable
.- Returns:
- the trailers or
null
if not found.
-
formatThrowableMessage
-
withCause
Create a derived instance ofStatus
with the given cause. However, the cause is not transmitted from server to client. -
withDescription
Create a derived instance ofStatus
with the given description. Leading and trailing whitespace may be removed; this may change in the future. -
augmentDescription
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
The canonical status code. -
getDescription
A description of this status for human consumption. -
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
Convert thisStatus
to aRuntimeException
. UsefromThrowable(java.lang.Throwable)
to recover thisStatus
instance when the returned exception is in the causal chain. -
asRuntimeException
Same asasRuntimeException()
but includes the provided trailers in the returned exception. -
asException
Convert thisStatus
to anException
. UsefromThrowable(java.lang.Throwable)
to recover thisStatus
instance when the returned exception is in the causal chain. -
asException
Same asasException()
but includes the provided trailers in the returned exception. -
toString
A string representation of the status useful for debugging. -
equals
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. -
hashCode
public int hashCode()Hash codes on Statuses are not well defined.
-