wt.util.xml.io
Class DOMDocumentWriter

java.lang.Object
  wt.util.xml.io.DOMDocumentWriter

public class DOMDocumentWriter

extends Object

A class for writing DOM documents to writers as XML text.

Character Encoding

If an OutputStream is used to create the DOMDocumentWriter, the UTF-8 encoding will be used by default to write to it.

If the DOMDocumentWriter is created using a java.io.OutputStreamWriter, its encoding will be used in the XML declaration.

If a java.io.Writer that does not extend java.io.OutputStreamWriter is used, then UTF-8 encoding will be used.

Note that if you use a java.io.FileWriter, the default platform encoding will be used. On a US Windows machine this will likely be ISO-8859-1 or Windows Latin-1 (the default encoding is specified in the System property file.encoding). This may not be desirable for interoperability with Systems from other locales. As such you may want to explicitly specify an alternative encoding. Here are some examples of how to control the encoding.

Example of Asing an Alternative Encoding

This example shows how to write using the SHIFT_JIS encoding. Note that the Java version of the encoding must be used. The writer will map this to the MIME version of encoding string.

      FileOutputStream fos = new FileOutputStream(new File("foo.xml"));
      OutputStreamWriter w = new OutputStreamWriter(fos, "SJIS");
      DOMDocumentWriter writer = new DOMDocumentWriter(w);
      writer.write(doc);
      writer.close();
 

Example Using Default UTF-8 Encoding

You could explicitly specify UTF-8 encoding in the way that the example above does. You'd have to create the OutputStreamWriter using the Java encoding "UTF8". However, there is a simpler way.

If you create a DOMDocumentWriter with an OutputStream, then it will automatically encode the document using UTF-8 encoding. This form of the constructore is

      FileOutputStream stream = new FileOutputStream(new File("foo.xml"));
      DOMDocumentWriter writer = new DOMDocumentWriter(stream);
      writer.write(doc);
      writer.close();
 

Thread Safety

The writer can only be written to by one thread at a time. All write methods are synchronized to enforce this. Similarly, the indent string cannot be changed while the wirter is writing a Node.

DOCTYPES

The DOM level 1 API does not support "editing" of DOCTYPEs. Furthermore, the DocumentType node type does not support specification of external SYSTEM and PUBLIC DTD ids. So only in-document document type definitions will be output when writing a Document by default. If you want to specify a SYSTEM or PUBLIC external DTD, then use the overriden methods for write(Document) which allow you to specify the appropriate IDs.

Supported API: false

Extendable: false

Field Summary

private static String	CLASSNAME
private String	cummulativeIndentString
private String	dtdPublicId_
private String	dtdSystemId_
private String	encoding
private String	indentString
private static String	LINE_SEPARATOR
private static String	RESOURCE
private Writer	writer

Constructor Summary

DOMDocumentWriter(OutputStream stream)
Create and instance to write the document to the specified stream in UTF-8 encoding.

DOMDocumentWriter(Writer writer)
Create instance to write documents to the specified Writer.

Method Summary

void	close() Close the wrappered writer.
private void	descend(Node node, boolean perform_indent) For a specified node, increase the indent depth, then iterate over each child.
void	flush() Flush work written to the wrappered writer.
private void	indent()
private String	normalize(String s) Normalizes the string.
private void	printIndent()
void	setIndentString(String indent_string) Set the string that will be used for each indent level.
private Attr[]	sortAttributes(NamedNodeMap attrs) Sorts the attributes alphabetically.
private void	unindent()
void	write(CDATASection cdata) Write a CDATA node to the writer like <![CDATA[...]]>.
void	write(Comment comment) Write a comment in the format .
void	write(Document document) Write a document to the writer including the <?xml version=...?> tag.
void	write(DocumentFragment document_fragment) Write a DocumentFragment node to the writer.
void	write(Document document, String system_id) Write a document to the writer including the <?xml version=...?> tag.
void	write(Document document, String public_id, String system_id) Write a document to the writer including the <?xml version=...?> tag.
void	write(DocumentType document_type) Write a DOCTYPE node to the writer.
void	write(Element element) Write an element, its attrbutes, and its children to the writer.
void	write(Entity entity) Write an Entity node to the writer.
void	write(EntityReference entity_reference) Write an entity reference to the writer (e.g.
void	write(Node node) Write any type of node to the wrappered writer.
void	write(Notation notation) Write a Notation node to the writer.
void	write(ProcessingInstruction processing_instruction) Write a processing instruction to the writer (e.g.
void	write(Text text) Write a text node as escaped text to the writer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RESOURCE

private static final String RESOURCE

See Also:

Constant Field Values

CLASSNAME

private static final String CLASSNAME

writer

private Writer writer

encoding

private String encoding

cummulativeIndentString

private String cummulativeIndentString

indentString

private String indentString

dtdPublicId_

private String dtdPublicId_

dtdSystemId_

private String dtdSystemId_

LINE_SEPARATOR

private static final String LINE_SEPARATOR

Constructor Detail

DOMDocumentWriter

public DOMDocumentWriter(Writer writer)

Create instance to write documents to the specified Writer. If the writer is an instance of OutputStreamWriter, the writer's character encoding will be used in the XML document tag. Otherwise, a UTF-8 encoding will be used.

Supported API: false

Parameters:

writer - A writer to write to. Because it is an OutputStreamWriter, the document writer can ask it for its character encoding and include in in the <?xml ... tag of the written document. May not be null. If it is, an IllegalArgumentException will be issued.

DOMDocumentWriter

public DOMDocumentWriter(OutputStream stream)
                  throws UnsupportedEncodingException

Create and instance to write the document to the specified stream in UTF-8 encoding.

Supported API: false

Parameters:

stream -

Throws:

UnsupportedEncodingException

Method Detail

setIndentString

public void setIndentString(String indent_string)

Set the string that will be used for each indent level. By default the tab character is used.

Supported API: false

Parameters:

indent_string - May not be null. If it is, an IllegalArgumentException will be issued.

write

public void write(Node node)
           throws IOException

Write any type of node to the wrappered writer.

Supported API: false

Parameters:

node - The node to write. Must not be null. If it is an IllegalArgumentException will be issued.

Throws:

IOException

write

public void write(CDATASection cdata)
           throws IOException

Write a CDATA node to the writer like <![CDATA[...]]>. If the content of the CDATA contains the string ]]> the content will be split across multiple CDATA sections with part of the ] ending a CDATA section and ]> starting the next section.

