http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Home

Readme
Download
Installation
Build

API Docs
Samples
Schema

FAQs
Programming
Migration

Releases
Bug-Reporting
Feedback

Y2K Compliance
PDF Document

CVS Repository
Mail Archive

API Docs for SAX and DOM
 

Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

IDOM_Document Class Reference

Class to refer to XML Document nodes in the IDOM. More...

#include <IDOM_Document.hpp>

Inheritance diagram for IDOM_Document

Inheritance graph
[legend]
Collaboration diagram for IDOM_Document:

Collaboration graph
[legend]
List of all members.

Public Methods

Destructor
virtual ~IDOM_Document ()
Factory methods to create new nodes for the Document
virtual IDOM_EntitycreateEntity (const XMLCh *name)=0
 Create a new entity. More...

virtual IDOM_ElementcreateElement (const XMLCh *tagName)=0
 Creates an element of the type specified. More...

virtual IDOM_DocumentFragmentcreateDocumentFragment ()=0
 Creates an empty DocumentFragment object. More...

virtual IDOM_TextcreateTextNode (const XMLCh *data)=0
 Creates a Text node given the specified string. More...

virtual IDOM_CommentcreateComment (const XMLCh *data)=0
 Creates a Comment node given the specified string. More...

virtual IDOM_CDATASectioncreateCDATASection (const XMLCh *data)=0
 Creates a CDATASection node whose value is the specified string. More...

virtual IDOM_DocumentTypecreateDocumentType (const XMLCh *name)=0
 Create a DocumentType node. More...

virtual IDOM_NotationcreateNotation (const XMLCh *name)=0
 Create a Notation. More...

virtual IDOM_ProcessingInstructioncreateProcessingInstruction (const XMLCh *target,const XMLCh *data)=0
 Creates a ProcessingInstruction node given the specified name and data strings. More...

virtual IDOM_AttrcreateAttribute (const XMLCh *name)=0
 Creates an Attr of the given name. More...

virtual IDOM_EntityReferencecreateEntityReference (const XMLCh *name)=0
 Creates an EntityReference object. More...

virtual IDOM_NodeIteratorcreateNodeIterator (IDOM_Node *root,unsigned long whatToShow,IDOM_NodeFilter *filter,bool entityReferenceExpansion)=0
 Creates a NodeIterator object. More...

virtual IDOM_TreeWalkercreateTreeWalker (IDOM_Node *root,unsigned long whatToShow,IDOM_NodeFilter *filter,bool entityReferenceExpansion)=0
 Creates a TreeWalker object. More...

virtual IDOM_RangecreateRange ()=0
 To create the range consisting of boundary-points and offset of the selected contents. More...

Getter functions
virtual IDOM_DocumentTypegetDoctype ()const=0
 Get Document Type Declaration (see IDOM_DocumentType) associated with this document. More...

virtual IDOM_DOMImplementationgetImplementation ()const=0
 Return the IDOMImplementation object that handles this document.

virtual IDOM_ElementgetDocumentElement ()const=0
 Return a reference to the root element of the document.

virtual IDOM_NodeListgetElementsByTagName (const XMLCh *tagname)const=0
 Returns a IDOM_NodeList of all the elements with a given tag name. More...

Functions introduced in IDOM Level 2.
virtual IDOM_NodeimportNode (IDOM_Node *importedNode,bool deep)=0
 Imports a node from another document to this document. More...

virtual IDOM_ElementcreateElementNS (const XMLCh *namespaceURI,const XMLCh *qualifiedName)=0
 Creates an element of the given qualified name and namespace URI. More...

virtual IDOM_AttrcreateAttributeNS (const XMLCh *namespaceURI,const XMLCh *qualifiedName)=0
 Creates an attribute of the given qualified name and namespace URI. More...

virtual IDOM_NodeListgetElementsByTagNameNS (const XMLCh *namespaceURI,const XMLCh *localName)const=0
 Returns a IDOM_NodeList of all the IDOM_Elements with a given local name and namespace URI in the order in which they would be encountered in a preorder traversal of the IDOM_Document tree. More...

virtual IDOM_ElementgetElementById (const XMLCh *elementId)const=0
 Returns the IDOM_Element whose ID is given by elementId. More...


