Modifier and Type	Class and Description
public static enum	AttributeMapper.AttributeStability Indicates the data dependency of the `class` file representation of an attribute.

Method Summary

Modifier and Type	Method and Description
public default boolean	Returns: whether this attribute may appear more than once in one structure allowMultiple() Returns whether this attribute may appear more than once in one structure.
public String	Returns: the name of the attribute name() Returns the name of the attribute.
public A	Returns: the read attribute readAttribute(AttributedElement the structure in which this attribute appears enclosing, ClassReader provides access to the `class` file to read from cf, int the offset into the `class` file at which the contents of the attribute starts pos) Creates an `Attribute` instance from a `class` file for the Class-File API.
public AttributeMapper.AttributeStability	Returns: the data dependency of this attribute on the `class` file stability() Returns the data dependency of this attribute on the `class` file.
public void	writeAttribute(BufWriter the `BufWriter` to which the attribute should be written buf, A the attribute to write attr) Writes an `Attribute` instance to a `class` file for the Class-File API.

Method Detail

allowMultiple back to summary

allowMultiple	back to summary
public 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 Specification The default implementation returns `false`. Returns:boolean whether this attribute may appear more than once in one structure

public 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 Specification

The default implementation returns false.

Returns:boolean: whether this attribute may appear more than once in one structure

name	back to summary
public String name() Returns the name of the attribute. Returns:String the name of the attribute

name

back to summary

public String name()

Returns the name of the attribute.

Returns:String: the name of the attribute

readAttribute back to summary

readAttribute	back to summary
public A readAttribute(AttributedElement enclosing, ClassReader cf, int pos) Creates an `Attribute` instance from a `class` file 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 `Utf8Entry` for the name of the attribute is accessible with `cf.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 the `class` file; The `AttributedElement` attribute access functionalities on the `enclosing` model 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 `Attribute` must fulfill these requirements: `Attribute#attributeMapper()` returns this mapper; `Attribute#attributeName()` returns the attribute name in the `class` file. 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 `class` file data or performing actions that may throw exceptions. Parameters enclosing:AttributedElement the structure in which this attribute appears cf:ClassReader provides access to the `class` file to read from pos:int the offset into the `class` file at which the contents of the attribute starts Returns:A the read attribute

public A readAttribute(AttributedElement enclosing, ClassReader cf, int pos)

Creates an Attribute instance from a class file 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 Utf8Entry for the name of the attribute is accessible with cf.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 the class file;
The AttributedElement attribute access functionalities on the enclosing model 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 Attribute must fulfill these requirements:

Attribute#attributeMapper() returns this mapper;
Attribute#attributeName() returns the attribute name in the class file.

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 class file data or performing actions that may throw exceptions.

Parameters

enclosing:AttributedElement: the structure in which this attribute appears
cf:ClassReader: provides access to the class file to read from
pos:int: the offset into the class file at which the contents of the attribute starts

Returns:A

the read attribute

stability back to summary

stability	back to summary
public AttributeMapper.AttributeStability stability() Returns the data dependency of this attribute on the `class` file. Returns:AttributeMapper.AttributeStability the data dependency of this attribute on the `class` file

public AttributeMapper.AttributeStability stability()

Returns the data dependency of this attribute on the class file.

Returns:AttributeMapper.AttributeStability: the data dependency of this attribute on the class file

writeAttribute back to summary

writeAttribute	back to summary
public void writeAttribute(BufWriter buf, A attr) Writes an `Attribute` instance to a `class` file 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 `buf` may already have data written, that its `size` may not be `0`. The `class` file writing must fulfill these requirements: The attribute name `u2` and attribute length `u4` must be written to the `buf`; `attr.attributeName()` is written as if with `buf.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 the `class` file format of the attribute, an `IllegalArgumentException` is thrown. API Note `BufWriter#patchInt` can be used to update the attribute length after the attribute contents are written to the `buf`. Parameters buf:BufWriter the `BufWriter` to which the attribute should be written attr:A the attribute to write Exceptions IllegalArgumentException: if some data in the API model of the attribute is invalid for the `class` file format

