Class Observed<T>
java.lang.Object
privbot.api.Observed<T>
- Type Parameters:
T- the type of the value read
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 producedget();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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enumWhich of the three answers a read gave. -
Method Summary
Modifier and TypeMethodDescriptionstatic <T> Observed<T> absent()A successful read that observed nothing.static <T> Observed<T> A successful read that observed nothing, with a note saying what was looked for.static <T> Observed<T> Runs a read and turns any exception it throws into UNREADABLE.booleanKeeps a VALUE that matchestest; a VALUE that does not becomes ABSENT.<R> Observed<R> Chains a read that depends on this one.<R> Rfold(Function<? super T, ? extends R> onValue, Supplier<? extends R> onAbsent, Function<String, ? extends R> onUnreadable) Folds the three answers into one value.get()The value read.inthashCode()voidbooleanTrue only for a VALUE equal toexpected.booleanisAbsent()static booleanbooleanbooleanstatic booleanboolean<R> Observed<R> Transforms a VALUE.booleanTrue only for a VALUE that matchestest.static <T> Observed<T> of(T value) A successful read holdingvalue.static <T> Observed<T> ofNullable(T value, String reasonIfNull) Converts an existing nullable read whosenullmeans "could not read" (the convention ofSkills.observedLevel,Game.observedRunEnabledand the otherobserved*reads that predate this class).static <T> Observed<T> ofPresentOrAbsent(T value) Converts a read whosenullgenuinely means "observed: nothing there" (a resolved interacting target on a client where the read itself cannot fail).Falls back to another read only when this one is UNREADABLE (a second source for the same fact).orNull()The value or null.reason()Why the read is UNREADABLE, or the note an ABSENT result carries; null for VALUE (and for an ABSENT without a note).state()static BooleanConverts a boolean read into the nullableBooleanconvention (null = cannot tell).Lossy conversion: ABSENT and UNREADABLE both become empty.toString()static <T> Observed<T> unreadable(String reason) A read that could not be made.
-
Method Details
-
of
A successful read holdingvalue.- Type Parameters:
T- the value type- Parameters:
value- the value read; must not be null (useabsent()orunreadable(String))- Returns:
- a
Observed.State.VALUEresult - Throws:
NullPointerException- whenvalueis null
-
absent
A successful read that observed nothing.- Type Parameters:
T- the value type- Returns:
- the shared
Observed.State.ABSENTresult
-
absent
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.ABSENTresult
-
unreadable
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.UNREADABLEresult
-
ofNullable
Converts an existing nullable read whosenullmeans "could not read" (the convention ofSkills.observedLevel,Game.observedRunEnabledand the otherobserved*reads that predate this class).- Type Parameters:
T- the value type- Parameters:
value- the value, or null when the read failedreasonIfNull- the reason recorded whenvalueis null- Returns:
- VALUE when
valueis non-null, otherwise UNREADABLE
-
ofPresentOrAbsent
Converts a read whosenullgenuinely 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
valueis non-null, otherwise ABSENT
-
attempt
Runs a read and turns any exception it throws into UNREADABLE. A null result is UNREADABLE too: a read that means "nothing there" must returnabsent()itself.- Type Parameters:
T- the value type- Parameters:
what- the read's name, used in the reasonread- the read- Returns:
- the read's own result, or UNREADABLE
-
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
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
The value read.- Returns:
- the value
- Throws:
NoSuchElementException- when this is not VALUE; the message carries the reason
-
orElse
-
orElseGet
-
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
True only for a VALUE equal toexpected.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
-
ifPresent
-
toOptional
-
map
-
flatMap
-
filter
-
or
-
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 VALUEonAbsent- supplies the answer for ABSENTonUnreadable- applied to the reason of an UNREADABLE- Returns:
- the folded result
-
isTrue
-
isFalse
-
toNullableBoolean
Converts a boolean read into the nullableBooleanconvention (null = cannot tell). ABSENT becomesfalse: 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
-
hashCode
-
toString
-