org.apache.xmlbeans

## Interface XmlTokenSource

- All Known Subinterfaces:
    SimpleValue, XmlAnySimpleType, XmlAnyURI, XmlBase64Binary, XmlBoolean, XmlByte, XmlCursor, XmlDate, XmlDateTime, XmlDecimal, XmlDouble, XmlDuration, XmlENTITIES, XmlENTITY, XmlFloat, XmlGDay, XmlGMonth, XmlGMonthDay, XmlGYear, XmlGYearMonth, XmlHexBinary, XmlID, XmlIDREF, XmlIDREFS, XmlInt, XmlInteger, XmlLanguage, XmlLong, XmlName, XmlNCName, XmlNegativeInteger, XmlNMTOKEN, XmlNMTOKENS, XmlNonNegativeInteger, XmlNonPositiveInteger, XmlNormalizedString, XmlNOTATION, XmlObject, XmlPositiveInteger, XmlQName, XmlShort, XmlString, XmlTime, XmlToken, XmlUnsignedByte, XmlUnsignedInt, XmlUnsignedLong, XmlUnsignedShort
  All Known Implementing Classes:
    Cursor, FilterXmlObject, JavaBase64Holder, JavaBase64HolderEx, JavaBooleanHolder, JavaBooleanHolderEx, JavaDecimalHolder, JavaDecimalHolderEx, JavaDoubleHolder, JavaDoubleHolderEx, JavaFloatHolder, JavaFloatHolderEx, JavaGDateHolderEx, JavaGDurationHolderEx, JavaHexBinaryHolder, JavaHexBinaryHolderEx, JavaIntegerHolder, JavaIntegerHolderEx, JavaIntHolder, JavaIntHolderEx, JavaLongHolder, JavaLongHolderEx, JavaNotationHolder, JavaNotationHolderEx, JavaQNameHolder, JavaQNameHolderEx, JavaStringEnumerationHolderEx, JavaStringHolder, JavaStringHolderEx, JavaUriHolder, JavaUriHolderEx, XmlAnySimpleTypeImpl, XmlAnySimpleTypeRestriction, XmlAnyTypeImpl, XmlAnyUriImpl, XmlAnyUriRestriction, XmlBase64BinaryImpl, XmlBase64BinaryRestriction, XmlBooleanImpl, XmlBooleanRestriction, XmlByteImpl, XmlComplexContentImpl, XmlDateImpl, XmlDateTimeImpl, XmlDecimalImpl, XmlDecimalRestriction, XmlDoubleImpl, XmlDoubleRestriction, XmlDurationImpl, XmlEntitiesImpl, XmlEntityImpl, XmlFloatImpl, XmlFloatRestriction, XmlGDayImpl, XmlGMonthDayImpl, XmlGMonthImpl, XmlGYearImpl, XmlGYearMonthImpl, XmlHexBinaryImpl, XmlHexBinaryRestriction, XmlIdImpl, XmlIdRefImpl, XmlIdRefsImpl, XmlIntegerImpl, XmlIntegerRestriction, XmlIntImpl, XmlIntRestriction, XmlLanguageImpl, XmlListImpl, XmlLongImpl, XmlLongRestriction, XmlNameImpl, XmlNCNameImpl, XmlNegativeIntegerImpl, XmlNmTokenImpl, XmlNmTokensImpl, XmlNonNegativeIntegerImpl, XmlNonPositiveIntegerImpl, XmlNormalizedStringImpl, XmlNotationImpl, XmlNotationRestriction, XmlObjectBase, XmlPositiveIntegerImpl, XmlQNameImpl, XmlQNameRestriction, XmlShortImpl, XmlStringEnumeration, XmlStringImpl, XmlStringRestriction, XmlTimeImpl, XmlTokenImpl, XmlUnionImpl, XmlUnsignedByteImpl, XmlUnsignedIntImpl, XmlUnsignedLongImpl, XmlUnsignedShortImpl

      public interface XmlTokenSource

  Represents a holder of XML that can return an `XmlCursor` or copy itself to various media such as `Writers` or `Files`. Both `XmlObject` (and thus all XML Beans) and `XmlCursor` are XmlTokenSource implementations.
  See Also:
    `XmlObject`, `XmlCursor`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `XmlDocumentProperties` | `documentProperties()` Returns the XmlDocumentProperties object for the document this token source is associated with.
    `void` | `dump()` Prints to stdout the state of the document in which this token source is positioned.
    `Node` | `getDomNode()` Returns a W3C DOM Node containing the XML represented by this source.
    `Object` | `monitor()` Returns the synchronization object for the document.
    `XmlCursor` | `newCursor()` Returns a new XML cursor.
    `Node` | `newDomNode()` Returns a W3C DOM Node containing the XML represented by this source.
    `Node` | `newDomNode(XmlOptions options)` Just like newDomNode() but with options.
    `InputStream` | `newInputStream()` Returns a new stream containing standard XML text, encoded according to the given encoding.
    `InputStream` | `newInputStream(XmlOptions options)` Just like newInputStream(String encoding) but with options.
    `Reader` | `newReader()` Returns a new character reader containing XML text.
    `Reader` | `newReader(XmlOptions options)` Just like newReader() but with options.
    `XMLStreamReader` | `newXMLStreamReader()` Returns a new XMLStreamReader.
    `XMLStreamReader` | `newXMLStreamReader(XmlOptions options)` Returns a new XMLStreamReader.
    `void` | `save(ContentHandler ch, LexicalHandler lh)` Writes the XML represented by this source to the given SAX content and lexical handlers.
    `void` | `save(ContentHandler ch, LexicalHandler lh, XmlOptions options)` Writes the XML represented by this source to the given SAX content and lexical handlers.
    `void` | `save(File file)` Writes the XML represented by this source to the given File.
    `void` | `save(File file, XmlOptions options)` Writes the XML represented by this source to the given File.
    `void` | `save(OutputStream os)` Writes the XML represented by this source to the given output stream.
    `void` | `save(OutputStream os, XmlOptions options)` Writes the XML represented by this source to the given output stream.
    `void` | `save(Writer w)` Writes the XML represented by this source to the given output.
    `void` | `save(Writer w, XmlOptions options)` Writes the XML represented by this source to the given output.
    `String` | `xmlText()` Returns standard XML text.
    `String` | `xmlText(XmlOptions options)` Just like xmlText() but with options.

