StackMapTableAttribute (Drools 4.0.0.11754MR2 API) - JBoss RULES 4.0.0.11754MR2 API 英文版文档

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.drools.asm.attrs
Class StackMapTableAttribute

java.lang.Object
  org.drools.asm.Attribute
      org.drools.asm.attrs.StackMapTableAttribute

Direct Known Subclasses:: ASMStackMapTableAttribute

public class StackMapTableAttribute
extends Attribute
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:

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;
 }

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.drools.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.drools.asm.Attribute

getLabels

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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.drools.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.drools.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