[jdt-core-dev] 36888 - closing the gap between compilation units and wor

["Philippe P Mulet" <philippe_mulet@xxxxxxxxxx>]

Please answer to jdt-core-dev@xxxxxxxxxxx.

This work item is intending to ease manipulating of working copies for
clients. As of today, there are currently two typical users:
      long lifecycle: editor. As long as the editor is openend, a working
      copy is kept active, and will be shown in various views, and be
      updated as changes are notified. In particular, the package view must
      handle the lazy creation of working copies as it shows units which
      can then be opened in editor. In order for several editors (opened in
      different perspective on the same unit) to share their contents, we
      support a notion of shared working copies (we will answer back the
      existing one if already active).
      short lifecycle: refactoring. A working copy is created for a short
      duration, a few changes are performed, then it is discarded. No need
      to react to changes in the meantime, but need to be able to have
      changes performed simultaneously amongst several units to be aware of
      each other.

Goal
   Provide a way to edit directly a compilation unit. Since working copies
   are used to update units, a compilation unit should implicitly provide a
   built-in working copy used for the Java editor. In practice, a handle
   onto a compilation unit would remain the same whether it is reflecting a
   file or an editor contents.
   Other shared working copies should implicitly be aware of each other.
   For instance, when refactoring performs a change across several units at
   once, these modification must be visible to other refactored units:
   search, name resolution, etc... In particular, the built-in working
   copies associated with units should be aware of each other.

Proposal
   ICompilationUnit is enrished to support built-in working copy behavior,
   and thus working copy behavior is directly spec'ed there.
   A compilation unit handle reflects the filesystem until it is toggled
   into working mode (#becomeWorkingCopy()) and until it exits this mode
   (#discardWorkingCopy()).
   Other clients needing working copies would register for an operation
   relative to this specific client (WorkingCopyOwner). In order to
   register a client working copy owner, a WorkingCopyOwner#run(Runnable)
   action would be invoked, and for the duration of this operation, all
   subsequent working copies created by ICompilationUnit#getWorkingCopy()
   would be owned by this very client. These would automatically be aware
   of each other and for this very client only; i.e., during this client
   operation, its owned working copies would automatically take precedence
   over the underlying resource (even if already opened in editor).

   This is roughly what can be achieved today using shared working copies,
   but the notion of client is currently explicit and only a few APIs are
   able to support these shared working copies to achieve awareness (type
   hierarchy and search). With the notion of an implicitly registered
   client, all APIs would be untouched, and implicitely give precedence to
   this client specific working copies.

API implications for 2.1 clients
   Units open in editor would take precedence over the filesystem. This is
   likely the behavior they need anyway. Thus when navigating inside a unit
   element, they may now see unsaved changes.
   IWorkingCopy would be deleted, since no longer needed as a separate
   entity (no more gap).
   Shared working copies would be the default behavior. If needing more
   than one working copy on the same unit at once, then a different client
   should be registered. Thus the support for arbitrary individual working
   copies would disappear.

Example: Refactoring wants to rename a field declaration
   It performs a search for references to this field, and finds matches in
   term of true compilation units. Note that since these compilation units
   have built-in working copy support, these matches could reflect unsaved
   editor contents.
   Refactoring decides to update these references, and creates working
   copies for these so as to edit them.
   From thereon, all resolution actions would implicitly consider these
   refactoring working copies in place of the original units.
   However, if performing a further reference search outside these
   refactoring working copies, a regular unit handle would be returned, and
   it would need to be converted into a working copy again before being
   edited as the refactoring client.
   At any time, using IPackageFragment#getCompilationUnit would answer back
   the original unit (either associated file contents or editor contents).


Question/Answers
   How can I distinguish in between a filesystem unit versus an editor
   working copy ?
   The handle remains stable, but it can be asked whether it is a working
   copy or not (#isWorkingCopy).
   How can I get the contents of the original compilation unit, once it is
   open in editor ?
   Use resource API to read its contents.
   What happens if a unit opened in editor is modified on the filesystem ?
   Once a compilation unit is opened in editor, the editor changes will
   take precedence over the filesystem resource changes. In practice,
   unless listening to resource changes, there will no longer be a way to
   notice these, since the editor contents is implicitly hiding the file
   contents.
   Can client code be nested in each other ?
   Yes, registering a client would support nesting. Only the most specific
   client would be active at once.
   Is becomeWorkingCopy()/discardWorkingCopy() a good name for the
   activating the built-in working copy ?
   Unclear. Maybe it should rather clearly state that this is a reserved
   working copy for editors ? Suggestions are welcome.
   Would the builder see the unsaved editor contents through the built-in
   working copy support ?
   No, this would only be an artifact for the Java model tools (search,
   codeassist, formatter, dom, eval) which aren't used by the Java builder.