Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Artifact ID: | 47d21faeb55edeecfae1b6b28d9866be0b5f32bd |
---|---|
Page Name: | WSClient Client Side |
Date: | 2012-06-11 23:54:55 |
Original User: | gwlester |
Parent: | 1129fc076458e7b46e07b0b35157f1e2b3bf699b (diff) |
Next | c2c5fc52f1606b175a214b240279c89fa8af538e |
Calling a Web Service from Tcl
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:
- Loading a pre-parsed WSDL
- Quering a remote Web Services Server for its WSDL and parsing it
- Parsing a saved WSDL
- Defining a REST based service by hand
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:
- Synchronous Call returning a dictionary object
- Synchronous Call returning the raw XML
- Asynchronous Call with separate success and error callbacks
- Creation of stub Tcl procedures to make synchronous calls
This package makes use of the log package from TclLib. In particular the following levels are used:
- error/warning -- errors encountered when parsing a WSDL. Actual level depends on options that are set in the ::WS::Utils package.
- info -- HTTP calls, including the XML, made to invoke operations and the replies received. Introduced in 2.2.8.
- debug -- detailed internal information. This should only be used if you want to code dive into the TclWs package internals.
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
- contentType -- default is "text/xml;charset=utf-8"
- suppressTargetNS -- boolean indicating if target namespace is not to be added to XML. Derived from options. Default is 0 (do not suppress).
- skipLevelWhenActionPresent -- boolean indicating if the first level of the XML is to be skipped. Derived from options. Default is 0 (do not skip).
- skipLevelOnReply -- boolean indicating the first level of the XML in a reply may be skipped. Derived from options. Default is 0 (do not skip). (Introduced in 2.2.8)
- location -- The URL of the service, derived from the WSDL.
- targetNamespace -- the target namespace of the service, derived from the WSDL.
Returns :
The value of the item.Side-Effects : None
Exception Conditions : None
Pre-requisite Conditions : Service must have been defined.