FAQ


1. Generator ends with error "Wsdl contains external file which cannot be loaded. File: (filename)". Can I fix this problem?


This problem occurs when you have multi file WSDL, which contains local paths. For example your WSDL can look like this:

Notice that there are two references to external files: one is xml schema definition file (other_types.xsd) and the second is to another wsdl (Web.svc?wsdl=wsdl0). The problem is that the location of those files are localhost. So when you upload such file into EasyWsdl then localhost path is wrong. But you can still generate classes for it but this will require a little bit more work. There are three solutions for this problem:

Solution 1 (recommended)

If you are using Android Studio or IntelliJ IDE for Android app development you can use our new easyWSDL plugin which simplify generation process.

Here you will find a tutorial how to use our plugin.

Solution 2 (easy)

You can use our WsdlUtil application to generate a zip file which you can use to generate classes.
  1. Download and run WsdlUtil application (requires .NET Framework 4.0 or Mono)
  2. Put an url to your WSDL file in WSDL Url box
  3. In Output ZIP you must specify the name and location for generated zip file
  4. Click Generate ZIP button. After a few seconds in your Output location you should have a zip file.
  5. Now go to Generate page and upload zip file to our service in Upload a WSDL file box.
  6. Click Generate button to generate classes for your web service

Solution 3 (more difficult)

  1. Create a folder and put your WSDL file in it with *.wsdl extension (for example main.wsdl)
  2. Open it in Notepad and find all external file links (find all schemalocation and location attributes). Copy each link and paste it into Web Browser. Next save opened file into the same folder. Do this for every external file. In our cases I would do this twice (one to save Web.svc?wsdl=wsdl0 and second for other_types.xsd).
  3. After this in your folder you should have a few files. In my example I have Main.wsdl, other_types.xsd and Web10.wsdl.
  4. Now open you WSDL file and remove all wrong paths and leave file names only, so in my example:

       location="http://localhost:40678/WebService/Web.svc?wsdl=wsdl0" -> location="Web10.wsdl"

       schemaLocation="http://localhost:40678/WebService/other_types.xsd" ->schemaLocation="other_types.xsd"

  5. Now zip content of this folder
  6. Upload this zip file. We must do one more thing. There is a small issue with my zip file. It contains two files with *.wsdl extension and EasyWsdl cannot determine which file is a starting point. To fix this please put your Main.wsdl filename in Url text box and then you are ready to generate your classes.


2. Generate classes for many wsdl files


In some cases you have a few web services which share some common types. If you generate classes for each web service separately, you will end up with duplicated classes.

The latest version of easyWSDL generator allows you to specify more than one wsdl file. In this case all shared types will be generated only once.

To specify more than one wsdl file you need to create JSON file which looks like this:

In this file we have specified 3 different wsdl files. This JSON file now we can upload to easyWSDL generator instead of wsdl file. NOTE: For now this feature is supported by our website only. You cannot use the JSON file with our Android Studio/IntelliJ Plugin

Additionally you can specify additional schema files which should be processed by the generator

In this example we have added rules.xsd file that needs to be included in the generation process.

Important

In most cases when you include additional schema files, you should generate classes with option Advanced settings -> Generate All classes. This is important if your web service have <any/> elements because this ensure that all types from your wsdl/xsd files will be generated.

If you are trying to generate classes for ONVIF web services, here you can download a JSON file with all wsdl files.

The same technique you can use if you have wsdl files on your local machine only. In this case, you can put this json file into the zip. Here you can download a zip file with all ONVIF wsdl files



3. I have an idea or a suggestion about a new feature in easyWSDL. Where can I report it?


If you see a way to improve easyWSDL, then don't hesitate to inform us. We constantly looking for improvements. This could be anything, like:

  • New output language - for now we generates Java, Objective-C and Swift code. But if you need soap client in any other language, please let us know.
  • New improvements in generated classes - our soap client are pretty powerful. They support many different options like MTOM transfer. But if you need something else, inform us!
  • New improvements in easyWSDL website - this could be anything, like custom themes, additional login provider...
  • New IDE plugin or improvements in existing - for now we have a easyWSDL plugin for Android Studio/IntelliJ. But we could create more...

