org.apache.xerces.dom
Class NamedNodeMapImpl

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

public class NamedNodeMapImpl

extends java.lang.Object

implements NamedNodeMap, java.io.Serializable

NamedNodeMaps represent collections of Nodes that can be accessed by name. They're currently used in two modes. Attributes are placed in a NamedNodeMap rather than being children of the node they describe. On the other hand Entity and Notation appear both in the NamedNodeMap _and_ as kids of the DocumentType, requiring some additional logic so these are maintained as "live views" of each other.

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 "nodes" Vector is kept sorted by this key to speed lookup, ad make it easier to reconcile with the defaults. 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 Vector 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.

As of REC-DOM-Level-1-19981001, Entities and Notations are no longer shadowed as children of DocumentType.

This implementation includes support for DOM Level 2 Mutation Events. If the static boolean NodeImpl.MUTATIONEVENTS is not set true, that support is disabled and can be optimized out to reduce code size.

Since:

PR-DOM-Level-1-19980818.

Version:

See Also:

Serialized Form

Field Summary

protected int	changes Changes.
protected NamedNodeMapImpl	defaults Default nodes.
protected ElementImpl	element Element.
protected int	lastDefaultsChanges Last defaults changes.
protected java.util.Vector	nodes Nodes.
protected Document	ownerDocument Owner document.
protected boolean	readOnly Read-only.

Constructor Summary

protected	NamedNodeMapImpl(Document ownerDoc, NamedNodeMapImpl defaults) Constructs a named node map.
protected	NamedNodeMapImpl(ElementImpl element, NamedNodeMapImpl defaults) Constructs a named node map.

Method Summary

NamedNodeMapImpl	cloneMap() Cloning a NamedNodeMap is a DEEP OPERATION; it always clones all the nodes contained in the map.
int	getLength() Report how many nodes are currently stored in this NamedNodeMap.
Node	getNamedItem(java.lang.String name) Retrieve a node by name.
Node	getNamedItemNS(java.lang.String namespaceURI, java.lang.String localName) Introduced in DOM Level 2.
Node	item(int index) Retrieve an item from the map by 0-based index.
protected void	reconcileDefaults() Subroutine: If this NamedNodeMap is backed by a "defaults" map (eg, if it's being used for Attributes of an XML file validated against a DTD), we need to deal with the risk that those defaults might have changed.
Node	removeNamedItem(java.lang.String name) Removes a node specified by name.
Node	removeNamedItemNS(java.lang.String namespaceURI, java.lang.String name) Introduced in DOM Level 2.
Node	setNamedItem(Node arg) Adds a node using its nodeName attribute.
Node	setNamedItemNS(Node arg) Adds a node using its namespaceURI and localName.

Methods inherited from class java.lang.Object

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

Field Detail

nodes

protected java.util.Vector nodes

Nodes.

ownerDocument

protected Document ownerDocument

Owner document.

element

protected ElementImpl element

Element. Only named node maps holding attributes for elements have an element object. This value is here to support the Attr#getElement method and MutationEvent processing (DOM Level 2, 19 June 1999).

defaults

protected NamedNodeMapImpl defaults

Default nodes.

changes

protected int changes

Changes.

lastDefaultsChanges

protected int lastDefaultsChanges

Last defaults changes.

readOnly

protected boolean readOnly

Read-only.

Constructor Detail

NamedNodeMapImpl

protected NamedNodeMapImpl(Document ownerDoc,
                           NamedNodeMapImpl defaults)

Constructs a named node map.

NamedNodeMapImpl

protected NamedNodeMapImpl(ElementImpl element,
                           NamedNodeMapImpl defaults)

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).

COMPLICATION: In the case of attributes, the count has to include any defaults that may be inherited, yet not double-count when there is both a default and a specified value. Convolving the two lists is expensive, and for GC reasons we don't want to register with the DTD (it wouldn't know when to release us).

One solution is to go into the change-counter domain, as we did for DeepNodeList. Another is to accept the convolution, and count on the fact that our implementation is a sorted list to keep the cost managable... which works pretty well for getLength(), but makes item() expensive.

The ideal fix would be to rearchitect to eliminate integer indexing, but of course that wouldn't meet the spec!

Specified by:

getLength in interface NamedNodeMap

item

public Node item(int index)

Retrieve an item from the map by 0-based index.

Specified by:

item in interface 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.

getNamedItem

public Node getNamedItem(java.lang.String name)

Retrieve a node by name. If not explicitly defined, checks the defaults before giving up.

Specified by:

getNamedItem in interface NamedNodeMap

Parameters:

name - Name of a node to look up.

getNamedItemNS

public 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 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 Node setNamedItem(Node arg)
                  throws 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 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:

DOMException - The exception description.

See Also:

NamedNodeMap.setNamedItem(org.w3c.dom.Node)

setNamedItemNS

public Node setNamedItemNS(Node arg)
                    throws DOMException

Adds a node using its namespaceURI and localName.

Specified by:

setNamedItemNS in interface 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.

See Also:

NamedNodeMap.setNamedItem(org.w3c.dom.Node)

removeNamedItem

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

Description copied from interface: NamedNodeMap

Removes a node specified by name. A removed attribute may be known to have a default value when this map contains the attributes attached to an element, as returned by the attributes attribute of the Node interface. If so, 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 NamedNodeMap

Tags copied from interface: 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:

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 Node removeNamedItemNS(java.lang.String namespaceURI,
                              java.lang.String name)
                       throws DOMException

Introduced in DOM Level 2.

Removes a node specified by local name and namespace URI.

Specified by:

removeNamedItemNS in interface NamedNodeMap

Parameters:

namespaceURI - The namespace URI of the node to remove. When it is null or an empty string, this method behaves like removeNamedItem.

The - local name of the node to remove. When this NamedNodeMap contains the attributes attached to an element, as returned by the attributes attribute of the Node interface, if the removed attribute is known to have a default value, an attribute immediately appears containing the default value.

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.

cloneMap

public NamedNodeMapImpl cloneMap()

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

reconcileDefaults

protected void reconcileDefaults()

Subroutine: If this NamedNodeMap is backed by a "defaults" map (eg, if it's being used for Attributes of an XML file validated against a DTD), we need to deal with the risk that those defaults might have changed. Entries may have been added, changed, or removed, and if so we need to update our version of that information

Luckily, this currently applies _only_ to Attributes, which have a "specified" flag that allows us to distinguish which we set manually versus which were defaults... assuming that the defaults list is being maintained properly, of course.

Also luckily, The NameNodeMaps are maintained as sorted lists. This should keep the cost of convolving the two lists managable... not wonderful, but at least more like 2N than N**2..

Finally, to avoid doing the convolution except when there are actually changes to be absorbed, I've made the Map aware of whether or not its defaults Map has changed. This is not 110% reliable, but it should work under normal circumstances, especially since the DTD is usually relatively static information.

Note: This is NON-DOM implementation, though used to support behavior that the DOM requires.