org.apache.xml.serializer

Class ToStream

Implemented Interfaces:
org.xml.sax.ContentHandler, DeclHandler, ErrorHandler, DOM2DTM.CharacterNodeHandler, DOMSerializer, ExtendedContentHandler, ExtendedLexicalHandler, org.xml.sax.ext.LexicalHandler, SerializationHandler, Serializer, SerializerConstants, XSLOutputAttributes
Known Direct Subclasses:
ToHTMLStream, ToTextStream, ToXMLStream

public abstract class ToStream
extends SerializerBase

This abstract class is a base class for other stream serializers (xml, html, text ...) that write output to a stream.
Authors:
Santiago Pericas-Geertsen
G. Todd Miller

Fields inherited from interface org.apache.xml.serializer.ExtendedContentHandler

HTML_ATTREMPTY, HTML_ATTRURL, NO_BAD_CHARS

Fields inherited from interface org.apache.xml.serializer.SerializerConstants

BEGCDATA, CDATA_CONTINUE, CDATA_DELIMITER_CLOSE, CDATA_DELIMITER_OPEN, CNTCDATA, DEFAULT_SAX_SERIALIZER, EMPTYSTRING, ENDCDATA, ENTITY_AMP, ENTITY_CRLF, ENTITY_GT, ENTITY_LT, ENTITY_QUOT, XMLNS_PREFIX, XMLNS_URI, XML_PREFIX

Constructor Summary

ToStream()
Default constructor

Method Summary

void
addAttributeAlways(String uri, String localName, String rawName, String type, String value)
Adds the given attribute to the set of attributes, even if there is nocurrently open element.
void
attributeDecl(String eName, String aName, String type, String valueDefault, String value)
Report an attribute type declaration.
void
characters(String s)
Receive notification of character data.
void
characters(chars[] , int start, int length)
Receive notification of character data.
void
comment(ch[] , int start, int length)
Receive notification of an XML comment anywhere in the document.
void
elementDecl(String name, String model)
Report an element type declaration.
void
endCDATA()
Report the end of a CDATA section.
void
endDTD()
Report the end of DTD declarations.
void
endElement(String name)
Receive notification of the end of an element.
void
endElement(String namespaceURI, String localName, String name)
Receive notification of the end of an element.
void
endNonEscaping()
Ends an un-escaping section.
void
endPrefixMapping(String prefix)
End the scope of a prefix-URI Namespace mapping.
void
externalEntityDecl(String name, String publicId, String systemId)
Report a parsed external entity declaration.
void
flushPending()
This method flushes any pending events, which can be startDocument() closing the opening tag of an element, or closing an open CDATA section.
int
getIndentAmount()
Returns the m_indentAmount.
Properties
getOutputFormat()
Returns the output format for this serializer.
OutputStream
getOutputStream()
Get the output stream where the events will be serialized to.
Writer
getWriter()
Get the character stream where the events will be serialized to.
void
ignorableWhitespace(ch[] , int start, int length)
Receive notification of ignorable whitespace in element content.
void
internalEntityDecl(String name, String value)
Report an internal entity declaration.
void
processAttributes(Writer writer, int nAttrs)
Process the attributes, which means to write out the currently collected attributes to the writer.
boolean
reset()
Try's to reset the super class and reset this class for re-use, so that you don't need to create a new serializer (mostly for performance reasons).
void
serialize(Node node)
Serializes the DOM node.
void
setCdataSectionElements(Vector URI_and_localNames)
Remembers the cdata sections specified in the cdata-section-elements.
void
setContentHandler(ContentHandler ch)
boolean
setEscaping(boolean escape)
void
setIndentAmount(int m_indentAmount)
Sets the m_indentAmount.
boolean
setLineSepUse(boolean use_sytem_line_break)
Set if the operating systems end-of-line line separator should be used when serializing.
void
setOutputFormat(Properties format)
Specifies an output format for this serializer.
void
setOutputStream(OutputStream output)
Specifies an output stream to which the document should be serialized.
void
setTransformer(Transformer transformer)
void
setWriter(Writer writer)
Specifies a writer to which the document should be serialized.
void
skippedEntity(String name)
Receive notification of a skipped entity.
void
startCDATA()
Report the start of a CDATA section.
void
startDTD(String name, String publicId, String systemId)
Report the start of DTD declarations, if any.
void
startElement(String elementName)
void
startElement(String elementNamespaceURI, String elementLocalName, String elementName)
Receive notification of the beginning of an element, additional namespace or attribute information can occur before or after this call, that is associated with this element.
void
startElement(String namespaceURI, String localName, String name, Attributes atts)
Receive notification of the beginning of an element, although this is a SAX method additional namespace or attribute information can occur before or after this call, that is associated with this element.
void
startEntity(String name)
Report the beginning of an entity.
void
startNonEscaping()
Starts an un-escaping section.
void
startPrefixMapping(String prefix, String uri)
Begin the scope of a prefix-URI Namespace mapping just before another element is about to start.
boolean
startPrefixMapping(String prefix, String uri, boolean shouldFlush)
Handle a prefix/uri mapping, which is associated with a startElement() that is soon to follow.
void
writeAttrString(Writer writer, String string, String encoding)
Returns the specified string after substituting specials, and UTF-16 surrogates for chracter references &#xnn.

