View Javadoc
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   * tpe 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       * Return 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 arguemnts, 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 }