From 3713fcd0803074a802ae344d35c598bf7dd1eebb Mon Sep 17 00:00:00 2001 From: Andrew Gvozdev Date: Sun, 11 Dec 2011 21:47:24 -0500 Subject: [PATCH] JavaDoc --- .../ILanguageSettingsProvidersKeeper.java | 8 ++- .../providers/LanguageSettingsManager.java | 54 +++++++++++------- .../LanguageSettingsExtensionManager.java | 47 +++++++++------ .../LanguageSettingsProvidersSerializer.java | 57 ++++++++++++++----- 4 files changed, 113 insertions(+), 53 deletions(-) diff --git a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/language/settings/providers/ILanguageSettingsProvidersKeeper.java b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/language/settings/providers/ILanguageSettingsProvidersKeeper.java index 76c2e28c72c..51dc65f05e5 100644 --- a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/language/settings/providers/ILanguageSettingsProvidersKeeper.java +++ b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/language/settings/providers/ILanguageSettingsProvidersKeeper.java @@ -25,10 +25,12 @@ public interface ILanguageSettingsProvidersKeeper { * used to supply language settings {@link ICLanguageSettingEntry} such as include paths * or preprocessor macros. * - * @param providers the list of providers to assign to the owner (configuration description). + * @param providers - the list of providers to assign to the owner (configuration description). * This method clones the internal list or otherwise ensures immutability of the internal - * list before actual addition to the project model. - * That is due to TODO - very important reason but I forgot why by now. + * list before actual addition to the project model. That is to ensure that there is no + * back-door access and all changes in the list done by this method which fires notifications + * to the registered listeners about the accompanied changes in settings entries, see + * {@link LanguageSettingsManager#registerLanguageSettingsChangeListener(ILanguageSettingsChangeListener)}. */ public void setLanguageSettingProviders(List providers); diff --git a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/language/settings/providers/LanguageSettingsManager.java b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/language/settings/providers/LanguageSettingsManager.java index 3cd135f41d6..c51c0eab544 100644 --- a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/language/settings/providers/LanguageSettingsManager.java +++ b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/language/settings/providers/LanguageSettingsManager.java @@ -121,7 +121,10 @@ public class LanguageSettingsManager { } /** - * Checks if the provider is defined on the workspace level. + * Checks if the provider is a workspace level provider. + * This method is intended to check providers retrieved from a configuration. + * Raw providers from {@link #getRawProvider(ILanguageSettingsProvider)} + * are not considered as workspace providers. * * @param provider - provider to check. * @return {@code true} if the given provider is workspace provider, {@code false} otherwise. @@ -131,12 +134,16 @@ public class LanguageSettingsManager { } /** - * TODO - helper method for often used chunk of code - * @param provider - * @return ILanguageSettingsProvider + * Helper method to get to real underlying provider collecting entries as opposed to wrapper + * which is normally used for workspace provider. + * @see LanguageSettingsProvidersSerializer#isWorkspaceProvider(ILanguageSettingsProvider) + * + * @param provider - the provider to get raw provider for. Can be either workspace provider + * or regular one. + * @return raw underlying provider for workspace provider or provider itself if no wrapper is used. */ public static ILanguageSettingsProvider getRawProvider(ILanguageSettingsProvider provider) { - if (LanguageSettingsManager.isWorkspaceProvider(provider)){ + if (LanguageSettingsManager.isWorkspaceProvider(provider)) { provider = LanguageSettingsProvidersSerializer.getRawWorkspaceProvider(provider.getId()); } return provider; @@ -158,34 +165,43 @@ public class LanguageSettingsManager { } /** - * TODO - * @param deepCopy TODO - * @param id + * Copy language settings provider. It is different from clone() methods in that + * it does not throw {@code CloneNotSupportedException} but returns {@code null} + * instead. + * + * @param provider - language settings provider to copy. + * @param deep - {@code true} to request deep copy including copying settings entries + * or {@code false} to return shallow copy with no settings entries. * - * @return + * @return a copy of the provider or null if copying is not possible. */ public static ILanguageSettingsEditableProvider getProviderCopy(ILanguageSettingsEditableProvider provider, boolean deep) { return LanguageSettingsExtensionManager.getProviderCopy(provider, deep); } /** - * Get Language Settings Provider defined via - * {@code org.eclipse.cdt.core.LanguageSettingsProvider} extension point. + * Get language settings provider defined via extension point + * {@code org.eclipse.cdt.core.LanguageSettingsProvider}. + * A new copy of the extension provider is returned. * - * @param id - ID of provider to find. - * @param deep TODO - * @return the copy of the provider if possible (i.e. for {@link ILanguageSettingsEditableProvider}) - * or workspace provider if provider is not copyable. + * @param id - ID of the extension provider. + * @param deep - {@code true} to request deep copy including copying settings entries + * or {@code false} to return shallow copy with no settings entries. + * @return the copy of the extension provider if possible (i.e. for {@link ILanguageSettingsEditableProvider}) + * or {@code null} if provider is not copyable. */ public static ILanguageSettingsProvider getExtensionProviderCopy(String id, boolean deep) { return LanguageSettingsExtensionManager.getExtensionProviderCopy(id, deep); } /** - * TODO - * @param provider - * @param deep - * @return + * Test if the provider is equal to the one defined via extension point + * {@code org.eclipse.cdt.core.LanguageSettingsProvider}. + * + * @param provider - the provider to test. + * @param deep - {@code true} to check for deep equality testing also settings entries + * or {@code false} to test shallow copy with no settings entries. + * @return - {@code true} if the provider matches the extension or {@code false} otherwise. */ public static boolean isEqualExtensionProvider(ILanguageSettingsProvider provider, boolean deep) { return LanguageSettingsExtensionManager.isEqualsExtensionProvider(provider, deep); diff --git a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/language/settings/providers/LanguageSettingsExtensionManager.java b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/language/settings/providers/LanguageSettingsExtensionManager.java index d47c6f78a4d..848eb9d8a47 100644 --- a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/language/settings/providers/LanguageSettingsExtensionManager.java +++ b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/language/settings/providers/LanguageSettingsExtensionManager.java @@ -276,8 +276,8 @@ public class LanguageSettingsExtensionManager { } ILanguageSettingsProvider provider = createProviderCarcass(className, Platform.getExtensionRegistry()); - if (provider==null) { - IStatus status = new Status(IStatus.ERROR, CCorePlugin.PLUGIN_ID, "Not able to load provider class=" + className); + if (provider == null) { + IStatus status = new Status(IStatus.ERROR, CCorePlugin.PLUGIN_ID, "Not able to load provider class=" + className); //$NON-NLS-1$ CCorePlugin.log(new CoreException(status)); } return provider; @@ -291,20 +291,27 @@ public class LanguageSettingsExtensionManager { ArrayList list = new ArrayList(fExtensionProviders.size()); for (String id : fExtensionProviders.keySet()) { ILanguageSettingsProvider extensionProvider = getExtensionProviderCopy(id, true); - if (extensionProvider==null) + if (extensionProvider == null) { extensionProvider = fExtensionProviders.get(id); + } - if (extensionProvider!=null) + if (extensionProvider != null) { list.add(extensionProvider); + } } return list; } /** - * TODO - * @param provider - * @param deep - * @return + * Copy language settings provider. It is different from clone() methods in that + * it does not throw {@code CloneNotSupportedException} but returns {@code null} + * instead. + * + * @param provider - language settings provider to copy. + * @param deep - {@code true} to request deep copy including copying settings entries + * or {@code false} to return shallow copy with no settings entries. + * + * @return a copy of the provider or null if copying is not possible. */ public static ILanguageSettingsEditableProvider getProviderCopy(ILanguageSettingsEditableProvider provider, boolean deep) { try { @@ -320,12 +327,15 @@ public class LanguageSettingsExtensionManager { } /** - * Get Language Settings Provider defined via - * {@code org.eclipse.cdt.core.LanguageSettingsProvider} extension point. + * Get language settings provider defined via extension point + * {@code org.eclipse.cdt.core.LanguageSettingsProvider}. + * A new copy of the extension provider is returned. * - * @param id - ID of provider to find. - * @param deep TODO - * @return the clone of the provider or {@code null} TODO if provider is not defined. + * @param id - ID of the extension provider. + * @param deep - {@code true} to request deep copy including copying settings entries + * or {@code false} to return shallow copy with no settings entries. + * @return the copy of the extension provider if possible (i.e. for {@link ILanguageSettingsEditableProvider}) + * or {@code null} if provider is not copyable. */ public static ILanguageSettingsProvider getExtensionProviderCopy(String id, boolean deep) { ILanguageSettingsProvider provider = fExtensionProviders.get(id); @@ -337,10 +347,13 @@ public class LanguageSettingsExtensionManager { } /** - * TODO - * @param provider - * @param deep - * @return + * Test if the provider is equal to the one defined via extension point + * {@code org.eclipse.cdt.core.LanguageSettingsProvider}. + * + * @param provider - the provider to test. + * @param deep - {@code true} to check for deep equality testing also settings entries + * or {@code false} to test shallow copy with no settings entries. + * @return - {@code true} if the provider matches the extension or {@code false} otherwise. */ public static boolean isEqualsExtensionProvider(ILanguageSettingsProvider provider, boolean deep) { String id = provider.getId(); diff --git a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/language/settings/providers/LanguageSettingsProvidersSerializer.java b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/language/settings/providers/LanguageSettingsProvidersSerializer.java index 25822dac944..8f9b62edbdd 100644 --- a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/language/settings/providers/LanguageSettingsProvidersSerializer.java +++ b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/language/settings/providers/LanguageSettingsProvidersSerializer.java @@ -88,6 +88,9 @@ public class LanguageSettingsProvidersSerializer { private static ListenerList fLanguageSettingsChangeListeners = new ListenerList(ListenerList.IDENTITY); + /** + * language settings provider listener-cfgDescription association + */ private static class ListenerAssociation { private ICListenerAgent listener; private ICConfigurationDescription cfgDescription; @@ -98,6 +101,11 @@ public class LanguageSettingsProvidersSerializer { } } + /** + * Wrapper for workspace providers to ensure level of indirection. That way workspace providers + * can be changed/replaced without notifying/changing the configurations which keep the providers + * in their lists. + */ private static class LanguageSettingsWorkspaceProvider implements ILanguageSettingsProvider, ICListenerAgent { private String providerId; private int projectCount = 0; @@ -141,6 +149,7 @@ public class LanguageSettingsProvidersSerializer { } return false; } + /** * Method toString() for debugging purposes. */ @@ -171,7 +180,7 @@ public class LanguageSettingsProvidersSerializer { @Override public void registerListener(ICConfigurationDescription cfgDescription) { - // keep in mind that rawProvider can change + // keep in mind that rawProvider can change externally ILanguageSettingsProvider rawProvider = getRawProvider(); if (rawProvider instanceof ICListenerAgent) { ((ICListenerAgent) rawProvider).registerListener(null); @@ -180,7 +189,7 @@ public class LanguageSettingsProvidersSerializer { @Override public void unregisterListener() { - // keep in mind that rawProvider can change + // keep in mind that rawProvider can change externally ILanguageSettingsProvider rawProvider = getRawProvider(); if (rawProvider instanceof ICListenerAgent) { ((ICListenerAgent) rawProvider).unregisterListener(); @@ -190,7 +199,6 @@ public class LanguageSettingsProvidersSerializer { /** * Language Settings Change Event implementation. - * */ private static class LanguageSettingsChangeEvent implements ILanguageSettingsChangeEvent { private String projectName = null; @@ -287,7 +295,7 @@ public class LanguageSettingsProvidersSerializer { } /** - * Set and store in workspace area user defined providers. + * Set and store user defined providers in workspace area. * * @param providers - array of user defined providers * @throws CoreException in case of problems @@ -424,6 +432,7 @@ projects: Element elementExtension = XmlUtil.appendElement(rootElement, ELEM_EXTENSION, new String[] {ATTR_POINT, LanguageSettingsExtensionManager.PROVIDER_EXTENSION_FULL_ID}); for (LanguageSettingsSerializableProvider provider : serializableWorkspaceProviders) { + // TODO don't serialize if equals to extension provider provider.serialize(elementExtension); } @@ -448,14 +457,17 @@ projects: } } + /** + * Load language settings for workspace. + */ public static void loadLanguageSettingsWorkspace() throws CoreException { List providers = null; URI uriStoreWsp = getStoreInWorkspaceArea(STORAGE_WORKSPACE_LANGUAGE_SETTINGS); Document doc = null; - serializingLock.acquire(); try { + serializingLock.acquire(); doc = XmlUtil.loadXml(uriStoreWsp); } catch (Exception e) { CCorePlugin.log("Can't load preferences from file "+uriStoreWsp, e); //$NON-NLS-1$ @@ -463,12 +475,12 @@ projects: serializingLock.release(); } - if (doc!=null) { + if (doc != null) { Element rootElement = doc.getDocumentElement(); NodeList providerNodes = rootElement.getElementsByTagName(LanguageSettingsSerializableProvider.ELEM_PROVIDER); List userDefinedProvidersIds = new ArrayList(); - for (int i=0;i(); - + if (provider != null) { + if (providers == null) { + providers = new ArrayList(); + } if (!LanguageSettingsManager.isEqualExtensionProvider(provider, true)) { providers.add(provider); } @@ -615,6 +627,8 @@ projects: } /** + * Load language settings to the project description from XML. + * * @noreference This method is not intended to be referenced by clients. * It is public solely for benefit of JUnit testing. */ @@ -748,6 +762,10 @@ projects: return provider; } + /** + * Load language settings from workspace and project storages for the given project description. + * @param prjDescription - project description to load language settings. + */ public static void loadLanguageSettings(ICProjectDescription prjDescription) { IProject project = prjDescription.getProject(); IFile storePrj = project.getFile(SETTINGS_FOLDER_NAME+STORAGE_PROJECT_LANGUAGE_SETTINGS); @@ -766,8 +784,8 @@ projects: URI uriStoreWsp = getStoreInWorkspaceArea(project.getName()+'.'+STORAGE_WORKSPACE_LANGUAGE_SETTINGS); Document docWsp = null; - serializingLock.acquire(); try { + serializingLock.acquire(); docWsp = XmlUtil.loadXml(uriStoreWsp); } finally { serializingLock.release(); @@ -821,6 +839,14 @@ projects: return provider; } + /** + * Helper method to get to real underlying provider collecting entries as opposed to wrapper + * which is normally used for workspace provider. + * @see LanguageSettingsProvidersSerializer#isWorkspaceProvider(ILanguageSettingsProvider) + * + * @param id - ID of the provider. + * @return raw underlying provider. + */ public static ILanguageSettingsProvider getRawWorkspaceProvider(String id) { return rawGlobalWorkspaceProviders.get(id); } @@ -839,11 +865,13 @@ projects: } /** - * Checks if the provider is defined on the workspace level. + * Checks if the provider is a workspace level provider. + * This method is intended to check providers retrieved from a configuration. + * Raw providers from {@link #getRawWorkspaceProvider(String)} + * are not considered as workspace providers. * * @param provider - provider to check. * @return {@code true} if the given provider is workspace provider, {@code false} otherwise. - * */ public static boolean isWorkspaceProvider(ILanguageSettingsProvider provider) { return provider instanceof LanguageSettingsWorkspaceProvider; @@ -1066,6 +1094,7 @@ projects: return LanguageSettingsStorage.getPooledList(provider.getSettingEntries(cfgDescription, rc, languageId)); } catch (Throwable e) { String cfgId = cfgDescription!=null ? cfgDescription.getId() : null; + @SuppressWarnings("nls") String msg = "Exception in provider "+provider.getId()+": getSettingEntries("+cfgId+", "+rc+", "+languageId+")"; CCorePlugin.log(msg, e); // return empty list to prevent getting potentially non-empty list from up the resource tree