Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.xml.stream.buffer
Class XMLStreamBuffer

    java.lang.Object
      com.sun.xml.stream.buffer.XMLStreamBuffer

Direct Known Subclasses:
  MutableXMLStreamBuffer, XMLStreamBufferMark

    public abstract class XMLStreamBuffer

extends java.lang.Object

An immutable stream-based buffer of an XML infoset.

A XMLStreamBuffer is an abstract class. It is immutable with respect to the methods on the class, which are non-modifying in terms of state.

A XMLStreamBuffer can be processed using specific SAX and StAX-based processors. Utility methods on XMLStreamBuffer are provided for such functionality that utilize SAX and StAX-based processors. The same instance of a XMLStreamBuffer may be processed multiple times and concurrently by more than one processor.

There are two concrete implementations of XMLStreamBuffer. The first, `MutableXMLStreamBuffer`, can be instantiated for the creation of a buffer using SAX and StAX-based creators, and from which may be processed as an XMLStreamBuffer. The second, `XMLStreamBufferMark`, can be instantiated to mark into an existing buffer that is being created or processed. This allows a subtree of `XMLStreamBuffer` to be treated as its own `XMLStreamBuffer`.

A XMLStreamBuffer can represent a complete XML infoset or a subtree of an XML infoset. It is also capable of representing a "forest", where the buffer represents multiple adjacent XML elements, although in this mode there are restrictions about how you can consume such forest, because not all XML APIs handle forests very well.

Field Summary
`protected com.sun.xml.stream.buffer.FragmentedArray<char[]>` | `_contentCharactersBuffer` Fragmented array to hold content information in a shared char[]
`protected int` | `_contentCharactersBufferPtr`
`protected com.sun.xml.stream.buffer.FragmentedArray<java.lang.Object[]>` | `_contentObjects` Fragmented array to hold content information as objects
`protected int` | `_contentObjectsPtr`
`protected boolean` | `_hasInternedStrings` True if the buffer was created from a parser that interns Strings as specified by the SAX interning features
`protected java.util.Map<java.lang.String,java.lang.String>` | `_inscopeNamespaces` In scope namespaces on a fragment
`protected com.sun.xml.stream.buffer.FragmentedArray<byte[]>` | `_structure` Fragmented array to hold structural information
`protected int` | `_structurePtr`
`protected com.sun.xml.stream.buffer.FragmentedArray<java.lang.String[]>` | `_structureStrings` Fragmented array to hold structural information as strings
`protected int` | `_structureStringsPtr`
`protected java.lang.String` | `systemId` The system identifier associated with the buffer
`protected int` | `treeCount` Number of trees in this stream buffer.

Constructor Summary
`XMLStreamBuffer()`