Methods inherited from class org.apache.xml.serializer.SerializerBase

addAttribute, addAttribute, addAttributeAlways, addAttributes, asContentHandler, asDOMSerializer, characters, close, comment, endEntity, entityReference, error, fatalError, fireEndEntity, getDoctypePublic, getDoctypeSystem, getEncoding, getIndent, getIndentAmount, getMediaType, getNamespaceMappings, getNamespaceURI, getNamespaceURIFromPrefix, getOmitXMLDeclaration, getPrefix, getStandalone, getTransformer, getVersion, namespaceAfterStartElement, reset, setDoctype, setDoctypePublic, setDoctypeSystem, setDocumentLocator, setEncoding, setIndent, setIndentAmount, setMediaType, setNamespaceMappings, setOmitXMLDeclaration, setSourceLocator, setStandalone, setTransformer, setVersion, startDocument, warning

Constructor Details

ToStream

public ToStream()
Default constructor

Method Details

addAttributeAlways

public void addAttributeAlways(String uri,
                               String localName,
                               String rawName,
                               String type,
                               String value)
Adds the given attribute to the set of attributes, even if there is nocurrently open element. This is useful if a SAX startPrefixMapping() should need to add an attribute before the element name is seen. This method is a copy of its super classes method, except that some tracing of events is done. This is so the tracing is only done for stream serializers, not for SAX ones.
Overrides:
addAttributeAlways in interface SerializerBase
Parameters:
uri - the URI of the attribute
localName - the local name of the attribute
rawName - the qualified name of the attribute
type - the type of the attribute (probably CDATA)
value - the value of the attribute

attributeDecl

public void attributeDecl(String eName,
                          String aName,
                          String type,
                          String valueDefault,
                          String value)
            throws SAXException
Report an attribute type declaration.

Only the effective (first) declaration for an attribute will be reported. The type will be one of the strings "CDATA", "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", or "NOTATION", or a parenthesized token group with the separator "|" and all whitespace removed.

Parameters:
eName - The name of the associated element.
aName - The name of the attribute.
type - A string representing the attribute type.
valueDefault - A string representing the attribute default ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if none of these applies.
value - A string representing the attribute's default value, or null if there is none.

characters

public void characters(String s)
            throws org.xml.sax.SAXException
Receive notification of character data.
Specified by:
characters in interface ExtendedContentHandler
Parameters:
s - The string of characters to process.

characters

public void characters(chars[] ,
                       int start,
                       int length)
            throws org.xml.sax.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).

Parameters:
start - The start position in the array.
length - The number of characters to read from the array.

comment

public void comment(ch[] ,
                    int start,
                    int length)
            throws org.xml.sax.SAXException
Receive notification of 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).
Parameters:
start - The starting position in the array.
length - The number of characters to use from the array.

elementDecl

public void elementDecl(String name,
                        String model)
            throws SAXException
Report an element type declaration.

The content model will consist of the string "EMPTY", the string "ANY", or a parenthesised group, optionally followed by an occurrence indicator. The model will be normalized so that all whitespace is removed,and will include the enclosing parentheses.

Parameters:
name - The element type name.
model - The content model as a normalized string.

endCDATA

public void endCDATA()
            throws org.xml.sax.SAXException
Report the end of a CDATA section.

endDTD

public void endDTD()
            throws org.xml.sax.SAXException
Report the end of DTD declarations.

endElement

public void endElement(String name)
            throws org.xml.sax.SAXException
Receive notification of the end of an element.
Specified by:
endElement in interface ExtendedContentHandler
Parameters:
name - The element type name

endElement

public void endElement(String namespaceURI,
                       String localName,
                       String name)
            throws org.xml.sax.SAXException
Receive notification of the end of an element.
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

endNonEscaping

public void endNonEscaping()
            throws org.xml.sax.SAXException
Ends an un-escaping section.

endPrefixMapping

public void endPrefixMapping(String prefix)
            throws org.xml.sax.SAXException
End the scope of a prefix-URI Namespace mapping.
Parameters:
prefix - The prefix that was being mapping.
See Also:
org.xml.sax.ContentHandler.endPrefixMapping

externalEntityDecl

public void externalEntityDecl(String name,
                               String publicId,
                               String systemId)
            throws SAXException
Report a parsed external entity declaration.

Only the effective (first) declaration for each entity will be reported.

Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%'.
publicId - The declared public identifier of the entity, or null if none was declared.
systemId - The declared system identifier of the entity.
See Also:
internalEntityDecl(String,String), org.xml.sax.DTDHandler.unparsedEntityDecl

flushPending

public void flushPending()
            throws SAXException
This method flushes any pending events, which can be startDocument() closing the opening tag of an element, or closing an open CDATA section.
Specified by:
flushPending in interface SerializationHandler

getIndentAmount

public int getIndentAmount()
Returns the m_indentAmount.
Specified by:
getIndentAmount in interface XSLOutputAttributes
Overrides:
getIndentAmount in interface SerializerBase
Returns:
int

getOutputFormat

public Properties getOutputFormat()
Returns the output format for this serializer.
Specified by:
getOutputFormat in interface Serializer
Returns:
The output format in use

getOutputStream

public 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.

getWriter

public 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.

ignorableWhitespace

public void ignorableWhitespace(ch[] ,
                                int start,
                                int length)
            throws org.xml.sax.SAXException
Receive notification of ignorable whitespace in element content. Not sure how to get this invoked quite yet.
Parameters:
start - The start position in the array.
length - The number of characters to read from the array.
See Also:
characters

internalEntityDecl

public void internalEntityDecl(String name,
                               String value)
            throws SAXException
Report an internal entity declaration.

Only the effective (first) declaration for each entity will be reported.

Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%'.
value - The replacement text of the entity.
See Also:
externalEntityDecl(String,String,String), org.xml.sax.DTDHandler.unparsedEntityDecl

processAttributes

public void processAttributes(Writer writer,
                              int nAttrs)
            throws IOException,
                   SAXException
Process the attributes, which means to write out the currently collected attributes to the writer. The attributes are not cleared by this method
Parameters:
writer - the writer to write processed attributes to.
nAttrs - the number of attributes in m_attributes to be processed

reset

public boolean reset()
Try's to reset the super class and reset this class for re-use, so that you don't need to create a new serializer (mostly for performance reasons).
Specified by:
reset in interface Serializer
Overrides:
reset in interface SerializerBase
Returns:
true if the class was successfuly reset.

serialize

public void serialize(Node node)
            throws IOException
Serializes the DOM node. Throws an exception only if an I/O exception occured while serializing.
Specified by:
serialize in interface SerializationHandler
serialize in interface DOMSerializer
Parameters:
node - Node to serialize.

setCdataSectionElements

public void setCdataSectionElements(Vector URI_and_localNames)
Remembers the cdata sections specified in the cdata-section-elements. The "official way to set URI and localName pairs. This method should be used by both Xalan and XSLTC.
Specified by:
setCdataSectionElements in interface XSLOutputAttributes
Parameters:

setContentHandler

public void setContentHandler(ContentHandler ch)
Specified by:
setContentHandler in interface SerializationHandler

setEscaping

public boolean setEscaping(boolean escape)
Specified by:
setEscaping in interface SerializationHandler

setIndentAmount

