Skip to content

Class: cClientWebService

Properties | Events | Methods | Index of Classes

The base class for all client web-services

Hierarchy

cObject > cClientWebService

Show full hierarchy and direct subclasses

Library: Common Class Library

Package: cClientWebService.pkg

Description

See cClientWebService12 for web services using SOAP 1.2.

Within a DataFlex windows application, a web service is accessed by:

  1. Generating a sub-class that provides access to a web-service.

This class, which will be automatically generated by accessing to the web-service's description. The new class will contain a method interface (function name and parameters) that matches the interface of the actual web-service.

  1. Creating an object within your program that is based on this sub-class.

This is accomplished by selecting the web-service class from the Studio's control palette and dropping it into your view.

  1. Calling the function within this client object.

The object will convert your function into a SOAP request and send it to the server. When it gets a response from the server it will unpack the SOAP response and place the data into the function's return value.

SOAP Headers

The SoapHeaderResponseNode, ClearSoapHeaders, AddSoapHeaderNode and SoapHeaderRequestNode methods provide a low level mechanism for working with SOAP headers.

Creating a Client Web-Service Class

The cClientWebService class is used as the basis for all client web-services. This class knows how to handle generic SOAP messages. Each web-service has its own definition and therefore each web-service will be represented on the client side as a sub-class, based on cClientWebService. These custom classes contain functions that correspond to the functions that exist in the actual service.

A tool, the Web-Service Client Class Generator is provided for automatically creating client web-service classes. This class generator requires that you provide it with the location of a web-service's description (its WSDL location). The tool will parse the WSDL document and create a sub-class based on that information. It will create the class and all additional files required to integrate the class directly in the Studio so that it can be accessed from the Studio's Control Palette.

Adding a Client Web Service Object to your Application

Once a web service client sub-class has been created it can be added to any program in the same manner that any object is added to a DataFlex application. You will need to find your web-service class in your Control Palette, grab it and drag and drop it into your component.

Calling a Web-Service

If you look at the client web-service object that was created you will see that the service's interface is shown as part of the object's documentation. These interfaces will appear as standard functions consisting of a function name, parameter data-types and names, and a return data-type. A web service is called, by sending a message to this object (i.e., you just call the function). The object will take this local function call, turn it into a proper SOAP request and make the needed HTTP request to the server. The server will process the request and send back a SOAP response. The client object will take this response, parse it and set up the return value or, if needed, handle any error messages. As a developer, you will see none of this. You will simply be calling a method within an object and getting return value.

Methods from cClientWebService that you might use in your sub-class

When you a web-client sub-class you will usually just access the methods defined for this sub-class. There are a few methods from the cClientWebService class that you may use:

The property pbSuppressLastError determines if errors encountered during a web-service call should be reported.

The property peTransferStatus returns the error status of the last web-service call.

The function TransferErrorDescription can be used to return the error text for any transfer status error.

The properties psFaultString and psFaultString can be used to return SOAP Fault information

The procedure LastError can be sent to manually display error information about your last web-service call.

The property phoSoapClientHelper can be used along with the WebClientHelper.vw view to display debug information about a web-service call.

The properties phoSoapRequest and phoSoapResponse can be used to access the raw information about a web-service request and response.

The property psServiceLocation contains the URL location of the web-service.

User name and Password

If the Http site hosting the web service requires that you login, you must provide a username and password. You do this using the psUserName and psPassWord properties. This information is not added to the WSDL so it must be added manually by the programmer.

HTTPS/ Secure SSL Sites

Secure HTTPS sites are supported. If the URL in psServiceLocation contains "HTTPS" the object will recognize that this is an secure site and will change the default port to rpHttpSSL (443) and will set the appropriate transfer flag in the http object. When your web-service client is created, this information should be contained in your WSDL and the generated client class will automatically support this.

In some cases a client certificate may be required for a secure site. This information is not stored in the WSDL. The programmer will need to select the certificate by setting the properties psCertificateStore and psCertificateSubject

Using the cClientWebService Class without the Class generator

Because the class is generated automatically for you, you do not need to know much about the cClientWebService class. Most of the public methods in this class will not be used by the developer. They will just call the custom methods created in their sub-class. For this reason, this class might almost be considered to be abstract and most of the methods could be considered to be private. However, this class could be used by the developer for advanced purposes such as using the class to support dynamic client web-service access (i.e., using the same object to access multiple web-services). In such as case, much can be learned by studying the sub-classes created by the class generator - this will show you how the cClientWebService class is used.