Faq


1. I'm in the middle of developing my web service therefore it is changing a lot and I generate classes a few times a week. Is there any way to configure the service class without modifying generated source code?


Yes, you can set some configuration without changing generated code. This feature is available in the code generated for Premium account only. Basically you should create your own service class which extend the generated one and override one or many methods. Let's take a look on this example.

Of course you don't need to override all methods.

2. Is version of ksoap2 library important?


Yes, it is important. Generated classes by EasyWsdl are created with specific ksoap2 version. Information about the correct version you can find in readme.txt file in generated zip. It is not recommended to upgrade ksoap2 to different version without generating classes in our service. Of course you shouldn't generate a new classes without upgrading ksoap2 library (if needed of course). Basically you should always do both operations, so generate new classes in easywsdl and if needed upgrade ksoap2 library.

3. How to use async methods? (Android only)


First thing is to generate async methods. Simply select a check box Generate async methods on the Generate page.
Next thing is to use Async method in your application. This can be done in this way:

You don't need to do anything with this AsyncTask returned object (it is used for canceling request).
Instead of creating anonymous class you can implement IServiceEvents interface in you Activity class and pass this to the constructor.

4. How to send/receive a large binary data?


Typical SOAP web service has some limitation in sending a large binary data (like images, videos, documents, etc). Problem is that the binary data are base64-encoded and added to XML message body. Many XML parsers cannot parse very well huge in size documents. To address this issue there is a possibility to send binary data as an attachment (outside the SOAP message body). Of course Web service has to support this feature (MTOM transfer/attachment).

So if your web service supports MTOM transfer then you can use EasyWSDL to generate classes with attachment support. To do this you should select Add MTOM transfer in generator page. Please remember to add ExKsoap2-1.X.X.X.jar library to your project (you will find it in libs folder in generated zip file)

By default, attachments are stored in a memory (it uses MemoryDestinationManager) so in case you retrieve large binary data you still can have OutOfMemoryException in Android. You can change this default behavior by using FileDestinationManager which uses file system to store attachments in files.

To configure your classes to store attachments in files you can create a custom service class and overwrite CreateEnvelope method, like this:

In baseDirectory you should set a path to the folder where you want to store files. We recommend to use a dedicated folder which can be deleted if you don't need attachments any more.

Warning


Keep in mind that attachments can be large and everytime your application download a new attachment it will take some space in device storage, so you should remove attachment files when you don't need them.

5. I need MTOM attachments in my Android project. I use raw ksoap2 and I would like to use MTOM Transfer feature provided by your ExKsoap2 library. Can I use ExKsoap2-1.X.X.X.jar without generating classes in EasyWSDL?


ExKsoap2 library is available to all Premium users. So every Premium user can use this library in any project

6. I got compilation error: com.android.dex.DexException: Multiple dex files define Lorg/kobjects/....


This problem occures when you have many copies of ksoap2.jar added as a dependencies in your project. For Premium account we add ExKsoap2.jar library which already has ksoap2.jar. So basically you should add ExKsoap2.jar only to your dependencies (without ksoap2.jar). If you added both ExKsoap2.jar and Ksoap.jar libs, then you can have this issue. To solve it, please remove Ksoap2.jar from dependencies.

7. How to use any collection?


Some web services use <any> element to return/retrieve any type of data. The schema (structure) of these data is unknown so EasyWSDL are not able to generate a strongly typed fields for them. Instead, there is one field any which is a collection of PropertyInfo objects and using it you can still retrieve or send such data in a raw format. Here you will find example how to retrieve and send data using any collection.

Sending data
Retrieving data

8. How to add a Basic authentication?


To implement a Basic authentication, you have to add a special http header to your service. Here you have two solutions:

1. Add http header directly to your service instance:

2. Create a custom transport class

This is more elegant solution. You can create a separate transport class which is responsible for basic authentication. Click here to see example of such class. Next step is to override createTransport method in service class and use this new class instead of existing one:

9. BinaryObject.getUnderlayingObject() returns null after restored from Parcel.


