libjava/org/w3c/dom/NamedNodeMap.java

   1 /*
   2  * Copyright (c) 2000 World Wide Web Consortium,
   3  * (Massachusetts Institute of Technology, Institut National de
   4  * Recherche en Informatique et en Automatique, Keio University). All
   5  * Rights Reserved. This program is distributed under the W3C's Software
   6  * Intellectual Property License. This program is distributed in the
   7  * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
   8  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
   9  * PURPOSE.
  10  * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
  11  */
  12
  13 package org.w3c.dom;
  14
  15 /**
  16  * Objects implementing the <code>NamedNodeMap</code> interface are used to
  17  * represent collections of nodes that can be accessed by name. Note that
  18  * <code>NamedNodeMap</code> does not inherit from <code>NodeList</code>;
  19  * <code>NamedNodeMaps</code> are not maintained in any particular order.
  20  * Objects contained in an object implementing <code>NamedNodeMap</code> may
  21  * also be accessed by an ordinal index, but this is simply to allow
  22  * convenient enumeration of the contents of a <code>NamedNodeMap</code>,
  23  * and does not imply that the DOM specifies an order to these Nodes.
  24  * <p><code>NamedNodeMap</code> objects in the DOM are live.
  25  * <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>.
  26  */
  27 public interface NamedNodeMap {
  28     /**
  29      * Retrieves a node specified by name.
  30      * @param nameThe <code>nodeName</code> of a node to retrieve.
  31      * @return A <code>Node</code> (of any type) with the specified
  32      *   <code>nodeName</code>, or <code>null</code> if it does not identify
  33      *   any node in this map.
  34      */
  35     public Node getNamedItem(String name);
  36
  37     /**
  38      * Adds a node using its <code>nodeName</code> attribute. If a node with
  39      * that name is already present in this map, it is replaced by the new
  40      * one.
  41      * <br>As the <code>nodeName</code> attribute is used to derive the name
  42      * which the node must be stored under, multiple nodes of certain types
  43      * (those that have a "special" string value) cannot be stored as the
  44      * names would clash. This is seen as preferable to allowing nodes to be
  45      * aliased.
  46      * @param argA node to store in this map. The node will later be
  47      *   accessible using the value of its <code>nodeName</code> attribute.
  48      * @return If the new <code>Node</code> replaces an existing node the
  49      *   replaced <code>Node</code> is returned, otherwise <code>null</code>
  50      *   is returned.
  51      * @exception DOMException
  52      *   WRONG_DOCUMENT_ERR: Raised if <code>arg</code> was created from a
  53      *   different document than the one that created this map.
  54      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
  55      *   <br>INUSE_ATTRIBUTE_ERR: Raised if <code>arg</code> is an
  56      *   <code>Attr</code> that is already an attribute of another
  57      *   <code>Element</code> object. The DOM user must explicitly clone
  58      *   <code>Attr</code> nodes to re-use them in other elements.
  59      */
  60     public Node setNamedItem(Node arg)
  61                              throws DOMException;
  62
  63     /**
  64      * Removes a node specified by name. When this map contains the attributes
  65      * attached to an element, if the removed attribute is known to have a
  66      * default value, an attribute immediately appears containing the
  67      * default value as well as the corresponding namespace URI, local name,
  68      * and prefix when applicable.
  69      * @param nameThe <code>nodeName</code> of the node to remove.
  70      * @return The node removed from this map if a node with such a name
  71      *   exists.
  72      * @exception DOMException
  73      *   NOT_FOUND_ERR: Raised if there is no node named <code>name</code> in
  74      *   this map.
  75      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
  76      */
  77     public Node removeNamedItem(String name)
  78                                 throws DOMException;
  79
  80     /**
  81      * Returns the <code>index</code>th item in the map. If <code>index</code>
  82      * is greater than or equal to the number of nodes in this map, this
  83      * returns <code>null</code>.
  84      * @param indexIndex into this map.
  85      * @return The node at the <code>index</code>th position in the map, or
  86      *   <code>null</code> if that is not a valid index.
  87      */
  88     public Node item(int index);
  89
  90     /**
  91      * The number of nodes in this map. The range of valid child node indices
  92      * is <code>0</code> to <code>length-1</code> inclusive.
  93      */
  94     public int getLength();
  95
  96     /**
  97      * Retrieves a node specified by local name and namespace URI. HTML-only
  98      * DOM implementations do not need to implement this method.
  99      * @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 }