Web Services Client for ILE

Transcription

1 System i Web Services Client for ILE Version 1.0

2 Note! Before using this information and the product it supports, be sure to read the general information under Appendix B, Notices, on page 65. First edition (December 2007) This edition applies to version 5, release 4, modification 0 of IBM i5/os (product number 5722SS1) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 2007, All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents Figures v Tables vii About this book ix Who this book is for ix What you need to know to understand this book..ix Terms used in this book ix Chapter 1. Introduction to Web Services Client for ILE What is Web Services Client for ILE? Client development and deployment Components Chapter 2. The Web Services Client for ILE Installation Prerequisites The Web Services Client for ILE package What is installed Configuring after installation Chapter 3. Developing and deploying web service client applications The wsdl2ws.sh tool Creating client stubs Coding and building client applications Using C++ stubs Using C stubs Client API Deploying web service client applications Chapter 4. Developing and using client side handlers Types of handler Rules for writing handlers Required handler files Developing client side handlers Handler definitions in WSDD file WSDD file path definition in axiscpp.conf file..20 Deploying web service client applications with handlers Chapter 5. Securing web service communications Security information defined in axiscpp.conf file..23 Security information defined using the SetSecure method Chapter 6. Exception handling Exception handling in C SOAP faults defined in a WSDL file Generated stubs Other exceptions Client application Exception handling in C Generated stubs Client application Chapter 7. Memory management Memory management in C XML built-in simple types Arrays of simple type Complex types and arrays of complex type...37 Deep copying Summary of rules Memory management in C XML built-in simple types Arrays of simple type Complex types and arrays of complex type...43 Summary of rules Chapter 8. Floating point numbers Chapter 9. Cookie support Chapter 10. Reference Sample code for mygetquote client application..51 Sample client handler code myclienthandler.hpp myclienthandler.cpp myclienthandlerfactory.cpp WSDD file GSKit configuration settings axiscpp.config file (SecureInfo tag) Client application (SetSecure method) Parameter definition Appendix A. Glossary Appendix B. Notices Trademarks Index Copyright IBM Corp. 2007, 2007 iii

4 iv Web Services Client for ILE

5 Figures 1. Process flow between WSDL source file and C or C++ stubs Process flow between client and server applications using stubs generated by wsdl2ws.sh Process flow between client and server applications using generated stubs, and request and response handlers Installed directory structure mygetquote run from command line Use of handlers in the preparation of a request message Use of handlers in the preparation of a response message mygetquote run from command line (with handlers) Copyright IBM Corp. 2007, 2007 v

6 vi Web Services Client for ILE

7 Tables 1. Required components Installed directories and their contents Available wsdl2ws.sh options Example WSDD file with invocation rules for a service handler Decomposition of example WSDD file Behavior of Web Services Client for ILE with regard to cookie attributes Parameter definitions for secure settings 61 Copyright IBM Corp. 2007, 2007 vii

8 viii Web Services Client for ILE

9 About this book Who this book is for This book is about IBM Web Services Client for ILE, Version 1.0. For the latest information about Web Services Client for ILE, see the product readme.txt file, supplied with Web Services Client for ILE. This book is primarily for application programmers who develop web service applications. Some of the information might also be useful to system administrators who manage systems on which web service applications are developed and deployed. What you need to know to understand this book Terms used in this book To understand this book, you need the following skills, knowledge, and experience: v C or C++ application programming skills. If you are not a C++ programmer, and you want to use the C++ support, you need some knowledge of object oriented concepts and terminology. v A working knowledge of the operating system that you are using. v Experience in using TCP/IP as a communications protocol. v Experience in working with WSDL files. The term OS/400 means OS/400 V5R4, and all subsequent versions, releases, and modifications until otherwise indicated in new editions. Copyright IBM Corp. 2007, 2007 ix

10 x Web Services Client for ILE

11 Chapter 1. Introduction to Web Services Client for ILE This chapter introduces the concepts and tasks involved in developing a web service client application. This chapter consists of the following sections: v What is Web Services Client for ILE? v Client development and deployment v Components on page 4 What is Web Services Client for ILE? Web Services Client for ILE provides a set of libraries and Java tools that enable you to build ANSI C or C++ web service client applications from existing Web Service Description Language (WSDL) files. A web service consists of one or more methods that share a common point of reference, and that can, using SOAP protocols, synchronously communicate with other applications that are enabled in a similar way. The ANSI C or C++ web service client applications that you build from existing WSDL files, using the Web Services Client for ILE libraries and Java tools, are able to communicate with other similarly configured applications over HTTP using TCP/IP with SOAP protocols. The Web Services Client for ILE product has the following capabilities: v Platform independence v Support for WSDL (document literal only) v Support for WSI 1.0 basic profile compliance v Support for SSL v JAX-RPC style implementation Client development and deployment Web Services Client for ILE enables you to manage messaging between a client and web service server. Web services are based on files called WSDLs, which are XML files containing all the information relating to services that are available at a particular location on the internet. At their simplest level, WSDLs describe request and response message pairs in detail, and contain all the information that is relevant to the web service. The Web Services Client for ILE package provides a Java program, the wsdl2ws.sh tool. This tool enables you to turn a WSDL into a suite of C or C++ stubs and data objects that you can call and pass information to, and that request information from the server and then wait for the corresponding reply before passing the response data objects back to the client. The stubs hide the internet communication from the application writer. All you need to know is the name of the service, the method it contains and the structure of any data objects that are passed. There are two distinct ways of using Web Services Client for ILE : IBM Corporation

12 v The first and most commonly used approach is to create a WSDL source file that describes the communication between the client and server, and then use the wsdl2ws.sh tool to generate stubs that you can use to communicate with the web service server. v The second, more specialized approach, is to use the Web Services Client for ILE API to manage messaging between the client and server directly. Both of these approaches work well, but the second approach is not recommended because the client application writer has to be more aware of the API and of the communication protocols between the client and server. Also, if changes are required, the writer has to make the changes to the code manually, which is more prone to error. The recommended implementation is to use a WSDL to describe messages and any associated XSD, and then use the wsdl2ws.sh tool to generate the stubs. The following three diagrams describe the actions that are required to turn a WSDL into a web service using this recommended implementation of Web Services Client for ILE. Generation of client stubs from WSDL source file Figure 1 illustrates the first step, which is to convert the WSDL into a set of C or C++ client stubs that can be called by the client application. WSDL WSDL passed into WSDL2Ws tool that generates C/C++ stubs C/C++ stubs Figure 1. Process flow between WSDL source file and C or C++ stubs Communication between client and server applications As shown in Figure 2 on page 3, the client application that uses C++ stubs calls a method on a service in the stub (a client application using a C stub would call a function, passing an opaque pointer representing the Web service). This method (C++ stub) or function (C stub) calls a number of underlying methods in the AxisClient library, which generates the SOAP message that communicates with the server. 2 Web Services Client for ILE

13 Figure 2. Process flow between client and server applications using stubs generated by wsdl2ws.sh Addition of web service handlers You can add web service handlers to the AxisClient library to allow further processing of the SOAP message, either before it is transmitted to the server or after the corresponding reply has been received from the server. The Web Service Deployment Descriptor (WSDD) file controls how handlers are used. Figure 3 on page 4 is an amended version of Figure 2, showing how handlers can be hooked into the AxisClient library. Chapter 1. Introducing Web Services Client for ILE 3

14 Figure 3. Process flow between client and server applications using generated stubs, and request and response handlers Components Web Services Client for ILE provides a number of required components. Table 1. Required components Component Description wsdl2ws.sh shell script This tool enables you to produce client stubs from WSDL files. Client include files There are a number of common files and libraries that are required to enable the client to compile with the client stubs. Client engine This is a set of libraries that are made available at runtime to the client stubs. SSL support This uses GSKit, IBM s SSL component. 4 Web Services Client for ILE

15 Chapter 2. The Web Services Client for ILE Installation This chapter describes the installation and configuration activities for the Web Services Client for ILE package. This chapter consists of the following sections: v Prerequisites v The Web Services Client for ILE package v What is installed on page 6 v Configuring after installation on page 7 Prerequisites The following prerequisite applications are required: Platform Application Application version OS/400 C++ Compiler Compiler - ILE C++, licensed program product ID 5722WDS, option 52 can be used to compile C and C++ stubs; or for compiling C stubs only, compiler ILE C, licensed program product ID 5722WDS, option 51 Java IBM Developer Kit for Java, JDK 1.4, licensed program product ID 5722JV1, option 6 GSKit Install and configure Digital Certificate Manager licensed program (5722SS1 Option 34). The Web Services Client for ILE package The installation directory for Web Services Client for ILE is /QIBM/ProdData/OS/ WebServices/V1/client. In this chapter, and throughout this documentation, the installation directory is shown as <inst_dir>. When the package has been installed, the installation directory (<inst_dir>) contains the following directory structure: Copyright IBM Corp. 2007,

16 <inst_dir> bin (Windows and OS/400 only) docs api html etc (UNIX and OS/400 only) include axis client lib licenses (Unix and Windows only) prereqs java XML4C (Unix and Windows only) samples getquote handlers WSDL2Ws What is installed Figure 4. Installed directory structure After the Web Services Client for ILE package has been installed, the supplied samples should be ready to build and run. You can verify this by using the samples to follow the instructions in Chapter 3, Developing and deploying web service client applications, on page 9. The Web Services Client for ILE package, including libraries and Java tools, samples and documentation, is installed within the installation directory, /QIBM/ProdData/OS/WebServices/V1/client. The following table gives an overview of the contents of each directory: Table 2. Installed directories and their contents Installed directory Contents <inst_dir> Contains readme.txt file. <inst_dir>/bin Contains the wsdl2ws.sh shell script that is used to invoke the Java tool in order to generate Web service stubs. <inst_dir>/docs Contains the Web Services Client for ILE (what you are currently reading) documentation in PDF format and the API documentation in HTML format. The PDF version of the documentation is in the <inst_dir>/docs parent directory. The API documentation is in the api subdirectory of <inst_dir>/docs. 6 Web Services Client for ILE

17 Table 2. Installed directories and their contents (continued) Installed directory Contents <inst_dir>/etc This directory level contains an example axiscpp.conf configuration file. <inst_dir>/include Web Services Client for ILE header files, which are required for building web service specific generated stubs. <inst_dir>/lib Contains all of the built libraries needed for building web service specific generated stubs. <inst_dir>/prereqs/java The prerequisite Java jar files that are required for the wsdl2ws.sh tool and that are shipped as part of Web Services Client for ILE. <inst_dir>/samples The location of the samples that accompany Web Services Client for ILE. <inst_dir>/wsdl2ws The Java tool that is used to generate Web service stubs. Configuring after installation After you have installed Web Services Client for ILE, some configuration may be required. After installation is complete, you may need to configure the axiscpp.conf file to match your installation. The axiscpp.conf file is located in <inst_dir>/etc. The following code shows the supplied default template configuration file. # The comment character is # # Available directives are as follows # # ClientWSDDFilePath: The path to the client WSDD # SecureInfo: The GSKit security information # You only need to change this file if you are using handlers with your web service client application, or if you are securing your web service communications using SSL. If you are not adding handlers or SSL, you do not need to change this file. If you are using the axiscpp.conf configuration file, you must create an environment variable that gives the location of axiscpp.conf to the Axis client library. This variable is called AXISCPP_DEPLOY. To carry out the post installation configuration for Web Services Client for ILE, complete the following steps. 1. If you are adding handlers or SSL, configure the axiscpp.conf file as described in Chapter 4, Developing and using client side handlers, on page 15 and Chapter 5, Securing web service communications, on page If an application requires its own axiscpp.conf file, you must: a. Create a directory. b. Copy the <inst_dir>/etc directory and directory contents into the newly created directory. Chapter 2. The Web Services Client for ILE Installation 7

18 c. Set AXISCPP_DEPLOY using the CL command ADDENVVAR as follows: ADDENVVAR ENVVAR(AXISCPP_DEPLOY) VALUE( <MYINSTALL_DIR> ) where <MYINSTALL_DIR> is the newly created user directory. You are now ready to begin developing and deploying web service applications. 8 Web Services Client for ILE

19 Chapter 3. Developing and deploying web service client applications The wsdl2ws.sh tool This chapter describes how to develop and deploy web service client applications. To develop a web service client application, you first create the client stubs from your WSDL source file, then code and build your application. If you are not using handlers, then you are ready to deploy your application. If you are using handlers, see Chapter 4, Developing and using client side handlers, on page 15 before deploying your application. This chapter consists of the following sections: v The wsdl2ws.sh tool v Creating client stubs v Coding and building client applications on page 10 v Client API on page 12 v Deploying web service client applications on page 13 The wsdl2ws.sh tool enables you to generate client stubs from a WSDL source file. The wsdl2ws.sh tool uses the WSDL that is passed to it, and any associated XSD files, to create either the client or server side stubs. The code within the stub methods handles the interface with Web Services Client for ILE and provides you with one or more classes (that is, one class per service) with methods that equate to the message names in that service. To run the wsdl2ws.sh tool, use the following command: <install-dir>/bin/wsdl2ws.sh Below is a list of the options that are available to you when you are using wsdl2ws.sh: Table 3. Available wsdl2ws.sh options Option Description -o<folder> The target output directory. The default is the current directory. -lc Generate C stubs. The default is to generate C++ stubs Creating client stubs For an example of how to use wsdl2ws.sh, see Creating client stubs. Before you can create a web service client application, you must first generate the client stubs using the wsdl2ws.sh tool. It is assumed that the WSDL that you are using to create client stubs is valid and well formed. IBM Corporation

20 The steps below use an example WSDL that comes from the installation Web Services Samples provided with WebSphere Application Server (Version 5.0 or later). This very simple sample provides a good introduction to using wsdl2ws.sh. To generate the client stubs from your WSDL source file, complete the following steps. 1. Change the directory to the one in which you want to build the client stubs, for example, <inst_dir>/samples/getquote. 2. Run the wsdl2ws.sh tool to generate the client stubs. To do this, use a command as shown in the following example, which creates C++ stubs in the <inst_dir>/samples/getquote directory. <inst_dir>/bin/wsdl2ws.sh GetQuote.wsdl -omygetquote The command above generates C++ stubs. To generate C stubs simply add the -lc option to the command. The stubs from GetQuote.wsdl are generated in the sub-directory mygetquote, which is within the <inst_dir>/samples/getquote parent directory. If you leave them in this directory, they will be ready for you to use when working through the instructions in Coding and building client applications. Now that the C++ stubs have created, you can begin coding and building a client application. Coding and building client applications After you have generated the client stubs from your WSDL source file, you can use these stubs to create a web service client application. The wsdl2ws.sh tool places the files that it generates from WSDL in an output directory. By default, the target output directory is the current directory, but you can specify a different directory by using the -o option when you run wsdl2ws.sh. You can then create a web service client application by using the appropriate build command to create an executable file. The following steps illustrate what you need to do to create an application, using the example of the client stubs generated from GetQuote.wsdl by the wsdl2ws.sh tool as described in Creating client stubs on page 9. Assuming that the generated client stubs files are still in the mygetquote sub-directory within the <inst_dir>/samples/getquote parent directory, you can now use these stubs to create a web service client application. When you are working with the sample files, note the following points: v GetQuote.wsdl has only one service called getquoteservice. v The service only has one port type called StockQuote. v The StockQuote port type has only one operation called getquote. For C++ stub generation, this operation has the following method signature: xsd float getquote( char * pszstockquotename) For C stub generation, the function prototype is as follows: xsdc float getquote( AXISCHANDLE ws, char * pszstockquotename) v The web service is called StockQuote. For C++ stub generation, the web service is implemented as a class of the same name. You can create either a dynamic or static instance of the class and then call any available public method. For C stub generation, a function is created with the following prototype: 10 Web Services Client for ILE

21 AXISCHANDLE get_stockquote_stub(const char* pchendpointuri) The return value is an opaque pointer representing the web service that is then passed on to the web service operation. Using C++ stubs In the following steps, it is assumed that the generated stubs are C++ and the new project that you are building is called mygetquote, and that all components are in a directory called mygetquote. The mygetquote.cpp file contains the client application, along with the automatically generated StockQuote.cpp and StockQuote.hpp. The code for the client application is shown in Sample code for mygetquote client application on page 51. To build the mygetquote client application, complete the following steps. 1. Change the current working directory to where the project mygetquote is to be built (for example, <inst_dir>/samples/getquote/mygetquote). 2. Using any text editor, create a.cpp file: a. Create a new file named mygetquote.cpp. b. Copy the C++ version of the example code in Sample code for mygetquote client application on page 51 into the new file. c. Change the ServerName and PortNumber to match your server. If WebSphere Application Server is on your own machine and the default values have been used, ServerName is localhost and portnumber is d. Save the new file in the current directory. 3. Build the client application by using the following commands. CRTCPPMOD MODULE(MYLIB/mygetquote) SRCSTMF( mygetquote/mygetquote.cpp ) INCDIR( /qibm/proddata/os/webservices/v1/client/include ) ENUM(*INT) CRTCPPMOD MODULE(MYLIB/GetQuote) SRCSTMF( mygetquote/stockquote.cpp ) INCDIR( /qibm/proddata/os/webservices/v1/client/include ) ENUM(*INT) CRTPGM PGM(MYLIB/MYGETQUOTE) MODULE(MYLIB/MYGETQUOTE MYLIB/GETQUOTE) BNDSRVPGM(QSYSDIR/QAXIS10C) 4. Check that a mygetquote executable file has been created. For additional information about developing web service client applications, see Client API on page 12. When you have finished coding and building your web service client application, you are ready to deploy and test the application as described in Deploying web service client applications on page 13. Note: If you want to use one or more handlers with your application, see Chapter 4, Developing and using client side handlers, on page 15. If you are using handlers, you must deploy your application as described in Deploying web service client applications with handlers on page 21. Using C stubs In the following steps, it is assumed that the generated stubs are C and the new project that you are building is called mygetquote, and that all components are in a directory called mygetquote. The mygetquote.c file contains the client application, along with the automatically generated StockQuote.c and Chapter 3. Developing and deploying web service client applications 11

22 Client API StockQuote.h. The code for the client application is shown in Sample code for mygetquote client application on page 51. To build the mygetquote client application, complete the following steps. 1. Change the current working directory to where the project mygetquote is to be built (for example, <inst_dir>/samples/getquote/mygetquote). 2. Using any text editor, create a.c file: a. Create a new file named mygetquote.c. b. Copy the C version of the example code in Sample code for mygetquote client application on page 51 into the new file. c. Change the ServerName and PortNumber to match your server. If WebSphere Application Server is on your own machine and the default values have been used, ServerName is localhost and portnumber is d. Save the new file in the current directory. 3. Build the client application using the following commands. CRTCMOD MODULE(MYLIB/mygetquote) SRCSTMF( mygetquote/mygetquote.c ) INCDIR( /qibm/proddata/os/webservices/v1/client/include ) ENUM(*INT) CRTCMOD MODULE(MYLIB/GetQuote) SRCSTMF( mygetquote/stockquote.c ) INCDIR( /qibm/proddata/os/webservices/v1/client/include ) ENUM(*INT) CRTPGM PGM(MYLIB/MYGETQUOTE) MODULE(MYLIB/MYGETQUOTE MYLIB/GETQUOTE) BNDSRVPGM(QSYSDIR/QAXIS10CC) 4. Check that a mygetquote executable file has been created. For additional information about developing web service client applications, see Client API. When you have finished coding and building your web service client application, you are ready to deploy and test the application as described in Deploying web service client applications on page 13. Note: If you want to use one or more handlers with your application, see Chapter 4, Developing and using client side handlers, on page 15. If you are using handlers, you must deploy your application as described in Deploying web service client applications with handlers on page 21. The Axis client API provides further methods in addition to those methods that the client stubs use. Examples of ways in which you might use these further methods include for adding proxy information to a web service, and for applications that initialize multiple stubs or calls. Although the quickest way of creating web service client applications is to start with a WSDL and use wsdl2ws.sh to create the client stubs, the methods that the stubs use are only a part of the available AxisClient API. For more information about all the methods that the AxisClient API provides, open the file index.html in the api sub-directory within the <inst_dir>/docs parent directory. The following sections provide some examples of ways in which you can use methods that the AxisClient API provides. 12 Web Services Client for ILE

23 Proxy information for a web service An example of how you might want to build on the Stock Quote sample referred to in this documentation is by adding proxy information to the web service. To do this for a C++ stub, you must add the following lines of code after creating the web service object and before calling any web service methods: // If your network requires the use of a proxy, then add the following line of // code to configure AxisClient. /* char * pszproxyurl = "<ProxyHost>"; int iproxyportnumber = <ProxyPort>; pwsstockquote->setproxy( pszproxyurl, iproxyportnumber); */ For a C stub, you would need to add the following lines after creating the web service stub and before calling any web service functions: // If your network requires the use of a proxy, then add the following line of // code to configure AxisClient. /* char * pszproxyurl = "<ProxyHost>"; int iproxyportnumber = <ProxyPort>; */ axiscstubsetproxy(pwsstockquote, pszproxyurl, iproxyportnumber); Axis::initialize and Axis::terminate Applications that initialize multiple stubs or calls before using them must call Axis::initialize() before calling any Web Services Client for ILE methods, and must call Axis::terminate after the last call to a Web Services Client for ILE method. Applications that use Web Services Client for ILE in multiple threads must also use Axis::initialize and Axis::terminate. If you are using C stub support, the equivalent APIs to Axis::initialize and Axis::terminate are axiscaxisinitialize and axiscaxisterminate. Deploying web service client applications When you have finished coding and building your web service client application, you are ready to deploy and test the application. Use this task to deploy applications that do not use handlers. Before deploying a client application, you must first make the following checks: v That the AXISCPP_DEPLOY environment variable points to <inst_dir>, as described in Configuring after installation on page 7. The steps below use the example mygetquote client application, and assume that a GetQuote service is running. (This service is with the samples supplied with WebSphere Application Server Version or later). If you do not have the appropriate service, you must create the service code from the WSDL in the samples directory. This task applies to client applications that do not use handlers. If your application does use handlers, see Deploying web service client applications with handlers on page 21 instead. Chapter 3. Developing and deploying web service client applications 13

24 Once you have confirmed the above prerequisites, run and test the client application by completing the following steps. 1. Run the mygetquote application. 2. Check that the mygetquote application has returned the price of IBM shares in dollars. The example screen shot below shows the mygetquote application run from the command line. > mygetquote The stock quote for IBM is $94.33 > Figure 5. mygetquote run from command line 14 Web Services Client for ILE

25 Chapter 4. Developing and using client side handlers Types of handler This chapter describes how to develop client side handlers for use with your web service client applications, and how to deploy applications that use handlers. Client side handlers are optional. You only need to use handlers if you need to alter the SOAP header of a request SOAP message before the message is transmitted, or the SOAP header of a response SOAP message before the body of the message is deserialized. Note: Only the SOAP header can be changed inside the request or response handler. This chapter consists of the following sections: v Types of handler v Rules for writing handlers on page 17 v Required handler files on page 18 v Developing client side handlers on page 18 v Deploying web service client applications with handlers on page 21 Web Services Client for ILE supports the use of handlers, which you can use to customize or extend message components. Handlers are invoked either just before a request message is transmitted or just after a response message has been received and can be either service-specific or global. Web Services Client for ILE supports two basic types of handler: v The service handler, which is specific to the web service with which it is associated. v The global handler, which is called regardless of the web service port or message name. From a coding perspective, there are no differences between service and global handlers. The only distinction is where they are specified within the WSDD file. A service handler is associated with a particular service/port combination and is only invoked when a SOAP message with the appropriate destination has been called. A global handler is always invoked, regardless of the message destination. The handler invocation rules are provided by the contents of the WSDD file, and are described in Handler definitions in WSDD file on page 19. The pivot point is the name given to the point where a message is either written on to or read from the wire. The term wire refers to all the underlying components that are responsible for physically sending or receiving a message on the web. Any handler that works on the request message to be transmitted is a pre-pivot handler and conversely, any handler that works on the response message after it has been received is a post-pivot handler. Pre-pivot handlers When a request message is being prepared, the handlers are the last link in the message construction chain, and are invoked just before the message is Copyright IBM Corp. 2007,

