Team Developer 3.0 Web Services Toolkit White Paper

By Suren BehariProduct Manager

September 2003

Page 2

Table of Contents

Understanding XML Web Services .............................................. 3Overview ...................................................................................................... 3How XML Web Services Work ............................................................... 3Providers and Consumers ...................................................................... 6How it Works .............................................................................................. 7Summary ...................................................................................................... 7

Creating an XML Web Service ..................................................... 8Team Developer COM Server as an XML Web Service ................. 8The Web Services Definition Language ............................................. 9About the WSDL/WSML Generator ....................................................... 9Using the WSDL/WSML Generator ..................................................... 10Toolkit API Architecture ....................................................................... 10Exposing Web Services ......................................................................... 11To use the GUI version of the WSDL/WSML Generator .............. 12The Final Product .................................................................................... 18Summary .................................................................................................... 19

Discovering an XML Web Service .............................................. 20Discover the XML Web Service .......................................................... 20The UDDI Browser Utility ..................................................................... 21Summary .................................................................................................... 24

Consuming an XML Web Service ............................................... 25Overview .................................................................................................... 25Create a Proxy ......................................................................................... 25Create an Instance and Invoke .......................................................... 25Available Protocols ................................................................................ 26Proxy Clients and WSDL File ............................................................... 26The Sal Proxy Generator Utility ......................................................... 27The Clients ................................................................................................ 30Summary .................................................................................................... 32

Download Web Services Toolkit ................................................ 33Setup Instructions ...................................................................... 33Requirements: ............................................................................ 33Limitations and Liabilities ......................................................... 33

Page 3

Understanding XML Web Services

OverviewAs businesses have embraced the Internet as a means for communicating with each other, the need for easy to implement, Internet-based information exchange has grown. Businesses need to be able to exchange information, whether it be sales data, order information, or any other business data we can think of, in an efficient, and preferable entirely electronic format. Over the past few years many technologies have been used for this, such as Microsoft’s Distributed Component Object Model (DCOM) and Sun’s Remote Machine Integration (RMI), but none of them was particularly easy to implement, and they did not address the needs of disparate systems using different operating systems, languages and architectures. The concept of Internet-based data exchange has been growing, and XML Web Services are the newest technology in this arena.

XML Web Services are designed to enable disparate systems the ability to communicate and exchange data with one another, regardless of their operating system, language, or architecture. Essentially, a Unix-based system could easily exchange data with a Microsoft .NET-based system.

Team Developer’s Web Services Toolkit enables the easy construction of XML Web Services that can be consumed by any application that has access to the URL of the XML Web Service. The consuming application could be a Web application, a Windows application, a console application, or anything else we can dream up that can access the XML Web Service URL.

How XML Web Services WorkXML Web Services are pieces of program logic that are exposed publicly, either on an intranet, extranet, or the Internet. They enable disparate systems to exchange data using Internet standards such as HTTP, XML and SOAP. The integration of these Internet standards is critical to the acceptance and success of XML Web Services. By implementing the use of standards, XML Web Services become accessible to any client, regardless of their system or architecture. This infrastructure supports the exchange of data in a format that can be used by .NET applications and non-.NET applications, since the data exchange is done using XML, which is text-based, and can be used (to some degree) by any system. Since XML is self-describing, the data exchanged is immediately useful, and easily interpreted.

Basically XML Web Services are black boxes of programming logic that abstract the functionality away from the consuming application. The consuming application only needs to know how to invoke the XML Web Service, and what to expect in return. Beyond that the consuming application is oblivious to what is happening in the XML Web Service. As developers we can build applications that expose methods over the Internet, in the form of XML Web Services. The implementation of these methods is done through cross-Internet calls to the method using HTTP

XML Web Services are designed to enable disparate systems the ability to communicate and exchange data with one another, regardless of their operating system, language, or architecture.

XML Web Services are black boxes of programming logic that abstract the functionality away from the consuming application.

Page 4

or HTTPS, and accepting the return values as XML. The data exchange can occur using one of three protocols:

HTTP GET - XML Web Services are invoked using a basic GET request over HTTP. Any inputs are passed in the query string. The results are returned as an XML document.

HTTP POST - XML Web Services are invoked using a basic POST request over HTTP. Any input values are passed in the HTTP POST body. The results are returned as an XML document.

SOAP - XML Web Services can be invoked using a SOAP message passed over HTTP. Any inputs are passed in the SOAP message body, and the return values are passed in the body of a new SOAP message.

For XML Web Services that take in or return simple data types, such as strings or integers, any input arguments can be passed to the method as HTTP GET (query string), HTTP POST (form post) values, or in the body of a SOAP message. For XML Web Services that either take in or return complex types, such as DataSets, images, or objects, method arguments are serialized to XML and sent and received in the body of a SOAP message.

An XML Web Service can be exposed for the intended user, whether that is the world as a whole, a private client, or for use internally on an intranet, by either telling the client where to find the XML Web Service (the URL), or by registering the XML Web Service in the Universal Description, Discovery and Integration (UDDI) database. UDDI is a global organization trying to broaden the acceptance and use of XML Web Services; UDDI is essentially a registry for XML Web Services. Potential clients can search the UDDI registry to find XML Web Services that match their business needs.

When an XML Web Service is created, a Web Service Description Language (WSDL) document is created with it. The WSDL is essentially a contract that a consumer agrees to, which specifies the exposed methods of invoking the XML Web Service, the inputs expected, and the outputs that will be returned. The URL for the WSDL is listed in the UDDI registry; so potential clients can discover it. If we are privately informing a client about the XML Web Service, the URL for the WSDL is all they need to implement the XML Web Service (although a document explaining what the XML Web Service is for may be nice). The WSDL contains all the information needed to invoke the XML Web Service.Figure 1 shows a partial WSDL:

The WSDL describes the inputs, including data type and name, and the outputs, also including data type and name, for HTTP GET, HTTP POST and SOAP invocation.

Page 5

Figure 1.

The WSDL describes the inputs, including data type and name, and the outputs, also including data type and name, for HTTP GET, HTTP POST and SOAP invocation.

As long as the XML Web Service interfaces do not change, the WSDL will remain the same. This means that the XML Web Service provider can make changes to the logic, as long as the inputs and outputs don’t change, and the client will not be affected. For example, as a provider of an XML Web Service, we can change what database we are connecting to, or how the logic performs, provided the expected inputs and outputs do not change, and the client will never know we made the change.

Page 6

Providers and Consumers

XML Web Services are based around the concept of a provider and a consumer. The provider is the application that exposes the XML Web Service, and the consumer is an application that uses the XML Web Service. The user of an application should never see the XML document returned from an XML Web Service. Rather, the application consumes the XML Web Service, and uses the data to provide output to the application user. For example, an XML Web Service that retrieves a company name given a company id, would return an XML document that looks like Figure 2:

<?xml version=”1.0” encoding=”utf-8” ?> <GetCustomerInfo xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd=”http://www.w3.org/2001/XMLSchema” xmlns=”’http://suren/IslandWebService/”> <CompanyID>105</CompanyID> <CompanyName>Zanzibar Limited</CompanyName > </GetCustomerInfo>

Figure 2.

The application user shouldn’t ever see the XML document that is returned. In the application we would write code to invoke the XML Web Service, and display the returned values to a user in a format appropriate to our application, as in Figure 3.

Figure 3.

The Web application acts as the consumer, invokes the XML Web Service, receives the XML data returned, and displays it appropriately for the user.

Page 7

How It WorksFigure 4 below shows the communication between the consumer and the provider.

Figure 4.

A consumer application connects to an XML Web Service provider. The steps that occur are as follows:• The consumer finds an available XML Web Service either in the UDDI registry, or directly from the provider (not shown). • The consumer makes a request to the provider for the WSDL document. • The provider returns the XML-based WSDL document. • The provider makes a request to the XML Web Service in the WSDL document, passing in any required arguments as defined in the WSDL. • The provider processes the request, performing any functions necessary to complete the request, and returns the result to the consumer as either an XML document, or a SOAP message.

SummaryXML Web Services provide the infrastructure for exchanging data between disparate systems, enabling the automation of simple functionality, or critical business processes. An XML Web Service is basically a black box, abstracting functionality away from a consuming application by exposing only the necessary interfaces, and performing all of the processing on the provider system. In Part II I will discuss how to create a simple Web Service using Team Developer and the WSDL Generator.

Page 8

Creating an XML Web ServiceIn Part I we discussed XML Web Services from a high-level, and saw how Consumers and Providers communicate. In Part II we will build a basic XML Web Service using Team Developer. As we progress we will get into building more complex XML Web Services, but...we have to start somewhere.

Team Developer COM Server as an XML Web ServiceXML Web Service files are identified by the, wsdl extension. These files do not define any user interface, only the class and methods of the XML Web Service. It is important to keep in mind that the intended consumer of an XML Web Service is another application, not a person, so the user interface is not important, but the class interface is. We will walkthrough the process of creating the Web Service and generating this wsdl file.

You can write COM automation servers with Team Developer and create non-visual business objects. You use the Interface and the CoClass outline types to write COM servers. Through COM automation, clients can call methods that you write in the Interface.

Figure 5.

The CoClass merely derives from the Interface (Figure 6):

You can write COM automation servers with Team Developer and create non-visual business objects.

Page 9

Figure 6In this XML Web Service we create an Interface, IISOInfoServer, as a XML Web Service, and expose one method, GetCustomerInfo(). The method takes in a Number value, the CompanyID, and returns company information. This is an incredibly basic XML Web Service, but it does show what is necessary to make one. This XML Web Service can be invoked using HTTP GET, HTTP POST or SOAP protocols. The input argument is a simple type, a Number, so any of the three protocols will work. When invoked, this XML Web Service will return an XML document with the String values.

The purpose of this Part of the paper is to demonstrate the generation of the wsdl file for the Web Service, so I will not elaborate on the details of the COM Server creation.

The Web Services Definition LanguageThe Web Services Description Language (WSDL) is an XML format for describing the network services offered by the server. You use WSDL to create a file that identifies the services provided by the server and the set of operations within each service that the server supports. For each of the operations, the WSDL file also describes the format that the client must follow in requesting an operation. Since the WSDL file sets up requirements for both the server and the client, this file is like a contract between the two. The server agrees to provide certain services only if the client sends a properly formatted SOAP request.

About the WSDL/WSML GeneratorDepending on the services and operations the server supports, writing your own Web Services Description Language (WSDL) and Web Services Meta Language (WSML) files can be tedious. Therefore, the Microsoft Simple Object Access Protocol (SOAP) Toolkit 3.0 provides a tool, the WSDL/WSML Generator that generates these files for you.

As input to the WSDL/WSML Generator, you simply have to provide a DLL file that implements all the operations the server supports. Before using the generator, make sure to register this DLL and that the DLL has a type library.

With the DLL as input, the WSDL/WSML Generator goes through the type library object and provides you a list of COM object interfaces in the DLL. You then select the appropriate COM object(s), and the generator produces the appropriate WSDL and WSML files.

The Web Services Description Language (WSDL) is an XML format for describing the network services offered by the server.

Page 10

Using the WSDL/WSML GeneratorThe WSDL/WSML Generator tool is useful for creating your own Web Services Description Language (WSDL) and Web Services Meta Language (WSML) files. While you do not have to use this generator tool, you may find that this tool saves you from the potentially tedious process of creating WSDL and WSML files.

There are two ways in which to run the WSDL/WSML Generator: • If you want to use a graphical user interface (GUI), use wsdlgen.exe to generate the WSDL and WSML files. • To use a generator tool that can be used in script files and setup programs, use the command line tool, wsdlstb.exe. This command line tool allows you to select multiple interfaces and methods within an interface. For syntax, type wsdlstb.exe /? at the command prompt.

Toolkit API ArchitectureThe SOAP toolkit is made up of two main parts that can be used together or independently. The first part is the client, which is made up of several COM components that allow you to invoke SOAP-based Web services. The second part is made of the server components used to expose Web services, usually implemented as COM components. A client application calls a Web service using the SOAP toolkit’s client API as shown in figure 6. The toolkit’s client reads the WSDL describing the Web service and handles creating the SOAP message and sending it in an HTTP request to the Web server. On the server, you can choose to use an ASP page or an ISAPI extension as the listener for incoming requests. This listener captures the request and invokes the toolkit’s SoapServer30 component which handles instantiating the appropriate COM component and invoking the requested method. SoapServer30 relies on information in a .wsml file to determine the ProgID of the component to instantiate and the DispID of the method to call. WSML is a toolkit-specific XML file format for providing additional information needed to invoke the Web service. After invoking the COM component’s method, SoapServer30 then takes the return value and any ByRef parameters and creates the response SOAP message. The Web server then sends this response message back to the client as the HTTP response.

Figure 6.

The WSDL/WSML Generator tool is useful for creating your own Web Services Description Language (WSDL) and Web Services Meta Language (WSML) files..

Page 11

The toolkit provides a high-level API which makes it almost trivial to expose and invoke Web services by encapsulating all the SOAP message creation and parsing. For cases where you need more control, the toolkit also exposes a low-level API that allows you to control every aspect of SOAP messages and therefore requires extra coding. This high level of control sometimes comes in handy when trying to interoperate with Java-based and other Web services.

Exposing Web ServicesFrom a business standpoint, there are great benefits to be gained by exposing existing COM-based server components as Web services. The most obvious benefit is easier integration with other platforms. Most business functions today span multiple supporting applications running on several platforms. Integrating those applications can improve the overall business process by removing or reducing some of the seams and gaps in existing solutions.

Businesses can also benefit from exposing existing data to other applications rather than people. In the past 6 to 7 years there’s been an explosion of intranet applications designed to make business information readily available to more workers. A typical Web application’s architecture is based on a COM-based middle tier with an ASP based front end. If this describes your applications, you’ve already done the hard part: You’ve created business logic and data access code in the form of COM components. To extend the reach of your application, you can expose these existing components (or some of them) as Web services for consumption by other applications rather than people. Doing this increases the usefulness of existing multi-tier applications and allows other systems to nicely integrate with your systems (back to integration again).

Finally, a huge business benefit is the ease of deployment of client applications. Again, if you’ve built the server COM components, you’ve already taken care of the server side of things. Exposing these components as Web services makes it easier to deploy clients that require only HTTP access to the server. Simplifying deployment and network configuration translates into saved time (i.e. money) and frustration. So how do you expose existing COM components as Web services?

It’s generally a bad idea to try to expose each COM component as a Web service and each interface method as a Web service operation. Instead, you should design a new layer on top of existing server-side (e.g. MTS or COM+) components as in figure 7. This Web Services Layer (WSL) is a new set of stateless COM components designed to expose the services that clients need in order to perform their business function.

When designing the WSL, think in terms of business services and documents not in terms of object models. For example, don’t design an Order object with properties such as order number, and order amount and methods such as Save, Update, and Delete. Instead, design an OrderMgmt Web service with PlaceOrder and DeleteOrder operations that take in an Order XML document and return an OrderReceipt document. Use XML Schemas to define each of your service documents.

Page 12

Each of the service operations, e.g. PlaceOrder, would aggregate several existing COM components to perform a specific, complete, business function.

The WSL uses the SOAP Toolkit to handle incoming SOAP requests and send outgoing responses. You can use either the high level API or the low level API to do this. I usually recommend using the low level API because it is a consistent API that gives you lots of control over the messages being transmitted. However, there are many cases where the high level API might be sufficient, especially if you are building quick prototypes. For purposes of this paper, I will explain the use of the high level API for exposing and invoking Web services.

Figure 7.

To use the GUI version of the WSDL/WSML GeneratorThe following procedure shows you how to use the GUI version of the WSDL/WSML Generator to create WSDL and WSML files that can be used with the IslandWebService DLL created and registered before.1. On the Start menu, point to Programs, Microsoft SOAP Toolkit version 3. Click WSDL Generator to start the WSDL Generator wizard. 2. On the Welcome to the SOAP Toolkit 3.0 WSDL Generator screen, click Next. (Figure 8)

Page 13

Figure 8.

3. When you launch the wizard, it first asks you whether you want to use an existing configuration file, as shown in Figure 9. When you use the wizard you can save your selections and input to a configuration file then use this file as a starting point the next time you run the wizard. Since this is the first time you run the wizard, you won’t use an existing configuration file.

Figure 9.

4. On the next screen you enter a Web service name (enter ‘IslandWebService’ as the name of your service). This is the nam

Page 14

that the generator tool uses for the WSDL and WSML files.

Figure 10.

5. Click Select COM Object, select the IslandWebService.dll or type library that implements the server object, and then click OK.

Figure 11.

6. Click Next.

7. Select all the objects and methods that you want to appear in the WSDL and WSML files (Figure 12). Then click Next.

Page 15

Figure 12.

When you click next, you get a screen asking you to specify SOAP listener infor-mation (Figure 13). You now get to decide on the type of listener: ASP or ISAPI. Generally, an ISAPI listener is slightly faster than an ASP listener. However, you can learn more from examining the code within an ASP listener, so go ahead and select ISAPI listener for this example.

You must also specify the listener’s URL. Here’s a tip to ensure you enter the right URL here. First, create a folder on your hard drive where you want the listener and other service files to reside, e.g. C:\InetPub\wwwroot\IslandWebSer-vice\ or something like that. Then open the IIS administration console and create a new virtual directory called IslandWebService that maps to the folder you cre-ated are sure to enable directory browsing. To ensure you configured things right, open Internet Explorer and enter the URL to this new virtual directory, e.g. http://suren/IslandWebService. If everything is right, you should see a directory listing of the folder you created which is probably empty at this point.

Page 16

Figure 13.

8. Now copy the URL from IE’s address bar and past it in the wizard’s URI field as shown in figure 13. This is the folder for the WSDL and WSML files. Do not include the files in the URL; the wizard will add the files to this location.

9. Select the listener type (ASP or ISAPI). In our case ISAPI will be used.

10. Click Next.

Page 17

Figure 14.

11. When you click next, you get the screen in figure 14 asking you to specify four URI’s. The first URI is the WSDL target namespace. The second one is the schema target namespace. The third URI is the SOAP operation namespace. Finally, the last URI is the value of the SOAPAction HTTP header.

If you’re building a new Web service (as opposed to implementing a pre-defined Web service interface), the URI values are completely up to you. Just be consis-tent in what you pick and try to use your organization’s Internet domain name if possible.

The next screen (figure 15) asks you to pick the character set to be used for SOAP messages. For maximum interoperability, you should pick UTF-8 unless you know you’ll need to use characters from the UTF-16 character set. You also have to enter two paths. The first is where the generated WSDL, WSML, and ASP files will be saved. This must be the same folder you created and configured as a virtual directory (e.g. C:\InetPub\wwwroot\IslandWebService\). The second path is where the WSDL Generator’s configuration file will be saved. You can choose any folder to store the configuration file and it need not be Web-acces-sible.

Page 18

Figure 15.

12. Select the character set for the WSDL file (UTF-8 in our case). This is the character set used for the WSDL and WSML files (Figure 10).

13. Enter the path to where you want to save the resulting WSDL and WSML files (C:\InetPub\wwwroot\IslandWebService\ in our case), and the path where you want to save the configuration path. Then, click Next. At this point, the generator tool creates and saves the files.

14. Click Finish to exit (Figure 16).

Figure 16.

The Final ProductOnce the WSDL file is generated we can browse to the wsdl file and view the Web methods we exposed (Figure 17).

Page 19

Figure 17.

SummaryIn this part of the paper we looked at how a very basic XML Web Service is built. The most important thing is that you got an understanding of what the WSDL Generator does. In Part III of this paper I will show you how to build a client to consume this XML Web Service.

Page 20

Discovering an XML Web Service

Discover the XML Web ServiceThe discovery of an XML Web Service will typically be done on a business-to-business level. In other words, two businesses will agree to exchange data using an XML Web Service, and the provider of the service will inform the consumer about where to find the service.

Another means of discovering an XML Web Service is by using the Universal De-scription, Discovery, and Integration service (http://www.uddi.org). This is a regis-try of XML Web Services provided by a number of different companies. Currently two member companies of UDDI, Microsoft and IBM, provide search engines for finding an XML Web Service that suits your need. Businesses that are exposing XML Web Services can be listed in the UDDI registry, detailing information about the company and the XML Web Services they are making available.The result of the discovery process should be the URL to the Web Service Description Language (WSDL) document. The WSDL is an XML document that describes the XML Web Service. This is basically the contract that the consumer agrees to; the WSDL states:

1. The URL for invoking the XML Web Service. 2. The Web methods available. 3. The input arguments expected and their data types for each Web method. 4. The output data type for each Web method.

When a method of the proxy is invoked, the proxy calls out to the XML Web Service and invokes the same method.

Page 21

The UDDI Browser UtilityThis utility uses the Microsoft UDDI SDK to interrogate the Microsoft UDDI Regis-tries. When you start up this utility, the dialog in Figure 18 is presented.

Figure 18.

By default, Microsoft’s Production UDDI Registry is selected for the Web service search. For purposes of the paper, we will use the already registered Service in the Production Registry.

1. Type in Island in the Search for Web Service field and click Refresh List2. Double-click the node http://uddi.microsoft.com/inquire

The node expands, using a wildcard search, with services that have island in their name, as shown in Figure 19.

Page 22

Figure 19.

3. Double-clicking the IslandWebService will expand the node showing more information on the service, as shown in Figure 20.

Page 23

Figure 20.

4. Expand the nodes as shown in Figure 21 to determine the accessPoint or location of the WSDL file.

Page 24

Figure 21.

5. This is all the information we need to consume the Web Service.

SummaryIn this part of the paper we looked at how to discover a Web Service using the UDDI Registry. Part IV will cover how to consume this Web Service from a Team Developer client application. The most important thing is that you got an under-standing of what the UDDI Browser utility does. In Part IV of this paper I will show you how to build a client to consume the XML Web Service built in Part II.

Page 25

Consuming an XML Web Service

In Part II of this paper I showed you how to build a very basic XML Web Service. In this part I will show you how to build a consumer for that XML Web Service.An XML Web Service consumer is an application that invokes the methods of an XML Web Service made available by a provider; the consumer feeds on the data derived from the XML Web Service provider. A consumer application may be an-other Web application, XML Web Service, Windows desktop application, or any other type of application with access to the XML Web Service using HTTP.

OverviewThe steps to consuming an XML Web Service are:1. Discover the XML Web Service. 2. Create a proxy of the XML Web Service. 3. Create an instance of the proxy and invoke a method.

Create a ProxyProxy, by definition, is the function, power, or capacity to substitute for another. This definition is perfect for an XML Web Service proxy. The proxy is a class on the local server that exposes the same interfaces as the XML Web Service. The proxy acts as a local substitute for the XML Web Service, and handles the calls to the XML Web Service to invoke the specified Web method.

Using the included SAL Proxy Generator we can easily create proxy classes with a utility named ProxyGen.exe. This utility is downloadable as part of the Team Developer Web Services Toolkit. The ProxyGen.exe utility is used to parse the XML Web Service WSDL and automatically generate a proxy class for the ser-vice.

Create an Instance and InvokeOnce we have a proxy we can, anywhere in our application, create an instance of the proxy class and invoke one of its methods.

When a method of the proxy is invoked, the proxy calls out to the XML Web Service and invokes the same method. The XML Web Service returns the output to the proxy instance in the consumer application. The proxy can then expose the output data to the original caller as if the method were invoked locally (Figure 22).

The discovery of an XML Web Service will typically be done on a business-to-business level.

Page 26

Figure 22.

Available ProtocolsXML Web Service methods can be invoked using, as of this writing, one of three protocols, HTTP GET, HTTP POST, or SOAP (over HTTP). We will use SOAP as the means of communication between Consumer and Provider.

A SOAP message can be used to invoke the Web method. The inputs are passed to the XML Web Service in the SOAP message body - the return data is passed back to the consumer in the body of a SOAP message. The SOAP message can be passed to the provider using either HTTP or HTTPS.

Proxy Clients and WSDL FileTo build a proxy client we can use the ProxyGen.exe utility - of course we could also code the proxy client ourselves, but why do that when a utility can do it for us. ProxyGen.exe is a GUI utility that we can invoke and it will generate a proxy client class based on the WSDL document of the XML Web Service we are creat-ing a proxy for.

A SOAP message can be used to invoke the Web method.

Page 27

The Sal Proxy Generator UtilityThis utility is a C++ program that extends the Microsoft Soap Toolkit sample by using the WSDLReader, SoapReader, SoapSerializer objects and the Team Developer C++ CDK to generate the SAL Proxy for the Web Service. When you start up this utility, the dialog in Figure 23 is presented.

Figure 23.

1. Click “Browse...” and select a WSDL file using the file system, or enter the URL for a WSDL document and click “Load.” In our case, you will first enter the URL specified for the Web Service created in Part II. Later we will use the accessPoint URL discovered in the previous part.2. Enter http://<yourServerName>/IslandWebSerice/IslandWebService.wsdl and click “Load”.

You will notice that you have a listing for the Web Service, with its Ports and Op-erations (as in Figure 24).

Page 28

Figure 24.

3. Drill down to the service, port, operation you wish to execute or generate a proxy for. You can select an operation and test the service directly from this inter-face before generating the proxy. In our case, drill down and select the “GetCus-tomerInfo” operation (Figure 25).

4. Select the “[in]” operation parameter (nCompanyID, in our case) and enter the value (eg. “105”) that will be sent to the service.

Figure 25.

5. It is also important to select every non-string [in/out] parameter and set a de-fault value as follows:

Page 29

nInvoice_no – 0dtInvoice_date – 9/11/2002dtDate_paid – 9/11/2002nAmount_paid – 0This is important as the web service expects to receive some value for each these parameters. (see Figure 26).

Figure 26.

6. Click “Execute” to test the service (Figure 27).

Figure 27.7. To generate the SAL Proxy, select the operation (GetCustomerInfo), and click “Generate SAL Proxy”.

With some luck, the dialog in Figure 28 should display. The generated code is in SOAPProxy.apl in your AXLibs directory.

Page 30

Figure 28.

The ClientThe client for the IslandWebService XML Web Service is relatively simple, as seen in Figure 29.

Figure 29.

The IslandConsumer has a ComboBox where the user can select a company ID. This value will be used as the input for the GetCustomerInfo() Web method. When the “Go” Button is clicked, it triggers a postback. 1. We create instances of the Functional Classes “IslandWebService” and “cPort”, as shown in Figure 30.

Page 31

Figure 30.

2. We then call the GetPort_ISOInfoServerSoapPort() method of the Island-WebServcie Functional Class, passing in as parameter the instance of the cPort Functional Class.3. Next we call the GetCustomerInfo() method of the instance of the cPort object, passing in the required parameters from the client application (Figure 31).

Figure 31.

4. The Proxy Class takes care of the SOAP implementation, so that it is transpar-ent to the developer.

Make sure that your local Web Server and SQLBase Database Engine are run-ning before executing the IslandConsumer application. You may run this applica-tion in Web Mode through Web Application Manager, as well. Clicking the “Go” button after selecting a CompanyID, produces the results in Figure 32:

Page 32

Figure 32.

SummaryWhile this part dealt with consuming a very simple XML Web Service, the prin-cipals are the same as if we had been consuming a complex XML Web Service. We used a proxy class to expose the XML Web Service’s interface in a local object. With that local object we were able to invoke a method of the XML Web Service and catch the return data as if the method were executed locally.

Page 33

Download Web Services Toolkit

Setup Instructions• Download and install the Microsoft SOAP Toolkit v3.0.• Make sure SQLBase is running with the Island database• Unzip the Web Services Toolikit.zip file into a subdirectory of the Team Devel-oper 2.1 root.• Create a Virtual directory on your Web Server called IslandWebService, that points to the subdirectory created above.• Open the IslandWebService.app - Build the dll and register• Use the Microsoft Soap Toolkit v3.0 to generate the WSDL and WSML files into the Virtual directory - Select the recently registered dll - Use the Virtual directory as the Listener URI and “ISAPI” as the Listener Type • Copy the SOAPProxy.apl to your AXLibs directory• Use the ActiveX Explorer to generate the Microsoft SOAP Type Library v3.0.apl - Select the SoapClient30 CoClass and ISoapClient30 Dispinterface• Use the SalProxyGenerator to test the Web Service and generate code in SOAPProxy.apl - Type in the URI to the WSDL file - Select the GetCustomerInfo function and then the CompanyID input parameter - Type in a value like “105” for the input parameter and click Set Parameter - Click Test Web Service - Generate the Proxy• Open IslandConsumer.app (Windows/Web App) and run

Requirements:• Team Developer 3.0 • SQLBase• Microsoft SOAP Toolkit v3.0 (Download from Microsoft)

Limitations and LiabilitiesThe UDDI Browser and Sal Proxy Generator utilities are NOT GUPTA Technolo-gies products and are therefore not supported by Gupta Technologies LLC.

Copyright © 2004 Gupta Technologies LLC. GUPTA, the GUPTA logo, and all GUPTA products are licensed or registered trademarks of Gupta Technologies, LLC. All rights reserved.

All other trademarks are property of their respective owners.”

Gupta Technologies, LLC975 Island DriveRedwood Shores, CA 94065 USAPhone +1-650-596-3400Fax +1-650-596-4690