My First Experience Using the JSON-RPC Service.

This is one of those posts, where I am writing to my future self so that I can remember all that I learned about using the JSON-RPC service.

If you are an XPages developer who is interested in learning about this tool then I first suggest checking out the following resources:

• This email response to a question by Tim Tripcony is sheer brilliance. I had to read and re-read this several times to really understand it, but that speaks all about me and nothing about how Tim explains things.  A big thanks to David Leedy for making it available to all.

• Keith Strickland has written a very helpful blog post on JSON-RPC way back in June 2011. It was Keith who first turned me on to the Remote Service control when I found his answer to this Stack Overflow question.

• The Extension Library Book devotes a few pages (351-353) to the JSON-RPC that I found very helpful.

How I and why I used the JSON-RPC control

I needed to run a server based Java method that called a process and returned a result. My requirements stated that I need to try this process twice in a single event, and tell the user if the first try has failed. The way that Java works is to always one return value, so the intermediary messages would never be returned. In order to accomplish what I needed, I knew that clientside javascript was my best bet. In order to call a serverside java method from clientside JS, I decided to use an JSON-PRC call.

How to create the JSON-RPC service

1) Pull the tool from the pallet under “Data Access”. It is just called “Remote Service”.



2) Give the service a serviceName and/or a pathInfo. I believe that the service may be referred to as either.



3) Create the methods that you need to run. This will involve adding optional arguments and adding SSJS code to run in the script property. The script property doesn’t use the standard script editor that is usually used when you can enter serverside javascript.



4) The finished result

Using the Remote Service

It took me a while to understand that the service doesn’t return a value initially, it returns an object that contains a callback method. The callback method actually returns the value. Thanks to Toby Samples who answered my Stack Overflow question helping me with this.

Here is the code where I call my remote service methods:

Code Explanation:

1. First the code shows the user a message that the process is starting
2. Next, a value needed in one of the messages is pulled from a hidden input
3. The RPC method is called, the object returned is assigned to the var “deferred”
4. The callback of the object is called to get the result of the ‘first’ method
5. If the ‘first’ method returns true, the user gets a success message
6. If the ‘first’ method fails, the user gets a ‘retrying’ message, and the second method is called and the resulting object is assigned to a var “insideDeferred”
7. If the result of the ‘second’ is true, the user gets a success message
8. If the result of the ‘second’ method is false, the user gets a ‘try later’ message.

A slight problem

This code all worked great, except… it ran so fast that the ‘trying again’ message appeared too quick for a user to read. I spent a lot of time trying to figure out a way to use timers to slow it down. Eventually I decided that I was spending too much time on this, and used an simple alert for that message, which fulfills my requirement and allowed me to get moving with the rest of the project.

Parting Thoughts

Now that I understand how the Remote Service is used, I am sure I will find more uses for it.  It is an important tool in any XPages developers toolbox.  I can also see it being an important part of web applications that use a Domino backend and frontend Javascript frameworks like Angular JS.