## org.dom4j.io
Class STAXEventReader

    java.lang.Object
      org.dom4j.io.STAXEventReader

public class STAXEventReader
extends Object

Reads a DOM4J `Document`, as well as other `Node`s, from a StAX `XMLEventReader`.

Author:
  Christian Niles

Constructor Summary
`STAXEventReader()` Constructs a default `STAXEventReader` instance with a default `DocumentFactory`.
`STAXEventReader(DocumentFactory factory)` Constructs a `STAXEventReader` instance that uses the specified `DocumentFactory`to construct DOM4J `Node`s.

Method Summary
`Attribute` `createAttribute(Element elem, javax.xml.stream.events.Attribute attr)` Constructs a new DOM4J Attribute from the provided StAX Attribute event.
`CharacterData` `createCharacterData(javax.xml.stream.events.Characters characters)` Constructs a new DOM4J Text or CDATA object from the provided Characters event.
`Comment` `createComment(javax.xml.stream.events.Comment comment)` Constructs a new DOM4J Comment from the provided StAX Comment event.
`Element` `createElement(javax.xml.stream.events.StartElement startEvent)` Constructs a new DOM4J Element from the provided StartElement event.
`Entity` `createEntity(javax.xml.stream.events.EntityReference entityRef)` Constructs a new DOM4J Entity from the provided StAX EntityReference event.
`Namespace` `createNamespace(javax.xml.stream.events.Namespace ns)` Constructs a new DOM4J Namespace from the provided StAX Namespace event.
`ProcessingInstruction` `createProcessingInstruction(javax.xml.stream.events.ProcessingInstruction pi)` Constructs a new DOM4J ProcessingInstruction from the provided StAX ProcessingInstruction event.
`QName` `createQName(javax.xml.namespace.QName qname)` Constructs a new DOM4J QName from the provided JAXP QName.
`Attribute` `readAttribute(javax.xml.stream.XMLEventReader reader)` Constructs a DOM4J Attribute from the provided event stream.
`CharacterData` `readCharacters(javax.xml.stream.XMLEventReader reader)` Constructs a DOM4J Text or CDATA section from the provided event stream.
`Comment` `readComment(javax.xml.stream.XMLEventReader reader)` Constructs a DOM4J Comment from the provided event stream.
`Document` `readDocument(InputStream is)` Constructs a StAX event stream from the provided I/O stream and reads a DOM4J document from it.
`Document` `readDocument(InputStream is, String systemId)` Constructs a StAX event stream from the provided I/O stream and reads a DOM4J document from it.
`Document` `readDocument(Reader reader)` Constructs a StAX event stream from the provided I/O character stream and reads a DOM4J document from it.
`Document` `readDocument(Reader reader, String systemId)` Constructs a StAX event stream from the provided I/O character stream and reads a DOM4J document from it.
`Document` `readDocument(javax.xml.stream.XMLEventReader reader)` Reads a DOM4J `Document`from the provided stream.
`Element` `readElement(javax.xml.stream.XMLEventReader eventReader)` Reads a DOM4J Element from the provided event stream.
`Entity` `readEntityReference(javax.xml.stream.XMLEventReader reader)` Constructs a DOM4J Entity from the provided event stream.
`Namespace` `readNamespace(javax.xml.stream.XMLEventReader reader)` Constructs a DOM4J Namespace from the provided event stream.
`Node` `readNode(javax.xml.stream.XMLEventReader reader)` Reads a `Node`from the event stream.
`ProcessingInstruction` `readProcessingInstruction(javax.xml.stream.XMLEventReader reader)` Constructs a DOM4J ProcessingInstruction from the provided event stream.
`void` `setDocumentFactory(DocumentFactory documentFactory)` Sets the DocumentFactory to be used when constructing DOM4J nodes.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### STAXEventReader

    public STAXEventReader()

  Constructs a default `STAXEventReader` instance with a default `DocumentFactory`.

### STAXEventReader

    public STAXEventReader(DocumentFactory factory)

  Constructs a `STAXEventReader` instance that uses the specified `DocumentFactory`to construct DOM4J `Node`s.

Parameters:
  `factory` - The DocumentFactory to use when constructing DOM4J nodes, or `null` if a default should be used.

Method Detail

### setDocumentFactory

    public void setDocumentFactory(DocumentFactory documentFactory)

  Sets the DocumentFactory to be used when constructing DOM4J nodes.

  Parameters:
    `documentFactory` - The DocumentFactory to use when constructing DOM4J nodes, or `null` if a default should be used.

