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
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core.jdom;
13 import java.util.Enumeration;
15 import net.sourceforge.phpdt.core.IJavaElement;
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
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.
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
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.
43 * The following manipulations on DFs are distinct:
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
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>
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>.
63 * This interface is not intended to be implemented by clients.
66 public interface IDOMNode extends Cloneable {
69 * Node type constant indicating a compilation unit. Nodes of this type
70 * maybe by safely cast to <code>IDOMCompilationUnit</code>.
74 public static int COMPILATION_UNIT = 1;
77 * Node type constant indicating a package declaration. Nodes of this type
78 * maybe by safely cast to <code>IDOMPackage</code>.
82 public static int PACKAGE = 2;
85 * Node type constant indicating an import declaration. Nodes of this type
86 * maybe by safely cast to <code>IDOMImport</code>.
90 public static int IMPORT = 3;
93 * Node type constant indicating a type declaration. Nodes of this type
94 * maybe by safely cast to <code>IDOMType</code>.
98 public static int TYPE = 4;
101 * Node type constant indicating a field declaration. Nodes of this type
102 * maybe by safely cast to <code>IDOMField</code>.
106 public static int FIELD = 5;
109 * Node type constant indicating a method (or constructor) declaration.
110 * Nodes of this type maybe by safely cast to <code>IDOMMethod</code>.
114 public static int METHOD = 6;
117 * Node type constant indicating an initializer declaration. Nodes of this
118 * type maybe by safely cast to <code>IDOMInitializer</code>.
122 public static int INITIALIZER = 7;
125 * Adds the given un-parented node (document fragment) as the last child of
130 * @exception DOMException
131 * if any of the following conditions hold:
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>
138 * @exception IllegalArgumentException
139 * if the child is <code>null</code>
141 * @see #insertSibling
144 public void addChild(IDOMNode child) throws DOMException,
145 IllegalArgumentException;
148 * Returns whether this node is allowed to have children.
150 * @return <code>true</code> if this node can have children
152 public boolean canHaveChildren();
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.
158 * @return a copy of type <code>IDOMNode</code>
160 * @see #insertSibling
163 public Object clone();
166 * Returns the current contents of this document fragment as a character
169 * Note: To obtain complete source for the ".java" file, ask a compilation
170 * unit node for its contents.
173 * @return the contents, or <code>null</code> if this node has no contents
175 public char[] getCharacters();
178 * Returns the first named child of this node with the given name.
182 * @return the child node, or <code>null</code> if no such child exists
184 public IDOMNode getChild(String name);
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.
192 * @return an enumeration of the children
194 public Enumeration getChildren();
197 * Returns the current contents of this document fragment.
199 * Note: To obtain complete source for the ".java" file, ask a compilation
200 * unit node for its contents.
203 * @return the contents, or <code>null</code> if this node has no contents
205 public String getContents();
208 * Returns the first child of this node. Children appear in the order in
209 * which they exist in the source code.
211 * @return the first child, or <code>null</code> if this node has no
215 public IDOMNode getFirstChild();
218 * Returns a handle for the Java element associated with this document
219 * fragment, based on the parent Java element.
222 * the parent Java element
223 * @exception IllegalArgumentException
224 * if the parent element is not of a valid parent type for
227 public IJavaElement getJavaElement(IJavaElement parent)
228 throws IllegalArgumentException;
231 * Returns the name of this node. More details are provided in each of the
234 * @return the name, or <code>null</code> if it has no name
236 public String getName();
239 * Returns the sibling node immediately following this node.
241 * @return the next node, or <code>null</code> if there is no following
244 public IDOMNode getNextNode();
247 * Returns the type of this node.
249 * @return one of the node type constants defined in <code>IDOMNode</code>
251 public int getNodeType();
254 * Returns the parent of this node.
256 * @return the parent node, or <code>null</code> if this node does not
259 public IDOMNode getParent();
262 * Returns the sibling node immediately preceding this node.
264 * @return the previous node, or <code>null</code> if there is no
267 public IDOMNode getPreviousNode();
270 * Inserts the given un-parented node as a sibling of this node, immediately
274 * the new sibling node
275 * @exception DOMException
276 * if any of the following conditions hold:
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>
283 * @exception IllegalArgumentException
284 * if the sibling is <code>null</code>
290 public void insertSibling(IDOMNode sibling) throws DOMException,
291 IllegalArgumentException;
294 * Returns whether the given node is an allowable child for this node.
297 * the potential child node
298 * @return <code>true</code> if the given node is an allowable child
300 public boolean isAllowableChild(IDOMNode node);
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.
309 * @return <code>true</code> if the nodes have equivalent signatures
311 public boolean isSignatureEqual(IDOMNode node);
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.
322 * @see #insertSibling
324 public void remove();
327 * Sets the name of this node. Name format depends on node type. More
328 * details are provided in each of the subtypes.
331 * the name, or <code>null</code> to clear the name
333 public void setName(String name);