Класс CharsetDecoder

public abstract class CharsetDecoder
extends Object

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

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

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

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

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

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

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

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

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

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

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

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

Since:
1.4
See Also:
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, должна иметь ненулевую длину и не должна быть длиннее значения, возвращаемого методом maxCharsPerByte
Возвращает:
Этот декодер
Исключения:
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 - Буфер вывода символов
Возвращает:
Объект coder-result, либо CoderResult.UNDERFLOW, либо CoderResult.OVERFLOW
Выбрасывает:
IllegalStateException - Если предыдущий шаг текущей операции декодирования был вызовом ни метода flush, ни метода с тремя аргументами decode со значением true для параметра endOfInput

implFlush

protected CoderResult implFlush(CharBuffer out)

Очищает этот декодер.

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

Параметры:
out - Буфер вывода символов
Возвращает:
Объект coder-result, либо 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 - Буфер вывода символов
Возвращает:
Объект coder-result, описывающий причину завершения

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.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/charset/CharsetDecoder.html

Spec-Zone .ru
спецификации, руководства, описания, API