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 package org.objectweb.asm; 29 30 /** 31 * A visitor to visit a Java annotation. The methods of this class must be called in the following 32 * order: ( {@code visit} | {@code visitEnum} | {@code visitAnnotation} | {@code visitArray} )* 33 * {@code visitEnd}. 34 * 35 * @author Eric Bruneton 36 * @author Eugene Kuleshov 37 */ 38 public abstract class AnnotationVisitor { 39 40 /** 41 * The ASM API version implemented by this visitor. The value of this field must be one of the 42 * {@code ASM}<i>x</i> values in {@link Opcodes}. 43 */ 44 protected final int api; 45 46 /** 47 * The annotation visitor to which this visitor must delegate method calls. May be {@literal 48 * null}. 49 */ 50 protected AnnotationVisitor av; 51 52 /** 53 * Constructs a new {@link AnnotationVisitor}. 54 * 55 * @param api the ASM API version implemented by this visitor. Must be one of the {@code 56 * ASM}<i>x</i> values in {@link Opcodes}. 57 */ AnnotationVisitor(final int api)58 protected AnnotationVisitor(final int api) { 59 this(api, null); 60 } 61 62 /** 63 * Constructs a new {@link AnnotationVisitor}. 64 * 65 * @param api the ASM API version implemented by this visitor. Must be one of the {@code 66 * ASM}<i>x</i> values in {@link Opcodes}. 67 * @param annotationVisitor the annotation visitor to which this visitor must delegate method 68 * calls. May be {@literal null}. 69 */ AnnotationVisitor(final int api, final AnnotationVisitor annotationVisitor)70 protected AnnotationVisitor(final int api, final AnnotationVisitor annotationVisitor) { 71 if (api != Opcodes.ASM9 72 && api != Opcodes.ASM8 73 && api != Opcodes.ASM7 74 && api != Opcodes.ASM6 75 && api != Opcodes.ASM5 76 && api != Opcodes.ASM4 77 && api != Opcodes.ASM10_EXPERIMENTAL) { 78 throw new IllegalArgumentException("Unsupported api " + api); 79 } 80 if (api == Opcodes.ASM10_EXPERIMENTAL) { 81 Constants.checkAsmExperimental(this); 82 } 83 this.api = api; 84 this.av = annotationVisitor; 85 } 86 87 /** 88 * The annotation visitor to which this visitor must delegate method calls. May be {@literal 89 * null}. 90 * 91 * @return the annotation visitor to which this visitor must delegate method calls, or {@literal 92 * null}. 93 */ getDelegate()94 public AnnotationVisitor getDelegate() { 95 return av; 96 } 97 98 /** 99 * Visits a primitive value of the annotation. 100 * 101 * @param name the value name. 102 * @param value the actual value, whose type must be {@link Byte}, {@link Boolean}, {@link 103 * Character}, {@link Short}, {@link Integer} , {@link Long}, {@link Float}, {@link Double}, 104 * {@link String} or {@link Type} of {@link Type#OBJECT} or {@link Type#ARRAY} sort. This 105 * value can also be an array of byte, boolean, short, char, int, long, float or double values 106 * (this is equivalent to using {@link #visitArray} and visiting each array element in turn, 107 * but is more convenient). 108 */ visit(final String name, final Object value)109 public void visit(final String name, final Object value) { 110 if (av != null) { 111 av.visit(name, value); 112 } 113 } 114 115 /** 116 * Visits an enumeration value of the annotation. 117 * 118 * @param name the value name. 119 * @param descriptor the class descriptor of the enumeration class. 120 * @param value the actual enumeration value. 121 */ visitEnum(final String name, final String descriptor, final String value)122 public void visitEnum(final String name, final String descriptor, final String value) { 123 if (av != null) { 124 av.visitEnum(name, descriptor, value); 125 } 126 } 127 128 /** 129 * Visits a nested annotation value of the annotation. 130 * 131 * @param name the value name. 132 * @param descriptor the class descriptor of the nested annotation class. 133 * @return a visitor to visit the actual nested annotation value, or {@literal null} if this 134 * visitor is not interested in visiting this nested annotation. <i>The nested annotation 135 * value must be fully visited before calling other methods on this annotation visitor</i>. 136 */ visitAnnotation(final String name, final String descriptor)137 public AnnotationVisitor visitAnnotation(final String name, final String descriptor) { 138 if (av != null) { 139 return av.visitAnnotation(name, descriptor); 140 } 141 return null; 142 } 143 144 /** 145 * Visits an array value of the annotation. Note that arrays of primitive values (such as byte, 146 * boolean, short, char, int, long, float or double) can be passed as value to {@link #visit 147 * visit}. This is what {@link ClassReader} does for non empty arrays of primitive values. 148 * 149 * @param name the value name. 150 * @return a visitor to visit the actual array value elements, or {@literal null} if this visitor 151 * is not interested in visiting these values. The 'name' parameters passed to the methods of 152 * this visitor are ignored. <i>All the array values must be visited before calling other 153 * methods on this annotation visitor</i>. 154 */ visitArray(final String name)155 public AnnotationVisitor visitArray(final String name) { 156 if (av != null) { 157 return av.visitArray(name); 158 } 159 return null; 160 } 161 162 /** Visits the end of the annotation. */ visitEnd()163 public void visitEnd() { 164 if (av != null) { 165 av.visitEnd(); 166 } 167 } 168 } 169