Интерфейс XMLStreamReader

public interface XMLStreamReader
extends XMLStreamConstants

Интерфейс XMLStreamReader предоставляет прямой, только для чтения доступ к XML. Он разработан как самый низкий и наиболее эффективный уровень для чтения данных XML.

XMLStreamReader предназначен для итерации по XML с помощью методов next() и hasNext(). Данные можно получить, используя методы, такие как getEventType(), getNamespaceURI(), getLocalName() и getText().

Метод next() заставляет читатель читать следующий парсер-событие. Метод next() возвращает целое число, определяющее тип только что считанного события.

Тип события можно определить, используя getEventType().

События парсинга определяются как объявление XML, DTD, начальный тег, символьные данные, пробелы, закрывающий тег, комментарий или инструкция обработки. Событие атрибута или пространства имен может быть встречено на корневом уровне документа в результате операции запроса.

Для соответствия XML 1.0, обработчик XML должен передавать идентификаторы объявленных необработанных сущностей, деклараций обозначений и их соответствующих идентификаторов приложению. Эта информация предоставляется через API свойств в этом интерфейсе. Следующие два свойства позволяют получить доступ к этой информации: javax.xml.stream.notations и javax.xml.stream.entities. Когда текущее событие является DTD, следующий вызов вернет список обозначений List l = (List) getProperty("javax.xml.stream.notations"); Следующий вызов вернёт список деклараций сущностей: List l = (List) getProperty("javax.xml.stream.entities"); К этим свойствам можно получить доступ только во время события DTD, и они определены для возврата null, если информация недоступна.

Следующая таблица описывает, какие методы допустимы в каком состоянии. Если метод вызывается в недопустимом состоянии, метод бросит исключение java.lang.IllegalStateException.

Допустимые методы для каждого состояния
Тип события	Допустимые методы
Все состояния	getProperty(), hasNext(), require(), close(), getNamespaceURI(), isStartElement(), isEndElement(), isCharacters(), isWhiteSpace(), getNamespaceContext(), getEventType(),getLocation(), hasText(), hasName()
START_ELEMENT	next(), getName(), getLocalName(), hasName(), getPrefix(), getAttributeXXX(), isAttributeSpecified(), getNamespaceXXX(), getElementText(), nextTag()
ATTRIBUTE	next(), nextTag() getAttributeXXX(), isAttributeSpecified(),	NAMESPACE	next(), nextTag() getNamespaceXXX()
END_ELEMENT	next(), getName(), getLocalName(), hasName(), getPrefix(), getNamespaceXXX(), nextTag()
CHARACTERS	next(), getTextXXX(), nextTag()
CDATA	next(), getTextXXX(), nextTag()
COMMENT	next(), getTextXXX(), nextTag()
SPACE	next(), getTextXXX(), nextTag()
START_DOCUMENT	next(), getEncoding(), getVersion(), isStandalone(), standaloneSet(), getCharacterEncodingScheme(), nextTag()
END_DOCUMENT	close()
PROCESSING_INSTRUCTION	next(), getPITarget(), getPIData(), nextTag()
ENTITY_REFERENCE	next(), getLocalName(), getText(), nextTag()
DTD	next(), getText(), nextTag()

Методы

getProperty

Object getProperty(String name)
            throws IllegalArgumentException

Получить значение атрибута/свойства из базовой реализации

Параметры:

name - Имя свойства, не может быть null

Возвращает:

Значение свойства

Исключение:

IllegalArgumentException - если имя равно null

next

int next()
  throws XMLStreamException

Возвращает:

целочисленный код, соответствующий текущему событию парсинга

Исключение:

NoSuchElementException - если это вызов, когда hasNext() возвращает false

XMLStreamException - если при обработке базового XML-источника произошла ошибка

См. также:

XMLEvent

require

void require(int type,
             String namespaceURI,
             String localName)
      throws XMLStreamException

Проверка, является ли текущее событие заданного типа, и совпадают ли пространство имён и имя с текущим пространством имён и имен текущего события. Если namespaceURI равно null, оно не проверяется на равенство; если localName равно null, оно не проверяется на равенство.

Параметры:

type - тип события

namespaceURI - uri события, может быть null

localName - localName события, может быть null

Исключение:

XMLStreamException - если требуемые значения не совпадают.

getElementText

String getElementText()
               throws XMLStreamException

Считывает содержимое элемента, содержащего только текст; если это не элемент, содержащий только текст, выбрасывается исключение. Независимо от значения javax.xml.stream.isCoalescing этот метод всегда возвращает объединённое содержимое.
Предварительное условие: текущее событие — START_ELEMENT.
Последовательное условие: текущее событие — соответствующий END_ELEMENT.
Метод выполняет следующее (реализации могут оптимизировать, но должны выполнить эквивалентную обработку):

if(getEventType() != XMLStreamConstants.START_ELEMENT) {
 throw new XMLStreamException(
 "parser must be on START_ELEMENT to read next text", getLocation());
 }
 int eventType = next();
 StringBuffer content = new StringBuffer();
 while(eventType != XMLStreamConstants.END_ELEMENT ) {
 if(eventType == XMLStreamConstants.CHARACTERS
 || eventType == XMLStreamConstants.CDATA
 || eventType == XMLStreamConstants.SPACE
 || eventType == XMLStreamConstants.ENTITY_REFERENCE) {
 buf.append(getText());
 } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
 || eventType == XMLStreamConstants.COMMENT) {
 // skipping
 } else if(eventType == XMLStreamConstants.END_DOCUMENT) {
 throw new XMLStreamException(
 "unexpected end of document when reading element text content", this);
 } else if(eventType == XMLStreamConstants.START_ELEMENT) {
 throw new XMLStreamException(
 "element text content may not contain START_ELEMENT", getLocation());
 } else {
 throw new XMLStreamException(
 "Unexpected event type "+eventType, getLocation());
 }
 eventType = next();
 }
 return buf.toString();

Исключение:

XMLStreamException - если текущее событие не START_ELEMENT или если встречен элемент, не содержащий только текст

nextTag

int nextTag()
     throws XMLStreamException

Пропускает все пробелы (isWhiteSpace() возвращает true), комментарии (COMMENT) или инструкции обработки (PROCESSING_INSTRUCTION), пока не будет достигнут START_ELEMENT или END_ELEMENT. Если встречено что-либо кроме пробелов, комментариев, инструкций обработки, START_ELEMENT или END_ELEMENT, выбрасывается исключение. Этот метод следует использовать при обработке содержимого только элементов, разделённого пробелами.
Предварительное условие: нет
Последовательное условие: текущее событие — START_ELEMENT или END_ELEMENT, и курсор может переместиться над любым событием пробела.
В сущности, он выполняет следующее (реализации могут оптимизировать, но должны выполнить эквивалентную обработку):

int eventType = next();
 while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) // skip whitespace
 || (eventType == XMLStreamConstants.CDATA && isWhiteSpace())
 // skip whitespace
 || eventType == XMLStreamConstants.SPACE
 || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
 || eventType == XMLStreamConstants.COMMENT
 ) {
 eventType = next();
 }
 if (eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT) {
 throw new String XMLStreamException("expected start or end tag", getLocation());
 }
 return eventType;

Возвращает:

тип события элемента, прочитанного (START_ELEMENT или END_ELEMENT)

Исключение:

XMLStreamException - если текущее событие не пробел, инструкция обработки, START_ELEMENT или END_ELEMENT

NoSuchElementException - если этот метод вызван, когда hasNext() возвращает false

hasNext

boolean hasNext()
         throws XMLStreamException

Возвращает true, если есть больше событий парсинга, и false, если больше событий нет. Этот метод вернёт false, если текущее состояние XMLStreamReader — END_DOCUMENT

Возвращает:

true, если есть больше событий, false в противном случае

