offapi/com/sun/star/xml/dom/XNode.idl

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