001    // Copyright 2002-2007 Waterken Inc. under the terms of the MIT X license
002    // found at http://www.opensource.org/licenses/mit-license.html
003    package org.ref_send.promise;
004    
005    /**
006     * A promise for a referent.
007     * <p>
008     * If you conceptualize a reference as being like an arrow, where an invocation
009     * is started at the tail end of the arrow and delivered to the object pointed
010     * to by the head end of the arrow, then a promise is like the tail end of an
011     * arrow which doesn't yet point to anything. The object referred to by a
012     * promise can be determined later. Using a promise, an algorithm can refer to
013     * an object which will be the result of future computation.
014     * </p>
015     * <pre>
016     *                       reference
017     *                       |
018     *            referrer ----&gt; referent
019     *                     |
020     *                     promise end of the reference
021     * </pre>
022     * <p>
023     * There are three states for a promise: <em>fulfilled</em>,
024     * <em>rejected</em> and <em>unresolved</em>. A <em>fulfilled</em>
025     * promise is successfully bound to a referent, which can be either local or
026     * remote. A <em>rejected</em> promise failed to acquire a referent, and
027     * carries an {@link Exception} specifying the reason for the failure. An
028     * <em>unresolved</em> promise is in neither the success nor failure state. A
029     * promise is <em>resolved</em> if it is in either the success or failure
030     * state.
031     * </p>
032     * @param <T> referent type
033     */
034    public interface
035    Promise<T> {
036        
037        /**
038         * Gets the current referent.
039         * <p>
040         * For example:
041         * </p>
042         * <pre>
043         * final Promise&lt;Foo&gt; foo = &hellip;
044         * try {
045         *     foo.call().bar();
046         * } catch (final Exception reason) {
047         *     // Either there is no referent, or the bar() invocation failed.
048         *     throw reason;
049         * }
050         * </pre>
051         * @throws Exception    reason the referent is not known
052         */
053        T call() throws Exception;
054    }