ksoap2-android Documentation

ksoap2-android is a lightweight and efficient SOAP client library specifically optimized for the Android platform. It is a fork of the original kSOAP2 library. While primarily tested on Android, it is compatible with other platforms that support Java libraries.

Compatibility Notes:

• Versions up to 3.4.0 use Java 1.3, making them suitable for JavaME, BlackBerry, and older environments.
• Versions beyond 3.4.0 require Java 1.5 or higher.

The library provides several ways to manage how null values are represented in the generated SOAP XML:

• Skip null properties: You can configure the library to skip properties with null values entirely, meaning they are not rendered in the output XML at all (added in 3.2.0).
• Control null representation: There is a feature to control the specific representation of a null value within a SOAP message (added in 3.3.0).

ksoap2-android provides granular control over network timeouts and response handling:

• Timeouts: Since version 3.6.3, you can differentiate between read timeouts and connection timeouts.
• HTTP Status Codes:
  • The library accepts 202 status codes (added in 3.6.2).
  • You can retrieve the HTTP response code from a Call() object even when the response code is not 200 (added in 3.1.0).
  • HttpResponseException can store all HTTP headers from the response (added in 3.5.0).

The library supports advanced XML features for SOAP:

• Attributes:
  • Supports the HasAttributes interface for classes to hold attributes (added in 3.2.0).
  • Supports SoapSerializationEnvelope to serialize attributes from any class inheriting from AttributeContainer (added in 3.2.0).
  • Improved handling for attributes and inner text for tags (added in 3.4.0).
• Namespaces:
  • Supports namespace extensions (added in 3.5.0).
  • Supports different namespaces and prefixes for attribute values, even when the value and attribute are in different namespaces (added in 3.4.0).

The primary sources for technical documentation are the Javadoc and the source code.

• Maven/Gradle Users: Javadoc and source JARs are typically hooked up automatically in your IDE, allowing you to browse documentation and implementation details during development.
• Ant/Eclipse Users: You may need to manually download the source and Javadoc JAR files to view them in your environment.
• GitHub: The source repository contains numerous test cases that serve as practical examples for common tasks, such as creating SOAP requests and parsing results.

To use ksoap2-android in a Maven project, add the dependency to your pom.xml. If you are not using a repository manager, you must also define the Sonatype release repository in your pom.xml or settings.xml to allow Maven to locate the artifacts.

Repository URL: https://oss.sonatype.org/content/repositories/ksoap2-android-releases/

<dependencies>
  <dependency>
    <groupId>com.google.code.ksoap2-android</groupId>
    <artifactId>ksoap2-android</artifactId>
    <version>3.6.4</version>
  </dependency>
</dependencies>

<repositories>
  <repository>
    <id>ossrh</id>
    <url>https://oss.sonatype.org/content/repositories/ksoap2-android-releases/</url>
  </repository>
</repositories>

Additional libraries are available as separate dependencies. For example, to use NTLM support, add the ksoap2-extra-ntlm artifact using the same group ID and version as the core library.

<dependency>
   <groupId>com.google.code.ksoap2-android</groupId>
   <artifactId>ksoap2-extra-ntlm</artifactId>
   <version>3.6.4</version>
</dependency>

To send binary data like an image or PDF, you must enable MarshalBase64 by registering it with the envelope. This ensures the byte array is correctly encoded as a Base64 string in the XML.

Requirements:

• Register new MarshalBase64().register(envelope).
• Set envelope.encodingStyle = SoapEnvelope.ENC;.
• Add the byte[] directly to your SoapObject property.

byte[] fileData = convertDocToByteArray(path);
request.addProperty("FileFirma", fileData);

SoapSerializationEnvelope envelope = new SoapSerializationEnvelope(SoapEnvelope.VER11);
new MarshalBase64().register(envelope);
envelope.encodingStyle = SoapEnvelope.ENC;

envelope.setOutputSoapObject(request);

HttpTransportSE transport = new HttpTransportSE(URL);
transport.call(SOAP_ACTION, envelope);

For secure communications, ksoap2-android provides several capabilities:

• Custom SSLFactory: You can set an SSLSocketFactory for HTTPS connections, which is useful for using self-signed certificates (added in 2.6.3).
• HTTPS Transport: Dedicated HTTPS transport support was added in version 2.5.2.
• Proxy Configuration: Support for proxy configuration using HttpsTransportSE was added in 3.0.0-RC.4.

To contribute to the ksoap2-android codebase, ensure you have the following pre-requisites installed:

• Apache Maven: Version 3.1.1 or higher is required. Alternatively, you can use the provided mvnw wrapper scripts.
• Java IDE: Any IDE is supported for testing and debugging.
• Version Control: git or svn to clone the repository, or you can download the source as a ZIP file.