EasyWSDL can generate classes which implements Parcelable interface. There is one limitation in this feature, which is supporting BinaryObject class. Problem is that BinaryObject can hold many different binary data representation like byte[], Stream and more. Only byte[] can be stored in Parcel, the all other objects not (like streams) and because of this after you restore BinaryObject from a Parcel, getUnderlayingObject returns null, therefore we recommend to invoke getUnderlayingObject method first, store returned object (eg stream) in a variable and then put BinaryObject to a Parcel.

10. SoapObject in any collection. Can we have a strong types instead?


In the latest generator we have introduced a feature to detect a strong types in any collections. To use this option, you have to set createClassesForAny property in you service class:

service.createClassesForAny=true;

With this option, you should find your objects instead of raw SoapObject in any collection.

Important

If you still have raw DDXMLElement objects in any collection, you should generate classes with option Advanced settings -> Generate All classes.

1. How to use enum types?


Enums are converted to special classes. The easiest way to explain this is by example. We have the following enum:

Our generator will create the following class in Objective-C: We can do the following operations with this enum:

2. Using generated code

Setup
  1. Add all files from src folder to your iOS project. We recommend to create a separate group for these files in your XCode project.
  2. Add all files from KissXML folder to your project.
  3. Go to the project settings (choose "Edit Project Settings" from "Project" menu").
  4. Go to the "Build" tab and make the following changes:
       In the "Linking" section, go to the "Other Linker Flags" section and add the value "-lxml2" (without quotes).
       In the "Search Paths" section add a new search path to the "Header Search Paths" for "/usr/include/libxml2" (needed for KissXML library)

Working with the code

First step is to add import directive in the class file where you want to use your service

#import "MyService.h"

Then create an instance of your service class (you can also use initWithUrl to specify different URL)

TestWSPortBinding *service=[[TestWSPortBinding alloc] init];

Now let's invoke a method. There are one synchronous method and two asynchronous (with Async in method name).

[service getOrderAsync:orderItem __target:self __handler:@selector(handler:)];

In the same class where we use our service we must add a callback method which will be invoked when web service return any result. Here is an example of these steps

You can also use a second version of async method with SoapServiceResponse protocol.

Please notice how we get access to errors (especially Soap faults returned by web service)

3. Configure the service properties

Many settings related with the service is in RequestResultHandler (which is not directly available). So to change some properties of this class you should create a new class which inhertis from you service class and override CreateRequestResultHandler method. See the example: Here BasicHttpBinding_IBodyArchitectAccessService is a service class generated by EasyWsdl.

4. How to send/receive a large binary data?


Typical SOAP web service has some limitation in sending a large binary data (like images, videos, documents, etc). Problem is that the binary data are base64-encoded and added to XML message body. Many XML parsers cannot parse very well huge in size documents. To address this issue there is a possibility to send binary data as an attachment (outside the SOAP message body). Of course Web service has to support this feature (MTOM transfer/attachment).

So if your web service supports MTOM transfer then you can use EasyWSDL to generate classes with attachment support. To do this you should select Add MTOM transfer in generator page. Please remember to add MIMEKit library to your project (you will find it in libs folder in generated zip file)

By default MTOM transfer is disabled. To enable it you should set EnableMTOM to TRUE in your service class:

service.EnableMTOM=TRUE;


7. How to use any collection?


Some web services use <any> element to return/retrieve any type of data. The schema (structure) of these data is unknown so EasyWSDL are not able to generate a strongly typed fields for them. Instead, there is one field any which is a collection of DDXMLElement objects and using it you can still retrieve or send such data in a raw format. Here you will find example how to retrieve and send data using any collection.

Sending data
Retrieving data


8. How to implement a Basic authentication


To implement a basic authentication in iOS you can go to RequestResultHandler class and there is a method didReceiveAuthenticationChallenge. The implementation could looks like this:

9. DDXMLElement in any collection. Can we have a strong types instead?


In the latest generator we have introduced a feature to detect a strong types in any collections. To use this option, you have to set CreateClassesForAny property in you service class:

service.CreateClassesForAny=TRUE;

With this option, you should find your objects instead of raw DDXMLElement in any collection.

Important

If you still have raw DDXMLElement objects in any collection, you should generate classes with option Advanced settings -> Generate All classes.