KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > core > jdom > IDOMNode


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.jdt.core.jdom;
12
13 import java.util.Enumeration JavaDoc;
14
15 import org.eclipse.jdt.core.IJavaElement;
16
17 /**
18  * Nodes represent structural fragments of a Java source file, also known as document fragments. Their implementation
19  * is known as a DOM (Document Object Model) - in this case a JDOM (Java DOM). A root node (node
20  * with no parent or siblings) represents the root of a document fragment (DF). A complete Java document is
21  * represented by a compilation unit node (<code>IDOMCompilationUnit</code>). In this way, a DF is
22  * comprised of DFs, and a document itself (compilation unit) is also a DF.
23  * <p>
24  * A DF may be created empty and programmatically filled, or it may be created from
25  * a source code string. The <code>IDOMFactory</code> allows the creation of all kinds
26  * of nodes from source code strings. Manipulations performed on a DF are immediately
27  * reflected in the DF's contents.
28  * </p>
29  * <p>
30  * Children fragments are represented as a linked list of nodes. Children are inserted via their parent node, and
31  * are automatically linked up with previous and next nodes.
32  * </p>
33  * <p>
34  * The contents of any node (DF) may be retrieved at any time. In this way it is possible to retrieve
35  * source code representing fragments of the compilation unit (for example, a type or a method), since
36  * the contents of any node (not just the root node) may be obtained.
37  * </p>
38  * <p>
39  * The following manipulations on DFs are distinct:
40  * <ul>
41  * <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>
42  * <li>remove - this orphans a DF from its host DF. The removed DF may still be dependent on its previous host
43  * (perhaps to generate its contents), and hanging onto the fragment means that its previous host is also
44  * retained in memory.</li>
45  * <li>add/insert - this splices an un-parented DF (one that has been cloned, removed, or created stand-alone),
46  * into an existing DF such that the newly inserted DF is only dependent on its new host.</li>
47  * </ul>
48  * </p>
49  * <p>
50  * Wherever types are specified in DOM APIs, type names must be specified as they would appear
51  * in source code. The DOM does not have a notion of type signatures, only raw text. Example type
52  * names are <code>"Object"</code>, <code>"java.io.File"</code>, and <code>"int[]"</code>.
53  * </p>
54  * <p>
55  * This interface is not intended to be implemented by clients.
56  * </p>
57  * @deprecated The JDOM was made obsolete by the addition in 2.0 of the more
58  * powerful, fine-grained DOM/AST API found in the
59  * org.eclipse.jdt.core.dom package.
60  */

61 public interface IDOMNode extends Cloneable JavaDoc {
62
63     /**
64      * Node type constant indicating a compilation unit.
65      * Nodes of this type maybe by safely cast to <code>IDOMCompilationUnit</code>.
66      * @see #getNodeType()
67      */

68     public static int COMPILATION_UNIT= 1;
69     
70     /**
71      * Node type constant indicating a package declaration.
72      * Nodes of this type maybe by safely cast to <code>IDOMPackage</code>.
73     * @see #getNodeType()
74      */

75     public static int PACKAGE= 2;
76     
77     /**
78      * Node type constant indicating an import declaration.
79      * Nodes of this type maybe by safely cast to <code>IDOMImport</code>.
80      * @see #getNodeType()
81      */

82     public static int IMPORT= 3;
83     
84     /**
85      * Node type constant indicating a type declaration.
86      * Nodes of this type maybe by safely cast to <code>IDOMType</code>.
87      * @see #getNodeType()
88      */

89     public static int TYPE= 4;
90     
91     /**
92      * Node type constant indicating a field declaration.
93      * Nodes of this type maybe by safely cast to <code>IDOMField</code>.
94      * @see #getNodeType()
95      */

96     public static int FIELD= 5;
97     
98     /**
99      * Node type constant indicating a method (or constructor) declaration.
100      * Nodes of this type maybe by safely cast to <code>IDOMMethod</code>.
101      * @see #getNodeType()
102      */

103     public static int METHOD= 6;
104     
105     /**
106      * Node type constant indicating an initializer declaration.
107      * Nodes of this type maybe by safely cast to <code>IDOMInitializer</code>.
108      * @see #getNodeType()
109      */

110     public static int INITIALIZER= 7;
111     
112 /**
113  * Adds the given un-parented node (document fragment) as the last child of this node.
114  *
115  * @param child the new child node
116  * @exception DOMException if any of the following conditions hold:<ul>
117  * <li>this node is not allowed to have children,</li>
118  * <li>the child is not of an allowable type</li>
119  * <li>the child already has a parent</li>
120  * <li>the child is an ancestor of this node</li>
121  * </ul>
122  * @exception IllegalArgumentException if the child is <code>null</code>
123  *
124  * @see #insertSibling(IDOMNode)
125  * @see #remove()
126  */

127 public void addChild(IDOMNode child) throws DOMException, IllegalArgumentException JavaDoc;
128 /**
129  * Returns whether this node is allowed to have children.
130  *
131  * @return <code>true</code> if this node can have children
132  */

133 public boolean canHaveChildren();
134 /**
135  * Returns a stand-alone copy of the document fragment represented by this node that
136  * is in no way dependent on the document this node is part of.
137  *
138  * @return a copy of type <code>IDOMNode</code>
139  * @see #addChild(IDOMNode)
140  * @see #insertSibling(IDOMNode)
141  * @see #remove()
142  */

143 public Object JavaDoc clone();
144 /**
145  * Returns the current contents of this document fragment as a character array.
146  * <p>
147  * Note: To obtain complete source for the source file, ask a compilation unit
148  * node for its contents.
149  * </p>
150  *
151  * @return the contents, or <code>null</code> if this node has no contents
152  */

153 public char[] getCharacters();
154 /**
155  * Returns the first named child of this node with the given name.
156  *
157  * @param name the name
158  * @return the child node, or <code>null</code> if no such child exists
159  */

160 public IDOMNode getChild(String JavaDoc name);
161 /**
162  * Returns an enumeration of children of this node. Returns an empty enumeration
163  * if this node has no children (including nodes that cannot have children).
164  * Children appear in the order in which they are declared in the source code.
165  *
166  * @return an enumeration of the children
167  */

168 public Enumeration JavaDoc getChildren();
169 /**
170  * Returns the current contents of this document fragment.
171  * <p>
172  * Note: To obtain complete source for the source file, ask a compilation unit
173  * node for its contents.
174  * </p>
175  *
176  * @return the contents, or <code>null</code> if this node has no contents
177  */

178 public String JavaDoc getContents();
179 /**
180  * Returns the first child of this node.
181  * Children appear in the order in which they exist in the source code.
182  *
183  * @return the first child, or <code>null</code> if this node has no children
184  * @see #getChildren()
185  */

186 public IDOMNode getFirstChild();
187 /**
188  * Returns a handle for the Java element associated with this
189  * document fragment, based on the parent Java element.
190  *
191  * @param parent the parent Java element
192  * @exception IllegalArgumentException if the parent element is not
193  * of a valid parent type for this node
194  * @return a handle for the Java element associated with this
195  * document fragment, based on the parent Java element
196  */

197 public IJavaElement getJavaElement(IJavaElement parent) throws IllegalArgumentException JavaDoc;
198 /**
199  * Returns the name of this node.
200  * More details are provided in each of the subtypes.
201  *
202  * @return the name, or <code>null</code> if it has no name
203  */

204 public String JavaDoc getName();
205 /**
206  * Returns the sibling node immediately following this node.
207  *
208  * @return the next node, or <code>null</code> if there is no following node
209  */

210 public IDOMNode getNextNode();
211 /**
212  * Returns the type of this node.
213  *
214  * @return one of the node type constants defined in <code>IDOMNode</code>
215  */

216 public int getNodeType();
217 /**
218  * Returns the parent of this node.
219  *
220  * @return the parent node, or <code>null</code> if this node does not have a
221  * parent
222  */

223 public IDOMNode getParent();
224 /**
225  * Returns the sibling node immediately preceding this node.
226  *
227  * @return the previous node, or <code>null</code> if there is no preceding node
228  */

229 public IDOMNode getPreviousNode();
230 /**
231  * Inserts the given un-parented node as a sibling of this node, immediately before
232  * this node.
233  *
234  * @param sibling the new sibling node
235  * @exception DOMException if any of the following conditions hold:<ul>
236  * <li>this node is a document fragment root</li>
237  * <li>the sibling is not of the correct type</li>
238  * <li>the sibling already has a parent</li>
239  * <li>this sibling is an ancestor of this node</li>
240  * </ul>
241  * @exception IllegalArgumentException if the sibling is <code>null</code>
242  *
243  * @see #addChild(IDOMNode)
244  * @see #clone()
245  * @see #remove()
246  */

247 public void insertSibling(IDOMNode sibling) throws DOMException, IllegalArgumentException JavaDoc;
248 /**
249  * Returns whether the given node is an allowable child for this node.
250  *
251  * @param node the potential child node
252  * @return <code>true</code> if the given node is an allowable child
253  */

254 public boolean isAllowableChild(IDOMNode node);
255 /**
256  * Returns whether this node's signature is equivalent to the given
257  * node's signature. In other words, if the nodes were siblings,
258  * would the declarations collide because they represent the same declaration.
259  *
260  * @param node the other node
261  * @return <code>true</code> if the nodes have equivalent signatures
262  */

263 public boolean isSignatureEqual(IDOMNode node);
264 /**
265  * Separates this node from its parent and siblings, maintaining any ties that this node
266  * has to the underlying document fragment. A document fragment that is removed
267  * from its host document may still be dependent on that host document until it is
268  * inserted into a different document. Removing a root node has no effect.
269  *
270  * @see #addChild(IDOMNode)
271  * @see #clone()
272  * @see #insertSibling(IDOMNode)
273  */

274 public void remove();
275 /**
276  * Sets the name of this node. Name format depends on node type.
277  * More details are provided in each of the subtypes.
278  *
279  * @param name the name, or <code>null</code> to clear the name
280  */

281 public void setName(String JavaDoc name);
282 }
283
Popular Tags