org.apache.xalan.serialize
Class SerializerToXML

java.lang.Object
  |
  +--org.apache.xalan.serialize.SerializerToXML

Direct Known Subclasses:

SerializerToHTML, SerializerToText

public class SerializerToXML

extends java.lang.Object

implements ContentHandler, LexicalHandler, Serializer, DOMSerializer

SerializerToXML formats SAX-style events into XML.

Field Summary

int	m_indentAmount Amount to indent.
boolean	m_shouldNotWriteXMLHeader Tells if we should write the XML declaration.
boolean	m_spaceBeforeClose Add space before '/>' for XHTML.
java.lang.String	m_version Tells the XML version, for writing out to the XML decl.

Constructor Summary

SerializerToXML()
Default constructor.

Method Summary

ContentHandler	asContentHandler() Return a ContentHandler interface into this serializer.
DOMSerializer	asDOMSerializer() Return a DOMSerializer interface into this serializer.
void	cdata(char[] ch, int start, int length) Receive notification of cdata.
void	characters(char[] chars, int start, int length) Receive notification of character data.
void	charactersRaw(char[] ch, int start, int length) If available, when the disable-output-escaping attribute is used, output raw text without escaping.
void	comment(char[] ch, int start, int length) Report an XML comment anywhere in the document.
void	CopyFrom(SerializerToXML xmlListener) Copy properties from another SerializerToXML.
void	endCDATA() Report the end of a CDATA section.
void	endDocument() Receive notification of the end of a document.
void	endDTD() Report the end of DTD declarations.
void	endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String name) Receive notification of the end of an element.
void	endEntity(java.lang.String name) Report the end of an entity.
void	endNonEscaping() Ends an un-escaping section.
void	endPrefixMapping(java.lang.String prefix) End the scope of a prefix-URI Namespace mapping.
void	endPreserving() Ends a whitespace preserving section.
void	entityReference(java.lang.String name) Receive notivication of a entityReference.
void	flush() Flush all accumulated characters or bytes to the result stream.
void	flushWriter() Flush the formatter's result stream.
java.util.Properties	getOutputFormat() Returns the output format for this serializer.
java.io.OutputStream	getOutputStream() Get the output stream where the events will be serialized to.
java.io.Writer	getWriter() Get the character stream where the events will be serialized to.
void	ignorableWhitespace(char[] ch, int start, int length) Receive notification of ignorable whitespace in element content.
void	indent(int n) Prints a newline character and n spaces.
void	init(java.io.OutputStream output, java.util.Properties format) Initialize the serializer with the specified output stream and output format.
void	init(java.io.Writer writer, java.util.Properties format) Initialize the serializer with the specified writer and output format.
void	printSpace(int n) Prints n spaces.
void	processingInstruction(java.lang.String target, java.lang.String data) Receive notification of a processing instruction.
boolean	reset() Resets the serializer.
void	serialize(Node node) Serializes the DOM node.
void	setDocumentLocator(Locator locator) Receive an object for locating the origin of SAX document events.
void	setOutputFormat(java.util.Properties format) Specifies an output format for this serializer.
void	setOutputStream(java.io.OutputStream output) Specifies an output stream to which the document should be serialized.
void	setWriter(java.io.Writer writer) Specifies a writer to which the document should be serialized.
void	skippedEntity(java.lang.String name) Receive notification of a skipped entity.
void	startCDATA() Report the start of a CDATA section.
void	startDocument() Receive notification of the beginning of a document.
void	startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId) Report the start of DTD declarations, if any.
void	startElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String name, Attributes atts) Receive notification of the beginning of an element.
void	startEntity(java.lang.String name) Report the beginning of an entity.
void	startNonEscaping() Starts an un-escaping section.
void	startPrefixMapping(java.lang.String prefix, java.lang.String uri) Begin the scope of a prefix-URI Namespace mapping.
void	startPreserving() Starts a whitespace preserving section.
void	writeAttrString(java.lang.String string, java.lang.String encoding) Returns the specified string after substituting specials, and UTF-16 surrogates for chracter references &#xnn.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_shouldNotWriteXMLHeader

public boolean m_shouldNotWriteXMLHeader

Tells if we should write the XML declaration.

m_version

public java.lang.String m_version

Tells the XML version, for writing out to the XML decl.

m_indentAmount

public int m_indentAmount

Amount to indent.

m_spaceBeforeClose

public boolean m_spaceBeforeClose

Add space before '/>' for XHTML.

Constructor Detail

SerializerToXML

