While the explosion of mobile devices has created an unprecedented opportunity for application developers to extend their reach beyond the desktop, the advent of Web Services has provided a handy interface to remote libraries. These two items combined offer the promise of a thin client with high functionality on lightweight platforms.
But the promise is not the reality. Even though Apache Axis 2 is billed as being designed from the ground up to be lighter, in this case lighter is not less filling. The libraries required to run Axis2 on a client are massive considering the space available. Enter KSOAP2, a lightweight SOAP client library that totals about 100K in client-side space requirements when compiled for either JAR or COD format. Utilizing kSOAP2, a six man-month development cycle delivered a stable Blackberry web services application that could be retargeted for any Java ME capable device with a recompile.
Utilizing kSOAP2 is relatively easy once you know a few basic concepts: How to establish a connection, how to send a request, and how to access the objects in a parsed a response.
The first thing necessary -- particularly on the Blackberry platform -- is to build the libraries from source. For our project we did this in the JDE, but it doesn't really matter where you build them. A JAR to COD converter is included with the Blackberry Java Development Environment (JDE) but I don't recommend it primarily because building provides full debug information with source link-in, and some kSOAP errors are just easier to debug by stepping through the parser.
Once the libraries are built-in the environment, create a new project and include all of the libraries -- kSOAP, kXML, kObjects, and XMLPullParser. These are all required for even the simplest of kSOAP calls to work correctly.
kSOAP is lightweight, and as such the library only supports HTTP and HTTPS, both with and without basic authentication.
Connections
The first step is to establish connection parameters to begin communicating with the server the web service is on. There are two possible calls to establish this connection:
HttpTransport httpt = new HttpTransport("http://" + IPorHostname + "Path/To/Webservice/function");
HttpTransportBasicAuth httpt = new HttpTransportBasicAuth("https://" + IPorHostname + "Path/To/Webservice/function", username, password);
In the first case, the connection is made with no authorization, and in the second HTTP Basic Auth is used. The only real difference is that the second call is using HTTPS and it is passed a username and password.
Requests
Once a connection is established, you can format the request and indicate where kSOAP should put the response. All SOAP communications have an envelope that wraps the SOAP request or response. To reflect this, kSOAP uses the SOAP envelope as the top-level object of all requests.
SoapSerializationEnvelope envelope = new SoapSerializationEnvelope(SoapEnvelope.VER11);
The valid values of the single parameter are SoapEnvelope.VER10, SoapEnvelope.VER11, and SoapEnvelope.VER12, indicating the use of SOAP 1.0, 1.1, or 1.2.
The next step is to tell kSOAP which operation will be invoked on the endpoint (URL) sent in the call to create the connection.
SoapObject request = new SoapObject("urn:iControl:LocalLB/VirtualServer", "get_list");
The first parameter is the SOAP namespace, and the second is the operation you wish to invoke. In object terms this would be iControl.LocalLB.VirtualServer.get_list(). This is one of the web service operations available on F5's BIG-IP load balancers. Replace the path with the path for your web service.
Then you have to tell kSOAP to use request as the outgoing object:
envelope.setOutputSoapObject(request);
If your web service requires parameters, this is where you create them. You can also set miscellaneous parameters for the call The most useful parameter is the debug parameter of the transport object:
httpt.debug = true;
tells kSOAP to keep a copy of the text input and output buffers so that you can see what was actually sent and received over the SOAP interface.
You can add request parameters using the addProperty method. For example, to set the call parameter vlans to the values in the Vector variable named portList you would use:
request.addProperty("vlans",portList);
Thus the SOAP call will include a complex element named vlans with the values in portList.
The format of the addProperty method is:
addProperty(SOAP Parameter Name, variable or value)
You can use any valid kSOAP object, a Vector, or any Java primitive as the value.
