From afa71216dd7978ed25e1b578579f7685c5287a8b Mon Sep 17 00:00:00 2001 From: Andrew Gvozdev Date: Sat, 17 Dec 2011 11:59:20 -0500 Subject: [PATCH] JavaDoc ICConfigurationDescription --- .../model/CProjectDescriptionEvent.java | 52 ++++++++++--------- .../model/ICConfigurationDescription.java | 20 ++++++- .../model/CConfigurationDescription.java | 8 +++ .../model/CConfigurationDescriptionCache.java | 45 ++++++++++------ 4 files changed, 82 insertions(+), 43 deletions(-) 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 771eb1280de..d3e4a2e36a4 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 @@ -21,6 +21,7 @@ import org.eclipse.cdt.core.cdtvariables.ICdtVariablesContributor; import org.eclipse.cdt.core.language.settings.providers.ILanguageSettingsProvider; import org.eclipse.cdt.core.language.settings.providers.ILanguageSettingsProvidersKeeper; 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,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, ILanguageSettingsProvidersKeeper { private CfgProxyCache fCache; 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 42087ea7220..d66b85bd1f1 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 @@ -19,6 +19,7 @@ import org.eclipse.cdt.core.cdtvariables.ICdtVariablesContributor; import org.eclipse.cdt.core.language.settings.providers.ILanguageSettingsProvider; import org.eclipse.cdt.core.language.settings.providers.ILanguageSettingsProvidersKeeper; 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; @@ -60,22 +61,34 @@ import org.eclipse.core.runtime.QualifiedName; * * An inspection of the scenario where user changes project properties and saves it yields * following sequence of events: - * - Initialization: - * - After eclipse started a project is being opened. A new CConfigurationDescriptionCache is created - * with CConfigurationDescriptionCache(ICStorageElement storage, CProjectDescription parent) constructor. - * - Any clients needed ICConfigurationDescription get CConfigurationDescription using constructor - * CConfigurationDescription(CConfigurationData data, String buildSystemId, ICDataProxyContainer cr) - * where the CConfigurationDescriptionCache is passed as data. The reference to cache is kept in field fCfgCache. - * - fCfgCache is used to getSpecSettings() CConfigurationSpecSettings, after that fCfgCache is set to null. - * - User enters project properties/settings: - * - another CConfigurationDescription (settings configuration) created using the same constructor setting fCfgCache - * to the CConfigurationDescriptionCache. - * - User changes settings (in the settings configuration CConfigurationDescription) and saves it: - * - new CConfigurationDescriptionCache is created from the CConfigurationDescription via constructor - * CConfigurationDescriptionCache(ICConfigurationDescription baseDescription, ...) where - * baseDescription is saved as fBaseDescription. - * - CConfigurationDescriptionCache.applyData(...) is used to persist the data. at that point - * reference fBaseDescription gets set to null. + *
    + *
  1. Initialization: + *
      + *
    • After eclipse started a project is being opened. A new CConfigurationDescriptionCache is created + * with CConfigurationDescriptionCache(ICStorageElement storage, CProjectDescription parent) constructor. + *
    • Any clients needed ICConfigurationDescription get CConfigurationDescription using constructor + * CConfigurationDescription(CConfigurationData data, String buildSystemId, ICDataProxyContainer cr) + * where the CConfigurationDescriptionCache is passed as data. The reference to cache is kept in field fCfgCache. + *
    • fCfgCache is used to getSpecSettings() CConfigurationSpecSettings, after that fCfgCache is set to null. + *
    + *
  2. User enters project properties/settings: + *
      + *
    • another CConfigurationDescription (settings configuration) created using the same constructor setting fCfgCache + * to the CConfigurationDescriptionCache. + *
    + *
  3. User changes settings (in the settings configuration CConfigurationDescription) and saves it: + *
      + *
    • new CConfigurationDescriptionCache is created from the CConfigurationDescription via constructor + * CConfigurationDescriptionCache(ICConfigurationDescription baseDescription, ...) where + * baseDescription is saved as fBaseDescription. + *
    • CConfigurationDescriptionCache.applyData(...) is used to persist the data. at that point + * reference fBaseDescription gets set to null. + *
    + *
+ * + * @see ICConfigurationDescription + * @see CConfigurationDescription + * @see CProjectDescriptionEvent */ public class CConfigurationDescriptionCache extends CDefaultConfigurationData implements ICConfigurationDescription, IInternalCCfgInfo, ILanguageSettingsProvidersKeeper, ICachedData {