Class AltsFailure

java.lang.Object
lol.trq.alts.AltsFailure

public final class AltsFailure extends Object
What went wrong, in the one form every part of the library reports it: a sign-in, a check or a refresh, an account service, a bulk entry, a store.

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
  • Method Details

    • kind

      public AltsFailure.Kind kind()
      Returns what kind of failure this is; the thing to branch on.
      Returns:
      the kind
      Since:
      1.0.0
    • message

      public String message()
      Returns a short description built by the library, safe to show and to log.
      Returns:
      the message
      Since:
      1.0.0
    • retryAfter

      public Optional<Duration> retryAfter()
      Returns how long the service asked the caller to wait before trying again, when it said.
      Returns:
      the stated wait, or empty
      Since:
      1.0.0
    • xstsError

      public Optional<XstsError> xstsError()
      Returns why Xbox Live refused the account; present only on AltsFailure.Kind.XBOX_DENIED.
      Returns:
      the Xbox Live reason, or empty
      Since:
      1.0.0
    • retryAt

      public Optional<Instant> retryAt()
      Returns when the stated wait ends; present exactly when retryAfter() is.
      Returns:
      the end of the wait, or empty
      Since:
      1.0.0
    • of

      public static AltsFailure of(AltsFailure.Kind kind, String message)
      Creates a failure of kind with no stated wait and no Xbox Live reason.
      Parameters:
      kind - what kind of failure it is
      message - a short description built by the library
      Returns:
      the failure
      Since:
      1.0.0
    • rateLimited

      public static AltsFailure rateLimited(String message, Duration retryAfter)
      Creates a AltsFailure.Kind.RATE_LIMITED failure; a stated wait starts now.
      Parameters:
      message - a short description built by the library
      retryAfter - how long the service asked the caller to wait, or null when it did not say
      Returns:
      the failure
      Since:
      1.0.0
    • of

      public static AltsFailure of(AltsFailure.Kind kind, String message, Duration retryAfter)
      Creates a failure of kind that 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 is
      message - a short description built by the library
      retryAfter - how long the service asked the caller to wait, or null when it did not say
      Returns:
      the failure
      Since:
      1.0.0
    • xboxDenied

      public static AltsFailure xboxDenied(String message, XstsError error)
      Creates an AltsFailure.Kind.XBOX_DENIED failure.
      Parameters:
      message - a short description built by the library
      error - why Xbox Live refused the account
      Returns:
      the failure
      Since:
      1.0.0
    • withMessage

      public AltsFailure 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. 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.NETWORK and AltsFailure.Kind.RATE_LIMITED are retryable once now is at or past it. With no stated wait, AltsFailure.Kind.NETWORK is retryable, and AltsFailure.Kind.RATE_LIMITED is 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

      public boolean equals(Object o)
      Returns whether o is a failure with every field equal to this one's.
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare
      Returns:
      true when every field is equal
      Since:
      1.0.0
    • hashCode

      public int hashCode()
      Returns a hash over every field, consistent with equals(Object).
      Overrides:
      hashCode in class Object
      Returns:
      the hash
      Since:
      1.0.0
    • toString

      public String toString()
      Returns every field, in the form the record printed them. The message is the library's own, so it is safe to log.
      Overrides:
      toString in class Object
      Returns:
      a description
      Since:
      1.0.0