Package io.grpc

Class Status

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

  • Field Details

    • STATUS_LIST

      private static final 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. 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.
    • 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<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<String> MESSAGE_KEY
      Key to bind status message to trailing metadata.
    • code

      private final Status.Code code
    • description

      private final String description
    • cause

      private final Throwable cause
  • Constructor Details

  • Method Details

    • buildStatusList

      private static List<Status> buildStatusList()
    • fromCodeValue

      public static Status fromCodeValue(int codeValue)
      Return a Status given a canonical error Status.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 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 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.
    • formatThrowableMessage

      static String formatThrowableMessage(Status status)
    • 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

      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: