diff --git a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/CProjectDescriptionEvent.java b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/CProjectDescriptionEvent.java index 1744c26e494..92cd751417f 100644 --- a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/CProjectDescriptionEvent.java +++ b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/CProjectDescriptionEvent.java @@ -10,27 +10,29 @@ *******************************************************************************/ package org.eclipse.cdt.core.settings.model; +import org.eclipse.cdt.internal.core.settings.model.CConfigurationDescription; +import org.eclipse.cdt.internal.core.settings.model.CConfigurationDescriptionCache; import org.eclipse.cdt.internal.core.settings.model.CProjectDescriptionDelta; import org.eclipse.cdt.internal.core.settings.model.CProjectDescriptionManager; import org.eclipse.core.resources.IProject; /** - * Events fired for the project delats. - * The ProjectDescription lifecycle looks like: + * Events fired for the project deltas. + * The ProjectDescription life-cycle looks like: * + * + * @see ICConfigurationDescription + * @see CConfigurationDescription + * @see CConfigurationDescriptionCache */ public final class CProjectDescriptionEvent { @@ -44,8 +46,8 @@ public final class CProjectDescriptionEvent { public static final int DATA_APPLIED = 1 << 4; /** Event kind encapsulated ALL events */ public static final int ALL = LOADED | ABOUT_TO_APPLY | APPLIED | COPY_CREATED | DATA_APPLIED; - - /** The type of event this corresponds to */ + + /** The type of event this corresponds to */ private final int fType; /** A *writable* new description */ private final ICProjectDescription fNewDescription; @@ -56,7 +58,7 @@ public final class CProjectDescriptionEvent { private ICDescriptionDelta fActiveCfgDelta; private ICDescriptionDelta fIndexCfgDelta; private final IProject fProject; - + public CProjectDescriptionEvent(int type, ICDescriptionDelta delta, ICProjectDescription newDes, @@ -75,7 +77,7 @@ public final class CProjectDescriptionEvent { fProject = null; } } - + public IProject getProject() { return fProject; } @@ -83,11 +85,11 @@ public final class CProjectDescriptionEvent { public int getEventType() { return fType; } - + public ICDescriptionDelta getProjectDelta() { return fProjDelta; } - + public ICDescriptionDelta getActiveCfgDelta() { if (fActiveCfgDelta == null) { fActiveCfgDelta = getDelta(true); @@ -101,7 +103,7 @@ public final class CProjectDescriptionEvent { } return fIndexCfgDelta; } - + private ICDescriptionDelta getDelta(boolean active) { ICDescriptionDelta delta = null; switch(getEventType()) { @@ -139,17 +141,17 @@ public final class CProjectDescriptionEvent { } } break; - + case COPY_CREATED: break; } return delta; } - + private ICConfigurationDescription getCfg(ICProjectDescription des, boolean active) { - return active ? des.getActiveConfiguration() : des.getDefaultSettingConfiguration(); + return active ? des.getActiveConfiguration() : des.getDefaultSettingConfiguration(); } - + private ICDescriptionDelta findCfgDelta(ICDescriptionDelta delta, String id) { if (delta == null) return null; diff --git a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/ICConfigurationDescription.java b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/ICConfigurationDescription.java index eac75d44021..cc53679e3d1 100644 --- a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/ICConfigurationDescription.java +++ b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/ICConfigurationDescription.java @@ -16,13 +16,29 @@ import org.eclipse.cdt.core.cdtvariables.ICdtVariablesContributor; import org.eclipse.cdt.core.model.CoreModel; import org.eclipse.cdt.core.settings.model.extension.CConfigurationData; import org.eclipse.cdt.core.settings.model.extension.CConfigurationDataProvider; +import org.eclipse.cdt.internal.core.settings.model.CConfigurationDescription; +import org.eclipse.cdt.internal.core.settings.model.CConfigurationDescriptionCache; import org.eclipse.core.runtime.CoreException; import org.eclipse.core.runtime.IPath; import org.eclipse.core.runtime.QualifiedName; /** - * This is the element representing configuration and thus this is the root element - * for configuration-specific settings + * This is the class representing configuration and thus this is the root element + * for configuration-specific settings. + *

+ * A typical (simplified) life-cycle of configuration description in CDT is as following: + *
1. A project is created or opened. A new read-only configuration description is loaded. + *
2. If a description needs to be changed, a client gets a copy as a writable configuration + * description first. Then, that instance can be edited. + *
3. The changed writable configuration description gets applied to the model and becomes + * read-only. + *
4. The project gets closed or removed. The configuration description gets disposed. + *

+ * Typically read-only configuration description would be represented by {@link CConfigurationDescriptionCache} + * and writable one by {@link CConfigurationDescription}. + * + * @see CProjectDescriptionEvent + * @see CConfigurationDescriptionCache */ public interface ICConfigurationDescription extends ICSettingContainer, ICSettingObject, ICSettingsStorage { /** diff --git a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/settings/model/CConfigurationDescription.java b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/settings/model/CConfigurationDescription.java index 0f2af5f4b18..3c74980e662 100644 --- a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/settings/model/CConfigurationDescription.java +++ b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/settings/model/CConfigurationDescription.java @@ -19,6 +19,7 @@ import java.util.Map; import org.eclipse.cdt.core.CCorePlugin; import org.eclipse.cdt.core.cdtvariables.ICdtVariablesContributor; import org.eclipse.cdt.core.settings.model.CConfigurationStatus; +import org.eclipse.cdt.core.settings.model.CProjectDescriptionEvent; import org.eclipse.cdt.core.settings.model.ICBuildSetting; import org.eclipse.cdt.core.settings.model.ICConfigExtensionReference; import org.eclipse.cdt.core.settings.model.ICConfigurationDescription; @@ -50,6 +51,13 @@ import org.eclipse.core.runtime.CoreException; import org.eclipse.core.runtime.IPath; import org.eclipse.core.runtime.QualifiedName; +/** + * The writable configuration description. + * + * @see ICConfigurationDescription + * @see CConfigurationDescriptionCache + * @see CProjectDescriptionEvent + */ public class CConfigurationDescription extends CDataProxyContainer implements ICConfigurationDescription, IProxyFactory, IInternalCCfgInfo { private CfgProxyCache fCache; // private ProxyProvider fFileProxyProvider; diff --git a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/settings/model/CConfigurationDescriptionCache.java b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/settings/model/CConfigurationDescriptionCache.java index 8a50d8369ed..f1285d887c3 100644 --- a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/settings/model/CConfigurationDescriptionCache.java +++ b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/settings/model/CConfigurationDescriptionCache.java @@ -17,6 +17,7 @@ import java.util.Map; import org.eclipse.cdt.core.cdtvariables.ICdtVariable; import org.eclipse.cdt.core.cdtvariables.ICdtVariablesContributor; import org.eclipse.cdt.core.settings.model.CConfigurationStatus; +import org.eclipse.cdt.core.settings.model.CProjectDescriptionEvent; import org.eclipse.cdt.core.settings.model.ICBuildSetting; import org.eclipse.cdt.core.settings.model.ICConfigExtensionReference; import org.eclipse.cdt.core.settings.model.ICConfigurationDescription; @@ -52,6 +53,40 @@ import org.eclipse.core.runtime.CoreException; import org.eclipse.core.runtime.IPath; import org.eclipse.core.runtime.QualifiedName; +/** + * CConfigurationDescriptionCache is a proxy class for serialization of configuration description data. + * + * An inspection of the scenario where user changes project properties and saves it yields + * following sequence of events: + *
    + *
  1. Initialization: + * + *
  2. User enters project properties/settings: + * + *
  3. User changes settings (in the settings configuration CConfigurationDescription) and saves it: + * + *
+ * + * @see ICConfigurationDescription + * @see CConfigurationDescription + * @see CProjectDescriptionEvent + */ public class CConfigurationDescriptionCache extends CDefaultConfigurationData implements ICConfigurationDescription, IInternalCCfgInfo, ICachedData { private CProjectDescription fParent;