Domino XML-RPC Client
If you have reached this page directly, it might be a good idea to read this first.
The first thing you need to do is get hold of a class-library implementation of the XML-RPC protocol. I use Java for all my server-side Domino development, so I used Apache XML-RPC. Their implementation is quite simple and easy to understand The class libraries with the documentation are a small 294KB download. The actual Jar file for the XML-RPC implementation is just 57KB.
Step 1: Convert the XML-RPC JAR file (xmlrpc-1.1.jar) into a Notes "Script Library".
(For instructions on how to do that, read the section titled Creating a ServletSupport Script Library in this article.
Call the Script Library something like "XmlRpcLib".
Step 2: Create a new Java Agent in your notes database, and include the XML-RPC library by doing the following:
- Click on Edit Project in the Java code window and then click "Shared Java Libraries" in the "Browse" combo-box
- Select XmlRpcLib from the displayed libraries.
The actual code is quite straight-forward. I start by capturing AgentOutput to a PrintWriter object.
The listener web-service at weblogs.com is located at http://rpc.weblogs.com/RPC2.
I connect to that service using the XmlRpcClientLite object provided by the Apache XML-RPC classes.
XmlRpcClientLite xrcObj = new XmlRpcClientLite(strServerWeblogsDotCom);
(here strServerWeblogsDotCom is a string containing the http:// address to the weblogs RPC server)
The method name on weblogs.com, is weblogUpdates.ping and it takes two parameters, the name of your website and the URL of the website. The method is described in detail over here
(See the code for details on how these parameters are passed).
I use the XmlRpcClient.execute() method to remotely execute the method on weblogs.com.
The method returns either a success (shown on the left - I pinged as evolt.org) or a failure ("No Changes")message (shown below) upon completion.
The Apache XML-RPC classes also come with the building blocks to create XML-RPC servers (or web-services). These open whole new ways of how Domino can be extended. I can imagine that the functionality for propagating the same website information (like weather reports, for example) from a central server across many geographically different servers, can be easily created using these services .
In the end, how you use it, is really up to you.
Download a sample notes database with the sample agent code & Xml-Rpc class libraries (67KB)
by clicking here
(You will need to sign it, to execute it on your server)
The database has:
- A Script Library for the Apache XML-RPC libraries
- A Java Agent that contains the sample code shown below
You can execute the agent in two ways :
- Through a URL like : /pingdb.nsf/XmlRpcPing?openagent
- Execute it as a scheduled agent. I use it as a scheduled agent, though my website agent does some additional work by actually looking up to see I have updated a blog, only then does it ping weblogs.com
This is how my site appeared on weblogs.com, after I created a new weblog entry :
Read the commented code below on the details:
import lotus.domino.*;
/*for the Vector and HashTable classes*/
import java.util.*;
import java.io.PrintWriter;
/*remember to add this for the XmlRpc objects to compile*/
import org.apache.xmlrpc.*;
/*This is the standard JavaAgent class created by Designer, I just renamed it*/
public class XmlRpcAgent extends AgentBase {
/*weblogs.com RPC listener server*/
private String strServerWeblogsDotCom ="http://rpc.weblogs.com/RPC2";
public void NotesMain () {
try {
PrintWriter pw = getAgentOutput();
/*set the right content type*/
pw.println("Content-Type:text/html");
/*initialize the page tags*/
pw.println("<html><head>")
pw.println("<title>Domino does an XML-RPC ping</title>");
pw.println("</head>");
pw.println("<body><h1>");
/*create a new XmlRpcClientLite object for the weblogs
listener server, You can also use the full blown
XmlRpcClient object*/
XmlRpcClientLite xrcObj = new XmlRpcClientLite(strServerWeblogsDotCom);
/*stores the name of your website*/
String strWebsiteName;
/*stores the name of your websites URL*/
String strWebsiteUrl;
/*my website :) */
strWebsiteName = "Ashok Hariharan's website and weblog";
/*my website url*/
strWebsiteUrl = "http://www.unganisha.org";
/*create a vector to pass parameters to the weblogs server*/
Vector vParameters = new Vector();
/*add the parameters to the vector*/
vParameters.addElement(strWebsiteName);
vParameters.addElement(strWebsiteUrl);
/*ping the weblogs server by calling the weblogUpdates.ping method*/
/*See http://www.xmlrpc.com/weblogsCom, for the method details*/
/*the result of the ping is returned as HashTable*/
Hashtable htResult = (Hashtable) xrcObj.execute("weblogUpdates.ping",
vParameters);
String strResult = new String("");
/*get the result message from the Weblogs xml-rpc service by
getting the message from the Hashtable*/
strResult = ((String) htResult.get("message")).toString();
/*Print the result message on the browser*/
pw.println("Ping Result : " + strResult);
pw.println("</h1></body></html>");
}
catch (XmlRpcException exception)
{
System.err.println("XML-RPC Error" +
Integer.toString(exception.code) + ": " +
exception.toString());
}
catch (Exception exception) {
System.err.println("Error: " + exception.toString());
}
}
}