Package io.grpc

Class 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 Detail

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

    • Method Detail

      • fromCodeValue

        public static Status fromCodeValue​(int codeValue)
        Return a Status given a canonical error Status.Code value.

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

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

      • 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