Класс CharsetEncoder

java.lang.Object

java.nio.charset.CharsetEncoder

public abstract class CharsetEncoder extends Object

Механизм, который может преобразовать последовательность шестнадцатибитных символов Unicode в последовательность байтов в определённой кодировке.

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

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

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

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

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

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

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

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

Начиная с:

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()`	Возвращает текущее действие этого кодировщика при ошибках с символами, не поддающимися отображению.

Методы, объявленные в классе 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 — Положительное значение типа float, указывающее ожидаемое количество байтов, которое будет создано для каждого входного символа; maxBytesPerChar — Положительное значение типа float, указывающее максимальное количество байтов, которое будет создано для каждого входного символа; replacement — Начальное значение замены; не должно быть null, должно иметь ненулевую длину, не должно быть длиннее maxBytesPerChar и должно быть допустимым
Выбрасывает:: IllegalArgumentException — Если предварительные условия для параметров не выполняются

CharsetEncoder

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

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

Параметры:: cs — Кодировка, создавшая этот кодировщик; averageBytesPerChar — Положительное значение типа float, указывающее ожидаемое количество байтов, которое будет создано для каждого входного символа; maxBytesPerChar — Положительное значение типа float, указывающее максимальное количество байтов, которое будет создано для каждого входного символа
Выбрасывает:: 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-битных символов 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()

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

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

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

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

flush

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

reset

public final CharsetEncoder reset()

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

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

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

implReset

protected void implReset()

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

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

encodeLoop

protected abstract CoderResult encodeLoop(CharBuffer in, ByteBuffer out)

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

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

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

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

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

encode

public final ByteBuffer encode(CharBuffer in) throws CharacterCodingException

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

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

Параметры:: in — Входной буфер символов
Возвращает:: Новый буфер байтов, содержащий результат операции кодирования. Позиция буфера будет равна нулю, а предел будет указывать на позицию после последнего записанного байта.
Выбрасывает:: IllegalStateException — Если операция кодирования уже выполняется; MalformedInputException — Если последовательность символов, начинающаяся с текущей позиции входного буфера, не является допустимой 16-битной последовательностью Unicode, а для текущего действия при некорректном входе задано значение CodingErrorAction.REPORT; UnmappableCharacterException — Если последовательность символов, начинающаяся с текущей позиции входного буфера, не может быть преобразована в эквивалентную последовательность байтов, а для текущего действия при несопоставимых символах задано значение CodingErrorAction.REPORT; CharacterCodingException — MalformedInputException, если последовательность символов, начинающаяся с текущей позиции входного буфера, не является допустимой 16-битной последовательностью Unicode, а для текущего действия при некорректном входе задано значение 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, 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://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/charset/CharsetEncoder.html