The secret behind OutlineView in Eclipse - Delta

(All is under the scope of JAVA, the provided example is applied in plugin development)

Everyone uses eclipse must know what is OutlineView. If you could not find it, choose "Window->show view->outline". This view shows the skeleton of the currently opened java file. The most interesting thing is not what it shows, but the synchronization functionality. How the view reflect what you are editing so fast? Activate the outline view, press "shift+alt+F1", wow! a plugin-spy appears. Let's choose the JavaOutlinePage and continue our adventure.

 

From our experience, we could know

1. Caculating this change is much lighter than buiding a full model; Otherwise, the view won't change simultaneously.

2. The synchronzation is triggered by some kind of event. Because everytime you stop typing for some seconds, then the view start to change. Lucky we, we can find a "ElementChangedListener" at the top of body. It sounds like what we are looking for and actually it is. 

 

public void elementChanged(final ElementChangedEvent e) { ...... IJavaElementDelta delta= findElement(base, e.getDelta()); if (delta != null && fOutlineViewer != null) { fOutlineViewer.reconcile(delta); } }

 

This listener caputres a "ElementChangedEvent", and extract a "delta" from the event by the code "e.getDelta()". This delta is the key for the secret.

 

In math, delta means difference. It stands for the distance between two discrete points. Here, delta is the changes between two versions of code. Let me give you a intuition that what it looks like. Add the following code fragment.

 

JavaCore.addElementChangedListener(new IElementChangedListener() { @Override public void elementChanged(ElementChangedEvent event) { IJavaElementDelta delta = event.getDelta(); System.out.println(delta); } });

 

During the runtime, I change a function name from "getZero" to "getZer". Then I see such infomation in console

 

[Working copy] T.java[*]: {CHILDREN | FINE GRAINED | AST AFFECTED}
 T[*]: {CHILDREN | FINE GRAINED}
  getZer()[+]: {}
  getZero()[-]: {}

 

It tells what has been changed in the previous version. From top to bottom, it's a path of changes. "T.java" is a file, "T" is the class in "T.java", then "getZer()" is added and "getZero()" is deleted which can be read from "[+]" and "[-]". Then let's see what is delta and how it is created?

 

The type of delta is "JavaElementDelta ", it extends SimpleDelta and implements IJavaElementDelta . From the constructor

 public JavaElementDelta(IJavaElement element) { this.changedElement = element; }

we could assume it's nothing but a decorator of IJavaElement . Acctually, JavaElementDelta is "changed IJavaElement".

 

To build a "JavaElementDelta"[code ], we have to use "JavaElementDeltaBuilder"[code ], I spent several days reading it and finally had a clear view of the approximate work flow.

1. Old JavaElement information is recorded in Map infos. Start to find addtions.

2. Read the current code, if corresponding element exists in infos , that means this element is not changed. Then delete the element from Map. If it doesn't exist, that means it's a new element and a delta should be created.

3. During the creation of delta, actually it's a delta tree. The process traces back and records all its parents. Then wrap every JavaElement into JavaElementDelta and insert it into some appropriate place in the tree.

4. Find additions is finised and start to find deletions. All elements left in infos are deleted from the orignal code.

5. If a deleted element is found, a new delta should be inserted to the current delta tree. The place where it should be added is where it existed (which is its dierct parent).

6. Checking position ordering changes.

 

This is how the delta is created. Actually, it's a descriptive information showing changes. The OutlineView apply this delta by "reconcile(delta)", old model changes accordingly so new one doesn't need to be created fully.

 

But somehow, deleting a letter inside the method body could not be sensed by delta. For answering this question, I'll introduce JavaElement in the next article. Briefly speaking, as I said, delta is a changed Java element. If the change is not Java element, of course it couldn't be a delta.