WSClient Client Side
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.

Calling a Web Service from Tcl


Contents

Overview

The Webservices Client package provides a several ways to define what operations a remote Web Services Server provides and how to call those operations. It also includes several ways to call an operation.

The following ways are provided to define remote operations:

The parsed format is much more compact than the XML of a WSDL.

The following ways are provided to directly call an operation of a Web Service Server:

This package makes use of the log package from TclLib. In particular the following levels are used:

Loading the Webservices Client Package

To load the webservices server package, do:

 package require WS::Client

This command will only load the utilities the first time it is used, so it causes no ill effects to put this in each file using the utilties.


Quering a remote Web Services Server for its WSDL and parsing it

Procedure Name : ::WS::Client::GetAndParseWsdl

Description :

Arguments :

     url     - The url of the WSDL
     headers - Extra headers to add to the HTTP request. This
                 is a key value list argument. It must be a list with
                 an even number of elements that alternate between
                 keys and values. The keys become header field names.
                 Newlines are stripped from the values so the header
                 cannot be corrupted.
                 This is an optional argument and defaults to {}.
     serviceAlias - Alias (unique) name for service.
                     This is an optional argument and defaults to the name of the
                     service in serviceInfo.

Returns : The parsed service definition

Side-Effects : None

Exception Conditions : None

Pre-requisite Conditions : None


Parsing a saved WSDL

Procedure Name : ::WS::Client::ParseWsdl

Description : Parse a WSDL

Arguments :

     wsdlXML - XML of the WSDL

Optional Arguments:

     -createStubs 0|1 - create stub routines for the service
                             NOTE -- Webservice arguments are position
                                     independent, thus the proc arguments
                                     will be defined in alphabetical order.
     -headers         - Extra headers to add to the HTTP request. This
                        is a key value list argument. It must be a list with
                        an even number of elements that alternate between
                        keys and values. The keys become header field names.
                        Newlines are stripped from the values so the header
                        cannot be corrupted.
                        This is an optional argument and defaults to {}.
     -serviceAlias - Alias (unique) name for service.
                      This is an optional argument and defaults to the name of the
                      service in serviceInfo.

Returns : The parsed service definition

Side-Effects : None

Exception Conditions :None

Pre-requisite Conditions : None


Loading a pre-parsed WSDL

Procedure Name : ::WS::Client::LoadParsedWsdl

Description : Load a saved service definition in

Arguments :

     serviceInfo - parsed service definition, as returned from
                   ::WS::Client::ParseWsdl or ::WS::Client::GetAndParseWsdl
     headers     - Extra headers to add to the HTTP request. This
                     is a key value list argument. It must be a list with
                     an even number of elements that alternate between
                     keys and values. The keys become header field names.
                     Newlines are stripped from the values so the header
                     cannot be corrupted.
                     This is an optional argument and defaults to {}.
     serviceAlias - Alias (unique) name for service.
                     This is an optional argument and defaults to the name of the
                     service in serviceInfo.

Returns : The name of the service loaded

Side-Effects : None

Exception Conditions : None

Pre-requisite Conditions : None


Defining a REST based service by hand


Service Definition

Procedure Name : ::WS::Client::CreateService

Description : Define a REST service

Arguments :

     serviceName - Service name to add namespace to
     type        - The type of service, currently only REST is supported.
     url          - URL of namespace.
     args         - Optional arguments:
                            This is an optional argument and defaults to the name of the
                                -header httpHeaderList.

Returns : The local alias (tns)

Side-Effects : None

Exception Conditions : None

Pre-requisite Conditions : None

Method Definition

Procedure Name : ::WS::Client::DefineRestMethod

Description : Define a method on a REST service

Arguments :

     serviceName - Service name to add namespace to
     objectName  - The name of the object the method is on
     methodName  - The name of the method to add.
     returnType  - The type, if any returned by the procedure.  Format is:
                           xmlTag typeInfo.
     inputArgs   - List of input argument definitions where each argument
                           definition is of the format: name typeInfo.
where, typeInfo is of the format {type typeName comment commentString}

Returns : The current service definition

Side-Effects : None

Exception Conditions : None

Pre-requisite Conditions : None


Defining Transforms

Procedure Name : ::WS::Client::SetServiceTransforms

Description : Define a service's transforms

               Transform signature is:
                   cmd serviceName operationName transformType xml {url {}} {argList {}}
               where transformType is REQUEST or REPLY
               and url and argList will only be present for transformType == REQUEST

Arguments :

     serviceName  - The name of the Webservice
     inTransform  - Input transform cmd, defaults to {}
     outTransform - Output transformcmd, defaults to {}

Returns : None

Side-Effects : None

Exception Conditions : None

Pre-requisite Conditions : Service must have been defined.


Synchronous Call returning a dictionary object

Procedure Name : ::WS::Client::DoCall

Description : Call an operation of a web service

Arguments :

     serviceName     - The name of the Webservice
     operationName   - The name of the Operation to call
     argList         - The arguements to the operation as a dictionary object
                       This is for both the Soap Header and Body messages.
     headers         - Extra headers to add to the HTTP request. This
                       is a key value list argument. It must be a list with
                       an even number of elements that alternate between
                       keys and values. The keys become header field names.
                       Newlines are stripped from the values so the header
                       cannot be corrupted.
                       This is an optional argument and defaults to {}.

Returns :

     The return value of the operation as a dictionary object.
       This includes both the return result and any return headers.

Side-Effects : None

Exception Conditions :

     WSCLIENT HTTPERROR      - if an HTTP error occured
     others                  - as raised by called Operation

Pre-requisite Conditions : Service must have been defined.


Asynchronous Call with separate success and error callbacks

Procedure Name : ::WS::Client::DoAsyncCall

Description : Call an operation of a web service asynchronously

Arguments :

     serviceName     - The name of the Webservice
     operationName   - The name of the Operation to call
     argList         - The arguements to the operation as a dictionary object
                       This is for both the Soap Header and Body messages.
     succesCmd       - A command prefix to be called if the operations
                       does not raise an error.  The results, as a dictionary
                       object are concatinated to the prefix. This includes
                       both the return result and any return headers.
errorCmd - A command prefix to be called if the operations raises an error. The error code and stack trace are concatinated to the prefix. headers - Extra headers to add to the HTTP request. This is a key value list argument. It must be a list with an even number of elements that alternate between keys and values. The keys become header field names. Newlines are stripped from the values so the header cannot be corrupted. This is an optional argument and defaults to {}.

Returns : Nothing.

Side-Effects : None

Exception Conditions :

     WSCLIENT HTTPERROR      - if an HTTP error occured
     others                  - as raised by called Operation

Pre-requisite Conditions : Service must have been defined.


Creation of stub Tcl procedures to make synchronous calls

Procedure Name : ::WS::Client::CreateStubs

Description : Create stubs routines to make calls to Webservice Operations.

             All routines will be create in a namespace that is the same
             as the service name.  The procedure name will be the same
             as the operation name.
             NOTE -- Webservice arguments are position independent, thus
                     the proc arguments will be defined in alphabetical order.

Arguments :

     serviceName     - The service to create stubs for

Returns : A string describing the created procedures.

Side-Effects : Existing namespace is deleted.

Exception Conditions : None

Pre-requisite Conditions : Service must have been defined.


Synchronous Call returning the raw XML

Procedure Name : ::WS::Client::DoRawCall

Description : Call an operation of a web service

Arguments :

     serviceName     - The name of the Webservice
     operationName   - The name of the Operation to call
     argList         - The arguements to the operation as a dictionary object
                       This is for both the Soap Header and Body messages.
     headers         - Extra headers to add to the HTTP request. This
                       is a key value list argument. It must be a list with
                       an even number of elements that alternate between
                       keys and values. The keys become header field names.
                       Newlines are stripped from the values so the header
                       cannot be corrupted.
                       This is an optional argument and defaults to {}.

Returns :

     The XML of the operation.

Side-Effects : None

Exception Conditions :

     WSCLIENT HTTPERROR      - if an HTTP error occured

Pre-requisite Conditions : Service must have been defined.

Configuring a Service

Procedure Name : ::WS::Client::Config

Description : Configure a service's information

Arguments :

     
     serviceName     - The name of the Webservice
     item   - The item to configure.  Must be one of

     value         - Optional, the new value.

Returns :

     The value of the item.

Side-Effects : None

Exception Conditions  : None

Pre-requisite Conditions : Service must have been defined.