org.objectweb.asm.attrs
Class StackMapTableAttribute

java.lang.Object
  extended by org.objectweb.asm.Attribute
      extended by org.objectweb.asm.attrs.StackMapTableAttribute
Direct Known Subclasses:
ASMStackMapTableAttribute

public class StackMapTableAttribute
extends Attribute

The stack map attribute is used during the process of verification by typechecking (4.11.1).

A stack map attribute consists of zero or more stack map frames. Each stack map frame specifies (either explicitly or implicitly) a bytecode offset, the verification types (4.11.1) for the local variables, and the verification types for the operand stack.

The type checker deals with and manipulates the expected types of a method's local variables and operand stack. Throughout this section, a location refers to either a single local variable or to a single operand stack entry.

We will use the terms stack frame map and type state interchangeably to describe a mapping from locations in the operand stack and local variables of a method to verification types. We will usually use the term stack frame map when such a mapping is provided in the class file, and the term type state when the mapping is inferred by the type checker.

If a method's Code attribute does not have a StackMapTable attribute, it has an implicit stack map attribute. This implicit stack map attribute is equivalent to a StackMapTable attribute with number_of_entries equal to zero. A method's Code attribute may have at most one StackMapTable attribute, otherwise a java.lang.ClassFormatError is thrown.

The format of the stack map in the class file is given below. In the following, if the length of the method's byte code is 65535 or less, then uoffset represents the type u2; otherwise uoffset represents the type u4. If the maximum number of local variables for the method is 65535 or less, then ulocalvar represents the type u2; otherwise ulocalvar represents the type u4. If the maximum size of the operand stack is 65535 or less, then ustack represents the type u2; otherwise ustack represents the type u4.

 stack_map { // attribute StackMapTable
   u2 attribute_name_index;
   u4 attribute_length
   uoffset number_of_entries;
   stack_map_frame entries[number_of_entries];
 }
 
Each stack_map_frame structure specifies the type state at a particular byte code offset. Each frame type specifies (explicitly or implicitly) a value, offset_delta, that is used to calulate the actual byte code offset at which it applies. The byte code offset at which the frame applies is given by adding 1 + offset_delta to the offset of the previous frame, unless the previous frame is the initial frame of the method, in which case the byte code offset is offset_delta.

Note that the length of the byte codes is not the same as the length of the Code attribute. The byte codes are embedded in the Code attribute, along with other information.

By using an offset delta rather than the actual byte code offset we ensure, by definition, that stack map frames are in the correctly sorted order. Furthermore, by consistently using the formula offset_delta + 1 for all explicit frames, we guarantee the absence of duplicates.

All frame types, even full_frame, rely on the previous frame for some of their semantics. This raises the question of what is the very first frame? The initial frame is implicit, and computed from the method descriptor. See the Prolog code for methodInitialStacFrame.

The stack_map_frame structure consists of a one-byte tag followed by zero or more bytes, giving more information, depending upon the tag.

A stack map frame may belong to one of several frame types
 union stack_map_frame {
   same_frame;
   same_locals_1_stack_item_frame;
   chop_frame;
   same_frame_extended;
   append_frame;
   full_frame;
 }
 
The frame type same_frame is represented by tags in the range [0-63]. If the frame type is same_frame, it means the frame has exactly the same locals as the previous stack map frame and that the number of stack items is zero. The offset_delta value for the frame is the value of the tag field, frame_type. The form of such a frame is then:
 same_frame {
   u1 frame_type = SAME;  // 0-63
 }
 
The frame type same_locals_1_stack_item_frame is represented by tags in the range [64, 127]. If the frame_type is same_locals_1_stack_item_frame, it means the frame has exactly the same locals as the previous stack map frame and that the number of stack items is 1. The offset_delta value for the frame is the value (frame_type - 64). There is a verification_type_info following the frame_type for the one stack item. The form of such a frame is then:
 same_locals_1_stack_item_frame {
   u1 frame_type = SAME_LOCALS_1_STACK_ITEM;  // 64-127
    verification_type_info stack[1];
 }
 
Tags in the range [128-247] are reserved for future use.

The frame type chop_frame is represented by tags in the range [248-250]. If the frame_type is chop_frame, it means that the current locals are the same as the locals in the previous frame, except that the k last locals are absent. The value of k is given by the formula 251-frame_type.

The form of such a frame is then:
 chop_frame {
   u1 frame_type=CHOP;  // 248-250
   uoffset offset_delta;
 }
 
The frame type same_frame_extended is represented by the tag value 251. If the frame type is same_frame_extended, it means the frame has exactly the same locals as the previous stack map frame and that the number of stack items is zero. The form of such a frame is then:
 same_frame_extended {
   u1 frame_type = SAME_FRAME_EXTENDED;  // 251
   uoffset offset_delta;
 }
 
The frame type append_frame is represented by tags in the range [252-254]. If the frame_type is append_frame, it means that the current locals are the same as the locals in the previous frame, except that k additional locals are defined. The value of k is given by the formula frame_type-251.

The form of such a frame is then:
 append_frame {
   u1 frame_type =APPEND;  // 252-254
   uoffset offset_delta;
   verification_type_info locals[frame_type -251];
 }
 
The 0th entry in locals represents the type of the first additional local variable. If locals[M] represents local variable N, then locals[M+1] represents local variable N+1 if locals[M] is one of Top_variable_info, Integer_variable_info, Float_variable_info, Null_variable_info, UninitializedThis_variable_info, Object_variable_info, or Uninitialized_variable_info, otherwise locals[M+1] represents local variable N+2. It is an error if, for any index i, locals[i] represents a local variable whose index is greater than the maximum number of local variables for the method.

The frame type full_frame is represented by the tag value 255. The form of such a frame is then:
 full_frame {
   u1 frame_type = FULL_FRAME;  // 255
   uoffset offset_delta;
   ulocalvar number_of_locals;
   verification_type_info locals[number_of_locals];
   ustack number_of_stack_items;
   verification_type_info stack[number_of_stack_items];
 }
 
The 0th entry in locals represents the type of local variable 0. If locals[M] represents local variable N, then locals[M+1] represents local variable N+1 if locals[M] is one of Top_variable_info, Integer_variable_info, Float_variable_info, Null_variable_info, UninitializedThis_variable_info, Object_variable_info, or Uninitialized_variable_info, otherwise locals[M+1] represents local variable N+2. It is an error if, for any index i, locals[i] represents a local variable whose index is greater than the maximum number of local variables for the method.

The 0th entry in stack represents the type of the bottom of the stack, and subsequent entries represent types of stack elements closer to the top of the operand stack. We shall refer to the bottom element of the stack as stack element 0, and to subsequent elements as stack element 1, 2 etc. If stack[M] represents stack element N, then stack[M+1] represents stack element N+1 if stack[M] is one of Top_variable_info, Integer_variable_info, Float_variable_info, Null_variable_info, UninitializedThis_variable_info, Object_variable_info, or Uninitialized_variable_info, otherwise stack[M+1] represents stack element N+2. It is an error if, for any index i, stack[i] represents a stack entry whose index is greater than the maximum operand stack size for the method.

We say that an instruction in the byte code has a corresponding stack map frame if the offset in the offset field of the stack map frame is the same as the offset of the instruction in the byte codes.

The verification_type_info structure consists of a one-byte tag followed by zero or more bytes, giving more information about the tag. Each verification_type_info structure specifies the verification type of one or two locations.
 union verification_type_info {
   Top_variable_info;
   Integer_variable_info;
   Float_variable_info;
   Long_variable_info;
   Double_variable_info;
   Null_variable_info;
   UninitializedThis_variable_info;
   Object_variable_info;
   Uninitialized_variable_info;
 }
 
The Top_variable_info type indicates that the local variable has the verification type top (T.)
 Top_variable_info {
   u1 tag = ITEM_Top; // 0
 }
 
The Integer_variable_info type indicates that the location contains the verification type int.
 Integer_variable_info {
   u1 tag = ITEM_Integer; // 1
 }
 
The Float_variable_info type indicates that the location contains the verification type float.
 Float_variable_info {
   u1 tag = ITEM_Float; // 2
 }
 
The Long_variable_info type indicates that the location contains the verification type long. If the location is a local variable, then: If the location is an operand stack entry, then: This structure gives the contents of two locations in the operand stack or in the local variables.
 Long_variable_info {
   u1 tag = ITEM_Long; // 4
 }
 
The Double_variable_info type indicates that the location contains the verification type double. If the location is a local variable, then: If the location is an operand stack entry, then: This structure gives the contents of two locations in in the operand stack or in the local variables.
 Double_variable_info {
   u1 tag = ITEM_Double; // 3
 }
 
The Null_variable_info type indicates that location contains the verification type null.
 Null_variable_info {
   u1 tag = ITEM_Null; // 5
 }
 
The UninitializedThis_variable_info type indicates that the location contains the verification type uninitializedThis.
 UninitializedThis_variable_info {
   u1 tag = ITEM_UninitializedThis; // 6
 }
 
The Object_variable_info type indicates that the location contains an instance of the class referenced by the constant pool entry.
 Object_variable_info {
   u1 tag = ITEM_Object; // 7
   u2 cpool_index;
 }
 
The Uninitialized_variable_info indicates that the location contains the verification type uninitialized(offset). The offset item indicates the offset of the new instruction that created the object being stored in the location.
 Uninitialized_variable_info {
   u1 tag = ITEM_Uninitialized // 8
   uoffset offset;
 }
 

Author:
Eugene Kuleshov
See Also:
"ClassFileFormat-Java6.fm Page 138 Friday, April 15, 2005 3:22 PM"

Field Summary
static int APPEND_FRAME
          Frame where current locals are the same as the locals in the previous frame, except that k additional locals are defined.
static int CHOP_FRAME
          Frame where current locals are the same as the locals in the previous frame, except that the k last locals are absent.
static int FULL_FRAME
          Full frame
static int RESERVED
          Reserved for future use
static int SAME_FRAME
          Frame has exactly the same locals as the previous stack map frame and number of stack items is zero.
static int SAME_FRAME_EXTENDED
          Frame has exactly the same locals as the previous stack map frame and number of stack items is zero.
static int SAME_LOCALS_1_STACK_ITEM_FRAME
          Frame has exactly the same locals as the previous stack map frame and number of stack items is 1
static int SAME_LOCALS_1_STACK_ITEM_FRAME_EXTENDED
          Frame has exactly the same locals as the previous stack map frame and number of stack items is 1.
 
Fields inherited from class org.objectweb.asm.Attribute
type
 
Constructor Summary
StackMapTableAttribute()
           
StackMapTableAttribute(List frames)
           
 
Method Summary
static List calculateLocals(String className, int access, String methodName, String methodDesc)
          Use method signature and access flags to resolve initial locals state.
 StackMapFrame getFrame(Label label)
           
 List getFrames()
           
static int getMethodOff(ClassReader cr, int codeOff, char[] buf)
           
 boolean isCodeAttribute()
          Returns true if this type of attribute is a code attribute.
 boolean isUnknown()
          Returns true if this type of attribute is unknown.
protected  Attribute read(ClassReader cr, int off, int len, char[] buf, int codeOff, Label[] labels)
          Reads a type attribute.
 String toString()
           
protected  ByteVector write(ClassWriter cw, byte[] code, int len, int maxStack, int maxLocals)
          Returns the byte array form of this attribute.
 
Methods inherited from class org.objectweb.asm.Attribute
getLabels
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

SAME_FRAME

public static final int SAME_FRAME
Frame has exactly the same locals as the previous stack map frame and number of stack items is zero.

See Also:
Constant Field Values

SAME_LOCALS_1_STACK_ITEM_FRAME

public static final int SAME_LOCALS_1_STACK_ITEM_FRAME
Frame has exactly the same locals as the previous stack map frame and number of stack items is 1

See Also:
Constant Field Values

RESERVED

public static final int RESERVED
Reserved for future use

See Also:
Constant Field Values

