[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
[jdt-core-dev] 36888 - closing the gap between compilation units and working copies
|
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.