001: /*
002: * Copyright 2006 Google Inc.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License. You may obtain a copy of
006: * the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013: * License for the specific language governing permissions and limitations under
014: * the License.
015: */
016: package com.google.gwt.xml.client;
017:
018: /*
019: * Implementation notes: Safari does not support mutable attributes, so no
020: * mechanism for creating Attr objects has been supplied. IE does not support
021: * any of the xxxNS operations, so they have been omitted as well. IE does not
022: * use importNode to copy nodes from one document into another.
023: */
024: /**
025: * <code>Document</code> objects represent XML documents. Each
026: * <code>Document</code> can contain exactly one <code>Element</code> node,
027: * and any number of other node types.
028: */
029: public interface Document extends Node {
030: /**
031: * This method creates a new <code>CDATASection</code>.
032: *
033: * @param data the data of the new <code>CDATASection</code>
034: * @return the newly created <code>CDATASection</code>
035: */
036: public CDATASection createCDATASection(String data);
037:
038: /**
039: * This method creates a new <code>Comment</code>.
040: *
041: * @param data the data of the new <code>Comment</code>
042: * @return the newly created <code>Comment</code>
043: */
044: public Comment createComment(String data);
045:
046: /**
047: * This method creates a new <code>DocumentFragment</code>.
048: *
049: * @return the newly created <code>DocumentFragment</code>
050: */
051: public DocumentFragment createDocumentFragment();
052:
053: /**
054: * This method creates a new <code>Element</code>.
055: *
056: * @param tagName the tag name of the new <code>Element</code>
057: * @return the newly created <code>Element</code>
058: */
059: public Element createElement(String tagName);
060:
061: /**
062: * This method creates a new <code>ProcessingInstruction</code>.
063: *
064: * @param target the target of the new <code>ProcessingInstruction</code>
065: * @param data the data of the new <code>ProcessingInstruction</code>
066: * @return the newly created <code>ProcessingInstruction</code>
067: */
068: public ProcessingInstruction createProcessingInstruction(
069: String target, String data);
070:
071: /**
072: * This method creates a new <code>Text</code>.
073: *
074: * @param data the data of the new <code>Text</code>
075: * @return the newly created <code>Text</code>
076: */
077: public Text createTextNode(String data);
078:
079: /**
080: * This method retrieves the document element. Each document has at most one
081: * <code>Element</code> as its direct child, and this node is returned if it
082: * exists. <code>null</code> is returned otherwise.
083: *
084: * @return the document element of this <code>Document</code>
085: */
086: public Element getDocumentElement();
087:
088: /**
089: * This method retrieves the unique descendent elements which has an id of
090: * <code>elementId</code>. Note the attribute which is used as an ID must
091: * be supplied in the DTD of the document. It is not sufficient to give the
092: * <code>Element</code> to be retrieved an attribute named 'id'.
093: *
094: * @return the <code>Element</code> which has an id of
095: * <code>elementId</code> and belongs to this <code>Document</code>
096: */
097: public Element getElementById(String elementId);
098:
099: /**
100: * This method retrieves any descendent elements which have a tag name of
101: * <code>tagname</code>.
102: *
103: * @return the <code>NodeList</code> of elements which has a tag name of
104: * <code>tagname</code> and belong to this <code>Document</code>
105: */
106: public NodeList getElementsByTagName(String tagname);
107:
108: /**
109: * This method imports a node into the current <code>Document</code>.
110: *
111: * @param deep whether to recurse to children
112: * @return the node <code>Node</code> imported
113: */
114: public Node importNode(Node importedNode, boolean deep);
115: }
|