26 transmitted, as shown in Figure 6. Start Prepare message by generating SOAP message parts (header, body, etc). Is WSDD defined in axiscpp.conf? Is there a request handler? Are there any service specific handlers? Consecutively invoke the service specific request handlers. (Note: Handlers have access to the SOAP header message.) Are there any global handlers? Consecutively invoke the global request handlers. (Note: Handlers have access to the SOAP header message.) Transmit the request message Return Figure 6. Use of handlers in the preparation of a request message Post-pivot handlers When a response message is being prepared, the handlers are the first link in the message deconstruction chain, and are invoked just after the message is received, as shown in Figure 7 on page Web Services Client for ILE

27 Start Is WSDD defined in axiscpp.conf? Is there a response handler? Are there any global handlers? Consecutively invoke the global response handlers. (Note: Handlers have access to the SOAP header message.) Are there any service specific handlers? Consecutively invoke the service specific response handlers. (Note: Handlers have access to the SOAP header message.) Process the response message Return Figure 7. Use of handlers in the preparation of a response message Rules for writing handlers When you are writing handlers, there are a number of rules that you must follow to ensure that your handlers function correctly. Handlers must conform to the rules listed below: v One or more handlers can be called together for outgoing or incoming requests. They are called in the order in which they appear in the WSDD file. v Each handler must be created as an individual shared library. v Each handler library must have the following export functions. (For an example, see Sample client handler code on page 55.) int GetClassInstance( BasicHandler ** ppclassinstance); int DestroyInstance( BasicHandler * pclassinstance); v The handler must implement the BasicHandler interface. Chapter 4. Developing and using client side handlers 17

28 Required handler files v To allow a handler to be used, you must create or amend the WSDD and axiscpp.conf files to include the appropriate details, as described in Handler definitions in WSDD file on page 19 and WSDD file path definition in axiscpp.conf file on page 20. v If the same handler is to be used on the request and response sides, take care to ensure that the handler is aware of its invoked context (that is, pre-pivot and post-pivot point, as described in Types of handler on page 15). v Handler names must be unique. When you are writing a client side handler, you must create a client handler header file, a client handler file and client handler factory file. The example files supplied with Web Services Client for ILE provide templates that you can use for guidance when you are creating your own handlers. When you are writing a client side handler, you must create the following files: Client handler header file (myclienthandler.hpp) The client handler header file defines the handler object. Client handler file (myclienthandler.cpp) The client handler file defines and has the function for the public methods of the handler that are available to the library loader once an instance of the library has been created by the factory. Client handler factory file (myclienthandlerfactory.cpp) The client handler factory file defines and provides the function for the external methods that are exposed by the library to allow library loaders to create instances of the handler. The templates for the example handler files for the Stock Quote sample are in Sample client handler code on page 55. These templates contain no function, but define what is required to allow a handler to be used with the AxisClient library. Developing client side handlers To develop a client side handler, you first create the required files, which you can do using any text editor, and then build the client library. To create a handler, you first create a client handler header file, a client handler file and client handler factory file. You can then use these files to build your handler library in the same way as you would any other library. If you are writing more than one handler, you must remember to ensure that the handler names are unique. To create and build a handler, complete the following steps, which use the example of the myclienthandler library. 1. Change the current working directory to where the project myclienthandler is to be built (for example, <inst_dir>/samples/handlers). 2. Create the three basic files required for the handler: a. Using any text editor, create three new files named myclienthandler.cpp, myclienthandler.hpp and myclienthandlerfactory.cpp (see Required handler files ). 18 Web Services Client for ILE

