| /******************************************************************************* |
| * Copyright (c) 2000, 2008 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.jdt.core.jdom; |
| |
| import java.util.Enumeration; |
| |
| import org.eclipse.jdt.core.IJavaElement; |
| |
| /** |
| * Nodes represent structural fragments of a Java source file, also known as document fragments. Their implementation |
| * is known as a DOM (Document Object Model) - in this case a JDOM (Java DOM). A root node (node |
| * with no parent or siblings) represents the root of a document fragment (DF). A complete Java document is |
| * represented by a compilation unit node (<code>IDOMCompilationUnit</code>). In this way, a DF is |
| * comprised of DFs, and a document itself (compilation unit) is also a DF. |
| * <p> |
| * A DF may be created empty and programmatically filled, or it may be created from |
| * a source code string. The <code>IDOMFactory</code> allows the creation of all kinds |
| * of nodes from source code strings. Manipulations performed on a DF are immediately |
| * reflected in the DF's contents. |
| * </p> |
| * <p> |
| * Children fragments are represented as a linked list of nodes. Children are inserted via their parent node, and |
| * are automatically linked up with previous and next nodes. |
| * </p> |
| * <p> |
| * The contents of any node (DF) may be retrieved at any time. In this way it is possible to retrieve |
| * source code representing fragments of the compilation unit (for example, a type or a method), since |
| * the contents of any node (not just the root node) may be obtained. |
| * </p> |
| * <p> |
| * The following manipulations on DFs are distinct: |
| * <ul> |
| * <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> |
| * <li>remove - this orphans a DF from its host DF. The removed DF may still be dependent on its previous host |
| * (perhaps to generate its contents), and hanging onto the fragment means that its previous host is also |
| * retained in memory.</li> |
| * <li>add/insert - this splices an un-parented DF (one that has been cloned, removed, or created stand-alone), |
| * into an existing DF such that the newly inserted DF is only dependent on its new host.</li> |
| * </ul> |
| * </p> |
| * <p> |
| * Wherever types are specified in DOM APIs, type names must be specified as they would appear |
| * in source code. The DOM does not have a notion of type signatures, only raw text. Example type |
| * names are <code>"Object"</code>, <code>"java.io.File"</code>, and <code>"int[]"</code>. |
| * </p> |
| * |
| * @deprecated The JDOM was made obsolete by the addition in 2.0 of the more |
| * powerful, fine-grained DOM/AST API found in the |
| * org.eclipse.jdt.core.dom package. |
| * @noimplement This interface is not intended to be implemented by clients. |
| */ |
| public interface IDOMNode extends Cloneable { |
| |
| /** |
| * Node type constant indicating a compilation unit. |
| * Nodes of this type maybe by safely cast to <code>IDOMCompilationUnit</code>. |
| * @see #getNodeType() |
| */ |
| public static int COMPILATION_UNIT= 1; |
| |
| /** |
| * Node type constant indicating a package declaration. |
| * Nodes of this type maybe by safely cast to <code>IDOMPackage</code>. |
| * @see #getNodeType() |
| */ |
| public static int PACKAGE= 2; |
| |
| /** |
| * Node type constant indicating an import declaration. |
| * Nodes of this type maybe by safely cast to <code>IDOMImport</code>. |
| * @see #getNodeType() |
| */ |
| public static int IMPORT= 3; |
| |
| /** |
| * Node type constant indicating a type declaration. |
| * Nodes of this type maybe by safely cast to <code>IDOMType</code>. |
| * @see #getNodeType() |
| */ |
| public static int TYPE= 4; |
| |
| /** |
| * Node type constant indicating a field declaration. |
| * Nodes of this type maybe by safely cast to <code>IDOMField</code>. |
| * @see #getNodeType() |
| */ |
| public static int FIELD= 5; |
| |
| /** |
| * Node type constant indicating a method (or constructor) declaration. |
| * Nodes of this type maybe by safely cast to <code>IDOMMethod</code>. |
| * @see #getNodeType() |
| */ |
| public static int METHOD= 6; |
| |
| /** |
| * Node type constant indicating an initializer declaration. |
| * Nodes of this type maybe by safely cast to <code>IDOMInitializer</code>. |
| * @see #getNodeType() |
| */ |
| public static int INITIALIZER= 7; |
| |
| /** |
| * Adds the given un-parented node (document fragment) as the last child of this node. |
| * |
| * @param child the new child node |
| * @exception DOMException if any of the following conditions hold:<ul> |
| * <li>this node is not allowed to have children,</li> |
| * <li>the child is not of an allowable type</li> |
| * <li>the child already has a parent</li> |
| * <li>the child is an ancestor of this node</li> |
| * </ul> |
| * @exception IllegalArgumentException if the child is <code>null</code> |
| * |
| * @see #insertSibling(IDOMNode) |
| * @see #remove() |
| */ |
| public void addChild(IDOMNode child) throws DOMException, IllegalArgumentException; |
| /** |
| * Returns whether this node is allowed to have children. |
| * |
| * @return <code>true</code> if this node can have children |
| */ |
| public boolean canHaveChildren(); |
| /** |
| * Returns a stand-alone copy of the document fragment represented by this node that |
| * is in no way dependent on the document this node is part of. |
| * |
| * @return a copy of type <code>IDOMNode</code> |
| * @see #addChild(IDOMNode) |
| * @see #insertSibling(IDOMNode) |
| * @see #remove() |
| */ |
| public Object clone(); |
| /** |
| * Returns the current contents of this document fragment as a character array. |
| * <p> |
| * Note: To obtain complete source for the source file, ask a compilation unit |
| * node for its contents. |
| * </p> |
| * |
| * @return the contents, or <code>null</code> if this node has no contents |
| */ |
| public char[] getCharacters(); |
| /** |
| * Returns the first named child of this node with the given name. |
| * |
| * @param name the name |
| * @return the child node, or <code>null</code> if no such child exists |
| */ |
| public IDOMNode getChild(String name); |
| /** |
| * Returns an enumeration of children of this node. Returns an empty enumeration |
| * if this node has no children (including nodes that cannot have children). |
| * Children appear in the order in which they are declared in the source code. |
| * |
| * @return an enumeration of the children |
| */ |
| public Enumeration getChildren(); |
| /** |
| * Returns the current contents of this document fragment. |
| * <p> |
| * Note: To obtain complete source for the source file, ask a compilation unit |
| * node for its contents. |
| * </p> |
| * |
| * @return the contents, or <code>null</code> if this node has no contents |
| */ |
| public String getContents(); |
| /** |
| * Returns the first child of this node. |
| * Children appear in the order in which they exist in the source code. |
| * |
| * @return the first child, or <code>null</code> if this node has no children |
| * @see #getChildren() |
| */ |
| public IDOMNode getFirstChild(); |
| /** |
| * Returns a handle for the Java element associated with this |
| * document fragment, based on the parent Java element. |
| * |
| * @param parent the parent Java element |
| * @exception IllegalArgumentException if the parent element is not |
| * of a valid parent type for this node |
| * @return a handle for the Java element associated with this |
| * document fragment, based on the parent Java element |
| */ |
| public IJavaElement getJavaElement(IJavaElement parent) throws IllegalArgumentException; |
| /** |
| * Returns the name of this node. |
| * More details are provided in each of the subtypes. |
| * |
| * @return the name, or <code>null</code> if it has no name |
| */ |
| public String getName(); |
| /** |
| * Returns the sibling node immediately following this node. |
| * |
| * @return the next node, or <code>null</code> if there is no following node |
| */ |
| public IDOMNode getNextNode(); |
| /** |
| * Returns the type of this node. |
| * |
| * @return one of the node type constants defined in <code>IDOMNode</code> |
| */ |
| public int getNodeType(); |
| /** |
| * Returns the parent of this node. |
| * |
| * @return the parent node, or <code>null</code> if this node does not have a |
| * parent |
| */ |
| public IDOMNode getParent(); |
| /** |
| * Returns the sibling node immediately preceding this node. |
| * |
| * @return the previous node, or <code>null</code> if there is no preceding node |
| */ |
| public IDOMNode getPreviousNode(); |
| /** |
| * Inserts the given un-parented node as a sibling of this node, immediately before |
| * this node. |
| * |
| * @param sibling the new sibling node |
| * @exception DOMException if any of the following conditions hold:<ul> |
| * <li>this node is a document fragment root</li> |
| * <li>the sibling is not of the correct type</li> |
| * <li>the sibling already has a parent</li> |
| * <li>this sibling is an ancestor of this node</li> |
| * </ul> |
| * @exception IllegalArgumentException if the sibling is <code>null</code> |
| * |
| * @see #addChild(IDOMNode) |
| * @see #clone() |
| * @see #remove() |
| */ |
| public void insertSibling(IDOMNode sibling) throws DOMException, IllegalArgumentException; |
| /** |
| * Returns whether the given node is an allowable child for this node. |
| * |
| * @param node the potential child node |
| * @return <code>true</code> if the given node is an allowable child |
| */ |
| public boolean isAllowableChild(IDOMNode node); |
| /** |
| * Returns whether this node's signature is equivalent to the given |
| * node's signature. In other words, if the nodes were siblings, |
| * would the declarations collide because they represent the same declaration. |
| * |
| * @param node the other node |
| * @return <code>true</code> if the nodes have equivalent signatures |
| */ |
| public boolean isSignatureEqual(IDOMNode node); |
| /** |
| * Separates this node from its parent and siblings, maintaining any ties that this node |
| * has to the underlying document fragment. A document fragment that is removed |
| * from its host document may still be dependent on that host document until it is |
| * inserted into a different document. Removing a root node has no effect. |
| * |
| * @see #addChild(IDOMNode) |
| * @see #clone() |
| * @see #insertSibling(IDOMNode) |
| */ |
| public void remove(); |
| /** |
| * Sets the name of this node. Name format depends on node type. |
| * More details are provided in each of the subtypes. |
| * |
| * @param name the name, or <code>null</code> to clear the name |
| */ |
| public void setName(String name); |
| } |