Java : Document (XML) - API使用例

Document (Java SE 22 & JDK 22) の使い方まとめです。
ほとんどのメソッドにサンプルコードがあります。
API仕様書のおともにどうぞ。

概要

Documentインタフェースは、HTML文書またはXML文書全体を表します。概念上は文書ツリーのルートであり、文書データに最初にアクセスする手段を提供します。

クラス構成

Documentクラスは、DOMノードツリーと、DocumentType や DOMConfiguration といった XML文書の設定類を持ちます。
また、Element や Text といった各種ノードの生成の役割も持ちます。

クラス構成

本記事のコード例では、利便性のために以下の printDocument メソッドを使います。

public void printDocument(Document document) throws TransformerException {
    final var transformer = TransformerFactory.newInstance().newTransformer();
    transformer.setOutputProperty(OutputKeys.INDENT, "yes");
    transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "yes");

    final var result = new StreamResult(new StringWriter());
    transformer.transform(new DOMSource(document), result);

    System.out.print(result.getWriter());
}

final var builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
final var document = builder.newDocument();

final var root = document.createElement("root");
System.out.println(root); // [root: null]

document.appendChild(root);

final var child = document.createElement("child");
System.out.println(child); // [child: null]

root.appendChild(child);

final var text = document.createTextNode("abcd");
System.out.println(text); // [#text: abcd]

child.appendChild(text);

//<root>
//    <child>abcd</child>
//</root>
printDocument(document);

Nodeで宣言されたフィールド

ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE

「Java API 使用例 : Node」をご参照ください。

メソッド

Node adoptNode (Node source)

ほかの文書のノードを現在の文書にインポートします。

ノードは移動されます。
つまり他の文書からは source が削除されます。

Attr createAttribute (String name)

所定の名前のAttrを作成します。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.newDocument();

final var root = document.createElement("root");
document.appendChild(root);

final var attrA = document.createAttribute("attr-a");
System.out.println(attrA); // attr-a=""

attrA.setValue("aaa");
System.out.println(attrA); // attr-a="aaa"

final var attrB = document.createAttribute("attr-b");
System.out.println(attrB); // attr-b=""

attrB.setValue("bbb");
System.out.println(attrB); // attr-b="bbb"

root.setAttributeNode(attrA);
root.setAttributeNode(attrB);

//<root attr-a="aaa" attr-b="bbb"/>
printDocument(document);

Attr createAttributeNS (String namespaceURI, String qualifiedName)

所定の修飾名と名前空間URIを持つ属性を作成します。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.newDocument();

final var root = document.createElementNS("http://example.com", "ns:root");
System.out.println(root); // [ns:root: null]

document.appendChild(root);

final var attrA = document.createAttributeNS("http://example.com", "ns:attr-a");
System.out.println(attrA); // ns:attr-a=""

attrA.setValue("aaa");
System.out.println(attrA); // ns:attr-a="aaa"

root.setAttributeNode(attrA);

//<ns:root xmlns:ns="http://example.com" ns:attr-a="aaa"/>
printDocument(document);

CDATASection createCDATASection (String data)

指定された文字列を値として持つCDATASectionノードを作成します。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.newDocument();

final var root = document.createElement("root");
document.appendChild(root);

final var cdataSection = document.createCDATASection("<?>");
System.out.println(cdataSection); // [#cdata-section: <?>]

root.appendChild(cdataSection);

//<root><![CDATA[<?>]]></root>
printDocument(document);

Comment createComment (String data)

指定された文字列を持つCommentノードを作成します。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.newDocument();

final var root = document.createElement("root");
document.appendChild(root);

final var commentA = document.createComment("aaa");
System.out.println(commentA); // [#comment: aaa]

root.appendChild(commentA);

//<root>
//    <!--aaa-->
//</root>
printDocument(document);

root.appendChild(document.createElement("child"));
root.appendChild(document.createComment("bbb"));

//<root>
//    <!--aaa-->
//    <child/>
//    <!--bbb-->
//</root>
printDocument(document);

DocumentFragment createDocumentFragment ()

空のDocumentFragmentオブジェクトを作成します。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.newDocument();

final var root = document.createElement("root");
document.appendChild(root);

final var documentFragment = document.createDocumentFragment();
System.out.println(documentFragment); // [#document-fragment: null]

documentFragment.appendChild(document.createElement("child-a"));
documentFragment.appendChild(document.createElement("child-b"));

root.appendChild(documentFragment);

//<root>
//    <child-a/>
//    <child-b/>
//</root>
printDocument(document);

Element createElement (String tagName)

指定された型の要素を作成します。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.newDocument();

final var root = document.createElement("root");
System.out.println(root); // [root: null]

document.appendChild(root);

root.appendChild(document.createElement("child-a"));
root.appendChild(document.createElement("child-b"));

//<root>
//    <child-a/>
//    <child-b/>
//</root>
printDocument(document);

Element createElementNS (String namespaceURI, String qualifiedName)

所定の修飾名と名前空間URIを持つ要素を作成します。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.newDocument();

final var root = document.createElementNS("http://example.com", "ns:root");
System.out.println(root); // [ns:root: null]

document.appendChild(root);

final var attrA = document.createAttributeNS("http://example.com", "ns:attr-a");
System.out.println(attrA); // ns:attr-a=""

attrA.setValue("aaa");
System.out.println(attrA); // ns:attr-a="aaa"

root.setAttributeNode(attrA);

//<ns:root xmlns:ns="http://example.com" ns:attr-a="aaa"/>
printDocument(document);

EntityReference createEntityReference (String name)

EntityReferenceオブジェクトを作成します。

final var xml = """
        <!DOCTYPE root [
            <!ENTITY aaa "bbb">
            <!ENTITY xxx "yyy">
        ]>
        <root/>
        """;

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

final var root = document.getDocumentElement();
System.out.println(root); // [root: null]

final var entityReferenceA = document.createEntityReference("aaa");
System.out.println(entityReferenceA); // [aaa: null]

root.appendChild(entityReferenceA);

final var entityReferenceX = document.createEntityReference("xxx");
System.out.println(entityReferenceX); // [xxx: null]

root.appendChild(entityReferenceX);

//<root/>
printDocument(document);

final var domImpl = builder.getDOMImplementation();
if (domImpl.getFeature("LS", "3.0") instanceof DOMImplementationLS ls) {
    final var serializer = ls.createLSSerializer();
    final var str = serializer.writeToString(document);

    //<?xml version="1.0" encoding="UTF-16"?><!DOCTYPE root [
    //<!ENTITY aaa 'bbb'>
    //<!ENTITY xxx 'yyy'>
    //]>
    //<root>&aaa;&xxx;</root>
    System.out.println(str);
}

ProcessingInstruction createProcessingInstruction (String target, String data)

指定された名前およびデータ文字列を使用してProcessingInstructionノードを作成します。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.newDocument();

final var root = document.createElement("root");
document.appendChild(root);

final var processingInstruction =
        document.createProcessingInstruction("target", "data");
System.out.println(processingInstruction); // [target: data]

root.appendChild(processingInstruction);

//<root>
//    <?target data?>
//</root>
printDocument(document);

Text createTextNode (String data)

指定された文字列を持つTextノードを作成します。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.newDocument();

final var root = document.createElement("root");
document.appendChild(root);

final var text = document.createTextNode("abcd");
System.out.println(text); // [#text: abcd]

root.appendChild(text);

//<root>abcd</root>
printDocument(document);

DocumentType getDoctype ()

この文書に関連付けられている文書型宣言(DocumentTypeを参照)。

final var dtd = Path.of("R:", "java-work", "sample.dtd");
System.out.println(dtd); // R:\java-work\sample.dtd

Files.writeString(dtd, """
        <!ENTITY aaa "bbb">
        <!ENTITY xxx "yyy">
        """);

final var xml = """
        <!DOCTYPE root SYSTEM "file:///R:/java-work/sample.dtd">
        <root/>
        """;

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

final var docType = document.getDoctype();

System.out.println(docType); // [root: null]
System.out.println(docType.getSystemId()); // file:///R:/java-work/sample.dtd

final var entities = docType.getEntities();
System.out.println("-- entities --");
for (int i = 0; i < entities.getLength(); i++) {
    System.out.println(entities.item(i));
}

// 結果
// ↓
//-- entities --
//[aaa: null]
//[xxx: null]

Element getDocumentElement ()

文書の文書要素になっている子ノードへの直接アクセスを可能にする便利な属性です。

final var xml = """
        <root>abcd</root>
        """;

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

final var root = document.getDocumentElement();
System.out.println(root); // [root: null]
System.out.println(root.getTextContent()); // abcd

String getDocumentURI ()

ドキュメントの場所。未定義の場合やDOMImplementation.createDocumentを使ってDocumentが作成された場合はnull。

final var path = Path.of("R:", "java-work", "sample.xml");
System.out.println(path); // R:\java-work\sample.xml

Files.writeString(path, """
        <root>abcd</root>
        """);

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.parse(path.toFile());

final var uri = document.getDocumentURI();
System.out.println(uri); // file:/R:/java-work/sample.xml

//<root>abcd</root>
printDocument(document);

DOMConfiguration getDomConfig ()

Document.normalizeDocument()が呼び出されたときに使用される構成。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.newDocument();

final var domConfig = document.getDomConfig();
final var names = domConfig.getParameterNames();

for (int i = 0; i < names.getLength(); i++) {
    final var name = names.item(i);
    final var param = domConfig.getParameter(name);
    System.out.println(name + " : " + param);
}

// 結果
// ↓
//comments : true
//datatype-normalization : false
//cdata-sections : true
//entities : true
//split-cdata-sections : true
//namespaces : true
//validate : false
//infoset : false
//normalize-characters : false
//canonical-form : false
//validate-if-schema : false
//check-character-normalization : false
//well-formed : true
//namespace-declarations : true
//element-content-whitespace : true
//error-handler : null
//schema-type : null
//schema-location : null
//resource-resolver : null
//http://apache.org/xml/properties/internal/entity-resolver : null
//http://apache.org/xml/properties/internal/grammar-pool : null
//http://apache.org/xml/properties/security-manager : jdk.xml.internal.XMLSecurityManager@3fc79729
//http://apache.org/xml/properties/internal/symbol-table : com.sun.org.apache.xerces.internal.util.SymbolTable@34f6515b
//http://apache.org/xml/features/validation/schema/augment-psvi : true

Element getElementById (String elementId)

所定の値のID属性を持つElementを返します。

final var xml = """
        <!DOCTYPE root [
          <!ATTLIST child id-x ID "ID-X">
        ]>
        <root>
            <child>AAA</child>
            <xxx>
                <child id-x="ID-X">BBB</child>
                <child>CCC</child>
            </xxx>
        </root>
        """;

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

final var child = document.getElementById("ID-X");
System.out.println(child); // [child: null]
System.out.println(child.getTextContent()); // BBB

final var nodes = document.getElementsByTagName("child");
System.out.println("-- nodes --");
for (int i = 0; i < nodes.getLength(); i++) {
    final var node = nodes.item(i);
    System.out.println(node + " : " + node.getTextContent());
}

// 結果
// ↓
//-- nodes --
//[child: null] : AAA
//[child: null] : BBB
//[child: null] : CCC

NodeList getElementsByTagName (String tagname)

文書内の、特定のタグ名を持つすべてのElementsを文書の順に格納するNodeListを返します。

final var xml = """
        <!DOCTYPE root [
          <!ATTLIST child id-x ID "ID-X">
        ]>
        <root>
            <child>AAA</child>
            <xxx>
                <child id-x="ID-X">BBB</child>
                <child>CCC</child>
            </xxx>
        </root>
        """;

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

final var child = document.getElementById("ID-X");
System.out.println(child); // [child: null]
System.out.println(child.getTextContent()); // BBB

final var nodes = document.getElementsByTagName("child");
System.out.println("-- nodes --");
for (int i = 0; i < nodes.getLength(); i++) {
    final var node = nodes.item(i);
    System.out.println(node + " : " + node.getTextContent());
}

// 結果
// ↓
//-- nodes --
//[child: null] : AAA
//[child: null] : BBB
//[child: null] : CCC

NodeList getElementsByTagNameNS (String namespaceURI, String localName)

特定のローカル名と名前空間URIを持つすべてのElementsを文書の順に格納するNodeListを返します。

final var xml = """
        <root xmlns:ns1="sample1" xmlns:ns2="sample2">
            <ns1:child>AAA</ns1:child>
            <ns2:child>BBB</ns2:child>
        </root>
        """;

final var factory = DocumentBuilderFactory.newNSInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

final var child1 = document.getElementsByTagNameNS("sample1", "child").item(0);
System.out.println(child1); // [ns1:child: null]
System.out.println(child1.getTextContent()); // AAA

final var child2 = document.getElementsByTagNameNS("sample2", "child").item(0);
System.out.println(child2); // [ns2:child: null]
System.out.println(child2.getTextContent()); // BBB

DOMImplementation getImplementation ()

この文書を処理するDOMImplementationオブジェクト。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.newDocument();

final var domImpl = document.getImplementation();
System.out.println(domImpl.hasFeature("LS", "3.0")); // true

final var ret = domImpl.getFeature("LS", "3.0") instanceof DOMImplementationLS;
System.out.println(ret); // true

String getInputEncoding ()

このドキュメントを解析するときに使用するエンコーディングを指定します。

final var xml = """
        <root>abcd</root>
        """;

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

System.out.println(document.getInputEncoding()); // UTF-8

boolean getStrictErrorChecking ()

エラー・チェックを適用するかどうかを指定します。

final var xml = """
        <root>abcd</root>
        """;

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

final var root = document.getDocumentElement();
System.out.println(root); // [root: null]

{
    System.out.println(document.getStrictErrorChecking()); // true

    try {
        document.createElement("<?>");
    } catch (DOMException e) {
        System.out.println(e);
    }

    // 結果
    // ↓
    //org.w3c.dom.DOMException: INVALID_CHARACTER_ERR:
    // 無効または不正なXML文字が指定されています。
}

document.setStrictErrorChecking(false);

{
    System.out.println(document.getStrictErrorChecking()); // false

    final var element = document.createElement("<?>");
    root.appendChild(element);

    //<root>
    //    abcd
    //    <<?>/>
    //</root>
    printDocument(document);
}

String getXmlEncoding ()

この文書のエンコーディングをXML宣言の一部として指定する属性。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

{
    final var xml = """
            <root/>
            """;

    final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

    System.out.println(document.getXmlEncoding()); // null
}
{
    final var xml = """
            <?xml version="1.0" encoding="UTF-8"?>
            <root/>
            """;

    final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

    System.out.println(document.getXmlEncoding()); // UTF-8
}
{
    final var xml = """
            <?xml version="1.0" encoding="Shift_JIS"?>
            <root/>
            """;

    final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

    System.out.println(document.getXmlEncoding()); // Shift_JIS
}

boolean getXmlStandalone ()

このドキュメントがスタンドアロンかどうかをXML宣言の一部として指定します。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();
final var transformer = TransformerFactory.newInstance().newTransformer();

final var xml = """
        <root/>
        """;

final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

System.out.println(document.getXmlStandalone()); // false

{
    final var result = new StreamResult(new StringWriter());
    transformer.transform(new DOMSource(document), result);

    //<?xml version="1.0" encoding="UTF-8" standalone="no"?><root/>
    System.out.println(result.getWriter());
}

document.setXmlStandalone(true);
System.out.println(document.getXmlStandalone()); // true

{
    final var result = new StreamResult(new StringWriter());
    transformer.transform(new DOMSource(document), result);

    //<?xml version="1.0" encoding="UTF-8"?><root/>
    System.out.println(result.getWriter());
}

String getXmlVersion ()

この文書のバージョン番号をXML宣言の一部として指定します。

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();
final var transformer = TransformerFactory.newInstance().newTransformer();

final var xml = """
        <root/>
        """;

final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

System.out.println(document.getXmlVersion()); // 1.0

{
    final var result = new StreamResult(new StringWriter());
    transformer.transform(new DOMSource(document), result);

    //<?xml version="1.0" encoding="UTF-8" standalone="no"?><root/>
    System.out.println(result.getWriter());
}

document.setXmlVersion("1.1");
System.out.println(document.getXmlVersion()); // 1.1

{
    final var result = new StreamResult(new StringWriter());
    transformer.transform(new DOMSource(document), result);

    //<?xml version="1.1" encoding="UTF-8" standalone="no"?><root/>
    System.out.println(result.getWriter());
}

Node importNode (Node importedNode, boolean deep)

別の文書から現在の文書へノードをインポートします。このとき、元の文書のソース・ノードが変更または削除されることはありません。このメソッドはソース・ノードの新しいコピーを作成します。

final var xml = """
        <root><child>abcd</child></root>
        """;

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var docA = builder.newDocument();
final var docB = builder.parse(new ByteArrayInputStream(xml.getBytes()));

System.out.println(docA.getDocumentElement()); // null

//<root>
//    <child>abcd</child>
//</root>
printDocument(docB);

// docBのノードをそのままdocAに追加しようとすると失敗します。
final var source = docB.getDocumentElement();

try {
    docA.appendChild(source);
} catch (DOMException e) {
    System.out.println(e);
}

// 結果
// ↓
//org.w3c.dom.DOMException: WRONG_DOCUMENT_ERR:
// ノードが、そのノードを作成したものとは異なるドキュメントで使用されています。

final var ret = docA.importNode(source, true);
System.out.println(ret); // [root: null]
System.out.println(docA.appendChild(ret)); // [root: null]

//<root>
//    <child>abcd</child>
//</root>
printDocument(docA);

//<root>
//    <child>abcd</child>
//</root>
printDocument(docB);

void normalizeDocument ()

このメソッドは、文書を通常の形式に変換して、保存およびロードするように動作します。

final var builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
final var document = builder.newDocument();

final var root = document.createElement("root");
document.appendChild(root);

// 意図的にTextノードを不必要に分割して作成します。
root.appendChild(document.createTextNode("aaa"));
root.appendChild(document.createTextNode("bbb"));

root.appendChild(document.createElement("child"));
root.appendChild(document.createTextNode(""));

{
    final var nodes = root.getChildNodes();
    System.out.println("-- nodes --");
    for (int i = 0; i < nodes.getLength(); i++) {
        System.out.println(nodes.item(i));
    }

    // 結果
    // ↓
    //-- nodes --
    //[#text: aaa]
    //[#text: bbb]
    //[child: null]
    //[#text: ]
}

// 結合可能なTextは結合されます。空のTextは削除されます。
document.normalizeDocument();

{
    final var nodes = root.getChildNodes();
    System.out.println("-- nodes --");
    for (int i = 0; i < nodes.getLength(); i++) {
        System.out.println(nodes.item(i));
    }

    // 結果
    // ↓
    //[#text: aaabbb]
    //[child: null]
}

Node renameNode (Node n, String namespaceURI, String qualifiedName)

ELEMENT_NODEまたはATTRIBUTE_NODE型の既存のノードを変更します。

final var xml = """
        <root><child-a>abcd</child-a></root>
        """;

final var factory = DocumentBuilderFactory.newInstance();
final var builder = factory.newDocumentBuilder();

final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

//<root>
//    <child-a>abcd</child-a>
//</root>
printDocument(document);

final var childA = document.getElementsByTagName("child-a").item(0);
System.out.println(childA); // [child-a: null]

final var ret = document.renameNode(childA, null, "child-z");
System.out.println(ret); // [child-z: null]

//<root>
//    <child-z>abcd</child-z>
//</root>
printDocument(document);

void setDocumentURI (String documentURI)