001/* 002 * Copyright (c) 2000 World Wide Web Consortium, 003 * (Massachusetts Institute of Technology, Institut National de 004 * Recherche en Informatique et en Automatique, Keio University). All 005 * Rights Reserved. This program is distributed under the W3C's Software 006 * Intellectual Property License. This program is distributed in the 007 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even 008 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 009 * PURPOSE. 010 * See W3C License http://www.w3.org/Consortium/Legal/ for more details. 011 */ 012 013package org.w3c.dom; 014 015/** 016 * Objects implementing the <code>NamedNodeMap</code> interface are used to 017 * represent collections of nodes that can be accessed by name. Note that 018 * <code>NamedNodeMap</code> does not inherit from <code>NodeList</code>; 019 * <code>NamedNodeMaps</code> are not maintained in any particular order. 020 * Objects contained in an object implementing <code>NamedNodeMap</code> may 021 * also be accessed by an ordinal index, but this is simply to allow 022 * convenient enumeration of the contents of a <code>NamedNodeMap</code>, 023 * and does not imply that the DOM specifies an order to these Nodes. 024 * <p><code>NamedNodeMap</code> objects in the DOM are live. 025 * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>. 026 */ 027public interface NamedNodeMap { 028 /** 029 * Retrieves a node specified by name. 030 * @param nameThe <code>nodeName</code> of a node to retrieve. 031 * @return A <code>Node</code> (of any type) with the specified 032 * <code>nodeName</code>, or <code>null</code> if it does not identify 033 * any node in this map. 034 */ 035 public Node getNamedItem(String name); 036 037 /** 038 * Adds a node using its <code>nodeName</code> attribute. If a node with 039 * that name is already present in this map, it is replaced by the new 040 * one. 041 * <br>As the <code>nodeName</code> attribute is used to derive the name 042 * which the node must be stored under, multiple nodes of certain types 043 * (those that have a "special" string value) cannot be stored as the 044 * names would clash. This is seen as preferable to allowing nodes to be 045 * aliased. 046 * @param argA node to store in this map. The node will later be 047 * accessible using the value of its <code>nodeName</code> attribute. 048 * @return If the new <code>Node</code> replaces an existing node the 049 * replaced <code>Node</code> is returned, otherwise <code>null</code> 050 * is returned. 051 * @exception DOMException 052 * WRONG_DOCUMENT_ERR: Raised if <code>arg</code> was created from a 053 * different document than the one that created this map. 054 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly. 055 * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>arg</code> is an 056 * <code>Attr</code> that is already an attribute of another 057 * <code>Element</code> object. The DOM user must explicitly clone 058 * <code>Attr</code> nodes to re-use them in other elements. 059 */ 060 public Node setNamedItem(Node arg) 061 throws DOMException; 062 063 /** 064 * Removes a node specified by name. When this map contains the attributes 065 * attached to an element, if the removed attribute is known to have a 066 * default value, an attribute immediately appears containing the 067 * default value as well as the corresponding namespace URI, local name, 068 * and prefix when applicable. 069 * @param nameThe <code>nodeName</code> of the node to remove. 070 * @return The node removed from this map if a node with such a name 071 * exists. 072 * @exception DOMException 073 * NOT_FOUND_ERR: Raised if there is no node named <code>name</code> in 074 * this map. 075 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly. 076 */ 077 public Node removeNamedItem(String name) 078 throws DOMException; 079 080 /** 081 * Returns the <code>index</code>th item in the map. If <code>index</code> 082 * is greater than or equal to the number of nodes in this map, this 083 * returns <code>null</code>. 084 * @param indexIndex into this map. 085 * @return The node at the <code>index</code>th position in the map, or 086 * <code>null</code> if that is not a valid index. 087 */ 088 public Node item(int index); 089 090 /** 091 * The number of nodes in this map. The range of valid child node indices 092 * is <code>0</code> to <code>length-1</code> inclusive. 093 */ 094 public int getLength(); 095 096 /** 097 * Retrieves a node specified by local name and namespace URI. HTML-only 098 * DOM implementations do not need to implement this method. 099 * @param namespaceURIThe namespace URI of the node to retrieve. 100 * @param localNameThe local name of the node to retrieve. 101 * @return A <code>Node</code> (of any type) with the specified local 102 * name and namespace URI, or <code>null</code> if they do not 103 * identify any node in this map. 104 * @since DOM Level 2 105 */ 106 public Node getNamedItemNS(String namespaceURI, 107 String localName); 108 109 /** 110 * Adds a node using its <code>namespaceURI</code> and 111 * <code>localName</code>. If a node with that namespace URI and that 112 * local name is already present in this map, it is replaced by the new 113 * one. 114 * <br>HTML-only DOM implementations do not need to implement this method. 115 * @param argA node to store in this map. The node will later be 116 * accessible using the value of its <code>namespaceURI</code> and 117 * <code>localName</code> attributes. 118 * @return If the new <code>Node</code> replaces an existing node the 119 * replaced <code>Node</code> is returned, otherwise <code>null</code> 120 * is returned. 121 * @exception DOMException 122 * WRONG_DOCUMENT_ERR: Raised if <code>arg</code> was created from a 123 * different document than the one that created this map. 124 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly. 125 * <br>INUSE_ATTRIBUTE_ERR: Raised if <code>arg</code> is an 126 * <code>Attr</code> that is already an attribute of another 127 * <code>Element</code> object. The DOM user must explicitly clone 128 * <code>Attr</code> nodes to re-use them in other elements. 129 * @since DOM Level 2 130 */ 131 public Node setNamedItemNS(Node arg) 132 throws DOMException; 133 134 /** 135 * Removes a node specified by local name and namespace URI. A removed 136 * attribute may be known to have a default value when this map contains 137 * the attributes attached to an element, as returned by the attributes 138 * attribute of the <code>Node</code> interface. If so, an attribute 139 * immediately appears containing the default value as well as the 140 * corresponding namespace URI, local name, and prefix when applicable. 141 * <br>HTML-only DOM implementations do not need to implement this method. 142 * @param namespaceURIThe namespace URI of the node to remove. 143 * @param localNameThe local name of the node to remove. 144 * @return The node removed from this map if a node with such a local 145 * name and namespace URI exists. 146 * @exception DOMException 147 * NOT_FOUND_ERR: Raised if there is no node with the specified 148 * <code>namespaceURI</code> and <code>localName</code> in this map. 149 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly. 150 * @since DOM Level 2 151 */ 152 public Node removeNamedItemNS(String namespaceURI, 153 String localName) 154 throws DOMException; 155 156}