SOAP
Overview
“SOAP Version 1.2 (SOAP) is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment. It uses XML technologies to define an extensible messaging framework providing a message construct that can be exchanged over a variety of underlying protocols. The framework has been designed to be independent of any particular programming model and other implementation specific semantics.” - Definition from SOAP Version 1.2 Part 1: Messaging Framework (Second Edition) - W3C Recommendation 27 April 2007
Because of its implementation independence, the SOAP protocol is widely used on the implementation of Web Services.
The SOAP Class
This class represents a SOAP message that, when executed, is sent to the server in a HTTP request. The server response is then received, processed, and the answer made available.
Before creating a instance of SOAP, you may set the following class fields:
The prefix string used to start the request. Note that it uses UTF-8, so unicode characters are not supported. Its default value is:
suffix The suffix string used to finish the request. Its default value is:
debug Changing this value to true enables debug mode, which writes XML parsing information on the debug console (or the default error output when running on JDK). You may also set HttpStream.debugHeader = true. Caution: don’t use this on device because it increases a lot the memory usage.
disableEncoding The SOAP request will ask the server for GZip or ZLib encoded response by default. To disable encoding, set this field to true.
Constructors
To create a new SOAP instance, you must use the following constructor:
Type | Name | Description |
constructor | SOAP(String mtd, String uri) | Creates a new SOAP request where mtd specifies the remote method to be executed, and uri, the address of the Web Service. The default namespace will be used, along with an open timeout of 25 seconds, and a read and write timeout of 60 seconds. |
Instance Fields
After creating a new SOAP object, you may set some of its following instance fields:
Type | Name | Description |
boolean | wasCompressionUsed | A flag that indicates if the SOAP connection was using either GZip or ZLib. This is a ready-only flag, set during the execute() method, and changing its value has no effect. |
String | alternativeReturnTag | By default, the XML parser used by SOAP will recognize as an answer tag any tags whose name ends with “result” or “return” (ignoring the case). This field, if set, specifies an alternative answer tag name, recognizing any XML element that ends with the specified value as an answer tag. AlternativeReturnTag IS CASE SENSITIVE, unlike the SOAP default tag names. Also, alternativeReturnTag does not replace the default values. It’s just a new value with higher priority over the default ones. |
String | namespace | String that identifies the service’s namespace. Its default value is: http://schemas.xmlsoap.org/soap/. |
int | openTimtout | Specifies the connection open timeout value in milliseconds. Its default value is defined by the constant DEFAULT_OPEN_TIMEOUT (25 s). |
int | readTimeout | Specifies the connection read timeout value in milliseconds. Its default value is defined by the constant DEFAULT_READ_TIMEOUT (60 s). |
int | writeTimeout | Specifies the connection write timeout value in milliseconds. Its default value is defined by the constant DEFAULT_WRITE_TIMEOUT (60 s). |
String | mtd | Stores the name of the remote method. |
String | uri | Stores the address to the Web Service. |
You may change both the mtd and the uri values before executing the request. Although this seems to be pointless, because these values are passed to the constructor.
If the remote method expects any arguments, you must set them using the setParam() method. However, there are several versions of this method to cover different argument types. Listing all of them would be pointless, so we’ll define a generic type that we’ll refer as , and may be one of the of the following:
int
boolean
double
String
So, whenever a SOAP method is described like setParam( param), you can safely assume there are four versions of this method, one for each type listed above. Other type of parameters can be passed using similar methods. Unicode characters are not accepted because the default header uses UTF-8.
SOAP methods for parameters setting:
Type | Name | Description |
void | setParam( param) | Sets the given value in the method’s argument order. |
void | setParam([] param) | Sets the given array in the method’s argument order. |
void | setParam( param, String paramName) | Sets the given value, identifying it with the given parameter name. |
void | setParam([] param, String paramName) | Sets the given array value, identifying it with the given parameter name. |
void | setParam(byte[] param, String paramName) | Sets a byte array value, identifying it with the given parameter name. |
void | setParam(String param, String paramName, String paramType) | Sets a String parameter in the method, identifying it with the given name and specifying its type as the given one. |
void | setParam(String[] param, String paramName, String paramType) | Sets a String array value, identifying it with the given parameter name and specifying its type as the given one. |
void | setObjectParam(String paramName,String[] fieldNames, String[] fieldValues) | Sets an Object parameter value, by specifying its parameter name, field names and field values. |
void | setObjectArrayParam(String paramName,String[] fieldNames, Vector fieldValues) | Sets an Object array parameter value, by specifying its parameter name, field names and field values. |
The only thing left to do now is to execute the request and check the service’s answer:
Type | Name | Description |
void | execute( ) | This method simply executes the prepared SOAP request. |
Object | getAnswer( ) | To retrieve the method’s answer, you must call this method after execute(). The return type of this method is Object, but it may return only three different values (the values may be escaped; use totalcross.ui.html.EscapeHtml.unescape() to convert it back). The remote method return type is known, so you may just typecast the Object returned by getAnswer() to String or String array, converting its values if necessary. The possible returns are: 1- null When the remote method has no return value or the execution failed for any reason. 2- String When the remote method returns a single value. If the expected value is not String, you must convert the received String to the right type (e.g. if you’re expecting an int value, you can use Convert.toInt()). 3- String[] When the remote method returns an array or an Object. If the expected value is not a String array, you must convert each value of the array to the right type. If it’s an object, the array contains its field values. |
void | useProxy(String address, int port, String username, String password) | Sets the proxy settings to be used by the SOAP connection. You may optionally set the username and password for basic proxy authorization. Proxy authorization is disabled if either username or password is null. In this method, address is the proxy address port and port is the proxy port. |
References
For more details, check out the totalcross.xml.soap package JavaDocs.
Last updated