Исключение:

XMLStreamException - если возникла критическая ошибка при обнаружении следующего состояния

close

void close()
    throws XMLStreamException

Освобождает все ресурсы, связанные с этим чтецом. Этот метод не закрывает базовый источник ввода.

Исключение:

XMLStreamException - если при освобождении связанных ресурсов произошли ошибки

getNamespaceURI

String getNamespaceURI(String prefix)

Параметры:

prefix - Префикс для поиска, не может быть null

Возвращает:

uri, привязанный к заданному префиксу, или null, если он не привязан

Исключение:

IllegalArgumentException - если префикс равен null

isStartElement

boolean isStartElement()

Возвращает true, если курсор указывает на открывающий тег (в противном случае false)

Возвращает:

true, если курсор указывает на открывающий тег, false в противном случае

isEndElement

boolean isEndElement()

Возвращает true, если курсор указывает на закрывающий тег (в противном случае false)

Возвращает:

true, если курсор указывает на закрывающий тег, false в противном случае

isCharacters

boolean isCharacters()

Возвращает true, если курсор указывает на событие данных символов

Возвращает:

true, если курсор указывает на данные символов, false в противном случае

isWhiteSpace

boolean isWhiteSpace()

Возвращает true, если курсор указывает на событие данных символов, состоящее только из пробелов

Возвращает:

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

getAttributeValue

String getAttributeValue(String namespaceURI,
                         String localName)

Возвращает нормализованное значение атрибута с указанным пространством имен и локальным именем. Если namespaceURI равно null, пространство имен не проверяется на равенство.

Параметры:

namespaceURI - пространство имен атрибута

localName - локальное имя атрибута, не может быть null

Возвращает:

возвращает значение атрибута; возвращает null, если не найдено

Исключение:

IllegalStateException - если это не START_ELEMENT или ATTRIBUTE

getAttributeCount

int getAttributeCount()

Возвращает количество атрибутов в этом START_ELEMENT; этот метод действителен только для START_ELEMENT или ATTRIBUTE. Это количество не включает определения пространств имён. Индексы атрибутов нумеруются с нуля.

Возвращает:

возвращает количество атрибутов

Исключение:

IllegalStateException - если это не START_ELEMENT или ATTRIBUTE

getAttributeName

QName getAttributeName(int index)

Возвращает qname атрибута по указанному индексу

Параметры:

index - позиция атрибута

Возвращает:

QName атрибута

Исключение:

IllegalStateException - если это не START_ELEMENT или ATTRIBUTE

getAttributeNamespace

String getAttributeNamespace(int index)

Возвращает пространство имен атрибута по указанному индексу

Параметры:

index - позиция атрибута

Возвращает:

URI пространства имён (может быть null)

Исключение:

IllegalStateException - если это не START_ELEMENT или ATTRIBUTE

getAttributeLocalName

String getAttributeLocalName(int index)

Возвращает локальное имя атрибута по указанному индексу

Параметры:

index - позиция атрибута

Возвращает:

локальное имя атрибута

Исключение:

IllegalStateException - если это не START_ELEMENT или ATTRIBUTE

getAttributePrefix

String getAttributePrefix(int index)

Возвращает префикс этого атрибута по указанному индексу

Параметры:

index - позиция атрибута

Возвращает:

префикс атрибута

Исключение:

IllegalStateException - если это не START_ELEMENT или ATTRIBUTE

getAttributeType

String getAttributeType(int index)

Возвращает XML-тип атрибута по указанному индексу

Параметры:

index - позиция атрибута

Возвращает:

XML-тип атрибута

Исключение:

IllegalStateException - если это не START_ELEMENT или ATTRIBUTE

getAttributeValue

String getAttributeValue(int index)

Возвращает значение атрибута по индексу

Параметры:

index - позиция атрибута

Возвращает:

значение атрибута

Исключение:

IllegalStateException - если это не START_ELEMENT или ATTRIBUTE

isAttributeSpecified

boolean isAttributeSpecified(int index)

Возвращает логическое значение, указывающее, был ли этот атрибут создан по умолчанию

Параметры:

index - позиция атрибута

Возвращает:

true, если это атрибут по умолчанию

Исключение:

IllegalStateException - если это не START_ELEMENT или ATTRIBUTE

getNamespaceCount

int getNamespaceCount()

Возвращает количество пространств имён, объявленных в этом START_ELEMENT или END_ELEMENT; этот метод действителен только для START_ELEMENT, END_ELEMENT или NAMESPACE. В END_ELEMENT счёт ведётся для пространств имён, которые вот-вот выйдут из области видимости. Это эквивалентно информации, сообщённой обратным вызовом SAX для события завершения элемента.

Возвращает:

возвращает количество объявлений пространств имён для этого элемента

Исключение:

IllegalStateException - если это не START_ELEMENT, END_ELEMENT или NAMESPACE

getNamespacePrefix

String getNamespacePrefix(int index)

Возвращает префикс для пространства имён, объявленного по указанному индексу. Возвращает null, если это объявление по умолчанию.

Параметры:

index - позиция объявления пространства имён

Возвращает:

префикс пространства имён

Исключения:

IllegalStateException - если это не элемент START_ELEMENT, END_ELEMENT или NAMESPACE

getNamespaceURI

String getNamespaceURI(int index)

Возвращает URI для пространства имён, объявленного по указанному индексу.

Параметры:

index - позиция объявления пространства имён

Возвращает:

URI пространства имён

Исключения:

IllegalStateException - если это не элемент START_ELEMENT, END_ELEMENT или NAMESPACE

getNamespaceContext

NamespaceContext getNamespaceContext()

Возвращает контекст пространства имён для текущей позиции. Контекст является транзиентным и действителен только до вызова метода next(), изменяющего состояние ридера.

Возвращает:

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

getEventType

int getEventType()

Возвращает целовый код, указывающий тип события, к которому указывает курсор.

getText

String getText()

Возвращает текущее значение события парсинга в виде строки. Возвращает строковое значение события CHARACTERS, значение комментария, значение замены для ENTITY_REFERENCE, строковое значение раздела CDATA, строковое значение для события SPACE или строковое значение внутреннего подмножества DTD. Если ENTITY_REFERENCE был разрешен, все символьные данные будут сообщаться как события CHARACTERS.

Возвращает:

текущий текст или null

Исключения:

IllegalStateException - если состояние не является допустимым состоянием текста.

getTextCharacters

char[] getTextCharacters()

Возвращает массив, содержащий символы из этого события. К этому массиву следует относиться как к неизменяемому и транзиентному. То есть, массив будет содержать символы текста, пока XMLStreamReader не перейдёт к следующему событию. Попытки удержания массива символов после этого момента или изменения его содержимого нарушают договор об этом интерфейсе.

Возвращает:

текущий текст или пустой массив

Исключения:

IllegalStateException - если состояние не является допустимым состоянием текста.

getTextCharacters

int getTextCharacters(int sourceStart,
                      char[] target,
                      int targetStart,
                      int length)
               throws XMLStreamException

Получает текст, связанный с событием CHARACTERS, SPACE или CDATA. Текст, начиная с "sourceStart", копируется в "target" начиная с "targetStart". Копируется до "length" символов. Возвращается количество скопированных символов. Аргумент "sourceStart" должен быть больше или равен 0 и меньше или равен количеству символов, связанных с событием. Обычно запрашивается текст, начинающийся с "sourceStart" равным 0. Если количество скопированных символов меньше "length", то больше текста нет. В противном случае необходимо делать последующие вызовы, пока весь текст не будет извлечён. Например: int length = 1024; char[] myBuffer = new char[ length ]; for ( int sourceStart = 0 ; ; sourceStart += length ) { int nCopied = stream.getTextCharacters( sourceStart, myBuffer, 0, length ); if (nCopied < length) break; } XMLStreamException может быть выброшен, если в исходном источнике есть ошибки XML. Аргумент "targetStart" должен быть больше или равен 0 и меньше длины "target". Длина должна быть больше 0, и "targetStart + length" должна быть меньше или равна длине "target".

