Dr. Dobb's is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.


Channels ▼
RSS

Mobile

SOAP-enabling Mobile Devices with KSOAP-2


Don MacVittie is technical marketing manager at F5 Networks.


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.


Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.