home *** CD-ROM | disk | FTP | other *** search
/ Dynamic HTML in Action / Dynamicke-HTML-v-akci-covermount.bin / XML / PARSER / XMLINST.EXE / classes / com / ms / xml / om / Element.java < prev    next >
Encoding:
Java Source  |  1997-10-20  |  9.1 KB  |  298 lines
  1. /*
  2.  * @(#)Element.java 1.0 6/3/97
  3.  * 
  4.  * Copyright (c) 1997 Microsoft, Corp. All Rights Reserved.
  5.  * 
  6.  */
  7.  
  8. package com.ms.xml.om;
  9.  
  10. import com.ms.xml.util.Name;
  11. import com.ms.xml.util.Attributes;
  12. import com.ms.xml.util.XMLOutputStream;
  13.  
  14. import java.lang.String;
  15. import java.util.Enumeration;
  16. import java.io.IOException;
  17.  
  18. /**
  19.  * 
  20.  * This interface implements an Element object. Each XML tag in a document is represented by an Element object in
  21.  * the XML parse tree. The elements are named with a string, have 
  22.  * attributes, and can contain child nodes.
  23.  * <P>
  24.  * There are seven types of elements, DOCUMENT, ELEMENT, PCDATA, PI,
  25.  * META, COMMENT, and CDATA.
  26.  *
  27.  * @version 1.0, 6/3/97
  28.  */
  29. public interface Element
  30. {
  31. //  Types 0 through 4 match the element types exposed by the
  32. //  IDL interface to the C++ parser.
  33.  
  34.     /**
  35.      * A general container element having optional attributes
  36.      * and optional child elements.
  37.      */
  38.     static public final int ELEMENT = 0;
  39.     /**
  40.      * A text element that has no children or attributes and that
  41.      * contains parsed character data.
  42.      */
  43.     static public final int PCDATA = 1;
  44.     /**
  45.      * An XML comment ( <!-- ... --> ).
  46.      */
  47.     static public final int COMMENT = 2;
  48.     /**
  49.      * Reserved for use by the Document node only.
  50.      */
  51.     static public final int DOCUMENT = 3;
  52.     /**
  53.      * Reserved for use by the DTD node only.
  54.      */
  55.     static public final int DTD = 4;
  56.     /**
  57.      * A processing instruction node ( <? ... ?> ).
  58.      */
  59.     static public final int PI = 5;
  60.     /**
  61.      * Raw character data specified with special CDATA construct:
  62.      * <![CDATA[...]]>
  63.      * where ... can be anything except ]]>, including HTML tags. 
  64.      */
  65.     static public final int CDATA = 6;     
  66.     /**
  67.      * An entity node. 
  68.      */
  69.     static public final int ENTITY = 7;     
  70.     /**
  71.      * A notation node. 
  72.      */
  73.     static public final int NOTATION = 8;     
  74.     /**
  75.      * An element declaration node. 
  76.      */
  77.     static public final int ELEMENTDECL = 9;     
  78.     /**
  79.      * A namespace node that declares new namespaces in the element tree.
  80.      */
  81.     static public final int NAMESPACE = 10;
  82.     /**
  83.      * Entity reference nodes.
  84.      */
  85.     static public final int ENTITYREF = 11;
  86.     /**
  87.      * Ignorable white space between elements.
  88.      */
  89.     static public final int WHITESPACE = 12;
  90.     /**
  91.      * INCLUDE conditional section
  92.      */
  93.     static public final int INCLUDESECTION = 13;
  94.     /**
  95.      * IGNORE conditional section
  96.      */
  97.     static public final int IGNORESECTION = 14;
  98.  
  99.     /** 
  100.      * Retrieves the name of the tag as a string. The string
  101.      * will be in uppercase.
  102.      * 
  103.      * @return the tag name or null for DATA and PCDATA elements. 
  104.      */
  105.     public Name getTagName();
  106.  
  107.     /**
  108.      * Retrieves the type of the element.
  109.      * This is always one of the following values:
  110.      * <code>DOCUMENT</code>, <code>ELEMENT</code>, <code>PCDATA</code>, <code>PI</code>,
  111.      * <code>META</code>, <code>COMMENT</code>, or <code>CDATA</code>.
  112.      * 
  113.      * @return element type.
  114.      */    
  115.     public int getType();
  116.  
  117.      /** 
  118.      * Returns the non-marked-up text contained by this element.
  119.      * For text elements, this is the raw data.  For elements
  120.      * with child nodes, this traverses the entire subtree and
  121.      * appends the text for each terminal text element, effectively
  122.      * stripping out the XML markup for the subtree. For example,
  123.      * if the XML document contains the following:
  124.      * <xmp>
  125.      *      <AUTHOR>
  126.      *          <FIRST>William</FIRST>
  127.      *          <LAST>Shakespeare</LAST>
  128.      *      </AUTHOR>
  129.      * </xmp>
  130.      * <p><code>Document.getText</code> returns "William Shakespeare".
  131.      */
  132.     public String getText();
  133.     
  134.     /**
  135.      * Sets the text for this element. Only meaningful in 
  136.      * <code>CDATA</code>, <code>PCDATA</code>, and <code>COMMENT</code> nodes.
  137.      *
  138.      * @param text The text to set.
  139.       * @return No return value.
  140.      */    
  141.     public void setText(String text);
  142.  
  143.     /** 
  144.      * Retrieves the parent of this element. 
  145.      * Every element in the tree except the Document itself, has
  146.      * a parent.  
  147.      *
  148.      * @return the parent element or null if at the root of 
  149.      * the tree.
  150.      */
  151.     public Element getParent();
  152.  
  153.     /**
  154.      * Returns an enumeration of the children of this element.
  155.      * <code>Enumeration.nextElement</code> returns <code>Element</code> objects.
  156.      * 
  157.      * @return an enumeration of child objects. It must not return null. 
  158.      * See <code>EnumWrapper</code> for an easy way to return an empty enumeration.
  159.      */
  160.     public Enumeration getElements();
  161.  
  162.     /**
  163.      * Returns an element collection of the children of this element.
  164.      * It must not return null. See <code>EnumWrapper</code> for an emptyEnumeration. 
  165.      * @return ElementCollection of child objects.
  166.      */
  167.     public ElementCollection getChildren();
  168.  
  169.     /**
  170.      * Retrieves the number of child elements.
  171.      * @return the number of child elements.
  172.      */
  173.     public int numElements();
  174.  
  175.     /**
  176.      * Adds a child to this element. Any element can only
  177.      * have one parent element and so the previous parent will lose this child
  178.      * from its subtree.  
  179.      *
  180.      * @param elem  The element to add.      
  181.      * The child element becomes the last element if <i>after</i> is null.
  182.      * The child is added to the beginning of the list if <i>after</i> is this object.
  183.      * @param after The element after which to add it. 
  184.       * @return No return value.
  185.      */
  186.     public void addChild(Element elem, Element after);
  187.     /**
  188.      * Adds a child to this element. 
  189.      * @param elem The element to add.
  190.      * @param pos  The position to add this element (calling <code>getChild(pos)</code> 
  191.      * will return this element). If <i>pos</i> is less than 0, <i>elem</i> becomes 
  192.      * the new last element.
  193.      * @param reserved The reserved parameter.
  194.       * @return No return value.
  195.      */
  196.     public void addChild(Element elem, int pos, int reserved);
  197.  
  198.      /**
  199.       * Retrieves the child element by index.
  200.       * @param index The index of the child element.
  201.       * @return null if there is no child by that index.
  202.       */   
  203.     public Element getChild(int index);
  204.     
  205.      /**
  206.       * Removes a child element from the tree.
  207.       *
  208.       * @param elem  The element to remove.
  209.       */   
  210.     public void removeChild(Element elem);
  211.     
  212.     /**
  213.      * Retrieves an enumeration for the element attributes.
  214.      * 
  215.      * The enumeration returns <code>Attribute</code> objects.
  216.      * @return the enumeration. It must not return null (see <code>EnumWrapper</code>
  217.      * for returning empty enumerations).
  218.      * @see Attribute
  219.      */
  220.     public Enumeration getAttributes();
  221.  
  222.     /**
  223.      * Retrieves the number of attributes.
  224.      * @return the number of attributes.
  225.      */
  226.     public int numAttributes();
  227.  
  228.     /**
  229.      * Retrieves an attribute's value given its name.
  230.      * @param name The name of the attribute.
  231.      * @return the value of the attribute 
  232.      * or null if the attribute is not found.
  233.      */    
  234.     public Object getAttribute(String name);
  235.     /**
  236.      * Retrieves an attribute's value given its name.
  237.      * @param name The name of the attribute.
  238.      * @return the value of the attribute 
  239.      * or null if the attribute is not found.
  240.      */    
  241.     public Object getAttribute(Name n);
  242.     
  243.     /**
  244.      * Sets the attribute of this element.    
  245.      *
  246.      * @param name  The attribute name.
  247.      * @param value The attribute value.
  248.      */    
  249.     public void setAttribute(String name, Object value);
  250.     /**
  251.      * Sets the attribute of this element.    
  252.      *
  253.      * @param name  The attribute name.
  254.      * @param value The attribute value.
  255.      */    
  256.     public void setAttribute(Name name, Object value);
  257.  
  258.     
  259.     /**
  260.      * Deletes an attribute from an element.
  261.      * @param name The attribute to delete.
  262.       * @return No return value.
  263.      */    
  264.     public void removeAttribute(String name);
  265.     /**
  266.      * Deletes an attribute from an element.
  267.      * @param name The attribute to delete.
  268.       * @return No return value.
  269.      */    
  270.     public void removeAttribute(Name name);
  271.  
  272.     /**
  273.      * Sets the parent of this element.
  274.      * @param parent The element to set as parent.
  275.       * @return No return value.
  276.      */
  277.     public void setParent(Element parent);
  278.  
  279.     /**
  280.      * Returns the XML-DATA specification for the DTD element.
  281.      * (Only applies to ElementDecl and Entity nodes).
  282.      * This is DTD information represented in an XML Object Model.
  283.      * See <a href="http://www.microsoft.com/standards/xml/xmldata.htm">Specification for XML-Data</a> for details.
  284.      */
  285.     public Element toSchema(); 
  286.  
  287.     /**
  288.      * Saves this element.
  289.      * @param o The output stream to save to.
  290.      * @exception IOException if there is a problem saving the output.
  291.       * @return No return value.
  292.      */
  293.     public void save(XMLOutputStream o) throws IOException;
  294.  
  295. }
  296.  
  297.  
  298.