XML-RPC Java Examples

Version 1.6 by dilipkumarj on 2010/01/30 04:18
Contents

Requirements

The following libraries should be added to your application classpath:

Most of the libraries can be easily found in the WEB-INF/lib folder of your XWiki instance. As mentioned at XMLRPC, version numbers of these libraries for the most part are irrelevant. In the examples listed here, XWiki version 2.1.1 is used.

LibrarySource
commons-logging-1.1.1.jarWEB-INF/lib folder of XWiki 2.1.1
ws-commons-util-1.0.2.jarWEB-INF/lib folder of XWiki 2.1.1
xmlrpc-common-3.1.jarWEB-INF/lib folder of XWiki 2.1.1
xmlrpc-client-3.1.jarWEB-INF/lib folder of XWiki 2.1.1
xwiki-core-2.1.1.jarWEB-INF/lib folder of XWiki 2.1.1
swizzle-confluence-1.2-20080419-xwiki.jarWEB-INF/lib folder of XWiki 2.1.1
xwiki-core-xmlrpc-client-2.1.1.jarFor XWiki 2.1.1 the jar is available here
xwiki-core-xmlrpc-model-2.1.1.jarWEB-INF/lib folder of XWiki 2.1.1

Authentication: Login Example

Try Providing an incorrect username & password. The application will throw an exception
For correct username & password, the application will compile & run successfully.

import java.net.MalformedURLException;
import org.apache.xmlrpc.XmlRpcException;
import org.xwiki.xmlrpc.XWikiXmlRpcClient;
public class XmlRpcLogin {
   public static void main(String[] args) throws MalformedURLException{

       //URL of the xwiki instance
        String url="http://localhost:8080/xwiki/xmlrpc/confluence";

       //Replace user & pass with desired xwiki username & password
        String user="Admin";
        String pass="admin";

       //Perform Login & Authentication using above url address
        try{
        XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
        rpc.login(user, pass);

       }
       catch(XmlRpcException e){
            System.out.println("invalid username/password was specified or communication problem");
       }
   }
}

Authentication: Logout Example

Let's build on the previous example where we "Logged In". We test logout action using a boolean variable since rpc.logout() method returns true on successful logout.


import java.net.MalformedURLException;
import org.apache.xmlrpc.XmlRpcException;
import org.xwiki.xmlrpc.XWikiXmlRpcClient;
public class XmlRpcLogout {
   public static void main(String[] args) throws MalformedURLException{

       //Variable to test whether user logged out successfully. Default set to false
         boolean loggedOut=false;

       //URL of the xwiki instance
        String url="http://localhost:8080/xwiki/xmlrpc/confluence";

       //Replace user & pass with desired xwiki username & password
        String user="Admin";
        String pass="admin";
       
       try{
      //Perform Login & Authentication using above url address
        XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
        rpc.login(user, pass);
      
       //Log out action. Returns true if user successfully logged out
        loggedOut=rpc.logout();
        System.out.println(loggedOut);
       }
       catch(XmlRpcException e){
            System.out.println("invalid username/password was specified or communication problem");
       }
   }
}

Search documents

import java.net.MalformedURLException;
import java.util.List;
import org.apache.xmlrpc.XmlRpcException;
import org.codehaus.swizzle.confluence.SearchResult;
import org.xwiki.xmlrpc.XWikiXmlRpcClient;

public class XWikiXMLRPCSearch {

   public static void main(String[] args) throws MalformedURLException, XmlRpcException {
       //Replace the url with your xwiki server address
        String url = "http://localhost:8080/xwiki/xmlrpc/confluence";

       //Replace user & pass with desired xwiki username & password
        String user = "Admin";
        String pass = "admin";
       
       //Perform Login & Authentication using above url address
        XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
        rpc.login(user, pass);

       //Replace string to search in the rpc.search() method below
        //Specify the number of results to be returned in rpc.search() as 5
        List<SearchResult> result = rpc.search("text I want to search", 5);


       //Print obtained results to console if result is not empty
        if (result.size() != 0) {
           for (int i = 0; i < result.size(); i++) {
                System.out.println(result.get(i).getTitle());
           }
       } //Print standard message if result is empty
        else {
            System.out.println("No Results To Display");
       }
   }
}

Space: Get A List Of Spaces

Now, that we can log in and log out, let's move to finding out what's inside your wiki. How about a list of all the spaces inside the wiki. Compare the above two examples and you will see the new import that we added viz. the SpaceSummary class. 