public void setIndentAmount(int m_indentAmount)
Sets the m_indentAmount.
Specified by:
setIndentAmount in interface SerializationHandler
Overrides:
setIndentAmount in interface SerializerBase
Parameters:
m_indentAmount - The m_indentAmount to set

setLineSepUse

public boolean setLineSepUse(boolean use_sytem_line_break)
Set if the operating systems end-of-line line separator should be used when serializing. If set false NL character (decimal 10) is left alone, otherwise the new-line will be replaced on output with the systems line separator. For example on UNIX this is NL, while on Windows it is two characters, CR NL, where CR is the carriage-return (decimal 13).
Parameters:
use_sytem_line_break - True if an input NL is replaced with the operating systems end-of-line separator.
Returns:
The previously set value of the serializer.

setOutputFormat

public void setOutputFormat(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

setOutputStream

public void setOutputStream(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

setTransformer

public void setTransformer(Transformer transformer)
Specified by:
setTransformer in interface SerializationHandler
Overrides:
setTransformer in interface SerializerBase

setWriter

public void setWriter(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

skippedEntity

public void skippedEntity(String name)
            throws org.xml.sax.SAXException
Receive notification of a skipped entity.
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]".
See Also:
org.xml.sax.ContentHandler.skippedEntity

startCDATA

public void startCDATA()
            throws org.xml.sax.SAXException
Report the start of a CDATA section.

startDTD

public void startDTD(String name,
                     String publicId,
                     String systemId)
            throws org.xml.sax.SAXException
Report the start of DTD declarations, if any. Any declarations are assumed to be in the internal subset unless otherwise indicated.
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.

startElement

public void startElement(String elementName)
            throws SAXException
Specified by:
startElement in interface ExtendedContentHandler

startElement

public void startElement(String elementNamespaceURI,
                         String elementLocalName,
                         String elementName)
            throws SAXException
Receive notification of the beginning of an element, additional namespace or attribute information can occur before or after this call, that is associated with this element.
Specified by:
startElement in interface ExtendedContentHandler
Parameters:
See Also:
org.xml.sax.ContentHandler.startElement, org.xml.sax.ContentHandler.endElement, org.xml.sax.AttributeList

startElement

public void startElement(String namespaceURI,
                         String localName,
                         String name,
                         Attributes atts)
            throws org.xml.sax.SAXException
Receive notification of the beginning of an element, although this is a SAX method additional namespace or attribute information can occur before or after this call, that is associated with this element.
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.
See Also:
org.xml.sax.ContentHandler.startElement, org.xml.sax.ContentHandler.endElement, org.xml.sax.AttributeList

startEntity

public void startEntity(String name)
            throws org.xml.sax.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.
Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%'.
See Also:
ToStream, org.xml.sax.ext.DeclHandler.internalEntityDecl, org.xml.sax.ext.DeclHandler.externalEntityDecl

startNonEscaping

public void startNonEscaping()
            throws org.xml.sax.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.


startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
            throws org.xml.sax.SAXException
Begin the scope of a prefix-URI Namespace mapping just before another element is about to start. This call will close any open tags so that the prefix mapping will not apply to the current element, but the up comming child.
Parameters:
prefix - The Namespace prefix being declared.
uri - The Namespace URI the prefix is mapped to.
See Also:
org.xml.sax.ContentHandler.startPrefixMapping

startPrefixMapping

public boolean startPrefixMapping(String prefix,
                                  String uri,
                                  boolean shouldFlush)
            throws org.xml.sax.SAXException
Handle a prefix/uri mapping, which is associated with a startElement() that is soon to follow. Need to close any open start tag to make sure than any name space attributes due to this event are associated wih the up comming element, not the current one.
Specified by:
startPrefixMapping in interface ExtendedContentHandler
Parameters:
prefix - The Namespace prefix being declared.
uri - The Namespace URI the prefix is mapped to.
shouldFlush - true if any open tags need to be closed first, this will impact which element the mapping applies to (open parent, or its up comming child)
Returns:
returns true if the call made a change to the current namespace information, false if it did not change anything, e.g. if the prefix/namespace mapping was already in scope from before.

writeAttrString

public void writeAttrString(Writer writer,
                            String string,
                            String encoding)
            throws IOException
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.

Copyright B) 2004 Apache XML Project. All Rights Reserved.