com.sun.xml.ws.streaming.XMLReader Maven / Gradle / Ivy
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the license at
* https://glassfish.dev.java.net/public/CDDLv1.0.html.
* See the License for the specific language governing
* permissions and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at https://glassfish.dev.java.net/public/CDDLv1.0.html.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* you own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* Copyright 2006 Sun Microsystems Inc. All Rights Reserved
*/
package com.sun.xml.ws.streaming;
import org.xml.sax.helpers.XMLReaderFactory;
import java.util.Iterator;
import javax.xml.namespace.QName;
/**
* XMLReader provides a high-level streaming parser interface
* for reading XML documents.
*
* The {@link #next} method is used to read events from the XML document.
*
* Each time it is called, {@link #next} returns the new state of the reader.
*
* Possible states are: BOF, the initial state, START, denoting the start
* tag of an element, END, denoting the end tag of an element, CHARS, denoting
* the character content of an element, PI, denoting a processing instruction,
* EOF, denoting the end of the document.
*
* Depending on the state the reader is in, one or more of the following
* query methods will be meaningful: {@link #getName}, {@link #getURI},
* {@link #getLocalName}, {@link #getAttributes}, {@link #getValue}.
*
* Elements visited by a XMLReader are tagged with unique IDs. The ID of the
* current element can be found by calling {@link #getElementId}.
*
* A XMLReader is always namespace-aware, and keeps track of the namespace
* declarations which are in scope at any time during streaming. The
* {@link #getURI(java.lang.String)} method can be used to find the URI
* associated to a given prefix in the current scope.
*
* XMLReaders can be created using a {@link XMLReaderFactory}.
*
* Some utility methods, {@link #nextContent} and {@link #nextElementContent}
* make it possible to ignore whitespace and processing instructions with
* minimum impact on the client code.
*
* Similarly, the {@link #skipElement} and {@link #skipElement(int elementId)}
* methods allow to skip to the end tag of an element ignoring all its content.
*
* Finally, the {@link #recordElement} method can be invoked when the XMLReader
* is positioned on the start tag of an element to record the element's contents
* so that they can be played back later.
*
* @see XMLReaderFactory
*
* @author WS Development Team
*/
public interface XMLReader {
/**
* The initial state of a XMLReader.
*/
public static final int BOF = 0;
/**
* The state denoting the start tag of an element.
*/
public static final int START = 1;
/**
* The state denoting the end tag of an element.
*/
public static final int END = 2;
/**
* The state denoting the character content of an element.
*/
public static final int CHARS = 3;
/**
* The state denoting a processing instruction.
*/
public static final int PI = 4;
/**
* The state denoting that the end of the document has been reached.
*/
public static final int EOF = 5;
/**
* Return the next state of the XMLReader.
*
* The return value is one of: START, END, CHARS, PI, EOF.
*/
public int next();
/*
* Return the next state of the XMLReader.
*
* Whitespace character content and processing instructions are ignored.
*
* The return value is one of: START, END, CHARS, EOF.
*/
public int nextContent();
/**
* Return the next state of the XMLReader.
*
* Whitespace character content, processing instructions are ignored.
* Non-whitespace character content triggers an exception.
*
* The return value is one of: START, END, EOF.
*/
public int nextElementContent();
/**
* Return the current state of the XMLReader.
*
*/
public int getState();
/**
* Return the current qualified name.
*
* Meaningful only when the state is one of: START, END.
*/
public QName getName();
/**
* Return the current URI.
*
* Meaningful only when the state is one of: START, END.
*/
public String getURI();
/**
* Return the current local name.
*
* Meaningful only when the state is one of: START, END, PI.
*/
public String getLocalName();
/**
* Return the current attribute list. In the jaxws implementation,
* this list also includes namespace declarations.
*
* Meaningful only when the state is one of: START.
*
* The returned {@link Attributes} object belong to the XMLReader and is
* only guaranteed to be valid until the {@link #next} method is called,
* directly or indirectly.
*/
public Attributes getAttributes();
/**
* Return the current value.
*
* Meaningful only when the state is one of: CHARS, PI.
*/
public String getValue();
/**
* Return the current element ID.
*/
public int getElementId();
/**
* Return the current line number.
*
* Due to aggressive parsing, this value may be off by a few lines.
*/
public int getLineNumber();
/**
* Return the URI for the given prefix.
*
* If there is no namespace declaration in scope for the given
* prefix, return null.
*/
public String getURI(String prefix);
/**
* Return an iterator on all prefixes in scope, except for the default prefix.
*
*/
public Iterator getPrefixes();
/**
* Records the current element and leaves the reader positioned on its end tag.
*
* The XMLReader must be positioned on the start tag of the element.
* The returned reader will play back all events starting with the
* start tag of the element and ending with its end tag.
*/
public XMLReader recordElement();
/**
* Skip all nodes up to the end tag of the element with the current element ID.
*/
public void skipElement();
/**
* Skip all nodes up to the end tag of the element with the given element ID.
*/
public void skipElement(int elementId);
/**
* Close the XMLReader.
*
* All subsequent calls to {@link #next} will return EOF.
*/
public void close();
}