Packages

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 is Succeeded.
  • onFailedThen - registers a callback to be executed if the future outcome is Failed.
  • onCanceledThen - registers a callback to be executed if the future outcome is Canceled.
  • onPendingThen - registers a callback to be executed if the future outcome is Pending.
  • onOutcomeThen - registers a callback to be executed if the future outcome is actually an Outcome 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
Linear Supertypes
AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. FutureOutcome
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Instance Constructors

  1. new FutureOutcome(underlying: Future[Outcome])

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##: Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. 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 new FutureOutcome representing the result of passing this FutureOutcome's Outcome 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 new FutureOutcome representing the result of passing this FutureOutcome's Outcome 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 an Outcome

    executionContext

    an execution context that provides a strategy for executing the transformation function

    returns

    a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes with a valid Outcome, the passed callback function has completed execution.

  6. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native()
  7. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  8. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  9. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable])
  10. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  11. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  12. def isCompleted: Boolean

    Indicates whether this FutureOutcome has completed.

    Indicates whether this FutureOutcome has completed.

    This method does not block.

    returns

    true if this FutureOutcome has completed; false otherwise.

  13. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  14. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  15. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  16. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  17. 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 this FutureOutcome, unless the callback completes abruptly with an exception. In that case, 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.

    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 this FutureOutcome has completed and, if this FutureOutcome completes abnormally with a run-aborting exception, the passed callback function has completed execution.

  18. 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 this FutureOutcome, unless the callback completes abruptly with an exception. In that case, 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.

    callback

    a side-effecting function to execute if and when this FutureOutcome completes with Canceled

    executionContext

    an execution context that provides a strategy for executing the callback function

    returns

    a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes with Canceled, the passed callback function has completed execution.

  19. 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 this FutureOutcome, unless the callback completes abruptly with an exception. In that case, 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.

    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 this FutureOutcome and, subsequently, the passed callback function have completed execution.

  20. 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 this FutureOutcome, unless the callback completes abruptly with an exception. In that case, 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.

    callback

    a side-effecting function to execute if and when this FutureOutcome completes with Failed

    executionContext

    an execution context that provides a strategy for executing the callback function

    returns

    a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes with Failed, the passed callback function has completed execution.

  21. 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 this FutureOutcome, unless the callback completes abruptly with an exception. In that case, 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.

    callback

    a side-effecting function to execute if and when this FutureOutcome completes with an Outcome (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 this FutureOutcome has completed and, if this FutureOutcome completes with a valid Outcome, the passed callback function has completed execution.

  22. 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 this FutureOutcome, unless the callback completes abruptly with an exception. In that case, 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.

    callback

    a side-effecting function to execute if and when this FutureOutcome completes with Pending

    executionContext

    an execution context that provides a strategy for executing the callback function

    returns

    a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes with Pending, the passed callback function has completed execution.

  23. 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 this FutureOutcome, unless the callback completes abruptly with an exception. In that case, 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.

    callback

    a side-effecting function to execute if and when this FutureOutcome completes with Succeeded

    executionContext

    an execution context that provides a strategy for executing the callback function

    returns

    a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes with Succeeded, the passed callback function has completed execution.

  24. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  25. def toFuture: Future[Outcome]

    Converts this FutureOutcome to a Future[Outcome].

    Converts this FutureOutcome to a Future[Outcome].

    returns

    the underlying Future[Outcome]

  26. def toString(): String
    Definition Classes
    AnyRef → Any
  27. 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 return None. Otherwise, this method will return a Some that contains either a Good[Outcome], if this FutureOutcome completed with a valid Outcome result, or if it completed with a thrown run-aborting exception, a Bad[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 an Or value that indicates the result of this FutureOutcome if it has completed; None otherwise.

  28. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  29. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  30. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException]) @native()

Inherited from AnyRef

Inherited from Any

Ungrouped