com.ironcorelabs.shaded.opencensus.trace.Status Maven / Gradle / Ivy
Show all versions of tenant-security-java Show documentation
/*
* Copyright 2016-17, OpenCensus Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.opencensus.trace;
import io.opencensus.internal.Utils;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.TreeMap;
import javax.annotation.Nullable;
import javax.annotation.concurrent.Immutable;
/*>>>
import org.checkerframework.dataflow.qual.Deterministic;
*/
/**
* Defines the status of a {@link Span} by providing a standard {@link CanonicalCode} in conjunction
* with an optional descriptive message. Instances of {@code Status} are created by starting with
* the template for the appropriate {@link Status.CanonicalCode} and supplementing it with
* additional information: {@code Status.NOT_FOUND.withDescription("Could not find
* 'important_file.txt'");}
*
* @since 0.5
*/
@Immutable
public final class Status {
/**
* The set of canonical status codes. If new codes are added over time they must choose a
* numerical value that does not collide with any previously used value.
*
* @since 0.5
*/
public enum CanonicalCode {
/**
* The operation completed successfully.
*
* @since 0.5
*/
OK(0),
/**
* The operation was cancelled (typically by the caller).
*
* @since 0.5
*/
CANCELLED(1),
/**
* Unknown error. An example of where this error may be returned is if a Status value received
* from another address space belongs to an error-space that is not known in this address space.
* Also errors raised by APIs that do not return enough error information may be converted to
* this error.
*
* @since 0.5
*/
UNKNOWN(2),
/**
* Client specified an invalid argument. Note that this differs from FAILED_PRECONDITION.
* INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the
* system (e.g., a malformed file name).
*
* @since 0.5
*/
INVALID_ARGUMENT(3),
/**
* Deadline expired before operation could complete. For operations that change the state of the
* system, this error may be returned even if the operation has completed successfully. For
* example, a successful response from a server could have been delayed long enough for the
* deadline to expire.
*
* @since 0.5
*/
DEADLINE_EXCEEDED(4),
/**
* Some requested entity (e.g., file or directory) was not found.
*
* @since 0.5
*/
NOT_FOUND(5),
/**
* Some entity that we attempted to create (e.g., file or directory) already exists.
*
* @since 0.5
*/
ALREADY_EXISTS(6),
/**
* The caller does not have permission to execute the specified operation. PERMISSION_DENIED
* must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED
* instead for those errors). PERMISSION_DENIED must not be used if the caller cannot be
* identified (use UNAUTHENTICATED instead for those errors).
*
* @since 0.5
*/
PERMISSION_DENIED(7),
/**
* Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system
* is out of space.
*
* @since 0.5
*/
RESOURCE_EXHAUSTED(8),
/**
* Operation was rejected because the system is not in a state required for the operation's
* execution. For example, directory to be deleted may be non-empty, an rmdir operation is
* applied to a non-directory, etc.
*
* A litmus test that may help a service implementor in deciding between FAILED_PRECONDITION,
* ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call.
* (b) Use ABORTED if the client should retry at a higher-level (e.g., restarting a
* read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until
* the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory
* is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless
* they have first fixed up the directory by deleting files from it.
*
* @since 0.5
*/
FAILED_PRECONDITION(9),
/**
* The operation was aborted, typically due to a concurrency issue like sequencer check
* failures, transaction aborts, etc.
*
*
See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
*
* @since 0.5
*/
ABORTED(10),
/**
* Operation was attempted past the valid range. E.g., seeking or reading past end of file.
*
*
Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system
* state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to
* read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if
* asked to read from an offset past the current file size.
*
*
There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend
* using OUT_OF_RANGE (the more specific error) when it applies so that callers who are
* iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are
* done.
*
* @since 0.5
*/
OUT_OF_RANGE(11),
/**
* Operation is not implemented or not supported/enabled in this service.
*
* @since 0.5
*/
UNIMPLEMENTED(12),
/**
* Internal errors. Means some invariants expected by underlying system has been broken. If you
* see one of these errors, something is very broken.
*
* @since 0.5
*/
INTERNAL(13),
/**
* The service is currently unavailable. This is a most likely a transient condition and may be
* corrected by retrying with a backoff.
*
*
See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
*
* @since 0.5
*/
UNAVAILABLE(14),
/**
* Unrecoverable data loss or corruption.
*
* @since 0.5
*/
DATA_LOSS(15),
/**
* The request does not have valid authentication credentials for the operation.
*
* @since 0.5
*/
UNAUTHENTICATED(16);
private final int value;
private CanonicalCode(int value) {
this.value = value;
}
/**
* Returns the numerical value of the code.
*
* @return the numerical value of the code.
* @since 0.5
*/
public int value() {
return value;
}
/**
* Returns the status that has the current {@code CanonicalCode}..
*
* @return the status that has the current {@code CanonicalCode}.
* @since 0.5
*/
public Status toStatus() {
return STATUS_LIST.get(value);
}
}
// Create the canonical list of Status instances indexed by their code values.
private static final List STATUS_LIST = buildStatusList();
private static List buildStatusList() {
TreeMap canonicalizer = new TreeMap();
for (CanonicalCode code : CanonicalCode.values()) {
Status replaced = canonicalizer.put(code.value(), new Status(code, null));
if (replaced != null) {
throw new IllegalStateException(
"Code value duplication between "
+ replaced.getCanonicalCode().name()
+ " & "
+ code.name());
}
}
return Collections.unmodifiableList(new ArrayList(canonicalizer.values()));
}
// A pseudo-enum of Status instances mapped 1:1 with values in CanonicalCode. This simplifies
// construction patterns for derived instances of Status.
/**
* The operation completed successfully.
*
* @since 0.5
*/
public static final Status OK = CanonicalCode.OK.toStatus();
/**
* The operation was cancelled (typically by the caller).
*
* @since 0.5
*/
public static final Status CANCELLED = CanonicalCode.CANCELLED.toStatus();
/**
* Unknown error. See {@link CanonicalCode#UNKNOWN}.
*
* @since 0.5
*/
public static final Status UNKNOWN = CanonicalCode.UNKNOWN.toStatus();
/**
* Client specified an invalid argument. See {@link CanonicalCode#INVALID_ARGUMENT}.
*
* @since 0.5
*/
public static final Status INVALID_ARGUMENT = CanonicalCode.INVALID_ARGUMENT.toStatus();
/**
* Deadline expired before operation could complete. See {@link CanonicalCode#DEADLINE_EXCEEDED}.
*
* @since 0.5
*/
public static final Status DEADLINE_EXCEEDED = CanonicalCode.DEADLINE_EXCEEDED.toStatus();
/**
* Some requested entity (e.g., file or directory) was not found.
*
* @since 0.5
*/
public static final Status NOT_FOUND = CanonicalCode.NOT_FOUND.toStatus();
/**
* Some entity that we attempted to create (e.g., file or directory) already exists.
*
* @since 0.5
*/
public static final Status ALREADY_EXISTS = CanonicalCode.ALREADY_EXISTS.toStatus();
/**
* The caller does not have permission to execute the specified operation. See {@link
* CanonicalCode#PERMISSION_DENIED}.
*
* @since 0.5
*/
public static final Status PERMISSION_DENIED = CanonicalCode.PERMISSION_DENIED.toStatus();
/**
* The request does not have valid authentication credentials for the operation.
*
* @since 0.5
*/
public static final Status UNAUTHENTICATED = CanonicalCode.UNAUTHENTICATED.toStatus();
/**
* Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system
* is out of space.
*
* @since 0.5
*/
public static final Status RESOURCE_EXHAUSTED = CanonicalCode.RESOURCE_EXHAUSTED.toStatus();
/**
* Operation was rejected because the system is not in a state required for the operation's
* execution. See {@link CanonicalCode#FAILED_PRECONDITION}.
*
* @since 0.5
*/
public static final Status FAILED_PRECONDITION = CanonicalCode.FAILED_PRECONDITION.toStatus();
/**
* The operation was aborted, typically due to a concurrency issue like sequencer check failures,
* transaction aborts, etc. See {@link CanonicalCode#ABORTED}.
*
* @since 0.5
*/
public static final Status ABORTED = CanonicalCode.ABORTED.toStatus();
/**
* Operation was attempted past the valid range. See {@link CanonicalCode#OUT_OF_RANGE}.
*
* @since 0.5
*/
public static final Status OUT_OF_RANGE = CanonicalCode.OUT_OF_RANGE.toStatus();
/**
* Operation is not implemented or not supported/enabled in this service.
*
* @since 0.5
*/
public static final Status UNIMPLEMENTED = CanonicalCode.UNIMPLEMENTED.toStatus();
/**
* Internal errors. See {@link CanonicalCode#INTERNAL}.
*
* @since 0.5
*/
public static final Status INTERNAL = CanonicalCode.INTERNAL.toStatus();
/**
* The service is currently unavailable. See {@link CanonicalCode#UNAVAILABLE}.
*
* @since 0.5
*/
public static final Status UNAVAILABLE = CanonicalCode.UNAVAILABLE.toStatus();
/**
* Unrecoverable data loss or corruption.
*
* @since 0.5
*/
public static final Status DATA_LOSS = CanonicalCode.DATA_LOSS.toStatus();
// The canonical code of this message.
private final CanonicalCode canonicalCode;
// An additional error message.
@Nullable private final String description;
private Status(CanonicalCode canonicalCode, @Nullable String description) {
this.canonicalCode = Utils.checkNotNull(canonicalCode, "canonicalCode");
this.description = description;
}
/**
* Creates a derived instance of {@code Status} with the given description.
*
* @param description the new description of the {@code Status}.
* @return The newly created {@code Status} with the given description.
* @since 0.5
*/
public Status withDescription(@Nullable String description) {
if (Utils.equalsObjects(this.description, description)) {
return this;
}
return new Status(this.canonicalCode, description);
}
/**
* Returns the canonical status code.
*
* @return the canonical status code.
* @since 0.5
*/
public CanonicalCode getCanonicalCode() {
return canonicalCode;
}
/**
* Returns the description of this {@code Status} for human consumption.
*
* @return the description of this {@code Status}.
* @since 0.5
*/
@Nullable
/*@Deterministic*/
public String getDescription() {
return description;
}
/**
* Returns {@code true} if this {@code Status} is OK, i.e., not an error.
*
* @return {@code true} if this {@code Status} is OK.
* @since 0.5
*/
public boolean isOk() {
return CanonicalCode.OK == canonicalCode;
}
/**
* Equality on Statuses is not well defined. Instead, do comparison based on their CanonicalCode
* with {@link #getCanonicalCode}. The description of the Status is unlikely to be stable, and
* additional fields may be added to Status in the future.
*/
@Override
public boolean equals(@Nullable Object obj) {
if (obj == this) {
return true;
}
if (!(obj instanceof Status)) {
return false;
}
Status that = (Status) obj;
return canonicalCode == that.canonicalCode
&& Utils.equalsObjects(description, that.description);
}
/**
* Hash codes on Statuses are not well defined.
*
* @see #equals
*/
@Override
public int hashCode() {
return Arrays.hashCode(new Object[] {canonicalCode, description});
}
@Override
public String toString() {
return "Status{canonicalCode=" + canonicalCode + ", description=" + description + "}";
}
}