## javanet.staxutils
Class XMLStreamUtils

    java.lang.Object
      javanet.staxutils.XMLStreamUtils

    public class XMLStreamUtils

extends Object

Static utility methods useful when handling XML Streams.

Version:
  $Revision: 1.8 $
Author:
  Christian Niles

Constructor Summary
`XMLStreamUtils()`

Method Summary
`static String` `attributeValue(XMLStreamReader reader, QName name)` Returns the value of the attribute with the given name.
`static String` `attributeValue(XMLStreamReader reader, String name)` Returns the value of the attribute with the given non-qualified name.
`static void` `copy(Source source, XMLEventWriter writer)` Copies the content read from a TrAX `Source` to a StAX `XMLEventWriter`.
`static void` `copy(Source source, XMLStreamWriter writer)` Copies the content read from a TrAX `Source` to a StAX `XMLStreamWriter`.
`static void` `copy(XMLEventReader reader, Result result)` Copies the content read from a StAX `XMLEventReader` to a TrAX `Result`.
`static void` `copy(XMLEventReader reader, XMLEventConsumer consumer)` Copies the content read from the specified source stream to the provided result stream.
`static void` `copy(XMLEventReader reader, XMLEventWriter writer)` Copies the content read from the specified source stream to the provided result stream.
`static void` `copy(XMLStreamReader reader, Result result)` Copies the content read from a StAX `XMLStreamReader` to a TrAX `Result`.
`static void` `copy(XMLStreamReader reader, XMLStreamWriter writer)` Copies the content read from the specified source stream to the provided result stream.
`static void` `copy(XMLStreamReader reader, XMLStreamWriter writer, XMLInputFactory factory)` Copies the content read from the specified source stream to the provided result stream.
`static void` `copyElement(XMLEventReader reader, XMLEventConsumer consumer)` Copies an element and all its content from the provided event reader, to the provided event consumer.
`static void` `copyElementContent(XMLEventReader reader, XMLEventConsumer consumer)` Copies all events within a `StartElement` until the matching `EndElement` is reached.
`static String` `getEventTypeName(int eventType)` Returns the name of the specified stream event constant.
`static StartElement` `mergeAttributes(StartElement tag, Iterator attrs, XMLEventFactory factory)` Constructs a new StartElement that merges the attributes and namespaces found in the specified StartElement, with the provided attributes.
`static StartElement` `nextElement(XMLEventReader reader)` Reads the events from the provided event stream until either a start or end tag is encountered.
`static StartElement` `nextElement(XMLEventReader reader, QName name)` Reads the events from the provided event stream until either a start or end tag is encountered.
`static XMLEvent` `nextTag(XMLEventReader reader)` Advances the event stream until it encounters a start or end tag, but does not actaully read the event.
`static String` `readTextElement(XMLEventReader reader, QName elemName)` Reads the text content of an element.
`static void` `requireElement(XMLStreamReader reader, QName name)` Static utility method that throws an exception if the supplied reader's cursor doesn't point to a START_ELEMENT with the given name.
`static void` `requireStartElement(XMLEventReader reader, QName qname)` Utility method that throws an exception if the provided reader is not positioned before a StartElement event with the specified tag name.
`static void` `skipElement(XMLEventReader reader)` Skips all events within a single element, including its start and end tags.
`static void` `skipElement(XMLStreamReader reader)` Skips the complete content of the element at the specified reader's cursor.
`static void` `skipElementContent(XMLEventReader reader)` Skips all events within a `StartElement` until the matching `EndElement` is reached.
`static void` `skipElementContent(XMLStreamReader reader)` Skips an element's complete content.

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

Constructor Detail

### XMLStreamUtils

    public XMLStreamUtils()

Method Detail

### getEventTypeName

    public static final String getEventTypeName(int eventType)

  Returns the name of the specified stream event constant.

  Parameters:
    `eventType` - The event constant, such as `XMLStreamConstants.START_DOCUMENT`.
  Returns:
    The name of the specified event, or `"UNKNOWN"` if the constant isn't valid.

### attributeValue

    public static final String attributeValue(XMLStreamReader reader,
                                              String name)

  Returns the value of the attribute with the given non-qualified name.

  Parameters:
    `reader` - The xml stream reader
    `name` - The name of the attribute.
  Returns:
    The value of the unqualified attribute, or `null` if the attribute wasn't present.

### attributeValue

    public static final String attributeValue(XMLStreamReader reader,
                                              QName name)

  Returns the value of the attribute with the given name.

  Parameters:
    `reader` - The xml stream reader
    `name` - The name of the attribute.
  Returns:
    The value of the attribute, or `null` if the attribute wasn't present.

### skipElement

    public static final void skipElement(XMLEventReader reader)
                                  throws XMLStreamException

  Skips all events within a single element, including its start and end tags. The provided reader must be positioned directly in front of a `StartElement` event or it will have no effect. After this method completes, the reader will be positioned before the event following the end tag (the end tag will have been read).

  Parameters:
    `reader` - The event stream to read.
  Throws:
    `XMLStreamException` - If an error occurs reading events.

### copyElement

    public static final void copyElement(XMLEventReader reader,
                                         XMLEventConsumer consumer)
                                  throws XMLStreamException

  Copies an element and all its content from the provided event reader, to the provided event consumer. The event reader must be positioned before a start element event, or this method has no effect.

  Parameters:
    `reader` - The reader from which to read the events.
    `consumer` - The destination for read events, or `null` to ignore all events.
  Throws:
    `XMLStreamException` - If an error occurs reading or writing the events.

### skipElementContent

    public static final void skipElementContent(XMLEventReader reader)
                                         throws XMLStreamException

  Skips all events within a `StartElement` until the matching `EndElement` is reached. This method assumes that the reader is positioned after the `StartElement` event, and when the method completes, the stream will be positioned before the `EndElement` event, but it will not consume the end tag.

  Parameters:
    `reader` - The event stream to read, positioned after the `StartElement`
  Throws:
    `XMLStreamException` - If an error occurs reading events.

### copyElementContent

    public static final void copyElementContent(XMLEventReader reader,
                                                XMLEventConsumer consumer)
                                         throws XMLStreamException

  Copies all events within a `StartElement` until the matching `EndElement` is reached. This method assumes that the reader is positioned after the `StartElement` event, and when the method completes, the stream will be positioned before the `EndElement` event, but it will not consume the end tag.

  Parameters:
    `reader` - The event stream to read, positioned after the `StartElement`
    `consumer` - The destination for events read from teh stream, or `null` to ignore the events completely.
  Throws:
    `XMLStreamException` - If an error occurs reading events.

### skipElement

    public static final void skipElement(XMLStreamReader reader)
                                  throws XMLStreamException

  Skips the complete content of the element at the specified reader's cursor. The reader's current event type must be START_ELEMENT, otherwise this method will have no effect. Upon completion, the reader's cursor will be at the END_ELEMENT event for the skipped element.

  Parameters:
    `reader` - An XML stream reader currently in the START_ELEMENT event.
  Throws:
    `XMLStreamException`

### skipElementContent

    public static final void skipElementContent(XMLStreamReader reader)
                                         throws XMLStreamException

  Skips an element's complete content. This method assumes that the `START_ELEMENT` has already be passed, and when it terminates, the stream will be positioned at the `END_ELEMENT`.

  Parameters:
    `reader` - The stream reader to read.
  Throws:
    `XMLStreamException` - If an error occurs reading the stream.

### requireElement

    public static final void requireElement(XMLStreamReader reader,
                                            QName name)
                                     throws XMLStreamException

  Static utility method that throws an exception if the supplied reader's cursor doesn't point to a START_ELEMENT with the given name.

  Parameters:
    `reader` - The reader to test.
    `name` - The name of the element to require.
  Throws:
    `XMLStreamException` - If the reader state is an element with the specified name.

### copy

    public static final void copy(XMLEventReader reader,
                                  XMLEventConsumer consumer)
                           throws XMLStreamException

  Copies the content read from the specified source stream to the provided result stream. This method is exactly the same as calling `XMLEventWriter.add(XMLEventReader)`, and is provided only for completeness.

  Parameters:
    `reader` - The source stream.
    `consumer` - The destination stream.
  Throws:
    `XMLStreamException` - If an error occurs copying the stream contents.

### copy

    public static final void copy(XMLEventReader reader,
                                  XMLEventWriter writer)
                           throws XMLStreamException

  Copies the content read from the specified source stream to the provided result stream. This method is exactly the same as calling `XMLEventWriter.add(XMLEventReader)`, and is provided only for completeness.

  Parameters:
    `reader` - The source stream.
    `writer` - The destination stream.
  Throws:
    `XMLStreamException` - If an error occurs copying the stream contents.

### copy

    public static final void copy(XMLStreamReader reader,
                                  XMLStreamWriter writer)
                           throws XMLStreamException

  Copies the content read from the specified source stream to the provided result stream.

  Parameters:
    `reader` - The source stream.
    `writer` - The destination stream.
  Throws:
    `XMLStreamException` - If an error occurs copying the stream contents.

### copy

    public static final void copy(XMLStreamReader reader,
                                  XMLStreamWriter writer,
                                  XMLInputFactory factory)
                           throws XMLStreamException

  Copies the content read from the specified source stream to the provided result stream.

  Parameters:
    `reader` - The source stream.
    `writer` - The destination stream.
    `factory` - An optional input factory used to create any intermediate streams.
  Throws:
    `XMLStreamException` - If an error occurs copying the stream contents.

