1 /* 2 * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package sun.reflect.generics.factory; 27 28 import java.lang.reflect.ParameterizedType; 29 import java.lang.reflect.Type; 30 import java.lang.reflect.TypeVariable; 31 import java.lang.reflect.WildcardType; 32 import sun.reflect.generics.tree.FieldTypeSignature; 33 34 /** 35 * A factory interface for reflective objects representing generic types. 36 * Implementors (such as core reflection or JDI, or possibly javadoc 37 * will manufacture instances of (potentially) different classes 38 * in response to invocations of the methods described here. 39 * <p> The intent is that reflective systems use these factories to 40 * produce generic type information on demand. 41 * Certain components of such reflective systems can be independent 42 * of a specific implementation by using this interface. For example, 43 * repositories of generic type information are initialized with a 44 * factory conforming to this interface, and use it to generate the 45 * type information they are required to provide. As a result, such 46 * repository code can be shared across different reflective systems. 47 */ 48 public interface GenericsFactory { 49 /** 50 * Returns a new type variable declaration. Note that <tt>name</tt> 51 * may be empty (but not <tt>null</tt>). If <tt>bounds</tt> is 52 * empty, a bound of <tt>java.lang.Object</tt> is used. 53 * @param name The name of the type variable 54 * @param bounds An array of abstract syntax trees representing 55 * the upper bound(s) on the type variable being declared 56 * @return a new type variable declaration 57 * @throws NullPointerException - if any of the actual parameters 58 * or any of the elements of <tt>bounds</tt> are <tt>null</tt>. 59 */ 60 TypeVariable<?> makeTypeVariable(String name, 61 FieldTypeSignature[] bounds); 62 /** 63 * Returns an instance of the <tt>ParameterizedType</tt> interface 64 * that corresponds to a generic type instantiation of the 65 * generic declaration <tt>declaration</tt> with actual type arguments 66 * <tt>typeArgs</tt>. 67 * If <tt>owner</tt> is <tt>null</tt>, the declaring class of 68 * <tt>declaration</tt> is used as the owner of this parameterized 69 * type. 70 * <p> This method throws a MalformedParameterizedTypeException 71 * under the following circumstances: 72 * If the type declaration does not represent a generic declaration 73 * (i.e., it is not an instance of <tt>GenericDeclaration</tt>). 74 * If the number of actual type arguments (i.e., the size of the 75 * array <tt>typeArgs</tt>) does not correspond to the number of 76 * formal type arguments. 77 * If any of the actual type arguments is not an instance of the 78 * bounds on the corresponding formal. 79 * @param declaration - the generic type declaration that is to be 80 * instantiated 81 * @param typeArgs - the list of actual type arguments 82 * @return - a parameterized type representing the instantiation 83 * of the declaration with the actual type arguments 84 * @throws MalformedParameterizedTypeException - if the instantiation 85 * is invalid 86 * @throws NullPointerException - if any of <tt>declaration</tt> 87 * , <tt>typeArgs</tt> 88 * or any of the elements of <tt>typeArgs</tt> are <tt>null</tt> 89 */ 90 ParameterizedType makeParameterizedType(Type declaration, 91 Type[] typeArgs, 92 Type owner); 93 94 /** 95 * Returns the type variable with name <tt>name</tt>, if such 96 * a type variable is declared in the 97 * scope used to create this factory. 98 * Returns <tt>null</tt> otherwise. 99 * @param name - the name of the type variable to search for 100 * @return - the type variable with name <tt>name</tt>, or <tt>null</tt> 101 * @throws NullPointerException - if any of actual parameters are 102 * <tt>null</tt> 103 */ 104 TypeVariable<?> findTypeVariable(String name); 105 106 /** 107 * Returns a new wildcard type variable. If 108 * <tt>ubs</tt> is empty, a bound of <tt>java.lang.Object</tt> is used. 109 * @param ubs An array of abstract syntax trees representing 110 * the upper bound(s) on the type variable being declared 111 * @param lbs An array of abstract syntax trees representing 112 * the lower bound(s) on the type variable being declared 113 * @return a new wildcard type variable 114 * @throws NullPointerException - if any of the actual parameters 115 * or any of the elements of <tt>ubs</tt> or <tt>lbs</tt>are 116 * <tt>null</tt> 117 */ 118 WildcardType makeWildcard(FieldTypeSignature[] ubs, 119 FieldTypeSignature[] lbs); 120 121 Type makeNamedType(String name); 122 123 /** 124 * Returns a (possibly generic) array type. 125 * If the component type is a parameterized type, it must 126 * only have unbounded wildcard arguments, otherwise 127 * a MalformedParameterizedTypeException is thrown. 128 * @param componentType - the component type of the array 129 * @return a (possibly generic) array type. 130 * @throws MalformedParameterizedTypeException if <tt>componentType</tt> 131 * is a parameterized type with non-wildcard type arguments 132 * @throws NullPointerException - if any of the actual parameters 133 * are <tt>null</tt> 134 */ 135 Type makeArrayType(Type componentType); 136 137 /** 138 * Returns the reflective representation of type <tt>byte</tt>. 139 * @return the reflective representation of type <tt>byte</tt>. 140 */ 141 Type makeByte(); 142 143 /** 144 * Returns the reflective representation of type <tt>boolean</tt>. 145 * @return the reflective representation of type <tt>boolean</tt>. 146 */ 147 Type makeBool(); 148 149 /** 150 * Returns the reflective representation of type <tt>short</tt>. 151 * @return the reflective representation of type <tt>short</tt>. 152 */ 153 Type makeShort(); 154 155 /** 156 * Returns the reflective representation of type <tt>char</tt>. 157 * @return the reflective representation of type <tt>char</tt>. 158 */ 159 Type makeChar(); 160 161 /** 162 * Returns the reflective representation of type <tt>int</tt>. 163 * @return the reflective representation of type <tt>int</tt>. 164 */ 165 Type makeInt(); 166 167 /** 168 * Returns the reflective representation of type <tt>long</tt>. 169 * @return the reflective representation of type <tt>long</tt>. 170 */ 171 Type makeLong(); 172 173 /** 174 * Returns the reflective representation of type <tt>float</tt>. 175 * @return the reflective representation of type <tt>float</tt>. 176 */ 177 Type makeFloat(); 178 179 /** 180 * Returns the reflective representation of type <tt>double</tt>. 181 * @return the reflective representation of type <tt>double</tt>. 182 */ 183 Type makeDouble(); 184 185 /** 186 * Returns the reflective representation of <tt>void</tt>. 187 * @return the reflective representation of <tt>void</tt>. 188 */ 189 Type makeVoid(); 190 }