|
JavaTM Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
public interface Document
Document
接口表示整个 HTML 或 XML 文档。从概念上讲,它是文档树的根,并提供对文档数据的基本访问。
因为元素、文本节点、注释、处理指令等不能存在于 Document
的上下文之外,所以 Document
接口还包含所需的创建这些对象的工厂方法。所创建的 Node
对象具有 ownerDocument
属性,该属性将 Node
对象与创建这些对象时的上下文所属的 Document
关联起来。
另请参见 Document Object Model (DOM) Level 3 Core Specification。
字段摘要 |
---|
方法摘要 | |
---|---|
Node |
adoptNode(Node source) 试图把另一文档中的节点采用到此文档。 |
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() 这是一种便捷属性,该属性允许直接访问文档的文档元素的子节点。 |
String |
getDocumentURI() 文档的位置,如果未定义或 Document 是使用 DOMImplementation.createDocument 创建的,则为 null 。 |
DOMConfiguration |
getDomConfig() 调用 Document.normalizeDocument() 时使用的配置。 |
Element |
getElementById(String elementId) 返回具有带给定值的 ID 属性的 Element 。 |
NodeList |
getElementsByTagName(String tagname) 按文档顺序返回包含在文档中且具有给定标记名称的所有 Element 的 NodeList 。 |
NodeList |
getElementsByTagNameNS(String namespaceURI, String localName) 以文档顺序返回具有给定本地名称和名称空间 URI 的所有 Elements 的 NodeList 。 |
DOMImplementation |
getImplementation() 处理此文档的 DOMImplementation 对象。 |
String |
getInputEncoding() 指定解析时此文档使用的编码的属性。 |
boolean |
getStrictErrorChecking() 指定是否强制执行错误检查的属性。 |
String |
getXmlEncoding() 作为 XML 声明的一部分,指定此文档编码的属性。 |
boolean |
getXmlStandalone() 作为 XML 声明的一部分,指定此文档是否为独立文档的属性。 |
String |
getXmlVersion() 作为 XML 声明 的一部分指定此文档版本号的属性。 |
Node |
importNode(Node importedNode, boolean deep) 从另一文档向此文档导入节点,而不改变或移除原始文档中的源节点;此方法创建源节点的一个新副本。 |
void |
normalizeDocument() 此方法的行为如同使文档通过一个保存和加载的过程,而将其置为 "normal(标准)" 形式。 |
Node |
renameNode(Node n, String namespaceURI, String qualifiedName) 重命名 ELEMENT_NODE 或 ATTRIBUTE_NODE 类型的现有节点。 |
void |
setDocumentURI(String documentURI) 文档的位置,如果未定义或 Document 是使用 DOMImplementation.createDocument 创建的,则为 null 。 |
void |
setStrictErrorChecking(boolean strictErrorChecking) 指定是否强制执行错误检查的属性。 |
void |
setXmlStandalone(boolean xmlStandalone) 作为 XML 声明 的一部分指定此文档是否是单独的的属性。 |
void |
setXmlVersion(String xmlVersion) 作为 XML 声明 的一部分指定此文档版本号的属性。 |
方法详细信息 |
---|
DocumentType getDoctype()
DocumentType
)。对于没有文档类型声明的 XML 文档,此方法返回
null
。对于 HTML 文档,可以返回
DocumentType
对象,与 HTML 文档中是否有文档类型声明无关。
Document
的子节点
DocumentType
节点的直接访问。此节点可以在文档创建时设置,以后可以通过使用子节点操作方法(如
Node.insertBefore
或
Node.replaceChild
)进行更改。不过要注意的是,根据创建时指定的
DocumentType
,在有些实现可以实例化不同类型的
Document
对象(支持 "Core" 之外的其他功能,如 "HTML" [
DOM Level 2 HTML])时,以后对它的更改很可能会导致所支持功能的不可更改。
DOMImplementation getImplementation()
DOMImplementation
对象。DOM 应用程序可以使用多个实现中的对象。
Element getDocumentElement()
Element createElement(String tagName) throws DOMException
Element
接口,所以可以直接在返回的对象上指定属性。
Attr
节点,并将其连接到该元素。
createElementNS
方法。
tagName
- 要实例化的元素类型名称。对于 XML,tagName 参数是区分大小写的;而对于其他文档,则取决于所使用标记语言的大小写敏感性。在该情况下,可通过 DOM 实现将该名称映射到该标记的规范形式。
Element
对象,该对象具有设置为
tagName
的
nodeName
属性以及设置为
null
的
localName
、
prefix
和
namespaceURI
。
DOMException
- INVALID_CHARACTER_ERR:如果指定的名称是不遵循所使用的 XML 版本(在
Document.xmlVersion
属性中指定)的 XML 名称,则引发此异常。
DocumentFragment createDocumentFragment()
DocumentFragment
对象。
DocumentFragment
。
Text createTextNode(String data)
Text
节点。
data
- 该节点的数据。
Text
对象。
Comment createComment(String data)
Comment
节点。
data
- 该节点的数据。
Comment
对象。
CDATASection createCDATASection(String data) throws DOMException
CDATASection
节点。
data
-
CDATASection
内容的数据。
CDATASection
对象。
DOMException
- NOT_SUPPORTED_ERR:如果此文档为 HTML 文档,则引发该异常。
ProcessingInstruction createProcessingInstruction(String target, String data) throws DOMException
ProcessingInstruction
节点。
target
- 处理指令的目标部分。与
Document.createElementNS
或
Document.createAttributeNS
不同,此方法不检查目标名称是否为格式良好的名称空间。为了确保目标名称是格式良好的名称空间,应用程序应该使用设置为
true
的参数 "namespaces" 调用
Document.normalizeDocument()
。
data
- 该节点的数据。
ProcessingInstruction
对象。
DOMException
- INVALID_CHARACTER_ERR:如果指定的目标是不遵循在
Document.xmlVersion
属性中指定的使用中的 XML 版本的 XML 名称,则引发此异常。
Attr createAttribute(String name) throws DOMException
Attr
。注意,然后可以使用
setAttributeNode
方法在
Element
上设置
Attr
。
createAttributeNS
方法。
name
- 属性名称。
Attr
对象,该对象具有设置为
name
的
nodeName
属性以及设置为
null
的
localName
、
prefix
和
namespaceURI
。该属性的值为空字符串。
DOMException
- INVALID_CHARACTER_ERR:如果指定的名称是不遵循在
Document.xmlVersion
属性中指定的使用中的 XML 版本的 XML 名称,则引发此异常。
EntityReference createEntityReference(String name) throws DOMException
EntityReference
对象。此外,如果引用的实体是已知的,则使
EntityReference
节点的子列表与相应
Entity
节点的子列表相同。
注: 如果任何 Entity
节点的后代具有未绑定的名称空间前缀,则相应的所创建的 EntityReference
节点的后代也未绑定;(其 namespaceURI
为 null
)。DOM Level 2 和 3 不支持在此情况下解析名称空间前缀的任何机制。
name
- 要引用的实体的名称。与
Document.createElementNS
或
Document.createAttributeNS
不同,不在实体名称上检查名称空间是否为格式良好的。为了确保实体名称是格式良好的名称空间,应用程序应该使用设置为
true
的参数 "namespaces" 调用
Document.normalizeDocument()
。
EntityReference
对象。
DOMException
- INVALID_CHARACTER_ERR:如果指定的名称是不遵循在
Document.xmlVersion
属性中指定的使用中的 XML 版本的 XML 名称,则引发此异常。
NodeList getElementsByTagName(String tagname)
Element
的
NodeList
。
tagname
- 要匹配的标记的名称。特殊值 "*" 匹配所有标记。对于 XML ,
tagname
参数是区分大小写的,否则它将依靠正在使用的标记语言的大小写敏感性。
Elements
的新
NodeList
对象。
Node importNode(Node importedNode, boolean deep) throws DOMException
parentNode
为
null
)。
nodeName
和
nodeType
,加上与名称空间相关的属性(
prefix
、
localName
和
namespaceURI
)。与在
cloneNode
操作中一样,源节点没有改变。与导入的节点相关的用户数据不可继续使用。不过,如果随相关数据一起指定了任何
UserDataHandlers
,则将在此方法返回之前用适当的参数调用这些处理程序。
nodeType
复制,在从一个文档向另一文档复制 XML 或 HTML 源的分段时试图镜像所需的行为,并认识到两个方法可以在 XML 实例中具有不同的 DTD。下表描述了每种类型节点的细节。
Attr
上,将
ownerElement
属性设置为
null
并将
specified
标志设置为
true
。递归地导入源
Attr
的后代,并且重新集合得到的节点来构造相应的子树。注意,
deep
参数对
Attr
节点无效;它们总是在导入时带着子节点。
deep
选项设置为
true
,则递归地导入源
DocumentFragment
的后代,并在导入的
DocumentFragment
下重新集合得到的节点以构造相应的子树。否则,此操作仅生成一个空
DocumentFragment
。
Document
节点。
DocumentType
节点。
Attr
节点连接到生成的
Element
。默认属性是
不 被复制的,不过,如果被导入的文档定义了此元素名称的默认属性,则分配这些属性。如果将
importNode
deep
参数设置为
true
,则递归地导入源元素的后代并集合得到的节点,以构造相应的子树。
Entity
节点,但在当前版本的 DOM 中,
DocumentType
是只读的。将考虑在以后版本的 DOM 中包含将这些导入的节点添加到
DocumentType
中这一功能。导入时,将复制
publicId
、
systemId
和
notationName
属性。如果请求
deep
导入,则递归地导入源
Entity
的后代,并重新集合得到的节点以构造相应的子树。
deep
导入,也只复制
EntityReference
本身,因为源和目标文档可能以不同方式定义实体。如果正在导入的文档提供对此实体名称的定义,则它的值得以分配。
Notation
节点,但在当前版本的 DOM 中,
DocumentType
是只读的。能够将这些导入的节点添加到
DocumentType
将被认为是以后版本的 DOM 的附加功能。导入时,复制
publicId
和
systemId
属性。注意,
deep
参数对此类型的节点无效,因为它们不能有任何子节点。
target
和
data
值。注意,该
deep
参数对此类型的节点无效,因为它们不能有任何子节点。
CharacterData
的这三种类型的节点从源节点复制其
data
和
length
属性。注意,
deep
参数对这三种类型的节点无效,因为它们不能有任何子节点。
importedNode
- 要导入的节点。
deep
- 如果为
true
,则递归地导入在指定节点下的子树;如果为
false
,则仅导入节点本身,如上面的解释。这对不能有任何子节点的节点、对
Attr
和
EntityReference
节点都无效。
Document
的节点。
DOMException
- NOT_SUPPORTED_ERR:如果不支持正在导入的该类型的节点,则引发此异常。
Document.xmlVersion
属性中指定的使用中的 XML 版本的 XML 名称,则引发此异常。例如,将 XML 1.1 [
XML 1.1] 元素导入 XML 1.0 文档时可能引发此异常。
Element createElementNS(String namespaceURI, String qualifiedName) throws DOMException
null
作为方法的 namespaceURI 参数的值。
namespaceURI
- 要创建的元素的名称空间 URI。
qualifiedName
- 要实例化的元素类型的限定名称。
Element
对象:
属性 | 值 |
---|---|
Node.nodeName |
qualifiedName |
Node.namespaceURI |
namespaceURI |
Node.prefix |
前缀,从 qualifiedName 中提取的;如果没有前缀,则为 null |
Node.localName |
本地名称,从 qualifiedName 提取的 |
Element.tagName |
qualifiedName |
DOMException
- INVALID_CHARACTER_ERR:如果指定的
qualifiedName
是不遵循在
Document.xmlVersion
属性中指定的使用中的 XML 版本的 XML 名称,则引发此异常。
qualifiedName
是错误格式的限制名称;如果
qualifiedName
具有前缀且
namespaceURI
为
null
;或者如果
qualifiedName
具有前缀 "xml" 且该
namespaceURI
不同于 "
http://www.w3.org/XML/1998/namespace" [
XML Namespaces];或者如果
qualifiedName
或其前缀为 "xmlns" 且该
namespaceURI
不同于 "
http://www.w3.org/2000/xmlns/";或者如果
namespaceURI
为 "
http://www.w3.org/2000/xmlns/" 且
qualifiedName
及其前缀都不是 "xmlns"。
"XML"
特性,则总是抛出此异常。
Attr createAttributeNS(String namespaceURI, String qualifiedName) throws DOMException
null
作为方法的
namespaceURI
参数的值。
namespaceURI
- 要创建的属性的名称空间 URI。
qualifiedName
- 要实例化的属性的限定名称。
Attr
对象:
属性 | 值 |
---|---|
Node.nodeName |
qualifiedName |
Node.namespaceURI |
namespaceURI |
Node.prefix |
前缀,从 qualifiedName 中提取的;如果没有前缀,则为 null |
Node.localName |
本地名称,从 qualifiedName 提取的 |
Attr.name |
qualifiedName |
Node.nodeValue |
空字符串 |
DOMException
- INVALID_CHARACTER_ERR:如果指定的
qualifiedName
是不遵循在
Document.xmlVersion
属性中指定的使用中的 XML 版本的 XML 名称,则引发此异常。
qualifiedName
为错误格式的限定名称;如果
qualifiedName
有前缀且
namespaceURI
为
null
;如果
qualifiedName
有前缀 "xml" 且
namespaceURI
不同于 "
http://www.w3.org/XML/1998/namespace";如果
qualifiedName
或其前缀为 "xmlns" 且
namespaceURI
不同于 "
http://www.w3.org/2000/xmlns/";或者
namespaceURI
为 "
http://www.w3.org/2000/xmlns/" 且
qualifiedName
及其前缀都不是 "xmlns"。
"XML"
特性,则总是抛出此异常。
NodeList getElementsByTagNameNS(String namespaceURI, String localName)
Elements
的
NodeList
。
namespaceURI
- 要匹配的元素的名称空间 URI。特殊值
"*"
匹配所有名称空间。
localName
- 要匹配的元素的本地名称。特殊值 "*" 匹配所有本地名称。
Elements
的新
NodeList
对象。
Element getElementById(String elementId)
Element
。如果不存在此类元素,则此方法返回
null
。如果一个以上的元素具有带该值的 ID 属性,返回哪一个元素是不确定的。
Attr.isId
来确定属性是否属于类型 ID。
注: 具有名称 "ID" 或 "id" 的属性不属于类型 ID,除非这样定义。
elementId
- 元素的唯一
id
值。
null
。
String getInputEncoding()
Document
时),则为
null
。
String getXmlEncoding()
Document
时,此属性为
null
。
boolean getXmlStandalone()
false
。
注: 设置此属性时不对此值进行任何验证。应用程序应该使用带有 "validate" 参数的 Document.normalizeDocument()
验证该值是否匹配在 [XML 1.0] 中定义的有关独立文档声明的有效性约束()。
void setXmlStandalone(boolean xmlStandalone) throws DOMException
false
。
注: 设置此属性时不对此值进行任何验证。应用程序应该使用带有 "validate" 参数的 Document.normalizeDocument()
验证该值是否匹配 validity constraint for standalone document declaration(在 [XML 1.0] 中定义)。
DOMException
- NOT_SUPPORTED_ERR:如果此文档不支持 "XML" 特性,则引发此异常。
String getXmlVersion()
"1.0"
。如果此文档不支持 "XML" 特性,则该值始终为
null
。更改此属性将影响在 XML 名称中检查无效字符的方法。应用程序应该调用
Document.normalizeDocument()
来检查在已经是此
Document
一部分的
Node
中的无效字符。
DOMImplementation.hasFeature(feature, version)
方法来确定实现是否支持 [
XML 1.0]。DOM 应用程序还可以使用参数值分别为 "XMLVersion" 和 "1.1"的同一方法来确定实现是否支持 [
XML 1.1]。在这两种情况下,为了支持 XML,实现还必须支持在此规范中定义的 "XML" 特性。支持某版本的 "XMLVersion" 特性的
Document
对象不能在使用
Document.xmlVersion
时对相同版本号引发
NOT_SUPPORTED_ERR
异常。
void setXmlVersion(String xmlVersion) throws DOMException
"1.0"
。如果此文档不支持 "XML" 特性,则该值始终为
null
。更改此属性将影响在 XML 名称中检查无效字符的方法。应用程序应该调用
Document.normalizeDocument()
来检查在已经是此
Document
一部分的
Node
中的无效字符。
DOMImplementation.hasFeature(feature, version)
方法来确定实现是否支持 [
XML 1.0]。DOM 应用程序还可以使用参数值分别为 "XMLVersion" 和 "1.1"的同一方法来确定实现是否支持 [
XML 1.1]。在这两种情况下,为了支持 XML,实现还必须支持在此规范中定义的 "XML" 特性。支持某版本的 "XMLVersion" 特性的
Document
对象不能在使用
Document.xmlVersion
时对相同版本号引发
NOT_SUPPORTED_ERR
异常。
DOMException
- NOT_SUPPORTED_ERR:如果将该版本设置为此
Document
不支持的值,或此文档不支持 "XML" 特性,则引发此异常。
boolean getStrictErrorChecking()
false
时,该实现可以不测试通常在 DOM 操作上定义的每个可能的错误情形,可以不在 DOM 操作上引发任何
DOMException
,也可以不在使用
Document.normalizeDocument()
时报告错误。如果发生错误,则该行为将会不确定。此属性默认为
true
。
void setStrictErrorChecking(boolean strictErrorChecking)
false
时,该实现不会随意测试通常在 DOM 操作上定义的每个可能的错误情形,不会在 DOM 操作上引发任何
DOMException
,也不会在使用
Document.normalizeDocument()
时报告错误。如果发生错误,则该行为不确定。此属性默认为
true
。
String getDocumentURI()
Document
是使用
DOMImplementation.createDocument
创建的,则为
null
。设置此属性时不执行任何词汇检查;这可能导致在使用
Node.baseURI
时返回
null
值。
Document
支持 "HTML" [
DOM Level 2 HTML] 特性,则计算
Node.baseURI
时 HTML BASE 元素的 href 属性优先于此属性。
void setDocumentURI(String documentURI)
Document
是使用
DOMImplementation.createDocument
创建的,则为
null
。设置此属性时不执行任何词汇检查;这可能导致在使用
Node.baseURI
时返回
null
值。
Document
支持 "HTML" [
DOM Level 2 HTML] 特性,则计算
Node.baseURI
时 HTML BASE 元素的 href 属性优先于此属性。
Node adoptNode(Node source) throws DOMException
ownerDocument
、它的子节点以及连接的属性节点(如果有)。如果源节点有父节点,则首先从其父节点的子节点列表中移除它。此方法允许将子树从一个文档移动到另一个文档(与
importNode()
不同,后者创建源节点副本,而不是移动子树)。失败时,应用程序应该改为使用
Document.importNode()
。注意,如果采用的节点已经是此文档的一部分(即源文档和目标文档相同),此方法仍可有效地从其父节点(如果有)的子列表移除源节点。下表描述了每种类型节点的细节。
Attr
上,将
ownerElement
属性设置为
null
并将
specified
标志设置为
true
。递归地采用源
Attr
的后代。
Document
节点。
DocumentType
节点。
Entity
节点。
EntityReference
节点本身并丢弃其后代,因为源文档和目标文档可能以不同方式定义实体。如果要导入的文档提供了对此实体名称的定义,则分配其值。
Notation
节点。
注: 由于它与 Document.importNode()
方法不同,不创建新的节点,因此此方法不引发 INVALID_CHARACTER_ERR
异常,并且应用程序应该使用 Document.normalizeDocument()
方法来检查导入的名称是否是遵循正在使用的 XML 版本的 XML 名称。
source
- 要移入此文档的节点。
null
。
DOMException
- NOT_SUPPORTED_ERR:如果源节点属于
DOCUMENT
、
DOCUMENT_TYPE
类型,则引发此异常。
DOMConfiguration getDomConfig()
Document.normalizeDocument()
时使用的配置。
void normalizeDocument()
EntityReference
节点的替换树并规范化
Text
节点,如在方法
Node.normalize()
中定义的那样。
Document.domConfig
对象上设置的、控制哪个操作实际发生的特性。值得注意的是,此方法还可以按照其中描述的算法使文档名称空间格式良好、检查字符规范化、移除
CDATASection
节点,等等。有关详细信息请参见
DOMConfiguration
。
// Keep in the document the information defined // in the XML Information Set (Java example) DOMConfiguration docConfig = myDocument.getDomConfig(); docConfig.setParameter("infoset", Boolean.TRUE); myDocument.normalizeDocument();
Node.nodeName
包含无效字符,则将使用与 "error-handler" 参数相关联的
DOMErrorHandler
对象报告错误或警告(
DOMError.SEVERITY_ERROR
或
DOMError.SEVERITY_WARNING
)。注意,如果实现无法从错误中恢复,则此方法还可能报告严重错误(
DOMError.SEVERITY_FATAL_ERROR
)。
Node renameNode(Node n, String namespaceURI, String qualifiedName) throws DOMException
ELEMENT_NODE
或
ATTRIBUTE_NODE
类型的现有节点。
Element
,则其属性移动到新节点;将新节点插入旧节点原来在其父(如果有)的子节点列表中的位置;将连接到旧节点的用户数据连接到新节点。
Element
时,只移动指定的属性,源于 DTD 的默认属性按照新的元素名称更新。此外,实现还可以更新源自其他模式的默认属性。应用程序应该使用
Document.normalizeDocument()
来保证这些属性是最新的。
Element
的
Attr
时,则首先从
Element
属性映射中移除该节点。然后,一旦通过修改现有节点或创建新节点(如上所述)重命名,则将它放回原处。
NODE_RENAMED
, http://www.w3.org/2001/xml-events
DOMElementNameChanged
} 或 { http://www.w3.org/2001/xml-events
DOMAttributeNameChanged
}。
n
- 要重命名的节点。
namespaceURI
- 新的名称空间 URI。
qualifiedName
- 新的限定名称。
DOMException
- NOT_SUPPORTED_ERR:当指定节点的类型不是
ELEMENT_NODE
,也不是
ATTRIBUTE_NODE
时,或者如果实现不支持重命名文档元素,则引发此异常。
Document.xmlVersion
属性中指定的 XML 版本的 XML 名称,则引发此异常。
qualifiedName
为错误格式的限定名称;如果
qualifiedName
有前缀且
namespaceURI
为
null
;或者如果
qualifiedName
有前缀 "xml" 且
namespaceURI
不同于 "
http://www.w3.org/XML/1998/namespace" [
XML Namespaces]。当正被重命名的节点为一属性时,如果
qualifiedName
或其前缀为 "xmlns" 且
namespaceURI
不同于 "
http://www.w3.org/2000/xmlns/",也引发此异常。
|
JavaTM Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。