You can send your ideas on two way: by sending email or submit it here. We cannot guarantee that we will implement every feature or suggestion, but for sure we will investigate it!

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 every time 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 occurs 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.


11. How to add custom SOAP headers?


The easiest way is to create a custom class which inherits from the generated service class. Then override createEnvelope method and set correct soap headers. In the code you should use this custom class to invoke a web service. Here is an example:



12. How to set a cookie from the response (cookie management)?


The easiest way to maintain a cookies between requests is to use CookieManager class. Basically put these two lines at the start of your application

More info you can find here


13. How to create custom Date/Time handler?


If you find that easyWSDL classes handle date/time in a wrong way, you can create a custom provider. First step is to create a converter class, where you could override one or more methods:

Next is to create an instance of this class and set it into ExtendedSoapSerializationEnvelope. You need to do this before you connect to your webservice.

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 inherits 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;


5. 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


6. 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:


7. 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.


8. How to add custom SOAP headers?


The easiest way is to create a custom class which inherits from the generated service class. Then override createEnvelope method and set correct soap headers. In the code you should use this custom class to invoke a web service. Here is an example:



9. How to create custom Date/Time handler?


If you find that easyWSDL classes handle date/time in a wrong way, you can create a custom provider. First step is to create a converter class, where you could override one or more methods:

Next is to create an instance of this class and set it into RequestResultHandler.

If you need change Time Zone only, you can set it by accessing StandardDateTimeConverter instance and set TimeZone property.

All these changes you need to do this before you connect to your webservice.

Important

Check also Objective-C FAQ. Solution in SWIFT should be similar.

1. I have generated Swift classes but still I see some code in Objective C. Why?


easyWSDL generates all classes in SWIFT language. But still we are using external libraries (KissXML and MIMEKit) which are written in Objective C (they haven't been ported to SWIFT yet). If there will be swift versions of these libraries, we will use them in our generator. But for now we have to use Objective C libraries.


2. 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.


3. How to create custom Date/Time handler?


If you find that easyWSDL classes handle date/time in a wrong way, you can create a custom provider. First step is to create a converter class, where you could override one or more methods:

Next is to create an instance of this class and set it into RequestResultHandler.

If you need change Time Zone only, you can set it by accessing StandardDateTimeConverter instance and set timeZone property.

All these changes you need to do this before you connect to your webservice.

1. 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 apache-mime4j-*.jar libraries 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 createRequestResultHandler 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 every time 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.



2. 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


3. 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:


4. BinaryObject.underlayingObject or BinaryObject.stream 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 ByteArray, Stream and more. Only ByteArray can be stored in Parcel, the all other objects not (like streams) and because of this after you restore BinaryObject from a Parcel, underlayingObject or stream returns null, therefore we recommend to invoke underlayingObject first, store returned object (eg stream) in a variable and then put BinaryObject to a Parcel.


5. How to add custom SOAP headers?


The easiest way is to create a custom class which inherits from the generated service class. Then override createRequestResultHandler method and set correct soap headers. In the code you should use this custom class to invoke a web service. Here is an example:



6. How to set a cookie from the response (cookie management)?


The easiest way to maintain a cookies between requests is to use CookieManager class. Basically put these two lines at the start of your application

More info you can find here


7. How to create custom Date/Time handler?


If you find that easyWSDL classes handle date/time in a wrong way, you can create a custom provider. First step is to create a converter class, where you could override one or more methods:

Next is to create an instance of this class and set it into RequestResultHandler. You need to do this before you connect to your webservice.



7. How to configure/change connection provider


By default easyWSDL uses HttpURLConnection to all network operations. If you need set any properties of this object before sending request, you can override the existing connection provider class and set some properties:

Now you can inject an instance of this provider directly into your service class

You can also create a custom connection provider and use another library for network communication (for example HttpClient). In this case you need to implement ConnectionProvider interface. See the implementation of HttpConnectionProvider class from the generated zip as example.

An unhandled error has occurred. Reload 🗙