SAXOutputter (JDOM v1.1.1)
Date: 2016-03-09

org.jdom.output

## Class SAXOutputter

- java.lang.Object
- - org.jdom.output.SAXOutputter

-     public class SAXOutputter
      extends java.lang.Object

  Outputs a JDOM document as a stream of SAX2 events.

  Most ContentHandler callbacks are supported. Both `ignorableWhitespace()` and `skippedEntity()` have not been implemented. The ``JDOMLocator`` class returned by ``getLocator()`` exposes the current node being operated upon.

  At this time, it is not possible to access notations and unparsed entity references in a DTD from JDOM. Therefore, `DTDHandler` callbacks have not been implemented yet.

  The `ErrorHandler` callbacks have not been implemented, since these are supposed to be invoked when the document is parsed and at this point the document exists in memory and is known to have no errors.

  Version:
    $Revision: 1.40 $, $Date: 2007/11/10 05:29:01 $
  Author:
    Brett McLaughlin, Jason Hunter, Fred Trimble, Bradley S. Huffman

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SAXOutputter()` This will create a `SAXOutputter` without any registered handler.
    `SAXOutputter(org.xml.sax.ContentHandler contentHandler)` This will create a `SAXOutputter` with the specified `ContentHandler`.
    `SAXOutputter(org.xml.sax.ContentHandler contentHandler, org.xml.sax.ErrorHandler errorHandler, org.xml.sax.DTDHandler dtdHandler, org.xml.sax.EntityResolver entityResolver)` This will create a `SAXOutputter` with the specified SAX2 handlers.
    `SAXOutputter(org.xml.sax.ContentHandler contentHandler, org.xml.sax.ErrorHandler errorHandler, org.xml.sax.DTDHandler dtdHandler, org.xml.sax.EntityResolver entityResolver, org.xml.sax.ext.LexicalHandler lexicalHandler)` This will create a `SAXOutputter` with the specified SAX2 handlers.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected org.xml.sax.XMLReader` | `createParser()` Creates a SAX XMLReader.
    `org.xml.sax.ContentHandler` | `getContentHandler()` Returns the registered `ContentHandler`.
    `org.xml.sax.ext.DeclHandler` | `getDeclHandler()` Return the registered `DeclHandler`.
    `org.xml.sax.DTDHandler` | `getDTDHandler()` Return the registered `DTDHandler`.
    `org.xml.sax.EntityResolver` | `getEntityResolver()` Return the registered `EntityResolver`.
    `org.xml.sax.ErrorHandler` | `getErrorHandler()` Return the registered `ErrorHandler`.
    `boolean` | `getFeature(java.lang.String name)` This will look up the value of a SAX feature.
    `org.xml.sax.ext.LexicalHandler` | `getLexicalHandler()` Return the registered `LexicalHandler`.
    `JDOMLocator` | `getLocator()` Returns a JDOMLocator object referencing the node currently being processed by this outputter.
    `java.lang.Object` | `getProperty(java.lang.String name)` This will look up the value of a SAX property.
    `boolean` | `getReportDTDEvents()` Returns whether DTD events will be reported.
    `boolean` | `getReportNamespaceDeclarations()` Returns whether attribute namespace declarations shall be reported as "xmlns" attributes.
    `void` | `output(Document document)` This will output the `JDOM Document`, firing off the SAX events that have been registered.
    `void` | `output(Element node)` This will output a single JDOM element as a document, firing off the SAX events that have been registered.
    `void` | `output(java.util.List nodes)` This will output a list of JDOM nodes as a document, firing off the SAX events that have been registered.
    `void` | `outputFragment(Content node)` This will output a single JDOM nodes as a fragment of an XML document, firing off the SAX events that have been registered.
    `void` | `outputFragment(java.util.List nodes)` This will output a list of JDOM nodes as a fragment of an XML document, firing off the SAX events that have been registered.
    `void` | `setContentHandler(org.xml.sax.ContentHandler contentHandler)` This will set the `ContentHandler`.
    `void` | `setDeclHandler(org.xml.sax.ext.DeclHandler declHandler)` This will set the `DeclHandler`.
    `void` | `setDTDHandler(org.xml.sax.DTDHandler dtdHandler)` This will set the `DTDHandler`.
    `void` | `setEntityResolver(org.xml.sax.EntityResolver entityResolver)` This will set the `EntityResolver`.
    `void` | `setErrorHandler(org.xml.sax.ErrorHandler errorHandler)` This will set the `ErrorHandler`.
    `void` | `setFeature(java.lang.String name, boolean value)` This will set the state of a SAX feature.
    `void` | `setLexicalHandler(org.xml.sax.ext.LexicalHandler lexicalHandler)` This will set the `LexicalHandler`.
    `void` | `setProperty(java.lang.String name, java.lang.Object value)` This will set the value of a SAX property.
    `void` | `setReportDTDEvents(boolean reportDtdEvents)` This will define whether to report DTD events to SAX DeclHandlers and LexicalHandlers if these handlers are registered and the document to output includes a DocType declaration.
    `void` | `setReportNamespaceDeclarations(boolean declareNamespaces)` This will define whether attribute namespace declarations shall be reported as "xmlns" attributes.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### SAXOutputter

          public SAXOutputter()

      This will create a `SAXOutputter` without any registered handler. The application is then responsible for registering them using the `setXxxHandler()` methods.

    - #### SAXOutputter

          public SAXOutputter(org.xml.sax.ContentHandler contentHandler)

      This will create a `SAXOutputter` with the specified `ContentHandler`.
      Parameters:
        `contentHandler` - contains `ContentHandler` callback methods

    - #### SAXOutputter

          public SAXOutputter(org.xml.sax.ContentHandler contentHandler,
                      org.xml.sax.ErrorHandler errorHandler,
                      org.xml.sax.DTDHandler dtdHandler,
                      org.xml.sax.EntityResolver entityResolver)

      This will create a `SAXOutputter` with the specified SAX2 handlers. At this time, only `ContentHandler` and `EntityResolver` are supported.
      Parameters:
        `contentHandler` - contains `ContentHandler` callback methods
        `errorHandler` - contains `ErrorHandler` callback methods
        `dtdHandler` - contains `DTDHandler` callback methods
        `entityResolver` - contains `EntityResolver` callback methods

    - #### SAXOutputter

          public SAXOutputter(org.xml.sax.ContentHandler contentHandler,
                      org.xml.sax.ErrorHandler errorHandler,
                      org.xml.sax.DTDHandler dtdHandler,
                      org.xml.sax.EntityResolver entityResolver,
                      org.xml.sax.ext.LexicalHandler lexicalHandler)

      This will create a `SAXOutputter` with the specified SAX2 handlers. At this time, only `ContentHandler` and `EntityResolver` are supported.
      Parameters:
        `contentHandler` - contains `ContentHandler` callback methods
        `errorHandler` - contains `ErrorHandler` callback methods
        `dtdHandler` - contains `DTDHandler` callback methods
        `entityResolver` - contains `EntityResolver` callback methods
        `lexicalHandler` - contains `LexicalHandler` callbacks.

  - ### Method Detail

    - #### setContentHandler

          public void setContentHandler(org.xml.sax.ContentHandler contentHandler)

      This will set the `ContentHandler`.
      Parameters:
        `contentHandler` - contains `ContentHandler` callback methods.

    - #### getContentHandler

          public org.xml.sax.ContentHandler getContentHandler()

      Returns the registered `ContentHandler`.
      Returns:
        the current `ContentHandler` or `null` if none was registered.

    - #### setErrorHandler

          public void setErrorHandler(org.xml.sax.ErrorHandler errorHandler)

      This will set the `ErrorHandler`.
      Parameters:
        `errorHandler` - contains `ErrorHandler` callback methods.

    - #### getErrorHandler

          public org.xml.sax.ErrorHandler getErrorHandler()

      Return the registered `ErrorHandler`.
      Returns:
        the current `ErrorHandler` or `null` if none was registered.

    - #### setDTDHandler

          public void setDTDHandler(org.xml.sax.DTDHandler dtdHandler)

      This will set the `DTDHandler`.
      Parameters:
        `dtdHandler` - contains `DTDHandler` callback methods.

    - #### getDTDHandler

          public org.xml.sax.DTDHandler getDTDHandler()

      Return the registered `DTDHandler`.
      Returns:
        the current `DTDHandler` or `null` if none was registered.

    - #### setEntityResolver

          public void setEntityResolver(org.xml.sax.EntityResolver entityResolver)

      This will set the `EntityResolver`.
      Parameters:
        `entityResolver` - contains EntityResolver callback methods.

    - #### getEntityResolver

          public org.xml.sax.EntityResolver getEntityResolver()

      Return the registered `EntityResolver`.
      Returns:
        the current `EntityResolver` or `null` if none was registered.

    - #### setLexicalHandler

          public void setLexicalHandler(org.xml.sax.ext.LexicalHandler lexicalHandler)

      This will set the `LexicalHandler`.
      Parameters:
        `lexicalHandler` - contains lexical callback methods.

    - #### getLexicalHandler

          public org.xml.sax.ext.LexicalHandler getLexicalHandler()

      Return the registered `LexicalHandler`.
      Returns:
        the current `LexicalHandler` or `null` if none was registered.

    - #### setDeclHandler

          public void setDeclHandler(org.xml.sax.ext.DeclHandler declHandler)

      This will set the `DeclHandler`.
      Parameters:
        `declHandler` - contains declaration callback methods.

    - #### getDeclHandler

          public org.xml.sax.ext.DeclHandler getDeclHandler()

      Return the registered `DeclHandler`.
      Returns:
        the current `DeclHandler` or `null` if none was registered.

    - #### getReportNamespaceDeclarations

          public boolean getReportNamespaceDeclarations()

      Returns whether attribute namespace declarations shall be reported as "xmlns" attributes.
      Returns:
        whether attribute namespace declarations shall be reported as "xmlns" attributes.

    - #### setReportNamespaceDeclarations

          public void setReportNamespaceDeclarations(boolean declareNamespaces)

      This will define whether attribute namespace declarations shall be reported as "xmlns" attributes. This flag defaults to `false` and behaves as the "namespace-prefixes" SAX core feature.
      Parameters:
        `declareNamespaces` - whether attribute namespace declarations shall be reported as "xmlns" attributes.

    - #### getReportDTDEvents

          public boolean getReportDTDEvents()

      Returns whether DTD events will be reported.
      Returns:
        whether DTD events will be reported

    - #### setReportDTDEvents

          public void setReportDTDEvents(boolean reportDtdEvents)

      This will define whether to report DTD events to SAX DeclHandlers and LexicalHandlers if these handlers are registered and the document to output includes a DocType declaration.
      Parameters:
        `reportDtdEvents` - whether to notify DTD events.

    - #### setFeature

          public void setFeature(java.lang.String name,
                        boolean value)
                          throws org.xml.sax.SAXNotRecognizedException,
                                 org.xml.sax.SAXNotSupportedException

      This will set the state of a SAX feature.

      All XMLReaders are required to support setting to true and to false.

      SAXOutputter currently supports the following SAX core features:

      `http://xml.org/sax/features/namespaces`
        description: `true` indicates namespace URIs and unprefixed local names for element and attribute names will be available
        access: read/write, but always `true`!
      `http://xml.org/sax/features/namespace-prefixes`
        description: `true` indicates XML 1.0 names (with prefixes) and attributes (including xmlns* attributes) will be available
        access: read/write
      `http://xml.org/sax/features/validation`
        description: controls whether SAXOutputter is reporting DTD-related events; if `true`, the DocType internal subset will be parsed to fire DTD events
        access: read/write, defaults to `true`
      Parameters:
        `name` - `String` the feature name, which is a fully-qualified URI.
        `value` - `boolean` the requested state of the feature (true or false).
      Throws:
        `org.xml.sax.SAXNotRecognizedException` - when SAXOutputter does not recognize the feature name.
        `org.xml.sax.SAXNotSupportedException` - when SAXOutputter recognizes the feature name but cannot set the requested value.

    - #### getFeature

          public boolean getFeature(java.lang.String name)
                             throws org.xml.sax.SAXNotRecognizedException,
                                    org.xml.sax.SAXNotSupportedException

      This will look up the value of a SAX feature.
      Parameters:
        `name` - `String` the feature name, which is a fully-qualified URI.
      Returns:
        `boolean` the current state of the feature (true or false).
      Throws:
        `org.xml.sax.SAXNotRecognizedException` - when SAXOutputter does not recognize the feature name.
        `org.xml.sax.SAXNotSupportedException` - when SAXOutputter recognizes the feature name but determine its value at this time.

    - #### setProperty

          public void setProperty(java.lang.String name,
                         java.lang.Object value)
                           throws org.xml.sax.SAXNotRecognizedException,
                                  org.xml.sax.SAXNotSupportedException

      This will set the value of a SAX property. This method is also the standard mechanism for setting extended handlers.

      SAXOutputter currently supports the following SAX properties:

      `http://xml.org/sax/properties/lexical-handler`
        data type: `org.xml.sax.ext.LexicalHandler`
        description: An optional extension handler for lexical events like comments.
        access: read/write
      `http://xml.org/sax/properties/declaration-handler`
        data type: `org.xml.sax.ext.DeclHandler`
        description: An optional extension handler for DTD-related events other than notations and unparsed entities.
        access: read/write
      Parameters:
        `name` - `String` the property name, which is a fully-qualified URI.
        `value` - `Object` the requested value for the property.
      Throws:
        `org.xml.sax.SAXNotRecognizedException` - when SAXOutputter does not recognize the property name.
        `org.xml.sax.SAXNotSupportedException` - when SAXOutputter recognizes the property name but cannot set the requested value.

    - #### getProperty

          public java.lang.Object getProperty(java.lang.String name)
                                       throws org.xml.sax.SAXNotRecognizedException,
                                              org.xml.sax.SAXNotSupportedException

      This will look up the value of a SAX property.
      Parameters:
        `name` - `String` the property name, which is a fully-qualified URI.
      Returns:
        `Object` the current value of the property.
      Throws:
        `org.xml.sax.SAXNotRecognizedException` - when SAXOutputter does not recognize the property name.
        `org.xml.sax.SAXNotSupportedException` - when SAXOutputter recognizes the property name but cannot determine its value at this time.

    - #### output

          public void output(Document document)
                      throws JDOMException

      This will output the `JDOM Document`, firing off the SAX events that have been registered.
      Parameters:
        `document` - `JDOM Document` to output.
      Throws:
        `JDOMException` - if any error occurred.

    - #### output

          public void output(java.util.List nodes)
                      throws JDOMException

      This will output a list of JDOM nodes as a document, firing off the SAX events that have been registered.

      Warning: This method may output ill-formed XML documents if the list contains top-level objects that are not legal at the document level (e.g. Text or CDATA nodes, multiple Element nodes, etc.). Thus, it should only be used to output document portions towards ContentHandlers capable of accepting such ill-formed documents (such as XSLT processors).

      Parameters:
        `nodes` - `List` of JDOM nodes to output.
      Throws:
        `JDOMException` - if any error occurred.
      See Also:
        `output(org.jdom.Document)`

    - #### output

          public void output(Element node)
                      throws JDOMException

      This will output a single JDOM element as a document, firing off the SAX events that have been registered.
      Parameters:
        `node` - the `Element` node to output.
      Throws:
        `JDOMException` - if any error occurred.

    - #### outputFragment

          public void outputFragment(java.util.List nodes)
                              throws JDOMException

      This will output a list of JDOM nodes as a fragment of an XML document, firing off the SAX events that have been registered.

      Warning: This method does not call the `ContentHandler.setDocumentLocator(org.xml.sax.Locator)`, `ContentHandler.startDocument()` and `ContentHandler.endDocument()` callbacks on the `ContentHandler`. The user shall invoke these methods directly prior/after outputting the document fragments.

      Parameters:
        `nodes` - `List` of JDOM nodes to output.
      Throws:
        `JDOMException` - if any error occurred.
      See Also:
        `outputFragment(org.jdom.Content)`

    - #### outputFragment

          public void outputFragment(Content node)
                              throws JDOMException

      This will output a single JDOM nodes as a fragment of an XML document, firing off the SAX events that have been registered.

      Warning: This method does not call the `ContentHandler.setDocumentLocator(org.xml.sax.Locator)`, `ContentHandler.startDocument()` and `ContentHandler.endDocument()` callbacks on the `ContentHandler`. The user shall invoke these methods directly prior/after outputting the document fragments.

      Parameters:
        `node` - the `Content` node to output.
      Throws:
        `JDOMException` - if any error occurred.
      See Also:
        `outputFragment(java.util.List)`

    - #### createParser

          protected org.xml.sax.XMLReader createParser()
                                                throws java.lang.Exception

      Creates a SAX XMLReader.

      Returns:
        `XMLReader` a SAX2 parser.
      Throws:
        `java.lang.Exception` - if no parser can be created.

    - #### getLocator

          public JDOMLocator getLocator()

      Returns a JDOMLocator object referencing the node currently being processed by this outputter. The returned object is a snapshot of the location information and can thus safely be memorized for later use.

      This method allows direct access to the location information maintained by SAXOutputter without requiring to implement `XMLFilter`. (In SAX, locators are only available though the `ContentHandler` interface).

      Note that location information is only available while SAXOutputter is outputting nodes. Hence this method should only be used by objects taking part in the output processing such as `ErrorHandler`s.

      Returns:
        a JDOMLocator object referencing the node currently being processed or `null` if no output operation is being performed.

Copyright ? 2007 Jason Hunter, Brett McLaughlin. All Rights Reserved.