/*******************************************************************************
* Copyright (c) 2000, 2010 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
* IBM Corporation - added getOption(String, boolean), getOptions(boolean) and setOptions(Map)
* IBM Corporation - deprecated getPackageFragmentRoots(IClasspathEntry) and
* added findPackageFragmentRoots(IClasspathEntry)
* IBM Corporation - added isOnClasspath(IResource)
* IBM Corporation - added setOption(String, String)
* IBM Corporation - added forceClasspathReload(IProgressMonitor)
*******************************************************************************/
package org.eclipse.jdt.core;
import java.util.Map;
import org.eclipse.core.resources.IProject;
import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.jdt.core.dom.IAnnotationBinding;
import org.eclipse.jdt.core.dom.IMethodBinding;
import org.eclipse.jdt.core.dom.IPackageBinding;
import org.eclipse.jdt.core.dom.ITypeBinding;
import org.eclipse.jdt.core.dom.IVariableBinding;
import org.eclipse.jdt.core.eval.IEvaluationContext;
/**
* A Java project represents a view of a project resource in terms of Java elements such as package
* fragments, types, methods and fields. A project may contain several package roots, which contain
* package fragments. A package root corresponds to an underlying folder or JAR.
* <p>
* Each Java project has a classpath, defining which folders contain source code and where required
* libraries are located. Each Java project also has an output location, defining where the builder
* writes <code>.class</code> files. A project that references packages in another project can
* access the packages by including the required project in a classpath entry. The Java model will
* present the source elements in the required project; when building, the compiler will use the
* corresponding generated class files from the required project's output location(s)). The
* classpath format is a sequence of classpath entries describing the location and contents of
* package fragment roots.
* </p>
* Java project elements need to be opened before they can be navigated or manipulated. The children
* of a Java project are the package fragment roots that are defined by the classpath and contained
* in this project (in other words, it does not include package fragment roots for other projects).
* </p>
* <p>
* An instance of one of these handles can be created via <code>JavaCore.create(project)</code>.
* </p>
*
* @see JavaCore#create(org.eclipse.core.resources.IProject)
* @see IClasspathEntry
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IJavaProject extends IParent, IJavaElement, IOpenable {
/**
* Decodes the classpath entry that has been encoded in the given string in the context of this
* project. Returns null if the encoded entry is malformed.
*
* @param encodedEntry the encoded classpath entry
* @return the decoded classpath entry, or <code>null</code> if unable to decode it
* @since 3.2
*/
IClasspathEntry decodeClasspathEntry(String encodedEntry);
/**
* Encodes the given classpath entry into a string in the context of this project.
*
* @param classpathEntry the classpath entry to encode
* @return the encoded classpath entry
* @since 3.2
*/
String encodeClasspathEntry(IClasspathEntry classpathEntry);
/**
* Returns the <code>IJavaElement</code> corresponding to the given classpath-relative path, or
* <code>null</code> if no such <code>IJavaElement</code> is found. The result is one of an
* <code>ICompilationUnit</code>, <code>IClassFile</code>, or <code>IPackageFragment</code>.
* <p>
* When looking for a package fragment, there might be several potential matches; only one of
* them is returned.
*
* <p>
* For example, the path "java/lang/Object.java", would result in the
* <code>ICompilationUnit</code> or <code>IClassFile</code> corresponding to "java.lang.Object".
* The path "java/lang" would result in the <code>IPackageFragment</code> for "java.lang".
*
* @param path the given classpath-relative path
* @exception JavaModelException if the given path is <code>null</code> or absolute
* @return the <code>IJavaElement</code> corresponding to the given classpath-relative path, or
* <code>null</code> if no such <code>IJavaElement</code> is found
*/
IJavaElement findElement(IPath path) throws JavaModelException;
/**
* Returns the <code>IJavaElement</code> corresponding to the given classpath-relative path, or
* <code>null</code> if no such <code>IJavaElement</code> is found. The result is one of an
* <code>ICompilationUnit</code>, <code>IClassFile</code>, or <code>IPackageFragment</code>. If
* it is an <code>ICompilationUnit</code>, its owner is the given owner.
* <p>
* When looking for a package fragment, there might be several potential matches; only one of
* them is returned.
*
* <p>
* For example, the path "java/lang/Object.java", would result in the
* <code>ICompilationUnit</code> or <code>IClassFile</code> corresponding to "java.lang.Object".
* The path "java/lang" would result in the <code>IPackageFragment</code> for "java.lang".
*
* @param path the given classpath-relative path
* @param owner the owner of the returned compilation unit, ignored if it is not a compilation
* unit.
* @exception JavaModelException if the given path is <code>null</code> or absolute
* @return the <code>IJavaElement</code> corresponding to the given classpath-relative path, or
* <code>null</code> if no such <code>IJavaElement</code> is found
* @since 3.0
*/
IJavaElement findElement(IPath path, WorkingCopyOwner owner) throws JavaModelException;
/**
* Finds the Java element corresponding to the given binding key if any, else returns
* <code>null</code>. Elements are looked up using this project's classpath. The first element
* corresponding to the given key on this project's classpath is returned.
* <p>
* Possible elements are:
* <ul>
* <li>{@link IPackageFragment} for a binding key from an {@link IPackageBinding}</li>
* <li>{@link IType} for a binding key from an {@link ITypeBinding}</li>
* <li>{@link IMethod} for a binding key from an {@link IMethodBinding}</li>
* <li>{@link IField} for a binding key from an {@link IVariableBinding} representing a
* {@link IVariableBinding#isField() field}</li>
* <li>{@link ITypeParameter} for a binding key from an {@link ITypeBinding} representing a
* {@link ITypeBinding#isTypeVariable() type variable}</li>
* <li>{@link IAnnotation} for a binding key from an {@link IAnnotationBinding}</li>
* </ul>
* </p>
* <p>
* Note: if two methods correspond to the binding key because their parameter types' simple
* names are the same, then the first one is returned. For example, if a class defines two
* methods <code>foo(p1.Y, String)</code> and <code>foo(p2.Y, String)</code>, in both cases the
* parameter type's simple names are <code>{"Y", "String"}</code>. Thus
* <code>foo(p1.Y, String)</code> is returned.
* </p>
*
* @param bindingKey the given binding key
* @param owner the owner of the returned element's compilation unit, or <code>null</code> if
* the default working copy owner must be used
* @exception JavaModelException if this project does not exist or if an exception occurs while
* accessing its corresponding resource
* @return the Java element corresponding to the given key, or <code>null</code> if no such Java
* element is found
* @since 3.4
*/
IJavaElement findElement(String bindingKey, WorkingCopyOwner owner) throws JavaModelException;
/**
* Returns the first existing package fragment on this project's classpath whose path matches
* the given (absolute) path, or <code>null</code> if none exist. The path can be: - internal to
* the workbench: "/Project/src" - external to the workbench: "c:/jdk/classes.zip/java/lang"
*
* @param path the given absolute path
* @exception JavaModelException if this project does not exist or if an exception occurs while
* accessing its corresponding resource
* @return the first existing package fragment on this project's classpath whose path matches
* the given (absolute) path, or <code>null</code> if none exist
*/
IPackageFragment findPackageFragment(IPath path) throws JavaModelException;
/**
* Returns the existing package fragment root on this project's classpath whose path matches the
* given (absolute) path, or <code>null</code> if one does not exist. The path can be: -
* internal to the workbench: "/Compiler/src" - external to the workbench: "c:/jdk/classes.zip"
*
* @param path the given absolute path
* @exception JavaModelException if this project does not exist or if an exception occurs while
* accessing its corresponding resource
* @return the existing package fragment root on this project's classpath whose path matches the
* given (absolute) path, or <code>null</code> if one does not exist
*/
IPackageFragmentRoot findPackageFragmentRoot(IPath path)
throws JavaModelException;
/**
* Returns the existing package fragment roots identified by the given entry. Note that a
* classpath entry that refers to another project may have more than one root (if that project
* has more than on root containing source), and classpath entries within the current project
* identify a single root.
* <p>
* If the classpath entry denotes a variable, it will be resolved and return the roots of the
* target entry (empty if not resolvable).
* <p>
* If the classpath entry denotes a container, it will be resolved and return the roots
* corresponding to the set of container entries (empty if not resolvable).
*
* @param entry the given entry
* @return the existing package fragment roots identified by the given entry
* @see IClasspathContainer
* @since 2.1
*/
IPackageFragmentRoot[] findPackageFragmentRoots(IClasspathEntry entry);
/**
* Returns the first type found following this project's classpath with the given fully
* qualified name or <code>null</code> if none is found. The fully qualified name is a
* dot-separated name. For example, a class B defined as a member type of a class A in package
* x.y should have a the fully qualified name "x.y.A.B".
*
* Note that in order to be found, a type name (or its toplevel enclosing type name) must match
* its corresponding compilation unit name. As a consequence, secondary types cannot be found
* using this functionality. To find secondary types use
* {@link #findType(String, IProgressMonitor)} instead.
*
* @param fullyQualifiedName the given fully qualified name
* @exception JavaModelException if this project does not exist or if an exception occurs while
* accessing its corresponding resource
* @return the first type found following this project's classpath with the given fully
* qualified name or <code>null</code> if none is found
* @see IType#getFullyQualifiedName(char)
* @since 2.0
*/
IType findType(String fullyQualifiedName) throws JavaModelException;
/**
* Same functionality as {@link #findType(String)} but also look for secondary types if given
* name does not match a compilation unit name.
*
* @param fullyQualifiedName the given fully qualified name
* @param progressMonitor the progress monitor to report progress to, or <code>null</code> if no
* progress monitor is provided
* @exception JavaModelException if this project does not exist or if an exception occurs while
* accessing its corresponding resource
* @return the first type found following this project's classpath with the given fully
* qualified name or <code>null</code> if none is found
* @see IType#getFullyQualifiedName(char)
* @since 3.2
*/
IType findType(String fullyQualifiedName, IProgressMonitor progressMonitor) throws JavaModelException;
/**
* Returns the first type found following this project's classpath with the given fully
* qualified name or <code>null</code> if none is found. The fully qualified name is a
* dot-separated name. For example, a class B defined as a member type of a class A in package
* x.y should have a the fully qualified name "x.y.A.B". If the returned type is part of a
* compilation unit, its owner is the given owner.
*
* Note that in order to be found, a type name (or its toplevel enclosing type name) must match
* its corresponding compilation unit name. As a consequence, secondary types cannot be found
* using this functionality. To find secondary types use
* {@link #findType(String, WorkingCopyOwner, IProgressMonitor)} instead.
*
* @param fullyQualifiedName the given fully qualified name
* @param owner the owner of the returned type's compilation unit
* @exception JavaModelException if this project does not exist or if an exception occurs while
* accessing its corresponding resource
* @return the first type found following this project's classpath with the given fully
* qualified name or <code>null</code> if none is found
* @see IType#getFullyQualifiedName(char)
* @since 3.0
*/
IType findType(String fullyQualifiedName, WorkingCopyOwner owner) throws JavaModelException;
/**
* Same functionality as {@link #findType(String, WorkingCopyOwner)} but also look for secondary
* types if given name does not match a compilation unit name.
*
* @param fullyQualifiedName the given fully qualified name
* @param owner the owner of the returned type's compilation unit
* @param progressMonitor the progress monitor to report progress to, or <code>null</code> if no
* progress monitor is provided
* @exception JavaModelException if this project does not exist or if an exception occurs while
* accessing its corresponding resource
* @return the first type found following this project's classpath with the given fully
* qualified name or <code>null</code> if none is found
* @see IType#getFullyQualifiedName(char)
* @since 3.2
*/
IType findType(String fullyQualifiedName, WorkingCopyOwner owner, IProgressMonitor progressMonitor) throws JavaModelException;
/**
* Returns the first type found following this project's classpath with the given package name
* and type qualified name or <code>null</code> if none is found. The package name is a
* dot-separated name. The type qualified name is also a dot-separated name. For example, a
* class B defined as a member type of a class A should have the type qualified name "A.B".
*
* Note that in order to be found, a type name (or its toplevel enclosing type name) must match
* its corresponding compilation unit name. As a consequence, secondary types cannot be found
* using this functionality. To find secondary types use
* {@link #findType(String, String, IProgressMonitor)} instead.
*
* @param packageName the given package name
* @param typeQualifiedName the given type qualified name
* @exception JavaModelException if this project does not exist or if an exception occurs while
* accessing its corresponding resource
* @return the first type found following this project's classpath with the given package name
* and type qualified name or <code>null</code> if none is found
* @see IType#getTypeQualifiedName(char)
* @since 2.0
*/
IType findType(String packageName, String typeQualifiedName) throws JavaModelException;
/**
* Same functionality as {@link #findType(String, String)} but also look for secondary types if
* given name does not match a compilation unit name.
*
* @param packageName the given package name
* @param typeQualifiedName the given type qualified name
* @param progressMonitor the progress monitor to report progress to, or <code>null</code> if no
* progress monitor is provided
* @exception JavaModelException if this project does not exist or if an exception occurs while
* accessing its corresponding resource
* @return the first type found following this project's classpath with the given fully
* qualified name or <code>null</code> if none is found
* @see IType#getFullyQualifiedName(char)
* @since 3.2
*/
IType findType(String packageName, String typeQualifiedName, IProgressMonitor progressMonitor) throws JavaModelException;
/**
* Returns the first type found following this project's classpath with the given package name
* and type qualified name or <code>null</code> if none is found. The package name is a
* dot-separated name. The type qualified name is also a dot-separated name. For example, a
* class B defined as a member type of a class A should have the type qualified name "A.B". If
* the returned type is part of a compilation unit, its owner is the given owner.
*
* Note that in order to be found, a type name (or its toplevel enclosing type name) must match
* its corresponding compilation unit name. As a consequence, secondary types cannot be found
* using this functionality. To find secondary types use
* {@link #findType(String, String, WorkingCopyOwner, IProgressMonitor)} instead.
*
* @param packageName the given package name
* @param typeQualifiedName the given type qualified name
* @param owner the owner of the returned type's compilation unit
* @exception JavaModelException if this project does not exist or if an exception occurs while
* accessing its corresponding resource
* @return the first type found following this project's classpath with the given package name
* and type qualified name or <code>null</code> if none is found
* @see IType#getTypeQualifiedName(char)
* @since 3.0
*/
IType findType(String packageName, String typeQualifiedName, WorkingCopyOwner owner) throws JavaModelException;
/**
* Same functionality as {@link #findType(String, String, WorkingCopyOwner)} but also look for
* secondary types if given name does not match a compilation unit name.
*
* @param packageName the given package name
* @param typeQualifiedName the given type qualified name
* @param owner the owner of the returned type's compilation unit
* @param progressMonitor the progress monitor to report progress to, or <code>null</code> if no
* progress monitor is provided
* @exception JavaModelException if this project does not exist or if an exception occurs while
* accessing its corresponding resource
* @return the first type found following this project's classpath with the given fully
* qualified name or <code>null</code> if none is found
* @see IType#getFullyQualifiedName(char)
* @since 3.2
*/
IType findType(String packageName, String typeQualifiedName, WorkingCopyOwner owner, IProgressMonitor progressMonitor) throws JavaModelException;
/**
* Returns all of the existing package fragment roots that exist on the classpath, in the order
* they are defined by the classpath.
*
* @return all of the existing package fragment roots that exist on the classpath
* @exception JavaModelException if this element does not exist or if an exception occurs while
* accessing its corresponding resource
*/
IPackageFragmentRoot[] getAllPackageFragmentRoots() throws JavaModelException;
/**
* Returns an array of non-Java resources directly contained in this project. It does not
* transitively answer non-Java resources contained in folders; these would have to be
* explicitly iterated over.
* <p>
* Non-Java resources includes other files and folders located in the project not accounted for
* by any of it source or binary package fragment roots. If the project is a source folder
* itself, resources excluded from the corresponding source classpath entry by one or more
* exclusion patterns are considered non-Java resources and will appear in the result (possibly
* in a folder)
* </p>
*
* @return an array of non-Java resources (<code>IFile</code>s and/or <code>IFolder</code>s)
* directly contained in this project
* @exception JavaModelException if this element does not exist or if an exception occurs while
* accessing its corresponding resource
*/
Object[] getNonJavaResources() throws JavaModelException;
/**
* Helper method for returning one option value only. Equivalent to
* <code>(String)this.getOptions(inheritJavaCoreOptions).get(optionName)</code> Note that it may
* answer <code>null</code> if this option does not exist, or if there is no custom value for
* it.
* <p>
* For a complete description of the configurable options, see
* <code>JavaCore#getDefaultOptions</code>.
* </p>
*
* @param optionName the name of an option
* @param inheritJavaCoreOptions - boolean indicating whether JavaCore options should be
* inherited as well
* @return the String value of a given option
* @see JavaCore#getDefaultOptions()
* @since 2.1
*/
String getOption(String optionName, boolean inheritJavaCoreOptions);
/**
* Returns the table of the current custom options for this project. Projects remember their
* custom options, in other words, only the options different from the the JavaCore global
* options for the workspace. A boolean argument allows to directly merge the project options
* with global ones from <code>JavaCore</code>.
* <p>
* For a complete description of the configurable options, see
* <code>JavaCore#getDefaultOptions</code>.
* </p>
*
* @param inheritJavaCoreOptions - boolean indicating whether JavaCore options should be
* inherited as well
* @return table of current settings of all options (key type: <code>String</code>; value type:
* <code>String</code>)
* @see JavaCore#getDefaultOptions()
* @since 2.1
*/
Map getOptions(boolean inheritJavaCoreOptions);
/**
* Returns the default output location for this project as a workspace- relative absolute path.
* <p>
* The default output location is where class files are ordinarily generated (and resource
* files, copied). Each source classpath entry can also specify an output location for the
* generated class files (and copied resource files) corresponding to compilation units under
* that source folder. This makes it possible to arrange generated class files for different
* source folders in different output folders, and not necessarily the default output folder.
* This means that the generated class files for the project may end up scattered across several
* folders, rather than all in the default output folder (which is more standard).
* </p>
*
* @return the workspace-relative absolute path of the default output folder
* @exception JavaModelException if this element does not exist
* @see #setOutputLocation(org.eclipse.core.runtime.IPath, IProgressMonitor)
* @see IClasspathEntry#getOutputLocation()
*/
IPath getOutputLocation() throws JavaModelException;
/**
* Returns a package fragment root for an external library (a ZIP archive - e.g. a
* <code>.jar</code>, a <code>.zip</code> file, etc. - or - since 3.4 - a class folder) at the
* specified file system path. This is a handle-only method. The underlying
* <code>java.io.File</code> may or may not exist. No resource is associated with this local
* library package fragment root.
*
* @param externalLibraryPath the library's file system path
* @return a package fragment root for the external library at the specified file system path
*/
IPackageFragmentRoot getPackageFragmentRoot(String externalLibraryPath);
/**
* Returns a package fragment root for the given resource, which must either be a folder
* representing the top of a package hierarchy, or a ZIP archive (e.g. a <code>.jar</code>, a
* <code>.zip</code> file, etc.) This is a handle-only method. The underlying resource may or
* may not exist.
*
* @param resource the given resource
* @return a package fragment root for the given resource, which must either be a folder
* representing the top of a package hierarchy, or a ZIP archive (e.g. a
* <code>.jar</code>, a <code>.zip</code> file, etc.)
*/
IPackageFragmentRoot getPackageFragmentRoot(IResource resource);
/**
* Returns all of the package fragment roots contained in this project, identified on this
* project's resolved classpath. The result does not include package fragment roots in other
* projects referenced on this project's classpath.
*
* <p>
* NOTE: This is equivalent to <code>getChildren()</code>.
*
* @return all of the package fragment roots contained in this project, identified on this
* project's resolved classpath
* @exception JavaModelException if this element does not exist or if an exception occurs while
* accessing its corresponding resource
*/
IPackageFragmentRoot[] getPackageFragmentRoots() throws JavaModelException;
/**
* Returns the existing package fragment roots identified by the given entry. Note that a
* classpath entry that refers to another project may have more than one root (if that project
* has more than on root containing source), and classpath entries within the current project
* identify a single root.
* <p>
* If the classpath entry denotes a variable, it will be resolved and return the roots of the
* target entry (empty if not resolvable).
* <p>
* If the classpath entry denotes a container, it will be resolved and return the roots
* corresponding to the set of container entries (empty if not resolvable).
*
* @param entry the given entry
* @return the existing package fragment roots identified by the given entry
* @see IClasspathContainer
* @deprecated Use {@link IJavaProject#findPackageFragmentRoots(IClasspathEntry)} instead
*/
IPackageFragmentRoot[] getPackageFragmentRoots(IClasspathEntry entry);
/**
* Returns all package fragments in all package fragment roots contained in this project. This
* is a convenience method.
*
* Note that the package fragment roots corresponds to the resolved classpath of the project.
*
* @return all package fragments in all package fragment roots contained in this project
* @exception JavaModelException if this element does not exist or if an exception occurs while
* accessing its corresponding resource
*/
IPackageFragment[] getPackageFragments() throws JavaModelException;
/**
* Returns the <code>IProject</code> on which this <code>IJavaProject</code> was created. This
* is handle-only method.
*
* @return the <code>IProject</code> on which this <code>IJavaProject</code> was created
*/
IProject getProject();
/**
* Returns the raw classpath for the project, as a list of classpath entries. This corresponds
* to the exact set of entries which were assigned using <code>setRawClasspath</code>, in
* particular such a classpath may contain classpath variable and classpath container entries.
* Classpath variable and classpath container entries can be resolved using the helper method
* <code>getResolvedClasspath</code>; classpath variable entries also can be resolved
* individually using <code>JavaCore#getClasspathVariable</code>).
* <p>
* Both classpath containers and classpath variables provides a level of indirection that can
* make the <code>.classpath</code> file stable across workspaces. As an example, classpath
* variables allow a classpath to no longer refer directly to external JARs located in some user
* specific location. The classpath can simply refer to some variables defining the proper
* locations of these external JARs. Similarly, classpath containers allows classpath entries to
* be computed dynamically by the plug-in that defines that kind of classpath container.
* </p>
* <p>
* Note that in case the project isn't yet opened, the classpath will be read directly from the
* associated <tt>.classpath</tt> file.
* </p>
*
* @return the raw classpath for the project, as a list of classpath entries
* @exception JavaModelException if this element does not exist or if an exception occurs while
* accessing its corresponding resource
* @see IClasspathEntry
*/
IClasspathEntry[] getRawClasspath() throws JavaModelException;
/**
* Returns the names of the projects that are directly required by this project. A project is
* required if it is in its classpath.
* <p>
* The project names are returned in the order they appear on the classpath.
*
* @return the names of the projects that are directly required by this project in classpath
* order
* @exception JavaModelException if this element does not exist or if an exception occurs while
* accessing its corresponding resource
*/
String[] getRequiredProjectNames() throws JavaModelException;
/**
* This is a helper method returning the resolved classpath for the project as a list of simple
* (non-variable, non-container) classpath entries. All classpath variable and classpath
* container entries in the project's raw classpath will be replaced by the simple classpath
* entries they resolve to.
* <p>
* The resulting resolved classpath is accurate for the given point in time. If the project's
* raw classpath is later modified, or if classpath variables are changed, the resolved
* classpath can become out of date. Because of this, hanging on resolved classpath is not
* recommended.
* </p>
* <p>
* Note that if the resolution creates duplicate entries (i.e. {@link IClasspathEntry entries}
* which are {@link Object#equals(Object)}), only the first one is added to the resolved
* classpath.
* </p>
*
* @param ignoreUnresolvedEntry indicates how to handle unresolvable variables and containers;
* <code>true</code> indicates that missing variables and unresolvable classpath
* containers should be silently ignored, and that the resulting list should consist
* only of the entries that could be successfully resolved; <code>false</code>
* indicates that a <code>JavaModelException</code> should be thrown for the first
* unresolved variable or container
* @return the resolved classpath for the project as a list of simple classpath entries, where
* all classpath variable and container entries have been resolved and substituted with
* their final target entries
* @exception JavaModelException in one of the corresponding situation:
* <ul>
* <li>this element does not exist</li>
* <li>an exception occurs while accessing its corresponding resource</li>
* <li>a classpath variable or classpath container was not resolvable and
* <code>ignoreUnresolvedEntry</code> is <code>false</code>.</li>
* </ul>
* @see IClasspathEntry
*/
IClasspathEntry[] getResolvedClasspath(boolean ignoreUnresolvedEntry)
throws JavaModelException;
/**
* Returns whether this project has been built at least once and thus whether it has a build
* state.
*
* @return true if this project has been built at least once, false otherwise
*/
boolean hasBuildState();
/**
* Returns whether setting this project's classpath to the given classpath entries would result
* in a cycle.
*
* If the set of entries contains some variables, those are resolved in order to determine
* cycles.
*
* @param entries the given classpath entries
* @return true if the given classpath entries would result in a cycle, false otherwise
*/
boolean hasClasspathCycle(IClasspathEntry[] entries);
/**
* Returns whether the given element is on the classpath of this project, that is, referenced
* from a classpath entry and not explicitly excluded using an exclusion pattern.
*
* @param element the given element
* @return <code>true</code> if the given element is on the classpath of this project,
* <code>false</code> otherwise
* @see IClasspathEntry#getInclusionPatterns()
* @see IClasspathEntry#getExclusionPatterns()
* @since 2.0
*/
boolean isOnClasspath(IJavaElement element);
/**
* Returns whether the given resource is on the classpath of this project, that is, referenced
* from a classpath entry and not explicitly excluded using an exclusion pattern.
*
* @param resource the given resource
* @return <code>true</code> if the given resource is on the classpath of this project,
* <code>false</code> otherwise
* @see IClasspathEntry#getInclusionPatterns()
* @see IClasspathEntry#getExclusionPatterns()
* @since 2.1
*/
boolean isOnClasspath(IResource resource);
/**
* Creates a new evaluation context.
*
* @return a new evaluation context.
*/
IEvaluationContext newEvaluationContext();
/**
* Creates and returns a type hierarchy for all types in the given region, considering subtypes
* within that region.
*
* @param monitor the given progress monitor
* @param region the given region
* @exception JavaModelException if this element does not exist or if an exception occurs while
* accessing its corresponding resource
* @exception IllegalArgumentException if region is <code>null</code>
* @return a type hierarchy for all types in the given region, considering subtypes within that
* region
*/
ITypeHierarchy newTypeHierarchy(IRegion region, IProgressMonitor monitor)
throws JavaModelException;
/**
* Creates and returns a type hierarchy for all types in the given region, considering subtypes
* within that region and considering types in the working copies with the given owner. In other
* words, the owner's working copies will take precedence over their original compilation units
* in the workspace.
* <p>
* Note that if a working copy is empty, it will be as if the original compilation unit had been
* deleted.
* <p>
*
* @param monitor the given progress monitor
* @param region the given region
* @param owner the owner of working copies that take precedence over their original compilation
* units
* @exception JavaModelException if this element does not exist or if an exception occurs while
* accessing its corresponding resource
* @exception IllegalArgumentException if region is <code>null</code>
* @return a type hierarchy for all types in the given region, considering subtypes within that
* region
* @since 3.0
*/
ITypeHierarchy newTypeHierarchy(IRegion region, WorkingCopyOwner owner, IProgressMonitor monitor)
throws JavaModelException;
/**
* Creates and returns a type hierarchy for the given type considering subtypes in the specified
* region.
*
* @param type the given type
* @param region the given region
* @param monitor the given monitor
*
* @exception JavaModelException if this element does not exist or if an exception occurs while
* accessing its corresponding resource
*
* @exception IllegalArgumentException if type or region is <code>null</code>
* @return a type hierarchy for the given type considering subtypes in the specified region
*/
ITypeHierarchy newTypeHierarchy(
IType type,
IRegion region,
IProgressMonitor monitor)
throws JavaModelException;
/**
* Creates and returns a type hierarchy for the given type considering subtypes in the specified
* region and considering types in the working copies with the given owner. In other words, the
* owner's working copies will take precedence over their original compilation units in the
* workspace.
* <p>
* Note that if a working copy is empty, it will be as if the original compilation unit had been
* deleted.
* <p>
*
* @param type the given type
* @param region the given region
* @param monitor the given monitor
* @param owner the owner of working copies that take precedence over their original compilation
* units
*
* @exception JavaModelException if this element does not exist or if an exception occurs while
* accessing its corresponding resource
*
* @exception IllegalArgumentException if type or region is <code>null</code>
* @return a type hierarchy for the given type considering subtypes in the specified region
* @since 3.0
*/
ITypeHierarchy newTypeHierarchy(
IType type,
IRegion region,
WorkingCopyOwner owner,
IProgressMonitor monitor)
throws JavaModelException;
/**
* Returns the default output location for the project as defined by its <code>.classpath</code>
* file from disk, or <code>null</code> if unable to read the file.
* <p>
* This output location may differ from the in-memory one returned by
* <code>getOutputLocation</code>, in case the automatic reconciliation mechanism has not been
* performed yet. Usually, any change to the <code>.classpath</code> file is automatically
* noticed and reconciled at the next resource change notification event. However, if the file
* is modified within an operation, where this change needs to be taken into account before the
* operation ends, then the output location from disk can be read using this method, and further
* assigned to the project using <code>setRawClasspath(...)</code>.
* <p>
* The default output location is where class files are ordinarily generated (and resource
* files, copied). Each source classpath entry can also specify an output location for the
* generated class files (and copied resource files) corresponding to compilation units under
* that source folder. This makes it possible to arrange generated class files for different
* source folders in different output folders, and not necessarily the default output folder.
* This means that the generated class files for the project may end up scattered across several
* folders, rather than all in the default output folder (which is more standard).
* <p>
* In order to manually force a project classpath refresh, one can simply assign the project
* classpath using the result of this method, as follows:
* <code>proj.setRawClasspath(proj.readRawClasspath(), proj.readOutputLocation(), monitor)</code>
* (note that the <code>readRawClasspath/readOutputLocation</code> methods could return
* <code>null</code>).
* <p>
*
* @return the workspace-relative absolute path of the default output folder
* @see #getOutputLocation()
* @since 3.0
*/
IPath readOutputLocation();
/**
* Returns the raw classpath for the project as defined by its <code>.classpath</code> file from
* disk, or <code>null</code> if unable to read the file.
* <p>
* This classpath may differ from the in-memory classpath returned by
* <code>getRawClasspath</code>, in case the automatic reconciliation mechanism has not been
* performed yet. Usually, any change to the <code>.classpath</code> file is automatically
* noticed and reconciled at the next resource change notification event. However, if the file
* is modified within an operation, where this change needs to be taken into account before the
* operation ends, then the classpath from disk can be read using this method, and further
* assigned to the project using <code>setRawClasspath(...)</code>.
* </p>
* <p>
* Classpath variable and classpath container entries can be resolved using the helper method
* <code>getResolvedClasspath</code>; classpath variable entries also can be resolved
* individually using <code>JavaCore#getClasspathVariable</code>).
* </p>
* <p>
* Note that no check is performed whether the project has the Java nature set, allowing an
* existing <code>.classpath</code> file to be considered independantly (unlike
* <code>getRawClasspath</code> which requires the Java nature to be associated with the
* project).
* </p>
* <p>
* In order to manually force a project classpath refresh, one can simply assign the project
* classpath using the result of this method, as follows:
* <code>proj.setRawClasspath(proj.readRawClasspath(), proj.readOutputLocation(), monitor)</code>
* (note that the <code>readRawClasspath/readOutputLocation</code> methods could return
* <code>null</code>).
* </p>
*
* @return the raw classpath from disk for the project, as a list of classpath entries
* @see #getRawClasspath()
* @see IClasspathEntry
* @since 3.0
*/
IClasspathEntry[] readRawClasspath();
/**
* Helper method for setting one option value only.
* <p>
* Equivalent to:
*
* <pre>
* Map options = this.getOptions(false);
* map.put(optionName, optionValue);
* this.setOptions(map)
* </pre>
* <p>
* For a complete description of the configurable options, see
* <code>JavaCore#getDefaultOptions</code>.
* </p>
*
* @param optionName the name of an option
* @param optionValue the value of the option to set. If <code>null</code>, then the option is
* removed from project preferences.
* @throws NullPointerException if <code>optionName</code> is <code>null</code> (see
* {@link org.osgi.service.prefs.Preferences#put(String, String)}).
* @see JavaCore#getDefaultOptions()
* @since 3.0
*/
void setOption(String optionName, String optionValue);
/**
* Sets the project custom options. All and only the options explicitly included in the given
* table are remembered; all previous option settings are forgotten, including ones not
* explicitly mentioned.
* <p>
* For a complete description of the configurable options, see
* <code>JavaCore#getDefaultOptions</code>.
* </p>
*
* @param newOptions the new options (key type: <code>String</code>; value type:
* <code>String</code>), or <code>null</code> to flush all custom options (clients
* will automatically get the global JavaCore options).
* @see JavaCore#getDefaultOptions()
* @since 2.1
*/
void setOptions(Map newOptions);
/**
* Sets the default output location of this project to the location described by the given
* workspace-relative absolute path.
* <p>
* The default output location is where class files are ordinarily generated (and resource
* files, copied). Each source classpath entries can also specify an output location for the
* generated class files (and copied resource files) corresponding to compilation units under
* that source folder. This makes it possible to arrange that generated class files for
* different source folders to end up in different output folders, and not necessarily the
* default output folder. This means that the generated class files for the project may end up
* scattered across several folders, rather than all in the default output folder (which is more
* standard).
* </p>
*
* @param path the workspace-relative absolute path of the default output folder
* @param monitor the progress monitor
*
* @exception JavaModelException if the classpath could not be set. Reasons include:
* <ul>
* <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
* <li>The path refers to a location not contained in this project (
* <code>PATH_OUTSIDE_PROJECT</code>)
* <li>The path is not an absolute path (<code>RELATIVE_PATH</code>)
* <li>The path is nested inside a package fragment root of this project (
* <code>INVALID_PATH</code>)
* <li>The output location is being modified during resource change event
* notification (CORE_EXCEPTION)
* </ul>
* @see #getOutputLocation()
* @see IClasspathEntry#getOutputLocation()
*/
void setOutputLocation(IPath path, IProgressMonitor monitor)
throws JavaModelException;
/**
* Sets both the classpath of this project and its default output location at once. The
* classpath is defined using a list of classpath entries. In particular such a classpath may
* contain classpath variable entries. Classpath variable entries can be resolved individually (
* {@link JavaCore#getClasspathVariable(String)}), or the full classpath can be resolved at once
* using the helper method {@link #getResolvedClasspath(boolean)}.
* <p>
* A classpath variable provides an indirection level for better sharing a classpath. As an
* example, it allows a classpath to no longer refer directly to external JARs located in some
* user specific location. The classpath can simply refer to some variables defining the proper
* locations of these external JARs.
* </p>
* <p>
* If it is specified that this operation cannot modify resources, the .classpath file will not
* be written to disk and no error marker will be generated. To synchronize the .classpath with
* the in-memory classpath, one can use
* <code>setRawClasspath(readRawClasspath(), true, monitor)</code>.
* </p>
* <p>
* Setting the classpath to <code>null</code> specifies a default classpath (the project root).
* Setting the classpath to an empty array specifies an empty classpath.
* </p>
* <p>
* If a cycle is detected while setting this classpath (and if resources can be modified), an
* error marker will be added to the project closing the cycle. To avoid this problem, use
* {@link #hasClasspathCycle(IClasspathEntry[])} before setting the classpath.
* <p>
* This operation acquires a lock on the workspace's root.
*
* @param entries a list of classpath entries
* @param outputLocation the default output location
* @param canModifyResources whether resources should be written to disk if needed
* @param monitor the given progress monitor
* @exception JavaModelException if the classpath could not be set. Reasons include:
* <ul>
* <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li> <li> The
* classpath is being modified during resource change event notification
* (CORE_EXCEPTION) <li> The classpath failed the validation check as defined by
* {@link JavaConventions#validateClasspath(IJavaProject, IClasspathEntry[], IPath)}
* </ul>
* @see IClasspathEntry
* @since 3.2
*/
void setRawClasspath(IClasspathEntry[] entries, IPath outputLocation, boolean canModifyResources, IProgressMonitor monitor) throws JavaModelException;
/**
* Sets the classpath of this project using a list of classpath entries. In particular such a
* classpath may contain classpath variable entries. Classpath variable entries can be resolved
* individually ({@link JavaCore#getClasspathVariable(String)}), or the full classpath can be
* resolved at once using the helper method {@link #getResolvedClasspath(boolean)}.
* <p>
* A classpath variable provides an indirection level for better sharing a classpath. As an
* example, it allows a classpath to no longer refer directly to external JARs located in some
* user specific location. The classpath can simply refer to some variables defining the proper
* locations of these external JARs.
* </p>
* <p>
* If it is specified that this operation cannot modify resources, the .classpath file will not
* be written to disk and no error marker will be generated. To synchronize the .classpath with
* the in-memory classpath, one can use
* <code>setRawClasspath(readRawClasspath(), true, monitor)</code>.
* </p>
* <p>
* Setting the classpath to <code>null</code> specifies a default classpath (the project root).
* Setting the classpath to an empty array specifies an empty classpath.
* </p>
* <p>
* If a cycle is detected while setting this classpath (and if resources can be modified), an
* error marker will be added to the project closing the cycle. To avoid this problem, use
* {@link #hasClasspathCycle(IClasspathEntry[])} before setting the classpath.
* <p>
* This operation acquires a lock on the workspace's root.
*
* @param entries a list of classpath entries
* @param canModifyResources whether resources should be written to disk if needed
* @param monitor the given progress monitor
* @exception JavaModelException if the classpath could not be set. Reasons include:
* <ul>
* <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li> <li> The
* classpath is being modified during resource change event notification
* (CORE_EXCEPTION) <li> The classpath failed the validation check as defined by
* {@link JavaConventions#validateClasspath(IJavaProject, IClasspathEntry[], IPath)}
* </ul>
* @see IClasspathEntry
* @since 3.2
*/
void setRawClasspath(IClasspathEntry[] entries, boolean canModifyResources, IProgressMonitor monitor) throws JavaModelException;
/**
* Works similar to {@link #setRawClasspath(IClasspathEntry[], IPath, IProgressMonitor)} and
* additionally allows persisting the given array of referenced entries for this project. The
* referenced entries and their attributes are stored in the .classpath file of this project.
* For details on referenced entries, see
* {@link JavaCore#getReferencedClasspathEntries(IClasspathEntry, IJavaProject)} and
* {@link IClasspathEntry#getReferencingEntry()}.
* <p>
* Since the referenced entries are stored in the .classpath file, clients can store additional
* information that belong to these entries and retrieve them across sessions, though the
* referenced entries themselves may not be present in the raw classpath. By passing a
* <code>null</code> referencedEntries, clients can choose not to modify the already persisted
* referenced entries, which is fully equivalent to
* {@link #setRawClasspath(IClasspathEntry[], IPath, IProgressMonitor)}. If an empty array is
* passed as referencedEntries, the already persisted referenced entries, if any, will be
* cleared.
* </p>
* <p>
* If there are duplicates of a referenced entry or if any of the <code>referencedEntries</code>
* is already present in the raw classpath(<code>entries</code>) those referenced entries will
* be excluded and not be persisted.
* </p>
*
* @param entries a list of classpath entries
* @param referencedEntries the list of referenced classpath entries to be persisted
* @param outputLocation the default output location
* @param monitor the given progress monitor
* @exception JavaModelException if the classpath could not be set. Reasons include:
* <ul>
* <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
* <li>The classpath is being modified during resource change event notification
* (CORE_EXCEPTION)
* <li>The classpath failed the validation check as defined by
* {@link JavaConventions#validateClasspath(IJavaProject, IClasspathEntry[], IPath)}
* </ul>
* @see IClasspathEntry
* @see #getReferencedClasspathEntries()
* @since 3.6
*/
void setRawClasspath(IClasspathEntry[] entries, IClasspathEntry[] referencedEntries, IPath outputLocation,
IProgressMonitor monitor) throws JavaModelException;
/**
* Returns the list of referenced classpath entries stored in the .classpath file of
* <code>this</code> java project. Clients can store the referenced classpath entries using
* {@link #setRawClasspath(IClasspathEntry[], IClasspathEntry[], IPath, IProgressMonitor)} If
* the client has not stored any referenced entries for this project, an empty array is
* returned.
*
* @throws JavaModelException
* @return an array of referenced classpath entries stored for this java project or an empty
* array if none stored earlier.
* @since 3.6
*/
IClasspathEntry[] getReferencedClasspathEntries() throws JavaModelException;
/**
* Sets the classpath of this project using a list of classpath entries. In particular such a
* classpath may contain classpath variable entries. Classpath variable entries can be resolved
* individually ({@link JavaCore#getClasspathVariable(String)}), or the full classpath can be
* resolved at once using the helper method {@link #getResolvedClasspath(boolean)}.
* <p>
* A classpath variable provides an indirection level for better sharing a classpath. As an
* example, it allows a classpath to no longer refer directly to external JARs located in some
* user specific location. The classpath can simply refer to some variables defining the proper
* locations of these external JARs.
* <p>
* Setting the classpath to <code>null</code> specifies a default classpath (the project root).
* Setting the classpath to an empty array specifies an empty classpath.
* <p>
* If a cycle is detected while setting this classpath, an error marker will be added to the
* project closing the cycle. To avoid this problem, use
* {@link #hasClasspathCycle(IClasspathEntry[])} before setting the classpath.
* <p>
* This operation acquires a lock on the workspace's root.
*
* @param entries a list of classpath entries
* @param monitor the given progress monitor
* @exception JavaModelException if the classpath could not be set. Reasons include:
* <ul>
* <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li> <li> The
* classpath is being modified during resource change event notification
* (CORE_EXCEPTION) <li> The classpath failed the validation check as defined by
* {@link JavaConventions#validateClasspath(IJavaProject, IClasspathEntry[], IPath)}
* </ul>
* @see IClasspathEntry
*/
void setRawClasspath(IClasspathEntry[] entries, IProgressMonitor monitor)
throws JavaModelException;
/**
* Sets the both the classpath of this project and its default output location at once. The
* classpath is defined using a list of classpath entries. In particular, such a classpath may
* contain classpath variable entries. Classpath variable entries can be resolved individually
* (see ({@link JavaCore#getClasspathVariable(String)}), or the full classpath can be resolved
* at once using the helper method {@link #getResolvedClasspath(boolean)}.
* <p>
* A classpath variable provides an indirection level for better sharing a classpath. As an
* example, it allows a classpath to no longer refer directly to external JARs located in some
* user specific location. The classpath can simply refer to some variables defining the proper
* locations of these external JARs.
* </p>
* <p>
* Setting the classpath to <code>null</code> specifies a default classpath (the project root).
* Setting the classpath to an empty array specifies an empty classpath.
* </p>
* <p>
* If a cycle is detected while setting this classpath, an error marker will be added to the
* project closing the cycle. To avoid this problem, use
* {@link #hasClasspathCycle(IClasspathEntry[])} before setting the classpath.
* </p>
* <p>
* This operation acquires a lock on the workspace's root.
* </p>
*
* @param entries a list of classpath entries
* @param monitor the progress monitor
* @param outputLocation the default output location
* @exception JavaModelException if the classpath could not be set. Reasons include:
* <ul>
* <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
* <li>Two or more entries specify source roots with the same or overlapping
* paths (NAME_COLLISION)
* <li>A entry of kind <code>CPE_PROJECT</code> refers to this project
* (INVALID_PATH)
* <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
* <li>The output location path refers to a location not contained in this
* project (<code>PATH_OUTSIDE_PROJECT</code>)
* <li>The output location path is not an absolute path (
* <code>RELATIVE_PATH</code>)
* <li>The output location path is nested inside a package fragment root of this
* project (<code>INVALID_PATH</code>)
* <li>The classpath is being modified during resource change event notification
* (CORE_EXCEPTION)
* </ul>
* @see IClasspathEntry
* @since 2.0
*/
void setRawClasspath(IClasspathEntry[] entries, IPath outputLocation, IProgressMonitor monitor)
throws JavaModelException;
}