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 annotation. The methods of this class must be called in the following 032 * order: ( {@code visit} | {@code visitEnum} | {@code visitAnnotation} | {@code visitArray} )* 033 * {@code visitEnd}. 034 * 035 * @author Eric Bruneton 036 * @author Eugene Kuleshov 037 */ 038public abstract class AnnotationVisitor { 039 040 /** 041 * The ASM API version implemented by this visitor. The value of this field must be one of {@link 042 * Opcodes#ASM4}, {@link Opcodes#ASM5}, {@link Opcodes#ASM6} or {@link Opcodes#ASM7}. 043 */ 044 protected final int api; 045 046 /** 047 * The annotation visitor to which this visitor must delegate method calls. May be {@literal 048 * null}. 049 */ 050 protected AnnotationVisitor av; 051 052 /** 053 * Constructs a new {@link AnnotationVisitor}. 054 * 055 * @param api the ASM API version implemented by this visitor. Must be one of {@link 056 * Opcodes#ASM4}, {@link Opcodes#ASM5}, {@link Opcodes#ASM6} or {@link Opcodes#ASM7}. 057 */ 058 public AnnotationVisitor(final int api) { 059 this(api, null); 060 } 061 062 /** 063 * Constructs a new {@link AnnotationVisitor}. 064 * 065 * @param api the ASM API version implemented by this visitor. Must be one of {@link 066 * Opcodes#ASM4}, {@link Opcodes#ASM5}, {@link Opcodes#ASM6} or {@link Opcodes#ASM7}. 067 * @param annotationVisitor the annotation visitor to which this visitor must delegate method 068 * calls. May be {@literal null}. 069 */ 070 @SuppressWarnings("deprecation") 071 public AnnotationVisitor(final int api, final AnnotationVisitor annotationVisitor) { 072 if (api != Opcodes.ASM7 073 && api != Opcodes.ASM6 074 && api != Opcodes.ASM5 075 && api != Opcodes.ASM4 076 && api != Opcodes.ASM8_EXPERIMENTAL) { 077 throw new IllegalArgumentException("Unsupported api " + api); 078 } 079 // SPRING PATCH: no preview mode check for ASM 8 experimental 080 this.api = api; 081 this.av = annotationVisitor; 082 } 083 084 /** 085 * Visits a primitive value of the annotation. 086 * 087 * @param name the value name. 088 * @param value the actual value, whose type must be {@link Byte}, {@link Boolean}, {@link 089 * Character}, {@link Short}, {@link Integer} , {@link Long}, {@link Float}, {@link Double}, 090 * {@link String} or {@link Type} of {@link Type#OBJECT} or {@link Type#ARRAY} sort. This 091 * value can also be an array of byte, boolean, short, char, int, long, float or double values 092 * (this is equivalent to using {@link #visitArray} and visiting each array element in turn, 093 * but is more convenient). 094 */ 095 public void visit(final String name, final Object value) { 096 if (av != null) { 097 av.visit(name, value); 098 } 099 } 100 101 /** 102 * Visits an enumeration value of the annotation. 103 * 104 * @param name the value name. 105 * @param descriptor the class descriptor of the enumeration class. 106 * @param value the actual enumeration value. 107 */ 108 public void visitEnum(final String name, final String descriptor, final String value) { 109 if (av != null) { 110 av.visitEnum(name, descriptor, value); 111 } 112 } 113 114 /** 115 * Visits a nested annotation value of the annotation. 116 * 117 * @param name the value name. 118 * @param descriptor the class descriptor of the nested annotation class. 119 * @return a visitor to visit the actual nested annotation value, or {@literal null} if this 120 * visitor is not interested in visiting this nested annotation. <i>The nested annotation 121 * value must be fully visited before calling other methods on this annotation visitor</i>. 122 */ 123 public AnnotationVisitor visitAnnotation(final String name, final String descriptor) { 124 if (av != null) { 125 return av.visitAnnotation(name, descriptor); 126 } 127 return null; 128 } 129 130 /** 131 * Visits an array value of the annotation. Note that arrays of primitive types (such as byte, 132 * boolean, short, char, int, long, float or double) can be passed as value to {@link #visit 133 * visit}. This is what {@link ClassReader} does. 134 * 135 * @param name the value name. 136 * @return a visitor to visit the actual array value elements, or {@literal null} if this visitor 137 * is not interested in visiting these values. The 'name' parameters passed to the methods of 138 * this visitor are ignored. <i>All the array values must be visited before calling other 139 * methods on this annotation visitor</i>. 140 */ 141 public AnnotationVisitor visitArray(final String name) { 142 if (av != null) { 143 return av.visitArray(name); 144 } 145 return null; 146 } 147 148 /** Visits the end of the annotation. */ 149 public void visitEnd() { 150 if (av != null) { 151 av.visitEnd(); 152 } 153 } 154}