This is the first post of Nano Tutorial Series, in this post, I will show you how easy to use Nano framework to put WSDL driven application development on Android platform into practice. If this is the first time you get to know Nano, then after this tutorial, you will basically understand what Nano can do for you, and the basic development process when using Nano to carry out WSDL driven development on Android. If you want to see the big picture, please read this post first.
The whole source of this demo is here.
WSDL driven development using Nano framework has following steps:
- Generate Java proxy from WSDL
- Create new Android project, add Nano runtime and generated proxy into your project
- Implement appliction logic and UI, call proxy to invoke web service as needed.
Step 1 - Generate Java Proxy from WSDL
Nano has an accompanying code generator which can generate Java proxy for Android from wsdl, the tool is called mwsc, please download the latest zip package here then extract it into your local folder. Note : mwsc code generator needs Java 1.6 or above to run, so please ensure Java is installed on your OS, if not, please install it first.
The command line script
mwsc.bat is in the bin folder, note,
mwsc.bat is for windows, for linux, please use
mwsc in the same folder. Before code generation, you may optionally create a folder as your code generation target(for example,
generated), otherwise, mwsc will generate code in current folder. Now let’s generate code from wsdl by running flowing command in the terminal:
If everything works fine, you will see the code generator output
generating code… and
done at the end, the target proxy will be generated in the
Step 2 - Create New Android Project, Add Nano Library and Generated Proxy into Your Project
Now let’s create a simple Android project in eclipse(or other IDE you prefer), then you need to:
- Download latest nano library jar and add it to the
libsfolder of your Android project.
- Drag the above generated proxy into the
srcfolder of your Android project.
- Add following user permissions in the
AndroidManifest.xmlfile to enable network access.
Now since both Nano runtime library and the NumberConversion web service proxy have been added in the project, you can try to refresh(or build) the project, if no build error, job well done, you can continue to the next step, otherwise, please do some troubleshooting, or check the source of this tutorial(in the sample/webservice folder).
Below is an eclipse package explorer screenshot after finishing this step:
Step 3 - Implement Appliction Logic and UI, Call Proxy to Invoke Web Service as Needed.
A SOAP web service client called
NumberConversionSoapType_SOAPClient has been generated in the
com.dataaccess.webservicesserver.client package, it’s the main proxy to the external number conversion service, you can invoke number conversion service by calling methods on a
NumberConversionSoapType_SOAPClient instance. As a Nano best practice, it’s not necessary for you to initiate a new client everytime you need to call service, a singleton client instance is enough for the whole application, so before writing any application logic, let’s create a shared NumberConversion service client for later use first, see code below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
The code is quite self-explanatory, the
getSharedClient static factory method just returns a NumberConversionSoapType_SOAPClient instance with specified target service endpoint address, and there will be only one such client instance within the application.
With the help of the NumberConversion service proxy generated from WSDL, web service call through Nano is extremely simple, let’s review and understand the generated numberToWords proxy interface first before writing calling logic:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
This is just a plain old interface generated from wsdl, unlike normal interface, this interface is asynchronous, when you call
numberToWords service, you need to provide a request of type
NumberToWords as first parameter, also you need to provide(or register) a callback implementing interface
SOAPServiceCallback, see definition of this interface below:
1 2 3 4 5 6 7 8 9
1 2 3 4 5 6 7
SOAPServiceCallback interface supports three callback methods,
onSOAPFault callbacks, success callback will be called if the service invocation succeed, and you will get a response object of type
NumberToWordsResponse, usually, in success callback, you implement response handling logic and update UI according to the response; failure callback will be called if there is any HTTP or Nano parsing error, you may get an exception and an error message in such case, usually, you implement error handling logic in failure callback and update UI accordingly; soap fault callback will be called if Nano get a SOAP fault from service response, usually, you implement error handling logic in the soap fault callback and update UI accordingly.
By the way, although not necessary, I suggest you to review all proxy code generated by mwsc, this will help you better understand the inner working of Nano.
Now time to the UI part, for this simple demo, we only need an
EditText for number input, and two
Button, one for number to dollars conversion, the other for number to words conversion, see graphical layout screenshot below:
Now let’s implement application logic by calling the
the application logic is implemented in the
MainActivity class, a registered
onClick method will be triggered when you click the
Number To Words button on the UI:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
The call logic can’t be simpler, I’ve added comments in the service call code for you to better understand the call flow. Also, I’ve enabled the debug mode of the proxy, so you can see the detailed request/response messages when you run the demo, this feature is extremely useful for troubleshooting.
Final Step - Run the Demo
Now it’s time to run the demo, let’s try it in the simulator(you may use a real device of course), below is a screenshot of the simulator after converting a number to dollars:
You can also find the debug output in the Android LogCat, like below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
If you have any problem to run the demo, please check the debug output first.
Now you see the power of Nano framework, you don’t get troubled with error prone and tedious SOAP/XML parsing or http handling, the generic Nano framework will do these stuff for you, you only need to use a plain old asynchronous interface for service invocation, this can not only accelerate application development, but reduce the long term maintenance cost.
NumberConversion is just a bare minimum demo, there are other more featured demos(like Amazon, eBay search demo) in the sample folder of Nano project, please try them to better understand how Nano works, then you can begin to develop your own service based applications, using wsdl driven methodology supported by Nano.
See your next great Android application!