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