001// ASM: a very small and fast Java bytecode manipulation framework 002// Copyright (c) 2000-2011 INRIA, France Telecom 003// All rights reserved. 004// 005// Redistribution and use in source and binary forms, with or without 006// modification, are permitted provided that the following conditions 007// are met: 008// 1. Redistributions of source code must retain the above copyright 009// notice, this list of conditions and the following disclaimer. 010// 2. Redistributions in binary form must reproduce the above copyright 011// notice, this list of conditions and the following disclaimer in the 012// documentation and/or other materials provided with the distribution. 013// 3. Neither the name of the copyright holders nor the names of its 014// contributors may be used to endorse or promote products derived from 015// this software without specific prior written permission. 016// 017// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 018// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 019// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 020// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 021// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 022// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 023// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 024// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 025// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 026// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 027// THE POSSIBILITY OF SUCH DAMAGE. 028package org.springframework.asm; 029 030/** 031 * A visitor to visit a Java class. The methods of this class must be called in the following order: 032 * {@code visit} [ {@code visitSource} ] [ {@code visitModule} ][ {@code visitNestHost} ][ {@code 033 * visitPermittedSubtype} ][ {@code visitOuterClass} ] ( {@code visitAnnotation} | {@code 034 * visitTypeAnnotation} | {@code visitAttribute} )* ( {@code visitNestMember} | {@code 035 * visitInnerClass} | {@code visitField} | {@code visitMethod} )* {@code visitEnd}. 036 * 037 * @author Eric Bruneton 038 */ 039public abstract class ClassVisitor { 040 041 /** 042 * The ASM API version implemented by this visitor. The value of this field must be one of {@link 043 * Opcodes#ASM4}, {@link Opcodes#ASM5}, {@link Opcodes#ASM6} or {@link Opcodes#ASM7}. 044 */ 045 protected final int api; 046 047 /** The class visitor to which this visitor must delegate method calls. May be {@literal null}. */ 048 protected ClassVisitor cv; 049 050 /** 051 * Constructs a new {@link ClassVisitor}. 052 * 053 * @param api the ASM API version implemented by this visitor. Must be one of {@link 054 * Opcodes#ASM4}, {@link Opcodes#ASM5}, {@link Opcodes#ASM6} or {@link Opcodes#ASM7}. 055 */ 056 public ClassVisitor(final int api) { 057 this(api, null); 058 } 059 060 /** 061 * Constructs a new {@link ClassVisitor}. 062 * 063 * @param api the ASM API version implemented by this visitor. Must be one of {@link 064 * Opcodes#ASM4}, {@link Opcodes#ASM5}, {@link Opcodes#ASM6} or {@link Opcodes#ASM7}. 065 * @param classVisitor the class visitor to which this visitor must delegate method calls. May be 066 * null. 067 */ 068 @SuppressWarnings("deprecation") 069 public ClassVisitor(final int api, final ClassVisitor classVisitor) { 070 if (api != Opcodes.ASM7 071 && api != Opcodes.ASM6 072 && api != Opcodes.ASM5 073 && api != Opcodes.ASM4 074 && api != Opcodes.ASM8_EXPERIMENTAL) { 075 throw new IllegalArgumentException("Unsupported api " + api); 076 } 077 // SPRING PATCH: no preview mode check for ASM 8 experimental 078 this.api = api; 079 this.cv = classVisitor; 080 } 081 082 /** 083 * Visits the header of the class. 084 * 085 * @param version the class version. The minor version is stored in the 16 most significant bits, 086 * and the major version in the 16 least significant bits. 087 * @param access the class's access flags (see {@link Opcodes}). This parameter also indicates if 088 * the class is deprecated. 089 * @param name the internal name of the class (see {@link Type#getInternalName()}). 090 * @param signature the signature of this class. May be {@literal null} if the class is not a 091 * generic one, and does not extend or implement generic classes or interfaces. 092 * @param superName the internal of name of the super class (see {@link Type#getInternalName()}). 093 * For interfaces, the super class is {@link Object}. May be {@literal null}, but only for the 094 * {@link Object} class. 095 * @param interfaces the internal names of the class's interfaces (see {@link 096 * Type#getInternalName()}). May be {@literal null}. 097 */ 098 public void visit( 099 final int version, 100 final int access, 101 final String name, 102 final String signature, 103 final String superName, 104 final String[] interfaces) { 105 if (cv != null) { 106 cv.visit(version, access, name, signature, superName, interfaces); 107 } 108 } 109 110 /** 111 * Visits the source of the class. 112 * 113 * @param source the name of the source file from which the class was compiled. May be {@literal 114 * null}. 115 * @param debug additional debug information to compute the correspondence between source and 116 * compiled elements of the class. May be {@literal null}. 117 */ 118 public void visitSource(final String source, final String debug) { 119 if (cv != null) { 120 cv.visitSource(source, debug); 121 } 122 } 123 124 /** 125 * Visit the module corresponding to the class. 126 * 127 * @param name the fully qualified name (using dots) of the module. 128 * @param access the module access flags, among {@code ACC_OPEN}, {@code ACC_SYNTHETIC} and {@code 129 * ACC_MANDATED}. 130 * @param version the module version, or {@literal null}. 131 * @return a visitor to visit the module values, or {@literal null} if this visitor is not 132 * interested in visiting this module. 133 */ 134 public ModuleVisitor visitModule(final String name, final int access, final String version) { 135 if (api < Opcodes.ASM6) { 136 throw new UnsupportedOperationException("This feature requires ASM6"); 137 } 138 if (cv != null) { 139 return cv.visitModule(name, access, version); 140 } 141 return null; 142 } 143 144 /** 145 * Visits the nest host class of the class. A nest is a set of classes of the same package that 146 * share access to their private members. One of these classes, called the host, lists the other 147 * members of the nest, which in turn should link to the host of their nest. This method must be 148 * called only once and only if the visited class is a non-host member of a nest. A class is 149 * implicitly its own nest, so it's invalid to call this method with the visited class name as 150 * argument. 151 * 152 * @param nestHost the internal name of the host class of the nest. 153 */ 154 public void visitNestHost(final String nestHost) { 155 if (api < Opcodes.ASM7) { 156 throw new UnsupportedOperationException("This feature requires ASM7"); 157 } 158 if (cv != null) { 159 cv.visitNestHost(nestHost); 160 } 161 } 162 163 /** 164 * Visits the enclosing class of the class. This method must be called only if the class has an 165 * enclosing class. 166 * 167 * @param owner internal name of the enclosing class of the class. 168 * @param name the name of the method that contains the class, or {@literal null} if the class is 169 * not enclosed in a method of its enclosing class. 170 * @param descriptor the descriptor of the method that contains the class, or {@literal null} if 171 * the class is not enclosed in a method of its enclosing class. 172 */ 173 public void visitOuterClass(final String owner, final String name, final String descriptor) { 174 if (cv != null) { 175 cv.visitOuterClass(owner, name, descriptor); 176 } 177 } 178 179 /** 180 * Visits an annotation of the class. 181 * 182 * @param descriptor the class descriptor of the annotation class. 183 * @param visible {@literal true} if the annotation is visible at runtime. 184 * @return a visitor to visit the annotation values, or {@literal null} if this visitor is not 185 * interested in visiting this annotation. 186 */ 187 public AnnotationVisitor visitAnnotation(final String descriptor, final boolean visible) { 188 if (cv != null) { 189 return cv.visitAnnotation(descriptor, visible); 190 } 191 return null; 192 } 193 194 /** 195 * Visits an annotation on a type in the class signature. 196 * 197 * @param typeRef a reference to the annotated type. The sort of this type reference must be 198 * {@link TypeReference#CLASS_TYPE_PARAMETER}, {@link 199 * TypeReference#CLASS_TYPE_PARAMETER_BOUND} or {@link TypeReference#CLASS_EXTENDS}. See 200 * {@link TypeReference}. 201 * @param typePath the path to the annotated type argument, wildcard bound, array element type, or 202 * static inner type within 'typeRef'. May be {@literal null} if the annotation targets 203 * 'typeRef' as a whole. 204 * @param descriptor the class descriptor of the annotation class. 205 * @param visible {@literal true} if the annotation is visible at runtime. 206 * @return a visitor to visit the annotation values, or {@literal null} if this visitor is not 207 * interested in visiting this annotation. 208 */ 209 public AnnotationVisitor visitTypeAnnotation( 210 final int typeRef, final TypePath typePath, final String descriptor, final boolean visible) { 211 if (api < Opcodes.ASM5) { 212 throw new UnsupportedOperationException("This feature requires ASM5"); 213 } 214 if (cv != null) { 215 return cv.visitTypeAnnotation(typeRef, typePath, descriptor, visible); 216 } 217 return null; 218 } 219 220 /** 221 * Visits a non standard attribute of the class. 222 * 223 * @param attribute an attribute. 224 */ 225 public void visitAttribute(final Attribute attribute) { 226 if (cv != null) { 227 cv.visitAttribute(attribute); 228 } 229 } 230 231 /** 232 * Visits a member of the nest. A nest is a set of classes of the same package that share access 233 * to their private members. One of these classes, called the host, lists the other members of the 234 * nest, which in turn should link to the host of their nest. This method must be called only if 235 * the visited class is the host of a nest. A nest host is implicitly a member of its own nest, so 236 * it's invalid to call this method with the visited class name as argument. 237 * 238 * @param nestMember the internal name of a nest member. 239 */ 240 public void visitNestMember(final String nestMember) { 241 if (api < Opcodes.ASM7) { 242 throw new UnsupportedOperationException("This feature requires ASM7"); 243 } 244 if (cv != null) { 245 cv.visitNestMember(nestMember); 246 } 247 } 248 249 /** 250 * <b>Experimental, use at your own risk. This method will be renamed when it becomes stable, this 251 * will break existing code using it</b>. Visits a permitted subtypes. A permitted subtypes is one 252 * of the allowed subtypes of the current class. 253 * 254 * @param permittedSubtype the internal name of a permitted subtype. 255 * @deprecated this API is experimental. 256 */ 257 @Deprecated 258 public void visitPermittedSubtypeExperimental(final String permittedSubtype) { 259 if (api != Opcodes.ASM8_EXPERIMENTAL) { 260 throw new UnsupportedOperationException("This feature requires ASM8_EXPERIMENTAL"); 261 } 262 if (cv != null) { 263 cv.visitPermittedSubtypeExperimental(permittedSubtype); 264 } 265 } 266 267 /** 268 * Visits information about an inner class. This inner class is not necessarily a member of the 269 * class being visited. 270 * 271 * @param name the internal name of an inner class (see {@link Type#getInternalName()}). 272 * @param outerName the internal name of the class to which the inner class belongs (see {@link 273 * Type#getInternalName()}). May be {@literal null} for not member classes. 274 * @param innerName the (simple) name of the inner class inside its enclosing class. May be 275 * {@literal null} for anonymous inner classes. 276 * @param access the access flags of the inner class as originally declared in the enclosing 277 * class. 278 */ 279 public void visitInnerClass( 280 final String name, final String outerName, final String innerName, final int access) { 281 if (cv != null) { 282 cv.visitInnerClass(name, outerName, innerName, access); 283 } 284 } 285 286 /** 287 * Visits a record component of the class. 288 * 289 * @param access the record component access flags, the only possible value is {@link 290 * Opcodes#ACC_DEPRECATED}. 291 * @param name the record component name. 292 * @param descriptor the record component descriptor (see {@link Type}). 293 * @param signature the record component signature. May be {@literal null} if the record component 294 * type does not use generic types. 295 * @return a visitor to visit this record component annotations and attributes, or {@literal null} 296 * if this class visitor is not interested in visiting these annotations and attributes. 297 * @deprecated this API is experimental. 298 */ 299 @Deprecated 300 public RecordComponentVisitor visitRecordComponentExperimental( 301 final int access, final String name, final String descriptor, final String signature) { 302 if (api < Opcodes.ASM8_EXPERIMENTAL) { 303 throw new UnsupportedOperationException("This feature requires ASM8_EXPERIMENTAL"); 304 } 305 if (cv != null) { 306 return cv.visitRecordComponentExperimental(access, name, descriptor, signature); 307 } 308 return null; 309 } 310 311 /** 312 * Visits a field of the class. 313 * 314 * @param access the field's access flags (see {@link Opcodes}). This parameter also indicates if 315 * the field is synthetic and/or deprecated. 316 * @param name the field's name. 317 * @param descriptor the field's descriptor (see {@link Type}). 318 * @param signature the field's signature. May be {@literal null} if the field's type does not use 319 * generic types. 320 * @param value the field's initial value. This parameter, which may be {@literal null} if the 321 * field does not have an initial value, must be an {@link Integer}, a {@link Float}, a {@link 322 * Long}, a {@link Double} or a {@link String} (for {@code int}, {@code float}, {@code long} 323 * or {@code String} fields respectively). <i>This parameter is only used for static 324 * fields</i>. Its value is ignored for non static fields, which must be initialized through 325 * bytecode instructions in constructors or methods. 326 * @return a visitor to visit field annotations and attributes, or {@literal null} if this class 327 * visitor is not interested in visiting these annotations and attributes. 328 */ 329 public FieldVisitor visitField( 330 final int access, 331 final String name, 332 final String descriptor, 333 final String signature, 334 final Object value) { 335 if (cv != null) { 336 return cv.visitField(access, name, descriptor, signature, value); 337 } 338 return null; 339 } 340 341 /** 342 * Visits a method of the class. This method <i>must</i> return a new {@link MethodVisitor} 343 * instance (or {@literal null}) each time it is called, i.e., it should not return a previously 344 * returned visitor. 345 * 346 * @param access the method's access flags (see {@link Opcodes}). This parameter also indicates if 347 * the method is synthetic and/or deprecated. 348 * @param name the method's name. 349 * @param descriptor the method's descriptor (see {@link Type}). 350 * @param signature the method's signature. May be {@literal null} if the method parameters, 351 * return type and exceptions do not use generic types. 352 * @param exceptions the internal names of the method's exception classes (see {@link 353 * Type#getInternalName()}). May be {@literal null}. 354 * @return an object to visit the byte code of the method, or {@literal null} if this class 355 * visitor is not interested in visiting the code of this method. 356 */ 357 public MethodVisitor visitMethod( 358 final int access, 359 final String name, 360 final String descriptor, 361 final String signature, 362 final String[] exceptions) { 363 if (cv != null) { 364 return cv.visitMethod(access, name, descriptor, signature, exceptions); 365 } 366 return null; 367 } 368 369 /** 370 * Visits the end of the class. This method, which is the last one to be called, is used to inform 371 * the visitor that all the fields and methods of the class have been visited. 372 */ 373 public void visitEnd() { 374 if (cv != null) { 375 cv.visitEnd(); 376 } 377 } 378}