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

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

  • Method Details

    • fromCodeValue

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

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

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