Используя StAX

Вообще, программисты StAX создают потоковых читателей XML, писателей, и события при использовании XMLInputFactory, XMLOutputFactory, и классов XMLEventFactory. Конфигурация делается, устанавливая свойства на фабриках, посредством чего специфичные для реализации настройки можно передать к базовой реализации, используя метод setProperty на фабриках. Точно так же специфичные для реализации настройки могут быть запрошены, используя метод фабрики getProperty.

XMLInputFactory, XMLOutputFactory, и классы XMLEventFactory описываются ниже, сопровождаются обсуждениями распределения ресурсов, пространства имен и приписывают управление, обработку ошибок, и затем наконец читающие и пишущие потоки, используя курсор и iterator API.

Классы Фабрики StAX

Классы фабрики StAX. XMLInputFactory, XMLOutputFactory, и XMLEventFactory, позволял Вам определять и конфигурировать экземпляры реализации потокового читателя XML, потокового писателя, и классов событий.

XMLInputFactory

XMLInputFactory class позволяет Вам конфигурировать экземпляры реализации потоковых процессоров читателя XML, создаваемых фабрикой. Новые экземпляры абстрактного class XMLInputFactory создаются, вызывая метод newInstance на class. Статический метод XMLInputFactory.newInstance тогда используется, чтобы создать новый экземпляр фабрики.

Происходя из JAXP, метод XMLInputFactory.newInstance определяет определенную реализацию XMLInputFactory class, чтобы загрузиться при использовании следующей процедуры поиска:

1. Используйте системное свойство javax.xml.stream.XMLInputFactory.

2. Используйте файл lib/xml.stream.properties в Java среда выполнения Java платформы SE (JRE) каталог.

3. Используйте API Служб, при наличии, чтобы определить имя класса, смотря в файлах META-INF/services/javax.xml.stream.XMLInputFactory в файлах JAR, доступных JRE.

4. Используйте значение по умолчанию платформы экземпляр XMLInputFactory.

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

Таблица: Свойства javax.xml.stream.XMLInputFactory

XMLOutputFactory

Новые экземпляры абстрактного class XMLOutputFactory создаются, вызывая метод newInstance на class. Статический метод XMLOutputFactory.newInstance тогда используется, чтобы создать новый экземпляр фабрики. Алгоритм, используемый, чтобы получить экземпляр, является тем же самым что касается XMLInputFactory, но ссылается на системное свойство javax.xml.stream.XMLOutputFactory.

XMLOutputFactory поддерживает только одно свойство, javax.xml.stream.isRepairingNamespaces. Это свойство требуется, и его цель состоит в том, чтобы создать префиксы значения по умолчанию и связать их с URI Пространства имен. См. спецификацию StAX для получения дополнительной информации.

XMLEventFactory

Новые экземпляры абстрактного class XMLEventFactory создаются, вызывая метод newInstance на class. Статический метод XMLEventFactory.newInstance тогда используется, чтобы создать новый экземпляр фабрики. Эта фабрика ссылается на свойство javax.xml.stream.XMLEventFactory, чтобы инстанцировать фабрики. Алгоритм, используемый, чтобы получить экземпляр, является тем же самым что касается XMLInputFactory и XMLOutputFactory, но ссылается на системное свойство javax.xml.stream.XMLEventFactory.

Нет никаких свойств значения по умолчанию для XMLEventFactory.

Ресурсы, Пространства имен, и Ошибки

Спецификация StAX обрабатывает разрешение ресурса, атрибуты и пространство имен, и ошибки и исключения как описано ниже.

Разрешение ресурса

Интерфейс XMLResolver обеспечивает средство установить метод, который разрешает ресурсы во время обработки XML. Приложение устанавливает интерфейс на XMLInputFactory, который тогда устанавливает интерфейс на всех процессорах, создаваемых тем экземпляром фабрики.

Атрибуты и Пространства имен

Об атрибутах сообщает процессор StAX, используя методы поиска и строки в интерфейсе курсора, и события Attribute И Namespace в интерфейсе iterator. Отметьте здесь, что пространства имен обрабатываются как атрибуты, хотя о пространствах имен сообщают отдельно от атрибутов и в курсоре и в iterator API. Отметьте также, что обработка пространства имен является дополнительной для процессоров StAX. См. спецификацию StAX для полной информации о привязке пространства имен и дополнительной обработке пространства имен.

Сообщение об ошибке и Обработка исключений

Обо всех фатальных ошибках сообщают посредством интерфейса javax.xml.stream.XMLStreamException. Обо всех нефатальных ошибках и предупреждениях сообщают, используя интерфейс javax.xml.stream.XMLReporter.

Чтение XML Потоки

Как описано ранее в этом уроке, способ, которым Вы читаете потоки XML с процессором StAX — и что еще более важно, что Вы возвращаете — изменяется значительно в зависимости от того, используете ли Вы API курсора StAX или событие iterator API. Следующие два раздела описывают, как считать потоки XML с каждым из этих API.

Используя XMLStreamReader

Интерфейс XMLStreamReader в API курсора StAX позволяет Вам читать потоки XML или документы в прямом направлении только, одном элементе в инфонаборе за один раз. Следующие методы доступны для того, чтобы вытянули данные от потока или пропустили нежелательные события:

• Получите значение атрибута

• Считайте контент XML

• Определите, имеет ли элемент контент или пуст

• Получите индексный доступ к набору атрибутов

• Получите индексный доступ к набору пространств имен

• Получите имя текущего события (если применимый)

• Получите контент текущего события (если применимый)

У экземпляров XMLStreamReader есть в любой момент единственное текущее событие, на котором работают его методы. Когда Вы создаете экземпляр XMLStreamReader на потоке, начальное текущее событие является состоянием START_DOCUMENT. Метод XMLStreamReader.next может тогда использоваться, чтобы ступить в следующее событие в потоке.

Чтение Свойств, Атрибутов, и Пространств имен

Метод XMLStreamReader.next загружает свойства следующего события в потоке. Можно тогда получить доступ к тем свойствам, вызывая методы XMLStreamReader.getLocalName И XMLStreamReader.getText.

Когда курсор XMLStreamReader по событию StartElement, он читает имя и любые атрибуты для события, включая пространство имен. Ко всем атрибутам для события можно получить доступ, используя индексировать значение, и могут также искаться URI пространства имен и локальным именем. Отметьте, однако, что только пространства имен, объявленные на текущем StartEvent, доступны; ранее объявленные пространства имен не сохраняются, и повторно объявленные пространства имен не удаляются.

Методы XMLStreamReader

XMLStreamReader обеспечивает следующие методы для того, чтобы они получили информацию о пространствах имен и атрибутах:

int getAttributeCount();
String getAttributeNamespace(int index);
String getAttributeLocalName(int index);
String getAttributePrefix(int index);
String getAttributeType(int index);
String getAttributeValue(int index);
String getAttributeValue(String namespaceUri, String localName);
boolean isAttributeSpecified(int index);

К пространствам имен можно также получить доступ, используя три дополнительных метода:

int getNamespaceCount();
String getNamespacePrefix(int index);
String getNamespaceURI(int index);

Инстанцирование XMLStreamReader

Этот пример, взятый от спецификации StAX, шоу, как инстанцировать входной фабрики, создает читателя, и выполняет итерации по элементам потока XML:

XMLInputFactory f = XMLInputFactory.newInstance();
XMLStreamReader r = f.createXMLStreamReader( ... );
while(r.hasNext()) {
    r.next();
}

Используя XMLEventReader

API XMLEventReader в событии StAX iterator API обеспечивает средства отобразить события в потоке XML к выделенным объектам-событиям, которые могут быть свободно снова использованы, и сам API может быть расширен, чтобы обработать пользовательские события.

XMLEventReader обеспечивает четыре метода для того, чтобы они многократно проанализировали потоки XML:

• next: Возвращает следующее событие в потоке

• nextEvent: Возвращается следующее вводило XMLEvent

• hasNext: Возвращает true, если есть больше событий, чтобы обработать в потоке

• peek: Возвращает событие, но не выполняет итерации к следующему событию

Например, следующий фрагмент кода иллюстрирует объявления метода XMLEventReader:

package javax.xml.stream;
import java.util.Iterator;

