1 /*
2 * Copyright (c) 2013, 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.reflect;
26
27 import java.lang.annotation.*;
28 import java.util.HashMap;
29 import java.util.Map;
30 import java.util.Objects;
31 import sun.reflect.annotation.AnnotationSupport;
32
33 /**
34 * Information about method parameters.
35 *
36 * A {@code Parameter} provides information about method parameters,
37 * including its name and modifiers. It also provides an alternate
38 * means of obtaining attributes for the parameter.
39 *
40 * @since 1.8
41 */
42 public final class Parameter implements AnnotatedElement {
43
44 private final String name;
45 private final int modifiers;
46 private final Executable executable;
47 private final int index;
48
49 /**
50 * Package-private constructor for {@code Parameter}.
51 *
52 * If method parameter data is present in the classfile, then the
53 * JVM creates {@code Parameter} objects directly. If it is
54 * absent, however, then {@code Executable} uses this constructor
55 * to synthesize them.
56 *
57 * @param name The name of the parameter.
58 * @param modifiers The modifier flags for the parameter.
59 * @param executable The executable which defines this parameter.
60 * @param index The index of the parameter.
61 */
62 Parameter(String name,
63 int modifiers,
64 Executable executable,
65 int index) {
66 this.name = name;
67 this.modifiers = modifiers;
68 this.executable = executable;
69 this.index = index;
70 }
71
72 /**
73 * Compares based on the executable and the index.
74 *
75 * @param obj The object to compare.
76 * @return Whether or not this is equal to the argument.
77 */
78 public boolean equals(Object obj) {
79 if(obj instanceof Parameter) {
80 Parameter other = (Parameter)obj;
81 return (other.executable.equals(executable) &&
82 other.index == index);
83 }
84 return false;
85 }
86
87 /**
88 * Returns a hash code based on the executable's hash code and the
89 * index.
90 *
91 * @return A hash code based on the executable's hash code.
92 */
93 public int hashCode() {
94 return executable.hashCode() ^ index;
95 }
96
97 /**
98 * Returns true if the parameter has a name according to the class
99 * file; returns false otherwise. Whether a parameter has a name
100 * is determined by the {@literal MethodParameters} attribute of
101 * the method which declares the parameter.
102 *
103 * @return true if and only if the parameter has a name according
104 * to the class file.
105 */
106 public boolean isNamePresent() {
107 return executable.hasRealParameterData() && name != null;
108 }
109
110 /**
111 * Returns a string describing this parameter. The format is the
112 * modifiers for the parameter, if any, in canonical order as
113 * recommended by <cite>The Java™ Language
114 * Specification</cite>, followed by the fully- qualified type of
115 * the parameter (excluding the last [] if the parameter is
116 * variable arity), followed by "..." if the parameter is variable
117 * arity, followed by a space, followed by the name of the
118 * parameter.
119 *
120 * @return A string representation of the parameter and associated
121 * information.
122 */
123 public String toString() {
124 final StringBuilder sb = new StringBuilder();
125 final Type type = getParameterizedType();
126 final String typename = type.getTypeName();
127
128 sb.append(Modifier.toString(getModifiers()));
129
130 if(0 != modifiers)
131 sb.append(' ');
132
133 if(isVarArgs())
134 sb.append(typename.replaceFirst("\\[\\]$", "..."));
135 else
136 sb.append(typename);
137
138 sb.append(' ');
139 sb.append(getName());
140
141 return sb.toString();
142 }
143
144 /**
145 * Return the {@code Executable} which declares this parameter.
146 *
147 * @return The {@code Executable} declaring this parameter.
148 */
149 public Executable getDeclaringExecutable() {
150 return executable;
151 }
152
153 /**
154 * Get the modifier flags for this the parameter represented by
155 * this {@code Parameter} object.
156 *
157 * @return The modifier flags for this parameter.
158 */
159 public int getModifiers() {
160 return modifiers;
161 }
162
163 /**
164 * Returns the name of the parameter. If the parameter's name is
165 * {@linkplain #isNamePresent() present}, then this method returns
166 * the name provided by the class file. Otherwise, this method
167 * synthesizes a name of the form argN, where N is the index of
168 * the parameter in the descriptor of the method which declares
169 * the parameter.
170 *
171 * @return The name of the parameter, either provided by the class
172 * file or synthesized if the class file does not provide
173 * a name.
174 */
175 public String getName() {
176 // Note: empty strings as parameter names are now outlawed.
177 // The .isEmpty() is for compatibility with current JVM
178 // behavior. It may be removed at some point.
179 if(name == null || name.isEmpty())
180 return "arg" + index;
181 else
182 return name;
183 }
184
185 // Package-private accessor to the real name field.
186 String getRealName() {
187 return name;
188 }
189
190 /**
191 * Returns a {@code Type} object that identifies the parameterized
192 * type for the parameter represented by this {@code Parameter}
193 * object.
194 *
195 * @return a {@code Type} object identifying the parameterized
196 * type of the parameter represented by this object
197 */
198 public Type getParameterizedType() {
199 Type tmp = parameterTypeCache;
200 if (null == tmp) {
201 tmp = executable.getAllGenericParameterTypes()[index];
202 parameterTypeCache = tmp;
203 }
204
205 return tmp;
206 }
207
208 private transient volatile Type parameterTypeCache;
209
210 /**
211 * Returns a {@code Class} object that identifies the
212 * declared type for the parameter represented by this
213 * {@code Parameter} object.
214 *
215 * @return a {@code Class} object identifying the declared
216 * type of the parameter represented by this object
217 */
218 public Class<?> getType() {
219 Class<?> tmp = parameterClassCache;
220 if (null == tmp) {
221 tmp = executable.getParameterTypes()[index];
222 parameterClassCache = tmp;
223 }
224 return tmp;
225 }
226
227 /**
228 * Returns an AnnotatedType object that represents the use of a type to
229 * specify the type of the formal parameter represented by this Parameter.
230 *
231 * @return an {@code AnnotatedType} object representing the use of a type
232 * to specify the type of the formal parameter represented by this
233 * Parameter
234 */
235 public AnnotatedType getAnnotatedType() {
236 // no caching for now
237 return executable.getAnnotatedParameterTypes()[index];
238 }
239
240 private transient volatile Class<?> parameterClassCache;
241
242 /**
243 * Returns {@code true} if this parameter is implicitly declared
244 * in source code; returns {@code false} otherwise.
245 *
246 * @return true if and only if this parameter is implicitly
247 * declared as defined by <cite>The Java™ Language
248 * Specification</cite>.
249 */
250 public boolean isImplicit() {
251 return Modifier.isMandated(getModifiers());
252 }
253
254 /**
255 * Returns {@code true} if this parameter is neither implicitly
256 * nor explicitly declared in source code; returns {@code false}
257 * otherwise.
258 *
259 * @jls 13.1 The Form of a Binary
260 * @return true if and only if this parameter is a synthetic
261 * construct as defined by
262 * <cite>The Java™ Language Specification</cite>.
263 */
264 public boolean isSynthetic() {
265 return Modifier.isSynthetic(getModifiers());
266 }
267
268 /**
269 * Returns {@code true} if this parameter represents a variable
270 * argument list; returns {@code false} otherwise.
271 *
272 * @return {@code true} if an only if this parameter represents a
273 * variable argument list.
274 */
275 public boolean isVarArgs() {
276 return executable.isVarArgs() &&
277 index == executable.getParameterCount() - 1;
278 }
279
280
281 /**
282 * {@inheritDoc}
283 * @throws NullPointerException {@inheritDoc}
284 */
285 public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
286 Objects.requireNonNull(annotationClass);
287 return annotationClass.cast(declaredAnnotations().get(annotationClass));
288 }
289
290 /**
291 * {@inheritDoc}
292 * @throws NullPointerException {@inheritDoc}
293 */
294 @Override
295 public <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass) {
296 Objects.requireNonNull(annotationClass);
297
298 return AnnotationSupport.getDirectlyAndIndirectlyPresent(declaredAnnotations(), annotationClass);
299 }
300
301 /**
302 * {@inheritDoc}
303 */
304 public Annotation[] getDeclaredAnnotations() {
305 return executable.getParameterAnnotations()[index];
306 }
307
308 /**
309 * @throws NullPointerException {@inheritDoc}
310 */
311 public <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass) {
312 // Only annotations on classes are inherited, for all other
313 // objects getDeclaredAnnotation is the same as
314 // getAnnotation.
315 return getAnnotation(annotationClass);
316 }
317
318 /**
319 * @throws NullPointerException {@inheritDoc}
320 */
321 @Override
322 public <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass) {
323 // Only annotations on classes are inherited, for all other
324 // objects getDeclaredAnnotations is the same as
325 // getAnnotations.
326 return getAnnotationsByType(annotationClass);
327 }
328
329 /**
330 * {@inheritDoc}
331 */
332 public Annotation[] getAnnotations() {
333 return getDeclaredAnnotations();
334 }
335
336 private transient Map<Class<? extends Annotation>, Annotation> declaredAnnotations;
337
338 private synchronized Map<Class<? extends Annotation>, Annotation> declaredAnnotations() {
339 if(null == declaredAnnotations) {
340 declaredAnnotations = new HashMap<>();
341 for (Annotation a : getDeclaredAnnotations())
342 declaredAnnotations.put(a.annotationType(), a);
343 }
344 return declaredAnnotations;
345 }
346
347 }