org.codehaus.stax2.XMLStreamWriter2 Maven / Gradle / Ivy
Show all versions of stax2-api Show documentation
package org.codehaus.stax2;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;
import org.codehaus.stax2.typed.TypedXMLStreamWriter;
import org.codehaus.stax2.validation.Validatable;
/**
* Extended interface that implements functionality that is necessary
* to properly build event API on top of {@link 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])
*/
public interface XMLStreamWriter2
extends TypedXMLStreamWriter,
Validatable
{
/*
/**********************************************************************
/* Configuration
/**********************************************************************
*/
/**
* Method similar to {@link javax.xml.stream.XMLOutputFactory#isPropertySupported}, 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.
*/
public boolean isPropertySupported(String name);
/**
* Method that can be used to set per-writer properties; a subset of
* properties one can set via matching
* {@link org.codehaus.stax2.XMLOutputFactory2}
* 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 IllegalArgumentException if the property is not supported
* (or recognized) by the stream writer implementation
*/
public boolean setProperty(String name, Object value);
/*
/**********************************************************************
/* Other accessors, mutators
/**********************************************************************
*/
/**
* Method that should return current output location, if the writer
* keeps track of it; null if it does not.
*/
public XMLStreamLocation2 getLocation();
/**
* 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):
*
* - Passed to one of factory methods of
* {@link javax.xml.stream.XMLOutputFactory}
*
* - Passed to
writeStartDocument method (explicitly
* or implicity; latter in cases where defaults are imposed
* by Stax specification)
*
*
*/
public String getEncoding();
/*
/**********************************************************************
/* Write methods base interface is missing
/**********************************************************************
*/
public void writeCData(char[] text, int start, int len)
throws XMLStreamException;
public void writeDTD(String rootName, String systemId, String publicId,
String internalSubset)
throws XMLStreamException;
/**
* Method similar to {@link #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.
*/
public void writeFullEndElement() throws XMLStreamException;
public void writeStartDocument(String version, String encoding,
boolean standAlone)
throws 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.
*
* @since 3.0
*/
public void writeSpace(String text)
throws 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.
*
* @since 3.0
*/
public void writeSpace(char[] text, int offset, int length)
throws XMLStreamException;
/*
/**********************************************************************
/* Pass-through methods
/**********************************************************************
*/
/**
* 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.
*/
public void writeRaw(String text) throws 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.
*/
public void writeRaw(String text, int offset, int length)
throws 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.
*/
public void writeRaw(char[] text, int offset, int length)
throws 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)
*
* @param r Reader to use for accessing event to copy
* @param 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.
*/
public void copyEventFromReader(XMLStreamReader2 r, boolean preserveEventData)
throws XMLStreamException;
/*
/**********************************************************************
/* Output handling
/**********************************************************************
*/
/**
* Method similar to
* {@link javax.xml.stream.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)
*/
public void closeCompletely() throws XMLStreamException;
}