Package 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 Details

    • XMLStreamUtils

      public XMLStreamUtils()

  • Method Details

    • 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.