Package javanet.staxutils

Class XMLStreamUtils

  • public class XMLStreamUtils
extends Object
    Static utility methods useful when handling XML Streams.
    Version:
    $Revision: 1.8 $
    Author:
    Christian Niles

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

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