Method Summary
`static XMLStreamBuffer` | `createNewBufferFromXMLReader(org.xml.sax.XMLReader reader, java.io.InputStream in)` Create a new buffer from a `XMLReader` and `InputStream`.
`static XMLStreamBuffer` | `createNewBufferFromXMLReader(org.xml.sax.XMLReader reader, java.io.InputStream in, java.lang.String systemId)` Create a new buffer from a `XMLReader` and `InputStream`.
`static XMLStreamBuffer` | `createNewBufferFromXMLStreamReader(javax.xml.stream.XMLStreamReader reader)` Create a new buffer from a XMLStreamReader.
`protected com.sun.xml.stream.buffer.FragmentedArray<char[]>` | `getContentCharactersBuffer()`
`protected int` | `getContentCharactersBufferPtr()`
`protected com.sun.xml.stream.buffer.FragmentedArray<java.lang.Object[]>` | `getContentObjects()`
`protected int` | `getContentObjectsPtr()`
`java.util.Map<java.lang.String,java.lang.String>` | `getInscopeNamespaces()` Get the in-scope namespaces.
`protected com.sun.xml.stream.buffer.FragmentedArray<byte[]>` | `getStructure()`
`protected int` | `getStructurePtr()`
`protected com.sun.xml.stream.buffer.FragmentedArray<java.lang.String[]>` | `getStructureStrings()`
`protected int` | `getStructureStringsPtr()`
`java.lang.String` | `getSystemId()` Get the system identifier associated with the buffer.
`boolean` | `hasInternedStrings()` Has the buffer been created using Strings that have been interned for certain properties of information items.
`boolean` | `isCreated()` Is the buffer created by creator.
`boolean` | `isElementFragment()` Is the buffer a representation of a fragment of an XML infoset that is an element (and its contents).
`boolean` | `isForest()` Returns ture if this buffer represents a forest, which is are more than one adjacent XML elements.
`boolean` | `isFragment()` Is the buffer a representation of a fragment of an XML infoset.
`SAXBufferProcessor` | `readAsXMLReader()` Deprecated. Use `readAsXMLReader(boolean)`
`SAXBufferProcessor` | `readAsXMLReader(boolean produceFragmentEvent)` Reads the contents of the buffer from a `XMLReader`.
`StreamReaderBufferProcessor` | `readAsXMLStreamReader()` Read the contents of the buffer as a `XMLStreamReader`.
`void` | `writeTo(org.xml.sax.ContentHandler handler)` Deprecated. Use `writeTo(ContentHandler,boolean)`
`void` | `writeTo(org.xml.sax.ContentHandler handler, boolean produceFragmentEvent)` Write the contents of the buffer to a `ContentHandler`.
`void` | `writeTo(org.xml.sax.ContentHandler handler, org.xml.sax.ErrorHandler errorHandler)`
`void` | `writeTo(org.xml.sax.ContentHandler handler, org.xml.sax.ErrorHandler errorHandler, boolean produceFragmentEvent)` Write the contents of the buffer to a `ContentHandler` with errors report to a `ErrorHandler`.
`org.w3c.dom.Node` | `writeTo(org.w3c.dom.Node n)` Writes out the contents of this buffer as DOM node and append that to the given node.
`void` | `writeToXMLStreamWriter(javax.xml.stream.XMLStreamWriter writer)` Deprecated. Use `writeToXMLStreamWriter(XMLStreamWriter, boolean)`
`void` | `writeToXMLStreamWriter(javax.xml.stream.XMLStreamWriter writer, boolean writeAsFragment)` Write the contents of the buffer to an XMLStreamWriter.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### _inscopeNamespaces

    protected java.util.Map<java.lang.String,java.lang.String> _inscopeNamespaces

  In scope namespaces on a fragment

### _hasInternedStrings

    protected boolean _hasInternedStrings

  True if the buffer was created from a parser that interns Strings as specified by the SAX interning features

### _structure

    protected com.sun.xml.stream.buffer.FragmentedArray<byte[]> _structure

  Fragmented array to hold structural information

### _structurePtr

    protected int _structurePtr

### _structureStrings

    protected com.sun.xml.stream.buffer.FragmentedArray<java.lang.String[]> _structureStrings

  Fragmented array to hold structural information as strings

### _structureStringsPtr

    protected int _structureStringsPtr

### _contentCharactersBuffer

    protected com.sun.xml.stream.buffer.FragmentedArray<char[]> _contentCharactersBuffer

  Fragmented array to hold content information in a shared char[]

### _contentCharactersBufferPtr

    protected int _contentCharactersBufferPtr

### _contentObjects

    protected com.sun.xml.stream.buffer.FragmentedArray<java.lang.Object[]> _contentObjects

  Fragmented array to hold content information as objects

### _contentObjectsPtr

    protected int _contentObjectsPtr

### treeCount

    protected int treeCount

  Number of trees in this stream buffer.

  1 if there's only one, which is the normal case. When the buffer holds a forest, this value is greater than 1. If the buffer is empty, then 0.

  Notice that we cannot infer this value by looking at the `FragmentedArray`s, because this `XMLStreamBuffer` maybe a view of a portion of another bigger `XMLStreamBuffer`.

### systemId

    protected java.lang.String systemId

  The system identifier associated with the buffer

Constructor Detail

### XMLStreamBuffer

    public XMLStreamBuffer()

Method Detail

### isCreated

    public final boolean isCreated()

  Is the buffer created by creator.

  Returns:
    `true` if the buffer has been created.

### isFragment

    public final boolean isFragment()

  Is the buffer a representation of a fragment of an XML infoset.

  Returns:
    `true` if the buffer is a representation of a fragment of an XML infoset.

### isElementFragment

    public final boolean isElementFragment()

  Is the buffer a representation of a fragment of an XML infoset that is an element (and its contents).

  Returns:
    `true` if the buffer a representation of a fragment of an XML infoset that is an element (and its contents).

### isForest

    public final boolean isForest()

  Returns ture if this buffer represents a forest, which is are more than one adjacent XML elements.

