xref: /aoo42x/main/offapi/com/sun/star/xml/dom/XNode.idl (revision d1766043)
1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23
24#ifndef __com_sun_star_xml_dom_XNode_idl__
25#define __com_sun_star_xml_dom_XNode_idl__
26
27#ifndef __com_sun_star_uno_XInterface_idl__
28#include <com/sun/star/uno/XInterface.idl>
29#endif
30#ifndef __com_sun_star_xml_dom_NodeType_idl__
31#include <com/sun/star/xml/dom/NodeType.idl>
32#endif
33#ifndef __com_sun_star_xml_dom_XNodeList_idl__
34#include <com/sun/star/xml/dom/XNodeList.idl>
35#endif
36#ifndef __com_sun_star_xml_dom_XNamedNodeMap_idl__
37#include <com/sun/star/xml/dom/XNamedNodeMap.idl>
38#endif
39
40
41module com { module sun { module star { module xml { module dom {
42
43interface XDocument;
44
45/** The primary dom datatype
46
47<p>The Node interface is the primary datatype for the entire Document Object Model.
48It represents a single node in the document tree. While all objects implementing
49the Node interface expose methods for dealing with children, not all objects
50#implementing the Node interface may have children. For example, Text nodes may not
51have children, and adding children to such nodes results in a DOMException being raised.</p>
52
53<p>The attributes nodeName, nodeValue and attributes are included as a mechanism to get at
54node information without casting down to the specific derived interface. In cases where
55there is no obvious mapping of these attributes for a specific nodeType (e.g., nodeValue
56for an Element or attributes for a Comment ), this returns null. Note that the specialized
57interfaces may contain additional and more convenient mechanisms to get and set the relevant
58information.</p>
59
60<p>The values of nodeName, nodeValue, and attributes vary according to the node type as follows:
61<table align=left border=1>
62<tr><th>Interface </th><th>nodeName </th><th>nodeValue </th><th>attributes</th></tr>
63<tr><th>Attr 	                </th><td>name of attribute 	</td><td>value of attribute 	            </td><td>null</td></tr>
64<tr><th>CDATASection 	        </th><td>"#cdata-section" 	</td><td>content of the CDATA Section 	</td><td>null</td></tr>
65<tr><th>Comment 	            </th><td>"#comment" 	        </td><td>content of the comment          </td><td>null</td></tr>
66<tr><th>Document 	            </th><td>"#document" 	    </td><td>null 	</td><td>null</td></tr>
67<tr><th>DocumentFragment        </th><td>"#document-fragment"</td><td>null 	</td><td>null</td></tr>
68<tr><th>DocumentType 	        </th><td>document type name 	</td><td>null 	</td><td>null</td></tr>
69<tr><th>Element 	            </th><td>tag name 	        </td><td>null 	</td><td>NamedNodeMap</td></tr>
70<tr><th>Entity 	                </th><td>entity name 	    </td><td>null 	</td><td>null</td></tr>
71<tr><th>EntityReference         </th><td>name of entity referenced 	    </td><td>null 	</td><td>null</td></tr>
72<tr><th>Notation 	            </th><td>notation name 	    </td><td>null 	</td><td>null</td></tr>
73<tr><th>ProcessingInstruction   </th><td>target 	            </td><td>entire content excluding the target 	</td><td>null</td></tr>
74<tr><th>Text 	                </th><td>"#text" 	        </td><td>content of the text node 	</td><td>null</td></tr>
75</table></p>
76
77@see <a href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113">Document Object Model (DOM) Level 2 Core Specification</a> </p>
78@since OOo 2.0
79*/
80interface XNode : com::sun::star::uno::XInterface
81{
82
83    /**
84    Adds the node newChild to the end of the list of children of this node.
85    @param newChild
86    the new child node
87    @throws com::sun::star::xml::dom::DOMException
88        <p>HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does
89           not allow children of the type of the newChild node, or if the
90           node to append is one of this node's ancestors or this node itself.</p>
91        <p>WRONG_DOCUMENT_ERR: Raised if newChild was created from a different
92           document than the one that created this node.</p>
93        <p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if
94           the previous parent of the node being inserted is readonly.</p>
95    */
96    XNode appendChild([in] XNode newChild) raises (DOMException);
97
98    /**
99    Returns a duplicate of this node, i.e., serves as a generic copy
100    constructor for nodes.
101    <p></p>
102    @param deep
103    <true/>: clone node together with any children<br>
104    <false/>: clone without children
105    @returns
106    the cloned node
107    */
108    XNode cloneNode([in] boolean deep);
109
110    /**
111    A NamedNodeMap containing the attributes of this node (if it is an Element)
112    or null otherwise.
113    */
114    XNamedNodeMap getAttributes();
115
116    /**
117    A NodeList that contains all children of this node.
118    */
119    XNodeList getChildNodes();
120
121    /**
122    The first child of this node.
123    */
124    XNode getFirstChild();
125
126    /**
127    The last child of this node.
128    */
129    XNode getLastChild();
130
131    /**
132    Returns the local part of the qualified name of this node.
133    */
134    string getLocalName();
135
136    /**
137    The namespace URI of this node, or null if it is unspecified.
138    */
139    string getNamespaceURI();
140
141    /**
142    The node immediately following this node.
143    */
144    XNode getNextSibling();
145
146    /**
147    The name of this node, depending on its type; see the table above.
148    */
149    string getNodeName();
150
151    /**
152    A code representing the type of the underlying object, as defined above.
153    */
154    NodeType getNodeType();
155
156    /**
157    The value of this node, depending on its type; see the table above.
158
159    @throws com::sun::star::xml::dom::DOMException
160    <p>DOMSTRING_SIZE_ERR: Raised when it would return more characters
161    than fit in a DOMString variable on the implementation platform.</p>
162    */
163    string getNodeValue() raises (DOMException);
164
165    /**
166    The Document object associated with this node.
167    */
168    XDocument getOwnerDocument();
169
170    /**
171    The parent of this node.
172    */
173    XNode getParentNode();
174
175    /**
176    The namespace prefix of this node, or null if it is unspecified.
177    */
178    string getPrefix();
179
180    /**
181    The node immediately preceding this node.
182    */
183    XNode getPreviousSibling();
184
185    /**
186    Returns whether this node (if it is an element) has any attributes.
187    */
188    boolean hasAttributes();
189
190    /**
191    Returns whether this node has any children.
192    */
193    boolean hasChildNodes();
194
195    /**
196    Inserts the node newChild before the existing child node refChild.
197    @throws DOMException
198    <p>HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does
199                      not allow children of the type of the newChild node, or if the
200                      node to insert is one of this node's ancestors or this node itself.
201                   <p>WRONG_DOCUMENT_ERR: Raised if newChild was created from a different
202                      document than the one that created this node.
203                   <p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if the
204                      parent of the node being inserted is readonly.
205                   <p>NOT_FOUND_ERR: Raised if refChild is not a child of this node.
206    */
207    XNode insertBefore([in] XNode newChild, [in] XNode refChild) raises (DOMException);
208
209    /**
210    Tests whether the DOM implementation implements a specific feature and
211    that feature is supported by this node.
212    */
213    boolean isSupported([in] string feature, [in] string ver);
214
215    /**
216    Puts all Text nodes in the full depth of the sub-tree underneath this
217    Node, including attribute nodes, into a "normal" form where only structure
218    (e.g., elements, comments, processing instructions, CDATA sections, and
219    entity references) separates Text nodes, i.e., there are neither adjacent
220    Text nodes nor empty Text nodes.
221    */
222    void normalize();
223
224    /**
225    Removes the child node indicated by oldChild from the list of children,
226    and returns it.
227    @throws DOMException
228    <p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
229    <p>NOT_FOUND_ERR: Raised if oldChild is not a child of this node.
230    */
231    XNode removeChild([in] XNode oldChild) raises (DOMException);
232
233    /**
234    Replaces the child node oldChild with newChild in the list of children,
235    and returns the oldChild node.
236    @throws DOMException
237                   <p>HIERARCHY_REQUEST_ERR: Raised if this node is of a type that
238                      does not allow children of the type of the newChild node, or
239                      if the node to put in is one of this node's ancestors or this
240                      node itself.
241                   <p>WRONG_DOCUMENT_ERR: Raised if newChild was created from a different
242                      document than the one that created this node.
243                   <p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of the
244                      new node is readonly.
245                   <p>NOT_FOUND_ERR: Raised if oldChild is not a child of this node.
246    */
247    XNode replaceChild([in] XNode newChild, [in] XNode oldChild) raises (DOMException);
248
249    /**
250    The value of this node, depending on its type; see the table above.
251    @throws DOMException
252        <p>NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
253        <p>DOMSTRING_SIZE_ERR: Raised when it would return more characters
254                      than fit in a DOMString variable on the implementation platform.
255    */
256    void setNodeValue([in] string nodeValue) raises (DOMException);
257
258    /**
259    The namespace prefix of this node, or null if it is unspecified.
260    @throws DOMException
261        <p>INVALID_CHARACTER_ERR: Raised if the specified prefix contains an illegal character,
262                      per the XML 1.0 specification .
263                   <p>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
264                   <p>NAMESPACE_ERR: Raised if the specified prefix is malformed per the Namespaces
265                      in XML specification, if the namespaceURI of this node is null, if the specified
266                      prefix is "xml" and the namespaceURI of this node is different from
267                      "http://www.w3.org/XML/1998/namespace", if this node is an attribute and the
268                      specified prefix is "xmlns" and the namespaceURI of this node is different from
269                      " http://www.w3.org/2000/xmlns/", or if this node is an attribute and the qualifiedName
270                      of this node is "xmlns" .
271    */
272    void setPrefix([in] string prefix) raises (DOMException);
273
274};
275
276}; }; }; }; };
277
278#endif
279