net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/jdom/IDOMNode.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2003 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Common Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/cpl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core.jdom;
  12
  13 import java.util.Enumeration;
  14
  15 import net.sourceforge.phpdt.core.IJavaElement;
  16
  17
  18 /**
  19  * Nodes represent structural fragments of a Java source file, also known as document fragments. Their implementation
  20  * is known as a DOM (Document Object Model) -  in this case a JDOM (Java DOM). A root node (node
  21  * with no parent or siblings) represents the root of a document fragment (DF). A complete Java document is
  22  * represented by a compilation unit node (<code>IDOMCompilationUnit</code>). In this way, a DF is
  23  * comprised of DFs, and a document itself (compilation unit) is also a DF.
  24  * <p>
  25  * A DF may be created empty and programmatically filled, or it may be created from
  26  * a source code string. The <code>IDOMFactory</code> allows the creation of all kinds
  27  * of nodes from source code strings. Manipulations performed on a DF are immediately
  28  * reflected in the DF's contents.
  29  * </p>
  30  * <p>
  31  * Children fragments are represented as a linked list of nodes. Children are inserted via their parent node, and
  32  * are automatically linked up with previous and next nodes.
  33  * </p>
  34  * <p>
  35  * The contents of any node (DF) may be retrieved at any time. In this way it is possible to retrieve
  36  * source code representing fragments of the compilation unit (for example, a type or a method), since
  37  * the contents of any node (not just the root node) may be obtained.
  38  * </p>
  39  * <p>
  40  * The following manipulations on DFs are distinct:
  41  * <ul>
  42  * <li>clone - this creates a stand-alone copy of the DF that is in no way dependent on the DF that it was cloned from</li>
  43  * <li>remove - this orphans a DF from its host DF. The removed DF may still be dependent on its previous host
  44  *    (perhaps to generate its contents), and hanging onto the fragment means that its previous host is also
  45  *    retained in memory.</li>
  46  * <li>add/insert - this splices an un-parented DF (one that has been cloned, removed, or created stand-alone),
  47  *    into an existing DF such that the newly inserted DF is only dependent on its new host.</li>
  48  * </ul>
  49  * </p>
  50  * <p>
  51  * Wherever types are specified in DOM APIs, type names must be specified as they would appear
  52  * in source code. The DOM does not have a notion of type signatures, only raw text. Example type
  53  * names are <code>"Object"</code>, <code>"java.io.File"</code>, and <code>"int[]"</code>.
  54  * </p>
  55  * <p>
  56  * This interface is not intended to be implemented by clients.
  57  * </p>
  58  */
  59 public interface IDOMNode extends Cloneable  {
  60
  61         /**
  62          * Node type constant indicating a compilation unit.
  63          * Nodes of this type maybe by safely cast to <code>IDOMCompilationUnit</code>.
  64          * @see #getNodeType
  65          */
  66         public static int COMPILATION_UNIT= 1;
  67
  68         /**
  69          * Node type constant indicating a package declaration.
  70          * Nodes of this type maybe by safely cast to <code>IDOMPackage</code>.
  71         * @see #getNodeType
  72          */
  73         public static int PACKAGE= 2;
  74
  75         /**
  76          * Node type constant indicating an import declaration.
  77          * Nodes of this type maybe by safely cast to <code>IDOMImport</code>.
  78          * @see #getNodeType
  79          */
  80         public static int IMPORT= 3;
  81
  82         /**
  83          * Node type constant indicating a type declaration.
  84          * Nodes of this type maybe by safely cast to <code>IDOMType</code>.
  85          * @see #getNodeType
  86          */
  87         public static int TYPE= 4;
  88
  89         /**
  90          * Node type constant indicating a field declaration.
  91          * Nodes of this type maybe by safely cast to <code>IDOMField</code>.
  92          * @see #getNodeType
  93          */
  94         public static int FIELD= 5;
  95
  96         /**
  97          * Node type constant indicating a method (or constructor) declaration.
  98          * Nodes of this type maybe by safely cast to <code>IDOMMethod</code>.
  99          * @see #getNodeType
 100          */
 101         public static int METHOD= 6;
 102
 103         /**
 104          * Node type constant indicating an initializer declaration.
 105          * Nodes of this type maybe by safely cast to <code>IDOMInitializer</code>.
 106          * @see #getNodeType
 107          */
 108         public static int INITIALIZER= 7;
 109
 110 /**
 111  * Adds the given un-parented node (document fragment) as the last child of this node.
 112  *
 113  * @param child the new child node
 114  * @exception DOMException if any of the following conditions hold:<ul>
 115  * <li>this node is not allowed to have children,</li>
 116  * <li>the child is not of an allowable type</li>
 117  * <li>the child already has a parent</li>
 118  * <li>the child is an ancestor of this node</li>
 119  * </ul>
 120  * @exception IllegalArgumentException if the child is <code>null</code>
 121  *
 122  * @see #insertSibling
 123  * @see #remove
 124  */
 125 public void addChild(IDOMNode child) throws DOMException, IllegalArgumentException;
 126 /**
 127  * Returns whether this node is allowed to have children.
 128  *
 129  * @return <code>true</code> if this node can have children
 130  */
 131 public boolean canHaveChildren();
 132 /**
 133  * Returns a stand-alone copy of the document fragment represented by this node that
 134  * is in no way dependent on the document this node is part of.
 135  *
 136  * @return a copy of type <code>IDOMNode</code>
 137  * @see #addChild
 138  * @see #insertSibling
 139  * @see #remove
 140  */
 141 public Object clone();
 142 /**
 143  * Returns the current contents of this document fragment as a character array.
 144  * <p>
 145  * Note: To obtain complete source for the ".java" file, ask a compilation unit
 146  * node for its contents.
 147  * </p>
 148  *
 149  * @return the contents, or <code>null</code> if this node has no contents
 150  */
 151 public char[] getCharacters();
 152 /**
 153  * Returns the first named child of this node with the given name.
 154  *
 155  * @param name the name
 156  * @return the child node, or <code>null</code> if no such child exists
 157  */
 158 public IDOMNode getChild(String name);
 159 /**
 160  * Returns an enumeration of children of this node. Returns an empty enumeration
 161  * if this node has no children (including nodes that cannot have children).
 162  * Children appear in the order in which they are declared in the source code.
 163  *
 164  * @return an enumeration of the children
 165  */
 166 public Enumeration getChildren();
 167 /**
 168  * Returns the current contents of this document fragment.
 169  * <p>
 170  * Note: To obtain complete source for the ".java" file, ask a compilation unit
 171  * node for its contents.
 172  * </p>
 173  *
 174  * @return the contents, or <code>null</code> if this node has no contents
 175  */
 176 public String getContents();
 177 /**
 178  * Returns the first child of this node.
 179  * Children appear in the order in which they exist in the source code.
 180  *
 181  * @return the first child, or <code>null</code> if this node has no children
 182  * @see #getChildren
 183  */
 184 public IDOMNode getFirstChild();
 185 /**
 186  * Returns a handle for the Java element associated with this
 187  * document fragment, based on the parent Java element.
 188  *
 189  * @param parent the parent Java element
 190  * @exception IllegalArgumentException if the parent element is not
 191  *   of a valid parent type for this node
 192  */
 193 public IJavaElement getJavaElement(IJavaElement parent) throws IllegalArgumentException;
 194 /**
 195  * Returns the name of this node.
 196  * More details are provided in each of the subtypes.
 197  *
 198  * @return the name, or <code>null</code> if it has no name
 199  */
 200 public String getName();
 201 /**
 202  * Returns the sibling node immediately following this node.
 203  *
 204  * @return the next node, or <code>null</code> if there is no following node
 205  */
 206 public IDOMNode getNextNode();
 207 /**
 208  * Returns the type of this node.
 209  *
 210  * @return one of the node type constants defined in <code>IDOMNode</code>
 211  */
 212 public int getNodeType();
 213 /**
 214  * Returns the parent of this node.
 215  *
 216  * @return the parent node, or <code>null</code> if this node does not have a
 217  *   parent
 218  */
 219 public IDOMNode getParent();
 220 /**
 221  * Returns the sibling node immediately preceding this node.
 222  *
 223  * @return the previous node, or <code>null</code> if there is no preceding node
 224  */
 225 public IDOMNode getPreviousNode();
 226 /**
 227  * Inserts the given un-parented node as a sibling of this node, immediately before
 228  * this node.
 229  *
 230  * @param sibling the new sibling node
 231  * @exception DOMException if any of the following conditions hold:<ul>
 232  * <li>this node is a document fragment root</li>
 233  * <li>the sibling is not of the correct type</li>
 234  * <li>the sibling already has a parent</li>
 235  * <li>this sibling is an ancestor of this node</li>
 236  * </ul>
 237  * @exception IllegalArgumentException if the sibling is <code>null</code>
 238  *
 239  * @see #addChild
 240  * @see #clone
 241  * @see #remove
 242  */
 243 public void insertSibling(IDOMNode sibling) throws DOMException, IllegalArgumentException;
 244 /**
 245  * Returns whether the given node is an allowable child for this node.
 246  *
 247  * @param node the potential child node
 248  * @return <code>true</code> if the given node is an allowable child
 249  */
 250 public boolean isAllowableChild(IDOMNode node);
 251 /**
 252  * Returns whether this node's signature is equivalent to the given
 253  * node's signature. In other words, if the nodes were siblings,
 254  * would the declarations collide because they represent the same declaration.
 255  *
 256  * @param node the other node
 257  * @return <code>true</code> if the nodes have equivalent signatures
 258  */
 259 public boolean isSignatureEqual(IDOMNode node);
 260 /**
 261  * Separates this node from its parent and siblings, maintaining any ties that this node
 262  * has to the underlying document fragment. A document fragment that is removed
 263  * from its host document may still be dependent on that host document until it is
 264  * inserted into a different document. Removing a root node has no effect.
 265  *
 266  * @see #addChild
 267  * @see #clone
 268  * @see #insertSibling
 269  */
 270 public void remove();
 271 /**
 272  * Sets the name of this node. Name format depends on node type.
 273  * More details are provided in each of the subtypes.
 274  *
 275  * @param name the name, or <code>null</code> to clear the name
 276  */
 277 public void setName(String name);
 278 }