### readDocument

    public Document readDocument(InputStream is)
                          throws javax.xml.stream.XMLStreamException

  Constructs a StAX event stream from the provided I/O stream and reads a DOM4J document from it.

  Parameters:
    `is` - The I/O stream from which the Document will be read.
  Returns:
    The Document that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occurs reading content from the stream.

### readDocument

    public Document readDocument(Reader reader)
                          throws javax.xml.stream.XMLStreamException

  Constructs a StAX event stream from the provided I/O character stream and reads a DOM4J document from it.

  Parameters:
    `reader` - The character stream from which the Document will be read.
  Returns:
    The Document that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occurs reading content from the stream.

### readDocument

    public Document readDocument(InputStream is,
                                 String systemId)
                          throws javax.xml.stream.XMLStreamException

  Constructs a StAX event stream from the provided I/O stream and reads a DOM4J document from it.

  Parameters:
    `is` - The I/O stream from which the Document will be read.
    `systemId` - A system id used to resolve entities.
  Returns:
    The Document that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occurs reading content from the stream.

### readDocument

    public Document readDocument(Reader reader,
                                 String systemId)
                          throws javax.xml.stream.XMLStreamException

  Constructs a StAX event stream from the provided I/O character stream and reads a DOM4J document from it.

  Parameters:
    `reader` - The character stream from which the Document will be read.
    `systemId` - A system id used to resolve entities.
  Returns:
    The Document that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occurs reading content from the stream.

### readNode

    public Node readNode(javax.xml.stream.XMLEventReader reader)
                  throws javax.xml.stream.XMLStreamException

  Reads a `Node`from the event stream. If the next event is a `StartElement`, all events until the closing `EndElement` will be read, and the resulting nodes will be added to the returned `Element`.

  Pre-Conditions : The stream must be positioned before an event other than an `EndElement`,`EndDocument`, or any DTD-related events, which are not currently supported.

  Parameters:
    `reader` - The reader from which events will be read.
  Returns:
    A DOM4J `Node`constructed from the read events.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occurs reading from the stream, or the stream was positioned before an unsupported event.

### readDocument

    public Document readDocument(javax.xml.stream.XMLEventReader reader)
                          throws javax.xml.stream.XMLStreamException

  Reads a DOM4J `Document`from the provided stream. The stream should be positioned at the start of a document, or before a `StartElement` event.

  Parameters:
    `reader` - The event stream from which to read the `Document`.
  Returns:
    The `Document`that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occurs reading events from the stream.

### readElement

    public Element readElement(javax.xml.stream.XMLEventReader eventReader)
                        throws javax.xml.stream.XMLStreamException

  Reads a DOM4J Element from the provided event stream. The stream must be positioned before an `StartElement`event. In addition to the initial start event, all events up to and including the closing `EndElement` will be read, and included with the returned element.

  Parameters:
    `eventReader` - The event stream from which to read the Element.
  Returns:
    The Element that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occured reading events from the stream, or the stream was not positioned before a event.

### readAttribute

    public Attribute readAttribute(javax.xml.stream.XMLEventReader reader)
                            throws javax.xml.stream.XMLStreamException

  Constructs a DOM4J Attribute from the provided event stream. The stream must be positioned before an `Attribute`event.

  Parameters:
    `reader` - The event stream from which to read the Attribute.
  Returns:
    The Attribute that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occured reading events from the stream, or the stream was not positioned before an event.

### readNamespace

    public Namespace readNamespace(javax.xml.stream.XMLEventReader reader)
                            throws javax.xml.stream.XMLStreamException

  Constructs a DOM4J Namespace from the provided event stream. The stream must be positioned before a `Namespace`event.

  Parameters:
    `reader` - The event stream from which to read the Namespace.
  Returns:
    The Namespace that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occured reading events from the stream, or the stream was not positioned before a event.

### readCharacters

    public CharacterData readCharacters(javax.xml.stream.XMLEventReader reader)
                                 throws javax.xml.stream.XMLStreamException

  Constructs a DOM4J Text or CDATA section from the provided event stream. The stream must be positioned before a `Characters`event.

  Parameters:
    `reader` - The event stream from which to read the Text or CDATA.
  Returns:
    The Text or CDATA that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occured reading events from the stream, or the stream was not positioned before a event.

### readComment

    public Comment readComment(javax.xml.stream.XMLEventReader reader)
                        throws javax.xml.stream.XMLStreamException

  Constructs a DOM4J Comment from the provided event stream. The stream must be positioned before a `Comment`event.

  Parameters:
    `reader` - The event stream from which to read the Comment.
  Returns:
    The Comment that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occured reading events from the stream, or the stream was not positioned before a event.

### readEntityReference

    public Entity readEntityReference(javax.xml.stream.XMLEventReader reader)
                               throws javax.xml.stream.XMLStreamException

  Constructs a DOM4J Entity from the provided event stream. The stream must be positioned before an `EntityReference`event.

  Parameters:
    `reader` - The event stream from which to read the `EntityReference`.
  Returns:
    The `Entity`that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occured reading events from the stream, or the stream was not positioned before an event.

### readProcessingInstruction

    public ProcessingInstruction readProcessingInstruction(javax.xml.stream.XMLEventReader reader)
                                                    throws javax.xml.stream.XMLStreamException

  Constructs a DOM4J ProcessingInstruction from the provided event stream. The stream must be positioned before a `ProcessingInstruction` event.

  Parameters:
    `reader` - The event stream from which to read the ProcessingInstruction.
  Returns:
    The ProcessingInstruction that was read from the stream.
  Throws:
    `javax.xml.stream.XMLStreamException` - If an error occured reading events from the stream, or the stream was not positioned before a `ProcessingInstruction` event.

### createElement

    public Element createElement(javax.xml.stream.events.StartElement startEvent)

  Constructs a new DOM4J Element from the provided StartElement event. All attributes and namespaces will be added to the returned element.

  Parameters:
    `startEvent` - The StartElement event from which to construct the new DOM4J Element.
  Returns:
    The Element constructed from the provided StartElement event.

### createAttribute

    public Attribute createAttribute(Element elem,
                                     javax.xml.stream.events.Attribute attr)

  Constructs a new DOM4J Attribute from the provided StAX Attribute event.

  Parameters:
    `elem` - DOCUMENT ME!
    `attr` - The Attribute event from which to construct the new DOM4J Attribute.
  Returns:
    The Attribute constructed from the provided Attribute event.

### createNamespace

    public Namespace createNamespace(javax.xml.stream.events.Namespace ns)

  Constructs a new DOM4J Namespace from the provided StAX Namespace event.

  Parameters:
    `ns` - The Namespace event from which to construct the new DOM4J Namespace.
  Returns:
    The Namespace constructed from the provided Namespace event.

### createCharacterData

    public CharacterData createCharacterData(javax.xml.stream.events.Characters characters)

  Constructs a new DOM4J Text or CDATA object from the provided Characters event.

  Parameters:
    `characters` - The Characters event from which to construct the new DOM4J Text or CDATA object.
  Returns:
    The Text or CDATA object constructed from the provided Characters event.

### createComment

    public Comment createComment(javax.xml.stream.events.Comment comment)

  Constructs a new DOM4J Comment from the provided StAX Comment event.

  Parameters:
    `comment` - The Comment event from which to construct the new DOM4J Comment.
  Returns:
    The Comment constructed from the provided Comment event.

### createEntity

    public Entity createEntity(javax.xml.stream.events.EntityReference entityRef)

  Constructs a new DOM4J Entity from the provided StAX EntityReference event.

  Parameters:
    `entityRef` - The EntityReference event from which to construct the new DOM4J Entity.
  Returns:
    The Entity constructed from the provided EntityReference event.

### createProcessingInstruction

    public ProcessingInstruction createProcessingInstruction(javax.xml.stream.events.ProcessingInstruction pi)

  Constructs a new DOM4J ProcessingInstruction from the provided StAX ProcessingInstruction event.

  Parameters:
    `pi` - The ProcessingInstruction event from which to construct the new DOM4J ProcessingInstruction.
  Returns:
    The ProcessingInstruction constructed from the provided ProcessingInstruction event.

### createQName

    public QName createQName(javax.xml.namespace.QName qname)

  Constructs a new DOM4J QName from the provided JAXP QName.

  Parameters:
    `qname` - The JAXP QName from which to create a DOM4J QName.
  Returns:
    The newly constructed DOM4J QName.

Copyright © 2001-2005 MetaStuff Ltd.. All Rights Reserved.