JDOM
2.0.5

org.jdom2.output
Class SAXOutputter

java.lang.Object
  extended by org.jdom2.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.

Author:
Brett McLaughlin, Jason Hunter, Fred Trimble, Bradley S. Huffman

Constructor Summary
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.
SAXOutputter(SAXOutputProcessor processor, Format format, 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
 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.
 Format getFormat()
          Get the current Format being used for output
 org.xml.sax.ext.LexicalHandler getLexicalHandler()
          Return the registered LexicalHandler.
 JDOMLocator getLocator()
          Deprecated. there is no way to get a meaningful document Locator outside of an active output process, and the contents of the locator are meaningless outside of an active output process anyway.
 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.
 SAXOutputProcessor getSAXOutputProcessor()
          Get the current SAXOutputProcessor being used for output.
 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<? extends Content> 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<? extends Content> 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 setFormat(Format format)
          Set the current Format to be used for output.
 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.
 void setSAXOutputProcessor(SAXOutputProcessor processor)
          Set the current SAXOutputProcessor to be used for output.
 
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.

SAXOutputter

public SAXOutputter(SAXOutputProcessor processor,
                    Format format,
                    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:
processor - the SAXOutputProcessor to use for output.
format - the Format to use for output.
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.

getSAXOutputProcessor

public SAXOutputProcessor getSAXOutputProcessor()
Get the current SAXOutputProcessor being used for output.

Returns:
The current SAXOutputProcessor

setSAXOutputProcessor

public void setSAXOutputProcessor(SAXOutputProcessor processor)
Set the current SAXOutputProcessor to be used for output.

Parameters:
processor - the new SAXOutputProcessor

getFormat

public Format getFormat()
Get the current Format being used for output

Returns:
the current Format

setFormat

public void setFormat(Format format)
Set the current Format to be used for output.

Parameters:
format - the new Format

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<? extends Content> 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.jdom2.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<? extends Content> 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.jdom2.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)

getLocator

@Deprecated
public JDOMLocator getLocator()
Deprecated. there is no way to get a meaningful document Locator outside of an active output process, and the contents of the locator are meaningless outside of an active output process anyway.

Returns null.

Returns:
null

JDOM
2.0.5

Copyright 2013 Jason Hunter, Brett McLaughlin. All Rights Reserved.