public void writeAttribute(BufWriter buf, A attr)

Writes an Attribute instance to a class file 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 buf may already have data written, that its size may not be 0.

The class file writing must fulfill these requirements:

The attribute name u2 and attribute length u4 must be written to the buf;
attr.attributeName() is written as if with buf.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 the class file format of the attribute, an IllegalArgumentException is thrown.

API Note

BufWriter#patchInt can be used to update the attribute length after the attribute contents are written to the buf.

Parameters

buf:BufWriter: the BufWriter to which the attribute should be written
attr:A: the attribute to write

Exceptions

IllegalArgumentException:: if some data in the API model of the attribute is invalid for the class file format

java.lang.classfile back to summary

public final Enum AttributeMapper.AttributeStability

Class Inheritance

extends Enum<AttributeMapper.AttributeStability>

java.lang.Object
java.lang.Enum
java.lang.classfile.AttributeMapper.AttributeStability

Indicates the data dependency of the class file representation of an attribute. Whether an attribute can be bulk-copied by its binary representation to a new class file depends on if its data refers to other parts of its enclosing class file.

API Note

This dependency is called "stability" because it indicates the conditions for a class file attribute to be eligible for bulk-copying to another class file.

Since: 24
See Also: AttributeMapper#stability()

Field Summary

Modifier and Type	Field and Description
public static final AttributeMapper.AttributeStability	CP_REFS In addition to standalone data, the attribute refers to the constant pool, including the `BootstrapMethods` attribute, of its enclosing `class` file.
public static final AttributeMapper.AttributeStability	LABELS In addition to standalone data and references to the constant pool, the attribute refers to positions into the `code` array of a `Code` attribute.
public static final AttributeMapper.AttributeStability	STATELESS The attribute contains only standalone data, and has no reference to other parts of its enclosing `class` file, besides the name of the attribute.
public static final AttributeMapper.AttributeStability	UNKNOWN The attribute is completely unknown.
public static final AttributeMapper.AttributeStability	UNSTABLE The attribute refers to structures not managed by the library (type variable lists, etc.).

Constructor Summary

Access	Constructor and Description
private	AttributeStability()

Method Summary

