001    /*
002     * Copyright 2006 Google Inc.
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005     * use this file except in compliance with the License. You may obtain a copy of
006     * the License at
007     * 
008     * http://www.apache.org/licenses/LICENSE-2.0
009     * 
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012     * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013     * License for the specific language governing permissions and limitations under
014     * the License.
015     */
016    package com.google.gwt.user.client.rpc;
017    
018    /**
019     * The primary interface a caller must implement to receive a response from a
020     * remote procedure call.
021     * 
022     * <p>
023     * If an RPC is successful, then {@link #onSuccess(Object)} is called, otherwise
024     * {@link #onFailure(Throwable)} is called.
025     * </p>
026     * 
027     * <p>
028     * Each callable asynchronous method corresponds to a method in the correlated
029     * service interface. The asynchronous method always takes an
030     * <code>AsyncCallback</code> as its last parameter.
031     * </p>
032     * 
033     * <p>
034     * As an example, suppose the service interface defines a method called
035     * <code>getShapes</code> as follows:
036     * 
037     * <pre>
038     * Shape[] getShapes(String databaseName) throws ShapeException, DbException;
039     * </pre>
040     * 
041     * Its asynchronous counterpart method be declared as:
042     * 
043     * <pre>
044     * void getShapes(String databaseName, AsyncCallback callback);
045     * </pre>
046     * 
047     * Note that <code>throws</code> declaration is not repeated in the async
048     * version.
049     * </p>
050     * 
051     * <p>
052     * A call with a typical use of <code>AsyncCallback</code> might look like
053     * this:
054     * 
055     * <pre class="code">
056     * service.getShapes(dbName, new AsyncCallback() {
057     *   public void onSuccess(Object result) {
058     *     // It's always safe to downcast to the known return type. 
059     *     Shape[] shapes = (Shape[]) result;
060     *     controller.processShapes(shapes);
061     *   }
062     * 
063     *   public void onFailure(Throwable caught) {
064     *     // Convenient way to find out which exception was thrown.
065     *     try {
066     *       throw caught;
067     *     } catch (InvocationException e) {
068     *       // the call didn't complete cleanly
069     *     } catch (ShapeException e) {
070     *       // one of the 'throws' from the original method
071     *     } catch (DbException e) {
072     *       // one of the 'throws' from the original method
073     *     } catch (Throwable e) {
074     *       // last resort -- a very unexpected exception
075     *     }
076     *   }
077     * });
078     * </pre>
079     * 
080     * </p>
081     */
082    public interface AsyncCallback {
083    
084      /**
085       * Called when an asynchronous call completes successfully. It is always safe
086       * to downcast the parameter (of type <code>Object</code>) to the return
087       * type of the original method for which this is a callback. Note that if the
088       * return type of the synchronous service interface method is a primitive then
089       * the parameter will be the boxed version of the primitive (for example, an
090       * <code>int</code> return type becomes an {@link Integer}.
091       */
092      void onSuccess(Object result);
093    
094      /**
095       * Called when an asynchronous call fails to complete normally.
096       */
097      void onFailure(Throwable caught);
098    }