Класс 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 basic encoding loop. Подкласс, поддерживающий внутреннее состояние, должен дополнительно переопределить методы 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)

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

Значение замены допустимо тогда и только тогда, когда это допустимая последовательность байтов в кодировке этого кодировщика; то есть, замена должна быть декодируема в один или несколько 16-разрядных символов Юникода.

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

Параметры:: 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()

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

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

encode

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, интерпретации его результатов, обработки условий ошибок и повторного вызова, если необходимо.

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

flush

public final CoderResult flush(ByteBuffer out)

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

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

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

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

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

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

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

implFlush

protected CoderResult implFlush(ByteBuffer out)

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

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

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

reset

public final CharsetEncoder reset()

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

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

Returns:: Этот кодер

implReset

protected void implReset()

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

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

encodeLoop

protected abstract CoderResult encodeLoop(CharBuffer in, ByteBuffer out)

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

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

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

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

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

кодировать

public final ByteBuffer encode(CharBuffer in) throws CharacterCodingException

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

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

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

можно закодировать

public boolean canEncode(char c)

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

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

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

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

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

можно закодировать

public boolean canEncode(CharSequence cs)

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

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

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

© 1993, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/nio/charset/CharsetEncoder.html