WebReference.com - Chapter 30 of Curl Programming Bible, from John Wiley & Sons (2/8)

[previous] [next]

Curl Programming Bible, chapter 30

Making a SOAP Call

Consider a Web service that returns a stock quote. The service takes as input a string containing the stock symbol and returns its price. Below is a code sample calling such a Web service. The following sample calls the SOAP operation with the string GE (the stock symbol for General Electric) and displays the stock price returned.

...
{import * from CURL.XML.SOAP}
{let get-quote:Soap-1-1-HttpOperation = 
        ...
}
{let anys:{Array-of any} =
    {get-quote.call "GE"}
}
The stock price of General Electric is {value anys[0]}

The Curl SOAP support is in the CURL.XML.SOAP package. The package must be explicitly imported by applets that use it. You do this by adding {import *from CURL.XML.SOAP} to your applet.

A variable (get-quote) of the class Soap-1-1-HttpOperation is initialized to describe the SOAP operation (more on this below).

The call method of Soap-1-1-HttpOperation makes the SOAP call. The arguments of the call method are the input arguments of the SOAP call. In the example above, the call method has one argument (GE) which is passed as an input argument to the SOAP call.

The call method returns an array of any. The call method returns an array rather than a single result because SOAP operations may return more than one output argument. The SOAP operation described by get-quote has only one out-put argument: the stock price corresponding to the stock symbol given as the input argument. The stock price is returned as the first element of the array.

Describing SOAP Operations

We used the call method of the Soap-1-1-HttpOperation above to make a SOAP call. Before the call method can be invoked, you must call the class constructor supplying information to describe the SOAP operation. The information includes the URL of the SOAP server, the contents of the SOAPAction HTTP header field, and the operation name. Here is the code to initialize an instance of Soap-1-1-HttpOperation corresponding to the SOAP operation that returns a stock quote:

          {let get-quote:Soap-1-1-HttpOperation = 
    {new Soap-1-1-HttpOperation,
        || operation name
        {new XMLName, "", "getQuote"},
        || URL of the SOAP server
        {url "https://64.39.29.211:9090/soap" },
        || SOAPAction value in HTTP headers
        "urn:xmethods-delayed-quotes#getQuote",
        input-arguments,
        output-arguments
    }
}

The name of the corresponding SOAP operation is getQuote. This is used as the tag name of the element surrounding the input arguments in the SOAP request message. The URL of the SOAP service is https://64.39.29.211:9090/soap. The SOAP request message will be sent as the body of an HTTP POST to this URL when the SOAP call is invoked. And the value of the SOAPAction HTTP header field is "urn:xmethods-delayed-quotes#getQuote ". All SOAP requests sent over HTTP contain a SOAPAction field in their HTTP header. The SOAPAction field can be used by servers such as a firewall to filter SOAP request messages sent over HTTP.

Soap-1-1-HttpOperation also contains information about the SOAP operation's input and output arguments. In the example above, input-arguments describes the input argument and output-arguments describes the output argument.

Describing SOAP Arguments

The Soap-1-1-StandardArgumentDescriptor class is used to describe the arguments of a SOAP operation. You must supply a Soap-1-1-StandardArgumentDescriptor for each input and output argument. A SOAP-1-1-StandardArgumentDescriptor has four fields:

• name
• curl-type
• xml-type
• encoding-style

The name field contains the name of the argument. All arguments to SOAP operations are named. The name is used as a tag name for the element that encloses the argument in the SOAP message.

The curl-type field is the Curl type of the argument. For input arguments, it is the expected type of corresponding argument in the Soap-1-1-HttpOperation.call method. For output arguments, it is the type of corresponding argument in the array returned by the call method.

The xml-type is the type of the argument as passed in the SOAP message. The SOAP encoding style uses a type system that incorporates all the built-in data types of XML Schema.

For every combination of xml-type and curl-type in the argument descriptors, there must be a mapping that converts between XML type and Curl type. Curl supplies mappings for a subset of the XML Schema built-in data types to the corresponding Curl types. The mappings are enumerated in the next section. Mappings between XML types and Curl types include a marshaler and unmarshaler. Input arguments are converted from the Curl type to the XML type by a marshaler. Output arguments are converted from the XML type to the Curl type by an unmar-shaler. Users may supply additional mappings between XML types and Curl types. A section below describes how to do this.

The default value for encoding-style is https://schemas.xmlsoap.org/soap/encoding/, the URI that identifies the SOAP encoding rules.

Here are the argument descriptors for the previous example:

{let constant xsd:String = "https://www.w3.org/2001/XMLSchema"}
{let input-arguments:{Array-of Soap-1-1-ArgumentDescriptor} =
     {new {Array-of Soap-1-1-ArgumentDescriptor},
         || one input argument named symbol of XML type string
         || corresponding to Curl type String.
         {new Soap-1-1-StandardArgumentDescriptor,
             {new XMLName, "", "symbol"},
             {new XMLName, xsd, "string"},
             String
         }
     }
}
{let output-arguments:{Array-of Soap-1-1-ArgumentDescriptor} =
     {new {Array-of Soap-1-1-ArgumentDescriptor},
         || one output argument named Result of XML type float
         || corresponding to Curl type float
         {new Soap-1-1-StandardArgumentDescriptor,
             {new XMLName, "", "Result"},
             {new XMLName, xsd, "float"},
             float
         }
     }
}

Notice the input-arguments and output-arguments fields of Soap-1-1-HttpOperation are arrays of argument descriptors. They are arrays because there may be multiple input arguments and multiple output arguments to a SOAP RPC. The order of the descriptors in the array is important. The order of the descriptors in the input-argument array correspond to the order of the actual arguments in the call method. Similarly, the descriptors in the output-arguments array correspond to the index of the argument in the array returned by the call method.

The complete Curl applet (stock-quote.curl) that calls the stock quote service is on the accompanying Web site.

[previous] [next]

Created: August 14, 2002
Revised: August 14, 2002

URL: https://webreference.com/programming/curlbible/chap30/2.html