1 // ASM: a very small and fast Java bytecode manipulation framework 2 // Copyright (c) 2000-2011 INRIA, France Telecom 3 // All rights reserved. 4 // 5 // Redistribution and use in source and binary forms, with or without 6 // modification, are permitted provided that the following conditions 7 // are met: 8 // 1. Redistributions of source code must retain the above copyright 9 // notice, this list of conditions and the following disclaimer. 10 // 2. Redistributions in binary form must reproduce the above copyright 11 // notice, this list of conditions and the following disclaimer in the 12 // documentation and/or other materials provided with the distribution. 13 // 3. Neither the name of the copyright holders nor the names of its 14 // contributors may be used to endorse or promote products derived from 15 // this software without specific prior written permission. 16 // 17 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 18 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 21 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 27 // THE POSSIBILITY OF SUCH DAMAGE. 28 29 package org.objectweb.asm; 30 31 /** 32 * A reference to a type appearing in a class, field or method declaration, or on an instruction. 33 * Such a reference designates the part of the class where the referenced type is appearing (e.g. an 34 * 'extends', 'implements' or 'throws' clause, a 'new' instruction, a 'catch' clause, a type cast, a 35 * local variable declaration, etc). 36 * 37 * @author Eric Bruneton 38 */ 39 public class TypeReference { 40 41 /** 42 * The sort of type references that target a type parameter of a generic class. See {@link 43 * #getSort}. 44 */ 45 public static final int CLASS_TYPE_PARAMETER = 0x00; 46 47 /** 48 * The sort of type references that target a type parameter of a generic method. See {@link 49 * #getSort}. 50 */ 51 public static final int METHOD_TYPE_PARAMETER = 0x01; 52 53 /** 54 * The sort of type references that target the super class of a class or one of the interfaces it 55 * implements. See {@link #getSort}. 56 */ 57 public static final int CLASS_EXTENDS = 0x10; 58 59 /** 60 * The sort of type references that target a bound of a type parameter of a generic class. See 61 * {@link #getSort}. 62 */ 63 public static final int CLASS_TYPE_PARAMETER_BOUND = 0x11; 64 65 /** 66 * The sort of type references that target a bound of a type parameter of a generic method. See 67 * {@link #getSort}. 68 */ 69 public static final int METHOD_TYPE_PARAMETER_BOUND = 0x12; 70 71 /** The sort of type references that target the type of a field. See {@link #getSort}. */ 72 public static final int FIELD = 0x13; 73 74 /** The sort of type references that target the return type of a method. See {@link #getSort}. */ 75 public static final int METHOD_RETURN = 0x14; 76 77 /** 78 * The sort of type references that target the receiver type of a method. See {@link #getSort}. 79 */ 80 public static final int METHOD_RECEIVER = 0x15; 81 82 /** 83 * The sort of type references that target the type of a formal parameter of a method. See {@link 84 * #getSort}. 85 */ 86 public static final int METHOD_FORMAL_PARAMETER = 0x16; 87 88 /** 89 * The sort of type references that target the type of an exception declared in the throws clause 90 * of a method. See {@link #getSort}. 91 */ 92 public static final int THROWS = 0x17; 93 94 /** 95 * The sort of type references that target the type of a local variable in a method. See {@link 96 * #getSort}. 97 */ 98 public static final int LOCAL_VARIABLE = 0x40; 99 100 /** 101 * The sort of type references that target the type of a resource variable in a method. See {@link 102 * #getSort}. 103 */ 104 public static final int RESOURCE_VARIABLE = 0x41; 105 106 /** 107 * The sort of type references that target the type of the exception of a 'catch' clause in a 108 * method. See {@link #getSort}. 109 */ 110 public static final int EXCEPTION_PARAMETER = 0x42; 111 112 /** 113 * The sort of type references that target the type declared in an 'instanceof' instruction. See 114 * {@link #getSort}. 115 */ 116 public static final int INSTANCEOF = 0x43; 117 118 /** 119 * The sort of type references that target the type of the object created by a 'new' instruction. 120 * See {@link #getSort}. 121 */ 122 public static final int NEW = 0x44; 123 124 /** 125 * The sort of type references that target the receiver type of a constructor reference. See 126 * {@link #getSort}. 127 */ 128 public static final int CONSTRUCTOR_REFERENCE = 0x45; 129 130 /** 131 * The sort of type references that target the receiver type of a method reference. See {@link 132 * #getSort}. 133 */ 134 public static final int METHOD_REFERENCE = 0x46; 135 136 /** 137 * The sort of type references that target the type declared in an explicit or implicit cast 138 * instruction. See {@link #getSort}. 139 */ 140 public static final int CAST = 0x47; 141 142 /** 143 * The sort of type references that target a type parameter of a generic constructor in a 144 * constructor call. See {@link #getSort}. 145 */ 146 public static final int CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT = 0x48; 147 148 /** 149 * The sort of type references that target a type parameter of a generic method in a method call. 150 * See {@link #getSort}. 151 */ 152 public static final int METHOD_INVOCATION_TYPE_ARGUMENT = 0x49; 153 154 /** 155 * The sort of type references that target a type parameter of a generic constructor in a 156 * constructor reference. See {@link #getSort}. 157 */ 158 public static final int CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT = 0x4A; 159 160 /** 161 * The sort of type references that target a type parameter of a generic method in a method 162 * reference. See {@link #getSort}. 163 */ 164 public static final int METHOD_REFERENCE_TYPE_ARGUMENT = 0x4B; 165 166 /** 167 * The target_type and target_info structures - as defined in the Java Virtual Machine 168 * Specification (JVMS) - corresponding to this type reference. target_type uses one byte, and all 169 * the target_info union fields use up to 3 bytes (except localvar_target, handled with the 170 * specific method {@link MethodVisitor#visitLocalVariableAnnotation}). Thus, both structures can 171 * be stored in an int. 172 * 173 * <p>This int field stores target_type (called the TypeReference 'sort' in the public API of this 174 * class) in its most significant byte, followed by the target_info fields. Depending on 175 * target_type, 1, 2 or even 3 least significant bytes of this field are unused. target_info 176 * fields which reference bytecode offsets are set to 0 (these offsets are ignored in ClassReader, 177 * and recomputed in MethodWriter). 178 * 179 * @see <a href="https://docs.oracle.com/javase/specs/jvms/se9/html/jvms-4.html#jvms-4.7.20">JVMS 180 * 4.7.20</a> 181 * @see <a 182 * href="https://docs.oracle.com/javase/specs/jvms/se9/html/jvms-4.html#jvms-4.7.20.1">JVMS 183 * 4.7.20.1</a> 184 */ 185 private final int targetTypeAndInfo; 186 187 /** 188 * Constructs a new TypeReference. 189 * 190 * @param typeRef the int encoded value of the type reference, as received in a visit method 191 * related to type annotations, such as {@link ClassVisitor#visitTypeAnnotation}. 192 */ TypeReference(final int typeRef)193 public TypeReference(final int typeRef) { 194 this.targetTypeAndInfo = typeRef; 195 } 196 197 /** 198 * Returns a type reference of the given sort. 199 * 200 * @param sort one of {@link #FIELD}, {@link #METHOD_RETURN}, {@link #METHOD_RECEIVER}, {@link 201 * #LOCAL_VARIABLE}, {@link #RESOURCE_VARIABLE}, {@link #INSTANCEOF}, {@link #NEW}, {@link 202 * #CONSTRUCTOR_REFERENCE}, or {@link #METHOD_REFERENCE}. 203 * @return a type reference of the given sort. 204 */ newTypeReference(final int sort)205 public static TypeReference newTypeReference(final int sort) { 206 return new TypeReference(sort << 24); 207 } 208 209 /** 210 * Returns a reference to a type parameter of a generic class or method. 211 * 212 * @param sort one of {@link #CLASS_TYPE_PARAMETER} or {@link #METHOD_TYPE_PARAMETER}. 213 * @param paramIndex the type parameter index. 214 * @return a reference to the given generic class or method type parameter. 215 */ newTypeParameterReference(final int sort, final int paramIndex)216 public static TypeReference newTypeParameterReference(final int sort, final int paramIndex) { 217 return new TypeReference((sort << 24) | (paramIndex << 16)); 218 } 219 220 /** 221 * Returns a reference to a type parameter bound of a generic class or method. 222 * 223 * @param sort one of {@link #CLASS_TYPE_PARAMETER} or {@link #METHOD_TYPE_PARAMETER}. 224 * @param paramIndex the type parameter index. 225 * @param boundIndex the type bound index within the above type parameters. 226 * @return a reference to the given generic class or method type parameter bound. 227 */ newTypeParameterBoundReference( final int sort, final int paramIndex, final int boundIndex)228 public static TypeReference newTypeParameterBoundReference( 229 final int sort, final int paramIndex, final int boundIndex) { 230 return new TypeReference((sort << 24) | (paramIndex << 16) | (boundIndex << 8)); 231 } 232 233 /** 234 * Returns a reference to the super class or to an interface of the 'implements' clause of a 235 * class. 236 * 237 * @param itfIndex the index of an interface in the 'implements' clause of a class, or -1 to 238 * reference the super class of the class. 239 * @return a reference to the given super type of a class. 240 */ newSuperTypeReference(final int itfIndex)241 public static TypeReference newSuperTypeReference(final int itfIndex) { 242 return new TypeReference((CLASS_EXTENDS << 24) | ((itfIndex & 0xFFFF) << 8)); 243 } 244 245 /** 246 * Returns a reference to the type of a formal parameter of a method. 247 * 248 * @param paramIndex the formal parameter index. 249 * @return a reference to the type of the given method formal parameter. 250 */ newFormalParameterReference(final int paramIndex)251 public static TypeReference newFormalParameterReference(final int paramIndex) { 252 return new TypeReference((METHOD_FORMAL_PARAMETER << 24) | (paramIndex << 16)); 253 } 254 255 /** 256 * Returns a reference to the type of an exception, in a 'throws' clause of a method. 257 * 258 * @param exceptionIndex the index of an exception in a 'throws' clause of a method. 259 * @return a reference to the type of the given exception. 260 */ newExceptionReference(final int exceptionIndex)261 public static TypeReference newExceptionReference(final int exceptionIndex) { 262 return new TypeReference((THROWS << 24) | (exceptionIndex << 8)); 263 } 264 265 /** 266 * Returns a reference to the type of the exception declared in a 'catch' clause of a method. 267 * 268 * @param tryCatchBlockIndex the index of a try catch block (using the order in which they are 269 * visited with visitTryCatchBlock). 270 * @return a reference to the type of the given exception. 271 */ newTryCatchReference(final int tryCatchBlockIndex)272 public static TypeReference newTryCatchReference(final int tryCatchBlockIndex) { 273 return new TypeReference((EXCEPTION_PARAMETER << 24) | (tryCatchBlockIndex << 8)); 274 } 275 276 /** 277 * Returns a reference to the type of a type argument in a constructor or method call or 278 * reference. 279 * 280 * @param sort one of {@link #CAST}, {@link #CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT}, {@link 281 * #METHOD_INVOCATION_TYPE_ARGUMENT}, {@link #CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT}, or {@link 282 * #METHOD_REFERENCE_TYPE_ARGUMENT}. 283 * @param argIndex the type argument index. 284 * @return a reference to the type of the given type argument. 285 */ newTypeArgumentReference(final int sort, final int argIndex)286 public static TypeReference newTypeArgumentReference(final int sort, final int argIndex) { 287 return new TypeReference((sort << 24) | argIndex); 288 } 289 290 /** 291 * Returns the sort of this type reference. 292 * 293 * @return one of {@link #CLASS_TYPE_PARAMETER}, {@link #METHOD_TYPE_PARAMETER}, {@link 294 * #CLASS_EXTENDS}, {@link #CLASS_TYPE_PARAMETER_BOUND}, {@link #METHOD_TYPE_PARAMETER_BOUND}, 295 * {@link #FIELD}, {@link #METHOD_RETURN}, {@link #METHOD_RECEIVER}, {@link 296 * #METHOD_FORMAL_PARAMETER}, {@link #THROWS}, {@link #LOCAL_VARIABLE}, {@link 297 * #RESOURCE_VARIABLE}, {@link #EXCEPTION_PARAMETER}, {@link #INSTANCEOF}, {@link #NEW}, 298 * {@link #CONSTRUCTOR_REFERENCE}, {@link #METHOD_REFERENCE}, {@link #CAST}, {@link 299 * #CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT}, {@link #METHOD_INVOCATION_TYPE_ARGUMENT}, {@link 300 * #CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT}, or {@link #METHOD_REFERENCE_TYPE_ARGUMENT}. 301 */ getSort()302 public int getSort() { 303 return targetTypeAndInfo >>> 24; 304 } 305 306 /** 307 * Returns the index of the type parameter referenced by this type reference. This method must 308 * only be used for type references whose sort is {@link #CLASS_TYPE_PARAMETER}, {@link 309 * #METHOD_TYPE_PARAMETER}, {@link #CLASS_TYPE_PARAMETER_BOUND} or {@link 310 * #METHOD_TYPE_PARAMETER_BOUND}. 311 * 312 * @return a type parameter index. 313 */ getTypeParameterIndex()314 public int getTypeParameterIndex() { 315 return (targetTypeAndInfo & 0x00FF0000) >> 16; 316 } 317 318 /** 319 * Returns the index of the type parameter bound, within the type parameter {@link 320 * #getTypeParameterIndex}, referenced by this type reference. This method must only be used for 321 * type references whose sort is {@link #CLASS_TYPE_PARAMETER_BOUND} or {@link 322 * #METHOD_TYPE_PARAMETER_BOUND}. 323 * 324 * @return a type parameter bound index. 325 */ getTypeParameterBoundIndex()326 public int getTypeParameterBoundIndex() { 327 return (targetTypeAndInfo & 0x0000FF00) >> 8; 328 } 329 330 /** 331 * Returns the index of the "super type" of a class that is referenced by this type reference. 332 * This method must only be used for type references whose sort is {@link #CLASS_EXTENDS}. 333 * 334 * @return the index of an interface in the 'implements' clause of a class, or -1 if this type 335 * reference references the type of the super class. 336 */ getSuperTypeIndex()337 public int getSuperTypeIndex() { 338 return (short) ((targetTypeAndInfo & 0x00FFFF00) >> 8); 339 } 340 341 /** 342 * Returns the index of the formal parameter whose type is referenced by this type reference. This 343 * method must only be used for type references whose sort is {@link #METHOD_FORMAL_PARAMETER}. 344 * 345 * @return a formal parameter index. 346 */ getFormalParameterIndex()347 public int getFormalParameterIndex() { 348 return (targetTypeAndInfo & 0x00FF0000) >> 16; 349 } 350 351 /** 352 * Returns the index of the exception, in a 'throws' clause of a method, whose type is referenced 353 * by this type reference. This method must only be used for type references whose sort is {@link 354 * #THROWS}. 355 * 356 * @return the index of an exception in the 'throws' clause of a method. 357 */ getExceptionIndex()358 public int getExceptionIndex() { 359 return (targetTypeAndInfo & 0x00FFFF00) >> 8; 360 } 361 362 /** 363 * Returns the index of the try catch block (using the order in which they are visited with 364 * visitTryCatchBlock), whose 'catch' type is referenced by this type reference. This method must 365 * only be used for type references whose sort is {@link #EXCEPTION_PARAMETER} . 366 * 367 * @return the index of an exception in the 'throws' clause of a method. 368 */ getTryCatchBlockIndex()369 public int getTryCatchBlockIndex() { 370 return (targetTypeAndInfo & 0x00FFFF00) >> 8; 371 } 372 373 /** 374 * Returns the index of the type argument referenced by this type reference. This method must only 375 * be used for type references whose sort is {@link #CAST}, {@link 376 * #CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT}, {@link #METHOD_INVOCATION_TYPE_ARGUMENT}, {@link 377 * #CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT}, or {@link #METHOD_REFERENCE_TYPE_ARGUMENT}. 378 * 379 * @return a type parameter index. 380 */ getTypeArgumentIndex()381 public int getTypeArgumentIndex() { 382 return targetTypeAndInfo & 0xFF; 383 } 384 385 /** 386 * Returns the int encoded value of this type reference, suitable for use in visit methods related 387 * to type annotations, like visitTypeAnnotation. 388 * 389 * @return the int encoded value of this type reference. 390 */ getValue()391 public int getValue() { 392 return targetTypeAndInfo; 393 } 394 395 /** 396 * Puts the given target_type and target_info JVMS structures into the given ByteVector. 397 * 398 * @param targetTypeAndInfo a target_type and a target_info structures encoded as in {@link 399 * #targetTypeAndInfo}. LOCAL_VARIABLE and RESOURCE_VARIABLE target types are not supported. 400 * @param output where the type reference must be put. 401 */ putTarget(final int targetTypeAndInfo, final ByteVector output)402 static void putTarget(final int targetTypeAndInfo, final ByteVector output) { 403 switch (targetTypeAndInfo >>> 24) { 404 case CLASS_TYPE_PARAMETER: 405 case METHOD_TYPE_PARAMETER: 406 case METHOD_FORMAL_PARAMETER: 407 output.putShort(targetTypeAndInfo >>> 16); 408 break; 409 case FIELD: 410 case METHOD_RETURN: 411 case METHOD_RECEIVER: 412 output.putByte(targetTypeAndInfo >>> 24); 413 break; 414 case CAST: 415 case CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT: 416 case METHOD_INVOCATION_TYPE_ARGUMENT: 417 case CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT: 418 case METHOD_REFERENCE_TYPE_ARGUMENT: 419 output.putInt(targetTypeAndInfo); 420 break; 421 case CLASS_EXTENDS: 422 case CLASS_TYPE_PARAMETER_BOUND: 423 case METHOD_TYPE_PARAMETER_BOUND: 424 case THROWS: 425 case EXCEPTION_PARAMETER: 426 case INSTANCEOF: 427 case NEW: 428 case CONSTRUCTOR_REFERENCE: 429 case METHOD_REFERENCE: 430 output.put12(targetTypeAndInfo >>> 24, (targetTypeAndInfo & 0xFFFF00) >> 8); 431 break; 432 default: 433 throw new IllegalArgumentException(); 434 } 435 } 436 } 437