|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.apache.xml.serialize.BaseMarkupSerializer
Base class for a serializer supporting both DOM and SAX pretty serializing of XML/HTML/XHTML documents. Derives classes perform the method-specific serializing, this class provides the common serializing mechanisms.
The serializer must be initialized with the proper writer and
output format before it can be used by calling #init
.
The serializer can be reused any number of times, but cannot
be used concurrently by two threads.
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(org.w3c.dom.Element)
and SAX serializing is done by firing
SAX events and using the serializer as a document handler.
This also applies to derived class.
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 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.
When indenting, the serializer is capable of detecting seemingly element content, and serializing these elements indented on separate lines. An element is serialized indented when it is the first or last child of an element, or immediate following or preceding another element.
Serializer
,
DOMSerializer
Field Summary | |
protected java.lang.String |
_docTypePublicId
The system identifier of the document type, if known. |
protected java.lang.String |
_docTypeSystemId
The system identifier of the document type, if known. |
protected java.io.IOException |
_exception
Holds the exception thrown by the serializer. |
protected OutputFormat |
_format
The output format associated with this serializer. |
protected java.util.Hashtable |
_prefixes
Association between namespace URIs (keys) and prefixes (values). |
protected boolean |
_started
If the document has been started (header serialized), this flag is set to true so it's not started twice. |
protected java.io.Writer |
_writer
The writer to which the document is written. |
Constructor Summary | |
protected |
BaseMarkupSerializer()
Protected constructor can only be used by derived class. |
Method Summary | |
ContentHandler |
asContentHandler()
Return a ContentHandler interface into this serializer. |
DocumentHandler |
asDocumentHandler()
Return a DocumentHandler interface into this serializer. |
DOMSerializer |
asDOMSerializer()
Return a DOMSerializer interface into this serializer. |
void |
attributeDecl(java.lang.String eName,
java.lang.String aName,
java.lang.String type,
java.lang.String valueDefault,
java.lang.String value)
Report an attribute type declaration. |
protected void |
breakLine()
Called to print a line consisting of the text accumulated so far. |
protected void |
breakLine(boolean preserveSpace)
|
void |
characters(char[] chars,
int start,
int length)
Receive notification of character data. |
protected void |
characters(java.lang.String text,
boolean unescaped)
Called to print the text contents in the prevailing element format. |
void |
comment(char[] chars,
int start,
int length)
Report an XML comment anywhere in the document. |
void |
comment(java.lang.String text)
|
protected org.apache.xml.serialize.ElementState |
content()
Must be called by a method about to print any type of content. |
void |
elementDecl(java.lang.String name,
java.lang.String model)
Report an element type declaration. |
void |
endCDATA()
Report the end of a CDATA section. |
void |
endDocument()
Called at the end of the document to wrap it up. |
void |
endDTD()
Report the end of DTD declarations. |
void |
endEntity(java.lang.String name)
Report the end of an entity. |
void |
endPrefixMapping(java.lang.String prefix)
End the scope of a prefix-URI mapping. |
protected void |
enterDTD()
Called by any of the DTD handlers to enter DTD mode. |
protected org.apache.xml.serialize.ElementState |
enterElementState(java.lang.String namespaceURI,
java.lang.String localName,
java.lang.String rawName,
boolean preserveSpace)
Enter a new element state for the specified element. |
protected java.lang.String |
escape(java.lang.String source)
Escapes a string so it may be printed as text content or attribute value. |
void |
externalEntityDecl(java.lang.String name,
java.lang.String publicId,
java.lang.String systemId)
Report a parsed external entity declaration. |
void |
flush()
Flush the output stream. |
protected org.apache.xml.serialize.ElementState |
getElementState()
Return the state of the current element, or null if not within any element (e.g. |
protected abstract java.lang.String |
getEntityRef(char ch)
Returns the suitable entity reference for this character value, or null if no such entity exists. |
protected java.lang.String |
getPrefix(java.lang.String namespaceURI)
|
void |
ignorableWhitespace(char[] chars,
int start,
int length)
Receive notification of ignorable whitespace in element content. |
protected void |
indent()
Increment the indentation for the next line. |
void |
internalEntityDecl(java.lang.String name,
java.lang.String value)
Report an internal entity declaration. |
protected java.lang.String |
leaveDTD()
Called by the root element to leave DTD mode and if any DTD parts were printer, will return a string with their textual content. |
protected org.apache.xml.serialize.ElementState |
leaveElementState()
Leave the current element state and return to the state of the parent element, or no state if this is the root element. |
void |
notationDecl(java.lang.String name,
java.lang.String publicId,
java.lang.String systemId)
Receive notification of a notation declaration event. |
protected void |
printDoctypeURL(java.lang.String url)
Print a document type public or system identifier URL. |
protected void |
printSpace()
Called to print a single space between text parts that may be broken into separate lines. |
protected void |
printText(char[] chars,
int start,
int end)
|
protected void |
printText(java.lang.String text)
Called to print additional text. |
protected void |
printText(java.lang.String text,
boolean preserveSpace)
Called to print additional text with whitespace handling. |
protected void |
printText(java.lang.StringBuffer text,
boolean preserveSpace)
|
void |
processingInstruction(java.lang.String target,
java.lang.String code)
Receive notification of a processing instruction. |
protected void |
reset()
|
void |
serialize(Document doc)
Serializes the DOM document using the previously specified writer and output format. |
void |
serialize(DocumentFragment frag)
Serializes the DOM document fragmnt using the previously specified writer and output format. |
void |
serialize(Element elem)
Serializes the DOM element using the previously specified writer and output format. |
protected abstract void |
serializeElement(Element elem)
Called to serializee the DOM element. |
protected void |
serializeNode(Node node)
Serialize the DOM node. |
protected void |
serializePreRoot()
Comments and PIs cannot be serialized before the root element, because the root element serializes the document type, which generally comes first. |
void |
setDocumentLocator(Locator locator)
Receive an object for locating the origin of SAX document events. |
void |
setOutputByteStream(java.io.OutputStream output)
Specifies an output stream to which the document should be serialized. |
void |
setOutputCharStream(java.io.Writer output)
Specifies a writer to which the document should be serialized. |
void |
setOutputFormat(OutputFormat format)
Specifies an output format for this serializer. |
void |
skippedEntity(java.lang.String name)
Receive notification of a skipped entity. |
void |
startCDATA()
Report the start of a CDATA section. |
void |
startDTD(java.lang.String name,
java.lang.String publicId,
java.lang.String systemId)
Report the start of DTD declarations, if any. |
void |
startEntity(java.lang.String name)
Report the beginning of an entity. |
void |
startPrefixMapping(java.lang.String prefix,
java.lang.String uri)
Begin the scope of a prefix-URI Namespace mapping. |
protected void |
unindent()
Decrement the indentation for the next line. |
void |
unparsedEntityDecl(java.lang.String name,
java.lang.String publicId,
java.lang.String systemId,
java.lang.String notationName)
Receive notification of an unparsed entity declaration event. |
Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Field Detail |
protected OutputFormat _format
protected java.io.Writer _writer
protected java.io.IOException _exception
protected boolean _started
protected java.util.Hashtable _prefixes
protected java.lang.String _docTypePublicId
protected java.lang.String _docTypeSystemId
Constructor Detail |
protected BaseMarkupSerializer()
#init
.Method Detail |
public DocumentHandler asDocumentHandler()
DocumentHandler
interface into this serializer.
If the serializer does not support the DocumentHandler
interface, it should return null.public ContentHandler asContentHandler()
ContentHandler
interface into this serializer.
If the serializer does not support the ContentHandler
interface, it should return null.public DOMSerializer asDOMSerializer()
DOMSerializer
interface into this serializer.
If the serializer does not support the DOMSerializer
interface, it should return null.public void setOutputByteStream(java.io.OutputStream output) throws java.io.UnsupportedEncodingException
public void setOutputCharStream(java.io.Writer output)
public void setOutputFormat(OutputFormat format)
format
- The output format to useprotected void reset()
public void serialize(Element elem) throws java.io.IOException
elem
- The element to serializepublic void serialize(DocumentFragment frag) throws java.io.IOException
elem
- The element to serializepublic void serialize(Document doc) throws java.io.IOException
doc
- The document to serializepublic void characters(char[] chars, int start, int length)
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).
ch
- The characters from the XML document.start
- The start position in the array.length
- The number of characters to read from the array.ContentHandler.ignorableWhitespace(char[], int, int)
,
Locator
public void ignorableWhitespace(char[] chars, int start, int length)
Validating Parsers must use this method to report each chunk of ignorable whitespace (see the W3C XML 1.0 recommendation, section 2.10): non-validating parsers may also use this method if they are capable of parsing and using content models.
SAX parsers may return all contiguous whitespace 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.
ch
- The characters from the XML document.start
- The start position in the array.length
- The number of characters to read from the array.ContentHandler.characters(char[], int, int)
public void processingInstruction(java.lang.String target, java.lang.String code)
The Parser will invoke this method once for each processing instruction found: note that processing instructions may occur before or after the main document element.
A SAX parser should never report an XML declaration (XML 1.0, section 2.8) or a text declaration (XML 1.0, section 4.3.1) using this method.
target
- The processing instruction target.data
- The processing instruction data, or null if
none was supplied.public void comment(char[] chars, int start, int length)
This callback will be used for comments inside or outside the document element, including comments in the external DTD subset (if read).
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.public void comment(java.lang.String text)
public void startCDATA()
The contents of the CDATA section will be reported through
the regular characters
event.
LexicalHandler.endCDATA()
public void endCDATA()
LexicalHandler.startCDATA()
public void endDocument() throws SAXException
public void startEntity(java.lang.String name)
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.
Note that skipped entities will be reported through the
skippedEntity
event, which is part of the ContentHandler interface.
name
- The name of the entity. If it is a parameter
entity, the name will begin with '%'.LexicalHandler.endEntity(java.lang.String)
,
DeclHandler.internalEntityDecl(java.lang.String, java.lang.String)
,
DeclHandler.externalEntityDecl(java.lang.String, java.lang.String, java.lang.String)
public void endEntity(java.lang.String name)
name
- The name of the entity that is ending.LexicalHandler.startEntity(java.lang.String)
public void setDocumentLocator(Locator locator)
SAX parsers are strongly encouraged (though not absolutely required) to supply a locator: if it does so, it must supply the locator to the application by invoking this method before invoking any of the other methods in the DocumentHandler interface.
The locator allows the application to determine the end position of any document-related event, even if the parser is not reporting an error. Typically, the application will use this information for reporting its own errors (such as character content that does not match an application's business rules). The information returned by the locator is probably not sufficient for use with a search engine.
Note that the locator will return correct information only during the invocation of the events in this interface. The application should not attempt to use it at any other time.
locator
- An object that can return the location of
any SAX document event.Locator
public void skippedEntity(java.lang.String name) throws SAXException
The Parser will invoke this method once for each entity skipped. Non-validating processors may skip entities if they have not seen the declarations (because, for example, the entity was declared in an external DTD subset). All processors may skip external entities, depending on the values of the http://xml.org/sax/features/external-general-entities and the http://xml.org/sax/features/external-parameter-entities properties.
name
- The name of the skipped entity. If it is a
parameter entity, the name will begin with '%'.public void startPrefixMapping(java.lang.String prefix, java.lang.String uri) throws SAXException
The information from this event is not necessary for normal Namespace processing: the SAX XML reader will automatically replace prefixes for element and attribute names when the http://xml.org/sax/features/namespaces feature is true (the default).
There are cases, however, when applications need to use prefixes in character data or in attribute values, where they cannot safely be expanded automatically; the start/endPrefixMapping event supplies the information to the application to expand prefixes in those contexts itself, if necessary.
Note that start/endPrefixMapping events are not guaranteed to be properly nested relative to each-other: all startPrefixMapping events will occur before the corresponding startElement event, and all endPrefixMapping events will occur after the corresponding endElement event, but their order is not guaranteed.
prefix
- The Namespace prefix being declared.uri
- The Namespace URI the prefix is mapped to.ContentHandler.endPrefixMapping(java.lang.String)
,
ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)
public void endPrefixMapping(java.lang.String prefix) throws SAXException
See startPrefixMapping for details. This event will always occur after the corresponding endElement event, but the order of endPrefixMapping events is not otherwise guaranteed.
prefix
- The prefix that was being mapping.ContentHandler.startPrefixMapping(java.lang.String, java.lang.String)
,
ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)
public void startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
Any declarations are assumed to be in the internal subset
unless otherwise indicated by a startEntity
event.
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.LexicalHandler.endDTD()
,
LexicalHandler.startEntity(java.lang.String)
public void endDTD()
LexicalHandler.startDTD(java.lang.String, java.lang.String, java.lang.String)
public void elementDecl(java.lang.String name, java.lang.String model)
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.
name
- The element type name.model
- The content model as a normalized string.public void attributeDecl(java.lang.String eName, java.lang.String aName, java.lang.String type, java.lang.String valueDefault, java.lang.String value)
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.
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.public void internalEntityDecl(java.lang.String name, java.lang.String value)
Only the effective (first) declaration for each entity will be reported.
name
- The name of the entity. If it is a parameter
entity, the name will begin with '%'.value
- The replacement text of the entity.DeclHandler.externalEntityDecl(java.lang.String, java.lang.String, java.lang.String)
,
DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)
public void externalEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
Only the effective (first) declaration for each entity will be reported.
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.DeclHandler.internalEntityDecl(java.lang.String, java.lang.String)
,
DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)
public void unparsedEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId, java.lang.String notationName)
Note that the notation name corresponds to a notation reported by the notationDecl() event. It is up to the application to record the entity for later reference, if necessary.
If the system identifier is a URL, the parser must resolve it fully before passing it to the application.
name
- The unparsed entity's name.publicId
- The entity's public identifier, or null if none
was given.systemId
- The entity's system identifier (it must always
have one).notation
- name The name of the associated notation.DTDHandler.notationDecl(java.lang.String, java.lang.String, java.lang.String)
,
AttributeList
public void notationDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
It is up to the application to record the notation for later reference, if necessary.
If a system identifier is present, and it is a URL, the SAX parser must resolve it fully before passing it to the application.
name
- The notation name.publicId
- The notation's public identifier, or null if
none was given.systemId
- The notation's system identifier, or null if
none was given.DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)
,
AttributeList
protected void enterDTD()
leaveDTD()
.protected java.lang.String leaveDTD()
protected void serializeNode(Node node)
serializeElement(org.w3c.dom.Element)
.node
- The node to serializeserializeElement(org.w3c.dom.Element)
protected org.apache.xml.serialize.ElementState content()
protected void characters(java.lang.String text, boolean unescaped)
text
- The text to printunescaped
- True is should print unescapedprotected abstract java.lang.String getEntityRef(char ch)
ch
- Character valueprotected abstract void serializeElement(Element elem)
elem
- The element to serializeprotected void serializePreRoot()
protected final void printText(java.lang.String text)
printSpace()
) all the accumulated text becomes one part and is
added to the accumulate line. When a line is long enough, it can
be broken at its text boundary.text
- The text to printprotected final void printText(char[] chars, int start, int end)
protected final void printText(java.lang.String text, boolean preserveSpace)
printText(String)
with a call to 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.text
- The text to printpreserveSpace
- Space preserving flagprotected final void printText(java.lang.StringBuffer text, boolean preserveSpace)
protected final void printSpace()
printText(java.lang.String)
will be added to the accumulated line, and a space
separator will be counted. If the line accumulated so far is
long enough, it will be printed.protected final void breakLine()
printSpace()
but
forcing the line to print and starting a new line (printSpace()
will only start a new line if the current line
is long enough).protected final void breakLine(boolean preserveSpace)
public void flush()
protected void indent()
protected void unindent()
protected void printDoctypeURL(java.lang.String url)
printText(java.lang.String)
.url
- The document type url to printprotected java.lang.String escape(java.lang.String source)
source
- The string to escapeprotected org.apache.xml.serialize.ElementState getElementState()
protected org.apache.xml.serialize.ElementState enterElementState(java.lang.String namespaceURI, java.lang.String localName, java.lang.String rawName, boolean preserveSpace)
protected org.apache.xml.serialize.ElementState leaveElementState()
protected java.lang.String getPrefix(java.lang.String namespaceURI)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |