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  ;
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    {
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  ;
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   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   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   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   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  ;
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   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  ;
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   name);
282 }
283
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags