Класс 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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Показывает, «равен» ли этот объект другому объекту.
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API может быть удалён в будущей версии. Финализация устарела и может быть удалена в одном из следующих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает значение хеш-кода этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания, либо до истечения заданного интервала реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания, либо до истечения заданного интервала реального времени.

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

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.