[xwiki-devs] [XEclipse] Design improvements discussion

[Fabio Mancinelli]

Dear all,

I am starting to take a deeper look at XEclipse and I think there are  
some improvements at the design level that, IMHO, are worth to be  
taken into account.
These improvements leverage Eclipse platform's features that, to some  
extent, have been re-implemented in XEclipse.

1) Deferred tree content managers.
I am a big fan of this feature and I tend to use it whenever I can.
Basically a deferred tree content manager allows you to "fetch" tree  
children in a deferred way.
One example is the "SVN Repository" or "CVS Repository" views in your  
Eclipse IDE. When you expand a node it displays a "Pending..." element
and, when the fetching job is over, the actual elements (i.e., files  
and directories available on the repository) are displayed.

The same mechanism could be used in XEclipse to fetch Spaces and Pages.

The good thing about this approach is that the manager takes care of  
everything:
* A tree node that is collapsed before the fetching job is terminated  
deletes the corresponding job;
* Changing the input element of the tree invalidates all the active jobs
* You can expand different tree nodes without waiting that the  
previous ones terminate their fetching job: in this case you will  
have several "Pending..." indicators in the tree.

You can play a bit with the "SVN Repository" view and see what I mean.
The best news is that all of this already implemented and available  
in the eclipse platform through the DeferredTreeContentManager[1] class.

Using the deferred tree content fetching mechanism eliminates the  
need of having additional logic in XWikiSpace for understanding when  
pages are ready (i.e., all the code that manages isPagesReady in  
XWikiSpace.java). You will simply have a method getPages that could  
take possibly forever and that directly fetches the pages from the  
XMLRPC source (or from the offline cache).

I think that this will also have impact on the Decorators that are  
used to wrap XWiki* elements in order to provide a visual feedback on  
what's going on (i.e., all the GuiUtils.runOperationWithProgress will  
be unnecessary since the deferred tree content manager will take care  
of everything)


2) Adapters
I noticed that there is a TreeAdapter interface that basically is  
used for providing labels, children and so on.
All classes that can be "displayed" in a tree implements this  
interface (i.e., XWikiConnection, XWikiPage, XWikiSpace).

I think that this "pollutes" the model because, for example, getPages  
and getTreeChildren basically return the same thing and, therefore,  
are duplicated methods. Moreover in this way you put "GUI"-oriented  
stuff in the model and this is not good.

The Eclipse platform has a mechanism for providing adapters that are  
able to give information about model elements to GUI components[2].
Not surprisingly they are called Adapters and are handled via  
extension points. Basically you register an AdapterFactory that  
provides IWorkbenchAdapters.
An IWorkbenchAdapter[3] actually contains what was declared in  
XEclipse TreeAdapter.

When you need structural information about an object, you can then  
query the platform for an adapter that matches a given interface and  
is suitable for a given object. In our case I can register an adapter  
for XWikiSpace that implements the getChildren method and that will  
simply call the getPages method of the XWikiSpace model object.

In this way I can clearly separate the "GUI" code from the "model"  
code and leave Eclipse handle the rest.

It is worth to notice that many GUI content providers directly  
support IWorkbenchAdapters out of the box, so if you carefully write  
your model adapters you will never have to write a content/label  
provider; but even when you write your own content provider you can  
always put a lookup to the adapter and then talk to it for getting  
the information to display (this is actually a standard practice).

In the attachment you can find a sample implementation of the  
"deferred tree" way of displaying the XWiki navigator that makes use  
of adapters.
Notice the getChildren methods in XWikiSpaceAdapter (declared in  
AdapterFactory.java). It calls a method myGetPages that I've added  
for testing purposes to the IXWikiSpace interface and that basically  
does the following straight simple thing:

public Collection<IXWikiPage> myGetPages() throws  
ConfluenceException, SwizzleConfluenceException {
   Confluence rpc = getConnection().getRpcProxy();
   String spaceKey = getKey();
   List<Object> pages = rpc.getPages(spaceKey);
   List<IXWikiPage> result = new ArrayList<IXWikiPage>();
   for (int i = 0; i < pages.size(); i++) {
     PageSummary pageSummary = (PageSummary) pages.get(i);
     XWikiPage xWikiPage = new XWikiPage(this, pageSummary);
     result.add(xWikiPage);
   }

   return result;
}


Of course this is a proposal to discuss about.
But I think that we should spend some time on it because we could end  
up with a lighter design and a more maintainable product.

WDYT?

Cheers,
Fabio

[1] http://help.eclipse.org/help33/index.jsp?topic=/ 
org.eclipse.platform.doc.isv/reference/api/org/eclipse/ui/progress/ 
DeferredTreeContentManager.html
[2] Of course the adapters mechanism is not limited to GUI components  
but can be used to adapt an object to whatever interface we need to.
[3] http://help.eclipse.org/help33/index.jsp?topic=/ 
org.eclipse.platform.doc.isv/reference/api/org/eclipse/ui/model/ 
IWorkbenchAdapter.html

-------------- next part --------------
A non-text attachment was scrubbed...
Name: classes.tar.gz
Type: application/x-gzip
Size: 1654 bytes
Desc: not available
Url : http://lists.xwiki.org/pipermail/devs/attachments/20071010/276ea6c7/attachment-0001.bin 
-------------- next part --------------

These are the XML lines in plugin.xml that defines the  
org.eclipse.core.runtime.adapters extension point for registering the  
AdapterFactory and types:

<extension point="org.eclipse.core.runtime.adapters">
   <factory
      adaptableType="org.xwiki.plugins.eclipse.model.IXWikiConnection"
      class="fm.AdapterFactory">
     <adapter  
type="org.eclipse.ui.progress.IDeferredWorkbenchAdapter"></adapter>
   </factory>
   <factory
      adaptableType="org.xwiki.plugins.eclipse.model.IXWikiSpace"
      class="fm.AdapterFactory">
     <adapter  
type="org.eclipse.ui.progress.IDeferredWorkbenchAdapter"></adapter>
   </factory>
</extension>