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

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

Если не указано иное, передача null или массива либо коллекции, содержащей элемент null, в качестве аргумента конструктору или методу любого класса или интерфейса API файлов классов приведёт к выбрасыванию NullPointerException.

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

При чтении файлов 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, могут быть отброшены.