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;
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.
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.
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.
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.
40 * The following manipulations on DFs are distinct:
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>
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>.
56 * This interface is not intended to be implemented by clients.
59 public interface IDOMNode extends Cloneable {
62 * Node type constant indicating a compilation unit.
63 * Nodes of this type maybe by safely cast to <code>IDOMCompilationUnit</code>.
66 public static int COMPILATION_UNIT= 1;
69 * Node type constant indicating a package declaration.
70 * Nodes of this type maybe by safely cast to <code>IDOMPackage</code>.
73 public static int PACKAGE= 2;
76 * Node type constant indicating an import declaration.
77 * Nodes of this type maybe by safely cast to <code>IDOMImport</code>.
80 public static int IMPORT= 3;
83 * Node type constant indicating a type declaration.
84 * Nodes of this type maybe by safely cast to <code>IDOMType</code>.
87 public static int TYPE= 4;
90 * Node type constant indicating a field declaration.
91 * Nodes of this type maybe by safely cast to <code>IDOMField</code>.
94 public static int FIELD= 5;
97 * Node type constant indicating a method (or constructor) declaration.
98 * Nodes of this type maybe by safely cast to <code>IDOMMethod</code>.
101 public static int METHOD= 6;
104 * Node type constant indicating an initializer declaration.
105 * Nodes of this type maybe by safely cast to <code>IDOMInitializer</code>.
108 public static int INITIALIZER= 7;
111 * Adds the given un-parented node (document fragment) as the last child of this node.
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>
120 * @exception IllegalArgumentException if the child is <code>null</code>
122 * @see #insertSibling
125 public void addChild(IDOMNode child) throws DOMException, IllegalArgumentException;
127 * Returns whether this node is allowed to have children.
129 * @return <code>true</code> if this node can have children
131 public boolean canHaveChildren();
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.
136 * @return a copy of type <code>IDOMNode</code>
138 * @see #insertSibling
141 public Object clone();
143 * Returns the current contents of this document fragment as a character array.
145 * Note: To obtain complete source for the ".java" file, ask a compilation unit
146 * node for its contents.
149 * @return the contents, or <code>null</code> if this node has no contents
151 public char[] getCharacters();
153 * Returns the first named child of this node with the given name.
155 * @param name the name
156 * @return the child node, or <code>null</code> if no such child exists
158 public IDOMNode getChild(String name);
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.
164 * @return an enumeration of the children
166 public Enumeration getChildren();
168 * Returns the current contents of this document fragment.
170 * Note: To obtain complete source for the ".java" file, ask a compilation unit
171 * node for its contents.
174 * @return the contents, or <code>null</code> if this node has no contents
176 public String getContents();
178 * Returns the first child of this node.
179 * Children appear in the order in which they exist in the source code.
181 * @return the first child, or <code>null</code> if this node has no children
184 public IDOMNode getFirstChild();
186 * Returns a handle for the Java element associated with this
187 * document fragment, based on the parent Java element.
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
193 public IJavaElement getJavaElement(IJavaElement parent) throws IllegalArgumentException;
195 * Returns the name of this node.
196 * More details are provided in each of the subtypes.
198 * @return the name, or <code>null</code> if it has no name
200 public String getName();
202 * Returns the sibling node immediately following this node.
204 * @return the next node, or <code>null</code> if there is no following node
206 public IDOMNode getNextNode();
208 * Returns the type of this node.
210 * @return one of the node type constants defined in <code>IDOMNode</code>
212 public int getNodeType();
214 * Returns the parent of this node.
216 * @return the parent node, or <code>null</code> if this node does not have a
219 public IDOMNode getParent();
221 * Returns the sibling node immediately preceding this node.
223 * @return the previous node, or <code>null</code> if there is no preceding node
225 public IDOMNode getPreviousNode();
227 * Inserts the given un-parented node as a sibling of this node, immediately before
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>
237 * @exception IllegalArgumentException if the sibling is <code>null</code>
243 public void insertSibling(IDOMNode sibling) throws DOMException, IllegalArgumentException;
245 * Returns whether the given node is an allowable child for this node.
247 * @param node the potential child node
248 * @return <code>true</code> if the given node is an allowable child
250 public boolean isAllowableChild(IDOMNode node);
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.
256 * @param node the other node
257 * @return <code>true</code> if the nodes have equivalent signatures
259 public boolean isSignatureEqual(IDOMNode node);
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.
268 * @see #insertSibling
270 public void remove();
272 * Sets the name of this node. Name format depends on node type.
273 * More details are provided in each of the subtypes.
275 * @param name the name, or <code>null</code> to clear the name
277 public void setName(String name);