|
Xerces 1.0.1 | ||||||||
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.io.IOException |
_exception
Holds the exception thrown by the serializer. |
protected OutputFormat |
_format
The output format associated with this serializer. |
protected boolean |
_started
If the document has been started (header serialized), this flag is set to true so it's not started twice. |
Constructor Summary | |
protected |
BaseMarkupSerializer()
Protected constructor can only be used by derived class. |
Method Summary | |
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)
|
protected void |
breakLine()
Called to print a line consisting of the text accumulated so far. |
void |
characters(char[] chars,
int start,
int length)
Receive notification of character data. |
protected void |
characters(java.lang.String text,
boolean cdata,
boolean unescaped)
Called to print the text contents in the prevailing element format. |
void |
comment(char[] chars,
int start,
int length)
|
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)
|
void |
endCDATA()
|
void |
endDocument()
Called at the end of the document to wrap it up. |
void |
endDTD()
|
void |
endEntity(java.lang.String name)
|
protected void |
enterDTD()
Called by any of the DTD handlers to enter DTD mode. |
protected org.apache.xml.serialize.ElementState |
enterElementState(java.lang.String tagName,
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)
|
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. |
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)
|
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 |
startCDATA()
|
void |
startDTD(java.lang.String name,
java.lang.String publicId,
java.lang.String systemId)
|
void |
startEntity(java.lang.String name)
|
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.IOException _exception
protected boolean _started
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 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.DocumentHandler.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.DocumentHandler.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)
public void comment(java.lang.String text)
public void startCDATA()
public void endCDATA()
public void endDocument() throws SAXException
public void startEntity(java.lang.String name)
public void endEntity(java.lang.String name)
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 startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
public void endDTD()
public void elementDecl(java.lang.String name, java.lang.String model)
public void attributeDecl(java.lang.String eName, java.lang.String aName, java.lang.String type, java.lang.String valueDefault, java.lang.String value)
public void internalEntityDecl(java.lang.String name, java.lang.String value)
public void externalEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
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 cdata, boolean unescaped)
text
- The text to printcdata
- True is should print as CDATAunescaped
- 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).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 tagName, boolean preserveSpace)
protected org.apache.xml.serialize.ElementState leaveElementState()
|
Xerces 1.0.1 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |