Class AltsFailure
A host branches on kind(), never on message(). The message is built by the
library for a person to read: it never repeats a transport exception's own text, never carries a
token, a cookie, a code or a filesystem path, and its wording may change in any release.
A failure appears in one of two places. Where the caller is expected to branch on the outcome
(a sign-in, an account's status, a name change, a profile creation, a name claim, a bulk entry) it is
carried by the result as an Optional<AltsFailure>. Everywhere else it is thrown, or completes a
future exceptionally, as an AltsException carrying it.
When the service stated a wait, retryAt() is the instant it ends: the moment the failure
was made plus retryAfter(). retryable() compares it with the current time, so a
failure a host holds on to becomes retryable once the wait has passed, without the host keeping its
own clock beside it. A failure with no stated wait records no time, so two such failures with the same
kind and message are equal whenever they were made.
It is a value the library hands a host, not a wire DTO: it carries no @SerializedName and
the library never serializes it. A host that wants to persist one writes the parts it needs. It is a
final class rather than a record, so a later field is an addition and not a break: build one with
of(AltsFailure.Kind, String), rateLimited(String, Duration) or xboxDenied(String, XstsError). Two failures are equal when every field is.
- Since:
- 1.0.0
-
Nested Class Summary
Nested Classes -
Method Summary
Modifier and TypeMethodDescriptionbooleanReturns whetherois a failure with every field equal to this one's.inthashCode()Returns a hash over every field, consistent withequals(Object).kind()Returns what kind of failure this is; the thing to branch on.message()Returns a short description built by the library, safe to show and to log.static AltsFailureof(AltsFailure.Kind kind, String message) Creates a failure ofkindwith no stated wait and no Xbox Live reason.static AltsFailureof(AltsFailure.Kind kind, String message, Duration retryAfter) Creates a failure ofkindthat may carry a stated wait, which starts now.static AltsFailurerateLimited(String message, Duration retryAfter) Creates aAltsFailure.Kind.RATE_LIMITEDfailure; a stated wait starts now.booleanReturns whether trying the same thing again, unchanged, may succeed now.Returns how long the service asked the caller to wait before trying again, when it said.retryAt()Returns when the stated wait ends; present exactly whenretryAfter()is.toString()Returns every field, in the form the record printed them.withMessage(String message) Returns the same failure under another message, for a caller that adds context (the route's name, say) to a failure a lower layer classified.static AltsFailurexboxDenied(String message, XstsError error) Creates anAltsFailure.Kind.XBOX_DENIEDfailure.Returns why Xbox Live refused the account; present only onAltsFailure.Kind.XBOX_DENIED.
-
Method Details
-
kind
Returns what kind of failure this is; the thing to branch on.- Returns:
- the kind
- Since:
- 1.0.0
-
message
Returns a short description built by the library, safe to show and to log.- Returns:
- the message
- Since:
- 1.0.0
-
retryAfter
-
xstsError
Returns why Xbox Live refused the account; present only onAltsFailure.Kind.XBOX_DENIED.- Returns:
- the Xbox Live reason, or empty
- Since:
- 1.0.0
-
retryAt
Returns when the stated wait ends; present exactly whenretryAfter()is.- Returns:
- the end of the wait, or empty
- Since:
- 1.0.0
-
of
Creates a failure ofkindwith no stated wait and no Xbox Live reason.- Parameters:
kind- what kind of failure it ismessage- a short description built by the library- Returns:
- the failure
- Since:
- 1.0.0
-
rateLimited
Creates aAltsFailure.Kind.RATE_LIMITEDfailure; a stated wait starts now.- Parameters:
message- a short description built by the libraryretryAfter- how long the service asked the caller to wait, ornullwhen it did not say- Returns:
- the failure
- Since:
- 1.0.0
-
of
Creates a failure ofkindthat may carry a stated wait, which starts now. A server error can state one as well as a throttle.- Parameters:
kind- what kind of failure it ismessage- a short description built by the libraryretryAfter- how long the service asked the caller to wait, ornullwhen it did not say- Returns:
- the failure
- Since:
- 1.0.0
-
xboxDenied
Creates anAltsFailure.Kind.XBOX_DENIEDfailure.- Parameters:
message- a short description built by the libraryerror- why Xbox Live refused the account- Returns:
- the failure
- Since:
- 1.0.0
-
withMessage
Returns the same failure under another message, for a caller that adds context (the route's name, say) to a failure a lower layer classified. Kind, wait, end of the wait and Xbox Live reason are kept.- Parameters:
message- the new message, built by the library- Returns:
- the relabelled failure
- Since:
- 1.0.0
-
retryable
public boolean retryable()Returns whether trying the same thing again, unchanged, may succeed now.A stated wait is honoured for every kind that can be retried: when
retryAt()is present,AltsFailure.Kind.NETWORKandAltsFailure.Kind.RATE_LIMITEDare retryable once now is at or past it. With no stated wait,AltsFailure.Kind.NETWORKis retryable, andAltsFailure.Kind.RATE_LIMITEDis not, since retrying into an unknown limit is how a short limit becomes a long one, and a host picks its own back-off for it. Every other kind is not: the credential, the input, the configuration or the user's choice has to change first.- Returns:
- true when an unchanged retry may now succeed
- Since:
- 1.0.0
-
equals
-
hashCode
public int hashCode()Returns a hash over every field, consistent withequals(Object). -
toString
-