Module java.base
Package java.lang.classfile

# Interface AttributeMapper

≠
public abstract interface AttributeMapper<A>
Comparing jdk-master and valhalla-csr-open

Type Parameters:
  `A` - the attribute type

public interface AttributeMapper<A extends AttributePREVIEW <A>>
Bidirectional mapper between the `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 `AttributeMapper` s must be registered to the `ClassFile.AttributeMapperOption` .

Since:
  24
See Also:
  - `Attributes`
  - `ClassFile.AttributeMapperOption`
  - `java.lang.classfile.attribute`

## Nested Types

- ≠ AttributeStability

## Methods

- =
  public default boolean allowMultiple()
- =
  public abstract java.lang.String name()
- ≠
  public abstract A readAttribute(java.lang.classfile.AttributedElement arg0, java.lang.classfile.ClassReader arg1, int arg2)
  Comparing jdk-master and valhalla-csr-open

  ### readAttribute

  A readAttribute (AttributedElement enclosing, ClassReader cf, int pos)
  Creates an `Attribute` PREVIEW 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` - the structure in which this attribute appears
    `cf` - provides access to the `class` file to read from
    `pos` - the offset into the `class` file at which the contents of the attribute starts
  Returns:
    the read attribute
- =
  public abstract java.lang.classfile.AttributeMapper.AttributeStability stability()
- ≠
  public abstract void writeAttribute(java.lang.classfile.BufWriter arg0, A arg1)
  Comparing jdk-master and valhalla-csr-open

  ### writeAttribute

  void writeAttribute (BufWriter buf, A attr)
  Writes an `Attribute` PREVIEW 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(int, int, int)` can be used to update the attribute length after the attribute contents are written to the `buf` .
  Parameters:
    `buf` - the `BufWriter` to which the attribute should be written
    `attr` - the attribute to write
  Throws:
    `IllegalArgumentException` - if some data in the API model of the attribute is invalid for the `class` file format

## Summary

Differences
| Elements | Comments | Descriptions | Total
Added | Changed | Removed | Added | Changed | Removed | Added | Changed | Removed
--- | --- | --- | --- | --- | --- | --- | --- | ---
AttributeMapper |  |  |  |  |  |  | 1 |  |  | 1
AttributeMapper.AttributeStability |  |  |  |  |  |  | 1 |  |  | 1
readAttribute(AttributedElement,ClassReader,int) |  |  |  |  |  |  | 2 |  |  | 2
writeAttribute(BufWriter,A) |  |  |  |  |  |  | 2 |  |  | 2
Total |  |  |  |  |  |  | 6 |  |  | 6