Domino, XML-RPC and Java - An Example

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
  • 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....


  1. Great example!


    A very good implementation considering the lack of documentation and examples out [<acronym title="the internet">there</acronym>]. How's about a follow up using the xml-rpc.MetaWeblog api?

      • avatar
      • Jake Howlett
      • Mon 16 Jun 2003

      Re: Great example!

      Glad you like it Mike.

      You're right about the lack of documentation. It's a wonder we ever get anywhere as Domino developers. I like to think that this is where I fit in ;o)

      If you want to use the MetaWeblog API it should be a case of finding the API specifics and simply tairloring my code to that spec. A good test of my articles will be whether or not you find this as easy as it should be....

      Show the rest of this thread

  2. Worked the first time I tried it!

    I can't believe it!!!! I just upgraded to the newest version of DomBlog and downloaded w.bloggar v3.02. I followed the directions in this post (which are a little outdated because w.blogger now has an option for Lotus Domino Blog API in the setup and the agent only requires username and password, not server or other stuff). To my amazement, it worked the very first time. I can't remember the last time that something worked the very first time.

      • avatar
      • Jake
      • Mon 1 Sep 2003

      Re: Worked the first time I tried it!

      Well, what can I say. We aim to please at Codestore ;o)

    • avatar
    • john
    • Mon 13 Nov 2006

    how to add keywords

    i want to know how to add keywords using wbloggar. as a site labnol.blogspot.com has different keywords for each page how to do this. plz tell me

Your Comments


Navigate other articles in the category "Java"

« Previous Article Next Article »
Domino, XML-RPC and Java - A Primer   Sending HTML mail via SMTP part 2

About This Article

Author: Jake Howlett
Category: Java
Keywords: blog; rpc. xml;


Print Friendly

Let's Get Social

About This Website

CodeStore is all about web development. Concentrating on Lotus Domino, ASP.NET, Flex, SharePoint and all things internet.

Your host is Jake Howlett who runs his own web development company called Rockall Design and is always on the lookout for new and interesting work to do.

You can find me on Twitter and on Linked In.

Read more about this site »