Modifier and Type	Method and Description
public static AttributeMapper.AttributeStability	valueOf(String name)
public static AttributeMapper.AttributeStability[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

CP_REFS back to summary

CP_REFS	back to summary
public static final AttributeMapper.AttributeStability CP_REFS In addition to standalone data, the attribute refers to the constant pool, including the `BootstrapMethods` attribute, of its enclosing `class` file. Thus, it can be bulk-copied when the destination `class` file extends its constant pool from that of the original `class`. It must be expanded to translate constant pool references and rewritten when constant pool indices are not compatible. For example, a `Utf8Entry` is a reference to the constant pool. See Also `ConstantPoolBuilder#of(ClassModel)`, `ClassFile.ConstantPoolSharingOption`

public static final AttributeMapper.AttributeStability CP_REFS

In addition to standalone data, the attribute refers to the constant pool, including the BootstrapMethods attribute, of its enclosing class file. Thus, it can be bulk-copied when the destination class file extends its constant pool from that of the original class. It must be expanded to translate constant pool references and rewritten when constant pool indices are not compatible.

For example, a Utf8Entry is a reference to the constant pool.

See Also: ConstantPoolBuilder#of(ClassModel), ClassFile.ConstantPoolSharingOption

LABELS back to summary

LABELS	back to summary
public static final AttributeMapper.AttributeStability LABELS In addition to standalone data and references to the constant pool, the attribute refers to positions into the `code` array of a `Code` attribute. Thus, it can be bulked-copied when the `code` array is unchanged, which requires that the destination `class` file extends its constant pool from that of the original `class`. It must be expanded to translate `Label`s or constant pool references and rewritten if the `code` array is perturbed, including when constant pool indices are not compatible. For example, a bci value, modeled by a `Label`, is a reference to a position in the `code` array.

public static final AttributeMapper.AttributeStability LABELS

In addition to standalone data and references to the constant pool, the attribute refers to positions into the code array of a Code attribute. Thus, it can be bulked-copied when the code array is unchanged, which requires that the destination class file extends its constant pool from that of the original class. It must be expanded to translate Labels or constant pool references and rewritten if the code array is perturbed, including when constant pool indices are not compatible.

For example, a bci value, modeled by a Label, is a reference to a position in the code array.

STATELESS back to summary

STATELESS	back to summary
public static final AttributeMapper.AttributeStability STATELESS The attribute contains only standalone data, and has no reference to other parts of its enclosing `class` file, besides the name of the attribute. Thus, its contents can always be bulk-copied to another `class` file. For example, a bit mask is standalone data.

public static final AttributeMapper.AttributeStability STATELESS

The attribute contains only standalone data, and has no reference to other parts of its enclosing class file, besides the name of the attribute. Thus, its contents can always be bulk-copied to another class file.

For example, a bit mask is standalone data.

UNKNOWN back to summary

UNKNOWN	back to summary
public static final AttributeMapper.AttributeStability UNKNOWN The attribute is completely unknown. As a result, expanding and rewriting is not possible, and any difference between the destination `class` file and its enclosing `class` file may make the attribute incorrect. `ClassFile.AttributesProcessingOption` determines whether to preserve or drop the attribute during transformation. See Also `UnknownAttribute`, `ClassFile.AttributesProcessingOption#DROP_UNSTABLE_ATTRIBUTES`, `ClassFile.AttributesProcessingOption#DROP_UNKNOWN_ATTRIBUTES`

public static final AttributeMapper.AttributeStability UNKNOWN

The attribute is completely unknown. As a result, expanding and rewriting is not possible, and any difference between the destination class file and its enclosing class file may make the attribute incorrect.

ClassFile.AttributesProcessingOption determines whether to preserve or drop the attribute during transformation.

See Also: UnknownAttribute, ClassFile.AttributesProcessingOption#DROP_UNSTABLE_ATTRIBUTES, ClassFile.AttributesProcessingOption#DROP_UNKNOWN_ATTRIBUTES

UNSTABLE back to summary

UNSTABLE	back to summary
public static final AttributeMapper.AttributeStability UNSTABLE The attribute refers to structures not managed by the library (type variable lists, etc.). As a result, even when the attribute is expanded, those references may not be correctly translated, and the rewritten results may be incorrect. If the attribute is read from a `class` file, `ClassFile.AttributesProcessingOption` determines whether to preserve or drop the attribute during transformation. See Also `ClassFile.AttributesProcessingOption#DROP_UNSTABLE_ATTRIBUTES`

public static final AttributeMapper.AttributeStability UNSTABLE

The attribute refers to structures not managed by the library (type variable lists, etc.). As a result, even when the attribute is expanded, those references may not be correctly translated, and the rewritten results may be incorrect.

If the attribute is read from a class file, ClassFile.AttributesProcessingOption determines whether to preserve or drop the attribute during transformation.

See Also: ClassFile.AttributesProcessingOption#DROP_UNSTABLE_ATTRIBUTES

Constructor Detail

AttributeStability	back to summary
private AttributeStability()

Method Detail

valueOf	back to summary
public static AttributeMapper.AttributeStability valueOf(String name)

values	back to summary
public static AttributeMapper.AttributeStability[] values()

public Interface AttributeMapper<A extends Attribute<A>>

Nested and Inner Type Summary

Method Summary

Method Detail

public final Enum AttributeMapper.AttributeStability

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail