org.eclipse.cdt.core.language.settings.providers

Class LanguageSettingsSerializableProvider

java.lang.Object

org.eclipse.cdt.core.AbstractExecutableExtensionBase

org.eclipse.cdt.core.language.settings.providers.LanguageSettingsBaseProvider

org.eclipse.cdt.core.language.settings.providers.LanguageSettingsSerializableProvider

All Implemented Interfaces:

ILanguageSettingsBroadcastingProvider, ILanguageSettingsProvider

Direct Known Subclasses:

LanguageSettingsGenericProvider

public class LanguageSettingsSerializableProvider
extends LanguageSettingsBaseProvider
implements ILanguageSettingsBroadcastingProvider

This class is the base class for language settings providers able to serialize into XML storage. Although this class has setter methods, by design its instances are not editable in UI nor instances can be assigned to a configuration (cannot be global or non-shared). Implement ILanguageSettingsEditableProvider interface for that. There is a generic implementation of this interface available to be used, see LanguageSettingsGenericProvider. For more on the suggested way of extending this class see the description of ILanguageSettingsProvider.

Since:

5.4

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	ATTR_CLASS
protected static String	ATTR_ID
protected static String	ATTR_NAME
protected static String	ELEM_LANGUAGE_SCOPE
protected static String	ELEM_PROVIDER

Fields inherited from class org.eclipse.cdt.core.language.settings.providers.LanguageSettingsBaseProvider

languageScope, properties

Constructor Summary

Constructors

Constructor and Description
LanguageSettingsSerializableProvider() Default constructor.
LanguageSettingsSerializableProvider(Element elementProvider) Constructor which allows to instantiate provider defined via XML markup.
LanguageSettingsSerializableProvider(String id, String name) Constructor.

Method Summary

Modifier and Type	Method and Description
void	clear() Clears all the entries for all configurations, all resources and all languages.
protected LanguageSettingsSerializableProvider	clone()
protected LanguageSettingsSerializableProvider	cloneShallow() Shallow clone of the provider.
void	configureProvider(String id, String name, List<String> languages, List<ICLanguageSettingEntry> entries, Map<String,String> properties) A method to configure the provider.
LanguageSettingsStorage	copyStorage() Return a copy of internal storage.
boolean	equals(Object obj)
List<ICLanguageSettingEntry>	getSettingEntries(ICConfigurationDescription cfgDescription, org.eclipse.core.resources.IResource rc, String languageId) Returns the list of setting entries for the given configuration description, resource and language.
int	hashCode()
boolean	isEmpty()
void	load(Element providerNode) Load provider from XML provider element.
void	loadAttributes(Element providerNode) Load attributes from XML provider element.
void	loadEntries(Element providerNode) Load provider entries from XML provider element.
Element	serialize(Element parentElement) Serialize the provider under parent XML element.
Element	serializeAttributes(Element parentElement) Serialize the provider attributes under parent XML element.
void	serializeEntries(Element elementProvider) Serialize the provider entries under parent XML element.
org.eclipse.core.runtime.IStatus	serializeLanguageSettings(ICConfigurationDescription cfgDescription) Convenience method to persist language settings entries for the project or workspace as often-used operation.
void	serializeLanguageSettingsInBackground(ICConfigurationDescription cfgDescription) Convenience method to persist language settings entries in background for the project or workspace as often-used operation.
void	setLanguageScope(List<String> languages) Sets the language scope of the provider.
void	setProperty(String key, String value) Set a custom property of the provider.
void	setPropertyBool(String key, boolean value) Set a custom boolean property of the provider.
void	setSettingEntries(ICConfigurationDescription cfgDescription, org.eclipse.core.resources.IResource rc, String languageId, List<? extends ICLanguageSettingEntry> entries) Sets language settings entries for the provider.

Methods inherited from class org.eclipse.cdt.core.language.settings.providers.LanguageSettingsBaseProvider

getLanguageScope, getProperty, getPropertyBool

Methods inherited from class org.eclipse.cdt.core.AbstractExecutableExtensionBase

getId, getName, setId, setName, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.eclipse.cdt.core.language.settings.providers.ILanguageSettingsBroadcastingProvider

getId, getName

Field Detail

ATTR_ID

protected static final String ATTR_ID

See Also:

Constant Field Values

ATTR_NAME

protected static final String ATTR_NAME

See Also:

Constant Field Values

ATTR_CLASS

protected static final String ATTR_CLASS

See Also:

Constant Field Values

ELEM_PROVIDER

protected static final String ELEM_PROVIDER

See Also:

Constant Field Values

ELEM_LANGUAGE_SCOPE

protected static final String ELEM_LANGUAGE_SCOPE

See Also:

Constant Field Values

Constructor Detail

LanguageSettingsSerializableProvider

public LanguageSettingsSerializableProvider()

Default constructor. This constructor has to be always followed with setting id and name of the provider. This constructor is necessary to instantiate the class via the extension point in plugin.xml.

LanguageSettingsSerializableProvider

public LanguageSettingsSerializableProvider(String id,
                                            String name)

Constructor.

Parameters:

id - - id of the provider.

name - - name of the provider. Note that this name shows up in UI.

LanguageSettingsSerializableProvider

public LanguageSettingsSerializableProvider(Element elementProvider)

Constructor which allows to instantiate provider defined via XML markup.

Parameters:

elementProvider -

Method Detail

configureProvider

public void configureProvider(String id,
                              String name,
                              List<String> languages,
                              List<ICLanguageSettingEntry> entries,
                              Map<String,String> properties)

Description copied from class: LanguageSettingsBaseProvider

A method to configure the provider. The initialization of provider from the extension point is done in 2 steps. First, the class is created as an executable extension using the default provider. Then this method is used to configure the provider.

It is not allowed to reconfigure the provider.

Overrides:

configureProvider in class LanguageSettingsBaseProvider

Parameters:

id - - id of the provider.

name - - name of the provider to be presented to a user.

languages - - list of languages the entries provided for. languages can be null, in this case the entries are provided for any language.

entries - - the list of language settings entries this provider provides. If null is passed, the provider creates an empty list.

properties - - custom properties as the means to customize providers.

isEmpty

public boolean isEmpty()

Returns:

true if the provider does not keep any settings yet or false if there are some.

setLanguageScope

public void setLanguageScope(List<String> languages)

Sets the language scope of the provider.

Parameters:

languages - - the list of languages this provider provides for. If null, the provider provides for any language.

See Also:

LanguageSettingsBaseProvider.getLanguageScope()

clear

public void clear()

Clears all the entries for all configurations, all resources and all languages.

setSettingEntries

public void setSettingEntries(ICConfigurationDescription cfgDescription,
                              org.eclipse.core.resources.IResource rc,
                              String languageId,
                              List<? extends ICLanguageSettingEntry> entries)

Sets language settings entries for the provider. Note that the entries are not persisted at that point. Use this method to set the entries for all resources one by one and after all done persist in one shot using serializeLanguageSettings(ICConfigurationDescription). See for example AbstractBuildCommandParser and AbstractBuiltinSpecsDetector in build plugins.

Parameters:

cfgDescription - - configuration description.

rc - - resource such as file or folder. If null the entries are considered to be being defined as default entries for resources.

languageId - - language id. If null, then entries are considered to be defined for the language scope. See LanguageSettingsBaseProvider.getLanguageScope()

entries - - language settings entries to set.

getSettingEntries

public List<ICLanguageSettingEntry> getSettingEntries(ICConfigurationDescription cfgDescription,
                                                      org.eclipse.core.resources.IResource rc,
                                                      String languageId)

Returns the list of setting entries for the given configuration description, resource and language.

Note to implementers - this method should not be used to do any long running operations such as extensive calculations or reading files. If you need to do so, the recommended way is to do the calculations outside of this function call - in advance and on appropriate event. For example, Build Output Parser prepares the list and stores it in internal cache while parsing output. ILanguageSettingsProvider.getSettingEntries(ICConfigurationDescription, IResource, String) will return cached entries when asked. You can also implement ICListenerAgent interface to get registered and listen to arbitrary events.
Note that this list is unmodifiable. To modify the list copy it, change and use setSettingEntries(ICConfigurationDescription, IResource, String, List).

Note also that you can compare these lists with simple equality operator ==, as the lists themselves are backed by WeakHashSet> where identical copies (deep comparison is used) are replaced with the same one instance.

Specified by:

getSettingEntries in interface ILanguageSettingsBroadcastingProvider

Specified by:

getSettingEntries in interface ILanguageSettingsProvider

Overrides:

getSettingEntries in class LanguageSettingsBaseProvider

Parameters:

cfgDescription - - configuration description.

rc - - resource such as file or folder. If null, the default entries for all resources are returned.

languageId - - language id. If null, then entries defined for the language scope are returned. See LanguageSettingsBaseProvider.getLanguageScope()

Returns:

unmodifiable list of setting entries or null if no settings defined. the list is internally pooled and guaranteed to be the same object for equal lists.

serialize

public final Element serialize(Element parentElement)

Serialize the provider under parent XML element. This is convenience method not intended to be overridden on purpose. Override serializeAttributes(Element) or serializeEntries(Element) instead.

Parameters:

parentElement - - element where to serialize.

Returns:

- newly created "provider" element. That element will already be attached to the parent element.

serializeAttributes

public Element serializeAttributes(Element parentElement)

Serialize the provider attributes under parent XML element. That is equivalent to serializing everything (including language scope) except entries.

Parameters:

parentElement - - element where to serialize.

Returns:

- newly created "provider" element. That element will already be attached to the parent element.

serializeEntries

public void serializeEntries(Element elementProvider)

Serialize the provider entries under parent XML element.

Parameters:

elementProvider - - element where to serialize the entries.

serializeLanguageSettings

public org.eclipse.core.runtime.IStatus serializeLanguageSettings(ICConfigurationDescription cfgDescription)

Convenience method to persist language settings entries for the project or workspace as often-used operation. Note that configuration description is passed as an argument but the current implementation saves all configurations.

Parameters:

cfgDescription - - configuration description. If not null, all providers of the project are serialized. If null, global workspace providers are serialized.

Returns:

- status of operation.

serializeLanguageSettingsInBackground

public void serializeLanguageSettingsInBackground(ICConfigurationDescription cfgDescription)

Convenience method to persist language settings entries in background for the project or workspace as often-used operation. Note that configuration description is passed as an argument but the current implementation saves all configurations.

Parameters:

cfgDescription - - configuration description. If not null, all providers of the project are serialized. If null, global workspace providers are serialized.

load

public final void load(Element providerNode)

Load provider from XML provider element. This is convenience method not intended to be overridden on purpose. Override loadAttributes(Element) or loadEntries(Element) instead.

Parameters:

providerNode - - XML element "provider" to load provider from.

loadAttributes

public void loadAttributes(Element providerNode)

Load attributes from XML provider element.

Parameters:

providerNode - - XML element "provider" to load attributes from.

loadEntries

public void loadEntries(Element providerNode)

Load provider entries from XML provider element.

Parameters:

providerNode - - parent XML element "provider" where entries are defined.

setProperty

public void setProperty(String key,
                        String value)

Set a custom property of the provider.

A note of caution - do not use default values for a provider which are different from empty or null value. When providers are checked for equality (during internal operations in core) the missing properties are evaluated as empty ones.

Parameters:

key - - name of the property.

value - - value of the property. If value is null the property is removed from the list.

See Also:

LanguageSettingsBaseProvider.getProperty(String)

setPropertyBool

public void setPropertyBool(String key,
                            boolean value)

Set a custom boolean property of the provider.
Please, note that default value is always false.

Parameters:

key - - name of the property.

value - - boolean value of the property.

See Also:

LanguageSettingsBaseProvider.getProperty(String)

cloneShallow

protected LanguageSettingsSerializableProvider cloneShallow()
                                                     throws CloneNotSupportedException

Shallow clone of the provider. "Shallow" is defined here as the exact copy except that the copy will have zero language settings entries.

Returns:

shallow copy of the provider.

Throws:

CloneNotSupportedException - in case clone() throws the exception.

clone

protected LanguageSettingsSerializableProvider clone()
                                              throws CloneNotSupportedException

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

copyStorage

public LanguageSettingsStorage copyStorage()

Description copied from interface: ILanguageSettingsBroadcastingProvider

Return a copy of internal storage. This should be a deep copy/clone of the storage. It is used to calculate the delta and being kept in the last state object of configuration description to compare to a new state later.

Specified by:

copyStorage in interface ILanguageSettingsBroadcastingProvider

Returns:

a copy of internal storage.

hashCode

public int hashCode()

Overrides:

hashCode in class LanguageSettingsBaseProvider

equals

public boolean equals(Object obj)

Overrides:

equals in class LanguageSettingsBaseProvider

Returns:

true if the objects are equal, false otherwise.

See Also:

Object.equals(java.lang.Object)