class FutureOutcome extends AnyRef
Wrapper class for Future[Outcome]
that presents a more convenient API for
manipulation in withFixture
methods in async styles.
This type serves as the result type of both test functions and withFixture
methods
in ScalaTest's async styles. A Future[Outcome]
is not used as this result type
for two reasons. First, Outcome
treats exceptions specially, and as a result
methods on Future
would usually not yield the desired Future[Outcome]
result.
Only run-aborting exceptions should result in a failed Future[Outcome]
. Any other thrown exception
other than TestCanceledException
or TestPendingException
should result in a successfulFuture
containing a org.scalatest.Failed
.
A thrown TestCanceledException
should result in a successful Future
containing an org.scalatest.Canceled
; A thrown TestPendingException
should result in
a successful Future
containing a org.scalatest.Pending
.
If manipulating a Future[Outcome]
directly, by contrast, any thrown exception would result in
a failed Future
.
Additionally, to be consistent with corresponding transformations in traditional testing styles,
methods registering callbacks should return a new future outcome that doesn't complete until
both the original future outcome has completed and the subsequent callback has completed execution.
Additionally, if the callback itself throws an exception, that exception should determine the result
of the future outcome returned by the callback registration method. This behavior is rather inconvenient
to obtain on the current Future
API, so FutureOutcome
provides well-named
methods that have this behavior.
Lastly, the FutureOutcome
is intended to help prevent confusion by eliminating the need
to work with types like scala.util.Success(org.scalatest.Failed)
. For this purpose a
org.scalactic.Or
is used instead of a scala.util.Try
to describe results
of FutureOutcome
.
A FutureOutcome
represents a computation that can result in an Outcome
or an "abort." An abort means
that a run-aborting exception occurred during the computation. Any other, non-run-aborting exception will be represented
as an non-Succeeded
Outcome
: one of Failed
, Canceled
, or Pending
.
The methods of FutureOutcome
include the following callback registration methods:
onSucceededThen
- registers a callback to be executed if the future outcome isSucceeded
.onFailedThen
- registers a callback to be executed if the future outcome isFailed
.onCanceledThen
- registers a callback to be executed if the future outcome isCanceled
.onPendingThen
- registers a callback to be executed if the future outcome isPending
.onOutcomeThen
- registers a callback to be executed if the future outcome is actually anOutcome
and not an abort.onAbortedThen
- registers a callback to be executed if the future outcome aborts.onCompletedThen
- registers a callback to be executed upon completion no matter how the future outcome completes.
The callback methods listed previously can be used to perform a side effect once a FutureOutcome
completes. To change an
Outcome
into a different Outcome
asynchronously, use the change
registration method, which takes a function
from Outcome
to Outcome
. The other methods on FutureOutcome
, isCompleted
and
value
, allow you to poll a FutureOutcome
. None of the methods on FutureOutcome
block.
Lastly, because an implicit Futuristic
instance is provided for
FutureOutcome
, you can use complete
-lastly
syntax
with FutureOutcome
.
- Source
- FutureOutcome.scala
- Alphabetic
- By Inheritance
- FutureOutcome
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Value Members
-
final
def
!=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
final
def
##(): Int
- Definition Classes
- AnyRef → Any
-
final
def
==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
final
def
asInstanceOf[T0]: T0
- Definition Classes
- Any
-
def
change(f: (Outcome) ⇒ Outcome)(implicit executionContext: ExecutionContext): FutureOutcome
Registers a transformation function to be executed if this future completes with any
Outcome
(i.e., no run-aborting exception is thrown), returning a newFutureOutcome
representing the result of passing thisFutureOutcome
'sOutcome
result to the given transformation function.Registers a transformation function to be executed if this future completes with any
Outcome
(i.e., no run-aborting exception is thrown), returning a newFutureOutcome
representing the result of passing thisFutureOutcome
'sOutcome
result to the given transformation function.If the passed function completes abruptly with an exception, the resulting
FutureOutcome
will be determined by the type of the thrown exception:TestPendingException
-Good(Pending)
TestCanceledException
-Good(Canceled(<the exception>))
- Any non-run-aborting
Throwable
-Good(Failed(<the exception>))
- A run-aborting
Throwable
-Bad(<the run-aborting exception>)
For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait
Suite
.- f
a transformation function to execute if and when this
FutureOutcome
completes with anOutcome
- executionContext
an execution context that provides a strategy for executing the transformation function
- returns
a new
FutureOutcome
that will complete only after thisFutureOutcome
has completed and, if thisFutureOutcome
completes with a validOutcome
, the passed callback function has completed execution.
-
def
clone(): AnyRef
- Attributes
- protected[java.lang]
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
-
def
equals(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
def
finalize(): Unit
- Attributes
- protected[java.lang]
- Definition Classes
- AnyRef
- Annotations
- @throws( classOf[java.lang.Throwable] )
-
final
def
getClass(): Class[_]
- Definition Classes
- AnyRef → Any
-
def
hashCode(): Int
- Definition Classes
- AnyRef → Any
-
def
isCompleted: Boolean
Indicates whether this
FutureOutcome
has completed.Indicates whether this
FutureOutcome
has completed.This method does not block.
- returns
true
if thisFutureOutcome
has completed;false
otherwise.
-
final
def
isInstanceOf[T0]: Boolean
- Definition Classes
- Any
-
final
def
ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
-
final
def
notify(): Unit
- Definition Classes
- AnyRef
-
final
def
notifyAll(): Unit
- Definition Classes
- AnyRef
-
def
onAbortedThen(callback: (Throwable) ⇒ Unit)(implicit executionContext: ExecutionContext): FutureOutcome
Registers a callback function to be executed if this future completes because a run-aborting exception was thrown, returning a new future that completes only after the callback has finished execution.
Registers a callback function to be executed if this future completes because a run-aborting exception was thrown, returning a new future that completes only after the callback has finished execution.
The resulting
FutureOutcome
will have the same result as thisFutureOutcome
, unless the callback completes abruptly with an exception. In that case, the resultingFutureOutcome
will be determined by the type of the thrown exception:TestPendingException
-Good(Pending)
TestCanceledException
-Good(Canceled(<the exception>))
- Any non-run-aborting
Throwable
-Good(Failed(<the exception>))
- A run-aborting
Throwable
-Bad(<the run-aborting exception>)
For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait
Suite
.- callback
a side-effecting function to execute if and when this
FutureOutcome
completes with an abort.- executionContext
an execution context that provides a strategy for executing the callback function
- returns
a new
FutureOutcome
that will complete only after thisFutureOutcome
has completed and, if thisFutureOutcome
completes abnormally with a run-aborting exception, the passed callback function has completed execution.
-
def
onCanceledThen(callback: (TestCanceledException) ⇒ Unit)(implicit executionContext: ExecutionContext): FutureOutcome
Registers a callback function to be executed if this future completes with
Canceled
, returning a new future that completes only after the callback has finished execution.Registers a callback function to be executed if this future completes with
Canceled
, returning a new future that completes only after the callback has finished execution.The resulting
FutureOutcome
will have the same result as thisFutureOutcome
, unless the callback completes abruptly with an exception. In that case, the resultingFutureOutcome
will be determined by the type of the thrown exception:TestPendingException
-Good(Pending)
TestCanceledException
-Good(Canceled(<the exception>))
- Any non-run-aborting
Throwable
-Good(Failed(<the exception>))
- A run-aborting
Throwable
-Bad(<the run-aborting exception>)
For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait
Suite
.- callback
a side-effecting function to execute if and when this
FutureOutcome
completes withCanceled
- executionContext
an execution context that provides a strategy for executing the callback function
- returns
a new
FutureOutcome
that will complete only after thisFutureOutcome
has completed and, if thisFutureOutcome
completes withCanceled
, the passed callback function has completed execution.
-
def
onCompletedThen(callback: (Or[Outcome, Throwable]) ⇒ Unit)(implicit executionContext: ExecutionContext): FutureOutcome
Registers a callback function to be executed after this future completes, returning a new future that completes only after the callback has finished execution.
Registers a callback function to be executed after this future completes, returning a new future that completes only after the callback has finished execution.
The resulting
FutureOutcome
will have the same result as thisFutureOutcome
, unless the callback completes abruptly with an exception. In that case, the resultingFutureOutcome
will be determined by the type of the thrown exception:TestPendingException
-Good(Pending)
TestCanceledException
-Good(Canceled(<the exception>))
- Any non-run-aborting
Throwable
-Good(Failed(<the exception>))
- A run-aborting
Throwable
-Bad(<the run-aborting exception>)
For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait
Suite
.- callback
a side-effecting function to execute when this
FutureOutcome
completes- executionContext
an execution context that provides a strategy for executing the callback function
- returns
a new
FutureOutcome
that will complete only after thisFutureOutcome
and, subsequently, the passed callback function have completed execution.
-
def
onFailedThen(callback: (Throwable) ⇒ Unit)(implicit executionContext: ExecutionContext): FutureOutcome
Registers a callback function to be executed if this future completes with
Failed
, returning a new future that completes only after the callback has finished execution.Registers a callback function to be executed if this future completes with
Failed
, returning a new future that completes only after the callback has finished execution.The resulting
FutureOutcome
will have the same result as thisFutureOutcome
, unless the callback completes abruptly with an exception. In that case, the resultingFutureOutcome
will be determined by the type of the thrown exception:TestPendingException
-Good(Pending)
TestCanceledException
-Good(Canceled(<the exception>))
- Any non-run-aborting
Throwable
-Good(Failed(<the exception>))
- A run-aborting
Throwable
-Bad(<the run-aborting exception>)
For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait
Suite
.- callback
a side-effecting function to execute if and when this
FutureOutcome
completes withFailed
- executionContext
an execution context that provides a strategy for executing the callback function
- returns
a new
FutureOutcome
that will complete only after thisFutureOutcome
has completed and, if thisFutureOutcome
completes withFailed
, the passed callback function has completed execution.
-
def
onOutcomeThen(callback: (Outcome) ⇒ Unit)(implicit executionContext: ExecutionContext): FutureOutcome
Registers a callback function to be executed if this future completes with any
Outcome
(i.e., no run-aborting exception is thrown), returning a new future that completes only after the callback has finished execution.Registers a callback function to be executed if this future completes with any
Outcome
(i.e., no run-aborting exception is thrown), returning a new future that completes only after the callback has finished execution.The resulting
FutureOutcome
will have the same result as thisFutureOutcome
, unless the callback completes abruptly with an exception. In that case, the resultingFutureOutcome
will be determined by the type of the thrown exception:TestPendingException
-Good(Pending)
TestCanceledException
-Good(Canceled(<the exception>))
- Any non-run-aborting
Throwable
-Good(Failed(<the exception>))
- A run-aborting
Throwable
-Bad(<the run-aborting exception>)
For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait
Suite
.- callback
a side-effecting function to execute if and when this
FutureOutcome
completes with anOutcome
(i.e., not an abort)- executionContext
an execution context that provides a strategy for executing the callback function
- returns
a new
FutureOutcome
that will complete only after thisFutureOutcome
has completed and, if thisFutureOutcome
completes with a validOutcome
, the passed callback function has completed execution.
-
def
onPendingThen(callback: ⇒ Unit)(implicit executionContext: ExecutionContext): FutureOutcome
Registers a callback function to be executed if this future completes with
Pending
, returning a new future that completes only after the callback has finished execution.Registers a callback function to be executed if this future completes with
Pending
, returning a new future that completes only after the callback has finished execution.The resulting
FutureOutcome
will have the same result as thisFutureOutcome
, unless the callback completes abruptly with an exception. In that case, the resultingFutureOutcome
will be determined by the type of the thrown exception:TestPendingException
-Good(Pending)
TestCanceledException
-Good(Canceled(<the exception>))
- Any non-run-aborting
Throwable
-Good(Failed(<the exception>))
- A run-aborting
Throwable
-Bad(<the run-aborting exception>)
For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait
Suite
.- callback
a side-effecting function to execute if and when this
FutureOutcome
completes withPending
- executionContext
an execution context that provides a strategy for executing the callback function
- returns
a new
FutureOutcome
that will complete only after thisFutureOutcome
has completed and, if thisFutureOutcome
completes withPending
, the passed callback function has completed execution.
-
def
onSucceededThen(callback: ⇒ Unit)(implicit executionContext: ExecutionContext): FutureOutcome
Registers a callback function to be executed if this future completes with
Succeeded
, returning a new future that completes only after the callback has finished execution.Registers a callback function to be executed if this future completes with
Succeeded
, returning a new future that completes only after the callback has finished execution.The resulting
FutureOutcome
will have the same result as thisFutureOutcome
, unless the callback completes abruptly with an exception. In that case, the resultingFutureOutcome
will be determined by the type of the thrown exception:TestPendingException
-Good(Pending)
TestCanceledException
-Good(Canceled(<the exception>))
- Any non-run-aborting
Throwable
-Good(Failed(<the exception>))
- A run-aborting
Throwable
-Bad(<the run-aborting exception>)
For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait
Suite
.- callback
a side-effecting function to execute if and when this
FutureOutcome
completes withSucceeded
- executionContext
an execution context that provides a strategy for executing the callback function
- returns
a new
FutureOutcome
that will complete only after thisFutureOutcome
has completed and, if thisFutureOutcome
completes withSucceeded
, the passed callback function has completed execution.
-
final
def
synchronized[T0](arg0: ⇒ T0): T0
- Definition Classes
- AnyRef
-
def
toFuture: Future[Outcome]
Converts this
FutureOutcome
to aFuture[Outcome]
.Converts this
FutureOutcome
to aFuture[Outcome]
.- returns
the underlying
Future[Outcome]
-
def
toString(): String
- Definition Classes
- AnyRef → Any
-
def
value: Option[Or[Outcome, Throwable]]
Returns a value that indicates whether this
FutureOutcome
has completed, and if so, indicates its result.Returns a value that indicates whether this
FutureOutcome
has completed, and if so, indicates its result.If this
FutureOutcome
has not yet completed, this method will returnNone
. Otherwise, this method will return aSome
that contains either aGood[Outcome]
, if thisFutureOutcome
completed with a validOutcome
result, or if it completed with a thrown run-aborting exception, aBad[Throwable]
.For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait
Suite
.- returns
a
Some
containing anOr
value that indicates the result of thisFutureOutcome
if it has completed;None
otherwise.
-
final
def
wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )