X-Git-Url: http://git.phpeclipse.com diff --git a/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/ICompilationUnit.java b/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/ICompilationUnit.java index c25a7cc..52a777c 100644 --- a/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/ICompilationUnit.java +++ b/net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/ICompilationUnit.java @@ -10,299 +10,396 @@ *******************************************************************************/ package net.sourceforge.phpdt.core; -import net.sourceforge.phpdt.internal.core.ImportContainer; - import org.eclipse.core.runtime.IProgressMonitor; - - /** - * Represents an entire Java compilation unit (.java source file). - * Compilation unit elements need to be opened before they can be navigated or manipulated. - * The children are of type IPackageDeclaration, - * IImportContainer, and IType, - * and appear in the order in which they are declared in the source. - * If a .java file cannot be parsed, its structure remains unknown. - * Use IJavaElement.isStructureKnown to determine whether this is - * the case. + * Represents an entire Java compilation unit (.java source + * file). Compilation unit elements need to be opened before they can be + * navigated or manipulated. The children are of type + * IPackageDeclaration, IImportContainer, and + * IType, and appear in the order in which they are declared in + * the source. If a .java file cannot be parsed, its structure + * remains unknown. Use IJavaElement.isStructureKnown to + * determine whether this is the case. *

* This interface is not intended to be implemented by clients. *

- */ -public interface ICompilationUnit extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, ISourceManipulation { -//extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, ISourceManipulation, ICodeAssist { + */ +public interface ICompilationUnit extends IJavaElement, ISourceReference, + IParent, IOpenable, IWorkingCopy, ISourceManipulation { + // extends IJavaElement, ISourceReference, IParent, IOpenable, IWorkingCopy, + // ISourceManipulation, ICodeAssist { /** * Constant indicating that a reconcile operation should not return an AST. + * * @since 3.0 */ public static final int NO_AST = 0; /** - * Changes this compilation unit handle into a working copy. A new IBuffer is - * created using this compilation unit handle's owner. Uses the primary owner is none was - * specified when this compilation unit handle was created. + * Changes this compilation unit handle into a working copy. A new + * IBuffer is created using this compilation unit handle's + * owner. Uses the primary owner is none was specified when this compilation + * unit handle was created. *

- * When switching to working copy mode, problems are reported to given + * When switching to working copy mode, problems are reported to given * IProblemRequestor. *

*

- * Once in working copy mode, changes to this compilation unit or its children are done in memory. - * Only the new buffer is affected. Using commitWorkingCopy(boolean, IProgressMonitor) - * will bring the underlying resource in sync with this compilation unit. + * Once in working copy mode, changes to this compilation unit or its + * children are done in memory. Only the new buffer is affected. Using + * commitWorkingCopy(boolean, IProgressMonitor) will bring + * the underlying resource in sync with this compilation unit. *

*

- * If this compilation unit was already in working copy mode, an internal counter is incremented and no - * other action is taken on this compilation unit. To bring this compilation unit back into the original mode - * (where it reflects the underlying resource), discardWorkingCopy must be call as many - * times as becomeWorkingCopy. + * If this compilation unit was already in working copy mode, an internal + * counter is incremented and no other action is taken on this compilation + * unit. To bring this compilation unit back into the original mode (where + * it reflects the underlying resource), discardWorkingCopy + * must be call as many times as becomeWorkingCopy. *

* - * @param problemRequestor a requestor which will get notified of problems detected during - * reconciling as they are discovered. The requestor can be set to null indicating - * that the client is not interested in problems. - * @param monitor a progress monitor used to report progress while opening this compilation unit - * or null if no progress should be reported - * @throws JavaModelException if this compilation unit could not become a working copy. + * @param problemRequestor + * a requestor which will get notified of problems detected + * during reconciling as they are discovered. The requestor can + * be set to null indicating that the client is + * not interested in problems. + * @param monitor + * a progress monitor used to report progress while opening this + * compilation unit or null if no progress should + * be reported + * @throws JavaModelException + * if this compilation unit could not become a working copy. * @see #discardWorkingCopy() * @since 3.0 */ - void becomeWorkingCopy(IProblemRequestor problemRequestor, IProgressMonitor monitor) throws JavaModelException; + void becomeWorkingCopy(IProblemRequestor problemRequestor, + IProgressMonitor monitor) throws JavaModelException; + /** * Commits the contents of this working copy to its underlying resource. - * - *

It is possible that the contents of the original resource have changed - * since this working copy was created, in which case there is an update conflict. - * The value of the force parameter effects the resolution of - * such a conflict:

+ * *

- * Since 2.1, a working copy can be created on a not-yet existing compilation - * unit. In particular, such a working copy can then be committed in order to create - * the corresponding compilation unit. - *

- * @param force a flag to handle the cases when the contents of the original resource have changed - * since this working copy was created - * @param monitor the given progress monitor - * @throws JavaModelException if this working copy could not commit. Reasons include: + * It is possible that the contents of the original resource have changed + * since this working copy was created, in which case there is an update + * conflict. The value of the force parameter effects the + * resolution of such a conflict: * + *

+ * Since 2.1, a working copy can be created on a not-yet existing + * compilation unit. In particular, such a working copy can then be + * committed in order to create the corresponding compilation unit. + *

+ * + * @param force + * a flag to handle the cases when the contents of the original + * resource have changed since this working copy was created + * @param monitor + * the given progress monitor + * @throws JavaModelException + * if this working copy could not commit. Reasons include: + * * @since 3.0 */ - void commitWorkingCopy(boolean force, IProgressMonitor monitor) throws JavaModelException; + void commitWorkingCopy(boolean force, IProgressMonitor monitor) + throws JavaModelException; + /** - * Changes this compilation unit in working copy mode back to its original mode. + * Changes this compilation unit in working copy mode back to its original + * mode. *

* This has no effect if this compilation unit was not in working copy mode. *

*

* If becomeWorkingCopy was called several times on this - * compilation unit, discardWorkingCopy must be called as + * compilation unit, discardWorkingCopy must be called as * many times before it switches back to the original mode. *

* - * @throws JavaModelException if this working copy could not return in its original mode. + * @throws JavaModelException + * if this working copy could not return in its original mode. * @see #becomeWorkingCopy(IProblemRequestor, IProgressMonitor) * @since 3.0 */ void discardWorkingCopy() throws JavaModelException; -/** - * Creates and returns an import declaration in this compilation unit - * with the given name. - *

- * Optionally, the new element can be positioned before the specified - * sibling. If no sibling is specified, the element will be inserted - * as the last import declaration in this compilation unit. - *

- * If the compilation unit already includes the specified import declaration, - * the import is not generated (it does not generate duplicates). - * Note that it is valid to specify both a single-type import and an on-demand import - * for the same package, for example "java.io.File" and - * "java.io.*", in which case both are preserved since the semantics - * of this are not the same as just importing "java.io.*". - * Importing "java.lang.*", or the package in which the compilation unit - * is defined, are not treated as special cases. If they are specified, they are - * included in the result. - * - * @param name the name of the import declaration to add as defined by JLS2 7.5. (For example: "java.io.File" or - * "java.awt.*") - * @param sibling the existing element which the import declaration will be inserted immediately before (if - * null , then this import will be inserted as the last import declaration. - * @param monitor the progress monitor to notify - * @return the newly inserted import declaration (or the previously existing one in case attempting to create a duplicate) - * - * @exception JavaModelException if the element could not be created. Reasons include: - *

- */ -//IImportDeclaration createImport(String name, IJavaElement sibling, IProgressMonitor monitor) throws JavaModelException; -/** - * Creates and returns a package declaration in this compilation unit - * with the given package name. - * - *

If the compilation unit already includes the specified package declaration, - * it is not generated (it does not generate duplicates). - * - * @param name the name of the package declaration to add as defined by JLS2 7.4. (For example, "java.lang") - * @param monitor the progress monitor to notify - * @return the newly inserted package declaration (or the previously existing one in case attempting to create a duplicate) - * - * @exception JavaModelException if the element could not be created. Reasons include: - *

- */ -// IPackageDeclaration createPackageDeclaration(String name, IProgressMonitor monitor) throws JavaModelException; -/** - * Creates and returns a type in this compilation unit with the - * given contents. If this compilation unit does not exist, one - * will be created with an appropriate package declaration. - *

- * Optionally, the new type can be positioned before the specified - * sibling. If sibling is null, the type will be appended - * to the end of this compilation unit. - * - *

It is possible that a type with the same name already exists in this compilation unit. - * The value of the force parameter effects the resolution of - * such a conflict:

- * - * @param contents the source contents of the type declaration to add. - * @param sibling the existing element which the type will be inserted immediately before (if - * null , then this type will be inserted as the last type declaration. - * @param force a boolean flag indicating how to deal with duplicates - * @param monitor the progress monitor to notify - * @return the newly inserted type - * - * @exception JavaModelException if the element could not be created. Reasons include: - * - */ -//IType createType(String contents, IJavaElement sibling, boolean force, IProgressMonitor monitor) throws JavaModelException; -/** - * Returns all types declared in this compilation unit in the order - * in which they appear in the source. - * This includes all top-level types and nested member types. - * It does NOT include local types (types defined in methods). - * - * @return the array of top-level and member types defined in a compilation unit, in declaration order. - * @exception JavaModelException if this element does not exist or if an - * exception occurs while accessing its corresponding resource - */ -IType[] getAllTypes() throws JavaModelException; -/** - * Returns the smallest element within this compilation unit that - * includes the given source position (that is, a method, field, etc.), or - * null if there is no element other than the compilation - * unit itself at the given position, or if the given position is not - * within the source range of this compilation unit. - * - * @param position a source position inside the compilation unit - * @return the innermost Java element enclosing a given source position or null - * if none (excluding the compilation unit). - * @exception JavaModelException if the compilation unit does not exist or if an - * exception occurs while accessing its corresponding resource - */ -IJavaElement getElementAt(int position) throws JavaModelException; -/** - * Returns the first import declaration in this compilation unit with the given name. - * This is a handle-only method. The import declaration may or may not exist. This - * is a convenience method - imports can also be accessed from a compilation unit's - * import container. - * - * @param name the name of the import to find as defined by JLS2 7.5. (For example: "java.io.File" - * or "java.awt.*") - * @return a handle onto the corresponding import declaration. The import declaration may or may not exist. - */ -//IImportDeclaration getImport(String name) ; -/** - * Returns the import container for this compilation unit. - * This is a handle-only method. The import container may or - * may not exist. The import container can used to access the - * imports. - * @return a handle onto the corresponding import container. The - * import contain may or may not exist. - */ -ImportContainer getImportContainer(); -/** - * Returns the import declarations in this compilation unit - * in the order in which they appear in the source. This is - * a convenience method - import declarations can also be - * accessed from a compilation unit's import container. - * - * @exception JavaModelException if this element does not exist or if an - * exception occurs while accessing its corresponding resource - */ -//IImportDeclaration[] getImports() throws JavaModelException; -/** - * Returns the first package declaration in this compilation unit with the given package name - * (there normally is at most one package declaration). - * This is a handle-only method. The package declaration may or may not exist. - * - * @param name the name of the package declaration as defined by JLS2 7.4. (For example, "java.lang") - */ -IPackageDeclaration getPackageDeclaration(String name); -/** - * Returns the package declarations in this compilation unit - * in the order in which they appear in the source. - * There normally is at most one package declaration. - * - * @return an array of package declaration (normally of size one) - * - * @exception JavaModelException if this element does not exist or if an - * exception occurs while accessing its corresponding resource - */ -//IPackageDeclaration[] getPackageDeclarations() throws JavaModelException; -/** - * Returns the primary compilation unit (whose owner is the primary owner) - * this working copy was created from, or this compilation unit if this a primary - * compilation unit. - *

- * Note that the returned primary compilation unit can be in working copy mode. - *

- * - * @return the primary compilation unit this working copy was created from, - * or this compilation unit if it is primary - * @since 3.0 - */ -ICompilationUnit getPrimary(); -/** - * Returns the top-level type declared in this compilation unit with the given simple type name. - * The type name has to be a valid compilation unit name. - * This is a handle-only method. The type may or may not exist. - * - * @param name the simple name of the requested type in the compilation unit - * @return a handle onto the corresponding type. The type may or may not exist. - * @see JavaConventions#validateCompilationUnitName(String name) - */ -IType getType(String name); -/** - * Returns the top-level types declared in this compilation unit - * in the order in which they appear in the source. - * - * @exception JavaModelException if this element does not exist or if an - * exception occurs while accessing its corresponding resource - */ -IType[] getTypes() throws JavaModelException; + + /** + * Creates and returns an import declaration in this compilation unit with + * the given name. + *

+ * Optionally, the new element can be positioned before the specified + * sibling. If no sibling is specified, the element will be inserted as the + * last import declaration in this compilation unit. + *

+ * If the compilation unit already includes the specified import + * declaration, the import is not generated (it does not generate + * duplicates). Note that it is valid to specify both a single-type import + * and an on-demand import for the same package, for example + * "java.io.File" and "java.io.*", in which + * case both are preserved since the semantics of this are not the same as + * just importing "java.io.*". Importing + * "java.lang.*", or the package in which the compilation + * unit is defined, are not treated as special cases. If they are specified, + * they are included in the result. + * + * @param name + * the name of the import declaration to add as defined by JLS2 + * 7.5. (For example: "java.io.File" or + * "java.awt.*") + * @param sibling + * the existing element which the import declaration will be + * inserted immediately before (if null , then + * this import will be inserted as the last import declaration. + * @param monitor + * the progress monitor to notify + * @return the newly inserted import declaration (or the previously existing + * one in case attempting to create a duplicate) + * + * @exception JavaModelException + * if the element could not be created. Reasons include: + *

+ */ + // IImportDeclaration createImport(String name, IJavaElement sibling, + // IProgressMonitor monitor) throws JavaModelException; + /** + * Creates and returns a package declaration in this compilation unit with + * the given package name. + * + *

+ * If the compilation unit already includes the specified package + * declaration, it is not generated (it does not generate duplicates). + * + * @param name + * the name of the package declaration to add as defined by JLS2 + * 7.4. (For example, "java.lang") + * @param monitor + * the progress monitor to notify + * @return the newly inserted package declaration (or the previously + * existing one in case attempting to create a duplicate) + * + * @exception JavaModelException + * if the element could not be created. Reasons include: + *

+ */ + // IPackageDeclaration createPackageDeclaration(String name, + // IProgressMonitor monitor) throws JavaModelException; + /** + * Creates and returns a type in this compilation unit with the given + * contents. If this compilation unit does not exist, one will be created + * with an appropriate package declaration. + *

+ * Optionally, the new type can be positioned before the specified sibling. + * If sibling is null, the type will be + * appended to the end of this compilation unit. + * + *

+ * It is possible that a type with the same name already exists in this + * compilation unit. The value of the force parameter effects + * the resolution of such a conflict: + *

+ * + * @param contents + * the source contents of the type declaration to add. + * @param sibling + * the existing element which the type will be inserted + * immediately before (if null , then this type + * will be inserted as the last type declaration. + * @param force + * a boolean flag indicating how to deal with + * duplicates + * @param monitor + * the progress monitor to notify + * @return the newly inserted type + * + * @exception JavaModelException + * if the element could not be created. Reasons include: + * + */ + // IType createType(String contents, IJavaElement sibling, boolean force, + // IProgressMonitor monitor) throws JavaModelException; + /** + * Returns all types declared in this compilation unit in the order in which + * they appear in the source. This includes all top-level types and nested + * member types. It does NOT include local types (types defined in methods). + * + * @return the array of top-level and member types defined in a compilation + * unit, in declaration order. + * @exception JavaModelException + * if this element does not exist or if an exception occurs + * while accessing its corresponding resource + */ + IType[] getAllTypes() throws JavaModelException; + + /** + * Returns the smallest element within this compilation unit that includes + * the given source position (that is, a method, field, etc.), or + * null if there is no element other than the compilation + * unit itself at the given position, or if the given position is not within + * the source range of this compilation unit. + * + * @param position + * a source position inside the compilation unit + * @return the innermost Java element enclosing a given source position or + * null if none (excluding the compilation unit). + * @exception JavaModelException + * if the compilation unit does not exist or if an exception + * occurs while accessing its corresponding resource + */ + IJavaElement getElementAt(int position) throws JavaModelException; + + /** + * Returns the first import declaration in this compilation unit with the + * given name. This is a handle-only method. The import declaration may or + * may not exist. This is a convenience method - imports can also be + * accessed from a compilation unit's import container. + * + * @param name + * the name of the import to find as defined by JLS2 7.5. (For + * example: "java.io.File" or + * "java.awt.*") + * @return a handle onto the corresponding import declaration. The import + * declaration may or may not exist. + */ + IImportDeclaration getImport(String name); + + /** + * Returns the import declarations in this compilation unit in the order in + * which they appear in the source. This is a convenience method - import + * declarations can also be accessed from a compilation unit's import + * container. + * + * @return the import declarations in this compilation unit + * @throws JavaModelException + * if this element does not exist or if an exception occurs + * while accessing its corresponding resource + */ + IImportDeclaration[] getImports() throws JavaModelException; + + /** + * Returns the import container for this compilation unit. This is a + * handle-only method. The import container may or may not exist. The import + * container can used to access the imports. + * + * @return a handle onto the corresponding import container. The import + * contain may or may not exist. + */ + IImportContainer getImportContainer(); + + /** + * Returns the import declarations in this compilation unit in the order in + * which they appear in the source. This is a convenience method - import + * declarations can also be accessed from a compilation unit's import + * container. + * + * @exception JavaModelException + * if this element does not exist or if an exception occurs + * while accessing its corresponding resource + */ + // IImportDeclaration[] getImports() throws JavaModelException; + /** + * Returns the first package declaration in this compilation unit with the + * given package name (there normally is at most one package declaration). + * This is a handle-only method. The package declaration may or may not + * exist. + * + * @param name + * the name of the package declaration as defined by JLS2 7.4. + * (For example, "java.lang") + */ + IPackageDeclaration getPackageDeclaration(String name); + + /** + * Returns the package declarations in this compilation unit in the order in + * which they appear in the source. There normally is at most one package + * declaration. + * + * @return an array of package declaration (normally of size one) + * + * @exception JavaModelException + * if this element does not exist or if an exception occurs + * while accessing its corresponding resource + */ + IPackageDeclaration[] getPackageDeclarations() throws JavaModelException; + + /** + * Returns the primary compilation unit (whose owner is the primary owner) + * this working copy was created from, or this compilation unit if this a + * primary compilation unit. + *

+ * Note that the returned primary compilation unit can be in working copy + * mode. + *

+ * + * @return the primary compilation unit this working copy was created from, + * or this compilation unit if it is primary + * @since 3.0 + */ + ICompilationUnit getPrimary(); + + /** + * Returns the top-level type declared in this compilation unit with the + * given simple type name. The type name has to be a valid compilation unit + * name. This is a handle-only method. The type may or may not exist. + * + * @param name + * the simple name of the requested type in the compilation unit + * @return a handle onto the corresponding type. The type may or may not + * exist. + * @see JavaConventions#validateCompilationUnitName(String name) + */ + IType getType(String name); + + /** + * Returns the top-level types declared in this compilation unit in the + * order in which they appear in the source. + * + * @exception JavaModelException + * if this element does not exist or if an exception occurs + * while accessing its corresponding resource + */ + IType[] getTypes() throws JavaModelException; }