Параметры:

sourceStart - индекс первого символа в исходном массиве для копирования

target - целевой массив

targetStart - начальный смещение в целевом массиве

length - количество символов для копирования

Возвращает:

количество скопированных символов

Исключения:

XMLStreamException - если исходный источник XML не имеет правильной структуры

IndexOutOfBoundsException - если targetStart < 0 или > длины target

IndexOutOfBoundsException - если length < 0 или targetStart + length > длины target

UnsupportedOperationException - если этот метод не поддерживается

NullPointerException - если target равно null

getTextStart

int getTextStart()

Возвращает смещение в массиве символов текста, где хранится первый символ (этого события текста).

Исключения:

IllegalStateException - если состояние не является допустимым состоянием текста.

getTextLength

int getTextLength()

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

Исключения:

IllegalStateException - если состояние не является допустимым состоянием текста.

getEncoding

String getEncoding()

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

Возвращает:

кодировку этого экземпляра или null

hasText

boolean hasText()

Возвращает true, если текущее событие имеет текст, иначе false. Следующие события имеют текст: CHARACTERS, DTD, ENTITY_REFERENCE, COMMENT, SPACE

getLocation

Location getLocation()

Возвращает текущее расположение процессора. Если расположение неизвестно, процессор должен вернуть реализацию Location, возвращающую -1 для расположения и null для publicId и systemId. Информация о расположении действительна только до вызова next().

getName

QName getName()

Возвращает QName для текущего события START_ELEMENT или END_ELEMENT.

Возвращает:

QName для текущего события START_ELEMENT или END_ELEMENT

Исключения:

IllegalStateException - если это не START_ELEMENT или END_ELEMENT

getLocalName

String getLocalName()

Возвращает (локальное) имя текущего события. Для START_ELEMENT или END_ELEMENT возвращает (локальное) имя текущего элемента. Для ENTITY_REFERENCE возвращает имя сущности. Текущее событие должно быть START_ELEMENT, END_ELEMENT или ENTITY_REFERENCE.

Возвращает:

локальное имя

Исключения:

IllegalStateException - если это не START_ELEMENT, END_ELEMENT или ENTITY_REFERENCE

hasName

boolean hasName()

Возвращает true, если текущее событие имеет имя (является START_ELEMENT или END_ELEMENT), иначе false.

getNamespaceURI

String getNamespaceURI()

Если текущее событие является START_ELEMENT или END_ELEMENT, этот метод возвращает URI префикса или пространства имён по умолчанию. Возвращает null, если событие не имеет префикса.

Возвращает:

URI, связанный с префиксом этого элемента, пространством имён по умолчанию или null

getPrefix

String getPrefix()

Возвращает префикс текущего события или null, если событие не имеет префикса.

Возвращает:

префикс или null

getVersion

String getVersion()

Возвращает версию XML, объявленную в объявлении XML. Возвращает null, если она не была объявлена.

Возвращает:

версия XML или null

isStandalone

boolean isStandalone()

Возвращает объявление standalone из объявления XML.

Возвращает:

true, если это автономное, или false в противном случае

standaloneSet

boolean standaloneSet()

Проверяет, было ли установлено standalone в документе.

Возвращает:

true, если standalone было установлено в документе, или false в противном случае

getCharacterEncodingScheme

String getCharacterEncodingScheme()

Возвращает кодировку символов, объявленную в объявлении XML. Возвращает null, если она не была объявлена.

Возвращает:

кодировка, объявленная в документе, или null

getPITarget

String getPITarget()

Возвращает целевой элемент инструкции обработки.

Возвращает:

цель или null

getPIData

String getPIData()

Возвращает раздел данных инструкции обработки.

Возвращает:

данные или null