import java.net.MalformedURLException;
import java.util.List;
import org.apache.xmlrpc.XmlRpcException;
import org.codehaus.swizzle.confluence.SpaceSummary;
import org.xwiki.xmlrpc.XWikiXmlRpcClient;
public class SpaceList {

   public static void main(String[] args) throws MalformedURLException {
        //URL of the xwiki instance
        String url="http://localhost:8080/xwiki/xmlrpc/confluence";

       //Replace user & pass with desired xwiki username & password
        String user="Admin";
        String pass="admin";

       //Perform Login & Authentication using above url address
        try{
        XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
        rpc.login(user, pass);

            List<SpaceSummary> spaceList = rpc.getSpaces();
            System.out.println("Total Number of Spaces: " +spaceList.size());
           for(int i=0;i<spaceList.size();i++){
                System.out.println(spaceList.get(i).getKey());
           }
        rpc.logout();
       }
       catch(XmlRpcException e){
            System.out.println("invalid username/password was specified or communication problem");
       }
   }
}

Space: Create A Space

So far, we logged in, logged out & also were able to see a list of spaces in the xwiki instance. Let's go ahead and create a new space. And not just that we will also assign the default home page for the space. In this example, we use "XMLRPC" as the space name & "xmlrpc.WebHome" as the home page

import java.net.MalformedURLException;
import org.apache.xmlrpc.XmlRpcException;
import org.codehaus.swizzle.confluence.Space;
import org.xwiki.xmlrpc.XWikiXmlRpcClient;

public class CreateSpace {

   public static void main(String[] args) throws MalformedURLException {
       //URL of the xwiki instance
        String url = "http://localhost:8080/xwiki/xmlrpc/confluence";

       //Replace user & pass with desired xwiki username & password
        String user = "Admin";
        String pass = "admin";

       //Perform Login & Authentication using above url address
        try {
            XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
            rpc.login(user, pass);

           //Create a Space object which holds the Key, Homepage, Name & description.
            //Key is visible name for the space
            Space space = new Space();
            space.setKey("XMLRPC");
            space.setHomepage("xmlrpc.WebHome");
            space.setName("xmlrpc");
            space.setDescription("Demo Space Created To Test XMLRPC");

           //One simple method adds the space created to your xwiki instance
            rpc.addSpace(space);

            rpc.logout();
       } catch (XmlRpcException e) {
            System.out.println("invalid username/password was specified or communication problem");
       }
   }
}

Space: Delete A Space

Removal of a space is far more easier than creating one. All it requires is the "Key" (the visible name of the space) to be provided to the remove() method.

Please note that deletion of space removes all pages in the space too. It is recommended to always make sure that the space is empty before deleting it.


import java.net.MalformedURLException;
import org.apache.xmlrpc.XmlRpcException;
import org.codehaus.swizzle.confluence.Space;
import org.xwiki.xmlrpc.XWikiXmlRpcClient;

public class DeleteSpace {

   public static void main(String[] args) throws MalformedURLException {
       //URL of the xwiki instance
        String url = "http://localhost:8080/xwiki/xmlrpc/confluence";

       //Replace user & pass with desired xwiki username & password
        String user = "Admin";
        String pass = "admin";

       //Perform Login & Authentication using above url address
        try {
            XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
            rpc.login(user, pass);

           //Delete the space which is reference by "XMLRPC" key
            rpc.removeSpace("XMLRPC");

            rpc.logout();
       } catch (XmlRpcException e) {
            System.out.println("invalid username/password was specified or communication problem");
       }
   }
}

Page: Retrieve/Search A Page

A page is probably the most important unit of any wiki around which everything else is built. Spaces/Categories, Attachments, Comments, etc are more or less meaningless without a supporting page in a wiki system.
One of the most widely performed action on any wiki has to be searching for pages. Searches may happen through search boxes provided in a wiki or may be through following links from one page to another. On the XMLRPC side too, searching pages has been given a lot of importance and quite a few methods are available for the same.
Since, this topic is an important one, all the page retrieval/search examples can be found here

Page: Create A Page

Now for the moment of truth. Addition of Pages to a Wiki is as simple as searching for them. Thankfully, the XWiki XMLRPC api has just the tools you need to do your job.
At the very least, you would require the following three parameters to create a Page:

  1. Space - The Space where the Page is to be stored
  2. Title - The title for the Page
  3. Content - The content to be displayed inside the Page

