Advanced Topics in Web Services

Working with Messages

Sometimes it is useful to work directly with the request message that is sent to a web service. This message may be retrieved using the ToServiceRequest function. ToServiceRequest is called by providing a web service function as the first parameter and its parameters as the additional parameters. The function will not invoke the web service operation. Rather the function will return the symbolic XML representation of the request message that would generally be sent to the web service.

A user may change the request message to have different values or different attributes. In fact, the user may create an entirely new message. However, the message must still follow the format specified in the SOAP specification. Using ToServiceRequest gives the user a nice starting point. The request message can then be invoked using the InvokeServiceOperation function. The first parameter of this function is the endpoint URI or the symbol representing a web service function. The web service function specifies the endpoint URI internally along with other options for invoking the service. The second argument is the symbolic XML representation of the request message.

The result of this call is the response message. Sometimes it is useful to work directly with the response message. However, web service functions by default return a deserialized version of the response message. The original response message may be retrieved using the InvokeServiceOperation function. The first parameter is the web service function, and the function's parameters follow. InvokeServiceOperation invokes the service and returns the entire response message in symbolic XML. This will allow the user to customize how the data is deserialized into Wolfram Language representation.

Once a web service function is called using InvokeServiceOperation, the results come back in the form of a SOAP envelope. FromServiceResponse can be used to extract the results from the SOAP envelope. The data will be deserialized into the proper Wolfram Language types specified by the operation symbol.

Working without a WSDL

Web services will work without a WSDL file, and sometimes the user may be forced into a situation where a WSDL file is not available. Although it is much more convenient to use web services with a WSDL file, it is possible to use the Wolfram Language web services client without a WSDL. A user can build the SOAP message from scratch in the Wolfram Language using symbolic XML.

ToServiceRequest can also be used to build a SOAP message using XML Schema definitions. DefineSchema can be used to define type definitions for a web service. In this example, the IntegrateString web services have a root element of IntegrateString, have a namespace of http://localhost:8080/webMathematica/Examples/WebServices/Integrate.m, and take a string named str as a parameter.

NewSchemaInstance can be used to create an instance of the type just defined and this can be passed into ToServiceRequest, which takes two parameters. First, it takes a list of parameters for the body of the message. Second, it takes a list of parameters for the header.

ToServiceRequest supports two options as well. First, OperationName can be used to wrap an element that identifies a web service operation around the parameters. This is often useful when using RPC-style web services or when mapping document-style web services to functions. Second, EncodingStyleURI may be used to set the encoding style. The only encoding style supported is SOAP encoding as demonstrated next. This adds type attributes to the parameters.

InvokeServiceOperation can then be used to invoke the service with the message that has been generated. InvokeServiceOperation requires two parameters. First the endpoint is required, which specifies the URL where the message will be sent. The second parameter is the message. A couple of options are supported as well. SOAPActionURI may be used to set a SOAP Action header. TransportStyleURI may be used to set the transport style (although http is the only transport currently supported). Username and Password may be used for authentication and Timeout may be used to set a timeout.

FromServiceResponse can be used to process a SOAP message using XML Schema definitions. DefineSchema can be used to define a return type for a web service. In this example, the IntegrateString returns an element with a string named element. FromServiceResponse takes the message as a parameter and the option ReturnType is used to specify the return type.

InstallServiceOperation can be used to install these definitions as a Wolfram Language function. It takes a symbol as its first parameter that the function definition will be associated with. It takes a URL as its second parameter that will define where a message is sent. The third parameter is a list of parameters for the function. These parameters are defined using XML Schema element definition symbols defined using DefineSchema. The fourth parameter is a list of header parameters. Finally, options may be used. Each option from ToServiceRequest, InvokeServiceOperation, and FromServiceResponse is valid.

Once the function is installed, it may be used just like other functions installed using Web Services Link.

Debugging

Web Services Link provides a few symbols that can help in debugging. The debugging symbols are defined in the following table.

Debugging symbols.