Domino, XML-RPC and Java - An Example

Jake Howlett, 9 June 2003

Category: Java; Keywords: blog rpc. xml

Okay so in the last article we covered the ins and outs of XML-RPC and we're happy with the fact that Domino can process RPC requests using nothing but a simple Java agent. Now let's look at an example of using them together in a practical application. If you've not read the primer article, you might want to do that now.

The Scenario:

Before you start to curse me under your breath, I'll warn you now, I am going to be using the word blog and its derivatives quite a bit in this article. But, please don't think this in any way means the article is of no relevance to you. I would hate to alienate 99% of my readers in this way! This article has something for everyone. I'm using blogging as an example for two reasons. One is that I needed to write the code for my own blog site anyway and the other is that it's a good example to get us started. I also needed to write this article as an introduction to using RPC for the people who are already using the template to which I added the code.

The code I wrote was to enable me to add and edit documents in my blogging database directly from a a third party piece of software called w.bloggar. The main reason being that this application offered many nice features missing from the Notes client and the web browser. In writing the code I also opened up the site to many other similar tools that use the XML-RPC methods.

Using the code:

Instead of talking you throuh the code I am going to talk you through an example of its use. If you are interested in the code then you should read the primer article and then dig round in the agent for more ideas. This should be all you need as the code used is a simple extension of the primer's core functionality.

To start using this example you'll need two things - 1) The latest version of the DomBlog Template (v1.5 as of writing) and 2) a copy of w.bloggar (no licence required). Add the database to a server (leave the ACL and documents intact) and then install w.bloggar locally. Now we can go through getting them both working.

First thing to do is edit the agent called "xml-rpc" in the domblog.nsf database. Near the top of it you will see the following declarations:

public final static String SERVER_ADDRESS = "mydominoserver"; public final static String USERNAME = "Jake Howlett"; public final static String PASSWORD = "secret"; public final static String LOGIN_ERROR_MESSAGE = "Can\'t Authenticate"; public final static String TITLE_STRING_START = "<title>"; public final static String TITLE_STRING_END = "</title>";

Change the settings as follows:

SERVER_ADDRESS - The host name of your server, e.g domino-9.prominic.net or 192.168.0.10
USERNAME - Give yourself a username. This does not have to be the same as your Notes ID!
PASSWORD - Give this username a password. Again, doesn't have to be the same as the Notes ID or your internet password
TITLE_STRING_START and TITLE_STRING_END - leave these as they are for the time being

Note: You may be wondering why there's a need for a new username and password. Well, as you will see in the RPC calls to the Blogger API, each request is passed a username and password from the client application. Adding these directly to the code was a whole lot easier than playing with IOR and Notes authentication. You'll have to trust me on this one!

Once you made the changes you can save and close the Agent. In doing so you have signed it with your ID. Hopefully you will have enough permissions to run Java agents on the server. If not you need to resign with an ID that does.

Now we can setup the w.bloggar application. Launch the program from wherever it left an icon and you should see the following screen:

Enter the username and password (case-sensitive) that you specified in the Java agent. Press Ok and it will ask if you want to create a new account. Say yes. You will then see the Account Properties screen, as below:

Change the Blog Tool setting to >> Custom << and give the account an Alias that will mean something to you next time you launch w.bloggar. Change the Host field to the address of the server you installed DomBlog on. In the Page field enter the absolute path to the database and append to this the name of the agent to be called.

Once you've done that switch to the Custom tab (unless you need to specify the Proxy settings first that is):

In this tab make sure that the Posts field is set to Blogger API and that Templates are set to unsupported. Change the title tags to whatever are in TITLE_STRING_START or TITLE_STRING_END settings in the agent. Remove the Category tag strings completely.

These should be all the changes you need to make. Press Ok and, all being well, you should get taken to the main editing screen, shown below. If you have any problems, you will get prompted as to the reasons why. Normally just a typo somewhere in your settings. Double-check them all before you start to panic.

You are now ready to blog (that is, add documents) to the DomBlog database from w.bloggar. Enter a title and some text for the body of the blog. Once you've previewed it and done a quick spell-check, press the Post button. After a short pause you should see that the NoteID of the document has been returned to w.bloggar to signify success, as below:

Note that pressing Post only places the document in the Draft Blogs view and it's not gone live yet. To do this we have to press the Post & Publish button. A good job really as there are two typos in my entry. It should say "that Jake Howlett" instead of "the Jake Howlett" and why did I add the "be"?. You can tell how excited I am. After a quick edit I can now safely make it live. This time the returned message simply tells me that the blog was updated successfully.

Notice that I've ringed one of the buttons in the screen-grab above? Pressing this takes you straight to the site in your browser. Press it and you should, as if by magic, see your new post at the top of the homepage:

Wait. It doesn't end there. You're not restricted to posting and editing new blogs. You can download old ones and edit them too. They don't even have to have been created in the w.bloggar client. Press the Posts button and (by default) you will see a list of the 5 most recent entries (including drafts). You can edit and delete these at your will.

The only thing we can't do with w.bloggar yet is add image resources. w.bloggar assumes you upload files using FTP. We don't. I'm afraid until I come up with a better alternative there is still the need to log in to Domino the old fashioned way.

In summary:

Hopefully you've not got this far and feel a little disappointed. Were you expected some code insight? Sorry. The reason I chose not to is that if you look at the code in the XML-RPC agent it should all be pretty clear if you've read and understood the primer. What I wanted to do was show you a real-world example of its use.

Whether or not you're a blogger you should be able to get something useful out of it all. If not then you might want to wait for my next article. You've not heard the last of Web Services from me yet....