Named node maps

In some circumstances, a set of nodes that have no particular ordering significance need to be grouped together. This applies to attributes and to entity and notation declarations. Attributes do have a real location, in the sense that they belong to a specific element instance, but their order of appearance within the start-tag is not significant. Likewise, entity declarations have an order in the data stream, but this order is not significant (beyond the fact that only the first occurrence of duplicate declarations is acted upon). While the location is not significant in these instances, the names of these items certainly is significant. Unique names are essential.

The NamedNodeMap interface is designed to contain nodes, in no particular order, that can be accessed by name. For this reason, the names must be unique within a NamedNodeMap object. This can be used to hold a set of attributes that belong to a given element, and sets of entity and notation declarations that belong to a document, as the following examples demonstrate:

NamedNodeMap elemAttributes = myElement.getAttributes();

NamedNodeMap docEntities = myDoc.getEntities();

NamedNodeMap docNotations = myDoc.getNotations();

The methods defined in this interface are:

Node  item(int index);
int   getLength( );
Node  getNamedItem(String nodeName);
Node  setNamedItem(Node theNode) throws DOMException;
Node  removeNamedItem(String nodeName)
                                 throws DOMException;

For example:

Extracting by name

Because nodes in these lists are distinguished by name, a method called getNamedItem is included. The following example extracts the security status of an element (the node is 'null' if the attribute is not present):

NamedNodeMap myMap = myElement.getAttributes();

Attr security = (Attr) myMap.getNamedItem("Security");
					

Removing and adding items

Nodes can be removed from and added to the list.

The removeNamedItem method removes the node with the given name from the list. However, it does not actually delete the node, but returns a reference to it for possible reuse elsewhere.

The setNamedItem method adds a given node to the list, but despite its name passes a node reference to the list, not the node name. This method is probably so named as a reminder that the operation will not succeed if there is a node with the same name already present in the list.

The following example demonstrates both methods, by first removing the Security attribute, then reinserting it into the list:

Node temp = myMap.removeNamedItem("Security");

myMap.setNamedItem(temp);

The setNamedItem method also returns a reference to the node just added, which can be useful when the node is added at the same time as it is created:

Node newNode =
   myMap.setNamedItem(myDoc.createAttribute("Added"));

Extracting without name

Although NamedNodeMap objects have an item method that works in the same way as in the NodeList interface, there is no equivalent significance to the item number. The getLength and item methods are included so that nodes can be selected even when their names are not known.

In the following example, all attributes are accessed, and their names are displayed:

Node aNode;

NamedNodeMap atts = myElement.getAttributes();

for( int i = 0; i < atts.getLength(); i++ )
{
  aNode = atts.item(i);

  System.out.println( aNode.getNodeName() );
}