public interface XMLEventReader extends Iterator {
    public Object next();
    public XMLEvent nextEvent() throws XMLStreamException;
    public boolean hasNext();
    public XMLEvent peek() throws XMLStreamException;
    // ...
}

Чтобы считать все события на потоке и затем напечатать их, Вы могли использовать следующее:

while(stream.hasNext()) {
    XMLEvent event = stream.nextEvent();
    System.out.print(event);
}

Чтение Атрибутов

Можно получить доступ к атрибутам от их связанного javax.xml.stream.StartElement, следующим образом:

public interface StartElement extends XMLEvent {
    public Attribute getAttributeByName(QName name);
    public Iterator getAttributes();
}

Можно использовать метод getAttributes в интерфейсе StartElement, чтобы использовать Iterator по всем атрибутам, объявленным на том StartElement.

Чтение Пространств имен

Подобный чтению атрибутов, пространства имен читаются, используя Iterator, создаваемый, вызывая метод getNamespaces в интерфейсе StartElement. Только пространство имен для текущего StartElement возвращается, и приложение может получить текущий контекст пространства имен при использовании StartElement.getNamespaceContext.

Запись XML Потоки

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

Используя XMLStreamWriter

Интерфейс XMLStreamWriter в API курсора StAX позволяет приложениям записывать обратно к потоку XML или создавать полностью новые потоки. У XMLStreamWriter есть методы, которые позволяют Вам:

• Запишите правильно построенный XML

• Сбросьте или закройте вывод

• Запишите полностью определенные имена

Отметьте, что реализации XMLStreamWriter не обязаны выполнять отмеченность или проверки достоверности на вводе. В то время как некоторые реализации могут выполнить строгую проверку на ошибки, другие не могут. Правила, которые Вы реализуете, применяются к свойствам, определенным в XMLOutputFactory class.

Метод writeCharacters привык к символам ESC, таким как &, <, >, и ". Обязательные префиксы могут быть обработаны или передачей фактического значения для префикса, при использовании метода setPrefix, или устанавливая свойство для принимающих значение по умолчанию объявлений пространства имен.

Следующий пример, взятый от спецификации StAX, шоу, как инстанцировать выходной фабрики, создает писателя, и вывод XML записи:

XMLOutputFactory output = XMLOutputFactory.newInstance();
XMLStreamWriter writer = output.createXMLStreamWriter( ... );

writer.writeStartDocument();
writer.setPrefix("c","http://c");
writer.setDefaultNamespace("http://c");

writer.writeStartElement("http://c","a");
writer.writeAttribute("b","blah");
writer.writeNamespace("c","http://c");
writer.writeDefaultNamespace("http://c");

writer.setPrefix("d","http://c");
writer.writeEmptyElement("http://c","d");
writer.writeAttribute("http://c", "chris","fry");
writer.writeNamespace("d","http://c");
writer.writeCharacters("Jean Arp");
writer.writeEndElement();

writer.flush();

Этот код генерирует следующий XML (новые строки ненормативны):

<?xml version=’1.0’ encoding=’utf-8’?>
<a b="blah" xmlns:c="http://c" xmlns="http://c">
<d:d d:chris="fry" xmlns:d="http://c"/>Jean Arp</a>

Используя XMLEventWriter

Интерфейс XMLEventWriter в событии StAX iterator API позволяет приложениям записывать обратно к потоку XML или создавать полностью новые потоки. Этот API может быть расширен, но основной API следующие:

public interface XMLEventWriter {
    public void flush() throws XMLStreamException;
    public void close() throws XMLStreamException;
    public void add(XMLEvent e) throws XMLStreamException;
    // ... other methods not shown.
}

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

Атрибуты, Выходя из Символов, Связывая Префиксы

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

Можно использовать метод Characters для символов ESC как &, <, >, и ".

Метод setPrefix(...) может использоваться, чтобы явно связать префикс для использования во время вывода, и метод getPrefix(...) может использоваться, чтобы получить текущий префикс. Отметьте, что по умолчанию, XMLEventWriter добавляет привязку пространства имен к своей внутренней карте пространства имен. Префиксы выходят из контекста после соответствующего EndElement для события, в котором они связываются.