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

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