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.env.reflect.ClassInfo;
    19  import org.as2lib.env.reflect.PackageInfo;
    20  
    21  /**
    22   * Cache chaches classes and packages.
    23   *
    24   * <p>The caching of classes and packages leads to better performance. You also
    25   * must cache them because for example the parent of two classes residing in the
    26   * same package should be the same {@code PackageInfo} instance.
    27   * 
    28   * <p>The cache is mostly used internally. But you can also use it to add
    29   * {@code ClassInfo} or {@code PackageInfo} instances directly so that they do not
    30   * have to be searched for. This can improve the performance dramatically with
    31   * classes or packages that are needed quite often.
    32   *
    33   * @author Simon Wacker
    34   */
    35  interface org.as2lib.env.reflect.Cache extends BasicInterface {
    36  	
    37  	/**
    38  	 * @overload #getClassByClass
    39  	 * @overload #getClassByInstance
    40  	 */
    41  	public function getClass():ClassInfo;
    42  	
    43  	/**
    44  	 * Returns the class info representing the passed-in {@code clazz}.
    45  	 * 
    46  	 * <p>{@code null} will be returned if:
    47  	 * <ul>
    48  	 *   <li>There is no corresponding {@code ClassInfo} instance cached.</li>
    49  	 *   <li>The passed-in {@code clazz} is {@code null} or {@code undefined}.</li>
    50  	 * </ul>
    51  	 *
    52  	 * @param clazz the class to return the class info for
    53  	 * @return the class info representing the passed-in {@code clazz}
    54  	 */
    55  	public function getClassByClass(clazz:Function):ClassInfo;
    56  	
    57  	/**
    58  	 * Returns the class info representing the class the {@code instance} was
    59  	 * instantiated of.
    60  	 * 
    61  	 * <p>{@code null} will be returned if:
    62  	 * <ul>
    63  	 *   <li>There is no corresponding {@code ClassInfo} instance cached.</li>
    64  	 *   <li>The passed-in {@code instance} is {@code null} or {@code undefined}.</li>
    65  	 * </ul>
    66  	 *
    67  	 * @param instance the instance to return the appropriate class info for
    68  	 * @return the class info representing the instance's class
    69  	 */
    70  	public function getClassByInstance(instance):ClassInfo;
    71  	
    72  	/**
    73  	 * Adds the passed-in {@code classInfo} to the list of cached class infos and returns
    74  	 * this {@code classInfo}.
    75  	 * 
    76  	 * @param classInfo the class info to add
    77  	 * @return the passed-in and added {@code classInfo}
    78  	 */
    79  	public function addClass(classInfo:ClassInfo):ClassInfo;
    80  	
    81  	/**
    82  	 * Returns the package info representing the passed-in {@code package}. 
    83  	 *
    84  	 * <p>{@code null} will be returned if:
    85  	 * <ul>
    86  	 *   <li>There is no corresponding {@code PackageInfo} instance cached.</li>
    87  	 *   <li>The passed-in {@code package} is {@code null} or {@code undefined}.</li>
    88  	 * </ul>
    89  	 *
    90  	 * @param package the package to return the appropriate package info for
    91  	 * @return the pakcage info representing the passed-in {@code package}
    92  	 */
    93  	public function getPackage(package):PackageInfo;
    94  	
    95  	/**
    96  	 * Adds the passed-in {@code packageInfo} to this cache and returns this added
    97  	 * {@code packageInfo}.
    98  	 * 
    99  	 * @param packageInfo the package info to add
   100  	 * @return the passed-in and added {@code packageInfo}
   101  	 */
   102  	public function addPackage(packageInfo:PackageInfo):PackageInfo;
   103  	
   104  	/**
   105  	 * Returns the root package of the whole package hierarchy.
   106  	 * 
   107  	 * <p>The root package is also refered to as the default package.
   108  	 *
   109  	 * <p>The root/default package determines where the {@code ClassAlgorithm} and
   110  	 * {@code PackageAlgorithm} classes start their search.
   111  	 *
   112  	 * @return the root/default package
   113  	 */
   114  	public function getRoot(Void):PackageInfo;
   115  	
   116  	/**
   117  	 * Releases all cached class and package infos.
   118  	 */
   119  	public function releaseAll(Void):Void;
   120  	
   121  }
as2api