Класс CharsetEncoder

java.lang.Object

java.nio.charset.CharsetEncoder

public abstract class CharsetEncoder extends Object

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

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

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

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

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

Способ обработки ошибки кодирования зависит от запрошенного действия для этого типа ошибки, которое описывается экземпляром класса 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)

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

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

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:: Объект результата кодировщика, описывающий причину завершения

encode

public final ByteBuffer encode(CharBuffer in) throws CharacterCodingException

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

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

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

canEncode

public boolean canEncode(char c)

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

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

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

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

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

canEncode

public boolean canEncode(CharSequence cs)

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

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

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

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