Attributes

Attributes — Attributes for classes, fields and methods.

Synopsis


#include <jclass/attributes.h>


typedef     AttributeContainer;
typedef     InnerClassInfo;
typedef     InnerClassesAttribute;
typedef     ExceptionsAttribute;
typedef     SourceFileAttribute;
typedef     ConstantValueAttribute;
typedef     ExceptionTableEntry;
typedef     CodeAttribute;
typedef     LineNumberInfo;
typedef     LineNumberAttribute;
typedef     LocalVariableInfo;
typedef     LocalVariableAttribute;
int         jclass_attribute_container_has_attribute
                                            (const AttributeContainer *container,
                                             const char *attribute_name,
                                             const ConstantPool *cpool);
SourceFileAttribute* jclass_sourcefile_attribute_new
                                            (const AttributeContainer *container);
void        jclass_sourcefile_attribute_free
                                            (SourceFileAttribute *attribute);
ConstantValueAttribute* jclass_constantvalue_attribute_new
                                            (const AttributeContainer *container);
void        jclass_constantvalue_attribute_free
                                            (ConstantValueAttribute *attribute);
ExceptionsAttribute* jclass_exceptions_attribute_new
                                            (const AttributeContainer *container);
void        jclass_exceptions_attribute_free
                                            (ExceptionsAttribute *attribute);
InnerClassesAttribute* jclass_innerclasses_attribute_new
                                            (const AttributeContainer *container);
void        jclass_innerclasses_attribute_free
                                            (InnerClassesAttribute *attribute);
CodeAttribute* jclass_code_attribute_new    (const AttributeContainer *container);
void        jclass_code_attribute_free      (CodeAttribute *attribute);
LineNumberAttribute* jclass_linenumber_attribute_new
                                            (const AttributeContainer *container);
void        jclass_linenumber_attribute_free
                                            (LineNumberAttribute *attribute);
LocalVariableAttribute* jclass_localvariable_attribute_new
                                            (const AttributeContainer *container);
void        jclass_localvariable_attribute_free
                                            (LocalVariableAttribute *attribute);

Description

Attributes are used to store any type of data in class files about any method, field or class.

All attributes are inside a "container" that provide the VM with information about the name and length in bytes of the attribute. If the VM does not know about an attribute it can simply skip it but it should understand the official attributes.

Official attributes as of the 2nd ed. of the VM Spec

Synthetic Compiler generated field/method/class. It did not appear in the source code.
Deprecated Used for informative purposes. (optional).
SourceFile Points to the constant pool for the name of the source file. (optional).
ConstantValue Holds the constant pool index for the value of final variables.
Code Holds the code and other relevant information for methods.
Exceptions A table with references to the exceptions thrown.
InnerClasses References for Inner classes.
LineNumberTable A PC -> linenumber map (optional).
LocalVariableTable Holds the programmer assigned names for variables (optional).

Details

AttributeContainer

typedef struct {
	/* The index of the utf8_info entry in the constant pool
	* with the name of the attribute.
	*/
	uint16_t name_index;
	/* The length in bytes of the contents of the attribute */
	uint32_t length;
	/* The attribute. */
	uint8_t* contents;
} AttributeContainer;

An attribute container contains exactly one attribute. The actual attribute is stored in the contents array There is no generic way to interprete an attribute, so libjclass does not extract attributes automatically. Use jclass_attribute_container_has_attribute() to detect the type of attribute contained and then the appropriate jclass_X_attribute_new function to extract the attribute.

InnerClassInfo

typedef struct {
	uint16_t type_index;	     
    uint16_t outer_class_type_index;	     
    uint16_t name_index;	     
    uint16_t access_flags;	
} InnerClassInfo;

Information about an inner class in the innerclass attribute.

InnerClassesAttribute

typedef struct {
	uint16_t no_innerclasses;
    InnerClassInfo* classes;
} InnerClassesAttribute;

Holds information about inner classes.

ExceptionsAttribute

typedef struct {
	uint16_t no_exceptions;
    uint16_t* exception_index;
} ExceptionsAttribute;

Exceptions attribute for classes and methods. It contains information about exceptions thrown only (not for exceptions caught).

SourceFileAttribute

typedef struct {
	/* Index to the constant pool for a utf8 entry
	with the name of the source file.
	*/
	uint16_t filename_index;
} SourceFileAttribute;

Attribute for the name of the source file used to compile the class.

ConstantValueAttribute

typedef struct {
	/* Index to the constant pool for an entry
	with the constant value.
	*/
	uint16_t cp_index;
} ConstantValueAttribute;

Attribute for the value of a constant.

ExceptionTableEntry

typedef struct {
	/* The start PC of the exception handler scope. */
	uint16_t start_pc;
	/* The end PC of the exception handler scope. */
    uint16_t end_pc;
	/* The PC where the exception handler is found. */
    uint16_t handler_pc;
	/* The index in the constant pool for the exception class.
	* An index of 0 indicates all exceptions will be handled (finally).
	*/
    uint16_t catch_type;
} ExceptionTableEntry;

An entry in the exception table.

CodeAttribute

typedef struct {
	uint16_t max_stack;
    uint16_t max_locals;
	/* Length of the code in bytes */
    uint32_t code_length;
	/* The code. It is stored in big-endian order */
    uint8_t* code;
	/* The length of the exception table */
    uint16_t exception_table_length;
	/* Holds information about the exceptions and handlers
	* in the code.
	*/
    ExceptionTableEntry* exception_table;
	/* Number of attributes */
    uint16_t attributes_count;
	/* Attributes for the code */
    AttributeContainer* attributes;
} CodeAttribute;

