NamedNodeMapImpl (Xerces2 Implementation)
Date: 2014-11-21

org.apache.xerces.dom

## Class NamedNodeMapImpl

- java.lang.Object
- - org.apache.xerces.dom.NamedNodeMapImpl

- All Implemented Interfaces:
    java.io.Serializable, org.w3c.dom.NamedNodeMap
  Direct Known Subclasses:
    AttributeMap

      public class NamedNodeMapImpl
      extends java.lang.Object
      implements org.w3c.dom.NamedNodeMap, java.io.Serializable

  NamedNodeMaps represent collections of Nodes that can be accessed by name. Entity and Notation nodes are stored in NamedNodeMaps attached to the DocumentType. Attributes are placed in a NamedNodeMap attached to the elem they're related too. However, because attributes require more work, such as firing mutation events, they are stored in a subclass of NamedNodeMapImpl.

  Only one Node may be stored per name; attempting to store another will replace the previous value.

  NOTE: The "primary" storage key is taken from the NodeName attribute of the node. The "secondary" storage key is the namespaceURI and localName, when accessed by DOM level 2 nodes. All nodes, even DOM Level 2 nodes are stored in a single ArrayList sorted by the primary "nodename" key.

  NOTE: item()'s integer index does _not_ imply that the named nodes must be stored in an array; that's only an access method. Note too that these indices are "live"; if someone changes the map's contents, the indices associated with nodes may change.

  Since:
    PR-DOM-Level-1-19980818.
  Version:
    $Id: NamedNodeMapImpl.java 652698 2008-05-01 22:38:53Z mrglavas $
  See Also:
    Serialized Form

  # INTERNAL:

    Usage of this class is not supported. It may be altered or removed at any time.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static short` | `CHANGED`
    `protected short` | `flags`
    `protected static short` | `HASDEFAULTS`
    `protected java.util.List` | `nodes` Nodes.
    `protected NodeImpl` | `ownerNode`
    `protected static short` | `READONLY`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `NamedNodeMapImpl(NodeImpl ownerNode)` Constructs a named node map.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected int` | `addItem(org.w3c.dom.Node arg)`
    `protected void` | `cloneContent(NamedNodeMapImpl srcmap)`
    `protected java.util.ArrayList` | `cloneMap(java.util.ArrayList list)` NON-DOM: copy content of this map into the specified ArrayList
    `NamedNodeMapImpl` | `cloneMap(NodeImpl ownerNode)` Cloning a NamedNodeMap is a DEEP OPERATION; it always clones all the nodes contained in the map.
    `protected int` | `findNamePoint(java.lang.String name, int start)` Subroutine: Locate the named item, or the point at which said item should be added.
    `protected int` | `findNamePoint(java.lang.String namespaceURI, java.lang.String name)` This findNamePoint is for DOM Level 2 Namespaces.
    `protected java.lang.Object` | `getItem(int index)`
    `int` | `getLength()` Report how many nodes are currently stored in this NamedNodeMap.
    `org.w3c.dom.Node` | `getNamedItem(java.lang.String name)` Retrieve a node by name.
    `protected int` | `getNamedItemIndex(java.lang.String namespaceURI, java.lang.String localName)`
    `org.w3c.dom.Node` | `getNamedItemNS(java.lang.String namespaceURI, java.lang.String localName)` Introduced in DOM Level 2.
    `org.w3c.dom.Node` | `item(int index)` Retrieve an item from the map by 0-based index.
    `protected boolean` | `precedes(org.w3c.dom.Node a, org.w3c.dom.Node b)`
    `void` | `removeAll()` NON-DOM remove all elements from this map
    `protected void` | `removeItem(int index)` NON-DOM: Remove attribute at specified index
    `org.w3c.dom.Node` | `removeNamedItem(java.lang.String name)` Removes a node specified by name.
    `org.w3c.dom.Node` | `removeNamedItemNS(java.lang.String namespaceURI, java.lang.String name)` Introduced in DOM Level 2.
    `org.w3c.dom.Node` | `setNamedItem(org.w3c.dom.Node arg)` Adds a node using its nodeName attribute.
    `org.w3c.dom.Node` | `setNamedItemNS(org.w3c.dom.Node arg)` Adds a node using its namespaceURI and localName.
    `protected void` | `setOwnerDocument(CoreDocumentImpl doc)` NON-DOM set the ownerDocument of this node, and the attributes it contains

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### flags

          protected short flags

    - #### READONLY

          protected static final short READONLY

      See Also:
        Constant Field Values

    - #### CHANGED

          protected static final short CHANGED

      See Also:
        Constant Field Values

    - #### HASDEFAULTS

          protected static final short HASDEFAULTS

      See Also:
        Constant Field Values

    - #### nodes

          protected java.util.List nodes

      Nodes.

    - #### ownerNode

          protected NodeImpl ownerNode

  - ### Constructor Detail

    - #### NamedNodeMapImpl

          protected NamedNodeMapImpl(NodeImpl ownerNode)

      Constructs a named node map.

  - ### Method Detail

    - #### getLength

          public int getLength()

      Report how many nodes are currently stored in this NamedNodeMap. Caveat: This is a count rather than an index, so the highest-numbered node at any time can be accessed via item(getLength()-1).
      Specified by:
        `getLength` in interface `org.w3c.dom.NamedNodeMap`

    - #### item

          public org.w3c.dom.Node item(int index)

      Retrieve an item from the map by 0-based index.
      Specified by:
        `item` in interface `org.w3c.dom.NamedNodeMap`
      Parameters:
        `index` - Which item to retrieve. Note that indices are just an enumeration of the current contents; they aren't guaranteed to be stable, nor do they imply any promises about the order of the NamedNodeMap's contents. In other words, DO NOT assume either that index(i) will always refer to the same entry, or that there is any stable ordering of entries... and be prepared for double-reporting or skips as insertion and deletion occur.
      Returns:
        the node which currenly has the specified index, or null if index is greater than or equal to getLength().

    - #### getNamedItem

          public org.w3c.dom.Node getNamedItem(java.lang.String name)

      Retrieve a node by name.
      Specified by:
        `getNamedItem` in interface `org.w3c.dom.NamedNodeMap`
      Parameters:
        `name` - Name of a node to look up.
      Returns:
        the Node (of unspecified sub-class) stored with that name, or null if no value has been assigned to that name.

    - #### getNamedItemNS

          public org.w3c.dom.Node getNamedItemNS(java.lang.String namespaceURI,
                                        java.lang.String localName)

      Introduced in DOM Level 2.

      Retrieves a node specified by local name and namespace URI.

      Specified by:
        `getNamedItemNS` in interface `org.w3c.dom.NamedNodeMap`
      Parameters:
        `namespaceURI` - The namespace URI of the node to retrieve. When it is null or an empty string, this method behaves like getNamedItem.
        `localName` - The local name of the node to retrieve.
      Returns:
        Node A Node (of any type) with the specified name, or null if the specified name did not identify any node in the map.

    - #### setNamedItem

          public org.w3c.dom.Node setNamedItem(org.w3c.dom.Node arg)
                                        throws org.w3c.dom.DOMException

      Adds a node using its nodeName attribute. As the nodeName attribute is used to derive the name which the node must be stored under, multiple nodes of certain types (those that have a "special" string value) cannot be stored as the names would clash. This is seen as preferable to allowing nodes to be aliased.
      Specified by:
        `setNamedItem` in interface `org.w3c.dom.NamedNodeMap`
      Parameters:
        `arg` - A node to store in a named node map. The node will later be accessible using the value of the namespaceURI and localName attribute of the node. If a node with those namespace URI and local name is already present in the map, it is replaced by the new one.
      Returns:
        If the new Node replaces an existing node the replaced Node is returned, otherwise null is returned.
      Throws:
        `org.w3c.dom.DOMException` - The exception description.
      See Also:
        `NamedNodeMap.setNamedItem(org.w3c.dom.Node)`

    - #### setNamedItemNS

          public org.w3c.dom.Node setNamedItemNS(org.w3c.dom.Node arg)
                                          throws org.w3c.dom.DOMException

      Adds a node using its namespaceURI and localName.
      Specified by:
        `setNamedItemNS` in interface `org.w3c.dom.NamedNodeMap`
      Parameters:
        `arg` - A node to store in a named node map. The node will later be accessible using the value of the namespaceURI and localName attribute of the node. If a node with those namespace URI and local name is already present in the map, it is replaced by the new one.
      Returns:
        If the new Node replaces an existing node the replaced Node is returned, otherwise null is returned.
      Throws:
        `org.w3c.dom.DOMException` - WRONG_DOCUMENT_ERR: Raised if `arg` was created from a different document than the one that created this map.
        NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
        INUSE_ATTRIBUTE_ERR: Raised if `arg` is an `Attr` that is already an attribute of another `Element` object. The DOM user must explicitly clone `Attr` nodes to re-use them in other elements.
        HIERARCHY_REQUEST_ERR: Raised if an attempt is made to add a node doesn't belong in this NamedNodeMap. Examples would include trying to insert something other than an Attr node into an Element's map of attributes, or a non-Entity node into the DocumentType's map of Entities.
        NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
      See Also:
        `NamedNodeMap.setNamedItem(org.w3c.dom.Node)`

    - #### removeNamedItem

          public org.w3c.dom.Node removeNamedItem(java.lang.String name)
                                           throws org.w3c.dom.DOMException

      Description copied from interface: `org.w3c.dom.NamedNodeMap`
      Removes a node specified by name. When this map contains the attributes attached to an element, if the removed attribute is known to have a default value, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.
      Specified by:
        `removeNamedItem` in interface `org.w3c.dom.NamedNodeMap`
      Parameters:
        `name` - The `nodeName` of the node to remove.
      Returns:
        The node removed from this map if a node with such a name exists.
      Throws:
        `org.w3c.dom.DOMException` - NOT_FOUND_ERR: Raised if there is no node named `name` in this map.
        NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

    - #### removeNamedItemNS

          public org.w3c.dom.Node removeNamedItemNS(java.lang.String namespaceURI,
                                           java.lang.String name)
                                             throws org.w3c.dom.DOMException

      Introduced in DOM Level 2.

      Removes a node specified by local name and namespace URI.

      Specified by:
        `removeNamedItemNS` in interface `org.w3c.dom.NamedNodeMap`
      Parameters:
        `namespaceURI` - The namespace URI of the node to remove. When it is null or an empty string, this method behaves like removeNamedItem.
        `name` - The local name of the node to remove.
      Returns:
        Node The node removed from the map if a node with such a local name and namespace URI exists.
      Throws:
        `NOT_FOUND_ERR:` - Raised if there is no node named name in the map.
        `org.w3c.dom.DOMException` - NOT_FOUND_ERR: Raised if there is no node with the specified `namespaceURI` and `localName` in this map.
        NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
        NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

    - #### cloneMap

          public NamedNodeMapImpl cloneMap(NodeImpl ownerNode)

      Cloning a NamedNodeMap is a DEEP OPERATION; it always clones all the nodes contained in the map.

    - #### cloneContent

          protected void cloneContent(NamedNodeMapImpl srcmap)

    - #### setOwnerDocument

          protected void setOwnerDocument(CoreDocumentImpl doc)

      NON-DOM set the ownerDocument of this node, and the attributes it contains

    - #### findNamePoint

          protected int findNamePoint(java.lang.String name,
                          int start)

      Subroutine: Locate the named item, or the point at which said item should be added.
      Parameters:
        `name` - Name of a node to look up.
      Returns:
        If positive or zero, the index of the found item. If negative, index of the appropriate point at which to insert the item, encoded as -1-index and hence reconvertable by subtracting it from -1. (Encoding because I don't want to recompare the strings but don't want to burn bytes on a datatype to hold a flagged value.)

    - #### findNamePoint

          protected int findNamePoint(java.lang.String namespaceURI,
                          java.lang.String name)

      This findNamePoint is for DOM Level 2 Namespaces.

    - #### precedes

          protected boolean precedes(org.w3c.dom.Node a,
                         org.w3c.dom.Node b)

    - #### removeItem

          protected void removeItem(int index)

      NON-DOM: Remove attribute at specified index

    - #### getItem

          protected java.lang.Object getItem(int index)

    - #### addItem

          protected int addItem(org.w3c.dom.Node arg)

    - #### cloneMap

          protected java.util.ArrayList cloneMap(java.util.ArrayList list)

      NON-DOM: copy content of this map into the specified ArrayList
      Parameters:
        `list` - ArrayList to copy information into.
      Returns:
        A copy of this node named map

    - #### getNamedItemIndex

          protected int getNamedItemIndex(java.lang.String namespaceURI,
                              java.lang.String localName)

    - #### removeAll

          public void removeAll()

      NON-DOM remove all elements from this map

Copyright © 1999-2010 The Apache Software Foundation. All Rights Reserved.