| java.lang.Object
 org.objectweb.asm.jip.Attribute
org.objectweb.asm.jip.attrs.StackMapTableAttribute
| StackMapTableAttribute | | public class StackMapTableAttribute extends Attribute (Code) | | 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:
- It must not be the local variable with the highest index.
- The next higher numbered local variable contains the verification type
T.
If the location is an operand stack entry, then:
- The current location must not be the topmost location of the
operand stack.
- the next location closer to the top of the operand
stack contains the verification type T.
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:
- It must not be the local variable with the highest index.
- The next higher numbered local variable contains the verification type
T.
-
If the location is an operand stack entry, then:
- The current location must not be the topmost location of the
operand stack.
- the next location closer to the top of the operand
stack contains the verification type T.
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;
}
See Also: "ClassFileFormat-Java6.fm Page 138 Friday, April 15, 2005 3:22 PM"
author:
Eugene Kuleshov |
| Field Summary | |
| final public 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. | | final public 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. | | final public static int | FULL_FRAME
| | final public static int | RESERVED
| | final public static int | SAME_FRAME
Frame has exactly the same locals as the previous stack map frame and
number of stack items is zero. | | final public static int | SAME_FRAME_EXTENDED
Frame has exactly the same locals as the previous stack map frame and
number of stack items is zero. | | final public static int | SAME_LOCALS_1_STACK_ITEM_FRAME
| | final public 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. |
| Method Summary | |
| 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.
Parameters:
access - access flags of the method.
Parameters:
methodName - name of the method.
Parameters:
methodDesc - descriptor of the method. | | public StackMapFrame | getFrame(Label label)
| | public List | getFrames()
| | public static int | getMethodOff(ClassReader cr, int codeOff, char[] buf)
| | public boolean | isCodeAttribute()
| | public boolean | isUnknown()
| | protected Attribute | read(ClassReader cr, int off, int len, char[] buf, int codeOff, Label[] labels)
| | public String | toString()
| | protected ByteVector | write(ClassWriter cw, byte[] code, int len, int maxStack, int maxLocals)
|
| APPEND_FRAME | | final public static int APPEND_FRAME(Code) | | 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.
|
| CHOP_FRAME | | final public static int CHOP_FRAME(Code) | | 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.
|
| FULL_FRAME | | final public static int FULL_FRAME(Code) | | Full frame
|
| RESERVED | | final public static int RESERVED(Code) | | Reserved for future use
|
| SAME_FRAME | | final public static int SAME_FRAME(Code) | | Frame has exactly the same locals as the previous stack map frame and
number of stack items is zero.
|
| SAME_FRAME_EXTENDED | | final public static int SAME_FRAME_EXTENDED(Code) | | Frame has exactly the same locals as the previous stack map frame and
number of stack items is zero. Offset is bigger then 63;
|
| SAME_LOCALS_1_STACK_ITEM_FRAME | | final public static int SAME_LOCALS_1_STACK_ITEM_FRAME(Code) | | Frame has exactly the same locals as the previous stack map frame and
number of stack items is 1
|
| SAME_LOCALS_1_STACK_ITEM_FRAME_EXTENDED | | final public static int SAME_LOCALS_1_STACK_ITEM_FRAME_EXTENDED(Code) | | Frame has exactly the same locals as the previous stack map frame and
number of stack items is 1. Offset is bigger then 63;
|
| StackMapTableAttribute | | public StackMapTableAttribute()(Code) | | |
| StackMapTableAttribute | | public StackMapTableAttribute(List frames)(Code) | | |
| calculateLocals | | public static List calculateLocals(String className, int access, String methodName, String methodDesc)(Code) | | Use method signature and access flags to resolve initial locals state.
Parameters:
className - name of the method's owner class.
Parameters:
access - access flags of the method.
Parameters:
methodName - name of the method.
Parameters:
methodDesc - descriptor of the method. list of StackMapType instances representing localsfor an initial frame. |
| getMethodOff | | public static int getMethodOff(ClassReader cr, int codeOff, char[] buf)(Code) | | |
| isCodeAttribute | | public boolean isCodeAttribute()(Code) | | |
| isUnknown | | public boolean isUnknown()(Code) | | |
|
|