Holds the code for each method. The internal name for this attribute is "Code"

LineNumberInfo

typedef struct {
	/* The index in the code array that the line begins */
	uint16_t start_pc;
	/* The line number in the source code */	
   	uint16_t line_number;	  
} LineNumberInfo;

Line number information.

LineNumberAttribute

typedef struct {
	/* The number of line numbers (not length in bytes) */
	uint16_t length;
    LineNumberInfo* line_number;     
} LineNumberAttribute;

Holds line number information for debugging. The internal name of this attribute is "LineNumberTable" It can only appear inside the Code attribute.

LocalVariableInfo

typedef struct {
	/* The PC where the scope of the variable begins */
	uint16_t start_pc;
	/* The length of the scope of the variable*/
	uint16_t length;
	/* The index in the constant pool of the UTF8Entry 
	* with the name of the local variable.
	*/
	uint16_t name_index;
	/* The index in the constant pool of the UTF8Entry 
	* with the descriptor of the local variable.
	*/
	uint16_t descriptor_index;
	/* The index of the variable */
	uint16_t index;
} LocalVariableInfo;

An entry in the local variable table.

LocalVariableAttribute

typedef struct {
	uint16_t length;
	LocalVariableInfo* localvariable;
} LocalVariableAttribute;

Holds local variable information for debugging. The internal name for this attribute is "LocalVariableTable" It can only appear inside the Code attribute.

jclass_attribute_container_has_attribute ()

int         jclass_attribute_container_has_attribute
                                            (const AttributeContainer *container,
                                             const char *attribute_name,
                                             const ConstantPool *cpool);

Checks if the given attribute container contains a specific attribute.

`container` :	The container to check.
`attribute_name` :	The name of the attribute to look for.
`cpool` :	The constant pool for the class.
Returns :	1 if the container has the given attribute, 0 otherwise.

jclass_sourcefile_attribute_new ()

SourceFileAttribute* jclass_sourcefile_attribute_new
                                            (const AttributeContainer *container);

Extracts a sourcefile attribute from its attribute container.

`container` :	The attribute container.
Returns :	A newly constructed SourceFileAttribute.

jclass_sourcefile_attribute_free ()

void        jclass_sourcefile_attribute_free
                                            (SourceFileAttribute *attribute);

Frees a source file attribute.

attribute : The source file attribute to free.

jclass_constantvalue_attribute_new ()

ConstantValueAttribute* jclass_constantvalue_attribute_new
                                            (const AttributeContainer *container);

Extracts an constantvalue attribute from its attribute container.

`container` :	The attribute container.
Returns :	A newly constructed ConstantValue attribute.

jclass_constantvalue_attribute_free ()

void        jclass_constantvalue_attribute_free
                                            (ConstantValueAttribute *attribute);

Frees a constant value attribute.

attribute : The constant value attribute to free.

jclass_exceptions_attribute_new ()

ExceptionsAttribute* jclass_exceptions_attribute_new
                                            (const AttributeContainer *container);

Extracts an exceptions attribute from its attribute container.

`container` :	The attribute container.
Returns :	A newly constructed ExceptionsAttribute.

jclass_exceptions_attribute_free ()

void        jclass_exceptions_attribute_free
                                            (ExceptionsAttribute *attribute);

Frees an exceptions attribute.

attribute : The exception attribute to free.

jclass_innerclasses_attribute_new ()

InnerClassesAttribute* jclass_innerclasses_attribute_new
                                            (const AttributeContainer *container);

Extracts an innerclass attribute from its attribute container.

`container` :	The attribute container.
Returns :	A newly constructed InnerClassesAttribute.

jclass_innerclasses_attribute_free ()

void        jclass_innerclasses_attribute_free
                                            (InnerClassesAttribute *attribute);

Frees an innerclasses attribute.

attribute : The innerclasses attribute to free.

jclass_code_attribute_new ()

CodeAttribute* jclass_code_attribute_new    (const AttributeContainer *container);

Extracts a code attribute from its attribute container. This is a copy and it should be freed when it is no longer needed.

`container` :	The attribute container.
Returns :	A newly constructed CodeAttribute.

jclass_code_attribute_free ()

void        jclass_code_attribute_free      (CodeAttribute *attribute);

Frees a code attribute.

attribute : The Code attribute to free.

jclass_linenumber_attribute_new ()

LineNumberAttribute* jclass_linenumber_attribute_new
                                            (const AttributeContainer *container);

Extracts a line number attribute from its container.

`container` :	The attribute container holding the attribute.
Returns :	A newly constructed LineNumberAttribute.

jclass_linenumber_attribute_free ()

void        jclass_linenumber_attribute_free
                                            (LineNumberAttribute *attribute);

Frees a line number attribute.

attribute : The line number attribute to free.

jclass_localvariable_attribute_new ()

LocalVariableAttribute* jclass_localvariable_attribute_new
                                            (const AttributeContainer *container);

Extracts a localvariable attribute from its attribute container. Local variable attributes are contained only within code attributes.

`container` :	The attribute container containing the localvariable attribute.
Returns :	A newly constructed LocalVariableAttribute.

jclass_localvariable_attribute_free ()

void        jclass_localvariable_attribute_free
                                            (LocalVariableAttribute *attribute);

Frees a local variable attribute.

attribute : The attribute to free.