1 /*
2 * Copyright (c) 2018, 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 package java.lang.invoke;
26
27 import java.util.List;
28
29 /**
30 * An entity that has a type descriptor.
31 *
32 * @since 12
33 */
34 public interface TypeDescriptor {
35 /**
36 * Returns the descriptor string for this {@code TypeDescriptor} object.
37 *
38 * If this {@code TypeDescriptor} object can be described in nominal form,
39 * then this method returns a type descriptor as specified in JVMS {@jvms 4.3}.
40 * The result descriptor string can be used to produce
41 * a {@linkplain java.lang.constant.ConstantDesc nominal descriptor}.
42 *
43 * Otherwise, the result string is not a type descriptor.
44 * No {@linkplain java.lang.constant.ConstantDesc nominal descriptor}
45 * can be produced from the result string.
46 *
47 * @return the descriptor string for this {@code TypeDescriptor} object
48 * @jvms 4.3.2 Field Descriptors
49 * @jvms 4.3.3 Method Descriptors
50 */
51 String descriptorString();
52
53
54 /**
55 * An entity that has a field type descriptor.
56 * Field descriptors conforming to JVMS {@jvms 4.3.2} can be described
57 * nominally via {@link Class#describeConstable Class::describeConstable};
58 * otherwise they cannot be described nominally.
59 *
60 * @param <F> the class implementing {@linkplain TypeDescriptor.OfField}
61 * @jvms 4.3.2 Field Descriptors
62 * @since 12
63 */
64 interface OfField<F extends TypeDescriptor.OfField<F>> extends TypeDescriptor {
65 /**
66 * Does this field descriptor describe an array type?
67 * @return whether this field descriptor describes an array type
68 */
69 boolean isArray();
70
71 /**
72 * Does this field descriptor describe a primitive type (including void.)
73 *
74 * @return whether this field descriptor describes a primitive type
75 */
76 boolean isPrimitive();
77
78 /**
79 * If this field descriptor describes an array type, return
80 * a descriptor for its component type, otherwise return {@code null}.
81 * @return the component type, or {@code null} if this field descriptor does
82 * not describe an array type
83 */
84 F componentType();
85
86 /**
87 * Return a descriptor for the array type whose component type is described by this
88 * descriptor
89 * @return the descriptor for the array type
90 */
91 F arrayType();
92 }
93
94
95 /**
96 * An entity that has a method type descriptor
97 * Method descriptors conforming to JVMS {@jvms 4.3.3} can be described
98 * nominally via {@link MethodType#describeConstable MethodType::describeConstable};
99 * otherwise they cannot be described nominally.
100 *
101 * @param <F> the type representing field type descriptors
102 * @param <M> the class implementing {@linkplain TypeDescriptor.OfMethod}
103 * @jvms 4.3.2 Field Descriptors
104 * @jvms 4.3.3 Method Descriptors
105 * @since 12
106 */
107 interface OfMethod<F extends TypeDescriptor.OfField<F>, M extends TypeDescriptor.OfMethod<F, M>>
108 extends TypeDescriptor {
109
110 /**
111 * Return the number of parameters in the method type
112 * @return the number of parameters
113 */
114 int parameterCount();
115
116 /**
117 * Return a field descriptor describing the requested parameter of the method type
118 * described by this descriptor
119 * @param i the index of the parameter
120 * @return a field descriptor for the requested parameter type
121 * @throws IndexOutOfBoundsException if the index is outside the half-open
122 * range {[0, parameterCount)}
123 */
124 F parameterType(int i);
125
126 /**
127 * Return a field descriptor describing the return type of the method type described
128 * by this descriptor
129 * @return a field descriptor for the return type
130 */
131 F returnType();
132
133 /**
134 * Return an array of field descriptors for the parameter types of the method type
135 * described by this descriptor
136 * @return field descriptors for the parameter types
137 */
138 F[] parameterArray();
139
140 /**
141 * Return an immutable list of field descriptors for the parameter types of the method type
142 * described by this descriptor
143 * @return field descriptors for the parameter types
144 */
145 List<F> parameterList();
146
147 /**
148 * Return a method descriptor that is identical to this one, except that the return
149 * type has been changed to the specified type
150 *
151 * @param newReturn a field descriptor for the new return type
152 * @throws NullPointerException if any argument is {@code null}
153 * @return the new method descriptor
154 */
155 M changeReturnType(F newReturn);
156
157 /**
158 * Return a method descriptor that is identical to this one,
159 * except that a single parameter type has been changed to the specified type.
160 *
161 * @param index the index of the parameter to change
162 * @param paramType a field descriptor describing the new parameter type
163 * @return the new method descriptor
164 * @throws NullPointerException if any argument is {@code null}
165 * @throws IndexOutOfBoundsException if the index is outside the half-open
166 * range {[0, parameterCount)}
167 */
168 M changeParameterType(int index, F paramType);
169
170 /**
171 * Return a method descriptor that is identical to this one,
172 * except that a range of parameter types have been removed.
173 *
174 * @param start the index of the first parameter to remove
175 * @param end the index after the last parameter to remove
176 * @return the new method descriptor
177 *
178 * @throws IndexOutOfBoundsException if {@code start} is outside the half-open
179 * range {@code [0, parameterCount)}, or {@code end} is outside the closed range
180 * {@code [0, parameterCount]}, or if {@code start > end}
181 */
182 M dropParameterTypes(int start, int end);
183
184 /**
185 * Return a method descriptor that is identical to this one,
186 * except that a range of additional parameter types have been inserted.
187 *
188 * @param pos the index at which to insert the first inserted parameter
189 * @param paramTypes field descriptors describing the new parameter types
190 * to insert
191 * @return the new method descriptor
192 * @throws NullPointerException if any argument is {@code null}
193 * @throws IndexOutOfBoundsException if {@code pos} is outside the closed
194 * range {[0, parameterCount]}
195 */
196 @SuppressWarnings("unchecked")
197 M insertParameterTypes(int pos, F... paramTypes);
198 }
199 }