Top Description Fields Constructors Methods
org.apache.xml.serialize

public Class XMLSerializer

extends BaseMarkupSerializer
Class Inheritance
Known Direct Subclasses
org.apache.xml.serialize.XML11Serializer
Imports
java.io.IOException, .OutputStream, .Writer, java.util.Iterator, .Map, org.apache.xerces.dom.DOMMessageFormatter, org.apache.xerces.util.NamespaceSupport, .SymbolTable, .XMLChar, .XMLSymbols, org.apache.xerces.xni.NamespaceContext, org.w3c.dom.Attr, .DOMError, .Document, .Element, .NamedNodeMap, .Node, org.w3c.dom.traversal.NodeFilter, org.xml.sax.AttributeList, .Attributes, .SAXException, org.xml.sax.helpers.AttributesImpl

Deprecated

This class was deprecated in Xerces 2.9.0. It is recommended that new applications use the DOM Level 3 LSSerializer or JAXP's Transformation API for XML (TrAX) for serializing XML. See the Xerces documentation for more information.

Implements an XML serializer supporting both DOM and SAX pretty serializing. For usage instructions see Serializer.

If an output stream is used, the encoding is taken from the output format (defaults to UTF-8). If a writer is used, make sure the writer uses the same encoding (if applies) as specified in the output format.

The serializer supports both DOM and SAX. SAX serializing is done by firing SAX events and using the serializer as a document handler. DOM serializing is done by calling serialize(Document) or by using DOM Level 3 org.w3c.dom.ls.LSSerializer and serializing with org.w3c.dom.ls.LSSerializer#write, org.w3c.dom.ls.LSSerializer#writeToString.

If an I/O exception occurs while serializing, the serializer will not throw an exception directly, but only throw it at the end of serializing (either DOM or SAX's org.xml.sax.DocumentHandler#endDocument.

For elements that are not specified as whitespace preserving, the serializer will potentially break long text lines at space boundaries, indent lines, and serialize elements on separate lines. Line terminators will be regarded as spaces, and spaces at beginning of line will be stripped.

Authors
Assaf Arkin, Rahul Srivastava, Elena Litani IBM
Version
$Revision: 704573 $ $Date: 2008-10-14 21:41:22 +0530 (Tue, 14 Oct 2008) $
See Also
Serializer

Field Summary

Modifier and TypeField and Description
protected static final boolean
DEBUG

protected NamespaceSupport
fLocalNSBinder

stores all namespace bindings on the current element

protected boolean
fNamespacePrefixes

Controls whether namespace prefixes will be printed out during serialization

protected boolean
fNamespaces

Controls whether namespace fixup should be performed during the serialization.

protected NamespaceSupport
fNSBinder

stores namespaces in scope

private boolean
fPreserveSpace

protected SymbolTable
fSymbolTable

symbol table for serialization

protected static final String
PREFIX

Inherited from org.apache.xml.serialize.BaseMarkupSerializer:
_docTypePublicId_docTypeSystemId_encodingInfo_format_indenting_prefixes_printer_startedfCurrentNodefDOMErrorfDOMErrorHandlerfDOMFilterfeaturesfStrBuffer

Constructor Summary

AccessConstructor and Description
public
XMLSerializer()

Constructs a new serializer.

public
XMLSerializer(OutputFormat format)

Deprecated as a consequence of OutputFormat being deprecated.
Constructs a new serializer.
public
XMLSerializer(Writer
The writer to use
writer, OutputFormat
The output format to use, null for the default
format)

Deprecated as a consequence of OutputFormat being deprecated.
Constructs a new serializer that writes to the specified writer using the specified output format.
public
XMLSerializer(OutputStream
The output stream to use
output, OutputFormat
The output format to use, null for the default
format)

Deprecated as a consequence of OutputFormat being deprecated.
Constructs a new serializer that writes to the specified output stream using the specified output format.

Method Summary

Modifier and TypeMethod and Description
protected void
checkUnboundNamespacePrefixedNode(Node
The node to check for unbound namespace prefices
node)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.checkUnboundNamespacePrefixedNode.

DOM Level 3: Check a node to determine if it contains unbound namespace prefixes.
public void
endElement(String
the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed
namespaceURI, String
the local name (without prefix), or the empty string if Namespace processing is not being performed
localName, String
the qualified XML name (with prefix), or the empty string if qualified names are not available
rawName)

Implements org.xml.sax.ContentHandler.endElement.

Receive notification of the end of an element.
public void
endElement(String
The element type name
tagName)

Implements org.xml.sax.DocumentHandler.endElement.

Receive notification of the end of an element.
public void
endElementIO(String namespaceURI, String localName, String rawName)

private Attributes
extractNamespaces(Attributes attrs)

Retrieve and remove the namespaces declarations from the list of attributes.

protected String
getEntityRef(int
Character value
ch)

Implements abstract org.apache.xml.serialize.BaseMarkupSerializer.getEntityRef.

Returns the suitable entity reference for this character value, or null if no such entity exists.
private void
printAttribute(String name, String value, boolean isSpecified, Attr attr)

Prints attribute.

protected void
printEscaped(String
The string to escape
source)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.printEscaped.

Escapes a string so it may be printed as text content or attribute value.
private void
printNamespaceAttr(String prefix, String uri)

Serializes a namespace attribute with the given prefix and value for URI.

protected void
printText(String text, boolean preserveSpace, boolean unescaped)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.printText.

protected void
printText(char[]
The text to print
chars, int
The start offset
start, int
The number of characters
length, boolean
Space preserving flag
preserveSpace, boolean
Print unescaped
unescaped)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.printText.

Called to print additional text with whitespace handling.
protected void
printXMLChar(int ch)

print text data

public boolean
reset()

Overrides org.apache.xml.serialize.BaseMarkupSerializer.reset.

protected void
serializeElement(Element
The element to serialize
elem)

Implements abstract org.apache.xml.serialize.BaseMarkupSerializer.serializeElement.

Called to serialize a DOM element.
public void
setNamespaces(boolean namespaces)

This methods turns on namespace fixup algorithm during DOM serialization.

public void
setOutputFormat(OutputFormat
The output format to use
format)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.setOutputFormat.

Implements org.apache.xml.serialize.Serializer.setOutputFormat.

Deprecated as a consequence of OutputFormat being deprecated.
Specifies an output format for this serializer.
protected void
startDocument(String rootTagName)

Called to serialize the document's DOCTYPE by the root element.

public void
startElement(String
the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed
namespaceURI, String
the local name (without prefix), or the empty string if Namespace processing is not being performed
localName, String
the qualified name (with prefix), or the empty string if qualified names are not available
rawName, Attributes
the attributes attached to the element. If there are no attributes, it shall be an empty Attributes object. The value of this object after startElement returns is undefined
attrs)

Implements org.xml.sax.ContentHandler.startElement.

Receive notification of the beginning of an element.
public void
startElement(String
The element type name.
tagName, AttributeList
The attributes attached to the element, if any.
attrs)

Implements org.xml.sax.DocumentHandler.startElement.

Deprecated as a consequence of AttributeList being deprecated.
Receive notification of the beginning of an element.
Inherited from org.apache.xml.serialize.BaseMarkupSerializer:
asContentHandlerasDocumentHandlerasDOMSerializerattributeDeclcharacterscharacterscleanupclearDocumentStatecommentcommentcontentelementDeclendCDATAendDocumentendDTDendEntityendNonEscapingendPrefixMappingendPreservingenterElementStateexternalEntityDeclfatalErrorgetElementStategetPrefixignorableWhitespaceinternalEntityDeclisDocumentStateleaveElementStatemodifyDOMErrornotationDeclprepareprintCDATATextprintDoctypeURLprintEscapedprintHexprocessingInstructionprocessingInstructionIOserializeserializeserializeserializeNodeserializePreRootsetDocumentLocatorsetOutputByteStreamsetOutputCharStreamskippedEntitystartCDATAstartDocumentstartDTDstartEntitystartNonEscapingstartPrefixMappingstartPreservingsurrogatesunparsedEntityDecl

Field Detail

DEBUGback to summary
protected static final boolean DEBUG
fLocalNSBinderback to summary
protected NamespaceSupport fLocalNSBinder

stores all namespace bindings on the current element

fNamespacePrefixesback to summary
protected boolean fNamespacePrefixes

Controls whether namespace prefixes will be printed out during serialization

fNamespacesback to summary
protected boolean fNamespaces

Controls whether namespace fixup should be performed during the serialization.

Note

if this field is set to true the following fields need to be initialized: fNSBinder, fLocalNSBinder, fSymbolTable, XMLSymbols.EMPTY_STRING, fXmlSymbol, fXmlnsSymbol

fNSBinderback to summary
protected NamespaceSupport fNSBinder

stores namespaces in scope

fPreserveSpaceback to summary
private boolean fPreserveSpace
fSymbolTableback to summary
protected SymbolTable fSymbolTable

symbol table for serialization

PREFIXback to summary
protected static final String PREFIX

Constructor Detail

XMLSerializerback to summary
public XMLSerializer()

Constructs a new serializer. The serializer cannot be used without calling setOutputCharStream or setOutputByteStream first.

XMLSerializerback to summary
public XMLSerializer(OutputFormat format)

Deprecated

as a consequence of OutputFormat being deprecated. See corresponding docs for further information.

Constructs a new serializer. The serializer cannot be used without calling setOutputCharStream or setOutputByteStream first.

XMLSerializerback to summary
public XMLSerializer(Writer writer, OutputFormat format)

Deprecated

as a consequence of OutputFormat being deprecated. See corresponding docs for further information.

Constructs a new serializer that writes to the specified writer using the specified output format. If format is null, will use a default output format.

Parameters
writer:Writer

The writer to use

format:OutputFormat

The output format to use, null for the default

XMLSerializerback to summary
public XMLSerializer(OutputStream output, OutputFormat format)

Deprecated

as a consequence of OutputFormat being deprecated. See corresponding docs for further information.

Constructs a new serializer that writes to the specified output stream using the specified output format. If format is null, will use a default output format.

Parameters
output:OutputStream

The output stream to use

format:OutputFormat

The output format to use, null for the default

Method Detail

checkUnboundNamespacePrefixedNodeback to summary
protected void checkUnboundNamespacePrefixedNode(Node node) throws IOException

Overrides org.apache.xml.serialize.BaseMarkupSerializer.checkUnboundNamespacePrefixedNode.

DOM Level 3: Check a node to determine if it contains unbound namespace prefixes.

Parameters
node:Node

The node to check for unbound namespace prefices

endElementback to summary
public void endElement(String namespaceURI, String localName, String rawName) throws SAXException

Implements org.xml.sax.ContentHandler.endElement.

Doc from org.xml.sax.ContentHandler.endElement.

Receive notification of the end of an element.

The SAX parser will invoke this method at the end of every element in the XML document; there will be a corresponding startElement event for every endElement event (even when the element is empty).

For information on the names, see startElement.

Parameters
namespaceURI:String

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

localName:String

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

rawName:String

the qualified XML name (with prefix), or the empty string if qualified names are not available

Exceptions
SAXException:
any SAX exception, possibly wrapping another exception
endElementback to summary
public void endElement(String tagName) throws SAXException

Implements org.xml.sax.DocumentHandler.endElement.

Doc from org.xml.sax.DocumentHandler.endElement.

Receive notification of the end of an element.

The SAX parser will invoke this method at the end of every element in the XML document; there will be a corresponding startElement() event for every endElement() event (even when the element is empty).

If the element name has a namespace prefix, the prefix will still be attached to the name.

Parameters
tagName:String

The element type name

Exceptions
SAXException:
Any SAX exception, possibly wrapping another exception.
endElementIOback to summary
public void endElementIO(String namespaceURI, String localName, String rawName) throws IOException
extractNamespacesback to summary
private Attributes extractNamespaces(Attributes attrs) throws SAXException

Retrieve and remove the namespaces declarations from the list of attributes.

getEntityRefback to summary
protected String getEntityRef(int ch)

Implements abstract org.apache.xml.serialize.BaseMarkupSerializer.getEntityRef.

Doc from org.apache.xml.serialize.BaseMarkupSerializer.getEntityRef.

Returns the suitable entity reference for this character value, or null if no such entity exists. Calling this method with '&' will return "&".

Parameters
ch:int

Character value

Returns:String

Character entity name, or null

printAttributeback to summary
private void printAttribute(String name, String value, boolean isSpecified, Attr attr) throws IOException

Prints attribute.

Note

xml:space attribute modifies output format

printEscapedback to summary
protected void printEscaped(String source) throws IOException

Overrides org.apache.xml.serialize.BaseMarkupSerializer.printEscaped.

Doc from org.apache.xml.serialize.BaseMarkupSerializer.printEscaped.

Escapes a string so it may be printed as text content or attribute value. Non printable characters are escaped using character references. Where the format specifies a deault entity reference, that reference is used (e.g. <).

Parameters
source:String

The string to escape

printNamespaceAttrback to summary
private void printNamespaceAttr(String prefix, String uri) throws IOException

Serializes a namespace attribute with the given prefix and value for URI. In case prefix is empty will serialize default namespace declaration.

printTextback to summary
protected void printText(String text, boolean preserveSpace, boolean unescaped) throws IOException

Overrides org.apache.xml.serialize.BaseMarkupSerializer.printText.

printTextback to summary
protected void printText(char[] chars, int start, int length, boolean preserveSpace, boolean unescaped) throws IOException

Overrides org.apache.xml.serialize.BaseMarkupSerializer.printText.

Doc from org.apache.xml.serialize.BaseMarkupSerializer.printText.

Called to print additional text with whitespace handling. If spaces are preserved, the text is printed as if by calling printText(String, boolean, boolean) with a call to Printer#breakLine for each new line. If spaces are not preserved, the text is broken at space boundaries if longer than the line width; Multiple spaces are printed as such, but spaces at beginning of line are removed.

Parameters
chars:char[]

The text to print

start:int

The start offset

length:int

The number of characters

preserveSpace:boolean

Space preserving flag

unescaped:boolean

Print unescaped

printXMLCharback to summary
protected void printXMLChar(int ch) throws IOException

print text data

resetback to summary
public boolean reset()

Overrides org.apache.xml.serialize.BaseMarkupSerializer.reset.

serializeElementback to summary
protected void serializeElement(Element elem) throws IOException

Implements abstract org.apache.xml.serialize.BaseMarkupSerializer.serializeElement.

Called to serialize a DOM element. Equivalent to calling startElement, endElement and serializing everything inbetween, but better optimized.

Parameters
elem:Element

Doc from org.apache.xml.serialize.BaseMarkupSerializer.serializeElement.

The element to serialize

Exceptions
IOException:

Doc from org.apache.xml.serialize.BaseMarkupSerializer.serializeElement.

An I/O exception occured while serializing

setNamespacesback to summary
public void setNamespaces(boolean namespaces)

This methods turns on namespace fixup algorithm during DOM serialization.

See Also
org.w3c.dom.ls.LSSerializer
setOutputFormatback to summary
public void setOutputFormat(OutputFormat format)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.setOutputFormat.

Implements org.apache.xml.serialize.Serializer.setOutputFormat.

Doc from org.apache.xml.serialize.Serializer.setOutputFormat.

Deprecated

as a consequence of OutputFormat being deprecated. See corresponding docs for further information.

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.

Parameters
format:OutputFormat

The output format to use

startDocumentback to summary
protected void startDocument(String rootTagName) throws IOException

Called to serialize the document's DOCTYPE by the root element. The document type declaration must name the root element, but the root element is only known when that element is serialized, and not at the start of the document.

This method will check if it has not been called before (_started), will serialize the document type declaration, and will serialize all pre-root comments and PIs that were accumulated in the document (see serializePreRoot). Pre-root will be serialized even if this is not the first root element of the document.

startElementback to summary
public void startElement(String namespaceURI, String localName, String rawName, Attributes attrs) throws SAXException

Implements org.xml.sax.ContentHandler.startElement.

Doc from org.xml.sax.ContentHandler.startElement.

Receive notification of the beginning of an element.

The Parser will invoke this method at the beginning of every element in the XML document; there will be a corresponding endElement event for every startElement event (even when the element is empty). All of the element's content will be reported, in order, before the corresponding endElement event.

This event allows up to three name components for each element:

  1. the Namespace URI;
  2. the local name; and
  3. the qualified (prefixed) name.

Any or all of these may be provided, depending on the values of the http://xml.org/sax/features/namespaces and the http://xml.org/sax/features/namespace-prefixes properties:

  • the Namespace URI and local name are required when the namespaces property is true (the default), and are optional when the namespaces property is false (if one is specified, both must be);
  • the qualified name is required when the namespace-prefixes property is true, and is optional when the namespace-prefixes property is false (the default).

Note that the attribute list provided will contain only attributes with explicit values (specified or defaulted): #IMPLIED attributes will be omitted. The attribute list will contain attributes used for Namespace declarations (xmlns* attributes) only if the http://xml.org/sax/features/namespace-prefixes property is true (it is false by default, and support for a true value is optional).

Like characters(), attribute values may have characters that need more than one char value.

Parameters
namespaceURI:String

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

localName:String

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

rawName:String

the qualified name (with prefix), or the empty string if qualified names are not available

attrs:Attributes

the attributes attached to the element. If there are no attributes, it shall be an empty Attributes object. The value of this object after startElement returns is undefined

Exceptions
SAXException:
any SAX exception, possibly wrapping another exception
startElementback to summary
public void startElement(String tagName, AttributeList attrs) throws SAXException

Implements org.xml.sax.DocumentHandler.startElement.

Doc from org.xml.sax.DocumentHandler.startElement.

Deprecated

as a consequence of AttributeList being deprecated. See corresponding docs for further information.

Receive notification of the beginning of an element.

The Parser will invoke this method at the beginning of every element in the XML document; there will be a corresponding endElement() event for every startElement() event (even when the element is empty). All of the element's content will be reported, in order, before the corresponding endElement() event.

If the element name has a namespace prefix, the prefix will still be attached. Note that the attribute list provided will contain only attributes with explicit values (specified or defaulted): #IMPLIED attributes will be omitted.

Parameters
tagName:String

The element type name.

attrs:AttributeList

The attributes attached to the element, if any.

Exceptions
SAXException:
Any SAX exception, possibly wrapping another exception.