org.codehaus.stax2
Interface XMLStreamWriter2

All Superinterfaces:
TypedXMLStreamWriter, Validatable, javax.xml.stream.XMLStreamWriter
All Known Implementing Classes:
DOMWrappingWriter, Stax2WriterAdapter, Stax2WriterImpl, StreamWriter2Delegate

public interface XMLStreamWriter2
extends TypedXMLStreamWriter, Validatable

Extended interface that implements functionality that is necessary to properly build event API on top of XMLStreamWriter, as well as to configure individual instances. It also adds limited number of methods that are important for efficient pass-through processing (such as one needed when routing SOAP-messages).

Since version 3.0, stream writer will also implement "Typed Access API" on output side.

Version:
3.0.1 06-Nov-2008
Author:
Tatu Saloranta ([email protected])

Method Summary
 void closeCompletely()
          Method similar to XMLStreamWriter.close(), except that this method also does close the underlying output destination (stream) if it has not yet been closed.
 void copyEventFromReader(XMLStreamReader2 r, boolean preserveEventData)
          Method that essentially copies event that the specified reader has just read.
 String getEncoding()
          Method that can be called to get information about encoding that this writer is using (or at least claims is using).
 XMLStreamLocation2 getLocation()
          Method that should return current output location, if the writer keeps track of it; null if it does not.
 boolean isPropertySupported(String name)
          Method similar to XMLOutputFactory.isPropertySupported(java.lang.String), used to determine whether a property is supported by the Writer instance.
 boolean setProperty(String name, Object value)
          Method that can be used to set per-writer properties; a subset of properties one can set via matching XMLOutputFactory2 instance.
 void writeCData(char[] text, int start, int len)
           
 void writeDTD(String rootName, String systemId, String publicId, String internalSubset)
           
 void writeFullEndElement()
          Method similar to XMLStreamWriter.writeEndElement(), but that will always write the full end element, instead of empty element.
 void writeRaw(char[] text, int offset, int length)
          Method that writes specified content as is, without encoding or deciphering it in any way.
 void writeRaw(String text)
          Method that writes specified content as is, without encoding or deciphering it in any way.
 void writeRaw(String text, int offset, int length)
          Method that writes specified content as is, without encoding or deciphering it in any way.
 void writeSpace(char[] text, int offset, int length)
          Method that can be called to write whitespace-only content.
 void writeSpace(String text)
          Method that can be called to write whitespace-only content.
 void writeStartDocument(String version, String encoding, boolean standAlone)
           
 
Methods inherited from interface org.codehaus.stax2.typed.TypedXMLStreamWriter
writeBinary, writeBinary, writeBinaryAttribute, writeBinaryAttribute, writeBoolean, writeBooleanAttribute, writeDecimal, writeDecimalAttribute, writeDouble, writeDoubleArray, writeDoubleArrayAttribute, writeDoubleAttribute, writeFloat, writeFloatArray, writeFloatArrayAttribute, writeFloatAttribute, writeInt, writeIntArray, writeIntArrayAttribute, writeIntAttribute, writeInteger, writeIntegerAttribute, writeLong, writeLongArray, writeLongArrayAttribute, writeLongAttribute, writeQName, writeQNameAttribute
 
Methods inherited from interface javax.xml.stream.XMLStreamWriter
close, flush, getNamespaceContext, getPrefix, getProperty, setDefaultNamespace, setNamespaceContext, setPrefix, writeAttribute, writeAttribute, writeAttribute, writeCData, writeCharacters, writeCharacters, writeComment, writeDefaultNamespace, writeDTD, writeEmptyElement, writeEmptyElement, writeEmptyElement, writeEndDocument, writeEndElement, writeEntityRef, writeNamespace, writeProcessingInstruction, writeProcessingInstruction, writeStartDocument, writeStartDocument, writeStartDocument, writeStartElement, writeStartElement, writeStartElement
 
Methods inherited from interface org.codehaus.stax2.validation.Validatable
setValidationProblemHandler, stopValidatingAgainst, stopValidatingAgainst, validateAgainst
 

Method Detail

isPropertySupported

boolean isPropertySupported(String name)
Method similar to XMLOutputFactory.isPropertySupported(java.lang.String), used to determine whether a property is supported by the Writer instance. This means that this method may return false for some properties that the output 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 writer instance.


setProperty

boolean setProperty(String name,
                    Object value)
Method that can be used to set per-writer properties; a subset of properties one can set via matching XMLOutputFactory2 instance. Exactly which methods are mutable is implementation specific.

Parameters:
name - Name of the property to set
value - Value to set property to.
Returns:
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 writer implementation

getLocation

XMLStreamLocation2 getLocation()
Method that should return current output location, if the writer keeps track of it; null if it does not.


getEncoding

String getEncoding()
Method that can be called to get information about encoding that this writer is using (or at least claims is using). That is, it returns name of encoding specified when (in order of priority):


writeCData

void writeCData(char[] text,
                int start,
                int len)
                throws javax.xml.stream.XMLStreamException
Throws:
javax.xml.stream.XMLStreamException

writeDTD

void writeDTD(String rootName,
              String systemId,
              String publicId,
              String internalSubset)
              throws javax.xml.stream.XMLStreamException
Throws:
javax.xml.stream.XMLStreamException

writeFullEndElement

void writeFullEndElement()
                         throws javax.xml.stream.XMLStreamException
Method similar to XMLStreamWriter.writeEndElement(), but that will always write the full end element, instead of empty element. This only matters for cases where the element itself has no content, and if writer is allowed to write empty elements when it encounters such start/end element write pairs.

Throws:
javax.xml.stream.XMLStreamException

writeStartDocument

void writeStartDocument(String version,
                        String encoding,
                        boolean standAlone)
                        throws javax.xml.stream.XMLStreamException
Throws:
javax.xml.stream.XMLStreamException

writeSpace

void writeSpace(String text)
                throws javax.xml.stream.XMLStreamException
Method that can be called to write whitespace-only content. If so, it is to be written as is (with no escaping), and does not contain non-whitespace characters (writer may validate this, and throw an exception if it does).

This method is useful for things like outputting indentation.

Throws:
javax.xml.stream.XMLStreamException
Since:
3.0

writeSpace

void writeSpace(char[] text,
                int offset,
                int length)
                throws javax.xml.stream.XMLStreamException
Method that can be called to write whitespace-only content. If so, it is to be written as is (with no escaping), and does not contain non-whitespace characters (writer may validate this, and throw an exception if it does).

This method is useful for things like outputting indentation.

Throws:
javax.xml.stream.XMLStreamException
Since:
3.0

writeRaw

void writeRaw(String text)
              throws javax.xml.stream.XMLStreamException
Method that writes specified content as is, without encoding or deciphering it in any way. It will not update state of the writer (except by possibly flushing output of previous writes, like finishing a start element), nor be validated in any way. As such, care must be taken, if this method is used.

Method is usually used when encapsulating output from another writer as a sub-tree, or when passing through XML fragments.

NOTE: since text to be written may be anything, including markup, it can not be reliably validated. Because of this, validator(s) attached to the writer will NOT be informed about writes.

Throws:
javax.xml.stream.XMLStreamException

writeRaw

void writeRaw(String text,
              int offset,
              int length)
              throws javax.xml.stream.XMLStreamException
Method that writes specified content as is, without encoding or deciphering it in any way. It will not update state of the writer (except by possibly flushing output of previous writes, like finishing a start element), nor be validated in any way. As such, care must be taken, if this method is used.

Method is usually used when encapsulating output from another writer as a sub-tree, or when passing through XML fragments.

NOTE: since text to be written may be anything, including markup, it can not be reliably validated. Because of this, validator(s) attached to the writer will NOT be informed about writes.

Throws:
javax.xml.stream.XMLStreamException

writeRaw

void writeRaw(char[] text,
              int offset,
              int length)
              throws javax.xml.stream.XMLStreamException
Method that writes specified content as is, without encoding or deciphering it in any way. It will not update state of the writer (except by possibly flushing output of previous writes, like finishing a start element), nor be validated in any way. As such, care must be taken, if this method is used.

Method is usually used when encapsulating output from another writer as a sub-tree, or when passing through XML fragments.

NOTE: since text to be written may be anything, including markup, it can not be reliably validated. Because of this, validator(s) attached to the writer will NOT be informed about writes.

Throws:
javax.xml.stream.XMLStreamException

copyEventFromReader

void copyEventFromReader(XMLStreamReader2 r,
                         boolean preserveEventData)
                         throws javax.xml.stream.XMLStreamException
Method that essentially copies event that the specified reader has just read. This can be both more convenient (no need to worry about details) and more efficient than separately calling access methods of the reader and write methods of the writer, since writer may know more about reader than the application (and may be able to use non-public methods)

Parameters:
r - Reader to use for accessing event to copy
preserveEventData - If true, writer is not allowed to change the state of the reader (so that all the data associated with the current event has to be preserved); if false, writer is allowed to use methods that may cause some data to be discarded. Setting this to false may improve the performance, since it may allow full no-copy streaming of data, especially textual contents.
Throws:
javax.xml.stream.XMLStreamException

closeCompletely

void closeCompletely()
                     throws javax.xml.stream.XMLStreamException
Method similar to XMLStreamWriter.close(), except that this method also does close the underlying output destination (stream) if it has not yet been closed. It is specifically necessary to call this method if the parsing ends in an exception to ensure that the output destination does get properly closed, even if the stream writer would otherwise close it (as is the case for destinations it manages where calling application has no access)

Throws:
javax.xml.stream.XMLStreamException


Copyright © 2005-2013 Oracle Corporation. All Rights Reserved.