Интерфейс Pack200.Packer

Вложенный класс:: Pack200

@Deprecated(since="11",
            forRemoval=true)
public static interface Pack200.Packer

Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии.

Этот интерфейс устарел и планируется к удалению в будущей версии.

Двигатель упаковки применяет различные преобразования к входному файлу JAR, делая поток упаковки высоко сжимаемым с помощью компрессора, такого как gzip или zip. Экземпляр двигателя можно получить, используя Pack200.newPacker(). Высокая степень сжатия достигается с помощью ряда методов, описанных в спецификации JSR 200. Некоторые из этих методов включают сортировку, переупорядочение и размещение в одном месте константного пула.

Двигатель упаковки инициализируется начальным состоянием, как описано в его свойствах ниже. Начальное состояние можно изменить, получив свойства двигателя (используя properties()) и сохранив изменённые свойства в карте. Файлы ресурсов будут переданы без изменений. Файлы классов не будут содержать идентичные байты, так как распаковщик свободен изменять незначительные особенности файлов классов, такие как порядок константного пула. Однако файлы классов будут семантически идентичны, как указано в Спецификации виртуальной машины Java™.

По умолчанию упаковщик не изменяет порядок элементов JAR. Также время изменения и подсказка сжатия каждого элемента JAR передаются без изменений. (Любая другая информация архива ZIP, такая как дополнительные атрибуты, указывающие права доступа к файлам Unix, теряются.)

Обратите внимание, что упаковка и распаковка JAR в целом изменят байтовое содержимое файлов классов в JAR. Это означает, что упаковка и распаковка в целом аннулируют все цифровые подписи, которые полагаются на байтовое изображение элементов JAR. Для того, чтобы одновременно подписать и упаковать JAR, необходимо сначала упаковать и распаковать JAR, чтобы «нормализовать» его, затем вычислить подписи для распакованных элементов JAR и, наконец, переупаковать подписанный JAR. Оба шага упаковки должны использовать точно те же параметры, а предел сегмента также может потребоваться установить в «-1», чтобы предотвратить случайное изменение границ сегментов, так как размеры файлов классов незначительно изменятся.

(Вот почему это работает: любое переупорядочение, производимое упаковщиком, для любых структур файлов классов, является идемпотентным, поэтому вторая упаковка не изменяет порядок, произведённый первой упаковкой. Кроме того, распаковщик гарантирует спецификация JSR 200, что он создаст определённое байтовое изображение для любого заданного порядка передачи элементов архива.)

Для обеспечения обратной совместимости версия файла упаковки устанавливается с учётом файлов классов, присутствующих во входном файле JAR. Другими словами, версия файла упаковки будет последней, если файлы классов являются последними, и наоборот, версия файла упаковки будет самой старой, если версии файлов классов также являются самыми старыми. Для промежуточных версий файлов классов будет использоваться соответствующая версия файла упаковки. Например: если входные файлы JAR состоят только из файлов классов версии 1.5 (или более ранних), создаётся совместимый с версией 1.5 файл упаковки. Это также будет справедливо для архивов, не содержащих файлов классов. Если входной файл JAR содержит файл класса версии 1.6, то версия файла упаковки будет установлена в 1.6.

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

С:: 1.5

Поля

