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  
    19  /**
    20   * {@code OverloadHandler} declares methods needed by overload handlers.
    21   *
    22   * <p>Overload handlers are used by the {@link Overload} class to identify the 
    23   * corresponding method for a specific list of arguments. Whereby the overload handler
    24   * holds the method and the expected arguments' types of this method.
    25   *
    26   * <p>It also offers functionalities to match real arguments against the expected
    27   * arguments' types, {@link #matches}, and to determine which overload handler or
    28   * rather which arguments' types of two handlers are more explicit,
    29   * {@link #isMoreExplicit}.
    30   *
    31   * <p>It also offers the ability to invoke/execute the target method on a target scope
    32   * passing-in a list of arguments.
    33   *
    34   * @author Simon Wacker
    35   */
    36  interface org.as2lib.env.overload.OverloadHandler extends BasicInterface {
    37  	
    38  	/**
    39  	 * Checks whether the passed-in {@code realArguments} match the expected arguments'
    40  	 * types of this overload handler.
    41  	 *
    42  	 * @param realArguments the real arguments to match against the arguments' types
    43  	 * @return {@code true} if the {@code realArguments} match the arguments' types
    44  	 * else {@code false}
    45  	 */
    46  	public function matches(realArguments:Array):Boolean;
    47  	
    48  	/**
    49  	 * Executes the method of this handler on the given {@code target} passing-in the
    50  	 * given {@code args}.
    51  	 *
    52  	 * <p>The {@code this} scope of the method refers to the passed-in {@code target}
    53  	 * on execution.
    54  	 *
    55  	 * @param target the target object to invoke the method on
    56  	 * @param args the arguments to pass-in on method invocation
    57  	 * @return the result of the method invocation
    58  	 */
    59  	public function execute(target, args:Array);
    60  	
    61  	/**
    62  	 * Checks if this overload handler is more explicit than the passed-in
    63  	 * {@code handler}.
    64  	 *
    65  	 * <p>What means more explicit? The type {@code String} is for example more
    66  	 * explicit than {@code Object}. The type {@code org.as2lib.core.BasicClass} is
    67  	 * also more explicit than {@code Object}. And the type
    68  	 * {@code org.as2lib.env.overload.SimpleOverloadHandler} is more explicit than
    69  	 * {@code org.as2lib.core.BasicClass}. I hope you get the image. As you can see,
    70  	 * the explicitness depends on the inheritance hierarchy.
    71  	 * 
    72  	 * <p>Note that classes are supposed to be more explicit than interfaces.
    73  	 *
    74  	 * @param handler the handler to compare this handler with regarding explicitness
    75  	 * @return {@code true} if this handler is more explicit else {@code false} or
    76  	 * {@code null} if the two handlers have the same explicitness
    77  	 */
    78  	public function isMoreExplicit(handler:OverloadHandler):Boolean;
    79  	
    80  	/**
    81  	 * Returns the arguments' types used to match against the real arguments.
    82  	 *
    83  	 * <p>The arguments' types determine for which types of arguments the method was
    84  	 * declared for. That means which arguments' types the method expects.
    85  	 *
    86  	 * @return the arguments' types the method expects
    87  	 */
    88  	public function getArgumentsTypes(Void):Array;
    89  	
    90  	/**
    91  	 * Returns the method this overload handler was assigned to.
    92  	 *
    93  	 * <p>This is the method to invoke passing the appropriate arguments when this
    94  	 * handler matches the arguments and is the most explicit one.
    95  	 *
    96  	 * @return the method to invoke when the real arguments match the ones of this
    97  	 * handler and this handler is the most explicit one
    98  	 */
    99  	public function getMethod(Void):Function;
   100  	
   101  }
as2api