public SerializerToXML()

Default constructor.

Method Detail

CopyFrom

public void CopyFrom(SerializerToXML xmlListener)

Copy properties from another SerializerToXML.

Parameters:

xmlListener - non-null reference to a SerializerToXML object.

init

public void init(java.io.Writer writer,
                 java.util.Properties format)

Initialize the serializer with the specified writer and output format. Must be called before calling any of the serialize methods.

Parameters:

writer - The writer to use

format - The output format

init

public void init(java.io.OutputStream output,
                 java.util.Properties format)
          throws java.io.UnsupportedEncodingException

Initialize the serializer with the specified output stream and output format. Must be called before calling any of the serialize methods.

Parameters:

output - The output stream to use

format - The output format

Throws:

java.io.UnsupportedEncodingException - The encoding specified in the output format is not supported

setDocumentLocator

public void setDocumentLocator(Locator locator)

Receive an object for locating the origin of SAX document events.

Specified by:

setDocumentLocator in interface ContentHandler

Parameters:

locator - An object that can return the location of any SAX document event.

See Also:

Locator

startDocument

public void startDocument()
                   throws SAXException

Receive notification of the beginning of a document.

Specified by:

startDocument in interface ContentHandler

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

SAXException -

endDocument

public void endDocument()
                 throws SAXException

Receive notification of the end of a document.

Specified by:

endDocument in interface ContentHandler

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

SAXException -

startDTD

public void startDTD(java.lang.String name,
                     java.lang.String publicId,
                     java.lang.String systemId)
              throws SAXException

Report the start of DTD declarations, if any. Any declarations are assumed to be in the internal subset unless otherwise indicated.

Specified by:

startDTD in interface LexicalHandler

Parameters:

name - The document type name.

publicId - The declared public identifier for the external DTD subset, or null if none was declared.

systemId - The declared system identifier for the external DTD subset, or null if none was declared.

Throws:

SAXException - The application may raise an exception.

See Also:

endDTD(), startEntity(java.lang.String)

endDTD

public void endDTD()
            throws SAXException

Report the end of DTD declarations.

Specified by:

endDTD in interface LexicalHandler

Throws:

SAXException - The application may raise an exception.

See Also:

startDTD(java.lang.String, java.lang.String, java.lang.String)

startPrefixMapping

public void startPrefixMapping(java.lang.String prefix,
                               java.lang.String uri)
                        throws SAXException

Begin the scope of a prefix-URI Namespace mapping.

Specified by:

startPrefixMapping in interface ContentHandler

Parameters:

prefix - The Namespace prefix being declared.

uri - The Namespace URI the prefix is mapped to.

Throws:

SAXException - The client may throw an exception during processing.

See Also:

ContentHandler.startPrefixMapping(java.lang.String, java.lang.String)

endPrefixMapping

public void endPrefixMapping(java.lang.String prefix)
                      throws SAXException

End the scope of a prefix-URI Namespace mapping.

Specified by:

endPrefixMapping in interface ContentHandler

Parameters:

prefix - The prefix that was being mapping.

Throws:

SAXException - The client may throw an exception during processing.

See Also:

ContentHandler.endPrefixMapping(java.lang.String)

startElement

public void startElement(java.lang.String namespaceURI,
                         java.lang.String localName,
                         java.lang.String name,
                         Attributes atts)
                  throws SAXException

Receive notification of the beginning of an element.

Specified by:

startElement in interface ContentHandler

Parameters:

namespaceURI - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.

localName - The local name (without prefix), or the empty string if Namespace processing is not being performed.

name - The element type name.

atts - The attributes attached to the element, if any.

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

SAXException -

See Also:

ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes), ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String), AttributeList

endElement

public void endElement(java.lang.String namespaceURI,
                       java.lang.String localName,
                       java.lang.String name)
                throws SAXException

Receive notification of the end of an element.

Specified by:

endElement in interface ContentHandler

Parameters:

namespaceURI - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.

localName - The local name (without prefix), or the empty string if Namespace processing is not being performed.

name - The element type name

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

SAXException -

startNonEscaping

public void startNonEscaping()
                      throws SAXException

Starts an un-escaping section. All characters printed within an un-escaping section are printed as is, without escaping special characters into entity references. Only XML and HTML serializers need to support this method.

The contents of the un-escaping section will be delivered through the regular characters event.

Throws:

SAXException -

endNonEscaping

public void endNonEscaping()
                    throws SAXException

Ends an un-escaping section.

Throws:

SAXException -