Модификатор и тип	Поле	Описание
`static String`	`CLASS_ATTRIBUTE_PFX`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. При конкатенации с именем атрибута класса указывает формат этого атрибута, используя язык разметки, указанный в спецификации JSR 200.
`static String`	`CODE_ATTRIBUTE_PFX`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. При конкатенации с именем атрибута кода указывает формат этого атрибута.
`static String`	`DEFLATE_HINT`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Если это свойство установлено в `TRUE` или `FALSE`, упаковщик установит подсказку сжатия соответствующим образом в выходном архиве и не будет передавать отдельные подсказки сжатия элементов архива.
`static String`	`EFFORT`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Если это свойство установлено в одиночную цифру, упаковщик будет использовать указанное количество усилий при сжатии архива.
`static String`	`ERROR`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Строка «error», возможное значение для определённых свойств.
`static String`	`FALSE`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Строка «false», возможное значение для определённых свойств.
`static String`	`FIELD_ATTRIBUTE_PFX`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. При конкатенации с именем атрибута поля указывает формат этого атрибута.
`static String`	`KEEP`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Строка «keep», возможное значение для определённых свойств.
`static String`	`KEEP_FILE_ORDER`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Если это свойство установлено в `TRUE`, упаковщик будет передавать все элементы в их исходном порядке внутри исходного архива.
`static String`	`LATEST`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Строка «latest», возможное значение для определённых свойств.
`static String`	`METHOD_ATTRIBUTE_PFX`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. При конкатенации с именем атрибута метода указывает формат этого атрибута.
`static String`	`MODIFICATION_TIME`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Если это свойство установлено в специальную строку `LATEST`, упаковщик попытается определить последнее время изменения среди всех доступных записей в исходном архиве или последнее время изменения всех доступных записей в каждом сегменте.
`static String`	`PASS`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Строка «pass», возможное значение для определённых свойств.
`static String`	`PASS_FILE_PFX`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Указывает, что файл должен быть передан байтово, без сжатия.
`static String`	`PROGRESS`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Прогресс упаковщика в процентах, периодически обновляемый упаковщиком.
`static String`	`SEGMENT_LIMIT`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Это свойство — числовое значение, представляющее целевой размер N (в байтах) каждого сегмента архива.
`static String`	`STRIP`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Строка «strip», возможное значение для определённых свойств.
`static String`	`TRUE`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Строка «true», возможное значение для определённых свойств.
`static String`	`UNKNOWN_ATTRIBUTE`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Указывает действие, которое следует предпринять при обнаружении файла класса, содержащего неизвестный атрибут.

Методы

Модификатор и тип Метод Описание

Модификатор и тип	Метод	Описание
`void`	`pack(JarFile in, OutputStream out)`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Принимает JarFile и преобразует его в архив Pack200.
`void`	`pack(JarInputStream in, OutputStream out)`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Принимает JarInputStream и преобразует его в архив Pack200.
`SortedMap<String,String>`	`properties()`	Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии. Получить набор свойств этого двигателя.

void

pack(JarFile in,
    OutputStream out)

Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии.

Принимает JarFile и преобразует его в архив Pack200.

void

pack(JarInputStream in,
    OutputStream out)

Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии.

Принимает JarInputStream и преобразует его в архив Pack200.

SortedMap<String,String>

properties()

Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии.

Получить набор свойств этого двигателя.

Поля

SEGMENT_LIMIT

static final String SEGMENT_LIMIT

Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии.

Это свойство — числовое значение, представляющее приблизительный целевой размер N (в байтах) каждого сегмента архива. Если отдельный входной файл требует больше N байт, ему будет выделен свой сегмент архива.

В качестве специального случая, значение -1 приведет к созданию одного большого сегмента со всеми входными файлами, а значение 0 — к созданию одного сегмента для каждого класса. Более крупные сегменты архива приводят к меньшей фрагментации и лучшему сжатию, но их обработка требует больше памяти.

Размер каждого сегмента оценивается путем подсчета размера каждого входного файла, который должен быть передан в сегменте, вместе с размером его имени и других передаваемых свойств.

По умолчанию установлено значение -1, что означает, что упаковщик всегда будет создавать один выходной файл сегмента. В случаях, когда генерируются чрезвычайно большие выходные файлы, пользователям настоятельно рекомендуется использовать сегментацию или разбить входной файл на более мелкие JAR-файлы.

JAR-файл размером 10 МБ, упакованный без этого ограничения, обычно будет упакован примерно на 10% меньше, но упаковщику может потребоваться большая куча Java (примерно в десять раз превышающая ограничение сегмента).

См. также:: Значения константных полей

KEEP_FILE_ORDER

static final String KEEP_FILE_ORDER

Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии.

Если это свойство установлено в значение TRUE, упаковщик будет передавать все элементы в исходном порядке внутри исходного архива.

Если оно установлено в значение FALSE, упаковщик может изменить порядок элементов, а также удалить записи каталога JAR, которые не содержат полезной информации для приложений Java. (Обычно это позволяет улучшить сжатие.)

По умолчанию установлено значение TRUE, которое сохраняет исходную информацию, но может привести к тому, что переданный архив будет больше, чем необходимо.

См. также:: Значения константных полей

EFFORT

static final String EFFORT

Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии.

Если это свойство установлено на одно десятичное число, упаковщик использует указанное количество усилий для сжатия архива. Уровень 1 может привести к несколько большему размеру и более высокой скорости сжатия, а уровень 9 займет гораздо больше времени, но может обеспечить лучшее сжатие.

Специальное значение 0 указывает упаковщику копировать исходный JAR-файл напрямую без сжатия. Стандарт JSR 200 требует, чтобы любой распаковщик понимал этот специальный случай как проход через весь архив.

По умолчанию установлено значение 5, что означает умеренное время для достижения приемлемого сжатия.

См. также:: Значения константных полей

DEFLATE_HINT

static final String DEFLATE_HINT

Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии.

Если это свойство установлено на TRUE или FALSE, упаковщик соответствующим образом установит подсказку сжатия в выходном архиве и не будет передавать отдельные подсказки сжатия элементов архива.

Если это свойство установлено на специальную строку KEEP, упаковщик попытается определить независимую подсказку сжатия для каждого доступного элемента входного архива и передать эту подсказку отдельно.

По умолчанию установлено значение KEEP, которое сохраняет входную информацию, но может привести к тому, что переданный архив будет больше, чем необходимо.

Реализация распаковщика должна принять действие по подсказке, чтобы надлежащим образом сжать элементы получившегося распакованного jar-файла.

Подсказка сжатия элемента ZIP или JAR указывает, был ли элемент сжат или сохранен напрямую.

См. также:: Значения константных полей

ВРЕМЯ_ИЗМЕНЕНИЯ

static final String MODIFICATION_TIME

Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии.

Если это свойство установлено на специальную строку LATEST, упаковщик попытается определить последнее время изменения среди всех доступных записей в исходном архиве или последнее время изменения всех доступных записей в каждом сегменте. Это единственное значение будет передано как часть сегмента и применено ко всем записям в каждом сегменте, SEGMENT_LIMIT.

Это может незначительно уменьшить размер переданного архива за счет установки всех установленных файлов на одну дату.

Если это свойство установлено на специальную строку KEEP, упаковщик передает отдельное время изменения для каждого входного элемента.

Реализация распаковщика должна принять действие, чтобы соответствующим образом установить время изменения каждого элемента выходного файла.

См. также:: SEGMENT_LIMIT, Значения константных полей

PASS_FILE_PFX

static final String PASS_FILE_PFX

Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии.

Указывает, что файл должен быть передан байтово без сжатия. Несколько файлов можно указать, указав дополнительные свойства с различными добавленными строками, чтобы создать набор свойств с общим префиксом.

Преобразования пути не производится, за исключением того, что системный разделитель файлов заменяется разделителем JAR-файлов '/'.

Имена получившихся файлов должны точно совпадать как строки со своими появлениями в JAR-файле.

Если значение свойства — имя каталога, все файлы в этом каталоге также будут переданы.

Примеры:

Map p = packer.properties();
     p.put(PASS_FILE_PFX+0, "mutants/Rogue.class");
     p.put(PASS_FILE_PFX+1, "mutants/Wolverine.class");
     p.put(PASS_FILE_PFX+2, "mutants/Storm.class");
     # Pass all files in an entire directory hierarchy:
     p.put(PASS_FILE_PFX+3, "police/");

См. также:: Значения константных полей

НЕИЗВЕСТНОЕ_АТРИБУТ

