Класс CharsetDecoder

java.lang.Object
- java.nio.charset.CharsetDecoder

public abstract class CharsetDecoder
extends Object

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

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

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

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

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

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

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

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

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

Since:: 1.4
См. также:: ByteBuffer, CharBuffer, Charset, CharsetEncoder

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

Модификатор	Конструктор и описание
`protected`	`CharsetDecoder(Charset cs, float averageCharsPerByte, float maxCharsPerByte)` Инициализирует новый декодер.

Методы

Модификатор и тип	Метод и описание
`float`	`averageCharsPerByte()` Возвращает среднее количество символов, которое будет произведено для каждого байта входных данных.
`Charset`	`charset()` Возвращает кодировку, которая создала этот декодер.
`CharBuffer`	`decode(ByteBuffer in)` Удобный метод, который декодирует оставшееся содержимое единственного входного буфера байтов в новый буфер символов.
`CoderResult`	`decode(ByteBuffer in, CharBuffer out, boolean endOfInput)` Декодирует как можно больше байтов из данного буфера ввода, записывая результаты в данный буфер вывода.
`protected abstract CoderResult`	`decodeLoop(ByteBuffer in, CharBuffer out)` Декодирует один или более байтов в один или более символов.
`Charset`	`detectedCharset()` Возвращает кодировку, определённую этим декодером (необязательная операция).
`CoderResult`	`flush(CharBuffer out)` Очищает этот декодер.
`protected CoderResult`	`implFlush(CharBuffer out)` Очищает этот декодер.
`protected void`	`implOnMalformedInput(CodingErrorAction newAction)` Сообщает об изменении действия этого декодера для ошибок неверного ввода.
`protected void`	`implOnUnmappableCharacter(CodingErrorAction newAction)` Сообщает об изменении действия этого декодера для ошибок неотображаемых символов.
`protected void`	`implReplaceWith(String newReplacement)` Сообщает об изменении значения замены этого декодера.
`protected void`	`implReset()` Сбрасывает этот декодер, очищая любое состояние, специфичное для кодировки.
`boolean`	`isAutoDetecting()` Указывает, реализует ли этот декодер автоматическое определение кодировки.
`boolean`	`isCharsetDetected()` Указывает, определил ли этот декодер кодировку (необязательная операция).
`CodingErrorAction`	`malformedInputAction()` Возвращает текущее действие этого декодера для ошибок неверного ввода.
`float`	`maxCharsPerByte()` Возвращает максимальное количество символов, которые будут произведены для каждого байта входных данных.
`CharsetDecoder`	`onMalformedInput(CodingErrorAction newAction)` Изменяет действие этого декодера для ошибок неверного ввода.
`CharsetDecoder`	`onUnmappableCharacter(CodingErrorAction newAction)` Изменяет действие этого декодера для ошибок неотображаемых символов.
`String`	`replacement()` Возвращает значение замены этого декодера.
`CharsetDecoder`	`replaceWith(String newReplacement)` Изменяет значение замены этого декодера.
`CharsetDecoder`	`reset()` Сбрасывает этот декодер, очищая внутреннее состояние.
`CodingErrorAction`	`unmappableCharacterAction()` Возвращает текущее действие этого декодера для ошибок неотображаемых символов.

Методы, унаследованные от класса java.lang.Object

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

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

CharsetDecoder

protected CharsetDecoder(Charset cs,
                         float averageCharsPerByte,
                         float maxCharsPerByte)

Инициализирует новый декодер. Новый декодер будет иметь заданные значения символов на байт, а его замена будет строкой "\uFFFD".

Параметры:: cs - Кодировка, которая создала этот декодер; averageCharsPerByte - Положительное значение с плавающей точкой, указывающее ожидаемое количество символов, которое будет произведено для каждого входного байта; maxCharsPerByte - Положительное значение с плавающей точкой, указывающее максимальное количество символов, которое будет произведено для каждого входного байта
Исключения:: IllegalArgumentException - Если предварительные условия параметров не выполняются

Методы

charset

public final Charset charset()

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

Возвращает:: Кодировка декодера

replacement

public final String replacement()

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

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

replaceWith

public final CharsetDecoder replaceWith(String newReplacement)

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

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

Параметры:: newReplacement - Значение замены Новая замена; не должна быть null и должна иметь ненулевую длину
Возвращает:: Этот декодер
Исключения:: IllegalArgumentException - Если предварительные условия параметра не выполняются

implReplaceWith

protected void implReplaceWith(String newReplacement)

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

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

Параметры:: newReplacement - Значение замены

malformedInputAction

public CodingErrorAction malformedInputAction()

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

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

onMalformedInput

public final CharsetDecoder onMalformedInput(CodingErrorAction newAction)

Изменяет действие декодера для ошибок неверного ввода.

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

Параметры:: newAction - Новое действие; не должно быть null
Возвращает:: Этот декодер
Исключения:: IllegalArgumentException - Если условие предварительной обработки параметра не выполняется

implOnMalformedInput

protected void implOnMalformedInput(CodingErrorAction newAction)

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

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

Параметры:: newAction - Новое действие

unmappableCharacterAction

public CodingErrorAction unmappableCharacterAction()

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

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

onUnmappableCharacter

public final CharsetDecoder onUnmappableCharacter(CodingErrorAction newAction)

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

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

