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 }