View Javadoc
1   /*
2    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3    *
4    * This code is free software; you can redistribute it and/or modify it
5    * under the terms of the GNU General Public License version 2 only, as
6    * published by the Free Software Foundation.  Oracle designates this
7    * particular file as subject to the "Classpath" exception as provided
8    * by Oracle in the LICENSE file that accompanied this code.
9    *
10   * This code is distributed in the hope that it will be useful, but WITHOUT
11   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
13   * version 2 for more details (a copy is included in the LICENSE file that
14   * accompanied this code).
15   *
16   * You should have received a copy of the GNU General Public License version
17   * 2 along with this work; if not, write to the Free Software Foundation,
18   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19   *
20   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21   * or visit www.oracle.com if you need additional information or have any
22   * questions.
23   */
24  
25  /*
26   * This file is available under and governed by the GNU General Public
27   * License version 2 only, as published by the Free Software Foundation.
28   * However, the following notice accompanied the original version of this
29   * file:
30   *
31   * ASM: a very small and fast Java bytecode manipulation framework
32   * Copyright (c) 2000-2011 INRIA, France Telecom
33   * All rights reserved.
34   *
35   * Redistribution and use in source and binary forms, with or without
36   * modification, are permitted provided that the following conditions
37   * are met:
38   * 1. Redistributions of source code must retain the above copyright
39   *    notice, this list of conditions and the following disclaimer.
40   * 2. Redistributions in binary form must reproduce the above copyright
41   *    notice, this list of conditions and the following disclaimer in the
42   *    documentation and/or other materials provided with the distribution.
43   * 3. Neither the name of the copyright holders nor the names of its
44   *    contributors may be used to endorse or promote products derived from
45   *    this software without specific prior written permission.
46   *
47   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
48   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
49   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
50   * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
51   * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
52   * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
53   * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
54   * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
55   * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
56   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
57   * THE POSSIBILITY OF SUCH DAMAGE.
58   */
59  package jdk.internal.org.objectweb.asm;
60  
61  /**
62   * A visitor to visit a Java class. The methods of this class must be called in
63   * the following order: <tt>visit</tt> [ <tt>visitSource</tt> ] [
64   * <tt>visitOuterClass</tt> ] ( <tt>visitAnnotation</tt> |
65   * <tt>visitTypeAnnotation</tt> | <tt>visitAttribute</tt> )* (
66   * <tt>visitInnerClass</tt> | <tt>visitField</tt> | <tt>visitMethod</tt> )*
67   * <tt>visitEnd</tt>.
68   *
69   * @author Eric Bruneton
70   */
71  public abstract class ClassVisitor {
72  
73      /**
74       * The ASM API version implemented by this visitor. The value of this field
75       * must be one of {@link Opcodes#ASM4} or {@link Opcodes#ASM5}.
76       */
77      protected final int api;
78  
79      /**
80       * The class visitor to which this visitor must delegate method calls. May
81       * be null.
82       */
83      protected ClassVisitor cv;
84  
85      /**
86       * Constructs a new {@link ClassVisitor}.
87       *
88       * @param api
89       *            the ASM API version implemented by this visitor. Must be one
90       *            of {@link Opcodes#ASM4} or {@link Opcodes#ASM5}.
91       */
92      public ClassVisitor(final int api) {
93          this(api, null);
94      }
95  
96      /**
97       * Constructs a new {@link ClassVisitor}.
98       *
99       * @param api
100      *            the ASM API version implemented by this visitor. Must be one
101      *            of {@link Opcodes#ASM4} or {@link Opcodes#ASM5}.
102      * @param cv
103      *            the class visitor to which this visitor must delegate method
104      *            calls. May be null.
105      */
106     public ClassVisitor(final int api, final ClassVisitor cv) {
107         if (api != Opcodes.ASM4 && api != Opcodes.ASM5) {
108             throw new IllegalArgumentException();
109         }
110         this.api = api;
111         this.cv = cv;
112     }
113 
114     /**
115      * Visits the header of the class.
116      *
117      * @param version
118      *            the class version.
119      * @param access
120      *            the class's access flags (see {@link Opcodes}). This parameter
121      *            also indicates if the class is deprecated.
122      * @param name
123      *            the internal name of the class (see
124      *            {@link Type#getInternalName() getInternalName}).
125      * @param signature
126      *            the signature of this class. May be <tt>null</tt> if the class
127      *            is not a generic one, and does not extend or implement generic
128      *            classes or interfaces.
129      * @param superName
130      *            the internal of name of the super class (see
131      *            {@link Type#getInternalName() getInternalName}). For
132      *            interfaces, the super class is {@link Object}. May be
133      *            <tt>null</tt>, but only for the {@link Object} class.
134      * @param interfaces
135      *            the internal names of the class's interfaces (see
136      *            {@link Type#getInternalName() getInternalName}). May be
137      *            <tt>null</tt>.
138      */
139     public void visit(int version, int access, String name, String signature,
140             String superName, String[] interfaces) {
141         if (cv != null) {
142             cv.visit(version, access, name, signature, superName, interfaces);
143         }
144     }
145 
146     /**
147      * Visits the source of the class.
148      *
149      * @param source
150      *            the name of the source file from which the class was compiled.
151      *            May be <tt>null</tt>.
152      * @param debug
153      *            additional debug information to compute the correspondance
154      *            between source and compiled elements of the class. May be
155      *            <tt>null</tt>.
156      */
157     public void visitSource(String source, String debug) {
158         if (cv != null) {
159             cv.visitSource(source, debug);
160         }
161     }
162 
163     /**
164      * Visits the enclosing class of the class. This method must be called only
165      * if the class has an enclosing class.
166      *
167      * @param owner
168      *            internal name of the enclosing class of the class.
169      * @param name
170      *            the name of the method that contains the class, or
171      *            <tt>null</tt> if the class is not enclosed in a method of its
172      *            enclosing class.
173      * @param desc
174      *            the descriptor of the method that contains the class, or
175      *            <tt>null</tt> if the class is not enclosed in a method of its
176      *            enclosing class.
177      */
178     public void visitOuterClass(String owner, String name, String desc) {
179         if (cv != null) {
180             cv.visitOuterClass(owner, name, desc);
181         }
182     }
183 
184     /**
185      * Visits an annotation of the class.
186      *
187      * @param desc
188      *            the class descriptor of the annotation class.
189      * @param visible
190      *            <tt>true</tt> if the annotation is visible at runtime.
191      * @return a visitor to visit the annotation values, or <tt>null</tt> if
192      *         this visitor is not interested in visiting this annotation.
193      */
194     public AnnotationVisitor visitAnnotation(String desc, boolean visible) {
195         if (cv != null) {
196             return cv.visitAnnotation(desc, visible);
197         }
198         return null;
199     }
200 
201     /**
202      * Visits an annotation on a type in the class signature.
203      *
204      * @param typeRef
205      *            a reference to the annotated type. The sort of this type
206      *            reference must be {@link TypeReference#CLASS_TYPE_PARAMETER
207      *            CLASS_TYPE_PARAMETER},
208      *            {@link TypeReference#CLASS_TYPE_PARAMETER_BOUND
209      *            CLASS_TYPE_PARAMETER_BOUND} or
210      *            {@link TypeReference#CLASS_EXTENDS CLASS_EXTENDS}. See
211      *            {@link TypeReference}.
212      * @param typePath
213      *            the path to the annotated type argument, wildcard bound, array
214      *            element type, or static inner type within 'typeRef'. May be
215      *            <tt>null</tt> if the annotation targets 'typeRef' as a whole.
216      * @param desc
217      *            the class descriptor of the annotation class.
218      * @param visible
219      *            <tt>true</tt> if the annotation is visible at runtime.
220      * @return a visitor to visit the annotation values, or <tt>null</tt> if
221      *         this visitor is not interested in visiting this annotation.
222      */
223     public AnnotationVisitor visitTypeAnnotation(int typeRef,
224             TypePath typePath, String desc, boolean visible) {
225         if (api < Opcodes.ASM5) {
226             throw new RuntimeException();
227         }
228         if (cv != null) {
229             return cv.visitTypeAnnotation(typeRef, typePath, desc, visible);
230         }
231         return null;
232     }
233 
234     /**
235      * Visits a non standard attribute of the class.
236      *
237      * @param attr
238      *            an attribute.
239      */
240     public void visitAttribute(Attribute attr) {
241         if (cv != null) {
242             cv.visitAttribute(attr);
243         }
244     }
245 
246     /**
247      * Visits information about an inner class. This inner class is not
248      * necessarily a member of the class being visited.
249      *
250      * @param name
251      *            the internal name of an inner class (see
252      *            {@link Type#getInternalName() getInternalName}).
253      * @param outerName
254      *            the internal name of the class to which the inner class
255      *            belongs (see {@link Type#getInternalName() getInternalName}).
256      *            May be <tt>null</tt> for not member classes.
257      * @param innerName
258      *            the (simple) name of the inner class inside its enclosing
259      *            class. May be <tt>null</tt> for anonymous inner classes.
260      * @param access
261      *            the access flags of the inner class as originally declared in
262      *            the enclosing class.
263      */
264     public void visitInnerClass(String name, String outerName,
265             String innerName, int access) {
266         if (cv != null) {
267             cv.visitInnerClass(name, outerName, innerName, access);
268         }
269     }
270 
271     /**
272      * Visits a field of the class.
273      *
274      * @param access
275      *            the field's access flags (see {@link Opcodes}). This parameter
276      *            also indicates if the field is synthetic and/or deprecated.
277      * @param name
278      *            the field's name.
279      * @param desc
280      *            the field's descriptor (see {@link Type Type}).
281      * @param signature
282      *            the field's signature. May be <tt>null</tt> if the field's
283      *            type does not use generic types.
284      * @param value
285      *            the field's initial value. This parameter, which may be
286      *            <tt>null</tt> if the field does not have an initial value,
287      *            must be an {@link Integer}, a {@link Float}, a {@link Long}, a
288      *            {@link Double} or a {@link String} (for <tt>int</tt>,
289      *            <tt>float</tt>, <tt>long</tt> or <tt>String</tt> fields
290      *            respectively). <i>This parameter is only used for static
291      *            fields</i>. Its value is ignored for non static fields, which
292      *            must be initialized through bytecode instructions in
293      *            constructors or methods.
294      * @return a visitor to visit field annotations and attributes, or
295      *         <tt>null</tt> if this class visitor is not interested in visiting
296      *         these annotations and attributes.
297      */
298     public FieldVisitor visitField(int access, String name, String desc,
299             String signature, Object value) {
300         if (cv != null) {
301             return cv.visitField(access, name, desc, signature, value);
302         }
303         return null;
304     }
305 
306     /**
307      * Visits a method of the class. This method <i>must</i> return a new
308      * {@link MethodVisitor} instance (or <tt>null</tt>) each time it is called,
309      * i.e., it should not return a previously returned visitor.
310      *
311      * @param access
312      *            the method's access flags (see {@link Opcodes}). This
313      *            parameter also indicates if the method is synthetic and/or
314      *            deprecated.
315      * @param name
316      *            the method's name.
317      * @param desc
318      *            the method's descriptor (see {@link Type Type}).
319      * @param signature
320      *            the method's signature. May be <tt>null</tt> if the method
321      *            parameters, return type and exceptions do not use generic
322      *            types.
323      * @param exceptions
324      *            the internal names of the method's exception classes (see
325      *            {@link Type#getInternalName() getInternalName}). May be
326      *            <tt>null</tt>.
327      * @return an object to visit the byte code of the method, or <tt>null</tt>
328      *         if this class visitor is not interested in visiting the code of
329      *         this method.
330      */
331     public MethodVisitor visitMethod(int access, String name, String desc,
332             String signature, String[] exceptions) {
333         if (cv != null) {
334             return cv.visitMethod(access, name, desc, signature, exceptions);
335         }
336         return null;
337     }
338 
339     /**
340      * Visits the end of the class. This method, which is the last one to be
341      * called, is used to inform the visitor that all the fields and methods of
342      * the class have been visited.
343      */
344     public void visitEnd() {
345         if (cv != null) {
346             cv.visitEnd();
347         }
348     }
349 }