src.java.org.codehaus.stax2.XMLStreamReader2 Maven / Gradle / Ivy
/* StAX2 extension for StAX API (JSR-173).
*
* Copyright (c) 2005- Tatu Saloranta, [email protected]
*
* Licensed under the License specified in file LICENSE, included with
* the source code.
* You may not use this file except in compliance with the License.
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.codehaus.stax2;
import java.io.IOException;
import java.io.Reader;
import java.io.Writer;
import javax.xml.namespace.NamespaceContext;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamReader;
import org.codehaus.stax2.validation.Validatable;
/**
* Extended interface that implements functionality that is necessary
* to properly build event API on top of {@link XMLStreamReader}.
* It also adds limited number of methods that are important for
* efficient pass-through processing (such as one needed when routing
* SOAP-messages).
*
* The features supported via {@link #setFeature} are:
*
* FEATURE_DTD_OVERRIDE: (write-only)
* Feature used to specify the source for DTD external subset to use
* instead of DTD specified by the XML document itself (if any).
* Setting the feature for a reader that supports DTD validation
* essentially allows for injecting an alternate DOCTYPE declaration.
* Note that setting this value to null is both legal, and sometimes
* useful: it is equivalent of removing the DOCTYPE declaration.
*
Feature is write-only, since storing it after loading the DTD
* in question does not have much use.
*
*
*/
public interface XMLStreamReader2
extends XMLStreamReader, Validatable
{
/**
* Feature used to specify the source for DTD external subset to use
* instead of DTD specified by the XML document itself (if any).
*/
public final static String FEATURE_DTD_OVERRIDE = "org.codehaus.stax2.propDtdOverride";
/*
///////////////////////////
// Configuration
///////////////////////////
*/
/**
* Method that can be used to get per-reader values; both generic
* ones (names for which are defined as constants in this class),
* and implementation dependant ones.
*
* Note: although some feature names are shared with
* {@link #setFeature}, not all are: some features are read-only,
* some write-only
*
* @deprecated Should use {@link #getProperty} instead
*
* @param name Name of the feature of which value to get
*
* @return Value of the feature (possibly null), if supported; null
* otherwise
*/
public Object getFeature(String name);
/**
* Method that can be used to set per-reader features such as configuration
* settings; both generic
* ones (names for which are defined as constants in this class),
* and implementation dependant ones.
*
* Note: although some feature names are shared with
* {@link #getFeature}, not all are: some features are read-only,
* some write-only
*
* @deprecated Should use {@link #setProperty} instead
*
* @param name Name of the feature to set
* @param value Value to set feature to.
*/
public void setFeature(String name, Object value);
/**
* Method similar to {@link javax.xml.stream.XMLInputFactory#isPropertySupported}, used
* to determine whether a property is supported by the Reader
* instance. This means that this method may return false
* for some properties that the input factory does support: specifically,
* it should only return true if the value is mutable on per-instance
* basis. False means that either the property is not recognized, or
* is not mutable via reader instance.
*/
public boolean isPropertySupported(String name);
/**
* Method that can be used to set per-reader properties; a subset of
* properties one can set via matching
* {@link org.codehaus.stax2.XMLInputFactory2}
* instance. Exactly which methods are mutable is implementation
* specific.
*
* @param name Name of the property to set
* @param value Value to set property to.
*
* @return True, if the specified property was succesfully
* set to specified value; false if its value was not changed
*
* @throws InvalidArgumentException if the property is not supported
* (or recognized) by the stream reader implementation
*/
public boolean setProperty(String name, Object value);
/*
/////////////////////////////////
// Additional event traversing
/////////////////////////////////
*/
/**
* Method that will skip all the contents of the element that the
* stream currently points to. Current event when calling the method
* has to be START_ELEMENT (or otherwise {@link IllegalStateException}
* is thrown); after the call the stream will point to the matching
* END_ELEMENT event, having skipped zero or more intervening events
* for the contents.
*/
public void skipElement() throws XMLStreamException;
/*
/////////////////////////////////
// Additional DTD access
/////////////////////////////////
*/
/**
* Method that can be called to get information about DOCTYPE declaration
* that the reader is currently pointing to, if the reader has parsed
* it. Implementations can also choose to return null to indicate they
* do not provide extra information; but they should not throw any
* exceptions beyond normal parsing exceptions.
*
* @return Information object for accessing further DOCTYPE information,
* iff the reader currently points to DTD event, AND is operating
* in mode that parses such information (DTD-aware at least, and
* usually also validating)
*/
public DTDInfo getDTDInfo() throws XMLStreamException;
/*
/////////////////////////////////
// Additional attribute accessors
/////////////////////////////////
*/
/**
* Method that can be called to get additional information about
* attributes related to the current start element, as well as
* related DTD-based information if available. Note that the
* reader has to currently point to START_ELEMENT; if not,
* a {@link IllegalStateException} will be thrown.
*/
public AttributeInfo getAttributeInfo() throws XMLStreamException;
/*
/////////////////////////////////////////
// Extended location information access
/////////////////////////////////////////
*/
public LocationInfo getLocationInfo();
/*
///////////////////////////////
// Pass-through text accessors
///////////////////////////////
*/
/**
* Method similar to {@link #getText()}, except
* that it just uses provided Writer to write all textual content,
* and that it works for wider range of event types.
* For further optimization, it may also be allowed to do true
* pass-through, thus possibly avoiding one temporary copy of the
* data. Finally, note that this method is also guaranteed NOT
* to return fragments, even when coalescing is not enabled and
* a parser is otherwised allowed to return partial segments: this
* requirement is due to there being little benefit in returning
* such short chunks when streaming. Coalescing property is still
* honored normally.
*
* Method can only be called on states CDATA, CHARACTERS, COMMENT,
* DTD, ENTITY_REFERENCE, SPACE and PROCESSING_INSTRUCTION; if called
* when reader is in another state,
* {@link IllegalStateException} will be thrown. Content written
* for elements is same as with {@link #getText()}.
*
* @param w Writer to use for writing textual contents
* @param preserveContents If true, reader has to preserve contents
* so that further calls to getText will return
* proper conntets. If false, reader is allowed to skip creation
* of such copies: this can improve performance, but it also means
* that further calls to getText is not guaranteed to
* return meaningful data.
*
* @return Number of characters written to the reader
*/
public int getText(Writer w, boolean preserveContents)
throws IOException, XMLStreamException;
/**
* Method similar to {@link #getText()}, except
* that onlt a {@link Reader} is returned, which may then be used
* by the caller to read all the text.
* For further optimization, it may also be allowed to do true
* pass-through, thus possibly avoiding one temporary copy of the
* data (without allowing that to be done, stream reader still needs
* to create a copy of data read, thus negating benefits of using
* a simple Reader).
*
* Method can only be called on states CDATA, CHARACTERS, COMMENT,
* DTD, ENTITY_REFERENCE; if called when reader is in another state,
* {@link IllegalStateException} will be thrown. Content written
* for elements is same as with {@link #getText()}.
*
* @param preserveContents If true, reader has to preserve contents
* so that further calls to getText will return
* proper conntets. If false, reader is allowed to skip creation
* of such copies: this can improve performance, but it also means
* that further calls to getText is not guaranteed to
* return meaningful data.
*
* @return Reader through which textual contents of the current event
* can be read.
*/
/*
// 19-Apr-2005, TSa: This method was left out of StAX2 v1.0...
public Reader getTextReader(boolean preserveContents)
throws IOException, XMLStreamException;
*/
/*
///////////////////////////
// Other accessors
///////////////////////////
*/
/**
* Method that can be used to check whether current START_ELEMENT
* event was created for an empty element (xml short-hand notation
* where one tag implies start and end, ending with "/>"), or not.
*
* Note: method may need to read more data to know if the element
* is an empty one, and as such may throw an i/o or parsing exception
* (as {@link XMLStreamException}); however, it won't throw exceptions
* for non-START_ELEMENT event types.
*
* @return True, if current event is START_ELEMENT
* and is based on a parsed empty element; otherwise false
*/
public boolean isEmptyElement() throws XMLStreamException;
/**
* Method that returns the number of open elements in the stack; 0 when
* the reader is in prolog/epilog, 1 inside root element and so on.
* Depth is same for matching start/end elements, as well as for the
* immediate non-element children of the element.
*
* @return Number of open elements currently in the reader's stack
*/
public int getDepth();
/**
* This method returns a namespace contenxt object that contains
* information identical to that returned by
* {@link javax.xml.stream.XMLStreamReader#getNamespaceContext()},
* but one that is
* not transient. That is, one that will remain valid and unchanged
* after its creation. This allows the namespace context to be used
* independent of its source documents life cycle. One possible use
* case is to use this namespace context for 'initializing' writers
* (especially ones that use repairing mode) with optimal/preferred name
* space bindings.
*
* @return Non-transient namespace context as explained above.
*/
public NamespaceContext getNonTransientNamespaceContext();
/**
* This method returns "prefix-qualified" name of the current
* element. In general, this means character-by-character exact
* name of the element in XML content, and may be useful in informational
* purposes, as well as when interacting with packages and APIs that
* use such names (such as what SAX may use as qnames).
*
* Note: implementations are encouraged to provide an implementation
* that would be more efficient than calling getLocalName
* and getPrefix separately, but are not required to do
* so. Nonetheless it is usually at least as efficient (if not more)
* to call this method as to do it fully in calling code.
*
* @return Prefix-qualified name of the current element; essentially
* 'prefix:localName' if the element has a prefix, or 'localName'
* if it does not have one (belongs to the default namespace)
*/
public String getPrefixedName();
/*
///////////////////////////
// Input handling
///////////////////////////
*/
/**
* Method similar to
* {@link javax.xml.stream.XMLStreamReader#getNamespaceContext()},
* except that this method also does close the underlying input
* source if it has not yet been closed. It is generally preferable
* to call this method if the parsing ends in an exception;
* and for some input sources (when passing
* a {@link java.io.File} or {@link java.net.URL} for factory
* method) it has to be called as the application does not have
* access to the actually input source ({@link java.io.InputStream}
* opened from a {@link java.net.URL} and so on).
*/
public void closeCompletely()
throws XMLStreamException;
}