Класс CharsetEncoder

public abstract class CharsetEncoder
extends Object

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

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

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

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

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

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

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

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

Обработка ошибки кодирования зависит от действия, запрошенного для данного типа ошибки, которое описывается экземпляром класса CodingErrorAction. Возможные действия при ошибках: проигнорировать ошибочный вход, сообщить об ошибке вызывающему коду через возвращаемый объект CoderResult или заменить ошибочный вход текущим значением массива байтов замены. Значение замены по умолчанию устанавливается для кодировщика, который часто (но не всегда) имеет начальное значение { (byte)'?' }; его значение можно изменить с помощью метода 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 - Если условия на параметрах не выполняются

Методы

charset

public final Charset charset()

Возвращает кодировку, создавшую этот кодировщик.

Возвращает:

Кодировка этого кодировщика

replacement

public final byte[] replacement()

Возвращает значение замены этого кодировщика.

Возвращает:

Текущее значение замены кодировщика, которое никогда не null и никогда не пустое

replaceWith

public final CharsetEncoder replaceWith(byte[] newReplacement)

Параметры:

newReplacement - Значение замены Новое значение замены; не должно быть null, должно иметь ненулевую длину, не должно быть длиннее значения, возвращаемого методом maxBytesPerChar, и должно быть legal

Возвращает:

Этот кодировщик

Исключения:

IllegalArgumentException - Если условия на параметре не выполняются

implReplaceWith

protected void implReplaceWith(byte[] newReplacement)

Параметры:

newReplacement - Значение замены

isLegalReplacement

public boolean isLegalReplacement(byte[] repl)

Параметры:

repl - Массив байтов, который необходимо проверить

Возвращает:

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

malformedInputAction

public CodingErrorAction malformedInputAction()

Возвращает текущее действие кодировщика для ошибок некорректного ввода.

Возвращает:

Текущее действие для ошибок некорректного ввода, которое никогда не null

onMalformedInput

public final CharsetEncoder onMalformedInput(CodingErrorAction newAction)

Параметры:

newAction - Новое действие; не должно быть null

Возвращает:

Этот кодировщик

Исключения:

IllegalArgumentException - Если условие на параметре не выполняется

implOnMalformedInput

protected void implOnMalformedInput(CodingErrorAction newAction)

Параметры:

newAction - Новое действие

unmappableCharacterAction

public CodingErrorAction unmappableCharacterAction()

Возвращает текущее действие кодировщика для ошибок неотображаемых символов.

Возвращает:

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

onUnmappableCharacter

public final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)

Параметры:

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 - Буфер входных символов

out - Буфер выходных байтов

endOfInput - true если и только если вызывающий объект не может предоставить дополнительные входные символы, помимо тех, которые находятся в заданном буфере

Возвращает:

Объект coder-result, описывающий причину завершения

Исключения:

IllegalStateException - Если операция кодирования уже выполняется, и предыдущий шаг был вызовом ни метода reset, ни этого метода со значением false для параметра endOfInput, ни этого метода со значением true для параметра endOfInput, но возвращаемое значение указывает на незавершенную операцию кодирования

CoderMalfunctionError - Если вызов метода encodeLoop вызвал непредвиденное исключение

flush

public final CoderResult flush(ByteBuffer out)

Параметры:

out - Буфер выходных байтов

Возвращает:

Объект coder-result, либо CoderResult.UNDERFLOW, либо CoderResult.OVERFLOW

Исключения:

IllegalStateException - Если предыдущий шаг текущей операции кодирования был вызовом ни метода flush, ни трехаргументного метода encode со значением true для параметра endOfInput

implFlush

protected CoderResult implFlush(ByteBuffer out)

Параметры:

out - Буфер выходных байтов

Возвращает:

Объект coder-result, либо CoderResult.UNDERFLOW, либо CoderResult.OVERFLOW

reset

public final CharsetEncoder reset()

Возвращает:

Этот кодировщик

implReset

protected void implReset()

encodeLoop

protected abstract CoderResult encodeLoop(CharBuffer in,
                                          ByteBuffer out)

Параметры:

in - Буфер входных символов

out - Буфер выходных байтов

Возвращает:

Объект coder-result, описывающий причину завершения

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)

Параметры:

c - Заданный символ

Возвращает:

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

Исключения:

IllegalStateException - Если операция кодирования уже выполняется

canEncode

public boolean canEncode(CharSequence cs)

Параметры:

cs - Заданная последовательность символов

Возвращает:

true если и только если этот кодировщик может закодировать заданную последовательность символов без выброса исключений и без выполнения каких-либо замен

Исключения:

IllegalStateException - Если операция кодирования уже выполняется