Класс CharsetEncoder

java.lang.Object

java.nio.charset.CharsetEncoder

public abstract class CharsetEncoder extends Object

Двигатель, который может преобразовать последовательность символов Юникода в 16-битном формате в последовательность байтов в определённом наборе символов.

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

Сбросьте кодировщик с помощью метода reset, если он не был использован ранее;
Вызовите метод encode ноль или более раз, пока доступны дополнительные данные на входе, передавая false в качестве аргумента endOfInput и заполняя буфер ввода и очищая буфер вывода между вызовами;
Вызовите метод encode один последний раз, передавая true для аргумента endOfInput; а затем
Вызовите метод flush, чтобы кодировщик мог очистить любое внутреннее состояние в буфер вывода.

Каждый вызов метода encode будет кодировать как можно больше символов из буфера ввода, записывая полученные байты в буфер вывода. Метод encode возвращает, когда требуется дополнительный вход, когда в буфере вывода недостаточно места или когда произошла ошибка кодирования. В каждом случае возвращается объект CoderResult, чтобы описать причину завершения. Вызывающий метод может проверить этот объект, заполнить буфер ввода, очистить буфер вывода или попытаться восстановить от ошибки кодирования, как необходимо, и попробовать снова.

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

Обработка ошибки кодирования зависит от запрошенного действия для данного типа ошибки, которое описывается экземпляром класса CodingErrorAction. Возможными действиями по обработке ошибок являются: проигнорировать ошибочный вход, сообщить об ошибке вызывающему методу через возвращаемый объект CoderResult или заменить ошибочный вход текущим значением массива байтов замены. Значение замены изначально установлено на значение замены по умолчанию кодировщика, которое часто (но не всегда) имеет начальное значение { (byte)'?' }; его значение может быть изменено с помощью метода replaceWith.

Действие по умолчанию для ошибок некорректного ввода и неотображаемых символов — сообщить о них. Действие по ошибке некорректного ввода может быть изменено с помощью метода onMalformedInput; действие по ошибке неотображаемого символа может быть изменено с помощью метода onUnmappableCharacter.

Этот класс разработан для обработки многих деталей процесса кодирования, включая реализацию действий по обработке ошибок. Кодировщику для конкретного набора символов, который является конкретным подклассом этого класса, нужно только реализовать абстрактный метод encodeLoop, который encapsulates основной цикл кодирования. Подкласс, который сохраняет внутреннее состояние, должен дополнительно переопределить методы implFlush и implReset.

Экземпляры этого класса не являются потокобезопасными.

Since:

1.4

См. также:

Краткое описание конструкторов

CharsetEncoder(Charset cs,
 float averageBytesPerChar,
 float maxBytesPerChar)

CharsetEncoder(Charset cs,
 float averageBytesPerChar,
 float maxBytesPerChar,
 byte[] replacement)

Модификатор	Конструктор	Описание
`protected`	Инициализирует новый кодировщик.
`protected`	Инициализирует новый кодировщик.

Краткое описание методов

