Interface AttributeMapper<A extends Attribute<A>>
- Type Parameters:
A- the attribute type
class file representation of an
attribute and its API model. The attribute mapper identifies an attribute
by its name, and is used to parse the
class file representation into a model, and to write the model
representation back to a class file.
Attributes defines the mappers for predefined attributes in the JVMS
and certain conventional attributes. For other attributes (JVMS 4.7.1), users can define their own AttributeMapper; classes that
model those attributes should extend CustomAttribute. To read those
attributes, user-defined AttributeMappers must be registered to the
ClassFile.AttributeMapperOption.
- Since:
- 24
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic enumIndicates the data dependency of theclassfile representation of an attribute. -
Method Summary
Modifier and TypeMethodDescriptiondefault booleanReturns whether this attribute may appear more than once in one structure.name()Returns the name of the attribute.readAttribute(AttributedElement enclosing, ClassReader cf, int pos) Creates anAttributeinstance from aclassfile for the Class-File API.Returns the data dependency of this attribute on theclassfile.voidwriteAttribute(BufWriter buf, A attr) Writes anAttributeinstance to aclassfile for the Class-File API.
-
Method Details
-
name
-
readAttribute
Creates anAttributeinstance from aclassfile for the Class-File API.This method is called by the Class-File API to support reading of attributes. Users should never call this method.
The Class-File API makes these promises about the call to this method:
- The
Utf8Entryfor the name of the attribute is accessible withcf.readEntry(pos - 6, Utf8Entry.class), and is validated; - The length of the attribute is accessible with
cf.readInt(pos - 4), and is validated to be positive and not beyond the length of theclassfile; - The
AttributedElementattribute access functionalities on theenclosingmodel may not be accessed when this method is called, but can be accessed later by the returned attribute when it is accessible to users.
The returned
Attributemust fulfill these requirements:Attribute.attributeMapper()returns this mapper;Attribute.attributeName()returns the attribute name in theclassfile.
- API Note:
- Implementations of this method should perform minimal work to return an
attribute, as this method is called even if the resulting attribute is
never used. In particular, the implementation should avoid checking the
validity of the attribute
classfile data or performing actions that may throw exceptions. - Parameters:
enclosing- the structure in which this attribute appearscf- provides access to theclassfile to read frompos- the offset into theclassfile at which the contents of the attribute starts- Returns:
- the read attribute
- The
-
writeAttribute
Writes anAttributeinstance to aclassfile for the Class-File API.This method is called by the Class-File API to support writing of attributes. Users should never call this method.
The Class-File API makes these promises about the call to this method:
attr.attributeMapper()returns this mapper;- The
bufmay already have data written, that itssizemay not be0.
The
classfile writing must fulfill these requirements:- The attribute name
u2and attribute lengthu4must be written to thebuf; attr.attributeName()is written as if withbuf.writeIndex(attr.attributeName());- The attribute length is the length, in bytes, of attribute contents
written to the
buf, not including the 6 bytes used by the name and the length; - If any information in the API model of the attribute,
attr, cannot be represented in theclassfile format of the attribute, anIllegalArgumentExceptionis thrown.
- API Note:
BufWriter.patchInt(int, int, int)can be used to update the attribute length after the attribute contents are written to thebuf.- Parameters:
buf- theBufWriterto which the attribute should be writtenattr- the attribute to write- Throws:
IllegalArgumentException- if some data in the API model of the attribute is invalid for theclassfile format
-
allowMultiple
default boolean allowMultiple()Returns whether this attribute may appear more than once in one structure.If an attribute does not allow multiple instances in one structure, can be supplied to a
ClassFileBuilder, and multiple instances of the attribute are supplied to the builder, the last supplied attribute appears on the built structure.- Implementation Requirements:
- The default implementation returns
false. - Returns:
- whether this attribute may appear more than once in one structure
-
stability
AttributeMapper.AttributeStability stability()Returns the data dependency of this attribute on theclassfile.- Returns:
- the data dependency of this attribute on the
classfile
-