Параметры:: newAction - Новое действие; не должно быть null
Возвращает:: Этот декодер
Исключения:: IllegalArgumentException - Если условие предварительной обработки параметра не выполняется

implOnUnmappableCharacter

protected void implOnUnmappableCharacter(CodingErrorAction newAction)

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

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

Параметры:: newAction - Новое действие

averageCharsPerByte

public final float averageCharsPerByte()

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

Возвращает:: Среднее количество символов, производимых на каждый байт входных данных

maxCharsPerByte

public final float maxCharsPerByte()

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

Возвращает:: Максимальное количество символов, производимых на каждый байт входных данных

decode

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

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

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

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

CoderResult.UNDERFLOW указывает, что как можно больше входного буфера было декодировано. Если дальнейшего ввода нет, вызывающий метод может перейти к следующему шагу операции декодирования. В противном случае этот метод должен быть вызван снова с дополнительным вводом.
CoderResult.OVERFLOW указывает, что в буфере вывода недостаточно места для декодирования дополнительных байтов. Этот метод должен быть вызван снова с буфером вывода, имеющим больше оставшихся символов. Обычно это делается путем сброса любых декодированных символов из буфера вывода.
Результат неправильного ввода указывает, что была обнаружена ошибка неверного ввода. Неправильные байты начинаются в позиции входного буфера (возможно, сдвинутой); количество неправильных байтов можно определить, вызвав метод length объекта результата. Этот случай применяется только в том случае, если действие неправильного ввода этого декодера равно CodingErrorAction.REPORT; в противном случае неверный ввод будет проигнорирован или заменен, как требуется.
Результат неотображаемого символа указывает, что была обнаружена ошибка неотображаемого символа. Байты, декодирующие неотображаемый символ, начинаются в позиции входного буфера (возможно, сдвинутой); количество таких байтов можно определить, вызвав метод length объекта результата. Этот случай применяется только в том случае, если действие неотображаемого символа этого декодера равно CodingErrorAction.REPORT; в противном случае неотображаемый символ будет проигнорирован или заменен, как требуется.

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

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

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

Параметры:: in - Входной буфер байтов; out - Буфер вывода символов; endOfInput - true если, и только если, вызывающий метод не может предоставить дополнительные байты ввода за пределами данного буфера
Возвращает:: Объект результата кодера, описывающий причину завершения
Исключения:: IllegalStateException - Если операция декодирования уже в процессе, а предыдущий шаг был вызовом ни метода reset, ни этого метода со значением false для параметра endOfInput, ни этого метода со значением true для параметра endOfInput, но возвращаемое значение указывает на незавершенную операцию декодирования; CoderMalfunctionError - Если вызов метода decodeLoop бросил непредвиденное исключение

flush

public final CoderResult flush(CharBuffer out)

Сбрасывает этот декодер.

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

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

Если этот метод завершится успешно, то он возвращает CoderResult.UNDERFLOW. Если в буфере вывода недостаточно места, то он возвращает CoderResult.OVERFLOW. В этом случае этот метод необходимо вызвать снова с буфером вывода, имеющим больше места, чтобы завершить текущую операцию декодирования.

Если этот декодер уже был сброшен, вызов этого метода не оказывает никакого влияния.

Этот метод вызывает метод implFlush для выполнения фактической операции сброса.

Параметры:: out - Буфер символов вывода
Возвращает:: Объект результата кодера, либо CoderResult.UNDERFLOW, либо CoderResult.OVERFLOW
Выбрасывает:: IllegalStateException - Если предыдущий шаг текущей операции декодирования был вызовом ни метода flush, ни метода с тремя аргументами decode со значением true для параметра endOfInput

implFlush

protected CoderResult implFlush(CharBuffer out)

Сбрасывает этот декодер.

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

Параметры:: out - Буфер символов вывода
Возвращает:: Объект результата кодера, либо CoderResult.UNDERFLOW, либо CoderResult.OVERFLOW

reset

public final CharsetDecoder reset()

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

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

Возвращает:: Этот декодер

implReset

protected void implReset()

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

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

decodeLoop

protected abstract CoderResult decodeLoop(ByteBuffer in,
                                          CharBuffer out)

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

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

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

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

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

Параметры:: in - Буфер байтов ввода; out - Буфер символов вывода
Возвращает:: Объект результата кодера, описывающий причину завершения

decode

public final CharBuffer decode(ByteBuffer in)
                        throws CharacterCodingException

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

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

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

isAutoDetecting

public boolean isAutoDetecting()

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

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

Возвращает:: true только в том случае, если этот декодер реализует автоматическое определение кодировки

isCharsetDetected

public boolean isCharsetDetected()

Указывает, определил ли этот декодер кодировку (необязательная операция).

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

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

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

Возвращает:: true если, и только если, этот декодер определил конкретную кодировку
Выбрасывает:: UnsupportedOperationException - Если этот декодер не реализует автоматическое определение кодировки

detectedCharset

public Charset detectedCharset()

Получает кодировку, определённую этим декодером (необязательная операция).

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

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

Возвращает:: Кодировку, определенную этим декодером с автоматическим определением кодировки, или null если кодировка ещё не определена
Выбрасывает:: IllegalStateException - Если для определения кодировки не было прочитано достаточного количества байтов; UnsupportedOperationException - Если этот декодер не реализует автоматическое определение кодировки

© 1993, 2020, 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.