The Minimum Steps to utilize KSOAP2

kSOAP is a lightweight access library for web services. Designed with hand-held devices in mind, it's light and easy to use, but documentation and samples for the project is lacking. YOu can download the kSOAP libraries and JavaDoc documentation here.
There are not a ton of solid examples out their for using KSOAP to access web services, in fact, only one page on a wiki has good solid examples, and they're not well explained. Since we're using kSOAP to access BIG-IP from cell phones via JavaSE, we've built some solid experience in it, and offer up this short tutorial as our way of repaying the community.

To access Web Services, you need a connection to the web server, the name of the web service, some way to represent the XML request, and some way to get the relevant data out of the XML response. In kSOAP, this translates to the following objects/calls being required:

- HttpTransport httpt = new HttpTransportBasicAuth("http://" + IPorHostname + "Path/To/Webservice/function");

This establishes communication with the web service. For use with the BIG-IP, all communications must be over https. kSOAP provides for this. Simply use the HTTPS transport instead:

- HttpTransportBasicAuth httpt = new HttpTransportBasicAuth("https://" + IPorHostname + "Path/To?Webservice/Function", Username, Password);

In the above examples, it is assumed that IPorHostname, Username, and Password are String variables with the named data in them. You will also have to replace "Path/To/Webservice/function" with the actual path on the web server.

Next you need the SOAP envelope - the container that holds your data in both calls and responses.

- SoapSerializationEnvelope envelope = new SoapSerializationEnvelope(SoapEnvelope.VER11);

This creates an envelope to hold the call and response. Note that it allows you to specify which version of SOAP you wish to utilize.

Since this is the simplest example of utilizing kSOAP, we're going to call a web service that takes no parameters. Calling one that takes parameters is a little more involved, but should be easy to figure out if you have the basics down. As such, you need to make a web service request to put in the envelope.

- SoapObject request = new SoapObject("urn:iControl:LocalLB/VirtualServer", "get_list");

This creates a request to call the iControl:LocalLB:VirtualServer.get_list() web service. You can get the URN of your web service from the web service's WSDL.

Next, you have to tell the envelope that when it goes out to the server, this is the request it should use. In kSOAP, you do that by passing the object created above to the setOutputSoapObject routine of the envelope. It is named with Output because it is the command your program will be writing out to the web service.

- envelope.setOutputSoapObject(request);

Now we've built a connection, created the envelope and given it a request, all that is left to us is to make the call and process the results. First, the call...

- httpt.call("", envelope);

That's it, you're telling it call the web service defined in the object envelope. Inside envelope is your request, so it builds a SOAP request correctly. Now you need to get to the data. Our get_list service returns an array of Virtual Server Names, so we know the result will come back as a list of items. In kSOAP, lists are automatically mapped to Java Vectors, so we have the following combination to get to the data.

- SoapObject body = (SoapObject)envelope.bodyIn;

The bodyIn variable holds the body of the response from the webserver - because it is the data we're getting in from the web service, it's named bodyIn. SoapObject is utilized to represent anything that can be transfered that is a complex type but not a list. So this Soap Object represents the entire response body. Next we want to get our list, which is the only value that should be in the body, so it will be at location zero in the list of SOAP properties in the body.

- Vector virtualServerList = (Vector) body.getProperty(0);

The SoapObject method getProperty is used throughout the system to return one of the items in the subitem list of this instance of SoapObject. Since nested responses will have several layers of SoapObjects and/or Vectors, you can call this as much as you need to get to the actual data you are after. In our case, we only need to do this once since this first call returns a Vector that is populated with Strings (Java primitives are mapped correctly without any action on your part).

Now we can use the Vector created in the last statement anywhere in our code - it is a Java vector and will behave like one.

That's it. These few steps will get you access to your data on any JavaME platform that you have configured kSOAP on.