SAME_LOCALS_1_STACK_ITEM_FRAME_EXTENDED

public static final int SAME_LOCALS_1_STACK_ITEM_FRAME_EXTENDED
Frame has exactly the same locals as the previous stack map frame and number of stack items is 1. Offset is bigger then 63;

See Also:
Constant Field Values

CHOP_FRAME

public static final int CHOP_FRAME
Frame where current locals are the same as the locals in the previous frame, except that the k last locals are absent. The value of k is given by the formula 251-frame_type.

See Also:
Constant Field Values

SAME_FRAME_EXTENDED

public static final int SAME_FRAME_EXTENDED
Frame has exactly the same locals as the previous stack map frame and number of stack items is zero. Offset is bigger then 63;

See Also:
Constant Field Values

APPEND_FRAME

public static final int APPEND_FRAME
Frame where current locals are the same as the locals in the previous frame, except that k additional locals are defined. The value of k is given by the formula frame_type-251.

See Also:
Constant Field Values

FULL_FRAME

public static final int FULL_FRAME
Full frame

See Also:
Constant Field Values
Constructor Detail

StackMapTableAttribute

public StackMapTableAttribute()

StackMapTableAttribute

public StackMapTableAttribute(List frames)
Method Detail

getFrames

public List getFrames()

getFrame

public StackMapFrame getFrame(Label label)

isUnknown

public boolean isUnknown()
Description copied from class: Attribute
Returns true if this type of attribute is unknown. The default implementation of this method always returns true.

Overrides:
isUnknown in class Attribute
Returns:
true if this type of attribute is unknown.

isCodeAttribute

public boolean isCodeAttribute()
Description copied from class: Attribute
Returns true if this type of attribute is a code attribute.

Overrides:
isCodeAttribute in class Attribute
Returns:
true if this type of attribute is a code attribute.

read

protected Attribute read(ClassReader cr,
                         int off,
                         int len,
                         char[] buf,
                         int codeOff,
                         Label[] labels)
Description copied from class: Attribute
Reads a type attribute. This method must return a new Attribute object, of type type, corresponding to the len bytes starting at the given offset, in the given class reader.

Overrides:
read in class Attribute
Parameters:
cr - the class that contains the attribute to be read.
off - index of the first byte of the attribute's content in cr.b. The 6 attribute header bytes, containing the type and the length of the attribute, are not taken into account here.
len - the length of the attribute's content.
buf - buffer to be used to call readUTF8, readClass or readConst.
codeOff - index of the first byte of code's attribute content in cr.b, or -1 if the attribute to be read is not a code attribute. The 6 attribute header bytes, containing the type and the length of the attribute, are not taken into account here.
labels - the labels of the method's code, or null if the attribute to be read is not a code attribute.
Returns:
a new Attribute object corresponding to the given bytes.

write

protected ByteVector write(ClassWriter cw,
                           byte[] code,
                           int len,
                           int maxStack,
                           int maxLocals)
Description copied from class: Attribute
Returns the byte array form of this attribute.

Overrides:
write in class Attribute
Parameters:
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.
code - the bytecode of the method corresponding to this code attribute, or null if this attribute is not a code attributes.
len - the length of the bytecode of the method corresponding to this code attribute, or null if this attribute is not a code attribute.
maxStack - the maximum stack size of the method corresponding to this code attribute, or -1 if this attribute is not a code attribute.
maxLocals - the maximum number of local variables of the method corresponding to this code attribute, or -1 if this attribute is not a code attribute.
Returns:
the byte array form of this attribute.

getMethodOff

public static int getMethodOff(ClassReader cr,
                               int codeOff,
                               char[] buf)

calculateLocals

public static List calculateLocals(String className,
                                   int access,
                                   String methodName,
                                   String methodDesc)
Use method signature and access flags to resolve initial locals state.

Parameters:
className - name of the method's owner class.
access - access flags of the method.
methodName - name of the method.
methodDesc - descriptor of the method.
Returns:
list of StackMapType instances representing locals for an initial frame.

toString

public String toString()
Overrides:
toString in class Object