ervice orientation is sweeping through modern enterprise environments like the Black Plague swept through Europe (hopefully the parallels end there). At the same time, enterprises seem increasingly interested in supporting thin clients and mobile interfaces. The convergence of these trends presents new challenges and more complex requirements, which enterprise developers can help address by choosing the best messaging protocol.
A service is a platform-neutral and typically coarse-grained interface to one or more business systems that can be invoked across a network. Wireless networks complicate this invocation process because the service provider must account for dropped packets and hops across multiple relays. Consequently, wireless clients must keep their exchanges as thin as possible to ensure optimum performance. Additionally, mobile devices typically do not have an abundance of resources for processing fat requests, synchronous request-response exchanges, or storing robust data models.
Its extremely lightweight XML grammar makes XML-RPC the ideal remote procedure-calling protocol for these service-oriented mobile computing scenarios, where application size, memory, and bandwidth are top priorities. (See “Sidebar 1. Why XML-RPC and Not SOAP“.) For Java developers, kXML-RPC, the XML-RPC implementation for the Java Platform, Micro Edition (Java ME), offers a mechanism for enabling their mobile applications to communicate with enterprise services. (See “Sidebar 2. kXML-RPC vs. JAX-RPC“.)
This article demonstrates how to build and run a Java mobile application that implements kXML-RPC on the client side to access a web service example. It includes a complete downloadable sample of all the code.
What You Need
The heart of this tutorial is the kXML-RPC library. As such, to build and run the example, you will need the following:
- Sun Java Wireless Toolkit for CLDC 2.5.1: This toolkit provides an emulation environment including the build tools for developing mobile applications. You will use the Wireless Toolkit (WTK) to compile and run the mobile client-side code.
- kXML-RPC 1.1 full binary: This library enables developers to perform XML-RPC calls for Java ME (CLDC) applications. The kXML-RPC binary does the grunt work of XML parsing and serialization of the service messages.
Installing the WTK should be straightforward; just follow the product’s installation instructions and refer to its documentation for the system requirements. The WTK is available only for Windows XP and Linux.
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).
| Description | Operation Identifier | Return Value |
|---|---|---|
| Add two integers | math.add | Integer |
| Subtract one integer from the other | math.subtract | Integer |
| Multiply two integers | math.multiply | Integer |
| Divide one integer by another | math.divide | Integer |
| Assert if one integer is greater than the other | math.greaterThan | Boolean |
| Assert if one integer is smaller than the other | math.lessThan | Boolean |
| 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();parameters.add(new Integer(2));parameters.add(new Integer(3));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:
math.add 2 3 The service returns a response as follows:
5 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.
How It Works
In the XML-RPC standard, you represent datatypes by enclosing them in specific XML tags. This example indicates the two integer parameters by enclosing them in
... 2 3 The XML-RPC clients and servers encode the data in this way, and they must map them to the appropriate equivalent platform datatype implementation. In kXML-RPC, the XML-RPC datatypes are mapped to the Java 1.3-compliant datatypes shown in Table 2.
| XML-RPC Type | Encoding Example | Java 1.3 Type |
|---|---|---|
| Four-byte signed integer | | java.lang.Integer |
| 0 (false) or 1 (true) | | java.lang.Boolean |
| String | | java.lang.String |
| Date/time | | java.util.Date |
| Base-64 encoded binary | | byte[] |
| Struct These are name-value pairs where the name is a string used as a key to retrieve the paired value. The value can be of any valid XML-RPC datatype, including structs and arrays. | | java.util.Hashtable |
| Array The specification for arrays allows for an ordered sequence of any type of valid XML-RPC datatype value. | | java.util.Vector |
| Table 2. Mappings from XML-RPC Datatypes to the Java 1.3-Compliant Datatypes |
The integers and boolean values do not map to int and bool primitives, but to their respective class equivalents. kXML-RPC is designed as such so that these kinds of values can be added to Vectors and Hashtables, because this is how the XML-RPC Struct and Array types are mapped respectively. Also note that when tags are not used to specify a type, the type is assumed to be a String.
kXML-RPC utilizes the kXML parser and serializer to create outgoing messages and process incoming messages. The XmlRpcClient class delegates serialization and parsing to the XmlRpcWriter and XmlRpcParser classes. Figure 1 illustrates the flow of control when the execute method of XmlRpcClient is called.
| Figure 1. Flow of Control When Execute Method of XmlRpcClient Is Called |
The XmlRpcWriter class creates the XML-RPC message and uses an HTTP POST request to send the message to a web service. The payload of the HTTP response is then processed by the XmlRpcParser, where the resulting object is finally returned by the execute method.
XML-RPC Limitations
XML-RPC provides a simple, minimalist XML grammar for invoking service operations. It does not, however, lend itself well to more advanced scenarios. Securing XML-RPC messages is limited to Transport Level Security (TLS) or ad-hoc XML encryption. Additionally, the protocol provides no extension mechanism to facilitate exchange of security tokens, transaction semantics, conversational state, endpoint addressing, intermediary handling, or other enterprise-grade messaging capabilities. If these more sophisticated capabilities are a part of your system requirements, then XML-RPC is not the answer. If, however, you’re looking for a quick, streamlined means of exchanging simple data structures between two systems in a neutral fashion, then XML-RPC is just right.
SOA Goes Wireless
As SOA continues to become a more pervasive factor within enterprise information systems, its convergence with mobile computing is inevitable. Service orientation is going wireless; it’s simply a matter of how much and how soon. When this occurs, enterprises will need to evaluate their requirements and make a determination regarding the right messaging protocol. XML-RPC and the kXML-RPC library certainly are in the mix.