See Also:

startNonEscaping()

startPreserving

public void startPreserving()
                     throws SAXException

Starts a whitespace preserving section. All characters printed within a preserving section are printed without indentation and without consolidating multiple spaces. This is equivalent to the xml:space="preserve" attribute. Only XML and HTML serializers need to support this method.

The contents of the whitespace preserving section will be delivered through the regular characters event.

Throws:

SAXException -

endPreserving

public void endPreserving()
                   throws SAXException

Ends a whitespace preserving section.

Throws:

SAXException -

See Also:

startPreserving()

processingInstruction

public void processingInstruction(java.lang.String target,
                                  java.lang.String data)
                           throws SAXException

Receive notification of a processing instruction.

Specified by:

processingInstruction in interface ContentHandler

Parameters:

target - The processing instruction target.

data - The processing instruction data, or null if none was supplied.

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

SAXException -

comment

public void comment(char[] ch,
                    int start,
                    int length)
             throws SAXException

Report an XML comment anywhere in the document. This callback will be used for comments inside or outside the document element, including comments in the external DTD subset (if read).

Specified by:

comment in interface LexicalHandler

Parameters:

ch - An array holding the characters in the comment.

start - The starting position in the array.

length - The number of characters to use from the array.

Throws:

SAXException - The application may raise an exception.

startCDATA

public void startCDATA()
                throws SAXException

Report the start of a CDATA section.

Specified by:

startCDATA in interface LexicalHandler

Throws:

SAXException - The application may raise an exception.

See Also:

endCDATA()

endCDATA

public void endCDATA()
              throws SAXException

Report the end of a CDATA section.

Specified by:

endCDATA in interface LexicalHandler

Throws:

SAXException - The application may raise an exception.

See Also:

startCDATA()

cdata

public void cdata(char[] ch,
                  int start,
                  int length)
           throws SAXException

Receive notification of cdata.

The Parser will call this method to report each chunk of character data. SAX parsers may return all contiguous character data in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity, so that the Locator provides useful information.

The application must not attempt to read from the array outside of the specified range.

Note that some parsers will report whitespace using the ignorableWhitespace() method rather than this one (validating parsers must do so).

Parameters:

ch - The characters from the XML document.

start - The start position in the array.

length - The number of characters to read from the array.

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

SAXException -

See Also:

ignorableWhitespace(char[], int, int), Locator

flushWriter

public final void flushWriter()
                       throws SAXException

Flush the formatter's result stream.

Throws:

SAXException -

flush

public final void flush()
                 throws SAXException

Flush all accumulated characters or bytes to the result stream.

Throws:

SAXException -

characters

public void characters(char[] chars,
                       int start,
                       int length)
                throws SAXException

Receive notification of character data.

The Parser will call this method to report each chunk of character data. SAX parsers may return all contiguous character data in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity, so that the Locator provides useful information.

The application must not attempt to read from the array outside of the specified range.

Note that some parsers will report whitespace using the ignorableWhitespace() method rather than this one (validating parsers must do so).

Specified by:

characters in interface ContentHandler

Parameters:

chars - The characters from the XML document.

start - The start position in the array.

length - The number of characters to read from the array.

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

SAXException -

See Also:

ignorableWhitespace(char[], int, int), Locator

charactersRaw

public void charactersRaw(char[] ch,
                          int start,
                          int length)
                   throws SAXException

If available, when the disable-output-escaping attribute is used, output raw text without escaping.

Parameters:

ch - The characters from the XML document.

start - The start position in the array.

length - The number of characters to read from the array.

Throws:

SAXException -

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException

Receive notification of ignorable whitespace in element content. Not sure how to get this invoked quite yet.

Specified by:

ignorableWhitespace in interface ContentHandler

Parameters:

ch - The characters from the XML document.

start - The start position in the array.

length - The number of characters to read from the array.

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

SAXException -

See Also:

characters(char[], int, int)

skippedEntity

public void skippedEntity(java.lang.String name)
                   throws SAXException

Receive notification of a skipped entity.

Specified by:

skippedEntity in interface ContentHandler

Parameters:

name - The name of the skipped entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be the string "[dtd]".

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.skippedEntity(java.lang.String)

startEntity

public void startEntity(java.lang.String name)
                 throws SAXException

Report the beginning of an entity. The start and end of the document entity are not reported. The start and end of the external DTD subset are reported using the pseudo-name "[dtd]". All other events must be properly nested within start/end entity events.

Specified by:

startEntity in interface LexicalHandler

