Package org.eclipse.cdt.core.settings.model

Interface ICProjectDescriptionManager

public interface ICProjectDescriptionManager

This interface represents the manager of CDT Project descriptions.

Restriction:

This interface is not intended to be implemented by clients.

Restriction:

This interface is not intended to be extended by clients.

Field Summary

Fields

Modifier and Type	Field	Description
static int	GET_CREATE_DESCRIPTION	Flag indicating that the user has called createProjectDescription.
static int	GET_EMPTY_PROJECT_DESCRIPTION	Flag indicating that a new empty ICProjectDescription should be created and returned (irrespective of whether one already exists)
static int	GET_IF_LOADDED	Return the project description only if it's already loaded
static int	GET_WRITABLE	Flag indicating writable project description is required
static int	PROJECT_CREATING	Flag indicating that the Project is in the process of being created (i.e.
static int	SET_FORCE	Flag indicating that the description should be serialized even if the ProjectDescription isn't marked as modified.
static int	SET_NO_SERIALIZE	Flag indicating that the project description shouldn't be serialized.

Method Summary

Modifier and Type	Method	Description
void	addCProjectDescriptionListener(ICProjectDescriptionListener listener, int eventTypes)	Register a listener for changes on the set of known ICProjectDescriptions for the specified set of events
ICProjectDescription	createProjectDescription(org.eclipse.core.resources.IProject project, boolean loadIfExists)	This method is a full equivalent to: - createProjectDescription(IProject, boolean, false) - getProjectDescription(IProject, GET_WRITABLE | loadIfExists ? 0 : GET_EMPTY_PROJECT_DESCRIPTION) and returns a writable project description which is either empty or a copy of the previous configuration description if loadIfExists == true.
ICProjectDescription	createProjectDescription(org.eclipse.core.resources.IProject project, boolean loadIfExists, boolean creating)	the method creates and returns a writable project description
ICConfigurationDescription	getPreferenceConfiguration(java.lang.String buildSystemId)
ICConfigurationDescription	getPreferenceConfiguration(java.lang.String buildSystemId, boolean write)
ICProjectDescription	getProjectDescription(org.eclipse.core.resources.IProject project)	returns the project description associated with this project or null if the project does not contain the CDT data associated with it.
ICProjectDescription	getProjectDescription(org.eclipse.core.resources.IProject project, boolean write)	returns the project description associated with this project or null if the project does not contain the CDT data associated with it.
ICProjectDescription	getProjectDescription(org.eclipse.core.resources.IProject project, int flags)
ICProjectDescriptionWorkspacePreferences	getProjectDescriptionWorkspacePreferences(boolean write)	Returns the workspace project description preferences.
boolean	isNewStyleProject(ICProjectDescription des)
boolean	isNewStyleProject(org.eclipse.core.resources.IProject project)
void	removeCProjectDescriptionListener(ICProjectDescriptionListener listener)	Remove the listener from the set of ICProjecctDescriptionListeners
void	setPreferenceConfiguration(java.lang.String buildSystemId, ICConfigurationDescription des)
void	setProjectDescription(org.eclipse.core.resources.IProject project, ICProjectDescription des)	This method is called to save/apply the project description the method should be called to apply changes made to the project description returned by the getProjectDescription(IProject, boolean) or createProjectDescription(IProject, boolean) Note that having persisted changes to the description, the passed in ICProjectDescription is read-only and shouldn't be used.
void	setProjectDescription(org.eclipse.core.resources.IProject project, ICProjectDescription des, boolean force, org.eclipse.core.runtime.IProgressMonitor monitor)	This method is called to
void	setProjectDescription(org.eclipse.core.resources.IProject project, ICProjectDescription des, int flags, org.eclipse.core.runtime.IProgressMonitor monitor)
boolean	setProjectDescriptionWorkspacePreferences(ICProjectDescriptionWorkspacePreferences prefs, boolean updateProjects, org.eclipse.core.runtime.IProgressMonitor monitor)	used to apply the project description workspace preferences
void	updateExternalSettingsProviders(java.lang.String[] ids, org.eclipse.core.runtime.IProgressMonitor monitor)	forces the external settings providers of the specified IDs to be rescanned and all configurations referencing the specified providers to be updated
void	updateProjectDescriptions(org.eclipse.core.resources.IProject[] projects, org.eclipse.core.runtime.IProgressMonitor monitor)	forces the cached data of the specified projects to be re-loaded.

Field Detail

SET_FORCE

static final int SET_FORCE

Flag indicating that the description should be serialized even if the ProjectDescription isn't marked as modified.

See Also:

setProjectDescription(IProject, ICProjectDescription, int, IProgressMonitor), Constant Field Values

SET_NO_SERIALIZE

static final int SET_NO_SERIALIZE

Flag indicating that the project description shouldn't be serialized.

See Also:

setProjectDescription(IProject, ICProjectDescription, int, IProgressMonitor), Constant Field Values

GET_WRITABLE

static final int GET_WRITABLE

Flag indicating writable project description is required

See Also:

getProjectDescription(IProject, int), Constant Field Values

GET_IF_LOADDED

static final int GET_IF_LOADDED

Return the project description only if it's already loaded

See Also:

Constant Field Values

GET_EMPTY_PROJECT_DESCRIPTION

static final int GET_EMPTY_PROJECT_DESCRIPTION

Flag indicating that a new empty ICProjectDescription should be created and returned (irrespective of whether one already exists)

Since:

5.1

See Also:

Constant Field Values

GET_CREATE_DESCRIPTION

static final int GET_CREATE_DESCRIPTION

Flag indicating that the user has called createProjectDescription. i.e. a description should be returned irrespective of whether one already exists. If the project already has a description and !GET_EMPTY_PROJECT_DESCRIPTION the existing description will be returned, otherwise a new description is returned

Since:

5.1

See Also:

Constant Field Values

PROJECT_CREATING

static final int PROJECT_CREATING

Flag indicating that the Project is in the process of being created (i.e. the user is working through the new project dialog...) This flag doesn't affect whether a description should or shouldn't be created.

Since:

5.1

See Also:

GET_CREATE_DESCRIPTION, ICProjectDescription.isCdtProjectCreating(), Constant Field Values

Method Detail

createProjectDescription

ICProjectDescription createProjectDescription(org.eclipse.core.resources.IProject project,
                                              boolean loadIfExists)
                                       throws org.eclipse.core.runtime.CoreException

This method is a full equivalent to:
- createProjectDescription(IProject, boolean, false)
- getProjectDescription(IProject, GET_WRITABLE | loadIfExists ? 0 : GET_EMPTY_PROJECT_DESCRIPTION)
and returns a writable project description which is either empty or a copy of the previous configuration description if loadIfExists == true.

Throws:

org.eclipse.core.runtime.CoreException - if the Project doesn't exist, or the storage couldn't be found

See Also:

createProjectDescription(IProject, boolean, boolean)

createProjectDescription

ICProjectDescription createProjectDescription(org.eclipse.core.resources.IProject project,
                                              boolean loadIfExists,
                                              boolean creating)
                                       throws org.eclipse.core.runtime.CoreException

the method creates and returns a writable project description

Parameters:

project - project for which the project description is requested

loadIfExists - if true the method first tries to load and return the project description from the settings file (.cproject) if false, the stored settings are ignored and the new (empty) project description is created

creating - if true the created project description will be contain the true "isCdtProjectCreating" state. NOTE: in case the project already contains the project description AND its "isCdtProjectCreating" is false the resulting description will be created with the false "isCdtProjectCreating" state NOTE: changes made to the returned project description will not be applied until the setProjectDescription(IProject, ICProjectDescription) is called

Returns:

ICProjectDescription

Throws:

org.eclipse.core.runtime.CoreException - if the Project doesn't exist, or the storage couldn't be found

setProjectDescription

void setProjectDescription(org.eclipse.core.resources.IProject project,
                           ICProjectDescription des)
                    throws org.eclipse.core.runtime.CoreException

This method is called to save/apply the project description the method should be called to apply changes made to the project description returned by the getProjectDescription(IProject, boolean) or createProjectDescription(IProject, boolean) Note that having persisted changes to the description, the passed in ICProjectDescription is read-only and shouldn't be used. If the user wishes to continue editing the ICProjectDescription they must ensure they getProjectDescription again.

Parameters:

project -

des -

Throws:

org.eclipse.core.runtime.CoreException

See Also:

createProjectDescription(IProject, boolean)

setProjectDescription

void setProjectDescription(org.eclipse.core.resources.IProject project,
                           ICProjectDescription des,
                           boolean force,
                           org.eclipse.core.runtime.IProgressMonitor monitor)
                    throws org.eclipse.core.runtime.CoreException

This method is called to

Parameters:

project -

des -

force -

monitor -

Throws:

org.eclipse.core.runtime.CoreException

setProjectDescription

void setProjectDescription(org.eclipse.core.resources.IProject project,
                           ICProjectDescription des,
                           int flags,
                           org.eclipse.core.runtime.IProgressMonitor monitor)
                    throws org.eclipse.core.runtime.CoreException

Parameters:

project -

des -

flags -

monitor -

Throws:

org.eclipse.core.runtime.CoreException

getProjectDescription

ICProjectDescription getProjectDescription(org.eclipse.core.resources.IProject project)

returns the project description associated with this project or null if the project does not contain the CDT data associated with it. this is a convenience method fully equivalent to getProjectDescription(project, true) see getProjectDescription(IProject, boolean) for more detail

Parameters:

project -

Returns:

a writable copy of the ICProjectDescription or null if the project does not contain the CDT data associated with it. Note: changes to the project description will not be reflected/used by the core until the setProjectDescription(IProject, ICProjectDescription) is called

See Also:

getProjectDescription(IProject, boolean)

getProjectDescription

ICProjectDescription getProjectDescription(org.eclipse.core.resources.IProject project,
                                           boolean write)

returns the project description associated with this project or null if the project does not contain the CDT data associated with it.

Parameters:

project - project for which the description is requested

write - if true, the writable description copy is returned. If false the cached read-only description is returned. CDT core maintains the cached project description settings. If only read access is needed to description, then the read-only project description should be obtained. This description always operates with cached data and thus it is better to use it for performance reasons All set* calls to the read-only description result in the WriteAccessException When the writable description is requested, the description copy is created. Changes to this description will not be reflected/used by the core and Build System until the setProjectDescription(IProject, ICProjectDescription) is called Each getProjectDescription(project, true) returns a new copy of the project description The writable description uses the cached data until the first set call after that the description communicates directly to the Build System i.e. the implementer of the org.eclipse.cdt.core.CConfigurationDataProvider extension This ensures the Core<->Build System settings integrity

Returns:

ICProjectDescription or null if the project does not contain the CDT data associated with it.

getProjectDescription

ICProjectDescription getProjectDescription(org.eclipse.core.resources.IProject project,
                                           int flags)

Parameters:

project -

flags - some combination of GET_WRITABLE, GET_IF_LOADDED, GET_EMPTY_PROJECT_DESCRIPTION, GET_CREATE_DESCRIPTION, and PROJECT_CREATING

Returns:

ICProjectDescription or null if the project does not contain the CDT data associated with it.

See Also:

createProjectDescription(IProject, boolean)

updateProjectDescriptions

void updateProjectDescriptions(org.eclipse.core.resources.IProject[] projects,
                               org.eclipse.core.runtime.IProgressMonitor monitor)
                        throws org.eclipse.core.runtime.CoreException

forces the cached data of the specified projects to be re-loaded. if the projects argument is null all projects within the workspace are updated

Parameters:

projects -

monitor -

Throws:

org.eclipse.core.runtime.CoreException

isNewStyleProject

boolean isNewStyleProject(org.eclipse.core.resources.IProject project)

Parameters:

project -

Returns:

whether the given project is a new-style project, i.e. CConfigurationDataProvider-driven

isNewStyleProject

boolean isNewStyleProject(ICProjectDescription des)

Parameters:

des -

Returns:

whether the given project is a new-style project, i.e. CConfigurationDataProvider-driven

addCProjectDescriptionListener

void addCProjectDescriptionListener(ICProjectDescriptionListener listener,
                                    int eventTypes)

Register a listener for changes on the set of known ICProjectDescriptions for the specified set of events

Parameters:

listener -

eventTypes - see the eventTypes in CProjectDescriptionEvent

See Also:

CProjectDescriptionEvent.ABOUT_TO_APPLY, CProjectDescriptionEvent.APPLIED, CProjectDescriptionEvent.COPY_CREATED, CProjectDescriptionEvent.DATA_APPLIED, CProjectDescriptionEvent.LOADED, CProjectDescriptionEvent.ALL

removeCProjectDescriptionListener

void removeCProjectDescriptionListener(ICProjectDescriptionListener listener)

Remove the listener from the set of ICProjecctDescriptionListeners

Parameters:

listener -

getProjectDescriptionWorkspacePreferences

ICProjectDescriptionWorkspacePreferences getProjectDescriptionWorkspacePreferences(boolean write)

Returns the workspace project description preferences. if the write argument is false, the returned preferences are read-only otherwise the preferences are writable. NOTE: the changes made to the preferences will NOT get applied until the preferences are set via the setProjectDescriptionWorkspacePreferences(ICProjectDescriptionWorkspacePreferences, boolean, IProgressMonitor) method

Parameters:

write - if true, the writable preferences copy is returned.

Returns:

the workspace project description preferences

See Also:

setProjectDescriptionWorkspacePreferences(ICProjectDescriptionWorkspacePreferences, boolean, IProgressMonitor)

setProjectDescriptionWorkspacePreferences

boolean setProjectDescriptionWorkspacePreferences(ICProjectDescriptionWorkspacePreferences prefs,
                                                  boolean updateProjects,
                                                  org.eclipse.core.runtime.IProgressMonitor monitor)

used to apply the project description workspace preferences

Parameters:

prefs - - preferences to be applied

updateProjects - - if true all project descriptions within the workspace will be updated to reflect/use the settings specified with the given preferences

monitor -

Returns:

true if new prefs differ from the old ones, i.e. preferences changed

updateExternalSettingsProviders

void updateExternalSettingsProviders(java.lang.String[] ids,
                                     org.eclipse.core.runtime.IProgressMonitor monitor)

forces the external settings providers of the specified IDs to be rescanned and all configurations referencing the specified providers to be updated

Parameters:

ids - the ids of externalSettinsProvider extensions

See Also:

ICConfigurationDescription.getExternalSettingsProviderIds(), ICConfigurationDescription.setExternalSettingsProviderIds(String[]), ICConfigurationDescription.updateExternalSettingsProviders(String[])

getPreferenceConfiguration

ICConfigurationDescription getPreferenceConfiguration(java.lang.String buildSystemId)
                                               throws org.eclipse.core.runtime.CoreException

Throws:

org.eclipse.core.runtime.CoreException

getPreferenceConfiguration

ICConfigurationDescription getPreferenceConfiguration(java.lang.String buildSystemId,
                                                      boolean write)
                                               throws org.eclipse.core.runtime.CoreException

Throws:

org.eclipse.core.runtime.CoreException

setPreferenceConfiguration

void setPreferenceConfiguration(java.lang.String buildSystemId,
                                ICConfigurationDescription des)
                         throws org.eclipse.core.runtime.CoreException

Throws:

org.eclipse.core.runtime.CoreException