com.google.gwt.xml.client.Document Maven / Gradle / Ivy

/*
 * Copyright 2008 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.
 */
/**
 * Document objects represent XML documents. Each
 * Document can contain exactly one Element node,
 * and any number of other node types.
 */
public interface Document extends Node {
  /**
   * This method creates a new CDATASection.
   * 
   * @param data the data of the new CDATASection
   * @return the newly created CDATASection
   */
  CDATASection createCDATASection(String data);

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

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

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

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

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

  /**
   * This method retrieves the document element. Each document has at most one
   * Element as its direct child, and this node is returned if it
   * exists. null is returned otherwise.
   * 
   * @return the document element of this Document
   */
  Element getDocumentElement();

  /**
   * This method retrieves the unique descendent elements which has an id of
   * elementId. 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
   * Element to be retrieved an attribute named 'id'.
   * 
   * @return the Element which has an id of
   *         elementId and belongs to this Document
   */
  Element getElementById(String elementId);

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

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