org.codehaus.staxmate.out

Class SMOutputContext

java.lang.Object

org.codehaus.staxmate.out.SMOutputContext

public final class SMOutputContext
extends Object

Class that encapsulates details about context in which StaxMate output is done. The most important of the details is the stream writer to use (since that is eventually invoked to do the real output), and its properties.

Usually the process of outputting XML content with StaxMate starts by instantiating an SMOutputContext. It can then be used to create output fragments; all of which bind to that context. Context is thus what "connects" various fragments when they are buffered (when there may or may not be child/parent relationships yet defined).

Context is also used (in addition to storing output relevant settings and acting as a fragment factory) as the owner of various other objects, most notable namespaces. All local namespaces are owned by one and only one context.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	_cfgPreferDefaultNs Configuration flag that specifies whether by default namespaces should bind as the default namespaces for elements or not.
protected boolean	_cfgRepairing
protected SMNamespace	_defaultNS Currently active default namespace; one that is in effect within current scope (inside currently open element, if any; if none, within root level).
protected HashMap<String,SMNamespace>	_localNsMap Map that contains all local namespaces, that is, namespaces that have been created for use with documents output using this context.
protected String	_nsPrefixPrefix Prefix to use for creating automatic namespace prefixes.
protected int	_nsPrefixSeqNr
protected NamespaceContext	_rootNsContext
protected org.codehaus.stax2.XMLStreamWriter2	_streamWriter
protected static int	DEF_NS_STACK_SIZE
protected static SMOTypedValue	FALSE_VALUE
protected static SMNamespace	NS_EMPTY
protected static SMNamespace	NS_XML
protected static SMNamespace	NS_XMLNS
protected static HashMap<String,SMNamespace>	sGlobalNsMap
protected static SMOTypedValue	TRUE_VALUE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SMOutputContext(org.codehaus.stax2.XMLStreamWriter2 sw, NamespaceContext rootNsCtxt)

Method Summary

Methods

