org.objectweb.asm.attrs
Class Annotation

java.lang.Object
  extended by org.objectweb.asm.attrs.Annotation

public class Annotation
extends Object

Annotation data contains an annotated type and its array of the element-value pairs. Structure is in the following format:

   annotation {
     u2 type_index;
     u2 num_element_value_pairs;
     {
       u2 element_name_index;
       element_value value;
     } element_value_pairs[num_element_value_pairs];
   }
 
The items of the annotation structure are as follows:
type_index
The value of the type_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure representing a field descriptor representing the annotation interface corresponding to the annotation represented by this annotation structure.
num_element_value_pairs
The value of the num_element_value_pairs item gives the number of element-value pairs in the annotation represented by this annotation structure. Note that a maximum of 65535 element-value pairs may be contained in a single annotation.
element_value_pairs
Each value of the element_value_pairs table represents a single element-value pair in the annotation represented by this annotation structure. Each element_value_pairs entry contains the following two items:
element_name_index
The value of the element_name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure representing the name of the annotation type element corresponding to this element_value_pairs entry.
value
The value item represents the value in the element-value pair represented by this element_value_pairs entry.
The element_value structure is a discriminated union representing the value of a element-value pair. It is used to represent values in all class file attributes that describe annotations ( RuntimeVisibleAnnotations, RuntimeInvisibleAnnotations, RuntimeVisibleParameterAnnotations, and RuntimeInvisibleParameterAnnotations).

The element_value structure has the following format:

   element_value {
     u1 tag;
     union {
       u2   const_value_index;
       {
         u2   type_name_index;
         u2   const_name_index;
       } enum_const_value;
       u2   class_info_index;
       annotation annotation_value;
       {
         u2    num_values;
         element_value values[num_values];
       } array_value;
     } value;
   }
 
The items of the element_value structure are as follows:
tag
The tag item indicates the type of this annotation element-value pair. The letters 'B', 'C', 'D', 'F', 'I', 'J', 'S', and 'Z' indicate a primitive type. These letters are interpreted as BaseType characters (Table 4.2). The other legal values for tag are listed with their interpretations in this table:
     tag  value Element Type
     's'  String
     'e'  enum constant
     'c'  class
     '@'  annotation type
     '['  array
   
value
The value item represents the value of this annotation element. This item is a union. The tag item, above, determines which item of the union is to be used:
const_value_index
The const_value_index item is used if the tag item is one of 'B', 'C', 'D', 'F', 'I', 'J', 'S', 'Z', or 's'. The value of the const_value_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be of the correct entry type for the field type designated by the tag item, as specified in table 4.6, with one exception: if the tag is 's', the the value of the const_value_index item must be the index of a CONSTANT_Utf8 structure, rather than a CONSTANT_String.
enum_const_value
The enum_const_value item is used if the tag item is 'e'. The enum_const_value item consists of the following two items:
type_name_index
The value of the type_name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure representing the binary name (JLS 13.1) of the type of the enum constant represented by this element_value structure.
const_name_index
The value of the const_name_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure representing the simple name of the enum constant represented by this element_value structure.
class_info_index
The class_info_index item is used if the tag item is 'c'. The class_info_index item must be a valid index into the constant_pool table. The constant_pool entry at that index must be a CONSTANT_Utf8_info structure representing the return descriptor of the type that is reified by the class represented by this element_value structure.
annotation_value
The annotation_value item is used if the tag item is '@'. The element_value structure represents a "nested" annotation.
array_value
The array_value item is used if the tag item is '['. The array_value item consists of the following two items:
num_values
The value of the num_values item gives the number of elements in the array-typed value represented by this element_value structure. Note that a maximum of 65535 elements are permitted in an array-typed element value.
values
Each element of the values table gives the value of an element of the array-typed value represented by this element_value structure.

Author:
Eugene Kuleshov
See Also:
JSR 175 : A Metadata Facility for the Java Programming Language

Nested Class Summary
static class Annotation.EnumConstValue
          Container class used to store enum_const_value structure.
 
Field Summary
 List elementValues
          List of Object[]{name, value} pairs.
 String type
          A fully qualified class name in internal form (see Type).
 
Constructor Summary
Annotation()
           
Annotation(String type)
           
 
Method Summary
 void add(String name, Object value)
           
 int read(ClassReader cr, int off, char[] buf)
          Reads annotation data structures.
static int readAnnotations(List annotations, ClassReader cr, int off, char[] buf)
          Utility method to read List of annotations.
static void readParameterAnnotations(List parameters, ClassReader cr, int off, char[] buf)
          Utility method to read List of parameters annotations.
protected static Object readValue(ClassReader cr, int[] off, char[] buf)
          Reads element_value data structures.
static String stringAnnotations(List annotations)
          Returns annotation values in the format described in JSR-175 for Java source code.
