1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 package org.w3c.dom;

    19 

    20 /**

    21  * The Document interface represents an XML Document.

    22  *

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

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

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

    26  *

    27  *

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

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

    30  * object:

    31  *

    32  * <ul>

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

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

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

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

    37  * </ul>

    38  * </p>

    39  *

    40  */

    41 public interface Document extends Node

    42 {

    43 

    44     /**

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

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

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

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

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

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

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

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

    53      * <a> and <g>.

    54      *

    55      * @param namespaceURI the namespace uri for the newly created

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

    57      * @param qualifiedName the qualified name for the newly created

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

    59      *

    60      * @return the newly created SVG Element.

    61      *

    62      * @throws DOMException NOT_SUPPORTED_ERR if the type of element is

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

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

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

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

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

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

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

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

    71      *

    72      */

    73     public Element createElementNS(String namespaceURI, String qualifiedName)

    74     throws DOMException;

    75 

    76     /**

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

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

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

    80      *

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

    82      * document.

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

    84      * to access this (SVG) content.

    85      */

    86 

    87     public Element getDocumentElement();

    88 

    89     /**

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

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

    92      *

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

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

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

    96      *

    97      * @throws NullPointerException if id is null

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

    99      * to access this (SVG) content.

   100      */

   101 

   102     public Element getElementById(String id);

   103 

   104 }

   105