org.w3c.dom.NamedNodeMap Maven / Gradle / Ivy
/*
* Copyright (C) 2005 by Quentin Anciaux
*
* This library is free software; you can redistribute it and/or modify it
* under the terms of the GNU Library General Public License as published by
* the Free Software Foundation; either version 2 of the License, or (at your
* option) any later version.
*
* This library is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License
* for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this library; if not, write to the Free Software Foundation,
* Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*
* @author Quentin Anciaux
*/
package org.w3c.dom;
/**
* Objects implementing the NamedNodeMap interface are used to
* represent collections of nodes that can be accessed by name. Note that
* NamedNodeMap does not inherit from NodeList;
* NamedNodeMaps are not maintained in any particular order.
* Objects contained in an object implementing NamedNodeMap may
* also be accessed by an ordinal index, but this is simply to allow
* convenient enumeration of the contents of a NamedNodeMap, and
* does not imply that the DOM specifies an order to these Nodes.
*
*
* NamedNodeMap objects in the DOM are live.
*
*
*
* See also the Document
* Object Model (DOM) Level 3 Core Specification .
*
*/
public interface NamedNodeMap {
/**
* Retrieves a node specified by name.
*
* @param name The nodeName of a node to retrieve.
*
* @return A Node (of any type) with the specified
* nodeName, or null if it does not
* identify any node in this map.
*/
public Node getNamedItem(String name);
/**
* Adds a node using its nodeName attribute. If a node with
* that name is already present in this map, it is replaced by the new
* one. Replacing a node by itself has no effect.
* 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.
*
* @param arg A node to store in this map. The node will later be
* accessible using the value of its nodeName
* attribute.
*
* @return If the new Node replaces an existing node the
* replaced Node is returned, otherwise
* null is returned.
*
* @exception 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.
*/
public Node setNamedItem(Node arg)
throws DOMException;
/**
* 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.
*
* @param name The nodeName of the node to remove.
*
* @return The node removed from this map if a node with such a name
* exists.
*
* @exception 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.
*/
public Node removeNamedItem(String name)
throws DOMException;
/**
* Returns the index th item in the map. If index
* is greater than or equal to the number of nodes in this map, this
* returns null.
*
* @param index Index into this map.
*
* @return The node at the index th position in the map, or
* null if that is not a valid index.
*/
public Node item(int index);
/**
* The number of nodes in this map. The range of valid child node indices
* is 0 to length-1 inclusive.
*
* @return DOCUMENT ME!
*/
public int getLength();
/**
* Retrieves a node specified by local name and namespace URI.
* Per [ XML
* Namespaces ] , applications must use the value null as the
* namespaceURI parameter for methods if they wish to have no namespace.
*
* @param namespaceURI The namespace URI of the node to retrieve.
* @param localName The local name of the node to retrieve.
*
* @return A Node (of any type) with the specified local name
* and namespace URI, or null if they do not identify
* any node in this map.
*
* @exception DOMException 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 ]).
*
* @since DOM Level 2
*/
public Node getNamedItemNS(
String namespaceURI,
String localName
)
throws DOMException;
/**
* Adds a node using its namespaceURI and
* localName. If a node with that namespace URI and that
* local name is already present in this map, it is replaced by the new
* one. Replacing a node by itself has no effect.
* Per [ XML
* Namespaces ] , applications must use the value null as the
* namespaceURI parameter for methods if they wish to have no namespace.
*
* @param arg A node to store in this map. The node will later be
* accessible using the value of its namespaceURI and
* localName attributes.
*
* @return If the new Node replaces an existing node the
* replaced Node is returned, otherwise
* null is returned.
*
* @exception 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 ]).
*
* @since DOM Level 2
*/
public Node setNamedItemNS(Node arg)
throws DOMException;
/**
* Removes a node specified by local name and namespace URI. 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.
* Per [ XML
* Namespaces ] , applications must use the value null as the
* namespaceURI parameter for methods if they wish to have no namespace.
*
* @param namespaceURI The namespace URI of the node to remove.
* @param localName The local name of the node to remove.
*
* @return The node removed from this map if a node with such a local name
* and namespace URI exists.
*
* @exception 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 ]).
*
* @since DOM Level 2
*/
public Node removeNamedItemNS(
String namespaceURI,
String localName
)
throws DOMException;
}