New subject: [xwiki-dev] Proposal: XML-RPC API - True Interoperability with Confluence

9 Aug 2007

Hello,

We have decided to implement the Confluence Remote API because the
interoperability would bring many advantages to XWiki (as Vincent
explained here http://tinyurl.com/ypfamt). However at this moment the
XWiki implementation of this API is not yet interoperable with
Confluence. And this is not only because we are implementing only a
very small subset of the API, but more important because nobody ever
checked that we are in fact behaving similarly.

The goal should be to write clients that are able to run against XWiki
or Confluence servers without being able to tell any difference. At
this moment this is not the case and there are many reasons for this.

One reason is that we are currently relying on dynamic proxies in our
client code (http://ws.apache.org/xmlrpc/advanced.html). In this
setting the client and the server have to use the same Java interface,
namely com.xpn.xwiki.xmlrpc.ConfluenceRpcInterface. And no, there is
absolutely no chance to convince the Confluence team to implement this
XWiki-specific interface.

One way around this is to write client code which does not use dynamic
proxies, but that is tedious and error prone (e.g. you can pass as
many agruments as you like and you can call methods that don't exist).
Remote calls look like this:
token = (String)rpc.execute("confluence1.login", new Object[] {token,
username, password});

There is however a better option, and that is to use
swizzle-confluence, a client proxy for the confluence XML-RPC API
(http://docs.codehaus.org/display/SWIZZLE). This would offer all the
advantages of calling a typed proxy. Still all calls would eventually
look like the one above, so they could go to any server that
implements the interface (whether it's XWiki or Confluence). There are
many other advantages: swizzle is intuitive, well-documented,
well-tested and makes it unnecessary to explicitly pass a token
around.

Switching to swizzle would mean that all our client code would need to
be modified. I already started to convert our tests to swizzle and it
seems an easy task. Setup is a lot easier than before. Compare this:
XmlRpcClientConfigImpl clientConfig = new XmlRpcClientConfigImpl();
clientConfig.setServerURL(new URL("http://127.0.0.1:8080/xwiki/xmlrpc"));
XmlRpcClient rpcClient = new XmlRpcClient();
rpcClient.setConfig(clientConfig);
ClientFactory factory = new ClientFactory(rpcClient);
xwikiRpc = (ConfluenceRpcInterface)factory.newInstance(ConfluenceRpcInterface.class);

to this
Confluence rpc = new Confluence("http://127.0.0.1:8080/xwiki/xmlrpc");

And using swizzle for the tests will allow not only to test the xwiki
implementation, but to validate that we are testing the right behavior
by running the tests against a confluence instance (this can be done
once when designing the test, not all the time).

Using swizzle is however not enough. Additionally we need to ensure
that the observable  behavior of XWiki matches that of Confluence. For
example we will need to adjust the way we deal with page modifications
and histories to the way Confluence does it. And we will need to
mirror even strange behavior in Confluence. For example we will need
to convert all non-string primitive values (e.g int, Date) into
strings in the maps and lists that get exchanged between the client
and server. Even if this is strange, this is how Confluence does it
and this is how clients (like the ones using swizzle) expect their
results.

I'm already working on these modifications and if everybody agrees
they will make it into the trunk after the M4 release. The easiest way
to adapt clients to these changes will be to make them use swizzle.

Regards,
Catalin