Package org.codehaus.staxmate.out

Class SMOutputContext

  • public final class SMOutputContext
extends java.lang.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 Detail

      • NS_EMPTY

        protected static final SMNamespace NS_EMPTY

      • NS_XMLNS

        protected static final SMNamespace NS_XMLNS

      • sGlobalNsMap

        protected static final java.util.HashMap<java.lang.String,​SMNamespace> sGlobalNsMap

      • _streamWriter

        protected final org.codehaus.stax2.XMLStreamWriter2 _streamWriter

      • _rootNsContext

        protected final javax.xml.namespace.NamespaceContext _rootNsContext

      • _cfgRepairing

        protected final boolean _cfgRepairing

      • _nsPrefixPrefix

        protected java.lang.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 java.util.HashMap<java.lang.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).

      • _nsStack

        SMNamespace[] _nsStack
        Stack of bound non-default namespaces.

      • _boundNsCount

        int _boundNsCount
        Number of bound namespaces in _nsStack

      • _currElemNS

        SMNamespace _currElemNS
        Namespace of the last START_ELEMENT output.

      • _indentString

        java.lang.String _indentString
        This String is null when not doing (heuristic) indentation. Otherwise it defines the longest possible indentation String to use; subset by the offset indexes as necessary.

      • _indentOffset

        int _indentOffset
        Current offset within indentation String, if indenting. Basically offset of the first character after end of indentation String.

      • _indentStep

        int _indentStep
        Number of characters to add to _indentOffset when adding a new indentation level (and conversely, subtract when closing such level).

      • _indentSuppress

        int _indentSuppress
        Counter used to suppress indentation, for levels where text has been output (indicating either pure-text or mixed content). Set to -1 when indentation is disabled. This remains 0 when no explicit text output has been done, and is set to 1 from such a state. After becoming non-zero, it will be incremented by one for each new level (start element output), and subtracted by one for close elements.

        Since this needs to be 0 for any indentation to be output, it is also used as a 'flag' to see if indentation is enabled.

      • _indentLevelEmpty

        boolean _indentLevelEmpty
        This flag is used to prevent indentation from being added for empty leaf elements, which should either be output as empty elements, or start/end tag pair, with no intervening spaces.

    • Constructor Detail

      • SMOutputContext

        protected SMOutputContext​(org.codehaus.stax2.XMLStreamWriter2 sw,
                          javax.xml.namespace.NamespaceContext rootNsCtxt)

    • Method Detail

      • setIndentation

        public void setIndentation​(java.lang.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,
                                             javax.xml.namespace.NamespaceContext rootNsCtxt)
                                      throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • createInstance

        public static SMOutputContext createInstance​(org.codehaus.stax2.XMLStreamWriter2 sw)
                                      throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • createDocument

        public SMOutputDocument createDocument()
                                throws javax.xml.stream.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:
        javax.xml.stream.XMLStreamException

      • createDocument

        public SMOutputDocument createDocument​(java.lang.String version,
                                       java.lang.String encoding)
                                throws javax.xml.stream.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:
        javax.xml.stream.XMLStreamException

      • createDocument

        public SMOutputDocument createDocument​(java.lang.String version,
                                       java.lang.String encoding,
                                       boolean standalone)
                                throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • createRootFragment

        public SMRootFragment createRootFragment()
                                  throws javax.xml.stream.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:
        javax.xml.stream.XMLStreamException

      • createBufferedFragment

        public SMBufferedFragment createBufferedFragment()
                                          throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • createAttribute

        public SMOutputtable createAttribute​(SMNamespace ns,
                                     java.lang.String localName,
                                     java.lang.String value)

      • createAttribute

        public SMOutputtable createAttribute​(SMNamespace ns,
                                     java.lang.String localName,
                                     byte[] value)

      • createCharacters

        public SMOutputtable createCharacters​(java.lang.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​(java.lang.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​(java.lang.String text)

      • createEntityRef

        public SMOutputtable createEntityRef​(java.lang.String name)

      • createProcessingInstruction

        public SMOutputtable createProcessingInstruction​(java.lang.String target,
                                                 java.lang.String data)

      • createValue

        public SMOutputtable createValue​(boolean 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​(java.lang.String uri)

      • getNamespace

        public final SMNamespace getNamespace​(java.lang.String uri,
                                      java.lang.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​(java.lang.String text)
                     throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeCharacters

        public void writeCharacters​(char[] buf,
                            int offset,
                            int len)
                     throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeCData

        public void writeCData​(java.lang.String text)
                throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeCData

        public void writeCData​(char[] buf,
                       int offset,
                       int len)
                throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeComment

        public void writeComment​(java.lang.String text)
                  throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeEntityRef

        public void writeEntityRef​(java.lang.String name)
                    throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeProcessingInstruction

        public void writeProcessingInstruction​(java.lang.String target,
                                       java.lang.String data)
                                throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeAttribute

        public void writeAttribute​(SMNamespace ns,
                           java.lang.String localName,
                           java.lang.String value)
                    throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeAttribute

        public void writeAttribute​(SMNamespace ns,
                           java.lang.String localName,
                           int value)
                    throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeAttribute

        public void writeAttribute​(SMNamespace ns,
                           java.lang.String localName,
                           byte[] value)
                    throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • _ensureBindingForAttribute

        protected java.lang.String _ensureBindingForAttribute​(SMNamespace ns)
                                               throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • predeclareNamespace

        public void predeclareNamespace​(SMNamespace ns,
                                SMNamespace parentDefaultNS,
                                int parentNsCount)
                         throws javax.xml.stream.XMLStreamException
        Method called to try to pre-declare given namespace
        Throws:
        javax.xml.stream.XMLStreamException

      • writeStartElement

        public SMNamespace writeStartElement​(SMNamespace ns,
                                     java.lang.String localName)
                              throws javax.xml.stream.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:
        javax.xml.stream.XMLStreamException

      • writeEndElement

        public void writeEndElement​(int parentNsCount,
                            SMNamespace parentDefNs)
                     throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeStartDocument

        public void writeStartDocument()
                        throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeStartDocument

        public void writeStartDocument​(java.lang.String version,
                               java.lang.String encoding)
                        throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeStartDocument

        public void writeStartDocument​(java.lang.String version,
                               java.lang.String encoding,
                               boolean standalone)
                        throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeEndDocument

        public void writeEndDocument()
                      throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeDoctypeDecl

        public void writeDoctypeDecl​(java.lang.String rootName,
                             java.lang.String systemId,
                             java.lang.String publicId,
                             java.lang.String intSubset)
                      throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeValue

        public void writeValue​(boolean v)
                throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeValue

        public void writeValue​(int v)
                throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeValue

        public void writeValue​(long v)
                throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeValue

        public void writeValue​(double d)
                throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeValue

        public void writeValue​(byte[] data)
                throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • writeValue

        public void writeValue​(byte[] data,
                       int offset,
                       int length)
                throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • flushWriter

        public void flushWriter()
                 throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException

      • closeWriterCompletely

        public void closeWriterCompletely()
                           throws javax.xml.stream.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:
        javax.xml.stream.XMLStreamException

      • generateUnboundPrefix

        public java.lang.String generateUnboundPrefix()

      • isPrefixBound

        public boolean isPrefixBound​(java.lang.String prefix)

      • isPrefixBoundLocally

        public boolean isPrefixBoundLocally​(java.lang.String prefix,
                                    int parentNsCount)
        Similar to isPrefixBound(java.lang.String), but only considers bindings added by the current start element.

      • findRootPrefix

        public java.lang.String findRootPrefix​(SMNamespace ns)

      • getNamespaceCount

        int getNamespaceCount()
        Returns:
        Number of bound non-default namespaces (ones with explicit prefix) currently

      • bindAndWriteNs

        private void bindAndWriteNs​(SMNamespace ns,
                            java.lang.String prefix)
                     throws javax.xml.stream.XMLStreamException
        Method for establishing binding between given namespace and a non-empty prefix, as well as writing resulting namespace declaration out.
        Throws:
        javax.xml.stream.XMLStreamException

      • outputIndentation

        private void outputIndentation()
                        throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException