org.w3c.dom
インタフェース Document

すべてのスーパーインタフェース:

Node

public interface Document

extends Node

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

要素、テキストノード、コメント、処理命令などのオブジェクトは、Document のコンテキスト外では存在し得ません。このため、Document インタフェースには、これらのオブジェクトを作成するために必要なファクトリメソッドが含まれています。作成された Node オブジェクトは、その作成コンテキスト内で自身と Document を関連付ける ownerDocument 属性を持っています。

「Document Object Model (DOM) Level 2 Core Specification」を参照してください。

フィールドの概要

インタフェース org.w3c.dom.Node から継承したフィールド

ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE

メソッドの概要

Attr	createAttribute(String name) 所定の名前の Attr を作成します。
Attr	createAttributeNS(String namespaceURI, String qualifiedName) 所定の修飾名とネームスペース URI を持つ属性を作成します。
CDATASection	createCDATASection(String data) 指定された文字列を値として持つ CDATASection ノードを作成します。
Comment	createComment(String data) 指定された文字列を持つ Comment ノードを作成します。
DocumentFragment	createDocumentFragment() 空の DocumentFragment オブジェクトを生成します。
Element	createElement(String tagName) 指定された型の要素を作成します。
Element	createElementNS(String namespaceURI, String qualifiedName) 所定の修飾名とネームスペース URI を持つ要素を作成します。
EntityReference	createEntityReference(String name) EntityReference オブジェクトを作成します。
ProcessingInstruction	createProcessingInstruction(String target, String data) 指定された名前およびデータを持つ ProcessingInstruction ノードを作成します。
Text	createTextNode(String data) 指定された文字列を持つ Text ノードを作成します。
DocumentType	getDoctype() この文書に関連付けられた文書タイプ宣言です (DocumentType を参照)。
Element	getDocumentElement() 文書のルート要素になっている子ノードへの直接アクセスを可能にする便利な属性です。
Element	getElementById(String elementId) elementId から与えられた ID を持つ Element を返します。
NodeList	getElementsByTagName(String tagname) 所定のタグ名とともに、すべての Elements の NodeList を返します。
NodeList	getElementsByTagNameNS(String namespaceURI, String localName) 所定のローカル名およびネームスペース URI とともに、すべての Elements の NodeList を返します。
DOMImplementation	getImplementation() この文書を処理する DOMImplementation オブジェクトです。
Node	importNode(Node importedNode, boolean deep) その他の文書から現在の文書へノードをインポートします。

インタフェース org.w3c.dom.Node から継承したメソッド

appendChild, cloneNode, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, hasAttributes, hasChildNodes, insertBefore, isSupported, normalize, removeChild, replaceChild, setNodeValue, setPrefix

メソッドの詳細

getDoctype

public DocumentType getDoctype()

この文書に関連付けられた文書タイプ宣言です (DocumentType を参照)。文書タイプ宣言のない XML 文書および HTML 文書に対しては null を返します。DOM レベル 2 では、文書タイプ宣言の変更はサポートされていません。いかなる方法によっても、docType を変更することはできません。たとえば、Node インタフェースから継承されたメソッド (insertNode、removeNode など) を使用する方法も許可されていません。

getImplementation

public DOMImplementation getImplementation()

この文書を処理する DOMImplementation オブジェクトです。DOM アプリケーションは、複数の実装のオブジェクトを使用できます。

getDocumentElement

public Element getDocumentElement()

文書のルート要素になっている子ノードへの直接アクセスを可能にする便利な属性です。HTML 文書の場合、「HTML」という tagName を持つ要素がこれに該当します。

createElement

public Element createElement(String tagName)
                      throws DOMException

指定された型の要素を作成します。返されるインスタンスは Element インタフェースを実装するため、属性は返されるオブジェクトに直接指定できます。
デフォルト値を持つ既知の属性が存在する場合は、これらを表す Attr ノードが自動的に作成され、要素に付加されます。
修飾名とネームスペース URI を持つ要素を作成するには、createElementNS メソッドを使用します。

パラメータ:

tagName - インスタンス化する要素型の名前。XML の場合、アルファベットの大文字と小文字が区別される。このような区別は、HTML の tagName パラメータには適用されない。ただし、DOM 実装はこのパラメータを大文字 (標準仕様) でマッピングする

戻り値:

tagName に設定された nodeName 属性、localName、prefix、null に設定された namespaceURI を持つ新しい Element オブジェクト

例外:

DOMException - INVALID_CHARACTER_ERR: 指定された名前に不正な文字が含まれている場合

createDocumentFragment

public DocumentFragment createDocumentFragment()

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

戻り値:

新しい DocumentFragment

createTextNode

public Text createTextNode(String data)

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

パラメータ:

data - ノードのデータ

戻り値:

新しい Text オブジェクト

createComment

public Comment createComment(String data)

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

パラメータ:

data - ノードのデータ

戻り値:

新しい Comment オブジェクト

createCDATASection

public CDATASection createCDATASection(String data)
                                throws DOMException

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

パラメータ:

data - CDATASection に含まれるデータ

戻り値:

新しい CDATASection オブジェクト

例外:

DOMException - NOT_SUPPORTED_ERR: この文書が HTML 文書の場合

createProcessingInstruction

public ProcessingInstruction createProcessingInstruction(String target,
                                                         String data)
                                                  throws DOMException

指定された名前およびデータを持つ ProcessingInstruction ノードを作成します。

パラメータ:

target - 処理命令のターゲット部分

data - ノードのデータ

戻り値:

新しい ProcessingInstruction オブジェクト

例外:

DOMException - INVALID_CHARACTER_ERR: 指定されたターゲットに不正な文字が含まれている場合
NOT_SUPPORTED_ERR: この文書が HTML 文書の場合

createAttribute

public Attr createAttribute(String name)
                     throws DOMException

所定の名前の Attr を作成します。その後、この Attr インスタンスは、setAttributeNode メソッドにより Element に設定されます。
修飾名とネームスペース URI を持つ属性を作成するには、createAttributeNS メソッドを使用します。

パラメータ:

name - 属性の名前

戻り値:

name に設定された nodeName 属性、localName、prefix、null に設定された namespaceURI を持つ新しい Attr オブジェクト

例外:

DOMException - INVALID_CHARACTER_ERR: 指定された名前に不正な文字が含まれている場合

createEntityReference

public EntityReference createEntityReference(String name)
                                      throws DOMException

EntityReference オブジェクトを作成します。さらに、参照されるエンティティが既知の場合は、Entity ノードの子リストが作成されるのと同じように、EntityReference ノードの子リストが作成されます。Entity ノードの子孫がバインドされていないネームスペース修飾子を持っている場合、作成された EntityReference ノードの対応する子孫もバインドされていません (namespaceURI が null)。DOM レベル 2 では、ネームスペース修飾子を解決するメカニズムはサポートされていません。

パラメータ:

name - 参照されるエンティティの名前

戻り値:

新しい EntityReference オブジェクト

例外:

DOMException - INVALID_CHARACTER_ERR: 指定された名前に不正な文字が含まれている場合
NOT_SUPPORTED_ERR: この文書が HTML 文書の場合

getElementsByTagName

public NodeList getElementsByTagName(String tagname)

所定のタグ名とともに、すべての Elements の NodeList を返します。返される順番は、Document ツリーの先行順 (preorder traversal) で検出された順番になります。

パラメータ:

tagname - 一致するタグの名前。特殊な値 "*" はすべてのタグに一致する

戻り値:

一致するすべての Elements を含む新しい NodeList オブジェクト

importNode

public Node importNode(Node importedNode,
                       boolean deep)
                throws DOMException

その他の文書から現在の文書へノードをインポートします。返されるノードは親ノードを持ちません (parentNode が null)。このメソッドはソースコードの新しいコピーを作成するだけです。元の文書のソースノードが変更または削除されることはありません。
どのノードをインポートしても、インポート側の文書を所有元とするノードオブジェクトが作成されます。このオブジェクトは、ソースノードの nodeName および nodeType とまったく同じ属性値に加えて、ネームスペース関連属性 (prefix、localName、namespaceURI) を持っています。Node に対する cloneNode 操作の場合と同じく、ソースノードは変更されません。
追加情報は適切な方法で nodeType にコピーされます。XML ソースまたは HTML ソースのフラグメントが一方の文書からもう一方の文書にコピーされた場合、2 つの文書が XML ケース内に異なった DTD を持つ可能性があることを受けて、適切な動作のミラー化が試行されます。以下では、各ノード型の特性を解説します。

ATTRIBUTE_NODE

生成された Attr 上で、ownerElement 属性は null、specified フラグは true に設定されます。ソースである Attr の子孫の再帰的インポートと結果ノードの再アセンブルにより、対応するサブツリーが形成されます。なお、deep パラメータは Attr ノードに影響を及ぼしません。これらのパラメータは、子とともにインポートされます。

DOCUMENT_FRAGMENT_NODE

deep オプションが true に設定されている場合、ソース要素の子孫の再帰的インポートと結果ノードの再アセンブルにより、対応するサブツリーが形成されます。それ以外の場合は、空の DocumentFragment が生成されるだけです。

DOCUMENT_NODE

Document ノードはインポートできません。

DOCUMENT_TYPE_NODE

DocumentType ノードはインポートできません。

ELEMENT_NODE

ソース要素の指定された属性ノードがインポートされ、生成された Attr ノードが同じく生成された Element に追加されます。インポートされる文書がこの要素名のデフォルト属性 (割り当て済み) を定義する場合も、デフォルト属性はコピーされません。importNode の deep パラメータが true に設定されている場合は、ソース要素の子孫が再帰的にインポートされ、結果ノードが再アセンブルされて、対応するサブツリーを形成します。

ENTITY_NODE

DOM の最新リリースである DocumentType は読み取り専用ですが、Entity ノードはインポート可能です。こうしてインポートされたノードを DocumentType に追加する機能は、将来の DOM のリリースで追加される予定です。インポート時には、publicId、systemId、notationName の各属性がコピーされます。deep のインポートが要求された場合は、Entity (ソース) の子孫が再帰的にインポートされ、結果ノードが再アセンブルされて、対応するサブツリーを形成します。

ENTITY_REFERENCE_NODE

deep のインポートが要求された場合も、ソース文書とディスティネーション文書でエンティティの定義が異なる場合があるので、EntityReference だけがコピーされることになります。インポートされる文書がこのエントリ名を定義する場合は、その値が割り当てられます。

NOTATION_NODE

DOM の最新リリースである DocumentType は読み取り専用ですが、Notation ノードはインポート可能です。こうしてインポートされたノードを DocumentType に追加する機能は、将来の DOM のリリースで追加される予定です。インポート時には、publicId 属性と systemId 属性がコピーされます。子を持つことがない deep パラメータは、Notation ノードに対して何の影響も及ぼしません。

PROCESSING_INSTRUCTION_NODE

インポートされたノードは、ソースノードから target と data の値をコピーします。

TEXT_NODE、CDATA_SECTION_NODE、COMMENT_NODE

CharacterData を継承する 3 つのノード型です。自身の data 属性と length 属性をソースノードからコピーします。

パラメータ:

importedNode - インポートされるノード

deep - true の場合は指定されたノードのサブツリーをインポートし、false の場合は指定されたノードだけをインポートする (上記の説明を参照)。Attr、EntityReference、Notation の各ノードには影響を及ぼさない

戻り値:

この Document に所属する、インポートされたノード

例外:

DOMException - NOT_SUPPORTED_ERR: インポートされるノード型がサポート対象外の場合

導入されたバージョン:

DOM Level 2

createElementNS

public Element createElementNS(String namespaceURI,
                               String qualifiedName)
                        throws DOMException

所定の修飾名とネームスペース URI を持つ要素を作成します。

パラメータ:

namespaceURI - 作成する要素のネームスペース URI

qualifiedName - インスタンス化する要素型の修飾名

戻り値:

以下の属性を持つ新しい Element オブジェクト:

属性	値
Node.nodeName	qualifiedName
Node.namespaceURI	namespaceURI
Node.prefix	qualifiedName から抽出された前置修飾子。前置修飾子が存在しない場合は null
Node.localName	qualifiedNameから抽出されたローカル名
Element.tagName	qualifiedName

例外:

DOMException - INVALID_CHARACTER_ERR: 指定された修飾名に XML 1.0 仕様に定められている不正な文字が含まれている場合
NAMESPACE_ERR: qualifiedName が XML 仕様のネームスペースの定義に沿ったものでない場合。qualifiedName が前置修飾子を持ち、namespaceURI が null の場合。qualifiedName が前置修飾子 "xml" を持ち、namespaceURI が "http://www.w3.org/XML/1998/namespace" 以外である場合
NOT_SUPPORTED_ERR: 現在の文書が "XML" をサポートしない場合 (ネームスペースは XML によって定義されている)

導入されたバージョン:

DOM Level 2

createAttributeNS

public Attr createAttributeNS(String namespaceURI,
                              String qualifiedName)
                       throws DOMException

所定の修飾名とネームスペース URI を持つ属性を作成します。

パラメータ:

namespaceURI - 作成する属性のネームスペース URI

qualifiedName - インスタンス化する属性の修飾名

戻り値:

以下の属性を持つ新しい Attr オブジェクト: qualifiedNameNode.namespaceURI

例外:

DOMException - INVALID_CHARACTER_ERR: 指定された修飾名に XML 1.0 仕様に定められている不正な文字が含まれている場合
NAMESPACE_ERR: qualifiedName が XML 仕様のネームスペースの定義に沿ったものでない場合。qualifiedName が前置修飾子を持ち、namespaceURI が null の場合。qualifiedName が前置修飾子 "xml" を持ち、namespaceURI が "http://www.w3.org/2000/xmlns/ 以外である場合。qualifiedName またはその前置修飾子が "xmlns" であり、namespaceURI が "http://www.w3.org/2000/xmlns/" 以外である場合
NOT_SUPPORTED_ERR: 現在の文書が "XML" をサポートしない場合 (ネームスペースは XML によって定義されている)

導入されたバージョン:

DOM Level 2

getElementsByTagNameNS

public NodeList getElementsByTagNameNS(String namespaceURI,
                                       String localName)

所定のローカル名およびネームスペース URI とともに、すべての Elements の NodeList を返します。返される順番は、Document ツリーの先行順 (preorder traversal) で検出された順番になります。

パラメータ:

namespaceURI - 一致する要素のネームスペース URI。特殊な値 "*" はすべてのネームスペースに一致する

localName - 一致する要素のローカル名。特殊な値 "*" はすべてのローカル名に一致する

戻り値:

一致するすべての Elements を含む新しい NodeList オブジェクト

導入されたバージョン:

DOM Level 2

getElementById

public Element getElementById(String elementId)

elementId から与えられた ID を持つ Element を返します。このような要素が存在しない場合は null を返します。複数の要素がこの ID を持っている場合の動作は未定義です。DOM 実装は、どの属性が ID 型の属性なのかを特定できなければなりません。"ID" という名前を持っていても、そのように定義されていなければ、ID 型の属性ではありません。どの属性が ID 型の属性なのかを特定できない場合、実装は null を返します。

パラメータ:

elementId - 要素の一意の id 値

戻り値:

一致する要素

導入されたバージョン:

DOM Level 2