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

public Class TextSerializer

extends BaseMarkupSerializer
Class Inheritance
Imports
java.io.IOException, org.w3c.dom.Element, .Node, org.xml.sax.AttributeList, .Attributes, .SAXException

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 and HTML. See the Xerces documentation for more information.

Implements a text serializer supporting both DOM and SAX 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. DOM serializing is done by calling serialize and SAX serializing is done by firing SAX events and using the serializer as a document handler.

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.

Author
Assaf Arkin
Version
$Revision: 476047 $ $Date: 2006-11-17 09:57:45 +0530 (Fri, 17 Nov 2006) $
See Also
Serializer

Field Summary

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

Constructor Summary

AccessConstructor and Description
public
TextSerializer()

Constructs a new serializer.

Method Summary

Modifier and TypeMethod and Description
public void
characters(char[]
the characters from the XML document
chars, int
the start position in the array
start, int
the number of characters to read from the array
length)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.characters.

Implements org.xml.sax.ContentHandler.characters, org.xml.sax.DocumentHandler.characters.

Receive notification of character data.
protected void
characters(String text, boolean unescaped)

public void
comment(String text)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.comment.

public void
comment(char[]
An array holding the characters in the comment.
chars, int
The starting position in the array.
start, int
The number of characters to use from the array.
length)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.comment.

Implements org.xml.sax.ext.LexicalHandler.comment.

Report an XML comment anywhere in the document.
protected ElementState
content()

Overrides org.apache.xml.serialize.BaseMarkupSerializer.content.

Deprecated as a consequence of ElementState being deprecated.
Must be called by a method about to print any type of content.
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 tagName)

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.
public void
processingInstructionIO(String target, String code)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.processingInstructionIO.

protected void
serializeElement(Element
The element to serialize
elem)

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

Called to serialize a DOM element.
protected void
serializeNode(Node
The node to serialize
node)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.serializeNode.

Serialize the DOM node.
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:
asContentHandlerasDocumentHandlerasDOMSerializerattributeDeclcharacterscheckUnboundNamespacePrefixedNodecleanupclearDocumentStateelementDeclendCDATAendDocumentendDTDendEntityendNonEscapingendPrefixMappingendPreservingenterElementStateexternalEntityDeclfatalErrorgetElementStategetPrefixignorableWhitespaceinternalEntityDeclisDocumentStateleaveElementStatemodifyDOMErrornotationDeclprepareprintCDATATextprintDoctypeURLprintEscapedprintEscapedprintHexprintTextprintTextprocessingInstructionresetserializeserializeserializeserializePreRootsetDocumentLocatorsetOutputByteStreamsetOutputCharStreamskippedEntitystartCDATAstartDocumentstartDTDstartEntitystartNonEscapingstartPrefixMappingstartPreservingsurrogatesunparsedEntityDecl

Constructor Detail

TextSerializerback to summary
public TextSerializer()

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

Method Detail

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

Overrides org.apache.xml.serialize.BaseMarkupSerializer.characters.

Implements org.xml.sax.ContentHandler.characters, org.xml.sax.DocumentHandler.characters.

Doc from org.xml.sax.ContentHandler.characters.

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.

Individual characters may consist of more than one Java char value. There are two important cases where this happens, because characters can't be represented in just sixteen bits. In one case, characters are represented in a Surrogate Pair, using two special Unicode values. Such characters are in the so-called "Astral Planes", with a code point above U+FFFF. A second case involves composite characters, such as a base character combining with one or more accent characters.

Your code should not assume that algorithms using char-at-a-time idioms will be working in character units; in some cases they will split characters. This is relevant wherever XML permits arbitrary characters, such as attribute values, processing instruction data, and comments as well as in data reported from this method. It's also generally relevant whenever Java code manipulates internationalized text; the issue isn't unique to XML.

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

Parameters
chars:char[]

the characters from the XML document

start:int

the start position in the array

length:int

the number of characters to read from the array

Exceptions
SAXException:
any SAX exception, possibly wrapping another exception
charactersback to summary
protected void characters(String text, boolean unescaped) throws IOException
commentback to summary
public void comment(String text)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.comment.

commentback to summary
public void comment(char[] chars, int start, int length)

Overrides org.apache.xml.serialize.BaseMarkupSerializer.comment.

Implements org.xml.sax.ext.LexicalHandler.comment.

Doc from org.xml.sax.ext.LexicalHandler.comment.

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). Comments in the DTD must be properly nested inside start/endDTD and start/endEntity events (if used).

Parameters
chars:char[]

An array holding the characters in the comment.

start:int

The starting position in the array.

length:int

The number of characters to use from the array.

contentback to summary
protected ElementState content()

Overrides org.apache.xml.serialize.BaseMarkupSerializer.content.

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

Deprecated

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

Must be called by a method about to print any type of content. If the element was just opened, the opening tag is closed and will be matched to a closing tag. Returns the current element state with empty and afterElement set to false.

Returns:ElementState

The current element state

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 tagName) throws IOException
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

processingInstructionIOback to summary
public void processingInstructionIO(String target, String code) throws IOException

Overrides org.apache.xml.serialize.BaseMarkupSerializer.processingInstructionIO.

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

serializeNodeback to summary
protected void serializeNode(Node node) throws IOException

Overrides org.apache.xml.serialize.BaseMarkupSerializer.serializeNode.

Serialize the DOM node. This method is unique to the Text serializer.

Parameters
node:Node

The node to serialize

Exceptions
IOException:

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

An I/O exception occured while serializing

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.

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.