### getSystemId

    public final java.lang.String getSystemId()

  Get the system identifier associated with the buffer.

  Returns:
    The system identifier.

### getInscopeNamespaces

    public final java.util.Map<java.lang.String,java.lang.String> getInscopeNamespaces()

  Get the in-scope namespaces.

  The in-scope namespaces will be empty if the buffer is not a fragment (`isFragment()` returns `false`). The in-scope namespace will correspond to the in-scope namespaces of the fragment if the buffer is a fragment (`isFragment()` returns `false`). The in-scope namespaces will include any namespace delcarations on an element if the fragment correspond to that of an element (`isElementFragment()` returns `false`).

  Returns:
    The in-scope namespaces of the XMLStreamBuffer. Prefix to namespace URI.

### hasInternedStrings

    public final boolean hasInternedStrings()

  Has the buffer been created using Strings that have been interned for certain properties of information items. The Strings that are interned are those that correspond to Strings that are specified by the SAX API "string-interning" property (see here).

  An buffer may have been created, for example, from an XML document parsed using the Xerces SAX parser. The Xerces SAX parser will have interned certain Strings according to the SAX string interning property. This method enables processors to avoid the duplication of String interning if such a feature is required by a procesing application and the buffer being processed was created using Strings that have been interned.

  Returns:
    `true` if the buffer has been created using Strings that have been interned.

### readAsXMLStreamReader

    public final StreamReaderBufferProcessor readAsXMLStreamReader()
                                                            throws javax.xml.stream.XMLStreamException

  Read the contents of the buffer as a `XMLStreamReader`.

  Returns:
    A an instance of a `StreamReaderBufferProcessor`. Always non-null.
  Throws:
    `javax.xml.stream.XMLStreamException`

### writeToXMLStreamWriter

    public final void writeToXMLStreamWriter(javax.xml.stream.XMLStreamWriter writer,
                                             boolean writeAsFragment)
                                      throws javax.xml.stream.XMLStreamException

  Write the contents of the buffer to an XMLStreamWriter.

  The XMLStreamBuffer will be written out to the XMLStreamWriter using an instance of `StreamWriterBufferProcessor`.

  Parameters:
    `writer` - A XMLStreamWriter to write to.
    `writeAsFragment` - If true, `XMLStreamWriter` will not receive `XMLStreamWriter.writeStartDocument()` nor `XMLStreamWriter.writeEndDocument()`. This is desirable behavior when you are writing the contents of a buffer into a bigger document.
  Throws:
    `javax.xml.stream.XMLStreamException`

### writeToXMLStreamWriter

    public final void writeToXMLStreamWriter(javax.xml.stream.XMLStreamWriter writer)
                                      throws javax.xml.stream.XMLStreamException

  Deprecated. Use `writeToXMLStreamWriter(XMLStreamWriter, boolean)`

  Throws:
    `javax.xml.stream.XMLStreamException`

### readAsXMLReader

    public final SAXBufferProcessor readAsXMLReader()

  Deprecated. Use `readAsXMLReader(boolean)`

  Reads the contents of the buffer from a `XMLReader`.

  Returns:
    A an instance of a `SAXBufferProcessor`.

### readAsXMLReader

    public final SAXBufferProcessor readAsXMLReader(boolean produceFragmentEvent)

  Reads the contents of the buffer from a `XMLReader`.

  Parameters:
    `produceFragmentEvent` - True to generate fragment SAX events without start/endDocument. False to generate a full document SAX events.
  Returns:
    A an instance of a `SAXBufferProcessor`.

### writeTo

    public final void writeTo(org.xml.sax.ContentHandler handler,
                              boolean produceFragmentEvent)
                       throws org.xml.sax.SAXException

  Write the contents of the buffer to a `ContentHandler`.

  If the `handler` is also an instance of other SAX-based handlers, such as `LexicalHandler`, than corresponding SAX events will be reported to those handlers.

  Parameters:
    `handler` - The ContentHandler to receive SAX events.
    `produceFragmentEvent` - True to generate fragment SAX events without start/endDocument. False to generate a full document SAX events.
  Throws:
    `org.xml.sax.SAXException` - if a parsing fails, or if `ContentHandler` throws a `SAXException`.

### writeTo

    public final void writeTo(org.xml.sax.ContentHandler handler)
                       throws org.xml.sax.SAXException

  Deprecated. Use `writeTo(ContentHandler,boolean)`

  Throws:
    `org.xml.sax.SAXException`