Модификатор и тип	Метод	Описание
`final float`	`averageBytesPerChar()`	Возвращает среднее число байтов, которые будут произведены для каждого символа входных данных.
`boolean`	`canEncode(char c)`	Указывает, может ли данный кодировщик закодировать заданный символ.
`boolean`	`canEncode(CharSequence cs)`	Указывает, может ли данный кодировщик закодировать заданную последовательность символов.
`final Charset`	`charset()`	Возвращает набор символов, который создал этот кодировщик.
`final ByteBuffer`	`encode(CharBuffer in)`	Метод-удобство, который кодирует оставшееся содержимое единственного входного буфера символов в новый выделенный буфер байтов.
`final CoderResult`	`encode(CharBuffer in, ByteBuffer out, boolean endOfInput)`	Кодирует как можно больше символов из данного входного буфера, записывая результаты в данный выходной буфер.
`protected abstract CoderResult`	`encodeLoop(CharBuffer in, ByteBuffer out)`	Кодирует один или несколько символов в один или несколько байтов.
`final CoderResult`	`flush(ByteBuffer out)`	Очищает этот кодировщик.
`protected CoderResult`	`implFlush(ByteBuffer out)`	Очищает этот кодировщик.
`protected void`	`implOnMalformedInput(CodingErrorAction newAction)`	Сообщает о изменении действия данного кодировщика по обработке некорректного ввода.
`protected void`	`implOnUnmappableCharacter(CodingErrorAction newAction)`	Сообщает о изменении действия данного кодировщика по обработке неотображаемых символов.
`protected void`	`implReplaceWith(byte[] newReplacement)`	Сообщает о изменении значения замены данного кодировщика.
`protected void`	`implReset()`	Сбрасывает этот кодировщик, очищая любое состояние, специфичное для набора символов.
`boolean`	`isLegalReplacement(byte[] repl)`	Указывает, является ли заданный массив байтов законным значением замены для данного кодировщика.
`CodingErrorAction`	`malformedInputAction()`	Возвращает текущее действие данного кодировщика по обработке ошибок некорректного ввода.
`final float`	`maxBytesPerChar()`	Возвращает максимальное число байтов, которые будут произведены для каждого символа входных данных.
`final CharsetEncoder`	`onMalformedInput(CodingErrorAction newAction)`	Изменяет действие данного кодировщика по обработке ошибок некорректного ввода.
`final CharsetEncoder`	`onUnmappableCharacter(CodingErrorAction newAction)`	Изменяет действие данного кодировщика по обработке ошибок неотображаемых символов.
`final byte[]`	`replacement()`	Возвращает значение замены данного кодировщика.
`final CharsetEncoder`	`replaceWith(byte[] newReplacement)`	Изменяет значение замены данного кодировщика.
`final CharsetEncoder`	`reset()`	Сбрасывает этот кодировщик, очищая любое внутреннее состояние.
`CodingErrorAction`	`unmappableCharacterAction()`	Возвращает текущее действие данного кодировщика по обработке ошибок неотображаемых символов.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Подробное описание конструкторов

CharsetEncoder

protected CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement)

Инициализирует новый кодировщик. Новый кодировщик будет иметь заданные значения байтов на символ и замены.

Параметры:: cs - Кодировка, создавшая этот кодировщик; averageBytesPerChar - Положительное значение с плавающей запятой, указывающее ожидаемое количество байтов, которое будет произведено для каждого символа ввода; maxBytesPerChar - Положительное значение с плавающей запятой, указывающее максимальное количество байтов, которое будет произведено для каждого символа ввода; replacement - Начальная замена; не должна быть null, должна иметь ненулевую длину, не должна быть длиннее maxBytesPerChar и должна быть допустимой
Исключения:: IllegalArgumentException - Если условия на параметрах не выполнены

CharsetEncoder

protected CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar)

Инициализирует новый кодировщик. Новый кодировщик будет иметь заданные значения байтов на символ, а его замена будет массивом байтов { (byte)'?' }.

Параметры:: cs - Кодировка, создавшая этот кодировщик; averageBytesPerChar - Положительное значение с плавающей запятой, указывающее ожидаемое количество байтов, которое будет произведено для каждого символа ввода; maxBytesPerChar - Положительное значение с плавающей запятой, указывающее максимальное количество байтов, которое будет произведено для каждого символа ввода
Исключения:: IllegalArgumentException - Если условия на параметрах не выполнены

Подробное описание методов

charset

public final Charset charset()

Возвращает кодировку, которая создала этот кодировщик.

Возвращает:: Кодировка этого кодировщика

replacement

public final byte[] replacement()

Возвращает значение замены этого кодировщика.

Возвращает:: Текущее значение замены кодировщика, которое никогда не null и никогда не пусто

replaceWith

public final CharsetEncoder replaceWith(byte[] newReplacement)

Изменяет значение замены этого кодировщика.

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

Параметры:: newReplacement - Новая замена; не должна быть null, должна иметь ненулевую длину, не должна быть длиннее значения, возвращаемого методом maxBytesPerChar, и должна быть legal
Возвращает:: Этот кодировщик
Исключения:: IllegalArgumentException - Если условия на параметре не выполнены

implReplaceWith

protected void implReplaceWith(byte[] newReplacement)

Сообщает об изменении значения замены этого кодировщика.

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

Параметры:: newReplacement - Значение замены

isLegalReplacement

public boolean isLegalReplacement(byte[] repl)

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

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

По умолчанию реализация этого метода не очень эффективна; ее следует переопределить для повышения производительности.

Параметры:: repl - Массив байтов для проверки
Возвращает:: true если и только если заданный массив байтов является допустимым значением замены для этого кодировщика

malformedInputAction

public CodingErrorAction malformedInputAction()

Возвращает текущее действие кодировщика для ошибок неверного ввода.

Возвращает:: Текущее действие для ошибок неверного ввода, которое никогда не null

onMalformedInput

public final CharsetEncoder onMalformedInput(CodingErrorAction newAction)

Изменяет действие этого кодировщика для ошибок неверного ввода.

Этот метод вызывает метод implOnMalformedInput, передавая новое действие.

Параметры:: newAction - Новое действие; не должно быть null
Возвращает:: Этот кодировщик
Исключения:: IllegalArgumentException - Если условие на параметре не выполняется

implOnMalformedInput

protected void implOnMalformedInput(CodingErrorAction newAction)

Сообщает об изменении действия кодировщика для ошибок неверного ввода.

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

Параметры:: newAction - Новое действие

unmappableCharacterAction

public CodingErrorAction unmappableCharacterAction()

Возвращает текущее действие кодировщика для ошибок неотображаемых символов.

Возвращает:: Текущее действие для ошибок неотображаемых символов, которое никогда не null

onUnmappableCharacter

public final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)

Изменяет действие этого кодировщика для ошибок неотображаемых символов.

Этот метод вызывает метод implOnUnmappableCharacter, передавая новое действие.

Параметры:: newAction - Новое действие; не должно быть null
Возвращает:: Этот кодировщик
Исключения:: IllegalArgumentException - Если условие на параметре не выполняется

implOnUnmappableCharacter

protected void implOnUnmappableCharacter(CodingErrorAction newAction)

Сообщает об изменении действия кодировщика для ошибок неотображаемых символов.

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

Параметры:: newAction - Новое действие

averageBytesPerChar

public final float averageBytesPerChar()

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

Возвращает:: Среднее количество байтов, производимых на символ ввода

maxBytesPerChar

public final float maxBytesPerChar()

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

Возвращает:: Максимальное количество байтов, которое будет произведено на символ ввода

кодирование

public final CoderResult encode(CharBuffer in, ByteBuffer out, boolean endOfInput)

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

Буферы считываются и записываются, начиная с их текущих позиций. Максимально будет прочитано in.remaining() символов и максимально будет записано out.remaining() байтов. Позиции буферов будут сдвинуты, чтобы отразить прочитанные символы и записанные байты, но их метки и пределы не будут изменены.

В дополнение к чтению символов из входного буфера и записи байтов в выходной буфер, этот метод возвращает объект CoderResult, чтобы описать причину завершения:

CoderResult.UNDERFLOW указывает, что как можно больше входного буфера было закодировано. Если больше нет входных данных, вызывающая сторона может перейти к следующему шагу операции кодирования. В противном случае этот метод должен быть вызван снова с дополнительными входными данными.
CoderResult.OVERFLOW указывает, что в выходном буфере недостаточно места для кодирования дополнительных символов. Этот метод должен быть вызван снова с выходным буфером, в котором больше оставшихся байтов. Обычно это делается путем сброса закодированных байтов из выходного буфера.
Результат ошибки формата указывает, что была обнаружена ошибка формата входных данных. Неправильные символы начинаются с позиции входного буфера (возможно, увеличенной); количество неправильных символов можно определить, вызвав метод length объекта результата. Этот случай применим только в том случае, если действие по обработке неправильных входных данных этого кодера равно CodingErrorAction.REPORT; в противном случае неправильный ввод будет проигнорирован или заменён, как запрошено.
Результат ошибки неотображаемого символа указывает, что была обнаружена ошибка неотображаемого символа. Символы, которые кодируют неотображаемый символ, начинаются с позиции входного буфера (возможно, увеличенной); количество таких символов можно определить, вызвав метод length объекта результата. Этот случай применим только в том случае, если действие по обработке неотображаемых символов этого кодера равно CodingErrorAction.REPORT; в противном случае неотображаемый символ будет проигнорирован или заменён, как запрошено.

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

Параметр endOfInput сообщает этому методу, может ли вызывающая сторона предоставить дополнительные данные, помимо содержащихся в данном входном буфере. Если существует возможность предоставления дополнительных данных, вызывающая сторона должна передать false; если нет возможности предоставить дополнительные данные, вызывающая сторона должна передать true. Не является ошибкой, и на самом деле это довольно распространённо, передать false в одном вызове и позже обнаружить, что на самом деле дополнительных данных не было. Однако крайне важно, чтобы при последнем вызове этого метода в последовательности вызовов всегда передавалось true, чтобы любые оставшиеся нескодированные входные данные рассматривались как неправильные.

Этот метод работает, вызывая метод encodeLoop, интерпретируя его результаты, обрабатывая условия ошибок и вызывая его повторно при необходимости.

Параметры:: in - Входной буфер символов; out - Выходной буфер байтов; endOfInput - true, если и только если вызывающая сторона не может предоставить дополнительных символов ввода, помимо тех, которые находятся в заданном буфере
Возвращает:: Объект результата кодирования, описывающий причину завершения
Исключения:: IllegalStateException - Если операция кодирования уже выполняется, и предыдущий шаг был вызовом ни метода reset, ни этого метода со значением false для параметра endOfInput, ни этого метода со значением true для параметра endOfInput, но возвращаемое значение указывает на незавершенную операцию кодирования; CoderMalfunctionError - Если вызов метода encodeLoop выбросил непредвиденное исключение

сброс

public final CoderResult flush(ByteBuffer out)

Сбрасывает этот кодер.

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

Любой дополнительный вывод записывается в выходной буфер, начиная с его текущей позиции. Максимально будет записано out.remaining() байтов. Позиция буфера будет соответствующим образом смещена, но его метка и предел не будут изменены.

Если этот метод выполняется успешно, он возвращает CoderResult.UNDERFLOW. Если в выходном буфере недостаточно места, то он возвращает CoderResult.OVERFLOW. Если это произойдёт, этот метод должен быть вызван снова с выходным буфером, в котором больше места, чтобы завершить текущую операцию кодирования.

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

Этот метод вызывает метод implFlush для выполнения фактической операции сброса.

Параметры:: out - Выходной буфер байтов
Возвращает:: Объект результата кодирования, либо CoderResult.UNDERFLOW, либо CoderResult.OVERFLOW
Исключения:: IllegalStateException - Если предыдущий шаг текущей операции кодирования был вызовом ни метода flush, ни трёх-аргументного метода encode со значением true для параметра endOfInput

implFlush

protected CoderResult implFlush(ByteBuffer out)

Сбрасывает этот кодер.

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

Параметры:: out - Выходной буфер байтов
Возвращает:: Объект результата кодирования, либо CoderResult.UNDERFLOW, либо CoderResult.OVERFLOW

сброс

public final CharsetEncoder reset()

Сбрасывает этот кодер, очищая любое внутреннее состояние.

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

Возвращает:: Этот кодер

implReset

protected void implReset()

Сбрасывает этот кодер, очищая любое внутреннее состояние, зависящее от кодировки.

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

encodeLoop

protected abstract CoderResult encodeLoop(CharBuffer in, ByteBuffer out)

Кодирует один или несколько символов в один или несколько байтов.

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

Буферы считываются и записываются, начиная с их текущих позиций. Максимально будет прочитано in.remaining() символов, и максимально будет записано out.remaining() байтов. Позиции буферов будут сдвинуты, чтобы отразить прочитанные символы и записанные байты, но их метки и пределы не будут изменены.

Этот метод возвращает объект CoderResult, чтобы описать причину завершения, аналогично методу encode. Большинство реализаций этого метода будут обрабатывать ошибки кодирования, возвращая соответствующий объект результата для интерпретации методом encode. Оптимизированная реализация может вместо этого проверить соответствующее действие по обработке ошибок и реализовать это действие сама.

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

Параметры:: in - Входной буфер символов; out - Выходной буфер байтов
Возвращает:: Объект результата кодирования, описывающий причину завершения

encode

public final ByteBuffer encode(CharBuffer in) throws CharacterCodingException

Удобный метод, кодирующий оставшееся содержимое единственного входного буфера символов в новый буфер байтов.

Этот метод реализует всю операцию кодирования; то есть, он сбрасывает этот кодировщик, затем кодирует символы в заданном буфере символов и, наконец, сбрасывает этот кодировщик. Поэтому этот метод не следует вызывать, если операция кодирования уже выполняется.

Параметры:: in - Входной буфер символов
Возвращаемое значение:: Новый выделенный буфер байтов, содержащий результат операции кодирования. Позиция буфера будет равна нулю, а его предел будет следовать за последним записанным байтом.
Исключения:: IllegalStateException - Если операция кодирования уже выполняется; MalformedInputException - Если последовательность символов, начинающаяся с текущей позиции входного буфера, не является допустимой последовательностью Unicode 16-битных символов, и текущее действие на некорректный вход — CodingErrorAction.REPORT; UnmappableCharacterException - Если последовательность символов, начинающаяся с текущей позиции входного буфера, не может быть отображена на эквивалентную последовательность байтов, и текущее действие на неотображаемый символ — CodingErrorAction.REPORT; CharacterCodingException - MalformedInputException если последовательность символов, начинающаяся с текущей позиции входного буфера, не является допустимой последовательностью Unicode 16-битных символов, и текущее действие на некорректный вход — CodingErrorAction.REPORT; UnmappableCharacterException если последовательность символов, начинающаяся с текущей позиции входного буфера, не может быть отображена на эквивалентную последовательность байтов, и текущее действие на неотображаемый символ — CodingErrorAction.REPORT; OutOfMemoryError - Если буфер выходных байтов для запрошенного размера входного буфера символов не может быть выделен

canEncode

public boolean canEncode(char c)

Определяет, может ли этот кодировщик закодировать данный символ.

Этот метод возвращает false если заданный символ является замещающим символом; такие символы могут интерпретироваться только тогда, когда они являются членами пары, состоящей из верхнего замещающего символа, за которым следует нижний замещающий символ. Метод canEncode(CharSequence) может использоваться для проверки возможности кодирования последовательности символов.

Этот метод может изменять состояние этого кодировщика; поэтому его не следует вызывать, если операция кодирования уже выполняется.

Стандартная реализация этого метода не очень эффективна; её обычно следует переопределять для повышения производительности.

Параметры:: c - Заданный символ
Возвращаемое значение:: true только в том случае, если этот кодировщик может закодировать заданный символ
Исключения:: IllegalStateException - Если операция кодирования уже выполняется

canEncode

public boolean canEncode(CharSequence cs)

Определяет, может ли этот кодировщик закодировать заданную последовательность символов.

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

Параметры:: cs - Заданная последовательность символов
Возвращаемое значение:: true только в том случае, если этот кодировщик может закодировать заданную последовательность символов без выброса исключений и без выполнения замен
Исключения:: IllegalStateException - Если операция кодирования уже выполняется

© 1993, 2023, 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/21/docs/api/java.base/java/nio/charset/CharsetEncoder.html