Class Observed<T>

java.lang.Object
privbot.api.Observed<T>
Type Parameters:
T - the type of the value read

public final class Observed<T> extends Object
The result of one read of game state, with "could not read it" kept apart from every real answer.

Three states:

  • Observed.State.VALUE: the read succeeded and produced get();
  • Observed.State.ABSENT: the read succeeded and observed that there is nothing (no interacting target, no such graphic). This is a real answer;
  • Observed.State.UNREADABLE: the read could not be made (a value this client cannot read, a dropped client-thread read, a server without the data). Nothing may be concluded from it; reason() says why.

Why this exists: a boolean read that cannot be made has to answer false, and a caller cannot tell that from a real "no". Silent wrong reads come through that path (a prayer that read "off" while it was on, a bank that read "open" after it closed, varbits that read 0). A caller that receives an Observed must decide what UNREADABLE means for its decision; the usual answer is "do nothing destructive and read again next tick".


 Observed<Boolean> on = ctx.prayer.observedActive("Protect from Magic");
 if (on.isUnreadable()) return;          // cannot tell: do not toggle blind
 if (on.is(false)) ctx.prayer.activate("Protect from Magic");
 

Immutable and thread-safe when T is. Never null: methods that return an Observed return unreadable(String) rather than null.

  • Method Details

    • of

      public static <T> Observed<T> of(T value)
      A successful read holding value.
      Type Parameters:
      T - the value type
      Parameters:
      value - the value read; must not be null (use absent() or unreadable(String))
      Returns:
      a Observed.State.VALUE result
      Throws:
      NullPointerException - when value is null
    • absent

      public static <T> Observed<T> absent()
      A successful read that observed nothing.
      Type Parameters:
      T - the value type
      Returns:
      the shared Observed.State.ABSENT result
    • absent

      public static <T> Observed<T> absent(String note)
      A successful read that observed nothing, with a note saying what was looked for.
      Type Parameters:
      T - the value type
      Parameters:
      note - what was not there (for logs); may be null
      Returns:
      a Observed.State.ABSENT result
    • unreadable

      public static <T> Observed<T> unreadable(String reason)
      A read that could not be made.
      Type Parameters:
      T - the value type
      Parameters:
      reason - why (for logs and support); a blank reason is replaced by "unreadable"
      Returns:
      a Observed.State.UNREADABLE result
    • ofNullable

      public static <T> Observed<T> ofNullable(T value, String reasonIfNull)
      Converts an existing nullable read whose null means "could not read" (the convention of Skills.observedLevel, Game.observedRunEnabled and the other observed* reads that predate this class).
      Type Parameters:
      T - the value type
      Parameters:
      value - the value, or null when the read failed
      reasonIfNull - the reason recorded when value is null
      Returns:
      VALUE when value is non-null, otherwise UNREADABLE
    • ofPresentOrAbsent

      public static <T> Observed<T> ofPresentOrAbsent(T value)
      Converts a read whose null genuinely means "observed: nothing there" (a resolved interacting target on a client where the read itself cannot fail).
      Type Parameters:
      T - the value type
      Parameters:
      value - the value, or null when nothing is there
      Returns:
      VALUE when value is non-null, otherwise ABSENT
    • attempt

      public static <T> Observed<T> attempt(String what, Supplier<Observed<T>> read)
      Runs a read and turns any exception it throws into UNREADABLE. A null result is UNREADABLE too: a read that means "nothing there" must return absent() itself.
      Type Parameters:
      T - the value type
      Parameters:
      what - the read's name, used in the reason
      read - the read
      Returns:
      the read's own result, or UNREADABLE
    • state

      public Observed.State state()
      Returns:
      which of the three answers this is
    • isPresent

      public boolean isPresent()
      Returns:
      true when the read succeeded and holds a value
    • isAbsent

      public boolean isAbsent()
      Returns:
      true when the read succeeded and observed nothing
    • isUnreadable

      public boolean isUnreadable()
      Returns:
      true when the read could not be made
    • isReadable

      public boolean isReadable()
      Returns:
      true when the read succeeded (VALUE or ABSENT): something may be concluded from it
    • reason

      public String reason()
      Why the read is UNREADABLE, or the note an ABSENT result carries; null for VALUE (and for an ABSENT without a note).
      Returns:
      the reason or note
    • get

      public T get()
      The value read.
      Returns:
      the value
      Throws:
      NoSuchElementException - when this is not VALUE; the message carries the reason
    • orElse

      public T orElse(T other)
      Parameters:
      other - the answer to use for ABSENT and UNREADABLE
      Returns:
      the value when present, else other
    • orElseGet

      public T orElseGet(Supplier<? extends T> other)
      Parameters:
      other - supplies the answer for ABSENT and UNREADABLE
      Returns:
      the value when present, else other.get()
    • orNull

      public T orNull()
      The value or null. Lossy: ABSENT and UNREADABLE both become null, so use it only where both mean the same to the caller (or to hand the result to code that already treats null as "unknown").
      Returns:
      the value, or null
    • is

      public boolean is(T expected)
      True only for a VALUE equal to expected. observed.is(false) is a real "no", never an unreadable read.
      Parameters:
      expected - the value to compare against
      Returns:
      whether this is VALUE and equals expected
    • matches

      public boolean matches(Predicate<? super T> test)
      True only for a VALUE that matches test. ABSENT and UNREADABLE are never a match.
      Parameters:
      test - the predicate
      Returns:
      whether this is VALUE and matches
    • ifPresent

      public void ifPresent(Consumer<? super T> action)
      Parameters:
      action - run with the value when present; not run for ABSENT or UNREADABLE
    • toOptional

      public Optional<T> toOptional()
      Lossy conversion: ABSENT and UNREADABLE both become empty. Prefer the Observed itself wherever the difference matters.
      Returns:
      the value as an Optional
    • map

      public <R> Observed<R> map(Function<? super T,? extends R> fn)
      Transforms a VALUE. A null mapping result is ABSENT. ABSENT and UNREADABLE pass through unchanged (with their reason).
      Type Parameters:
      R - the new value type
      Parameters:
      fn - the mapping
      Returns:
      the mapped result
    • flatMap

      public <R> Observed<R> flatMap(Function<? super T,Observed<R>> fn)
      Chains a read that depends on this one. ABSENT and UNREADABLE pass through unchanged.
      Type Parameters:
      R - the new value type
      Parameters:
      fn - the next read
      Returns:
      the next read's result
    • filter

      public Observed<T> filter(Predicate<? super T> test)
      Keeps a VALUE that matches test; a VALUE that does not becomes ABSENT. UNREADABLE stays UNREADABLE.
      Parameters:
      test - the predicate
      Returns:
      this or ABSENT
    • or

      public Observed<T> or(Supplier<Observed<T>> fallback)
      Falls back to another read only when this one is UNREADABLE (a second source for the same fact). VALUE and ABSENT are answers and are kept.
      Parameters:
      fallback - the second read
      Returns:
      this, or the fallback's result
    • fold

      public <R> R fold(Function<? super T,? extends R> onValue, Supplier<? extends R> onAbsent, Function<String,? extends R> onUnreadable)
      Folds the three answers into one value.
      Type Parameters:
      R - the result type
      Parameters:
      onValue - applied to a VALUE
      onAbsent - supplies the answer for ABSENT
      onUnreadable - applied to the reason of an UNREADABLE
      Returns:
      the folded result
    • isTrue

      public static boolean isTrue(Observed<Boolean> o)
      Parameters:
      o - a boolean read (may be null, which counts as unreadable)
      Returns:
      true only for a VALUE of true
    • isFalse

      public static boolean isFalse(Observed<Boolean> o)
      Parameters:
      o - a boolean read (may be null, which counts as unreadable)
      Returns:
      true only for a VALUE of false: a real "no"
    • toNullableBoolean

      public static Boolean toNullableBoolean(Observed<Boolean> o)
      Converts a boolean read into the nullable Boolean convention (null = cannot tell). ABSENT becomes false: for a yes/no question "observed: nothing there" is a no.
      Parameters:
      o - a boolean read (may be null)
      Returns:
      TRUE, FALSE, or null when unreadable
    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      VALUE(x), ABSENT, ABSENT(note) or UNREADABLE(reason)