1  /*
     2   * Copyright the original author or authors.
     3   * 
     4   * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
     5   * you may not use this file except in compliance with the License.
     6   * You may obtain a copy of the License at
     7   * 
     8   *      http://www.mozilla.org/MPL/MPL-1.1.html
     9   * 
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  
    17  import org.as2lib.core.BasicInterface;
    18  import org.as2lib.io.conn.core.event.MethodInvocationReturnInfo;
    19  import org.as2lib.io.conn.core.event.MethodInvocationErrorInfo;
    20  
    21  /**
    22   * {@code MethodInvocationCallback} awaits the response of a method invocation.
    23   * 
    24   * <p>There are two types of responses.
    25   * <dl>
    26   *   <dt>Return Response:</dt>
    27   *   <dd>
    28   *     Indicates that the method has been invoked successfully without throwing an
    29   *     exception.
    30   *   </dd>
    31   *   <dt>Error Response:</dt>
    32   *   <dd>
    33   *     Indicates that an error occured when trying to invoke the method. This error
    34   *     can for example be an exception the method threw or the unavailability of the
    35   *     method to invoke. For further details take a look at the '*_Error' constants
    36   *     declared by {@link MethodInvocationErrorInfo}.
    37   *   </dd>
    38   * </dl>
    39   *
    40   * <p>Depending on the client and service used, that are responsible for propagating
    41   * the methods on this callback, there may be other circumstances on which a specific
    42   * callback method is invoked.
    43   * 
    44   * <p>This interface can either be instantiated directly or implemented by a class.
    45   * If you instantiate it directly you must overwrite the callback methods you wanna
    46   * be informed of with anonymous functions.
    47   * 
    48   * <p>Note that implementing this interface is much cleaner and less error-prone. It
    49   * is thus recommended to implement this interface whenever possible, instead of
    50   * overwriting the methods with anonymous functions. Note also that the direct
    51   * instantiation of interfaces is not permitted in Flex.
    52   *
    53   * <code>
    54   *   var callback:MethodInvocationCallback = new MethodInvocationCallback();
    55   *   callback.onReturn = function(returnInfo:MethodInvocationReturnInfo):Void) {
    56   *       trace("Invoked method successfully: " + returnInfo); 
    57   *   }
    58   *   callback.onError = function(errorInfo:MethodInvocationErrorInfo):Void {
    59   *       trace("Error occured when trying to invoke the method: " + errorInfo);
    60   *   }
    61   * </code>
    62   *
    63   * <p>Implementing the interface by a class is a much neater way. But sometimes it
    64   * adds unnecessary complexity.
    65   * 
    66   * <code>
    67   *   class MyCallback implements MethodInvocationCallback {
    68   *       public function onReturn(returnInfo:MethodInvocationReturnInfo):Void {
    69   *           trace("Invoked method successfully: " + returnInfo); 
    70   *       }
    71   *       public function onError(errorInfo:MethodInvocationErrorInfo):Void {
    72   *           trace("Error occured when trying to invoke the method: " + errorInfo);
    73   *       }
    74   *   }
    75   * </code>
    76   *
    77   * @author Simon Wacker
    78   */
    79  interface org.as2lib.io.conn.core.event.MethodInvocationCallback extends BasicInterface {
    80  	
    81  	/**
    82  	 * Is executed when the return value of the method invocation arrives.
    83  	 *
    84  	 * <p>This indicates that the method was invoked successfully.
    85  	 *
    86  	 * @param returnInfo contains the return value and some other useful information about
    87  	 * the invoked method
    88  	 */
    89  	public function onReturn(returnInfo:MethodInvocationReturnInfo):Void;
    90  	
    91  	/**
    92  	 * Is executed when a method invocation fails.
    93  	 *
    94  	 * <p>Known issues are:
    95  	 * <ul>
    96  	 *   <li>The method threw an exception.</li>
    97  	 *   <li>The method does not exist on the remote service.</li>
    98  	 * </ul>
    99  	 *
   100  	 * <p>Remember that not all clients support this functionalities.
   101  	 *
   102  	 * @param errorInfo contains information about the error and some useful information
   103  	 * about the called method
   104  	 */
   105  	public function onError(errorInfo:MethodInvocationErrorInfo):Void;
   106  	
   107  }
as2api