Класс CharsetEncoder

public abstract class CharsetEncoder
extends Object

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

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

1. Сбросьте кодировщик с помощью метода reset, если он не был использован ранее;

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

3. Вызовите метод encode один раз, передавая true для аргумента endOfInput; и затем

4. Вызовите метод flush, чтобы кодировщик мог очистить любое внутреннее состояние в буфер вывода.

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

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

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

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

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

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

Конструкторы

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 - Если предварительные условия для параметров не выполнены