static String stringParameterAnnotations(List parameters)
          Returns parameter annotation values in the format described in JSR-175 for Java source code.
 String toString()
          Returns value in the format described in JSR-175 for Java source code.
 void write(ByteVector bv, ClassWriter cw)
          Writes annotation data structures.
static ByteVector writeAnnotations(ByteVector bv, List annotations, ClassWriter cw)
          Utility method to write List of annotations.
static ByteVector writeParametersAnnotations(ByteVector bv, List parameters, ClassWriter cw)
          Utility method to write List of parameters annotations.
protected static ByteVector writeValue(ByteVector bv, Object value, ClassWriter cw)
          Writes element_value data structures.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

type

public String type
A fully qualified class name in internal form (see Type).


elementValues

public List elementValues
List of Object[]{name, value} pairs. Where name is String and value is one of Byte, Character, Double, Float, Integer, Long, Short, Boolean, String, Annotation.EnumConstValue, Type, Annotation or Object[].

Constructor Detail

Annotation

public Annotation()

Annotation

public Annotation(String type)
Method Detail

add

public void add(String name,
                Object value)

read

public int read(ClassReader cr,
                int off,
                char[] buf)
Reads annotation data structures.

Parameters:
cr - the class that contains the attribute to be read.
off - index of the first byte of the data structure.
buf - buffer to be used to call readUTF8, readClass or readConst.
Returns:
offset position in bytecode after reading annotation

write

public void write(ByteVector bv,
                  ClassWriter cw)
Writes annotation data structures.

Parameters:
bv - the byte array form to store data structures.
cw - the class to which this attribute must be added. This parameter can be used to add to the constant pool of this class the items that corresponds to this attribute.

readAnnotations

public static int readAnnotations(List annotations,
                                  ClassReader cr,
                                  int off,
                                  char[] buf)
Utility method to read List of annotations. Each element of annotations List will have Annotation instance.

Parameters:
annotations - the List to store parameters annotations.
cr - the class that contains the attribute to be read.
off - index of the first byte of the data structure.
buf - buffer to be used to call readUTF8, readClass or readConst.
Returns:
offset position in bytecode after reading annotations

readParameterAnnotations

public static void readParameterAnnotations(List parameters,
                                            ClassReader cr,
                                            int off,
                                            char[] buf)
Utility method to read List of parameters annotations.

Parameters:
parameters - the List to store parameters annotations. Each element of the parameters List will have List of Annotation instances.
cr - the class that contains the attribute to be read.
off - index of the first byte of the data structure.
buf - buffer to be used to call readUTF8, readClass or readConst.

writeAnnotations

public static ByteVector writeAnnotations(ByteVector bv,
                                          List annotations,
                                          ClassWriter cw)
Utility method to write List of annotations.

Parameters:
bv - the byte array form to store data structures.
annotations - the List of annotations to write. Elements should be instances of the Annotation class.
cw - the class to which this attribute must be added. This parameter can be used to add to the constant pool of this class the items that corresponds to this attribute.
Returns:
the byte array form with saved annotations.

writeParametersAnnotations

public static ByteVector writeParametersAnnotations(ByteVector bv,
                                                    List parameters,
                                                    ClassWriter cw)
Utility method to write List of parameters annotations.

Parameters:
bv - the byte array form to store data structures.
parameters - the List of parametars to write. Elements should be instances of the List that contains instances of the Annotation class.
cw - the class to which this attribute must be added. This parameter can be used to add to the constant pool of this class the items that corresponds to this attribute.
Returns:
the byte array form with saved annotations.

stringAnnotations

public static String stringAnnotations(List annotations)
Returns annotation values in the format described in JSR-175 for Java source code.

Parameters:
annotations - a list of annotations.
Returns:
annotation values in the format described in JSR-175 for Java source code.

stringParameterAnnotations

public static String stringParameterAnnotations(List parameters)
Returns parameter annotation values in the format described in JSR-175 for Java source code.

Parameters:
parameters - a list of parameter annotations.
Returns:
parameter annotation values in the format described in JSR-175 for Java source code.

readValue

protected static Object readValue(ClassReader cr,
                                  int[] off,
                                  char[] buf)
Reads element_value data structures.

Parameters:
cr - the class that contains the attribute to be read.
off - index of the first byte of the data structure.
buf - buffer to be used to call readUTF8, readClass or readConst.
Returns:
offset position in bytecode after reading annotation

writeValue

protected static ByteVector writeValue(ByteVector bv,
                                       Object value,
                                       ClassWriter cw)
Writes element_value data structures.

Parameters:
bv - the byte array form to store data structures.
value -
cw - the class to which this attribute must be added. This parameter can be used to add to the constant pool of this class the items that corresponds to this attribute.
Returns:
bv.

toString

public String toString()
Returns value in the format described in JSR-175 for Java source code.

Overrides:
toString in class Object
Returns:
value in the format described in JSR-175 for Java source code.