Resource change events for encoding changes

Last modified: August 27th, 2004

This document is a place where to gather the requirements and plan a solution for bug 59899

Things that affect the encoding of files

1. the file's encoding as set by the user
2. the file's content type
   1. the file's name
   2. the list of file specifications for a content type
   3. the content type default encoding
   4. the encoding information embedded in the file's contents
3. the parent's default encoding
   1. the file.encoding property
   2. the workspace encoding preference
   3. the project or folder default encoding project preference

Scenarios where the encoding for a file could change

1. the user changed the encoding (or set it to default) for a specific file using the file's properties dialog

   This is the most basic scenario - affects the IFile#setCharset operation.

   Fix: instrument File#setCharset (the long-running version) to mark the file as having encoding changes.

2. the user changed the encoding (or set it to default) for a specific file using the text editor action (Edit > Encoding)

   Although the user action is different, this is similar to the scenario above.

   Fix: the same as in the case mentioned.

3. the user changed the default encoding (or set it to default) for a container (folder, project) using the resource's properties dialog

   Although this may not be easy to support, it is also a basic requirement. Affected operation: IContainer#setDefaultCharset.

   Planned fix: WorkspaceRoot/Project/Folder#setDefaultCharset need to traverse all children and mark those that a) don't have an encoding explicitly set and b) do not belong to any content type that provide a default encoding as having encoding changes.

   Actual fix: as planned, except that no deltas are generated for changes to the workspace root.

4. a file is moved to a different location, having a different file encoding inherited from the parent

   It is not clear we need any special support here. Not sure whether builders and interesting listeners always simply treat a file being moved as a big change and rebuild the affected model, or they just adjust their model correspondingly (re: resource's path change), without recomputing anything.

   Fix: no action required - listeners interested in encoding changes should consider MOVED_FROM/TO deltas as indication the encoding may have changed.

5. a direct change to the preferences file for a project (e.g. by manually editing the file, or checking it out from the repository, etc), causing changes to the encoding settings of projects, folders and/or files

   This would cause preference change events to be broadcast. We would have to capture such events and generate a corresponding resource change event. One problem here is that we are in the context of a POST_CHANGE/PRE_DELETE notification (workspace is closed for changes).

   Planned fix: project preference changes in this case will be sent while the workspace is still open for business. A project preference change listener has then to (from inside an workspace operation) mark all affected resources as having encoding changes.

   Actual fix: when the project preferences file that stores the charset preferences is changed, we fire encoding change events (in a background job) for *all* resources in the project, since we have no means to figure out which ones actually changed.

6. the user promotes direct changes to the corresponding project preferences file directly in the file system

   The changes will be caught when the file is refreshed, but it may not be possible to figure out what the previous values of properties were (for instance, when the properties have never been loaded in memory before). Other than that, is the same scenario as above.

   Fix: the same as in the case mentioned.

7. the user promotes direct changes to the corresponding project preferences file between two Eclipse sessions

   There will be no way to figure out what the previous values for the properties were. No changes will be detected.

   Fix: none.

8. the user changed the default encoding (or set it to default, which is the value of the file.encoding property) for the workspace using the preferences dialog (General > Editors > New text file encoding)

   A preference change listener would have to react appropriately by issuing a resource change event for the workspace root (and all affected children!). This is similar as the case where changes are made directly to the file.

   Planned fix: the same as in the case mentioned.

   Actual fix: the Platform/UI has been requested to use IWorkspaceRoot#setDefaultCharset instead (bug 71742). This handles the case the user changes its preferences but does not handle the case preferences are imported. This needs more work.

9. the very same preference is changed by directly editing the corresponding preferences file between two Eclipse sessions

   We would have to keep a copy of the preference value somewhere and check it during startup. If it has changed, the same as above would have to be done.

   Planned fix: during startup, compare the last workspace encoding (need to remember that somewhere) and the new one. If it has changed, mark the affected files accordingly.

   Actual fix: none.

10. the VM started with default default encoding (the value of the file.encoding system property) that was different than the one used in the previous session, and the workspace root default encoding was not set

    Similar to above.

    Planned fix: the same as in the case mentioned.

    Actual fix: none.

11. a file that has its encoding determined from its contents (e.g. a XML file) is modified, causing the resulting encoding to be different

    A regular resource change event is already issued for the content change. Should not have to do anything else.

    Fix: no action required. Clients are expected to react to content changes considering that the encoding may have changed.

12. a content type has its default encoding changed

    Planned fix: a preference change listener would have to catch the event and produce the appropriate delta for every affected resource in the whole workspace.

    Actual fix: we listen for content type change events and produce the appropriate delta for every affected resource in the whole workspace. We are not smart enough to avoid generating deltas for files that have a user-set encoding, which are not actually affected.

13. file specs are added to/removed from a content type that has a default encoding set

    Same as above.

    Planned fix: the same as in the case mentioned.

    Actual fix: when a change to a content type happens, encoding change events will be generated (in a background job) for all files whose names match the content type's current definition.This acknowledgedly misses the case where a file ceases to belong to a content type that used to determine its encoding.

14. a file name changes, and it stops/starts belonging to a given content type

    This is caught by the MODE_FROM/MOVED_TO case. Clients are expected to recompute their internal state when a file has its name changed.

    Fix: no action required.

15. a content type is added/removed between two sessions, causing the content types (and default encoding) of some files to change.

There would be no property/registry change events for that.

Fix: none.

16. a content type that has a default charset definition is dynamically installed.

    The Resources plug-in is not expected to react properly on such situations (it is not supposed to be dynamic-aware).

    Fix: none.

Notes from discussions on July 27th

Content Type (Runtime)

• new API for notification
• listener pattern
• when do notifications happen?
• no major technical difficulties

File Encoding (Resources)

• catch events related to changes in the content type registry
• potential for VERY long operations
• walking the resource tree looking for matches based on file extension, etc

• changes are made via the preference API and through the resource API (#setContents and #refreshLocal)
• we store the following values in prefs:
1. workspace encoding (instance prefs)
2. non-default content types (instance prefs)
3. project+children encodings (project prefs)
• ignore preference change events
• problem for #3 is that we need to generate a delta based on POST_CHANGE notification (workspace tree is locked)
• project description file already has special code in #setContents and #refreshLocal (#updateProjectDescription is called and this method determines whether or not we are dealing with the project description file and if so then what action to take)
• investigate adding a #updateProjectSettings method which does the same type of thing for project settings files

• follow the begin/end operation template
• modify the ResourceInfos so they generate a delta
• do we have deltas for the workspace root?
• DeltaDataTree short-circuit returns in its compare
• if deltas are deep, we might not care for case of root (except for consistency) - actually, although we spec'd more or less that we would do that, I don't actually think we should propagate change events when the default encoding for containers (root, projects, folders) change - only files. The specs can be reworded to have this meaning. Although it is not the main motivation, it makes this problem irrelevant.

• do we need to hold onto an extra int/log in ResourceInfo as a timestamp/generation count for the encoding?
• might be able to use bytes from the long we already have
• change the ResourceComparator to set the appropriate flags