XML-RPC Java and You

[bcoe]

Originally posted on my blog.
----------------------------------

What is XML-RPC? One answer to this question is that it is the way of the future… A less rhetorical/frustrating answer would be that it is a technology that leverages HTTP and XML to remotely, and platform independently, execute external services. With the interplay that takes place between web-services in the Web 2.0 environment, technologies such as XML-RPC facilitate the sharing of both information and functionality between various sources.

Examples of applications of XML-RPC include pinging third party sites such as Technorati regarding blog updates — as was done when I posted this new blog entry — and publishing remotely to your blog (this option is offered by sites like digg). Countless other quasi standards exist taking advantage of this technology.

I myself am a Java™ programmer (well, I call myself a Ninja), and in this tutorial I present two separate fully developed scenarios: creating a fully functional XML-RPC client, and creating an XML-RPC server application. Both these examples use the Apache XML-RPC libraries.
An RPC Pinging Client

Rather than present a client and its corresponding server, as is often done in this sort of tutorial, I thought I would present two separate and useful applications. In this example I demonstrate how you could create your own tool for pinging various blog search engines regarding a website update — presumably on your nifty Java™ powered website.

Without further adieu, Ping.java:

import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
import java.net.URL;
import java.util.*; 
 
 
public class Ping{
  public static final String PingMe[] = 
    new String[]{"http://rpc.pingomatic.com/"}; 
 
 
  //Connects to an RPC pinging service.
  public Ping(String Title,String Url,String UrlChanges,String UrlRSS){
    for(int i=0;i<PingMe.length;i++){
      try{
        XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
    config.setServerURL(new URL(PingMe[i]));
    XmlRpcClient client = new XmlRpcClient();
    client.setConfig(config);
        Object[] params = new Object[]{Title,Url,UrlChanges,UrlRSS};
        HashMap result = 
        (HashMap) client.execute("weblogUpdates.extendedPing", params);
    //Output the response from the server.
    System.out.println(result);
      }catch(Exception e){
        e.printStackTrace();
      }
    }
  } 
 
 
  //Testing main.
  public static void main(String args[]){
    Ping MyPing=new Ping("PLink News",
                         "http://www.plink-search.com/blog/news/",
                         "http://www.plink-search.com/blog/news/",
                         "http://www.plink-search.com/plink.xml?fetch=news");
  }
} 

This simple little application will ping whatever sites are included in the PingMe array. In this case it just pings Ping-o-Matic! — a site that, in-turn, pings several other sites.

The actual XML-RPC is run with a call to client.execute. As can be seen, I am executing the weblogUpdates.extendedPing procedure. The array of objects I pass in gets translated into XML-RPC types, and is transported over that magic series of tubes that is the Internet.
A MetaWeblog API Server Application

Having seen a useful client in action, what exactly is happening on the server side of things? The server entry points for your Java™-based XML-RPC take the form of a the most basic of Java™ classes — no fancy libraries need even be imported. All the work is in naming conventions, reading information pertaining to the specific specification you wish to implement, and making sure you understand the XML-RPC types. It is also assumed that you have a working Tomcat environment, or equivalent.

For PLink I decided to implement portions of the MetaWeblog API. This API is designed for allowing an RPC request to publish data to your blog — I was interested in adding digg’s Blog It functionality to PLink. Let’s begin by looking at the MetaWeblog RFC. Take note of the three main entry points:

metaWeblog.newPost (blogid, username, password, struct, publish) returns string

metaWeblog.editPost (postid, username, password, struct, publish) returns true

metaWeblog.getPost (postid, username, password) returns struct

Unfortunately, in the semi-standardized environment that is the Internet, I found it necessary to implement an additional function to allow for digg support:

getUsersBlogs(String appkey,String user,String pass) returns struct[]

Note: This procedure call is actually drawn from the Blogger API.

Having examined these function calls let’s look at the corresponding Java™ class, here’s metaweblog.java:

import java.io.*;
import java.util.*;
public class metaweblog{ 
 
 
    public String newPost(String blogid,String user,String pass,
                              Map struct,Boolean publish) throws Exception{
        //Parse values from struct corresponding to RSS specification.
        String title=(String)struct.get("title");
        String description=(String)struct.get("description");
        String postid="";
        //Database access and the like.
        return(postid);
    } 
 
 
    public Boolean editPost(String blogid,String username,String password,
                                Map struct,Boolean publish) throws Exception{
        //Parse values from struct corresponding to RSS specification.
        String title=(String)struct.get("title");
        String description=(String)struct.get("description");
        //Database access and the like.
        return(new Boolean(true));
    } 
 
 
    public Map getPost(String postid,String username,String password) throws Exception{
        HashMap returnMe=new HashMap();
        //Database access and the like.
        return(returnMe);
    } 
 
 
    public Object[] getUsersBlogs(String appkey,String user,String pass) throws Exception{
        String url="http://www.plink-search.com/";
        String blogName="My Crazy Blog!";
        //Return information pertaining to blogs that a given user owns on your server.
        Map returnMe[]=new Map[1];
        returnMe[0]=new HashMap();
        returnMe[0].put("userID",user);
        returnMe[0].put("url",url);
        returnMe[0].put("blogid",user);
        returnMe[0].put("blogName",blogName);
        return(returnMe);
    }
} 

Finally, to connect this code to incoming XML-RPC calls we can use the default XmlRpcServlet — assuming that we have installed ws-xmlrpc on our server — by adding the following to our web.xml file:

<servlet>
        <servlet-name>XmlRpcServlet</servlet-name>
        <servlet-class>org.apache.xmlrpc.webserver.XmlRpcServlet</servlet-class>
        <init-param>
          <param-name>enabledForExtensions</param-name>
          <param-value>true</param-value>
          <description>
            Sets, whether the servlet supports vendor extensions for XML-RPC.
          </description>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>XmlRpcServlet</servlet-name>
        <url-pattern>/xmlrpc</url-pattern>
    </servlet-mapping> 

The final step is to add a file to org/apache/xmlrpc/webserver/ named XmlRpcServlet.properties this file tells your XmlRpcServlet what remote applications can be executed. Here is the entry corresponding to the MetaWeblog example:

metaWeblog=metaweblog

The value before the equals indicates the request . The value after the equals maps this incoming request to a specific class — in our case the compiled version of metaweblog.java.

There you have it: Individuals, once all those stubs are filled out, could now publish remotely to your fancy blogging software using XML-RPC. This would take on the form of a call similar to,

HashMap Post=new HashMap();
  Post.put("description","My Story");
  Post.put("title","My Title");
  Object[] params = new Object[]{"Blog ID","user","pass",Post,new Boolean(true)};
  HashMap result = (HashMap) client.execute("metaWeblog.newPost", params); 

XML-RPC is a cool technology, and I hope this has provided other Java™ programmers like myself with a good primer.

-Ben (Developer Hack Wars - The Game of Virtual Hacking)