Interface NameService


public interface NameService
Everything an account can do about its name: check whether one is free, learn whether it may change now, change it, and — for a name dropping at a known time — claim it the instant it opens.

Not designed for host implementation; methods may be added in minor releases.

Since:
0.11.0
  • Method Details

    • checkAvailability

      NameAvailability checkAvailability(String name)
      Checks whether a username can be claimed.
      Parameters:
      name - the username to check
      Returns:
      whether it is available, taken, or disallowed
      Throws:
      AltsException - if the token was refused or the service failed
      Since:
      0.11.0
    • eligibility

      NameEligibility eligibility()
      Reads whether this account may change its name now, and when it was created.
      Returns:
      the eligibility
      Throws:
      AltsException - if the token was refused or the service failed
      Since:
      0.11.0
    • change

      NameChangeResult change(String name)
      Changes the account's username.

      Never throws for a refusal or an unreachable service: each is a NameChangeResult, a failure being NameChangeResult.Outcome.FAILED with its kind.

      Parameters:
      name - the new username
      Returns:
      the classified outcome, carrying the updated profile on success
      Since:
      0.11.0
    • claimAt

      CompletableFuture<ClaimResult> claimAt(String name, Instant target, ClaimOptions options)
      Claims a name at the instant it drops, firing a bounded burst of change attempts around target and stopping on the first success.

      The target is an input, not something the library discovers — a host reads the drop time off wherever names are listed and passes it here. Correct the clock through ClaimOptions.timeSource() if the target is millisecond-critical.

      The run ends early, without the name, in three cases, and ClaimResult.stopReason() says which: an attempt that no retry can fix (a refused token, an account with nothing to rename); the service answering 429, at which point every worker stops rather than keep sending to a service that asked to be left alone; and cancellation. Cancelling the returned future stops the run — no further attempt is started, though one already on the wire is not recalled.

      Parameters:
      name - the name to claim
      target - when the name becomes available
      options - how to pace the burst
      Returns:
      a future holding the outcome
      Since:
      0.11.0