- - ### Method Detail

    - #### monitor

          Object monitor()

      Returns the synchronization object for the document. If concurrent multithreaded access to a document is required, the access should should be protected by synchronizing on this monitor() object. There is one monitor per XML document tree.

    - #### documentProperties

          XmlDocumentProperties documentProperties()

      Returns the XmlDocumentProperties object for the document this token source is associated with.

    - #### newCursor

          XmlCursor newCursor()

      Returns a new XML cursor.

      A cursor provides random access to all the tokens in the XML data, plus the ability to extract strongly-typed XmlObjects for the data. If the data is not read-only, the XML cursor also allows modifications to the data.

      Using a cursor for the first time typically forces the XML document into memory.

    - #### newXMLStreamReader

          XMLStreamReader newXMLStreamReader()

      Returns a new XMLStreamReader.

      The stream starts at the current begin-tag or begin-document position and ends at the matching end-tag or end-document.

      This is a fail-fast stream, so if the underlying data is changed while the stream is being read, the stream throws a ConcurrentModificationException.

    - #### xmlText

          String xmlText()

      Returns standard XML text.

      The text returned represents the document contents starting at the current begin-tag or begin-document and ending at the matching end-tag or end-document. This is same content as newReader, but it is returned as a single string.

      Throws an IllegalStateException if the XmlTokenSource is not positioned at begin-tag or begin-document (e.g., if it is at an attribute).

      Note that this method does not produce XML with the XML declaration, including the encoding information. To save the XML declaration with the XML, see `save(OutputStream)` or `save(OutputStream, XmlOptions)`.

    - #### newInputStream

          InputStream newInputStream()

      Returns a new stream containing standard XML text, encoded according to the given encoding.

      The byte stream contains contents starting at the current begin-tag or begin-document and ending at the matching end-tag or end-document. The specified encoding is used and also emitted in a PI at the beginning of the stream.

      This is a fail-fast stream, so if the underlying data is changed while the stream is being read, the stream throws a ConcurrentModificationException.

      Throws an IllegalStateException if the XmlTokenSource is not positioned at begin-tag or begin-document (e.g., if it is at an attribute).

    - #### newReader

          Reader newReader()

      Returns a new character reader containing XML text.

      The contents of the reader represents the document contents starting at the current begin-tag or begin-document and ending at the matching end-tag or end-document. No encoding annotation will be made in the text itself.

      This is a fail-fast reader, so if the underlying data is changed while the reader is being read, the reader throws a ConcurrentModificationException.

      Throws an IllegalStateException if the XmlTokenSource is not positioned at begin-tag or begin-document (e.g., if it is at an attribute).

    - #### newDomNode

          Node newDomNode()

      Returns a W3C DOM Node containing the XML represented by this source. This is a copy of the XML, it is not a live with the underlying store of this token source. If this is the document node, then a Document is returned, else a DocumentFragment is returned.

    - #### getDomNode

          Node getDomNode()

      Returns a W3C DOM Node containing the XML represented by this source. This is a live DOM node, not a copy. Any changes made through this node are immediately reflected in the document associated with this token source. Depending on the kind of token this XmlTokenSource represents, an appropriate node will be returned.

    - #### save

          void save(ContentHandler ch,
                    LexicalHandler lh)
             throws SAXException

      Writes the XML represented by this source to the given SAX content and lexical handlers. Note that this method does not save the XML declaration, including the encoding information. To save the XML declaration with the XML, see `save(OutputStream)`, `save(OutputStream, XmlOptions)`, `save(File)` or `save(File, XmlOptions)`.
      Throws:
        `SAXException`

    - #### save

          void save(File file)
             throws IOException

      Writes the XML represented by this source to the given File. This method will save the XML declaration, including encoding information, with the XML.
      Throws:
        `IOException`

    - #### save

          void save(OutputStream os)
             throws IOException

      Writes the XML represented by this source to the given output stream. This method will save the XML declaration, including encoding information, with the XML.
      Throws:
        `IOException`

    - #### save

          void save(Writer w)
             throws IOException

      Writes the XML represented by this source to the given output. Note that this method does not save the XML declaration, including the encoding information. To save the XML declaration with the XML, see `save(OutputStream)`, `save(OutputStream, XmlOptions)`, `save(File)` or `save(File, XmlOptions)`.
      Throws:
        `IOException`

    - #### newXMLStreamReader

          XMLStreamReader newXMLStreamReader(XmlOptions options)

      Returns a new XMLStreamReader.

      The stream starts at the current begin-tag or begin-document position and ends at the matching end-tag or end-document.

      This is a fail-fast stream, so if the underlying data is changed while the stream is being read, the stream throws a ConcurrentModificationException.

      Throws an IllegalStateException if the XmlTokenSource is not positioned at begin-tag or begin-document (e.g., if it is at an attribute).

      To specify this | Use this method
      --- | ---
      The character encoding to use when converting the character data in the XML to bytess. | `XmlOptions.setCharacterEncoding(java.lang.String)`
      Prefix-to-namespace mappings that should be assumed when saving this XML. This is useful when the resulting XML will be part of a larger XML document, ensuring that this inner document will take advantage of namespaces defined in the outer document. | `XmlOptions.setSaveImplicitNamespaces(java.util.Map<java.lang.String, java.lang.String>)`
      Suggested namespace prefixes to use when saving. Used only when a namespace attribute needs to be synthesized. | `XmlOptions.setSaveSuggestedPrefixes(java.util.Map<java.lang.String, java.lang.String>)`
      That namespace attributes should occur first in elements when the XML is saved. By default, they occur last. | `XmlOptions.setSaveNamespacesFirst()`
      The XML should be pretty printed when saved. Note that this should only be used for debugging. | `XmlOptions.setSavePrettyPrint()`
      The number of spaces to use when indenting for pretty printing. The default is 2. | `XmlOptions.setSavePrettyPrintIndent(int)`
      The additional number of spaces indented from the left for pretty printed XML. | `XmlOptions.setSavePrettyPrintOffset(int)`
      To minimize the number of namespace attributes generated for the saved XML. Note that this can reduce performance significantly. | `XmlOptions.setSaveAggressiveNamespaces()`
      To reduce the size of the saved document by allowing the use of the default namespace. Note that this can potentially change the semantic meaning of the XML if unprefixed QNames are present as the value of an attribute or element. | `XmlOptions.setUseDefaultNamespace()`
      To filter out processing instructions with the specified target name. | `XmlOptions.setSaveFilterProcinst(java.lang.String)`
      Change the QName of the synthesized root element when saving. This replaces "xml-fragment" with "fragment" in the namespace http://www.openuri.org/fragment | `XmlOptions.setSaveUseOpenFrag()`
      Saving should begin on the element's contents. | `XmlOptions.setSaveInner()`
      Saving should begin on the element, rather than its contents. | `XmlOptions.setSaveOuter()`
      To rename the document element, or to specify the document element for this XML. | `XmlOptions.setSaveSyntheticDocumentElement(javax.xml.namespace.QName)`

      Parameters:
        `options` - Any of the described options. Options map may be null.
      Returns:
        A new validating XMLStreamReader.
      See Also:
        `XmlOptions`

    - #### xmlText

          String xmlText(XmlOptions options)

      Just like xmlText() but with options. Options map may be null.

      Note that this method does not produce XML with the XML declaration, including the encoding information. To save the XML declaration with the XML, see `save(OutputStream)` or `save(OutputStream, XmlOptions)`.

      See Also:
        `XmlOptions`

    - #### newInputStream

          InputStream newInputStream(XmlOptions options)

      Just like newInputStream(String encoding) but with options. Options map may be null.
      See Also:
        `XmlOptions`

    - #### newReader

          Reader newReader(XmlOptions options)

      Just like newReader() but with options. Options map may be null.
      See Also:
        `XmlOptions`

    - #### newDomNode

          Node newDomNode(XmlOptions options)

      Just like newDomNode() but with options. Options map may be null.
      See Also:
        `XmlOptions`

    - #### save

          void save(ContentHandler ch,
                    LexicalHandler lh,
                    XmlOptions options)
             throws SAXException

      Writes the XML represented by this source to the given SAX content and lexical handlers. Note that this method does not save the XML declaration, including the encoding information. To save the XML declaration with the XML, see `save(OutputStream)`, `save(OutputStream, XmlOptions)`, `save(File)` or `save(File, XmlOptions)`.
      Throws:
        `SAXException`

    - #### save

          void save(File file,
                    XmlOptions options)
             throws IOException

      Writes the XML represented by this source to the given File. This method will save the XML declaration, including encoding information, with the XML.
      Throws:
        `IOException`

    - #### save

          void save(OutputStream os,
                    XmlOptions options)
             throws IOException

      Writes the XML represented by this source to the given output stream. This method will save the XML declaration, including encoding information, with the XML.
      Throws:
        `IOException`

    - #### save

          void save(Writer w,
                    XmlOptions options)
             throws IOException

      Writes the XML represented by this source to the given output. Note that this method does not save the XML declaration, including the encoding information. To save the XML declaration with the XML, see `save(OutputStream)`, `save(OutputStream, XmlOptions)`, `save(File)` or `save(File, XmlOptions)`.
      Throws:
        `IOException`

    - #### dump

          void dump()

      Prints to stdout the state of the document in which this token source is positioned. This is very implementation specific and may change at any time. Dump can be useful for debugging purposes. It is very different from the save methods which produce XML text which only approximates the actual state of the document.