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

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

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

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

При чтении из файлов class атрибуты загружаются лениво; содержимое этих атрибутов не вычисляется для ускорения разбора, а атрибуты, определённые пользователем из AttributeMapper.readAttribute(java.lang.classfile.AttributedElement, java.lang.classfile.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, могут быть пропущены.