Parameters:

name - The name of the entity. If it is a parameter entity, the name will begin with '%'.

Throws:

SAXException - The application may raise an exception.

See Also:

endEntity(java.lang.String), DeclHandler.internalEntityDecl(java.lang.String, java.lang.String), DeclHandler.externalEntityDecl(java.lang.String, java.lang.String, java.lang.String)

endEntity

public void endEntity(java.lang.String name)
               throws SAXException

Report the end of an entity.

Specified by:

endEntity in interface LexicalHandler

Parameters:

name - The name of the entity that is ending.

Throws:

SAXException - The application may raise an exception.

See Also:

startEntity(java.lang.String)

entityReference

public void entityReference(java.lang.String name)
                     throws SAXException

Receive notivication of a entityReference.

Parameters:

name - The name of the entity.

Throws:

SAXException -

writeAttrString

public void writeAttrString(java.lang.String string,
                            java.lang.String encoding)
                     throws SAXException

Returns the specified string after substituting specials, and UTF-16 surrogates for chracter references &#xnn.

Parameters:

string - String to convert to XML format.

encoding - CURRENTLY NOT IMPLEMENTED.

Throws:

SAXException -

printSpace

public void printSpace(int n)
                throws SAXException

Prints n spaces.

Parameters:

pw - The character output stream to use.

n - Number of spaces to print.

Throws:

SAXException - if an error occurs when writing.

indent

public void indent(int n)
            throws SAXException

Prints a newline character and n spaces.

Parameters:

pw - The character output stream to use.

n - Number of spaces to print.

Throws:

SAXException - if an error occurs during writing.

setOutputStream

public void setOutputStream(java.io.OutputStream output)

Specifies an output stream to which the document should be serialized. This method should not be called while the serializer is in the process of serializing a document.

The encoding specified in the output properties is used, or if no encoding was specified, the default for the selected output method.

Specified by:

setOutputStream in interface Serializer

Parameters:

output - The output stream

getOutputStream

public java.io.OutputStream getOutputStream()

Get the output stream where the events will be serialized to.

Specified by:

getOutputStream in interface Serializer

Returns:

reference to the result stream, or null of only a writer was set.

setWriter

public void setWriter(java.io.Writer writer)

Specifies a writer to which the document should be serialized. This method should not be called while the serializer is in the process of serializing a document.

Specified by:

setWriter in interface Serializer

Parameters:

writer - The output writer stream

getWriter

public java.io.Writer getWriter()

Get the character stream where the events will be serialized to.

Specified by:

getWriter in interface Serializer

Returns:

Reference to the result Writer, or null.

setOutputFormat

public void setOutputFormat(java.util.Properties format)

Specifies an output format for this serializer. It the serializer has already been associated with an output format, it will switch to the new format. This method should not be called while the serializer is in the process of serializing a document.

Specified by:

setOutputFormat in interface Serializer

Parameters:

format - The output format to use

getOutputFormat

public java.util.Properties getOutputFormat()

Returns the output format for this serializer.

Specified by:

getOutputFormat in interface Serializer

Returns:

The output format in use

asContentHandler

public ContentHandler asContentHandler()
                                throws java.io.IOException

Return a ContentHandler interface into this serializer. If the serializer does not support the ContentHandler interface, it should return null.

Specified by:

asContentHandler in interface Serializer

Returns:

A ContentHandler interface into this serializer, or null if the serializer is not SAX 2 capable

Throws:

java.io.IOException - An I/O exception occured

asDOMSerializer

public DOMSerializer asDOMSerializer()
                              throws java.io.IOException

Return a DOMSerializer interface into this serializer. If the serializer does not support the DOMSerializer interface, it should return null.

Specified by:

asDOMSerializer in interface Serializer

Returns:

A DOMSerializer interface into this serializer, or null if the serializer is not DOM capable

Throws:

java.io.IOException - An I/O exception occured

reset

public boolean reset()

Resets the serializer. If this method returns true, the serializer may be used for subsequent serialization of new documents. It is possible to change the output format and output stream prior to serializing, or to use the existing output format and output stream.

Specified by:

reset in interface Serializer

Returns:

True if serializer has been reset and can be reused

serialize

public void serialize(Node node)
               throws java.io.IOException

Serializes the DOM node. Throws an exception only if an I/O exception occured while serializing.

Specified by:

serialize in interface DOMSerializer

Parameters:

elem - The element to serialize

node - Node to serialize.

Throws:

java.io.IOException - An I/O exception occured while serializing