Adds a callback to Future that is invoked upon completion, whether success or failure.

corelib/src/future.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 // Dart core library.
 
 
 /**
  * A [Future] is used to obtain a value sometime in the future.  Receivers of a
- * [Future] obtain the value by passing a callback to [then]. For example:
+ * [Future] can obtain the value by passing a callback to [then].
+ * For example:
  *
  *   Future<int> future = getFutureFromSomewhere();
  *   future.then((value) {
  *     print("I received the number $value");
  *   });
+ * 
+ * A future may complete by *succeeding* (producing a value) or *failing*
+ * (producing an exception, which may be handled with [handleException]).
+ * Callbacks passed to [onComplete] will be invoked in either case.
+ *
+ * When a future completes:

[Siggi Cherem (dart-lang), 2012/06/06 20:42:49]

say in order somewhere? For instance,
=> When a future completes the following actions happen in order:

+ *
+ *   1. if the future suceeded, handlers registered with [then] are called.
+ *   2. if the future failed, handlers registered with [handleException] are
+ *      called in sequence, until one returns true.
+ *   3. handlers registered with [onComplete] are called
+ *   4. if the future failed, and at least one handler was registered with
+ *      [then], and no handler registered with [handleException] returned
+ *      [:true:], then the exception is thrown.
  */
 interface Future<T> default FutureImpl<T> {
 
   /** A future whose value is immediately available. */
   Future.immediate(T value);
 
   /** The value provided. Throws an exception if [hasValue] is false. */
   T get value();
 
   /**
    * Exception that occurred ([:null:] if no exception occured). This property
    * throws a [FutureNotCompleteException] if it is used before this future is
    * completes.
    */
   Object get exception();
 
   /**
    * Whether the future is complete (either the value is available or there was
    * an exception).
    */
   bool get isComplete();
 
   /**
    * Whether the value is available (meaning [isComplete] is true, and there was
    * no exception).
    */
   bool get hasValue();
 
   /**
-   * When this future is complete and has a value, then [onComplete] is called
+   * When this future is complete (either with a value or with an exception),
+   * then [complete] is called with the future.
+   * If [complete] throws an exception, it is ignored.
+   */
+  void onComplete(void complete(Future<T> future));
+
+  /**
+   * If this future is complete and has a value, then [onValue] is called
    * with the value.
    */
-  void then(void onComplete(T value));
+  void then(void onValue(T value));
 
   /**
-   * If this future gets an exception, then call [onException].
+   * If this future is complete and has an exception, then call [onException].
    *
    * If [onException] returns true, then the exception is considered handled.
    *
    * If [onException] does not return true (or [handleException] was never
    * called), then the exception is not considered handled. In that case, if
    * there were any calls to [then], then the exception will be thrown when the
    * value is set.
    *
    * In most cases it should not be necessary to call [handleException],
    * because the exception associated with this [Future] will propagate
    * naturally if the future's value is being consumed. Only call
    * [handleException] if you need to do some special local exception handling
    * related to this particular Future's value.
    */
   void handleException(bool onException(Object exception));
 
   /**
    * A future representing [transformation] applied to this future's value.
    *
    * When this future gets a value, [transformation] will be called on the
    * value, and the returned future will receive the result.
    *
    * If an exception occurs (received by this future, or thrown by
    * [transformation]) then the returned future will receive the exception.
-   *
-   * You must not add exception handlers to [this] future prior to calling
-   * transform, and any you add afterwards will not be invoked.
    */
   Future transform(transformation(T value));
 
    /**
     * A future representing an asynchronous transformation applied to this
     * future's value. [transformation] must return a Future.
     *
     * When this future gets a value, [transformation] will be called on the
     * value. When the resulting future gets a value, the returned future
     * will receive it.
     *
     * If an exception occurs (received by this future, thrown by
     * [transformation], or received by the future returned by [transformation])
     * then the returned future will receive the exception.
-    *
-    * You must not add exception handlers to [this] future prior to calling
-    * chain, and any you add afterwards will not be invoked.
     */
    Future chain(Future transformation(T value));
 }
 
 
 /**
  * A [Completer] is used to produce [Future]s and supply their value when it
  * becomes available.
  *
  * A service that provides values to callers, and wants to return [Future]s can
@@ skipping 81 matching lines @@
         }
       });
       future.handleException((exception) {
         if (!result.isComplete) completer.completeException(exception);
         return true;
       });
     }
     return result;
   }
 }