Please beware that using a title for an existing Page will overwrite all the contents of that Page. Make sure no Page *with the same title* exists in the same Space before you attempt to use the create Page functionality of XMLRPC.

In our example below, we would use

ParameterValue
Spacedemo code
titleNew Page
ContentNew Page Created
This is XMLRPC Test
import java.net.MalformedURLException;
import org.apache.xmlrpc.XmlRpcException;
import org.codehaus.swizzle.confluence.Page;
import org.xwiki.xmlrpc.XWikiXmlRpcClient;

public class CreatePage {

   public static void main(String[] args) throws MalformedURLException, XmlRpcException {

           //URL of the xwiki instance
        String url = "http://localhost:8080/xwiki/xmlrpc/confluence";

       //Replace user & pass with desired xwiki username & password
        String user = "Admin";
        String pass = "admin";


        XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
       try {

           //Perform Login & Authentication
            rpc.login(user, pass);

           //Create a Page object & set it's three important attributes viz. Space, Title, Content
            //Observe how the \\\\ has been used to create a new line in the final wiki Page
            //Also, XWiki syntax can be passed as it is. Here, we passed the info macro
            //The info macro would get rendered an info box in the Page
            Page page = new Page();
            page.setSpace("demo code");
            page.setTitle("New Page");
            page.setContent("New Page Created \\\\ {{info}}This is XMLRPC Test{{/info}}");

           //Also set the parent Page to "demo code.WebHome" so that the "New Page" we created is not
            //an orphan Page
            page.setParentId("demo code.WebHome");


           //Store the page object into XWiki
            rpc.storePage(page);


       } catch (XmlRpcException e) {
            System.out.println("invalid username/password was specified or communication problem or ");
            System.out.println(e);
       } finally {
            rpc.logout();
       }
   }
}

Page: Get Page History

Now, that we are adding content to Pages, there are going to be versions of the same document. These versions are called History of the Page. The XWiki API has methods available to access the history of the Page. The class that would help us in this case is the XWikiPageHistorySummary class.

Please note that the methods of XWikiPageHistorySummary class only help you access the various historical revisions of the document & not the content of the document itself. Eg. You would get to know that a particular Page called Main.WebHome has highest version as 4.1 or maybe 10.9. In order to access the content of the 4.1 revision of the document, you would have to use the Page retrieval code provided here by passing the appropriate version of the document.

import java.net.MalformedURLException;
import java.util.List;
import org.apache.xmlrpc.XmlRpcException;
import org.xwiki.xmlrpc.XWikiXmlRpcClient;
import org.xwiki.xmlrpc.model.XWikiPageHistorySummary;


public class PageHistory {

   public static void main(String[] args) throws MalformedURLException, XmlRpcException {

       //URL of the xwiki instance
        String url = "http://localhost:8080/xwiki/xmlrpc/confluence";

       //Replace user & pass with desired xwiki username & password
        String user = "Admin";
        String pass = "admin";


        XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
       try {

           //Perform Login & Authentication
            rpc.login(user, pass);

           //Create a XWikiPageHistorySummary object to hold all the revisions/history
            //of the Main.WebHome Page
            List<XWikiPageHistorySummary> hist = rpc.getPageHistory("Main.WebHome");

           //Iterate through all the available versions for Main.WebHome
            for(XWikiPageHistorySummary xphs:hist){

               //Print the fully qualified name of the Page i.e. SpaceName.PageName
                //In our example this would be Main.WebHome
                System.out.println(xphs.getBasePageId());

               //Print the historical page ID or name of the Main.WebHome page
                //This would print something like:
                //Main.WebHome?minorVersion=1&language=&version=2
                //It means page=Main.WebHome, version=2, minor version=1 & language=default
                System.out.println(xphs.getId());

               //Printing the version of Main.WebHome in the majorversion.minorversion format
                System.out.println("Version: "+xphs.getVersion()+"."+xphs.getMinorVersion());

               //Date when the Page was last modified
                System.out.println(xphs.getModified());

               //User who last modified the Page
                System.out.println(xphs.getModifier());

               //Just a seperator between various versions of the document when printing
                //to console
                System.out.println("------------------------------");
                 }

       } catch (XmlRpcException e) {
            System.out.println("invalid username/password was specified or communication problem or ");
            System.out.println(e);
       } finally {
            rpc.logout();
       }
   }
}

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected