Class XMLWriter

Constructs this handler with System.out used to write SAX events using the UTF-8 encoding. Avoid using this except when you know it's safe to close System.out at the end of the document.

Constructs a handler which writes all input to the output stream in the UTF-8 encoding, and closes it when endDocument is called. (Yes it's annoying that this throws an exception -- but there's really no way around it, since it's barely possible a JDK may exist somewhere that doesn't know how to emit UTF-8.)

Constructs a handler which writes all input to the writer, and then closes the writer when the document ends. If an XML declaration is written onto the output, and this class can determine the name of the character encoding for this writer, that encoding name will be included in the XML declaration.

See the description of the constructor which takes an encoding name for imporant information about selection of encodings.

Constructs a handler which writes all input to the writer, and then closes the writer when the document ends. If an XML declaration is written onto the output, this class will use the specified encoding name in that declaration. If no encoding name is specified, no encoding name will be declared unless this class can otherwise determine the name of the character encoding for this writer.

At this time, only the UTF-8 ("UTF8") and UTF-16 ("Unicode") output encodings are fully lossless with respect to XML data. If you use any other encoding you risk having your data be silently mangled on output, as the standard Java character encoding subsystem silently maps non-encodable characters to a question mark ("?") and will not report such errors to applications.

For a few other encodings the risk can be reduced. If the writer is a java.io.OutputStreamWriter, and uses either the ISO-8859-1 ("8859_1", "ISO8859_1", etc) or US-ASCII ("ASCII") encodings, content which can't be encoded in those encodings will be written safely. Where relevant, the XHTML entity names will be used; otherwise, numeric character references will be emitted.

However, there remain a number of cases where substituting such entity or character references is not an option. Such references are not usable within a DTD, comment, PI, or CDATA section. Neither may they be used when element, attribute, entity, or notation names have the problematic characters.

Flushes the output stream. When this handler is used in long lived pipelines, it can be important to flush buffered state, for example so that it can reach the disk as part of a state checkpoint.

Returns value of flag controlling canonical output.

Returns true if the output will have no entity references; returns false (the default) otherwise.

Returns value of flag controlling pretty printing.

Returns true if the output attempts to echo the input following "transitional" XHTML rules and matching the "HTML Compatibility Guidelines" so that an HTML version 3 browser can read the output as HTML; returns false (the default) othewise.

Sets the output style to be canonicalized. Input events must meet requirements that are slightly more stringent than the basic well-formedness ones, and include:

• Namespace prefixes must not have been changed from those in the original document. (This may only be ensured by setting the SAX2 XMLReader namespace-prefixes feature flag; by default, it is cleared.)
• Redundant namespace declaration attributes have been removed. (If an ancestor element defines a namespace prefix and that declaration hasn't been overriden, an element must not redeclare it.)
• If comments are not to be included in the canonical output, they must first be removed from the input event stream; this Canonical XML with comments by default.
• If the input character encoding was not UCS-based, the character data must have been normalized using Unicode Normalization Form C. (UTF-8 and UTF-16 are UCS-based.)
• Attribute values must have been normalized, as is done by any conformant XML processor which processes all external parameter entities.
• Similarly, attribute value defaulting has been performed.

Note that fragments of XML documents, as specified by an XPath node set, may be canonicalized. In such cases, elements may need some fixup (for xml:* attributes and application-specific context).

Assigns the line ending style to be used on output.

Controls whether the output text contains references to entities (the default), or instead contains the expanded values of those entities.

Controls pretty-printing, which by default is not enabled (and currently is most useful for XHTML output). Pretty printing enables structural indentation, sorting of attributes by name, line wrapping, and potentially other mechanisms for making output more or less readable.

At this writing, structural indentation and line wrapping are enabled when pretty printing is enabled and the xml:space attribute has the value default (its other legal value is preserve, as defined in the XML specification). The three XHTML element types which use another value are recognized by their names (namespaces are ignored).

Also, for the record, the "pretty" aspect of printing here is more to provide basic structure on outputs that would otherwise risk being a single long line of text. For now, expect the structure to be ragged ... unless you'd like to submit a patch to make this be more strictly formatted!

Resets the handler to write a new text document.

Controls whether the output should attempt to follow the "transitional" XHTML rules so that it meets the "HTML Compatibility Guidelines" appendix in the XHTML specification. A "transitional" Document Type Declaration (DTD) is placed near the beginning of the output document, instead of whatever DTD would otherwise have been placed there, and XHTML empty elements are printed specially. When writing text in US-ASCII or ISO-8859-1 encodings, the predefined XHTML internal entity names are used (in preference to character references) when writing content characters which can't be expressed in those encodings.

When this option is enabled, it is the caller's responsibility to ensure that the input is otherwise valid as XHTML. Things to be careful of in all cases, as described in the appendix referenced above, include:

• Element and attribute names must be in lower case, both in the document and in any CSS style sheet.
• All XML constructs must be valid as defined by the XHTML "transitional" DTD (including all familiar constructs, even deprecated ones).
• The root element must be "html".
• Elements that must be empty (such as <br> must have no content.
• Use both lang and xml:lang attributes when specifying language.
• Similarly, use both id and name attributes when defining elements that may be referred to through URI fragment identifiers ... and make sure that the value is a legal NMTOKEN, since not all such HTML 4.0 identifiers are valid in XML.
• Be careful with character encodings; make sure you provide a <meta http-equiv="Content-type" content="text/xml;charset=..." /> element in the HTML "head" element, naming the same encoding used to create this handler. Also, if that encoding is anything other than US-ASCII, make sure that if the document is given a MIME content type, it has a charset=... attribute with that encoding.

Additionally, some of the oldest browsers have additional quirks, to address with guidelines such as:

• Processing instructions may be rendered, so avoid them. (Similarly for an XML declaration.)
• Embedded style sheets and scripts should not contain XML markup delimiters: &, <, and ]]> are trouble.
• Attribute values should not have line breaks or multiple consecutive white space characters.
• Use no more than one of the deprecated (transitional) <isindex> elements.
• Some boolean attributes (such as compact, checked, disabled, readonly, selected, and more) confuse some browsers, since they only understand minimized versions which are illegal in XML.

Also, some characteristics of the resulting output may be a function of whether the document is later given a MIME content type of text/html rather than one indicating XML (application/xml or text/xml). Worse, some browsers ignore MIME content types and prefer to rely URI name suffixes -- so an "index.xml" could always be XML, never XHTML, no matter its MIME type.