今回は XMLStreamWriter インターフェースに定義されている writeXxxx() メソッドを見ていきます(一部次回)。 これらは各種 XML ノードを書き出しますが、大まかに分類すると次のようになります:
- 文書
- writeStartDocument()
- writeEndDocument()
- 要素(次回)
- writeStartElement()
- writeEndElement()
- writeEmptyElement()
- 属性・名前空間(次回)
- writeAttribute()
- writeNamespace()
- writeDefaultNamespace()
- テキスト
- writeCharacters()
- writeCData()
- その他のノード
- writeComment()
- writeProcessingInstruction()
- writeEntityRef()
- writeDTD()
以下でそれぞれのメソッドを簡単に見ていきましょう。
文書
XML 文書の開始:writeStartDocument()
XML 文書の開始時に呼び出し、XML 宣言(<?xml version="1.0"?> など)を出力します。 以下の3つが定義されています:
void writeStartDocument(); // 「<?xml version="1.0" ?>」が出力される void writeStartDocument(String version); // 「<?xml version="《version》" ?>」が出力される void writeStartDocument(String encoding, String version); // 「<?xml version="《version》" encoding="《encoding》" ?>」が出力される
少し注意が必要なのは3つ目のメソッドでしょうか。
- エンコーディングとバージョンの、引数の順番と出力の順番が逆になっています(単なる定義ミス? あまりメリットは感じられませんが・・・)。
- 最初の引数にエンコーディング名を指定しても、実際に書き出すエンコーディングを設定できるわけではありません。 この引数は、あくまで「エンコーディング指定を書き出すかどうか」を指定するものです。 書き出しの時に使用するエンコーディングは、XMLStreamReader オブジェクトを生成する時などに指定されます。 もし実際のエンコーディングと引数に指定したエンコーディングが異なっていると、XMLStreamException が投げられます。
XML 文書の終了:writeEndDocument()
XML 文書の終了時に呼び出します。 通常は何も出力しませんが、閉じられていない要素があれば、終了タグを書き出します。
void writeEndDocument();
テキスト
void writeCharacters(String text); // 《text》の内容をエスケープして出力 void writeCharacters(char[] text, int start, int len); // writeCharacters(String.valueOf(text, start, len)); と同じ void writeCData(String data); // 「<![CDATA[《data》]]>」が出力される
少しややこしいのは、引数の文字列が「<」のようなエスケープを必要とする文字を含む場合でしょう。 以下に具体例を書いておきましょう:
XMLStreamWriter writer = ...; writer.writeCharacters("<"); // 「&lt;」が出力される writer.writeCData("<"); // 「<![CDATA[<]]>」が出力される
その他のノード
コメント
コメントを書き出します。
void writeComment(String data); // 「<!--《data》-->」が出力される
処理命令
処理命令を書き出します。
void writeProcessingInstruction(String target); // 「<?《target》?>」が出力される void writeProcessingInstruction(String target, String data); // 「<?《target》 《data》?>」が出力される
1つ目のメソッドは2つ目のメソッドの第2引数に空文字列 ("") を渡した場合とほとんど同じ(XML 文書としては同じ)ですが、スペースが1つ省略されます。
実体参照
実体参照を書き出します。
void writeEntityRef(String name); // 「&《name》;」が出力される
DTD
DTD を書き出します。 引数の文字列がそのまま出力されるようです。 したがって、<!DOCTYPE> のような宣言も書く必要があります。
void writeDTD(String dtd);