/*

* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

*

*/

package org.w3c.dom;

/**

 * The Document interface represents an XML Document.

 *

 * <p>This interface is a subset of the Document interface defined

 * in the <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/idl-definitions.html">

 * DOM Level 3 Core</a>.</p>

 *

 *

 * <p>Note the behavior of the following methods from the

 * <code>Node</code> interface when called on a <code>Document</code>

 * object:

 *

 * <ul>

 * <li>getParentNode returns <code>null</code></li>

 * <li>appendChild throws <code>HIERARCHY_REQUEST_ERR</code></li>

 * <li>insertBefore throws <code>HIERARCHY_REQUEST_ERR</code></li>

 * <li>removeChild throws <code>NOT_SUPPORTED_ERR</code></li>

 * </ul>

 * </p>

 *

 */

public interface Document extends Node

{

    /**

     * Create a new <code>Element</code> based on the specified

     * (qualified) SVG tag name. This JSR does not require multiple

     * namespaces and may throw a <code>DOMException</code> with a

     * code of <code>NOT_SUPPORTED_ERR</code> if the URI is not the

     * SVG namespace URI, or if the specified name is not a valid SVG

     * Tiny element name. Only the following elements must be supported:

     * <rect>, <circle>, <ellipse>, <line>,

     * <path> <use> <image> <text>,

     * <a> and <g>.

     *

     * @param namespaceURI the namespace uri for the newly created

     * element. This should always be the SVG namespace URI "http://www.w3.org/2000/svg".

     * @param qualifiedName the qualified name for the newly created

     * element (For example: "rect", to create a <rect> element)

     *

     * @return the newly created SVG Element.

     *

     * @throws DOMException NOT_SUPPORTED_ERR if the type of element is

     * not supported by the implementation. JSR 226 only requires creation

     * support for some of the SVG namespace elements and only for a limited

     * number of local names in that namespace (see above documentation).Therefore, in

     * a conformant JSR 226 implementation, trying to create elements with a namespace

     * URIs other than the SVG namespace URI and with a qualified name not in the list

     * of required qualified names may result in this exception being thrown.

     * @throws NullPointerException if <code>namespaceURI</code> or

     * <code>qualifiedName</code> is null.

     *

     */

    public Element createElementNS(String namespaceURI, String qualifiedName)

    throws DOMException;

    /**

     * Return a child element of this document Node which corresponds to the top-most

     * tag in XML file. For SVG files it must be <code>SVGSVGElement</code>, but return

     * type is Element for DOM Core compatibility and to allow for future extensions.

     *

     * @return the root <code>Element</code> associated with this

     * document.

     * @throws SecurityException if the application does not have the necessary privilege rights

     * to access this (SVG) content.

     */

    public Element getDocumentElement();

    /**

     * Return the <code>Element</code> in the current document with

     * the given unique ID. If no such element exists, this returns null.

     *

     * @param id the ID of the object to be retrieved.

     * @return the Element that matches with the given ID or

     * <code>null</code> if the ID is not present.

     *

     * @throws NullPointerException if id is null

     * @throws SecurityException if the application does not have the necessary privilege rights

     * to access this (SVG) content.

     */

    public Element getElementById(String id);

}