static final String UNKNOWN_ATTRIBUTE

Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии.

Указывает действие, которое должно быть выполнено при обнаружении файла с классами, содержащими неизвестный атрибут. Возможные значения — строки ERROR, STRIP и PASS.

Строка ERROR означает, что операция упаковки в целом завершится неудачей с исключением типа IOException. Строка STRIP означает, что атрибут будет удален. Строка PASS означает, что весь файл класса будет передан (как если бы это был файл ресурса) без сжатия со соответствующим предупреждением. Это значение по умолчанию для этого свойства.

Примеры:

Map p = pack200.getProperties();
     p.put(UNKNOWN_ATTRIBUTE, ERROR);
     p.put(UNKNOWN_ATTRIBUTE, STRIP);
     p.put(UNKNOWN_ATTRIBUTE, PASS);

См. также:: Значения константных полей

ПРЕФИКС_АТРИБУТА_КЛАССА

static final String CLASS_ATTRIBUTE_PFX

Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии.

При конкатенации с именем атрибута класса указывает формат этого атрибута, используя язык разметки, указанный в спецификации JSR 200.

Например, эффект этого параметра встроен в: pack.class.attribute.SourceFile=RUH.

Также разрешены специальные строки ERROR, STRIP и PASS с тем же значением, что и UNKNOWN_ATTRIBUTE. Это предоставляет способ запросить отказ, удаление или передачу конкретных атрибутов бит в бит (без сжатия класса).

Такой код может использоваться для поддержки атрибутов JCOV:

Map p = packer.properties();
     p.put(CODE_ATTRIBUTE_PFX+"CoverageTable",       "NH[PHHII]");
     p.put(CODE_ATTRIBUTE_PFX+"CharacterRangeTable", "NH[PHPOHIIH]");
     p.put(CLASS_ATTRIBUTE_PFX+"SourceID",           "RUH");
     p.put(CLASS_ATTRIBUTE_PFX+"CompilationID",      "RUH");

Код такого типа может использоваться для удаления атрибутов отладки:

Map p = packer.properties();
     p.put(CODE_ATTRIBUTE_PFX+"LineNumberTable",    STRIP);
     p.put(CODE_ATTRIBUTE_PFX+"LocalVariableTable", STRIP);
     p.put(CLASS_ATTRIBUTE_PFX+"SourceFile",        STRIP);

См. также:: Значения константных полей

ПРЕФИКС_АТРИБУТА_ПОЛЯ

static final String FIELD_ATTRIBUTE_PFX

Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии.

При конкатенации с именем атрибута поля указывает формат этого атрибута. Например, эффект этого параметра встроен в: pack.field.attribute.Deprecated=. Также разрешены специальные строки ERROR, STRIP и PASS.

См. также:: CLASS_ATTRIBUTE_PFX, Значения константных полей

ПРЕФИКС_АТРИБУТА_МЕТОДА

static final String METHOD_ATTRIBUTE_PFX

Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии.

При конкатенации с именем атрибута метода указывает формат этого атрибута. Например, эффект этого параметра встроен в: pack.method.attribute.Exceptions=NH[RCH]. Также разрешены специальные строки ERROR, STRIP и PASS.

См. также:: CLASS_ATTRIBUTE_PFX, Значения константных полей

ПРЕФИКС_АТРИБУТА_КОДА

static final String CODE_ATTRIBUTE_PFX

Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии.

При конкатенации со именем атрибута кода указывает формат этого атрибута. Например, эффект этого параметра встроен: pack.code.attribute.LocalVariableTable=NH[PHOHRUHRSHH]. Также разрешены специальные строки ERROR, STRIP и PASS.

См. также:: CLASS_ATTRIBUTE_PFX, Значения константных полей

PROGRESS

static final String PROGRESS

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Прогресс упаковщика в процентах, периодически обновляемый упаковщиком. Значения от 0 до 100 являются нормальными, а -1 указывает на задержку. Прогресс можно отслеживать, опрашивая значение этого свойства.

