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 a string describing this parameter. The format is the
99 * modifiers for the parameter, if any, in canonical order as
100 * recommended by <cite>The Java™ Language
101 * Specification</cite>, followed by the fully- qualified type of
102 * the parameter (excluding the last [] if the parameter is
103 * variable arity), followed by "..." if the parameter is variable
104 * arity, followed by a space, followed by the name of the
105 * parameter.
106 *
107 * @return A string representation of the parameter and associated
108 * information.
109 */
110 public String toString() {
111 final StringBuilder sb = new StringBuilder();
112 final Type type = getParameterizedType();
113 final String typename = type.getTypeName();
114
115 sb.append(Modifier.toString(getModifiers()));
116
117 if(0 != modifiers)
118 sb.append(' ');
119
120 if(isVarArgs())
121 sb.append(typename.replaceFirst("\\[\\]$", "..."));
122 else
123 sb.append(typename);
124
125 sb.append(' ');
126 sb.append(getName());
127
128 return sb.toString();
129 }
130
131 /**
132 * Return the {@code Executable} which declares this parameter.
133 *
134 * @return The {@code Executable} declaring this parameter.
135 */
136 public Executable getDeclaringExecutable() {
137 return executable;
138 }
139
140 /**
141 * Get the modifier flags for this the parameter represented by
142 * this {@code Parameter} object.
143 *
144 * @return The modifier flags for this parameter.
145 */
146 public int getModifiers() {
147 return modifiers;
148 }
149
150 /**
151 * Returns the name of the parameter. If the parameter's name is
152 * defined in a class file, then that name will be returned by
153 * this method. Otherwise, this method will synthesize a name of
154 * the form argN, where N is the index of the parameter.
155 */
156 public String getName() {
157 // Note: empty strings as paramete names are now outlawed.
158 // The .equals("") is for compatibility with current JVM
159 // behavior. It may be removed at some point.
160 if(name == null || name.equals(""))
161 return "arg" + index;
162 else
163 return name;
164 }
165
166 /**
167 * Returns a {@code Type} object that identifies the parameterized
168 * type for the parameter represented by this {@code Parameter}
169 * object.
170 *
171 * @return a {@code Type} object identifying the parameterized
172 * type of the parameter represented by this object
173 */
174 public Type getParameterizedType() {
175 Type tmp = parameterTypeCache;
176 if (null == tmp) {
177 tmp = executable.getGenericParameterTypes()[index];
178 parameterTypeCache = tmp;
179 }
180
181 return tmp;
182 }
183
184 private transient volatile Type parameterTypeCache = null;
185
186 /**
187 * Returns a {@code Class} object that identifies the
188 * declared type for the parameter represented by this
189 * {@code Parameter} object.
190 *
191 * @return a {@code Class} object identifying the declared
192 * type of the parameter represented by this object
193 */
194 public Class<?> getType() {
195 Class<?> tmp = parameterClassCache;
196 if (null == tmp) {
197 tmp = executable.getParameterTypes()[index];
198 parameterClassCache = tmp;
199 }
200 return tmp;
201 }
202
203 /**
204 * Returns an AnnotatedType object that represents the use of a type to
205 * specify the type of the formal parameter represented by this Parameter.
206 *
207 * @return an {@code AnnotatedType} object representing the use of a type
208 * to specify the type of the formal parameter represented by this
209 * Parameter
210 */
211 public AnnotatedType getAnnotatedType() {
212 // no caching for now
213 return executable.getAnnotatedParameterTypes()[index];
214 }
215
216 private transient volatile Class<?> parameterClassCache = null;
217
218 /**
219 * Returns {@code true} if this parameter is implicitly declared
220 * in source code; returns {@code false} otherwise.
221 *
222 * @return true if and only if this parameter is implicitly
223 * declared as defined by <cite>The Java™ Language
224 * Specification</cite>.
225 */
226 public boolean isImplicit() {
227 return Modifier.isMandated(getModifiers());
228 }
229
230 /**
231 * Returns {@code true} if this parameter is neither implicitly
232 * nor explicitly declared in source code; returns {@code false}
233 * otherwise.
234 *
235 * @jls 13.1 The Form of a Binary
236 * @return true if and only if this parameter is a synthetic
237 * construct as defined by
238 * <cite>The Java™ Language Specification</cite>.
239 */
240 public boolean isSynthetic() {
241 return Modifier.isSynthetic(getModifiers());
242 }
243
244 /**
245 * Returns {@code true} if this parameter represents a variable
246 * argument list; returns {@code false} otherwise.
247 *
248 * @return {@code true} if an only if this parameter represents a
249 * variable argument list.
250 */
251 public boolean isVarArgs() {
252 return executable.isVarArgs() &&
253 index == executable.getParameterCount() - 1;
254 }
255
256
257 /**
258 * {@inheritDoc}
259 * @throws NullPointerException {@inheritDoc}
260 */
261 public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
262 Objects.requireNonNull(annotationClass);
263 return annotationClass.cast(declaredAnnotations().get(annotationClass));
264 }
265
266 /**
267 * {@inheritDoc}
268 * @throws NullPointerException {@inheritDoc}
269 */
270 @Override
271 public <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass) {
272 Objects.requireNonNull(annotationClass);
273
274 return AnnotationSupport.getMultipleAnnotations(declaredAnnotations(), annotationClass);
275 }
276
277 /**
278 * {@inheritDoc}
279 */
280 public Annotation[] getDeclaredAnnotations() {
281 return executable.getParameterAnnotations()[index];
282 }
283
284 /**
285 * @throws NullPointerException {@inheritDoc}
286 */
287 public <T extends Annotation> T getDeclaredAnnotation(Class<T> annotationClass) {
288 // Only annotations on classes are inherited, for all other
289 // objects getDeclaredAnnotation is the same as
290 // getAnnotation.
291 return getAnnotation(annotationClass);
292 }
293
294 /**
295 * @throws NullPointerException {@inheritDoc}
296 */
297 @Override
298 public <T extends Annotation> T[] getDeclaredAnnotationsByType(Class<T> annotationClass) {
299 // Only annotations on classes are inherited, for all other
300 // objects getDeclaredAnnotations is the same as
301 // getAnnotations.
302 return getAnnotationsByType(annotationClass);
303 }
304
305 /**
306 * {@inheritDoc}
307 */
308 public Annotation[] getAnnotations() {
309 return getDeclaredAnnotations();
310 }
311
312 private transient Map<Class<? extends Annotation>, Annotation> declaredAnnotations;
313
314 private synchronized Map<Class<? extends Annotation>, Annotation> declaredAnnotations() {
315 if(null == declaredAnnotations) {
316 declaredAnnotations =
317 new HashMap<Class<? extends Annotation>, Annotation>();
318 Annotation[] ann = getDeclaredAnnotations();
319 for(int i = 0; i < ann.length; i++)
320 declaredAnnotations.put(ann[i].annotationType(), ann[i]);
321 }
322 return declaredAnnotations;
323 }
324
325 }