Method.java revision e77a467884a8b323a1ac6a229f06f9a032b141b5
1/* 2 * Copyright (C) 2014 The Android Open Source Project 3 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 27package java.lang.reflect; 28 29import dalvik.annotation.optimization.FastNative; 30import java.lang.annotation.Annotation; 31import java.util.Comparator; 32import libcore.reflect.Types; 33import libcore.util.EmptyArray; 34 35/** 36 * A {@code Method} provides information about, and access to, a single method 37 * on a class or interface. The reflected method may be a class method 38 * or an instance method (including an abstract method). 39 * 40 * <p>A {@code Method} permits widening conversions to occur when matching the 41 * actual parameters to invoke with the underlying method's formal 42 * parameters, but it throws an {@code IllegalArgumentException} if a 43 * narrowing conversion would occur. 44 * 45 * @see Member 46 * @see java.lang.Class 47 * @see java.lang.Class#getMethods() 48 * @see java.lang.Class#getMethod(String, Class[]) 49 * @see java.lang.Class#getDeclaredMethods() 50 * @see java.lang.Class#getDeclaredMethod(String, Class[]) 51 * 52 * @author Kenneth Russell 53 * @author Nakul Saraiya 54 */ 55public final class Method extends Executable { 56 /** 57 * Orders methods by their name, parameters and return type. 58 * 59 * @hide 60 */ 61 public static final Comparator<Method> ORDER_BY_SIGNATURE = new Comparator<Method>() { 62 @Override public int compare(Method a, Method b) { 63 if (a == b) { 64 return 0; 65 } 66 int comparison = a.getName().compareTo(b.getName()); 67 if (comparison == 0) { 68 comparison = a.compareMethodParametersInternal(b); 69 if (comparison == 0) { 70 // This is necessary for methods that have covariant return types. 71 Class<?> aReturnType = a.getReturnType(); 72 Class<?> bReturnType = b.getReturnType(); 73 if (aReturnType == bReturnType) { 74 comparison = 0; 75 } else { 76 comparison = aReturnType.getName().compareTo(bReturnType.getName()); 77 } 78 } 79 } 80 return comparison; 81 } 82 }; 83 84 private Method() { 85 } 86 87 @Override 88 boolean hasGenericInformation() { 89 // Android-changed: Signature retrieval is handled in Executable. 90 return super.hasGenericInformationInternal(); 91 } 92 93 /** 94 * {@inheritDoc} 95 */ 96 @Override 97 public Class<?> getDeclaringClass() { 98 // Android-changed: This is handled by Executable. 99 return super.getDeclaringClassInternal(); 100 } 101 102 /** 103 * Returns the name of the method represented by this {@code Method} 104 * object, as a {@code String}. 105 */ 106 @Override 107 public String getName() { 108 // Android-changed: This is handled by Executable. 109 return getMethodNameInternal(); 110 } 111 112 /** 113 * {@inheritDoc} 114 */ 115 @Override 116 public int getModifiers() { 117 // Android-changed: This is handled by Executable. 118 return super.getModifiersInternal(); 119 } 120 121 /** 122 * {@inheritDoc} 123 * @throws GenericSignatureFormatError {@inheritDoc} 124 * @since 1.5 125 */ 126 @Override 127 @SuppressWarnings({"rawtypes", "unchecked"}) 128 public TypeVariable<Method>[] getTypeParameters() { 129 // Android-changed: This is mostly handled by Executable. 130 GenericInfo info = getMethodOrConstructorGenericInfoInternal(); 131 return (TypeVariable<Method>[]) info.formalTypeParameters.clone(); 132 } 133 134 /** 135 * Returns a {@code Class} object that represents the formal return type 136 * of the method represented by this {@code Method} object. 137 * 138 * @return the return type for the method this object represents 139 */ 140 public Class<?> getReturnType() { 141 return getMethodReturnTypeInternal(); 142 } 143 144 /** 145 * Returns a {@code Type} object that represents the formal return 146 * type of the method represented by this {@code Method} object. 147 * 148 * <p>If the return type is a parameterized type, 149 * the {@code Type} object returned must accurately reflect 150 * the actual type parameters used in the source code. 151 * 152 * <p>If the return type is a type variable or a parameterized type, it 153 * is created. Otherwise, it is resolved. 154 * 155 * @return a {@code Type} object that represents the formal return 156 * type of the underlying method 157 * @throws GenericSignatureFormatError 158 * if the generic method signature does not conform to the format 159 * specified in 160 * <cite>The Java™ Virtual Machine Specification</cite> 161 * @throws TypeNotPresentException if the underlying method's 162 * return type refers to a non-existent type declaration 163 * @throws MalformedParameterizedTypeException if the 164 * underlying method's return typed refers to a parameterized 165 * type that cannot be instantiated for any reason 166 * @since 1.5 167 */ 168 public Type getGenericReturnType() { 169 // Android-changed: Modified implementation to use Executable. 170 return Types.getType(getMethodOrConstructorGenericInfoInternal().genericReturnType); 171 } 172 173 /** 174 * {@inheritDoc} 175 */ 176 @Override 177 public Class<?>[] getParameterTypes() { 178 // Android-changed: This is handled by Executable. 179 Class<?>[] paramTypes = super.getParameterTypesInternal(); 180 if (paramTypes == null) { 181 return EmptyArray.CLASS; 182 } 183 184 return paramTypes; 185 } 186 187 /** 188 * {@inheritDoc} 189 */ 190 public int getParameterCount() { 191 // Android-changed: This is handled by Executable. 192 return super.getParameterCountInternal(); 193 } 194 195 /** 196 * {@inheritDoc} 197 * @throws GenericSignatureFormatError {@inheritDoc} 198 * @throws TypeNotPresentException {@inheritDoc} 199 * @throws MalformedParameterizedTypeException {@inheritDoc} 200 * @since 1.5 201 */ 202 @Override 203 public Type[] getGenericParameterTypes() { 204 return super.getGenericParameterTypes(); 205 } 206 207 /** 208 * {@inheritDoc} 209 */ 210 @Override 211 @FastNative 212 public native Class<?>[] getExceptionTypes(); 213 214 /** 215 * {@inheritDoc} 216 * @throws GenericSignatureFormatError {@inheritDoc} 217 * @throws TypeNotPresentException {@inheritDoc} 218 * @throws MalformedParameterizedTypeException {@inheritDoc} 219 * @since 1.5 220 */ 221 @Override 222 public Type[] getGenericExceptionTypes() { 223 return super.getGenericExceptionTypes(); 224 } 225 226 /** 227 * Compares this {@code Method} against the specified object. Returns 228 * true if the objects are the same. Two {@code Methods} are the same if 229 * they were declared by the same class and have the same name 230 * and formal parameter types and return type. 231 */ 232 public boolean equals(Object obj) { 233 if (obj != null && obj instanceof Method) { 234 Method other = (Method)obj; 235 if ((getDeclaringClass() == other.getDeclaringClass()) 236 && (getName() == other.getName())) { 237 if (!getReturnType().equals(other.getReturnType())) 238 return false; 239 // Android-changed: Use getParameterTypes. 240 return equalParamTypes(getParameterTypes(), other.getParameterTypes()); 241 } 242 } 243 return false; 244 } 245 246 /** 247 * Returns a hashcode for this {@code Method}. The hashcode is computed 248 * as the exclusive-or of the hashcodes for the underlying 249 * method's declaring class name and the method's name. 250 */ 251 public int hashCode() { 252 return getDeclaringClass().getName().hashCode() ^ getName().hashCode(); 253 } 254 255 /** 256 * Returns a string describing this {@code Method}. The string is 257 * formatted as the method access modifiers, if any, followed by 258 * the method return type, followed by a space, followed by the 259 * class declaring the method, followed by a period, followed by 260 * the method name, followed by a parenthesized, comma-separated 261 * list of the method's formal parameter types. If the method 262 * throws checked exceptions, the parameter list is followed by a 263 * space, followed by the word throws followed by a 264 * comma-separated list of the thrown exception types. 265 * For example: 266 * <pre> 267 * public boolean java.lang.Object.equals(java.lang.Object) 268 * </pre> 269 * 270 * <p>The access modifiers are placed in canonical order as 271 * specified by "The Java Language Specification". This is 272 * {@code public}, {@code protected} or {@code private} first, 273 * and then other modifiers in the following order: 274 * {@code abstract}, {@code default}, {@code static}, {@code final}, 275 * {@code synchronized}, {@code native}, {@code strictfp}. 276 * 277 * @return a string describing this {@code Method} 278 * 279 * @jls 8.4.3 Method Modifiers 280 */ 281 public String toString() { 282 // Android-changed: Use getParameterTypes. 283 return sharedToString(Modifier.methodModifiers(), 284 isDefault(), 285 getParameterTypes(), 286 getExceptionTypes()); 287 } 288 289 @Override 290 void specificToStringHeader(StringBuilder sb) { 291 sb.append(getReturnType().getTypeName()).append(' '); 292 sb.append(getDeclaringClass().getTypeName()).append('.'); 293 sb.append(getName()); 294 } 295 296 /** 297 * Returns a string describing this {@code Method}, including 298 * type parameters. The string is formatted as the method access 299 * modifiers, if any, followed by an angle-bracketed 300 * comma-separated list of the method's type parameters, if any, 301 * followed by the method's generic return type, followed by a 302 * space, followed by the class declaring the method, followed by 303 * a period, followed by the method name, followed by a 304 * parenthesized, comma-separated list of the method's generic 305 * formal parameter types. 306 * 307 * If this method was declared to take a variable number of 308 * arguments, instead of denoting the last parameter as 309 * "<tt><i>Type</i>[]</tt>", it is denoted as 310 * "<tt><i>Type</i>...</tt>". 311 * 312 * A space is used to separate access modifiers from one another 313 * and from the type parameters or return type. If there are no 314 * type parameters, the type parameter list is elided; if the type 315 * parameter list is present, a space separates the list from the 316 * class name. If the method is declared to throw exceptions, the 317 * parameter list is followed by a space, followed by the word 318 * throws followed by a comma-separated list of the generic thrown 319 * exception types. 320 * 321 * <p>The access modifiers are placed in canonical order as 322 * specified by "The Java Language Specification". This is 323 * {@code public}, {@code protected} or {@code private} first, 324 * and then other modifiers in the following order: 325 * {@code abstract}, {@code default}, {@code static}, {@code final}, 326 * {@code synchronized}, {@code native}, {@code strictfp}. 327 * 328 * @return a string describing this {@code Method}, 329 * include type parameters 330 * 331 * @since 1.5 332 * 333 * @jls 8.4.3 Method Modifiers 334 */ 335 @Override 336 public String toGenericString() { 337 return sharedToGenericString(Modifier.methodModifiers(), isDefault()); 338 } 339 340 @Override 341 void specificToGenericStringHeader(StringBuilder sb) { 342 Type genRetType = getGenericReturnType(); 343 sb.append(genRetType.getTypeName()).append(' '); 344 sb.append(getDeclaringClass().getTypeName()).append('.'); 345 sb.append(getName()); 346 } 347 348 /** 349 * Invokes the underlying method represented by this {@code Method} 350 * object, on the specified object with the specified parameters. 351 * Individual parameters are automatically unwrapped to match 352 * primitive formal parameters, and both primitive and reference 353 * parameters are subject to method invocation conversions as 354 * necessary. 355 * 356 * <p>If the underlying method is static, then the specified {@code obj} 357 * argument is ignored. It may be null. 358 * 359 * <p>If the number of formal parameters required by the underlying method is 360 * 0, the supplied {@code args} array may be of length 0 or null. 361 * 362 * <p>If the underlying method is an instance method, it is invoked 363 * using dynamic method lookup as documented in The Java Language 364 * Specification, Second Edition, section 15.12.4.4; in particular, 365 * overriding based on the runtime type of the target object will occur. 366 * 367 * <p>If the underlying method is static, the class that declared 368 * the method is initialized if it has not already been initialized. 369 * 370 * <p>If the method completes normally, the value it returns is 371 * returned to the caller of invoke; if the value has a primitive 372 * type, it is first appropriately wrapped in an object. However, 373 * if the value has the type of an array of a primitive type, the 374 * elements of the array are <i>not</i> wrapped in objects; in 375 * other words, an array of primitive type is returned. If the 376 * underlying method return type is void, the invocation returns 377 * null. 378 * 379 * @param obj the object the underlying method is invoked from 380 * @param args the arguments used for the method call 381 * @return the result of dispatching the method represented by 382 * this object on {@code obj} with parameters 383 * {@code args} 384 * 385 * @exception IllegalAccessException if this {@code Method} object 386 * is enforcing Java language access control and the underlying 387 * method is inaccessible. 388 * @exception IllegalArgumentException if the method is an 389 * instance method and the specified object argument 390 * is not an instance of the class or interface 391 * declaring the underlying method (or of a subclass 392 * or implementor thereof); if the number of actual 393 * and formal parameters differ; if an unwrapping 394 * conversion for primitive arguments fails; or if, 395 * after possible unwrapping, a parameter value 396 * cannot be converted to the corresponding formal 397 * parameter type by a method invocation conversion. 398 * @exception InvocationTargetException if the underlying method 399 * throws an exception. 400 * @exception NullPointerException if the specified object is null 401 * and the method is an instance method. 402 * @exception ExceptionInInitializerError if the initialization 403 * provoked by this method fails. 404 */ 405 @FastNative 406 public native Object invoke(Object obj, Object... args) 407 throws IllegalAccessException, IllegalArgumentException, InvocationTargetException; 408 409 /** 410 * Returns {@code true} if this method is a bridge 411 * method; returns {@code false} otherwise. 412 * 413 * @return true if and only if this method is a bridge 414 * method as defined by the Java Language Specification. 415 * @since 1.5 416 */ 417 public boolean isBridge() { 418 // Android-changed: This is handled by Executable. 419 return super.isBridgeMethodInternal(); 420 } 421 422 /** 423 * {@inheritDoc} 424 * @since 1.5 425 */ 426 @Override 427 public boolean isVarArgs() { 428 return super.isVarArgs(); 429 } 430 431 /** 432 * {@inheritDoc} 433 * @jls 13.1 The Form of a Binary 434 * @since 1.5 435 */ 436 @Override 437 public boolean isSynthetic() { 438 return super.isSynthetic(); 439 } 440 441 /** 442 * Returns {@code true} if this method is a default 443 * method; returns {@code false} otherwise. 444 * 445 * A default method is a public non-abstract instance method, that 446 * is, a non-static method with a body, declared in an interface 447 * type. 448 * 449 * @return true if and only if this method is a default 450 * method as defined by the Java Language Specification. 451 * @since 1.8 452 */ 453 public boolean isDefault() { 454 // Android-changed: This is handled by Executable. 455 return super.isDefaultMethodInternal(); 456 } 457 458 /** 459 * Returns the default value for the annotation member represented by 460 * this {@code Method} instance. If the member is of a primitive type, 461 * an instance of the corresponding wrapper type is returned. Returns 462 * null if no default is associated with the member, or if the method 463 * instance does not represent a declared member of an annotation type. 464 * 465 * @return the default value for the annotation member represented 466 * by this {@code Method} instance. 467 * @throws TypeNotPresentException if the annotation is of type 468 * {@link Class} and no definition can be found for the 469 * default class value. 470 * @since 1.5 471 */ 472 @FastNative 473 public native Object getDefaultValue(); 474 475 /** 476 * {@inheritDoc} 477 * @throws NullPointerException {@inheritDoc} 478 * @since 1.5 479 */ 480 public <T extends Annotation> T getAnnotation(Class<T> annotationClass) { 481 return super.getAnnotation(annotationClass); 482 } 483 484 /** 485 * {@inheritDoc} 486 * @since 1.5 487 */ 488 public Annotation[] getDeclaredAnnotations() { 489 return super.getDeclaredAnnotations(); 490 } 491 492 /** 493 * {@inheritDoc} 494 * @since 1.5 495 */ 496 @Override 497 public Annotation[][] getParameterAnnotations() { 498 // Android-changed: This is handled by Executable. 499 return super.getParameterAnnotationsInternal(); 500 } 501 502 /** 503 * Returns true if this and {@code method} have the same name and the same 504 * parameters in the same order. Such methods can share implementation if 505 * one method's return types is assignable to the other. 506 * 507 * @hide needed by Proxy 508 */ 509 boolean equalNameAndParameters(Method m) { 510 return equalNameAndParametersInternal(m); 511 } 512} 513