### writeTo

    public final void writeTo(org.xml.sax.ContentHandler handler,
                              org.xml.sax.ErrorHandler errorHandler,
                              boolean produceFragmentEvent)
                       throws org.xml.sax.SAXException

  Write the contents of the buffer to a `ContentHandler` with errors report to a `ErrorHandler`.

  If the `handler` is also an instance of other SAX-based handlers, such as `LexicalHandler`, than corresponding SAX events will be reported to those handlers.

  Parameters:
    `handler` - The ContentHandler to receive SAX events.
    `errorHandler` - The ErrorHandler to receive error events.
  Throws:
    `org.xml.sax.SAXException` - if a parsing fails and `ErrorHandler` throws a `SAXException`, or if `ContentHandler` throws a `SAXException`.

### writeTo

    public final void writeTo(org.xml.sax.ContentHandler handler,
                              org.xml.sax.ErrorHandler errorHandler)
                       throws org.xml.sax.SAXException

  Throws:
    `org.xml.sax.SAXException`

### writeTo

    public final org.w3c.dom.Node writeTo(org.w3c.dom.Node n)
                                   throws XMLStreamBufferException

  Writes out the contents of this buffer as DOM node and append that to the given node. Faster implementation would be desirable.

  Returns:
    The newly added child node.
  Throws:
    `XMLStreamBufferException`

### createNewBufferFromXMLStreamReader

    public static XMLStreamBuffer createNewBufferFromXMLStreamReader(javax.xml.stream.XMLStreamReader reader)
                                                              throws javax.xml.stream.XMLStreamException

  Create a new buffer from a XMLStreamReader.

  Parameters:
    `reader` - A XMLStreamReader to read from to create.
  Returns:
    XMLStreamBuffer the created buffer
  Throws:
    `javax.xml.stream.XMLStreamException`
  See Also:
    `MutableXMLStreamBuffer.createFromXMLStreamReader(XMLStreamReader)`

### createNewBufferFromXMLReader

    public static XMLStreamBuffer createNewBufferFromXMLReader(org.xml.sax.XMLReader reader,
                                                               java.io.InputStream in)
                                                        throws org.xml.sax.SAXException,
                                                               java.io.IOException

  Create a new buffer from a `XMLReader` and `InputStream`.

  Parameters:
    `reader` - The `XMLReader` to use for parsing.
    `in` - The `InputStream` to be parsed.
  Returns:
    XMLStreamBuffer the created buffer
  Throws:
    `org.xml.sax.SAXException`
    `java.io.IOException`
  See Also:
    `MutableXMLStreamBuffer.createFromXMLReader(XMLReader, InputStream)`

### createNewBufferFromXMLReader

    public static XMLStreamBuffer createNewBufferFromXMLReader(org.xml.sax.XMLReader reader,
                                                               java.io.InputStream in,
                                                               java.lang.String systemId)
                                                        throws org.xml.sax.SAXException,
                                                               java.io.IOException

  Create a new buffer from a `XMLReader` and `InputStream`.

  Parameters:
    `reader` - The `XMLReader` to use for parsing.
    `in` - The `InputStream` to be parsed.
    `systemId` - The system ID of the input stream.
  Returns:
    XMLStreamBuffer the created buffer
  Throws:
    `org.xml.sax.SAXException`
    `java.io.IOException`
  See Also:
    `MutableXMLStreamBuffer.createFromXMLReader(XMLReader, InputStream, String)`

### getStructure

    protected final com.sun.xml.stream.buffer.FragmentedArray<byte[]> getStructure()

### getStructurePtr

    protected final int getStructurePtr()

### getStructureStrings

    protected final com.sun.xml.stream.buffer.FragmentedArray<java.lang.String[]> getStructureStrings()

### getStructureStringsPtr

    protected final int getStructureStringsPtr()

### getContentCharactersBuffer

    protected final com.sun.xml.stream.buffer.FragmentedArray<char[]> getContentCharactersBuffer()

### getContentCharactersBufferPtr

    protected final int getContentCharactersBufferPtr()

### getContentObjects

    protected final com.sun.xml.stream.buffer.FragmentedArray<java.lang.Object[]> getContentObjects()

### getContentObjectsPtr

    protected final int getContentObjectsPtr()

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD