- java.lang.Object
-
- com.machinezoo.hookless.ReactiveValue<T>
-
- Type Parameters:
-
T
- type of the result carried by thisReactiveValue
@DraftDocs("link to reactive value/output articles") public class ReactiveValue<T> extends Object
Container for output of reactive computation consisting of return value, exception, and reactive blocking flag.ReactiveValue
can be split into its constituent components by callingresult()
,exception()
, andblocking()
. It can be recreated from these components by callingReactiveValue(Object, Throwable, boolean)
or some other constructor.ReactiveValue
is immutable.Reactive code usually takes the form of a method and communicates its output like a method, i.e. via return value or an exception. Reactive code may additionally signal reactive blocking by calling
CurrentReactiveScope.block()
. Return value, exception, and signaling of reactive blocking constitutes implicit output of reactive computation.ReactiveValue
offers an explicit representation of the same. Conversion between explicit and implicit representations is performed by methodsget()
andcapture(Supplier)
.ReactiveValue
does not carry reactive dependencies. UseReactiveScope
for that.- See Also:
-
ReactiveVariable
,ReactiveScope
-
-
Constructor Summary
Constructors Constructor Description ReactiveValue()
Constructs newReactiveValue
.ReactiveValue(Throwable exception)
Constructs newReactiveValue
from exception.ReactiveValue(Throwable exception, boolean blocking)
Constructs newReactiveValue
from exception and blocking flag.ReactiveValue(T result)
Constructs newReactiveValue
from return value.ReactiveValue(T result, boolean blocking)
Constructs newReactiveValue
from return value and blocking flag.ReactiveValue(T result, Throwable exception, boolean blocking)
Constructs newReactiveValue
from return value, exception, and reactive blocking flag.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
blocking()
Gets the reactive blocking flag from thisReactiveValue
.static <T> ReactiveValue<T>
capture(Supplier<T> supplier)
Captures implicit reactive output of providedSupplier
and returns it encapsulated in newReactiveValue
.boolean
equals(Object obj)
Compares thisReactiveValue
to another object for equality.Throwable
exception()
Gets the exception component of thisReactiveValue
.T
get()
Unpacks explicit reactive output represented by thisReactiveValue
into implicit reactive output.int
hashCode()
Computes hash code of thisReactiveValue
.T
result()
Gets the return value component of thisReactiveValue
.boolean
same(ReactiveValue<?> other)
Checks reference equality between twoReactiveValue
instances.String
toString()
Returns a string representation of thisReactiveValue
.
-
-
-
Constructor Detail
-
ReactiveValue
public ReactiveValue(T result, Throwable exception, boolean blocking)
Constructs newReactiveValue
from return value, exception, and reactive blocking flag. Only one ofresult
andexception
can be non-null
. The parameters can be later retrieved viaresult()
,exception()
, andblocking()
.- Parameters:
-
result
- component representing return value of reactive computation that can be later retrieved viaresult()
-
exception
- component representing exception thrown by reactive computation that can be later retrieved viaexception()
-
blocking
-true
if the constructedReactiveValue
should represent blocking reactive computation,false
otherwise - Throws:
-
IllegalArgumentException
- if bothresult
andexception
are non-null
- See Also:
-
capture(Supplier)
-
ReactiveValue
public ReactiveValue()
Constructs newReactiveValue
. The newReactiveValue
represents reactive computation that successfully completed withnull
result and without blocking. TheReactiveValue
will havenull
result()
andexception()
andfalse
blocking()
flag.
-
ReactiveValue
public ReactiveValue(T result)
Constructs newReactiveValue
from return value. The newReactiveValue
represents reactive computation that successfully completed without blocking. TheReactiveValue
will havenull
exception()
andfalse
blocking()
flag.- Parameters:
-
result
- return value of the reactive computation the newReactiveValue
represents - See Also:
-
ReactiveValue(Object, Throwable, boolean)
-
ReactiveValue
public ReactiveValue(Throwable exception)
Constructs newReactiveValue
from exception. The newReactiveValue
represents reactive computation that threw an exception without blocking. TheReactiveValue
will havenull
result()
andfalse
blocking()
flag.- Parameters:
-
exception
- exception thrown by the reactive computation the newReactiveValue
represents - See Also:
-
ReactiveValue(Object, Throwable, boolean)
-
ReactiveValue
public ReactiveValue(T result, boolean blocking)
Constructs newReactiveValue
from return value and blocking flag. The newReactiveValue
represents reactive computation that successfully completed and possibly signaled blocking. TheReactiveValue
will havenull
exception()
.- Parameters:
-
result
- return value of the reactive computation the newReactiveValue
represents -
blocking
-true
if the constructedReactiveValue
should represent blocking reactive computation,false
otherwise - See Also:
-
ReactiveValue(Object, Throwable, boolean)
-
ReactiveValue
public ReactiveValue(Throwable exception, boolean blocking)
Constructs newReactiveValue
from exception and blocking flag. The newReactiveValue
represents reactive computation that threw an exception and possibly signaled blocking. TheReactiveValue
will havenull
result()
.- Parameters:
-
exception
- exception thrown by the reactive computation the newReactiveValue
represents -
blocking
-true
if the constructedReactiveValue
should represent blocking reactive computation,false
otherwise - See Also:
-
ReactiveValue(Object, Throwable, boolean)
-
-
Method Detail
-
result
public T result()
Gets the return value component of thisReactiveValue
. Only one ofresult()
andexception()
can be non-null
.- Returns:
-
return value component of
ReactiveValue
- See Also:
-
exception()
,get()
-
exception
public Throwable exception()
Gets the exception component of thisReactiveValue
. Only one ofresult()
andexception()
can be non-null
.
-
blocking
public boolean blocking()
Gets the reactive blocking flag from thisReactiveValue
. Blocking flag is set if thisReactiveValue
represents output of reactive computation that signaled blocking during its execution by callingCurrentReactiveScope.block()
.- Returns:
-
true
if thisReactiveValue
represents output of blocking reactive computation,false
otherwise - See Also:
-
get()
, Reactive blocking
-
get
public T get()
Unpacks explicit reactive output represented by thisReactiveValue
into implicit reactive output. Ifexception()
is notnull
, it is thrown wrapped inCompletionException
. Otherwiseresult()
is returned. In either case, ifblocking()
istrue
,CurrentReactiveScope.block()
is called.- Returns:
-
value of
result()
- Throws:
-
CompletionException
- ifexception()
is notnull
- See Also:
-
result()
,exception()
,blocking()
-
capture
public static <T> ReactiveValue<T> capture(Supplier<T> supplier)
Captures implicit reactive output of providedSupplier
and returns it encapsulated in newReactiveValue
. If thesupplier
throws, returnedReactiveValue
will haveexception()
set to the caught exception. Otherwise theReactiveValue
will haveresult()
set to value returned from thesupplier
.If the
supplier
reactively blocks by callingCurrentReactiveScope.block()
,blocking()
flag will be set on the returnedReactiveValue
. This method obtains blocking flag by callingCurrentReactiveScope.blocked()
after calling thesupplier
, which means the returnedReactiveValue
will haveblocking()
flag set also if the currentReactiveScope
was already blocked by the time this method was called. This is reasonable behavior, because thesupplier
might be itself derived from information produced by blocking operations executed earlier during the current reactive computation, which means thatsupplier
's output cannot be trusted to be non-blocking.If there is no current
ReactiveScope
, i.e.ReactiveScope.current()
returnsnull
, this method creates temporaryReactiveScope
and executes thesupplier
in it, so that blocking flag can be captured. This is particularly useful in unit tests.- Type Parameters:
-
T
- type of value returned by thesupplier
- Parameters:
-
supplier
- reactive code to execute - Returns:
-
ReactiveValue
encapsulating implicit reactive output of thesupplier
- See Also:
-
ReactiveValue(Object, Throwable, boolean)
-
equals
public boolean equals(Object obj)
Compares thisReactiveValue
to another object for equality.ReactiveValue
can only equal anotherReactiveValue
. TwoReactiveValue
instances are equal if theirresult()
,exception()
, andblocking()
flags are equal. Value equality is used for bothresult()
andexception()
. Two exceptions are equal when their stringified form (including stack trace and causes) compares equal.Full value equality checking may be expensive or even undesirable. Use
same(ReactiveValue)
to compute shallow reference equality.- Overrides:
-
equals
in classObject
- Parameters:
-
obj
- object to compare thisReactiveValue
to ornull
- Returns:
-
true
if the objects compare equal,false
otherwise - See Also:
-
same(ReactiveValue)
,hashCode()
-
hashCode
public int hashCode()
Computes hash code of thisReactiveValue
. Hash code is calculated in such a way that if twoReactiveValue
instances are equal as checked byequals(Object)
, then their hash codes are equal too. This makesReactiveValue
usable as a key in aMap
.Both
result()
andexception()
are included in hash code calculation. Exceptions are hashed in such a way that two exceptions with the same stringified form (including stack traces and causes) will have the same hash code.- Overrides:
-
hashCode
in classObject
- Returns:
-
hash code of this
ReactiveValue
- See Also:
-
equals(Object)
-
same
public boolean same(ReactiveValue<?> other)
Checks reference equality between twoReactiveValue
instances. AnotherReactiveValue
is reference-equal to this instance according to this method if it is notnull
and itsresult()
,exception()
, andblocking()
components are all reference-equal to corresponding components of thisReactiveValue
.This method is useful when
equals(Object)
would be too expensive or where reference equality is desirable.- Parameters:
-
other
-ReactiveValue
to compare this instance to ornull
- Returns:
-
true
if the twoReactiveValue
instances are reference-equal,false
otherwise - See Also:
-
equals(Object)
-
toString
public String toString()
Returns a string representation of thisReactiveValue
. The returned string is suitable for debug output and includes string representation ofresult()
orexception()
as well as indication whether theReactiveValue
isblocking()
.
-
-