user/src/com/google/gwt/xml/client/Document.java

/*
 * Copyright 2006 Google Inc.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.gwt.xml.client;

/*
 * Implementation notes:
 * Safari does not support mutable attributes, so no mechanism for creating Attr
 *  objects has been supplied.  IE does not support any of the xxxNS operations,
 *  so they have been omitted as well. IE does not use importNode to copy nodes
 * from one document into another.  
 */
/**
 * <code>Document</code> objects represent XML documents.  Each 
 * <code>Document</code> can contain exactly one <code>Element</code> node, and 
 * any number of other node types.  
 */
public interface Document extends Node  {
  /**
   * This method retrieves the document element.  Each document has at most one
   * <code>Element</code> as its direct child, and this node is returned if it 
   * exists.  <code>null</code> is returned otherwise. 
   * 
   * @return the document element of this <code>Document</code>
   */  
  public Element getDocumentElement();

  /**
   * This method retrieves any descendent elements which have a tag name of 
   * <code>tagname</code>. 
   * 
   * @return the <code>NodeList</code> of elements which has a tag name of 
   * <code>tagname</code> and belong to this <code>Document</code>
   */  
  public NodeList getElementsByTagName(String tagname);

  /**
   * This method retrieves the unique descendent elements which has an id of 
   * <code>elementId</code>.  Note the attribute which is used as an ID must
   * be supplied in the DTD of the document.  It is not sufficient to give the 
   * <code>Element</code> to be retrieved an attribute named 'id'.
   * 
   * @return the <code>Element</code> which has an id of 
   * <code>elementId</code> and belongs to this <code>Document</code>
   */  
  public Element getElementById(String elementId);

  /**
   * This method creates a new <code>Element</code>. 
   * 
   * @param tagName the tag name of the new <code>Element</code>
   * @return the newly created <code>Element</code>
   */  
  public Element createElement(String tagName);

  /**
   * This method creates a new <code>DocumentFragment</code>.  
   * 
   * @return the newly created <code>DocumentFragment</code>
   */  
  public DocumentFragment createDocumentFragment();

  /**
   * This method creates a new <code>Text</code>. 
   * 
   * @param data the data of the new <code>Text</code>
   * @return the newly created <code>Text</code>
   */  
  public Text createTextNode(String data);

  /**
   * This method creates a new <code>Comment</code>. 
   * 
   * @param data the data of the new <code>Comment</code>
   * @return the newly created <code>Comment</code>
   */  
  public Comment createComment(String data);

  /**
   * This method creates a new <code>CDATASection</code>. 
   * 
   * @param data the data of the new <code>CDATASection</code>
   * @return the newly created <code>CDATASection</code>
   */  
  public CDATASection createCDATASection(String data);

  /**
   * This method creates a new <code>ProcessingInstruction</code>. 
   * 
   * @param target the target of the new <code>ProcessingInstruction</code>
   * @param data the data of the new <code>ProcessingInstruction</code>
   * @return the newly created <code>ProcessingInstruction</code>
   */  
  public ProcessingInstruction createProcessingInstruction(String target, String data);

  /**
   * This method imports a node into the current <code>Document</code>.  
   * 
   * @param deep whether to recurse to children
   * @return the node <code>Node</code> imported
   */  
  public Node importNode(Node importedNode, boolean deep);
}