[java-gnome-hackers] a possible merge strategy

[Colin W. <wa...@ve...>]

Hi,

The introspection project
(http://live.gnome.org/GObjectIntrospection/) is getting pretty far
along now, and I wanted to talk in particular about my prototype Java
bindings (http://live.gnome.org/JGIR).

These bindings, while they share in common the terms "GNOME" and
"Java", have radically different approaches and therefore tradeoffs.
JGIR in particular goes for *completeness*.  There are multiple
aspects to this - one is having a largely autogenerated *public* API.
Another aspect is using JNA (https://jna.dev.java.net/) which gives
access directly to C structures.  Here's an example:

TextView tv = new TextView();
TextBuffer buf = tv.getBuffer();

TextIter iter = new TextIter();
buf.getStartIter(iter);
iter.forwardChars(5);
buf.insert(iter, "hello world", -1);

Note that TextIter is actually a C structure - the getStartIter takes
it by reference and modifies it, just like how it works in C.  Now,
arguably this could be an <out> parameter, and getStartIter() could
return it, but the current structure binding generalizes to multiple
arguments well enough.  I might later do an optimization around this
case, we'll see.

Another aspect of this is having automatic, useful coverage of a wide
variety of libraries not covered by java-gnome, such as the Clutter
library (http://clutter-project.org/) which uses structures like
ClutterColor.   You can see more examples here:
http://live.gnome.org/JGIR/SampleCode

What are the downsides versus java-gnome?  The main ones are that
there's no javadoc on the autogenerated part of the API, and that
there are no Cairo bindings (because Cairo isn't a GObject library).

The big picture here is that ideally, we can merge efforts and have
the best of both worlds - an autogenerated complete API useful to
platform hackers like me, and hand written custom bindings for tricky
things like GtkTreeView on top, and share binding code for things like
Cairo which aren't covered by introspection.

But let's take things step by step.  At the very first, one thing we
can do is say that for GTK+ one can use java-gnome as is today if it
has coverage you need.  For other libraries like Clutter, GStreamer,
libnotify etc., one can use JGIR.  It *should* be possible to combine
GTK+-using java-gnome with JGIR in the same process.

But the first fundamental piece that would need to be merged is the
GObject mapping layers.  In JGIR, GObject.java is actually written
entirely in Java, using JNA.  You can see this code here:
http://svn.gnome.org/svn/java-gobject-introspection/trunk/src/org/gnome/gir/gobject/GObject.java
To merge this we'll have to figure out also how the Cairo library
plugs in.  Should be relatively straightforward.

After that, I see two types of classes in java-gnome:
* Very straightforward wrappers for the underlying API
(AboutDialog.java, HBox.java)
* Custom classes (DataColumn.java)

For the first category, I think what we should do is write a script
which compares the JGIR API to the java-gnome API, and for classes
which are likely merge candidates (i.e. they have *exactly* the same
API) extract the java-gnome javadoc and put it into a forthcoming JGIR
"overrides" mechanism.  My plan is to take a transformation of the C
gtk-doc for the default javadoc, but java-gnome's javadoc could
override that.  Somewhat harder is to merge in custom Java override
methods, we can talk about that when we get there.

And for the custom classes, it should be relatively straightforward to
just rebase their internals on the JGIR if we can do the first part
right.