org.eclipse.core.resources
Interface IProject

All Superinterfaces:

IAdaptable, IContainer, IResource

public interface IProject

extends IContainer, IAdaptable

A project is a type of resource which groups resources into buildable, reusable units.

Features of projects include:

• A project collects together a set of files and folders.
• A project's location controls where the project's resources are stored in the local file system.
• A project's build spec controls how building is done on the project.
• A project can carry session and persistent properties.
• A project can be open or closed; a closed project is passive and has a minimal in-memory footprint.
• A project can carry references to other projects.
• A project can have one or more project natures.

This interface is not intended to be implemented by clients.

Projects implement the IAdaptable interface; extensions are managed by the platform's adapter manager.

See Also:

Platform.getAdapterManager()

Field Summary

Fields inherited from interface org.eclipse.core.resources.IContainer

INCLUDE_PHANTOMS, INCLUDE_TEAM_PRIVATE_MEMBERS

Fields inherited from interface org.eclipse.core.resources.IResource

ALWAYS_DELETE_PROJECT_CONTENT, DEPTH_INFINITE, DEPTH_ONE, DEPTH_ZERO, FILE, FOLDER, FORCE, KEEP_HISTORY, NEVER_DELETE_PROJECT_CONTENT, NONE, NULL_STAMP, PROJECT, ROOT

Method Summary

void	build(int kind, IProgressMonitor monitor) Builds this project.
void	build(int kind, String builderName, Map args, IProgressMonitor monitor) Invokes the build method of the specified builder for this project.
void	close(IProgressMonitor monitor) Closes this project.
void	create(IProgressMonitor monitor) Creates a new project resource in the workspace with files are the default location in the local file system.
void	create(IProjectDescription description, IProgressMonitor monitor) Creates a new project resource in the workspace using the given project description.
void	delete(boolean deleteContent, boolean force, IProgressMonitor monitor) Deletes this project from the workspace.
IProjectDescription	getDescription() Returns the description for this project.
IFile	getFile(String name) Returns a handle to the file with the given name in this project.
IFolder	getFolder(String name) Returns a handle to the folder with the given name in this project.
IProjectNature	getNature(String natureId) Returns the specified project nature for this project or null if the project nature has not been added to this project.
IPath	getPluginWorkingLocation(IPluginDescriptor plugin) Returns the location in the local file system of the project-specific working data area for use by the given plug-in or null if the project does not exist.
IProject[]	getReferencedProjects() Returns the projects referenced by this project.
IProject[]	getReferencingProjects() Returns the list of all open projects which reference this project.
boolean	hasNature(String natureId) Returns whether the project nature specified by the given nature extension id has been added to this project.
boolean	isNatureEnabled(String natureId) Returns true if the project nature specified by the given nature extension id is enabled for this project, and false otherwise.
boolean	isOpen() Returns whether this project is open.
void	move(IProjectDescription description, boolean force, IProgressMonitor monitor) Renames this project so that it is located at the name in the given description.
void	open(IProgressMonitor monitor) Opens this project.
void	setDescription(IProjectDescription description, int updateFlags, IProgressMonitor monitor) Changes this project resource to match the given project description.
void	setDescription(IProjectDescription description, IProgressMonitor monitor) Changes this project resource to match the given project description.

Methods inherited from interface org.eclipse.core.resources.IContainer

exists, findDeletedMembersWithHistory, findMember, findMember, findMember, findMember, getFile, getFolder, members, members, members

Methods inherited from interface org.eclipse.core.resources.IResource

accept, accept, accept, clearHistory, copy, copy, copy, copy, createMarker, delete, delete, deleteMarkers, equals, exists, findMarker, findMarkers, getFileExtension, getFullPath, getLocation, getMarker, getModificationStamp, getName, getParent, getPersistentProperty, getProject, getProjectRelativePath, getSessionProperty, getType, getWorkspace, isAccessible, isDerived, isLocal, isPhantom, isReadOnly, isSynchronized, isTeamPrivateMember, move, move, move, move, refreshLocal, setDerived, setLocal, setPersistentProperty, setReadOnly, setSessionProperty, setTeamPrivateMember, touch

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Method Detail

build

public void build(int kind,
                  String builderName,
                  Map args,
                  IProgressMonitor monitor)
           throws CoreException

Invokes the build method of the specified builder for this project. Does nothing if this project is closed.

The builder name is declared in the extension that plugs in to the standard org.eclipse.core.resources.builders extension point. The arguments are builder specific.

This method may change resources; these changes will be reported in a subsequent resource change event.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

kind - the kind of build being requested. Valid values are:

• IncrementalProjectBuilder.FULL_BUILD - indicates a full build.
• IncrementalProjectBuilder.INCREMENTAL_BUILD - indicates an incremental build.

builderName - the name of the builder

args - a table of builder-specific arguments keyed by argument name (key type: String, value type: String); null is equivalent to an empty map

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if the build fails. The status contained in the exception may be a generic BUILD_FAILED code, but it could also be any other status code; it might also be a multi-status.

See Also:

IProjectDescription, IncrementalProjectBuilder.build(int, java.util.Map, org.eclipse.core.runtime.IProgressMonitor), IncrementalProjectBuilder.FULL_BUILD, IncrementalProjectBuilder.INCREMENTAL_BUILD

build

public void build(int kind,
                  IProgressMonitor monitor)
           throws CoreException

Builds this project. Does nothing if the project is closed.

Building a project involves executing the commands found in this project's build spec.

This method may change resources; these changes will be reported in a subsequent resource change event.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

kind - the kind of build being requested. Valid values are:

• IncrementalProjectBuilder.FULL_BUILD - indicates a full build.
• IncrementalProjectBuilder.INCREMENTAL_BUILD - indicates an incremental build.

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if the build fails. The status contained in the exception may be a generic BUILD_FAILED code, but it could also be any other status code; it might also be a multi-status.

See Also:

IProjectDescription, IncrementalProjectBuilder.FULL_BUILD, IncrementalProjectBuilder.INCREMENTAL_BUILD

close

public void close(IProgressMonitor monitor)
           throws CoreException

Closes this project. The project need not be open. Closing a closed project does nothing.

Closing a project involves ensuring that all important project-related state is safely stored on disk, and then discarding the in-memory representation of its resources and other volatile state, including session properties. After this method, the project continues to exist in the workspace but its member resources (and their members, etc.) do not. A closed project can later be re-opened.

This method changes resources; these changes will be reported in a subsequent resource change event that includes an indication that this project has been closed and its members have been removed.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if this method fails. Reasons include:

• This resource does not exist.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

open(org.eclipse.core.runtime.IProgressMonitor), isOpen()

create

public void create(IProjectDescription description,
                   IProgressMonitor monitor)
            throws CoreException

Creates a new project resource in the workspace using the given project description. Upon successful completion, the project will exist but be closed.

Newly created projects have no session or persistent properties.

If the project content area given in the project description does not contain a project description file, a project description file is written in the project content area with the natures, build spec, comment, and referenced projects as specified in the given project description. If there is an existing project description file, it is not overwritten.

This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that the project has been added to the workspace.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

description - the project description

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if this method fails. Reasons include:

• This project already exists in the workspace.
• The name of this resource is not valid (according to IWorkspace.validateName).
• The project location is not valid (according to IWorkspace.validateProjectLocation).
• The project description file could not be created in the project content area.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

IWorkspace.validateProjectLocation(org.eclipse.core.resources.IProject, org.eclipse.core.runtime.IPath)

create

public void create(IProgressMonitor monitor)
            throws CoreException

Creates a new project resource in the workspace with files are the default location in the local file system. Upon successful completion, the project will exist but be closed.

Newly created projects have no session or persistent properties.

If the project content area does not contain a project description file, an initial project description file is written in the project content area with the following information:

• no references to other projects
• no natures
• an empty build spec
• an empty comment

If there is an existing project description file, it is not overwritten.

This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this project has been added to the workspace.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if this method fails. Reasons include:

• This project already exists in the workspace.
• The name of this resource is not valid (according to IWorkspace.validateName).
• The project location is not valid (according to IWorkspace.validateProjectLocation).
• The project description file could not be created in the project content area.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

IWorkspace.validateProjectLocation(org.eclipse.core.resources.IProject, org.eclipse.core.runtime.IPath)

delete

public void delete(boolean deleteContent,
                   boolean force,
                   IProgressMonitor monitor)
            throws CoreException

Deletes this project from the workspace. No action is taken if this project does not exist.

This is a convenience method, fully equivalent to:

   delete(
     (deleteContent ? IResource.ALWAYS_DELETE_PROJECT_CONTENT : IResource.NEVER_DELETE_PROJECT_CONTENT )
        | (force ? FORCE : IResource.NONE),
     monitor);
 

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

deleteContent - a flag controlling how whether content is aggressively deleted

force - a flag controlling whether resources that are not in sync with the local file system will be tolerated

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if this method fails. Reasons include:

• This project could not be deleted.
• This project's contents could not be deleted.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

IResource.delete(boolean, org.eclipse.core.runtime.IProgressMonitor), open(org.eclipse.core.runtime.IProgressMonitor), close(org.eclipse.core.runtime.IProgressMonitor), IResource.delete(int,IProgressMonitor)

getDescription

public IProjectDescription getDescription()
                                   throws CoreException

Returns the description for this project. The returned value is a copy and cannot be used to modify this project. The returned value is suitable for use in creating, copying and moving other projects.

Returns:

the description for this project

Throws:

CoreException - if this method fails. Reasons include:

• This project does not exist.
• This project is not open.

See Also:

create(org.eclipse.core.resources.IProjectDescription, org.eclipse.core.runtime.IProgressMonitor), IResource.copy(org.eclipse.core.resources.IProjectDescription, boolean, org.eclipse.core.runtime.IProgressMonitor), move(org.eclipse.core.resources.IProjectDescription, boolean, org.eclipse.core.runtime.IProgressMonitor)

getFile

public IFile getFile(String name)

Returns a handle to the file with the given name in this project.

This is a resource handle operation; neither the resource nor the result need exist in the workspace. The validation check on the resource name/path is not done when the resource handle is constructed; rather, it is done automatically as the resource is created.

Parameters:

name - the string name of the member file

Returns:

the (handle of the) member file

See Also:

getFolder(java.lang.String)

getFolder

public IFolder getFolder(String name)

Returns a handle to the folder with the given name in this project.

This is a resource handle operation; neither the container nor the result need exist in the workspace. The validation check on the resource name/path is not done when the resource handle is constructed; rather, it is done automatically as the resource is created.

Parameters:

name - the string name of the member folder

Returns:

the (handle of the) member folder

See Also:

getFile(java.lang.String)

getNature

public IProjectNature getNature(String natureId)
                         throws CoreException

Returns the specified project nature for this project or null if the project nature has not been added to this project. Clients may downcast to a more concrete type for more nature-specific methods. The documentation for a project nature specifies any such additional protocol.

This may cause the plug-in that provides the given nature to be activated.

Parameters:

natureId - the nature extension identifier

Returns:

the project nature object

Throws:

CoreException - if this method fails. Reasons include:

• This project does not exist.
• This project is not open.
• The project nature extension could not be found.

getPluginWorkingLocation

public IPath getPluginWorkingLocation(IPluginDescriptor plugin)

Returns the location in the local file system of the project-specific working data area for use by the given plug-in or null if the project does not exist. The content, structure, and management of this area is the responsibility of the plug-in. This area is deleted when the project is deleted. This project needs to exist but does not need to be open.

Parameters:

plugin - the plug-in

Returns:

a local file system path

getReferencedProjects

public IProject[] getReferencedProjects()
                                 throws CoreException

Returns the projects referenced by this project. The returned projects need not exist in the workspace. The result will not contain duplicates. Returns an empty array if there are no referenced projects.

Returns:

a list of projects

Throws:

CoreException - if this method fails. Reasons include:

• This project does not exist.
• This project is not open.

getReferencingProjects

public IProject[] getReferencingProjects()

Returns the list of all open projects which reference this project. This project may or may not exist. Returns an empty array if there are no referencing projects.

Returns:

a list of open projects referencing this project

hasNature

public boolean hasNature(String natureId)
                  throws CoreException

Returns whether the project nature specified by the given nature extension id has been added to this project.

Parameters:

natureId - the nature extension identifier

Returns:

true if the project has the given nature

Throws:

CoreException - if this method fails. Reasons include:

• This project does not exist.
• This project is not open.

isNatureEnabled

public boolean isNatureEnabled(String natureId)
                        throws CoreException

Returns true if the project nature specified by the given nature extension id is enabled for this project, and false otherwise.

Reasons for a nature not to be enabled include:
• The nature is not available in the install.
• The nature has not been added to this project.
• The nature has a prerequisite that is not enabled for this project.
• The nature specifies "one-of-nature" membership in a set, and there is another nature on this project belonging to that set.
• The prerequisites for the nature form a cycle.

Parameters:

natureId - the nature extension identifier

Returns:

true if the given nature is enabled for this project

Throws:

CoreException - if this method fails. Reasons include:

• This project does not exist.
• This project is not open.

Since:

2.0

See Also:

IWorkspace.validateNatureSet(java.lang.String[])

isOpen

public boolean isOpen()

Returns whether this project is open.

A project must be opened before it can be manipulated. A closed project is passive and has a minimal memory footprint; a closed project has no members.

Returns:

true if this project is open, false if this project is closed or does not exist

See Also:

open(org.eclipse.core.runtime.IProgressMonitor), close(org.eclipse.core.runtime.IProgressMonitor)

move

public void move(IProjectDescription description,
                 boolean force,
                 IProgressMonitor monitor)
          throws CoreException

Renames this project so that it is located at the name in the given description.

This is a convenience method, fully equivalent to:

   move(description, (force ? FORCE : IResource.NONE), monitor);
 

This method changes resources; these changes will be reported in a subsequent resource change event that will include an indication that the resource has been removed from its parent and that a corresponding resource has been added to its new parent. Additional information provided with resource delta shows that these additions and removals are related.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

description - the description for the destination project

force - a flag controlling whether resources that are not in sync with the local file system will be tolerated

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if this resource could not be moved. Reasons include:

• This resource is not accessible.
• This resource or one of its descendents is not local.
• This resource or one of its descendents is out of sync with the local file system and force is false.
• The workspace and the local file system are out of sync at the destination resource or one of its descendents.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

IResourceDelta.getFlags(), IResource.move(IProjectDescription,int,IProgressMonitor)

open

public void open(IProgressMonitor monitor)
          throws CoreException

Opens this project. No action is taken if the project is already open.

Opening a project constructs an in-memory representation of its resources from information stored on disk.

This method changes resources; these changes will be reported in a subsequent resource change event that includes an indication that the project has been opened and its resources have been added to the tree.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if this method fails. Reasons include:

• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

close(org.eclipse.core.runtime.IProgressMonitor)

setDescription

public void setDescription(IProjectDescription description,
                           IProgressMonitor monitor)
                    throws CoreException

Changes this project resource to match the given project description. This project should exist and be open.

This is a convenience method, fully equivalent to:

   setDescription(description, KEEP_HISTORY, monitor);
 

This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that the project's content has changed.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

description - the project description

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if this method fails. Reasons include:

• This project does not exist in the workspace.
• This project is not open.
• The location in the local file system corresponding to the project description file is occupied by a directory.
• The workspace is out of sync with the project description file in the local file system .
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.
• The file modification validator disallowed the change.

See Also:

getDescription(), IProjectNature.configure(), IProjectNature.deconfigure(), setDescription(IProjectDescription,int,IProgressMonitor)

setDescription

public void setDescription(IProjectDescription description,
                           int updateFlags,
                           IProgressMonitor monitor)
                    throws CoreException

Changes this project resource to match the given project description. This project should exist and be open.

The given project description is used to change the project's natures, build spec, comment, and referenced projects. The name and location of a project cannot be changed; these settings in the project description are ignored. The project's session and persistent properties are not affected.

If the new description includes nature ids of natures that the project did not have before, these natures will be configured in automatically, which involves instantiating the project nature and calling IProjectNature.configure on it. An internal reference to the nature object is retained, and will be returned on subsequent calls to getNature for the specified nature id. Similarly, any natures the project had which are no longer required will be automatically deconfigured by calling IProjectNature.deconfigure on the nature object and letting go of the internal reference to it.

The FORCE update flag controls how this method deals with cases where the workspace is not completely in sync with the local file system. If FORCE is not specified, the method will only attempt to overwrite the project's description file in the local file system provided it is in sync with the workspace. This option ensures there is no unintended data loss; it is the recommended setting. However, if FORCE is specified, an attempt will be made to write the project description file in the local file system, overwriting any existing one if need be.

The KEEP_HISTORY update flag controls whether or not a copy of current contents of the project description file should be captured in the workspace's local history. The local history mechanism serves as a safety net to help the user recover from mistakes that might otherwise result in data loss. Specifying KEEP_HISTORY is recommended. Note that local history is maintained with each individual project, and gets discarded when a project is deleted from the workspace.

Update flags other than FORCE and KEEP_HISTORY are ignored.

Prior to modifying the the project description file, the file modification validator (if provided by the Team plug-in), will be given a chance to perform any last minute preparations. Validation is performed by calling IFileModificationValidator.validateSave on the project description file. If the validation fails, then this operation will fail.

This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that the project's content has changed.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

description - the project description

updateFlags - bit-wise or of update flag constants (FORCE and KEEP_HISTORY)

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if this method fails. Reasons include:

• This project does not exist in the workspace.
• This project is not open.
• The location in the local file system corresponding to the project description file is occupied by a directory.
• The workspace is not in sync with the project description file in the local file system and FORCE is not specified.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.
• The file modification validator disallowed the change.

Since:

2.0

See Also:

getDescription(), IProjectNature.configure(), IProjectNature.deconfigure(), IResource.FORCE, IResource.KEEP_HISTORY