Пакет java.lang.classfile.attribute

Предоставляет интерфейсы, описывающие атрибуты файлов class для библиотеки java.lang.classfile.

API этого пакета выполняют проверку аргументов на null и непредставимые значения, если не указано иное.

Чтение атрибутов

При чтении из файлов class атрибуты разворачиваются лениво; содержимое этих атрибутов не анализируется, чтобы ускорить разбор, и пользовательские атрибуты из AttributeMapper.readAttribute(AttributedElement, ClassReader, int) также должны обрабатываться лениво. Интересующее пользователей содержимое можно прочитать по запросу, поэтому ошибки в одном атрибуте не препятствуют доступу к другим атрибутам.

Содержимое атрибутов представлено записями пула констант, чтобы точно отражать исходный файл class. Эти записи предоставляют методы преобразования, позволяющие просматривать их как проверенные символьные дескрипторы. Для эффективного чтения записей пула констант, которое также может повлиять на скорость чтения атрибутов, см. java.lang.classfile.constantpool. Ниже приведён пример проверки наличия аннотации Deprecated:

private static final String DEPRECATED_DESC = Deprecated.class.descriptorString();

static boolean hasDeprecated(AttributedElement element) {
    var annotations = element.findAttribute(Attributes.runtimeVisibleAnnotations())
            .map(RuntimeVisibleAnnotationsAttribute::annotations)
            .orElse(List.of());
    for (var anno : annotations) {
        // equalsString reduces extra computations for raw UTF-8 entries
        if (anno.className().equalsString(DEPRECATED_DESC)) {
            return true;
        }
    }
    return false;
}

Из-за ленивой природы разбора файлов class IllegalArgumentException, указывающее на повреждённые данные файла class, может быть выброшено при любом вызове метода: либо самим атрибутом из-за структурного повреждения, либо записью пула констант, на которую ссылается атрибут. Некоторые атрибуты, например атрибуты аннотаций, согласно JVMS должны молча игнорироваться, если они повреждены; поэтому код обработки атрибутов должен предусматривать возникновение IllegalArgumentException и пропускать такие атрибуты, а не передавать исключение дальше.

Запись атрибутов

Фабрики атрибутов обычно предоставляют два набора фабричных методов: один принимает символьную информацию, описывающую используемые элементы, а другой — записи пула констант. В большинстве случаев достаточно символьных фабрик, но фабрики, принимающие записи пула констант, можно использовать для более точного управления созданием файлов class; подробнее см. раздел «Запись записей пула констант».

Многие атрибуты можно копировать целиком, если данные, от которых они зависят, не меняются; эта информация доступна в AttributeMapper.stability() и описана для каждого атрибута в его интерфейсе моделирования. Возможность копирования целиком может значительно ускорить создание или преобразование файлов class. Кроме того, в сочетании с ClassFile.AttributesProcessingOption атрибуты, прочитанные из других файлов class, которые не могут подтвердить актуальность своих данных для создаваемого в данный момент файла class, могут быть отброшены.