Как минимум, упаковщик должен установить прогресс в 0 в начале операции упаковки и в 100 в конце.

См. также:: Значения константных полей

KEEP

static final String KEEP

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Строка "keep", возможное значение для некоторых свойств.

См. также:: DEFLATE_HINT, MODIFICATION_TIME, Значения константных полей

PASS

static final String PASS

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Строка "pass", возможное значение для некоторых свойств.

См. также:: UNKNOWN_ATTRIBUTE, CLASS_ATTRIBUTE_PFX, FIELD_ATTRIBUTE_PFX, METHOD_ATTRIBUTE_PFX, CODE_ATTRIBUTE_PFX, Значения константных полей

STRIP

static final String STRIP

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Строка "strip", возможное значение для некоторых свойств.

См. также:: UNKNOWN_ATTRIBUTE, CLASS_ATTRIBUTE_PFX, FIELD_ATTRIBUTE_PFX, METHOD_ATTRIBUTE_PFX, CODE_ATTRIBUTE_PFX, Значения константных полей

ERROR

static final String ERROR

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Строка "error", возможное значение для некоторых свойств.

См. также:: UNKNOWN_ATTRIBUTE, CLASS_ATTRIBUTE_PFX, FIELD_ATTRIBUTE_PFX, METHOD_ATTRIBUTE_PFX, CODE_ATTRIBUTE_PFX, Значения константных полей

TRUE

static final String TRUE

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Строка "true", возможное значение для некоторых свойств.

См. также:: KEEP_FILE_ORDER, DEFLATE_HINT, Значения константных полей

FALSE

static final String FALSE

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Строка "false", возможное значение для некоторых свойств.

См. также:: KEEP_FILE_ORDER, DEFLATE_HINT, Значения константных полей

LATEST

static final String LATEST

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Строка "latest", возможное значение для некоторых свойств.

См. также:: MODIFICATION_TIME, Значения константных полей

Методы

properties

SortedMap<String,String> properties()

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Получить набор свойств этого движка. Этот набор представляет собой "динамическое представление", поэтому изменение его содержимого немедленно влияет на движок Packer, а изменения со стороны движка (например, указания о прогрессе) немедленно отображаются в карте.

Карта свойств может содержать предопределенные свойства, специфичные для реализации, и свойства по умолчанию. Пользователям рекомендуется ознакомиться с информацией и полностью понять последствия перед изменением существующих свойств.

Свойства, специфичные для реализации, имеют префикс с именем пакета, связанного с исполнителем, начинающегося с com. или аналогичного префикса. Все имена свойств, начинающиеся с pack. и unpack., зарезервированы для использования в этом API.

Неизвестные свойства могут быть проигнорированы или отклонены с неопределенной ошибкой, а некорректные записи могут привести к возникновению неопределенной ошибки.

Возвращаемая карта реализует все необязательные SortedMap операции.

Возвращает:: Отсортированное отображение строк ключей свойств к значениям свойств.

pack

void pack(JarFile in,
          OutputStream out)
   throws IOException

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Преобразует JarFile в архив Pack200.

Закрывает свой ввод, но не свой вывод. (Архивы Pack200 могут быть дополняемыми.)

Параметры:: in - JarFile; out - OutputStream
Исключения:: IOException - если возникла ошибка.

pack

void pack(JarInputStream in,
          OutputStream out)
   throws IOException

Устарело, для удаления: Этот элемент API может быть удален в будущей версии.

Преобразует JarInputStream в архив Pack200.

Закрывает свой ввод, но не свой вывод. (Архивы Pack200 могут быть дополняемыми.)

Атрибуты времени изменения и подсказки сжатия не доступны для файла манифеста JAR и содержащей его директории.

Параметры:: in - JarInputStream; out - OutputStream
Исключения:: IOException - если возникла ошибка.
См. также:: MODIFICATION_TIME, DEFLATE_HINT

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/jar/Pack200.Packer.html