Package io.grpc

Class Status

  • @Immutable
@CheckReturnValue
public final class Status
extends java.lang.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 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).

      • 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.

      • 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.

      • UNIMPLEMENTED

        public static final Status UNIMPLEMENTED
        Operation is not implemented or not supported/enabled in this service.

      • 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.

      • description

        private final java.lang.String description

      • cause

        private final java.lang.Throwable cause

    • Constructor Detail

      • 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 a Status given a canonical error Status.Code value.

      • fromCodeValue

        private static Status fromCodeValue​(byte[] asciiCodeValue)

      • fromCodeValueSlow

        private static Status fromCodeValueSlow​(byte[] asciiCodeValue)

      • fromThrowable

        public static Status fromThrowable​(java.lang.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​(java.lang.Throwable t)
        Extract an error trailers from the causal chain of a Throwable.
        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 of Status 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 of Status 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 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 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.

      • toString

        public java.lang.String toString()
        A string representation of the status useful for debugging.
        Overrides:
        toString in class java.lang.Object

      • equals

        public boolean equals​(java.lang.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 java.lang.Object

      • hashCode

        public int hashCode()
        Hash codes on Statuses are not well defined.
        Overrides:
        hashCode in class java.lang.Object
        See Also:
        equals(java.lang.Object)