### copy

    public static final void copy(Source source,
                                  XMLStreamWriter writer)
                           throws XMLStreamException

  Copies the content read from a TrAX `Source` to a StAX `XMLStreamWriter`.

  Parameters:
    `source` - The content source.
    `writer` - The destination stream.
  Throws:
    `XMLStreamException` - If an error occurs copying the content to the stream.

### copy

    public static final void copy(Source source,
                                  XMLEventWriter writer)
                           throws XMLStreamException

  Copies the content read from a TrAX `Source` to a StAX `XMLEventWriter`.

  Parameters:
    `source` - The content source.
    `writer` - The destination event stream.
  Throws:
    `XMLStreamException` - If an error occurs copying the content to the event stream.

### copy

    public static final void copy(XMLEventReader reader,
                                  Result result)
                           throws XMLStreamException

  Copies the content read from a StAX `XMLEventReader` to a TrAX `Result`.

  Parameters:
    `reader` - The source event stream.
    `result` - The destination `Result`.
  Throws:
    `XMLStreamException` - If an error occurs copying the content to the result.

### copy

    public static final void copy(XMLStreamReader reader,
                                  Result result)
                           throws XMLStreamException

  Copies the content read from a StAX `XMLStreamReader` to a TrAX `Result`.

  Parameters:
    `reader` - The source stream.
    `result` - The destination `Result`.
  Throws:
    `XMLStreamException` - If an error occurs copying the content to the result.

### requireStartElement

    public static final void requireStartElement(XMLEventReader reader,
                                                 QName qname)
                                          throws XMLStreamException

  Utility method that throws an exception if the provided reader is not positioned before a StartElement event with the specified tag name.

  Parameters:
    `reader` - The reader to test.
    `qname` - The required name of the start-tag. If `null`, any start tag is accepted.
  Throws:
    `XMLStreamException` - If an error occurs reading from the stream.

### mergeAttributes

    public static StartElement mergeAttributes(StartElement tag,
                                               Iterator attrs,
                                               XMLEventFactory factory)

  Constructs a new StartElement that merges the attributes and namespaces found in the specified StartElement, with the provided attributes. The returned StartElement will contain all the attributes and namespaces of the original, plus those defined in the map.

  Parameters:
    `tag` - The original StartElement
    `attrs` - An iterator of Atributes to add to the element.
  Returns:
    A new StartElement that contains all the original attributes and namespaces, plus the provided attributes.

### readTextElement

    public static final String readTextElement(XMLEventReader reader,
                                               QName elemName)
                                        throws XMLStreamException

  Reads the text content of an element. The reader should be positioned in front of a StartElement event, and will be read up to and including the end element tag.

  Parameters:
    `reader` - The event stream from which to read the element text.
    `elemName` - The optional name of the element being read. If this paramter is non- `null` then an exception will be thrown if the element read doesn't have the same name.
  Returns:
    The text read from the element.
  Throws:
    `XMLStreamException` - If an error occurs reading the stream, or if the read element doesn't match the provided QName.

### nextTag

    public static final XMLEvent nextTag(XMLEventReader reader)
                                  throws XMLStreamException

  Advances the event stream until it encounters a start or end tag, but does not actaully read the event.

  Parameters:
    `reader` - The reader to peek.
  Returns:
    The next StartElement or EndElement event, retrieved using `peek()`, or `null` if the end of the stream was encountered before any tag event.
  Throws:
    `XMLStreamException` - If an error occurs reading the stream.

### nextElement

    public static final StartElement nextElement(XMLEventReader reader)
                                          throws XMLStreamException

  Reads the events from the provided event stream until either a start or end tag is encountered. In the former case, the start tag will be returned, but if an end tag is encountered, `null` will be returned. After returning, the stream will be positioned just before the returned start element. The start element will not be consumed by this method.

  Parameters:
    `reader` - The event stream from which to read.
  Returns:
    The StartElement read from the stream, or `null` if an end tag was found first, or the stream ended before a start element was found.
  Throws:
    `XMLStreamException` - If an error occurs reading the stream.

### nextElement

    public static final StartElement nextElement(XMLEventReader reader,
                                                 QName name)
                                          throws XMLStreamException

  Reads the events from the provided event stream until either a start or end tag is encountered. In the former case, the start tag will be returned if it matches the specified QName, but if it doesn't match, an end tag is encountered, or the stream ends, `null` will be returned. After returning, the stream will be positioned just before the start element. The start element will not be consumed by this method.

  Parameters:
    `reader` - The event stream from which to read.
    `name` - The name of the element to read, or `null` to read any start tag.
  Returns:
    The StartElement read from the stream, or `null` if the encountered start tag didn't match the specified QName, an end tag was found first, or the stream ended before a start element was found.
  Throws:
    `XMLStreamException` - If an error occurs reading the stream.