For our work on the C++ Refactoring in Eclipse CDT we created some helper classes. We thought it would be nice to document this helper classes in a way that it is browsable and searchable. The best would be to generate a wiki entry in our trac using the javadoc. Because then the documentation is directly in the source and not in a separate file and the advantage with the wiki should be obvious.
To extract the needed information out of the Java source code I wrote my own Doclet. This was not a big problem in contrary to editing the trac wiki.
Here are a few things you should pay attention to if you want use the Trac XML-RPC with Java:
Before starting you need to install the Trac XML-RPC Plugin. We had already done this to use Mylyn. After installing the plugin you should check if it works and make sure that you use the accurate url. You can do this by navigating to http://your.domain/xmlrpc or with authentication to http://your.domain/login/xmlrpc. You should see the “XML-RPC exported functions” site. Now you are ready to start!
I started with fetching all the needed libraries.
There are different vendors which provide libraries for XML-RPC. I use the own from apache.
To use the Trac XML-RPC Plugin the easiest way is to use the provided java library.
The next thing you should do is to create a user explicitly for this purpose and give him the needed privileges. Additionally you have to set the XML_RPC privilege. For a detailed view which privileges are needed look on your XML-RPC exported functions site.
After that let us have a look at the code. (Hint: I removed the exception handling)
This Code consists mainly of two parts. The first part where the connection is established over XML-RPC and the second part where the interaction with the Trac happens. I think that the first part is self explanatory. Therefore let us move on to the second part.
TrackerDynamicProxy tdp = new TrackerDynamicProxy(client);
Wiki wiki = (Wiki)tdp.newInstance(Wiki.class);
To add or change something in the wiki you need the correspondent object. This can be fetched over the TrackerDynamicProxy.
Hashtable h = new Hashtable();
wiki.putPage("MyWikiSite", "Hello World!", h);
From there it is quite easy. Just use the wiki object for all the modifications.
The Hashtable h can be used to set PageInformations which can be fetched again with wiki.getPageInfo(). But because we only need to write the page we won’t store any additional information with it.
Problems?
Following I will give you two hints which might help you.
- An exception will occur if you try to write the same page content into the wiki which already exists. This exception will look somewhat like:
Caused by: org.apache.xmlrpc.XmlRpcException: 'Page not modified' while executing 'wiki.putPage()'
- Another really strange problem I experienced was with the authenticated access. My first approach was to put the user and password into the url (username:password@url) as common on the internet .
conf.setServerURL(new URL("http://username:password@your.domain/login/xmlrpc"));
But that did not work and I do not have a clue why?
The only way it work was as shown above. By setting the user and password separately from the url.
conf.setBasicUserName("username");
conf.setBasicPassword("password");
conf.setServerURL(new URL("http://your.domain/login/xmlrpc"));
