Today is the last day of GWT, and so I've put together a rather long post talking about several different things.
A brief recap of the project
The original project goals were to port GMF to the web, which is to say, to create a graphical, web-based diagram editor frontend that would interface with an EMF model living on the server on the backend. I had related experience in this domain, prior to this project, from my work as a researcher for the McGill University Modelling, Simulation, and Deisgn Lab. My research explored the development of modelled, web-based diagram editors, and included the the production of a prototype editor. My hope was that with Google Summer of Code would allow me to extend this work, such that it would be possible to build a web-based diagram editor that would interact with a full meta-modelling kernel (Ecore) hosted on a server. You may see my original project proposal here.
The project
proposal was informed by the fact that GMF was built on top of GEF (a
generic diagram editor library), and that GEF was built on top
of Draw2D (a graphical drawing library).
Looking back, I would say that this project has been divided up into about three phases:
- Trying to get code already checked into e4 to work. In this phase, we attempted to leverage an existing body of code checked into in the e4 repositories. This code attempted to port the SWT API to GWT, and thus would have made an appropriate foundation for implementing SWT/GC, SWT's low-level, immediate-mode graphics API, on top of the HTML5 Canvas API. Unfortunately, the result of this was that we spent 1.5 months simply trying to compile the existing code, without success. After this time we focused on starting from scratch in bringing Draw2D into web browsers.
- Trying to implement Draw2d on top of SWT/GC by using Java2Script. This was done because Java2Script provided good support for SWT, and was an alternative to GWT, which we had had trouble with in Phase 1. The result was that we found bugs in the Java2Script compiler, and had to return to GWT.
- Trying to implement Draw2d on top of SVG by using GWT. This was done because we wanted to use GWT, but decided it would be more productive to start a level higher in the SWT/Draw2d/GEF stack.
As you can see, we ended up trying many different strategies throughout this project, and therefore, the work that I am doing now is the third time I've started over from scratch. This may be understandable, given the experimental nature of the project and the methods by which were attempting to achieve the project's goals (using a Java-to-JavaScript cross-compiler, etc).
Overview of implementation details of Phase 3
We use an adapter pattern: each org.eclipse.draw2d.Figure class composes an handle object native to the environment, which is in this case an org.w3c.dom.svg.SVGElement instance. Then internally, the Figure's API is implemented in terms of this native DOM object. Here's a snippet that should clarify what this means:
public class Figure<T extends SVGElement> implements IFigure<T> {
//in this implementation, Figure is no longer lightweight
protected T handle;
public Figure(){
//create the handle
handle = (T) DOM.getDocument().createElementNS(SVGConstants.SVG_NAMESPACE_URI, SVGConstants.SVG_G_TAG);
}
...
}
There are three interesting things to note in the above snippet:
- Figure composes a handle of type <T extends SVGElement>. SVGElement is a subclass of org.w3c.Node and the parent class of all SVG elements.
- The type of handle can be further specified using Java 5 syntax. This is useful, because a Draw2d Rect shape may want the compose a SVGRectElement rather than a generic SVGElement. Adding a generic parameter to Figure is thus useful, and has the additional advantage of extending the API without breaking compatibility with existing code.
- Figure is not abstract, and may be instantiated to contain other Draw2d elements. It is therefore roughly analogous to the SVGGElement, and this is what is instantiated in the constructor using the statically exposed method DOM.getDocument() and standard SVG DOM API's.
Implementing Draw2d in terms of SVG is theoretically achievable because the Draw2d API is attempting to achieve roughly the same thing as the SVG DOM API, namely, providing a retained-mode graphics API.
Nevertheless, there are architectural and conceptual differences between the two. Here are few that I've noticed:
- SVG lacks a concept of connectors and layout, which Draw2d has.
- Draw2d provides access to an immediate-mode API to its Figures through the Graphics object. SVG does not provide access to such an API
- In many Draw2d examples, it is common to see a class inheriting from Figure. While it might be sometimes possible to do the same thing in SVG, it is more common to see composition used, rather than inheritance.
- SVG hides paint events from its user. In Draw2d, you can force a manual refresh of the scene graph.
- Draw2d allows fine control over updates in the scene graph, while SVG will in general always update its scene graph synchronously, whenever you change a value in DOM.
It's also worth noting that, by implementing Draw2d in terms of SVG, the org.eclipse.draw2d.LightweightSystem class is no longer really a Lightweight System, as it's composing a System-native handle, which, among other things, can handle its own event dispatching. This means that, rather than having events be dispatched through a single source, the LightweightSystem, inner DOM node handles should instead be connected to the proper interfaces on their host Figure when the Figures are instantiated.
Figures will also have to handle tearing down the DOM node when they are destroyed.
What has been implemented
Everything required to get org.eclipse.draw2d.HelloWorld to work. Here's a snippet that should illustrate this:
public static void main(String[] args) {
Display d = new Display();
Shell shell = new Shell(d);
shell.setLayout(new FillLayout());
FigureCanvas canvas = new FigureCanvas(shell);
canvas.setContents(new Label("Hello World"));
shell.setText("draw2d");
shell.open();
while (!shell.isDisposed())
while (!d.readAndDispatch())
d.sleep();
}
- GWT-compatible classes have been created for Display, Shell, FigureCanvas, and Label.
- Instantiation of SWT objects, passing parents into the constructor should work in general, as occurs with Shell and FigureCanvas classes. The rest of the SWT API has been stubbed out.
- The Figure class and some subclasses, including Label and Rectangle have been created. The API has been completely stubbed out and partially implemented.
- The class will create JavaScript code which, when included in an XHTML document, will create a new HTMLDivElement, SVGSVGElement, and SVGTextElement, which will display "Hello World" on the page.
What has not been implemented
Everything else, notably:
- Most subclasses of Figure lack implementations.
- Most methods of Figure superclass lack implementations.
- Connectors
- Layout
- Colors
- Fonts
- Event Handling
- There are still holes in the gwt-svg library, the library that exposes native SVG and HTML DOM to GWT:
- not every SVGElement has an implementation.
- even those that do, not every element is properly wrapped in SVGElementImpl.wrapElement. So if you're getting ClassCastExceptions, check to make sure that your element is properly handled in SVGElementImpl.wrapElement
- The whole business of wrapping Elements should probably be cleaned up a bit. It's currently quite spread out and a bit confusing. Was already a bit crufty when I started using gwt-dom.
Most recent dev experience
General Approach
So the goal of Phase 3 was to implement the Draw2d API in terms of the SVG DOM API by way of GWT.
I worked very conservatively, only merging in code that I felt I understood quite well, and would not break the compiler. In that way, I was able to avoid most of the mysterious compiler errors that had occurred for me in Phase 1 of the project.
Problems with SVG Embedding and the SWT API
I did run into a few interesting problems that are worth talking about. Let me set up the problem like this:
- Since GWT 1.4, GWT out of the box does not support XHTML or SVG (XML) documents. It only support HTML4 in quirks mode and standards mode.
- SVG can be viewed by a web browser in the following ways:
- As a plain SVG document (image/svg+xml mimetype, usually with a .svg extension).
- Included in an (X)HTML document in the following ways:
- Inline in an XHTML document, in which the SVGSVGElement root element is loaded synchronously with the rest of the page.
- Embedded via the object, embed or iframe tags in an XHTML or XML document in which the SVGSVGElement in the embedded SVGDocument is loaded asynchronously, independent of the rest of the page. Basically, to get the SVGSVGRootElement, you need to set a LoadListener, otherwise, the internal contentDocument will simply be null. In general, listening to load events like this is quite common in web programming, and usually not problematic, but you will see that this did cause a problem of competing requirements...
- The SWT API requires widgets to be instantiated synchronously. The reason for this is simply that the method calls are synchronous, so for example, new FigureCanvas(shell), does not take a callback.
This system cannot be solved. 1 blocks 2.1 and 2.2.1. On the other hand, 3 blocks 2.2.2. I actually had been using option 2.2.2, with an object tag and the SVG document encoded in a data URI, and I had a first implementation of basic SWT support that used this, and tried to do some tricky things involving managing widgets' internal state and setting callbacks in order to fake some kind of synchronicity, but it clearly was not going to scale, and I felt that that was not the place spend my effort. So, basically, I had to change one of the assumptions, and the one I decided to change was GWT. This meant going into the GWT core and figuring out what it was doing to break XHTML support. I found most of these answers here and here, and it basically has to do with the fact that they're using document.write and document.body in the module loading code, neither of which are supported in XHTML DOM. Rather than go into the GWT core to change this, I just fixed it once by hand, and then wrote a little patch which I ran each time I compiled. Here's the patch, which you can see is not very much:
45c45,47
< $doc_0.write('<script id="' + markerId + '"><\/script>');
---
> var scriptElement = document.createElement("script");
> scriptElement.setAttribute("id",markerId);
> document.getElementsByTagName('head')[0].appendChild(scriptElement);
48c50
< while (thisScript && thisScript.tagName != 'SCRIPT') {
---
> while (thisScript && thisScript.tagName.toUpperCase() != 'SCRIPT') {
167c169
< $doc_0.body.appendChild(iframe);
---
> document.getElementsByTagName('body')[0].appendChild(iframe);
286c288,291
< $doc_0.write('>script defer="defer">org_eclipse_draw2d_e4_examples.onInjectionDone(\'org_eclipse_draw2d_e4_examples\')<\/script>');
---
> var scriptElement = document.createElement("script");
> scriptElement.setAttribute("defer","defer");
> scriptElement.text = "org_eclipse_draw2d_e4_examples.onInjectionDone('org_eclipse_draw2d_e4_examples')";
> document.getElementsByTagName('head')[0].appendChild(scriptElement);
Now, I highly suspect that there would be problems using GWT's widget library in the XHTML document context, as they're probably using innerHTML. But for the purposes of getting basic GWT's module loading and DOM API up and running, this small patch was perfectly sufficient. I would be very happy to see it get integrated into the GWT core, and get pushed upstream, and I imagine a lot of SVG developers would be as well.
Hacking on SWT API's confuses GWT
There was another issue involving GWT, namely that hacking on API's in the SWT namespace seems to confuse it a lot. When I attempted to launch Hosted mode, it complained about missing methods in some SWT classes. Those methods were missing in my emulated SWT classes. In any case, this meant that I couldn't use GWT Hosted mode, and hence did all of my debugging on the generated JavaScript code in Firefox and Firebug. This was challenging at first, but became easier as I became better acquainted with the kind of code GWT produces, and the most common errors I could run into.
Zero-Argument Constructors on Figures
In my implementation of Draw2d, every Figure is supposed to wrap a <T extends SVGElement>. The only way to create new SVG Elements is to use the Document factory. What I would have preferred to do was use dependency injection, and pass in the handle to a new DOM node to each new Figure in the constructor. Unfortunately, the Figure API only has a zero-argument constructor, and it was thus not possible to achieve this without changing the API. My solution to this was somewhat evil, which was to simply use a "global variable", namely, the statically exposed DOM.getDocument() method to obtain the document factory inside of the constructor. This is similar to what you might see in pure javascript, though (the document is a global variable), so I think it's not so bad.
Considerations about future work
GWT vs. Java2Script
My experiences with GWT in Phase 1 were not very favorable. After spending 1.5 months, I was still not able to get the code already checked into e4 to compile.
After that experience, I found that it was much easier to get set up with Java2Script. It compiled all of my Java code to JavaScript transparently, and without complaint. I found that it had excellent integration with Eclipse, especially with regard to building my code (it's actually hooked into the incremental compiler that comes with JDT!). This spared me the constant edit-compile-debug cycle one experiences with GWT. This was very refreshing.
However, while compiling a large body of Java code to JavaScript was very easy with Java2Script, I found I was running headlong into bugs in the Java2Script compiler. It would throw runtime errors in the core lib which were highly time consuming for me to debug.
I also wasn't very favorably disposed to the way Java2Script handled native JavaScript embedding, versus GWT's JSNI. Java2Script uses scriptdoc annotations before empty braces, with JavaScript being put in the comments. Compared to GWT's JSNI, was very easy to set up and use, and, while not perfect, I felt that it much easier to read than JSNI.
Unfortunately, there are two problems with Java2Script's method of native JavaScript injection versus JSNI. First, I feel it encouraged poor coding practices, as, rather than necessarily having native JS separated nicely out into its own method, where it is clearly marked as native and encapsulated, you instead find JavaScript code mixed intermittently with the Java code. For example, see the Java2Script implementation of org.eclipse.swt.widgets.Display. I find this method of programming very difficult to understand, and not very maintainable. The second reasons that I preferred JSNI is that the very awkward, ugly constructions used to preserve type information in JSNI actually serve a useful purpose, in that the compiler is able to do more useful checks at compile-time to prevent run-time bugs. It's also important for the way GWT optimizes the generated JavaScript code.
My mentor and I decided we needed a rock-solid cross-compiler, and for that reason elected to revisit GWT, this time moving one layer up the stack, focusing directly on Draw2d rather than SWT. With regard to my initial difficulties, when I adopted a more conservative approach in Phase 3, I did not have any trouble compiling a fairly complex project that leveraged an existing body of Java code. Also, I have yet to experience any compiler bugs in GWT.
Also, GWT should theoretically create code that loads and runs faster than Java2Script. However, with this gain in speed, you lose some flexibility, namely that dynamic class loading in GWT (class.forName) impossible. Dynamic class loaing is very possible in Java2Script. Other forms of reflection should be possible in both GWT and Java2Script.
An optimal middle-ground may be to take Java2Script's SWT implementation and port it to GWT. This would be very challenging, though, I think primarily because of the use of native JavaScript code inlining that I mentioned above.
SVG vs. Canvas
The approach we took in Phase 2 was to implement one immediate-mode Graphics API in terms of another: SWT GC on top of HTML Canvas. As we suspected, synchronizing these API's was not very difficult, and I experienced some success with that, as you may see in the demo here.
One difficulty with this approach, however, was that a common pattern in SWT is to attach a PaintListener to a Drawable (usually a Canvas), and and then put your your drawing logic there. HTML Canvas does not give you native paint events, so this would need to be somehow emulated. I moved onto Phase 3 before I resolved this.
Draw2d and SVG, on the other hand, both have much bigger API's, and are conceptually different from one-another in many ways. It is significantly more challenging to implement one API in terms of the other, and ensure that they have identical semantics.
Still a retained mode API is a necessary part of the stack we are trying to build, and the only question is, what is the best way to get there. I believe that one consideration that works in SVG's favor is speed. All things being equal, given an implementation of a retained-mode API in C++ vs. one in pure JavaScript (albeit highly optimized using GWT), it seems likely that the C++ implementation would be faster. Perhaps not, though... perhaps a lightweight system, with a single event handler and dispatcher (like org.eclipse.draw2d.LightweightSystem), would be faster than the slow DOM with all of event listeners. This is worth investigating.
Where is this being hosted?
Here: https://eclipse-gwf.svn.sourceforge.net/svnroot/eclipse-gwf/p3/
Right now you need a few libraries that are not included in that repo. I have a releng project which is almost done which I'm planning to commit soon, and I will also post explicit build instructions later.
I'm going to put some compiled examples up on my personal page as well.
Good project. I hope I have the opportunity to do more with it in the future.
No comments:
Post a Comment