001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.core.jdom;
011:
012: import java.util.Enumeration;
013:
014: import org.eclipse.jdt.core.IJavaElement;
015:
016: /**
017: * Nodes represent structural fragments of a Java source file, also known as document fragments. Their implementation
018: * is known as a DOM (Document Object Model) - in this case a JDOM (Java DOM). A root node (node
019: * with no parent or siblings) represents the root of a document fragment (DF). A complete Java document is
020: * represented by a compilation unit node (<code>IDOMCompilationUnit</code>). In this way, a DF is
021: * comprised of DFs, and a document itself (compilation unit) is also a DF.
022: * <p>
023: * A DF may be created empty and programmatically filled, or it may be created from
024: * a source code string. The <code>IDOMFactory</code> allows the creation of all kinds
025: * of nodes from source code strings. Manipulations performed on a DF are immediately
026: * reflected in the DF's contents.
027: * </p>
028: * <p>
029: * Children fragments are represented as a linked list of nodes. Children are inserted via their parent node, and
030: * are automatically linked up with previous and next nodes.
031: * </p>
032: * <p>
033: * The contents of any node (DF) may be retrieved at any time. In this way it is possible to retrieve
034: * source code representing fragments of the compilation unit (for example, a type or a method), since
035: * the contents of any node (not just the root node) may be obtained.
036: * </p>
037: * <p>
038: * The following manipulations on DFs are distinct:
039: * <ul>
040: * <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>
041: * <li>remove - this orphans a DF from its host DF. The removed DF may still be dependent on its previous host
042: * (perhaps to generate its contents), and hanging onto the fragment means that its previous host is also
043: * retained in memory.</li>
044: * <li>add/insert - this splices an un-parented DF (one that has been cloned, removed, or created stand-alone),
045: * into an existing DF such that the newly inserted DF is only dependent on its new host.</li>
046: * </ul>
047: * </p>
048: * <p>
049: * Wherever types are specified in DOM APIs, type names must be specified as they would appear
050: * in source code. The DOM does not have a notion of type signatures, only raw text. Example type
051: * names are <code>"Object"</code>, <code>"java.io.File"</code>, and <code>"int[]"</code>.
052: * </p>
053: * <p>
054: * This interface is not intended to be implemented by clients.
055: * </p>
056: * @deprecated The JDOM was made obsolete by the addition in 2.0 of the more
057: * powerful, fine-grained DOM/AST API found in the
058: * org.eclipse.jdt.core.dom package.
059: */
060: public interface IDOMNode extends Cloneable {
061:
062: /**
063: * Node type constant indicating a compilation unit.
064: * Nodes of this type maybe by safely cast to <code>IDOMCompilationUnit</code>.
065: * @see #getNodeType()
066: */
067: public static int COMPILATION_UNIT = 1;
068:
069: /**
070: * Node type constant indicating a package declaration.
071: * Nodes of this type maybe by safely cast to <code>IDOMPackage</code>.
072: * @see #getNodeType()
073: */
074: public static int PACKAGE = 2;
075:
076: /**
077: * Node type constant indicating an import declaration.
078: * Nodes of this type maybe by safely cast to <code>IDOMImport</code>.
079: * @see #getNodeType()
080: */
081: public static int IMPORT = 3;
082:
083: /**
084: * Node type constant indicating a type declaration.
085: * Nodes of this type maybe by safely cast to <code>IDOMType</code>.
086: * @see #getNodeType()
087: */
088: public static int TYPE = 4;
089:
090: /**
091: * Node type constant indicating a field declaration.
092: * Nodes of this type maybe by safely cast to <code>IDOMField</code>.
093: * @see #getNodeType()
094: */
095: public static int FIELD = 5;
096:
097: /**
098: * Node type constant indicating a method (or constructor) declaration.
099: * Nodes of this type maybe by safely cast to <code>IDOMMethod</code>.
100: * @see #getNodeType()
101: */
102: public static int METHOD = 6;
103:
104: /**
105: * Node type constant indicating an initializer declaration.
106: * Nodes of this type maybe by safely cast to <code>IDOMInitializer</code>.
107: * @see #getNodeType()
108: */
109: public static int INITIALIZER = 7;
110:
111: /**
112: * Adds the given un-parented node (document fragment) as the last child of this node.
113: *
114: * @param child the new child node
115: * @exception DOMException if any of the following conditions hold:<ul>
116: * <li>this node is not allowed to have children,</li>
117: * <li>the child is not of an allowable type</li>
118: * <li>the child already has a parent</li>
119: * <li>the child is an ancestor of this node</li>
120: * </ul>
121: * @exception IllegalArgumentException if the child is <code>null</code>
122: *
123: * @see #insertSibling(IDOMNode)
124: * @see #remove()
125: */
126: public void addChild(IDOMNode child) throws DOMException,
127: IllegalArgumentException;
128:
129: /**
130: * Returns whether this node is allowed to have children.
131: *
132: * @return <code>true</code> if this node can have children
133: */
134: public boolean canHaveChildren();
135:
136: /**
137: * Returns a stand-alone copy of the document fragment represented by this node that
138: * is in no way dependent on the document this node is part of.
139: *
140: * @return a copy of type <code>IDOMNode</code>
141: * @see #addChild(IDOMNode)
142: * @see #insertSibling(IDOMNode)
143: * @see #remove()
144: */
145: public Object clone();
146:
147: /**
148: * Returns the current contents of this document fragment as a character array.
149: * <p>
150: * Note: To obtain complete source for the source file, ask a compilation unit
151: * node for its contents.
152: * </p>
153: *
154: * @return the contents, or <code>null</code> if this node has no contents
155: */
156: public char[] getCharacters();
157:
158: /**
159: * Returns the first named child of this node with the given name.
160: *
161: * @param name the name
162: * @return the child node, or <code>null</code> if no such child exists
163: */
164: public IDOMNode getChild(String name);
165:
166: /**
167: * Returns an enumeration of children of this node. Returns an empty enumeration
168: * if this node has no children (including nodes that cannot have children).
169: * Children appear in the order in which they are declared in the source code.
170: *
171: * @return an enumeration of the children
172: */
173: public Enumeration getChildren();
174:
175: /**
176: * Returns the current contents of this document fragment.
177: * <p>
178: * Note: To obtain complete source for the source file, ask a compilation unit
179: * node for its contents.
180: * </p>
181: *
182: * @return the contents, or <code>null</code> if this node has no contents
183: */
184: public String getContents();
185:
186: /**
187: * Returns the first child of this node.
188: * Children appear in the order in which they exist in the source code.
189: *
190: * @return the first child, or <code>null</code> if this node has no children
191: * @see #getChildren()
192: */
193: public IDOMNode getFirstChild();
194:
195: /**
196: * Returns a handle for the Java element associated with this
197: * document fragment, based on the parent Java element.
198: *
199: * @param parent the parent Java element
200: * @exception IllegalArgumentException if the parent element is not
201: * of a valid parent type for this node
202: * @return a handle for the Java element associated with this
203: * document fragment, based on the parent Java element
204: */
205: public IJavaElement getJavaElement(IJavaElement parent)
206: throws IllegalArgumentException;
207:
208: /**
209: * Returns the name of this node.
210: * More details are provided in each of the subtypes.
211: *
212: * @return the name, or <code>null</code> if it has no name
213: */
214: public String getName();
215:
216: /**
217: * Returns the sibling node immediately following this node.
218: *
219: * @return the next node, or <code>null</code> if there is no following node
220: */
221: public IDOMNode getNextNode();
222:
223: /**
224: * Returns the type of this node.
225: *
226: * @return one of the node type constants defined in <code>IDOMNode</code>
227: */
228: public int getNodeType();
229:
230: /**
231: * Returns the parent of this node.
232: *
233: * @return the parent node, or <code>null</code> if this node does not have a
234: * parent
235: */
236: public IDOMNode getParent();
237:
238: /**
239: * Returns the sibling node immediately preceding this node.
240: *
241: * @return the previous node, or <code>null</code> if there is no preceding node
242: */
243: public IDOMNode getPreviousNode();
244:
245: /**
246: * Inserts the given un-parented node as a sibling of this node, immediately before
247: * this node.
248: *
249: * @param sibling the new sibling node
250: * @exception DOMException if any of the following conditions hold:<ul>
251: * <li>this node is a document fragment root</li>
252: * <li>the sibling is not of the correct type</li>
253: * <li>the sibling already has a parent</li>
254: * <li>this sibling is an ancestor of this node</li>
255: * </ul>
256: * @exception IllegalArgumentException if the sibling is <code>null</code>
257: *
258: * @see #addChild(IDOMNode)
259: * @see #clone()
260: * @see #remove()
261: */
262: public void insertSibling(IDOMNode sibling) throws DOMException,
263: IllegalArgumentException;
264:
265: /**
266: * Returns whether the given node is an allowable child for this node.
267: *
268: * @param node the potential child node
269: * @return <code>true</code> if the given node is an allowable child
270: */
271: public boolean isAllowableChild(IDOMNode node);
272:
273: /**
274: * Returns whether this node's signature is equivalent to the given
275: * node's signature. In other words, if the nodes were siblings,
276: * would the declarations collide because they represent the same declaration.
277: *
278: * @param node the other node
279: * @return <code>true</code> if the nodes have equivalent signatures
280: */
281: public boolean isSignatureEqual(IDOMNode node);
282:
283: /**
284: * Separates this node from its parent and siblings, maintaining any ties that this node
285: * has to the underlying document fragment. A document fragment that is removed
286: * from its host document may still be dependent on that host document until it is
287: * inserted into a different document. Removing a root node has no effect.
288: *
289: * @see #addChild(IDOMNode)
290: * @see #clone()
291: * @see #insertSibling(IDOMNode)
292: */
293: public void remove();
294:
295: /**
296: * Sets the name of this node. Name format depends on node type.
297: * More details are provided in each of the subtypes.
298: *
299: * @param name the name, or <code>null</code> to clear the name
300: */
301: public void setName(String name);
302: }
|