The Client and Web Service Examples
With everything installed, you can build a client. If you would like to see a working example of a client, the downloadable sample
provides the code for a MIDlet that implements the client-side code for accessing the web service example. The enclosed README.txt file includes build and running instructions with the WTK. You just need to include the kXML-RPC binary as an external API in your project's settings. To do this, simply copy kxmlrpc1.1.x.jar
to your WTK project's /lib/
directory. If you are using development environment such as NetBeans or Eclipse, just remember to add the binary either as an external library or to your classpath.
The downloadable code also includes a ready-to-deploy web service example that will run on your local machine. Just be sure to have the most recent version of the Java Runtime Environment installed (we used Version 6 Update 1), and then unzip the contents of the file:
- A Jetty web server
- Redstone XML-RPC libraries
- A Java servlet
- A service implementation class
- A main Java class that launches the service
To launch the web service, execute run.bat in Windows or run.sh in Linux. The web service implements a number of methods that perform some integer mathematics. You invoke the service by calling different operations that calculate the result of four different binary math equations and two boolean equations (see Table 1 for a complete listing of the service operations).
|Add two integers
|Subtract one integer from the other
|Multiply two integers
|Divide one integer by another
|Assert if one integer is greater than the other
|Assert if one integer is smaller than the other
|Table 1. Details of the XML-RPC Web Service Example|
All operations take two integers as parameters. Assume the first parameter corresponds to the left-hand side of the operator and the second parameter to the right. For example, the equation x = 2 + 3 translates to the method x = math.add(2, 3).
Calling a Web Service
The kXML-RPC library is extremely simple to use. It provides a single client class and a single blocking Java method call that you can use to execute any service operation. First of all, create an instance of the XmlRpcClient class:
XmlRpcClient client = new XmlRpcClient("http://localhost:8081");
The constructor takes as a parameter a String that refers to the web service host. The class provides two constructors. The other takes as parameters the hostname as a String and the port number as an int. Both constructors initialize internal variables in the same way, so you can use either.
At this point, you have yet to make a connection to the web service. Connections occur only when you make a call to the web service and all communication between the client and server are in the form of HTTP requests and responses.
Knowing the service example provides an operation identified by math.add that takes two integers as arguments and returns as a result the sum of the two integers, you use the XmlRpcClient's execute() method to make a call to the service operation:
Vector parameters = new Vector();
Object result = client.execute("math.add", parameters);
The execute() method takes two parameters:
- The remote method's name as a String
- The remote method's parameter list as a Vector object
Using a Vector allows any number of parameters. The execute() method produces the following service request:
The service returns a response as follows:
The result of this service request is an integer, but if you look back to the original code, the result returned by the execute() method is of an Object type. All results of the XmlRpcClient.execute() method must be cast into their expected result type. You must account for this during your initial software development as incorrect casting of results will cause erroneous behavior and exceptions during runtime.