/*******************************************************************************
* Copyright (c) 2000, 2003 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Common Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/cpl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package net.sourceforge.phpdt.core.jdom;
import java.util.Enumeration;
import net.sourceforge.phpdt.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 (IDOMCompilationUnit
).
* In this way, a DF is comprised of DFs, and a document itself (compilation
* unit) is also a DF.
*
* A DF may be created empty and programmatically filled, or it may be created
* from a source code string. The IDOMFactory
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.
*
* 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. *
** 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. *
** The following manipulations on DFs are distinct: *
* 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 "Object"
,
* "java.io.File"
, and "int[]"
.
*
* 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 toIDOMCompilationUnit
.
*
* @see #getNodeType
*/
public static int COMPILATION_UNIT = 1;
/**
* Node type constant indicating a package declaration. Nodes of this type
* maybe by safely cast to IDOMPackage
.
*
* @see #getNodeType
*/
public static int PACKAGE = 2;
/**
* Node type constant indicating an import declaration. Nodes of this type
* maybe by safely cast to IDOMImport
.
*
* @see #getNodeType
*/
public static int IMPORT = 3;
/**
* Node type constant indicating a type declaration. Nodes of this type
* maybe by safely cast to IDOMType
.
*
* @see #getNodeType
*/
public static int TYPE = 4;
/**
* Node type constant indicating a field declaration. Nodes of this type
* maybe by safely cast to IDOMField
.
*
* @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 IDOMMethod
.
*
* @see #getNodeType
*/
public static int METHOD = 6;
/**
* Node type constant indicating an initializer declaration. Nodes of this
* type maybe by safely cast to IDOMInitializer
.
*
* @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:
* null
*
* @see #insertSibling
* @see #remove
*/
public void addChild(IDOMNode child) throws DOMException,
IllegalArgumentException;
/**
* Returns whether this node is allowed to have children.
*
* @return true
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 IDOMNode
* @see #addChild
* @see #insertSibling
* @see #remove
*/
public Object clone();
/**
* Returns the current contents of this document fragment as a character
* array.
* * Note: To obtain complete source for the ".java" file, ask a compilation * unit node for its contents. *
* * @return the contents, ornull
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 null
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.
* * Note: To obtain complete source for the ".java" file, ask a compilation * unit node for its contents. *
* * @return the contents, ornull
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 null
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
*/
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 null
if it has no name
*/
public String getName();
/**
* Returns the sibling node immediately following this node.
*
* @return the next node, or null
if there is no following
* node
*/
public IDOMNode getNextNode();
/**
* Returns the type of this node.
*
* @return one of the node type constants defined in IDOMNode
*/
public int getNodeType();
/**
* Returns the parent of this node.
*
* @return the parent node, or null
if this node does not
* have a parent
*/
public IDOMNode getParent();
/**
* Returns the sibling node immediately preceding this node.
*
* @return the previous node, or null
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:
* null
*
* @see #addChild
* @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 true
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 true
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
* @see #clone
* @see #insertSibling
*/
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 null
to clear the name
*/
public void setName(String name);
}