1 /* 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * 4 * This code is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU General Public License version 2 only, as 6 * published by the Free Software Foundation. Oracle designates this 7 * particular file as subject to the "Classpath" exception as provided 8 * by Oracle in the LICENSE file that accompanied this code. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25 /* 26 * This file is available under and governed by the GNU General Public 27 * License version 2 only, as published by the Free Software Foundation. 28 * However, the following notice accompanied the original version of this 29 * file and, per its terms, should not be removed: 30 * 31 * Copyright (c) 2004 World Wide Web Consortium, 32 * 33 * (Massachusetts Institute of Technology, European Research Consortium for 34 * Informatics and Mathematics, Keio University). All Rights Reserved. This 35 * work is distributed under the W3C(r) Software License [1] in the hope that 36 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied 37 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 38 * 39 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 40 */ 41 42 package org.w3c.dom; 43 44 /** 45 * Objects implementing the <code>NamedNodeMap</code> interface are used to 46 * represent collections of nodes that can be accessed by name. Note that 47 * <code>NamedNodeMap</code> does not inherit from <code>NodeList</code>; 48 * <code>NamedNodeMaps</code> are not maintained in any particular order. 49 * Objects contained in an object implementing <code>NamedNodeMap</code> may 50 * also be accessed by an ordinal index, but this is simply to allow 51 * convenient enumeration of the contents of a <code>NamedNodeMap</code>, 52 * and does not imply that the DOM specifies an order to these Nodes. 53 * <p><code>NamedNodeMap</code> objects in the DOM are live. 54 * <p>See also the <a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>Document Object Model (DOM) Level 3 Core Specification</a>. 55 */ 56 public interface NamedNodeMap { 57 /** 58 * Retrieves a node specified by name. 59 * @param name The <code>nodeName</code> of a node to retrieve. 60 * @return A <code>Node</code> (of any type) with the specified 61 * <code>nodeName</code>, or <code>null</code> if it does not identify 62 * any node in this map. 63 */ getNamedItem(String name)64 public Node getNamedItem(String name); 65 66 /** 67 * Adds a node using its <code>nodeName</code> attribute. If a node with 68 * that name is already present in this map, it is replaced by the new 69 * one. Replacing a node by itself has no effect. 70 * <br>As the <code>nodeName</code> attribute is used to derive the name 71 * which the node must be stored under, multiple nodes of certain types 72 * (those that have a "special" string value) cannot be stored as the 73 * names would clash. This is seen as preferable to allowing nodes to be 74 * aliased. 75 * @param arg A node to store in this map. The node will later be 76 * accessible using the value of its <code>nodeName</code> attribute. 77 * @return If the new <code>Node</code> replaces an existing node the 78 * replaced <code>Node</code> is returned, otherwise <code>null</code> 79 * is returned. 80 * @exception DOMException 81 * WRONG_DOCUMENT_ERR: Raised if <code>arg</code> was created from a 82 * different document than the one that created this map. 83 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly. 84 * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>arg</code> is an 85 * <code>Attr</code> that is already an attribute of another 86 * <code>Element</code> object. The DOM user must explicitly clone 87 * <code>Attr</code> nodes to re-use them in other elements. 88 * <br>HIERARCHY_REQUEST_ERR: Raised if an attempt is made to add a node 89 * doesn't belong in this NamedNodeMap. Examples would include trying 90 * to insert something other than an Attr node into an Element's map 91 * of attributes, or a non-Entity node into the DocumentType's map of 92 * Entities. 93 */ setNamedItem(Node arg)94 public Node setNamedItem(Node arg) 95 throws DOMException; 96 97 /** 98 * Removes a node specified by name. When this map contains the attributes 99 * attached to an element, if the removed attribute is known to have a 100 * default value, an attribute immediately appears containing the 101 * default value as well as the corresponding namespace URI, local name, 102 * and prefix when applicable. 103 * @param name The <code>nodeName</code> of the node to remove. 104 * @return The node removed from this map if a node with such a name 105 * exists. 106 * @exception DOMException 107 * NOT_FOUND_ERR: Raised if there is no node named <code>name</code> in 108 * this map. 109 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly. 110 */ removeNamedItem(String name)111 public Node removeNamedItem(String name) 112 throws DOMException; 113 114 /** 115 * Returns the <code>index</code>th item in the map. If <code>index</code> 116 * is greater than or equal to the number of nodes in this map, this 117 * returns <code>null</code>. 118 * @param index Index into this map. 119 * @return The node at the <code>index</code>th position in the map, or 120 * <code>null</code> if that is not a valid index. 121 */ item(int index)122 public Node item(int index); 123 124 /** 125 * The number of nodes in this map. The range of valid child node indices 126 * is <code>0</code> to <code>length-1</code> inclusive. 127 */ getLength()128 public int getLength(); 129 130 /** 131 * Retrieves a node specified by local name and namespace URI. 132 * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] 133 * , applications must use the value null as the namespaceURI parameter 134 * for methods if they wish to have no namespace. 135 * @param namespaceURI The namespace URI of the node to retrieve. 136 * @param localName The local name of the node to retrieve. 137 * @return A <code>Node</code> (of any type) with the specified local 138 * name and namespace URI, or <code>null</code> if they do not 139 * identify any node in this map. 140 * @exception DOMException 141 * NOT_SUPPORTED_ERR: May be raised if the implementation does not 142 * support the feature "XML" and the language exposed through the 143 * Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 144 * @since 1.4, DOM Level 2 145 */ getNamedItemNS(String namespaceURI, String localName)146 public Node getNamedItemNS(String namespaceURI, 147 String localName) 148 throws DOMException; 149 150 /** 151 * Adds a node using its <code>namespaceURI</code> and 152 * <code>localName</code>. If a node with that namespace URI and that 153 * local name is already present in this map, it is replaced by the new 154 * one. Replacing a node by itself has no effect. 155 * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] 156 * , applications must use the value null as the namespaceURI parameter 157 * for methods if they wish to have no namespace. 158 * @param arg A node to store in this map. The node will later be 159 * accessible using the value of its <code>namespaceURI</code> and 160 * <code>localName</code> attributes. 161 * @return If the new <code>Node</code> replaces an existing node the 162 * replaced <code>Node</code> is returned, otherwise <code>null</code> 163 * is returned. 164 * @exception DOMException 165 * WRONG_DOCUMENT_ERR: Raised if <code>arg</code> was created from a 166 * different document than the one that created this map. 167 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly. 168 * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>arg</code> is an 169 * <code>Attr</code> that is already an attribute of another 170 * <code>Element</code> object. The DOM user must explicitly clone 171 * <code>Attr</code> nodes to re-use them in other elements. 172 * <br>HIERARCHY_REQUEST_ERR: Raised if an attempt is made to add a node 173 * doesn't belong in this NamedNodeMap. Examples would include trying 174 * to insert something other than an Attr node into an Element's map 175 * of attributes, or a non-Entity node into the DocumentType's map of 176 * Entities. 177 * <br>NOT_SUPPORTED_ERR: May be raised if the implementation does not 178 * support the feature "XML" and the language exposed through the 179 * Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 180 * @since 1.4, DOM Level 2 181 */ setNamedItemNS(Node arg)182 public Node setNamedItemNS(Node arg) 183 throws DOMException; 184 185 /** 186 * Removes a node specified by local name and namespace URI. A removed 187 * attribute may be known to have a default value when this map contains 188 * the attributes attached to an element, as returned by the attributes 189 * attribute of the <code>Node</code> interface. If so, an attribute 190 * immediately appears containing the default value as well as the 191 * corresponding namespace URI, local name, and prefix when applicable. 192 * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] 193 * , applications must use the value null as the namespaceURI parameter 194 * for methods if they wish to have no namespace. 195 * @param namespaceURI The namespace URI of the node to remove. 196 * @param localName The local name of the node to remove. 197 * @return The node removed from this map if a node with such a local 198 * name and namespace URI exists. 199 * @exception DOMException 200 * NOT_FOUND_ERR: Raised if there is no node with the specified 201 * <code>namespaceURI</code> and <code>localName</code> in this map. 202 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly. 203 * <br>NOT_SUPPORTED_ERR: May be raised if the implementation does not 204 * support the feature "XML" and the language exposed through the 205 * Document does not support XML Namespaces (such as [<a href='http://www.w3.org/TR/1999/REC-html401-19991224/'>HTML 4.01</a>]). 206 * @since 1.4, DOM Level 2 207 */ removeNamedItemNS(String namespaceURI, String localName)208 public Node removeNamedItemNS(String namespaceURI, 209 String localName) 210 throws DOMException; 211 212 } 213