java.nio.charset

Класс CharsetEncoder

java.lang. Объект

java.nio.charset. CharsetEncoder

public abstract class CharsetEncoder
extends Object

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

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

1. Сбросьте кодер через reset метод, если это не использовалось прежде;

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

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

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

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

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

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

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

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

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

С тех пор:

1.4

См. Также:

ByteBuffer, CharBuffer, Charset, CharsetDecoder

Сводка конструктора

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

Модификатор	Конструктор и Описание
protected	CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar) Инициализирует новый кодер.
protected	CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement) Инициализирует новый кодер.

Сводка метода

Методы

Модификатор и Тип	Метод и Описание
float	averageBytesPerChar() Возвращает среднее число байтов, которые будут произведены для каждого символа ввода.
boolean	canEncode(char c) Говорит, может ли этот кодер закодировать данный символ.
boolean	canEncode(CharSequence cs) Говорит, может ли этот кодер закодировать данную символьную последовательность.
Набор символов	charset() Возвращает набор символов, который создал этот кодер.
ByteBuffer	encode(CharBuffer in) Метод удобства, который кодирует остающийся контент единственного входного буфера символа в недавно выделенный буфер байта.
CoderResult	encode(CharBuffer in, ByteBuffer out, boolean endOfInput) Кодирует так много символов насколько возможно от данного входного буфера, пишущий результаты в данный буфер вывода.
protected abstract CoderResult	encodeLoop(CharBuffer in, ByteBuffer out) Кодирует один или более символов в один или более байтов.
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() Возвраты текущее действие этого кодера для ошибок уродливого ввода.
float	maxBytesPerChar() Возвращает максимальное количество байтов, которые будут произведены для каждого символа ввода.
CharsetEncoder	onMalformedInput(CodingErrorAction newAction) Изменения действие этого кодера для ошибок уродливого ввода.
CharsetEncoder	onUnmappableCharacter(CodingErrorAction newAction) Изменения действие этого кодера для неотображаемо-символьных ошибок.
byte[]	replacement() Возвраты заменяющее значение этого кодера.
CharsetEncoder	replaceWith(byte[] newReplacement) Изменения заменяющее значение этого кодера.
CharsetEncoder	reset() Сбросы этот кодер, очищая любое внутреннее состояние.
CodingErrorAction	unmappableCharacterAction() Возвраты текущее действие этого кодера для неотображаемо-символьных ошибок.

Методы java.lang унаследованный от класса. Объект

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Деталь конструктора

CharsetEncoder

protected CharsetEncoder(Charset cs,
              float averageBytesPerChar,
              float maxBytesPerChar,
              byte[] replacement)

Инициализирует новый кодер. У нового кодера будут данные байты на случайную работу и заменяющие значения.

Параметры:

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

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

replacement - Начальная замена; не должен быть null, должен иметь ненулевую длину, не должен быть более длинным чем maxBytesPerChar, и должен быть законный

Броски:

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

CharsetEncoder

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

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

Параметры:

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

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

Броски:

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

Деталь метода

набор символов

public final Charset charset()

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

Возвраты:

Набор символов этого кодера

замена

public final byte[] replacement()

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

Возвраты:

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

replaceWith

public final CharsetEncoder replaceWith(byte[] newReplacement)

Изменения заменяющее значение этого кодера.

Этот метод вызывает implReplaceWith метод, передавая новую замену, после проверки, что новая замена является приемлемой.

Параметры:

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

Возвраты:

Этот кодер

Броски:

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

implReplaceWith

protected void implReplaceWith(byte[] newReplacement)

Сообщает изменение заменяющему значению этого кодера.

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

Параметры:

newReplacement -

isLegalReplacement

public boolean isLegalReplacement(byte[] repl)

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

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

Сообщает изменение действию уродливого ввода этого кодера.

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

unmappableCharacterAction

public CodingErrorAction unmappableCharacterAction()

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

Возвраты:

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

onUnmappableCharacter

public final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)

Изменения действие этого кодера для неотображаемо-символьных ошибок.

Этот метод вызывает implOnUnmappableCharacter метод, передавая новое действие.

Параметры:

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

Возвраты:

Этот кодер

Броски:

IllegalArgumentException - Если предварительное условие на параметре не содержит

implOnUnmappableCharacter

protected void implOnUnmappableCharacter(CodingErrorAction newAction)

Сообщает изменение неотображаемо-символьному действию этого кодера.

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

averageBytesPerChar

public final float averageBytesPerChar()

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

Возвраты:

Среднее число байтов производится на символ ввода

maxBytesPerChar

public final float maxBytesPerChar()

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

Возвраты:

Максимальное количество байтов, которые будут произведены на символ ввода

закодировать

public final CoderResult encode(CharBuffer in,
                 ByteBuffer out,
                 boolean endOfInput)

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

Буферы читаются из, и пишутся, запускаясь в их текущих позициях. Самое большее in.remaining() символы будут считаны и самое большее out.remaining() байты будут записаны. Позиции буферов будут усовершенствованы, чтобы отразить чтение символов и записанные байты, но их метки и пределы не будут изменены.

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

• CoderResult.UNDERFLOW указывает, что так много входного буфера насколько возможно было закодировано. Если есть не далее ввод тогда, invoker может продолжиться к следующему шагу работы кодирования. Иначе этот метод должен быть вызван снова с дальнейшим вводом.

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

• A уродливый ввод результат указывает, что ошибка уродливого ввода была обнаружена. Уродливые символы начинают во входном буфере (возможно постепенно увеличенный) позицию; число уродливых символов может быть определено, вызывая объект результата length метод. Этот случай применяется только если уродливое действие из этого кодера CodingErrorAction.REPORT; иначе уродливый ввод будет проигнорирован или заменен, согласно просьбе.

• неотображаемо-символьный результат указывает, что была обнаружена неотображаемо-символьная ошибка. Символы, которые кодируют неотображаемый символ, начинают во входном буфере (возможно постепенно увеличенный) позицию; число таких символов может быть определено, вызывая объект результата length метод. Этот случай применяется только если неотображаемое действие из этого кодера CodingErrorAction.REPORT; иначе неотображаемый символ будет проигнорирован или заменен, согласно просьбе.

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

Параметр endOfInput советует этому методу относительно того, может ли invoker обеспечить далее ввод, кроме того содержавшийся в данном входном буфере. Если есть возможность обеспечения дополнительного ввода тогда, invoker должен передать false для этого параметра; если нет никакой возможности обеспечения дальнейшего ввода тогда, invoker должен передать true. Это не ошибочно, и фактически это довольно распространено, чтобы передать false в одном вызове и позже обнаружить, что никакой дальнейший ввод не был фактически доступен. Является критическим, однако, что заключительный вызов этого метода в последовательности вызовов всегда передает true так, чтобы любой остающийся незакодированный ввод был обработан как являющийся уродливым.

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

Параметры:

in - Входной буфер символа

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

endOfInput - true, если, и только если, invoker не может обеспечить дополнительные входные символы вне тех в данном буфере

Возвраты:

Объект результата кодера описание причины завершения

Броски:

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

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

сброс

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

сброс

public final CharsetEncoder reset()

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

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

Возвраты:

Этот кодер

implReset

protected void implReset()

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

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

encodeLoop

protected abstract CoderResult encodeLoop(CharBuffer in,
                     ByteBuffer out)

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

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

Буферы читаются из, и пишутся, запускаясь в их текущих позициях. Самое большее in.remaining() символы будут считаны, и самое большее out.remaining() байты будут записаны. Позиции буферов будут усовершенствованы, чтобы отразить чтение символов и записанные байты, но их метки и пределы не будут изменены.

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

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

Параметры:

in - Входной буфер символа

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

Возвраты:

Объект результата кодера описание причины завершения

закодировать

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

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

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

Возвраты:

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

Броски:

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

canEncode

public boolean canEncode(CharSequence cs)

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

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

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

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

Возвраты:

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

Броски:

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