Modifier and Type	Method and Description
protected String	_ensureBindingForAttribute(SMNamespace ns)
void	closeWriterCompletely() Method that can be called to force full closing of the underlying stream writer as well as output target it uses (usually a OutputStream or Writer).
SMOutputtable	createAttribute(SMNamespace ns, String localName, byte[] value)
SMOutputtable	createAttribute(SMNamespace ns, String localName, int value)
SMOutputtable	createAttribute(SMNamespace ns, String localName, String value)
SMBufferedFragment	createBufferedFragment()
SMOutputtable	createCData(char[] buf, int offset, int len)
SMOutputtable	createCData(String text)
SMOutputtable	createCharacters(char[] buf, int offset, int len)
SMOutputtable	createCharacters(String text)
SMOutputtable	createComment(String text)
SMOutputDocument	createDocument() Method used to create a StaxMate output fragment that corresponds to a single well-formed XML document.
SMOutputDocument	createDocument(String version, String encoding) Method used to create a StaxMate output fragment that corresponds to a single well-formed XML document.
SMOutputDocument	createDocument(String version, String encoding, boolean standalone)
SMOutputtable	createEntityRef(String name)
static SMOutputContext	createInstance(org.codehaus.stax2.XMLStreamWriter2 sw)
static SMOutputContext	createInstance(org.codehaus.stax2.XMLStreamWriter2 sw, NamespaceContext rootNsCtxt)
SMOutputtable	createNamespace(SMNamespace ns, SMNamespace parentDefaultNS, int parentNsCount) Method called by SMOutputElement to add buffered namespace pre-declaration.
SMOutputtable	createNonSharedCData(char[] buf, int offset, int len) Specialized alternative to {link #createCData(char[],int,int)} that can count on the passed char array NOT being shared.
SMOutputtable	createNonSharedCharacters(char[] buf, int offset, int len) Specialized alternative to {link #createCharacters(char[],int,int)} that can count on the passed char array NOT being shared.
SMOutputtable	createProcessingInstruction(String target, String data)
SMRootFragment	createRootFragment() Method to use when outputting an XML sub-tree, in which case the underlying stream writer may be (or has been) used for outputting XML content in addition to content that is output using StaxMate.
SMOutputtable	createValue(boolean value)
SMOutputtable	createValue(byte[] buffer)
SMOutputtable	createValue(byte[] buffer, int offset, int length)
SMOutputtable	createValue(double value)
SMOutputtable	createValue(int value)
SMOutputtable	createValue(long value)
String	findRootPrefix(SMNamespace ns)
void	flushWriter()
String	generateUnboundPrefix()
static SMNamespace	getEmptyNamespace()
SMNamespace	getNamespace(String uri)
SMNamespace	getNamespace(String uri, String prefPrefix)
org.codehaus.stax2.XMLStreamWriter2	getWriter()
boolean	isPrefixBound(String prefix)
boolean	isPrefixBoundLocally(String prefix, int parentNsCount) Similar to isPrefixBound(java.lang.String), but only considers bindings added by the current start element.
boolean	isWriterRepairing()
void	predeclareNamespace(SMNamespace ns, SMNamespace parentDefaultNS, int parentNsCount) Method called to try to pre-declare given namespace
void	setIndentation(String indentStr, int startOffset, int step) This method can be called to enable or disable heuristic indentation for the output done using this output context.
void	writeAttribute(SMNamespace ns, String localName, byte[] value)
void	writeAttribute(SMNamespace ns, String localName, int value)
void	writeAttribute(SMNamespace ns, String localName, String value)
void	writeCData(char[] buf, int offset, int len)
void	writeCData(String text)
void	writeCharacters(char[] buf, int offset, int len)
void	writeCharacters(String text)
void	writeComment(String text)
void	writeDoctypeDecl(String rootName, String systemId, String publicId, String intSubset)
void	writeEndDocument()
void	writeEndElement(int parentNsCount, SMNamespace parentDefNs)
void	writeEntityRef(String name)
void	writeProcessingInstruction(String target, String data)
void	writeStartDocument()
void	writeStartDocument(String version, String encoding)
void	writeStartDocument(String version, String encoding, boolean standalone)
SMNamespace	writeStartElement(SMNamespace ns, String localName) Method called by the element object when it is about to get written out.
void	writeValue(boolean v)
void	writeValue(byte[] data)
void	writeValue(byte[] data, int offset, int length)
void	writeValue(double d)
void	writeValue(int v)
void	writeValue(long v)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEF_NS_STACK_SIZE

protected static final int DEF_NS_STACK_SIZE

See Also:

Constant Field Values

NS_EMPTY

protected static final SMNamespace NS_EMPTY

NS_XML

protected static final SMNamespace NS_XML

NS_XMLNS

protected static final SMNamespace NS_XMLNS

sGlobalNsMap

protected static final HashMap<String,SMNamespace> sGlobalNsMap

FALSE_VALUE

protected static final SMOTypedValue FALSE_VALUE

TRUE_VALUE

protected static final SMOTypedValue TRUE_VALUE

_streamWriter

protected final org.codehaus.stax2.XMLStreamWriter2 _streamWriter

_rootNsContext

protected final NamespaceContext _rootNsContext

_cfgRepairing

protected final boolean _cfgRepairing

_nsPrefixPrefix

protected String _nsPrefixPrefix

Prefix to use for creating automatic namespace prefixes. For example, setting this to "ns" would result in automatic prefixes of form "ns1", "ns2" and so on.

_nsPrefixSeqNr

protected int _nsPrefixSeqNr

_cfgPreferDefaultNs

protected boolean _cfgPreferDefaultNs

Configuration flag that specifies whether by default namespaces should bind as the default namespaces for elements or not. If true, all unbound namespaces are always bound as the default namespace, when elements are output: if false, more complicated logics is used (which considers preferred prefixes, past bindings etc).

_localNsMap

protected HashMap<String,SMNamespace> _localNsMap

Map that contains all local namespaces, that is, namespaces that have been created for use with documents output using this context.

_defaultNS

protected SMNamespace _defaultNS

Currently active default namespace; one that is in effect within current scope (inside currently open element, if any; if none, within root level).

Constructor Detail

SMOutputContext

protected SMOutputContext(org.codehaus.stax2.XMLStreamWriter2 sw,
               NamespaceContext rootNsCtxt)

Method Detail

setIndentation

public void setIndentation(String indentStr,
                  int startOffset,
                  int step)

This method can be called to enable or disable heuristic indentation for the output done using this output context.

Here are some example calls:

context.setIndentation("\n ", 1, 2); // indent by lf and 2 spaces per level context.setIndentation(null, 0, 0); // disable indentation context.setIndentation("\r\n\t\t\t\t\t\t\t\t", 2, 1); // indent by windows lf and 1 tab per level

Parameters:

indentStr - String to use for indentation; if non-null, will enable indentation, if null, will disable it. Used in conjunction with the other arguments

startOffset - Initial character offset for the first level of indentation (current context; usually root context): basically, number of leading characters from indentStr to output.

step - Number of characters to add from the indentation String for each new level (and to subtract when closing levels).

createInstance

public static SMOutputContext createInstance(org.codehaus.stax2.XMLStreamWriter2 sw,
                             NamespaceContext rootNsCtxt)
                                      throws XMLStreamException

Throws:

XMLStreamException

createInstance

public static SMOutputContext createInstance(org.codehaus.stax2.XMLStreamWriter2 sw)
                                      throws XMLStreamException

Throws:

XMLStreamException

createDocument

public SMOutputDocument createDocument()
                                throws XMLStreamException

Method used to create a StaxMate output fragment that corresponds to a single well-formed XML document. Assumption, then, is that the underlying stream writer has only been created, but no writes have yet been done.

This version of the method calls the matching no-arguments method in the stream writer.

Throws:

XMLStreamException

createDocument

public SMOutputDocument createDocument(String version,
                              String encoding)
                                throws XMLStreamException

Method used to create a StaxMate output fragment that corresponds to a single well-formed XML document. Assumption, then, is that the underlying stream writer has only been created, but no writes have yet been done.

This version of the method calls the matching stream writer method which takes full xml declaration information.

Throws:

XMLStreamException

createDocument

public SMOutputDocument createDocument(String version,
                              String encoding,
                              boolean standalone)
                                throws XMLStreamException

Throws:

XMLStreamException

createRootFragment

public SMRootFragment createRootFragment()
                                  throws XMLStreamException

Method to use when outputting an XML sub-tree, in which case the underlying stream writer may be (or has been) used for outputting XML content in addition to content that is output using StaxMate. Resulting fragment is not buffered, and will thus be fully streamed (except for buffering caused by adding buffered children)

Throws:

XMLStreamException

createBufferedFragment

public SMBufferedFragment createBufferedFragment()
                                          throws XMLStreamException

Throws:

XMLStreamException

createAttribute

public SMOutputtable createAttribute(SMNamespace ns,
                            String localName,
                            String value)

createAttribute

public SMOutputtable createAttribute(SMNamespace ns,
                            String localName,
                            int value)

createAttribute

public SMOutputtable createAttribute(SMNamespace ns,
                            String localName,
                            byte[] value)

createNamespace

public SMOutputtable createNamespace(SMNamespace ns,
                            SMNamespace parentDefaultNS,
                            int parentNsCount)

Method called by SMOutputElement to add buffered namespace pre-declaration.

createCharacters

public SMOutputtable createCharacters(String text)

createCharacters

public SMOutputtable createCharacters(char[] buf,
                             int offset,
                             int len)

createNonSharedCharacters

public SMOutputtable createNonSharedCharacters(char[] buf,
                                      int offset,
                                      int len)

Specialized alternative to {link #createCharacters(char[],int,int)} that can count on the passed char array NOT being shared. This means that no intermediate copy needs to be done -- instance can just use the passed in reference knowing it will not be messed by other threads.

createCData

public SMOutputtable createCData(String text)

createCData

public SMOutputtable createCData(char[] buf,
                        int offset,
                        int len)

createNonSharedCData

public SMOutputtable createNonSharedCData(char[] buf,
                                 int offset,
                                 int len)

Specialized alternative to {link #createCData(char[],int,int)} that can count on the passed char array NOT being shared. This means that no intermediate copy needs to be done -- instance can just use the passed in reference knowing it will not be messed by other threads.

createComment

public SMOutputtable createComment(String text)

createEntityRef

public SMOutputtable createEntityRef(String name)

createProcessingInstruction

public SMOutputtable createProcessingInstruction(String target,
                                        String data)

createValue

public SMOutputtable createValue(boolean value)

createValue

public SMOutputtable createValue(int value)

createValue

public SMOutputtable createValue(long value)

createValue

public SMOutputtable createValue(double value)

createValue

public SMOutputtable createValue(byte[] buffer)

createValue

public SMOutputtable createValue(byte[] buffer,
                        int offset,
                        int length)

getNamespace

public final SMNamespace getNamespace(String uri)

getNamespace

public final SMNamespace getNamespace(String uri,
                       String prefPrefix)

getEmptyNamespace

public static final SMNamespace getEmptyNamespace()

getWriter

public final org.codehaus.stax2.XMLStreamWriter2 getWriter()

isWriterRepairing

public final boolean isWriterRepairing()

writeCharacters

public void writeCharacters(String text)
                     throws XMLStreamException

Throws:

XMLStreamException

writeCharacters

public void writeCharacters(char[] buf,
                   int offset,
                   int len)
                     throws XMLStreamException

Throws:

XMLStreamException

writeCData

public void writeCData(String text)
                throws XMLStreamException

Throws:

XMLStreamException

writeCData

public void writeCData(char[] buf,
              int offset,
              int len)
                throws XMLStreamException

Throws:

XMLStreamException

writeComment

public void writeComment(String text)
                  throws XMLStreamException

Throws:

XMLStreamException

writeEntityRef

public void writeEntityRef(String name)
                    throws XMLStreamException

Throws:

XMLStreamException

writeProcessingInstruction

public void writeProcessingInstruction(String target,
                              String data)
                                throws XMLStreamException

Throws:

XMLStreamException

writeAttribute

public void writeAttribute(SMNamespace ns,
                  String localName,
                  String value)
                    throws XMLStreamException

Throws:

XMLStreamException

writeAttribute

public void writeAttribute(SMNamespace ns,
                  String localName,
                  int value)
                    throws XMLStreamException

Throws:

XMLStreamException

writeAttribute

public void writeAttribute(SMNamespace ns,
                  String localName,
                  byte[] value)
                    throws XMLStreamException

Throws:

XMLStreamException

_ensureBindingForAttribute

protected String _ensureBindingForAttribute(SMNamespace ns)
                                     throws XMLStreamException

Throws:

XMLStreamException

predeclareNamespace

public void predeclareNamespace(SMNamespace ns,
                       SMNamespace parentDefaultNS,
                       int parentNsCount)
                         throws XMLStreamException

Method called to try to pre-declare given namespace

Throws:

XMLStreamException

writeStartElement

public SMNamespace writeStartElement(SMNamespace ns,
                            String localName)
                              throws XMLStreamException

Method called by the element object when it is about to get written out. In this case, element will keep track of part of namespace context information for this context object (to save allocation of separate namespace context object).

Returns:

Namespace that was the active namespace in parent scope of this element. Will be different from the default namespace if a new default namespace was declared to be used by this element.

Throws:

XMLStreamException

writeEndElement

public void writeEndElement(int parentNsCount,
                   SMNamespace parentDefNs)
                     throws XMLStreamException

Throws:

XMLStreamException

writeStartDocument

public void writeStartDocument()
                        throws XMLStreamException

Throws:

XMLStreamException

writeStartDocument

public void writeStartDocument(String version,
                      String encoding)
                        throws XMLStreamException

Throws:

XMLStreamException

writeStartDocument

public void writeStartDocument(String version,
                      String encoding,
                      boolean standalone)
                        throws XMLStreamException

Throws:

XMLStreamException

writeEndDocument

public void writeEndDocument()
                      throws XMLStreamException

Throws:

XMLStreamException

writeDoctypeDecl

public void writeDoctypeDecl(String rootName,
                    String systemId,
                    String publicId,
                    String intSubset)
                      throws XMLStreamException

Throws:

XMLStreamException

writeValue

public void writeValue(boolean v)
                throws XMLStreamException

Throws:

XMLStreamException

writeValue

public void writeValue(int v)
                throws XMLStreamException

Throws:

XMLStreamException

writeValue

public void writeValue(long v)
                throws XMLStreamException

Throws:

XMLStreamException

writeValue

public void writeValue(double d)
                throws XMLStreamException

Throws:

XMLStreamException

writeValue

public void writeValue(byte[] data)
                throws XMLStreamException

Throws:

XMLStreamException

writeValue

public void writeValue(byte[] data,
              int offset,
              int length)
                throws XMLStreamException

Throws:

XMLStreamException

flushWriter

public void flushWriter()
                 throws XMLStreamException

Throws:

XMLStreamException

closeWriterCompletely

public void closeWriterCompletely()
                           throws XMLStreamException

Method that can be called to force full closing of the underlying stream writer as well as output target it uses (usually a OutputStream or Writer). Latter is done by calling XMLStreamWriter2.closeCompletely() on stream writer.

Throws:

XMLStreamException

generateUnboundPrefix

public String generateUnboundPrefix()

isPrefixBound

public boolean isPrefixBound(String prefix)

isPrefixBoundLocally

public boolean isPrefixBoundLocally(String prefix,
                           int parentNsCount)

Similar to isPrefixBound(java.lang.String), but only considers bindings added by the current start element.

findRootPrefix

public String findRootPrefix(SMNamespace ns)