Класс CharsetDecoder

java.lang.Object

java.nio.charset.CharsetDecoder

public abstract class CharsetDecoder extends Object

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

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

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

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

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

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

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

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

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

Версия:

1.4

См. также:

Краткое описание конструкторов

CharsetDecoder(Charset cs,
 float averageCharsPerByte,
 float maxCharsPerByte)

Модификатор	Конструктор	Описание
`protected`	Инициализирует новый декодер.

Краткое описание методов

Модификатор и тип	Метод	Описание
`final float`	`averageCharsPerByte()`	Возвращает среднее количество символов, которое будет создано для каждого входного байта.
`final Charset`	`charset()`	Возвращает кодировку, создавшую этот декодер.
`final CharBuffer`	`decode(ByteBuffer in)`	Удобный метод, который декодирует оставшееся содержимое одного входного буфера байтов в новый буфер символов.
`final CoderResult`	`decode(ByteBuffer in, CharBuffer out, boolean endOfInput)`	Декодирует из заданного входного буфера максимально возможное количество байтов, записывая результат в заданный выходной буфер.
`protected abstract CoderResult`	`decodeLoop(ByteBuffer in, CharBuffer out)`	Декодирует один или несколько байтов в один или несколько символов.
`Charset`	`detectedCharset()`	Получает кодировку, определенную этим декодером (необязательная операция).
`final 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()`	Возвращает текущее действие этого декодера при ошибках некорректных входных данных.
`final float`	`maxCharsPerByte()`	Возвращает максимальное количество символов, которое будет создано для каждого входного байта.
`final CharsetDecoder`	`onMalformedInput(CodingErrorAction newAction)`	Изменяет действие этого декодера при ошибках некорректных входных данных.
`final CharsetDecoder`	`onUnmappableCharacter(CodingErrorAction newAction)`	Изменяет действие этого декодера при появлении несопоставимого символа.
`final String`	`replacement()`	Возвращает значение строки замены этого декодера.
`final CharsetDecoder`	`replaceWith(String newReplacement)`	Изменяет значение строки замены этого декодера.
`final CharsetDecoder`	`reset()`	Сбрасывает этот декодер, очищая любое внутреннее состояние.
`CodingErrorAction`	`unmappableCharacterAction()`	Возвращает текущее действие этого декодера при ошибках несопоставимых символов.

Методы, объявленные в классе Object

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

Подробное описание конструкторов

CharsetDecoder

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

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

Параметры:: cs — кодировка, создавшая этот декодер; averageCharsPerByte — положительное значение типа float, указывающее ожидаемое количество символов, создаваемых для каждого входного байта; maxCharsPerByte — положительное значение типа float, указывающее максимальное количество символов, создаваемых для каждого входного байта
Исключения:: 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 — выходной буфер символов
Возвращает:: Объект результата кодирования: 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, который интерпретирует результаты и выполняет обработку ошибок.

Этот метод возвращает объект 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 — MalformedInputException если последовательность байтов, начинающаяся с текущей позиции входного буфера, недопустима для этой кодировки, а текущее действие при некорректном вводе равно CodingErrorAction.REPORT; UnmappableCharacterException если последовательность байтов, начинающаяся с текущей позиции входного буфера, не может быть сопоставлена эквивалентной последовательности символов, а текущее действие при несопоставимом символе равно CodingErrorAction.REPORT; OutOfMemoryError — если не удается выделить выходной буфер символов для требуемого размера входного байтового буфера

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, 2025, 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/25/docs/api/java.base/java/nio/charset/CharsetDecoder.html