View Javadoc
1   /*
2    * Copyright (c) 2005, 2009, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  /*
27   * This file is available under and governed by the GNU General Public
28   * License version 2 only, as published by the Free Software Foundation.
29   * However, the following notice accompanied the original version of this
30   * file:
31   *
32   * ASM: a very small and fast Java bytecode manipulation framework
33   * Copyright (c) 2000-2007 INRIA, France Telecom
34   * All rights reserved.
35   *
36   * Redistribution and use in source and binary forms, with or without
37   * modification, are permitted provided that the following conditions
38   * are met:
39   * 1. Redistributions of source code must retain the above copyright
40   *    notice, this list of conditions and the following disclaimer.
41   * 2. Redistributions in binary form must reproduce the above copyright
42   *    notice, this list of conditions and the following disclaimer in the
43   *    documentation and/or other materials provided with the distribution.
44   * 3. Neither the name of the copyright holders nor the names of its
45   *    contributors may be used to endorse or promote products derived from
46   *    this software without specific prior written permission.
47   *
48   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
49   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
50   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
51   * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
52   * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
53   * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
54   * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
55   * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
56   * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
57   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
58   * THE POSSIBILITY OF SUCH DAMAGE.
59   */
60  package com.sun.xml.internal.ws.org.objectweb.asm;
61  
62  /**
63   * A visitor to visit a Java class. The methods of this interface must be called
64   * in the following order: <tt>visit</tt> [ <tt>visitSource</tt> ] [
65   * <tt>visitOuterClass</tt> ] ( <tt>visitAnnotation</tt> |
66   * <tt>visitAttribute</tt> )* (<tt>visitInnerClass</tt> |
67   * <tt>visitField</tt> | <tt>visitMethod</tt> )* <tt>visitEnd</tt>.
68   *
69   * @author Eric Bruneton
70   */
71  public interface ClassVisitor {
72  
73      /**
74       * Visits the header of the class.
75       *
76       * @param version the class version.
77       * @param access the class's access flags (see {@link Opcodes}). This
78       *        parameter also indicates if the class is deprecated.
79       * @param name the internal name of the class (see
80       *        {@link Type#getInternalName() getInternalName}).
81       * @param signature the signature of this class. May be <tt>null</tt> if
82       *        the class is not a generic one, and does not extend or implement
83       *        generic classes or interfaces.
84       * @param superName the internal of name of the super class (see
85       *        {@link Type#getInternalName() getInternalName}). For interfaces,
86       *        the super class is {@link Object}. May be <tt>null</tt>, but
87       *        only for the {@link Object} class.
88       * @param interfaces the internal names of the class's interfaces (see
89       *        {@link Type#getInternalName() getInternalName}). May be
90       *        <tt>null</tt>.
91       */
92      void visit(
93          int version,
94          int access,
95          String name,
96          String signature,
97          String superName,
98          String[] interfaces);
99  
100     /**
101      * Visits the source of the class.
102      *
103      * @param source the name of the source file from which the class was
104      *        compiled. May be <tt>null</tt>.
105      * @param debug additional debug information to compute the correspondance
106      *        between source and compiled elements of the class. May be
107      *        <tt>null</tt>.
108      */
109     void visitSource(String source, String debug);
110 
111     /**
112      * Visits the enclosing class of the class. This method must be called only
113      * if the class has an enclosing class.
114      *
115      * @param owner internal name of the enclosing class of the class.
116      * @param name the name of the method that contains the class, or
117      *        <tt>null</tt> if the class is not enclosed in a method of its
118      *        enclosing class.
119      * @param desc the descriptor of the method that contains the class, or
120      *        <tt>null</tt> if the class is not enclosed in a method of its
121      *        enclosing class.
122      */
123     void visitOuterClass(String owner, String name, String desc);
124 
125     /**
126      * Visits an annotation of the class.
127      *
128      * @param desc the class descriptor of the annotation class.
129      * @param visible <tt>true</tt> if the annotation is visible at runtime.
130      * @return a visitor to visit the annotation values, or <tt>null</tt> if
131      *         this visitor is not interested in visiting this annotation.
132      */
133     AnnotationVisitor visitAnnotation(String desc, boolean visible);
134 
135     /**
136      * Visits a non standard attribute of the class.
137      *
138      * @param attr an attribute.
139      */
140     void visitAttribute(Attribute attr);
141 
142     /**
143      * Visits information about an inner class. This inner class is not
144      * necessarily a member of the class being visited.
145      *
146      * @param name the internal name of an inner class (see
147      *        {@link Type#getInternalName() getInternalName}).
148      * @param outerName the internal name of the class to which the inner class
149      *        belongs (see {@link Type#getInternalName() getInternalName}). May
150      *        be <tt>null</tt> for not member classes.
151      * @param innerName the (simple) name of the inner class inside its
152      *        enclosing class. May be <tt>null</tt> for anonymous inner
153      *        classes.
154      * @param access the access flags of the inner class as originally declared
155      *        in the enclosing class.
156      */
157     void visitInnerClass(
158         String name,
159         String outerName,
160         String innerName,
161         int access);
162 
163     /**
164      * Visits a field of the class.
165      *
166      * @param access the field's access flags (see {@link Opcodes}). This
167      *        parameter also indicates if the field is synthetic and/or
168      *        deprecated.
169      * @param name the field's name.
170      * @param desc the field's descriptor (see {@link Type Type}).
171      * @param signature the field's signature. May be <tt>null</tt> if the
172      *        field's type does not use generic types.
173      * @param value the field's initial value. This parameter, which may be
174      *        <tt>null</tt> if the field does not have an initial value, must
175      *        be an {@link Integer}, a {@link Float}, a {@link Long}, a
176      *        {@link Double} or a {@link String} (for <tt>int</tt>,
177      *        <tt>float</tt>, <tt>long</tt> or <tt>String</tt> fields
178      *        respectively). <i>This parameter is only used for static fields</i>.
179      *        Its value is ignored for non static fields, which must be
180      *        initialized through bytecode instructions in constructors or
181      *        methods.
182      * @return a visitor to visit field annotations and attributes, or
183      *         <tt>null</tt> if this class visitor is not interested in
184      *         visiting these annotations and attributes.
185      */
186     FieldVisitor visitField(
187         int access,
188         String name,
189         String desc,
190         String signature,
191         Object value);
192 
193     /**
194      * Visits a method of the class. This method <i>must</i> return a new
195      * {@link MethodVisitor} instance (or <tt>null</tt>) each time it is
196      * called, i.e., it should not return a previously returned visitor.
197      *
198      * @param access the method's access flags (see {@link Opcodes}). This
199      *        parameter also indicates if the method is synthetic and/or
200      *        deprecated.
201      * @param name the method's name.
202      * @param desc the method's descriptor (see {@link Type Type}).
203      * @param signature the method's signature. May be <tt>null</tt> if the
204      *        method parameters, return type and exceptions do not use generic
205      *        types.
206      * @param exceptions the internal names of the method's exception classes
207      *        (see {@link Type#getInternalName() getInternalName}). May be
208      *        <tt>null</tt>.
209      * @return an object to visit the byte code of the method, or <tt>null</tt>
210      *         if this class visitor is not interested in visiting the code of
211      *         this method.
212      */
213     MethodVisitor visitMethod(
214         int access,
215         String name,
216         String desc,
217         String signature,
218         String[] exceptions);
219 
220     /**
221      * Visits the end of the class. This method, which is the last one to be
222      * called, is used to inform the visitor that all the fields and methods of
223      * the class have been visited.
224      */
225     void visitEnd();
226 }