LSSerializer provides an API for serializing (writing) a
* DOM document out into XML. The XML data is written to a string or an
* output stream. Any changes or fixups made during the serialization affect
* only the serialized data. The Document object and its
* children are never altered by the serialization operation.
* During serialization of XML data, namespace fixup is done as defined in
* [DOM Level 3 Core]
* , Appendix B. [DOM Level 2 Core]
* allows empty strings as a real namespace URI. If the
* namespaceURI of a Node is empty string, the
* serialization will treat them as null, ignoring the prefix
* if any.
*
LSSerializer accepts any node type for serialization. For
* nodes of type Document or Entity, well-formed
* XML will be created when possible (well-formedness is guaranteed if the
* document or entity comes from a parse operation and is unchanged since it
* was created). The serialized output for these node types is either as a
* XML document or an External XML Entity, respectively, and is acceptable
* input for an XML parser. For all other types of nodes the serialized form
* is implementation dependent.
*
Within a Document, DocumentFragment, or
* Entity being serialized, Nodes are processed as
* follows
*
Document nodes are written, including the XML
* declaration (unless the parameter "xml-declaration" is set to
* false) and a DTD subset, if one exists in the DOM. Writing a
* Document node serializes the entire document.
* Entity nodes, when written directly by
* LSSerializer.write, outputs the entity expansion but no
* namespace fixup is done. The resulting output will be valid as an
* external entity.
* true, EntityReference nodes are
* serialized as an entity reference of the form "
* &entityName;" in the output. Child nodes (the expansion)
* of the entity reference are ignored. If the parameter
* "entities"
* is set to false, only the children of the entity reference
* are serialized. EntityReference nodes with no children (no
* corresponding Entity node or the corresponding
* Entity nodes have no children) are always serialized.
* CDATAsections containing content characters that cannot be
* represented in the specified output encoding are handled according to the
* "split-cdata-sections"
* parameter. If the parameter is set to true,
* CDATAsections are split, and the unrepresentable characters
* are serialized as numeric character references in ordinary content. The
* exact position and number of splits is not specified. If the parameter
* is set to false, unrepresentable characters in a
* CDATAsection are reported as
* "wf-invalid-character" errors if the parameter
* "well-formed"
* is set to true. The error is not recoverable - there is no
* mechanism for supplying alternative characters and continuing with the
* serialization.
* DocumentFragment nodes are serialized by
* serializing the children of the document fragment in the order they
* appear in the document fragment.
* Note: The serialization of a Node does not always
* generate a well-formed XML document, i.e. a LSParser might
* throw fatal errors when parsing the resulting serialization.
*
Within the character data of a document (outside of markup), any * characters that cannot be represented directly are replaced with * character references. Occurrences of '<' and '&' are replaced by * the predefined entities < and &. The other predefined * entities (>, ', and ") might not be used, except * where needed (e.g. using > in cases such as ']]>'). Any * characters that cannot be represented directly in the output character * encoding are serialized as numeric character references (and since * character encoding standards commonly use hexadecimal representations of * characters, using the hexadecimal representation when serializing * character references is encouraged). *
To allow attribute values to contain both single and double quotes, the * apostrophe or single-quote character (') may be represented as * "'", and the double-quote character (") as """. New * line characters and other characters that cannot be represented directly * in attribute values in the output character encoding are serialized as a * numeric character reference. *
Within markup, but outside of attributes, any occurrence of a character
* that cannot be represented in the output character encoding is reported
* as a DOMError fatal error. An example would be serializing
* the element <LaCañada/> with encoding="us-ascii".
* This will result with a generation of a DOMError
* "wf-invalid-character-in-node-name" (as proposed in
* "well-formed").
*
When requested by setting the parameter
* "normalize-characters"
* on LSSerializer to true, character normalization is
* performed according to the definition of
* fully
* normalized characters included in appendix E of
* [XML 1.1] on all
* data to be serialized, both markup and character data. The character
* normalization process affects only the data as it is being written; it
* does not alter the DOM's view of the document after serialization has
* completed.
*
Implementations are required to support the encodings "UTF-8",
* "UTF-16", "UTF-16BE", and "UTF-16LE" to guarantee that data is
* serializable in all encodings that are required to be supported by all
* XML parsers. When the encoding is UTF-8, whether or not a byte order mark
* is serialized, or if the output is big-endian or little-endian, is
* implementation dependent. When the encoding is UTF-16, whether or not the
* output is big-endian or little-endian is implementation dependent, but a
* Byte Order Mark must be generated for non-character outputs, such as
* LSOutput.byteStream or LSOutput.systemId. If
* the Byte Order Mark is not generated, a "byte-order-mark-needed" warning
* is reported. When the encoding is UTF-16LE or UTF-16BE, the output is
* big-endian (UTF-16BE) or little-endian (UTF-16LE) and the Byte Order Mark
* is not be generated. In all cases, the encoding declaration, if
* generated, will correspond to the encoding used during the serialization
* (e.g. encoding="UTF-16" will appear if UTF-16 was
* requested).
*
Namespaces are fixed up during serialization, the serialization process * will verify that namespace declarations, namespace prefixes and the * namespace URI associated with elements and attributes are consistent. If * inconsistencies are found, the serialized form of the document will be * altered to remove them. The method used for doing the namespace fixup * while serializing a document is the algorithm defined in Appendix B.1, * "Namespace normalization", of * [DOM Level 3 Core] * . *
While serializing a document, the parameter "discard-default-content" * controls whether or not non-specified data is serialized. *
While serializing, errors and warnings are reported to the application
* through the error handler (LSSerializer.domConfig's
* "error-handler"
* parameter). This specification does in no way try to define all possible
* errors and warnings that can occur while serializing a DOM node, but some
* common error and warning cases are defined. The types (
* DOMError.type) of errors and warnings defined by this
* specification are:
*
"no-output-specified" [fatal]LSOutput if no output is specified in the
* LSOutput. "unbound-prefix-in-entity-reference" [fatal] true and an entity whose replacement text
* contains unbound namespace prefixes is referenced in a location where
* there are no bindings for the namespace prefixes. "unsupported-encoding" [fatal]In addition to raising the defined errors and warnings, implementations * are expected to raise implementation specific errors and warnings for any * other error and warning cases such as IO errors (file not found, * permission denied,...) and so on. *
See also the
*
Document Object Model (DOM) Level 3 Load and Save Specification.
*
* @since 1.5
*/
public interface LSSerializer {
/**
* The DOMConfiguration object used by the
* LSSerializer when serializing a DOM node.
*
In addition to the parameters recognized by the
* DOMConfiguration
* interface defined in
* [DOM Level 3 Core]
* , the DOMConfiguration objects for
* LSSerializer adds, or modifies, the following
* parameters:
*
"canonical-form"truetrue will set the parameters
* "format-pretty-print", "discard-default-content", and "xml-declaration
* ", to false. Setting one of those parameters to
* true will set this parameter to false.
* Serializing an XML 1.1 document when "canonical-form" is
* true will generate a fatal error. false"discard-default-content"trueAttr.specified attribute to decide what attributes
* should be discarded. Note that some implementations might use
* whatever information available to the implementation (i.e. XML
* schema, DTD, the Attr.specified attribute, and so on) to
* determine what attributes and content to discard if this parameter is
* set to true. false"format-pretty-print"truefalse"ignore-unknown-character-denormalizations" true"unknown-character-denormalization" warning (instead of
* raising an error, if this parameter is not set) and ignore any
* possible denormalizations caused by these characters. false"normalize-characters"DOMConfiguration in
* [DOM Level 3 Core]
* . Unlike in the Core, the default value for this parameter is
* true. While DOM implementations are not required to
* support fully
* normalizing the characters in the document according to appendix E of
* [XML 1.1], this
* parameter must be activated by default if supported. "xml-declaration"trueDocument,
* Element, or Entity
* node is serialized, the XML declaration, or text declaration, should
* be included. The version (Document.xmlVersion if the
* document is a Level 3 document and the version is non-null, otherwise
* use the value "1.0"), and the output encoding (see
* LSSerializer.write for details on how to find the output
* encoding) are specified in the serialized XML declaration. false"xml-declaration-needed" warning if this will cause
* problems (i.e. the serialized data is of an XML version other than
* [XML 1.0], or an
* encoding would be needed to be able to re-parse the serialized data). null will reset its
* value to the default value.
* null will reset its
* value to the default value.
* DOMConfiguration parameters have been applied. For
* example, CDATA sections won't be passed to the filter if
* "cdata-sections"
* is set to false.
*/
public LSSerializerFilter getFilter();
/**
* When the application provides a filter, the serializer will call out
* to the filter before serializing each Node. The filter implementation
* can choose to remove the node from the stream or to terminate the
* serialization early.
* DOMConfiguration parameters have been applied. For
* example, CDATA sections won't be passed to the filter if
* "cdata-sections"
* is set to false.
*/
public void setFilter(LSSerializerFilter filter);
/**
* Serialize the specified node as described above in the general
* description of the LSSerializer interface. The output is
* written to the supplied LSOutput.
* LSOutput, the encoding is found by
* looking at the encoding information that is reachable through the
* LSOutput and the item to be written (or its owner
* document) in this order:
* LSOutput.encoding,
* Document.inputEncoding,
* Document.xmlEncoding.
* LSOutput, a
* "no-output-specified" fatal error is raised.
* true if node was
* successfully serialized. Return false in case the
* normal processing stopped but the implementation kept serializing
* the document; the result of the serialization being implementation
* dependent then.
* @exception LSException
* SERIALIZE_ERR: Raised if the LSSerializer was unable to
* serialize the node. DOM applications should attach a
* DOMErrorHandler using the parameter
* "error-handler"
* if they wish to get details on the error.
*/
public boolean write(Node nodeArg,
LSOutput destination)
throws LSException;
/**
* A convenience method that acts as if LSSerializer.write
* was called with a LSOutput with no encoding specified
* and LSOutput.systemId set to the uri
* argument.
* @param nodeArg The node to serialize.
* @param uri The URI to write to.
* @return Returns true if node was
* successfully serialized. Return false in case the
* normal processing stopped but the implementation kept serializing
* the document; the result of the serialization being implementation
* dependent then.
* @exception LSException
* SERIALIZE_ERR: Raised if the LSSerializer was unable to
* serialize the node. DOM applications should attach a
* DOMErrorHandler using the parameter
* "error-handler"
* if they wish to get details on the error.
*/
public boolean writeToURI(Node nodeArg,
String uri)
throws LSException;
/**
* Serialize the specified node as described above in the general
* description of the LSSerializer interface. The output is
* written to a DOMString that is returned to the caller.
* The encoding used is the encoding of the DOMString type,
* i.e. UTF-16. Note that no Byte Order Mark is generated in a
* DOMString object.
* @param nodeArg The node to serialize.
* @return Returns the serialized data.
* @exception DOMException
* DOMSTRING_SIZE_ERR: Raised if the resulting string is too long to
* fit in a DOMString.
* @exception LSException
* SERIALIZE_ERR: Raised if the LSSerializer was unable to
* serialize the node. DOM applications should attach a
* DOMErrorHandler using the parameter
* "error-handler"
* if they wish to get details on the error.
*/
public String writeToString(Node nodeArg)
throws DOMException, LSException;
}