29 b. Into each file, copy the sample code described in Sample client handler code on page 55. c. Save the new files in the current directory. 3. Build the handler library: a. Use the following commands: CRTCPPMOD MODULE(MYLIB/mychfact) SRCSTMF( myclienthandlerfactory.cpp ) INCDIR( /qibm/proddata/os/webservices/v1/client/include ) ENUM(*INT) CRTCPPMOD MODULE(MYLIB/mych) SRCSTMF( myclienthandler.cpp ) INCDIR( /qibm/proddata/os/webservices/v1/client/include ) ENUM(*INT) CRTSRVPGM SRVPGM(MYLIB/MYCLH)MODULE(MYLIB/MYCH MYLIB/MYCHFACT) EXPORT(*ALL)BNDSRVPGM(QSYSDIR/QAXIS10C) 4. Check that the client handler library file has been created. 5. Create or amend the WSDD file to include a definition for each handler that you create. For further information about handler definitions, see Handler definitions in WSDD file. 6. Make sure that the axiscpp.conf file includes a line defining the path for the WSDD file. For further information about the file path definition, see WSDD file path definition in axiscpp.conf file on page 20. After you have finished developing your handlers, you are ready to deploy your application as described in Deploying web service client applications with handlers on page 21. Handler definitions in WSDD file If you are using handlers, you must configure the WSDD file, which contains the rules governing when the AxisClient must invoke a handler library. Service handlers and global handlers are defined in separate sections of the WSDD file. The WSDD file is an XML style file containing information that Web Services Client for ILE uses as it builds request messages and decodes response messages. A WSDD file has two main sections, one for service handlers and one for global handlers. For service handlers, each service definition that requires a handler must be defined with the appropriate handler list given for pre-pivot and post-pivot invocation. For global handlers, the WSDD file only needs to list those handlers that are to be invoked pre-pivot and post-pivot. For further information about global handlers see WSDD file on page 59. Example WSDD file The table below shows a line by line example of a WSDD file required to invoke the handler on both the request and response sides. Note that the handler filenames vary according to the operating system. The filenames used in this example are for Windows. Table 4. Example WSDD file with invocation rules for a service handler Line number WSDD line 1 <?xml version="1.0" encoding="utf-8"?> 2 <deployment xmlns=" xmlns:c=" 3 <service name="handler" provider="cpp:document" description="handler"> 4 <requestflow> Chapter 4. Developing and using client side handlers 19

30 Table 4. Example WSDD file with invocation rules for a service handler (continued) Line number WSDD line 5 <handler name="myclienthandlerreq" type="<inst_dir>\samples\handlers\myclienthandler.dll"> 6 </handler> 7 </requestflow> 8 <responseflow> 9 <handler name="myclienthandlerres" type="<inst_dir>\samples\handlers\myclienthandler.dll"> 10 </handler> 11 </responseflow> 12 </service> 13 </deployment> Important WSDD tags The following table describes the important parts of the WSDD file: Table 5. Decomposition of example WSDD file Line number Description 2 The deployment tag is the root element. 3 The service tag defines the type of Axis service. The name attribute defines the name of the service. The provider attribute defines the name of the provider for the service, and must appear in xmlns:c= xml.apache.org/axis/wsdd/providers/c. The description attribute defines a comment for this line. 4 The requestflow tag defines the start of a list of one or more handlers that are invoked when a request message is about to be transmitted. The handlers are invoked in the order in which they appear in the WSDD file. 5 The handler tag within a requestflow defines the unique name of a handler to be invoked, and its type, which is a fully qualified path to the location of the handler. 8 The responseflow tag defines the start of a list of one or more handlers that are invoked when a response message has just been received. The handlers are invoked in the order in which they appear in the WSDD file. 9 The handler tag within a responseflow defines the unique name of a handler to be invoked, and its type, which is a fully qualified path to the location of the handler. For a more detailed description of each tag and the parts that it may contain, see WSDD file on page 59. WSDD file path definition in axiscpp.conf file If you are using client side handlers, you must define the path to the WSDD file in the axiscpp.conf configuration file. If you are using client side handlers, you must add an additional line to the axiscpp.conf configuration file, defining the path to the WSDD file. The mandatory 20 Web Services Client for ILE

31 configuration for the axiscpp.conf file is described in Configuring after installation on page 7. The following example shows the axiscpp.conf file with WSDD information added. # The comment character is # # Available directives are as follows # # ClientWSDDFilePath: The path to the client WSDD # SecureInfo: The GSKit security information # ClientWSDDFilePath:<inst_dir>\conf\client.wsdd The important line of the above example is the first line after the comments, the ClientWSDDFilePath definition. When this line appears in the axiscpp.conf file, Web Services Client for ILE uses this reference to determine which handlers are to be included in the SOAP request/response message parser. Deploying web service client applications with handlers Web service client applications that use handlers need some additional configuration before you deploy them. This section assumes that you have already created and built your handlers by following the instructions in Chapter 4, Developing and using client side handlers, on page 15. The steps below use the example mygetquote client application and assume that a GetQuote service is running. (This service is with the samples supplied with WebSphere Application Server Version 5.0 or later). If you do not have the appropriate service, you must create the service code from the WSDL in the samples directory. Once you have developed a client application as described in Chapter 3, Developing and deploying web service client applications, on page 9, you can add one or more service handlers that can be used as a request or response type. Notes: v Handlers can only modify the SOAP header part of the message. v If the WSDL file that you are using does not specify SOAP actions, then these need to be added to your client application before calling the web service method, if you want the service handler to be invoked (see step 4 below). The method that you use for doing this is settransportproperty, which has the following signature: void settransportproperty( SOAPACTIONHEADER, <ServiceName> ); To deploy an application with handlers, complete the following steps. 1. Locate the Handler library. 2. Check the WSDD file to ensure that it specifies the correct path for the handler as described in Handler definitions in WSDD file on page Add the location of the WSDD file to the axiscpp.conf file as described in WSDD file path definition in axiscpp.conf file on page If the WSDL file that you are using does not specify SOAP actions, change the second parameter (value) in the settransportproperty method to the name of the service in the WSDD file. For example, if the service name is Handler, you must call settransportproperty( SOAPACTIONHEADER, Handler ) on the web service object. Chapter 4. Developing and using client side handlers 21

32 5. Rebuild the mygetquote application. 6. Run the mygetquote application. 7. Check that the mygetquote application has returned the price of IBM shares in dollars. The example screen shot below shows the mygetquote application run from the command line. To enable mygetquote to run as shown below, the required handlers have previously been defined in the WSDD file, and the location of the WSDD file has been defined in the axiscpp.conf file. > mygetquote Before the pivot point Handler can see the request message. Past the pivot point Handler can see the response message. The stock quote for IBM is $94.33 > Figure 8. mygetquote run from command line (with handlers) 22 Web Services Client for ILE

33 Chapter 5. Securing web service communications This chapter explains how to use Secure Sockets Layer (SSL) to set up security for web service client applications. The Global Security Kit product, and the use of secure channels are not available by default with Web Services Client for ILE. If you want to use SSL, you must first obtain a copy of GSKit. An HTTP SSL channel library is shipped with Web Services Client for ILE, but this cannot be used unless the GSKit libraries are available. You can secure your HTTP messages by using SSL, which encrypts the request and response messages before they are transmitted over the wire. Note: Handlers are not affected by SSL as they receive the message either before encryption or after decryption. Any web service that uses SSL adds the suffix s for secure to the http name in the URL. For example: becomes A secure endpoint URL is an endpoint beginning with https. To allow secure endpoint URLs to be used, you must initialize GSKit with user-defined security information to be passed to the AxisClient. You can do this either by adding the required information to the axiscpp.conf file, or by configuring the settings for secure service within your web service client application. To set up security using SSL, complete either of the following steps: v To modify the axiscpp.conf file, make the required changes to this file as described in Security information defined in axiscpp.conf file. v To configure the settings for secure service within your web service client application, use the SetSecure method to configure the GSKit secure information. A sample client application that configures GSKit security information before calling a web service is described in Security information defined using the SetSecure method on page 24. Security information defined in axiscpp.conf file If you are defining security information using the axiscpp.conf file, you must append two lines to this file to define the mandatory library and GSKit security information. The following example, which is for Windows, shows the information that you must add: #The comment character is?#? #Available directives are as follows # #ClientWSDDFilePath:The path to the client WSDD #SecureInfo:The GSKit security information # Channel_HTTP_SSL:<inst_dir>/bin/HTTPSSLChannel.dll SecureInfo:<GSKitInstDir><KeyRing.kdb>,<password or stash>,<label>, NONE,05,NONE,false Copyright IBM Corp. 2007,

34 Note: There are no spaces between the label, colon and directory path. Security information defined using the SetSecure method If you are defining security information using the SetSecure method, you must add a line of code to your web service client application to configure the GSKit settings for the secure service. The GSKit security information must be initialized before the application calls any methods on the web service. The following C++ example shows a Windows version of a sample client application that configures GSKit security information before calling a web service. To configure the secure setting within your own application, add the code shown in bold in this example. int main() // Create URLs for normal and secure communication. The localhost may require // a port number, i.e. localhost:80 char * psznormalurl = " char * pszsecureurl = " // Load instances of the service with normal and secure URL settings. ITestService * servicenormal = new ITestService( psznormalurl); ITestService * servicesecure = new ITestService( pszsecureurl); // Initialise the secure settings for the secure service. servicesecure->setsecure( // Remainder of application : // End of application "<GSKit_InstDir><KeyRing.kbd>", "<password or stash>", "<label>", "NONE", "05", "NONE", false); delete delete servicesecure; servicenormal; return 0; Note: The <password or stash> parameter can be replaced with a stash file containing an encrypted password, so that the raw password does not appear in the code or configuration file. The stash file has the same format as the key ring database definition, but the extension must be.sth (for example, <GSKit_InstDir><KeyRing.sth>). Below is a C example of how to set security information: int main() // Create URLs for normal and secure communication. The localhost may require // a port number, i.e. localhost:80 char * psznormalurl = " char * pszsecureurl = " // Load instances of the service with normal and secure URL settings. AXISCHANDLE servicenormal = get_itestservice_stub( psznormalurl); AXISCHANDLE servicesecure = get_itestservice_stub( pszsecureurl); // Initialise the secure settings for the secure service. axiscstubsetsecure(servicesecure, "<GSKit_InstDir><KeyRing.kbd>", "<password or stash>", "<label>", "NONE", "05", "NONE", 0); // Remainder of application : 24 Web Services Client for ILE