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 {@code name} 51 * may be empty (but not {@code null}). If {@code bounds} is 52 * empty, a bound of {@code java.lang.Object} 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 {@code bounds} are {@code null}. 59 */ 60 TypeVariable<?> makeTypeVariable(String name, 61 FieldTypeSignature[] bounds); 62 /** 63 * Returns an instance of the {@code ParameterizedType} interface 64 * that corresponds to a generic type instantiation of the 65 * generic declaration {@code declaration} with actual type arguments 66 * {@code typeArgs}. 67 * If {@code owner} is {@code null}, the declaring class of 68 * {@code declaration} 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 {@code GenericDeclaration}). 74 * If the number of actual type arguments (i.e., the size of the 75 * array {@code typeArgs}) 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 {@code declaration}, 87 * {@code typeArgs} 88 * or any of the elements of {@code typeArgs} are {@code null} 89 */ 90 ParameterizedType makeParameterizedType(Type declaration, 91 Type[] typeArgs, 92 Type owner); 93 94 /** 95 * Returns the type variable with name {@code name}, if such 96 * a type variable is declared in the 97 * scope used to create this factory. 98 * Returns {@code null} otherwise. 99 * @param name - the name of the type variable to search for 100 * @return - the type variable with name {@code name}, or {@code null} 101 * @throws NullPointerException if any of actual parameters are 102 * {@code null} 103 */ 104 TypeVariable<?> findTypeVariable(String name); 105 106 /** 107 * Returns a new wildcard type variable. If 108 * {@code ubs} is empty, a bound of {@code java.lang.Object} 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 {@code ubs} or {@code lbs} are 116 * {@code null} 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 {@code componentType} 131 * is a parameterized type with non-wildcard type arguments 132 * @throws NullPointerException if any of the actual parameters 133 * are {@code null} 134 */ 135 Type makeArrayType(Type componentType); 136 137 /** 138 * Returns the reflective representation of type {@code byte}. 139 * @return the reflective representation of type {@code byte}. 140 */ 141 Type makeByte(); 142 143 /** 144 * Returns the reflective representation of type {@code boolean}. 145 * @return the reflective representation of type {@code boolean}. 146 */ 147 Type makeBool(); 148 149 /** 150 * Returns the reflective representation of type {@code short}. 151 * @return the reflective representation of type {@code short}. 152 */ 153 Type makeShort(); 154 155 /** 156 * Returns the reflective representation of type {@code char}. 157 * @return the reflective representation of type {@code char}. 158 */ 159 Type makeChar(); 160 161 /** 162 * Returns the reflective representation of type {@code int}. 163 * @return the reflective representation of type {@code int}. 164 */ 165 Type makeInt(); 166 167 /** 168 * Returns the reflective representation of type {@code long}. 169 * @return the reflective representation of type {@code long}. 170 */ 171 Type makeLong(); 172 173 /** 174 * Returns the reflective representation of type {@code float}. 175 * @return the reflective representation of type {@code float}. 176 */ 177 Type makeFloat(); 178 179 /** 180 * Returns the reflective representation of type {@code double}. 181 * @return the reflective representation of type {@code double}. 182 */ 183 Type makeDouble(); 184 185 /** 186 * Returns the reflective representation of {@code void}. 187 * @return the reflective representation of {@code void}. 188 */ 189 Type makeVoid(); 190 }