Protected Methods

Constructors and assignment operators
 IDOM_Document ()
 The default constructor for IDOM_Document creates a null IDOM_Document object that refers to no document. More...

 IDOM_Document (const IDOM_Document &other)
 Copy constructor. More...

IDOM_Document& operator= (const IDOM_Document &other)
 Assignment operator. More...


Friends

class  IDOM_Node
class  DocumentImpl
class  NodeIteratorImpl
class  IDOM_IDOMImplementation

Detailed Description

Class to refer to XML Document nodes in the IDOM.

Conceptually, a IDOM document node is the root of the document tree, and provides the primary access to the document's data.

Since elements, text nodes, comments, processing instructions, etc. cannot exist outside the context of a Document, the Document interface also contains the factory methods needed to create these objects. The Node objects created have a ownerDocument attribute which associates them with the Document within whose context they were created.


Constructor & Destructor Documentation

IDOM_Document::IDOM_Document ( ) [protected]
 

The default constructor for IDOM_Document creates a null IDOM_Document object that refers to no document.

It may subsequently be assigned to refer to an actual Document node.

To create a new document, use the DOMImplementation IDOM_DOMImplementation::createDocument().

IDOM_Document::IDOM_Document ( const IDOM_Document & other ) [protected]
 

Copy constructor.

Creates a new IDOM_Document that refers to the same underlying actual document as the original.

Parameters:
other   The object to be copied

IDOM_Document::~IDOM_Document ( ) [virtual]
 


Member Function Documentation

IDOM_Attr * IDOM_Document::createAttribute ( const XMLCh * name ) [pure virtual]
 

Creates an Attr of the given name.

Note that the Attr instance can then be attached to an Element using the IDOMElement::setAttribute() method.

Parameters:
name   The name of the attribute.
Returns:
A new IDOM_Attr object with the nodeName attribute set to name, and localName, prefix, and namespaceURI set to null.
Exceptions:
IDOMException   INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

IDOM_Attr * IDOM_Document::createAttributeNS ( const XMLCh * namespaceURI,
const XMLCh * qualifiedName ) [pure virtual]
 

Creates an attribute of the given qualified name and namespace URI.

Parameters:
namespaceURI   The namespace URI of the attribute to create.
qualifiedName   The qualified name of the attribute to instantiate.
Returns:
A new IDOM_Attr object.
Exceptions:
IDOMException   INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character.
NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null or an empty string, if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace", if the qualifiedName has a prefix that is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/", or if the qualifiedName is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/".

IDOM_CDATASection * IDOM_Document::createCDATASection ( const XMLCh * data ) [pure virtual]
 

Creates a CDATASection node whose value is the specified string.

Parameters:
data   The data for the IDOM_CDATASection contents.
Returns:
A IDOM_CDATASection object.
Exceptions:
IDOMException   NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

IDOM_Comment * IDOM_Document::createComment ( const XMLCh * data ) [pure virtual]
 

Creates a Comment node given the specified string.

Parameters:
data   The data for the comment.
Returns:
A IDOM_Comment that references the newly created comment node.

IDOM_DocumentFragment * IDOM_Document::createDocumentFragment ( ) [pure virtual]
 

Creates an empty DocumentFragment object.

Returns:
A IDOM_DocumentFragment that references the newly created document fragment.

IDOM_DocumentType * IDOM_Document::createDocumentType ( const XMLCh * name ) [pure virtual]
 

Create a DocumentType node.

Non-standard extension.

Returns:
A IDOM_DocumentType that references the newly created DocumentType node.

IDOM_Element * IDOM_Document::createElement ( const XMLCh * tagName ) [pure virtual]
 

Creates an element of the type specified.

Note that the instance returned implements the Element interface, so attributes can be specified directly on the returned object.

Parameters:
tagName   The name of the element type to instantiate.
Returns:
A IDOM_Element that reference the new element.
Exceptions:
IDOMException   INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

IDOM_Element * IDOM_Document::createElementNS ( const XMLCh * namespaceURI,
const XMLCh * qualifiedName ) [pure virtual]
 

Creates an element of the given qualified name and namespace URI.

Parameters:
namespaceURI   The namespace URI of the element to create.
qualifiedName   The qualified name of the element type to instantiate.
Returns:
A new IDOM_Element object.
Exceptions:
IDOMException   INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character.
NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null or an empty string, or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace".

IDOM_Entity * IDOM_Document::createEntity ( const XMLCh * name ) [pure virtual]
 

Create a new entity.

Non-standard extension.

Parameters:
name   The name of the entity to instantiate

IDOM_EntityReference * IDOM_Document::createEntityReference ( const XMLCh * name ) [pure virtual]
 

Creates an EntityReference object.

Parameters:
name   The name of the entity to reference.
Returns:
A IDOM_EntityReference that references the newly created EntityReference node.
Exceptions:
IDOMException   INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

IDOM_NodeIterator * IDOM_Document::createNodeIterator ( IDOM_Node * root,
unsigned long whatToShow,
IDOM_NodeFilter * filter,
bool entityReferenceExpansion ) [pure virtual]
 

Creates a NodeIterator object.

(IDOM2)

NodeIterators are used to step through a set of nodes, e.g. the set of nodes in a NodeList, the document subtree governed by a particular node, the results of a query, or any other set of nodes. The set of nodes to be iterated is determined by the implementation of the NodeIterator. IDOM Level 2 specifies a single NodeIterator implementation for document-order traversal of a document subtree. Instances of these iterators are created by calling DocumentTraversal.createNodeIterator().

To produce a view of the document that has entity references expanded and does not expose the entity reference node itself, use the whatToShow flags to hide the entity reference node and set expandEntityReferences to true when creating the iterator. To produce a view of the document that has entity reference nodes but no entity expansion, use the whatToShow flags to show the entity reference node and set expandEntityReferences to false.

Parameters:
root   The root node of the IDOM tree
whatToShow   This attribute determines which node types are presented via the iterator.
filter   The filter used to screen nodes
entityReferenceExpansion   The value of this flag determines whether the children of entity reference nodes are visible to the iterator. If false, they will be skipped over.

IDOM_Notation * IDOM_Document::createNotation ( const XMLCh * name ) [pure virtual]
 

Create a Notation.

Non-standard extension.

Parameters:
name   The name of the notation to instantiate
Returns:
A IDOM_Notation that references the newly created Notation node.

IDOM_ProcessingInstruction * IDOM_Document::createProcessingInstruction ( const XMLCh * target,
const XMLCh * data ) [pure virtual]
 

Creates a ProcessingInstruction node given the specified name and data strings.

Parameters:
target   The target part of the processing instruction.
data   The data for the node.
Returns:
A IDOM_ProcessingInstruction that references the newly created PI node.
Exceptions:
IDOMException   INVALID_CHARACTER_ERR: Raised if an illegal character is specified.

IDOM_Range * IDOM_Document::createRange ( ) [pure virtual]
 

To create the range consisting of boundary-points and offset of the selected contents.

Returns:
The initial state of the Range such that both the boundary-points are positioned at the beginning of the corresponding IDOM_DOcument, before any content. The range returned can only be used to select content associated with this document, or with documentFragments and Attrs for which this document is the ownerdocument

IDOM_Text * IDOM_Document::createTextNode ( const XMLCh * data ) [pure virtual]
 

Creates a Text node given the specified string.

Parameters:
data   The data for the node.
Returns:
A IDOM_Text object that references the newly created text node.

IDOM_TreeWalker * IDOM_Document::createTreeWalker ( IDOM_Node * root,
unsigned long whatToShow,
IDOM_NodeFilter * filter,
bool entityReferenceExpansion ) [pure virtual]
 

Creates a TreeWalker object.

(IDOM2)

TreeWalker objects are used to navigate a document tree or subtree using the view of the document defined by its whatToShow flags and any filters that are defined for the TreeWalker. Any function which performs navigation using a TreeWalker will automatically support any view defined by a TreeWalker.

Omitting nodes from the logical view of a subtree can result in a structure that is substantially different from the same subtree in the complete, unfiltered document. Nodes that are siblings in the TreeWalker view may be children of different, widely separated nodes in the original view. For instance, consider a Filter that skips all nodes except for Text nodes and the root node of a document. In the logical view that results, all text nodes will be siblings and appear as direct children of the root node, no matter how deeply nested the structure of the original document.

To produce a view of the document that has entity references expanded and does not expose the entity reference node itself, use the whatToShow flags to hide the entity reference node and set expandEntityReferences to true when creating the TreeWalker. To produce a view of the document that has entity reference nodes but no entity expansion, use the whatToShow flags to show the entity reference node and set expandEntityReferences to false

Parameters:
root   The root node of the IDOM tree
whatToShow   This attribute determines which node types are presented via the tree-walker.
filter   The filter used to screen nodes
entityReferenceExpansion   The value of this flag determines whether the children of entity reference nodes are visible to the tree-walker. If false, they will be skipped over.

IDOM_DocumentType * IDOM_Document::getDoctype ( ) const [pure virtual]
 

Get Document Type Declaration (see IDOM_DocumentType) associated with this document.

For documents without a document type declaration this returns null reference object. The IDOM Level 1 does not support editing the Document Type Declaration, therefore docType cannot be altered in any way.

IDOM_Element * IDOM_Document::getDocumentElement ( ) const [pure virtual]
 

Return a reference to the root element of the document.

IDOM_Element * IDOM_Document::getElementById ( const XMLCh * elementId ) const [pure virtual]
 

Returns the IDOM_Element whose ID is given by elementId.

If no such element exists, returns null. Behavior is not defined if more than one element has this ID.

Note: The IDOM implementation must have information that says which attributes are of type ID. Attributes with the name "ID" are not of type ID unless so defined. Implementations that do not know whether attributes are of type ID or not are expected to return null.

Parameters:
elementId   The unique id value for an element.
Returns:
The matching element.

IDOM_NodeList * IDOM_Document::getElementsByTagName ( const XMLCh * tagname ) const [pure virtual]
 

Returns a IDOM_NodeList of all the elements with a given tag name.

The returned node list is "live", in that changes to the document tree made after a nodelist was initially returned will be immediately reflected in the node list.

The elements in the node list are ordered in the same order in which they would be encountered in a preorder traversal of the Document tree.

Parameters:
tagname   The name of the tag to match on. The special value "*" matches all tags.
Returns:
A reference to a NodeList containing all the matched Elements.

IDOM_NodeList * IDOM_Document::getElementsByTagNameNS ( const XMLCh * namespaceURI,
const XMLCh * localName ) const [pure virtual]
 

Returns a IDOM_NodeList of all the IDOM_Elements with a given local name and namespace URI in the order in which they would be encountered in a preorder traversal of the IDOM_Document tree.

Parameters:
namespaceURI   The namespace URI of the elements to match on. The special value "*" matches all namespaces.
localName   The local name of the elements to match on. The special value "*" matches all local names.
Returns:
A new IDOM_NodeList object containing all the matched IDOM_Elements.

IDOM_DOMImplementation * IDOM_Document::getImplementation ( ) const [pure virtual]
 

Return the IDOMImplementation object that handles this document.

IDOM_Node * IDOM_Document::importNode ( IDOM_Node * importedNode,
bool deep ) [pure virtual]
 

Imports a node from another document to this document.

The returned node has no parent (parentNode is null). The source node is not altered or removed from the original document; this method creates a new copy of the source node.
For all nodes, importing a node creates a node object owned by the importing document, with attribute values identical to the source node's nodeName and nodeType, plus the attributes related to namespaces (prefix and namespaces URI).

Parameters:
importedNode   The node to import.
deep   If true, recursively import the subtree under the specified node; if false, import only the node itself, as explained above. This does not apply to IDOM_Attr, IDOM_EntityReference, and IDOM_Notation nodes.
Returns:
The imported node that belongs to this IDOM_Document.
Exceptions:
IDOMException   NOT_SUPPORTED_ERR: Raised if the type of node being imported is not supported.

IDOM_Document & IDOM_Document::operator= ( const IDOM_Document & other ) [protected]
 

Assignment operator.

Parameters:
other   The object to be copied


Friends And Related Function Documentation

class DocumentImpl [friend]
 

class IDOM_IDOMImplementation [friend]
 

class IDOM_Node [friend]
 

class NodeIteratorImpl [friend]
 


The documentation for this class was generated from the following file:


Copyright © 2000 The Apache Software Foundation. All Rights Reserved.