Supported API: false

Parameters:

cdata - The CDATA section to be written.

Throws:

IOException

write

public void write(Comment comment)
           throws IOException

Write a comment in the format .

Supported API: false

Parameters:

comment - The comment node to render.

Throws:

IOException

write

public void write(Document document)
           throws IOException

Write a document to the writer including the <?xml version=...?> tag.

Supported API: false

Parameters:

document - The Document to be written.

Throws:

IOException

write

public void write(Document document,
                  String system_id)
           throws IOException

Write a document to the writer including the <?xml version=...?> tag. Specify the DTD as a SYSTEM DTD with the specified id.

Supported API: false

Parameters:

document -

system_id -

Throws:

IOException

write

public void write(Document document,
                  String public_id,
                  String system_id)
           throws IOException

Write a document to the writer including the <?xml version=...?> tag. Specify the DTD as a PUBLIC DTD with the specified public and system id.

Supported API: false

Parameters:

document -

public_id -

system_id -

Throws:

IOException

write

public void write(Element element)
           throws IOException

Write an element, its attrbutes, and its children to the writer.

Supported API: false

Parameters:

element - The Element to be written.

Throws:

IOException

write

public void write(EntityReference entity_reference)
           throws IOException

Write an entity reference to the writer (e.g. ).

Supported API: false

Parameters:

entity_reference - The EntityReference to be written.

Throws:

IOException

write

public void write(ProcessingInstruction processing_instruction)
           throws IOException

Write a processing instruction to the writer (e.g. <?pi ...?>).

Supported API: false

Parameters:

processing_instruction - The ProcessingInstruction to be written.

Throws:

IOException

write

public void write(Text text)
           throws IOException

Write a text node as escaped text to the writer.

Supported API: false

Parameters:

text - The Text node to be written.

Throws:

IOException

write

public void write(DocumentType document_type)
           throws IOException

Write a DOCTYPE node to the writer.

Supported API: false

Parameters:

document_type - The DocumentType node to be written.

Throws:

IOException

write

public void write(Entity entity)
           throws IOException

Write an Entity node to the writer.

Supported API: false

Parameters:

entity - The Entity node to be written.

Throws:

IOException

write

public void write(Notation notation)
           throws IOException

Write a Notation node to the writer.

Supported API: false

Parameters:

notation - The Notation node to be written.

Throws:

IOException

write

public void write(DocumentFragment document_fragment)
           throws IOException

Write a DocumentFragment node to the writer.

Supported API: false

Parameters:

document_fragment - The DocumentFragment node to be written.

Throws:

IOException

flush

public void flush()
           throws IOException

Flush work written to the wrappered writer.

Supported API: false

Throws:

IOException

close

public void close()
           throws IOException

Close the wrappered writer.

Supported API: false

Throws:

IOException

descend

private void descend(Node node,
                     boolean perform_indent)
              throws IOException

For a specified node, increase the indent depth, then iterate over each child.

Parameters:

node - The node to write out after indentation.

perform_indent - Whether or not to apply the indent. If false, no indentation will be done.

Throws:

IOException

indent

private void indent()

unindent

private void unindent()

normalize

private String normalize(String s)

Normalizes the string.

Parameters:

s -

Returns:

String

sortAttributes

private Attr[] sortAttributes(NamedNodeMap attrs)

Sorts the attributes alphabetically.

Parameters:

attrs -

Returns:

Attr[]

printIndent

private void printIndent()
                  throws IOException

Throws:

IOException