Front cover

WebSphere Version 5.1 Application Developer 5.1.1 Web Services Handbookk Web services overview and concepts

Web services tools and development Web services runtime environment

Ueli Wahli Gustavo Garcia Ochoa Sharad Cocasse Markus Muetschard

ibm.com/redbooks

International Technical Support Organization WebSphere Version 5.1 Application Developer 5.1.1 Web Services Handbook February 2004

SG24-6891-01

Note: Before using this information and the product it supports, read the information in “Notices” on page xxiii.

Second Edition (February 2004) This edition applies to WebSphere Application Server Version 5.1 and WebSphere Studio Application Developer Version 5.1.1, for use with the Windows NT and Windows 2000 Operating System. © Copyright International Business Machines Corporation 2003, 2004. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv Changes to the previous version of this redbook . . . . . . . . . . . . . . . . . . . . . . xxvi The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxvii Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii Part 1. Web services concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapter 1. Web services introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Motivation for a services-oriented architecture. . . . . . . . . . . . . . . . . . . . . . . . . . 4 Requirements for a service-oriented architecture . . . . . . . . . . . . . . . . . . . . . 4 Concept of a service-oriented architecture . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Characteristics of the Web service architecture . . . . . . . . . . . . . . . . . . . . . . 7 Web services approach for a SOA architecture . . . . . . . . . . . . . . . . . . . . . . . . . 7 Other concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Properties of the service-oriented architecture . . . . . . . . . . . . . . . . . . . . . . 10 Business models well supported by Web services. . . . . . . . . . . . . . . . . . . . . . 11 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Car selection sub-process (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Purchase sub-process (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Financing sub-process (3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Web services interoperability (WS-I) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Chapter 2. Introduction to SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 The three pillars of SOAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Overall message format - Envelope with header and body . . . . . . . . . . . . 21 Encoding rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 RPC representation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 SOAP elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 URN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 SOAP envelope. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

© Copyright IBM Corp. 2003, 2004. All rights reserved.

iii

Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Advanced topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Communication styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Style and encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 SOAP implementation general architecture . . . . . . . . . . . . . . . . . . . . . . . . 34 IBM SOAP4J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Apache SOAP 2.3 implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 SOAP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Server deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 SOAP client API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Axis server architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Axis client architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Axis subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Implementations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 WebSphere SOAP Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Microsoft SOAP Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Other toolkits and server implementations . . . . . . . . . . . . . . . . . . . . . . . . . 43 Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Chapter 3. Introduction to WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 WSDL document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 WSDL document anatomy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Physical files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 WSDL definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Port types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Service definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Port definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 WSDL bindings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

iv

WebSphere Version 5.1 Web Services Handbook

SOAP binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 HTTP binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 MIME binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 WSDL API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Chapter 4. JAX-RPC (JSR 101). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Terminology: JAX-RPC and JSR 101 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 JAX-RPC basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 JAX-RPC client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 JAX-RPC client programming styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Static stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Dynamic Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Dynamic invocation interface (DII) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Which style to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Managed and unmanaged JAX-RPC clients. . . . . . . . . . . . . . . . . . . . . . . . 74 JAX-RPC specification details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Data type mapping: XML -> Java, Java -> XML . . . . . . . . . . . . . . . . . . . . . 75 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Chapter 5. Implementing Enterprise Web Services (JSR 109) . . . . . . . . . 77 JSR 109 overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Client programming model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Client types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Static stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Dynamic proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Dynamic invocation interface (DII) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Web service client deployment descriptor . . . . . . . . . . . . . . . . . . . . . . . 82 JAX-RPC mapping deployment descriptor . . . . . . . . . . . . . . . . . . . . . . 83 Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Server programming model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Service implementation bean. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Server container responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Web service deployment descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 JAX-RPC mapping deployment descriptor . . . . . . . . . . . . . . . . . . . . . . 92 Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Contents

v

Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 SRJ 109 implementations in WebSphere. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 SOAP over HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 SOAP over JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Chapter 6. Introduction to UDDI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 UDDI overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Static versus dynamic Web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 UDDI registry structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Interactions with UDDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Publishing information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Finding information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Using the information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 UDDI support in WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . 105 Advanced features of UDDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Modeling features for complex business entities . . . . . . . . . . . . . . . . . . . 105 External taxonomies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Powerful inquiry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Combining categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Advanced search using categorization . . . . . . . . . . . . . . . . . . . . . . . . 106 Qualifier for searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Internationalization features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Peer-based replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 UDDI Business Registry on the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Web front ends for registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Finding information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Publishing information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Java API for dynamic UDDI interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 UDDI4J overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Using the library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Writing UDDI clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Creating a proxy object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Finding information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Publishing information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Private UDDI registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Motivation for the use of private UDDI registries. . . . . . . . . . . . . . . . . . . . 120 Need for privacy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Getting rid of UDDI pollution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Standards and guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Possible scenarios for private UDDI registries . . . . . . . . . . . . . . . . . . . . . 121

vi

WebSphere Version 5.1 Web Services Handbook

Internal registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 e-marketplace UDDI registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Extranet UDDI registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Benefits of private UDDI registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Additional considerations for private UDDI registries . . . . . . . . . . . . . . . . 122 Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Securing APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 WebSphere private UDDI registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 WebSphere Application Server 5.0.2 update . . . . . . . . . . . . . . . . . . . . 123 WebSphere Application Server 5.1 update . . . . . . . . . . . . . . . . . . . . . 124 Future of UDDI Version 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Keys assigned by publisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Human-friendly URI-based keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Complex registry topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Advanced security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Data model updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Extended inquiry API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Subscription API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Registry management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Chapter 7. Web services invocation framework . . . . . . . . . . . . . . . . . . . . 129 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 General concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 WSIF architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Provider class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Operation class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 WSDL documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 More concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Interaction flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Definition or modification of the binding selection algorithm . . . . . . . . 135 Modification of a binding implementation at runtime . . . . . . . . . . . . . . 135 Two invocation models using WSIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Stub-less (dynamic) invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Invocation using stubs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Sample scenarios for WSIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Current status and future . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 WebSphere Application Server 5.0.2 update . . . . . . . . . . . . . . . . . . . . . . 138 Integration into WebSphere products . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Future versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Contents

vii

Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Chapter 8. Web services inspection language . . . . . . . . . . . . . . . . . . . . . 141 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 WS-Inspection document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 WS-Inspection document anatomy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 WS-Inspection and UDDI relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 WS-Inspection definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Service name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Service description references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 WS-Inspection bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 WSDL binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 UDDI binding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 Inspection document publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 WSIL examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 WSDL binding example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 UDDI binding example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 WS-Inspection API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Chapter 9. Workflows and business processes . . . . . . . . . . . . . . . . . . . . 159 Web services flow language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Concepts and terms in WSFL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Business process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Flow model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Recursive composition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Service provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Control link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Data link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Transition condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Life cycle interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Sample WSFL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Flow definition markup language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Elements of FDML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 FDML sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Business process execution language for Web services . . . . . . . . . . . . . . . . 165

viii

WebSphere Version 5.1 Web Services Handbook

Concepts and terms in BPEL4WS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Partners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Fault handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Data containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Business process execution language for Web services runtime . . . . . . . 167 BPEL future. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Chapter 10. Web Services Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Motivation for a gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Externalizing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Return on investment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Securing access to Web service providers . . . . . . . . . . . . . . . . . . . . . 170 Protocol transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Web service access to non-SOAP objects . . . . . . . . . . . . . . . . . . . . . 171 General concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Managing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Exposing Web services to the outside world . . . . . . . . . . . . . . . . . . . . 172 Importing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 Managing channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Managing filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 UDDI publication and lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Administering the gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 Managing namespace URI and WSDL URI . . . . . . . . . . . . . . . . . . . . . . . 175 Managing channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 Managing filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Writing your own filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Managing UDDI references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Managing security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Web service security (WS-Security) . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Gateway-level authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Operation-level authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 SSL protocol using HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Proxy authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 Deploying Web services to the gateway . . . . . . . . . . . . . . . . . . . . . . . . . . 179 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Implementation details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Enhancements in Version 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Contents

ix

Chapter 11. Web services security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Common security exposures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 WS-Security concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Evolution of the WS-Security specification . . . . . . . . . . . . . . . . . . . . . . . . 188 WS-Security authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Alternatives to using a username/password mechanism . . . . . . . . . . . 190 Enable authentication in your application . . . . . . . . . . . . . . . . . . . . . . 191 WS-Security integrity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Steps to enable integrity in your application . . . . . . . . . . . . . . . . . . . . 193 WS-Security confidentiality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Steps to enable confidentiality in your application . . . . . . . . . . . . . . . . 194 Transport channel security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 SOAP/HTTP transport channel security . . . . . . . . . . . . . . . . . . . . . . . . . . 195 WS-Security extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Web services security model proposition . . . . . . . . . . . . . . . . . . . . . . . . . 196 End-to-end enterprise security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Part 2. Web services implementation and samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Chapter 12. IBM WebSphere product family . . . . . . . . . . . . . . . . . . . . . . . 203 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 WebSphere foundations and tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 WebSphere Application Server - Express . . . . . . . . . . . . . . . . . . . . . . 206 WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 WebSphere Application Server Network Deployment . . . . . . . . . . . . . 206 WebSphere Application Server Enterprise Edition . . . . . . . . . . . . . . . 206 Current status and outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 WebSphere Application Server Version 5.0.2 updates . . . . . . . . . . . . 207 WebSphere Application Server Version 5.1 updates . . . . . . . . . . . . . . 208 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Information Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 WebSphere Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 WebSphere Studio Site Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 WebSphere Studio Application Developer . . . . . . . . . . . . . . . . . . . . . . 210 WebSphere Studio Application Developer Integration Edition . . . . . . . 211 WebSphere Studio Enterprise Developer . . . . . . . . . . . . . . . . . . . . . . 211 Current status and outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

x

WebSphere Version 5.1 Web Services Handbook

Current status and outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 WebSphere reach and user experience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 WebSphere Portal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Portal Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Portal Extend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Portal Experience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Current status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 WebSphere Everyplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 IBM WebSphere Everyplace Embedded Edition . . . . . . . . . . . . . . . . . 215 WebSphere Everyplace Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 WebSphere Everyplace Server, Service Provider Offering . . . . . . . . . 215 Current status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 WebSphere Commerce. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 WebSphere Commerce Professional Entry . . . . . . . . . . . . . . . . . . . . . 217 WebSphere Commerce Professional Edition. . . . . . . . . . . . . . . . . . . . 217 WebSphere Commerce Business Edition . . . . . . . . . . . . . . . . . . . . . . 217 Current status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 WebSphere Business Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 WebSphere MQ Integrator Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Current status and outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 WebSphere Business Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Current status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 Chapter 13. Web services development overview . . . . . . . . . . . . . . . . . . 221 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Web services development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Build phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Deployment phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Run phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Management phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Building a new Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Bottom-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Top-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Contents

xi

Multiple services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Types of Web services implementation . . . . . . . . . . . . . . . . . . . . . . . . . . 227 Building a new Web service client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 Static client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Dynamic client with known service type . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Dynamic client with unknown service type . . . . . . . . . . . . . . . . . . . . . . . . 231 Types of client implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 Chapter 14. Weather forecast application. . . . . . . . . . . . . . . . . . . . . . . . . 233 Weather forecast application components . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Business module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Data module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Back-end module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Information flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Base code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 Weather data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 Weather forecast JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 Weather forecast session EJB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Weather predictor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 Environment variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Chapter 15. WebSphere Studio Application Developer . . . . . . . . . . . . . . 247 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Strategies for developing a Web service. . . . . . . . . . . . . . . . . . . . . . . . . . 248 Tool support by WebSphere Studio Application Developer . . . . . . . . . . . 248 Bottom-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Top-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Client development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Selected scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Preparing the enterprise applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Installing the weather forecast application . . . . . . . . . . . . . . . . . . . . . . . . 251 Creating a Web service from a JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Create a Web project for the test client. . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Web Service wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Service Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Web Service Java Bean Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Web Service Java Bean Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Web Service Test Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Web Service Proxy Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Web Service Client Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 Generated files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

xii

WebSphere Version 5.1 Web Services Handbook

Files generated in the server-side Web project . . . . . . . . . . . . . . . . . . 259 Files generated in the client-side Web project . . . . . . . . . . . . . . . . . . . 260 Testing the Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 Web Services Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 Test using generated JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Proxy classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Writing Web service clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Stand-alone Java client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Running the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Web client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 Tracing SOAP messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 Using the TCP/IP Monitoring server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 Define the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 Change the endpoint port number . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 Start the servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 Run a client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 TCP/IP Monitor view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 Target URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 Creating a Web service from a session bean. . . . . . . . . . . . . . . . . . . . . . . . . 271 Running the Web Service wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 Generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 Testing the EJB Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 Web Services Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 Universal test client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 Client servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 Web services and JMS protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 SOAP over JMS example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 Configuring the JMS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 Projects for the Web service and sample client . . . . . . . . . . . . . . . . . . . . 274 Create the SOAP over JMS Web service . . . . . . . . . . . . . . . . . . . . . . . . . 275 Creating a Web service client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 Create the Java proxy classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 Create the test servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 Creating a Web service top-down from WSDL. . . . . . . . . . . . . . . . . . . . . . . . 279 Create Web projects and import the WSDL . . . . . . . . . . . . . . . . . . . . . . . 279 Create the skeleton JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Generated files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Client proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Implementing the JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Web services interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 WS-I preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 Web service generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 WSDL validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Contents

xiii

Validating SOAP messages with the TCP/IP Monitor . . . . . . . . . . . . . . . . 283 Creating a Web service from a URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Importing the servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Creating a server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Running the servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 Creating the URL Web service for the servlet . . . . . . . . . . . . . . . . . . . . . . 286 Testing the URL Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 Creating a Web service from DADX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 DADX group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 Creating a Web service from an SQL statement. . . . . . . . . . . . . . . . . . . . 290 Create an SQL statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 Create a DADX group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Creating a DADX file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Create the Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Testing the Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Publishing and exploring a UDDI registry. . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 Publishing a business entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 Web Services Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 Discovering business entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 Publishing the weather forecast Web service . . . . . . . . . . . . . . . . . . . . . . 298 Discovering the weather forecast Web service . . . . . . . . . . . . . . . . . . . . . 299 Deployment of the sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 Exporting the EAR file and installing the enterprise application . . . . . . . . 301 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Chapter 16. Web services security with Application Developer . . . . . . . 303 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 Architecture and deployment model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 Securing Web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 Implementing security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 Defining client authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 Defining server authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 Testing authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 Integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 Defining client integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 Defining server integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 Testing integrity and authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 Confidentiality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 Defining client confidentiality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 Defining server confidentiality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 Configuring the server for confidentiality . . . . . . . . . . . . . . . . . . . . . . . 333 Testing confidentiality, integrity, and authentication . . . . . . . . . . . . . . 334

xiv

WebSphere Version 5.1 Web Services Handbook

Resetting the server configuration and client proxy . . . . . . . . . . . . . . . . . 336 Trace output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 J2EE security and WS-Security relationship . . . . . . . . . . . . . . . . . . . . . . . . . 337 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 Chapter 17. Application Developer Integration Edition . . . . . . . . . . . . . . 341 Enterprise services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 Creating an enterprise service: Bottom-up . . . . . . . . . . . . . . . . . . . . . . . . 342 Creating an enterprise service: Top-down . . . . . . . . . . . . . . . . . . . . . . . . 343 Resource adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 Using Application Developer Integration Edition . . . . . . . . . . . . . . . . . . . . . . 344 Business Integration perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 Services view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 Enhanced WSDL editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 Business process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 Process editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 Elements of the process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 Dynamic process properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 Sample business process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 Prepare existing services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 Create a service project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 Import existing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 Existing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 Set up WSDL files of existing services . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 Create the business process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 Adding services to the process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 Adding flow to the process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 Messages and variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 Extract of generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 Process files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 Process file: temperature.process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 FDML file: temperature.fdml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 Adding Java snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 Defining the process interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 Generate deploy code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 Flow definition markup language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 Testing a business process in the test environment . . . . . . . . . . . . . . . . . . . 370 Web service client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Business process Web client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 Server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 Configuring a remote WebSphere Application Server . . . . . . . . . . . . . . . 373 Debugging business processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

Contents

xv

Setting breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 Start debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 Process debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 Using the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 Deployment to an application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 Importing the process solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Importing the projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Web project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 EJB project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Service project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 EAR project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Defining the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Test the process sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 Chapter 18. WebSphere SDK for Web Services . . . . . . . . . . . . . . . . . . . . 381 The difference between the packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 WebSphere SDK for Web Services Version 5.1 . . . . . . . . . . . . . . . . . . . . . . 383 Application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 Sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 WS-Security in WSDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 Using the tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 Bean2WebService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 Generation steps explained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 Sample setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 Bean2WebService at work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 Command line help and options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 EJB2WebService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 WSDL2WebService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 Generation stages explained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 Sample setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 WSDL2WebService at work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 WSDL2Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 Sample setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 WSDL2Client at work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 Working with the application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 Installing the StringService enterprise application . . . . . . . . . . . . . . . . 402 Starting the server and listing the applications . . . . . . . . . . . . . . . . . . 402 Running a J2SE Web-service client. . . . . . . . . . . . . . . . . . . . . . . . . . . 403 Running the J2EE client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 UDDIPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

xvi

WebSphere Version 5.1 Web Services Handbook

Publishing a business entity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 Publishing a business service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 Security for publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 Additional properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 UDDIUnpublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 Unpublishing a business entity or service . . . . . . . . . . . . . . . . . . . . . . 406 Security for unpublishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Additional properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Sample 1—JavaBean request/response Web service . . . . . . . . . . . . . . . . . . 406 Using sample 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 Rebuilding sample 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 Implementing the weather forecast Web service . . . . . . . . . . . . . . . . . . . . . . 409 Setting up the environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 Running the EJB2WebService tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 Generated output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 Starting the Web service in the application server . . . . . . . . . . . . . . . . . . 412 Creating and running a stand-alone client . . . . . . . . . . . . . . . . . . . . . . . . 413 Client logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 Service locator or service factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 Compile and run the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 Sample client output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 Cleanup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 Using the WSDK plug-in for Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 Starting Eclipse with the WSDK plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . 416 Preparing a server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 Creating a Web service from a JavaBean. . . . . . . . . . . . . . . . . . . . . . . . . 417 Create a Web project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 Import the weather forecast application . . . . . . . . . . . . . . . . . . . . . . . . 417 Run the Web Service wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 Generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Testing the Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 Using the Web Services Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 Creating and running a client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Creating a Web service from a session EJB . . . . . . . . . . . . . . . . . . . . . . . 424 Import an EJB JAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 Create a Web project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Run the Web Service wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 Testing the EJB Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 Creating a stand-alone client application . . . . . . . . . . . . . . . . . . . . . . . . . 426 Exporting the proxy and mapping classes . . . . . . . . . . . . . . . . . . . . . . 427 Compile and run the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

Contents

xvii

Chapter 19. Web services scenario: Architecture and implementation . 429 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 Scenario situation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 Functional requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 Non-functional requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 Incorporating Web services concepts and technologies . . . . . . . . . . . . . . 433 Process to create the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 Types of service invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 Setup phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 Build phase of the client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Deployment phase of the client application. . . . . . . . . . . . . . . . . . . . . . . . 439 Run phase of the client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 General concepts of the UnitedSuns client application . . . . . . . . . . . . . . . . . 441 Application flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 Abstract servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 Invocation result JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445 Preferences class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445 Preferences JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 Preferences servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 UDDI lookup sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 UDDI lookup JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 UDDI lookup servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 Response JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 Testing the UDDI lookup sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 Sample 1: Dynamic invocation using UDDI lookup . . . . . . . . . . . . . . . . . . 454 Start JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 Response JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 Test the sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461 Sample 2: Dynamic invocation using WSIL lookup . . . . . . . . . . . . . . . . . . 461 Start JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461 Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 Response JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 Testing the sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466 General concepts of the IWA application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 Application flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 Home page with update HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 Update weather servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 Response JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 Static client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

xviii

WebSphere Version 5.1 Web Services Handbook

Installing the scenario in Application Developer . . . . . . . . . . . . . . . . . . . . . . . 473 Enterprise applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473 Importing the enterprise applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474 Server project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 Configurating a server for testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 Configure the HOSTS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 Run the samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Static client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Sample 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Sample 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 General UDDI lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Weather update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478 Chapter 20. Web services runtime and deployment in WebSphere . . . . 479 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 WebSphere Application Server general concepts . . . . . . . . . . . . . . . . . . . . . 480 Administration basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 WebSphere topology building blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 Administrative console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482 Enterprise application deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484 Installing an enterprise application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484 Preparing for application install (first page) . . . . . . . . . . . . . . . . . . . . . 484 Preparing for application install (second page) . . . . . . . . . . . . . . . . . . 484 Install new application pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485 Starting and stopping enterprise applications . . . . . . . . . . . . . . . . . . . . . . 486 Regenerate the HTTP server plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486 Web services deployment in WebSphere environment . . . . . . . . . . . . . . . . . 487 Web services enabling with the SoapEarEnabler tool . . . . . . . . . . . . . . . 487 Configuring a server for the ITSO Web services . . . . . . . . . . . . . . . . . . . . . . 487 Start the server and the administrative console . . . . . . . . . . . . . . . . . . . . 487 Define the data source for the weather forecast database . . . . . . . . . . . . 488 Creating JMS resources for use with the SOAP/JMS Web service . . . . . 489 Create a queue connection factory and queue destination . . . . . . . . . 490 Create a listener port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 Activate the queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 Activating Web service security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 Enable global security in WebSphere runtime . . . . . . . . . . . . . . . . . . . 491 Configure the server to decrypt the request. . . . . . . . . . . . . . . . . . . . . 493 Configure the server to encrypt the response . . . . . . . . . . . . . . . . . . . 493 Configuring for the scenario application . . . . . . . . . . . . . . . . . . . . . . . . . . 493 Configure the HOSTS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494 Configure the server with virtual host names . . . . . . . . . . . . . . . . . . . . 494 Restart the application server with security. . . . . . . . . . . . . . . . . . . . . . . . 494

Contents

xix

Install the enterprise applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494 Install the scenario enterprise application . . . . . . . . . . . . . . . . . . . . . . . . . 494 Regenerate the HTTP Server plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 Run the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 Install the enterprise applications of Application Developer . . . . . . . . . . . 495 Update the DADX group configuration. . . . . . . . . . . . . . . . . . . . . . . . . 496 Define a JDBC driver and data source . . . . . . . . . . . . . . . . . . . . . . . . 496 Installing the WORF runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496 Installing the enterprise applications . . . . . . . . . . . . . . . . . . . . . . . . . . 496 Running the sample enterprise applications . . . . . . . . . . . . . . . . . . . . 497 Installing an application with transport channel security . . . . . . . . . . . . . . . . 497 Configuring for HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 Create a self-signed certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 Extract the certificate for installation into WebSphere . . . . . . . . . . . . . 498 Install the certificate in WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 Configure the HTTP server for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 Accessing a Web service from a stand-alone Java client . . . . . . . . . . . . . . . 500 Using Tivoli Performance Viewer (TPF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 Enable PMI service in the application server . . . . . . . . . . . . . . . . . . . . 501 Restart the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 Start Tivoli Performance Viewer (TPV) . . . . . . . . . . . . . . . . . . . . . . . . 501 Implementing a private UDDI registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 Install the UDDI registry on an application server . . . . . . . . . . . . . . . . . . . 503 Using the UDDI registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 Using the UDDI GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 Start the UDDI GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 Publishing information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 Using the UDDI Explorer with the private UDDI registry . . . . . . . . . . . . . . 509 Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 Finding information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 Appendix A. Installation and setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 Installation planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 WebSphere Application Server Version 5.1 requirements . . . . . . . . . . . . 516 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 Database support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 Installing WebSphere Application Server 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . 517 Installation process for Version 5.1 base product . . . . . . . . . . . . . . . . . . . 517 Verifying the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518

xx

WebSphere Version 5.1 Web Services Handbook

Fixpack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 Installing WebSphere Application Server Network Deployment 5.1 . . . . . 519 Application Server Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 Installation of Application Developer 5.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 Installing optional components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 Starting Application Developer with a dedicated workspace. . . . . . . . . . . 521 Installation of Application Developer Integration Edition . . . . . . . . . . . . . . . . 522 CICS Transaction Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 Agent Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 Installation of WebSphere SDK for Web Services 5.1 . . . . . . . . . . . . . . . . . . 523 Eclipse plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 WSDK installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 Installation of the Emerging Technologies Toolkit (ETTK) . . . . . . . . . . . . . . . 524 Installing the sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524 Setting up the WEATHER database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524 Appendix B. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 System requirements for downloading the Web material . . . . . . . . . . . . . 526 Web material content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Workspace projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 Installing the weather forecast application . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 Set up the WEATHER database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 Set up the WebSphere test server (WeatherServer) . . . . . . . . . . . . . . . . 529 Server project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 WebSphere Version 5.1 server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 Configuring the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 Define an authentication alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 Define a data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 Verify the server variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 Configure the JMS server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Runtime classpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 Set up the initial applications for Web services development . . . . . . . . . . 537 Test the starting application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 Installing the scenario sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 Installing the sample applications into WebSphere . . . . . . . . . . . . . . . . . . . . 538 Importing solutions into Application Developer . . . . . . . . . . . . . . . . . . . . . . . 539 Importing a sample project into Application Developer . . . . . . . . . . . . . . . 539 Importing a single source file into Application Developer . . . . . . . . . . . . . 541 Universal test client problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543

Contents

xxi

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 IBM Redbooks collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549

xxii

WebSphere Version 5.1 Web Services Handbook

Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

xxiii

Trademarks The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both: AIX® alphaWorks® CICS® Cloudscape™ CrossWorlds® DB2 Universal Database™ DB2® developerWorks™ Domino™ eServer™ Everyplace™

IBM eServer™ IBM® ibm.com® IMS™ Informix® Lotus® MQSeries® Notes® OS/390® Redbooks (logo)™ Redbooks™

S/390® SAA® Sametime® SecureWay® SLC™ SP2® Tivoli® VisualAge® WebSphere® z/OS™

The following terms are trademarks of International Business Machines Corporation and Rational Software Corporation, in the United States, other countries or both: ClearCase®

Rational®

The following terms are trademarks of other companies: ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. C-bus is a trademark of Corollary, Inc. in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure Electronic Transaction LLC. Other company, product, and service names may be trademarks or service marks of others.

xxiv

WebSphere Version 5.1 Web Services Handbook

Preface This IBM® Redbook describes the new concept of Web services from various perspectives. It presents the major building blocks Web services rely on. Here, well-defined standards and new concepts are presented and discussed. Whereas these concepts are described as vendor independent, this book also presents IBM’s view and illustrates with suitable demonstration applications how Web services can be implemented using IBM’s product portfolio, especially WebSphere® Application Server Version 5.1 and WebSphere Studio Application Developer Version 5.1.1. The IBM Redbook Web Services Wizardry with WebSphere Studio Application Developer, SG24-6292, published in April 2002, has already covered the basics of Web services and how they can be implemented using the corresponding IBM tools. Thus, this new book goes beyond the scope of the 2002 release. Two major focus areas are defined:
Description of the underlying concepts—While the 2002 book mainly describes implementation aspects for J2EE, we concentrate more on the underlying principles and new concepts that are about to emerge, and their impact for the implementation of new application types.
Update of the information provided—Since the release of the first book, roughly two year have passed that have brought a new generation, not only of basically all WebSphere products, but also on all standards on Web services. Thus, we update the provided information. Although this book uses the 2002 book as a basis, it is written as a stand-alone release. All relevant concepts are introduced in reasonable depth. Reading SG24-6292 is thus not mandatory, but it deepens some aspects and is therefore still a useful source of information. This book is structured in two parts:
Part 1 presents the underlying concepts for the use of Web services: It presents the basic programming model, well-known concepts in an updated way, and new concepts that go beyond the scope of the earlier books.
Part 2 shows how Web services can be implemented using the latest IBM tools. Here we introduce a sample application that is demonstrated in various ways.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

xxv

Changes to the previous version of this redbook New in this version of the publication are the discussion and application of the two new specifications, JSR-101 Java API for XML-Based RPC (JAX-RPC), and JSR-109 Implementing Enterprise Web Services, discussion of the Business Process Execution Language (BPEL4WS) specification, extended coverage of Web service security, and an extended sample with database access. All the samples have been tested on Application Server 5.0.2 and 5.1 and Application Developer 5.1 and 5.1.1. Only minor changes were necessary to move to Application Server 5.1 and Application Developer 5.1.1.

The team that wrote this redbook This redbook was produced by a team of specialists from around the world working at the International Technical Support Organization, Raleigh Center. Ueli Wahli is a Consultant IT Specialist at the IBM International Technical Support Organization in San Jose, California. Before joining the ITSO 19 years ago, Ueli worked in technical support at IBM Switzerland. He writes extensively and teaches IBM classes worldwide on application development, object technology, WebSphere Application Server, and lately WebSphere Studio products. In his ITSO career, Ueli has produced over 30 IBM Redbooks™. Ueli holds a degree in Mathematics from the Swiss Federal Institute of Technology. Sharad Cocasse is a Staff Software Engineer on the WebSphere Execution Team. His experience includes over five years of developing object-oriented applications, supporting WebSphere customers, and developing/delivering WebSphere education to customers and IBM field technical personnel. Most recently, he has been assisting customers with advanced technical support for mission-critical WebSphere deployments. He has also coauthored a number of WebSphere-related publications. Sharad holds a Master Degree in Electrical Engineering from the University of Alabama and lives and works in Rochester, Minnesota. Markus Muetschard is a Technical Leader with a focus on IBM WebSphere technologies and product set in the Advanced Technology Support department of Perficient, Inc. Markus has a ABS in Mathematics and BS in Computer Science and Engineering. His expertise includes application and system design, and end-to-end implementations applying object-oriented, Web, and e-Business technologies. Before joining Perficient, Inc., Markus held various leading positions in IT development and service companies, including 13 years with IBM in Switzerland and the ITSO in San Jose, CA, USA, as mentor, consultant, project leader, author, and instructor.

xxvi

WebSphere Version 5.1 Web Services Handbook

Gustavo Garcia Ochoa is an IT Specialist at IBM Global Services Madrid, Spain. He has been with IBM for four years, focusing on the design and development of e-business solutions. Before joining IBM, he worked as a researcher at the División de Ingeniería de Sistemas y Automática in Madrid, where he concentrated on the authentication and recognition of video streaming. His areas of interest include e-business architecture and solutions, computer vision, and industrial and utilities businesses. Gustavo holds a Bachelor’s and a Master's degree in Industrial Engineering, with a major in Electrical Engineering, both from the Universidad Politécnica de Madrid, Spain. Gustavo is also co-author of the publication WebSphere Version 5 Web Services Handbook, SG24-6891. Thanks to the following people for their contributions to this project:
Matija Drobnic, IBM Slovenia, Christian Gerber, IBM Germany, and Michael Schramm, IBM Austria, who were part of the team that wrote the orginial IBM Redbook
Andre Tost of the WebSphere Business Developement Team for general Web with Web services technology and trends
Eric Erpenbach and Michele Chilanti of the WebSphere Skills Transfer Team, Rochester, for the help with SOAP/JMS and Studio Application Developer Integration Edition
Olaf Zimmermann, a Consulting IT Architect in IBM Germany, Heidelberg, who provided the basis for the introductory chapters on SOAP, WSDL, and UDDI
Bertrand Portier, Andy J Clarke, and Simon Nash of IBM Hursley for their input and help on the WebSphere SDK for Web Services

Become a published author Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You'll team with IBM technical professionals, Business Partners and/or customers. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll develop a network of contacts in IBM development labs, and increase your productivity and marketability. Find out more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.html

Preface

xxvii

Comments welcome Your comments are important to us! We want our Redbooks to be as helpful as possible. Send us your comments about this or other Redbooks in one of the following ways:
Use the online Contact us review redbook form found at: ibm.com/redbooks


Send your comments in an Internet note to: [email protected]


Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HZ8 Building 662 P.O. Box 12195 Research Triangle Park, NC 27709-2195

xxviii

WebSphere Version 5.1 Web Services Handbook

Part 1

Part

1

Web services concepts In this part we introduce the underlying concepts of Web services:
Simple Object Access Protocol (SOAP)
Web services description language (WSDL)
Universal description, discovery, and integration (UDDI)
Web services invocation framework (WSIF)
Web services inspection language (WSIL)
Workflows and business processes: Web services flow language (WSFL), flow definition markup language (FDML), and business process execution language (BPEL)
Web Services Gateway
Web services security

© Copyright IBM Corp. 2003, 2004. All rights reserved.

1

2

WebSphere Version 5.1 Web Services Handbook

1

Chapter 1.

Web services introduction This chapter presents the concept of the service-oriented architecture (SOA) for complex distributed Web-based systems. We introduce the concept of Web services, discuss its properties, and show how this approach implements the SOA paradigm. Finally, we sketch what new business models can be implemented with the use of the Web services concept. In this introductory chapter we present the approach from a conceptual perspective. The three subsequent chapters present the major concepts in more technical detail. The chapter is structured in the following way:
Business motivation for a service-oriented architecture
Overview of the service-oriented architecture
Overview of the relevant building blocks for Web services (SOAP, WSDL, and UDDI)
Business models that make use of the new architecture

© Copyright IBM Corp. 2003, 2004. All rights reserved.

3

Motivation for a services-oriented architecture There is a strong trend for companies to integrate existing systems to implement IT support for business processes that cover the entire business cycle. Today, interactions already exist using a variety of schemes that range from very rigid point-to-point electronic data interchange (EDI) interactions to open Web auctions. Many companies have already made some of their IT systems available to all of their divisions and departments, or even their customers or partners on the Web. However, techniques for collaboration vary from one case to another and are thus proprietary solutions; systems often collaborate without any vision or architecture. Thus, there is an increasing demand for technologies that support the connecting or sharing of resources and data in a very flexible and standardized manner. Because technologies and implementations vary across companies and even within divisions or departments, unified business processes could not be smoothly supported by technology. Integration has been developed only between units that are already aware of each other and that use the same static applications. Furthermore, there is a need to further structure large applications into building blocks in order to use well-defined components within different business processes. A shift towards a service-oriented approach will not only standardize interaction, but also allows for more flexibility in the process. The complete value chain within a company is divided into small modular functional units, or services. A service-oriented architecture thus has to focus on how services are described and organized to support their dynamic, automated discovery and use. Companies and their sub-units should be able to easily provide services. Other business units can use these services in order to implement their business processes. This integration can be ideally performed during the runtime of the system, not just at the design time.

Requirements for a service-oriented architecture For an efficient use of a service-oriented scenario, a number of requirements have to be fulfilled:
Interoperability between different systems and programming languages—The most important basis for a simple integration between applications on different platforms is a communication protocol, which is available for most systems and programming languages.

4

WebSphere Version 5.1 Web Services Handbook


Clear and unambiguous description language—To use a service offered by a provider, it is not only necessary to be able to access the provider system, but also the syntax of the service interface must be clearly defined in a platform-independent fashion.
Retrieval of the service—To allow a convenient integration at design time or even runtime of the system, we require a mechanism that provides search facilities to retrieve suitable available services. Such services should be classified into computer-accessible, hierarchical categories, or taxonomies, based upon what the services in each category do and how they can be invoked.
Security—Protection of the services, including the information passed to and received from the service against unauthorized and malicious access, must be supported by the platform to win the confidence of the requestor (chain)—at the end the business customer(s). The type and extent of security depends on the type and placement of the participants—service requestors and service providers—and the services themselves. Service usage monitoring and security incident action plans have to be in place to detect unauthorized access (attempts) and trigger counter measures. Even though security feels kind of contradictory to the service idea, it is required to empower and retain authenticated and authorized requestors/customers while fencing off everything and everyone.

Concept of a service-oriented architecture This is a short introduction to the key concepts of a service-oriented architecture. References for more information are given in “More information” on page 17 at the end of this chapter. Each component in a service-oriented architecture can play one (or more) of three roles: Service provider, broker, and requestor, which perform the operations shown in Figure 1-1.

Chapter 1. Web services introduction

5

2

Service Requestor

1

Internet

Service Provider

3

Service

Broker

Legacy system

Figure 1-1 Web services roles and operations

1. The service provider creates a Web service and possibly publishes its interface and access information to the service registry. Each provider must decide which services to expose, how to make trade-offs between security and easy availability, and how to price the services (or, if they are free, how to exploit them for other value). The provider also has to decide what category the service should be listed in for a given broker service and what sort of trading partner agreements are required to use the service. 2. The service broker (also known as service registry) is responsible for making the Web service interface and implementation access information available to any potential service requestor. The implementers of a broker have to decide about the scope of the broker. Public brokers are available all over the Internet, while private brokers are only accessible to a limited audience, for example, users of a company-wide intranet. Furthermore, the width and breadth of the offered information has to be decided. Some brokers will specialize in breadth of listings. Others will offer high levels of trust in the listed services. Some will cover a broad landscape of services, and others will focus within a given industry. Brokers will also arise that simply catalog other brokers. Depending on the business model, a broker may attempt to maximize look-up requests, number of listings, or accuracy of the listings. 3. The service requestor locates entries in the broker registry using various find operations and then binds to the service provider in order to invoke one of its Web services.

6

WebSphere Version 5.1 Web Services Handbook

One important issue for users of services is the degree to which services are statically chosen by designers compared to those dynamically chosen at runtime. Even if most initial usage is largely static, any dynamic choice opens up the issues of how to choose the best service provider and how to assess quality of service. Another issue is how the user of services can assess the risk of exposure to failures of service suppliers.

Characteristics of the Web service architecture The presented service-oriented architecture employs a loose coupling between the participants. Such a loose coupling provides greater flexibility:
In this architecture, a client is not coupled to a server, but to a service. Thus, the integration of the server to use takes place outside of the scope of the client application programs.
Old and new functional blocks are encapsulated into components that work as services.
Functional components and their interfaces are separated. Therefore, new interfaces can be plugged in more easily (for example, refer to WSIF in “Web services invocation framework” on page 129).
Within complex applications, the control of business processes can be isolated. A business rule engine can be incorporated to control the workflow of a defined business process. Depending on the state of the workflow, the engine calls the respective services.
Services can be incorporated dynamically during runtime.
Bindings are specified using configuration files and can thus easily be adapted to new needs.

Web services approach for a SOA architecture Web services are a rather new technology that implements the above service-oriented architecture. During the development of this technology, a major focus was put on making functional building blocks accessible over standard Internet protocols that are independent from platforms and programming languages. Web services are self-contained, modular applications that can be described, published, located, and invoked over a network. Web services perform encapsulated business functions, ranging from simple request-reply to full business process interactions.

Chapter 1. Web services introduction

7

These services can be new applications or just wrapped around existing legacy systems to make them network-enabled. Services can rely on other services to achieve their goals. The following are the core technologies used for Web services. These technologies are covered in detail in the subsequent chapters.
XML (eXtensible Markup Language) is the markup language that underlies most of the specifications used for Web services. XML is a generic language that can be used to describe any kind of content in a structured way, separated from its presentation to a specific device.
SOAP (Simple Object Access Protocol), similar to JDBC, is a network, transport, and programming language and platform neutral protocol that allows a client to call a remote service. The message format is XML.
WSDL (Web services description language) is an XML-based interface and implementation description language. The service provider uses a WSDL document in order to specify the operations a Web service provides, as well as the parameters and data types of these operations. A WSDL document also contains the service access information.
UDDI (universal description, discovery, and integration) is both a client-side API and a SOAP-based server implementation that can be used to store and retrieve information on service providers and Web services. Figure 1-2 shows the relationship between the core elements of the SOA.
All elements use XML including XML namespaces and XML schemas.
The service requestor and provider communicate with each other.
WSDL is one alternative to make service interfaces and implementations available in the UDDI registry.
WSDL includes the workflow description (business process execution language for Web services, BPEL4WS)
WSDL is the base for SOAP server deployment and SOAP client generation.

8

WebSphere Version 5.1 Web Services Handbook

XSD

XML

WSDL

BPEL4WS Service description (including Worklflow)

Metadata/vocabulary

UDDI (Broker)

HTTP Runtime transports

other

SOAP

Requestor

Provider

J2EE

other

SOA Runtime

Implementation

Figure 1-2 Main building blocks in an SOA approach based on Web services

Other concepts Besides WSDL, SOAP, and UDDI, there have been a number of other concepts developed to define certain sub-aspects. However, they are not considered to be the major building blocks of the new Web services approach (at least at the time this book was being written). Some of them are already well-defined standards, while others are just about to emerge. Some are already introduced into commercial products while others are available as alpha versions on the Web, if at all. The following concepts are presented in more detail in the later sections of this chapter:
WSIL (Web services inspection language) is another service discovery mechanism that addresses a different set of requirements using a distributed usage model. WSIL is designed around an XML-based model for building an aggregation of references to existing Web service descriptions.
WSIF (Web services invocation framework) is a means for a more flexible way to invoke Web services that allows the developer to develop services for transport protocols and service environments of his choice.

Chapter 1. Web services introduction

9


WSGW (Web Services Gateway) can be seen as a kind of proxy that acts as an additional layer between the Web service client and the Web service provider. It enables a flexible way to call Web services located in an intranet from the Internet, as well as calling Internet Web services from the intranet.
WSFL (Web services flow language), FDML (flow definition markup language), and BPEL (business process execution language)—connecting Web services and specifying how collections of Web services are jointly used to implement more complex functionality, typically a business process or a workflow.

Properties of the service-oriented architecture The service-oriented architecture offers the following properties:
Web services are self-contained. On the client side, no additional software is required. A programming language with XML and HTTP client support is enough to get you started. On the server side, merely a Web server and a SOAP server are required. It is possible to Web services enable an existing application without writing a single line of code.
Web services are self-describing. Neither the client nor the server knows or cares about anything besides the format and content of request and response messages (loosely coupled application integration). The definition of the message format travels with the message; no external metadata repositories or code generation tools are required.
Web services can be published, located, and invoked across the Web. This technology uses established lightweight Internet standards such as HTTP. It leverages the existing infrastructure. Some additional standards that are required to do so include SOAP, WSDL, and UDDI.
Web services are language-independent and interoperable. Client and server can be implemented in different environments. Existing code does not have to be changed in order to be Web service enabled. In this publication, however, we assume that Java is the implementation language for both the client and the server side of the Web service.
Web services are inherently open and standard-based. XML and HTTP are the major technical foundation for Web services. A large part of the Web service technology has been built using open-source projects. Therefore, vendor independence and interoperability are realistic goals this time.

10

WebSphere Version 5.1 Web Services Handbook


Web services are dynamic. Dynamic e-business can become reality using Web services because, with UDDI and WSDL, the Web service description and discovery can be automated.
Web services are composable. Simple Web services can be aggregated to more complex ones, either using workflow techniques or by calling lower-layer Web services from a Web service implementation. Web services can be chained together to perform higher-level business functions. This shortens development time and enables best-of-breed implementations.
Web services build on proven mature technology. There are a lot of commonalities, as well as a few fundamental differences to other distributed computing frameworks. For example, the transport protocol is text based and not binary.
Web services are loosely coupled. Traditionally, application design has depended on tight interconnections at both ends. Web services require a simpler level of coordination that allows a more flexible re-configuration for an integration of the services in question.
Web services provide programmatic access. The approach provides no graphical user interface; it operates at the code level. Service consumers have to know the interfaces to Web services but do not have to know the implementation details of services.
Web services provide the ability to wrap existing applications. Already existing stand-alone applications can easily be integrated into the service-oriented architecture by implementing a Web service as an interface.

Business models well supported by Web services Due to the properties described above, Web services are well suited for the encapsulation of rather small modules that perform independent tasks within a highly heterogeneous e-business landscape. Thus, they can easily be used to wrap applications that need little or no information concerning the state of the current business process and thus can be plugged easily into different business processes. For connecting to a large monolithic system that does not allow the implementation of different flexible business processes, other approaches might be better suited, for example, to satisfy specialized features, such as performance and security.

Chapter 1. Web services introduction

11

The use of the service-oriented architecture in general, and Web services in particular, enables an easy implementation of business models of the following kinds:
Business information—Sharing of information with consumers or other businesses. Web services can be used to expand the reach through such services as news streams, local weather reports, integrated travel planning, intelligent agents, and so forth.
Business integration—Providing transactional, fee-based services for customers. A global value network of suppliers can be easily created. Web services can be implemented in auctions, e-marketplaces, reservation systems, and so forth.
Business process externalization—Web services can be used to model value chains by dynamically integrating processes to a new solution within an organizational unit or even with those of other e-businesses. This can be achieved by dynamically linking internal applications to new partners and suppliers, to offer their services to complement internal services.

Example In this section, we present a sample scenario that illustrates the use of Web services in a service-oriented environment. This example is partially over-simplified and thus does not claim completeness or overall soundness. However, it gives an understanding of how to use this technology beyond simplistic scenarios such as stock quote examples. The scenario covers the buying process in a business-to-consumer (B2C) environment, say in the automotive industry. The following sub-processes are defined: 1. Selection of a car model 2. Purchase 3. Financing Figure 1-3 shows the different units that run these processes. Note that some parts of the first two processes are run through units within the company’s intranet, while the last process integrates units from different companies over the Internet.

12

WebSphere Version 5.1 Web Services Handbook

Image renderer

Intranet

Car configurator

Storing component 1

Dealer locator

B2C Web Application

Client

Credit history checker

2

Production system

3

Banking system 1

...

Banking system n

Figure 1-3 Components in a B2C scenario

Car selection sub-process (1) The user enters the general B2C portal site of the car manufacturer of choice. After having surfed on the public part of the site, he enters the car configuration area, where he can model a car with the features he is interested in (model, engine, color, equipment, and so on). As Figure 1-3 shows, in this scenario the B2C Web application makes use of a car configurator legacy system, which is wrapped by a Web service. The B2C Web application passes control to that application. The car configurator in turn uses another system, which is responsible for an online generation of images that show the car in the selected configuration. After every user’s change in the

Chapter 1. Web services introduction

13

configuration, the car configurator requests a new image from the renderer. This transaction is again performed with Web services. Once the user has finished the configuration process, he can store the particular configuration on the server side. Therefore, he first has to register for a login account and then actually log in (which we do not cover here in depth). In the scenario, the component for storing the configuration is a system that serves storing facilities to many other components. It offers Web services for storing, retrieving, and deleting configurations of any kind (not restricted to a modeled car). The B2C Web application contacts the storing component and makes use of the store Web service. The user might leave the portal and return another day. Then he can load the configured car (the B2C Web application retrieves the data from the storing module via the Web service), modify it, and store it again.

Purchase sub-process (2) After having finished the configuration process, the authenticated user decides to buy the configured car and initiates the purchase process. The B2C Web application asks the user to enter additional data, for instance delivery details, or the dealer he wishes to use as a contact person. In our scenario, a list of all available dealers may be stored in a remote catalogue, which can be accessed over a Web service. The B2C Web application transmits the user’s preferences as parameters and in return gets contact data for a selected dealer. Once all relevant data is inserted, the B2C Web application initiates the production of the ordered car. The responsible system is also accessible through a Web service.

Financing sub-process (3) The user decides to find a financing model for his purchase. Let us assume for our scenario that the car manufacturer does not provide any financing service. The B2C Web application collects relevant data from the user, such as the budget he wishes to spend per month. Furthermore, the B2C Web application contacts an external credit history check institution via a Web service in order to clarify the user’s credibility. After having collected these pieces of data, the B2C Web application contacts several banking systems through Web services and initiates an auction for this case. All connected banking systems may release a bid. The B2C Web application compares the offers, selects the best choice, grants the bid and

14

WebSphere Version 5.1 Web Services Handbook

submits the relevant customer data to the appropriate banking system. All other banking systems are sent a rejection.

Discussion This scenario is well suited to be implemented using Web services technology:
All components (except for the central B2C Web application) already existed beforehand and were easily wrapped to work as Web services.
The components deliver small, well-defined and independent pieces of functionality, which could be used for many business processes, because the components do not require any status data of a certain process as input.
Some of the integrated components run on the car manufacturer’s intranet, while others are run by different enterprises and are accessed over the Internet.

Web services interoperability (WS-I) WS-I is an organization designed to promote Web service interoperability across platforms, operating systems, and programming languages. For more information on WS-I, refer to their Web site: http://www.ws-i.org/

This site contains resources such as an overview of Web services interoperability, usage scenarios, and specifications. Here is a quote from Rod Smith, Vice President of Emerging Internet Technology, Software Group, IBM Corporation: “IBM is delighted with the broad industry support for WS-I's first profile, WS-I Basic Profile 1.0. Interoperability is a "must have" characteristic/attribute for the viability and growth of our industry and to the emerging technical infrastructures of grid and IBM's e-business on demand computing initiatives. With the availability of the Basic Profile 1.0, IBM continues its commitment to the development of open standards for Web services and their incorporation into products, thus ensuring the interoperability and viability of solutions for our customers.” Here an extract from the WS-I Web site:
WS-I is an open industry organization chartered to promote Web services interoperability across platforms, operating systems, and programming languages. The organization works across the industry and standards organizations to respond to customer needs by providing guidance, best practices, and resources for developing Web services solutions.

Chapter 1. Web services introduction

15


WS-I was formed specifically for the creation, promotion, or support of Generic Protocols for Interoperable exchange of messages between services. Generic Protocols are protocols that are independent of any specific action indicated by the message beyond actions necessary for the secure, reliable, or efficient delivery of messages; “Interoperable” means suitable for and capable of being implemented in a neutral manner on multiple operating systems and in multiple programming languages. The WS-I Basic Profile is an outline of requirements to which WSDL and Web service protocol (SOAP/HTTP) traffic must comply in order to claim WS-I conformance. The Web services WS-I validation tools currently support WS-I Basic Profile 1.0. To view the specifications, refer to the WS-I Web site, under Resources select Documentation. Depending on the type of Web service being created, you may or may not want your Web service to comply with the WS-I Basic Profile. WebSphere Studio Application Developer allows you to set your level of compliance. The default level of compliance is to generate a warning if a non-complaint Web service option is selected. See “Web services interoperability” on page 282 for support of WS-I in Application Developer Version 5.1.1.

Summary In this chapter we have presented the general business and programming concepts that Web services are built on. A service-oriented architecture provides a loose coupling between components that provide and use services. As discussed, this flexible approach gives a wide range of advantages in business scenarios, where reusable components are employed for different business processes. We have also sketched the core building blocks to run Web services. These building blocks are presented in more detail in the next chapters. Finally, we have outlined a scenario that is well suited to the use of Web services in order to give a taste of how new business processes could be modeled using the new technology. The scenario showed that new business processes can be implemented with components that were originally not necessarily intended for such processes. For instance, the interfaces of the banking systems provide the functionality to give financing offers. The new application uses these services to run an auction on top.

16

WebSphere Version 5.1 Web Services Handbook

The next three chapters introduce the main building blocks for Web services in more detail: SOAP, WSDL, and UDDI. The remaining chapters of Part 1 describe other concepts, which build on the base.

More information General introductions to Web services can be found at: http://www.ibm.com/developerworks/webservices/

The following Web site provides a collection of IBM resources on the topic at hand. For example, you can find an introduction to the SOA in a white paper titled Web Services Conceptual Architecture (WSCA 1.0): http://www.ibm.com/software/solutions/webservices/resources.html

More information is provided in the article Energize e-business with Web services from the IBM WebSphere software platform at: http://www.ibm.com/developerworks/library/ibm-lunar.html

Chapter 1. Web services introduction

17

18

WebSphere Version 5.1 Web Services Handbook

2

Chapter 2.

Introduction to SOAP In this chapter we introduce SOAP, the specification covering the exchange of XML-based messages between the three main actors in the service-oriented architecture (SOA). We cover the SOAP 1.1 specification in detail and present a couple of examples of SOAP messages. We cover the details of the SOAP architecture. We explore SOAP implementations such as Apache SOAP 2.3 and its successor, Apache eXtensible Interaction System (Axis). We also briefly touch upon other SOAP implementations, such as the Microsoft SOAP Toolkit. Finally, we outline recent developments and future trends in this field.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

19

Overview Simple Object Access Protocol (SOAP) is a specification for the exchange of structured information in a decentralized, distributed environment. As such, it represents the main way of communication between the three main actors in SOA: The service provider, service requestor and service broker. The main goal of its design is to be simple and extensible. Originally proposed by Microsoft, it is now submitted to W3C as the basis of the XML Protocol Working Group by several companies including IBM and Lotus®. At the time of writing of this book, the current standard version is 1.1 with 1.2 being in preparation. You can get more details at: http://www.w3.org/TR/SOAP

SOAP is an XML-based protocol that consists of three parts: An envelope that defines a framework for describing message content and process instructions, a set of encoding rules for expressing instances of application-defined data types, and a convention for representing remote procedure calls and responses. SOAP is, in principle, transport protocol-independent and can therefore potentially be used in combination with a variety of protocols. In this book, we describe how to use SOAP in combination with HTTP, HTTP extension framework, and JMS. SOAP is also operating system independent and not tied to any programming language or component technology. Because SOAP deals with objects serialized to plain text and not with stringified remote object references (interoperable object references, IORs, as defined in CORBA), distributed garbage collection has no meaning and is not covered. For the same reason, SOAP clients do not hold any stateful references to remote objects, and without this, activation in a Java RMI way is also impossible. Due to these characteristics, it does not matter what technology is used to implement the client, as long as the client can issue XML messages. Similarly, the service can be implemented in any language, as long as it can process XML messages. Also, both server and client sides can reside on any suitable platform. In this chapter we discuss the W3C SOAP 1.1 specification and the SOAP 2.3 implementation from Apache. We also discuss Apache Axis, the SOAP 2.3 successor, and the IBM WebSphere SOAP Engine. There are other Java implementations as well as non-Java implementations, such as Microsoft SOAP Toolkit, which we only briefly touch upon.

20

WebSphere Version 5.1 Web Services Handbook

The three pillars of SOAP This section discusses the key aspects of XML-based message exchange.

Overall message format - Envelope with header and body A SOAP message is an envelope containing zero or more headers and exactly one body.
The envelope is the top element of the XML document, providing a container for control information, the addressee of a message, and the message itself.
Headers contain control information, such as quality of service attributes.
The body contains the message identification and its parameters. Both the headers and the body are child elements of the envelope.

Envelope Header [0..n]

Body [1]

http://...org/soap/actor/next log

JDoe 0JDOE0

Figure 2-1 Example of a conceptualized SOAP message

Figure 2-1 shows a conceptualized SOAP request message based on a scenario of a personal text message recorder, similar to a recording phone answering machine, where the user can listen to the recorded messages:
The header tells who and how to deal with the message. The actor next (or omitted actor) is the default actor and declares the receiver as the server who has to do what the body says. Furthermore, the server must understand the application-defined quality of service log (and implement and execute it, as the name implies: Log the service request).
The body tells what has do be done: Get and return the next message for Jon Doe—in detail—invoke the getMessage method on the service object instance NextMessage passing the two string arguments UserID and Password with the values JDoe and 0JDOE0.

Chapter 2. Introduction to SOAP

21

More on envelope, header, and body is coverd in the section “SOAP elements” on page 24.

Encoding rules Encoding rules (of course included in a real SOAP message) define a serialization mechanism that can be used to exchange instances of application-defined data types. SOAP defines a programming language-independent data type schema based on the XML schema descriptor (XSD), plus encoding rules for all data types defined according to this model.

RPC representation The remote procedure call (RPC) representation is a convention suited to represent remote procedure calls and the related response messages. As arguments in remote method invocation, we normally use relatively simple data structures, although, with conventions such as XML Literal, it is possible to transfer more complex data. This convention, however, is only covered by SOAP implementations and standards beyond SOAP, such as the JSR-101 Java APIs for XML based RPC—or briefly, JAX-RPC—and is not a part of the SOAP standard. For more information on JAX-RPC see Chapter 4, “JAX-RPC (JSR 101)” on page 67. The usage of this RPC representation in a plain SOAP context is optional. If the convention is not used, the communication style is purely message oriented. When working with the message-oriented style, also called document-oriented communication, almost any XML document can be exchanged. Figure 2-2 shows an example of a SOAP request message embedded in an HTTP request:
The standard HTTP header contains the URL of the SOAP server, which in this case is /www.messages.com/webapp/servlet/rpcrouter. Relative to this URL, the Web service is identified by urn:NextMessage.
After the header comes a SOAP envelope that contains the message to be transmitted. Here the method invocation is the SOAP RPC representation of a call to the method getMessage(UserID, Password) of a Web service called urn:Nextmessage residing on the SOAP server.
http://schemas.xmlsoap.org/soap/encoding/ specifies the encoding that is used to convert the parameter values from the programming language on both the client side and the server side to XML and vice versa.

22

WebSphere Version 5.1 Web Services Handbook

POST /webapp/servlet/rpcrouter HTTP/1.1 Host: www.messages.com Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" JDoe 0JDOE0 Figure 2-2 A SOAP message embedded in an HTTP request

Figure 2-3 shows a (possible) response to the above request:
First comes the standard HTTP header.
After the header comes a SOAP envelope that contains the message to be transmitted. In this message, the service returned the requested message.

HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" Call mom! Figure 2-3 A SOAP message embedded in an HTTP response

SOAP messages are fundamentally one-way transmissions from a sender to a receiver, but, as illustrated above, SOAP messages are often combined to implement patterns such as request/response.

Chapter 2. Introduction to SOAP

23

SOAP elements This section discusses the major elements of a SOAP message.

Namespaces SOAP defines the two XML namespaces shown in Table 2-1. Table 2-1 SOAP namespaces Prefix

Namespace URI

Explanation

SOAP-ENV

http://schemas.xmlsoap.org/soap/envelope/

SOAP envelope

SOAP-ENC

http://schemas.xmlsoap.org/soap/encoding/

SOAP serialization

URN A unified resource name (URN) uniquely identifies the service to clients. It must be unique among all services deployed in a single SOAP server, which is identified by a certain network address. A URN is encoded as a universal resource identifier (URI). We commonly use the format urn:UniqueServiceID. urn:NextMessage is the URN of our message exchange Web service. All other addressing information is transport dependent. When using HTTP as the transport, for example, the URL of the HTTP request points to the SOAP server instance on the destination host. For the message exchange service, the URL could be http://www.messages.com/webapp/servlet/rpcrouter. This namespace URI identifying the method name in SOAP is very similar to the interface ID scoping a method name in distributed computing environments such as DCOM or CORBA, or the name and the associated remote interface of an Enterprise JavaBean (EJB).

SOAP envelope The envelope is the top element of the XML document representing the message with the following structure: [message payload]

24

WebSphere Version 5.1 Web Services Handbook

In general, a SOAP message is a (possibly empty) set of headers plus one body. The SOAP envelope also defines the namespace for structuring messages. The entire SOAP message (headers and body) is wrapped in this envelope. Note that the message body uses a service-specific namespace, urn:NextMessage, in our examples (Figure 2-2 on page 23 and Figure 2-3 on page 23). This namespace is different from SOAP-ENV, the namespace used by the envelope, which is defined by the SOAP specification. Therefore, the application can use its own domain-specific vocabulary when creating message bodies.

Headers Headers are a generic and flexible mechanism for extending a SOAP message in a decentralized and modular way without prior agreement between the parties involved. They allow control information to pass to the receiving SOAP server and provide extensibility for message structures as well. Headers are optional elements in the envelope. If present, the element must be the first immediate child element of a SOAP envelope element. All immediate child elements of the header element are called header entries. There is a predefined header attribute called SOAP-ENV:mustUnderstand. The value of the mustUnderstand attribute is either “1” or “0”. The absence of the SOAP mustUnderstand attribute is semantically equivalent to the value “0”. If it is present in a header element and set to “1”, the service provider must implement the semantics defined by the element: 3

In the example, the header element specifies that a service invocation must fail if the service provider does not support the quality of service (qos) 3 (whatever qos=3 stands for in the actual invocation and servicing context). A SOAP intermediary is an application that is capable of both receiving and forwarding SOAP messages on their way to the final destination. In realistic situations, not all parts of a SOAP message may be intended for the ultimate destination of the SOAP message, but, instead, may be intended for one or more of the intermediaries on the message path. Therefore, a second predefined header attribute, SOAP-ENV:actor, is used to identify the recipient of the header information. The value of the SOAP actor attribute is the URI of the mediator, which is also the final destination of the particular header element (the mediator does not forward the header).

Chapter 2. Introduction to SOAP

25

If the actor is omitted or set to the predefined default value, then the header is for the actual recipient and the actual recipient is also the final destination of the message (body). The predefine value is: http://schemas.xmlsoap.org/soap/actor/next

Headers can also carry authentication data, digital signatures, encryption information, and transactional settings. Headers can also carry client- or project-specific controls and extensions to the protocol; the definition of headers is not just up to standard bodies. Note: The header must not include service instructions (that would be used by the service implementation).

Body The SOAP body element provides a mechanism for exchanging information intended for the ultimate recipient of the message. The body element is encoded as an immediate child element of the SOAP envelope element. If a header element is present, then the body element must immediately follow the header element. Otherwise it must be the first immediate child element of the envelope element. All immediate child elements of the body element are called body entries and each body entry is encoded as an independent element within the SOAP body element. In the most simple case, the body of a basic SOAP message comprises:
A message name.
A reference to a service instance. In Apache SOAP, a service instance is identified by its URN. This reference is encoded as the namespace attribute.
One or more parameters carrying values and optional type references. Typical uses of the body element include invoking RPC calls with appropriate parameters, returning results, and error reporting. Fault elements are used in communicating error situations. The messages can contain almost any XML construct except document type definitions (DTDs) and processing instructions.

26

WebSphere Version 5.1 Web Services Handbook

Error handling SOAP itself predefines one body element, which is the fault element used for reporting errors. If present, the fault element must appear as a body entry and must not appear more than once within a body element. The fields of the fault element are defined as follows:
Faultcode—is a code that indicates the type of the fault. SOAP defines a small set of SOAP fault codes covering basic SOAP faults: – SOAP-ENV:Client, indicating incorrectly formatted messages – SOAP-ENV:Server, for delivery problems – SOAP-ENV:VersionMismatch, which can report any invalid namespaces for envelope element – SOAP-ENV:MustUnderstand, for errors regarding the processing of header content
Faultstring—is a human-readable description of the fault. It must be present in a fault element.
Faultactor—is an optional field that indicates the URI of the source of the fault. It is similar to the SOAP actor attribute, but instead of indicating the destination of the header entry, it indicates the source of the fault. The value of the faultactor attribute is a URI identifying the source that caused the error. Applications that do not act as the ultimate destination of the SOAP message must include the faultactor element in a SOAP fault element.
Detail—is an application-specific field that contains detailed information about the fault. It must not be used to carry information about errors belonging to header entries. Therefore, the absence of the detail element in the fault element indicates that the fault is not related to processing of the body element (the actual message). For example, a SOAP-ENV:Server fault message that is returned if the service implementation throws a SOAPException. The exception text is transmitted in the Faultstring field.

Chapter 2. Introduction to SOAP

27

Advanced topics In the following section, we discuss more advanced SOAP concepts, such as the different communication styles, the SOAP data model, the available encodings, and the corresponding type mappings. Although these concepts are rarely a concern in simple SOAP architectures, you will very quickly find them useful once you try to implement a nontrivial Web service.

Communication styles SOAP supports two different communication styles: Document

Also known as message-oriented style: This style provides a lower layer of abstraction, and requires more programming work. The in parameter is any XML document; the response can be anything (or nothing). This is a very flexible communication style that provides the best interoperability.

RPC

The remote procedure call is a synchronous invocation of operation returning a result, conceptually similar to other RPCs. This style is exploited by many Web service tools and featured in many tutorials.

Messages, parameters, and invocation APIs look different for RPC and document styles. The decision about which style to use is made at design time; a different client API and server-side router servlet are used. SOAP enables applications to encapsulate and exchange RPC calls using the extensibility and flexibility of XML. To make a method call, the following information is needed:






The URI of the target object A method name An optional method signature The parameters of the method Optional header data

Using SOAP for RPC does not imply any specific SOAP protocol binding; using SOAP for RPC is not limited to the HTTP protocol binding. When using HTTP as the protocol binding, however, an RPC call maps naturally to an HTTP request and an RPC response maps to an HTTP response. Figure 2-4 shows the interactions between the client and server as well as the server-side processing of a service invocation in RPC communication.

28

WebSphere Version 5.1 Web Services Handbook

SOAP Client

SOAP Server

Call - target object - encoding style - method name - parameters - transport - invoke()

2

Deployment Descriptors ServiceManager

5 RPC Router Servlet

1

SOAP Message

3

PluggableProvider

4 1. Send SOAP RPC Request 2. Lookup deployment descriptor 3. Pass request to provider 4. Invoke service 5. Return response

SOAP Service

Java Class Script EJB COM Application other

Figure 2-4 SOAP client and server interaction

Web service invocation using RPC involves the following steps: 1. A SOAP client generates a SOAP RPC request document and sends it to a RPC router. 2. The router contacts the service manager to obtain a deployment descriptor. 3. Based on routing information form the deployment descriptor, the router forwards the request to a service provider. 4. The service provider invokes the requested service and returns a result to the router. 5. The router sends the service result message to the client. It is worth noting that this is a very simple scenario. More sophisticated scenarios would use additional steps, such as the ones related to security policy.

Chapter 2. Introduction to SOAP

29

Data model One of the promises of SOAP is interoperability between different programming languages. That is the purpose of the SOAP data model, which provides a language-independent abstraction for common programming language types. It consists of: Simple XSD types

Basic data types found in most programming languages such as int, String, Date, and so forth.

Compound types

There are two kinds of compound types, structs and arrays:

Structs

Named aggregated types. Each element has a unique name, its accessor. An accessor is an XML tag. Structs are conceptually similar to records in languages such as Pascal or methodless classes with public data members in object-based programming languages.

Arrays

Elements in an array are identified by position, not by name. This is the same concept found in languages such as C and Java. SOAP also supports partially transmitted and sparse arrays. Array values may be structs or other compound values. Also, nested arrays (which means arrays of arrays) are allowed.

All elements and identifiers comprising the SOAP data model are defined in the namespace SOAP-ENC. It is worth noting that the SOAP standard only defines the rules of how data types can be constructed; a project-specific XML schema has to define the actual data types. A SOAP request message such as getMessage in Figure 2-2 on page 23 is modeled as a struct containing an accessor for each in and in/out parameter. It is shown in Figure 2-5.

JDoe 0JDOE0 Figure 2-5 A SOAP request message

In the example in Figure 2-5, the accessors are UserID and Password. The accessor names correspond to the names of the parameters, and the message types to the programming language data types (xsd:string and java.lang.String). The parameters must appear in the same order as in the method signature. The prefixes xsd and xsi reference the namespaces

30

WebSphere Version 5.1 Web Services Handbook

http://www.w3.org/2001/XMLSchema and http://www.w3.org/2001/XMLSchema-instance, respectively. In the example shown in Figure 2-6, the argument is an array whose values are structs.

JDoe 0JDOE0 MDoe 0JMDOE0 Figure 2-6 A SOAP request message with an array of structs

The SOAP data model makes self-describing messages possible. No external schema is needed to understand an XML element such as: JDoe

SOAP provides a preferred encoding for all data types defined according to this model. We cover this subject in the next section. Note: The use of a data model and associated encoding is optional.

Encodings In distributed computing environments, encodings define how data values defined in the application can be translated to and from a protocol format. We refer to these translation steps as serialization and deserialization, or, synonymously, marshalling and unmarshalling (even Apache SOAP uses both pairs of terms). When implementing a Web service, we have to choose one of the tools and programming or scripting languages that support the Web services model, for example Java. On the other hand, the protocol format for Web services is XML, which is independent of the programming language. Thus, SOAP encodings tell the SOAP runtime environment how to translate from data structures constructed in a specific programming language into SOAP XML, and vice versa.

Chapter 2. Introduction to SOAP

31

The following encodings are defined: SOAP encoding

The SOAP encoding enables marshalling/unmarshalling of values of data types from the SOAP data model. This encoding is defined in the SOAP 1.1 standard.

Literal

The literal encoding is a simple XML message that does not carry encoding information. Usually an XML Schema describes the format and data types of the XML message.

Literal XML

The literal XML encoding enables direct conversion of existing XML DOM tree elements into SOAP message content and vice versa. This encoding style is not defined by the SOAP standard, but is in the Apache SOAP 2.3 implementation.

XMI

XML metadata interchange (XMI) is defined by the Apache SOAP implementation. We do not use this encoding in this document.

The encoding to be used by the SOAP runtime can be specified at deploy time or at runtime. If it is specified at deploy time, it appears in the WSDL specification of the Web service. Tools can then analyze this specification and configure the SOAP runtime to use the desired encoding. At runtime, the SOAP client API allows the specification of the encoding for the entire message and for each of its parameters. On the server side, the encoding style is specified in the deployment descriptor of the Web service, an XML document that provides information to the SOAP runtime about the services that should be made available to clients. It contains information such as the URN for the service and method and class details (in case the service is implemented in Java) or the name of a script. The settings on the client and the server side have to match.

Style and encoding The two styles (RPC, document) and two encodings (encoded, literal) can be freely intermixed, but only three of the four combinations are generally used:
Document/literal—Provides the best interoperability between Java and non-Java implementations.
RPC/literal—Good choice between Java implementations.
RPC/encoded—Early Java implementations (WebSphere Version 4 and 5.0) supported this combination, but it does not provide interoperability with non-Java.
Document/encoded—Not used in practice.

32

WebSphere Version 5.1 Web Services Handbook

Mappings A mapping defines an association between a qualified XML element name, a Java class name, and one of the encodings as introduced above. Hence, mappings are not implementation language-independent. A mapping specifies how, under the given encoding, an incoming XML element with a fully qualified name is to be converted to a Java class, and vice versa. We refer to the two mapping directions as XML to Java and Java to XML, respectively. Any SOAP runtime environment holds a table of such mapping entries, the SOAPMappingRegistry. Standard Java-related mappings are shown in Table 2-2. Table 2-2 SOAP Java-related mappings Java

SOAP

serializer/deserializer

String

xsd:string

/StringDeserializer

boolean

xsd:boolean

/BooleanDeserializer

Boolean

xsd:boolean

/BooleanObjectDeserializer

double

xsd:double

/DoubleDeserializer

Double

xsd:double

/DoubleObjectDeserializer

long

xsd:long

/LongDeserializer

Long

xsd:long

/LongObjectDeserializer

float

xsd:float

/FloatDeserializer

Float

xsd:float

/FloatObjectDeserializer

int

xsd:int

/IntDeserializer

Integer

xsd:int

/IntObjectDeserializer

short

xsd:short

/ShortDeserializer

Short

xsd:short

/ShortObjectDeserializer

byte

xsd:byte

/ByteDeserializer

Byte

xsd:byte

/ByteObjectDeserializer

BigDecimal

xsd:decimal

/DecimalDeserializer

GregorianCalendar

xsd:timeInstant

CalendarSerializer

Date

xsd:date

DateSerializer

QName

xsd:QName

QNameSerializer

Chapter 2. Introduction to SOAP

33

If a data type is supposed to be used under a certain encoding, exactly one mapping must exist for it in this registry. Most standard Java types as well as JavaBeans are supported by default. Non-standard (custom) data types require the introduction of custom mappings on the client and on the server side.

Implementations So far we have discussed only SOAP specification. To build a Web services-based solution, the standard should be implemented in one of the programming languages. In the following sections, we discuss some of the most popular SOAP implementations.

SOAP implementation general architecture Figure 2-7 contains a high-level component model showing the conceptual architecture of both the service provider (SOAP server) and the service requestor (SOAP client). Service Requestor SOAP RPC Layer

Client Proxy Mapping Registry

Service Provider SOAP Server Pluggable Providers

Service Manager

Call Parameter

SOAP Message Layer

SOAP Transport Layer

Mapping Registry

RPC Router Servlet

Transport Layer (HTTP, HTTPS, SMTP, JMS, MQ, other) Figure 2-7 High-level SOAP component model

34

WebSphere Version 5.1 Web Services Handbook

Deployment Descriptor

Message Router Servlet

The client can invoke SOAP messages through the RPC layer (RPC style) or directly against the message layer (document style). Various transport protocols such as HTTP, SMTP, and others connect the requestor and the provider. On the provider side, RPC and message router servlets receive the incoming requests. Providers route them to the Java service implementation. The server is configured through deployment descriptor files. Both on the requestor and on the provider side, there are mapping registries providing access to serializer/deserializer classes implementing an encoding scheme.

IBM SOAP4J IBM’s SOAP for Java implementation became the basis of the Apache SOAP project.

Apache SOAP 2.3 implementation The basis of the Apache SOAP implementation is IBM SOAP for Java, the Java-based SOAP implementation that was submitted to the open-source community. Let us investigate the details of the SOAP server and then the SOAP client API.

SOAP server Apache SOAP 2.3, included with other implementations in WebSphere Application Server Version 5 and Application Developer Version 5, provides an implementation of a SOAP server for deploying and invoking Web services. Figure 2-8 gives an overview of the Apache SOAP server components. For now, the important elements in this architecture are the rpcrouter and messagerouter servlets, the deployment descriptor (explained below), and the type mapping registry. These components implement the SOAP concepts introduced so far. The pluggable providers link a Web service and its implementation. The service implementation is your Java code actually executing the invoked Web service. We do not go into detail about the configuration manager and the administrative GUI here. Refer to the Apache SOAP user documentation for more information.

Chapter 2. Introduction to SOAP

35

SOAP4J ==> Open Source

Transport Listener (rpcrouter and messagerouter servlets for HTTP)

SOAP Admin GUI (HTML based)

Type Mapping Registry

SOAP Server Engine Pluggable Configuration Manager

DeployedServices.ds

Pluggable Providers (JavaBean, EJB, BSF, COM, custom)

Service Implementation any type of programming artifact

Web Service Deployment Descriptor

Figure 2-8 Components of Apache SOAP server implementation

Server deployment Deployment stands for configuring a Web service implementation so that it becomes available within a hosting SOAP server. The following steps have to be performed when a Web service is deployed to the SOAP server:
Create a code artifact that is supported by one of the Apache SOAP providers.
Ensure that parameters to the method/function are serializable by SOAP, and exist within the SOAP type mapping registry. Otherwise, develop and register custom mappings.
Create an entry in the Apache SOAP deployment descriptor for the service. A Web service implementation Java class implementing the first step for the Exchange Web service is shown in Figure 2-9.

36

WebSphere Version 5.1 Web Services Handbook

public class NextMessage{ public String getMessage(String UserID, String Password) { System.out.println("getMessage(" + UserID + ", " + Password + ")"); return "Call mom!"; // fixed value for now } } Figure 2-9 Java class implementing the Web service

The corresponding deployment descriptor, which is read by the SOAP server at startup time, is shown in Figure 2-10.

Figure 2-10 Web service deployment descriptor (SOAP 2.3)

This deployment descriptor defines the URN, urn:NextMessage, and the name of the Java implementation class, NextMessage. There is one accessible method, getMessage. The Web service scope is request. This scope attribute can be set to application, request, or session:
If the scope is application, a singleton instance of the service is created at server startup time (like a servlet).
A service with request scope is instantiated whenever a message for it is received.
If the scope is session, the lifetime of the service instance is bound to the duration of the underlying transport session (for example, the HttpSession in case HTTP is the transport protocol). The actual deployment step can either be performed using the administrative GUI that comes with Apache SOAP or programmatically.

Chapter 2. Introduction to SOAP

37

SOAP client API There are two key abstractions in the SOAP client API, which is defined in the org.apache.soap package and its sub-packages: Call

Contains the URN, the SOAP address of the router servlet on the SOAP servers, as well as the name of the method to be called. A call object contains Parameter instances as data members.

Parameter

Contains the parameter value, type, and encoding style.

As a SOAP developer, you might have to use the following classes as well: QName

Qualified name: Combination of an XML namespace and a local name. QName instances are used to identify XML data types and other elements in an XML document.

SOAPMappingRegistry

Maps types and encoding styles to the available serializer and deserializer classes.

SOAPHttpTransport

Provides access to the HTTP transport layer. For example, this class can be used to modify proxy and authentication settings.

Let us take a look at an example (Figure 2-11). The message that travels if this code is executed is the same message we inspected in Figure 2-2 on page 23. You have to perform the following steps when developing a SOAP client:
Obtain the interface description of the SOAP service, so that you know what the signatures of the methods that you want to invoke are. Either contact the service provider directly, or use UDDI to do so (note that this step is not shown in the example).
Make sure that there are serializers registered for all parameters that you will be sending, and deserializers for all information that you will be receiving (this holds true for the example). Otherwise, develop and register the custom mapping.
Create and initialize the org.apache.soap.rpc.Call object. – Set the target URI in the Call object using the setTargetObjectURI method. – Set the method name that you wish to invoke into the Call object using the setMethodName method. – Create any Parameter objects necessary for the RPC call, and add them to the Call object using the setParams method.

38

WebSphere Version 5.1 Web Services Handbook

public class MySoapClient { public static void main(String[] args){ Call call = new Call(); call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC); call.setTargetObjectURI ("urn:NextMessage"); call.setMethodName ("getMessage"); Vector params = new Vector(); Parameter userIDParam = new Parameter( "UserID", String.class, "JDoe", Constants.NS_URI_SOAP_ENC); params.addElement(userIDParam); Parameter passwordParam = new Parameter( "Password", String.class, "0JDOE0", Constants.NS_URI_SOAP_ENC); params.addElement(passwordParam); call.setParams(params); Response resp = null; URL url = new URL ("http://www.messages.com/soap/servlet/rpcrouter"); resp = call.invoke (url, "urn:NextMessage"); // url, soapActionURI // soapActionURI is URN for Apache, "" for most other servers if (resp.generatedFault()) { Fault fault=resp.getFault(); System.out.println(" Fault code: " + fault.getFaultCode()); System.out.println(" Fault string: " + fault.getFaultString()); } else { Parameter result=resp.getReturnValue(); Object o = result.getValue(); System.out.println("Result: " + o); } } } Figure 2-11 SOAP 2.3 client


Execute the Call object's invoke method and capture the Response object that is returned from invoke.
Check the Response object to see if a fault was generated using the generatedFault method.
If a fault was returned, retrieve it using the getFault method. Otherwise, extract any result or returned parameters using the getReturnValue and getParams methods, respectively. The SOAP client API is a string-oriented, weakly typed interface. This is due to the fact that it is a fixed API that is unaware of the signatures of the messages that are exchanged over it.

Chapter 2. Introduction to SOAP

39

Usually programmers do not have to work with this rather cumbersome API directly because there are tools wrapping it. For example, code generated from WSDL-aware tools can provide a more type-oriented, easier-to-code interface. Apache SOAP implementation also represents the basis of another open-source project, Axis, which we cover in the next section.

Axis The Apache eXtensible Interaction System (Axis) is basically a SOAP engine. It represents a framework for constructing SOAP processors such as clients, servers, or gateways. Axis is an Apache open-source project and is written in Java. Axis Version 1.1 is available, and Version 1.2 is in alpha. Besides being a SOAP engine, Axis also includes the following features:
A server that plugs into servlet engines such as WebSphere Application Server or Apache Tomcat
Extensive support for the Web service description language (WSDL)
Tools that generate Java classes from WSDL and vice versa (WSDL2Java and Java2WSDL)
A tool for monitoring TCP/IP packets TCP/IP monitoring is a very efficient tool for Web services’ debugging and troubleshooting. Axis represents the third generation of Apache SOAP, which began at IBM as SOAP4J, and is often referred to as Apache SOAP 3.x. However, it does not share the code of the Apache SOAP 2.x project, but has been redesigned from scratch. It is based on the idea of configurable chains of message handlers, which would implement small bits of functionality in a flexible manner. Axis uses the event-based simple API for XML (SAX) instead of DOM parsing to perform significantly better than earlier versions of Apache SOAP. The extendable Axis architecture enables the developer to insert extensions into the engine. Axis defines a set of published interfaces that change relatively slowly compared to the rest of Axis and therefore provide a higher level of stability from the developer’s point of view. The core of the Axis SOAP engine is completely transport-independent. Therefore it enables SOAP message exchange using different communication channels such as SMTP, FTP, or message-oriented middleware.

40

WebSphere Version 5.1 Web Services Handbook

Axis server architecture The basic architecture of Axis in the server is shown in Figure 2-12.

Figure 2-12 Axis architecture

The large cylinders represent chains and the small cylinders represent handlers within a chain. The main flow elements are:
The transport listener puts the protocol-specific data into a Message object and the message data into a MessageContext object.
The Axis engine looks up the transport, which may contain a request chain, a response chain, or both. Each chain is a sequence of handlers that are invoked in turn.
After the transport chain, the global chain of handlers is invoked.
One of the handlers sets the serviceHandler field in the MessageContext and the Axis engine invokes that service (an instance of SOAPService).
The service invokes its request chain (if present) and finally the provider, which is the handler responsible for invoking the back-end logic.
The response is processed by the respective response handlers in the service, global, and transport chains.

Axis client architecture The client architecture is basically a mirror image of the server architecture:
The client application sends a message.
The Axis engine invokes the service chain, then the global chain, and then the transport chain, where the final handler, the sender, sends the message to the target.

Chapter 2. Introduction to SOAP

41

Axis subsystems Axis comprises several subsystems working together with the aim of separating responsibilities cleanly and making Axis modular. Subsystems that are properly layered enable parts of a system to be used without having to use all the parts. Figure 2-13 shows the layering of subsystems. The lower layers are independent of the higher layers. The stacked boxes represent mutually independent, although not necessary exclusive, alternatives. For example, the HTTP, SMTP, and JMS transports are independent of each other but may be used together.

MDB XML-RPC deployment descriptor

admin

SOAP

service

EJB

SMTP JMS

Java RPC

HTTP

provider

transport

encoding

message flow: handler, chain, message context, fault AXIS ENGINE

message model

WSDL tools

Figure 2-13 Axis subsystems

Implementations Axis 1.0 is implemented in the Emerging Technologies Toolkit (see “Emerging Technologies Toolkit” on page 382).

WebSphere SOAP Engine With Versions 5.0.2 and 5.1 of WebSphere Application Server comes a new SOAP engine written by IBM. This engine, commonly referred to as WebSphere SOAP Engine, is based on Axis principles but extended for performance and for enterprise Web services. We implement our sample application using WebSphere Application Server Version 5.1, WebSphere Studio Application Developer Version 5.1.1, and WebSphere SDK for Web Services Version 5.1, all of which come with the WebSphere SOAP Engine.

Microsoft SOAP Toolkit Microsoft has its own SOAP implementation in the Microsoft SOAP Toolkit. At the time of writing of this book, the current version was V3.0. SOAP is also part of .NET, Microsoft’s strategic platform for Web services.

42

WebSphere Version 5.1 Web Services Handbook

Other toolkits and server implementations Currently, Web service engines and development tools pop up like mushrooms in the market, for all kinds of platforms written in all kinds of languages for all kinds of devices to get simple connectivity. In addition, manu SOAP and SOAP-RPC user communities came into Web lives that you can join and participate in. Use, for example, this link as a starting point for you own research: http://www.google.com/search?q=soap+web+service+server

Outlook At the time of writing this book, the SOAP 1.2 specification was in its final phase. It introduces several changes to SOAP 1.1. It is beyond the scope of this book to go into the details of differences between SOAP 1.1 and SOAP 1.2 specifications. Recent information on this subject is available at: http://www.w3.org/TR/soap12-part0/#L4697

In October 2002, Apache Axis 1.0 was officially released; in June 2003 Axis 1.1 became available. Among other functions, Axis implements most of the SOAP 1.2 specification.

Summary SOAP represents the information exchange mechanism between the three main actors in the Web service model: A Web service provider, a Web service requestor, and a Web service broker. It is based on XML documents and is designed to be simple and extensible. It is also independent of actual Web services implementation and therefore enables interoperability between Web services implementations on different platforms. SOAP is defined by the W3C SOAP specification. Its current version is V1.1, with V1.2 in preparation. Currently, there are several SOAP implementations available:
The Apache SOAP 2.3 implementation is an open-source Java-based implementation based on IBM SOAP4J implementation and is a part of several commercial packages including WebSphere Application Server Version 5 and WebSphere Application Developer Version 5.
The Apache Axis implementation is a follow-up project of the Apache SOAP V2.X project and is often referred to as Apache SOAP 3.0 implementation.
IBM WebSphere Application Server Version 5.0.2 and 5.1 have their own WebSphere SOAP Engine.

Chapter 2. Introduction to SOAP

43


Other companies (for example, Microsoft) have other SOAP implementations based on different programming and scripting languages. As a communication protocol, SOAP enables the publication and invocation of Web services and represents the basic plumbing of a Web services infrastructure. However, this is not enough for the successful implementation of Web services:
A client has to obtain the information about the interface of a service, the server URL, the URN, the methods, the types, and type mappings. This is provided by WSDL.
A client has to learn about the existence of a service and its characteristics, which is the function of UDDI.
A Web services inspection language (WSIL) document provides location information to invoke Web services.
We introduce these three technologies in the chapters that follow.

More information The SOAP specification can be downloaded from: http://www.w3.org/TR/SOAP http://www.w3.org/TR/soap12-part0/ http://www.w3.org/TR/soap12-part1/

For information on Apache SOAP, check out the user and API documentation as well as the FAQ list at: http://www.apache.org/soap

For information on Apache Axis, check out the user and API documentation as well as the FAQ list at: http://xml.apache.org/axis/index.html

IBM’s developerWorks™ Web site provides many articles on SOAP (enter SOAP into the search engine): http://www.ibm.com/developerworks

For example, here are two articles about SOAP type mapping: http://www.ibm.com/developerworks/library/ws-soapmap1/ http://www.ibm.com/developerworks/library/ws-soapmap2/

44

WebSphere Version 5.1 Web Services Handbook

3

Chapter 3.

Introduction to WSDL This chapter provides an introductory view to Web services description language (WSDL) 1.1. WSDL specifies the characteristics of a Web service using an XML format, describing what a Web service can do, where it resides, and how it is invoked. WSDL is extensible to allow descriptions of different bindings, regardless of what message formats or network protocols are used to communicate. WSDL 1.1 provides a notation serving these purposes. The WSDL specification is a joint effort by Ariba, IBM, and Microsoft. It is not yet an official standard; at the time of the writing of this book, its status was “submission acknowledged” by the W3C. The Web services description language specification 1.2 is a working draft at this time. Therefore, we do not make any specific reference to WSDL 1.2, but we include some information in “Outlook” on page 64. On the other hand, some of the current implementations already implement selected features of the 1.2 draft specification.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

45

Overview WSDL allows a service provider to specify the following characteristics of a Web service:
Name of the Web service and addressing information
Protocol and encoding style to be used when accessing the public operations of the Web service
Type information: Operations, parameters, and data types comprising the interface of the Web service, plus a name for this interface A WSDL specification uses XML syntax; therefore, there is an XML schema for it. A valid WSDL document consists of one or more files. If there is more than one file, the use of the import element is required. This import element creates the needed references to locate the different files of the WSDL document. We recommend this split to maintain a clearer service definition based on level of abstraction of the parts.

WSDL document The WSDL document contains the following main elements: Types

A container for data type definitions using some type system, such as XML schema.

Message

An abstract, typed definition of the data being communicated. A message can have one or more typed parts.

Port type

An abstract set of one or more operations supported by one or more ports.

Operation

Binding

A concrete protocol and data format specification for a particular port type. The binding information contains the protocol name, the invocation style, a service ID, and the encoding for each operation.

Service

A collection of related ports.

Port

46

An abstract description of an action supported by the service that defines the input and output message as well as optional fault message.

A single endpoint, which is defined as an aggregation of a binding and a network address.

WebSphere Version 5.1 Web Services Handbook

Note that WSDL does not introduce a new type definition language. WSDL recognizes the need for rich type systems for describing message formats, and supports the XML schema specification (XSD). WSDL 1.1 introduces specific binding extensions for various protocols and message formats. There is a WSDL SOAP binding, which is capable of describing SOAP over HTTP, a direct HTTP interface (any plain servlet, for example), and a MIME binding. The language is extensible and allows the definition of other binding mechanisms, such as Java and SOAP over Java Messaging Service (JMS). It is worth noting that WSDL does not define any mapping-to-programming languages such as Java; rather the bindings deal with transport protocols. This is a major difference from interface description languages, such as CORBA interface definition language (IDL), which has language bindings.

WSDL document anatomy Figure 3-1 on page 48 shows the elements comprising a WSDL document as well as the various relationships between them. The diagram should be read in the following way:
One WSDL document contains zero or more services. A service contains zero or more port definitions (service endpoints), and a port definition contains a specific protocol extension.
The same WSDL document contains zero or more bindings. A binding is referenced by zero or more ports. The binding contains one protocol extension, where the style and transport are defined, and zero or more operations bindings. Each of these operation bindings is composed of one protocol extension, where the action and style are defined, and one to three messages bindings, where the encoding is defined.
The same WSDL document contains zero or more port types. A port type is referenced by zero or more bindings. This port type contains zero or more operations, which are referenced by zero or more operations bindings.
The same WSDL document contains zero or more messages. One to three messages are required to define an operation. The message is composed of zero or more parts.
The same WSDL document contains zero or more types. A type can be referenced by zero or more parts.
The same WSDL document points to zero or more XML schemas. An XML schema contains zero or more XSD types that define the different data types.

Chapter 3. Introduction to WSDL

47

The containment relationships shown in the diagram directly map to the XML schema for WSDL. WSDL Document

1

n

Service

1

n

Port

1

1

Protocol Extensions

n

1 1 1 n

Binding

1 1

n

Operation Binding n n 1

1 n

Port Type

1

n

1

n

n 0..1 n n

Type

1 1 1..3

Protocol Extensions Message Binding

action style

encoding

Part

Binding

n

Instance XML

1

XML Schema

1

Type

n

1

style/transport

Operation n

1..3

Message

Protocol Extensions

n

XSD Type

contains points to

Figure 3-1 WSDL elements and relationships

In practice a WSDL document can be split into multiple documents using the import element (see “Physical files” on page 51).

Example Let us now give an example of a simple, complete, and valid WSDL file. As we will see, even a simple WSDL document contains quite a few elements with various relationships to each other. Figure 3-2 and Figure 3-3 contain the WSDL file example. This example is analyzed in detail later in this chapter. The example is provided as one unique file. We will see later on that it is possible to fragment this WSDL document in more than one part. As an exercise, you can try identifying the different elements in Figure 3-1 while examining the example.

48

WebSphere Version 5.1 Web Services Handbook

" Figure 3-2 WSDL simple example: Part 1

Chapter 3. Introduction to WSDL

49

Figure 3-3 WSDL simple example: Part 2

50

WebSphere Version 5.1 Web Services Handbook

Physical files A WSDL document can be created in one or more physical files. If they are more than one, we need to connect these files using an import element. This separation of files can be convenient to hold the abstraction of concepts and to allow better maintenance.

WSDL

WSDL document Service Implementation

import service port

WSDL document Service Implementation

import service port

One file

types message portType binding services port

Two files

Service Interface

types message portType binding

binding file

Interface file

import

types

binding

message portType

Three files

WSDL document Figure 3-4 WSDL document structure as one, two, or three files

Figure 3-4 shows the same Web service described in one, two, or three files:
One file, typically used in Axis and in Application Developer Version 5.1
Two files, typically used in Application Developer Version 4
Three files, typically used in Application Developer Version 5.0

Chapter 3. Introduction to WSDL

51

All three examples stand for the same Web service. Therefore, it is important not to be confused by the number of files used to define the WSDL document. There is only one WSDL specification that defines the elements of a WSDL document; how many files are used to store the document is up to the implementer.

Namespaces WSDL uses the XML namespaces listed in Table 3-1. Table 3-1 WSDL namespaces Prefix

Namespace URI

Explanation

wsdl

http://schemas.xmlsoap.org/wsdl/

Namespace for WSDL framework.

soap

http://schemas.xmlsoap.org/wsdl/soap/

SOAP binding.

http

http://schemas.xmlsoap.org/wsdl/http/

HTTP binding.

mime

http://schemas.xmlsoap.org/wsdl/mime/

MIME binding.

soapenc

http://schemas.xmlsoap.org/soap/ encoding/

Encoding namespace as defined by SOAP 1.1.

soapenv

http://schemas.xmlsoap.org/soap/ envelope/

Envelope namespace as defined by SOAP 1.1.

xsi

http://www.w3.org/2000/10/ XMLSchema-instance

Instance namespace as defined by XSD.

xsd

http://www.w3.org/2000/10/ XMLSchema

Schema namespace as defined by XSD.

tns

(URL to WSDL file)

The this namespace (tns) prefix is used as a convention to refer to the current document. Do not confuse it with the XSD target namespace, which is a different concept.

The first four namespaces are defined by the WSDL specification itself; the next four definitions reference namespaces that are defined in the SOAP and XSD standards. The last one is local to each specification. Note that in our example we do not use real namespaces; the URIs contain localhost.

52

WebSphere Version 5.1 Web Services Handbook

WSDL definition The WSDL definition contains types, messages, operations, port types, bindings, ports and services. Also, WSDL provides an optional element called wsdl:document as a container for human-readable documentation.

Types The types element encloses data type definitions used by the exchanged messages. WSDL uses XML schema definitions (XSDs) as its canonical and built-in type system: (0 or more)

The XSD type system can be used to define the types in a message regardless of whether or not the resulting wire format is actually XML. There is an extensibility element (placeholder for additional XML elements, that is) that can be used to provide an XML container element to define additional type information in case the XSD type system does not provide sufficient modeling capabilities. In our example the type definition, shown in Figure 3-5, is where we specify that there is a complex type called AddressBean, which is composed of two elements, a street and a zipcode. We also specify that the type of the street is a string and the type of the zipcode is a number (int).

Chapter 3. Introduction to WSDL

53

Figure 3-5 Types definition in the WSDL document example

Messages Messages consist of one or more logical parts. A message represents one interaction between service requestor and service provider. If an operation is bidirectional (an RPC call returning a result, for example), at least two message definitions are used in order to specify the transmission on the way to and from the service provider: (0 or more) (0 or more)

The abstract message definitions are used by the operation element. Multiple operations can refer to the same message definition. Operation and messages are modeled separately in order to support flexibility and simplify reuse of existing specifications. For example, two operations with the same parameters can share one abstract message definition. In our example, the messages definition, shown in Figure 3-6, is where we specify the different parts that compose each message. The request message

54

WebSphere Version 5.1 Web Services Handbook

updateAddressRequest is composed of an AddressBean part and an int part. The response message updateAddressResponse is composed of a string part. The fault message updateAddressFaultInfo is composed of a string part.



Figure 3-6 Message definition in our WSDL document example

Port types A port type is a named set of abstract operations and the abstract messages involved: (0 or more)

Operations WSDL defines four types of operations that a port can support: One-way

The port receives a message. There is an input message only.

Request-response The port receives a message, and sends a correlated message. There is an input message followed by an output message. Solicit-response

The port sends a message, and receives a correlated message. There is an output message followed by an input message.

Notification

The port sends a message. There is an output message only. This type of operation could be used in a publish/subscribe scenario.

Chapter 3. Introduction to WSDL

55

Each of these operation types can be supported with variations of the following syntax. Presence and order of the input, output, and fault messages determine the type of message: (0 or more) (0 or 1) (0 or 1) (0 or more)

Note that a request-response operation is an abstract notion. A particular binding must be consulted to determine how the messages are actually sent:
Within a single transport-level operation, such as an HTTP request/response message pair, which is the preferred option
As two independent transport-level operations, which can be required if the transport protocol only supports one-way communication In our example the port type and operation definition, shown in Figure 3-7, are where we specify the port type, called AddressService, and a set of operations. In this case, there is only one operation, called updateAddress. We also specify the interface that the Web service provides to its possible clients, with the input message updateAddressRequest, the output message updateAddressResponse, and the updateAddressFaultInfo that are used in the transaction.

Figure 3-7 Port type and operation definition in our WSDL document example

56

WebSphere Version 5.1 Web Services Handbook

Bindings A binding contains:
Protocol-specific general binding data, such as the underlying transport protocol and the communication style for SOAP, for example.
Protocol extensions for operations and their messages include the URN and encoding information for SOAP, for example. Each binding references one port type; one port type can be used in multiple bindings. All operations defined within the port type must be bound in the binding. The pseudo XSD for the binding looks like this: (0 or more) <-- extensibility element (1) --> (0 or more) (0 or more) <-- extensibility element (2) --> (0 or more) (0 or 1) <-- extensibility element (3) --> (0 or 1) <-- extensibility element (4) --> (0 or more) (0 or more) <-- extensibility element (5) --> (0 or more)

As we have already seen, a port references a binding. Port and binding are modeled as separate entities in order to support flexibility and location transparency. Two ports that merely differ in their network address can share the same protocol binding. The extensibility elements <-- extensibility element (x) --> use XML namespaces in order to incorporate protocol-specific information into the language- and protocol-independent WSDL specification. We introduce the extensibility elements supporting SOAP, HTTP, and MIME in “WSDL bindings” on page 59. In our example, the binding definition, shown in Figure 3-8, is where we specify our binding name, AddressSoapBinding. The connection must be SOAP HTTP and the style must be rpc. We provide a reference to our operation, updateAddress; define the input message updateAddressRequest and the output message updateAddressResponse, both to be SOAP encoded; and the fault

Chapter 3. Introduction to WSDL

57

message, which is literal. Because the fault information is always one string only, it is suitable to use literal for the encoding.

Figure 3-8 Binding definition in our WSDL document example

Service definition A service definition merely bundles a set of ports together under a name, as the following pseudo XSD definition of the service element shows. This pseudo XSD notation is introduced by the WSDL specification: (0 or more) (0 or more)

Multiple service definitions can appear in a single WSDL document.

58

WebSphere Version 5.1 Web Services Handbook

Port definition A port definition describes an individual endpoint by specifying a single address for a binding: (0 or more) (0 or more) <-- extensibility element (1) -->

The binding attribute is of type QName, which is a qualified name (equivalent to the one used in SOAP). It refers to a binding. A port contains exactly one network address; all other protocol-specific information is contained in the binding. Any port in the implementation part must reference exactly one binding in the interface part. <-- extensibility element (1) --> is a placeholder for additional XML elements

that can hold protocol-specific information. This mechanism is required because WSDL is designed to support multiple runtime protocols. For SOAP, the URL of the RPC router servlet is specified as the SOAP address here. In our example the service and port definition, shown in Figure 3-9, is where we specify our service, called AddressServiceService, that contains a collection of our ports. In this case, there is only one that uses the AddressSoapBinding and is called Address. In this port, we specify our connection point as, for example, http://localhost:9080/Router/services/Address.

Figure 3-9 Service and port definition in our WSDL document example

WSDL bindings We now investigate the WSDL extensibility elements supporting SOAP, HTTP, and MIME transport bindings. Other bindings such as EJB, JMS, and plain Java are available as well.

Chapter 3. Introduction to WSDL

59

SOAP binding WSDL includes a binding for SOAP 1.1 endpoints, which supports the specification of the following protocol-specific information:





An indication that a binding is bound to the SOAP 1.1 protocol A way of specifying an address for a SOAP endpoint The URI for the SOAPAction HTTP header for the HTTP binding of SOAP A list of definitions for headers that are transmitted as part of the SOAP envelope

Table 3-2 lists the corresponding extension elements. Table 3-2 SOAP extensibility elements in WSDL Extension and attributes

Explanation



Binding level; specifies defaults for all operations.

transport="uri" (0 or 1)

Binding level; transport is the runtime transport protocol used by SOAP (HTTP, SMTP, ...).

style="rpc|document" (0 or 1)

The style is one of the two SOAP communication styles, rpc or document.

soapAction="uri" (0 or 1)

URN.

style="rpc|document" (0 or 1)

See binding level.



Extends operation definition; specifies how message parts appear inside the SOAP body.

parts="nmtokens"

Optional; allows externalizing message parts.

use="encoded|literal"

encoded: messages reference abstract WSDL type elements; encodingStyle extension used literal: messages reference concrete XSD (no WSDL type); usage of encodingStyle is optional.

encodingStyle= "uri-list"(0 or 1)

List of supported message encoding styles.

namespace="uri" (0 or 1)

URN of the service.



60

Extends operation definition.

Extends operation definition; contents of fault details element.

WebSphere Version 5.1 Web Services Handbook

Extension and attributes

Explanation

name="nmtoken"

Relates soap:fault to wsdl:fault for operation.

use, encodingStyle, namespace

See soap:body.

location="uri"

Extends port definition. Network address of RPC router.



Operation level; shaped after .



Operation level; shaped after .

For an example of extensibility elements, refer to Figure 3-8 on page 58. Note that the WSDL specification deals with encoding only. The mappings to be used for a specific type under a certain encoding are beyond the scope of this book. They are part of the SOAP client and server runtime configuration (client API and deployment descriptor, respectively).

HTTP binding WSDL includes a binding for HTTP 1.1 GET and POST verbs to describe the interaction between a Web browser and a Web application. This allows applications other than Web browsers to interact with the application (its controller servlets, for example). The following protocol-specific information is required to describe a Web service that can be accessed through HTTP:
An indication that a binding uses HTTP GET or POST
An address for the port
A relative address for each operation (relative to the base address defined by the port) Table 3-3 lists the defined extension elements. Table 3-3 HTTP extension elements in WSDL Extension

Explanation



Extends the port definition and contains the base URL.



The HTTP operation to be performed (nmtoken=GET or POST).

Chapter 3. Introduction to WSDL

61

Extension

Explanation



Extends the operation binding and specifies the relative URL.



Message parts are encoded into the HTTP request URI using the standard URI-encoding rules.



Message parts are encoded into the HTTP request URI using a replacement algorithm.

MIME extension elements might have to be used as well (see the next section).

MIME binding The response message of a Web service might be formatted according to the MIME format multipart/related, returning mixed content, such as images and text documents. WSDL provides support for describing such messages. Table 3-4 lists the extensions that are available to describe a Web service that can be accessed via MIME. Table 3-4 MIME extension elements in WSDL Extension name

Explanation



Name and MIME type of WSDL message part



Describes each part of a multipart/related message



Same as in SOAP binding



For XML elements that do not travel inside a SOAP envelope

WSDL API There is a WSDL Java API called WSDL4J, exposing the WSDL object model. Its capabilities include the parsing of the contents of a WSDL document and programmatic creation of new WSDL documents. Note that it is always possible to use XML parsers or XSL transformations. Currently, WSDL4J is an open-source project available on the IBM developerWorks Web site: http://www-124.ibm.com/developerworks/projects/wsdl4j/ http://www-136.ibm.com/developerworks/opensource

62

WebSphere Version 5.1 Web Services Handbook

WSDL4J will be a reference implementation for JSR 110 (Java APIs for WSDL). Primarily it is a set of Java interfaces that can be implemented by anyone. The Java package name is javax.wsdl. Figure 3-10 is an example in which we provide a function to obtain all the port addresses available for a specific SOAP binding in a specified WSDL document. These addresses are returned in a vector element of strings with the URL locations.

private Vector getWSDLPort(String fileName, String serviceName) { final String serviceNameSpace = "http://wsoj.itso"; int endPointCounter = 0; Service service; Port port = null; Vector serviceEndpoint = new Vector(); try { // Read WSDL document and get definitions element WSDLFactory wsdlFactory = WSDLFactory.newInstance(); WSDLReader wsdlReader = wsdlFactory.newWSDLReader(); Definition definition = wsdlReader.readWSDL(null,fileName); // Get the ports for the WeatherForecast_SEIService service = definition.getService(new QName(serviceNameSpace,serviceName)); Map ports = service.getPorts(); Collection values = ports.values(); for (Iterator iterator = values.iterator(); iterator.hasNext();) { port = (Port) iterator.next(); List list = port.getExtensibilityElements(); for (Iterator iter = list.iterator(); iter.hasNext();) { // The SOAP binding is an extensibility element of Port ExtensibilityElement element = (ExtensibilityElement) iter.next(); if (element instanceof SOAPAddress) { SOAPAddress soapAddress = (SOAPAddress) element; serviceEndpoint.add(soapAddress.getLocationURI()); } } } } catch (WSDLException e) { e.printStackTrace(); } return serviceEndpoint; } Figure 3-10 WSDL API example

Chapter 3. Introduction to WSDL

63

Outlook The WSDL 1.1 is currently in the process of being standardized by the W3C. On the other hand, new working draft specifications Web services description language (WSDL) Version 1.2 and Web services description language (WSDL) Version 1.2: Bindings have been released. These specifications provide a new conceptual framework approach to improve the operability and the components definition. Version 1.2 enhancements to Version 1.1 are:
WSDL 1.2 includes language clarifications that make it easier for developers to understand and use WSDL.
WSDL 1.2 provides support for W3C recommendations, including XML Schemas and XML Information Set. XML Information Set (Infoset) is an abstract data set that provides a consistent set of definitions for use in other specifications that need to refer to the information in a well-formed XML document. See: http://www.w3.org/TR/xml-infoset/


WSDL 1.2 adopts a conceptual framework approach to define the description components, which makes them simpler and more flexible.
WSDL 1.2 provides a better definition for the HTTP 1.1 binding and will soon provide a binding for SOAP 1.2, which allows description of services using the most current version of SOAP. Tool support for WSDL is already available, as covered in Part 2, “Web services implementation and samples” on page 201. An example of another innovation in the WSDL area is the Web services invocation framework (WSIF), providing a WSDL-centric service requestor API. WSIF is transport agnostic; thus a single WSIF client can support multiple runtime protocols simultaneously, such as SOAP, a direct HTTP connection, and a local Java call. See Chapter 7, “Web services invocation framework” on page 129.

64

WebSphere Version 5.1 Web Services Handbook

Summary This introduction has shown the power of WSDL. WSDL provides an abstract part that is language and protocol independent, as well as bindings for the runtime protocols used in the service-oriented architecture (SOA). This chapter has also shown that even a simple Web service definition has to cover many interrelated aspects yielding a rather complex specification file. Writing WSDL documents from scratch is an error-prone task; therefore, there is a strong need for tool support. We cover these tools in Part 2, “Web services implementation and samples” on page 201.

More information As of today, few WSDL tutorials or other supporting information are available. As WSDL becomes more widespread, this will change. Good sources for more information are the IBM WebSphere Development Kit for Web Service (WSDK, see Chapter 18, “WebSphere SDK for Web Services” on page 381) and the WSDL 1.1 specification. WSDL 1.1 is contained in the IBM WSDK and can also be found at: http://www.w3.org/TR/wsdl For further information about WSDL Version 1.2, visit: http://www.w3.org/TR/wsdl12 http://www.w3.org/TR/wsdl12-bindings

Chapter 3. Introduction to WSDL

65

66

WebSphere Version 5.1 Web Services Handbook

4

Chapter 4.

JAX-RPC (JSR 101) This chapter explains the Java API for XML-based Remote Procedure Call (JAX-RPC) style programming model. The JAX-RPC programming model is defined by the Web services standard JSR 101. JSR 101 formalizes the procedure for invoking Web services in an RPC-like manner. It is a required part of the J2EE 1.4 specification, but due to huge demand of this programming model, IBM it also provides on the J2EE 1.3 platform. This support has been provided out-of-the-box in WebSphere 5.0.2 and later. JSR 101 is not new to WebSphere. A sneak preview of JSR 101 was available in the WebSphere Web Services Technology Preview, which was based on WebSphere 5.0 and was intended to be a development level add-on. In WebSphere 5.0.2 and 5.1, JSR 101 is not only fully supported for production, but it also forms the default runtime infrastructure. JAX-RPC is a newly defined specification of distributed computing. Some of the earlier specifications of distributed computing are Java’s RMI-IIOP, OMG’s CORBA, Microsoft’s COM, and so forth.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

67

Terminology: JAX-RPC and JSR 101 Let us start with discussing the terminology. In Web services discussions, the terms JAX-RPC and JSR 101 are used quite interchangeably. This chapter also uses both the terms. However, at their core, they do not mean the same thing. There is a distinction between these terms. JAX-RPC is the programming style and JSR 101 is the specification document. JSR 101 lays down the requirements of JAX-RPC 1.0. Over time, as JAX-RPC picks up more momentum, it will encompass wider usage scenarios and may at that point implement newer JSRs in addition to or instead of JSR 101.

JAX-RPC basics Java API for XML-based RPC (JAX-RPC), as the name suggests, is a Java API that facilitates distributed computing in a Web services environment. JAX-RPC based Java applications can easily communicate with non-Java based technologies in the RPC style fashion. JAX-RPC compliance mandates client-side requirements as well as server-side requirements. Figure 4-1 and Figure 4-2 show JSR 101 clients and the JSR 101 server, respectively. JSR 101 clients can interoperate with any JAX-RPC compliant server.

JAX-RPC Clients (JSR 101 based) In a J2EE SERVER Container Servlet orJavaBean or session EJB (managed or unmanaged) In a J2EE CLIENT Container

Web Services Provider (SOAP-RPC compliant)

Java class with main() method using /bin/launchclient (managed or unmanaged) Standalone Java Client

Based on J2EE, .NET or any WS-RPC compliant technology

Java class with a main() method using /bin/java (unmanaged only)

Figure 4-1 JSR 101 client interoperates with any SOAP-RPC compliant server

68

WebSphere Version 5.1 Web Services Handbook

A JAX-RPC server can interoperate with any SOAP-RPC client, Java based or otherwise.

JSR 101 client In a J2EE SERVER container In a J2EE CLIENT container STANDALONE Java client

JAX-RPC Server "endpoint" (JSR 101 based)

.NET client WS-RPC compliant client

Non-Java, non-MicroSoft WS-RPC compliant client

JSR 101 compliant J2EE engine such as WebSphere 5.0.2 or 5.1

Figure 4-2 JSR 101 server interoperates with any SOAP-RPC compliant client

A JAX-RPC server application’s entry point is also known as an endpoint. A Web service endpoint is described using a Web services description language (WSDL) document. JAX-RPC is about Web services interoperability across heterogeneous platforms and languages. This makes JAX-RPC a key technology for Web services based integration.

JAX-RPC client A JAX-RPC client is capable of invoking a Web service irrespective of whether the service has been defined on the J2EE platform or on a non-Java platform. JAX-RPC clients do not necessarily have to be Java clients. For Java clients to be JAX-RPC compliant, they have to comply with JSR 101. Figure 4-1 explains the various forms of JAX-RPC clients. JAX-RPC clients can run inside a J2EE container or as a standalone Java client. If running inside a J2EE container, they can be coded as managed or unmanaged clients. If running as a standalone Java client, they can only be unmanaged. We will discuss unmanaged and managed clients in “Managed and unmanaged JAX-RPC clients” on page 74. Example 4-1 shows the most simple example of a JAX-RPC client.

Chapter 4. JAX-RPC (JSR 101)

69

Example 4-1 Simple JAX-RPC client package itso.test; import java.io.*; import java.util.*; import itso.test.*; public class WeatherForecastClient { public static void main(String [] args){ try{ WeatherForecastServiceLocator wsl = new WeatherForecastServiceLocator(); WeatherForecastService ws = (WeatherForecastService) wsl.getWeather(); String temperature = ws.getTemperature(); System.out.println(temperature); System.out.println("WeatherForecastClient completed"); } catch (Exception e) { e.printStackTrace(); } } }

In this example, we have highlighted the three essential operations of a JAX-RPC client:
Instantiate the locator class. The locator class has information about the Web service. The locator class is populated based on the content of the Web service’s WSDL file.
Instantiate the service using the locator class. The service interface is a local representation of the Web service. The service interface is implemented by the so-called stub class.
Invoke a method on the service interface.

JAX-RPC client programming styles If the Web service is not expected to ever change, the above mechanism of Example 4-1 works very well. This mechanism is known as static stub based invocation of a Web service. But if the Web service were to change, the client would have to be changed accordingly. We therefore provide capability for clients to be dynamic. There are three types of Web services clients (Figure 4-3):
Static stub
Dynamic proxy
Dynamic invocation interface (DII)

70

WebSphere Version 5.1 Web Services Handbook

JAX-RPC clients

Proxy based

No proxy

1. Static Stub

2. Dynamic Proxy

Tightly bound to the locator class Not dynamic

Loosely bound to the locator class Partially dynamic

3. Dynamic Invocation Interface (DII) Locator class not used Fully dynamic

Figure 4-3 Static and dynamic JAX-RPC clients

Static stub Let us fully understand the static stub client of Example 4-1 on page 70. A static stub-based JAX-RPC client uses proxy classes to communicate with the Web service (Figure 4-4). These proxy classes are generated from the WSDL of the Web service. In the WebSphere Application Server, the proxy classes can be generated by the tool /bin/WSDL2JAVA. Once the proxy classes have been generated, they are copied to the client machine. The client can then invoke the Web service based only on these proxy classes.

Proxy based JSR 101 client WeatherForecastClient.java

Proxy classes

JSR 101 compliant Web service

WeatherForecast.java WeatherForecastService.java WeatherForecastServiceLocator.java WeatherForecastSoapBinding.java

Figure 4-4 Proxy-based JAX-RPC client

Chapter 4. JAX-RPC (JSR 101)

71

The four proxy classes are:
Service endpoint interface (SEI): WeatherForecast—defines the method signatures of the Web service
Service interface: WeatherForecastService—defines the service methods of the locator class (for example, retrieving the SEI)
Service locator class: WeatherForecastServiceLocator—implements the service interface (provides access to the SEI)
Binding stub: WeatherForecastSoapBinding—implements the SEI (makes the actual calls to the Web service)

J2SE

Supports JavaBean Web services only

J2EE JavaBean

instance

1

Service Object (Factory)

Service Client

Client Stub

3

2 Service Interface

Transport

Service Endpoint Implementation

WSDL

Service Endpoint Interface

3

Service Endpoint Interface

JAX-RPC runtime

Figure 4-5 JAX-RPC static client calling sequence

At runtime, the client instantiates the service locator class, calls it to retrieve the SEI (actually the binding stub), then calls the SEI to invoke the Web service. Figure 4-5 shows the calling sequence in a Java implementation. 1. The client instantiates the service locator. 2. The client calls the service locator to retrieve the SEI (an instance of the client stub that implements the SEI is returned). 3. The client invokes a Web service through the SEI. The client can be a J2SE client that invokes a Web service in a J2EE-compliant application server. The Web service implementation is a JavaBean. To support an EJB Web service, refer to Chapter 5, “Implementing Enterprise Web Services (JSR 109)” on page 77.

72

WebSphere Version 5.1 Web Services Handbook

Dynamic Proxy Let us see an example of a dynamic proxy-based JAX-RPC client (Example 4-2). In dynamic proxy clients, the default destination of the Web service can be changed in the client by specifying a different destination in the client application. Example 4-2 Dynamic proxy client - only partially dynamic import javax.xml.namespace.QName; import java.io.*; import java.util.*; public class WeatherForecastDynamicProxyClient { public static void main(String [] args){ try{ WeatherForecastServiceLocator wsl = new WeatherForecastServiceLocator(); QName qn = new QName("http://www.somewhere.com", "WeatherForecast"); WeatherForecast ws = (WeatherForecast) wsl.getPort(qn,WeatherForecast.class); String temperature = ws.getTemperature(); System.out.println(temperature); System.out.println("DynamicProxyJavaClient completed"); } catch (Exception e){ e.printStackTrace(); } } }

At runtime the service locator is instantiated. The SEI is retrieved using a destination (QName).

Dynamic invocation interface (DII) DII is used when the WSDL of the Web service can change considerably over time. DII-based clients do not use proxy classes, but instead read the entire WSDL file during runtime:





Instantiate a DII service class. Instantiate a Call object (Call is a class provided by JAX-RPC). Populate the Call object. Invoke the Web service operation on the Call object.

Chapter 4. JAX-RPC (JSR 101)

73

Which style to use Table 4-1 lists the usage scenarios of the three styles. Table 4-1 Client styles Static stub

Dynamic proxy

DII

Web service not expected to change

Some changes to the Web service expected, such as the location of the service

Considerable changes to the Web service expected, such as: - Location of the service - Request/response format - Data types

Most common scenario

Less common

Less common

Managed and unmanaged JAX-RPC clients So far we have discussed unmanaged JAX-RPC clients. Managed clients allow the J2EE container to instantiate the proxy classes. Example 4-3 shows a code snippet of a managed, dynamic proxy-based JAX-RPC client. A static stub-based client can also be coded as managed clients. Example 4-3 Managed, dynamic proxy-based client InitialContext ic = new InitialContext(); WeatherForecastServiceLocator wsl = (WeatherForecastServiceLocator) ic.lookup("java:comp/env/service/WeatherForecastService"); QName qn = new QName("http://www.somwhere.com", "WeatherForecast"); WeatherForecast ws = (WeatherForecast) wsl.getPort(qn,WeatherForecast.class); String temperature = ws.getTemperature(); System.out.println(temperature); System.out.println("DynamicProxyJavaClient completed");

The main difference in a managed client and unmanaged client (Example 4-2 on page 73 versus Example 4-3) is the way the WeatherForecastServiceLocator class is instantiated:
For a managed client the locator class is instantiated by the container, by calling the lookup method on the default InitialContext.
For an unmanaged client the locator class is instantiated by calling a constructor of the locator class.

74

WebSphere Version 5.1 Web Services Handbook

JAX-RPC specification details JSR 101 provides details about JAX-RPC. Here we provide a brief idea of what lies therein.

Data type mapping: XML -> Java, Java -> XML JAX-RPC data flows as XML. For this purpose, the JAX-RPC client has to convert Java data types into XML and the JAX-RPC server has to convert XML data into Java data types, and vice versa on the result flow (Figure 4-6).

Java to XML 1 mapping

JAX-RPC Client

Input

XML to Java 2 mapping

SOAP messages XML to Java 4 mapping

Output

Java to XML 3 mapping

JAX-RPC Server

Figure 4-6 Mapping and encoding stages for a Web service

Support is provided to convert simple data types, such as xsd:string and xsd:integer to java.lang.String and java.math.BigInteger, and so on. The complete list is available at http://schemas.xmlsoap.org/soap/encoding/. In addition to simple data types, JAX-RPC also specifies the mapping of data structures such as arrays. These arrays can contain elements of simple data types or of user-defined data types (JavaBeans). Refer to the specification for details about the mappings. There are four steps in the process, indicated by the numbers in Figure 4-6: 1. Client input mapping (Java to XML)—This takes the parameter from the Java client and maps it using the input mapping style. 2. Server input mapping (XML to Java)—The inbound parameters are deserialized from the XML style in the message to Java types, which are then used to invoke the method in the JavaBean. 3. Server output mapping (Java to XML)—Once the JavaBean has completed its method execution, the return value is inserted into the SOAP reply using the output mapping style. 4. Client output mapping (XML to Java)—The final stage is performed by SOAP for the client proxy, which maps the returned XML elements into Java types.

Chapter 4. JAX-RPC (JSR 101)

75

Summary In this chapter we described JAX-RPC, as defined by the Web services standard JSR 101. We looked at JAX-RPC servers and clients, and the different styles of clients, static and dynamic.

More information The complete JSR 101 specification is at: http://www.jcp.org/en/jsr/detail?id=101 These are some informative article on the IBM developerWorks Web site: http://www-106.ibm.com/developerworks/webservices/library/ws-jsrart/ http://www-106.ibm.com/developerworks/webservices/library/ws-jaxrpc1 http://www-106.ibm.com/developerworks/xml/library/x-tipjaxrpc/

76

WebSphere Version 5.1 Web Services Handbook

5

Chapter 5.

Implementing Enterprise Web Services (JSR 109) This chapter provides a general view to introduce the Web Services for J2EE architecture, JSR 109. This is an architecture that standardizes the deployment of Web services in a Java 2 Platform, Enterprise Edition (J2EE) to create portable and interoperable services across different server platforms. At the time of the writing of this book, there is a public draft version 1.1 that removed J2EE 1.3 deployment requirements, but this chapter concentrates more on the final release 1.0. In this chapter, we discuss the following topics:






JSR 109 overview Client programming model Server programming model Handlers Security

© Copyright IBM Corp. 2003, 2004. All rights reserved.

77

JSR 109 overview Prior to the appearance of the Web Services for J2EE specification (JSR 109) there was no standard definition of how deploy a Web service in a J2EE platform. Thus, the process to do so was largely dependant on the destination runtime. JSR 109 standardizes the process, making it portable to every compliance J2EE server platform. JSR 109 leverages J2EE technology defining the needed mechanism to standardize a deployment model for Web services. This standardization wants to achieve the interoperability across different compliance J2EE platforms, transforming the migration among them into a routine process ensuring that vendors interoperate. JSR 109 defines the minimal new concepts, interface, file formats, and so forth, to support a simple model for defining and deploying Web services. Programmers ensure that their Web services can be deployed later in servers that comply with J2EE and JSR 109 specifications; meanwhile, the complexity of the process is hidden from them. JSR 109 also defines the required roles and their functions, and perform and their mapping to the J2EE platform roles. JSR 109 adds additional artifacts to those defined by JAX-RPC (see Chapter 4, “JAX-RPC (JSR 101)” on page 67), bringing JAX-RPC to the J2EE container components. Although the JSR 109 does not restrict any implementation, it is only defined for two implementations:
Stateless session EJB in an EJB container
Java class in a Web container For these two implementation models and for both client and server sides, the specification details are:
The programming model for J2EE components with Web services – How J2EE server components can be defined to be accessible as Web services – How J2EE client components and applications can use JAX-RPC to access Web services
The assembly of the components with Web services
The deploying of these components as Web services components – How J2EE server components can be described as Web services – How J2EE client components can be described for accessing Web services using JAX-RPC

78

WebSphere Version 5.1 Web Services Handbook

JSR 109 and JAX-RPC provide the standard programming and deployment model that will be an integral part of the J2EE 1.4 specification.

Client programming model In this section we describe the client programming model. We provide an overview of the characteristics of the client, a description of the different clients, an explanation of the deployment descriptors used in the client side, and a description of the roles that take part in the application development cycle.

Overview The client programming model provides the client guidelines for access to Web services in a J2EE environment. This client should be conformant with the client programming model defined by JAX-RPC (see Chapter 4, “JAX-RPC (JSR 101)” on page 67). However, Web services clients are not limited to those defined in this specification, which only covers those who run in a J2EE environment. Programmers can be sure that clients conformant to this specification can access any Web service running in a Web Services for J2EE container and can call any SOAP 1.1 Web service through HTTP/S SOAP Binding. How the service implementation is realized has to be transparent to the client. The client can be another Web service, J2EE component, or an arbitrary Java application. The client invokes Web service methods without distinguishing whether those are performed locally or remotely in a J2EE runtime environment. The client has not control the life cycle of the Web service only access to it. The port provider and the container configure the view of the client that includes:
Service interface—Defines the methods to access a port of a Web service
Service endpoint interface—Defines the methods to call a Web service Figure 5-1 shows an architectural model of a general client.

Chapter 5. Implementing Enterprise Web Services (JSR 109)

79

J2EE Client Container

JNDI Context

Client Application

Service Implementation

Stub Implementation

Service Interface

Service Endpoint Interface

Figure 5-1 General client architectural model

Client types The client uses a JNDI lookup to find the service interface. The container is responsible for the boundary between the JNDI name and the service implementation. With the service interface the client can get:
Static stub—Requires WSDL knowledge that has service location included
Dynamic proxy—May have only partial WSDL definition
Dynamic invocation interface (DII)—Does not require WSDL knowledge

Static stub The static stub client uses a defined service endpoint interface (SEI) based on the WSDL document to get a stub for a specific Web service. The stub is the local representation of the remote Web service and is used by the client to invoke the Web service. This client is the easiest of the three of them, but the small change in the WSDL document provokes the client useless; the stub has to be regenerated. Consequently, the use of this client is only recommended for stable and reliable Web service, where the probability for a modification in the Web service definition is practically zero. Figure 5-2 shows the static client calling sequence in a Java environment:
The client uses JNDI to get an instance of the service locator. The JNDI name is defined in the client deployment descriptor.
The client invokes the service locator to retrieve the SEI (actually an instance of the client stub that implements the SEI is returned).
The client invokes a Web service through the SEI.

80

WebSphere Version 5.1 Web Services Handbook

J2EE

Supports EJB Web services

J2EE JavaBean

JNDI

1

Service Object (Factory)

Client Stub

2

3

Service Client

Service Interface

Transport

EJB

Service Endpoint Implementation

WSDL

Service Endpoint Interface

3

Service Endpoint Interface

JAX-RPC runtime Client DD

Deployment Descriptor

Server DD

Figure 5-2 JSR 109 static client calling sequence

A simple coding sequence is shown here: InitialContext ic = new InitialContext(); BankEJBServiceLocator locator = (BankEJBServiceLocator)ic.lookup ("java:comp/env/service/BankEJBService"); BankEJB proxy = (BankEJB)locator.getBankEJB(); Account account = proxy.getAccount(accountId); // call Web service

Dynamic proxy The dynamic proxy client uses a generic service endpoint interface (SEI). Therefore, the client is not bound to an implemented stub and it is in runtime when a specific SEI is instantiated. From here, the client uses the same mechanism used by the static stub to invoke the Web service. This client presents some advantage to the static client for testing purposes, when the Web service definition is not perfectly closed.

Dynamic invocation interface (DII) The dynamic invocation interface uses a javax.xml.rpc.Call instance for dynamic invocation. Unlike the two previous clients, the DII has to previously configure the Call object, providing the following information:
Operation name
Parameters names, types and modes

Chapter 5. Implementing Enterprise Web Services (JSR 109)

81


Port type and address of a target service endpoint
Protocol and transport properties

Deployment descriptors The deployment descriptors used for the client programming model are the Web service client deployment descriptor, webservicesclient.xml, and the JAX-RPC mapping deployment descriptor (without a standard name).

Web service client deployment descriptor This deployment descriptor contains the service reference entries. The references are used by a J2EE component container to deploy the client. Example 5-1 shows a sample webservicesclient.xml file. Example 5-1 webserviceclient.xml of Weather service WSDL Service WeatherForecastService service/WeatherForecastService itso.session.WeatherForecastService WEB-INF/wsdl/WeatherForecast.wsdl WEB-INF/WeatherForecast_mapping.xml http://session.itso WeatherForecastService itso.session.WeatherForecast

Each Web service used by a client has to be defined in a service-ref element. A service-ref element has: Description

82

The human-readable description of our Web service. In our example, WSDL Service WeatherForecastService.

WebSphere Version 5.1 Web Services Handbook

Service ref name

The logical name of the reference used by JNDI to look up the service reference. In our example, service/WeatherForecastService.

Service type

The fully qualified name of the service interface returned by the JNDI lookup. In our example, itso.session.WeatherForecastService.

WSDL definition

The location of the WSDL description of the service. In our example, WEB-INF/wsdl/WeatherForecast.wsdl.

JAX-RPC mapping

The location of the WSDL-Java mapping file. In our example, WEB-INF/WeatherForecast_mapping.xml.

Service port

The qualified name of the referenced WSDL service. In our example, the namespace URI is http://session.itso and the service is WeatherForecastService.

Ports

The port component provides the local representation of our Web service, the service endpoint interface. In our example, itso.session.WeatherForecast.

Scope

If the client is an EJB, the scope provides the association between the service and the EJB client using the component-scope-refs. Our example is a servlet client; scope is not needed.

Handlers

The handlers associated with the Web service reference. In our example, there is no one.

JAX-RPC mapping deployment descriptor This deployment descriptor contains the mapping information between the WSDL definition and the Java interfaces. The main elements that compose a JAX-RPC mapping deployment descriptor are:
The package mapping—Contains the relation between the XML namespace and Java packages: itso.mapping http://mapping.itso


The type mapping—Contains the type mapping between Java types and XML types. It is the most remarkable component: itso.mapping.Weather http://mapping.itso

Chapter 5. Implementing Enterprise Web Services (JSR 109)

83

Weather complexType condition condition .... windSpeed windSpeed ....

The four fundamental elements are: – Class type—Contains the fully qualified name of the Java bean that stands for the type (in our example, itso.mapping.Weather). – Root qname—Contains the qualified name of the bean as it appears in the WSDL definition (in our example, the namespace URI is http://mapping.itso and the local name is Weather). – Scope—Contains the scope of the type. Possible values are simpleType, complexType and element (in our example, complexType). – Variables—Contains the mappings between the data members of the Java bean and the XML elements (in our example, condition, windSpeed and others).
The service interface mapping—Contains the mapping for the WSDL service definition: itso.session.WeatherForecastService http://session.itso WeatherForecastService WeatherForecast WeatherForecast

84

WebSphere Version 5.1 Web Services Handbook

The three fundamental elements are: – Service interface—Contains the fully qualified name of the service interface Java class (in our example, itso.session.WeatherForecastService) – Service name—Contains the qualified name of the service as it appears in the WSDL definition (in our example, the namespace URI is http://session.itso and the local name is WeatherForecastService) – Port mapping—Contains the mapping for the WSDL ports (in our example, WeatherForecast)
The service endpoint interface mapping—Contains the fully qualified class name of the service endpoint interface. It also contains the mappings for WSDL messages, port types and bindings: itso.session.WeatherForecast http://session.itso WeatherForecast http://session.itso WeatherForecastSoapBinding getDayForecast getDayForecast ........

Roles There are no new J2EE roles defined for the JSR 109 specification. The roles are mapped to existing J2EE roles. The three roles presented in the JSR 109 are:
Developer—Responsible for client definition, implementation and packaging within J2EE modules
Assembler—Responsible for assembling the modules into an application
Deployer—Responsible for publishing the deployed clients and resolving client references A more detailed description of the roles’ responsibilities is shown in Table 5-1.

Chapter 5. Implementing Enterprise Web Services (JSR 109)

85

Table 5-1 Roles’ responsibilities for client side Developer Client implementation

Implement the client. May implement handlers.

Web services client DD

Define service references. May define handler references.

JAX-RPC mapping DD

Provide the mapping.

Application server

Assembler

Deployer Generate the stubs from the JAX-RPC mapping DD information.

May configure handlers. Assembly modules in an EAR file.

Resolve service and port references.

Deploy the application.

Server programming model In this section we describe the server programming model. We provide an overview about the characteristic of the server, a description of the different server implementations, an explanation of the deployment descriptors used on the server side, and a description of the roles that take part in the application development cycle.

Overview The server programming model provides the server guidelines for standardizing the deployment of Web services in a J2EE environment. Depending on the runtime environment, two implementation models are described:
Web container—A Java class according to a JAX-RPC servlet based service
EJB container—A stateless session EJB Either of them provides the information to define a port component. A port component defines the server view of a Web service providing a portable Web services programming model. A port component makes available a service entry point defined in a WSDL port address to grant access to the operations stated in the WSDL definition. Each port model has a service endpoint interface that defines the operations exposed by a Web service and a service implementation bean that implements the business logic for all the operations defined in the service endpoint interface.

86

WebSphere Version 5.1 Web Services Handbook

The implementation and the packaging of that service depend upon the container where the port is deployed in. The life cycle can vary based on the implementation methodology used and is totally controlled by the associated container. In general, the life cycle of a Web service follows the same steps of its container. A port is created, initialized, executed and destroyed following the container criteria and without port operations interference. Figure 5-3 shows an architectural model of a general server.

J2EE Server Container Port

Web Service Client

Listener

Service Endpoint Implementation

Service Endpoint Interface

WSDL Figure 5-3 General server architectural model

Server The fundamental part of a Web service is the port component. A port component defines the programming model artifacts that make the Web service a portable server application. That programming model includes:
WSDL definition—Provides the description of a Web service.
Service endpoint interface (SEI)—Defines the operations available for a Web service. Must follow JAX-RPC mapping rules.
Service implementation bean—Implements the SEI methods to provide the business logic of a Web service.
Security role references—Provides instance level security check across the different modules.

Chapter 5. Implementing Enterprise Web Services (JSR 109)

87

Service implementation bean The service implementation bean can be implemented in two different ways: A stateless session EJB or a JAX-RPC servlet-based service, depending on the container where the service implementation bean is deployed in.

EJB container programming model A stateless session EJB can be used to implement a Web service. That stateless session EJB has to follow some requirements:
The stateless session EJB must have a default public constructor, a default EJB create method, and an EJB remote method.
The service endpoint interface has to be a subset of the methods stated in the remote interface of the stateless session EJB. Those methods must be public, but neither final nor static.
The stateless session EJB must be a stateless object.
The class must be public, but neither final nor abstract.
The class must not a defined finalize method. Because the stateless session EJB runs in an EJB container, the life cycle of the implementation bean is the same as is stated in the Enterprise JavaBeans specification. This life cycle is shown in Figure 5-4.

does not exit 1. newInstance() 2. setSessionContest(sc) 3. ejbCreate() SEI method

Action initiated by Web service client Action initiated by EJB container

ejbRemove()

method ready

ejbTimeout(arg)

Figure 5-4 Life cycle of a service implementation bean in an EJB container

The EJB container uses the ejbCreate and the ejbRemote methods to notify a service implementation bean instance of a change in its state. Once the container has called the ejbCreate method, the service implementation bean is ready for dispatching a request to clients using any of the SEI methods defined for the Web service. The dispatching of these SEI methods is initiated by the client.

88

WebSphere Version 5.1 Web Services Handbook

The stateless session EJB is packaged in an EJB JAR file that contains all the required classes, the WSDL definition, and the Web services deployment descriptors. Finally, the modules containing the port components are packaged in an EAR file following the J2EE specifications.

Web container programming model A Java class can be used to implement a Web service. That Java class follows the JAX-RPC specifications to create a service implementation bean that runs within a Web container (see Chapter 4, “JAX-RPC (JSR 101)” on page 67). Thus, the Java class requirements are:
The Java class must have a default public constructor.
The Java class must implement the method signatures of the service endpoint interface. Only those methods are exposed to the client.
The Java class must be stateless.
The Java class must be public, but neither final nor abstract.
The Java class must not be defined finalize method. The Java class life cycle is controlled by a Web container, as is shown in Figure 5-5.

does not exit 1. newInstance() 2. init()

SEI method

Action initiated by Web service client Action initiated by Web container

destroy()

method ready

Figure 5-5 Life cycle of a service implementation bean in a Web container

The Web container uses the init and the destroy methods to notify a service implementation bean instance of a change in its state. Once the container has called the init method, the service implementation bean is ready for dispatching requests to clients using any of the SEI methods defined for the Web service. The dispatching of these SEI methods is initiated by the client. The Java class is packaged in a WAR file that contains all the required classes, the WSDL definition, and the Web services deployment descriptors. Finally, the

Chapter 5. Implementing Enterprise Web Services (JSR 109)

89

modules containing the port components are packaged in an EAR file following the J2EE specifications.

Server container responsibilities A server container provides a JAX-RPC runtime environment for invoking Web services ports. The container is responsible for:
Listening to Web services SOAP HTTP request
Parsing the inbound message
Mapping the messages to the implementation class and method
Creating Java objects from the SOAP envelope
Invoking the service implementation bean handlers and instance methods
Capturing the response
Mapping the Java response objects into a SOAP message
Creating the message envelope
Sending the message to the client

Deployment descriptors The deployment descriptors used for the server programming model are the Web service deployment descriptor, webservices.xml, and the JAX-RPC mapping deployment descriptor without a standard name.

Web service deployment descriptor This deployment descriptor defines the Web services to deploy in a J2EE container and defines the mapping between WSDL ports and port components. The deployment information is presented in the module-specific deployment descriptor, ejb-jar.xml or web.xml, and in the Web service deployment descriptor. Example 5-2 shows a sample webservices.xml file. Example 5-2 webservice.xml of Weather service WeatherForecastService META-INF/wsdl/WeatherForecast.wsdl META-INF/WeatherForecast_mapping.xml

90

WebSphere Version 5.1 Web Services Handbook

WeatherForecast http://session.itso WeatherForecast itso.session.WeatherForecast_SEI WeatherForecast

Each Web service used by a client has to be defined in a webservice-description element. A webservice-description element has: Service name

The unique name of the WSDL service. This name is the same name of the wsdl:sevice element. In our example, WeatherForecastService.

WSDL file

The location of the WSDL description of the service. In our example, META-INF/wsdl/WeatherForecast.wsdl.

JAX-RPC mapping

The location of the WSDL-Java mapping file. In our example, WEB-INF/WeatherForecast_mapping.xml.

Port

The port component defines the server view, providing the access point and implementation details. name

The unique name of the WSDL port element for this service. This name is the same name of the wsdl:port element. In our example, WeatherForecast.

qname

The qualified name of the referenced WSDL port. In our example, the namespace URI is http://session.itso and the port is WeatherForecast.

SEI

The fully qualified class name of the service endpoint interface. In our example, itso.session.WeatherForecast_SEI.

bean class

The implementation name of the Web service. In our example, WeatherForecast. This name must match the name of the ejb-name element stated in the ejb-jar.xml file. For the Web container programming model the servlet-link element is used in the webservices.xml

Chapter 5. Implementing Enterprise Web Services (JSR 109)

91

and the name must match the name of the servlet-name stated in the web.xml file. Handlers

The handlers associated with the Web service reference. In our example, there is no one.

JAX-RPC mapping deployment descriptor This deployment descriptor contains the mapping information between the WSDL definition and the Java interfaces. There are not differences from the deployment descriptor of the client, because both of them are mapping to the WSDL file that it is the same for both sides. Please refer to “JAX-RPC mapping deployment descriptor” on page 83 for a JAX-RPC mapping deployment descriptor explanation.

Roles There are no new J2EE roles defined for the JSR 109 specification. The roles are mapped to existing J2EE roles. The three roles presented in the JSR 109 are:
Developer—Responsible for service definition, implementation, and packaging within J2EE modules
Assembler—Responsible for assembling the modules into an application
Deployer—Responsible for publishing the deployed services and resolving server references More detailed descriptions of the roles’ responsibilities are shown in Table 5-2. Table 5-2 Roles’ responsibilities for server side Developer

92

Service implementation

Implement the server. May implement handlers.

WSDL

Provide WSDL document.

Web services DD

Provide port components definitions. May define handler references.

WebSphere Version 5.1 Web Services Handbook

Assembler

Deployer

Resolve endpoint addresses. Resolve module dependencies. May configure handlers. Assemble modules in an EAR file.

Developer JAX-RPC mapping DD

Assembler

Deployer

Provide the mapping.

Application server

Deploy the application.

Handlers Handlers provide a mechanism for intercepting the SOAP message. The use of handlers is allowed in both sides, client and server, and has to be transport independent. A handler can examine and potentially modify the content of a SOAP message. A handler can operate in both directions of a message. A handler can preprocess a message before this one arrives to the business logic of a Web service or a client. A handler can also post process a message later on in the business process, but before the message is sent to its receiver. A handler is always associated with a particular port component and is processed in a strict order, called a handler chain. Handlers can manage encryption and decryption, logging, auditing and so forth. The client and server have to agree on the functionality of these handlers. A handler’s life cycle is controlled by the container and, thus, runs under the execution context of the application. Handlers have access to the resources and environment variables. Handlers cannot divert a message and cannot modify the WSDL operation and the part types associated with that operation. The handler life cycle is shown in Figure 5-6. The container uses the init and the destroy methods to notify a handler instance of a change in its state. Once the container has called the init method, the handler is ready for dispatching a request using the handleRequest, handleResponse and handleFault methods.

Chapter 5. Implementing Enterprise Web Services (JSR 109)

93

does not exit 1. newInstance() 2. init() handleRequest() handleResponse() handleFault()

Action initiated by the container

destroy()

method ready

Figure 5-6 Life cycle of a handler

Security The security specifications provided by the JSR 109 are not based on WS-Security specification. The security is based in the J2EE security and only valid for a specific communication protocol, HTTP, to which the specification is designed. The inclusion of security credentials in the SOAP message is left for future works.
Authentication—Basic authentication is provided in the HTTP header of the message.
Authorization—Is provided by the J2EE container, securing the HTTP POST access of the JAX-RPC service endpoint.
Integrity and confidentiality—Relies on the HTTPS protocol. For more information on Web service security refer to Chapter 11, “Web services security” on page 185.

SRJ 109 implementations in WebSphere WebSphere Application Server 5.0.2 and 5.1 provide implementations for JSR 109 for JavaBean and EJB Web services. Both SOAP over HTTP and SOAP over JMS are supported.

94

WebSphere Version 5.1 Web Services Handbook

SOAP over HTTP Figure 5-7 shows the implementation of SOAP over HTTP:
The client request to the Java proxy is handled by the SOAP client and is routed to the server over HTTP.
In the server, the WebSphere SOAP Engine calls a JavaBean Web service as a servlet, or uses a servlet in a Web router module to invoke an EJB Web service.

Application Server J2EE Client Java Client

WSDL

EJB session

Servlet

Web Router

Web Service

Java Proxy

Web Services Engine

SOAP Client

HTTP Client

Web JavaBean

SOAP

HTTP Server

Figure 5-7 JSR 109 with SOAP over HTTP

SOAP over JMS Figure 5-8 shows the implementation of SOAP over JMS:
The client request to the Java proxy is handled by the SOAP client and is placed into a JMS queue through a JMS sender.
In the server, a message-driven EJB (MDB) listens to the JMS queue and routes the message to the WebSphere SOAP Engine.
The WebSphere SOAP Engine invokes an EJB Web service.
Replies to the client are currently not supported.

Chapter 5. Implementing Enterprise Web Services (JSR 109)

95

Application Server J2EE Client Java Client

Java Proxy

WSDL

EJB session bean

Web Service

Reply

Web Services Engine

SOAP Client

Queue JMS Sender

EJB MDB Listener

Figure 5-8 JSR 109 with SOAP over JMS

Summary In this chapter we have presented the Web services for J2EE specification, JSR 109. This specification standardizes the deployment of Web services and Web services clients in a Java 2 Platform, Enterprise Edition (J2EE). We have reviewed the new concepts, interfaces, and file formats introduced by the JSR 109 specification. We have introduced the requirements to create a Web service client, analyzing its different phases, deployment characteristics, life cycle, and roles. We have introduced the deployment of Web service in a similar way and discussed the two runtime possibilities developed by the specification:
EJB container
Web container Finally, we have also introduced the handlers to show the role played by them in the JSR 109 specification, and described the poor quality standard security offers around Web services.

96

WebSphere Version 5.1 Web Services Handbook

More information The best source for more information is the Web Services for J2EE specification, JSR 109, which can be download from: http://www-124.ibm.com/developerworks/downloads/index.php?group_id=116

There is also a foundation article that helps to understand the JSR 109:
Build interoperable Web services with JSR-109 http://www-106.ibm.com/developerworks/webservices/library/ws-jsrart/

Chapter 5. Implementing Enterprise Web Services (JSR 109)

97

98

WebSphere Version 5.1 Web Services Handbook

6

Chapter 6.

Introduction to UDDI This chapter provides an introduction to universal description, discovery, and integration (UDDI), as well as some advanced topics. We describe UDDI Version 2.0.4, followed by a preview of Version 3. Version 2 of UDDI is implemented by the major UDDI registries currently in production. UDDI V2 is also supported by the Web services tooling in Application Developer Version 5.1 and a private UDDI V2 registry implementation is shipped with WebSphere Application Server Network Deployment Version 5.1. In this chapter we discuss the following topics:








UDDI overview New features in UDDI Version 2 UDDI repositories on the Web Web front-ends for registries Java API for dynamic UDDI interactions Private UDDI registries Future of UDDI Version 3

© Copyright IBM Corp. 2003, 2004. All rights reserved.

99

UDDI overview UDDI stands for universal description, discovery, and integration, and is the name for a specification that defines a way to store and retrieve information about a business and its technical interfaces, in our case Web services. One implementation of this specification is the UDDI Business Registry, or UBR. This is a group of Web-based UDDI nodes, which together form a UDDI registry. These nodes are run on separate sites by several companies and can be used by anyone who wants to make information available about a business or entity, as well as anyone who wants to find that information. A UDDI registry makes it possible to discover what technical programming interfaces are provided for interacting with a business for such purposes as electronic commerce, information retrieval, or others. UDDI addresses a number of business problems. First, it helps broaden and simplify business-to-business (B2B) interaction. For the manufacturer who needs to create many relationships with different customers, each with its own set of standards and protocols, UDDI provides a highly flexible description of services using virtually any interface. The specifications allow the efficient and simple discovery of a business and the services it offers by publishing them in the registry. UDDI is based on existing standards, such as XML and SOAP. It is a technical discovery layer. It defines:
The structure for a registry of service providers and services
The API that can be used to access registries with this structure
The organization and project defining this registry structure and its API In fact, UDDI is a search engine for application clients rather than human beings; however, many implementations provide a browser interface for human users. The central source of information about UDDI is the Web site: http://www.uddi.org

This site is operated by OASIS, which is a not-for-profit, global consortium that drives the development, convergence, and adoption of e-business standards.

Static versus dynamic Web services You often read about static and dynamic Web services. Static Web services mean that the service provider and the service requestor know about each other at design time. There is a WSDL document that was found in a UDDI registry, or—more often—directly sent to the client application developer by the provider

100

WebSphere Version 5.1 Web Services Handbook

for further use in the development tool. During runtime it is very clear (mostly hard coded) what the URL (access point) of the partner is. Dynamic Web services describe the fact that at design and development time the client does not know the explicit server and business entity where it will invoke a service. The client only knows an interface to call, and finds one or more concrete providers for that kind of service through exploring UDDI registries at runtime.

UDDI registry structure There are several types of information that have to be stored in such a registry, including information about the company—in UDDI called a business entity—that offers services, as well as the description of each service including interface specifications and pointers to servers where those services can be invoked. The data to be stored can be divided into six types of information that build up the data model of the registry:
Business entity—The list of business entities is similar to the white and yellow pages. A business entity describes a company or organization. Those entities provide information such as business name, contacts, descriptions, identifiers, and categorization.
Business service—This is non-technical information about a service that is provided. A business service is a descriptive container used to group a set of Web services related to a business process or group of services. Also, categorization is available on this level. A business service maps to a WSDL service.
Binding template—This contains service access information. These are the technical Web service descriptions relevant for application developers who want to find and invoke a Web service. In many cases a binding template points to an implementation address (for example, a URL) and maps to a WSDL port. This entity is sometimes also called an access locator.
tModel—A tModel (technical model) is a technical fingerprint holding metadata about type specifications, as well as categorization information. Its attributes are key, name, optional description, and URL. The simplest tModel contains some text characterizing a service. One type of tModel is sometimes referred to as a service type. In this case, the tModel points to a service description document (for example, through a URL). The type specification itself, which can be a WSDL document or any other formal specification, is not part of the UDDI model.
Taxonomy—A taxonomy is a scheme for categorization. There is a set of standard taxonomies, such as the North American Industry Classification

Chapter 6. Introduction to UDDI

101

System (NAICS) or the Universal Standard Products and Services Classification (UNSPSC). In specific circumstances you can publish your own taxonomies, but this is typically not possible using the Web client or publishing APIs because it needs special authorization and actions by the UDDI registry operator. The UDDI registry included with WebSphere Application Server Version 5.0.2 and 5.1 introduces the ability to add user-defined taxonomies. UDDI Version 3 uses the term value set for taxonomy.
Publisher assertions—These are also called business relationships. There are different kinds of relationships: Parent-child, peer-peer, and identity. This makes it possible to model complex businesses, such as subsidiaries, external business partners, or internal divisions. Figure 6-1 displays this data model with the entities introduced above. It also shows their relationships and the link to the WSDL documents.

Business Entity

Publisher Assertion

contains points to

1 n

Business Service

Taxonomy (Categorization)

Keyed Reference

1 n

Binding 1 Template

m

n find

tModel (ServiceType)

1

n

0..1

0..1

Access Point (URL)

WSDL Document

Figure 6-1 UDDI entities and their relationships

The business entity tops the containment hierarchy, containing one or more business service entities. Those services in turn contain binding template entities. The tModel instances (service types) are not contained by the business entity, but referenced by the binding template entities.

102

WebSphere Version 5.1 Web Services Handbook

A binding template points to an access point URL where the service can be invoked. This is a common use of the binding template, but not required. The binding template could point to a phone number as a contact point. A service type entity (tModel) has a reference to a Web service type specification, which typically is a WSDL document. Note that the UDDI registry merely contains a URL pointing to the Web site of the service provider where the document can be found, not the WSDL document itself. Businesses, services, and tModels can contain zero to many references to taxonomy entries to categorize their content. WSDL references are implemented as URLs; therefore, any other specification format can easily be supported as well. UDDI is not bound to WSDL. In general, you do not work with WSDL files at all when working with UDDI registries. There is an m:n relationship between the binding template and the tModel. Keep in mind that a tModel is just a technical fingerprint containing quite abstract metadata. Even if a service points to several tModels, it does not necessarily have to implement multiple interfaces on a technical level. The UDDI data model is designed to be flexible. Hence, there can be more than one technical description for one service (a formal specification and a supporting tutorial, for example) and vice versa, one tModel can be used to describe several similar business services. The possibility for the requestor to dynamically bind to a provided service through a given tModel is a real benefit of the Web service architecture.

Interactions with UDDI Using UDDI registries in general contains three different tasks, because on one side there are service providers who want to publish some information, and on the other side there are service requestors who want to find some services and finally use them. So the tasks using a UDDI registry are:
Publishing information
Finding information
Using the obtained information These typical steps of interacting with a UDDI registry are illustrated in Figure 6-2.

Chapter 6. Introduction to UDDI

103

1 Companies and organizations describe themselves

Companies and organizations publish their services

UDDI Registry

Services, bindings, tModels

Business entities

3 WSDL WSDL WSDL WSDL

Client applications retrieve WSDL file and invoke remote Web services

2 Human users and client applications search for business entities

Human users and client applications search for services

Figure 6-2 Interactions with UDDI registries

Publishing information There are the six types of information that can be published to UDDI registries:







Business entity information Business service information Binding templates tModels Taxonomy information Publisher assertions (business relationships)

Finding information After business entities have published their entity descriptions and services, clients (service requestors) might try to find this information. Clients have a number of possible ways to explore a registry. Either humans do that by using HTML clients of the registry, or applications use UDDI APIs to do that automatically, as described in “Java API for dynamic UDDI interactions” on page 114.

104

WebSphere Version 5.1 Web Services Handbook

In any case, the most likely strategy will be one of the following:
Find concrete business entities and explore their services.
Find services of a certain type regardless of which entity provides them.

Using the information After finding the services, the final step is to use the service that was obtained by the exploration step. This is typically done by accessing the service provider using the interface (messages and parameters) found in the downloaded WSDL file, and the access point information (URL). Details on this step are described in the second part of this book.

UDDI support in WebSphere Application Server A version of the UDDI registry that supported Version 2 of the specification runs on WebSphere Application Server Version 5.0.2 and 5.1 and it shipped with WebSphere Application Server Network Deployment.

Advanced features of UDDI In this section we describe the enhancements provided with UDDI Version 2. Important: The UDDI Version 2 API is not fully backward compatible to UDDI Version 1; some programs accessing a UDDI registry may not run correctly.

Modeling features for complex business entities This feature allows companies that might be spread over several countries to present themselves as many business entities that are related to each other. There are different kinds of relationships: Parent-child, peer-peer, and identity. This makes it possible to model relationships such as subsidiaries, external business partners, or internal divisions. Also, the inquiry API offers new functions, such as find_relatedBusinesses, to allow searches for related businesses of one company. The feature called service projection allows one business entity to reference a service that another (related) business entity offers. So it is possible to define a service that is offered by, for example, more than one department of a large company. The creator of a projected service is not allowed to alter anything in that service, but to the service requestor it looks as if the service is owned by that business entity.

Chapter 6. Introduction to UDDI

105

External taxonomies In Version 1 there were only three taxonomies that could be used to categorize services: NAICS (North American Industry Classification System), UNSPSC (international project and service categorization), and geographic taxonomies. These categorization standards were checked internally in the UDDI registry to avoid the setting of invalid codes. In Version 2 there is the possibility for companies to specify their own external taxonomy, which is not checked internally by the UDDI server. The provider of the taxonomy must also offer a standardized Web service to validate values against. The use of external taxonomies is a controlled process, so the UDDI Business Registry operator has to approve it.

Powerful inquiry The inquiry API allows the dynamic exploration of the UDDI registry, especially the search for services. This API was extended to support more powerful features dealing with more complex query requirements.

Combining categories The combineCategoryBags qualifier allows you to group all of the taxonomy data associated with a business and all of its contained services (including any service projections) into a single collection that the search is performed against. This is useful because it reduces the steps in finding a business of interest by looking in both the business and its constituent services at the same time. So you could, for example, in one step look up services that are categorized both as Construction, as per NAICS, and contain a geographic locator such as AT, stating that it is an Austrian company.

Advanced search using categorization Similarly, the serviceSubset filter allows you to search for businesses using taxonomy criteria, which are tested only against the categorizations associated with a business' constituent services. Categorizations associated with the business itself are not included in the search.

Qualifier for searching Finally, the orLikeKeys qualifier is particularly useful because it enables pseudo-complex queries. It allows you to combine search criteria with OR and not only with AND. For example, you can find businesses located in the United States, Mexico, or Canada that also offer cold storage or generic shipping services. This enables you to search for businesses that are categorized with

106

WebSphere Version 5.1 Web Services Handbook

different levels of specificity, while at the same time allowing a single inquiry to reference multiple different taxonomies.

Internationalization features Services and business entities can have language-dependent names. There must be at least one name in any language, but you can also provide different translations for both business entities and your services. A new type of taxonomy, postalAddress, allows you to specify addresses in different international formats.

Peer-based replication As the number of UDDI registries increases, a simple file-based replication scheme is not appropriate anymore. The new peer-based replication features do not require that each UDDI registry has to communicate with all the others for replicating the information.

UDDI Business Registry on the Web Currently there are four organizations hosting nodes in the UDDI Business Registry. All four of the nodes are replicated and therefore contain the same information. Most of the companies also host a test registry in addition to the business registry. Those test instances can be used by anyone for test purposes. Web services found there are often subject to change and lack of availability. They are not meant for production use. Table 6-1 specifies three URLs for each registry. The first is the URL for the Web client that can be used by humans for exploring and publishing any information. Typically you have unlimited access for reading information and need some sort of registration for publishing information. Besides the Web client URL, you also find URLs for API access using a UDDI API implementation, such as UDDI4J, as described in “Java API for dynamic UDDI interactions” on page 114. There are always two different URLs for inquiry (reading information) and publishing (writing information). The latter one is using HTTPS as a secure connection to ensure that the publishing information is not corrupted or altered.

Chapter 6. Introduction to UDDI

107

Table 6-1 UDDI registries Hosting organization

Access type

URL

IBM Business Registry

Web

http://uddi.ibm.com

Inquiry

http://uddi.ibm.com/ubr/inquiryapi

Publish

https://uddi.ibm.com/ubr/publishapi

Web

http://uddi.ibm.com/testregistry/registry.html

Inquiry

http://www-3.ibm.com/services/uddi/testregistry/inq uiryapi

Publish

https://uddi.ibm.com/testregistry/publishapi

Web

http://uddi.microsoft.com/

Inquiry

http://uddi.microsoft.com/inquire

Publish

https://uddi.microsoft.com/publish

Web

http://test.uddi.microsoft.com/

Inquiry

http://test.uddi.microsoft.com/inquire

Publish

https://test.uddi.microsoft.com/publish

Web

http://uddi.sap.com/

Inquiry

http://uddi.sap.com/uddi/api/inquiry

Publish

https://uddi.sap.com/uddi/api/publish

Web

http://udditest.sap.com/

Inquiry

http://udditest.sap.com/UDDI/api/inquiry

Publish

https://udditest.sap.com/UDDI/api/publish

Web

http://www.ntt.com/uddi/

Inquiry

http://www.uddi.ne.jp/ubr/inquiryapi

Publish

https://www.uddi.ne.jp/ubr/publishapi

IBM Test Registry

Microsoft Business Registry

Microsoft Test Registry

SAP Business Registry

SAP Test Registry

NTT Business Registry

In general, all of the UDDI registry nodes have the same functionality, although there are significant differences in user interface and usability. Functions that are typically performed by users are:
Find businesses, services, and tModels: – By name

108

WebSphere Version 5.1 Web Services Handbook

– By categorization – By key (UUID)
Browse through businesses, services, and tModels: – Show services for businesses – Show binding informations for services – Show tModels for services
Publish/change/unpublish: – – – –

Business entities Business relationships Services tModels

Web front ends for registries Each of the UDDI registries listed above has its own Web interface for human users. They have very different user interfaces with a different look and feel, and therefore the usability varies. The functionality itself is the same for all of them, since they are all implementing the UDDI Version 2 features. As an example, we introduce the Web client of the IBM UDDI Registry. When accessing the site using http://uddi.ibm.com, you reach a page with several links to articles regarding UDDI. You can choose between the business registry and the test registry using the linked images on the right. After you have chosen the UDDI registry, you will find the tasks on the left-side menu, for example, Find and Register. Note: A reading task—for example, finding businesses or services—does not require a registration. Whenever you want to publish some information about your business, service, or interfaces, you have to register. This is, in general, free and requires just your name, country of residence, and a valid e-mail address.

Finding information If you want to find published UDDI information, you can choose between a set of finders, depending on what you are searching on, as shown in Figure 6-3. The simple approach is just to specify the type of entry you are looking for and a string that is contained in the name of that entry.

Chapter 6. Introduction to UDDI

109

For more advanced searches you can use one of the links named Find a Business/Service/Technical Model, which allows you to use categorization information and combinations of search criteria.

Figure 6-3 Options for searching the UDDI registry

After you have successfully submitted a search query, you can navigate through the results, such as displaying services that were published by a specific business, or showing services that implement a certain tModel specification, and so on. Important: Unfortunately, there are a large number of experimental and test entries not only in the test registry, but also in the official business registry. So when locating services be sure you do not try to call a service with access points showing server names such as localhost, and be aware that there is no guarantee about availability of the services. Figure 6-4 shows an example of a service found in UDDI with detailed information that might be interesting to the client of the service. First of all, there is a unique ID (UUID) specifying the service, as well as the business owning the service, including its key. You could also use these keys in the advanced search feature. Names and descriptions of services can be specified in several languages. You will find the entries of all languages in the details view, including an ISO code of the language used. Two essential pieces of information are the access points and service locators. The first one is a pointer to concrete implementations of this service. The latter one describes the service using categorizations (taxonomies).

110

WebSphere Version 5.1 Web Services Handbook

Figure 6-4 Exploring details of a published service

Note: The UDDI registry does not contain only Web services. For example, IBM also publishes other services, such as phone numbers and URLs for Web sites, where to order IBM products, and e-mail addresses. Once you have identified a Web service you want to use, you can follow the tModel link to download the WSDL file. This WSDL file includes all the necessary interface descriptions that can be used by such tools as WebSphere Studio Application Developer to develop client applications that call the Web service statically. The binding template link provides the URL where you invoke the Web service.

Chapter 6. Introduction to UDDI

111

Publishing information The second task you might want to do using UDDI registries is to publish your company’s information and services, so that potential clients can use your services. After you have selected the desired registry and have successfully logged in, you will find an additional menu item on the left side called Publish. By clicking that, you reach a window with all the items that you ever published into the registry using this user name. The typical order in which you publish your information is the following: 1. Define a business. Describe your company or organization, and optionally assign some categorizations, describe your business domain, and add relationships to other business entities. 2. Define tModel(s). Define technical models, referencing WSDL files for Web services or simpler tModels such as mailto or ftp. Note that a tModel does not always reference a WSDL file on a provider’s site. tModels contain a unique key, a description, and classification locators. If a business provides public access to a WSDL file, it makes sense to specify that URL in the tModel description. 3. Define services and bindings. Finally define your services. They consist of a name, key, and some descriptive information. You also immediately provide the binding information, which in general is composed of an access point, where the service can be activated, and binding details such as the protocols used to connect (for example, SOAP over HTTP). You also have to reference one or more tModels to describe your interface. The path through the different steps is quite straightforward and not described in more detail here. There is only one interesting fact to point out:
When looking at the publishing window, you will immediately find your business entities, relationships, and tModels, including all the links to create new ones. But you do not initially see the business services. This is because a service (other than tModels) can only exist for a specific business entity. So you have to first expand one business entry to see the definitions and links regarding services (Figure 6-5).

112

WebSphere Version 5.1 Web Services Handbook

Figure 6-5 Expanding business entities to explore or define services

When you have finished defining your entities, services, and tModels, your publishing window looks like Figure 6-6.

Figure 6-6 Overview of published items

Chapter 6. Introduction to UDDI

113

Java API for dynamic UDDI interactions As described above, it is possible to use UDDI repositories as a human user by using Web front ends. A second possibility is to explore them using client applications. Therefore there is a standardized set of APIs defined for each version of UDDI registries. There are many implementations of that API. For example, Microsoft provides a UDDI SDK that is a collection of client development components, sample code, and reference documentation that enables developers to interact programmatically with UDDI-compliant servers. This is available for Visual Studio .NET and separately for Visual Studio 6.0 or any other COM-based development environment. A number of companies, such as IBM, HP, and SAP, officially support the UDDI4J implementation, which we discuss in the following section.

UDDI4J overview UDDI4J is a Java class library that provides support for an API that can be used to interact with a UDDI registry. This class library provides classes that can be used to generate and parse messages sent to and received from a UDDI server. Note: The UDDI4J API can be used against any of the registries (Business Registry, test registry, private UDDI registry of WebSphere Version 5). The central class in this set of APIs is org.uddi4j.client.UDDIProxy. It is a proxy for the UDDI server that is accessed from client code. You can use this proxy to interact with the server and possibly find and download WSDL files. You might then want to use such APIs as WSDL4J or Apache Axis to interpret these WSDLs and invoke remote Web services. This section describes the first part, which is exploring and publishing to the UDDI. Detailed information as well as download possibilities (including source code) can be found at: http://www.uddi4j.org

The important packages are:
org.uddi4j.datatype This package contains classes used to send or receive UDDI information.

114

WebSphere Version 5.1 Web Services Handbook


org.uddi4j.request This package contains messages sent to the server. These classes are typically not used directly; rather the UDDIProxy class uses these classes.
org.uddi4j.response This package represents response messages from a UDDI server.

Prerequisites Clients written using UDDI4J require a Java runtime environment of at least Version 1.2.2 and a SOAP transport, which at the moment can be one of the following:
Apache Axis
Apache SOAP 2.3
HP SOAP The WebSphere Version 5.0.2 Web services runtime is currently not a SOAP transport that can be used by UDDI4J on the client side, even though the UDDI registry (server side) itself could be running inside a WebSphere 5.0.2 runtime.

Using the library You have to do some preparations to use the UDDI library. First you have to specify a set of system properties where you define which SOAP implementation you are using and if there are proxies to cross. If you not only want to explore a UDDI server but also want to publish information, you have to activate the HTTPS transport protocol by adding an implementation of JSSE to your class path. Refer to the documentation on the UDDI4J Web site for detailed information.

Writing UDDI clients A typical application client to UDDI registries consists of three parts:
Connect to the server by creating a proxy object.
Find entities using this proxy.
Publish entities using this proxy.

Creating a proxy object When writing a UDDI client you typically first create a UDDIProxy object by setting the server URLs to access, as shown in Figure 6-7. The concrete values for the inquiryURL and publishURL are dependent on the UDDI registry you use and can be obtained from Table 6-1 on page 108.

Chapter 6. Introduction to UDDI

115

// --- Add SSL support (only needed for publishing) System.setProperty("java.protocol.handler.pkgs", "com.ibm.net.ssl.internal.www.protocol"); java.security.Security.addProvider(new com.ibm.jsse.JSSEProvider()); // --- Create UDDI proxy UDDIProxy uddiProxy = new UDDIProxy(); uddiProxy.setInquiryURL(inquiryURL); uddiProxy.setPublishURL(publishURL); // --- Cache authorization token for publishing AuthToken token = proxy.get_authToken("userid", "password") Figure 6-7 Creating a UDDI proxy object

Finding information Once you have created a proxy object, you can easily find any kind of information, such as business entities, services, bindings, or tModels.

Finding business entities The find_business method is used to find business entities by name. The method returns a BusinessList object, a collection that can be used to find specific information about all of the businesses that match the search parameter. BusinessList UDDIProxy.find_business( java.util.Vector names, DiscoveryURLs discoveryURLs, IdentifierBag identifierBag, CategoryBag categoryBag, TModelBag tModelBag, FindQualifiers findQualifiers, int maxRows)

Parameters:
names—A vector of names. You can use the % character as a wildcard.
discoveryURLs—This is a list of URLs to be matched against the data associated with the discoveryURLs contents of registered business entity information. The returned BusinessList contains BusinessInfo structures matching any of the URLs passed (logical OR).
identifierBag—This is a list of business identifier references. The result contains businesses matching any of the identifiers passed (logical OR).
categoryBag—This is a list of category references. The result contains businesses matching all of the categories passed (logical AND).

116

WebSphere Version 5.1 Web Services Handbook


tModelBag—The registered business entity data contains binding templates that in turn contain specific tModel references. The tModelBag argument lets you search for businesses that have bindings that are compatible with a specific tModel pattern. The result contains businesses matching all of the tModel keys passed (logical AND). tModel key values must be formatted as URN-qualified UUID values prefixed with "uuid:".
findQualifiers—Can be used to alter the default behavior of search functionality
maxRows—Allows the requesting program to limit the number of results returned

Finding services To find a service using whatever search criteria, you use the find_service method: ServiceList UDDIProxy.find_service( java.lang.String businessKey, java.util.Vector names, CategoryBag categoryBag, TModelBag tModelBag, FindQualifiers findQualifiers, int maxRows)

This function returns a ServiceList on success. In the event that no matches were located for the specified criteria, the ServiceList structure returned will contain an empty structure. Parameters:
businessKey—This optional uuid_key is used to specify a particular business entity instance. This argument may be used to specify an existing business entity in the registry or may be specified as "" (empty string) to indicate that all business entities are to be searched.
names—This optional vector of names represents one or more partial names. A wildcard character % may be used to signify any number of any characters. Up to five name values may be specified. If multiple name values are passed, the match occurs on a logical OR basis within any names supplied.
categoryBag—This is a list of category references. The returned ServiceList contains BusinessService structures matching all of the categories passed (logical AND by default).
tModelBag—This is a list of tModel uuid_key values that represent the technical fingerprint of a BindingTemplate structure to find. If more than one tModel key is specified in this structure, only BusinessService structures that contain BindingTemplate structures with fingerprint information that matches all of the tModel keys specified will be returned (logical AND only).

Chapter 6. Introduction to UDDI

117


findQualifiers—Used to alter the default behavior of search functionality.
maxRows—Allows the requesting program to limit the number of results returned.

Finding tModels To find tModels, use the find_tModel method. This method is for locating a list of tModel entries that match a set of specific criteria. The response will be a list of abbreviated information about tModels that match the criteria (tModelList). TModelList UDDIProxy.find_tModel( java.lang.String name, CategoryBag categoryBag, IdentifierBag identifierBag, FindQualifiers findQualifiers, int maxRows)

Parameters:
name—This string value represents a partial name. Because tModel data only has a single name, only a single name may be passed. A wildcard character (%) may be used. The returned tModelList contains tModelInfo elements for tModels whose name matches the value passed.
categoryBag—This is a list of category references. The result contains tModels matching all of the categories passed (logical AND by default). FindQualifiers can be used to alter this logical AND behavior.
identifierBag—This is a list of business identifier references. The result contains tModels matching any of the identifiers passed (logical OR).
findQualifiers—Used to alter the default behavior of search functionality.
maxRows—Allows the requesting program to limit the number of results returned. The three methods enable you to explore businesses, services, and tModels. As a typical dynamic client, you are not really interested in the name of a business or a service, but much more in the binding templates that tell you where you can access a service. A typical scenario would be to search for a binding using a tModel key, extract the access point, and invoke a service at that URL.

Finding bindings You can find bindings using the find_binding method: BindingDetail UDDIProxy.find_binding( FindQualifiers findQualifiers, java.lang.String serviceKey, TModelBag tModelBag, int maxRows)

118

WebSphere Version 5.1 Web Services Handbook

This method returns a BindingDetail object that contains zero or more BindingTemplate structures matching the criteria specified in the argument list. Parameters:
findQualifiers—This collection can be used to alter the default behavior of search functionality.
serviceKey—Used to specify a particular instance of a BusinessService element in the registered data. Only bindings in the specific BusinessService data identified by the serviceKey passed will be searched.
tModelBag—This is a list of tModel uuid_key values that represent the technical fingerprint to locate in a BindingTemplate structure contained within the BusinessService instance specified by the serviceKey value. If more than one tModel key is specified in this structure, only BindingTemplate information that exactly matches all of the tModel keys specified will be returned (logical AND).
maxRows—This optional integer value allows the requesting program to limit the number of results returned. This function returns a BindingDetail object on success. In the event that no matches were located for the specified criteria, the BindingDetail structure returned in the response will be empty and contain no BindingTemplate data. In all the find methods described above, you can set the parameter maxRows to define the maximum number of results. There you can also specify 0 in order to not limit the result. Keep in mind that, in the event of a large number of matches, an operator site may truncate the result set. If this occurs, the response message will contain the truncated attribute set to true.

Publishing information If you want to register some information on a UDDI server, you have to use the authorization token obtained when creating the proxy. Figure 6-8 shows how to publish a business entity. This example only fills the required name field. Of course in real scenarios you might also consider adding categorization information and descriptions.

Chapter 6. Introduction to UDDI

119

// create business entities and store them in a vector Vector businessEntities = new Vector(); BusinessEntity be = new BusinessEntity(""); be.setName("IBM ITSO"); entities.addElement(be); // save the entities on the UDDI server BusinessDetail bd = proxy.save_business (token.getAuthInfoString(), entities); Figure 6-8 Publishing a business entity

The BusinessDetail object returned by the save method holds the unique identifiers (UUID) that were given to the new entities by the UDDI registry. Similar to business entities, you can also create business services, and tModels, by using the classes BusinessService or TModel. Whenever you have to specify URLs or access points, you also find wrapper classes, such as OverviewURL or AccessPoint, that provide a very easy and intuitive way to model your registry entries. For more details and examples, refer to the UDDI4J documentation and to several articles published at the library section of the developerWorks site: http://www.ibm.com/developerworks

Private UDDI registries The first implementation of UDDI was the business registry, which sometimes is also called the UDDI cloud. This cloud consists of nodes operated by IBM, Microsoft, SAP, and others, which are replicated and hold exactly the same information. They can be accessed by everyone, both for exploring information as well as publishing information. But in fact there are other usage scenarios that seem to gain even more importance than the public registry, namely totally or partly private UDDI registries. There are a number of possible requirements that encourage companies and organizations to establish those UDDI registries outside the cloud.

Motivation for the use of private UDDI registries There are a number of problems that arise in some environments when using public UDDI registries, especially the business registry.

120

WebSphere Version 5.1 Web Services Handbook

Need for privacy One requirement is that companies often do not want to show all of their interfaces to the whole world, and therefore also open the possibility that everyone can (try to) communicate with their services.

Getting rid of UDDI pollution Because the UDDI cloud is public and free to be used by everyone, it is obvious that there is often inaccurate, outdated, wrong, or misleading information in the registries. There is no concept of expiration date for published information or any review mechanisms to ensure the quality of the content. This is a problem similar to Web sites on the Internet, with the main difference being that the users of Web sites are human and should be able to easily separate good or usable content from bad content. The clients of UDDI registries are often applications. This fact can lead to severe problems.

Standards and guidelines In UDDI you can publish businesses or services with very little information, and when entering URLs for access points, you can specify WSDL files, as well as Web sites, or documents that describe a service in prose. This is allowable in UDDI and may be exactly what is required in some cases. However, to make automatic (application client) inquiries (dynamic Web services) easier, you might want to set up some standards restricting the information that is set on specific places of the registry.

Possible scenarios for private UDDI registries In this section we list some scenarios where private registries are suitable.

Internal registry A company or organization might want to consider a totally private registry, which resides inside the firewall and can only be accessed from inside the intranet, both programmatically and Web-based. This scenario helps large organizations to provide internal services for other departments and divisions. It is very easy to mandate guidelines and restrictions, because no other company interacts with your registry.

e-marketplace UDDI registries Another scenario could be a registry that is in fact totally public, but specializes in a very specific topic, or a group of companies, or an industry. Those registries would be perfect candidates for using specialized taxonomies, which have been supported since UDDI Version 2.

Chapter 6. Introduction to UDDI

121

For example, the automotive industry might consider setting up a specialized registry with their own detailed categorization system. Another advantage would be to restrict the usage to some special set of tModels. In order not to allow every company to publish their own service interfaces, the organization hosting the registry might want to consider defining standardized tModels and WSDLs that are supported by this registry. Using those specialized registries would very much increase the possibility of automatically discovering and invoking Web services by application clients.

Extranet UDDI registries A third scenario is a usage of UDDI where one company or organization hosts one registry for the communication between the owning company and the business partners, so the registry is on the Internet, but access is restricted to the owning company and partners with previously negotiated business contracts. This enables a good compromise between the privacy of a company and the ability to communicate easily with its partners. All the advantages of private registries apply, keeping the registry clean and uniform.

Benefits of private UDDI registries The usage scenarios of UDDI registrations are not restricted to the public business registry already discussed. There are many reasons why an organization might want to consider establishing a registry that is not part of the official registries. That makes it possible to restrict one or more of the following points:
Who is allowed to explore the registry
Who can publish information
What kind of information is published (guidelines, standards) Another important point about private registries is that the success rate for dynamic exploration performed by application clients increases dramatically.

Additional considerations for private UDDI registries There are two considerations when thinking of any registry that is not part of the central business registry.

122

WebSphere Version 5.1 Web Services Handbook

Propagation Hosting a private registry does not necessarily mean that there is no propagation with the business registry. There might be scenarios where it makes sense to do one-way propagation from the private registry into the cloud. Especially in the e-marketplace scenario, this could make a lot of sense.

Securing APIs In each case you might consider enabling or disabling the inquiry and publishing APIs. So, in the partner scenario it could be required that everyone is allowed to explore the Web services, but nobody should be able to publish a service except the hosting company itself.

WebSphere private UDDI registry A private UDDI registry feature is shipped with WebSphere Application Server Network Deployment Version 5 and can be installed on a WebSphere server. Important: Installation and usage of the private UDDI registry is described in “Implementing a private UDDI registry” on page 503:
Installing the registry in a WebSphere Application Server
Using the UDDI GUI for publish and find operations
Using the UDDI Explorer of Application Developer to access the private UDDI registry

WebSphere Application Server 5.0.2 update WebSphere Application Server Version 5.0.2 introduces the ability to add user-defined taxonomies, with available allowed values presented in the existing GUI taxonomy tree display. WebSphere Studio Application Developer Version 5.1 has a Web Services Explorer user interface that also allows the addition and display of custom-checked taxonomies. The publisher of a custom taxonomy's categorization tModel may specify a display name for use in GUI implementations. For more information go to: http://publib.boulder.ibm.com/infocenter/wasinfo/topic/com.ibm.wasee.doc/in fo/ee/ae/rwsu_tax.html

Chapter 6. Introduction to UDDI

123

WebSphere Application Server 5.1 update WebSphere Application Server Version 5.1 introduces UDDI utility tools that provide these functions as commands and as a programmatic API (Figure 6-9):
Export—Export a UDDI entity (or list of entities) from a registry into an entity definition file (XML format).
Import—Import UDDI entities from an entity definition file or programmatically into a registry (add entities or update existing entities).
Promote—Combines export and import to copy entities from one registry to another. Generation of an entity definition file is optional.
Delete—Delete an entity or a list of entities.
Find—Search for matching entities based on inquiry API objects (only programmatic API). The resulting entity list can be used in subsequent export, promote, and delete requests.

find

find delete

entity keys

Source Registry get

export

API

promote entity definition file

import

delete

publish

Target Registry

API

Figure 6-9 UDDI utility tools

Future of UDDI Version 3 At the time this book was written, the business registry was implementing the UDDI Version 2 standard, and WebSphere 5 was also supporting Version 2. Since July 2002, there has been a new specification of UDDI called Version 3. The enhancements specified by this new version include multi-registry topologies, increased security features, improved WSDL support, a new subscription API, and core information model advances. Note that some of the features in the UDDI Version 3 specification are optional, and an implementor can choose not to implement them.

124

WebSphere Version 5.1 Web Services Handbook

Keys assigned by publisher Every item in a Version 2 UDDI registry, such as business entities, services, and tModels is assigned a key (UUID), which uniquely identifies that entity within the registry. In Version 2, copying a UDDI entry from one registry to another and preserving the unique key is not allowed. Version 3 of UDDI enables you to copy entries using the same key, because the key generation feature is extended. The behavior of copying entities is known as entity promotion. The solution to the problem is that the generation of entity keys is no longer exclusively performed by registry nodes. Depending on policies, publishers may request permission to use a partition of the registry’s root keyspace (using a tModel:keyGenerator request). If this request is successful, publishers can publish entities by supplying an entity key within the partition they own. If the publisher supplies a key—if it is allowed by policy—the supplied entity key is used instead of the node generating a new key.

Human-friendly URI-based keys Besides the new ability to promote keys across registries, a new format for UDDI keys is introduced in Version 3. Prior versions mandated that keys had to be a formatted universally unique identifier (UUID). Version 3 removes this restriction and recommends the usage of a key scheme based on DNS names. This allows publishers to establish a key partition of the registry’s root key space and then generate keys based on that partition. For example, a valid Version 3 key might look like this: uddi:mycompany.com:4711 uddi:ibm.com:itso:0815

These human-friendly keys allow organizations to manage their own key space using internally established conventions and structures.

Complex registry topologies In order to support these more complex topologies of UDDI registries, there are new possibilities for setting a UDDI registration in certain relationships to another. UDDI Version 3 introduces the notions of root and affiliate registries as part of its guidance on inter-registry associations. The existence of a root registry enables its affiliates to share data with the root registry and among themselves with the assurance that keys remain unique.

Chapter 6. Introduction to UDDI

125

Advanced security features Another advancement is the support for digital signatures. Entities can be digitally signed to provide better data integrity and authenticity. When exploring the registry, you can filter for signed entries to be sure you get the originally published information that came from a trusted source. These digital signatures are also kept when promoting entities to different registries.

Policies There are many different scenarios in which a UDDI registry can be used:







Public registry on the Internet Partly public registry in the extranet Private registry inside the intranet Private registry for development (for example, inside Application Developer) Stable private registry for test areas Scalable registry for production environments

Each of these registries requires slightly different behavior, because of its intended use, so there are a set of policies that can be applied to the registry that changes the actual behavior regarding:








Authorization models Data custody and confidentiality Key generation Value set validation Subscription User publication limits Audit policy

Data model updates Version 3 also introduces a set of improvements in the data model, which defines how the entities are stored in the registry. Some of the most important extensions are:





126

Categorization of binding templates. More complex categorization features such as derivation of taxonomies. XML schemas define more precisely the possible values stored in UDDI. Advanced support for internationalization.

WebSphere Version 5.1 Web Services Handbook

Extended inquiry API The programmatic exploration was extended to support more complex queries by nesting queries into one round-trip call. Wildcards can be used more flexibly, and special result set features allow processing of very large query results. In addition, more find qualifiers are supported by the API.

Subscription API The new subscription API includes robust support for notification of changes in the registry. Users can establish a subscription based on a specific query or set of entities that the user is interested in. This makes it possible to be notified of new businesses or services that are registered, as well as to monitor existing businesses or services.

Registry management To be more independent of the external taxonomy provider’s server availability and to improve performance, the UDDI registry contains some caching mechanisms for external taxonomies. Also, replication between UDDI registries is improved.

Chapter 6. Introduction to UDDI

127

Summary UDDI is a standard that provides the ability to use dynamic Web services, which means that the service requestor and service provider do not necessarily know about each other up front. An organization that wants to provide some service publishes this service in any UDDI registry. There are two ways a client can find a Web service:
This is a human exploring the UDDI at design time, who might search for service or a WSDL, and use that information when programming the client.
Another possibility would be a programmatic exploration by the client application, which allows dynamic binding and changing service providers at runtime. There are three major points that are often not considered or are misunderstood when talking about UDDI registries:
UDDI registries cannot only contain details of published Web services, but also details of other kinds of service, for example, services that cannot be used programmatically.
There is an increasing need for specialized and partly private registries that are hosted by standards bodies or industries. In addition, internal intranet registries (with or without contact to business partners) are gaining more and more importance.
When publishing or finding tModels, you never publish or store WSDL interface files. The tModel is just a logical link to a concrete interface. When a service references a tModel, you cannot directly find out the real interface.

More information For more information on UDDI, consult the IBM UDDI Web site at: http://uddi.ibm.com

For general UDDI information, use the Web site at: http://www.uddi.org

Fir more information about the WebSphere private registry, consult the WebSphere InfoCenter: http://publib.boulder.ibm.com/infocenter/ws51help/index.jsp

128

WebSphere Version 5.1 Web Services Handbook

7

Chapter 7.

Web services invocation framework In this chapter we introduce the Web service invocation framework (WSIF). It is a more flexible way to invoke Web services. The developer is no longer restricted to developing services for particular transport protocols or service environments. WSIF comes as a Java API that supports either the use of generated stubs or provides the stub-less and completely dynamic invocation of Web services, where the binding can be selected and updated at runtime. Furthermore, WSIF allows late binding, where a new provider and description are made available at runtime, and the existing client can then utilize the new implementation. The chapter is structured as follows:





Motivation of the need for WSIF General concept, including architecture Sketch of scenarios where the use of WSIF is reasonable Current status, outlook, and references

© Copyright IBM Corp. 2003, 2004. All rights reserved.

129

Motivation As we have pointed out before, the main building blocks for Web services are SOAP, WSDL, and UDDI. Thus, a straightforward way to implement Web services is to use just these concepts, which leads to the following binding procedure: assembling a SOAP message, sending it to the service provider, and getting a SOAP message back. This protocol has implementations and tools available in most programming languages. However, using only SOAP has some drawbacks:
The use of one particular protocol implementation may be too restricting. A stringent integration of client code to a client library for a particular protocol implementation can become hard to maintain. For instance, if the developer of the client code wants to take advantage of new features and bug fixes that came out in a new version of the transmitting protocol, he or she has to update all of the client code.
The incorporation of new bindings into client code is complex. As stated in Chapter 3, “Introduction to WSDL” on page 45, WSDL allows developers of the service provider code to define bindings for whatever protocol is available. To incorporate new bindings, the client APIs for using this protocol would have to be written from scratch. This may be a time-consuming task, especially if it has to be done repeatedly. Thus, an invocation mechanism is needed that supports bindings to be updated or new bindings to be plugged in easily.
A singular binding prevents flexible solutions. There are cases where a SOAP-based binding is quite inefficient, for instance, if a local binding directly using Java calls is possible. However, there might be reasons why the developer wants to make use of the Web services framework. Thus, it would be favorable to treat the local service implementation (a Java class) as a Web service. Clients would then have the ability to switch the binding based on runtime information. So another requirement to an invocation framework is a mechanism that allows you to switch between the available service bindings at runtime, without having to generate or recompile a stub.
Existing transport mechanisms may have technical advantages over SOAP and may be already established in businesses. In recent decades, a number of different data transport technologies have been developed and established that offer more than SOAP does today—especially in terms of management, transactions, security, and other quality of service (QoS) features. Many companies have already invested in technologies, such as CORBA, that they wish to use and keep. Thus, the goal must be to provide a concept that is so flexible that the transportation protocol

130

WebSphere Version 5.1 Web Services Handbook

can be adapted to the current needs within an application scenario, ideally even during runtime of the system. As we have pointed out in Chapter 3, “Introduction to WSDL” on page 45, the provider of a Web service uses WSDL to describe the properties of the service he offers. WSDL has been designed to allow multiple implementations for a Web service, and multiple ports that share the same PortType. For instance, a WSDL document can be written that allows the same interface to have bindings to SOAP and, say, IIOP. You can even treat a single Java class as a Web service, with in-thread Java method invocations as the access protocol. Having a flexible WSDL description of the service that offers multiple bindings, you need a framework that allows you to incorporate the service in any way that the requestor prefers and the provider offers. Thus the following requirements have to be fulfilled by such a framework:
Provide an API that frees code from the complexities of any particular protocol used to access a Web service.
Provide a binding-independent mechanism for Web service invocation.
Support dynamic invocation of services by choosing between multiple bindings to a Web service during runtime.

General concept The Web service invocation framework (WSIF) is a toolkit that provides all of the features we have identified in the previous discussion:
It provides an API to bind to and invoke any Web service.
J2SE 1.3 dynamic proxy support is used to generate stubs for the invocation.
WSIF supports the stub-less (completely dynamic) invocation of Web services.
An updated implementation of a binding can be plugged into WSIF at runtime.
The decision of which binding to use need only be made at runtime.
WSIF provides a WSDL-driven API to invoke Web services.
WSIF enables easy encapsulation of back-end systems connected through the J2EE Connector Architecture (JCA) as Web services. The introduction of WSIF leads to a shift in the programming paradigm. The invocation of a Web service is moved from a binding-centric approach to a more encapsulated and thus abstract level. This enables service bindings to be viewed as pieces of code required for invocation according to a particular protocol.

Chapter 7. Web services invocation framework

131

WSIF architecture In this section we describe the involved components in more detail. In “More information” on page 140, we point to relevant references that expand on the description of the architecture.

Provider class A WSIFProvider is an implementation of a WSDL binding. It can run a WSDL operation through a protocol that depends on a specific binding. WSIF providers implement the bridge between the WSIF API and the actual implementation of a service. WSIF providers are currently available for SOAP over HTTP, SOAP over JMS, Java, EJB, and native JMS. New providers can easily be added to the WSIF framework.
The SOAP provider allows WSIF stubs and dynamic clients to invoke SOAP services.
JMS is a messaging technology. The mapping to a JMS destination is defined during deployment and maintained by the container.
The WSIF Java provider allows WSIF to invoke Java classes and JavaBeans. Local Java code running on a JVM can be incorporated easily.
The EJB provider allows WSIF clients to invoke Enterprise JavaBeans. The EJB client JAR must be available in the client runtime with the current provider.

Operation class The WSIFOperation is the runtime representation of an operation. Based on a specific binding, it invokes the corresponding service.

Service The task of WSIFService is to generate an instance of WSIFOperation that is used for a specific invocation of a service operation.

WSDL documents The WSDL document specifies the location of the Web service, possible binding protocols, and formats for operations and messages. Figure 7-1 shows a fragment of a WSDL document for a fictious service. This fragment offers not just that SOAP binding, but also a Java binding, and ports for both bindings.

132

WebSphere Version 5.1 Web Services Handbook

...

...

... Weather forecast service ... ...

Figure 7-1 Fragment of a WSDL example with multiple bindings

More concepts More concepts are:
WSIFPort—The task of this class is to perform the actual invocation, depending on a given binding. For instance, a WSIFSOAPPort has been designed to use the SOAP binding as it is specified in the WSDL.

Chapter 7. Web services invocation framework

133


WSIFMessage—In WSDL, messages are composed of named parts tied to some type system, normally an XML schema. To invoke such services, this schema type is mapped to possibly more sophisticated type systems provided by the programming language in use. For instance, the schema type is mapped to certain Java classes by serialization and de-serialization in cases where Java is the native type system. The design of WSIFMessage allows you to employ any native type system as a message part. Parts in a message can be typed by employing different type systems. This is needed if parts from multiple separate WSDL messages are associated with different native type systems and have to be combined into a single message.

Interaction flow Figure 7-2 shows the main components of WSIF and their interaction. A Web service is invoked through the following steps: 1. A WSDL document is loaded. 2. A WSIF service is generated. 3. The new WSIFService is used to get the operation. 4. The message is created. 5. The service is invoked by supplying the port with the name of the operation to be invoked, along with an input and/or output message as required by the operation.

WSDL document 1

WSIF service factory

3

2

WSIF service

WSIF operation

Service

4 5

Figure 7-2 Main WSIF components

134

WebSphere Version 5.1 Web Services Handbook

WSIF provider

Definition or modification of the binding selection algorithm The WSIF architecture allows a convenient exchange or modification of the binding selection algorithm. Only the implementation of WSIFService has to be changed or written from scratch.

Modification of a binding implementation at runtime In order to change from one binding implementation to another, there is no longer a re-compilation of user code or stub code necessary, because the WSIF API remains the same. The approach follows the factory pattern; thus, only a new WSIFPort implementation and a provider is needed. The new WSIFPort implementation has to be capable of making invocations using the modified client API that is provided by the new binding implementation. The provider has to translate a WSDL port to the new WSIFPort implementation. The provider replaces the previous provider, and the invocation for all WSDL ports takes place through the new WSIFPort implementation.

Two invocation models using WSIF WSIF supports the invocation of Web services in two different ways: Either they can be invoked by using a stub-less dynamic approach, or they are incorporated with a generated stub. A direct invocation requires using the WSIF API directly, while the generated stub allows the application to work with Java interfaces and hides the WSIF API.

Stub-less (dynamic) invocation WSDL provide all necessary information to incorporate a Web service, such as the abstract interface, the binding, and the service endpoint. Thus once the location of the WSDL file is known to a service requestor, the WSFL API can be used to invoke this service at runtime. For this procedure, no stub classes have to be generated. The following steps have to be performed:






Select a port. Create an operation. Create and populate the in-message. Execute the operation. Read the response data from the out-message.

For stub invocations, WSIF uses Java's dynamic proxy mechanism. The dynamic proxy must be supplied with a Java interface reflecting the port type that is invoked. The Java interface corresponding to a WSDL port type is defined by JAX-RPC, a J2EE standard. Thus, WSIF can be used to invoke services through the standard stub interface defined by JAX-RPC.

Chapter 7. Web services invocation framework

135

Figure 7-3 presents a sample for the invocation code. In the example, the call of the procedure getTemperature is hardcoded for simplicity reasons. Obviously, invocation code can be written that first parses the retrieved WSDL document to extract the correct name and syntax of the provided methods.

WSIFService sq = WSIFServiceFactory.newInstance() .getService("http://my.com/forecast.wsdl",null,null,null,null); WSIFPort defPort = sq.getPort(); WSIFOperation getQ = defPort.createOperation("getTemperature"); WSIFMessage inMessage = getQ.createInputMessage(); inMessage.setStringPart("symbol", "Saarbruecken"); ... getQ.executeRequestResponse(inMessage, outMsg, fltMsg); outMessage.getFloatPart("value"); Figure 7-3 Example for the dynamic invocation

Note: We make no comment about the usefulness of the invocation of methods of which only their syntax but not their semantics is known.

Invocation using stubs Besides the dynamic invocation, there is another way to invoke Web services. This way is favorable in situations where the architecture defines services to be more encapsulated. Thus, a more abstract view on the service is provided, because the WSIF API is not directly addressed. Figure 7-4 shows a simple example.

WSIFService sq = WSIFServiceFactory.newInstance() .getService("http://my.com/forecast.wsdl",null,null,null,null); MyService mySvcStub = sq.getStub("soap", MyService.class); mySvcStub.myMethod(); Figure 7-4 Example using the stub model in WSIF

WSIF uses the J2SE 1.3 dynamic proxy support that generates a client stub for each port type depending on the given WSDL document. To use the generated stubs, applications use the abstract service interface. Therefore, they are more isolated from the protocol and the WSIF client API. A major advantage of the stub architecture is that the same stub can be used, while the managed environment may change in the plumbing without having to

136

WebSphere Version 5.1 Web Services Handbook

recompile anything. Furthermore, the stub-based model allows using the normal programming model to call business methods on Web services.

Sample scenarios for WSIF Remember that Web services are no longer tied to SOAP. In situations where the service provider resides in the same environment, a local call performs better than a call through a Web server and servlet engine into the SOAP router. In large projects, the technique of rapid prototyping is often used, where the first system has limited functionality, but can already serve as a proof of concept. Later, the prototype can be continuously enhanced. Web services in such a project will also be continuously redeveloped and possibly redeployed. If WSIF is used, the same API calls are used; however, the underlying technologies differ. Still, client code does not have to be rewritten. Another aspect is outsourcing, where an internal implementation of Web services using local calls is replaced by a service provider, and the Web services must be invoked using SOAP. Furthermore, WSIF development can be done remotely, but system test and maintenance is done in-house. Using WSIF, the same API can be used for development, testing, and maintenance.

Current status and future WSIF was initially released on the alphaWorks® Web site in October 200: http://www.alphaworks.ibm.com

WSIF is now an Apache open-source project and is supported by the open-source community. For links see “More information” on page 140. WSIF has not been standardized so far. Enhancement of the Apache WSIF project is continued in 2003. It is practical to employ a standard API to access Web services as well as back-end legacy applications through WSDL and WSIF. Therefore, it will be used in IBM products wherever appropriate; mostly as a behind-the-scenes middleware piece. The first release of WSIF became available in January 2003, including documentation of the WSIF Java and EJB bindings. The WSIF documentation is compiled with descriptions of the WSIF Java and EJB bindings.

Chapter 7. Web services invocation framework

137

Enhancements The main enhancements since the alphaWorks release are:
The WSIFPart interface has been removed and merged into WSIFMessage.
The WSIFPortFactory object has been renamed to WSIFService.
A new interface, WSIFServiceFactory, has been added.
The PortTypeCompiler is no longer used. Instead, the J2SE 1.3 dynamic proxy is supported.
New bindings and transports have been added: SOAP over JMS, EJB binding, and Apache Axis-based SOAP provider.
Tracing and logging activities are now supported.
A dynamic registration of new providers using the J2SE JAR service provider specification is now supported.
WSIF has been changed so that the Apache Axis provider is now used for the default SOAP binding. WSIF has two SOAP providers: One based on Apache SOAP 2.3, the other on Apache Axis (SOAP 3.x). Recently, a JCA provider has been added that allows applications accessible via JCA to be exposed through WSDL and invoked using WSIF APIs.

WebSphere Application Server 5.0.2 update WebSphere 5.0.2 introduces the following enhancements:
WSIF support for SOAP with Attachments API for Java (SAAJ) The SAAJ API provides a standard way to associate a SOAP message with one or more attachments in their native format (for example, GIF or JPEG) by using a multipart MIME structure for transport. It defines specific usage of the multipart/related MIME media type, and rules for the usage of URI references to refer to entities bundled within the MIME package. It thereby outlines a technique for a SOAP 1.1 message to be carried within a MIME multipart/related message in such a way that the SOAP processing rules for a standard SOAP message are not changed. WSIF supports passing attachments in a MIME message using the SOAP provider. The attachment is a javax.activation.DataHandler. The mime:multipartRelated, mime:part and mime:content tags are used to describe the attachment in the WSDL. For more information go to: http://publib.boulder.ibm.com/infocenter/wasinfo/topic/com.ibm.wasee.doc/in fo/ee/ae/twsf_attach.html

138

WebSphere Version 5.1 Web Services Handbook


WSIF support for automatic mapping of complex types For complex types defined in the WSDL, where a generated bean is used to represent this in Java, the WSIF programming model requires that a call is made to WSIFService.mapType(). This call tells WSIF the package and class name of the bean representing the XML schema type that is identified with a QName. To make things easier, WSIFService.mapPackage() provides a mechanism to specify a wildcard version of this, where any class within a specified package is mapped to the namespace of a QName. This is a mechanism for manually mapping an XML schema type to a Java class and back again (one mapping entry provides a bi-directional mapping). For more information go to: http://publib.boulder.ibm.com/infocenter/wasinfo/topic/com.ibm.wasee.doc/in fo/ee/ae/cwsf_comt.html

Integration into WebSphere products WSIF is used in WebSphere products such as WebSphere Workflow, the Web Services Gateway (refer to Chapter 10, “Web Services Gateway” on page 169), and in WebSphere Studio Application Developer Integration Edition (refer to Chapter 17, “Application Developer Integration Edition” on page 341), and is supported in WebSphere Application Server Version 5. In WebSphere Application Server, WSIF is provided as a stand-alone JAR file called wsif.jar. The JAR file contains the core WSIF classes, as well as the Java, EJB, SOAP over HTTP, and SOAP over JMS providers. Additional providers are packaged as separate JAR files. WSIF makes use of the WSDL4J API to parse WSDL files.

Future versions Besides the first Apache release, there are some other areas of further development on WSIF. A mechanism is envisaged to separate the transport from message formatting. Furthermore, some work has been done to implement an abstract tree representation of the data in a message. Also, there will be support for better providers for the many types of transports and object systems that exist. Finally, implementations of WSIF in C or C++ are considered.

Chapter 7. Web services invocation framework

139

Summary The Web services invocation framework is a Java API that supports SOAP-based and non-SOAP-based services to be described in WSDL and invoked in a common way. It specifies a provider interface that can be extended by new transports and protocols. WSIF supports two ways of service invocation: Dynamic invocation or by using a stub. Furthermore, it supports late binding, so that services can be adjusted to new protocol types without modifying and compiling client code. WSIF moves the issue of Web service invocation from a binding-centric viewpoint to a more abstract, encapsulated level, driven by the WSDL description of the service. Thus, service bindings are perceived as pieces of code needed for invocation according to a particular protocol.

More information The developerWorks Web site provides updated information on many activities concerning Web services, including WSIF: http://www.ibm.com/developerworks/webservices/

In particular, the following articles provide more detailed information:
Applying the Web Services Invocation Framework: http://www.ibm.com/developerworks/library/ws-appwsif.html


Web Service Invocation Sans SOAP: http://www.ibm.com/developerworks/webservices/library/ws-wsif


Web Service Invocation Sans SOAP2: http://www.ibm.com/developerworks/webservices/library/ws-wsif2

The home page of the WSIF open-source project on Apache is at: http://ws.apache.org/wsif/

The xml-axis-wsif code can be browsed at: http://cvs.apache.org/viewcvs.cgi/xml-axis-wsif

IBM’s contribution on WSIF from October 2001 can be found at: http://www.alphaworks.ibm.com/tech/wsif

140

WebSphere Version 5.1 Web Services Handbook

8

Chapter 8.

Web services inspection language This chapter provides an introduction to the Web services inspection language (WSIL or WS-Inspection) 1.0. A complement to UDDI, WS-Inspection is another service discovery mechanism that addresses a different subset of requirements using a distributed usage model. We discuss the principal features and taxonomy, as well as its business application. The WS-Inspection specification is designed around an XML-based model for building an aggregation of references to existing Web service descriptions. WS-Inspection 1.0 provides a notation serving these purposes. The WS-Inspection specification is a joint effort by IBM and Microsoft. It was a draft document at the time of writing this book, and represents the current status with regard to locating and inspecting services.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

141

Overview A centralized service registry, which is described in Chapter 6, “Introduction to UDDI” on page 99, is not the only model for Web services discovery. The simplest form of services discovery is requesting a copy of the service description from the provider. This is not very efficient because it requires a prior knowledge of the Web service. The most complex form is connecting to a UDDI registry that provides a more business-centric perspective. Between these two extremes, there is a need for a distributed service discovery method that provides references to service descriptions at the service provider's point-of-offering. The Web services inspection language provides this type of distributed discovery method by specifying how to inspect a Web site for available Web services. The WS-Inspection specification defines the locations on a Web site where you may find Web service descriptions. The WS-Inspection specification does not define a service description language, which is left to other languages such as WSDL. WS-Inspection documents provide a method for aggregating different types of service descriptions. Within a WS-Inspection document, a single service can have more than one reference to a service description. For example, a single Web service might be described using both a WSDL file and within a UDDI registry. References to these two service descriptions may be put into a WS-Inspection document. If multiple references are available, it is beneficial to put all of them in the WS-Inspection document so that the document user can select the type of service description that they can understand and want to use. The WS-Inspection specification contains two primary functions:
It defines an XML format for listing references to existing service descriptions.
It defines a set of conventions so that it is easy to locate WS-Inspection documents. The WS-Inspection specification complements a UDDI registry by facilitating the discovery of services available on Web sites, which may not be listed yet in a UDDI registry. An overview of WS-Inspection is shown in Figure 8-1.

142

WebSphere Version 5.1 Web Services Handbook

Service Description

Service Description

UDDI Registry

WS-Inspection Document

find service

Service Provider

WS-Inspection Document

Service Description

http://itso.com/inspection.wsil

Service Requestor

Web Service

Figure 8-1 WS-Inspection overview

WS-Inspection document The most important objectives of the inspection language are simplicity and extensibility. A WS-Inspection document is an aggregation of pointers to service description documents. Examples of service descriptions are WSDL files, UDDI entries, or simple plain text, for example, an HTML page. The WS-Inspection document is usually available at the point-of-offering (service provider) and allows the consumer to pick and choose from the available service descriptions using the access method that is most useful. The WS-Inspection document contains an inspection element at the root that provides a wrapper to the two main elements: service

Contains the references to different types of service descriptions for the same Web service.

link

Allows a WS-Inspection document to reference additional aggregation of services descriptions, such as other WS-Inspection documents or UDDI entries.

The optional abstract element is used as a container to provide a small textual description for human consumption. This element is allowed inside any other base element that allows child elements.

Chapter 8. Web services inspection language

143

WS-Inspection document anatomy Figure 8-2 shows the anatomy and the relationship among the different elements in a WS-Inspection document. The structure is quite simple and, therefore, it can be easily maintained.

WS-Inspection Document 1 1

inspection If links = 0 then services > 0

If services = 0 then links> 0

1

n

n

n

service

link

abstract

1 n

abstract

1

n

n

name

description

n

abstract

Figure 8-2 WS-Inspection document elements and relationship

The diagram should be read in the following way:
One WS-Inspection document contains one inspection element.
One inspection element contains zero or more abstract elements and zero or more links and/or services with one restriction. This restriction means that the inspection element must contain at least either one service or one link, but never none of them. For example, if there is no service, there has to be at least one link, and vice versa. A combination of links and services is possible.
One service contains zero or more abstract, name and description elements.
One link contains zero or more abstract elements. The containment relationship shown in the diagram directly maps to the XML schema for WS-Inspection.

144

WebSphere Version 5.1 Web Services Handbook

Example Figure 8-3 contains a simple WS-Inspection document example. As we see, the syntax used in this file is not very complex, but rather easy to understand. We analyze this example in detail in this chapter, but the whole document is presented here to obtain a complete picture. As an exercise, you can try identifying the different elements in Figure 8-2 while examining this example.

A simple service with two descriptions 4FA23580-5C39-14D5-9FCF-BB3200303F79 Figure 8-3 WS-Inspection document example

Namespaces The namespaces used in a WS-Inspection document are shown in Table 8-1. Table 8-1 WS-Inspection namespaces Prefix

Namespace URI

Definition

wsil

http://schemas.xmlsoap.org/ws/ 2001/10/inspection/

WS-Inspection namespace for the WS-Inspection framework.

wsilwsdl

http://schemas.xmlsoap.org/ws/ 2001/10/inspection/wsdl/

WS-Inspection namespace for the WS-Inspection WSDL binding.

Chapter 8. Web services inspection language

145

Prefix

Namespace URI

Definition

wsiluddi

http://schemas.xmlsoap.org/ws/ 2001/10/inspection/uddi/

WS-Inspection namespace for the WS-Inspection UDDI binding.

uddi

urn:uddi-org:api

API and document namespace defined by the UDDI V1 specification.

uddiv2

urn:uddi-org:api_v2

API and document namespace defined by the UDDI V2 specification.

(other)

(various)

All other namespace prefixes are samples only. In particular, URIs starting with "http://itso.com" represent some application-dependent or context-dependent URI.

WS-Inspection and UDDI relationship WS-Inspection and UDDI specifications address issues related to Web service discovery. Even so, they were designed with different goals in mind, and thus exhibit different characteristics. One of the fundamental points of a successful Web service is related to the discovery of the service. We illustrate how the two specifications may be used jointly to solve a variety of requirements. The information can be extracted either straight from the source of information, WS-Inspection, or from a third-party UDDI registry. The two possibilities have some characteristic features.

WS-Inspection
Retrieving the information directly from the source increases the possibilities of obtaining accurate information.
The use of a distributed model allows the service descriptions to be stored at any location.
They are very lightweight, easy to create, and easy to maintain.
They allow the provider to present its services in a proactive fashion.
They do not stipulate any particular format for the service and rely on other standards, including UDDI.
They do not provide a rich mechanism to execute any focus discovery.

146

WebSphere Version 5.1 Web Services Handbook

UDDI registry
Retrieving the information indirectly provides the opportunity for more developed and advanced services and does not require that the original source be available or easily accessible.
Uses a centralized model.
Provides high-level functionality in the discovery (search facility). Both systems address different sets of issues in the discovery problem space. Whereas the UDDI provides a high degree of functionality, the WS-Inspection document adopts it at a lower level. Therefore, both specifications should be understood as complementary technologies to be used either together or separately, depending upon the situation. There is a whole range of mutual benefit in the combined use of the technologies. For example, a UDDI registry can be populated using the WS-Inspection documents found in an Internet search. On the other hand, a UDDI registry can be discovered when a requestor retrieves a WS-Inspection document that references an entry in the repository. Thus, they should not be viewed as competing mechanisms; for example, a business card does not compete with the yellow pages in disseminating personal information.

WS-Inspection definition The WS-Inspection definition contains a detailed explanation of the core elements of the WS-Inspection language. The document contains an inspection element at the root, and references to individual service descriptions or links as descendants. The grammar of a WS-Inspection document is as follows: (0 or more) (0 or more) (0 or more) (0 or more) (0 or more) (0 or more) <-- extensibility element --> (0 or 1) (0 or more) (0 or more) <-- extensibility element --> (0 or more)

Chapter 8. Web services inspection language

147

The inspection element must contain at least one service or one link. To provide the possibility to include documentation, the specification uses the optional abstract element. This element contains a small textual description to be exploited by a human reader. The abstract element is allowed inside any base WS-Inspection language element that allows child elements. An optional xml:lang attribute specifies on the element the language in which the abstract element has been written.

Services The service element provides the mechanisms to include a collection of description references for services. An inspection element may contain any number of service elements within it. Each service element may have one or more abstract elements and one or more name elements, and must have at least one description element, but may have more.

Service name The name is used to associate the service with a particular name. The reason for this element is only for human consumption as the abstract element. In the same way used in the abstract element, an optional element, xml:lang, can be used to specify the language in which the name has been written.

Service description references The most important and useful part of the inspection is the information contained within the description element. This element is used to provide pointers to service description documents of various forms. The service description element contains the following attributes: referencedNamespace

Identifies the namespace to which the reference document belongs, such as WSDL or UDDI.

location

Provides the actual reference to the description. It has to be a valid URL.

extensible

Provides additional information that is needed to retrieve or process the service description. See “WS-Inspection bindings” on page 150 for more information.

In our example, the service definition is shown in Figure 8-4, where we specify two services, the first one about trains and the second one about planes.

148

WebSphere Version 5.1 Web Services Handbook

A simple service with two descriptions 4FA23580-5C39-14D5-9FCF-BB3200303F79 Figure 8-4 Service definition in our WS-Inspection document example

In the first service, we provide an abstract element explaining that it is a simple example that contains two descriptions:
One description makes a reference to a WSDL document, which is specified using the namespace http://schemas.xmlsoap.org/wsdl/ and the URL location http://itso.com/train.wsdl.
Another description for the same Web service is provided using a UDDI registry Version 2 that we specify with the namespace urn:uddi-org:api. The location for the query is http://itso.com/uddi/inquiryapi, and the service key 4FA23580-5C39-14D5-9FCF-BB3200303F79 can be used to retrieve the service description. In the second service, we provide a reference to a WSDL document, which is specified using the namespace http://schemas.xmlsoap.org/wsdl/ and the URL location ftp://itso.com/tools/plane.wsdl.

Links The link element allows WS-Inspection documents to reference additional aggregations of service descriptions, such as other WS-Inspection documents or UDDI repositories. Therefore, we can create a hierarchy of documents (see Figure 8-1 on page 143). The link element helps service providers to create inspection documents with a large number of services elements pointing to the same location in the

Chapter 8. Web services inspection language

149

information registry. Using the link, the providers are able to indicate to the consumers that they have to look at the indicated location for additional service description aggregations. The referencedNamespace attribute identifies the namespace of the linked aggregation source, such as another inspection document or a UDDI registry, but there is no specification of how this link element has to be processed. This means that there is no predefined rule of how this information has to be used. In our example (Figure 8-5), the link definition is where we specify one link to another WS-Inspection document providing the namespace and the location (http://itso.com/others/moreservices.wsil) of the document.

Figure 8-5 Link references in our WS-Inspection document example

WS-Inspection bindings We now introduce the characteristics of the extension elements related to the different bindings.

WSDL binding The WS-Inspection language includes a binding for WSDL 1.1, providing the following capabilities:
Indication of the type(s) of WSDL bindings that appear in the referenced WSDL document
Specification of which WSDL service is being referenced if several services exist within the same document
Indication of whether or not a particular referenced WSDL document provided endpoint information The use of the WSDL binding is optional if the referenced WSDL document has one service element or none. In these cases, a reference to a WSDL document may be made with only one description element. In cases where the WSDL document has more than one service, the binding must be used to indicate which service element is being referenced.

150

WebSphere Version 5.1 Web Services Handbook

The grammar for the binding extension elements is shown in Figure 8-6 and the description of its element in Table 8-2.

QName (0 or 1) QName (0 or more) Figure 8-6 WSDL binding extension elements grammar Table 8-2 WSDL extensibility elements in WS-Inspection Extension name

Explanation

wsilwsdl:reference

The container element for the rest of the binding information. The endpointPresent is a boolean attribute that indicates whether the referenced WSDL contains endpoint information.

wsilwsdl:referencedService

Specifies which service is being referenced when there are more than one. The QName specified must be a valid service name in the referenced WSDL document.

wsilwsdl:implementedBinding

Used to indicate the type(s) of binding that appear in a referenced WSDL document. The QName specified must be a valid binding name in the referenced WSDL document.

Chapter 8. Web services inspection language

151

UDDI binding The WS-Inspection language provides a set of usage patterns for references to business service or business entity information presented in a UDDI registry. This set of elements can refer to entries in a UDDI Version 1.0 or Version 2.0 registry, depending upon the referenceNamespace used. The UDDI extension elements can be included in the description or link elements, in contrast to the WSDL extension elements, which are only in the description element. The extension elements included in the link can only reference a UDDI business entity. Meanwhile, the extension elements included in the description may only reference a single UDDI business service. The grammar for the binding extension elements is shown in Figure 8-7, and the description of its element in Table 8-3.

(0 or 1) (0 or 1) (0 or 1) (0 or 1) (0 or 1) (0 or 1) Figure 8-7 UDDI binding extension elements grammar

152

WebSphere Version 5.1 Web Services Handbook

Table 8-3 UDDI extensibility elements in WS-Inspection Element

Extension name

Explanation

description

wsiluddi: serviceDescription

Specifies a reference to a single UDDI service description. Must contain a serviceKey and may also contain a discoveryURL.

wsiluddi: discoveryURL

Used to retrieve a UDDI business entity using HTTP GET to obtain a single service description using the serviceKey.

wsiluddi: serviceKey

Used to retrieve the UDDI service description.

wsiluddi: businessDescription

Specifies a reference to a UDDI business entity. Must contain a discoveryURL, a businessKey, or both. The location attribute contains the UDDI registry inquiry interface.

wsiluddi: discoveryURL

Specifies a valid URL to retrieve the UDDI business entity using HTTP GET.

wsiluddi: businessKey

Specifies a business key that is used in combination with the location attribute of the business description to retrieve the UDDI business entity using HTTP POST.

link

Inspection document publishing The WS-Inspection grammar only provides a partial solution to the problem of advertising services. We need some rules to easily locate these WS-Inspection documents, because if not, their added value is lost. Consequently, the WS-Inspection language provides two conventions for the location where the document should be placed and how it should be found.
Fixed name WS-Inspection documents They have to be called inspection.wsil and may be placed where the most common entry points to Web sites or applications deployed on the server are located. For instance, in the example used in this chapter, our document is placed in http://itso.com/inspection.wsil.
Linked WS-Inspection documents They allow for a mechanism to inform users about services inspection-related documents using other types of content, such as HTML pages.

Chapter 8. Web services inspection language

153

WSIL examples In this section we describe two examples of bindings that we use in the sample application described in Chapter 19, “Web services scenario: Architecture and implementation” on page 429.

WSDL binding example The first example shows the use of a WSDL binding, that is, the WSIL document points to a WSDL file on a server (Figure 8-8).

The Flash Weather forecast service description ITSO WS Flash Weather Service intf:WeatherForecastSoapBinding The Thunder Weather forecast service description ITSO WS Thunder Weather Service ...... Figure 8-8 WSIL example with WSDL binding

In this example the WSIL document refers to two services by pointing to the WSDL files on two provider servers using URLs.

154

WebSphere Version 5.1 Web Services Handbook

UDDI binding example The second example shows the use of a UDDI binding, that is, the WSIL document points to a UDDI registry (Figure 8-9).

...... ITSO WS Thunder Weather Service F3362720-0C6D-11D7-AB70-000629DC0A53 http://uddi.ibm.com/testregistry/inquiryapi ?businessKey=F5082FA0-0BCB-11D7-AB70-000629DC0A53 F5082FA0-0BCB-11D7-AB70-000629DC0A53 http://uddi.ibm.com/testregistry/inquiryapi ?businessKey=F5082FA0-0BCB-11D7-AB70-000629DC0A53 ...... Figure 8-9 WSIL example with UDDI binding

In this example the tag points to a single business service in the UDDI registry, whereas the tag points to a business entity. The location attribute points to the address and API of the registry that is accessed. Note that both entries are over-specified: The discoveryURL is optional in the tag, and only the discoveryURL or the businesskey are required in the tag.

Chapter 8. Web services inspection language

155

WS-Inspection API There is a WS-Inspection Java API called WSIL4J. This API can be used to locate and process WS-Inspection documents. The class library provides functionality to read and parse WS-Inspection documents and to generate new documents. The primary classes are: org.apache.wsil.WSILDocument

Interacts with the WS-Inspection documents.

org.apache.wsil.client.WSILProxy

Accesses specific service descriptions within a WS-Inspection document.

Currently, WSIL4J is an open-source project available on the Apache Software Foundation as a part of the Apache Axis work: http://xml.apache.org/axis/index.html Figure 8-10 contains an example of how to use this API. In this sample code, a WS-Inspection document is read and the service elements are searched for references to WSDL service descriptions. When a WSDL service description is found, its location is saved in a list.

... // Create a new instance of a WS-Inspection document WSILDocument document = WSILDocument.newInstance(); // Read and parse the WS-Inspection document document.read(wsinspectionURL); // Get the inspection element from the document Inspection inspection = document.getInspection(); // Obtain a list of all service elements Service[] services = inspection.getServices(); // Process each service element to find all WSDL document references for (int serviceCount = 0; serviceCount < services.length; serviceCount++) { // Get the next set of description elements descriptions = services[serviceCount].getDescriptions(); // Process each description to find the WSDL references for (int descCount = 0; descCount < descriptions.length; descCount++) { //If the referenced is WSDL, then save the location reference if(descriptions[descCount]. getReferencedNamespace().equals(WSDLConstants.NS_URI_WSDL)) { // Add WSDL location to the list wsdlList.add(descriptions[descCount].getLocation()); } } ... Figure 8-10 WS-Inspection API example

156

WebSphere Version 5.1 Web Services Handbook

Outlook At the time this book was written, this technology was in its first use as a new service discovery mechanism. The population of WS-Inspection documents should greatly increase in coming months. There are few examples of published WS-Inspection documents on the Internet. One example is at the XMethod Web site: http://www.xmethods.net/inspection.wsil

Based on the contribution of WSIL4J to Apache Axis, we may soon see a WS-Inspection API in Axis. This technology will be used for other applications, such as a Web service crawler. A service crawler would search through Web sites for WS-Inspection documents and then aggregate the service description references from multiple sites. Consequently, and based on the current and future applications of the Web services inspection language, the WS-Inspection documents will play a fundamental role in the overall development of the Web services technology.

Summary In this chapter we have described the Web services inspection language and how this specification provides a simple method to discover any type of Web service description document. We analyzed its grammar and how these WS-Inspection documents can be found. We also saw that this technology does not try to replace present technologies regarding service discovery, but is a complementary discovery method that can be integrated to work together with UDDI repositories, for example. Finally, we briefly reviewed the ways that the open-source WSIL4J API can facilitate the reading, parsing, and generation of WS-Inspection documents.

More information At present, this technology is not widespread, and real examples may be found in no more than a few documents. The best source for more information is the Web services inspection language (WS-Inspection) 1.0 specification that can be found at: http://www.ibm.com/developerworks/webservices/library/ws-wsilspec.html

Chapter 8. Web services inspection language

157

158

WebSphere Version 5.1 Web Services Handbook

9

Chapter 9.

Workflows and business processes Web services enable users to connect different components across organizational boundaries in a platform- and language-independent manner. However, none of these standards allow defining the business semantics of Web services. Today’s Web services are isolated. Breaking this isolation means connecting Web services and specifying how collections of Web services are jointly used to implement more complex functionality—typically a business process or a workflow. In this chapter we cover some concepts regarding workflows. Because a set of services can be composed to a workflow or business process, there are some conceptional topics to discuss. This chapter introduces two specifications dealing with workflows and business processes. The sections in this chapter include:
Web services flow language (WSFL)
Flow definition markup language (FDML)
Business process execution language (BPEL)

© Copyright IBM Corp. 2003, 2004. All rights reserved.

159

Web services flow language In 2001 IBM introduced a new language for describing business processes, which is called the Web services flow language (WSFL). WSFL is a language used to model workflows or processes using an XML syntax that can be read by both humans and machines. By interpreting WSFL, a workflow engine can walk through the business processes using such constructs as activities and control links. There are already a number of workflow systems available, but the power of WSFL lies in its ability to model business processes that span technology and business boundaries—a limitation that most workflow engines suffer from. A WSFL flow model defines the structure of the business process. Activities describe the processing steps, and data and control links represent the sequencing rules and information flows between these activities. For each activity, they would identify the WSFL service provider responsible for the execution of the process step and define the association between activities in the flow model and operations offered by the service provider using WSFL export and plug link elements. The purpose of a WSFL document is to define the composition of Web services as a flow model or a global model. Both models have a declared public interface and an internal compositional structure. The composition assumes that the Web services being composed support certain public interfaces, which can be specified as a single port type or as a collection of port types.

Concepts and terms in WSFL WSFL, like workflow in general, introduces a whole set of new terms that describe artifacts within the process and result in certain elements that you can use while modeling your workflow.

Activity An activity is one atomic step in a workflow. This can be a simple Java method, an EJB call, the invocation of another Web service, or even a complex business process itself.

Business process A business process is any collection of activities that, when combined, accomplish a given business objective. For example, processing a credit card number, hiring a new employee, and submitting a patent are all examples of business processes.

160

WebSphere Version 5.1 Web Services Handbook

Flow model The flow model is the actual XML representation of the directed graph that models the business process. It is the structure that is used to compose Web services, as defined by their individual WSDL documents, into workflows. Flow models are sometimes known as flow composition, orchestration, and choreography, to name three common synonyms. Simply modeling the processing flow between activities/services within a workflow is not enough. In addition to the flow model, there needs to be a way of specifying exactly how the Web services involved in the process are expected to interact with each other. That is where the global model comes in. The global model is a set of necessary links that specify how messages can be sent between the Web services in the flow model as the workflow is executed.

Recursive composition Recursive composition is the possibility that once you have defined both the global and flow models for a given business process, it is then possible to define the whole business process as a single Web service that may be used by other business processes. In other words, you can recursively compose business processes within existing business processes. This provides a great deal of flexibility and fine granularity in the models that you define.

Service provider A service provider is the party responsible for performing a particular activity within a business process. In WSFL, every activity is a Web service. Therefore, every service provider is a Web service provider. To maintain a clear separation between the definition of the business process and its implementation, WSFL's flow and global models define each activity as being implemented by specific types of service providers rather than by the specific service providers themselves. The service provider type is defined by a Web service interface document using WSDL. Service providers must properly implement the appropriate Web service interface in order to be classified as the appropriate type of service provider to handle a particular activity in the business process.

Control link A control link is a connection between two activities. It is the mechanism by which the workflow processor walks through each of the activities in the business process.

Chapter 9. Workflows and business processes

161

Data link The data link is the mechanism that the workflow processor uses to control the flow of data through the business process. While in most cases, the data flow will closely follow the control flow, it is quite possible that the way that information flows through the process is different from the sequence of activities that are invoked.

Transition condition As a business process is being run, the workflow processor must be able to recognize when a particular activity is finished and when the next activity can be determined and invoked. A transition condition is a true or false statement that the processor may use to determine the current state of any particular activity.

Life cycle interface As mentioned earlier, WSFL business processes are themselves capable of being defined as Web services. The life cycle interface is the WSDL-defined Web service interface that describes the basic set of operations that all WSFL Web services support within a particular Web services application. These operations include the ability to invoke, suspend, resume, stop, and terminate the business process as well as inquire about its current state.

Sample WSFL The essential entities are the activities and control links. Figure 9-1 shows how they are specified in WSFL. The concept that is important to understand here is simple:
Each activity is an individual Web service described by a WSDL document.
A control link connects these Web services together in a sequential order. In this example we find:
A flow model: WeatherForecast
Two service providers: MyWeatherGuru and MyMathGuru
A first activity, getDayForecast, which calls the weather forecast Web service
A second activity, convertCelsiusToFahrenheit, which calls the temperature conversion Web service
A control link that connects the first activity with the second activity
A datalink that connects the output message of the first activity to the input message of the second activity

162

WebSphere Version 5.1 Web Services Handbook

Figure 9-1 Activities and control links in WSFL

Flow definition markup language WebSphere Studio Application Developer Integration Edition uses the flow definition markup language (FDML) to describe business processes. This markup language is based on WSFL, but also introduces some extensions. Read Chapter 17, “Application Developer Integration Edition” on page 341, for further information on how to develop workflow and business processes using the IBM tools.

Chapter 9. Workflows and business processes

163

Elements of FDML The elements used in FDML are basically the same as in WSFL, with extensions:
Flow model—Represents a business process.
Activity—There are a number of activity types: – – – – – – – – – – – –

Input—Starting point of the business process Output—End of the process, delivers the result to the caller Java—Invokes a Java class EJB—Invokes an EJB Service—Invokes an external Web service Process—Invokes another business process (nested) Java snippet—Invokes a Java method that is part of the process Loop—Iteration with conditional expression Block—Decomposition of process to simplify the diagram Receive event—Stops process and waits for an event Staff—Stops execution and solicits human interaction Throw fault—Abnormal end of process, returns a message


Control link—Dictates the sequence of activities. Links can have transition conditions that decide which link should be followed after an activity.
Compensation—A service process can have a compensation service process that is executed if the service process throws a fault.
Message—Each activity has an input and an output message.
Variable—Holds data within the process, for example, messages. For a more detailed description of the process elements, see “Business process” on page 347.

FDML sample code We develop a sample business process with Application Developer Integration Edition in “Sample business process” on page 350. Integration Edition stores the process flow in an FDML file. Extracts of the FDML file are described in “Flow definition markup language” on page 368.

164

WebSphere Version 5.1 Web Services Handbook

Business process execution language for Web services This section describes another notation for specifying business process behavior based on Web Services. This notation is called business process execution language for Web services (BPEL4WS, or BPEL for short). Processes in BPEL4WS export and import functionality by using Web service interfaces exclusively. It represents a convergence of the ideas in Microsoft’s XLANG and IBM WSFL specifications. Both XLANG and WSFL are superseded by the BPEL4WS specification. BPEL4WS allows specifying business processes and how they relate to Web services. This includes specifying how a business process makes use of Web services to achieve its goal, as well as specifying Web services that are provided by a business process. Business processes specified in BPEL are fully executable and portable between BPEL-conforming environments. A BPEL business process interoperates with the Web services of its partners, whether or not these Web services are implemented based on BPEL. Finally, BPEL supports the specification of business protocols between partners and views on complex internal business processes. Business processes can be described in two ways:
Executable business processes model actual behavior of a participant in a business interaction.
Business protocols use process descriptions that specify the mutually visible message exchange behavior of each of the parties involved in the protocol, without revealing their internal behavior. The process descriptions for business protocols are called abstract processes. BPEL4WS is meant to be used to model the behavior of both executable and abstract processes.

Concepts and terms in BPEL4WS There are five major elements in the process definition.

Containers The section defines the data containers used by the process, providing their definitions in terms of WSDL message types. Containers allow processes to maintain state data and process history based on messages exchanged.

Chapter 9. Workflows and business processes

165

Partners The section defines the different parties that interact with the business process in the course of processing the order. Each partner is characterized by a service link type and a role name. This information identifies the functionality that must be provided by the business process and by the partner for the relationship to succeed (that is, the port types that the process and the partner need to implement).

Activities Activities are the actions that are being carried out within a business process. An important action in a business process is to simply wait for a message to be received from a partner. This kind of action is specified using a activity. It specifies the partner from which the message is to be received, as well as the port and operation provided by the process and used by the partner to pass the message. The activity is used to specify a synchronous response to the request corresponding to a activity. If the response to the original request is to be sent asynchronously, the response is delivered using the invocation of a Web service provided by the requestor. Consequently, the activity is used within the process that produces the asynchronous response. The original requestor will use a activity to process the response delivered by the activity. A more powerful mechanism is the usage of a activity. This kind of activity specifies a whole set of messages that can be received from the same or different partners. Whenever one of the specified messages is received, the activity is completed, and processing of the business process continues. Additionally, one may specify that processing should continue if no message is received in a given time.

Fault handler The section contains fault handlers defining the activities that must be executed in response to faults resulting from the invocation of the services. In BPEL4WS, all faults, whether internal or resulting from a service invocation, are identified by a qualified name. There is a uniform naming model for faults, in the expectation that future versions of WSDL will provide a better fault-naming model.

Data containers Note that information is passed between the different activities in an implicit way through the sharing of globally visible data containers. This is one of the main conceptual differences from WSFL, where data links explicitly describe how the data flows from one point to another.

166

WebSphere Version 5.1 Web Services Handbook

In BPEL4WS this data is stored in variables that are held in a container and can be accessed by several parts of the flow. The current version of BPEL4WS supports only global data containers, but future versions will include locally scoped data as well.

Business process execution language for Web services runtime The alphaWorks Web site (see “More information” on page 168) offers a runtime facility for BPEL. This platform:
Can execute business processes written in the business process execution language for Web services
Offers a set of samples demonstrating the use of BPEL4WS
Contains a tool that validates BPEL4WS documents
Includes an Eclipse plug-in that provides a simple editor for creating and modifying BPEL4WS files, supporting top-down and bottom-up approaches

BPEL future A new Web Services Business Process Execution Language technical council is being formed at OASIS to continue work on the business process language published in the Business Process Execution Language for Web Services (BPEL4WS) 1.0 specification. Refer to: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsbpel

BPEL4WS is included in the Emerging Technologies Toolkit and it is possible that future releases of business process model tools, such as Application Developer Integration Edition, will use BPEL4WS to internally describe the workflows.

Summary There are a number of running workflow systems on the market. The current specifications for XML-based workflow languages are in an early stage and are subject to be consolidated between different tool and runtime providers. The significant advantage of new XML-based workflow languages is that they support the usage of Web services in their processes and therefore provide a standard means of combining the services of different systems, programming languages, and protocols.

Chapter 9. Workflows and business processes

167

More information
The WSFL specification: http://www.ibm.com/software/solutions/webservices/pdf/WSFL.pdf
“The Web services insider: Introducing the Web Services Flow Language”: http://www.ibm.com/developerworks/library/was-ref4
“The Web services insider: Getting into the Flow”: http://www.ibm.com/developerworks/webservices/library/was-ref5
“Business process execution language for Web services, Version 1.0”: http://www.ibm.com/developerworks/library/was-bell
“Business processes in a Web services world”: http://www.ibm.com/developerworks/webservices/library/was-burlap
IBM business process execution language for Web services Java runtime (BPWS4J): http://www.alphaworks.ibm.com/tech/bpws4j
“XLANG— Web services for business process design”: http://www.gotdotnet.com/team/xml_wsspecs/xlang-c/default.htm

168

WebSphere Version 5.1 Web Services Handbook

10

Chapter 10.

Web Services Gateway This chapter describes the Web Services Gateway (WSGW), which is part of WebSphere Application Server Version 5.0.2 Network Deployment. This gateway can be seen as a kind of proxy that acts as an additional layer between a Web service client and Web service provider. The gateway is useful for enabling a flexible way to call Web services located in an intranet from the Internet, as well calling Internet Web services from the intranet. Another function of the gateway is the possibility for protocol switching and security for Web service calls. This chapter is divided into the following sections:






Overview General concepts Administrating the gateway Installation details Summary Note: The Web Services Gateway is a product feature implemented in WebSphere Application Server Version 5 Network Deployment. We include this chapter in Part 1 because the gateway can also be looked at as a technology for distributed Web service invocation.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

169

Overview If we plan to externalize our Web services beyond the boundaries of our enterprise network, we will be faced with a number of issues that we need to address. These issues include security, reliability, quality of service, communications compatibility, and more.

Motivation for a gateway In this section we describe the reasons for an additional gateway layer.

Externalizing Web services Businesses often deploy their Web services to servers inside the intranet for use by other intranet applications. Sometimes we want to externalize Web services to let clients from outside our intranet, such as customers, suppliers, and business partners, access our services. The Web Services Gateway lets clients from outside the firewall use Web services that are deployed on a server deep inside our enterprise.

Return on investment Processes that we already develop as Web services can be easily reused by our partners. Using the gateway, we can take advances from the existing messaging infrastructure to make Web services requests and use our existing Web services for external process integration.

Securing access to Web service providers The gateway also allows setting access control on each of these internal services, so that not every client can access every service, as would be the case when locating our server on the Internet. We might want to restrict access for all Web services or only certain operations.

Protocol transformation The service requestor might use one particular communication protocol to invoke Web services, while partners use some other protocol. Using the Web services gateway, it is possible to trap the request from the client and transform it to another messaging protocol. For example, a service provider might have implemented a service using SOAP/JMS because of the existing infrastructure, but it should also be possible to offer the service to clients that only understand SOAP/HTTP.

170

WebSphere Version 5.1 Web Services Handbook

Web service access to non-SOAP objects If we have some functionality not defined as a Web service, but as a JavaBean or EJB, then we may not want to wrap a new Web service around that function manually, but we want to do that implicitly by just defining the Java class or EJB in the gateway.

General concepts The gateway builds upon the Web services definition language (WSDL) and the Web services invocation framework (WSIF) for deployment and invocation. In general, we deploy a Web service not only to the server where it is actually running, but also to the Web Services Gateway by deploying a WSDL file that describes how the gateway should access the real implementation. A request to the Web Services Gateway arrives through a channel, is translated into an internal form, then passed through any filters that are registered for the requested service, and finally sent on to the service implementation. Responses follow the same path in reverse. With the Web Services Gateway we can administer:
Web services—Register them to make them available either inside or outside our intranet.
Channels—Define protocols that Web services can use, and also allow switching of these protocols between client and server.
Filters—Apply filters that act upon the services, for example, logging and data manipulation. In earlier releases of the gateway they were called Interceptors.
References to UDDI registries—Use them in order to automatically publish Web services from our gateway to UDDI registries.

Managing Web services The primary function of the Web Services Gateway is to map an existing WSDL-defined Web service to a new service that is offered by the gateway to others. The gateway thus acts as a proxy. External services are imported into the gateway and made available to the enterprise as internal proxy services. Likewise, internal services are imported into the gateway and made available as external proxy services. These services are also published to the relevant UDDI registries where required.

Chapter 10. Web Services Gateway

171

Exposing Web services to the outside world We can expose an internal service for outside use. Given the WSDL file, the gateway will generate a new WSDL file that can be shared with outside requestors. Of course the interface described in the WSDL will be exactly the same, but the service endpoint will be changed to the gateway, which is now the official endpoint for the service client. If we have deployed Web services on a server inside the intranet, we might want to allow access to clients from outside. We might also consider applying special security constraints to restrict the access to either specific users and/or specific methods of our service. This scenario is illustrated in Figure 10-1.

DMZ

Internet

Intranet

Web Services Gateway Channel 1

Prefilter

Client

Channel 1 Postfilter

UDDI

deployed WS

Channel 2

Web Service Channel 2 Implementation

external WSDL

internal WSDL

URI = http://theGateWay.com/...

URI = http://myInternalServer/...

Figure 10-1 Exposing Web services through the gateway

Importing Web services An external service may be imported and made available as an internal service. This will help the internal service requestors invoke the service as if it were running on the gateway. Again, a new WSDL is generated by the gateway showing the same interface but naming the gateway as the service provider rather than the real internal server. The gateway then reroutes all requests to the actual implementation specified in the original WSDL. Of course, every client could access external Web services by traditional means, but if we add the gateway as an additional layer in between, clients do not have to change anything if the service implementor changes. This scenario is very

172

WebSphere Version 5.1 Web Services Handbook

similar to the illustration in Figure 10-1, with the difference that the client resides in the intranet and the Web service implementation is located at a site on the Internet.

Managing channels A request for a service may originate in one protocol, but the service may be invoked in some other protocol by using the transformation function. Let us consider the case that an internal service is available on SOAP over JMS, but it should be invoked using SOAP over HTTP. To handle such cases we need to define a set of channels corresponding to the specific protocols that we wish the gateway to receive messages on. The outbound channels over which the gateway invokes the target Web services are defined implicitly by the bindings in the WSDL imported in the gateway and do not have to be explicitly configured. By using a different inbound channel to those defined in the imported WSDL bindings, we can switch the protocol. This scenario is illustrated in Figure 10-2.

Client

Channel 1 SOAP/HTTP

Web Services Gateway

Channel 2 SOAP/JMS

Web Service Implementation

Figure 10-2 Using the gateway for protocol switching

Managing filters We can develop and use one or more filters for our Web services, which means that some specific task is done using the input and/or output messages to and from our Web service. There are standard filters as well as the possibility of creating our own. An illustration of filters, especially prefilters that manipulate requests and postfilters that work on responses, is shown in Figure 10-1 on page 172. Refer to “Managing filters” on page 173 for more information.

UDDI publication and lookup The gateway facilitates working with UDDI registries. As we map a service for external consumption using the gateway, we can publish the exported WSDL in the UDDI registry. When the services in the gateway are modified, the UDDI registry is updated with the latest changes.

Chapter 10. Web Services Gateway

173

Administering the gateway To administer the Web Services Gateway, first start the WebSphere Application Server Administrative Server. After that, start the administrative tool of the gateway by opening a browser with the URL: http://host:port/wsgw/admin/index.html

Where host and port are the host name and port number that our HTTP server is listening on. We should reach a menu that allows us to configure the gateway:






Configure Security Back up Restore About

The gateway incorporates a facility to back up and restore the configuration. The back up option writes the deployment details for all the channels, filters, UDDI references and Web services deployed to the gateway. The restore option uses the information contained in a previously saved file to update an empty installation of the gateway with the same deployment details for those channels, filters, UDDI references and Web services. Also, the gateway can improve its performance and availability, if is configured so that a set of gateways acts as a cluster. We should also have a menu that allows administering (listing, deploying, and removing) the artifacts:





Channels Filters UDDI references Web services

Pay attention to the order in which the menu shows the options. This is exactly the order in which we should also do our configuration: 1. Configure the URI for our gateway. 2. Define channels, filters, and UDDI references. 3. Define our Web services. Note: If we change our gateway URI, we have to redefine all services. If we want a Web service to use any channel, filter or UDDI reference, define them before adding them to the service. However, we may update the list of channels, filters, and/or UDDI references for a service at any time.

174

WebSphere Version 5.1 Web Services Handbook

Managing namespace URI and WSDL URI Initial values for the namespace URI and WSDL URI are automatically configured when we install the Web Services Gateway. This URIs are used by the gateway:
Namespace URI—The namespace for the gateway services in exported WSDL documents
WSDL URI—To generate the URL in import statements within exported WSDL documents To modify these values with the appropriate values of our environment, we have to change the default values in the gateway administrative console under configuration.

Managing channels Channels are the entry points to the Web Services Gateway and transport requests and responses between Web services and the Web Services Gateway. A request to the Web Services Gateway arrives through a channel, is translated into a WSIF message, and then passed through filters that are registered for the requested service, and finally forwarded to the actual service implementation. Before we can use a channel, we must install the channel application in WebSphere Application Server, and then deploy the channel to the Web Services Gateway. Two versions of each type of channel are supplied with the gateway, so we can set up separate channels for inbound and outbound requests. This also provides a simple mechanism for giving different access rights to users from outside our organization from the rights we give to users within our organization:
To ensure that users outside our organization can only access those internal services that we choose to publish externally, we deploy those services on the inbound channel.
To give users inside our organization access to the full range of internal and external services, we deploy those services on the outbound channel. A channel is in fact an application that is deployed to the application server. Two channels are shipped with the gateway, both SOAP 1.1 compatible:
Apache SOAP channel—The SOAP message format must be RPC style.
SOAP/HTTP channel—The SOAP message format will be RPC or document style and supports SOAP messages with attachments.

Chapter 10. Web Services Gateway

175

Once we have successfully installed our channels (or are satisfied with the existing ones) we can use them when specifying Web services.

Managing filters Filters are used to manipulate service invocations that reach the Web Services Gateway, and responses that leave it. Filters can perform a wide range of tasks, including logging messages, transforming their contents, and terminating incoming requests. Filters are in fact session beans that reside in a separate enterprise application. To use a filter for a Web service, do the following steps: 1. Install the EAR file of the filter application. 2. Deploy that filter to the gateway using the admin tool. 3. Add this filter to the Web service definition in the gateway. When deploying a filter to the gateway, specify a name and a home. This home is the home interface of the session bean implementing the filter functionality.

Writing your own filters Restriction: Writing your own filters is supported only by WebSphere Application Server Enterprise Edition. A filter is in fact a session EJB that implements a specific interface. So if we want to create our own filter, we must develop a session bean that uses com.ibm.wsgw.beans.FilterHome as the home interface and com.ibm.wsgw.beans.FilterRemote as the remote interface. The bean class must implement the filter interface and is therefore provided with callback functions for initializing, destroying, and—more importantly— intercepting (filtering) requests and responses. After implementing the bean, we must do the following: 1. Install the application on the application server. 2. Deploy the filter to the gateway. 3. Specify the filter as pre- or postfilter in our Web service definition.

Managing UDDI references A UDDI reference is a pointer to a UDDI registry. This may be a private or a public UDDI registry, such as the IBM Business Registry (see “UDDI Business Registry on the Web” on page 107).

176

WebSphere Version 5.1 Web Services Handbook

If we want any Web service to use a UDDI reference, define the reference first. When specifying the reference, enter the information needed for accessing the UDDI registry, such as inquiry API, user ID, and password. Note that the values we enter for user ID and password must match those of the owner of the corresponding business in the registry. We can see the owning user ID in the UDDI registry by looking at the business details under the authorized name field.

Managing security The gateway provides facilities for secure communication between the service requester and the gateway, and between the gateway and the target service. These facilities go from transport level security to message level security. Security can be applied at different levels:






Web service security (WS-Security) Gateway-level authentication Operation-level authorization SSL protocol using HTTPS Proxy authentication

Web service security (WS-Security) We can configure the gateway for secure transmission of SOAP messages using tokens, keys, signatures, and encryption in accordance with the Web Services Security (WS-Security) draft recommendation. See Chapter 11, “Web services security” on page 185. The gateway sits between the client and the target Web service. When the gateway is introduced, it can be thought of as two separate request/response invocations: Client to gateway and gateway to target service. Thus, we need to get, from the owning parties, the WS-Security configurations for both the client and the Web service. The configuration of the gateway is exactly the same as explained in Chapter 16, “Web services security with Application Developer” on page 303. We have to create a new security binding and configure with the required information:









Signing information Encrypting information Trust anchors Certificates stores Key locators Trusted ID evaluators Login mappings Login bindings

Chapter 10. Web Services Gateway

177

Gateway-level authentication For gateway-level authentication, we set up a role and realm for the gateway on WebSphere Application Server’s Web server and servlet container, and define the user ID and password that is used by the gateway to access the role and realm. We also modify the gateway’s channel applications so that they only give access to the gateway to service requestors that supply the correct user ID and password for that role and realm. Note: This means that gateway-level authentication must be enabled before we install any channels.

Operation-level authorization For operation-level authorization, we apply security to individual methods in a Web service. To do this, we create an enterprise bean with methods matching the Web service operations. These EJB methods perform no operation and are just dummy entities for applying security. Existing WebSphere Application Server authentication mechanisms can be applied to the enterprise bean. Before any Web service operation is invoked, a call is made to the EJB method. If authorization is granted, the Web service is invoked. The target Web service is protected by wrapping it in an EAR file, and applying role-based authorization to the EAR file:
If we want to enable operation-level authorization, we must first enable gateway-level authentication.
After gateway-level authentication has been enabled, filters have access to the requestor’s authentication information.
We can only apply operation-level authorization to a Web service that has already been deployed to the gateway by enabling the option Authorization Policy - Control access to this service.
Enabling operation-level authorization involves making changes to the file /lib/wsgwauth.ear. To protect the installation version of this file, we should make a backup copy of it before we change it.

SSL protocol using HTTPS The Web services gateway can invoke Web services that include https:// in their addresses, if the Java and WebSphere security properties have been configured to allow it. This means that one gateway can send a SOAP/HTTPS message directly to another gateway, rather than having to export services and have clients invoke them using HTTPS.

178

WebSphere Version 5.1 Web Services Handbook

Proxy authentication The gateway requires access to the Internet for invoking Web services and for retrieval of WSDL files. Many enterprise installations use a proxy server in support of Internet routing, and many proxy servers require authentication before they grant access to the Internet. For messages passing through the gateway, we can enable and disable proxy authentication, and specify whether the authentication credentials are supplied by the service requester or by the gateway. If we specify requester-supplied credentials, the credentials in the HTTP message that the gateway receives are re-instantiated by the gateway in the equivalent message that it sends on to the proxy. If we specify gateway-supplied credentials, the gateway ignores any credentials in the incoming HTTP message and supplies its own credentials in the equivalent message that it sends on to the proxy.

Deploying Web services to the gateway Important: Before we start to define any Web service, be sure that we have correctly set up the gateway definition, which is the first menu item in the admin portal. Any change to the Namespace URI there will mean that existing Web services can no longer be found. When we configure a Web service, we choose the following resources:





The channels on which the service is available Any filters that apply to the service Any UDDI references to UDDI registries in which the service is published Security bindings that apply to the service

Each of these choices is made from a list of resources that have already been deployed to the Web Services Gateway. So we should deploy our channels, filters, and UDDI references before we deploy the Web services that use those resources. However, we can later update the channels, filters, UDDI references and security bindings for the service if necessary. When deploying a service, specify the following information:
Gateway service name—Each Web service is identified by a unique name without spaces in the gateway.
Message part representation: – Generic classes—Select this option if there are no special EJB or Java bindings.

Chapter 10. Web Services Gateway

179

– Deployed Java classes—Select this option if the target services for the gateway service use Vectors, Enumerations, Hashtables or Maps, or contain EJB or Java bindings. Note: When we choose this option, we must also ensure that the specific Java classes that have been generated for the Web service are available to the gateway.
Authorization policy—Control access to this service. Use this check box to enable or disable security for this gateway service.
Audit policy—Log requests to this service. The audit policy indicates whether to log requests and responses for this Web service.
Channels—Add or remove channels from the list of deployed channels through which this service is available.
Request filters—Add or remove filters from the list of deployed filters that are applied to the request. Note: The filters are executed in the order shown.
Response filters—Add or remove filters from the list of deployed filters that are applied to the response. Note: The filters are executed in the order shown.
UDDI references—Add or remove UDDI references from the list of deployed UDDI references to UDDI registries in which this service is registered. Note: After we add or remove UDDI references, the gateway publishes this service to (or removes it from) the UDDI registries that correspond to the added or removed references.
Target services—Add or remove single instances of multiple target services for this gateway service. To add a new target service instance, provide the following information: – WSDL location and type—Location of the internal WSDL file that describes the Web service to be deployed. This value is either a URL or the UDDI lookup information in the form: uddi_reference_name,tmodel_key,key_name,key_value

Note: When the Web Services Gateway deploys the Web service, it generates a matching external WSDL file that is made available to gateway users. This external WSDL file also describes the service, but is located at a new URL and is generated and maintained by the Web Services Gateway itself. – Target service name and namespace—If the Web service WSDL contains more than one service, type the name and namespace of the target service.

180

WebSphere Version 5.1 Web Services Handbook

– Target service identity information—Type the identity by which the target service is known within the Web Services Gateway. This identity does not have to be unique. This field is intended to be used within a routing filter to select a target service by its identity value.
UDDI publication properties—We only need to fill out these fields if we use UDDI references to automatically publish and update a registry: – – – – –

Service provider name Service provider description tModel tModel key name tModel key value (for update only)


Security bindings—Select the security settings that are applied between the target Web service and the gateway.

Troubleshooting To identify and resolve gateway-related problems, we can use the standard WebSphere Application Server facilities. If we encounter a problem that we think might be related to the gateway, we can check for error messages in the WebSphere Application Server Administrative Console, and in the application server’s stdout.log file. We can also enable the application server debug trace to provide a detailed exception dump. Refer to the WebSphere InfoCenter or the publication WebSphere Application Server Version 5 Handbook, SG24-6195, for details.

Implementation details The gateway was first introduced on the alphaWorks Web site as Version 1.0 in December 2001 (http://www.alphaworks.ibm.com) and later became part of the IBM WebSphere Business Connection. This package can be installed on top of IBM WebSphere Application Server Version 4. The gateway is part of Application Server Version 5.0.2 and 5.1 Network Deployment. The programming model extensions for writing filters are included in Application Server Version 5.0.2 Enterprise Edition. Note that the recent version of the gateway is rewritten using EJBs. Therefore, it is no longer possible to use it on pure Web containers such as Tomcat; rather, we need a complete J2EE server providing Web and EJB containers.

Chapter 10. Web Services Gateway

181

When installing and configuring the Web Services Gateway be sure to pay attention to the following tips:
WSDL definitions for target services must use XML Schema Version 2001.
The gateway application (wsgw.ear) must be installed before channel and filter applications. If the gateway application needs to be reinstalled, all channels and filters must be uninstalled first, then reinstalled after the gateway application.

Enhancements in Version 5.1 WebSphere Application Server Network Deployment 5.1 provides a number of enhancements for the gateway:
Selective SOAP Parsing—Only the header is parsed for better performance.
Local EJB Calls—Internal change to use the local interface between WSGW components (performance improvement).
JAX-RPC handlers—JAX_RPC handlers provided by the WebSphere SOAP Engine can be used in the WSGW.
Proxy operation—Using the JAX-RPC handler, multiple services can be invoked without having to be deployed to the WSGW.
SOAP over JMS—Limited support for SOAP over JMS Web services.
Security—Basic authentication, HTTPS, and Web services security.

Summary The Web Services Gateway is a middleware component that bridges the gap between Internet and intranet environments during Web service invocations. It can be used to expose Web services from the intranet to the outside world. We also can specify external Web services to use them inside our intranet. For both types of services we can specify filters to be applied before and/or after a specific service is called. When defining channels, we can translate from one protocol to another, if the client and server do not use the same. The gateway also automates the publishing and updating of our services in UDDI registries and incorporates possibilities to apply security on Web services and/or its methods.

182

WebSphere Version 5.1 Web Services Handbook

More information
An introduction to Web Services Gateway: http://www.ibm.com/developerworks/library/ws-gateway/


WebSphere Business Connection - Web Services Gateway: http://www.ibm.com/software/integration/busconn/gateway.html


Download the Web Services Gateway: http://www7b.boulder.ibm.com/wsdd/downloads/wsgw/wsgw.html

Chapter 10. Web Services Gateway

183

184

WebSphere Version 5.1 Web Services Handbook

11

Chapter 11.

Web services security Web services security is one of the most important Web services issues. It is hard to believe that one would be ready to publish or use a business service such as a stock purchase or bank account transfer without a proper security framework. In WebSphere 5.0.2 and 5.1, Web services security can be provided at the transport level (SSL) and at the message level (WS-Security specification). Highly secure client-server designs can be architected using these security levels. In this chapter we first address the main security requirements in a Web services-based application. We briefly cover the transport channel security solutions and then devote most of this chapter to the discussion on how the WS-Security specification support in WebSphere Application Server 5.0.2 and 5.1 can be fully utilized.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

185

Common security exposures First let us highlight the major security risk factors of concern when designing mission critical Web services-based applications. Let us use a bank teller scenario as a starting point. It is a simple client/server application where a bank teller (client) connects to the bank’s data center (server) using a Web services application (Figure 11-1).

Bank Data Center

Bank Teller 1

Network

Bank Teller 2 Figure 11-1 A sample bank teller application based on Web services

If no security has been applied, the three major risk factors are:
Unauthorized transactions: Someone posing as a bank teller sends a SOAP message to the data center requesting to withdraw money. This transaction is unauthorized. We fix this problem using the authentication mechanism of the WS-Security specification. An example of authentication is to include a user ID/password combination in the SOAP message.
Readable messages in clear text—no encryption: The account number and balance in the SOAP packet is read by a sniffer on the network. This exposure exists because the account and balance information is sent over the wire in plain text. As solution to this problem, plain text can be converted to unreadable form by encrypting the message either at the transport level (SSL) or at the message level (WS-Security).

186

WebSphere Version 5.1 Web Services Handbook


SOAP message susceptible to modification—no integrity: While the SOAP message is travelling from the teller to the data center, it is intercepted on the way. The interceptor modifies the message, and deposits the money in account number 1234 instead of account number 9876. The security exposure is due to lack of message integrity. This can be solved by applying a message integrity mechanisms as described in the WS-Security specification. An example is to use security tokens. In the above scenarios, we have described security concerns that fall under the areas of authentication, confidentiality, and integrity. We will discuss each of these terms in detail in this chapter and provide various options on how to ensure fully secure environments that safe-guard you against such risks. All these security mechanisms are fully supported in WebSphere 5.0.2 and later. Making Web services communications secure is not a question of if it can be done, but more of a question of how much processing power it will require. What we mean by that is that we can make applications fully secure, but the more security we apply, the more CPU time will be required by the application. Prior to the WS-Security specification, transport channel security was very commonly used. Transport channel security encrypts the entire message, resulting in higher CPU utilization. The recent advancements in the WS-Security specification provide ways to optimize security operations, which in turn require less CPU time. The security techniques are summarized in Figure 11-2.

Applying security to Web Services

SOAP message level security (WS-Security)

Authorization

Confidentiality

example: username password

example: message encryption

Transport Channel security (SSL) example: encrypt the entire message (for HTTP this means encrypting the entire HTTP message)

Integrity example: security token

Figure 11-2 Overview of applying security to Web services

Chapter 11. Web services security

187

Based on the level of security required, one or more of these security features may be applied to an application. In the following sections we cover different security approaches and their limitations.

WS-Security concepts Now that we have discussed Web services security provided either by the underlying communication channel middleware or at the XML document level, we give an overview of WS-Security, a standard proposition that covers security requirements at the Web services level. The WS-Security specification covers a standard set of SOAP extensions that can be used when building secure Web services to provide integrity and confidentiality. It is designed to be open to other security models including PKI, Kerberos, and SSL. WS-Security provides support for multiple security tokens, multiple signature formats, multiple trust domains, and multiple encryption technologies. The specification includes security token propagation, message integrity, and message confidentiality. However, these mechanisms by themselves do not address all the aspects of complete security solution. Therefore, WS-Security represents only one of the layers in a complex secure Web services solution design.

Evolution of the WS-Security specification The WS-Security support provided in WebSphere 5.0.2 and later is based on the Web services security language (WS-Security) proposed by IBM, Microsoft, and Verisign in April 2002. In WebSphere 5.0.2 and 5.1, this support is provided by the IBM WebSphere SOAP Engine. After the formalization of the April 2002 specification, more specifications have been added in this area. Some of the more recent advancements in this area have been performed under the OASIS consortium: http://www.oasis-open.org

Figure 11-3 shows the evolution of WS-Security.

188

WebSphere Version 5.1 Web Services Handbook

April 2002 WS-Security

August 2002 WS-Security Addendum

September 2002 WS-Core Draft 1

May 2003 WSS: Soap Message Security Draft 13

Oasis Activities

February 2003 WSS:Username Toke Profile Draft 2

Figure 11-3 Evolution of Web services security

To read more about these standards, refer to:
Specification: Web Services Security (WS-Security) Version 1.0 (April 2002): http://www-106.ibm.com/developerworks/webservices/library/ws-secure/


Web Services Security Addendum (August 2002): http://www-106.ibm.com/developerworks/webservices/library/ws-secureadd.html


Web Services Security: SOAP Message Security Working (May 2003): http://www.oasis-open.org/committees/download.php/2314/WSS-SOAPMessageSecur ity-13-050103-merged.pdf

Note: If you develop the Web services application using WebSphere Studio Application Developer Version 5.1.1, tools are provided for easily specifying security information. With the help of these tools you do not have to understand the SOAP format in detail.

WS-Security authentication In Example 11-1 and Example 11-2 we show a SOAP message with and without authentication. As you can see, with the authentication information in the SOAP message, we have a username and password information in the message. Example 11-1 SOAP message without security
Chapter 11. Web services security

189

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 2003-09-05T07:00:00.000Z Example 11-2 SOAP message with authentication stade2 PassWordHere 2003-09-05T07:00:00.000Z

When the username and password reach the Web service server, the message will be processed only if the username/password combination is a valid combination.

Alternatives to using a username/password mechanism Username and password validation is just one of the ways of implementing authentication. This mechanism is also known as basic authentication. Other forms of authentication are digital signature, ID assertion, LTPA, and custom tokens.

190

WebSphere Version 5.1 Web Services Handbook

Enable authentication in your application Application Developer provides user friendly screens that help you define authentication for the Web services application. Many of these steps can be performed using “drop/select”. In a typical application, the following tasks have to be performed to enable the application for authentication. Client side:
Provide a security token in the client’s deployment descriptors file. An example of security tokens is a username and password combination. This security token is sent inside the SOAP message to the server.
Specify a callback handler in the client’s deployment descriptor. The callback handler is a class file in the classpath of the client. The role of the callback handler is to grab the username and password from the deployment descriptor and insert them into the SOAP message. Callback handlers are provided by the WebSphere Web services runtime. Server side:
Configure the server to expect a SOAP message containing a valid security token. Without the security token, the request will fail.
Specify a callback handler that will read the security token in the request and then validate it.
Turn on global security in the WebSphere Application Server where the application is deployed. More information about using Application Developer to implement authentication is in Chapter 16, “Web services security with Application Developer” on page 303.

WS-Security integrity Integrity safeguards are applied to the application to ensure that no one illegally modifies the message while it is in transit. Essentially what integrity does is that it creates an XML digital signature based on the contents of the message. If the message data changes illegally, it would no longer be compatible with the XML digital signature. A signature is created based on a key that the sender is authorized to have. Unauthorized sniffers do not have this key. When the recipient gets the message it too creates a signature using the message contents. Only if the two signatures match does the receiver honor the message. If the signatures are different, an error is returned to the sender.

Chapter 11. Web services security

191

Example 11-3 shows a sample SOAP message with integrity. Different parts of the message can be digitally signed, parts such as message body, security token, and timestamp. In this example we digitally signed the security token and message body. Example 11-3 SOAP message with Integrity G+p3CZiiT/yYmkzORKt2m4KSEybc+dYEBUqbPUxA+L5epHSsy5FuxCW2XCJf ner5nov80OJdadyHCf0qfLI2Wzrx09JL0k4t+BtzgSY2B1tTIdgO770NcIIf Uq3uD9mAdVGuwKFqIofG0Kuh78ae1OjQk+Ty37FJqpVQCwxeSj0= rainy 2003-09-05T07:00:00.000Z NE 2 3 1

192

WebSphere Version 5.1 Web Services Handbook

Steps to enable integrity in your application The client and the server have to be equipped with integrity information. This can be performed with considerable ease using Application Developer as discussed in Chapter 16, “Web services security with Application Developer” on page 303. Client side:
Specify the parts of the message that have to be digitally signed. The message parts that can be signed are body, security token, and timestamp.
Specify a key on the file system that will sign the message. Only authorized clients are in the possession of this key.
Specify algorithms that will be used by the key to sign the message.
If a client expects a response that includes integrity information, then the client has to be configured to validate the integrity of the response message. Server side:
Configure the server to expect a SOAP message that contains integrity information. Specify the parts of the message that are signed. If the incoming message does not have a valid signature, the request will fail.
Specify a key that validates the signature of the incoming message.
Specify the algorithm that the key uses to validate the integrity of the incoming message.
If the response message has to be signed as well, provide similar signing information in the response.

WS-Security confidentiality Confidentiality is the process by which a SOAP message is protected so that only authorized recipients can view the SOAP message. The WS-Security specification allows encryption of any combination of body blocks, header blocks, their substructures, and attachments of a SOAP message. In Example 11-4 you can see the SOAP body with encryption. Example 11-4 SOAP body with encyption
Chapter 11. Web services security

193

Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"> cc1V//9/+mT2GerGLrCb2q7cur79S2RSx/g8V2CytHuO/KeGbGms88OKadFZB144zGSgDFggSvR7gao eJWU6ZsBM5uKvdN1yDxSiYBWXZ3e8rBByYa3N9PW1BaHFVOdTMOlc4m9MLpVyzhGb/t6utrpIdgaVrp p9Pi1s1MN7oFn/CUbCH6V5FsQFDNOkpd8dULAtArgNw4I4I3YfHO8v/A==

Steps to enable confidentiality in your application The steps to enable confidentiality follow. Client side:
Specify the parts of the message that are to be encrypted.
Specify a key on the file system that will encrypt the message. Only authorized clients posses this key.
Specify algorithms that are used by the key to encrypt the message.
If the response message is also encrypted, the client has to be configured with the location of the decryption key and decryption algorithms. Server side:
Specify the parts of the incoming message that are encrypted.
Configure the WebSphere runtime so that it is able to use the decryption key. This configuration change is made using an administrative tool such as the Administrative Console.
Specify a key on the file system that will decrypt the message.
Specify algorithms that will be used by the key to encrypt the message.
If the response message is also encrypted, the server has to be configured with the location of the encryption key and encryption algorithms.

Transport channel security Prior to the message level WS-Security, a popular means of securing Web services messages was transport channel security. It is implemented for SOAP/HTTP-based messages by using the HTTPS protocol. Unlike message level security, HTTPS provides security to the entire HTTP data packet.

194

WebSphere Version 5.1 Web Services Handbook

Therefore, we do not have an option to apply security selectively only on certain parts of the message.

SOAP/HTTP transport channel security HTTP, the most commonly used protocol for information exchange on the Internet, is an inherently insecure protocol, because all information is sent in clear text between unauthenticated peers over an insecure network. It belongs to the group of protocols, such as SMTP, telnet, and FTP, that were designed in the earlier stages of the Internet, when security seemed not to be an issue, and will eventually be replaced by transfer protocols that allow authentication and encryption. An evolution of HTTP is HTTPS, which stands for HTTP via SSL (Secure Sockets Layer). HTTPS allows client and server-side authentication through certificates, which have been either self-signed or signed by a certification agency. Upon establishing a secure connection, the server and the client negotiate the SSL protocol version to use, and a unique session ID is established. If the certificate presented by the server is unknown to the client, the client is free to accept or reject the certificate. In turn, the server can also demand a certificate from the client. During a secure session, the server and client share a common key pair that allows them to encrypt and decrypt messages they exchange. Although HTTPS does not cover all aspects of a general security framework, it provides a sufficient security level regarding party identification and authentication, message integrity, and confidentiality. However, authentication, auditing, and non-repudiation are not provided. Also, it is protocol-based and therefore all the security disappears once the message has passed the HTTP server. In addition, the encryption is message-wise and not element-wise; to access the routing information, we have to decrypt the entire message.

WS-Security extensions Because the WS-Security standard addresses only a subset of security services, a more general security model is needed to cover other security aspects such as logging and non-repudiation. This resulted in a common Web services security model framework, a proposition developed by IBM and Microsoft, which we describe in the following section.

Chapter 11. Web services security

195

Web services security model proposition The Web services security model introduces a set of individual interrelated specifications to form a layering approach to security. It includes several aspects of security: Identification, authentication, authorization, integrity, confidentiality, auditing, and non-repudiation. It is based on the WS-Security specification, co-developed by IBM, Microsoft, and VeriSign. The Web services security model is schematically shown in Figure 11-4.

WS-Security Layer

SOAP Foundation Layer

UsersWS-SecureConversation User Groups

WS-Federation

Passwords

WS-Authentication

Policies

WS-Policy

Privileges Encryption Keys

WS-Trust

Audit Logs

WS-Privacy Today

Future - specification in progress

Figure 11-4 Web services security model

The specification includes different aspects of Web services security: WS-SecureConversation Describes how to manage and authenticate message exchanges between parties, including security context exchange and establishing and deriving session keys. WS-Federation

196

Describes how to manage and broker the trust relationships in a heterogeneous federated environment, including support for federated identities.

WebSphere Version 5.1 Web Services Handbook

WS-Authentication

Describes how to manage authentication data and authentication policies.

WS-Policy

Describes the capabilities and constraints of the security (and other business) policies on intermediaries and endpoints (for example, required security tokens, supported encryption algorithms, and privacy rules).

WS-Trust

Describes a framework for trust models that enables Web services to securely interoperate.

WS-Privacy

Describes a model for how Web services and requestors state privacy preferences and organizational privacy practice statements.

The combination of these security specifications enables many scenarios that are difficult or impossible to implement with today's more basic security mechanisms such as transport securing or XML document encryption. At the time this book was written, the above specification was a proposal under review.

End-to-end enterprise security Since the early days of the Internet as a universal network open to anyone, there has been a concern for secure information exchange. Although it is worth noting that there is no absolute security, developments in this field were very quick and fruitful because they were driven by urgent business needs. Without an appropriate level of security, the commercial exploitation of the Internet would not be feasible. Networks must be designed to provide a high level of security for information that travels across the Internet or privately managed intranets or extranets. Algorithms such as third-party authentication, public key encryption, and digital signature can provide a sufficient level of security. However, security not only depends on algorithms, standards, and products, but companies must also follow security best-practice recommendations.

Note: A company’s security policy should reasonably cover the most important procedures, such as user management (adding/removing users and granting their rights and access levels), network use guidelines (private mail, Web site access policy, and antivirus protection), user authentication procedure (user ID/password, key cards), system monitoring procedures, and procedures in case of attack.

Chapter 11. Web services security

197

A general security framework should address the following requirements:
Identification—The party accessing the resource is able to identify itself to the system.
Authentication—There exists a procedure to verify the identity of the accessing party.
Authorization—There exists a set of transactions the authenticated party is allowed to perform.
Integrity—The information is not changed on its way.
Confidentiality—Nobody is able to read the information on its way.
Auditing—All transactions are recorded so that problems can be analyzed after the fact.
Non-repudiation—Both parties are able to provide legal proof to a third party that the sender did send the information, and the receiver received the identical information. Some classifications also include availability to be a part of the above schema, meaning that hostile attack cannot achieve denial-of-service by allocating too many system resources. In this chapter, we do not deal with this security aspect. Figure 11-5 shows the main components of a security framework (based upon ISO standard 7498-2). Most of the systems involved in Web services today only partially fulfill these requirements.

198

WebSphere Version 5.1 Web Services Handbook

SECURITY MANAGEMENT Service Management

Policy Management

Mechanism Management Audit & Alert Management Object Management

SEC. SERVICES

SEC. MECHANISMS

SEC. OBJECTS

Identification

Entity Authentication

Users

Authentication

Message Authentication

User Groups

Authorization

Enchiper/Dechiper

Passwords

Integrity

Access Control List

Policies

Confidentiality

Security Objects

Privileges

Auditing

Modification Detection

Encryption Keys

Non-repudiation

Digital Signature

Audit Logs

Figure 11-5 Main building blocks of a security framework

Summary Web services technology enables a loosely coupled, language-neutral, platform-independent way of linking applications within organizations, across enterprises, and across the Internet. To achieve the target, however, it is essential for Web services to provide a sufficient level of security to support business transactions. Ensuring the integrity, confidentiality, and security of Web services through the application of a comprehensive security model is critical, both for organizations and their customers.

More information Because Web services security is a quickly evolving field, it is essential for developers and designers to regularly check for recent updates. In this section, we provide some of the most important entry points for your exploration.

Chapter 11. Web services security

199

For information on IBM Tivoli® Access Manager for Business Integration, refer to this Web site: http://www.tivoli.com/products/index/access-mgr-bus-integration/

For information on IBM WebSphere MQ, refer to the standard proposition overview on developerWorks: http://www.ibm.com/software/ts/mqseries/messaging/

XML Signature Workgroup home page can be found at: http://www.w3.org/Signature/

XML Encryption Workgroup home page can be found at: http://www.w3.org/Encryption/

The SAML (security assertions markup language) Oasis Security Services Technical Committee home page can be found at: http://www.oasis-open.org/committees/security/docs/draft-sstc-use-strawman03.html

For information on WS-Security, refer to the standard proposition overview on developerWorks: http://www.ibm.com/developerworks/library/ws-secure/

The Web services security model proposition can be found at: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwssecur/ html/securitywhitepaper.asp

There are several commercial and non-commercial information sources that cover more general subjects, such as SSL encoding and HTTPS protocol.

200

WebSphere Version 5.1 Web Services Handbook

Part 2

Part

2

Web services implementation and samples In this part we describe practical examples using the IBM WebSphere products and tools and the Web Services Toolkit. We introduce the products and a simple Web service example that we then implement in various stages using the products.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

201

202

WebSphere Version 5.1 Web Services Handbook

12

Chapter 12.

IBM WebSphere product family This chapter provides an overview of the WebSphere product family. We describe the software packages that represent the core of IBM’s e-business offerings. We provide more details on WebSphere Application Server and WebSphere Studio products in the chapters that follow, but in this chapter we provide a general technical feature overview as well as the positioning information for the other WebSphere family packages. The WebSphere family products fall into one of these groups:
Foundation and tools—WebSphere Application Server, WebSphere MQ, WebSphere Studio
Reach and user experience—WebSphere Portal, WebSphere Everyplace™, WebSphere Commerce
Business integration—WebSphere Business Integration, WebSphere MQ Integrator Broker

© Copyright IBM Corp. 2003, 2004. All rights reserved.

203

Overview The IBM WebSphere family of products represents the core IBM offering for customers who want to transform their business to e-business. The main groups and products are shown in Figure 12-1.

WebSphere Portal Server

WebSphere Business Integration

WebSphere Everyplace

WebSphere MQ Integrator Broker

WebSphere Commerce

WebSphere Application Server WebSphere Studio WebSphere MQ Figure 12-1 WebSphere product family

In general, the WebSphere family of products are in one of the following groups:
Foundation and tools—This group contains products that represent the basic functional infrastructure for other products, such as WebSphere Application Server and WebSphere MQ. It also contains WebSphere Studio, a set of development tools for enterprise Web-based applications.
Reach and user experience—In this group we find the products that help the applications extend their range and reach new customers, such as WebSphere Portal and WebSphere Everyplace. WebSphere Commerce, on the other hand, enables customers to create online stores and move their business from traditional channels to the Internet.
Business integration—Products such as WebSphere MQ Integrator Broker and its extension, WebSphere Business Integration, help customers to interconnect their islands of information and make full use of the message-based architecture.

204

WebSphere Version 5.1 Web Services Handbook

The products of the first group are directly involved with Web services technology. WebSphere Application Server is the runtime environment of choice, WebSphere Studio provides the development environment, and WebSphere MQ provides JMS support as well as an alternative way of SOAP message interchange. The products from the other groups, on the other hand, represent a vehicle for extending Web services to enterprise environments and users. We cover these groups and products in the following sections.

WebSphere foundations and tools The products from this group are most directly related to Web services. WebSphere Studio products provide a range of tools and functions for the development and testing of Web services solutions. WebSphere Application Server represents an enterprise-level runtime environment for Web services-enabled applications and provides workload management, scalability, and security. WebSphere MQ provides an underlying message-oriented infrastructure as well as a channel for SOAP message exchange, in addition to other options such as HTTP and HTTPS.

WebSphere Application Server IBM WebSphere Application Server represents one of the IBM foundations of a business on demand infrastructure. It is the Java 2 Enterprise Edition (J2EE) and Web services technology-based application platform, offering one of the first production-ready application servers for the deployment of enterprise Web services solutions for dynamic e-business. WebSphere Application Server Version 5 provides an integration of deployment model, administration point, programming model, and integrated application development environment. It is fully J2EE 1.3 compatible. It delivers multiple configuration options for a wide range of scenarios, from simple administration of a single server to a clustered, highly available, high-volume environment with edge-of-network services. It offers advanced server technology, a production-ready environment, and visual workflow support for key Web services standards. The product is available for a broad range of platforms, including Windows NT/2000/XP, Linux, AIX®, Sun Solaris, HP-UX, and z/OS™.

Packaging WebSphere Application Server is available in several different configurations tailored to cover different levels of user requirements.

Chapter 12. IBM WebSphere product family

205

WebSphere Application Server - Express Express offers an affordable solution for managing simple dynamic Web sites with a simplified Web application server and a development environment based on WebSphere Studio. It is based on the latest Java technology and Web services standards. It allows you to convert static Web sites into dynamic Web applications that improve the customer experience. It provides a five-click wizard-driven installation. It is an entry-level configuration that offers a smooth migration path to other WebSphere Application Server and WebSphere Studio configurations.

WebSphere Application Server The basic WebSphere Application Server represents the production-ready Java-based application server with integrated enterprise data and transaction support for the e-business world. It offers a set of application services that include enhanced capabilities for enablement and management of heterogeneous Web services, increased security, performance, availability, connectivity, and scalability. It supports such core Web services standards as XML, Simple Object Access Protocol (SOAP), JAX-RPC and Web services description language (WSDL). It also extends the Java 2 Enterprise Edition (J2EE) 1.3 programming model by providing an infrastructure to support production-ready deployment of Web services-based applications. This makes it possible to deploy Web services with the communication mechanism of your choice, including SOAP and HTTP, Java Message Service (JMS), or Remote Method Invocation Internet Inter-ORB Protocol (RMI-IIOP).

WebSphere Application Server Network Deployment The Network Deployment Edition provides advanced Web services and clustering capabilities. It offers a private UDDI registry for easier deployment of internal Web services applications and the Web Services Gateway for external applications that request Web services from an internal Web services provider application.

WebSphere Application Server Enterprise Edition The Enterprise Edition provides an advanced application server configuration that simplifies build-to-integrate tasks, accelerates application development, and enables dynamic application flexibility. It offers build-to-integrate capabilities such as advanced application adapters, application workflow composition and choreography, extended messaging, dynamic rules-based application adaptability, internationalization, and asynchronous processing. It delivers more integration capabilities than WebSphere Application Server Network Deployment through extensions beyond the limitations of the J2EE standards.

206

WebSphere Version 5.1 Web Services Handbook

Current status and outlook WebSphere Application Server Version 5 became available at the end of 2002. Version 5 offers a variety of key benefits:
Full J2EE 1.3 compatibility together with the support of the latest stable versions of J2EE components (EJB 2.0, Servlet 2.3, JSP 1.2). The development of enterprise applications is easier when they are based on standardized, modular components.
Seamless configurations and administration, based on Java Management Extensions (JMX). The administration facility is browser-based across all deployment options.
Improved programmer productivity and simplified enterprise development with JMS API. It also supports core Web services standards, such as XML, SOAP, and WSDL, as well as enhanced options, such as the Web Services Gateway and a private UDDI registry.
Enhanced security model provides extensive support of open standards-based Java specifications, such as Java 2 Security and JAAS, as well as WebSphere’s pluggable security architecture.

WebSphere Application Server Version 5.0.2 updates WebSphere 5.0.2 (WebSphere Version 5 Fix Pack 2) provides not only fixes, but also adds new functionality to the WebSphere platform. Here are the major enhancements in WebSphere 5.0.2:
Web services updates – JSR 101 and JSR 109 support—Explained in Chapter 4, “JAX-RPC (JSR 101)” on page 67, and Chapter 5, “Implementing Enterprise Web Services (JSR 109)” on page 77 – SOAP/JMS support—Explained in Chapter 15, “WebSphere Studio Application Developer” on page 247, and “Web services runtime and deployment in WebSphere” on page 479 – WS-Security—Explained in Chapter 11, “Web services security” on page 185 – SOAP with Attachments API for Java (SAAJ) 1.1 support: http://java.sun.com/xml/saaj/

– WebSphere SOAP Engine—New SOAP engine to support JSR 101, JSR 109, and WS-Security
Expanded operating system and database support
Usability and performance improvements

Chapter 12. IBM WebSphere product family

207

WebSphere Application Server Version 5.1 updates WebSphere Application Server Version 5.1 provides these enhancements:
Support for Java SDK 1.4.1, without exploitation of new functions. – Applications compiled with 1.3 will run on 1.4.
UDDI utility tools (export, import, find, delete, promote from one registry to another). Refer to “WebSphere Application Server 5.1 update” on page 124 for more details.
Web Service Gateway enhancements, including JAX-RPC handler support and SOAP over JMS.
Tivoli Access Manager (TAM) Version 5.1 integration; TAM can be used to authenticate users in LDAP.
Support for Jython as scripting language in wsdadmin (Jython is a Java implementation of Python).
An application server can start without the node agent running.

More information For more information on IBM WebSphere Application Server, refer to: http://www.ibm.com/software/webservers/

Information Center The WebSphere Information Center is available online at: http://www.ibm.com/software/webservers/appserv/infocenter.html

WebSphere Studio The WebSphere Studio family of products is a set of development tools for enterprise e-business Java-based applications. Besides programming tools, it also enables the developers to test and deploy their application from the common environment. The rich set of utilities and wizards helps developers to simplify common tasks so that they can concentrate on more creative parts of their jobs and be more productive. The new WebSphere family of the products combines the functionality of the two former lines of IBM development tools, VisualAge® for Java, and WebSphere Studio (classic). The entire family is based on the WebSphere Studio Workbench, which contains a released level of the Eclipse Workbench. The Eclipse Workbench is an open-source project (IBM contributed the initial Workbench to Eclipse) that provides a general platform for different tools that will enable them to share the same look-and-feel and to integrate more smoothly.

208

WebSphere Version 5.1 Web Services Handbook

The WebSphere Studio Workbench will continually incorporate the features of new releases of the Eclipse Workbench as the open-source community makes them available.

Packaging The WebSphere Studio family has several member products (Figure 12-2). They are all based on the common Eclipse Workbench, whereas the many accompanying tools and plug-ins are tailored to the different needs of the developers.

Application Developer

Site Site Developer Developer Core Java IDE Create Web pages Struts support, JSP tags XML support JavaBean/DB Wizards Web Services Wizards Team Environment Integrated WebSphere App Server Express

EJB Development J2EE Development J2EE Deployment Profiling Integrated WebSphere App Server

Enterprise Developer

Application Developer Integration Edition Enterprise Connectors (CCF and J2C) Web service flow modeling WSDL Editor Integrated WebSphere App Server Enterprise

Enterprise Generation Language (EGL) COBOL and PL/I z/OS Development Environment

Figure 12-2 WebSphere Studio Product Suite

WebSphere Studio Site Developer The Site Developer package is a set of tools and perspectives targeted for developers of Web sites and Web applications. The tools support open Web standards such as XML, JavaServer Pages (JSPs), and Web services. The tools inherited from the Workbench also support Java and JavaScript development. In

Chapter 12. IBM WebSphere product family

209

addition, there is a rich set of media tools required for developing a high-quality user interface. The Web services tools include those for creating services from Java components and publishing their descriptions to a UDDI registry. It is also possible to browse a UDDI registry for available services and link to them from the Web application through JSPs. The Common Versions System (CVS) repository interface is a part of the Studio Workbench. In addition, Site Developer provides an interface to Rational®'s ClearCase® LT product. A WebSphere Express test environment is also part of the package.

WebSphere Studio Application Developer Application Developer contains all the functionality of the Site Developer. In addition, it contains the tools for J2EE 1.2 and J2EE 1.3 development as well as a set of profiling tools. The WebSphere test environment provides full J2EE support including EJBs. Application Developer Version 5.1 introduced new functions to match WebSphere Application Server Version 5.0.2:
Web services enhancements—Support for JSR 101 (JAX-RPC), JSR 109 (Implementing Enterprise Web Services), and WS-Security 1.0
Built-in Application Server 5.0.2
Performance improvements—Especially install, uninstall, EJB code generation
UML Visual Editor—Visualize Java and J2EE components in UML
Website Builder—Graphically building Web pages and their relationships
Page Designer enhancements—Free layout mode, improved taglib support
Struts—Support for Struts 1.1
Container-managed entity EJB—Mapping to view
Visual Editor—Event support
SQLJ—Support for SQLJ applications and usage of SQLJ for EJBs
Debugger—Hot method replace through new JVM Application Developer Version 5.1.1 introduced new functions to match WebSphere Application Server Version 5.1:
Built-in Application Server 5.1
Support for JDK 1.4.1 (although Application Developer runs on JDK 1.3.1)

210

WebSphere Version 5.1 Web Services Handbook


J2EE enhancements—Server targeting (for servers running on different JDKs), EJB Client JAR support
Beta support for JavaServer Faces (JSF) and WebSphere Data Objects (WDO) – JSF—GUI framework for J2EE applications – WDO—JSF objects for relational database access

WebSphere Studio Application Developer Integration Edition Application Developer Integrated Edition is targeted for professional developers of J2EE applications and Enterprise Extensions. It contains all the functionality of the Application Developer. In addition, it contains J2C support, Web services invocation framework, workflow and Web flow modeling tools, an enhanced WSDL editor, and an integrated WebSphere Application Server Enterprise Edition.

WebSphere Studio Enterprise Developer Enterprise Developer is targeted to developers and integrators, who can make use of advanced tooling such as RAD or visual modeling. It contains all the functionality of the Application Developer. In addition, it provides tools for remote edit-compile-debug for host COBOL and PL/I applications, a visual builder for adapters and microflows, and tools for visual modeling and RAD (based on VisualAge Generator technology).

Current status and outlook Application Developer Version 5 became available at the end of 2002. Application Developer Version 5.1 was released in the third quarter of 2003 and is the development environment for WebSphere Application Server 5.0.2. Application Developer Version 5.1.1 was released in December of 2003 and is the development environment for WebSphere Application Server 5.1.

More information For more information on IBM WebSphere Studio Site Developer, refer to: http://www.ibm.com/software/ad/studiositedev/

For more information on IBM WebSphere Studio Application Developer, refer to: http://www.ibm.com/software/ad/studioappdev/

Chapter 12. IBM WebSphere product family

211

WebSphere MQ IBM WebSphere MQ is a member of the IBM WebSphere MQ family (formerly MQSeries® family), which includes integrated middleware providing the intelligence and infrastructure to drive rapid and flexible business change to transform and integrate business application and processes across the extended enterprise. IBM WebSphere MQ represents the core of the WebSphere MQ family. It is available on more than 35 platforms. It provides the base messaging functions for servers and clients, and assures once-only message delivery. It can be used alone or with other members of the family. It also represents the infrastructure of WebSphere Application Server JMS, and this is the reason that it is part of the foundations and tools group. WebSphere MQ supports application integration by helping business applications to exchange information across different platforms, sending and receiving data as messages. WebSphere MQ hides network interfaces from the developer, assures once and once only delivery of messages, deals with communications protocols, dynamically distributes workload across available resources, handles recovery after system problems, and helps make programs portable. So programmers can use their skills to handle key business requirements, instead of wrestling with underlying network complexities.

Current status and outlook The latest release is WebSphere MQ Version 5.3. It maintains compatibility with the previous release, IBM MQSeries Version 5.2. In addition, it provides security using secure sockets layer (SSL), the Internet standard for secure communication. It also implements enhanced features for performance, especially for JMS applications, making WebSphere MQ the JMS provider of choice. Other features have been added to enhance system scalability and reliability, particularly useful for clustering of systems that can share workload.

More information For more information on IBM WebSphere MQ refer to: http://www.ibm.com/software/ts/mqseries/

WebSphere reach and user experience Products and offerings from this group provide smooth operation and continued scalable business growth with the support of commerce transactions. They help customers to extend and personalize their businesses.

212

WebSphere Version 5.1 Web Services Handbook

WebSphere Portal IBM WebSphere Portal for Multiplatforms provides a single point of interaction with dynamic information, applications, processes and people to help build successful business-to-employee (B2E), business-to-business (B2B) and business-to-consumer (B2C) portals. WebSphere Portal also supports a wide variety of pervasive devices enabling users to interact with their portal anytime, anywhere, using any device, wired or wireless.

Packaging WebSphere Portal provides three different configurations. The Portal Enable package is the base offering. Portal Extend and Portal Experience provide additional functionality for advanced customers.

Portal Enable WebSphere Portal Enable represents an entry level portal technology that simplifies and speeds your access to personalized information and application. It provides several common services including:
Connectivity and integration to allow access to enterprise data or external information by connecting to partners’ applications.
Presentation and administration to enable information access customization while providing access to enterprise resource planning (ERP), customer relationship management (CRM), and supply chain management (SCM) applications.
Security features that include an authentication layer to provide controlled access to the portal. User information is stored in a Lightweight Directory Access Protocol (LDAP) directory. Portal Enable provides two personalization technologies:
Rules-based filtering that determines which Web content is displayed for a particular user.
Statistical models and matching techniques that extract visitor behavior and trends. This way the displayed content can be tailored to different users and groups.

Portal Extend WebSphere Portal Extend extends the functionality of the Portal Enable by adding collaborative components and Web usage analysis tools together with tools to access, organize, and share information. Features include:
Parallel, distributed searching capability

Chapter 12. IBM WebSphere product family

213


Individual and shared team workspaces with built-in collaborative capabilities
Collaboration software components
Web site analysis tools

Portal Experience WebSphere Portal Experience provides new tools and functionality in addition to all the tools and capabilities contained in Portal Extend. This includes:
Advanced collaboration features for e-meetings, application sharing and white boarding
Data storage for a broad spectrum of digital information including Facsimiles, images, PC files, XML, and multimedia.
Content infrastructure for applications such as call centers.
Folder management and document workflow.
Sample Java applications as well as advanced application development tools.

Current status The most recent version of the WebSphere Portal offerings is Version 5.0. With this, a lightweight version of WebSphere portal called Portal Express has been released. Portal Express provides an easy-to-use, single-server installation, and quick, out-of-the-box operations demanded by smaller firms and departmental groups.

More information For more information on IBM WebSphere Portal refer to: http://www.ibm.com/software/webservers/portal/

WebSphere Everyplace IBM WebSphere Everyplace products are part of the larger pervasive computing products that enable users to interchange any information over any network using any device, not only the traditional desktop. WebSphere Everyplace focuses on the users of Web-enabled cellular phones and other mobile devices. It provides both server- and client-side technology to move the e-business solutions from the standard desktop environment to portable devices.

Products The WebSphere Everyplace group contains three different configurations.

214

WebSphere Version 5.1 Web Services Handbook

IBM WebSphere Everyplace Embedded Edition WebSphere Everyplace Embedded Edition integrates essential software to enable device manufacturers, developers and service providers to Web-enable their products. It includes built-in middleware, content development tools, customization services, and server integration for a variety of devices. It is based on the Java programming language and uses open standards to create a flexible platform. Embedded Edition includes an embedded, real-time operating system (RTOS); a Java Virtual Machine (JVM) environment built for embedded applications; a framework for managing the life cycle of network-delivered services and applications; network connection management for both wired and wireless connections; integrated support for a hybrid application environment using both Java and native code; integration with IBM content management and delivery technologies; as well as security mechanisms, like VPN, SSL, encryption and authentication.

WebSphere Everyplace Access WebSphere Everyplace Access supports mobile devices with the respect of device and network capabilities. The package features include PIM and e-mail synchronization using the SyncML standard, device-specific content tailoring through the use of portlets and transcoding, device support for PDAs and Internet-enabled phones, integration into your existing IT infrastructure through third-party directory support and authentication proxy, as well as well-defined APIs for application enablement. DB2® Everyplace and Lotus Domino™ Everyplace Enterprise Server are also part of the package.

WebSphere Everyplace Server, Service Provider Offering WebSphere Everyplace Server, Service Provider Offering (SPO) combines all of the middleware infrastructure needed to connect, adapt, manage, transform, and scale today's Web applications and legacy data into the pervasive computing environment. It extends the reach of Web applications to a broad range of wireless and mobile devices, including Wireless Application Protocol (WAP) phones and wireless connected PCs; sometimes connected devices such as PalmPilots and PocketPCs; and always connected devices such as residential gateways, Internet access devices, and digital set-top boxes. WebSphere Everyplace Server SPO is the most complete offering in the WebSphere Everyplace Server family. It provides tools and middleware infrastructure required for rapid development, deployment and management of mobile services. The solution also provides centralized management capabilities,

Chapter 12. IBM WebSphere product family

215

as well as network independence over a broad range of mobile and/or line networks for TCP/IP and WAP applications.

Current status WebSphere Everyplace Access V4.3 is being released in two phases. The first, V4.3.0, supports Windows 2000 and AIX. It includes enhancements in the area of Lotus SameTime messaging support for mobile devices and added support for palm devices. The second release, V4.3.1, will replace V4.3.0 and add further enhancements in the area of support for Solaris 8 and Oracle 8 plus support for selected Sharp devices. WebSphere Everyplace Server, SPO Version 2.1 replaces IBM WebSphere Everyplace Suite Version 1.1 (both the Service Provider Edition and the Enterprise Edition). Version 2.1 expands the capabilities of Version 1.1 editions by adding several new features. Among others, it allows users or applications to more easily manage information with intelligent notifications that are triggered when events occur and/or content is available based on preferences. It supports location-based information to dynamically determine the user's device position information, pass that information to an application, and manage the privacy of location information. It extends hands-free access to applications through the IBM WebSphere Voice Server, giving users voice recognition and voice access to application content. It integrates with Domino application adapters in Domino Everyplace Server. It also incorporates encryption and authentication capabilities in integration with Policy Director for enhanced authorization and access control.

More information For more information on IBM WebSphere Everyplace and other pervasive computing technologies and products refer to: http://www.ibm.com/software/pervasive/

WebSphere Commerce IBM WebSphere Commerce software helps you sell goods and services online. It supports B2C, B2B, or private exchange business models. WebSphere Commerce (formerly Commerce Suite) represents the IBM online trading solution. It enables customers to start small and grow fast once their business is established. It combines several middleware products from the WebSphere family, such as WebSphere Application server, with other products and applications into a complex e-trading environment.

Packaging WebSphere Commerce comes in three different configurations.

216

WebSphere Version 5.1 Web Services Handbook

WebSphere Commerce Professional Entry Professional Entry Edition provides an entry-level solution for a quick start of Web-based training. The features include tools for creation and management of online catalog information, marketing and reporting tools, filtering engines to discover customer buying patterns and preferences, as well as advanced inventory and order management capability to automate and optimize the processing of customer orders. The offering includes WebSphere Commerce Accelerator to provide a single point of administration for store and product management, marketing and merchandising, order management and customer service. In also includes IBM DB2 Universal Database™. The growth path to WebSphere Commerce Professional Edition is also provided.

WebSphere Commerce Professional Edition Professional Edition provides an online selling solution for a more demanding customer. It can handle high transaction volumes and provides the connectivity to existing back-end systems. The product provides enhanced features and functions including advanced order management capabilities to optimize movement of products through the supply chain, dynamic collaborative technology through Lotus Sametime®, portal add-on capability to provide customers with a personalized single point-of-access, and localization to meed the demands of the customers from different locations. The bundled product list includes WebSphere Catalog Manager and WebSphere Payment Manager. The product supports industry standards like Java, JSP, EJB and XML, therefore providing the connectivity with other middleware and systems including IBM CICS®, WebSphere MQ, and SAP R/3.

WebSphere Commerce Business Edition Business Edition is based on IBM’s enterprise technology, thus providing high reliability, scalability, and performance. Its features include B2B personalization to manage business relationships, assisted selling technology to walk customers and partners through the requirements gathering and product selection process, online collaboration and virtual teaming tools, as well as integrated contract management. It offers multi-cultural capabilities to reach global customers and business intelligence functionality.

Current status The latest product version is IBM WebSphere Commerce Version 5.5, which has introduced several improvements. V5.5 also introduces WebSphere Commerce Express - a lightweight solution for small- and medium-sized projects.

Chapter 12. IBM WebSphere product family

217

More information For more information on IBM WebSphere Commerce refer to: http://www.ibm.com/software/webservers/commerce/

WebSphere Business Integration In the WebSphere Business Integration group we meet the rest of the WebSphere MQ family: WebSphere MQ Integrator Broker and its extension WebSphere Business Integration.

WebSphere MQ Integrator Broker IBM WebSphere MQ Integrator Broker for Multiplatforms provides an infrastructure for business processes to control information flows according to their specific business needs. Thus, the necessary flexibility and control of their business data is achieved. WebSphere MQ Integrator Broker architecture provides an open framework where functions defined as nodes can be joined together to operate on the content of the messages. A set of prepared functions is available as a part of the product, and open API provides the extension possibility. Additionally, the WebSphere MQ Integrator Broker shares the functionality of relational database technology with respect to message augmentation, warehousing, and message flow tools.

Current status and outlook IBM WebSphere MQ Integrator Broker Version 2.1 provides customers with the necessary basis for application integration solutions architecture. It enables them to integrate existing applications to other existing or new applications. They can visually check the application flow through the use of a graphical development environment. The architecture includes rules for message transformation as well as routing and distributing between different systems. It enables integration of application and business data using dynamic content. It also supports topic-based publish/subscribe functions. The advanced message format dictionary and manipulation tools support multiple formats including XML and plug-in, third-party dictionaries, and formats. GUI-based tooling helps users designing, using and manipulating business rules.

More information For more information on IBM WebSphere MQ Integrator Broker refer to: http://www.ibm.com/software/ts/mqseries/integrator/broker/

218

WebSphere Version 5.1 Web Services Handbook

WebSphere Business Integration The IBM WebSphere family includes business integration products and solutions that help integrate either a single department or entire companies with the partners and Web customers. In addition to WebSphere MQ Integrator Broker, IBM WebSphere Business Integration contains the following products:
IBM CrossWorlds®—A freshly acquired process integration software based on pre-built, reusable components.
Collaborations— Process templates of many common operational activities such as synchronizing products or customer files, handling customer or supplier orders, or managing information about employees and departments across a company.
Connectors and Adapters—Pieces of software designed to access application data, or to link with business partner systems.
Common Business Objects—The components that simplify the implementation of an integration infrastructure and reduce maintenance of application interfaces.
IBM MQSeries Workflow—A process engine for model-driven e-business process automation and tracking.

Current status At the time of writing of this book, the recent version of the product is IBM WebSphere Business Integration Version 4.2.

More information For more information on IBM WebSphere Business Integration refer to: http://www.ibm.com/software/ts/wbi/

Summary In this chapter we covered the IBM WebSphere product family, which represents the basis of the IBM e-business strategy. The foundation and tools group covers the basic plumbing of the complex Web-based enterprise applications: Java-based application servers and message queuing middleware. It also contains tools for rapid application development.

Chapter 12. IBM WebSphere product family

219

In the reach and user experience group we find the products that extend enterprise applications to portals, where they can be reached by the growing Internet population. They can also extend the reach to users of handheld devices and cellular phones. Other products help customers moving their traditional selling operations to the Internet in a controlled scalable manner. The business integration group products help customers to integrate existing separate software and hardware assets and make the best use of them. The WebSphere family products are available for a wide range of software and hardware platforms and they are regularly enhanced to meet the growing and quickly changing demands of e-business.

More information The WebSphere family of products are regularly updated to cope with the e-business environment that changes at a high pace. Therefore the Internet represents one of the best sources of up-to-date information. For general information on the IBM WebSphere family of products refer to: http://www.software.ibm.com/websphere/

Sources of additional information on particular products can be found at the end of the corresponding subsection.

220

WebSphere Version 5.1 Web Services Handbook

13

Chapter 13.

Web services development overview This chapter provides a general introduction to Web services development. We present the different paths for developing a Web service and types of clients without getting too specific regarding implementation details. For implementation details regarding J2EE environments see Chapter 4, “JAX-RPC (JSR 101)” on page 67, and Chapter 5, “Implementing Enterprise Web Services (JSR 109)” on page 77. This chapter contains the following topics:
Building a new Web service
Building a new Web service client

© Copyright IBM Corp. 2003, 2004. All rights reserved.

221

Overview There are four main phases in developing a Web service: Build, deployment, run, and management.
The build phase includes development and testing of the Web service application, including the functionality and definition of the service.
The deployment phase includes publication of the service definition, the WSDL document, and deployment of the runtime code of the Web service.
The run phase includes finding and invoking of the Web service.
The management phase includes management and administration of the Web service application.

Web services development The build cycle for a Web service involves some common steps that have to be followed to create a new Web service. During its development the Web service passes between different states. These states are shown in Figure 13-1.

Build build or have

Initial

build or have

1 Service

definition WSDL

build

Java

1 code

Deploy

Run

Management

assemble

WebSphere Web service build

deploy

assemble

Web service deploy

run

Web service run

manage

Web service manage

invoke

publish Service registry

Client

find

Figure 13-1 Web services development

Build phase The first phase is the build phase, when we create a Web service. There are two possible paths:
The red path (solid)—From the initial state we build or already have Java code. Using this Java code we build the service definition (WSDL document)

222

WebSphere Version 5.1 Web Services Handbook

with the business methods that we want to expose. Once we have generated the WSDL document, we assemble the Web service application.
The blue path (dashed)—From the initial state we build or already have a service definition, WSDL document. Using this WSDL document we build or adapt the Java code to implement that service. Once we have implemented the code, we assemble the Web service application.

Deployment phase The second phase of a Web service is deployment. In this phase we deploy the Web service to an application server. After that, we publish the Web service to be found by the clients. The publication can be done using a UDDI registry, using a WSIL document, or by directly providing the information about the new service to future consumers, for example, with e-mail. A combination of all these publishing methods is also possible.

Run phase The third phase is the runtime. In this phase the Web service is operative and is invoked by several clients that require the functionality offered by this service.

Management phase The final phase is the management phase where we cover all the management and administration tasks of the Web service application. In the following sections, we concentrate on the different possible paths to create a Web service and a Web service client within the build phase.

Building a new Web service In this section, we describe the different paths to use in the generation of a Web service. We find three principal approaches, depending upon the elements that we use to start the creation of the service. A Web service can be implemented from:
An existing application (bottom-up) Transforming an existing application into Web services includes the generation of service wrappers to expose the business functionality.
An existing service definition, WSDL, to generate a new application (top-down)

Chapter 13. Web services development overview

223

Generating a new application includes using a specific programming language and model.
An existing group of already generated Web services to provide a new combination of functionality (multiple services) Composing a new Web service may include the use of workflow technologies.

Bottom-up The bottom-up approach is the most common way to build a Web service. We start with a business application that is already developed, tested and is running on the company systems. In Figure 13-2 we can see this path.

Generate

Service Application

Service definition WSDL Deployment descriptors

Web Service

Figure 13-2 Bottom-up path

We start with the service application and generate the WSDL document for it, providing all the functionality that we desire to externally expose as a Web service. Depending of the implementation model (J2EE, for example), we also have to generate the deployment descriptors.

Top-down The top-down approach is commonly used when we have a standard service definition and we want to implement this definition to provide the requested service. The service definition may, for instance, come from an industry-sector agreement and may be implemented by any number of providers, for example, when a group of airlines agree on how to provide their plane schedules. In that case, there is a strict definition of what the providers receive and how they have to respond.

224

WebSphere Version 5.1 Web Services Handbook

Therefore, the providers have to adapt their current systems to follow the new specification. The top-down path is shown in Figure 13-3.

Generate

Service definition WSDL

Service Skeleton Deployment descriptors Web Application Service Code Figure 13-3 Top-down path

The process of creating a Web service using this path can be divided into the following steps:
Find the service interface. We localize the service definition to use it as the entry point for the implementation. We obtain the WSDL document through a proprietary channel from the service provider (e-mail, for example) or through a WSIL document or by searching a UDDI registry.
Generate the implementation skeleton. Using the service definition, we generate a skeleton with the methods and parameters that we have to fill in to implement the Web service.
Develop the new Web service. Using the skeleton, we complete all the methods with the appropriate logic. Depending upon the amount of code that we can reuse from other applications and the complexity of the service definition, we develop more or less new code. In a J2EE environment, we also generate deployment descriptors. Finally, we test the new Web service to check that everything runs smoothly.

Chapter 13. Web services development overview

225

Multiple services The multiple services approach is commonly used when we have a collection of Web services running in one or more systems and we want to provide new functionality reusing the existing features provided by these Web services. In this path we create a new integrated Web service combining some of the individual characteristics provided by the existing Web services and also other business modules. This path is shown in Figure 13-4.

Service

Business module

Deployment definition descriptors

WSDL

WS 3 WS 1

WS 4 WS 2

WS 5

Web Service

Figure 13-4 Multiple services path

The individual Web services, WS n, are linked sequentially. Therefore, the output of one service is the input for the following service or business module. We can also create different outputs at runtime depending on the flow characteristics and the input data. The multiple services path can have both previous approaches, bottom-up and top-down, in its implementation. The most common is the bottom-up alone or combined with the generation of one or more top-down services to complete the sequence. On the other hand, we can consider the creation of a top-down Web service dividing the resulting service into multiple sub-services that can be useful for other applications.

226

WebSphere Version 5.1 Web Services Handbook

Types of Web services implementation The base for the J2EE implementation of a Web service can be varied from different modules and applications. These possibilities in the creation of a Web service depend upon the tools and products that we are using in the generation process and the facilities that they provide to easily complete the creation task. Table 13-1 lists the tools and which Web services implementation types they facilitate on a particular path. Table 13-1 Web services implementation facilities by products Tool or product

Path

Java bean

EJB

DADX

ISD

URL

WSAD (WebSphere Soap Engine)

Bottom-up

Yes

Yes

Yes

Yes

Yes

Top-down

Yes

Yes

No

No

No

WSADIE (SOAP 2.3)

Bottom-up

Yes

Yes

Yes

Yes

Yes

Top-down

Yes

Yes

No

No

No

Multiple services (business process) implemented as an EJB service WSDK (WebSphere Soap Engine) ETTK (Axis)

Bottom-up

Yes

Yes

No

No

No

Top-down

Yes

Yes

No

No

No

WSAD = WebSphere Studio Application Developer V5.1 WSADIE = WebSphere Studio Application Developer Integration Edition V5.0 WSDK = WebSphere SDK for Web Services V5.0.2 ETTK = Emerging Technologies Toolkit DADX = Document access definition extensions ISD = Web service deployment descriptor (points to implementation code) URL = Uniform resource locator (for a servlet)

Building a new Web service client Web services for J2EE specifies three different types of clients (see “Client programming model” on page 79). In this section, we explain types from a more general point of view. The task to build or generate a Web service client (also known as a service requestor) depends on the methods of how the client is binding to a Web service server. The client uses a local service stub or proxy to access the remote server and service. The WSDL document is used to generate or set up this particular

Chapter 13. Web services development overview

227

stub or proxy. The stub or proxy knows at request time how to invoke the Web service based on the binding information. The methods of binding to a service are defined by the time when the various elements of binding information are available and used, namely at build time vs. at runtime. This results in three client types:
Static client
Dynamic client with known service type
Dynamic client with unknown service type Note: In this context, the term binding information is used in a general sense and is not limited to the section of a WSDL document.

Static client The static client has a static binding created in the build time. This is made possible because in the development phase we know the interface, the binding method, and the service endpoint of the Web service that we are going to invoke. We also decide that we only use this client for that specific service and nothing else. Therefore, in these cases, the best solution is to use a static client. No public, private, or shared UDDI registry or WSIL document is involved in the runtime process. Figure 13-5 shows the process to generate a static client.

WSIL

e mail

Service definition WSDL

1 Find build time

Service definition WSDL

WS client

2

Generate

Deployment descriptors

3 Proxy or Stub

Figure 13-5 Static client path

228

UDDI registry

WebSphere Version 5.1 Web Services Handbook

Bind

Web Service

The steps to build a static service client are: 1. Manually find the service definition or WSDL. We obtain the WSDL document through a proprietary channel from the service provider (e-mail, for example) or through a WSIL or looking in a UDDI registry. An important point is that we store the WSDL document into a local configuration file. Therefore, we have all the information previously defined before we start to code the client. 2. Generate the service proxy or stub. Using the information contained in the WSDL document, we generate the proxy or stub and probably the deployment descriptors. This stub is a local representation of the remote Web service. Depending upon the tool or product we use in this step, the generation is performed automatically. 3. Test the client. We test the code to check that the client correctly operates and binds to the Web service.

Dynamic client with known service type The dynamic client has a dynamic binding that is only known and decided at runtime. This client is used when we know the interface of the service but not the implementation (the service endpoint). This means that the operation, the parameters associated with the operation, and the way to bind to the service are already known, but the address where this service is provided is not known. An example of this is when an industry defines a service interface and the partner companies implement the specification. In that case, we only want to have one client that can dynamically change between the different providers based on certain criteria (performance, cost, and so forth). The use of a public, private, or shared UDDI registry is involved in the process to dynamically provide to the client a range of entry points available at a specific time. Figure 13-6 shows the process to generate such a dynamic client.

Chapter 13. Web services development overview

229

Service definition WSDL

1 Find build time

Service interface

Service interface

Generate

UDDI Registry

Service implementation

3

Find runtime

2

WS client

Deployment descriptors

Proxy or Stub

4

Bind

Web Service

Figure 13-6 Dynamic client path

Note: Instead of a UDDI registry, Web services inspection language (WSIL) can also be used to create dynamic clients. The steps to build a dynamic service client are: 1. Manually find the service interface definition of the WSDL. We obtain the service interface definition, the types, the messages, the port type with the operations, and the binding of the WSDL document through the same mechanism used with the static client. In this case we are only interested in the service interface, which is what we load into a local configuration file. Therefore, the information of how to invoke the Web service is previously defined before we start to code the client. 2. Generate the generic service proxy or stub. Using the information contained in the service interface, we generate the generic proxy or stub and probably the deployment descriptors. This generic proxy or stub can be used to access any implementation of the service interface used in the generation process. 3. The proxy or stub (or a helper class) contains the necessary code to locate a service implementation by searching a UDDI registry. This UDDI lookup code is currently not generated by tools and must be hand-coded using the UDDI4J API.

230

WebSphere Version 5.1 Web Services Handbook

4. Test the client. We test the code to check that the client correctly operates and binds to any Web services that implement the service interface dynamically.

Dynamic client with unknown service type There are other, more dynamic ways to connect to a Web service. For example, at build time we do not know the binding to connect to a Web service, or the binding is decided at runtime from among different possibilities. The steps to create this client are the same as for the previously described client, with the only difference being that the proxy is created at runtime with the binding information collected just before the connection. To create such a client, we use WSIF (see Chapter 7, “Web services invocation framework” on page 129). Even more dynamic is when we do not know anything about the service in advance, as it is in a dynamic invocation interface (see “Dynamic invocation interface (DII)” on page 81). In these cases, the service client obtains the service definition WSDL document from a UDDI registry or WSIL document at runtime. There is no proxy code generation at build time; it is generated at runtime to bind and invoke the Web service. This kind of binding requires the presence of a user interface that can provide the input data and understand the meaning of the output. Therefore, this last path, totally dynamic, hardly has any real business application.

Types of client implementations The base for the Java implementation of a Web services client can vary depending on where the client can reside and what kind of module or application is built. From the point of view of where the client can reside, the possibilities are:
Stand-alone Java J2SE application client
J2EE application in some middleware container From the point of view of what kind of module or application is built, the possibilities are:







Java class JavaBean EJB session bean Servlet JavaServer Page (JSP) Java applet

Chapter 13. Web services development overview

231

The different tools and products that this publication refers to offer various facilities to automatically generate code required to build a client. Usually, there is always some manual coding required and is inevitable for dynamic clients. Table 13-2 lists the facilities provided by the tools. Table 13-2 Web services client implementation facilities by products Tool or product

Facilities

Application Developer (WebSphere Soap Engine)

Generates services and stubs as it is defined by JSR 101 and JSR 109, the mapping parameters, and JSPs to test the client visually.

Application Developer Integration Edition (SOAP 2.3)

Generates a proxy, the mapping parameters, and JSPs to test the client visually. Includes WSIF for dynamic invocation. Includes business process flow modeling. Generates Web services from EIS using connectors.

WebSphere SDK for Web Services (WebSphere Soap Engine)

Generates all the stubs needed to connect with the Web service, including the mapping parameters and a service locator (XML file and Java code to locate the service).

Emerging Technologies Toolkit (Axis)

Axis facilities.

For further information about the listed tools, products, and client generation, see the respective chapters.

Summary In this chapter we have presented the development concepts to create a Web service and a Web service client. We have studied the different paths to follow or choose when we want to create a Web service. We have also learned how to select these paths, depending upon the starting situation in the case of Web services or the functional objectives in the case of the Web service clients.

More information For a more comprehensive discussion of the topic, refer to the document Web Services Development Concepts 1.0 from the Emerging Technologies Toolkit. It is also available at the following URL: http://www.ibm.com/software/solutions/webservices/pdf/WSDC.pdf

232

WebSphere Version 5.1 Web Services Handbook

14

Chapter 14.

Weather forecast application In this chapter we describe the base Java code of a weather forecast application, which we use to demonstrate the Web services technology. Note: The weather forecast application was extended from the previous version of the publication:
Web service provider as session EJB or JavaBean
Includes a database to store weather information

© Copyright IBM Corp.2003, 2004. All rights reserved.

233

Weather forecast application components The weather forecast application is the example that we use in the following chapters to demonstrate how to create a Web service with different tools and programs. The weather forecast is an application that simulates weather forecast predictions. This weather forecast application is composed of three main modules: Business module, data module, and back-end module. It also provides two different implementations, as a session EJB in an EJB project and as a JavaBean in a Web project.

Business module The business module is implemented by the WeatherForecast class in a Web module and by the WeatherForecastEJB session bean in an EJB module. These classes offer the business logic of our example providing four principal functions:





Provides the weather forecast prediction for one specific day Provides the weather forecast prediction for a period of time Provides the temperature prediction for a period of time Provides the functionality to load new weather information

The data returned by the business methods is:





A JavaBean representing the complex type Weather An array of Weather JavaBeans An array of integer numbers (temperatures) None (void)

Data module The data module is implemented by the Weather class in both implementations. This class provides the content information of a weather prediction. The information contained in a weather prediction is:







234

Wind direction in an eight-point compass (String) Wind speed in kilometers per hour (int) Temperature in degrees Celsius (int) Weather condition: Sunny, partly cloudy, cloudy, rainy, stormy (String) Date of the prediction (Calendar) Database flag, info from database or not (boolean)

WebSphere Version 5.1 Web Services Handbook

Back-end module The back-end module is contained in the WEATHER database. This database contains the SANJOSE table, where the weather information for San Jose is loaded. The back-end module is supported by the WeatherPredictor class. This class is responsible for making a simulated prediction about weather conditions, using random values when no information for the requested day is contained in the database.

Information flow Figure 14-1shows the internal flow of the system information for one of the query methods. create the Weather elements

2 populate the Weather elements

Weather Weather Weather Weather Weather request weather information

Client

1

4

query the DB for weather prediction

Weather Forecast

3

6

populate the DB with new Weather elements

WEATHER Database

Weather Predictor

Weather Weather Weather Weather

return the Weather elements with the weather prediction

7 generate random Weather if no information in DB

5 Figure 14-1 Weather forecast query flow behavior

The steps for this flow are: 1. A client requests weather information from the WeatherForecast bean.

Chapter 14. Weather forecast application

235

2. The WeatherForecast creates a Weather element (or elements) for the response to the client’s weather request. 3. The WeatherForecast queries the weather prediction from the WEATHER database. 4. The WeatherForecast populates the Weather element(s) based on the information present at that moment in the database. 5. The weather information that is not in the database is requested from the WeatherPredictor. 6. The database is populated by the WeatherForecast with the new Weather element(s) generated by the WeatherPredictor. 7. The WeatherForecast returns the Weather element(s) to the client. Note: The WeatherPredictor class uses a random number algorithm to populate weather information. This makes our example very simple, but enables us to concentrate on the important Web services aspects instead of trying to write a sophisticated back-end application. Figure 14-2 shows the internal flow of the system information for the load method.

send weather information

Client

1

Weather Forecast

Weather Weather Weather Weather

2 load the weather predictions into the database

WEATHER Database

Figure 14-2 Weather forecast load flow behavior

The steps for this flow are: 1. A client sends weather information to the WeatherForecast bean to load the database. 2. The WeatherForecast populates the database with the Weather element (or elements). Note: The load operation does not return any data. It can be used to implement an asynchroneous Web service using SOAP over JMS.

236

WebSphere Version 5.1 Web Services Handbook

Base code In this section we list the base code of the main modules.

Weather data The Weather class is shown in Example 14-1. Example 14-1 Weather class package itso.mapping; import java.io.Serializable; import java.text.SimpleDateFormat; import java.util.Calendar; /** * class Weather * This class encapsulate some weather artifacts for a specific day */ public class Weather implements Serializable { private private private private private private

String windDirection = null; int windSpeed = 0; int temperatureCelsius = 0; String condition = null; Calendar date = null; boolean dbflag = false;

/** * Default Constructor for Weather. * initialize with today's date */ public Weather() { super(); } /** * Constructor for Weather. * Initialize with a given date * @param theDate */ public Weather(Calendar theDate) { super(); date = theDate; } /** * @see java.lang.Object#toString() * used for deugging and testing purposes only */ public String toString() { SimpleDateFormat sdf = new SimpleDateFormat("EEE. MMM d, yyyy");

Chapter 14. Weather forecast application

237

return "Weather: " + sdf.format(date.getTime()) + " '" + condition + "' wind: " + windDirection + " " + windSpeed + "km/h " + temperatureCelsius + " Celsius"; } // getter and setter methods abbreviated public public public public public public public public public public public public

String getCondition() { return condition; } Calendar getDate() { return date; } String getWindDirection() { return windDirection; } int getWindSpeed() { return windSpeed; } void setCondition(String condition) { this.condition = condition; } void setDate(Calendar date) { this.date = date; } void setWindDirection(String windDirection) { this.windDirection = windDirection; } void setWindSpeed(int windSpeed) { this.windSpeed = windSpeed; } int getTemperatureCelsius() { return temperatureCelsius; } void setTemperatureCelsius(int temperatureCelsius) { this.temperatureCelsius = temperatureCelsius; } boolean isDbflag() { return dbflag; } void setDbflag(boolean b) { dbflag = b; }

}

Weather forecast JavaBean The WeatherForecast class, a JavaBean, is shown in Example 14-2. Example 14-2 WeatherForecast class package itso.bean; import java.util.Calendar; import java.util.Vector; import itso.mapping.Weather; import itso.mapping.WeatherPredictor; import javax.naming.InitialContext; import javax.naming.NamingException; import javax.sql.DataSource; import java.sql.Connection; import java.sql.PreparedStatement; import java.sql.ResultSet;

238

WebSphere Version 5.1 Web Services Handbook

/** * This class is the main entry point into this service. * It offers four different methods to query and update the weather. * The four signatures represent different "challenges" for the Web service, which are: * - a complex type * - an array * - the combination of both */ public class WeatherForecast { private private private private

DataSource ds = null; String db2Select = null; String db2Insert = null; String db2Delete = null;

public WeatherForecast() throws java.lang.Exception { try { InitialContext envCtx = new InitialContext(); String dataSourceName = (String)envCtx.lookup("java:comp/env/dataSource"); ds = (DataSource)envCtx.lookup("java:comp/env/"+dataSourceName); db2Select = (String)envCtx.lookup("java:comp/env/getDB2Weather"); db2Insert = (String)envCtx.lookup("java:comp/env/setDB2Weather"); db2Delete = (String)envCtx.lookup("java:comp/env/removeDB2Weather"); } catch (Exception e) { System.out.println("WeatherForecast exception: "); e.printStackTrace(); throw (e); } } /** * Method getDayForecast returns one complex weather object for a specific day * @param theDate The chosen day to obtain the weather forecast * @return Weather The weather for that day * @throws Exception If any probem occurs during the process to retrieve the weather */ public Weather getDayForecast(Calendar theDate) throws Exception { if (theDate == null) theDate = Calendar.getInstance(); Weather [] iWeather = executeQuery(theDate, 0); return iWeather[0]; } /** * Method getForecast returns an array of complex weather object for a specific * period of time * @param startDate The chosen day to start with the weather forecast * @param days The number of days to include in the weather prediction * @return Weather[] An array with the weather forecast * @throws Exception If any probem occurs during the process to retrieve the weather */ public Weather[] getForecast(Calendar startDate, int days) throws Exception { if (startDate == null)

Chapter 14. Weather forecast application

239

startDate = Calendar.getInstance(); Weather [] iWeather = executeQuery(startDate, days); return iWeather; } /** * Method getTemperatures returns an array of temperatures ... * @param startDate The chosen day to start with the temperatures forecast * @param days The number of days to include in the temperatures prediction * @return Weather[] An array with the temperatures values * @throws Exception If any probem occurs during the process */ public int[] getTemperatures(Calendar startDate, int days) throws Exception { if (startDate == null) startDate = Calendar.getInstance(); Weather [] iWeather = getForecast(startDate, days); int[] temperatures = new int[iWeather.length]; for(int i=0; i
240

WebSphere Version 5.1 Web Services Handbook

} } catch(Exception e) { throw (e); } finally { try { if (ps != null) ps.close(); if (conn != null) conn.close(); } catch (Exception e) { } } } /** * Method executeQuery returns an array of complex weather object ... * @param startDate The chosen day to start with the weather forecast * @param days The number of days to include in the weather prediction * @return Weather[] An array with the weather forecast * @throws Exception If any probem occurs during the process to retrieve the weather */ private Weather [] executeQuery (Calendar startDate, int days) throws Exception { Vector result = new Vector(); Connection conn = null; PreparedStatement ps = null; ResultSet rs = null; int i = 0; try { conn = ds.getConnection(); ps = conn.prepareStatement(db2Select); ps.setDate(1, new java.sql.Date(startDate.getTime().getTime())); Calendar futureDate = (Calendar)startDate.clone(); futureDate.add(Calendar.DAY_OF_MONTH,days); ps.setDate(2,new java.sql.Date(futureDate.getTime().getTime())); rs = ps.executeQuery(); Calendar correctDay = (Calendar)startDate.clone(); while(rs.next()) { Weather iWeather = new Weather(); Calendar theDBDate = Calendar.getInstance(); theDBDate.setTime(rs.getDate("WEATHERDATE")); //check if it is the correct date while(theDBDate.after(correctDay)) { // one day miss Weather missWeather = new Weather(); missWeather.setDate((Calendar)correctDay.clone()); WeatherPredictor.calculateWeatherValues(missWeather); result.add(missWeather); //increase the expected day correctDay.add(Calendar.DAY_OF_MONTH,1); } iWeather.setDate(theDBDate);

Chapter 14. Weather forecast application

241

iWeather.setCondition(rs.getString("CONDITION")); iWeather.setTemperatureCelsius(rs.getInt("TEMPERATURE")); iWeather.setWindDirection(rs.getString("WINDDIR")); iWeather.setWindSpeed(rs.getInt("WINDSPEED")); iWeather.setDbflag(true); result.add(iWeather); //increase the expected day correctDay.add(Calendar.DAY_OF_MONTH,1); } //check if there are still remaining days while(result.size() < days+1) { //one day miss Weather missWeather = new Weather(); missWeather.setDate((Calendar)correctDay.clone()); WeatherPredictor.calculateWeatherValues(missWeather); result.add(missWeather); //increase the expected day correctDay.add(Calendar.DAY_OF_MONTH,1); } } catch(Exception e) { throw (e); } finally { try { if (rs != null) rs.close(); if (ps != null) ps.close(); if (conn != null) conn.close(); } catch (Exception e) { } } Weather[] arrayWeather = new Weather[result.size()]; Vector dbWeather = new Vector(); for (int j = 0; j < arrayWeather.length; j++) { arrayWeather[j] = (Weather)result.get(j); if(!arrayWeather[j].isDbflag()) dbWeather.add(arrayWeather[j]); } //load the database with the new predictions Weather[] arraydbWeather = new Weather[dbWeather.size()]; for (int k = 0; k < arraydbWeather.length; k++) arraydbWeather[k] = (Weather)dbWeather.get(k); if (arraydbWeather.length > 0) setWeather(arraydbWeather); return arrayWeather; } }

242

WebSphere Version 5.1 Web Services Handbook

Weather forecast session EJB The WeatherForecastEJB implementation class is shown in Example 14-3. Note: We provide two identical session EJBs:
WeatherForecastEJB—To create an HTTP-based Web service
WeatherForecastJMS—To create a JMS-based Web service Example 14-3 WeatherForecastEJBBean class package itso.session; import java.util.Calendar; import java.util.Vector; import itso.mapping.Weather; import itso.mapping.WeatherPredictor; import javax.naming.InitialContext; import javax.sql.DataSource; import java.sql.Connection; import java.sql.PreparedStatement; import java.sql.ResultSet; /** * Bean implementation class for Enterprise Bean: WeatherForecastEJB */ public class WeatherForecastEJBBean implements javax.ejb.SessionBean { private private private private

DataSource ds = null; String db2Select = null; String db2Insert = null; String db2Delete = null;

private javax.ejb.SessionContext mySessionCtx; /** * getSessionContext */ public javax.ejb.SessionContext getSessionContext() { return mySessionCtx; } /** * setSessionContext */ public void setSessionContext(javax.ejb.SessionContext ctx) { mySessionCtx = ctx; } /** * ejbCreate */

Chapter 14. Weather forecast application

243

public void ejbCreate() throws javax.ejb.CreateException { try { InitialContext envCtx = new InitialContext(); String dataSourceName = (String)envCtx.lookup("java:comp/env/dataSource"); ds = (DataSource)envCtx.lookup("java:comp/env/"+dataSourceName); db2Select = (String)envCtx.lookup("java:comp/env/getDB2Weather"); db2Insert = (String)envCtx.lookup("java:comp/env/setDB2Weather"); db2Delete = (String)envCtx.lookup("java:comp/env/removeDB2Weather"); } catch (Exception e) { System.out.println("WeatherForecastBean exception in ejbCreate: "); e.printStackTrace(); throw ( new javax.ejb.CreateException("Exception: "+e.getMessage()) ); } } /** * ejbActivate */ public void ejbActivate() { } /** * ejbPassivate */ public void ejbPassivate() { } /** * ejbRemove */ public void ejbRemove() { }

// the rest of the code is identical to the WeatherForecast JavaBean // ...... getDayForecast(......)

Weather predictor The WeatherPredictor class is shown in Example 14-4. Example 14-4 WeatherPredictor class package itso.mapping; import java.util.Calendar; import java.util.Random; /** * class WeatherPredictor * This class predicts several weather artifacts * for a given date on a daily or weekly base. * Random values are used for the simulation. */ public class WeatherPredictor {

244

WebSphere Version 5.1 Web Services Handbook

// possible conditions for weather in general and wind directions private static final String[] possibleConditions = new String[] { "sunny", "partly cloudy", "cloudy", "rainy", "stormy" }; private static final String[] possibleWinds = new String[] { "N", "NE", "E", "SE", "S", "SW", "W", "NW" }; // random number generator private static final Random random = new Random(System.currentTimeMillis()); /** * Method calculateWeatherValues. * This method takes a weather object and fills it with predicted values * @param w Weather object to fill with calculated values */ public static void calculateWeatherValues(Weather w) { w.setWindDirection(possibleWinds[random.nextInt(possibleWinds.length)]); w.setWindSpeed(random.nextInt(40) + 1); w.setTemperatureCelsius(random.nextInt(50) - 10); w.setCondition(possibleConditions[random.nextInt(possibleConditions.length)]); } }

Environment variables The weather forecast beans use a resource reference and environment variables to connect to the WEATHER database. Projects that contain the weather forecast beans must have a resource reference defined:
Name—ItsoWeatherDB
Type—javax.sql.DataSource
JNDI name—jdbc/sjweather A data source with the name jdbc/sjweather must be defined in the server. Table 14-1 lists the environment variables. Table 14-1 Environment variables Environment variable

Value

dataSource

ItsoWeatherDB

getDB2Weather

select * from itso.sanjose where weatherdate >= ? and weatherdate <= ?

setDB2Weather

insert into itso.sanjose (weatherdate, condition, temperature, winddir, windspeed) values (?,?,?,?,?)

removeDB2Weather

delete from itso.sanjose where weatherdate = ?

Chapter 14. Weather forecast application

245

Summary In this chapter we covered the weather forecast example base code that will be used to create a Web service using the different tools or products. We discussed the different components and how they interact to provide the weather forecast functionality. In the chapters that follow, we cover in detail the information required to create a Web service using the different tools and products and following the paths presented in this chapter:
Chapter 15, “WebSphere Studio Application Developer” on page 247, provides an implementation using Application Developer.
Chapter 16, “Web services security with Application Developer” on page 303, provides an implementation using WS-Security.
Chapter 17, “Application Developer Integration Edition” on page 341, provides an implementation using Application Developer Integration Edition.
Chapter 18, “WebSphere SDK for Web Services” on page 381, provides an implementation using the WebSphere SDK for Web Services.

246

WebSphere Version 5.1 Web Services Handbook

15

Chapter 15.

WebSphere Studio Application Developer This chapter describes the features of WebSphere Studio Application Developer Version 5.1 as they relate to Web services. If you are not familiar with the basic steps of how to create Web applications using Application Developer, refer to the redbooks WebSphere Studio Application Developer Version 5 Programming Guide, SG24-6957, (although this publication is about Version 5.0) and EJB 2.0 Development with WebSphere Studio Application Developer, SG24-6819. This chapter covers the following topics:
Overview of Web services-related features in WebSphere Studio Application Developer, including strategies for developing a new Web service
Creating a Web service in a bottom-up way, using HTTP and JMS protocols
Creating a Web service in a top-down fashion
Exploring and publishing to a UDDI directory from WebSphere Studio Application Developer

© Copyright IBM Corp. 2003, 2004. All rights reserved.

247

Overview WebSphere Studio Application Developer provides a toolbox for discovering, creating, and publishing Web services that are created from JavaBeans, DADX files, Enterprise JavaBeans, and URLs. You can also use Web service tools to create a skeleton JavaBean and a sample application from a WSDL document. The development path that you would typically follow to create and publish a Web service is as follows:






Create router projects. Create or import an artifact to be turned into a Web service. Create a Web service. Create a proxy and a test client. Publish a business entity and a Web service.

Web tools assist you in developing Web applications that you can configure as a Web service. Web applications are developed in a Web project, and server tools enable you to use the unit test environment to test and deploy your Web services.

Strategies for developing a Web service As pointed out in Chapter 13, “Web services development overview” on page 221, there are several different ways to develop Web services:
There is the distinction between a bottom-up and a top-down development of Web services, which addresses development issues for the provider part.
Furthermore, there is a question about which application and data structure the Web service is generated from.
Finally, on the requestor side, the invocation can be implemented either statically or dynamically.

Tool support by WebSphere Studio Application Developer Application Developer supports a wide range of the above options.

Bottom-up For bottom-up development (the most common case), the following data structures can be used to build a Web service:
JavaBean—The Web service wizard assists you in creating a new Web service, configuring it for deployment, and deploying the Web service to a server (which can be the test environment that comes with Application Developer, or an external application server).

248

WebSphere Version 5.1 Web Services Handbook


EJB—The Web service wizard assists you in creating a new Web service, configuring it for deployment, and deploying the Web service to a server. With Application Developer 5.1, SOAP/JMS support has been added for EJBs.
DADX—Document access definition extension (DADX) is an XML document format that specifies how to create a Web service using a set of operations that are defined by DAD documents and SQL statements. A DADX Web service enables you to wrap DB2 XML Extender or regular SQL statements inside a standard Web service. The DADX file defines the operations available to the DADX runtime environment, and the input and output parameters for the SQL operation.
URL—The Web service wizard assists you in creating a new Web service that directly accesses a servlet running on a remote server.
ISD—An ISD file is a Web service deployment descriptor and provides information to the SOAP runtime about the service that should be made available to clients, for example, URI, methods, implementation classes (JavaBean, EJB), serializers, and deserializers. ISD files are concatenated into the SOAP deployment descriptor, dds.xml.

Top-down For top-down development, Application Developer provides these functions:
JavaBean from WSDL—The Web service wizard assists you in creating a skeleton JavaBean from an existing WSDL document. The skeleton bean contains a set of methods that correspond to the operations described in the WSDL document. When the bean is created, each method has a trivial implementation that you replace by editing the bean.
JavaBean from XSD—The Web services tools support the generation of JavaBeans from an XML schema. Using these beans, you can create a JavaBean Web service.

Client development To assist in the development of Web service clients, Application Developer provides this function:
Java client proxy and sample application from WSDL—The Web service client wizard assists you in generating a proxy JavaBean and a sample application. The sample Web application demonstrates how to use the proxy bean in a client program. Note that the proxy and sample application can also be generated in bottom-up and top-down approaches for testing of the generated Web service.

Chapter 15. WebSphere Studio Application Developer

249

In summary, the tool offers many opportunities to create Web services from bottom-up (starting from server-side code to generating the WSDL document and the proxy code), but only limited opportunities to generate a service from top-down (creating a JavaBean skeleton from a Web service description). In particular, with the standard edition of Application Developer, an EJB cannot be created from a WSDL document; however, this can be achieved with the Integration Edition (see Chapter 17, “Application Developer Integration Edition” on page 341). On the client side, the invocation can be implemented in a static or dynamic way. Both options can be implemented using Application Developer. Furthermore, we show how Application Developer supports the developer in testing and accessing a UDDI registry.

Selected scenarios In the sections that follow we focus on the following scenarios:
Bottom-up development by generating a Web service from a JavaBean using HTTP as the transport for the SOAP messages
Bottom-up development by generating a Web service from a session EJB using HTTP as the transport for the SOAP messages
Bottom-up development by generating a Web service from an EJB using JMS as the transport for SOAP messages
Top-down development by generating a JavaBean from an existing WSDL
Implementing interoperable Web services (WS-I convention)
Bottom-up generation of a Web service from a URL
Bottom-up Web service generation from DADX
Publishing of Web services into a UDDI registry In these scenarios we do not focus on a dynamic invocation; this will be covered in Chapter 19, “Web services scenario: Architecture and implementation” on page 429. For other types of Web service generation, refer to the online documentation of Application Developer.

250

WebSphere Version 5.1 Web Services Handbook

Preparing the enterprise applications To make it very clear which projects belong together for a Web service solution we use different enterprise applications for each Web service generation:
ItsoWebService1—Contains one Web project, ItsoWebService1Web, with a JavaBean, WeatherForecast. A Web service is generated from the JavaBean, which also generates a client project.
ItsoWebService2—Contains one EJB project, ItsoWebService2EJB, with a session bean, WeatherForecastEJB. A Web service is generated from the session bean, which also generates a Web router project and a client project.
ItsoWebService3—Contains one EJB project, ItsoWebService3EJB, with a session bean, WeatherForecastJMS. A JMS-based Web service is generated from the session bean, which requires an EJB router project, and which generates a client project.

Installing the weather forecast application The Web services examples are based on the weather forecast application, which was discussed in Chapter 14, “Weather forecast application” on page 233. Although a thorough understanding of this application will be helpful in moving forward, it is certainly not a requirement. Important: To get started quickly, install the sample code available with this book. Follow the instructions in “Installing the weather forecast application” on page 528. You have to complete these steps:
“Set up the WEATHER database” on page 528
“Set up the WebSphere test server (WeatherServer)” on page 529
“Set up the initial applications for Web services development” on page 537
Optionally: “Test the starting application” on page 537 After installing the application, open the J2EE perspective, and in the J2EE Hierarchy view, verify that your workspace looks like Figure 15-1.

Chapter 15. WebSphere Studio Application Developer

251

Enterprise applications

JavaBean Web service (HTTP) Session EJB Web service (HTTP) Session EJB Web service (JMS) Server for testing

Figure 15-1 Weather forecast sample imported into the workspace

We will create three Web services:
JavaBean Web service from the itso.bean.WeatherForecast class in the ItsoWebService1Web project
EJB Web service from the itso.session.WeatherForecastEJB session bean in the ItsoWebService2EJB project
EJB Web service from the itso.jms.WeatherForecastJMS session bean in the ItsoWebService3EJB project (JMS-based Web service) If you want to examine the source code, navigate to the classes as seen in Figure 15-2.

EJB JavaBean EJB

Figure 15-2 Navigating to the source code

252

WebSphere Version 5.1 Web Services Handbook

Creating a Web service from a JavaBean In this section we create a Web service from an existing JavaBean, the WeatherForecast bean introduced in Chapter 14, “Weather forecast application” on page 233. We describe how to use WebSphere Studio wizard to create a Web service that returns information from the weather forecast service. The wizard guides us through generating the WSDL document from the JavaBean, creating a proxy bean, and testing the Web service in a Web browser using the Web Services Explorer, the generated test JSPs, the universal test client, and the built-in WebSphere test environment. Out first approach is to create a Web service from a JavaBean in a bottom-up way. We use the ItsoWebService1 enterprise application. To create the Web service, including the WSDL document, deployment descriptor, proxy, and test sample, we use the Web Service wizard. The Web service proxy and test client is created in a separate Web project. This client project can be created in advance, or quickly by the wizard. In this first example we create the client project in advance.

Create a Web project for the test client Here are the steps to create a Web project for the client code:
Select File -> New -> Other. Select Web in the left pane and Dynamic Web Project in the right pane, and click Next.
Enter ItsoWebService1WebClient as the project name. In the bottom left corner select Configure advanced options. Click Next.
From the EAR project drop-down menu, select ItsoWebService1. Click Finish.
Click Yes when prompted to repair the server configuration.

Web Service wizard Select the WeatherForecast class in the ItsoWebService1Web project and File -> New -> Other. Select Web Services to display the various Web service wizards. Select Web Service and click Next to start the Web Service wizard. We go through all the pages of the wizard. Click Next on each page to get to the next page.

Chapter 15. WebSphere Studio Application Developer

253

In the Web service type drop-down menu, Java bean Web service is preselected. Ensure that the following boxes are selected:







Start Web service in Web project Test the Web service Generate a proxy Test the generated proxy Overwrite files without warning (needed in case you rerun the wizard) Create folders when necessary

From the Client proxy type drop-down menu, ensure that Java proxy is selected. Figure 15-3 shows the window after making these selections.

Figure 15-3 Web Service wizard: Initial

Service Deployment Configuration The Service Deployment Configuration page allows you to specify the server and the project names. Make sure that the WeatherServer is selected as the Server, ItsoWebService1Web as the Service Web Project, and ItsoWebService1WebClient as Client Web Project.

Web Service Java Bean Selection The Web Service Java Bean Selection page allows you to specify the Java bean to be turned into a Web service. The itso.bean.WeatherForecast bean should be

254

WebSphere Version 5.1 Web Services Handbook

preselected; if not, click Browse classes and locate the class from the JavaSource folder and click OK.

Web Service Java Bean Identity In the Web Service Java Bean Identity page, the three main items are the WSDL file name, methods to be exposed in the Web service, and the SOAP format of the Web service. This is illustrated in Figure 15-4.

Figure 15-4 Web Service wizard: Java Bean Identity options

We now briefly describe these options before we continue:
Web service URI—Specifies the target URL that a Web service client will use to access the Web service.
WSDL Folder—The WSDL file is written into this folder. This folder is relative to the workspace.
WSDL File—Here we can specify a WSDL file name of our choice. The default file name should work fine for most applications.
Methods—A listing of public methods in the Java bean that are available to be exposed to the Web service. Select the methods that you want to expose. For our application, we select all the get methods of the WeatherForecast bean. We will use the setWeather method later in a JMS-based Web service. JMS-based Web services are discussed in “Web services and JMS protocol” on page 274.

Chapter 15. WebSphere Studio Application Developer

255


Style and Use—The SOAP format to be expected by the Web service. In our example, we will use the Document/Literal format. Attention: If you are creating an RPC/Encoded Web service, you are presented with a warning (Figure 15-5) indicating non-compliance with WS-I. We are creating a Document/Literal Web service here so you will not see this message. If your client and server are both WebSphere based, the WS-I warning is unlikely to be an issue. When presented with this warning, click Ignore and continue with creating the Web service.

Figure 15-5 WS-I compliance warning

Web Service Test Page This page allows you test a Web service using the Web Services Explorer. The Web Services Explorer is a new Web-based tool introduced with Application Developer 5.1. The tool uses the WSDL file to dynamically test the Web service. The Web Services Explorer can also be invoked manually after the Web service has been created. We will discuss the Web Services Explorer in “Web Services Explorer” on page 296. We skip this step for now. Note: in Application Developer 5.1.1 the Web Service Explorer is started even if you do not click Launch.

Web Service Proxy Page On this page, select options as shown in Figure 15-6.
Generate proxy—This creates JSR 101-compliant proxy classes for the Web service. Web service clients can then be written based on the proxy classes.
Output folder—The location of the proxy classes (in the client project). Accept the Security Configuration as No Security, and do not select Define custom mapping for namespace to package.

256

WebSphere Version 5.1 Web Services Handbook

Figure 15-6 Web Service wizard: Proxy page

Web Service Client Test The wizard offers to create a test client for you. This test client is JSP based and uses the proxy classes that were created in the previous step. We want to test all the methods exposed in the Web service, so select all the methods available in the Web service. Select the remaining options as shown in Figure 15-7. By selecting Run test on server, we launch these JSPs.

Figure 15-7 Web Service wizard: Test client

Chapter 15. WebSphere Studio Application Developer

257

Note: The first and last three method selections are new in Application Developer 5.1.1. The useJNDI method enables the test client to use or not to use JDNI to retrieve the service factory (JSR 109). Click Finish. The Web service is installed in the ItsoWebService1Web project (server-side project) and the proxy and sample test client are generated into the ItsoWebService1WebClient project (client-side project). The WeatherServer is started (be patient). A Web browser window with the test client is displayed (Figure 15-8). You can now test your newly created Web service using the three methods from the left frame. We will discuss the test JSPs and the procedure for invoking the tests in detail in “Test using generated JSPs” on page 262.

Figure 15-8 Testing the Web service using the test client

Note: In case the test JSPs do not work and return an error, restart the WeatherServer and rerun the JSPs.

258

WebSphere Version 5.1 Web Services Handbook

Generated files Let us take a moment to look at the generated files (Figure 15-9).

JavaBean SEI Data mapping files Proxy files (JSR 101)

Test JSPs WSDL

Deployment descriptor (JSR 109), bindings and extensions

Server Project

Client Project

Figure 15-9 Project Navigator view after the generation of the Web service

Files generated in the server-side Web project According to the settings made during the run of the wizard, the following files in the ItsoWebService1Web project have been created:
Service endpoint interface (SEI): itso.bean.WeatherForecast_SEI.java is the interface defining the methods of the Web service.
WSDL file: /WebContent/WEB-INF/wsdl/WeatherForecast.wsdl describes the Web service to the clients. A copy is also in the WebContent folder.
Deployment descriptor: webservices.xml, ibm-webservices-ext.xml, and ibm-webservices-bnd.xml. These files describe the Web service according to

Chapter 15. WebSphere Studio Application Developer

259

the Web services for J2EE style (JSR 109). The mapping is described in the WeatherForecast_mapping.xml file.
Data mapping files: The files in the itso.mapping package perform the data conversion from XML to Java and back.

Files generated in the client-side Web project If the creation of a client-side proxy is selected, two packages are generated in the ItsoWebService1ClientWeb project:
itso.mapping contains the Java -> XML and XML -> Java data mapping logic.
itso.bean contains the proxy classes. These classes are used by the client to make remote calls as per JSR 101. See “Proxy classes” on page 263 for a detailed description. With the help of these classes, the client can instantiate local representations of the remote classes (see “Writing Web service clients” on page 264). The generated test JSPs also use these proxy classes.
Test client: JSPs to test each method exposed as a Web service. The test client is generated in the WebContent/sample/WeatherForecastProxy folder.
Deployment descriptor: webservicesclient.xml and extension. These files describe the Web service in the client according to the Web services for J2EE style (JSR 109). The mapping file is also there.
A copy of the WSDL file (in WEB-INF\wsdl).

Testing the Web service We present two ways of testing the Web service and its generated proxy:
Test using the Web Services Explorer.
Test using generated JSPs. To test the Web service, you must have a Web service-enabled weather forecast application as generated in the previous step.

Web Services Explorer Application Developer 5.1 introduces the Web Services Explorer tool, which allows testing of a Web service. Ensure that the WeatherServer is running. Here are instructions for using the Explorer.
Navigate to the WSDL file of the Web service. For the weather application, this file is WeatherForecast.wsdl, as shown in Figure 15-9.
Select the WSDL file and Web Services -> Test with Web Services Explorer (context). This launches the tool (Figure 15-10).

260

WebSphere Version 5.1 Web Services Handbook

Figure 15-10 Web Services Explorer: Browser page


In the top right frame select the Web services method you want to test, for example, getForecast. Sample input values as shown in Figure 15-11.

Figure 15-11 Web Services Explorer: Testing a Web service method

Tip: Click Browse to open a calendar. Click any day and a suitable value is inserted into the parameter prompt.

Chapter 15. WebSphere Studio Application Developer

261


Click Go.
The result can be seen in the Status window (bottom right frame). Some results cannot be formatted and you have to select the Source link to view the SOAP request and response (Figure 15-12).

Note that this is a result of the getTemperatures method.

Figure 15-12 Web Services Explorer: SOAP message results

Test using generated JSPs Selecting Test the generated proxy in the Web services wizard (Figure 15-7) creates a JSP-based test client. To run the test, select the TestClient.jsp in the ItsoWebServiceTestClientWeb project (WebContent/sample/WeatherForecast) and Run on Server. The JSP opens in a browser pane with this URL: http://localhost:9080/ItsoWebService1WebClient/sample/WeatherForecastProxy /TestClient.jsp


If prompted to select a server, select the WeatherServer and select Set server as project default, then click Finish.
To examine the Web service application, select any of the three Web service methods, enter a date, and click Invoke. Figure 15-13 displays the results of the invocation of the getTemperatures method.

262

WebSphere Version 5.1 Web Services Handbook

Figure 15-13 Sample test client result

Note that the getForecast method returns an array of Weather objects. These are displayed as object references: [itso.mapping.Weather@2e50731b, itso.mapping.Weather@c438e01b, itso.mapping.Weather@fff01a6d, itso.mapping.Weather@2e506992, itso.mapping.Weather@fff02491]

To get a nicer result you could copy the toString method from the original Weather class (in ItsoWebService1Web) to the generated Weather class in the ItsoWebService1WebClient project.

Proxy classes The generated proxy classes include:
WeatherForecast—Service endpoint interface.
WeatherForecastSoapBindingStub—SOAP proxy class that implements the service endpoint interface and communicates with the SOAP runtime.
WeatherForecastService—Service interface.
WeatherForecastServiceLocator—Service locator class that implements the service interface and provides methods to acquire the service endpoint interface. This class also contains the service address: http://localhost:9080/ItsoWebService1Web/services/WeatherForecast

Chapter 15. WebSphere Studio Application Developer

263


WeatherForecastProxy—Simple proxy class for the client. This proxy class uses either JSR 101 (instantiate the WeatherForecastServiceLocator) or JSR 109 (use JNDI to find the WeatherForecastServiceLocator) to get the service endpoint interface. The useJNDI(boolean) method is provided to switch between JSR 101 and JSR 109 clients (JSR 109 is the default). The proxy also provides the Web service methods (getDayForecast, getForecast, getTemperatures) for easy invocation by a client. Note: The simple proxy class is new in Application Developer 5.1.1. A Web service client can use the service locator directly or the simple proxy class, as illustrated here: // Client using JSR 101 WeatherForecastServiceLocator loc = new WeatherForecastServiceLocator(); WeatherForecast proxy = loc.getWeatherForecast(); Weather w = proxy.getDayForecast(...date...); <=== invoke Web service // Client using JSR 109 InitialContext ctx = new InitialContext(); WeatherForecastServiceLocator loc = (WeatherForecastServiceLocator) ctx.lookup("java:comp/env/service/WeatherForecastService"); WeatherForecast proxy = loc.getWeatherForecast(); Weather w = proxy.getDayForecast(...date...); <=== invoke Web service // Client using simple proxy WeatherForecastProxy proxy = new WeatherForecastProxy(); Weather w = proxy.getDayForecast(...date...); <=== invoke Web service

Writing Web service clients In this section we develop two small Web service clients that invoke the methods of the Web service using the generated proxy classes:
Stand-alone Java client
Web client servlet

Stand-alone Java client The stand-alone Java client is a Java main program. To incorporate client code you have to create or use a suitable project in which you develop the client code; we use a new ItsoWebService1JavaClient project (Java project). The client code is shown in Example 15-1 and is available in the sample code: sg246891-01\sampcode\wsad51\JavaClient\WebServiceTestClientMain.java

264

WebSphere Version 5.1 Web Services Handbook

Example 15-1 Web service Java client package itso.client; import java.util.*; import itso.bean.*; import itso.mapping.*; public class WebServiceTestClientMain { public static void main(String[] args) { System.out.println( "** RUNNING THE STANDALONE JAVA CLIENT OF WEATHERFORECAST WEB SERVICE **\n"); try { // Instantiate the WeatherForecast object WeatherForecastServiceLocator wfsl = new WeatherForecastServiceLocator(); WeatherForecast wf = (WeatherForecast) wfsl.getWeatherForecast(); // Call each method one by one System.out.println("1. Testing getDayForecast() method ..."); Weather retGetDF = wf.getDayForecast(Calendar.getInstance()); System.out.println(retGetDF.getCondition().toString()); System.out.println( retGetDF.getDate().getTime().toString() + "\t" + "Temperature = " + retGetDF.getTemperatureCelsius() + "\t" + "WindDirection = " + retGetDF.getWindDirection().toString() + "\t" + "getWindSpeed = " + retGetDF.getWindSpeed() + "\t" + "Condition = " + retGetDF.getCondition().toString()); System.out.println("getDayForecast() test successful\n"); System.out.println("2. Testing getForecast() method ..."); int numDays = 2; Weather retGF[] = wf.getForecast(Calendar.getInstance(), numDays); for (int loopCount = 0; loopCount <= numDays; loopCount++) { System.out.println( retGF[loopCount].getDate().getTime().toString() + "\t" + "Temperature = " + retGF[loopCount].getTemperatureCelsius() + "\t" + "WindDirection = " + retGF[loopCount].getWindDirection().toString() + "\t" + "getWindSpeed = "

Chapter 15. WebSphere Studio Application Developer

265

+ + + +

retGF[loopCount].getWindSpeed() "\t" "Condition = " retGF[loopCount].getCondition().toString());

} System.out.println("getForecast() test successful\n"); System.out.println("3. Testing getTemperatures() method ..."); int retGT[] = wf.getTemperatures(Calendar.getInstance(), numDays); for (int loopCount = 0; loopCount <= numDays; loopCount++) { System.out.print("Temperature = " + retGT[loopCount] + ", "); } System.out.println("\ngetTemperatures() test successful\n"); } catch (Exception e) { System.out.println( "Request failed. For more information see the stack trace"); e.printStackTrace(); } } }

Running the client To run this client perform these steps:
Locate the WebServiceTestClientMain.java file in the sample code: sg246891-01\sampcode\wsad51\JavaClient\


Create a Java project named ItsoWebService1JavaClient. Create a package named itso.client.
Select the new package and Import (context). Select File system, click Next, and import the WebServiceTestClientMain client program. Many errors are reported in the Tasks view.
Copy the proxy (itso.bean) and mapping (itso.mapping) packages from the ItsoWebService1WebClient project to the ItsoWebService1JavaClient project.
Set up the classpath with the required libraries: – Select the ItsoWebServiceClientJava project and Properties (context). – Select Java Build Path and go to the Libraries tab (Figure 15-14). – Click Add Variable, locate WAS_50_PLUGINDIR, and click Extend. Expand the lib folder and select the j2ee.jar file. Click OK. – Repeat this and add the qname.jar, webservices.jar, and wsdl4j.jar files. – Click OK to close the properties window; the errors should disappear.

266

WebSphere Version 5.1 Web Services Handbook

Figure 15-14 Setting the Java Build Path


Make sure the WeatherServer is started.
In the Java perspective, select the WebServiceTestClientMain and Run -> Run As -> Java Application and enjoy the result in the Console view (select the correct Console output by using the drop-down menu): ** RUNNING THE STANDALONE JAVA CLIENT OF WEATHERFORECAST WEB SERVICE ** 1. Testing getDayForecast() method ... Wed Nov 19 00:00:00 PST 2003Temperature = 17WindDirection = SEgetWindSpeed = 17 Condition = partly cloudy getDayForecast() test successful 2. Testing getForecast() method ... Wed Nov 19 00:00:00 PST 2003Temperature = 17WindDirection = SEgetWindSpeed = 17 Condition = partly cloudy Thu Nov 20 00:00:00 PST 2003Temperature = 21WindDirection = NWgetWindSpeed = 22 Condition = partly cloudy Fri Nov 21 00:00:00 PST 2003Temperature = 22WindDirection = SEgetWindSpeed = 32 Condition = stormy getForecast() test successful 3. Testing getTemperatures() method ... Temperature = 17, Temperature = 21, Temperature = 22, getTemperatures() test successful

See “Accessing a Web service from a stand-alone Java client” on page 500 for how to run this client outside of Application Developer.

Chapter 15. WebSphere Studio Application Developer

267

Web client The Web client is a simple servlet that uses the proxy classes to invoke one of the Web service methods. We develop this client in the existing client project (ItsoWebService1WebClient). The code is available in: sg246891-01\sampcode\wsad51\WebClient\WeatherClient.java

To install and run the servlet:
Create an itso.servlet package in the ItsoWebService1WebClient project.
Import the WeatherClient file into the new package. Here is an extract of the servlet code: WeatherForecastServiceLocator wfsl = new WeatherForecastServiceLocator(); WeatherForecast wf = (WeatherForecast) wfsl.getWeatherForecast(); Weather[] wa = wf.getForecast(Calendar.getInstance(), 3); out.println("

Weather Results

"); out.println("..."); for (int i=0; i"); out.println("

Date	Condition	Temperature
"+sdf.format( wa[i].getDate().getTime() ) +"	"+wa[i].getCondition() + ... +"

");


Open the deployment descriptor of the Web project. On the Servlets page add the WeatherClient servlet. Also set the URL mapping to /WeatherClient.
Select the WeatherServer and Restart Project -> ItsoWebService1 (context).
Select the WeatherClient servlet and Run on Server. The output is displayed in an HTML table (Figure 15-15).

Figure 15-15 Web service client servlet output

268

WebSphere Version 5.1 Web Services Handbook

Tracing SOAP messages In this section we describe how you can watch the SOAP messages that are received and sent by the WebSphere server. Application Developer provides a TCP/IP Monitoring Server that can be used to watch the HTTP traffic, that is, the messages that are received by the server and the responses that are sent back.

Using the TCP/IP Monitoring server The TCP/IP Monitor intercepts the messages at a given port (9081 by default) and then forwards the messages to the server (port 9080 by default). This is a very practical way to study the SOAP messages that are received by the server and the responses that are sent back to the client.

Define the server First we have to define the server. Select File -> New -> Server and Server Configuration, enter WeatherMonitor as the name, select Other -> TCP/IP Monitoring Server as the server type, and click Finish.

Change the endpoint port number To intercept the SOAP messages, we change the proxy to send the requests to port 9081 (instead of 9080). Edit the WeatherForecastServiceLocator class in the client project (ItsoWebService1WebClient), and change the target URL to point to port 9081: private final java.lang.String weatherForecast_address = "http://localhost:9081/ItsoWebService1Web/services/WeatherForecast";

Note: After running this sample, change the port number back to 9080.

Start the servers Start the WeatherMonitor and the WeatherServer.

Run a client Run any of the clients, for example, the sample test client. When you select Run on Server you are prompted to select to run the browser with or without the TCP/IP Monitor. Note that this affects only the HTTP traffic from HTML pages and JSPs; the SOAP traffic from the proxy is already routed to port 9081. If we only want to watch the SOAP traffic, we can select the normal Web browser.

Chapter 15. WebSphere Studio Application Developer

269

TCP/IP Monitor view The output of the TCP/IP Monitor is displayed in the TCP/IP Monitor view (Figure 15-16).

Figure 15-16 TCP/IP Monitor output

For each request you can see the input message in the left pane and the output message in the right pane. You need to scroll to the right to view the entire SOAP message (or copy/paste the message into an editor). The SOAP input message for the getDayForecast operation is: 2003-11-26T08:00:00.000Z

In the SOAP response from the Web service, you can see that a Weather object is returned with all its attributes listed in XML tags:

270

WebSphere Version 5.1 Web Services Handbook

rainy 2003-11-26T08:00:00.000Z NW 10 17 1

The SOAP response message for getWeekForecast is an array of seven Weather objects, and the response for getWeekTemperatures is an array of seven integers.

Target URL Do not forget to reset the target URL in the WeatherForecastServiceLocator class back to port 9080. Note that you can also change the target URL dynamically by invoking the setEndpoint method of the proxy object. The test JSPs provide a link to execute the method. This eliminates the change in the source code. The easiest way is to invoke the getEndpoint method and copy the result. Then select the setEndpoint method, paste the copied URL, and change the port to 9081 before invoking the method.

Creating a Web service from a session bean We provide a session bean, WeatherForecastEJB, that has the same methods as the WeatherForecast JavaBean. In this section we create a Web service from the session bean. We use the ItsoWebService2 enterprise application.

Running the Web Service wizard This process is very similar to what we did with the JavaBean, so the instructions are shorter. Note that we create a router Web project in advance, and a client project while running the wizard:
Stop the WeatherServer if it is running.
Create a new Web project named ItsoWebService2RouterWeb in the ItsoWebService2 EAR project. The router project is used to route a Web

Chapter 15. WebSphere Studio Application Developer

271

service call to the session EJB. Such a project should not be used for anything else.
In the J2EE Hierarchy view for the ItsoWebService2EJB project, select the WeatherForecastEJB session bean and New -> Other -> Web Services -> Web Service. Click Next.
The Web service type is preselected (EJB Web service). Select Start Web service in Web project, Generate a proxy, Test the generated proxy, Overwrite files without warning, and Create folders when necessary.
For the Router project enter ItsoWebService2RouterWeb, and for the Client Web project enter ItsoWebService2EJBClient. This Web client project is created by the wizard.
The EJB is preselected and all defaults are fine (SOAP over HTTP is the only option).
Deselect the setWeather method, and leave the other three methods selected. Select Document/Literal.
Select Generate proxy (preselected).
Select Test the generated proxy, and click Finish. The code is generated and the WeatherServer is started. You can test the Web service using the generated test client.

Generated code In the ItsoWebService2EJB project you will find:





Service endpoint interface: itso.session.WeatherForecastEJB_SEI Mapping classes in itso.mapping WSDL file in META-INF/wsdl: WeatherForecastEJB.wsdl Web service deployment descriptor: webservices.xml in META-INF

In the ItsoWebService2RouterWeb project you will find:
Router servlet named WeatherForecastEJB, pointing to com.ibm.ws.webservices.engine.transport.http.WebServicesServlet, with a URL named services/WeatherForecastEJB
WSDL file in WebContent/wsdl In the ItsoWebService2EJBClient project you will find:





272

Proxy and mapping classes (itso.session and itso.mapping) Sample test client in WebContent/sample/WeatherForecastEJBProxy WSDL file in WebContent/WEB-INF/wsdl Web service deployment descriptor: webservicesclient.xml in WEB-INF

WebSphere Version 5.1 Web Services Handbook

Testing the EJB Web service We have a number of choices to test the EJB Web service.

Web Services Explorer You can run the Web Services Explorer from the WeatherForecastEJB.wsdl file (see “Web Services Explorer” on page 260). You can use the generated test client by running the TestClient.jsp in ItsoWebService2EJBClient/WebContent/sample/WeatherForecastEJBProxy.

Universal test client You can also use the universal test client to test a Web service:
Select the WeatherForecastEJBServiceLocator class in the client project and Web Services -> Launch Universal Test Client.
Expand the WeatherForecastEJBServiceLocator and invoke the getWeatherForecastEJB() method. Click on Work with Object and the result object, WeatherForecastEJBSoapBindingStub, is added to the object references.
Expand the WeatherForecastEJBSoapBindingStub object and run the Web service methods.
Alternatively, you can select the WeatherForecastEJBProxy class in the client project and Web Services -> Launch Universal Test Client. Expand the class and run the Web service methods.

Client servlet Create a servlet, WeatherClientEJB, in the ItsoWebService2EJBClient project. The code is the same as the WeatherClient in the ItsoWebService1WebClient project, but using the WeatherForecastEJBServiceLocator class: // Instantiate the WeatherForecast object WeatherForecastEJBServiceLocator wfsl = new WeatherForecastEJBServiceLocator(); WeatherForecastEJB wf = (WeatherForecastEJB) wfsl.getWeatherForecastEJB(); Weather[] wa = wf.getForecast(Calendar.getInstance(), 3); ......

The servlet is provided in sg246891-01\sampcode\wsad51\EJBClient and must be imported into an itso.servlet package and added to the deployment descriptor.

Chapter 15. WebSphere Studio Application Developer

273

Web services and JMS protocol Starting with Application Developer 5.1, we can develop Web services that use SOAP/JMS as the transport mechanism. Prior to this release, we could develop Web services based only on SOAP/HTTP.

SOAP over JMS example JMS-based Web services cannot return any result to the caller. We will use the setWeather method of the session EJB to create a SOAP over JMS Web service. Here are the main steps of how a JMS service is developed:
Configure the JMS server with JMS resources (QueueConnectionFactory, Queue, ListenerPort).
Create a JMS-based Web service.
Create a client to test the Web service. You can also create the Web service first and then configure the server for testing.

Configuring the JMS Server To run a JMS-based Web service the WeatherServer must be configured with a JMS Server. Follow the instructions in “Configure the JMS server” on page 534. Make sure the WeatherServer is stopped before continuing.

Projects for the Web service and sample client When creating a JMS-based Web service, an EJB router project is required. In this project a message-driven bean (MDB) is created. The MDB reads JMS messages from the queue and invokes the Web service. We will use a project named ItsoWebService3EJBRouter to house the MDB. To test the JMS-based Web service we use a new client Web project named ItsoWebService3EJBClient. The router EJB project must be defined in advance under the enterprise application, whereas client Web projects can be created dynamically when running the Web Service wizard. Create a new EJB project named ItsoWebService3EJBRouter under the ItsoWebService3 enterprise application (select File -> New -> EJB Project).

274

WebSphere Version 5.1 Web Services Handbook

Create the SOAP over JMS Web service We will create a Web service from of the WeatherForecastJMS session EJB. The setWeather method of this EJB will be exposed as a Web service:
In the J2EE Hierarchy view for the ItsoWebService3EJB project, select the WeatherForecastJMS session bean and New -> Other -> Web Services -> Web Service. Click Next.
We only create the Web service. We will start the Web service and create a client later (Figure 15-17). Click Next.

Figure 15-17 Create a JMS Web service


On the Service Deployment Configuration page, select ItsoWebService3EJB for the EJB Project and ItsoWebService3EJBRouter for the Router Project. Click Next.
On the Web Service EJB Selection pane, specify the values as shown in Figure 15-18 and click Next. Everything is prefilled, except for the port component value Weather.

Chapter 15. WebSphere Studio Application Developer

275

Figure 15-18 Specify the JMS settings of the Web service

On the Web Service Java Bean identity page, deselect all the get methods and select only the setWeather method. Select RPC/Encoded as the SOAP format. When prompted with the warning, as in Figure 15-19, click Ignore.

Figure 15-19 Warning issued when creating a JMS Web service

276

WebSphere Version 5.1 Web Services Handbook

At this point we are ready to generate the Web service. Click Finish. In the next section we will now create a test client to test this SOAP/JMS Web service.

Creating a Web service client In the previous examples we had a test client generated. This time we create the proxy classes from a WSDL file, and then we create a real client.

Create the Java proxy classes The client that we create later uses these proxy files to connect with the Web service. To create the proxy files, follow these steps:
Create a new Web project named ItsoWebService3EJBClient in the ItsoWebService3 enterprise application.
Select the WeatherForecastJMS.wsdl file (in the ItsoWebService3EJB project under META-INF) and Web Services -> Generate Client.
Select Java proxy and click Next. (Do not select Test the generated proxy.)
For the Client Web Project select ItsoWebService3EJBClient and click Next.
The WSDL file is preselected, so click Next.
Click Finish to generate the proxy classes.
If you look in the Tasks view, you will see several warnings. The warnings are Web services interoperability items that we can ignore for the purpose of this sample application. If you see an error, select the ItsoWebService3EJBClient project and Project -> Rebuild Project.

Create the test servlet We now create a test client in the form of a servlet that invokes the JMS Web service:
In the ItsoWebService3EJBClient project create an itso.servlet package.
In the new package create a servlet named JmsSetWeatherServlet.
Replace the servlet code with the sample code in Figure 15-20, which is available in sg246891-01\sampcode\wsad51\JMSClient.

Chapter 15. WebSphere Studio Application Developer

277

package itso.servlet; import import import import

itso.jms.WeatherForecastJMS; itso.jms.WeatherForecastJMSServiceLocator; itso.mapping.Weather; ...;

public class JmsSetWeatherServlet extends HttpServlet implements Servlet { public void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { PrintWriter out = resp.getWriter(); out.println("

JMS Set Weather Servlet

"); out.println("

Calling the JMS Web service ...

"); try { // Get the initial context and the local representation of the Web Service InitialContext ic = new InitialContext(); WeatherForecastJMSServiceLocator wfsl = (WeatherForecastJMSServiceLocator) ic.lookup( "java:comp/env/service/WeatherForecastJMSService"); WeatherForecastJMS wf = (WeatherForecastJMS) wfsl.getPort(WeatherForecastJMS.class); // The setWeather() method takes in a Weather[] as input. // Initializing an array with two sample elements ... Weather[] wObj = new Weather[2]; wObj[0] = new Weather(); wObj[0].setDate( new GregorianCalendar(2005,4,5) ); wObj[0].setCondition("sunny"); wObj[0].setTemperatureCelsius(15); wObj[0].setWindDirection("NE"); wObj[0].setWindSpeed(10); wObj[1] = new Weather(); wObj[1].setDate( Calendar.getInstance() ); wObj[1].setCondition("rainy"); wObj[1].setTemperatureCelsius(44); wObj[1].setWindDirection("NE"); wObj[1].setWindSpeed(44); // Calling the Web Service wf.setWeather(wObj); out.println("

JMS Set Weather Servlet call completed!

"); out.println("

Verify that 2 rows are inserted in the DB with date 5/5/2005 and current date.

"); out.println("

For example run: SELECT * from ITSO.SANJOSE

"); } catch (Exception e) { out.println("

Request failed. Check logs for details.

"); e.printStackTrace(); } } }

Figure 15-20 Sample JMS test client

278

WebSphere Version 5.1 Web Services Handbook


Start the WeatherServer and run the servlet. Upon successful completion of the servlet, you will see a success message in the Web browser (Figure 15-21). If you get an error messsage, check the WeatherServer logs.

Figure 15-21 Output of JMS servlet client

Creating a Web service top-down from WSDL In this section we create a Java Bean on the server side from an existing WSDL document. The wizard for this procedure is structured in the same way as for the previous example. Therefore, it also offers opportunities to create a proxy on the client side and to test the generated code. Because we have explored these features already in the previous sections, we could omit them. Generating the proxy enables us to test the new Web service.

Create Web projects and import the WSDL The wizard asks for a given WSDL document that can be placed anywhere on the workspace, and for a Web project into which the code is generated. In addition we can generate a proxy into a client project. For our scenario, we start by creating a new enterprise application, ItsoWebService4, with two Web projects, ItsoWebService4Web and ItsoWebService4WebClient. Next we import the WSDL files into the ItsoWebService4Web project:
Create a new folder named wsdl under WebContent.
Select the wsdl folder and Import to import the WSDL file: sg246891-01\sampcode\wsad51\top-down\WeatherForecastTD.wsdl

Chapter 15. WebSphere Studio Application Developer

279

Create the skeleton JavaBean Now we can run the Web services wizard to create the Java code. We could use the full Web Service wizard and generate the skeleton bean, the test client, and install the service in a server. We use a simpler approach here:
Select the WeatherForecastTD.wsdl file and Web Services -> Generate Java bean skeleton.
Make sure that ItsoWebService4Web is selected for the Web project.
The WSDL file is preselected.
The skeleton folder is set to /ItsoWebService4Web/JavaSource.
Click Finish.

Generated files The generated files in the ItsoWebService4Web project are:
Skeleton files in the itso.bean package: WeatherForecast (an interface) and WeatherForecastSoapBindingImpl, the implementation class.
Mapping classes in itso.mapping.
A copy of the WSDL file in WEB-INF/wsdl and in WebContent/wsdl, with an updated target address:

You may want to delete the original WSDL file (with the old address).
Deployment descriptor files (webservices.xml, ...) in WEB-INF.

Client proxy To generate a proxy and a test client, select the new WSDL file (under WEB-INF) and Web Services -> Generate Client.
Select Test the generated proxy to create the test client.
Make sure that the output goes into the ItsoWebService4WebClient project. Tip: If you see warnings in the Tasks view, select the project and Project -> Rebuild Project.

Implementing the JavaBean Figure 15-22 shows the generated skeleton JavaBean code.

280

WebSphere Version 5.1 Web Services Handbook

package itso.bean; public class WeatherForecastSoapBindingImpl implements itso.bean.WeatherForecast { public itso.mapping.Weather getDayForecast(java.util.Calendar theDate) throws java.rmi.RemoteException { return null; } public itso.mapping.Weather[] getForecast(java.util.Calendar startDate, int days) throws java.rmi.RemoteException { return null; } public int[] getTemperatures(java.util.Calendar startDate, int days) throws java.rmi.RemoteException { return null; } } Figure 15-22 Generated skeleton JavaBean

To implement a real Web service in place of this skeleton, replace the skeleton code with the implementation code similar to what is provided in ItsoWebService1Web project. Here are short instructions:
Add the method code to the skeleton methods.
Add the variables and helper methods.
The java.lang.Exception must be changed to java.rmi.RemoteException.
You will see several errors in the Tasks pane. To eliminated the errors the Web project must be configured: – Copy the WeatherPredictor.java file into the itso.mapping package. – Add a resource reference (ItsoWeatherDB) with JNDI name jdbc/sjweather for the data source. – Add four environment variables (dataSource, getDB2Weather, setDB2Weather, removeDB2Weather). For the last two steps copy the entries from the ItsoWebService1Web project. Note: You end up with the same Web service as in ItsoWebService1Web. Therefore, it is hardly worth the effort.

Chapter 15. WebSphere Studio Application Developer

281

Web services interoperability Application Developer provides facilities to generate WS-I compliant Web services and to test the generated Web services for WS-I compliance. See “Web services interoperability (WS-I)” on page 15 for a general introduction to WS-I.

WS-I preferences The WS-I compliance preference can be set in the Windows -> Preferences dialog (workspace level) or in the Properties for a project (Figure 15-23).

Figure 15-23 WS-I preference and project properties

The Web services WS-I validation tools support the level of WS-I compliance outlined in the WS-I Basic Profile 1.0. You can choose to make your Web service compliant or non-compliant, depending on your needs. For example, encoded and SOAP over JMS protocols, as well as secured Web services, are not supported by the WS-I specifications. You can select three levels of compliance with WS-I Basic Profile 1.0:
Require WS-I compliance—This level prevents you from creating a non-compliant Web service.
Suggest WS-I compliance—This level allows you to create a non-compliant Web service, but provides a visible warning stating how the service is non-compliant.
Ignore WS-I compliance—This level allows you to create a non-compliant Web service and does not notify you of non-compliance.

282

WebSphere Version 5.1 Web Services Handbook

Web service generation When generating a Web service that is not WS-I compliant and the preference has been set to Suggest WS-I compliance, you get a warning message, as shown in Figure 15-5 on page 256.

WSDL validation A WSDL file can be validated against WS-I. Set the workspace preference or project properties to Require WS-I compliance, select a WSDL file and Validate WSDL File (context), and you are notified with a message and errors in the Tasks view if the WSDL file is not WS-I compliant. For example, set the project preference for the ItsoWebService3EJB project to Require WS-I compliance, select the WeatherForecastJMS.wsdl file and Validate WSDL File, and you get the error message shown in Figure 15-24.

Figure 15-24 WS-I compliance validation error

If the preferences are set to Suggest WS-I compliance, the WSDL validation succeeds, but warning messages are shown in the Tasks view.

Validating SOAP messages with the TCP/IP Monitor To validate actual SOAP messages for WS-I compliance, start the TCP/IP Monitor and route the SOAP messages to port 9081 by changing the port in the service locator class; for example: private final java.lang.String weatherForecast_address = "http://localhost:9081/ItsoWebService1Web/services/WeatherForecast";

Start the WeatherServer, run a client, then check the SOAP messages in the TCP/IP Monitor view (Figure 15-25):
Open the TCP/IP Monitor view.
Click the Validate WS-I Message Log File icon (top right).
You are prompted for the location to store the log file. Select the WebContent folder, for example.
The log file is saved and validated; error messages are shown in the Tasks view.

Chapter 15. WebSphere Studio Application Developer

283

Figure 15-25 Validate SOAP messages for WSI-I compliance in TCP/IP Monitor

For example, when validating the SOAP messages sent by the DB2 DADX Web service (in ItsoWebService5WebClient), you get the error message shown in Figure 15-26.

Figure 15-26 SOAP message validation error

The Tasks view shows this error message: A child of the soap:Body element has a soap:encodingStyle attribute

The log file that is produced by the TCP/IP Monitor is an XML file, by default named log.wsimsg. The log file contains tags for each input and output message with and tags containing the full SOAP message and HTTP headers. Conclusion: Application Developer makes WS-I compliance easy by providing the tools required for generation of WS-I compliant Web services and for validating the generated code and runtime SOAP messages.

284

WebSphere Version 5.1 Web Services Handbook

Creating a Web service from a URL The purpose of a URL Web service is to provide a mechanism to easily incorporate remotely running servlets into a client application, which can further process the markup generated by the servlet. The Application Developer wizard generates a Web service and optionally a client proxy from an existing servlet, which can be located anywhere on the Web. During that process, the implementer can specify the syntax of the servlet parameters. We provide a servlet named WeatherForecastServlet that executes the same functions as the WeatherForecast JavaBean. We import this servlet into a new Web project named ItsoWebService5Web and then turn it into a Web service.

Importing the servlet To create the servlet and import the existing code into the Web project:
Import the ItsoWebService5 enterprise application provided in: sg246891-01\sampcode\wsad51\URL\ItsoWebService5.ear


This creates an enterprise application (ItsoWebService5) with a Web project (ItsoWebService5Web).
Study the content of the ItsoWebService5Web project. It contains the WeatherForecastServlet, and supporting classes (WeatherPredictor and Weather).
Study the WeatherForecastServlet. The servlet accepts one parameter called method, with values day, week, or weektemp, to invoke the three functions of the weather forecast application. Note: Ignore the WEB-INF\databases folder; it will be used in “Creating a Web service from DADX” on page 290.

Creating a server We could add the ItsoWebService5 enterprise application to the WeatherServer, but that server is already heavily loaded with data source and JMS. It is much easier to create a new Version 5 server, WeatherServletServer. This new server does not require any configuration. Create the server and add the ItsoWebService5 enterprise application.

Chapter 15. WebSphere Studio Application Developer

285

Running the servlet Start the WeatherServletServer and test the servlet using the URL: http://localhost:9080/ItsoWebService5Web/WeatherForecastServlet Tip: You can run the servlet by selecting the WeatherForecastServlet.java file and Run on Server (context). Figure 15-27 shows a sample run of the servlet.

Figure 15-27 Weather forecast servlet sample run

You can also invoke one of the methods directly with the URL: http://localhost:9080/ItsoWebService5Web/WeatherForecastServlet?method=day

Note that this servlet does not query the database for weather information, but instead used a random number generator for simplicity.

Creating the URL Web service for the servlet To create a Web service that can access the three functions of the servlet we run the Web services wizard:
Select File -> New -> Other -> Web Services -> Web Service and click Next.
Select URL Web Service as the service type, and select Start Web service in Web project, Generate a proxy, and Test the generated proxy. Do not select Test the Web service. Click Next.

286

WebSphere Version 5.1 Web Services Handbook


Make sure to select ItsoWebService5Web as the Web project and ItsoWebService5WebClient as the Client Web project (this project will be created). Click Next. Click Ignore for the WS-I compliance warning.
In the Web Service URL page, one icon named NewURLWebService is displayed (Figure 15-28). Starting from this icon we have to build the URL and parameters to invoke the servlet.

Figure 15-28 URL Web services wizard: Start


Select the NewURLWebService and Properties (context), replace NewURLWebService with WeatherForecastServlet in all fields, and click OK (Figure 15-29).

Figure 15-29 URL Web services wizard: Service properties


Select the WeatherForecastServlet and Add Port, expand the service, and a NewPort is displayed.
Select the NewPort and Properties. Change the name to WeatherPort, the HTTP address to http://localhost:9080/, accept the default HTTP method as Get, and click OK.

Chapter 15. WebSphere Studio Application Developer

287


Select the WeatherPort and Add Operation, expand, and a NewOperation is displayed.
Select the NewOperation and Properties. Enter forecast as the name, ItsoWebService5Web/WeatherForecastServlet as the URI location, and click OK.
Select forecast and Add Parameter, expand, and Return and NewParameter are displayed.
Select the NewParameter and Properties. Enter method as the name, leave the namespace and type, and click OK.
Select the Return and Properties, change the mime type from mimeXML to text/plain: – text/plain—The servlets returns HTML. – text/xml—The servlet returns valid XML (this could be HTML with properly nested matching begin/end tags); the proxy only returns the first text element. – mimeXML—Same as text/xml. Note: A DOM element of the complete XML should be returned for text/xml, but the proxy currently only returns the first text element.
Figure 15-30 shows the final tree.

Figure 15-30 URL Web services wizard: Final tree


Click Next to go through the pages of the wizard. Accept all the defaults.
Click Finish and wait while the wizard generates the code and starts the server.

288

WebSphere Version 5.1 Web Services Handbook

Note that no Web service is created in the ItsoWebService5Web project. The servlet itself is the Web service and it will be invoked directly using the URL we specified in the wizard. Let us take a look at the generated files:
Two WSDL files are generated in the ItsoWebService5Web project into WebContent/wsdl: WeatherForecastServletBinding.wsdl WeatherForecastServletService.wsdl

<=== binding and interface <=== implementation


A proxy named proxy.httpget.WeatherForecastServletProxy is generated in the ItsoWebService5WebClient project. When you open the proxy class, you can see that the servlet is invoked directly using HTTP-GET; SOAP is not involved.
Web service sample JSPs are generated into the folder WebContent/sample/WeatherForecastServlet.

Testing the URL Web service The sample test client should have started automatically; otherwise, select the sample/WeatherForecastServlet/TestClient.jsp file and Run on Server: In the Methods pane select the forecast method. Enter day, week, or weektemp and select Invoke. Figure 15-31 shows the generated HTML markup as the result of the invocation of the servlet with day as the parameter.

Figure 15-31 URL Web service invocation

Chapter 15. WebSphere Studio Application Developer

289

Creating a Web service from DADX A document access definition extension (DADX) Web service enables you to wrap a DB2 XML Extender document access definition (DAD), an SQL statement, or a stored procedure call as a Web service. DADX is an XML document that is used by the Web Service Object Runtime Facility (WORF) that comes with DB2. WORF executes the SQL statement (or DAD file or stored procedure) and returns the output in XML as a Web service result. WORF comes with Application Developer and with DB2 Version 8.1; it can be downloaded for free for DB2 Version 7.2.

DADX group Multiple DADX files are stored in a DADX group. A DADX group is a folder with DADX files and a group.properties file that specifies the connection information for the DB2 database (JDBC driver or data source). WORF provides a servlet (DxxInvoker) that is mapped to all the requests of a group.

Creating a Web service from an SQL statement To create DB2 Web services, you can either directly use WORF and a text editor or you can use the wizard that comes with Application Developer. The following steps have to be performed:





Create an SQL statement. Create a DADX group. Create a DADX file from the SQL statement. Create a Web service from the DADX file.

We provide the SQL statement for the DADX Web service in the ItsoWebService5 enterprise application. Import the application if not already done so for the URL Web service.

Create an SQL statement Application Developer provides a wizard to create an SQL statement. Refer to the WebSphere Studio Application Developer Version 5 Programming Guide, SG24-6957, for details on how to create an SQL statement. In short, select the ItsoWebService5Web project and New -> Other -> Data -> SQL Statement. Then select Create an SQL resource and invoke the SQL Builder. Create a database connection and name the statement GoodWeather.

290

WebSphere Version 5.1 Web Services Handbook

To make it easy, we provide the WEATHER_GoodWeather.sqx SQL statement in the WEB-INF\databases folder: SELECT ITSO.SANJOSE.WINDSPEED, ITSO.SANJOSE.TEMPERATURE, ITSO.SANJOSE.WINDDIR, ITSO.SANJOSE.CONDITION, ITSO.SANJOSE.WEATHERDATE FROM ITSO.SANJOSE WHERE ITSO.SANJOSE.TEMPERATURE > :temp AND ITSO.SANJOSE.WINDSPEED < :wind ORDER BY TEMPERATURE DESC

You may have to tailor the ConWEATHER.comxmi connection file with the correct location of the db2java.zip file, or recreate a ConWEATHER connection.

Create a DADX group To create a DADX group:
Select File -> New -> Web Services -> Web Services DADX Group Configuration.
Select the ItsoWebService5Web project and click Add group. Name the group WeatherGroup.
Select the group and click Group properties. Complete the dialog as shown in Figure 15-32.

To use a data source, set the context factory to: com.ibm.websphere.naming. WsnInitialContextFactory

And the data source to: jdbc/sjweather

Then you have to configure the server with the data source.

Figure 15-32 DADX group properties


Click Finish to create the group under JavaSource.

Chapter 15. WebSphere Studio Application Developer

291

Creating a DADX file To create the DADX file from the SQL statement:
Select File -> New -> Web Services -> DADX File.
Select the GoodWeather SQL statement under ItsoWebService5Web (expand WebContent/WEB-INF/databases/WEATHER/Statements).
Click Next twice. Enter GoodWeather.dadx as the statement name and set the output folder to /ItsoWebService5Web/JavaSource/groups/WeatherGroup.
Click Finish. The GoodWeather.dadx file opens in the editor (Example 15-2). Example 15-2 DADX file :temp AND ITSO.SANJOSE.WINDSPEED < :wind ORDER BY TEMPERATURE DESC ]]>


Notice the SQL statement and the parameter definitions.

Create the Web service To generate the Web service we use the Web Services wizard:
Select the GoodWeather.dadx file and New -> Web Services -> Web Service.
The DADX Web Service type is preselected. Select Start the Web service, Generate a proxy, and Test the generated proxy.

292

WebSphere Version 5.1 Web Services Handbook


Make sure the projects are ItsoWebService5Web and ItsoWebService5WebClient.
Go through the pages, accept all the defaults (soap binding), and click Finish.

Testing the Web service The test client opens automatically. Notice that two methods are generated in the proxy:
GoodWeather_—Returns a DOM element (the test client generates XML from the DOM element).
GodoWeather—Returns an object (GoodWeatherResultElement) that contains row objects. A sample run is shown in Figure 15-33.

Figure 15-33 DADX Web service result

Note: You may have to restart the ItsoWebService5 project in the server.

Chapter 15. WebSphere Studio Application Developer

293

A WORF test client is also generated. To run the WORF test client enter this URL into a browser window and play with the different functions: http://localhost:9080/ItsoWebService5Web/WeatherGroup/GoodWeather.dadx/TEST

A sample run is shown in Figure 15-34. You can also generate WSDL and XML Schema files using the WORF runtime.

Figure 15-34 DADX Web service WORF client

DADX Web services use the “old” SOAP engine (Apache SOAP 2.3). Running such Web services require:
A deployment descriptor file, dds.xml, in WebContent
A SOAP configuration file, soap.xml
A number of runtime files (in lib and in the classpath)
An admin folder (in WebContent) to administer the deployed services (select the index.html file and Run on Server)

294

WebSphere Version 5.1 Web Services Handbook

For the WORF runtime, these definition and files are created:
A servlet, WeatherGroup, configured in web.xml, pointing to: com.ibm.etools.webservice.rt.dxx.servlet.DxxInvoker


A worf folder with the WORF test client

Publishing and exploring a UDDI registry In this section we describe how to use the built-in features of Application Developer to publish the recently generated Web service and how to import services listed in a UDDI registry. Application Developer provides the Web Services Explorer tool—also called the UDDI Explorer—that enables you to publish and maintain your business entity, business services, and service interfaces. We do not describe UDDI basics here because they are presented in detail in Chapter 6, “Introduction to UDDI” on page 99. In this section we show:
How to create a business entity at a UDDI registry. The business entity contains information about the business, for example, contact information and URLs.
How to publish a Web service to a UDDI registry.
How to access a Web service with the Web Services Explorer. A complete scenario, where a Web service is invoked dynamically using UDDI4J, is presented in Chapter 19, “Web services scenario: Architecture and implementation” on page 429. Before you work with a UDDI registry, you must get an ID and password for that registry. To register with the IBM test registry, use a Web browser and enter: http://www.ibm.com/services/uddi

Click the icon for the UDDI V2 Business Test Registry and follow the link Get an IBM user ID and password. The procedure for getting this user ID and password is asynchronous now. After filling in the online request for a user ID, you will get an e-mail (to the address specified in the request form). In this e-mail you will be sent a URL, which will need to be copied and pasted into a Web browser to complete the registration. Remember, without completing this registration, some of the next steps in this exercise will not work.

Chapter 15. WebSphere Studio Application Developer

295

Publishing a business entity The IBM test registry allows only one business entity to be published per user ID. If you have previously published a business entity to the test registry, you can either remove the existing business entity, or publish the WeatherForecast service using your existing business entity.

Web Services Explorer The Web Services Explorer can be launched from the Web Services wizard described earlier in this chapter. It can also be started anytime by clicking the Launch Web Services Explorer icon ( ) on the main toolbar of Application Developer or by selecting Run -> Launch the Web Services Explorer. Once you have started the Web Services Explorer, perform these steps:
In the Navigator pane, select the UDDI Main node.
In the Actions pane, IBM UDDI Test Registry appears in the Registry Name field. Click Go.
Figure 15-35 shows the status of the Web Services Explorer.

Figure 15-35 Web Services Explorer ready to enter the business entity


In the toolbar of the Actions pane, click the Publish icon (

296

WebSphere Version 5.1 Web Services Handbook

).


Select Business in the Publish list, Simple for the format, and keep the default URL. Enter your user ID, password, business name, and a description of your business entity in the respective fields. Click Go.
The IBM Web Services Explorer is automatically updated with your published business entity.

Discovering business entities To discover your business entity or any other business entities using the Web Services Explorer, perform these steps:
In the Navigator pane, select the IBM UDDI Test Registry node.
In the toolbar of the Actions pane, click the Find icon (

):

– For the Name of this query, you can enter any name that you can associate with the search you are currently performing. – In the Search For drop-down list select Businesses. – For Type of Search select Simple. – In the Name field enter the name of your business entity. – Click Go. A search for ITSO WS% finds three businesses that were added for this publication (Figure 15-36) and potentially business from other people.

Figure 15-36 Web Services Explorer search

Chapter 15. WebSphere Studio Application Developer

297


Select a business to retrieve detailed information about that business entity. With proper authorization (user ID and password), you can also update the information.

Publishing the weather forecast Web service Once you have found your business entity in the UDDI, you can publish a Web service using the Web Services Explorer:
Make sure that the WeatherServer is started (the server that runs the service you want to publish).
In the Navigator pane, select your business entity under the Published Businesses folder or after executing a query to find the business.
In the toolbar of the Actions pane, click the Publish Service icon (

):

– For the Publication Format, select Simple. – Enter your user ID and password. – To enter the WSDL URL, click Browse. In the window, select Web Projects as the source for the WSDL, select the ItsoWebService5Web project, then select the correct WSDL file, and click Go: http://localhost:9080/ItsoWebService1Web/wsdl/itso/bean /WeatherForecast.wsdl

Note: Because we are using the WebSphere test environment, no concrete IP address but localhost is used. For this example, we did not run into difficulties retrieving the service, because this action is also done on the same machine (the WebSphere server must be running). For distributed scenarios, the host name can be changed here, but it can also be changed easily after publication in the registry.

298

WebSphere Version 5.1 Web Services Handbook

– Back in the Web Services Explorer window, in the Name field of the Actions pane, type WeatherForecast. – In the Description field of the Actions pane, type a description that helps you identify the service more easily, because there is a chance that some other forecasts have been published before. Figure 15-37 shows the completed Actions pane. – When you have finished entering the service information, click Go.

Figure 15-37 A Web service ready to be published


The Web Services Explorer is automatically updated with your published Web service. If the update is successful, the Status pane displays: IWAB0160I Service interface http://bean.itso was successfully published. IWAB0159I Service WeatherForecast was successfully published.

Discovering the weather forecast Web service Finally, we show how the Web Services Explorer can be used to find Web services in the registry. We cover here only the static case. Chapter 19, “Web services scenario: Architecture and implementation” on page 429, shows how to dynamically access a UDDI registry.

Chapter 15. WebSphere Studio Application Developer

299

There are several ways to search for a Web service. You can discover a Web service by searching for a business entity, business service, or service interface. Here is how to search directly for the name of the service:
Start the Web Services Explorer icon on the main toolbar.
In the Web Services Explorer toolbar, select the Favorites icon (

).


Expand Favorite UDDI Registries. Here you can choose any registry you want to browse. Because we have published our Web service on the IBM UDDI test registry, click IBM UDDI Test Registry.
In the Actions toolbar, click the Add to UDDI Page icon (

).


In the Actions toolbar, click the Find icon: – Select Services in the Search for box. – Select Advanced for type of search (there are more than 10 services with the name WeatherForecast in the test registry). – Click Add for Names and enter WeatherForecast. – Enter 50 for Maximum number of results. – Click Go.
Figure 15-38 shows the results of the search. Because we have an informative description, we can easily identify our previously published Web service.
Click the service of your choice. Now you can modify information or even unpublish it, if you have the rights.
You can download the WSDL file by clicking the Import WSDL to file system icon ( ), or even import it directly to the Application Developer Workbench. Click the Import WSDL to workbench icon ( ). Select one of the projects in your Workbench and a file name for the new WSDL document and click Go. If the import was successful, you get a successful confirmation message. You can find the imported file in the selected project. Once you have accessed the WSDL document, you can start to build a Web service from the top down, as described in “Creating a Web service top-down from WSDL” on page 279.

300

WebSphere Version 5.1 Web Services Handbook

Figure 15-38 Results of a UDDI query on weather forecast

Deployment of the sample applications To deploy the application means to export an EAR file from Application Developer and install the enterprise application in an Application Server.

Exporting the EAR file and installing the enterprise application To export an EAR file, select the ItsoWebServiceX project and Export (context). Select EAR file as the destination and click Next. Click Browse to locate the target directory. By default the output file is named ItsoWebServiceX.ear. For WebSphere, the target location is usually the installableApps directory (C:\WebSphere\AppServer\installableApps). Installation of enterprise applications into a WebSphere Application Server is covered in Chapter 20, “Web services runtime and deployment in WebSphere” on page 479.

Chapter 15. WebSphere Studio Application Developer

301

Summary In this chapter we have provided two Web services generation walk-throughs using Application Developer. First we generated a Web service for a given server-side application (JavaBean), the corresponding WSDL documents, and the client code. We also tested the Web service and traced the SOAP messages. We also developed a client application that uses the Web service. We repeated the process for a session EJB and generated both an HTTP Web service and a SOAP over JMS Web service. Then we took a WSDL document and generated the server-side skeleton code for a new Web service. We took a short look at Web services interoperability (WS-I) and the Application Developer tooling that can be used for WS-I compliance. We described how to generate a URL Web service and a DADX Web service. Finally, we discussed how to publish a service to a UDDI registry and how to incorporate services from a UDDI registry.

More Information The IBM Redbook Web Services Wizardry with WebSphere Studio Application Developer, SG24-6292, also provides insight into the tools provided by Application Developer. However, that book refers to Application Developer Version 4, where a number of changes apply. The IBM Redbook WebSphere Studio Application Developer Version 5 Programming Guide, SG24-6957, provides detailed information about using Application Developer, not only on Web services issues. The IBM Redbook Integrating Your Information, SG24-6892, gives detailed information on how to create Web services from DB2 SQL queries. Also, the online help that comes with WebSphere Studio Application Developer provides information and tutorials for creating and using Web services.

302

WebSphere Version 5.1 Web Services Handbook

16

Chapter 16.

Web services security with Application Developer This chapter describes the functionality offered by WebSphere Studio Application Developer Version 5.1 to secure Web services following the Web services security specification (refer to Chapter 11, “Web services security” on page 185). This chapter does not teach any basic feature of Application Developer 5.1; refer to Chapter 15, “WebSphere Studio Application Developer” on page 247, to understand the creation of Web services. This chapter concentrates on the supporting features provided by Application Developer 5.1 to apply authentication, integrity, and confidentiality to Web services.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

303

Overview The security that we apply in this chapter to Web services is purely SOAP message security. This means that the security is an integrated part of the SOAP message and travels with the message, making this kind of security platform and transport independent. It applies to SOAP over HTTP or SOAP over JMS. This security is based on:
XML digital signature—Provides message integrity
XML encryption—Provides message confidentiality
Security tokens—Provides message authentication

Architecture and deployment model The security is implemented using system handlers. These system handlers are registered to different parts of a Web service. Figure 16-1 shows the handlers and their responsibilities. Decrypt message Digital Signature validation Security Token validation and setup security context

Security Token generation Digital Signature generation Encrypt message

Client

2

1 Request

App. client

Request

Security Handlers

SOAP message = WS-Security headers + body content

Security Handlers

J2EE container

Response

Response

4 Configuration DD and service bindings

Server

Decrypt message Digital Signature validation

3 Digital Signature generation Encrypt message

webservicesclient.xml

Configuration DD and service bindings webservices.xml

Figure 16-1 Web services message security architecture

The message follows these steps: 1. At the client side, the request security handler is used to generate the required security headers in the SOAP message before the SOAP message

304

WebSphere Version 5.1 Web Services Handbook

is sent out to the server. These security constraints are defined in the client configuration deployment descriptor. 2. At the server side, the request security handler is invoked to check that the SOAP message complies with all the security constraints specified by the server deployment descriptors prior to dispatching the message to the Web service implementation. 3. At the server side, the response security handler is invoked to generate the SOAP security header information before the message is sent back to the client. The nature of that information is also specified in the server deployment descriptors. 4. At the client side, the response security handler is called to manage the SOAP message security information to know whether the message complies with the client deployment descriptor specifications before the message is passed to the client implementation. Therefore, the security constraints specified by the server and client must match, allowing both sides to understand each other (Figure 16-2).

matching

matching ibm-webservicesclient-ext.xmi

securityResponseReceiverServiceConfig securityRequestReceiverServiceConfig

securityRequestSenderServiceConfig securityResponseSenderServiceConfig

ibm-webservices-ext.xmi ibm-webservicesclient-bnd.xmi securityResponseReceiverBindingConfig securityRequestReceiverBindingConfig

securityRequestSenderBindingConfig securityResponseSenderBindingConfig

ibm-webservices-bnd.xmi Figure 16-2 Value compatibility between client and server deployment descriptor

The security requirements are specified in the deployment descriptors of the Web service or client. The assembler role is responsible for the definition of that information. Currently, there is no standard deployment model for Web services security. IBM uses these deployment descriptors for the server and client:





ibm-webservices-ext.xmi—Defines the security constraints to apply ibm-webservices-bnd.xmi—Defines how to apply these constraints ibm-webservicesclient-ext.xmi—Defines the security constraints to apply ibm-webservicesclient-bnd.xmi—Defines how to apply these constraints

Chapter 16. Web services security with Application Developer

305

The IBM deployment descriptor extensions and bindings are associated with each EJB module or Web module where the Web service server or client resides. Some of the binding information could be shared among various applications. To provide this capability, IBM defines some default elements at the server level in the ws-security.xml file, where elements such as key locators, trust anchors, certificates, and so forth are declared to be referenced from EJB or Web modules. When the same elements are defined at the application level, they have priority over the global definitions. Application Developer 5.1 provides an editor to graphically modify the deployment descriptor files. The editor functionality is exactly the same for client and server. Figure 16-3 shows the editors for the client side.

ibm-webservicesclient-bnd.xmi ibm-webservicesclient-bnd.xmi -

HOW TO DO

ibm-webservicesclient-ext.xmi WHAT TO DO Figure 16-3 Editors to modify the security deployment descriptors

When the requirements of the security constraints are not satisfied for a SOAP message, a SOAP fault response, as defined in the SOAP specification, is sent to the requester. This behavior is perfectly valid when no security constraints are applied to the server answer.

306

WebSphere Version 5.1 Web Services Handbook

If any security information is required in the server response, the client receives the fault fired by its own response handler. This handler generates a new SOAP fault with the lack of security information received by the server response. Although the original fault usually accompanies the message, we have lost the security constraints. Figure 16-4 shows this inappropriate behavior.

Server

Client SOAP message = WS-Security headers + body content

Request App. client

Security Handlers

1

Request Security Handlers

2

Response

J2EE container

SOAP Fault No WS-Security headers

4 3 Configuration DD and service bindings

Generate a SOAP security Fault

Configuration DD and service bindings

Figure 16-4 SOAP message flow with a SOAP fault error in the server

The steps are: 1. The client request handler generates the security information filling the header of the SOAP message. 2. The server request handler validates the security information provided by the client. If this information does not match the requirements, a SOAP fault message is sent to the client. This message is sent without passing through the server response handler. Therefore, there is no security header in the SOAP message sent to the client. The same behavior is applied when an error occurs in the Web service implementation. 3. The client response handler validates the security constraints, but there is nothing to validate because the security constraints do not come with the SOAP fault message. Consequently, the client response handler generates a new SOAP fault message to inform about the security fault in the incoming message. That message fault usually includes the original fault fired in the server. On the other hand, the security constraints are lost in the response message; no integrity and no confidentiality. 4. The client processes the SOAP fault message, obtaining as the primary error the one generated by its response handler and as the secondary error the real one. Therefore, the client does not have any mechanism to know if the message has been modified in its travel.

Chapter 16. Web services security with Application Developer

307

Securing Web services In this section we illustrate with an example how we can protect a Web service with authentication, integrity, and confidentiality using WebSphere Studio Application Developer. We start from the EJB-based Web service created in “Creating a Web service from a session bean” on page 271. We provide a copy of the ItsoWebService2 enterprise application as ItsoWebService6 to implement security.
Import the ItsoWebService6 enterprise application from the file: sg246891-01\sampcode\wsad51security\start\ItsoWebService6.ear


This creates the ItsoWebService6EJB, ItsoWebService6RouterWeb, and ItsoWebService6EJBClient projects.
Open the Properties of the ItsoWebService6RouterWeb project. On the Java Build Path, Libraries page, click Add Variable, select the WAS_50_PLUGINDIR, click Extend, and add the lib\webservices.jar file to the classpath.
Add the ItsoWebService6 application to the WeatherServer. To limit the number of projects loaded, remove all other applications from the server. You can start the server and run the test client (in ItsoWebService6EJBClient).

Implementing security The three security constraints that can be applied to Web services are:
Authentication—Using security tokens
Integrity—Using XML digital signature
Confidentiality—Using XML encryption Note: Although Application Developer can generate a client with security, it forces the user to choose one type of security (integrity or confidentiality), and only one. However, Application Developer does not allow the user to define to what part of the message and how security is applied. Consequently, if that limited option does not satisfy the requirements, the user has to remove the security features generated, which is more work than making a simple change in the client code. The security option is specified in the proxy page of the client creation (see Figure 15-6 on page 257), where you can choose between XML Digital Signature and XML Encryption.

308

WebSphere Version 5.1 Web Services Handbook

Authentication The authentication process creates a security token in a SOAP message. This security token is inserted in the message, authenticating the caller. Web services security offers these possibilities to provide a security token: Basic authentication

Includes user name and password information, and generates with and

Signature

Includes an X.509 certificate and generates with

ID assertion

Includes a user name and generates with

LTPA

Includes a Light-weight Third Party Authentication (LTPA) token and generates with

Custom

Includes a custom-defined token

Figure 16-5 shows the architecture diagram of how a security token is generated.

Callback Handler

Configuration

Security Token

JAAS Login Callback Handler Configuration

1 Security SecurityToken Tokengeneration generation

3 Security Token

Security Token validation Set security context

JAAS Subject

Server

Client 2 Request App. client

Security Handlers

Request SOAP message = WS-Security headers + body content

Response

Configuration DD and service bindings

Security Handlers

J2EE container

Response

Configuration DD and service bindings

Figure 16-5 Security token generation architecture

Chapter 16. Web services security with Application Developer

309

The complete process for the authentication of the client is: 1. The client security request handler uses a callback handler to generate the security token. This security token is inserted in the SOAP message. 2. The SOAP message is sent to the server. 3. The server security request handler takes the information from the SOAP message and validates it using a JAAS login module. If the validation is successful, a JAAS subject is returned; if not, a SOAP fault exception is generated.

Defining client authentication The definition of the authentication is performed using of the Web service deployment descriptor editor. Expand ItsoWebService6EJBClient -> WebContent -> WEB-INF, open the webservicesclient.xml file using the Web Services Client Editor, and select the Security Extensions page (Figure 16-6).

Figure 16-6 Web service client security extensions

310

WebSphere Version 5.1 Web Services Handbook

Select the WeatherForecastEJB port binding to apply the security constrictions to that port. Under Request Sender Configuration, expand Login Config. The available choices are:





BasicAuth IDAssertion Signature LTPA (Application Developer 5.1.1)

We use basic authentication for our example. Select BasicAuth for the authentication method and save. This selection produces the inclusion of that information in the ibm-webservicesclient-ext.xmi file:

Now we have to define the callback handler responsible for inserting the security token in the SOAP message.
On the Port Binding page select the WeatherForecastEJB port under Port Qualified Name Binding. Expand Security Request Sender Binding Configuration and Login Binding and click Enable. The login dialog opens (Figure 16-7).

Figure 16-7 Login binding dialog

Chapter 16. Web services security with Application Developer

311

In the dialog:
Select BasicAuth as Authentication method.
Enter com.ibm.wsspi.wssecurity.auth.callback.NonPromptCallbackHandler as Callback handler to provide the user ID and password hardcoded in the binding file. Other possibilities are: – com.ibm.wsspi.wssecurity.auth.callback.GUIPromptCallbackHandler to prompt for user ID and password in standard input – com.ibm.wsspi.wssecurity.auth.callback.StdinPromptCallbackHandler to prompt for user ID and password in a GUI panel – com.ibm.wsspi.wssecurity.auth.callback.GUIPromptCallbackHandler to generate LTPA token as binary security
Enter a valid user ID and password for the security environment.
Click OK and save. This callback handler definition produces the inclusion of the method type, the class of the callback handler, and the user name and password in the ibm-webservicesclient-bnd.xmi file:

Defining server authentication Once the client is configured, we have to configure the server to match both configurations. Expand ItsoWebService6EJB -> ejbModule -> META-INF, open the webservices.xml file using the Web Services Editor, and select the Security Extensions page. Select the WeatherForecastEJB port to apply the security constraints to that port. Under Request Receiver Service Configuration Details, expand Login Config and click Add. In the Add Authentication Dialog (Figure 16-8) select BasicAuth and click OK. The dialog has more fields in Version 5.1.1.

Figure 16-8 Add authentication dialog

312

WebSphere Version 5.1 Web Services Handbook

The available choices are the same as for the client: BasicAuth, IDAssertion, Signature, and LTPA. The ibm-webservices-ext.xmi file is modified with:

We have to define the callback handler responsible for processing the incoming authentication using the JAAS login configuration, which is responsible for user validation:
On the Binding Configurations page select the WeatherForecastEJB port. Expand Request Receiver Binding Configuration Details and Login Mapping, and click Add. The login mapping dialog opens (Figure 16-9).

The dialog has more fields in Version 5.1.1.

Figure 16-9 Login mapping dialog

In the dialog:
Select BasicAuth as Authentication method.
Enter WSLogin as Configuration name and com.ibm.wsspi.wssecurity.auth.callback.WSCallbackHandlerFactoryImpl as Callback Handler Factory Class name.
Click OK and save. The login mapping definition produces the following changes in the ibm-webservices-bnd.xmi file:
Chapter 16. Web services security with Application Developer

313

"com.ibm.wsspi.wssecurity.auth.callback.WSCallbackHandlerFactoryImpl" />

Testing authentication To test the authentication that we configured, we have to change the server configuration. We secure the server where the Web service and client will run, using local OS security:
Open the WeatherServer configuration. On the Security page, select Enable Security, enter a valid user ID and password for the local OS (Figure 16-10), and save.

Figure 16-10 Setting Local OS security


Create a TCP/IP Monitoring Server if you have not done so already (see “Using the TCP/IP Monitoring server” on page 269).
Modify the URI of the Web service in the WeatherForecastEJBServiceLocator class in the ItsowebService6EJBClient project (JavaSource\itso.session) and set the port to 9081: http://localhost:9081/ItsoWebService6RouterWeb/services/WeatherForecastEJB


In addition, we can include a Web service security trace in the WeatherServer configuration on the Trace page: Select Enable trace and enter this single line as the Trace string: com.ibm.xml.soapsec.*=all=enabled:com.ibm.ws.webservices.*=all=enabled:com. ibm.wsspi.wssecurity.*=all=enabled:com.ibm.ws.security.*=all=enabled:SASRas =all=enabled

314

WebSphere Version 5.1 Web Services Handbook

Container-managed client In Application Developer 5.1.1 the WeatherForecastEJBProxy uses JNDI by default to acquire the service locator and no change is required to support Web services security. Note: In Application Developer 5.1 the result.jsp instantiates the service locator. This does not work with security enabled and must be manually changed to use JNDI. Sample code would be: <% itso.session.WeatherForecastEJB WeatherForecastEJBid = (itso.session.WeatherForecastEJB)session.getAttribute ("itso.session.WeatherForecastEJB"); if(WeatherForecastEJBid == null){ // Get initial context and the local representation of the Web Service javax.naming.InitialContext ic = new javax.naming.InitialContext(); itso.session.WeatherForecastEJBServiceLocator weatherEJBLocator = (itso.session.WeatherForecastEJBServiceLocator) ic.lookup("java:comp/env/service/WeatherForecastEJBService"); WeatherForecastEJBid = weatherEJBLocator.getWeatherForecastEJB(); session.setAttribute("itso.session.WeatherForecastEJB", WeatherForecastEJBid); } %>

Starting the servers Start the TCP/IP Monitor and the WeatherServer. Select the Testclient.jsp (in ItsoWebService6EJBClient\WebContent\sample) and Run on Server, select the getDayForecast method, enter a date, and click Invoke. We see in the TCP/IP Monitor view the SOAP messages, and how the security authentication is included in the header of the SOAP message. Example 16-1 and Example 16-2 show the SOAP messages sent by the client and server, respectively. Example 16-1 Message sent by the client with authentication db2admin xxxxxxxx

Chapter 16. Web services security with Application Developer

315

2003-11-24T08:00:00.000Z Example 16-2 Message response delivered by the server sunny 2003-11-24T08:00:00.000Z SE 31 38 1

Integrity The integrity process ensures that data has not been manipulated in an unauthorized or accidental manner. By providing integrity to a SOAP message we ensure the message content in a multi-hop environment, while SSL provides integrity only in a one-hop scenario. XML digital signature is the mechanism used to provide that integrity in a multi-hop scenario. The signature appends information to a SOAP message that ensured that the SOAP information has not been manipulated. The different parts that can be digitally signed are:
Body
Security token
Timestamp

Defining client integrity As we did for the authentication, we use the Web service deployment editor. Open the webservicesclient.xml file (ItsoWebService6EJBClient) and select the Security Extensions page.

316

WebSphere Version 5.1 Web Services Handbook

Select the WeatherForecastEJB port to apply security to that port. Under Request Sender Configuration, expand Integrity. The available reference parts are:
body
timestamp
securitytoken Click Add, select body, and click OK. Click Add again, select securitytoken, and click OK (Figure 16-11, left). We also want to receive the response from the server digitally signed. Under Response Receiver Configuration, expand Required Integrity and add the body reference part (Figure 16-11, right).

Figure 16-11 Integrity parts to digitally sign

Save the changes. These changes produce the inclusion of following information in the ibm-webservicesclient-ext.xmi file: ...

Chapter 16. Web services security with Application Developer

317

We have to provide the specific details of how these parts are digitally signed. First, we have to create a key locator where the key is to digitally sign the certificates is loaded:
On the Port Binding page select WeatherForecastEJB port. Expand Security Request Sender Binding Configuration and Key Locators and click Add. The key locator dialog opens (Figure 16-12).

Figure 16-12 Key locator dialog

In the dialog:
Enter SampleClientSignerKey as Key locator name.
Select com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator as Key locator class.
Select Use key store.
Enter client as Key store storepass.
Enter ${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-sender.ks for the Key store path.
Enter JKS as Key store type (overtype).

318

WebSphere Version 5.1 Web Services Handbook


Click Add under Key. Enter soaprequester as Alias, client as Key pass, and clientsignerkey as Key name.
Click OK. Note: In this book we use the sample certificates provided with WebSphere Application Server 5.1. These certificates are already loaded and matched in the application server with the names we enter in the example. We only provide them as examples of how we can create our own key locators. Local key locators have priority over global key locators with the same name.

Exploring a key store file using the keytool Using the Java keytool we can see the content of the key store file:
In a DOS command window go to the directory of the dsig-sender.ks file: \runtimes\base_v51\etc\ws-security\samples


Run the command: \wsad-home>\runtimes\base_v51\java\jre\bin\keytool -list -keystore dsig-sender.ks -v


When prompted, provide the keystore password (client).
Example 16-3 shows the information contained in the key store. There is a key entry called soaprequester with a certificate authority called soapca. That is the reason to provide the soaprequester key in the key locator dialog. Example 16-3 dsig-sender.ks key information Keystore type: jks Keystore provider: IBMJCE Your keystore contains 2 entries: Alias name: soaprequester Creation date: Mon Oct 01 02:54:42 PDT 2001 Entry type: keyEntry Certificate chain length: 3 .... ******************************************* ******************************************* Alias name: soapca Creation date: Mon Oct 01 02:54:33 PDT 2001 Entry type: trustedCertEntry ....

Chapter 16. Web services security with Application Developer

319

Second, we have to specify the algorithm that we use to sign the information. Expand Security Request Sender Binding Configuration and Signing Information and click Enable. The Signing info dialog opens (Figure 16-13).

Figure 16-13 Signing info dialog client request

In the dialog:





Leave the default algorithm methods. Enter clientsignerkey as the Signing key name. Select SampleClientSignerKey as the Signing key locator. Click OK.

Save the changes. The modifications in the ibm-webservicesclient-bnd.xmi file are shown here: .......

320

WebSphere Version 5.1 Web Services Handbook

Third, we have to configure the signing information to receive the response from the server. Expand Security Response Receiver Binding Configuration and Signing Information and click Add. The signing info dialog opens (Figure 16-14).

Figure 16-14 Signing info dialog client receive

In the dialog:
Leave the default algorithm methods.
Select Use certificate path reference. Enter SampleClientTrustAnchor as the Trust anchor reference and SampleCollectionCertStore as the Certificates store reference. Note: The SampleClientTrustAnchor and SampleCollectionCertStore are defined as part of the default Web services security bindings. Save the changes. The modifications in the ibm-webservicesclient-bnd.xmi file are shown here:

Chapter 16. Web services security with Application Developer

321

Defining server integrity Once the client is configured, we have to configure the server to match both configurations. Open the webservices.xml file and select the Security Extensions page:
Select the WeatherForecastEJB port. – Under Request Receiver Service Configuration Details, expand Required Integrity and add the body and security tokens. – Under Response Sender Service Configuration Details, expand Integrity and add body (follow the same process used for client configuration). Save the changes. The modifications in the ibm-webservices-ext.xmi file are shown here: ....

To configure the binding information for the server we follow similar steps to those used when we configured the client. On the Binding Configurations page select the WeatherForecastEJB port. Expand Request Receiver Binding Configuration Details and Signing Information and click Add. The signing info dialog opens (Figure 16-14 on page 321). In the dialog:
Leave the default algorithm methods.
Select Use certificate path reference.
Enter SampleServerTrustAnchor as the Trust anchor reference and SampleCollectionCertStore as the Certificates store reference. Save the changes. The modifications in the ibm-webservices-bnd.xmi file are shown here:
322

WebSphere Version 5.1 Web Services Handbook

algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> ....

We define the digitally signed bindings for the server response message. Expand Response Sender Binding Configuration Details and Key Locators and click Add. The key locator dialog opens (Figure 16-12 on page 318). In the dialog:
Enter SampleServerSignerKey as the Key locator name.
Select com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator as t he Key locator class.
Select Use key store.
Enter server as the Key store storepass.
Enter ${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-receiver.ks for the Key store path.
Enter JKS as the Key store type.
Click Add under Key. Enter soapprovider as the Alias, server as the Key pass and serversignerkey as the Key name.
Click OK. You can find the valid aliases using the keytool on the dsig-receiver.ks file (see “Exploring a key store file using the keytool” on page 319). There is a key entry called soapprovider with a certificate authority called soapca, the same certificate authority for the soaprequester. Finally, we have to specify the algorithm that we use to digitally sign the information. Expand Response Sender Binding Configuration Details and Signing Information and click Enable. The Signing info dialog opens (Figure 16-13 on page 320). In the dialog:
Leave the default algorithm methods.
Enter serversignerkey as the Signing key name.
Select SampleServerSignerKey as the Signing key locator.

Chapter 16. Web services security with Application Developer

323


Click OK. Save the changes. The modifications in the ibm-webservices-bnd.xmi file are shown here:

Testing integrity and authentication To test integrity plus authentication we follow the same steps defined in “Testing authentication” on page 314:
Restart the WeatherServer (this is necessary when Web service deployment descriptors are modified).
Select the TestClient.jsp (in ItsoWebService6EJBClient) and Run on Server. Select the getDayForecast method, enter a date, and click Invoke.
In the TCP/IP Monitor we can see the SOAP messages, and how the defined security constraints are included in the header of the SOAP message. Example 16-4 and Example 16-5 show the SOAP messages sent by client and server respectively. Example 16-4 Message sent by the client with integrity and authentication
324

WebSphere Version 5.1 Web Services Handbook

ValueType="wsse:X509v3" wsu:Id="wssecurity_binary_security_token_id_8136177880451455025"> MIIDQTCCAqqgAwIBAgICAQQwDQYJKoZIhvcNAQEFBQAwTjELMAkGA1UEBhMCSlAxETAP 7AJOediqUBpXb1HNlrzSrbxHJLQ= jhqLJWM2bik/9yLv5ttQwdkqJus= uR0DAKo7rxWAKFUby8JFT4VioBKSv2FSq3LChtoJZlZtj5NTUH0A3wp8EeRt Rg1J2RDgJj0tgD7i9BgbXusiKLlyih6IAftF2maOpj2RGK2GCSI2H+df8RVJ AeZhlvCSiTLKUl6CjQW/mnJxchJMHNjfflSJ9aaWWzQgLBkfeAs=
Chapter 16. Web services security with Application Developer

325

.... Example 16-5 Message response delivered by the server with integrity \ MIIDQDCCAqmgAwIBAgICAQUwDQYJKoZIhvcNAQEFBQAwTjELMA...... ...... IebfSDgXsZROJyKXREo+Za9u1zs13cm9WbnPDGD3ZO5xZg3fUTCHs90m2J+r t4Xmy6NykbUtglQVJJsCc11mPXJN0LSp6WSgaiY7B+xEhUZ6BTeiwDPO8lkR /zg0GQye0RWglR6af54nKPnVnWRBuVZrWQUThN6FSvWW1HTzQ8Q= ...... ......

Confidentiality Confidentiality is the process by which data is protected such that only authorized actors can interpret the data, reducing the risk that someone not authorized can understand the content. The data is encrypted based on the XML Encryption specifications. Confidentiality applies encryption to some parts of the SOAP message:
Body content
User ID and password Note: Currently, Application Developer 5.1 does not provide granularity to encrypt only referenced parts of the body; the body content is encrypted as a whole. That possibility is expected for future releases.

326

WebSphere Version 5.1 Web Services Handbook

Defining client confidentiality As we did when we applied authentication and integrity to the SOAP message, we use the Web Service Deployment editor. Open the webservicesclient.xml file (in ItsoWebService6EJBClient) and select the Security Extensions page. Select the WeatherForecastEJB port to apply security to that port. Under Request Sender Configuration, expand Confidentiality. The available reference parts are:
bodycontent
usernametoken We select both available possibilities for our example. Click Add, select bodycontent, and click OK. Click Add again, select usernametoken, and click OK (Figure 16-15, left). We also want to receive the body content response from the server encrypted. Under Response Receiver Configuration, expand Required Confidentiality and add bodycontent (Figure 16-15, right).

sender

receiver

Figure 16-15 Confidentially parts to encrypt

Save the changes. The modifications in the ibm-webservicesclient-ext.xmi file are shown here: .... .... ....

Chapter 16. Web services security with Application Developer

327

We have to provide how these parts are encrypted. We create a key locator where the key to encrypt is loaded. On the Port Binding page select the WeatherForecastEJB port. Expand Security Request Sender Binding Configuration and Key Locators and click Add. The key locator dialog opens (Figure 16-12 on page 318). In the dialog:
Enter SampleSenderEncryptionKeyLocator as the Key locator name.
Select com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator as the Key locator class.
Select Use key store.
Enter storepass as the Key store storepass.
Enter ${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-sender.jceks as the Key store path.
Enter JCEKS as the Key store type.
Click Add under Key. Enter Group1 as the Alias, keypass as the Key pass, and CN=Group1 as the Key name.
Click OK. You can find the valid aliases using the keytool on the enc-sender.jceks file (see “Exploring a key store file using the keytool” on page 319, use the password storepass): \wsad-home>\runtimes\base_v51\java\jre\bin\keytool -list -keytype JCEKS -keystore dsig-sender.ks -v

There are key entries called alice, group1, and bob (Example 16-6). Example 16-6 enc-sender.jceks keys information Keystore type: JCEKS Keystore provider: IBMJCE Your keystore contains 3 entries: Alias name: alice Creation date: Wed Apr 23 21:01:20 PDT 2003 Entry type: keyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=Alice, O=IBM, C=US .... ******************************************* ******************************************* Alias name: group1

328

WebSphere Version 5.1 Web Services Handbook

Creation date: Wed Oct 09 00:57:47 PDT 2002 Entry type: keyEntry ******************************************* ******************************************* Alias name: bob Creation date: Wed Apr 23 21:02:39 PDT 2003 Entry type: trustedCertEntry Owner: CN=Bob, O=IBM, C=US Issuer: CN=Bob, O=IBM, C=US ....

We also have to specify the algorithm that we use to encrypt the information. We provide the public key bob to encrypt. Expand Security Request Sender Binding Configuration and Encryption Information and click Enable. The Encryption info dialog opens (Figure 16-16).

Figure 16-16 Encryption info dialog

In the dialog:






Enter EncryptionInfo_1 as the Encryption name. Leave the default algorithm methods. Enter CN=Bob, O=IBM, C=US as the Encryption key name. Select SampleSenderEncryptionKeyLocator as the Encryption key locator Click OK.

Save the changes. The modifications in the ibm-webservicesclient-bnd.xmi file are shown here: ....
Chapter 16. Web services security with Application Developer

329

algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/> ....

We have to configure how to decrypt the response message received from the server. We have to use the private key alice in enc-sender.jceks. Expand Security Response Receiver Binding Configuration and Encryption Information and click Add. The Encryption info dialog opens (Figure 16-16 on page 329) In the dialog:






Enter EncryptionInfo_2 as the Encryption name. Leave the default algorithm methods. Enter alice as the Encryption key name Enter SampleSenderEncryptionKeyLocator as the Encryption key locator. Click OK. Note: The definitions for SampleSenderEncryptionKeyLocator are part of the default Web services security bindings, but only the public key is defined.

Save the changes. The modifications in the ibm-webservicesclient-bnd.xmi file are shown here: ....

330

WebSphere Version 5.1 Web Services Handbook

Defining server confidentiality We have to configure the server to match both configurations. Open the webservices.xml file and select the Security Extensions page. Select the WeatherForecastEJB port. Under Request Receiver Service Configuration Details, expand Required Confidentiality and add bodycontent and usernametoken. Under Response Sender Service Configuration Details, expand Confidentiality and add bodycontent (the same as for the client configuration). Save the changes. The modifications in the ibm-webservices-ext.xmi file are shown here: .... .... ....

To configure the binding information for the server we follow similar steps to those used when we configured the client. On the Binding Configurations page select the WeatherForecastEJB port. Expand Request Receiver Binding Configuration Details and Encryption Information and click Add. The encryption info dialog opens (Figure 16-16 on page 329). In the dialog:






Enter EncryptionInfo_1 as the Encryption name Leave the default algorithm methods. Enter bob as the Encryption key name. Enter SampleReceiverEncryptionKeyLocator as the Encryption key locator. Click OK.

Save the changes. The modifications in the ibm-webservices-bnd.xmi file are shown here: ....

Chapter 16. Web services security with Application Developer

331



We define the encryption bindings for the server response message. Expand Response Sender Binding Configuration Details and Key Locators and click Add. The key locator dialog opens (Figure 16-12 on page 318). In the dialog:
Enter SampleReceiverEncryptionKeyLocator as the Key locator name.
Select com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator as the Key locator class.
Select Use key store.
Enter storepass as the Key store storepass.
Enter ${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-receiver.jceks as the Key store path.
Enter JCEKS as Key store type.
Click Add under Key. Enter Group1 as the Alias, keypass as the Key pass, and CN=Group1 as the Key name.
Click OK. You can find the valid aliases using the keytool on the enc-receiver.jceks file (see “Exploring a key store file using the keytool” on page 319, use the password storepass, use -storetype JCEKS). There are key entries called alice, group1, and bob. Note that alice is the trusted key for the server. Finally, we have to specify the algorithm that we use to encrypt the information. Expand Response Sender Binding Configuration Details and Encrypt Information and click Enable. The encryption info dialog opens (Figure 16-16 on page 329). In the dialog:






332

Enter EncryptionInfo_2 as the Encryption name. Leave the default algorithm methods. Enter CN=Alice, O=IBM, C=US as the Encryption key name. Select SampleReceiverEncryptionKeyLocator as the Encryption key locator. Click OK.

WebSphere Version 5.1 Web Services Handbook

Save the changes. The modifications in the ibm-webservices-bnd.xmi file are shown here: .... ....

Configuring the server for confidentiality Before we can test confidentiality we have to configure the WeatherServer. This configuration cannot be done using the standard configuration editor; we have to use the Administrative Console. We have to include the private key we use to encrypt the SOAP messages in the SampleSenderEncryptionKeyLocator:
Open the WeatherServer configuration and on the Configuration page select Enable administration console, then save and close.
Restart the WeatherServer.
Select the server and Run administrative console (context). A Web browser opens with http://localhost:9090/admin.
Accept the certificate when prompted and enter a valid user ID and password (use the values entered on the Security page).
Select Servers -> Application Servers -> server1 (wait until server1 appears).
Under Additional Properties select Web services: Default bindings for Web Services Security.
Select Key Locators -> SampleSenderEncryptionKeyLocator. Under Additional Properties select Keys and click New (Figure 16-17).

Chapter 16. Web services security with Application Developer

333

Figure 16-17 Private key configuration for sender


Enter CN=Alice, O=IBM, C=US as the Key Name, alice as the Key Alias, keypass as the Key Password, and click OK. Apply the new configuration in the master configuration; select Save in the Message(s) frame and click Save. As we have done for the private key in the client, we define the private key to decrypt the messages in the SampleReceiverEncryptionKeyLocator:
Select Web services: Default bindings for Web Services Security -> Key Locators -> SampleReceiverEncryptionKeyLocator. Under Additional Properties select Keys and click New.
Enter CN=Bob, O=IBM, C=US as the Key Name, bob as the Key Alias, keypass as the Key Password, and click OK.
Save the configuration by selecting Save in the top menu. Click Save.

Testing confidentiality, integrity, and authentication Restart the WeatherServer to activate the changes, then run the TestClient.jsp (in ItsoWebService6EJBClient). Select the getDayForecast method, enter a date, and click Invoke. In the TCP/IP Monitor we can see the SOAP messages, and now how the information is encrypted in the SOAP message. Example 16-7 and Example 16-8 show the SOAP messages sent by the client and server, respectively. Example 16-7 Message sent by the client with confidentiality, integrity and authentication ....

334

WebSphere Version 5.1 Web Services Handbook

/62wXObED7z6c1yX7QkvN1thQdY= UcPSKrpohBb3oOblReTIeZHWepMZnTGO....TWJu/VHlyF6wtGZDBERh2O2NU= .... c6GbasJU/OZ8hbdr....TXHUmig== cc1V//9/+mT2GerGLrCb2q7O....3YfHO8v/A==

Chapter 16. Web services security with Application Developer

335

Example 16-8 Message response delivered by the server with confidentiality and integrity .... .... UcPSKrpo....HlyF6wtGZDBERh2O2NU= .... c6GbasJU/OZ8hbd....CEfTXHUmig== .... .... cc1V//9/+mT2....ULAtArgNw4I4I3YfHO8v/A== ....

Note that the SOAP body is now encrypted and completely unreadable. However, the test client displays the result. Stop the server when finished.

Resetting the server configuration and client proxy Open the WeatherServer configuration:
Deselect Enable administration console on the Configuration page.
Switch off security on the Security page if you want to run the other enterprise applications.
Remove the trace setting on the Trace page by changing the Trace string to *=all=disabled. Also reset the destination address in the WeatherForecastEJBServiceLocator proxy in the ItsoWebService6EJBClient project (from port 9081 to 9080).

Trace output You can find the server trace output in this directory: \.metadata\.plugins\com.ibm.etools.server.core\tmp0\logs\server1

336

WebSphere Version 5.1 Web Services Handbook

J2EE security and WS-Security relationship J2EE security can be applied to secure Web services. We have to understand that J2EE security is not message-level security, like the security we applied in this chapter. By contrast, J2EE security is based on SSL transport security and J2EE role-based security. J2EE security is the security applied in Web services for the J2EE specification; see Chapter 5, “Implementing Enterprise Web Services (JSR 109)” on page 77. The Web service endpoint is secured using J2EE role-based security. The client can provide HTTP basic authentication in the HTTP header and also use SSL to secure the transport level. Once the message arrives to the Web service endpoint, the Web container authenticates the user using the value provided by the HTTP header and sets the security context for the call. That security context is propagated through the different required modules to complete the client request. WS-Security can be used for any scenario. If we have a Web service using JMS, only WS-Security can provide a way to propagate security tokens. WS-Security does not contrapose to J2EE security. In contrary, WS-Security complements and leverages J2EE role-based security. We can use SSL to transport a message over HTTP that includes SOAP message security. We also can use the EJB authorization process because WS-Security sets the security context for the call—once the user is authenticated—and propagates that context to the EJB. Using a process like that for a Web service, we can differentiate among clients. Depending on the client profile, we verify the authorized methods for that client at run time.

Summary In this chapter we presented the basic functionality that can be used to apply message-level security to Web services using Application Developer 5.1, the primary tool to specify security. This security is applied to JSR 101 and JSR 109 Web services, built in Application Developer 5.1.1 to run in WebSphere Application Server 5.1. WS-Security brings flexible options to specify different levels of security. We have reviewed the options to apply authentication, integrity, and confidentiality to existing Web services. First, we introduced the authentication mechanisms, followed by integrity, and finally implemented confidentiality.

Chapter 16. Web services security with Application Developer

337

We have also reviewed how we can trace SOAP messages with a TCP/IP Monitor and what security information is included in the headers of those messages. We have seen how a client can be modified to be a container management client, the only client type supported for security. Finally, we have discussed how WS-Security integrates with J2EE authentication and role-based authorization security and how both of them can work together. The tables that follow show the different security configurations we can apply to secure a Web service with message level security:
Table 16-1—Shows client server security extensions’ possibilities for the request message
Table 16-2—Shows client server security bindings’ possibilities for the request message
Table 16-3—Shows server client security extensions’ possibilities for the response message
Table 16-4—Shows server client security bindings’ possibilities for the response message Table 16-1 Client and server service extension configuration for request

338

securityRequestSenderServiceConfig

securityRequestReceiverServiceConfig

loginConfig AuthMethod

loginConfig AuthMethod

Integrity Body SecurityToken TimeStamp

Integrity Body SecurityToken TimeStamp

Confidentiality BodyContent UserNameToken

Confidentiality BodyContent UserNameToken

IDAssertion IDType valid username, DN or X509Cer TrustMode BasicAuth or Signature

IDAssertion IDType valid username, DN or X509Cer TrustMode BasicAuth or Signature

AddCreatedTimeStamp true or false expires

AddReceivedTimeStamp true or false

WebSphere Version 5.1 Web Services Handbook

Table 16-2 Client and server service extension configuration for response securityResponseReceiverServiceConfig

securityResponseSenderServiceConfig

Integrity Body TimeStamp

Integrity Body TimeStamp

Confidentiality BodyContent

Confidentiality BodyContent

AddReceivedTimeStamp true or false

AddCreatedTimeStamp true or false expires

Table 16-3 Client and server binding configuration for request securityRequestSenderBindingConfig

securityRequestReceiverBindingConfig

SigningInfo SignatureMethod CanonicalizationMethod DigestMethod SigningKey or CertPathSettings

SigningInfos SignatureMethod CanonicalizationMethod DigestMethod SigningKey or CertPathSettings

EncryptionInfo DataEncryptionMethod KeyEncryptionMethod EncryptionKey

EncryptionInfos DataEncryptionMethod KeyEncryptionMethod EncryptionKey

KeyLocators (0 or more) KeyStore, Key, Property

KeyLocators (0 or more) KeyStore, Key, Property

LoginBinding AuthMethod TokenValueType CallBackHandler

LoginMapping AuthMethod TokenValueType CallBackHandler TrustedIDEvaluator or TrustedIDEvaluatorRef TrustAnchors KeyStore CertStoreList LDAPCertStore or CollectionCertStore

Chapter 16. Web services security with Application Developer

339

Table 16-4 Client and server binding configuration for response securityResponseReceiverBinding Config

securityResponseSenderBindingConfig

SigningInfo SignatureMethod CanonicalizationMethod DigestMethod SigningKey or CertPathSettings

SigningInfos SignatureMethod CanonicalizationMethod DigestMethod SigningKey or CertPathSettings

EncryptionInfo DataEncryptionMethod KeyEncryptionMethod EncryptionKey

EncryptionInfos DataEncryptionMethod KeyEncryptionMethod EncryptionKey

KeyLocators (0 or more) KeyStore, Key, Property

KeyLocators (0 or more) KeyStore, Key, Property

TrustAnchors KeyStore CertStoreList LDAPCertStore or CollectionCertStore

More information The best source for more and updated information is the WebSphere Application Server Information Center: http://www.ibm.com/software/webservers/appserv/infocenter.html

Expand Securing -> Applications -> Web services.

340

WebSphere Version 5.1 Web Services Handbook

17

Chapter 17.

Application Developer Integration Edition WebSphere Studio Application Developer, introduced in the previous chapters, provides the support for developing, testing, and publishing Web services, and writing clients that use the Web services. Application Developer Integration Edition adds more sophisticated support, by providing a development environment for enterprise services and business processes. The main purpose of the Integration Edition is to provide development features used for applications running on WebSphere Application Server Enterprise Edition. Because the Integration Edition extends the function of Application Developer, this chapter only presents the additional features:






Enterprise services Resource adapters Business Integration perspective Business processes Development and testing of a sample business process Important: Application Developer Integration Edition was still at Version 5.0 when this book was updated. Therefore we did not change this chapter.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

341

Enterprise services The service-oriented architecture takes existing software components residing on the network and allows them to be published, discovered, and invoked by each other. The service-oriented architecture allows a software programmer to model programming solutions in terms of services offered by components to anyone, anywhere over the network. Therefore, existing software components are wrapped as services, and these services can communicate with other applications through a common interface. Like Web services, enterprise services offer access over the Internet to applications in a platform-neutral and language-neutral fashion. In addition, they offer access to enterprise information systems (EIS) and message queues, and can be used in a client/server configuration without the Internet. Enterprise services can access applications and data on a variety of EIS systems and in a variety of formats. And these services can be combined to form a new service. Software components wrapped as an enterprise service can be bound to use a range of protocols, including SOAP, IIOP, JMS, JCA, EJB, and Java native bindings. They are primarily used for wrapping connections to enterprise information systems. The concept of enterprise services extends the Web service model by using new open standard technologies, such as the Web services invocation framework (WSIF), to communicate to an endpoint. Enterprise services can be described in WSDL files using non-SOAP binding information. Some sources also use the term enterprise Web services in contrast to Internet Web services. Enterprise services can be developed in WebSphere Studio Application Developer Integration Edition.

Creating an enterprise service: Bottom-up When using the bottom-up approach to develop an enterprise service, you are primarily importing artifacts to generate the enterprise services for them. Besides generating services for artifacts supported by Application Developer, such as Java classes and EJBs, the Integration Edition can also generate enterprise services that support the following resource adapters:






342

CICS ECI CICS EPI Host On-Demand 3270 IMS™ Imported customized EIS JCA resource adapters

WebSphere Version 5.1 Web Services Handbook

The main steps to create and install an enterprise service are:






Create a service project. Develop or import the implementation into the service project. Generate the enterprise service by using the service wizard. Generate the deployed code (wrapper classes). Deploy the enterprise service as an EAR file to an application server.

Creating an enterprise service: Top-down You can develop enterprise services using a top-down approach by first creating the service definition and then adding the implementation for the service. Assuming that you have a WSDL file that contains the service interface definitions (port types, operations, and messages), you can follow these steps to add bindings and port definitions for the service and generate either a Java or EJB skeleton for the implementation of the service:
Create a service project.
Import the interface files (WSDL).
Create an EJB project if an EJB skeleton is to be generated (this step is not necessary when creating a simple Java skeleton).
Generate the service skeleton using the New Service Skeleton wizard, found by clicking New- > Other -> Business Integration -> Build from service.
Implement the business logic in the skeleton.
Deploy the service as an EAR file to an application server.

Resource adapters The J2EE Connector Architecture (JCA) is a standard way for a Java component to connect to any enterprise system. It is part of the J2EE standard, introduced in the J2EE 1.3 specification. WebSphere Application Server 5 is J2EE 1.3 compliant and therefore supports the connector architecture. The JCA states that the way an application server communicates with an enterprise system (such as CICS) is through a resource adapter. A resource adapter is written specifically for the enterprise system it supports, but the same resource adapter can be plugged into any application server. Resource adapters represent a middle tier that allow Java clients to communicate with enterprise information systems (EIS) such as CICS and IMS. A Java client that interacts with an EIS uses a resource adapter specific for that EIS. For example, a client connecting to IMS requires an IMS resource adapter.

Chapter 17. Application Developer Integration Edition

343

The Java client uses the common client interface (CCI) API to communicate with the resource adapter. The resource adapter in turn interprets the CCI request, and interacts with the EIS using a protocol native to the EIS. If a Java client calls a program running in CICS, the Java client uses the CCI API to send a request to the CICS ECI resource adapter, specifying the CICS program and server to call. Figure 17-1 illustrates how resource adapters are used by services to access legacy systems.

Client

Application Server

EIS

Application

Front end

Enterprise Service CCI

Resource adapter

native

Legacy application and data

Figure 17-1 Using resource adapters to access legacy applications or data

Resource adapters run in a J2EE application server, such as WebSphere Application Server. The application server can manage the connection between resource adapter and EIS, allowing it to perform connection pooling, security propagation, and transactions. IBM provides JCA adapters for CICS, IMS, and Host On-Demand (HOD). Other companies provides JCA adapters for a range of products, such as SAP, PeopleSoft, Siebel, and Oracle ERP. A list of JCA adapters is provided at: http://java.sun.com/j2ee/connector/products.html

Using Application Developer Integration Edition In this section we discuss the enterprise services development environment provided by Application Developer Integration Edition.

344

WebSphere Version 5.1 Web Services Handbook

Business Integration perspective The Business Integration perspective configures the layout of the Workbench to facilitate the development of enterprise services. The perspective contains views of Workbench resources that you would typically use when you develop enterprise services. Figure 17-2 shows the Business Integration perspective with two important parts that support Web services:
Services view
WSDL editor

Figure 17-2 Business Integration perspective

The Business Integration perspective introduces the service project. A service project holds the implementation of a service as well as meta information about the service and deployed code. The deployed code is a wrapper around the implementation to make it callable through specific bindings. Depending on the type of binding, the deployed code can be either an EJB (for IIOP clients), a SOAP wrapper (Web service), or a JMS wrapper (for asynchronous access).

Chapter 17. Application Developer Integration Edition

345

This Business Integration perspective offers several wizards that can be used to create enterprise services, and all artifacts that they require, such as service projects, business processes, wrapping and exposing of existing implementations.

Services view The Services view displays the service resources. The view presents two folders:
Service Projects—Contain service definitions, as well as other supporting resources, such as Java, COBOL, and C source files
Deployable Services—Contain the resources that can be deployed, which are the generated EJBs or Web services that wrap the actual implementation There are several ways to launch the tool components from the perspective. The quickest path is to launch them through the tool bar that the perspective offers. Another way is through pop-up menu choices and a resource creation window.

Enhanced WSDL editor In Integration Edition you can edit an enterprise service WSDL file using the enhanced WSDL editor. This editor visualizes the complex information of a WSDL file in a much better way than a normal XML editor. Figure 17-3 shows a page of the WSDL editor viewing the weather forecast sample.

Figure 17-3 WSDL editor in Integration Edition

346

WebSphere Version 5.1 Web Services Handbook

Note that the Outline view is connected to the editor and allows a quick navigation within the file. As per default, this editor is used when opening a WSDL file. You can explicitly start the editor by selecting a WSDL file and Open With -> WSDL Editor. The name of the WSDL file that is open is shown on the tab at the top of the WSDL editor view. You can have more than one WSDL file opened in the editor. Each file shows up as a separate tab at the top of the Editor pane. Often you split a WSDL document into two or three files to separate service, binding, and interface information. The linkage between these corresponding WSDLs is maintained by the editor, and whenever you access some information that is provided in another file, that file is opened automatically.

Business process There are a number of artifacts and components that can be exposed as services. Web services, JavaBeans, and enterprise beans can all be used to implement certain pieces of your business. The combination of more than one of such services is called a business process. A business process is the outcome of choreographing and combining services together. A business process is also often a single activity from a client point of view. The client is not aware of all the internal actions (services) that are required to perform the function. Integration Edition allows you to model such business processes in an easy way. These business processes themselves can then be deployed and exposed as new enterprise services for clients. For example, if you have an existing application composed of enterprise beans, and you want to integrate it with another application composed of enterprise beans, you can easily create a business process to define the integration in a flexible way. If you have an existing application and you want to add functionality available as a Web service, you can use a business process to integrate the enterprise bean application and the Web service. In either case you can add the activity that best represents your existing implementation and the business process will work in the same way regardless of the underlying implementation.

Process editor The process editor is a graphical modeling environment used to design processes that execute individual activities in a predetermined sequence to fulfill an overall business goal. The process execution begins at an input activity and

Chapter 17. Application Developer Integration Edition

347

progresses through other activities to the output activity. The activities in between describe either service or non-service specific operations:
Service-specific operations are described using Web services definition language (WSDL). There are three parameters to each service: The service name, the port type, and the operation.
Non service-oriented objects include JavaBean, EJB, event, or staff (people) activities.

Elements of the process Here is a list of process elements:
Input activity—The input activity is the source and starting point of the process, and can have any number of outgoing controls. The input activity is created automatically by the editor, and only one can be used per process.
Output activity—The output activity is the end of the process. For a synchronous process the output activity returns a variable to the caller. An output activity may also call a service passing a variable as parameter.
Control links—Control links dictate the sequence in which the flow's activities are executed. They are represented graphically by solid blue arrows.
Java snippet activity—Use this activity to write custom Java code to manipulate and prepare variables, for example, to transform output data of one activity into input data of another activity.
Invoke service activity—This is an activity that invokes an external Web service (any artifact with a service interface) as part of the business process.
Invoke Java activity—Use the Java activity to make a call to a Java class within your business process.
Invoke process—An activity that represents a separate business process that is being invoked within a larger one. Unlike the block activity, the process activity is a complete process, and can exist on its own outside of the primary process, and be used by other processes.
Invoke EJB—Use the EJB activity to make a call to an enterprise bean, and use its activity as a part of the process.
Empty activity—An empty activity has no defined implementation and can be used as a place holder in the design stage, and fleshed out later, or when a fault needs to be caught and suppressed.
Fault activity—The fault activity is used when a business process fails. It can throw an exception to the caller (synchronous), or it can call a separate service passing a variable as the message.
Block activity—Use the block activity to simplify the diagram by decomposing the process into individual distinct portions, each representing an entire

348

WebSphere Version 5.1 Web Services Handbook

nested business process that runs within a larger one. To open the process that the block activity represents, you can double-click it or you can select Open in New Page from the context menu.
Loop activity—This activity is a specialized form of a block that can be iterated so that the operation executes more than once during the flow. The execution of the loop is controlled by a conditional expression, and continues to execute as long as this conditional expression evaluates to true.
Staff activity—This is an activity that requires human input to decide how to proceed.
Receive event activity—The event activity represents an activity in the business process that waits for one or more external events to happen before continuing.
Text object—This is an activity that displays a message of your choice on the editor for documentation purposes.

Dynamic process properties Process dynamics refers to the manner in which a process runs from start to finish. Your process can include any of the following:
Looping—Repeats a specific operation and does not proceed until certain conditions are met
Asynchronous vs. synchronous processes—Determines whether the process returns a response
Throwing faults—Uses faults to deal with exceptions that you expect the process may encounter
Compensation service—Uses a compensation service to determine what to do with committed activities in the event of a rollback later in the process
Interruptible vs. non-interruptible processes—A process is interruptible if it stops for an external activity
Event activity—Uses an event to halt the process and wait for a predefined external event to occur
Correlation methods—Uses correlation methods with an event activity to instruct the runtime how to differentiate individual business processes in a multi-executed business process environment
Staff activities—Uses a staff activity to direct the process to a person and wait for human input before continuing Compare the list of elements with the description in “Business process execution language for Web services” on page 165.

Chapter 17. Application Developer Integration Edition

349

Sample business process This section covers how to model a business process using the Business Integration perspective. The example takes a week number as input and returns the temperature in degrees Fahrenheit of the first day in that week. The example uses the weather forecast service described in earlier chapters. Unfortunately the original service shows the temperature in degrees Celsius. Therefore we have to integrate another service, TemperatureCalculator, into the flow. This service translates between Celsius and Fahrenheit by taking a temperature value and converting it. Therefore, the steps in the sample process are:






Convert the week number into a concrete date. Call the original weather forecast Web service to retrieve a Weather object. Extract the temperature in degrees Celsius. Invoke another Web service to convert from Celsius to Fahrenheit. Return the temperature in Fahrenheit.

Prepare existing services Because we are building a business process from a number of existing services, we have to either create them first or at least make sure that they are accessible:
If the services are EJBs or Web services running in the same enterprise application, you might want to check the corresponding projects.
If your are going to use external services, you just have to make sure that you have the WSDL files specifying their interfaces. In our example, the external services for weather forecast and temperature calculation are placed in a separate Web module within the same enterprise application project to make testing and starting of servers simpler.

Create a service project First of all, you have to create a service project using File-> New -> Other -> Service Project. This project will hold all the artifacts and metadata that you use to model the process. Figure 17-4 shows the creation wizard. You typically create a project with a suffix such as Service to distinguish it from the Web and EJB projects that are created in a later step.

350

WebSphere Version 5.1 Web Services Handbook

Figure 17-4 Create a service project

Import existing Web services Before we can work with existing—and maybe external—services, we have to import their WSDL files into the service project, so that we can use them while modeling the process flow. Either these WSDL files can be imported from another project or file system, because you are using your own services, or they have to be obtained by the service provider directly or through a UDDI registry. In our case, we have an enterprise application (ItsoWebServBaseEAR) with two Web projects (ItsoWebServWFWEB and ItsoWebServTCWEB) either already in the workspace, or we import them from EAR/WAR files:
Select File -> Import -> EAR File, then click Browse and locate the file: sg246891-01\sampcode\wsadie\ItsoWebServBaseEAR.ear


Enter ItsoWebServBaseEAR as the project name.
Select Preserve project names, classpath, and meta-data included in the EAR and click Finish. If you import the EAR without the Preserve project names option, you get errors after import. In this case, select each Web project and Properties, and on the Libraries page click Add Variable and add the SOAPJAR variable. This action should remove the error messages from the Tasks view. Before continuing, it is a good idea to test that the services are up and running, either with the universal test client or a sample client. The Web modules also include the WSDL files, which are located inside the Web projects. To test, you would have to define a server, but you can wait to test until you define a server for the testing of the sample process.

Chapter 17. Application Developer Integration Edition

351

Existing Web services The ItsoWebServWFWEB project contains the weather forecast service, the same service we developed in Chapter 15, “WebSphere Studio Application Developer” on page 247. The only difference is the project name and therefore the access point in the service WSDL file: http://localhost:9080/ItsoWebServWFWEB/servlet/rpcrouter

The ItsoWebServFTCWEB project contains the temperature calculator service, which converts between degrees Celsius and Fahrenheit. We will use the convertCelsiusToFahrenheit method in our example.

Set up WSDL files of existing services Next we create folders within the service project and import or copy the WSDL files and associated XSD files. In the Business Integration perspective we can find them in the Services view, as shown in Figure 17-5.

Copied from ItsoWebServWFWeb

Copied from ItsoWebServTCWeb

Figure 17-5 Services view with the WSDL files that will be used in the process

Create the business process The next step is to create a new business process. We use the wizard, which can be started using File -> New -> Business Process. Then we have to specify a project, package, and file name for the process, as shown in Figure 17-6.

352

WebSphere Version 5.1 Web Services Handbook

Figure 17-6 Create a new business process

Every business process must have an input and an output operation. The input operation is called to start the process. If the service is synchronous, the input operation can return the result. If the service is asynchronous, the result of the business process can be sent to another operation that can act upon the result. If you had defined operations for the business process, you could specify them at this time in a top-down design. Because we do not have defined operations that our process must implement, we accept the default on the next wizard page and select Define business process interface later. Click Finish. The graphical business processor editor opens and displays an Input and Output node, as shown in Figure 17-7.

Figure 17-7 Initial state of new business process

Chapter 17. Application Developer Integration Edition

353

On the left side of the editor is a palette of items you can use for modeling the process. Note that there are a number of warnings both in the graphical design as well as in the Tasks view. They indicate that the process is not finished yet and disappear when we complete the process flow. The editor has a number of tabs:
The Process tab shows the graphical representation.
The Interface tab defines the input and output operations of the process. We did not define them yet in the wizard, so it shows an error. In that tab you can also define operations corresponding to faults that you may handle within the business process. Finally events can be defined that require requests to be processed between the beginning and end of a business process.
On the Server tab, there are a number of settings specified for running the business process in production. These settings can be modified when the business process is deployed to WebSphere Application Server 5 Enterprise Edition.
On the Variables tab, you can specify variables to maintain state as your process is completed. Variables are a very important part of a business process because they are used for holding information between calls to the different services and artifacts that make up the process. Initially an input and an output variable are defined.
On the Staff tab, you can define roles with certain levels of permission for different people.
On the Client tab, JSP attributes can be defined for testing the process using a Web client.

Adding services to the process An easy way to add services to a process is by dragging and dropping the appropriate WSDL files to the process space. We already imported the WSDL files to the service project, so we find them in the Services view. Note that there are three WSDL files for each service. The most interesting is the file that typically contains the word Service in it, because it is the root document and imports the others. When we drop a service WSDL file on the white area, a window pops up (as shown in Figure 17-8), where you can define which of the services, port types, and operations you want to use at this point. We add two services: The WeatherForecast and the TemperatureCalculator.

354

WebSphere Version 5.1 Web Services Handbook

Figure 17-8 Select service, port type, and operation to add a service

Adding flow to the process To add flow into the process, we can use the graphical process editor. In the palette you select Control Link, then click first the output terminal (the arrow on the right of the icon) of one service, and then click the input terminal (the arrow on the left of the icon) of another service. In general we want to pass the weather information from the weather forecast service to the temperature calculator service, and the calculator result to the output. After connecting all the services and the input and output nodes, the first draft of our process is shown in Figure 17-9.

input terminal

output terminal

Figure 17-9 Flow between the activities

Chapter 17. Application Developer Integration Edition

355

Besides sequential flows between services, you can also model loops and conditions that decide which part of the flow should be executed. For simplicity reasons they are not covered in this chapter. However, the process is not finished yet. We just connected the two services by a control link, but we totally ignored the fact that these two services require their input parameters in a specific data type:
Our business process has an integer (week number) as input, but the WeatherForecast requires a date.
Also, the WeatherForecast returns a Weather object as a result, and the TemperatureCalculator requires an integer (the temperature value inside the Weather object). There are two things to do to solve the problem:
Define variables for the input and output messages of the activities.
Insert a converter between the services to handle the data types.

Messages and variables When a service is called within a business process, a message is returned. The message is stored within a variable that you can specify. From this variable you can extract parts and map it to parts in other messages, which are sent to other services within the process. Often you have to place a mapping between two messages. This can be done either by a transformation service or by simple Java code. We will do the latter one for our process. In the Properties window of a service that can be reached using the context menu, there is a section called Implementation that specifies the messages and variables associated with the in- and outbound terminals of that service. The concrete message that is used is defined in the WSDL document of the service and cannot be changed. In the case where one operation has defined the same output message as the next service input message, you would not have to specify anything. Of course this is not the case in general and we have to implement converters:
We define a variable for the output message of the first activity.
We define a variable for the input message of the second activity.
We write a converter that fills the second variable with data of the first variable.

356

WebSphere Version 5.1 Web Services Handbook

WSDL

WSDL

Service A Operation 1

Response Message 1

Service: WeatherForecast Operation: getDayForecast

getDayForecast Response (Weather object)

Java Variable in Process

Java Code or Transformer

Java Variable in Process

Variable1

Converter

Variable2

Weather object

int tempC = weather. getTemperature()

int

WSDL

Request Message 2

convertCelsiusTo FahrenheitRequest (int)

WSDL

Service B Operation 2

Service: TemperatureCalculator Operation: convertCelsius.. ToFahrenheit

Figure 17-10 Using variables for conversion between messages

Figure 17-10 illustrates the chain of objects.
The middle row shows the elements in the process.
The upper row describes where and how these elements are specified.
The bottom row shows the names in our example. The services (activities) have been added to the process and the messages are defined in the WSDL file of each service. We now have to specify the variables for the input and output messages and implement a converter. In the Properties window of the getDayForecast, we find the variable bindings in the section called Implementation:
We select the correct types for each message. Because we know that the getDayForecast method returns a Weather object, we can select the Weather XML schema for the getDayForecastResponse, indicated with (1) in Figure 17-11.
There is also another—more general—way. You do not select the concrete Weather.xsd file, because you might not even have the XML schema file. The schema information is also included in the WSDL file. So the general approach is to select the WSDL file that defines the messages—in our case WeatherForecast.wsdl—and select the getDayForecastResponseMessage (which in fact contains one part, namely a Weather object) as indicated with (2) in Figure 17-11. Using the second approach you define variables for input and output terminals for both Web service calls:





getDayForecastRequest—Input of weather forecast getDayForecastResponse—Output of weather forecast convertCelsiusToFahrenheitRequest—Input of calculator convertCelsiusToFahrenheitResponse—Output of calculator

Chapter 17. Application Developer Integration Edition

357

(1)

(2)

Figure 17-11 Defining variables for in- and outbound messages of operations

358

WebSphere Version 5.1 Web Services Handbook

Figure 17-12 shows the variables defined for the getDayForecast service.

Figure 17-12 Variables for input and output

The input parameter for the business process is the week number. We use the predefined variable input for this, and its default type of Int is what we require for the process. Figure 17-13 shows the complete set of variables in the Variables tab.

Figure 17-13 Process variables

Chapter 17. Application Developer Integration Edition

359

Note the input and output variables. They define the data types of the input parameter and the result of the operation. The default of Int for both variables is exactly what we want for this process. Save the diagram. A number of Java classes are generated:
itso.wsie.temperature—The Java code for the process itself
wsdl.itso.wsoj.WeatherForecast_msg—A package with two message classes for the input and output messages (GetDayForecastRequestMessage and GetDayForecastResponseMessage)
wsdl.itso.wstc.TemperatureCalculator_msg—A package with two message classes (ConvertCelsiusToFahrenheitRequestMessage and ConvertCelsiusToFahrenheitResponseMessage)

Extract of generated code The temperature class provides the Java code to get and set the variables used in the business process. Some of the generated methods are:
getInput—Retrieves the input variable. This method returns an IntMessage from which the int value can be extracted: public org.xmlsoap.schemas.wsdl.wsadie.messages.IntMessage getInput() throws com.ibm.bpe.api.ProcessException { return new org.xmlsoap.schemas.wsdl.wsadie.messages.IntMessage( (WSIFMessage) readBPEVariable("input")); }


setGetDayForecastRequest—Sets the input variable for the getDayForecast activity by passing a message variable: public void setGetDayForecastRequest( wsdl.itso.wsoj.WeatherForecast_msg.GetDayForecastRequestMessage message) throws com.ibm.bpe.api.ProcessException { updateBPEVariable("getDayForecastRequest", message.message()); }


getGetDayForecastResponse—Retrieves the output variable of the getDayForecast activity: public wsdl.itso.wsoj.WeatherForecast_msg.GetDayForecastResponseMessage getGetDayForecastResponse() throws com.ibm.bpe.api.ProcessException { return new wsdl.itso.wsoj.WeatherForecast_msg.GetDayForecastResponseMessage( (WSIFMessage) readBPEVariable("getDayForecastResponse")); }

360

WebSphere Version 5.1 Web Services Handbook

The two messages associated with the getDayForecast activity are generated into the wsdl.itso.wsoj.WeatherForecast_msg package. The GetDayForecastRequestMessage class contains the input data of the Web service, a Date object, with getter/setter methods: public class GetDayForecastRequestMessage extends com.ibm.wsif.jca.util.WSIFMessageImpl { public GetDayForecastRequestMessage(WSIFMessage message) { super(message); } public GetDayForecastRequestMessage() { super(); } public java.util.Date getTheDate() { try { return (java.util.Date) super.getObjectPart("theDate"); } catch (WSIFException exc) { throw new java.lang.IllegalArgumentException(exc.toString()); } } public void setTheDate(java.util.Date newValue) { try { super.setObjectPart("theDate", newValue); } catch (WSIFException exc) { throw new java.lang.IllegalArgumentException(exc.toString()); } } }

The GetDayForecastResponseMessage class contains the output data of the Web service, a Weather object, with getter/setter methods: public class GetDayForecastResponseMessage extends com.ibm.wsif.jca.util.WSIFMessageImpl { ..... // constructors public itso.wsoj.Weather getResult() { try { return (itso.wsoj.Weather) super.getObjectPart("result"); } catch (WSIFException exc) { throw new java.lang.IllegalArgumentException(exc.toString()); } public void setResult(itso.wsoj.Weather newValue) { try { super.setObjectPart("result", newValue); } catch (WSIFException exc) { throw new java.lang.IllegalArgumentException(exc.toString()); } } }

Chapter 17. Application Developer Integration Edition

361

Process files The process flow information is stored in two files in the itso.wsie package.

Process file: temperature.process The temperature.process file is an XML file that stores the graphical information about the definition of the process, including the variables and conditions on the control links.

FDML file: temperature.fdml The temperature.fdml file uses the flow definition markup language (FDML) to store information about the activities, links, and messages. We examine the file in “Flow definition markup language” on page 368.

Adding Java snippets After we have defined variables for all necessary input and output messages, we have to implement the converters that translate the output of one node into the input of the next node. The easiest way to achieve this is by writing Java snippets, which in fact become methods in the process class. These snippets have access to all the variables defined in the process:
At the beginning of the flow there is a snippet that creates a Date object from the input week number.
One snippet translates the Weather object from the getDayForecast method of the WeatherForecast service into an int for the convertCelsiusToFahrenheit method of the TemperatureCalculator service.
We also added a final snippet at the end of the process to trace some output messages. To add a snippet between two operations:






Add a Java Snippet object from the palette. Select Rename (context) to change the default name to a nice name. Delete the old control link. Connect the output terminal of the previous node to the input of the snippet. Connect the output of the snippet to the input of the next node. Note: You can also grab the endpoint of a link and move it to another terminal.

To edit the Java code, select the Java snippet icon and Show Java (context) or click Show Java in the selection bar. In the source code pane underneath the process flow, you can update the code that is executed in that process step.

362

WebSphere Version 5.1 Web Services Handbook

Figure 17-14 shows the new process with the Java snippets connected with new control links. In the source pane you see the source code of the selected snippet, prepareDate, which shows how to access variables.

Figure 17-14 Adding Java snippets for conversion between messages

There are three snippets to implement:
prepareDate—Take the week number of the process input and calculate a date for the getDayForecast method: // retrieve week number from process input int weekNr = getInput().getValue(); // calculate date of monday in that week Calendar cal = Calendar.getInstance(); cal.setFirstDayOfWeek(java.util.Calendar.MONDAY); cal.set(java.util.Calendar.WEEK_OF_YEAR, weekNr); // create message for service and pass that date to getDayForecast GetDayForecastRequestMessage gdfr = new GetDayForecastRequestMessage(); gdfr.setTheDate(cal.getTime()); setGetDayForecastRequest(gdfr);

Chapter 17. Application Developer Integration Edition

363


extractDegrees—Extract the temperature out of the Weather object and pass it to the convertCelsiusToFahrenheit method: // get the weather response of getDayForecast Weather w = getGetDayForecastResponse().getResult(); // extract the temperature int degreeCelsius = w.getTemperatureCelsius(); // create new message and pass temperature to convert ConvertCelsiusToFahrenheitRequestMessage request = new ConvertCelsiusToFahrenheitRequestMessage(); request.setCelsius(degreeCelsius); setConvertCelsiusToFahrenheitRequest(request);


traceResults—Trace the results and set the output value of the process: Weather w = getGetDayForecastResponse().getResult(); System.out.println("traceResult: result of forecast weather=" +w.getDate()+"/"+w.getTemperatureCelsius()+"/"+w.getCondition()); int degreesCelsius = getGetDayForecastResponse().getResult().getTemperatureCelsius(); int degreesFahrenheit = getConvertCelsiusToFahrenheitResponse().getResult(); System.out.println("traceResult: result of Fahrenheit Calculator=" +degreesCelsius+"-->"+degreesFahrenheit); // set output value org.xmlsoap.schemas.wsdl.wsadie.messages.IntMessage outmsg = new org.xmlsoap.schemas.wsdl.wsadie.messages.IntMessage(); outmsg.setValue(degreesFahrenheit); setOutput(outmsg);

In the snippets we use short names for the Java classes. To remove error messages, we have to add import statements to the class:
Select the empty canvas to see the Java import statements.
Add these statements: import import import import import

wsdl.itso.wsoj.WeatherForecast_msg.*; wsdl.itso.wstc.TemperatureCalculator_msg.*; java.util.Calendar; java.util.Date; itso.wsoj.Weather;

Save the process. Only one warning remains in the Tasks view, indicating that the input node requires an operation. Important: Whenever you add custom code into a Java snippet or another method in the process class, be sure to add your code only within the comments user code begin and user code end. Code in other places is removed without any notice whenever the process class is regenerated.

364

WebSphere Version 5.1 Web Services Handbook

Defining the process interface The process is almost complete. The remaining step is to define the interface for the overall business process, which is again done using a WSDL file. Integration Edition generates the remaining information required to build the WSDL file. The context menu of the Input node provides the Generate WSDL interface selection:
This window offers options for the interface definition, for example, whether it is a synchronous or asynchronous service: – For synchronous service, the process is called and right after execution it returns a result message to the caller. – For asynchronous service, the call returns nothing, and the client is responsible for querying the result later on. The asynchronous model offers a large amount of flexibility but also requires a more complex programming model on the client side.
On the second wizard page you can choose the interface definitions, such as port type and operation, which should be used for this process. In our example all the defaults are fine. You will have to regenerate this interface whenever the interface of the process has changed, but not if the internals of the process have changed. A temperatureInterface.wsdl file is generated into the itso.wsie package (Figure 17-15) and more Java code is added to the process class.

Figure 17-15 WSDL interface file of the business process

Chapter 17. Application Developer Integration Edition

365

Generate deploy code The process is now completely defined, but there is a final step to do prior to deploying the process to an application server. When you deploy a business process, you generate the code necessary to make the process available as a service on the application server.

Figure 17-16 Generate deployed code for a process

The Deployment Code wizard is started by selecting Enterprise Services -> Generate Deploy Code in the context menu of the process file (Figure 17-16).
Within the wizard you can first choose to create a new port or use an existing port. The choice depends on whether this is a brand new service (our case), or if you have already deployed the service beforehand.
Another option is to choose the binding for this service. Remember that Application Developer (not Integration Edition) only supports Web services using SOAP/HTTP binding. Integration Edition also supports EJB and JMS

366

WebSphere Version 5.1 Web Services Handbook

bindings and therefore calls the services enterprise services. In our sample we create a SOAP binding, so any client can call the business process using the SOAP/HTTP protocol.
You can go through all the pages of the wizard to see what WSDL files are generated and what options you can choose. Click Finish to generate. The wizard creates an EJB as implementation for the business process and defines the binding as chosen. Therefore new projects are created, such as an EJB (ItsoWebServBPServiceEJB) and a Web (ItsoWebServBPServiceWeb) project. The Services view in the Business Integration perspective now displays a second section called Deployed Services, where you can find these generated projects with the appropriate EJB that implements the process behavior (Figure 17-17).

Process

WSDL interface binding service

Figure 17-17 Deployable services

Explore the ItsoWebServBPServiceEJB and ItsoWebServBPServiceWeb projects and study the generated code.

Chapter 17. Application Developer Integration Edition

367

Flow definition markup language Flow definition markup language (FDML) is used to describe the flow of a business process. FDML was introduced in “Flow definition markup language” on page 163. For our sample business process, the FDML file is named temperature.fdml. In this section we look at extracts of the FDML file.

Start The file starts with: microflow file This is a long description. ..... activities, messages, links

Service activity This code extract shows the service activity that invokes the weather forecast Web service. The activity refers to the WSDL file of the Web service and to two messages, in and out, that are defined elsewhere.

368

WebSphere Version 5.1 Web Services Handbook

Message The input message for the Web service refers to the message in the WSDL file.

Java snippet activity The Java snippet activity refers to the internal method that transforms the output of one activity into the input for another activity.

Data map A data map refers to the internal method that prepares the message content.

Control link The control link between the Java snippet and the Web service activities refers to the output and input terminals of the two activities the link connects.

Chapter 17. Application Developer Integration Edition

369

Testing a business process in the test environment To test the process, you have to create a server of type WebSphere Enterprise Edition; only the Enterprise Edition can run business processes. Create a server project named Servers. Then create a server and configuration named ProcessServer and select WebSphere version 5.0 -> EE Test Environment. This process adds two enterprise applications to the workspace:
BPEContainer, with three modules (one is a Web client Web project)
BPERemoteDeploy, with two modules (one is a SOAP client Web project) Add the two EAR files of our process and Web services to the server:
ItsoWebServBaseEAR—Which runs the weather forecast and temperature conversion services (ItsoWebServWFWEB and ItsoWebServTCWEB)
ItsoWebServBPEAR—Which holds the business process Every time the process is changed, you have to redeploy it. In the Servers view, select Deploy Process in the context menu of the EE Server (Figure 17-18).

Figure 17-18 Deploy process and run test client

Start the server. You should not get any exceptions and stack traces in the console.

Web service client To test the process you can create a client using the new WSDL files that were generated for the process. This is exactly the same as generating a proxy and a test or real client application as for any other Web service. However, there is an easier way.

370

WebSphere Version 5.1 Web Services Handbook

Business process Web client An easier way to test a process is to use the business process Web client, which is similar to the universal test client (UTC) for EJBs. Using this tool, you do not have to write a client or even a proxy object. Select Run Process Web client in the context menu of the server (Figure 17-18), or by just calling the URL http://localhost:8080/bpe/webclient. A welcome page appears where you can select Open the work item manager or, if you wait, the work item manager opens automatically (Figure 17-19).

Figure 17-19 Web client welcome page

The list of work items is displayed, but it is empty in our case. If you have deployed the temperature process, it appears in the Templates drop-down list. Select one of the templates (there is only one now) and click Start, and the process description and input field is displayed (Figure 17-20). Enter a value for the week number and click Start Process. A result page should present the result object or an exception if something went wrong. Note: Although the business process Web client can be used to start business process instances, its primary function is for viewing and interacting with work items created for a staff activity. Asynchronous business processes started in the Web client will not invoke their one-way operations specified for the output and fault activities. Interaction with events is also something that is not possible from within the Web client. Support for these two items is available through a proxy test client.

Chapter 17. Application Developer Integration Edition

371

13

Figure 17-20 Using the business process Web client to test processes

Server configuration When defining a WebSphere Version 5.0 EE Test Environment server, the configuration automatically includes two EAR projects: BPEContainer and BPERemoteDeploy. If you open the server configuration on the Data source page, you find that a Cloudscape™ JDBC provider (BPEJdbcDriverCloudscape) and a data source (BPEDataSourceCloudScape) have been defined. This data source is used by the

372

WebSphere Version 5.1 Web Services Handbook

business process container to maintain its state. Cloudscape is a complete Java SQL database (shipped with WebSphere) with a small overhead and low amount of administration, making it ideal for a testing environment. On the JMS page, you find a set of queues registered and that the JMS server is started. These queues are also used by the process container. Do not forget to invoke Deploy Process (Figure 17-18 on page 370) before testing business processes.

Configuring a remote WebSphere Application Server Note that you must have WebSphere Application Server 5 Enterprise Edition to run business processes. First you have to start the server and install all the necessary EAR projects of your application. If you want to use the server for debugging, you have to configure the debug mode for the application server:
Start the Administrative Console and navigate to Servers -> Application Servers.
On the Configuration tab select Debugging Service and make sure that Startup is selected.
For the JVM debug port enter 7777, and for the JVM debug arguments make sure that the address entry shows 7777 (Figure 17-21).

Figure 17-21 Configure debugging options in WebSphere Enterprise Edition


Because you normally step quite slowly through the code, it is necessary to turn off the transaction time-outs. Therefore, select Additional Properties -> Transaction Services and change the Total transaction lifetime time-out to 0.
Save the configuration and restart the server to make the changes effective. In the debugger you can then attach to the server process as described below.

Chapter 17. Application Developer Integration Edition

373

Debugging business processes A business process is executed on a higher level than Java code. To examine the execution flow of a business process, the process debugger can be used to step through the different activities that make up a business process. The debugger can also be used to step into the Java code, if available. The architecture for the process debugger is the same as for debugging or profiling a Java application. You can easily debug applications that run within the Integration Edition. Furthermore, you can use the IBM Agent Controller to debug applications that run on a remote WebSphere Application Server Enterprise.

Setting breakpoints To stop somewhere in the process, you have to set breakpoints. You can set breakpoints anywhere in your Java code, and you can also set them in your process:
Select Add Breakpoint in the context menu of a control link.
Select Add Breakpoint Before/After Activity in the context menu of an activity.

Start debugger Start the server in debug mode and the Debug perspective opens. After the server is started in debug mode, it is started in the step-by-step mode, which means that the execution is paused as different objects or components within the server are called. Whenever a new step is started, a window prompts you for further execution. You can decide to step into or skip a certain step. There is also the possibility to select Disable step-by-step mode and stop at breakpoints only. Start the process Web client and start the process. Execution stops at breakpoints. Figure 17-22 shows the Debug perspective with execution stopped. Note: The regular Debug perspective does not honor breakpoints set in the process; only breakpoints set in the Java code of the process are honored. To debug at the process level, you have to use the Process Debug perspective.

374

WebSphere Version 5.1 Web Services Handbook

Breakpoint

Figure 17-22 Debug perspective

Process debugging There is a new Process Debug perspective that can be used for high-level debugging of the business processes. Open the Debug Process perspective (after the server has been started in debug mode). Then click the Attach to Process Engine icon ( ) and a window opens. Select the host to which to connect; for debugging in your own machine select localhost. Select the server process and click Finish. You can start a business process by starting an appropriate action in the Web client. You can also start a business process from the Process Debug view. There you find Create Process Instance in the context menu of all processes. Since your process in general requires input parameters, you will be prompted in the Web browser.

Chapter 17. Application Developer Integration Edition

375

Figure 17-23 shows the Process Debug perspective with execution stopped at a process breakpoint. Notice the process breakpoint in the graphical view and in the Process Breakpoints view. The Process Variables view is hidden behind the Process Breakpoints view.

Step over activity

Step into Java

Stopped here

Figure 17-23 Process Debug perspective

Using the debugger Similar to the Java Debugger, there are controls to step over activities. Note that you work at an activity level in stepping mode, and every step is one complete activity. If you want to do more detailed debugging, you can step into the Java code and debug at that level. You can then switch between the Process Debug perspective and the Debug perspective (Java code). You can also watch any variables that are defined in the process. Figure 17-24 shows the Variables view at two breakpoints, just after beginning the process and before ending.

376

WebSphere Version 5.1 Web Services Handbook

Figure 17-24 Process variables in debug mode

In the Process Debug view, you can detach the process using the context menu. Afterwards you can stop the server.

Deployment to an application server You can deploy the business process as a Web service to an application server. You package the EAR file as you would do with any other enterprise application. In that EAR file, you will find the implementation EJB and WAR modules, as well as an additional utility JAR that holds all the business process-relevant data. Note that you can only deploy and run business processes on WebSphere Application Server Enterprise Edition. Deployment to WebSphere Application Server is covered in Chapter 20, “Web services runtime and deployment in WebSphere” on page 479. However, we did not install the Enterprise Edition for deployment of the process application.

Chapter 17. Application Developer Integration Edition

377

Importing the process solution We provide the files of our solution in the directory: sg246891-01\sampcode\wsadie\zSolution

Importing the projects We provide the ItsoWebServBPServiceEAR project and the contained projects in an EAR file that you can import:
Select File -> Import -> EAR File, and click Browse to locate the file: sg246891-01\sampcode\wsadie\zSolution\ItsoWebServBPServiceEAR.ear


Enter ItsoWebServBPServiceEAR as the project name.
Select Create a new Java project defined as a utility JAR or web library and Expanded: extract project contents for development.
Click Finish. You will see many errors in the Tasks view because the Java build path is not imported correctly and the service project is not recognized. To fix the errors in the projects, a number of steps are required.

Web project For the Web project:
Select the ItsoWebServBPServiceWeb project and Import -> File system. Locate the directory: sg246891-01\sampcode\wsadie\zSolution\Web


Import the .classpath file (select Overwrite existing resources without warning).
Delete the itso folder under Java Source.
Select the project and Rebuild Project.

EJB project For the EJB project:
Select the ItsoWebServBPServiceEJB project and Import -> File system. Locate the directory: sg246891-01\sampcode\wsadie\zSolution\EJB


Import the .classpath file (select Overwrite existing resources without warning).

378

WebSphere Version 5.1 Web Services Handbook

Service project For the Service project:
Delete the ItsoWebServBPService project completely (it was not recognized as a service project).
Create a service project with the name ItsoWebServBPService.
Select File -> Import -> Zip file. Locate the file: sg246891-01\sampcode\wsadie\zSolution\ItsoWebServBPService.jar


Select Overwrite existing resources without warning and click Finish.

EAR project For the EAR project:
Open the deployment descriptor (application.xml) of the ItsoWebServBPServiceEAR project.
Make sure that the ItsoWebServBPService.jar file is listed under Project Utility JARs on the Module page.

Defining the server Create a server project (Servers) and an EE test server (ProcessServer) as described in “Testing a business process in the test environment” on page 370. Add the two EAR files (ItsoWebServBPServerEAR and ItsoWebServBaseEAR) to the server configuration.

Test the process sample Select the ProcessServer in the Servers view and Deploy Process (context). Start the server, then select Run Process Web client (context) and run the application.

Chapter 17. Application Developer Integration Edition

379

Summary WebSphere Studio Application Developer Integration Edition adds significant features to the base Application Developer product, especially in the area of Web services. The concept of enterprise services allows services to be not only available through SOAP over HTTP, but uses the Web services invocation framework to offer several invocation scenarios for a service, including EJB, JMS, and native invocations. The implementation of such enterprise services is hidden from a client and the invocation is therefore completely transparent to a client. The Business Integration perspective with all its views and editors enables a graphical modeling of complex workflows that combine other services and/or Java code into a business process. The business processes can be exposed again as enterprise services that are used by clients or other business processes as a single activity. The enhanced WSDL editor provides for easy manipulation of WSDL documents that are stored in multiple files.

More information Refer to the online help in WebSphere Studio Application Developer Integration Edition for further information about those topics. There are many concepts described and well-documented examples show you how to implement and test enterprise services and workflows.

380

WebSphere Version 5.1 Web Services Handbook

18

Chapter 18.

WebSphere SDK for Web Services In this chapter we introduce the IBM WebSphere SDK for Web Services (WSDK), Version 5.1, which enables early adopters to create and test Java-based Web services applications. This entry-level developer kit contains everything in a single, convenient package. The WSDK is based on open specifications for Web services, such as SOAP, WSDL, and UDDI; conforms to the WS-I organization's Basic Profile 1.0; and runs on Windows and Linux operating systems. In this chapter, first, we explain the differences between the different packages for developing Web services for WebSphere Application Server. Second, we describe the IBM WebSphere SDK for Web Services (WSDK) and how to use it to build our sample weather forecast Web services.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

381

The difference between the packages There is some confusion about the different packages for developing Web services for WebSphere Application Server:
For WebSphere Application Server Version 5.0, there were three packages: – WebSphere SDK for Web Services – Technology Preview – Web Services Toolkit (WSTK)
For WebSphere Application Server Version 5.1, there are two packages: – WebSphere SDK for Web Services – Emerging Technologies Toolkit (ETTK), replacing WSTK WebSphere SDK for Web Services (WSDK) provides developer tools and a runtime environment for designing and executing Web service applications that are consistent with the industry-standard platform for Web services and the emerging standard for interoperability defined by the Web Services Interoperability Organization (WS-I). Such applications can discover and collaborate in business transactions without programming requirements or human intervention. WSDK uses the WebSphere SOAP engine and is based on JAX-RPC (JSR 101—see Chapter 4, “JAX-RPC (JSR 101)” on page 67) and on Web services for J2EE (JSR 109—see Chapter 5, “Implementing Enterprise Web Services (JSR 109)” on page 77). The Emerging Technologies Toolkit (ETTK)—formerly known as the Web Services Toolkit (WSTK)—delivers to developers early implementations of new technologies using Web services, and acts as a consolidator of Web services technologies from various IBM development and research labs. Unlike WSDK, the ETTK does not have an embedded application server or a private UDDI registry. The WSDK is therefore ideal for testing services applications developed with ETTK. ETTK is based on the Axis programming model. We can use WSDK without ETTK to develop industry-standard Web services applications, or we can use it with ETTK if we want to explore the latest emerging technologies, such as grid computing, that (can) use Web services. ETTK Version 1.2 contains service data objects (SDO), policy-based IT management demo, semantic Web services, autonomic computing toolset, WS-Manageability demo, WS-Trust, WS-Addressing, Web services failure recovery, and service domain technology. For more information on ETTK, go to: http://alphaworks.ibm.com/tech/ettk

382

WebSphere Version 5.1 Web Services Handbook

WebSphere SDK for Web Services Version 5.1 The IBM WebSphere SDK for Web Services (WSDK) provides developer tools and a runtime environment for designing and executing Web service applications that are consistent with the industry-standard platform for Web services and the emerging standard for interoperability defined by the Web Services Interoperability Organization (WS-I). We can use the WSDK to demonstrate the interoperability of Web services between the IBM WebSphere J2EE-based platform and platforms provided by other suppliers, for example, Microsoft .NET. The functionality of the WSDK is based on open specifications such as SOAP, WSDL, and UDDI, and the current release runs on both Linux and Windows operating systems. The WSDK is not a product. It is a free-of-charge IBM technology offering that enables development and testing of Java-based Web services as an entry-level developer kit. It is important to note that WSDK is not licensed for running production applications or redistribution. The WSDK contains:
An embedded version of IBM WebSphere Application Server Express, Version 5.0.2 with additional support for ORBs and EJBs. – Support for SOAP 1.1, WSDL 1.1, UDDI 2.0, JAX-RPC 1.0 (JSR 101), EJB 2.0, Enterprise Web Services (JSR 109) 1.0, WSDL4J, UDDI4J, and WS-Security. – A private UDDI Version 2 registry. – An entry-level database providing a JDBC implementation. – IBM SDK for Java Technology, Version 1.3.1. – Support for the Java Messaging Service (JMS) API and Message Driven Beans (MDB). These functions are not intended for general use and they have only been tested in the context of the WS-I Supply Chain Management (SCM) sample.
Plug-ins for Eclipse Version 2.1.1. Installing the plug-ins into the plugins directory of an Eclipse installation is an option when WSDK 5.1 is installed. See “Installation of WebSphere SDK for Web Services 5.1” on page 523.
Tools to enable JavaBeans and stateless session EJBs as Web services, to create Web services from WSDL definitions, and to publish and unpublish Web services to a UDDI registry.
Comprehensive documentation including Web services concepts, developer tasks, and reference materials.

Chapter 18. WebSphere SDK for Web Services

383


Samples showing how to enable JavaBeans and stateless session EJBs as Web services, create Web services from WSDL definitions, publish, unpublish, and look up Web services using UDDI, and create secure Web services using the WS-Security specification.

Application server The application server includes a private UDDI registry, used for publishing and discovery of Web services using the UDDI protocols. The UDDI registry itself runs as an enterprise application (EAR) within the application server. The application server provided with WSDK 5.1 is based on WebSphere Application Server Version 5.0.2. It is a J2EE-based server that provides the functions of an HTTP Web server, a servlet engine, and an EJB container. It also provides Web services capabilities based on the standards defined for J2EE, namely JAX-RPC as defined by JSR 101, and the integration of Web services with the J2EE server as defined by JSR 109. The application server also includes IBM Java SDK Version 1.3.1, which is used to run the server itself, and is also used to build and run client-side Java applications.

Tools The WSDK provides utility tools (in /bin) that allow us to enable, deploy, and publish J2EE applications:
Bean2WebService—Creates a fully deployable Web service from a Java class and optionally deploys it to the application server
EJB2WebService—Creates a fully deployable Web service from a stateless session EJB contained in an EJB module (contained in an EAR file) and optionally deploys it to the application server
WSDL2WebService—Creates a fully deployable Web service from one or more WSDL documents and optionally deploys it to the application server
WSDL2Client—Generates fully-deployable Web service clients from one or more WSDL documents and optionally deploys them to the application server
UDDIPublish—Publishes a business entity or a business service to a public or a private UDDI registry
UDDIUnpublish—Removes a business entity or a business service from a public or a private UDDI registry

384

WebSphere Version 5.1 Web Services Handbook

In addition to the Web services development tools, WSDK provides tools to monitor Web services and to administer the included application server:
tcpmon—Monitors and displays Web service messages (SOAP messages) that are exchanged between a Web service client and a Web service server
appserver—Provides basic and Web services related administration functions of the application server, such as starting and stopping the server, installing and uninstalling Web services, and listing all installed Web services
setProxy—Configures HTTP proxy information for the WSDK tools and runtime server Note: WSDK 5.1 provides an Eclipse plug-in to create Web services with graphical wizards in an Eclipse environment. See “Using the WSDK plug-in for Eclipse” on page 416.

Documentation WSDK documentation is divided into five main sections under IBM WebSphere SDK for Web Services:
Getting started with WSDK—This section provides tailored learning paths with different learning objectives, from Web services basics to an architectural view.
Concepts—This section talks about the Web services technologies, such as XML, SOAP, WSDL and UDDI. It also explains WS-Security, the Web services architecture, and the J2EE specifications for Web services.
Tasks—This section explains how to Web service-enable J2EE applications, or implement an existing Web service from its WSDL document. It also tells how to secure Web services applications and develop several types of Web services clients.
Reference—This section contains the reference materials for the tools shipped with the WSDK, the API documentation, and a troubleshooting guide.
Samples—This section describes the nine Web services samples shipped with the WSDK, tells how to run them, and what their expected behavior is. It also includes a step-by-step guide to rebuilding the samples. To access the documentation for WSDK, use the wsdkHelp command, located in the /bin directory, or click the WSDK Help icon.

Chapter 18. WebSphere SDK for Web Services

385

Sample applications There are nine sample applications located in /apps. These sample applications cover a range of scenarios for Web services, include code for both provider (server side) and requestors (client side), and also have examples of publishing and finding Web services using UDDI. They are:
Sample 1—A request-response Web service created from a JavaBean and a Web service requestor using the JAX-RPC service locator. Sample 1 also demonstrates split WSDL.
Sample 2—A request-response Web service created from a session enterprise bean and three Web service requestors for it: – A J2EE client running in the WebSphere client container and using JNDI. – A J2EE EJB client running in the EJB container and using JNDI. – A J2SE client running as a stand-alone application and using the JAX-RPC ServiceFactory.
Sample 3—Publishes and then unpublishes sample 1's Web service using the UDDI registry publish API.
Sample 4—Demonstrates dynamic discovery and invocation of Web services using the UDDI registry inquiry API.
Sample 5—Demonstrates the use of complex types in Web services.
Sample 6—A one-way Web service implemented as a JavaBean from a WSDL document.
Sample 7—Demonstrates how headers and faults are handled by SOAP and WSDL.
Sample 8—Demonstrates WS-Security digital signature, encryption, authentication, and ID assertion.
Sample 9—Demonstrates a third-party client, a Visual Basic .NET client, that invokes a WSDK-developed Web service. The sample applications are already built and deployed to the application server so that we can run them as soon as we have installed WSDK. Note: Even though the WSDK comes with nine comprehensive samples, we provide an additional, very simple and small sample to see the individual WSDK tools at work. This sample is a String service that returns an input argument string in all uppercase.

386

WebSphere Version 5.1 Web Services Handbook

WS-Security in WSDK The WSDK implements the WS-Security elements shown in Table 18-1. Table 18-1 WS-Security elements implemented in WSDK Element

Notes®



Both user name/password and IDAssertion authentication are implemented. Password digest is not implemented.



X.509 certificates can be embedded, but Kerberos tickets cannot.



X.509 certificate in can be referenced by .



Both and are implemented. is used to specify public keys; , secret keys.



With WSDK, SOAP messages that include these security elements can be exchanged by providing XML configuration files at both client and server sides. Figure 18-1 shows the overall architecture of the WS-Security implementation in the WSDK.

Figure 18-1 WS-Security implementation in WSDK

Chapter 18. WebSphere SDK for Web Services

387

Using the tools In this section we describe the development tools provided with the WSDK. For the installation see “Installation of WebSphere SDK for Web Services 5.1” on page 523. For the WSDK installation root directory, we suggest d:\WSDK51. For the command line examples we use the directory c:\wsdk51sample.

Bean2WebService The Bean2WebService tool generates a fully deployable Web service from a Java class, and optionally deploys it on the application server.

Generation steps explained The automatic process followed by the command tool to generate the Web services is shown in Figure 18-2.

J2EE EAR

WebSphere 5.0.2

J2EE WAR file

Deploy the EAR

J2EE EAR

JavaBean

8

WS DD

J2EE WAR file

WSDL

JavaBbean WS DD

SEI class

WSDL SEI class

Package WAR in EAR

7

Javabean added as part of web.xml

6

J2EE WAR file

J2EE WAR file

Add SEI, WSDL, WS-DD to WAR

JavaBean

JavaBean

Copy in WEB-INF/ dir

WS DD

CONFIGURED

WSDL

WebServices DD IBM binding

SEI class

1

Copy in WEB-INF/ dir

2 JavaBean Javabean in WAR package

Manually create

Service endpoint interface class (SEI)

Java2WSDL

5 4

3 WSDL

WSDL2Java

WebServices DD IBM binding

Options "-META-INF-Only -server-side Bean"

Figure 18-2 Process to create a Web service from a JavaBean (bottom-up)

388

WebSphere Version 5.1 Web Services Handbook

In brief, the steps are:
Step 1—Take the Java bean that will be available as a Web service.
Step 2—Create the SEI Java code from the Java bean with the methods that will be exposed in the Web service.
Step 3—Generate the WSDL from the SEI with the Java2WSDL command.
Step 4—Generate the Web service deployment descriptor templates from the WSDL with the WSDL2Java command.
Step 5—Configure the Web service deployment descriptor. Modify the tag in webservices.xml with the value of the tag in the web.xml file.
Step 6—Assemble all the files previously generated in a WAR file: – Add the SEI file to the WAR file. – Add the WSDL to the WAR file in the WEB-INF directory. – Add the Web services and IBM binding deployment descriptors to the WEB-INF directory.
Step 7—Assemble the WAR file in an enterprise application (EAR) file.
Step 8—Deploy the application on WebSphere Application Server Version 5.0.2.

Sample setup To see the tool at work we use the simple StringService example:
Create a beanSrc directory in the c:\wsdk51sample directory.
Copy the StringService.java file (Example 18-1): from: sg246891-01\sampcode\wsdk51\sample\beanSrc to: c:\wsdk51sample\beanSrc Example 18-1 StringService example public class StringService { public StringService() {} private String lowercase(String str) { return str.toLowerCase(); } public String uppercase(String str) { return str.toUpperCase(); } public static void main(String[] args) { StringService stringService = new StringService(); System.out.println(stringService.lowercase(args[0])); System.out.println(stringService.uppercase(args[0])); } }

Note that one method is private, and one is public. The private method returns the argument string in all lowercase, and the public in all uppercase.

Chapter 18. WebSphere SDK for Web Services

389

To verify and prepare the service example class, open a command window, set up the environment, compile the class, and run the program using the following command sequence: c: cd \wsdk51sample\beanSrc d:\\bin\setupEnv javac StringService.java java StringService Abc

d:\wsdk51\bin\setupEnv

The output should look like: abc ABC

Bean2WebService at work To experiment with the Bean2WebService tool we run the tool on the simple StringService bean: cd \wsdk51sample d:\\bin\setupEnv Bean2WebService [options] -cp -project Bean2WebService -verbose -cp .\beanSrc -project beanProj StringService

Note: Use Bean2WebService -help to see a short explanation of all the options. The WSDK Help facility has more detailed information.
-cp is a list of absolute or relative path and file names.
-project must be a valid directory name. The command window output is shown in Example 18-2, where ~ stands for c:\wsdk51sample. Example 18-2 Bean2WebService command output Creating new project: beanProj ... Removed all existing classes from directories under ~\beanProj\WEB-INF\classes\ Generating the service endpoint interface... Generating WSDL: WSWS3010I: Info: Generating portType {http://DefaultNamespace}StringService message {http://DefaultNamespace}uppercaseRequest message {http://DefaultNamespace}uppercaseResponse binding {http://DefaultNamespace}StringServiceSoapBinding service {http://DefaultNamespace}StringServiceService port StringService Generating server side files: WSWS3185I: Info: Parsing XML file: ~\beanProj\WEB-INF\wsdl\StringService.wsdl WSWS3282I: Info: Generating ~\beanProj\DefaultNamespace\StringService.java. ~\beanProj\DefaultNamespace\StringServiceSoapBindingImpl.java.

390

WebSphere Version 5.1 Web Services Handbook

~\beanProj\WEB-INF\webservices.xml. ~\beanProj\WEB-INF\ibm-webservices-bnd.xmi. ~\beanProj\WEB-INF\ibm-webservices-ext.xmi. ~\beanProj\WEB-INF\StringService_mapping.xml. Configuring webservices.xml... ~\beanProj\WEB-INF\wsdl\StringService.wsdl Added web module with context root: beanProj Web Service archive "file:~/beanProj/beanProj.ear" has been successfully generated. Generating client side files: WSWS3185I: Info: Parsing XML file: ~\beanProj\WEB-INF\wsdl\StringService.wsdl WSWS3282I: Info: Generating ~\beanProj\client-side\DefaultNamespace\StringServiceService.java. ~\beanProj\client-side\DefaultNamespace\StringServiceServiceLocator.java. ~\beanProj\client-side\DefaultNamespace\StringService.java. ~\beanProj\client-side\DefaultNamespace\StringServiceSoapBindingStub.java. ~\beanProj\client-side\META-INF\webservicesclient.xml. ~\beanProj\client-side\META-INF\ibm-webservicesclient-bnd.xmi. ~\beanProj\client-side\META-INF\ibm-webservicesclient-ext.xmi. ~\beanProj\client-side\META-INF\StringService_mapping.xml. Creating client-side build script... All done.

The main output of the Bean2WebService tool is the .ear file in the root of the generated directory structure named . The project structure is shown in Figure 18-3:
The EAR file contains a fully deployable Web service.
The WEB-INF directory holds the server-side Web project information: – Deployment descriptor – Java classes – WSDL file
Because we did not specify the -server-side-only option, a client-side directory is generated with: – Proxy classes (in DefaultNamespace) – Deployment descriptor – WSDL file Look into the generated files, especially the StringService.wsdl and StringService_SEI.java (service endpoint interface) files. Notice that by default they include the public (and non-static) methods of the StringServices.java class.

Chapter 18. WebSphere SDK for Web Services

391

c:\wsdk51sample

beanSrc StringService.java StringService.class

beanProj beanProj.ear

WEB-INF <=== server-side webservices.xml ibm-webwebservices-bnd.xml ibm-webwebservices-ext.xml StringService_mapping.xml

client-side buildclient.bat

classes StringService.class StringService_SEI.java StringService_SEI.class lib wsdl StringService.wsdl

DefaultNamespace StringService.java StringServiceService.java StringServiceServiceLocator.java StringServiceSoapBindingStub.java

META-INF webservicesclient.xml ibm-webwebservicesclient-bnd.xml ibm-webwebservicesclient-ext.xml StringService_mapping.xml wsdl StringService.wsdl

Figure 18-3 Bean2WebService project structure

Command line help and options The Bean2WebService command has many useful options:
-methods — Allows to define the subset of the public methods that should be exposed as Web services.
-deploy—Deploy the generated EAR file into the application server.
-server-side-only—Do not generate client-side files.
-genMain and -clientType — Generate a main client class and implementation template.
-style —WSDL style, RPC or DOCUMENT, WRAPPED (default) is a special document style.
-use —Encoding (LITERAL by default).
-splitWsdl—Generate separate interface and binding files.
-wsSecDir —Directory for deployment descriptors configured for security.

392

WebSphere Version 5.1 Web Services Handbook

EJB2WebService The EJB2WebService tool generates a fully deployable Web service from a stateless session EJB contained in an EAR file, and optionally deploys it to the application server. Note that only Version 2.0 of the EJB architecture is supported. To use EJB2WebService, open a command window and enter: cd \bin EJB2WebService [] -project -ri

The main output of this tool is a modified version of the original EAR file, which contains a fully deployable Web service, and optionally a client-side directory is generated with the extra files for client development. The automatic process followed by the command tool to generate the Web service is shown in Figure 18-4:
Step 1—Take the stateless session bean that will be available as a Web service.
Step 2—Create the SEI Java code from the EJB with the methods that will be be exposed in the Web service.
Step 3—Generate the WSDL from the SEI with the Java2WSDL command.
Step 4—Generate the Web service deployment descriptor templates from the WSDL with the WSDL2Java command.
Step 5—Configure the Web service deployment descriptor. Modify the tag in webservices.xml with the value of the tag in the ejb-jar.xml file.
Step 6—Assemble all the files previously generated in an EJB JAR: – Add the SEI file to the EJB JAR – Add the WSDL to the EJB JAR in the META-INF directory – Add the Web services and IBM binding deployment descriptors to the META-INF directory
Step 7—Assemble the EJB JAR in an enterprise application (EAR).
Step 8—Create the Web service endpoint Web module WAR. Use the command endptEnabler and answer the prompts.
Step 9—Deploy the application into WebSphere Application Server Version 5.0.2.

Chapter 18. WebSphere SDK for Web Services

393

J2EE EAR

J2EE EAR

8

EJB Jar

EJB Jar endptEnabler

EJB

J2EE WAR Enable WsRouterServlet

EJB

WebSphere 5.0.2

9

WS DD

WS DD

Install EAR

WSDL

WSDL

SEI class

SEI class

J2EE EAR EJB Jar EJB

J2EE WAR Enable WsRouterServlet

WS DD

7

WSDL

Package EJB Jar in EAR

SEI class

6

EJB Jar

EJB Jar

Add SEI, WSDL, WS-DD to EJB Jar

EJB

EJB

Copy in META-INF/ dir

WS DD

CONFIGURED

WSDL

WebServices DD IBM binding

SEI class

1

Copy in META-INF/ dir

2 EJB Stateless Session Bean

Manually create

Service endpoint interface class (SEI)

3 Java2WSDL

5 4

WSDL

WSDL2Java

WebServices DD IBM binding

Options "-META-INF-Only -server-side EJB"

Figure 18-4 Process to create a Web service from an EJB (bottom-up)

WSDL2WebService The WSDL2WebService tool generates, in three stages, fully deployable Web services from one or more WSDL documents and optionally deploys them on the application server.

Generation stages explained The automatic process followed by the command tool to generate the Web service is shown in Figure 18-5.

394

WebSphere Version 5.1 Web Services Handbook

J2EE EAR

WebSphere 5.0.2

EJB WAR Jar J2EE EJB JavaBean

WS DD WS DD

J2EE EAR

6

WSDL WSDL

J2EE WAR JavaBean

SEI class class SEI

WS DD WSDL SEI class

5

4

Stage3

J2EE WAR JavaBean WS DD WSDL

CONFIGURED

SEI class

WebServices DD IBM binding

3

Stage1

Stage2

1

WSDL

WSDL2Java

Options "-server-side Bean"

*SEI *Web service implementation Java Bean template *WS DD + Binding

Implement Web service from template

JavaBean

2

Figure 18-5 Process to create a JavaBean Web service from a WSDL (top-down)

In brief, the stages and steps are:
Stage 1—Step 1—Generate the Web service deployment descriptor templates and the implementation files from the WSDL using the WSDL2Java command.
Stage 2—Step 2—Complete the implementation of the bean.
Stage 3: – Step 3—Configure the Web service deployment descriptor. Modify the tag in webservices.xml with the value of the tag in the web.xml. – Step 4—Assemble all the generated files in a WAR: • • • •

Java bean as a servlet in the web.xml SEI class WSDL in the WEB-INF directory Web services IBM binding deployment descriptor into META-INF

– Step 5—Assemble the WAR into an enterprise application (EAR).

Chapter 18. WebSphere SDK for Web Services

395

– Step 6—Deploy the application into WebSphere Application Server Version 5.

Sample setup To see the tool at work, we use the WSDL file generated for the StringService sample:
Create a wsdlSrc directory in the wsdk51sample directory.
Copy the StringService.wsdl file into the directory. Take the file from the previous example, or copy from: sg246891-01\sampcode\wsdk51\sample\wsdlSrc

WSDL2WebService at work The three stages reviewed:
Stage 1—Run the tool with the -createService argument to create skeleton Java implementation templates for a Web service described by a particular WSDL document.
Stage 2—Write the implementation code in the templates and compile it using the compile script generated in stage 1.
Stage 3—Run the tool again with the -createEar argument to build a Web service-enabled archive from this implementation, and deploy it to the application server. Note that we can perform stage 1 several times to create related Web services in the same project directory. In stage 3 we can then create a separate module for each of these Web services and add them to the same EAR file.

Stage 1—Creating a Web service implementation skeleton To create a skeleton Web service implementation, open a command window and enter: cd wsdk51sample d:\\bin\setupEnv WSDL2WebService [] -createService -type -project WSDL2WebService -verbose -createService StringService -type Bean -project .\wsdlProj .\wsdlSrc\StringService.wsdl

The command window output is shown in Example 18-3, where ~ stands for c:\wsdk51sample. Example 18-3 WSDL2WebService command output (createService) Creating new Web-Service: StringService ... Generating server side files:

396

WebSphere Version 5.1 Web Services Handbook

WSWS3185I: Info: Parsing XML file: ~\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl WSWS3282I: Info: Generating ~\wsdlProj\StringService\DefaultNamespace\StringService.java. ~\wsdlProj\StringService\DefaultNamespace\StringServiceSoapBindingImpl.java. ~\wsdlProj\StringService\WEB-INF\webservices.xml. ~\wsdlProj\StringService\WEB-INF\ibm-webservices-bnd.xmi. ~\wsdlProj\StringService\WEB-INF\ibm-webservices-ext.xmi. ~\wsdlProj\StringService\WEB-INF\StringService_mapping.xml. Generating client side files: WSWS3185I: Info: Parsing XML file: ~\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl WSWS3282I: Info: Generating... ~\wsdlProj\StringService\client-side\DefaultNamespace\StringServiceService.java. ~\wsdlProj\StringService\client-side\DefaultNamespace\StringServiceServiceLocator.java. ~\wsdlProj\StringService\client-side\DefaultNamespace\StringService.java. ~\wsdlProj\StringService\client-side\DefaultNamespace\StringServiceSoapBindingStub.java. ~\wsdlProj\StringService\client-side\META-INF\webservicesclient.xml. ~\wsdlProj\StringService\client-side\META-INF\ibm-webservicesclient-bnd.xmi. ~\wsdlProj\StringService\client-side\META-INF\ibm-webservicesclient-ext.xmi. ~\wsdlProj\StringService\client-side\META-INF\StringService_mapping.xml. Creating client-side build script... Creating server-side build script... Configuring webservices.xml... A new Web-Service "StringService" has been created successfully in the project directory C:\wsdk51sample\wsdlProj. To complete the Web-Service, you can now fill in your implementation code in the following classes: StringServiceSoapBindingImpl.java Then compile the code using the provided script ~\wsdlProj\StringService\compile.bat and run the tool again with the -createEar option.

After running the tool with the -createService argument, a directory named containing several subdirectories is created under the specified project directory. These subdirectories contain all the necessary Java templates and deployment descriptors that are required to build the Web service implementation(s). A build script called compile.bat (Windows) or compile.sh (Linux) is also generated to compile the server-side code. The directory and file structure is similar to Figure 18-3 on page 392:
WEB-INF—Server-side files with deployment descriptor files and WSDL
DefaultNamespace—Interface (StringService.java) and implementation skeleton file (StringServiceSoapBindingImpl.java)
client-side—Identical to Bean2WebService command output

Chapter 18. WebSphere SDK for Web Services

397

Stage 2—Providing and Compiling the implementation code Provide the implementation code by editing the file: \\\SoapBindingImpl.java c:\wsdk51sample\wsdlProj\StringService\DefaultNamespace\StringServiceSoapBindingImpl. java

Replace the return statement as shown here and save the file: /** * StringServiceSoapBindingImpl.java * * This file was auto-generated ...... */ package DefaultNamespace; public class StringServiceSoapBindingImpl implements DefaultNamespace.StringService{ public java.lang.String uppercase(java.lang.String arg_0_0) throws java.rmi.RemoteException { return arg_0_0.toUpperCase(); // was: return null; } }

If the implementation code has dependencies such as .jar files or directories containing .class files, edit the compile.bat script, and add the full path names of these dependencies to the USER_CLASSPATH variable. To compile the code enter: cd wsdk51sample\wsdlProj\StringService compile

Note: Only the server code is compiled. If everything is OK, no command window output is displayed.

Stage 3—Creating a Web services-enabled archive To create a Web services-enabled archive: cd wsdk51sample d:\\bin\setupEnv WSDL2WebService [] -createEar -project WSDL2WebService -verbose -createEar StringService.ear -project .\wsdlProj

The command window output is shown in Example 18-4, where ~ stands for c:\wsdk51sample.

398

WebSphere Version 5.1 Web Services Handbook

Example 18-4 WSDL2WebService command output (createEAR) localhost:6080/StringService/services/StringService Preparing to create the archive... Organising the project directory: ~\wsdlProj\StringService ~\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl Added web module with context root: StringService Web Service archive "file://~/wsdlProj/StringService.ear" has been successfully generated. The archive ~\wsdlProj\StringService.ear has been successfully updated and is now ready to deploy.

After we have written the implementation code, compiled it, and run the tool again with the -createEar option, the output will be either a new or updated EAR file containing a Web service module for each of the Web service names specified with the -add argument. By specifying -type Bean in the stage 1 command we generated a JavaBean implementation template. By using -type EJB we would generate an EJB implementation template. Other command line options are similar to the Bean2WebService command.

WSDL2Client The WSDL2Client tool generates, in four stages, fully deployable Web service clients from one or more WSDL documents and optionally deploys them on the application server.

Sample setup To see the tool at work, we use the generated WSDL file: c:\wsdk51sample\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl

WSDL2Client at work The four stages reviewed:
Stage 1—Run the tool with the -project argument to create a client skeleton implementation for a Web service that is described by a particular WSDL document.
Stage 2—Write the implementation code in the templates and compile it using the build script that was generated in stage 1.

Chapter 18. WebSphere SDK for Web Services

399


Stage 3—If -clientType J2SE and -genMain options were specified in stage 1, run the client by using the run script generated in stage 1.
Stage 4—If -clientType Application, EJB or Servlet is specified in stage 1, run the tool again with the -createEar argument to build a Web service-enabled client archive (J2EE client) from this implementation.

Stage 1—Creating a skeleton client implementation To create a client implementation skeleton, open a command window and enter: cd wsdk51sample d:\\bin\setupEnv WSDL2Client [] -project WSDL2Client -verbose -clientType J2SE -genMain StringServiceClient -project .\wsdlClient .\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl

The output directory (wsdlClient\client-side\DefaultNamespace) contains all the necessary Java templates, including serializer and deserializer classes for complex types, and deployment descriptors that are required to build the Web service client implementations. A build script called buildclient.bat is also generated to help us compile all this code. If we have run the tool with the -clientType J2SE argument, a run script called runclient.bat is also generated. Rerun the WSDL2Client command, but this time we generate a J2EE client application into another output folder (wsdlJ2EE): WSDL2Client -verbose -clientType Application -genMain StringServiceJ2EEClient -project .\wsdlJ2EE .\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl

Stage 2—Writing and compiling the implementation code The generated client program skeleton, StringServiceClient, must be edited to add the Web service call (Example 18-5, modifications in bold). Example 18-5 Web service client (copied from sampcode\wsdk51\sample\wsdlClient) package DefaultNamespace; public class StringServiceClient { public static void main(String[] args) { try { StringServiceServiceLocator loc = new StringServiceServiceLocator(); // Call to the service locator's get() method returns an interface of // type PortType //StringService port = null; // loc.get(); StringService port = loc.getStringService();

400

WebSphere Version 5.1 Web Services Handbook

/* * Make calls to methods of the PortType to access the Web Service */ String result = port.uppercase("Hello StringServiceClient"); System.out.println(result); } catch (java.lang.Exception e){ e.printStackTrace(); } } }

If our implementation code has dependencies such as a .jar file or a directory containing .class files, edit the buildclient.bat script, and add the full path names of these dependencies to the USER_CLASSPATH variable. To compile the code: cd wsdk51sample\wsdlClient\client-side buildclient

Stage 3—Running the client application To run the client we have to install the enterprise application that contains the Web service. We will do that in a moment.

Stage 4—Creating a J2EE client application Edit the StringServiceJ2EEClient program (in wsdlJ2EE\client-side\...). Notice that the J2EE client code using JNDI is generated (Example 18-6). Example 18-6 Web service J2EE client (extract, modifications in bold) public class StringServiceJ2EEClient { public static void main(String[] args) { try { // Use JNDI to locate the Web Service Context ctx = new InitialContext(); String webService = "java:comp/env/service/StringServiceService"; StringServiceService service = (StringServiceService) ctx.lookup(webService); // Call to the service's get() method returns an interface ... //StringService port = null; // (StringService) service.get(); StringService port = service.getStringService(); /* * Make calls to methods of the Service Endpoint Interface (SEI) ... */ String result = port.uppercase("Hello StringServiceJ2EEClient"); System.out.println(result); } catch (java.lang.Exception e){ e.printStackTrace(); } } }

Chapter 18. WebSphere SDK for Web Services

401

To compile the code: cd wsdk51sample\wsdlJ2EE\client-side buildclient

To create the Web service-enabled client archive: cd wsdk51sample d:\\bin\setupEnv WSDL2Client [] -createEar -clientType WSDL2Client -createEar StringServiceClient.ear -clientType Application -main DefaultNamespace.StringServiceJ2EEClient .\wsdlJ2EE

The output will be either a new or updated EAR file. The -main parameter is required for -clientType Application or Servlet. Notice that the client-side classes are moved to the META-INF\classes directory. With -clientType Servlet the classes would be moved to WEB-INF\classes.

Working with the application server WSDK provides an appserver.bat command to work with the server. This command file enables you to:







Start, stop, and restart the server. Install and uninstall enterprise applications. Start and stop enterprise applications. List the installed applications. Enable and disable security. Enable and disable the samples.

Installing the StringService enterprise application We created the StringService.ear file in the wsdlProj directory. To install this enterprise application we run these commands: cd \bin appserver install c:/wsdk51sample/wsdlProj/StringService.ear

Note that we could have installed the application by using the -deploy options in the WSDL2WebService -createEar command.

Starting the server and listing the applications To start the server and list the enterprise applications use these commands: cd \bin appserver start appserver appstatus

402

WebSphere Version 5.1 Web Services Handbook

<=== list running applications

Running a J2SE Web-service client To run the J2SE client, we use the runclient.bat file that was generated into the client-side folder: cd wsdk51sample\wsdlClient\client-side runclient

The client connects to the enterprise application running in the server and displays this output: HELLO STRINGSERVICECLIENT

If the implementation code has dependencies such as a .jar file or a directory containing .class files, edit the runclient.bat script, and add the full path names of these dependencies to the USER_CLASSPATH variable.

Running the J2EE client In “Stage 4—Creating a J2EE client application” on page 401 we created the StringServiceClient.ear file, a Web service-enabled J2EE client application. We can run the J2EE client using the WebSphere launchClient command: cd \appserver\bin launchClient c:\wsdk51sample\wsdlJ2EE\client-side\StringServiceClient.ear

The output is similar to the J2SE client: D:\\appserver\bin>launchClient c:\wsdk51sample\wsdlJ2EE\client-side\StringServiceClient.ear IBM WebSphere Application Server, Release 5.0 J2EE Application Client Tool Copyright IBM Corp., 1997-2002 WSCL0012I: Processing command line arguments. WSCL0013I: Initializing the J2EE Application Client Environment. WSCL0035I: Initialization of the J2EE Application Client Environment ... WSCL0014I: Invoking the Application Client class DefaultNamespace.StringServiceJ2EEClient HELLO STRINGSERVICEJ2EECLIENT

UDDIPublish The UDDIPublish tool publishes either a business entity or a business service to a public or private UDDI registry. When publishing a service, the tool creates the necessary binding template and tModel elements in the UDDI hierarchy and associates the service with an existing business. By default, the tool publishes to the private WSDK registry.

Chapter 18. WebSphere SDK for Web Services

403

Publishing a business entity To publish a business entity: cd /bin UDDIPublish -business -businessName [] UDDIPublish -business -businessname ItsoBusiness

A message is returned informing us that the publish operation completed successfully. The unique key for the new business (as generated in the registry) is also displayed.

Publishing a business service To publish a business service: cd /bin UDDIPublish -service -serviceName -businessName -wsdlLocation -accessPoint [] UDDIPublish -service -serviceName StringService -businessname ItsoBusiness -wsdlLocation .\wsdlproj\StringService\WEB-INF\wsdl\StringService.wsdl -accessPoint http://localhost:6080/StringService/services/StringService

A message is returned informing us that the publish operation completed successfully. The unique keys for the new business service, binding template, and tModel instance are also displayed.

Security for publishing Because the application server is running with security on, default credentials (user ID: admin, password: adminpwd) are passed by the tool to the UDDI registry when the publish operation is attempted. These credentials can be overridden by the -username and -password arguments, which can be entered when publishing or unpublishing either a service or a business.

Additional properties With the -uddiprops argument of UDDIPublish, we can specify the location of a Java properties file that contains additional input information. Businesses and services can have this additional classification information associated with them in the registry to assist in the discovery process. This information can be added in the form of a keyed reference to the published item's category bag structure. A category bag can contain numerous keyed references, each one containing the name and the value of a category to which the published item belongs.

404

WebSphere Version 5.1 Web Services Handbook

We can use the provided speedstart.properties file with UDDIPublish to create and categorize businesses and services in the public IBM UDDI V2 Business Test Registry as being part of the IBM Speed Start program (Figure 18-6): \appserver\properties\speedstart.properties # Properties specific to IBM Speed Start # URLs pointing to IBM test registry wsdk.uddi.publish.url=https://uddi.ibm.com/testregistry/publishapi wsdk.uddi.inquiry.url=https://uddi.ibm.com/testregistry/inquiryapi # Added to category bags belonging to published services wsdk.uddi.publish.bs.keyref.name.1=Web service information for the developerWorks Web services community wsdk.uddi.publish.bs.keyref.value.1=General wsdk.uddi.publish.bs.keyref.tmodelkey.1=UUID:8F497C50-EB05-11D6-B618-000629DC0A53 wsdk.uddi.publish.bs.keyref.name.2=Web service information for the developerWorks Speed Start community wsdk.uddi.publish.bs.keyref.value.2=Speed Start wsdk.uddi.publish.bs.keyref.tmodelkey.2=UUID:8F497C50-EB05-11D6-B618-000629DC0A53 # Added to category bags belonging to published business wsdk.uddi.publish.be.keyref.name.1=Web service information for the developerWorks Web services community wsdk.uddi.publish.be.keyref.value.1=General wsdk.uddi.publish.be.keyref.tmodelkey.1=UUID:8F497C50-EB05-11D6-B618-000629DC0A53 wsdk.uddi.publish.be.keyref.name.2=Web service information for the developerWorks Speed Start community wsdk.uddi.publish.be.keyref.value.2=Speed Start wsdk.uddi.publish.be.keyref.tmodelkey.2=UUID:8F497C50-EB05-11D6-B618-000629DC0A53

Figure 18-6 Properties file for publishing

We can use the provided testregistry.properties file with UDDIPublish to publish businesses and services to the IBM UDDI V2 Business Test Registry (but without the special categories for the IBM Speed Start program). Similarly, we can use the businessregistry.properties file to enable us to work with the IBM UDDI V2 Business Registry.

UDDIUnpublish The UDDIUnpublish tool removes (that is, unpublishes) either a business entity or a business service from a public or private UDDI registry. By default, the tool unpublishes from the private WSDK registry.

Chapter 18. WebSphere SDK for Web Services

405

Unpublishing a business entity or service To unpublish a business entity or business service: cd /bin UDDIUnpublish -business -businessName [] UDDIUnpublish -service -serviceName -businessName -removeTModels []

A message is returned informing us that the unpublish operation completed successfully. The unique key for the deleted business entity or business service is also displayed.

Security for unpublishing Security is handled in the same way as for publishing (see “Security for publishing” on page 404).

Additional properties With the -uddiprops argument of UDDIUnpublish, we can specify the location of a Java properties file that contains additional input information. The following properties are used by UDDIUnpublish:
wsdk.uddi.publish.url—Overrides the URL to the publish API of the remote UDDI registry. Unless this property is set, the tool will publish to the WSDK private registry.
wsdk.uddi.inquiry.url—Overrides the URL to the inquiry API of the remote UDDI registry. Unless this property is set, the tool will send inquiries to the WSDK private registry. We can use the three provided properties files with UDDIUnpublish to remove businesses and services from the public IBM UDDI V2 Business Test Registry and IBM UDDI V2 Business Registry:
speedstart.properties (with categories for the IBM Speed Start program)
testregistry.properties
businessregistry.properties

Sample 1—JavaBean request/response Web service Here we describe sample 1 to give us an idea of what WSDK samples are. Sample 1 is a simple request-response Web service.

406

WebSphere Version 5.1 Web Services Handbook

Figure 18-7 Sample 1 scenario

The request message contains a string provided by the service requestor (that is, the user), usually his name. The response message from the Web service is “Hello !”, where is the argument passed in the request message. The scenario is described in Figure 18-7.
The Web service is a JavaBean application, Sample1WebService.ear, that has been Web services-enabled using the Bean2WebService tool. The only method in this Java bean is getGreeting, which takes a string, , and returns another string, “Hello !”
Sample 1 uses the -splitWsdl option to generate two WSDL files, the interface and the implementation. The WSDL document, containing service interface and implementation definitions, is accessed in the server at: http://localhost:6080/Sample1WebService/services/Sample1?wsdl


The WSDL2WebService tool is used to create the client-side bindings from the WSDL document describing the Web service.
When invoked, the client code obtains a static stub from the service locator and uses it to make a call to the Web service's getGreeting operation. Refer to the Accessing a Web service from a service locator client section of the WSDK 5.1 documentation for a description of the service locator client.
The Java client code is located in: \apps\Sample1\src\requester\com\ibm\wsdk\Sample1


Sample 1 uses the document/literal communication/encoding style, described in the WSDL bindings section of the WSDK 5.1 documentation.

Using sample 1 First, start the application server by invoking this command: \bin\appserver start

To run the sample client: cd /apps/Sample1/bin runclient.bat

Chapter 18. WebSphere SDK for Web Services

407

The output from running this sample is shown below, where Bertrand is the value of the parameter passed with the command. *************************************************** This is a J2SE client for Sample1. It will make a call to the getGreeting method of Sample1's service through a ServiceLocator. *************************************************** Hello Bertrand!

Rebuilding sample 1 If we want to rebuild the samples, WSDK provides detailed step-by-step instructions on how to do so. This section describes how to rebuild sample 1.
Compile the service provider source code (in this case a very simple Java bean called Hello): cd \apps\Sample1\src\provider \appserver\java\bin\javac -d \apps\Sample1\classes\provider com\ibm\wsdk\Sample1\Hello.java


Use the Bean2WebService tool to create a Web service from the compiled Java bean. Run the following commands: cd \apps\Sample1 \bin\Bean2WebService.bat -project Sample1WebService -methods "getGreeting" -servicePortName Sample1 -style WRAPPED -splitWsdl -sei .\src\provider\com\ibm\wsdk\Sample1\Sample1Interface.java -deploy -cp .\classes\provider com.ibm.wsdk.Sample1.Hello

This first removes any old versions of the classes, and then creates a new Sample1WebService project, rebuilds the archive, and finally deploys it to the application server. Note that during this last stage we are prompted for confirmation before overwriting the existing Sample1WebService application that is already installed on the application server, and the original EAR file is backed up to Sample1WebService.ear.backup. The -splitWsdl option causes separate implementation and interface WSDL documents.
Compile the service requestor source code. This consists of several helper classes automatically generated as source into the Sample1\Sample1WebService\client-side directory by the Bean2WebService tool, and also the J2SE client itself, located in the Sample1\src\requester directory. Copy the generated Java source files into this directory and compile everything using the supplied build script, by entering: \apps\Sample1\bin\buildclient.bat

408

WebSphere Version 5.1 Web Services Handbook

We have now successfully created the sample 1 Web service.
To check that it has worked, make sure the application server is running, and then start the application by entering the command: \bin\appserver.bat startapp Sample1WebService

Open up a browser and point to: http://localhost:6080/Sample1WebService/services/Sample1

We should see the confirmation message that the Web service has been deployed and is running successfully: And now...Some Services

Implementing the weather forecast Web service In this section we use the EJB2WebService tool to implement the weather forecast Web service. We start with an enterprise application (ItsoWebService7) that contains an EJB module (ItsoWebService7EJB) with a session bean (WeatherForecastEJB) that provides the weather forecast application: sg246891-01\sampcode\wsdk51\weather\ItsoWebService7.ear

Setting up the environment Note: Please refer to “Set up the WEATHER database” on page 528 if the WEATHER database has not yet been created. Copy the sample data for the weather forecast application to the wsdk51sample folder: from: sg246891-01\sampcode\wsdk51\weather to: c:\wsdk51sample\weather

First, we set the required environment to run the weather forecast application. We create a JAAS authentication alias, a JDBC Driver, and a data source. Use the WeatherDataSource.jacl script provided in: wsdk51sample\weather\setDataSource

Note: You have to tailor the WeatherDataSource.jacl file before executing (for DB2 Version 7.2 use the WeatherDataSource7.jacl file):
set driverClassPath: With correct DB2 directory
set defaultUser/set defaultPassword: With valid user ID and password

Chapter 18. WebSphere SDK for Web Services

409

Run the wsadmin tool using these commands: cd wsdk51sample\weather\setDataSource set PATH=d:\\appserver\bin;%PATH%; call wsadmin -f WeatherDataSource.jacl -conntype SOAP -host localhost -username admin -password adminpwd

The tool displays this output: WASX7209I: Connected to process "server1" on node DefaultNode using SOAP connector; The type of process is: UnManagedProcess Add an alias aliasW create JAASAuthData object for aliasW Installing DB2 datasource for WEATHER Finding the server server1 Found server server1(cells/DefaultNode/nodes/DefaultNode/servers/server1:server.xml#Serv er_1) Finding the Resource Adapter Creating the provider for com.ibm.db2.jcc.DB2ConnectionPoolDataSource Creating the datasource weather

Running the EJB2WebService tool After we configured the data source, we can create and deploy the weather forecast Web service. Run the EJB2WebService tool using the commands provided in RunEJB2WS.bat (edit the file before running): cd wsdk51sample\weather set PATH=d:\\bin;%PATH%; call EJB2WebService -methods getDayForecast getForecast getTemperatures -verbose -deploy -style wrapped -use literal -clientType J2SE -genMain WeatherClient -project ItsoWebServiceWSDK -ri itso.session.WeatherForecastEJB ItsoWebService7.ear

Note: Installation of the enterprise application is automated using the -deploy option of the EJB2WebService command. The tool displays this output with the -verbose option (abbreviated): Creating new project: ItsoWebServiceWSDK ... Generating the service endpoint interface... Generating WSDL: WSWS3010I: Info:Generating portType {http://session.itso}WeatherForecastEJB .... WSWS3010I: Info: Generating port WeatherForecastEJBBean

410

WebSphere Version 5.1 Web Services Handbook

Generating server side files: WSWS3185I: Info: Parsing XML file: c:\wsdk51sample\weather\ItsoWebServiceWSDK\META-INF\wsdl\WeatherForecastEJB.wsdl WSWS3282I: Info: Generating c:\wsdk51sample\weather\ItsoWebServiceWSDK\ wsdl2java_output\itso/mapping/Weather.java .... Configuring webservices.xml ... Saved archive: C:\wsdk51sample\weather\ItsoWebServiceWSDK\ItsoWebServiceWSDK.ear Checking server for existing application... Deploying Web Service client... Deploy command: "d:\\appserver\..\bin\appserver.bat" install \"C:/wsdk51sample/weather/ItsoWebServiceWSDK/ItsoWebServiceWSDK.ear\" {-usedefaultbindings -deployejb -appname \"ItsoWebServiceWSDK\"} .... ADMA5016I: Installation of ItsoWebServiceWSDK started. ADMA5018I: Starting EJBDeploy on ear .....\Temp\app56613.ear.. [EJBDeploy] Starting workbench.Starting workbench. .... [EJBDeploy] EJBDeploy complete.EJBDeploy complete. [EJBDeploy] 0 Errors, 0 Warnings, 0 Informational Messages 0 Errors, 0 Warnings, 0 Informational Messages .... ADMA5013I: Application ItsoWebServiceWSDK installed successfully. Generating client side files: WSWS3185I: Info: Parsing XML file: C:\wsdk51sample\weather\ItsoWebServiceWSDK\META-INF\wsdl\WeatherForecastEJB.wsdl .... Creating client-side build script... Creating main class... All done.

Manual installation of the enterprise application would use this command: appserver install \"C:/wsdk51sample/weather/ /ItsoWebServiceWSDK/ItsoWebServiceWSDK.ear\" {-usedefaultbindings -deployejb -appname \"ItsoWebServiceWSDK\"}

Generated output A subdirectory with the project name (ItsoWebServiceWSDK) is created. It contains:
ItsoWebServiceWSDK.ear—Installable enterprise application
META-INF folder with: – webservices.xml and ibm-webservices-XXX.xmi—Deployment descriptor and IBM bindings for the Web service – WeatherForecastEJB_mapping.xml—JAX-RPC mapping file

Chapter 18. WebSphere SDK for Web Services

411

– ejb-jar.xml and ibm-ejb-jar-bnd.xmi—Deployment descriptor and IBM binding for the EJB – wsdl folder with WeatherForecastEJB.wsdl
The implementation code of the Web service: – itso\mapping folder with Weather, Weather_Ser, Weather_Deser, Weather_Helper and WeatherPredictor – itso\session folder with WeatherForecastEJB_SEI and original classes (WeatherForecastEJB, WeatherForecastEJBHome, WeatherForecastEJBBean)
client-side folder with: – buildclient.bat and runclient.bat—To build and run the J2SE client we requested – itso\mapping folder with Weather, Weather_Ser, Weather_Deser, Weather_Helper – itso\session folder with WeatherForecastEJBBeanSoapBindingStub, WeatherForecastEJB (the interface), WeatherForecastEJBService, WeatherForecastEJBServiceLocator, and WeatherClient – META-INF folder with WeatherForecastEJB_mapping.xml, webservicesclient.xml, ibm-webservicesclient-XXX.xmi – META-INF\wsdl folder with the WSDL file
The installed enterprise application can be found in: d:\\appserver\installedApps\DefaultNode\

Starting the Web service in the application server Start the server using the appserver start command and wait for a ready message. If the server is already running, we must start the newly installed enterprise application using the command: appserver startapp ItsoWebServiceWSDK Enabling application ItsoWebServiceWSDK WASX7357I: By request, this scripting client is not connected ..... enabling ItsoWebServiceWSDK Enable process complete for application ItsoWebServiceWSDK WASX7209I: Connected to process "server1" on node DefaultNode using SOAP connector; The type of process is: UnManagedProcess starting ItsoWebServiceWSDK Start process complete for application ItsoWebServiceWSDK

412

WebSphere Version 5.1 Web Services Handbook

Creating and running a stand-alone client A small stand-alone client uses the service locator to access the Web service (Example 18-7). We modify the default skeleton generated by the tool with the code of our client (see wsdk51sample\weather\client). Example 18-7 Stand-alone client for weather forecast using service locator /* Generated by WSDK on Wed Dec 03 05:41:49 PST 2003 */ package itso.session; import itso.mapping.*; import java.util.Calendar; import java.text.SimpleDateFormat; public class WeatherClient { public static void main(String[] args) { try { WeatherForecastEJBServiceLocator loc = new WeatherForecastEJBServiceLocator(); // Call to the service locator's get() method .....e itso.session.WeatherForecastEJB port = loc.getWeatherForecastEJBBean(); /* Make calls to methods of the PortType to access the Web Service */ //gets today weather forecast Weather today = port.getDayForecast(Calendar.getInstance()); System.out.println("Today weather forecast..."); System.out.println(printWeather(today)); //gets weekly temperatures int[] temp = port.getTemperatures(Calendar.getInstance(),6); System.out.println("Weekly temperatures forecast for next week..."); for (int j = 0; j < 7; j++) System.out.println("Day " + (j+1) + ": "+ temp[j] + " Celsius"); //gets the weekly weather forecast Weather[] week = port.getForecast(Calendar.getInstance(),6); System.out.println("Weekly weather forecast for next week..."); for (int j = 0; j < 7; j++) System.out.println(printWeather(week[j])); } catch (java.lang.Exception e){ e.printStackTrace(); } } /** * printWeather creates a string with the weather information

Chapter 18. WebSphere SDK for Web Services

413

* @param w The weather object * @return A string with the weather information */ private static String printWeather(Weather w) { SimpleDateFormat sdf = new SimpleDateFormat("EEE. MMM d, yyyy"); return "Weather: " + sdf.format(w.getDate().getTime()) + " '" + w.getCondition() + "' wind: " + w.getWindDirection() + " " + w.getWindSpeed() + "km/h " + w.getTemperatureCelsius() + " Celsius"; } }

Client logic The main logic is very simple: A service locator is created, the port of the service is retrieved, and the service methods are invoked: WeatherForecastEJBServiceLocator loc = new WeatherForecastEJBServiceLocator(); itso.session.WeatherForecastEJB port = loc.getWeatherForecastEJBBean(); Weather today = port.getDayForecast(Calendar.getInstance());

Service locator or service factory Using the service locator (ServiceLocator class) may not work on all JAX-RPC implementations. For portable client code with WSDL document in a single file, the ServiceFactory should be used instead, as shown in WSDK's sample 5. We provide a second client (ServiceFactoryClient.java) that uses the service factory. An extract of the code is shown in Example 18-8. Note: This client can be used only if we generate the Web service without the -splitWsdl option. Example 18-8 Stand-alone client for weather forecast using service factory ...... import javax.xml.namespace.QName; import javax.xml.rpc.Service; import javax.xml.rpc.ServiceFactory; public class ServiceFactoryClient { public static void main(String[] args) { String wsdlURL = "http://localhost:6080/ItsoWebServiceWSDK/services/WeatherForecastEJBBean?wsdl"; String namespace = "http://session.itso"; String serviceName = "WeatherForecastEJBService"; String portName = "WeatherForecastEJBBean"; try { ServiceFactory factory = ServiceFactory.newInstance();

414

WebSphere Version 5.1 Web Services Handbook

Service myService = factory.createService( new java.net.URL(wsdlURL), new QName(namespace, serviceName) ); WeatherForecastEJB port = (WeatherForecastEJB)myService.getPort( new QName(namespace, portName), WeatherForecastEJB.class); /* Make calls to methods of the PortType to access the Web Service */ ...... // rest identical to WeatherClient.java

Compile and run the client Copy the WeatherClient.java and ServiceFactoryClient.java files into the generated client-side directory: from: wsdk51sample\weather\client to: wsdk51sample\weather\ItsoWebServiceWSDK\ client-side\itso\session Compile the client and all the generated code using the buildclient.bat file (in wsdk51sample\weather\ItsoWebServiceWSDK\client-side). Run the client using the runclient.bat file. To run the ServiceFactoryClient modify the runclient.bat file.

Sample client output Here is a sample output: Today weather forecast... Weather: Wed. Dec 3, 2003 'rainy' wind: E 31km/h -4 Celsius Weekly temperatures forecast for next week... Day 1: -4 Celsius Day 2: -8 Celsius ...... Weekly weather forecast for next week... Weather: Wed. Dec 3, 2003 'rainy' wind: E 31km/h -4 Celsius Weather: Thu. Dec 4, 2003 'partly cloudy' wind: SW 40km/h -8 Celsius ......

Cleanup In the rest of the chapter we are going to use the WSDK plug-in for Eclipse. To make the server start faster, we suggest that you remove the applications we installed: appserver uninstall StringService appserver uninstall ItsoWebServiceWSDK

Chapter 18. WebSphere SDK for Web Services

415

Using the WSDK plug-in for Eclipse If you have Eclipse 2.1.1 installed on your workstation, then you can select to install the WSDK plug-in for Eclipse when you install WSDK (see “Installation of WebSphere SDK for Web Services 5.1” on page 523). Note: What we call here the WSDK plug-in is really a set of plug-ins that together provide the functionality of WSDK in the base Eclipse environment.

Starting Eclipse with the WSDK plug-in WSDK provides a Launch Eclipse icon in the WSDK program group. Start Eclipse and a workspace is initialized, by default in /workspace. Figure 18-8 shows the Eclipse workbench after the applications discussed here have been created. Open the Java, Resource, and Server perspectives.

Projects Perpectives

Editor

Server

Figure 18-8 Eclipse workbench

416

WebSphere Version 5.1 Web Services Handbook

Preparing a server We will use the WSDK server for the testing of WSDK-generated Web services applications:
Open the Server perspective and select File -> New -> Server and Server Configuration.
Expand WebSphere Version 5.0 and select WSDK 5.1 Server. Enter WSDKServer as the name for the server. Click Finish. Note: You cannot configure this server; therefore, data sources must be defined outside of Eclipse (see “Setting up the environment” on page 409).

Creating a Web service from a JavaBean In this section we use Eclipse and the WSDK plug-in to create a Web service from a JavaBean.

Create a Web project First we create a Web project:
Select File -> New -> Project -> Web -> Dynamic Web Project.
Enter ItsowebServiceEclipseWeb as the name, select Configure advanced options, and click Next.
Enter ItsoWebServiceEclipse as the enterprise application name. Click Finish.
In the Server perspective select the WSDKServer and Add and remove projects. Select the ItsoWebServiceEclipse project and add it to the server.

Import the weather forecast application In the ItsowebServiceEclipseWeb project create two packages under JavaSource: itso.bean and itso.mapping. Import the code from sg246891-01\sampcode\wsdk51\eclipse\import:
Select the itso.bean package and Import. Select File system, navigate to ...\eclipse\import, and import the WeatherForecast bean.
Select the itso.mapping package and Import. Import the WeatherPredictor and Weather beans.
Select the META-INF folder in the ItsoWebServiceEclipse enterprise application and import the was.policy file. This is required for the data source because Java 2 Security is enabled in the server.

Chapter 18. WebSphere SDK for Web Services

417

Note: Alternatively Java 2 Security can be disabled in the server by editing: /appserver/config/cells/DefaultNode/security.xml

And changing the value:

Run the Web Service wizard The WSDK plug-in provides a Web Service wizard that has a subset of the functions of the same wizard in Application Developer. We use the wizard to generate a Web service from the WeatherForecast bean:
Select the WeatherForecast bean in the ItsowebServiceEclipseWeb project and New -> Other -> Web Service -> Web Service.
Select Start Web service in Web project, Generate a proxy, and Test the generated proxy (Figure 18-9).

Figure 18-9 Web Service wizard: Start


On the next page verify that ItsoWebServiceEclipseWeb is the service project and ItsowebServiceEclipseWebClient is the client project (this project will be created).
On the next page the WeatherForecast JavaBean is preselected.
On the next page select the three get methods, but deselect the setWeather method. Select Document/Literal and No Security (Figure 18-10).

418

WebSphere Version 5.1 Web Services Handbook

Figure 18-10 Web Service wizard: Methods and style


On the next page select Generate proxy. Note that the proxy will go into the ItsowebServiceEclipseWebClient project (Figure 18-11).

Figure 18-11 Web Service wizard: Proxy


On the next page select Test the generated proxy and Run test on server. Note that the test client will go into the sample/WeatherForecast folder in the client project (Figure 18-12).

Chapter 18. WebSphere SDK for Web Services

419

Figure 18-12 Web Service wizard: Test client


On the final page click Finish (we do not publish into UDDI). The Web service is installed, the client proxy and test client are generated, and the WSDKServer is started...be patient.

Generated code In the ItsowebServiceEclipseWeb project you will find:







SEI (service endpoint interface) WeatherForecast_SEI Helper classes: Weather_Deser, Weather_Helper, Weather_Ser WSDL file: WeatherForecast.wsdl Deployment descriptor: webservices.xml Mapping file: WeatherForecast_mapping.xml Servlet configured in web.xml: itso_bean_WeatherForecast

In the ItsowebServiceEclipseWebClient project you will find:







420

Proxy classes in itso.bean Helper classes in itso.mapping Test client in sample\WeatherForecast Deployment descriptor in WEB-INF: webservicesclient.xml Mapping file: WeatherForecast_mapping.xml WSDL file

WebSphere Version 5.1 Web Services Handbook

Testing the Web service The test client should be started automatically, or you select the TestClient.jsp (in the ItsoWebServiceEclipseWebClient project) and Run on Server. When prompted for a server, always select the WSDKServer and Set server as project default. Note: Sometimes it is necessary to publish the application manually. Select the WSDKServer and Publish. Select one of the methods, enter the parameter(s), and click Invoke (Figure 18-13).

Figure 18-13 Web service test client

Using the Web Services Explorer Select the WeatherForecast.wsdl file (in the ItsowebServiceEclipseWeb project) and Web Services -> Test with Web Services Explorer. The Web Services Explorer opens (be patient...):
Select one of the methods and enter the parameter(s). Click Browse to select a date from the calendar.
Click Go to invoke the service and the result is displayed (Figure 18-14).

Chapter 18. WebSphere SDK for Web Services

421

Figure 18-14 Web Services Explorer


Click Source to see the SOAP XML messages. Expand the window to see the text (Figure 18-15). The complete output message is: - - - - sunny 2003-12-25T18:27:22.549Z SE 11 36 0

422

WebSphere Version 5.1 Web Services Handbook

<

Figure 18-15 Web Services Explorer: SOAP XML

Creating and running a client Now let us create a real client application:
In the ItsowebServiceEclipseWebClient project create an itso.client package.
Import the two files BeanClient.java and ServletClient.java from sg246891-01\sampcode\wsdk51\eclipse\client into the new package.
Study the BeanClient. This is a stand-alone application that uses the proxy classes to run the three methods of the Web service. The output is displayed to the Console.
In the Java perspective, select the BeanClient and Run -> Run As -> Java Application. The output is displayed in the Console and is similar to “Sample client output” on page 415.
Study the ServletClient. This is an HTTP servlet that uses the proxy classes to run the three methods of the Web service. The output is displayed as HTML.

Chapter 18. WebSphere SDK for Web Services

423


In the Server perspective, select the ServletClient and Run on Server. The enterprise application is republished to the server (you can also select the WSDKServer and Publish). The servlet is started in a Web browser and the formatted output is displayed (Figure 18-16).

Figure 18-16 Web service servlet client

After testing the servlet, select the ItsoWebServiceEclipse application under the WSDKServer and Remove.

Creating a Web service from a session EJB In this section we use Eclipse and the WSDK plug-in to create a Web service from a session EJB.

Import an EJB JAR file You cannot create EJBs in the Eclipse plug-in, but you can run EJBs. We start by importing an EJB JAR file:
Select File -> Import. In the dialog select EJB JAR file and click Next.
Click Browse and navigate to the file: sg246891-01\sampcode\wsdk51\eclipse\ejb\ItsoWebService2EJB.jar


The EJB project name is set to ItsoWebService2EJB. Overtype ItsoWebService2 as the EAR project name and click Finish.

424

WebSphere Version 5.1 Web Services Handbook

Note: You get many warnings in the Tasks view about import statements not being used. This does occur in the generated code of EJBs.

Create a Web project Invoking an EJB Web service requires a Web router project:
Select File -> New -> Project -> Web -> Dynamic Web Project.
Enter ItsowebService2Router as the name, select Configure advanced options, and click Next.
Select ItsoWebService2 as the enterprise application name. Click Finish.
In the Server perspective select the WSDKServer and Add and remove projects. Select the ItsoWebService2 project and add it to the server. Note: We suggest that you remove the ItsoWebServiceEclipse project from the server for better performance.

Run the Web Service wizard We use the Web Service wizard to generate a Web service from the WeatherForecastEJB session bean:
Select File -> New -> Other -> Web Service -> Web Service.
Select EJB Web service as Web service type. Select Start Web service in Web project, Generate a proxy, and Test the generated proxy.
On the next page verify that ItsoWebService2Router is the router project, ItsoWebService2EJB is the EJB project, and ItsowebService2EJBClient is the client project (this project will be created).
On the next page click Browse EJB beans. Select the WeatherForecastEJB and click OK. The rest of the fields are now filled in.
On the next page select the three get methods, but deselect the setWeather method. Select Document/Literal and No Security.
On the next page select Generate proxy. Note that the proxy will go into the ItsowebService2EJBClient project.
On the next page select Test the generated proxy and Run test on server. Note that the test client will go into the sample/WeatherForecastEJB folder in the client project.
On the last page click Finish. The Web service is installed; the router project, client proxy, and test client are generated; and the WSDKServer is started...be patient.

Chapter 18. WebSphere SDK for Web Services

425

Generated code In the ItsowebService2EJB project you will find:






SEI (service endpoint interface) WeatherForecastEJB_SEI (itso.session) Helper classes: Weather_Deser, Weather_Helper, Weather_Ser WSDL file: WeatherForecastEJB.wsdl Deployment descriptor: webservices.xml Mapping file: WeatherForecastEJB_mapping.xml

In the ItsowebService2Router project you will find:
Servlet configured in web.xml: WeatherForecastEJB, pointing to com.ibm.ws.webservices.engine.transport.http.WebServicesServlet In the ItsowebService2EJBClient project you will find:







Proxy classes in itso.session Helper classes in itso.mapping Test client in sample\WeatherForecastEJB Deployment descriptor: webservicesclient.xml Mapping file: WeatherForecastEJB_mapping.xml WSDL file

Testing the EJB Web service The test client should be started automatically, or you select the TestClient.jsp and Run on Server. The test client runs identical to the JavaBean Web service test client. You can also use the Web Services Explorer (see “Using the Web Services Explorer” on page 421). Note: You may have to republish the enterprise application to make it work. Select the WSDKServer and Publish.

Creating a stand-alone client application With the server running and the EJB application (ItsoWebService2) installed, we can use a stand-alone client to access the EJB Web service. The code of the stand-alone client (EJBClient) is provided in: sg246891-01\sampcode\wsdk51\eclipse\EJBclient\itso\client\EJBClient.java

An extract of the code shows how the proxy is used: WeatherForecastEJBServiceLocator loc = new WeatherForecastEJBServiceLocator();

426

WebSphere Version 5.1 Web Services Handbook

WeatherForecastEJB port = loc.getWeatherForecastEJB(); Weather today = port.getDayForecast(Calendar.getInstance()); ......

To run the client we require the proxy classes (itso.session package), the mapping classes (itso.mapping package), and the Web service runtime JAR files.

Exporting the proxy and mapping classes We export the required classes from the Eclipse workbench:
Expand the ItsoWebService2EJBClient project and select the itso folder (under JavaSource) and Export.
Select File system and click Next.
For the target directory click Browse and locate: sg246891-01\sampcode\wsdk51\eclipse\ejbclient


Select Overwrite existing files without warning and click Finish.
The session and mapping folders are created under the itso folder.

Compile and run the client We provide the runEJBclient.bat file in the EJBclient folder to compile the client and run it. You have to tailor the directory names before executing the code: set LIB=d:\\appserver\lib set SYSTEM_CLASSPATH=%LIB%\webservices.jar;%LIB%\commons-logging-api.jar; %LIB%\j2ee.jar;%LIB%\qname.jar "d:\\appserver\java\bin\javac" -extdirs %LIB% -classpath . itso\client\*.java itso\mapping\*.java itso\session\*.java set CLASSPATH=.;%SYSTEM_CLASSPATH% "d:\\appserver\java\bin\java" itso.client.EJBClient

You have to run the command file from the EJBclient folder. The client produces sample output similar to “Sample client output” on page 415.

Chapter 18. WebSphere SDK for Web Services

427

Summary In this chapter we provided a short overview of the WebSphere SDK for Web Services Version 5.1 and described the differences between this package and the Emerging Technologies Toolkit. We also implemented our weather forecast example with the WSDK by generating the Web service using the EJB2WebService tool, installing it into the application server, and using a simple client to invoke the Web service. Finally we used the WSDK plug-in for Eclipse to work with JavaBean and EJB Web services. Note: The WSDK plug-in functionality is a subset of the Web services functions in WebSphere Studio Application Developer (see Chapter 15, “WebSphere Studio Application Developer” on page 247).

More information The WSDK Web site contains additional information: A FAQ list, a forum, and downloads. Check it out at: http://www.ibm.com/developerworks/webservices/wsdk/

The speed-start program for Web services is located at: http://www.ibm.com/developerworks/offers/ws-speed-start/

After installing the product we can find more information about the WSDK in the InfoCenter. Use the wsdkHelp command, located in the /bin directory, or click the WSDK Help icon from the program group. The WSDK Help is also available in the Eclipse environment using Help -> Help Contents.

428

WebSphere Version 5.1 Web Services Handbook

19

Chapter 19.

Web services scenario: Architecture and implementation This chapter describes a scenario that integrates most technologies and concepts presented earlier in this book. It gives an introduction to implementing the service-oriented architecture to meet the requirements of everyday business. We also show how the previously described concepts and technologies are incorporated into the solution. This chapter is structured as follows:
The scenario situation including requirements
A detailed description of the solution, including the following issues: – The project phases to build up the application, such as system build, deployment, and run – The processes within the application – General concepts of the implementation – Details of different client implementations

© Copyright IBM Corp. 2003, 2004. All rights reserved.

429

Overview In this chapter we present a detailed scenario that combines selected concepts and technologies presented in Part 1, “Web services concepts”. Due to the limitations of the scope of this book, we do not present a full-blown e-business application; instead we focus on selected aspects that we consider to be the most relevant issues in Web services technology in everyday projects. The scenario extends the weather forecast example presented in Chapter 14, “Weather forecast application” on page 233. The original example contains a Web service created from an EJB and from a JavaBean. Now we extend this by introducing several providers for that service using different implementations, a requestor that integrates the services into a local application, and a requestor that updates the information. Furthermore, security features are applied. We decided to focus on a single tool, WebSphere Studio Application Developer 5.1.1. It is the tool to use for tasks in many projects, because:
Application Developer Integration Edition will offer the same functionality plus extra features, such as work flow (see Figure 12-1 on page 204 for details). These additional tools, however, are not commonly used.
The other tools presented in the book (WebSphere SDK for Web Services and Emerging Technologies Toolkit) provide different possibilities to create Web services. Neither tool offers the basic range programming functionality provided by Application Developer.

Scenario situation In this chapter we extend the weather forecast scenario. In previous chapters we discussed different paths to build Web services. We have shown how to build the service bottom-up and top-down, and how to create a static client. For this scenario we take the existing Web services and discuss the challenges in creating a client. (We do not cover the creation of the services and the implementation of security for the services.) We assume the following situation:
There are several companies that provide weather forecasts. We introduce two companies:1 – SiliconWeather (www.siliconweather.com) – FlashAndThunder (www.flashandthunder.com) 1

430

These names are invented and do not relate to existing companies or persons. At the time of writing this book, neither was an existing Web site.

WebSphere Version 5.1 Web Services Handbook


Furthermore, there is an umbrella corporation for the weather business, the International Weather Association (IWA), that operates as a standards body. IWA specifies the format in which its members must provide their services and a requestor to updated weather information to its members. Both service providers are members of IWA: IWA (www.internationalweatherassociation.com)
Finally, our scenario contains an integrator, UnitedSuns (www.unitedsuns.com), which wants to generate business by integrating multiple weather forecasts and packaging them into a product or service.
All participants agree on a joint project that will offer a joint weather forecast to users. This forecast is generated by putting together individual information from the weather forecast producers. The providers give access to daily and weekly forecasts updated by IWA. Here we use the functionality used in the previous chapters and described for J2EE environments in Chapter 4, “JAX-RPC (JSR 101)” on page 67, and in Chapter 5, “Implementing Enterprise Web Services (JSR 109)” on page 77. As a special feature, FlashAndThunder offers its service in two flavors: A regular service called thunder, and an extremely accurate premium service called flash.
The participants agree to use Web services technology. According to Web services terminology, SiliconWeather and FlashAndThunder are service providers, while UnitedSuns and IWA act as service requestors. Furthermore, a UDDI registry is used to publish and retrieve Web services by UnitedSuns.
Providers generate Web services, WSIL documents, and WSDL documents according to a Web service interface WSDL provided by the IWA. The providers publish their services in the UDDI registry.

Requirements In a real project environment, the customer defines the requirements, possibly together with a technical consultant. Because this is only a sample application, we have invented our requirements.

Functional requirements To run the envisaged business, UnitedSuns and the providers must be able to perform a number of processes. Not all of them are run totally automated. The providers must be able to retrieve IWA’s service interfaces and publish their own

Chapter 19. Web services scenario: Architecture and implementation

431

services to the registry. UnitedSuns must be able to perform the following functionality:
Access the UDDI registry to find suitable providers and retrieve their service description (manual and automated).
Access providers and read their WSIL to decide on their suitability and to find their service (manual and automated).
Invoke the services of the providers and process the result into a Web page. Figure 19-1 provides an abstract overview of the interaction between the actors. For the sake of readability, we have drawn arrows only from the SiliconWeather provider. Of course, FlashAndThunder is treated in the same way.

JMS topic queue

IWA

update database information

provide updated weather publish references to defined standard

Silicon Weather

retrieve references

FlashAnd Thunder

publish services

UDDI invoke service find services

United Suns Figure 19-1 Actors in the scenario and their responsibilities

Non-functional requirements In a typical e-business application, non-functional requirements are often very important. They include such issues as availability, security, performance, maintainability, and portability. In our proof-of-concept scenario, most of these issues will not be addressed.

432

WebSphere Version 5.1 Web Services Handbook

We focus only on security, where we identify the following requirements:
Authentication for accessing a service
Integrity of the information transmitted
Secure transmission of requests and responses Furthermore, both providers would like to be able to change their access points rather frequently, which requires a flexible invocation.

Solution We now present our solution to address these requirements.

Incorporating Web services concepts and technologies To fulfill the requirements, we incorporate the following Web services concepts and technologies covered in this book:
The standard technologies WSDL, SOAP, and UDDI.
WSIL for retrieving Web service descriptions directly from the provider’s server.
UDDI4J, WSDL4J, and WSIL4J APIs for URL dynamic service invocation.
WS-Security and WebSphere security.

Process to create the application There are many steps to be performed to build the application. However, not all of them are processed automatically. For this chapter, we focus on the development of the client (that is, the requestor) code and on deployment and administration issues. The generation of the server-side code of the providers has already been described in depth in the previous chapters. Thus, we shorten this description and integrate the entire development of the server-side Web service (build, deployment, and run phases) into one setup phase. So we have to distinguish between four phases: 1. Setup phase—During this phase, preparation steps are taken, many of them manually. The providers generate and deploy Web services, WSIL documents, and WSDL documents according to a given Web service interface provided by the IWA. The providers publish the WSDL documents in the UDDI registry. 2. Build phase of the client application—In this phase the requestor’s application is constructed, including proxies or stubs and the business logic that uses them.

Chapter 19. Web services scenario: Architecture and implementation

433

3. Deployment phase of the client application—Next the developed application is deployed into an environment, including the security requirements. 4. Run phase of the client application—Finally the application is run. During runtime, the application performs a dynamic invocation of the provided services. The IWA also updates the weather information of the providers with the accurate values. These phases refer to the four-phase model described in Chapter 13, “Web services development overview” on page 221. For our example, we do not focus on the management phase presented in that chapter.

Types of service invocation For our scenario, we provide two ways to actually find the service (in the implementation we refer to them as sample 1 and sample 2) and one way to update the weather forecast:
Look up with UDDI—The requestor accesses the UDDI registry and retrieves references of implementations of the services requested.
Look up with WSIL— The requestor directly enters the Web server of a provider and gets the WSIL document. This document includes a reference to possibly several local WSDL documents or a UDDI registry, where the provider is registered. In that case the requestor has to access the registry to find a reference to the WSDL. We describe both variants as concepts; however, we provide code samples only for the first choice.
Weather update with JMS—IWA uses a JMS connection topic to provide the most updated and accurate information available. The providers retrieve that information and use it to update their databases providing the last information to their customer, UnitedSuns. Note: To simplify, we only provide code to update the SiliconWeather database using a connection queue. All providers also share the same database. In our scenario, the application retrieves the WSIL and WSDL documents at runtime, although these documents have already been retrieved at build time. This makes sense in situations in which the Web service access point changes quite often or when there is more than one provider that implements the service. Otherwise, a static invocation only during build time is acceptable.

434

WebSphere Version 5.1 Web Services Handbook

For a lookup in the UDDI registry, the requestor has to provide a description of the requested service. As a result, the requestor gets m businesses that provide n services (m and n do not necessarily have to be equal). For a lookup using WSIL, the requestor must have the URL of a given service provider. As a result, the requestor gets k services from this single business. The lookup with WSIL is a less dynamic approach, because the provider can be defined already during build time. This approach makes sense in cases where the provider is fixed and offers several implementations of the same service, or the binding access of the service changes frequently. Next, we describe in detail the four phases. In particular, we describe which steps are manual and which are performed automatically.

Setup phase For the restricted scope of this chapter, in this phase actions are performed that can be seen as preparation steps.

IWA

Service Providers

UDDI

define and store interface WSDL publish business entity, tModel retrieve tModelKey retrieve interface WSDL

generate Web service; store service WSDL deploy Web service publish business entity, publish service generate and store WSIL locally

Figure 19-2 Setup phase

Chapter 19. Web services scenario: Architecture and implementation

435

In particular, the actions shown in Figure 19-2 are performed.
The IWA decides on a standard interface for weather forecast services and describes it as an interface WSDL. This WSDL document cannot contain a service part, because that part refers to a concrete implementation of the service (which does not exist yet). If Application Developer is used to generate this WSDL document, the generated WeatherForecast.wsdl file has to be provided once the service information has been removed from the WSDL document. (The service information describes the concrete implementation, which is not available yet.)
The IWA publishes a business entity describing the IWA as an entry point for searches in the UDDI registry. The IWA also publishes a tModel. This tModel contains a tModelKey, which is a logical link to the actual WSDL document that describes the interface. Only the tModel is published to the UDDI. The WSDL document resides on IWA’s server and is not published to the UDDI. These publishing processes are done manually.
For both SiliconWeather and FlashAndThunder providers, a clerk enters the UDDI registry with a regular Web browser and retrieves the tModelKey.
The clerk can follow the link and also retrieve the WSDL file from the IWA server. Should this operation fail, the clerk contacts the IWA (for instance, using e-mail) and asks for the interface WSDL that matches the tModelKey, and IWA sends the WSDL document to the clerk.
The providers’ implementers generate the three Web services (one for SiliconWeather and the two flash and thunder services of FlashAndThunder). This is done in a top-down fashion using the Application Developer’s wizard to create a JavaBean skeleton. This skeleton is augmented with code to access the existing forecast systems. Chapter 15, “WebSphere Studio Application Developer” on page 247, describes these steps in much detail. The process also generates an implementation WSDL document (WeatherForecast.wsdl), which includes the service element that contains the actual bindings.
Each provider implements WS-Security for their Web services (see Chapter 16, “Web services security with Application Developer” on page 303).
Each provider deploys the Web service(s) to a WebSphere Application Server. See Chapter 20, “Web services runtime and deployment in WebSphere” on page 479, for instructions.
Both providers register themselves as business entities in the UDDI registry. They also publish the new generated services to the registry. (See Chapter 15, “WebSphere Studio Application Developer” on page 247, for details.) The service document, together with a binding template, describes the implemented service. The binding template contains the access point of the service. Again, no WSDL is published to the registry.

436

WebSphere Version 5.1 Web Services Handbook


Each provider generates a WSIL file and stores it on its own Web server. For our scenario the WSIL files include references to the locally stored WSDL documents and to the UDDI registry for demonstration purposes. We do not use the reference to the registry any further. FlashAndThunder’s WSIL file refers to both Web services of that company. Figure 19-3 shows the entities and relationships created during the setup phase.

UDDI Registry

IWA

IWA Business Entity

Interface WSDL

tModel

SW Business Entity

F&T Business Entity

SW SW Business Business Service Service

F&T Business Service

Binding Template

Binding Template

Silicon Weather Service WSDL

WSIL

FlashAnd Thunder flash Service WSDL

link WSDL URL access point

thunder Service WSDL

WSIL

Figure 19-3 Relationship of entities provided by IWA and the two providers

Note: The process followed by both providers to implement the automatic weather information update is slightly different. IWA has the only valid client to push the update process. Once a company turns into a member of the IWA, the company receives a package that includes a full WSDL document, including service, to locally implement the weather update Web service. Therefore, this last Web service is kept in secret among the IWA associates.

Chapter 19. Web services scenario: Architecture and implementation

437

Build phase of the client application In this phase we act as the implementer of the Web service client. We build the integration application. As stated above, we distinguish between two approaches. We present the steps to be performed, augmented with code snippets that demonstrate key aspects.

UnitedSuns Clerk

UDDI

IWA

Service Providers

find IWA business entry

Sample 1: Lookup over UDDI

retrieve IWA tModel

retrieve interface WSDL

retrieve WSIL

Sample 2: Lookup over WSIL

retrieve WSDL

Figure 19-4 Retrieving the WSDL implementation file in the build phase

We perform the steps shown in Figure 19-4.
For the lookup with UDDI option, we do not contact any provider. We manually access the UDDI to find the business entry of IWA for contact information. Also we find the tModel (for service lookups during runtime). There might be a link to the corresponding WSDL document specified in a field called Overview URL. If there is no WSDL referenced, we have to manually find the WSDL document. In our case the IWA provides the WSDL on their Web site.
For the lookup with WSIL option, we directly access the providers’ Web server and inspect the WSIL files, which are by definition located at: http://www.siliconweather.com/inspection.wsil http://www.flashandthunder.com/inspection.wsil

438

WebSphere Version 5.1 Web Services Handbook

The WSIL files specify the locations of the WSDL files, which in our case are located on the Web servers of the providers. We manually browse to the WSDL documents and retrieve them.
As described in Chapter 15, “WebSphere Studio Application Developer” on page 247, we generate the client, and as described in Chapter 16, “Web services security with Application Developer” on page 303, we apply the security features. – Authentication—Basic authentication – Integrity—Body and security token for request and body for response – Confidentiality—Body content and user name token for request and body content for response
We then generate the main code of the application. Here we have to distinguish between the two different invocation approaches. See “Run phase of the client application” on page 439 for a description of the different steps of the application.
We test the code.

Deployment phase of the client application The developed application is deployed, possibly to different test stages and eventually to the production stage. Details on deployment can be found in Chapter 20, “Web services runtime and deployment in WebSphere” on page 479.

Run phase of the client application Once UnitedSuns’ application has gone live, the automated steps are performed as shown in Figure 19-5. We distinguish between the two approaches during initialization of the application.2
Lookup with UDDI—In sample 1, the client accesses the UDDI with UDDI4J. Using the tModelKey, which has been obtained in an earlier lookup step during the build phase, the client searches for binding templates that reference this tModel. These binding templates are then used for invocation, because they contain the access points of the services.

2

It is good practice to run the lookup step only during the initialization of the application. In our proof-of-concept implementation, however, it is performed for each request.

Chapter 19. Web services scenario: Architecture and implementation

439


Lookup with WSIL—In sample 2, for each provider the client accesses the Web server and retrieves the current WSIL document: – The client uses the WSIL4J API and the URL of the WSIL document that has been retrieved during the build phase. – From the WSIL document the client retrieves the location of the most current WSDL document for each provider on their Web server. – The client accesses these WSDL documents using WSDL4J and extracts the service endpoints from the service tag in the service WSDL file and stores them locally.

UnitedSuns Application

UDDI

Service Providers

retrieve service binding

Sample 1: Lookup over UDDI

extract service access point

invoke service

retrieve WSIL

Sample 2: Lookup over WSIL

parse WSIL retrieve WSDL

parse WSDL

invoke service

Figure 19-5 Run phase

After an Internet user has entered UnitedSuns (www.unitedsuns.com) and initiated the integrated weather forecast, the client performs the following steps:
Using the gained endpoint information, the client applies the service’s getWeatherForecast(URL) method for each of the WSDL documents.

440

WebSphere Version 5.1 Web Services Handbook


The client uses the stub’s getDayForecast, getForecast, and getTemperatures methods to build its own content.
The markup is returned to the browser. In the next two sections we provide more details on the implementation of sample 1 and sample 2.

General concepts of the UnitedSuns client application The application of the fictitious company UnitedSuns is a Web application using servlets and JSPs.

Application flow The general flow in the application is that a JSP displays an HTML form asking for some parameter. When this form is submitted, a servlet is called to process the request and forward to a response JSP that presents the reply (Figure 19-6).

Home page

Menu JSP

present menu

choose sample or preferences

index.html

menu.jsp

Start JSP enter information preferences.jsp lookup.jsp client1.jsp client2.jsp

Included page

Response JSP

reusable results

display results

weatherObjects.jsp UDDIremark.html

preferences.jsp lookupResponse.jsp client1Response.jsp client2Response.jsp

Servlet process information access UDDI and Web services

SavePreferencesServlet LookupServlet StartClient1Servlet StartClient2Servlet

Figure 19-6 Scenario client application flow

Frames When starting the application, a frame set displays options in the frame called menu (at the top) and a welcome page in the frame called main, which is the content area. Using the menu, the user can choose between the different samples and the preferences window (Figure 19-7).

Chapter 19. Web services scenario: Architecture and implementation

441

Figure 19-7 Entry to the UnitedSuns Web application: IBM Almaden Lab

Abstract servlet The itso.wsdc.AbstractServlet is the base class for all servlets and provides features that are required in all subclasses. It provides helper methods such as trace, which writes a message to the console, or getPreferences, which returns the current preferences object from the HTTP session. Another method is forward, which is called after a servlet has finished processing. It takes the name of a JSP and forwards to that JSP to display the response. The AbstractServlet also cares for the UDDIProxy instance that is stored in the session. The servlet assures that the proxy is initialized with the desired inquiry URL, which was specified in the preferences.

442

WebSphere Version 5.1 Web Services Handbook

Other important features are the invocation invokeService and invokeAll methods, which call the getDayForecast method of a remote service and return the resulting Weather object, or a vector of objects. The invokeService method (Example 19-1) creates a context to look up the weather service, retrieves a stub of the service, and invokes the getDayForecast method. The resulting Weather object is returned, or an exception is thrown if a problem occurs. Example 19-1 AbstractServlet: invokeService method protected Weather invokeService(String accessUrl) throws MalformedURLException, Exception { Weather w = null; InitialContext ic = new InitialContext(); WeatherForecastService wfsl = (WeatherForecastService) ic.lookup("java:comp/env/service/WeatherForecastService"); WeatherForecast wf = (WeatherForecast) wfsl.getWeatherForecast(new URL(accessUrl)); w = wf.getDayForecast(Calendar.getInstance()); trace("StartClient1Servlet.invokeService: proxy returned weather: " + w); return w; }

The invokeAll method (Example 19-2) retrieves a vector with many access URLs that have to be invoked. For each access URL it calls the invokeService method. The resulting Weather object is added to a vector. Exceptions are caught and added to the vector instead of the Weather object. Example 19-2 AbstractServlet: invokeAll method protected void invokeAll(Vector accessUrls, HttpServletRequest request) { String invokeMessage = ""; Vector invocations = new Vector(); if (accessUrls == null || accessUrls.size() == 0) { invokeMessage = "There were no accessUrls found...”; return; } Enumeration enum = accessUrls.elements(); while (enum.hasMoreElements()) { String aMessage = ""; String accessUrl = (String) enum.nextElement(); invocations.add(accessUrl); try { Weather w = invokeService(accessUrl);

Chapter 19. Web services scenario: Architecture and implementation

443

invocations.add(w); } catch (Exception e) { trace(aMessage= ""+e.toString()+""); invokeMessage = "There were exceptions."; invocations.add(aMessage); } } request.setAttribute("invocations", invocations); request.setAttribute("invokeMessage", invokeMessage); }

Invocation result JSP After the services are invoked using the invoke methods of the AbstractServlet, the application presents the results of the invoked services. This is done in a simple table with two columns, where the first column is the access URL that was used, and the second column shows a string representation of the resulting Weather object, as illustrated in Figure 19-8.

Figure 19-8 Displaying result weather objects returned by invoked services

The JSP code to display the results is shown in Example 19-3. In our sample application this code is not in a specific response JSP, but in a separate JSP fragment called weatherObjects.jsp, which is included by the response JSPs of sample 1 and 2. The objects in the result vector can either be Weather objects after a successful invocation, or strings with an exception message text that was caught when trying to invoke the service.

444

WebSphere Version 5.1 Web Services Handbook

Example 19-3 JSP code for displaying results of invoked services ...... <% Enumeration enum = invocations.elements(); while (enum.hasMoreElements()) { String accessUrl = (String) enum.nextElement(); Object o = enum.nextElement(); %> <%= accessUrl %> <% /* distinguish between Weather result or String with exception*/ if (o instanceof String) { out.print(o); } else { itso.mapping.Weather w = (itso.mapping.Weather) o; %> <%= w.getDate().getTime() %>
<%= w.getCondition() %> <%= w.getTemperatureCelsius() %>°
Wind: <%= w.getWindDirection() %> <%= w.getWindSpeed() %>km/h <% } %> <% } %>

Preferences The preferences hold the setting that is used during runtime. The setting can be changed by the user in an online window. This setting is:
UDDI registry—Specifying which registry to be used for all UDDI interactions. You can choose one from the list, and you can also specify the inquire URL of another registry if it is not listed. Note that for the sample in this publication, all UDDI interactions were done with the IBM test registry.

Preferences class The preferences are stored in a class called itso.wsdc.Preferences and can be retrieved in any servlet by getPreferences().get. The current registry is stored as an index of the list of registries that are defined in the Util class. There is an additional field, customRegistry, which holds the URL of an optional registry, if the existing ones are not enough. In that case, the registry index is set to -1.

Chapter 19. Web services scenario: Architecture and implementation

445

The Preferences instances are stored in the HTTP session. Whenever a servlet is called, it checks if there is a preferences object in the HTTP session. If not, a preferences object is created with default values. Whenever a user changes some preferences, they are stored again in the HTTP session, but not persisted permanently.

Preferences JSP There is a JSP called preferences.jsp. This page displays the current options and also allows you to change them. It takes the preferences out of the HTTP session for display. It holds an HTML form that submits all fields to the SavePreferencesServlet. Figure 19-9 shows the JSP.

Figure 19-9 Preferences window

Preferences servlet The servlet called itso.wsdc.SavePreferencesServlet is called when the form in the preferences.jsp is submitted. It takes the parameter of the form using the getParameter method of the HTTPRequest object (registry), and stores it in the current preferences object in the HTTP session. It then forwards the request to the preferences.jsp again to redisplay the changed value.

UDDI lookup sample This part of the sample application uses the UDDI4J API to look up entries in a UDDI registry. We did not call the UDDI lookup a separate sample, because it is a human user and not a client application that wants to browse the registry. However, the tool shows the usage of UDDI4J in a dynamic client. The UDDI registry location can be specified in the preferences page (as described above).

446

WebSphere Version 5.1 Web Services Handbook

There are four possible searches that can be done:





Business entities by name Business services by name tModels by name Binding templates by the keys of a service and a tModel

UDDI lookup JSP This JSP is the starting point for the lookup, where you define the names of entities you want to look up, and the keys for the lookup of bindings. You can use the % sign as a wild card. Figure 19-10 shows the lookup window.

Figure 19-10 Starting the UDDI lookup: lookup.jsp

UDDI lookup servlet The servlet itso.wsdc.LookupServlet is used to take the parameters specified in the lookup.jsp and performs the actual inquiry. It uses the UDDIProxy object that has been prepared by the base AbstractServlet class.

Chapter 19. Web services scenario: Architecture and implementation

447

After retrieving the URL parameters and getting the UDDI proxy, the servlet calls several finder methods to perform the search. Each finder method takes some search criteria and returns a list of result objects. These methods are described in Chapter 6, “Introduction to UDDI” on page 99.

Look up businesses To look up a business entity, the find_business method of the UDDI4J API is used. Example 19-4 shows the code of the lookUpBusiness method in the LookupServlet, which shows how to:






Extract the parameters. Access the UDDI proxy object. Call the find_business method. Retrieve the vector with business information (getBusinessInfoVector). Pass the vector together with the message to the JSP by placing the two objects into the request block (setAttribute).

Example 19-4 Finding a business by name protected boolean lookUpBusiness(HttpServletRequest request) { // get the search string from the form String business = (String) request.getParameter("searchStringBusiness"); String message = ""; boolean success = false; try { // initialize a vector with the desired name. ... Vector names = new Vector(); names.addElement(new Name(business)); // invoke the finder on the uddi proxy BusinessList businessList = getUddiProxy(request). find_business(names, null, null, null, null, null, 0); // extract the vector with business infos out of the result Vector businesses = businessList.getBusinessInfos().getBusinessInfoVector(); // set a message for the response page int numberFound = businesses.size(); message = "Found " + numberFound + " business entries."; // add the resulting vector to the request for the JSP to display request.setAttribute("resultBusiness", businesses); success = true; } catch (Exception e) { // trace any exception to the console trace(message = "" + e.toString() + ""); } // add the message to the request for the JSP to display request.setAttribute("messageBusiness", message); return success; }

448

WebSphere Version 5.1 Web Services Handbook

Note that there are many null parameters in the find_business call. This is because we only have the name as search criteria for the lookup. In the other parameters we could provide further search criteria such as categorizations, referenced tModels, and so forth. We could also specify special find qualifiers specifying if the search string must fit exactly, or if the case within the name should be ignored.

Lookup services When searching for a service entity, the find_service method is used. Figure 19-5 shows an excerpt of the code of the lookUpService method in the LookupServlet, which shows how to:






Extract the parameters. Access the UDDI proxy object. Call the find_service method. Retrieve the vector with service information (getServiceInfoVector). Pass the vector together with the message to the JSP.

Example 19-5 Finding a service by name protected boolean lookUpServices(HttpServletRequest request) { String searchString = (String) request.getParameter("searchStringService"); String message = ""; ServiceList allServices = null; boolean success = false; try { Vector names = new Vector(); names.addElement(new Name(searchString)); allServices = getUddiProxy(request). find_service("", names, null, null, null, 0); Vector resultServices = allServices.getServiceInfos().getServiceInfoVector(); message = "Found " + resultServices.size() + " service entries."; request.setAttribute("resultService", resultServices); success = true; } catch (Exception e) { trace(message = "" + e.toString() + ""); } request.setAttribute("messageService", message); return success; }

Look up tModels When searching for a tModel entity, the find_tmodel method is used. Example 19-6 shows an extract of the code of the lookUpTModel method in the LookupServlet, which shows how to:
Extract the parameters.

Chapter 19. Web services scenario: Architecture and implementation

449







Access the UDDI proxy object. Call the find_tmodel method. Retrieve the vector with tModel information (gettModelInfoVector). Pass the vector together with the message to the JSP.

Example 19-6 Finding a tModel by name protected boolean lookUpTModel(HttpServletRequest request) { String searchString = (String) request.getParameter("searchStringTModel"); String message = ""; boolean success = false; try { TModelList tModelList = getUddiProxy(request). find_tModel(searchString, null, null, null, 0); Vector tModels = tModelList.getTModelInfos().getTModelInfoVector(); message = "Found " + tModels.size() + " tModel entries."; request.setAttribute("resultTModel", tModels); success = true; } catch (Exception e) { trace(message = "" + e.toString() + ""); } request.setAttribute("messageTModel", message); return success; }

Lookup bindings A binding can only exist for the combination of a service and one or more tModels. The most interesting attribute that a binding provides is the access point information. This is the URL where a service can be invoked. When searching for a binding, the find_binding method is used. Example 19-7 shows an extract of the code of the lookUpBinding method in the LookupServlet, which shows how to:






Extract the parameters. Access the UDDI proxy object. Call the find_binding method. Retrieve the vector with binding information (getBindingTemplateVector). Pass the vector together with the message to the JSP.

Example 19-7 Finding a binding for a given tModel and service protected boolean lookUpBinding(HttpServletRequest request) { String message = ""; boolean success = false; try { // check in input parameters

450

WebSphere Version 5.1 Web Services Handbook

String serviceKey = (String)request.getParameter("bindingServiceKey"); String tModelKey = (String) request.getParameter("bindingTModelKey"); if (serviceKey.trim().length() == 0 || tModelKey.trim().length() == 0) { message = "Need to specify search strings. Lookup skipped."; request.setAttribute("messageBinding", message); return true; } // ensure that tModel starts with 'UUID:' if (!tModelKey.toLowerCase().startsWith("uuid:")) tModelKey = "uuid:" + tModelKey; // create the search criteria TModelBag tModelBag = new TModelBag(); tModelBag.add(new TModelKey(tModelKey)); // call the finder BindingDetail bd = getUddiProxy(request).find_binding(null, serviceKey, tModelBag, 0); // extract the bindings vector Vector bindingTemplates = bd.getBindingTemplateVector(); // provide vector for JSP request.setAttribute("resultBinding", bindingTemplates); success = true; } catch (Exception e) { trace(message = "" + e.toString() + ""); } // provide message to JSP request.setAttribute("messageBinding", message); return success; }

Response JSP After the servlet has made all lookups, it presents the results using the lookupResponse.jsp. This result page is used in several cases; either it has found some entries, or nothing was found, or it even encountered an exception because the UDDI was not accessible. The JSP is called and it retrieves the two objects that were added by the servlet. For each lookup, there is a vector and a message. The JSP uses color encoding to make it easier to distinguish between business entities (blue), services (green), tModels (orange), and bindings (purple).

Presenting businesses and services The list of businesses and services is shown in Figure 19-11.

Chapter 19. Web services scenario: Architecture and implementation

451

Figure 19-11 Businesses and their services

The JSP iterates through the vector returned by the servlet and shows businesses and services. Both are shown with names and keys (UUIDs). Example 19-8 shows a code snippet of the JSP. Example 19-8 JSP code to display businesses and their services <% for (int i=0; i <%= bi.getNameString() %> <%= bi.getBusinessKey() %> <% Vector serviceInfos = bi.getServiceInfos().getServiceInfoVector(); for (int j=0; j --Service--> <%= si.getNameString() %> <%= si.getServiceKey() %> <% } %> <% } %>

Presenting services and tModels Displaying the services and tModels is simpler than presenting the businesses, because there are no hierarchical dependencies. (For the business, the associated services were displayed as well.) The output is shown in Figure 19-12.

452

WebSphere Version 5.1 Web Services Handbook

Figure 19-12 Services and associated tModels

The JSP code that is used to display the services and tModels is shown in Example 19-9. Example 19-9 JSP code that extracts and displays services and tModels <% for (int j = 0; j < resultService.size(); j++) { ServiceInfo serviceInfo = (ServiceInfo) resultService.elementAt(j); %> <%= serviceInfo.getNameString()%> <%= serviceInfo.getServiceKey()%> <%= serviceInfo.getBusinessKey()%> <% } %> (...) <% for (int i=0; i <%= ti.getNameString() %> <%= ti.getTModelKey() %> <% } %>

Presenting the bindings The bindings have more interesting attributes than the other entries. Most important is the URL of the access point, but also its type (protocol). The sample JSP displays the binding, as shown in Figure 19-13.

Chapter 19. Web services scenario: Architecture and implementation

453

Figure 19-13 Displaying the bindings for a given service and tModel

The JSP code that iterates through the binding vector to display the result is shown in Example 19-10. Example 19-10 JSP code that presents the binding <% for (int i=0; i <%= bt.getDefaultDescriptionString() %> <%= bt.getBindingKey() %> <%= bt.getAccessPoint().getURLType() %> <%= bt.getAccessPoint().getText() %> <%= bt.getServiceKey() %> <%= bt.getHostingRedirector() %> <% } %>

Testing the UDDI lookup sample The fields in the start page (Figure 19-10 on page 447) are already filled with ITSO WS%. We published all entries in our sample with this prefix, because there are other weather-related services already published. Of course you can use any other search strings for lookups. The last two fields on the start page require a valid service and tModelKey. You can retrieve valid keys by first looking up services and tModels by name and using the keys you found for further requests.

Sample 1: Dynamic invocation using UDDI lookup This sample shows how to use UDDI4J to search for services that use a given tModelKey and invokes them. We have to specify a tModelKey as input, for example, a key found using the UDDI lookup function.

454

WebSphere Version 5.1 Web Services Handbook

This client application already knows the interface WSDL and has a proxy or stub, which was created in the build phase. At runtime the client looks up the access point such a service is invoked. This sample has two parts:
UDDI lookup of businesses, services, and access points (bindings) that implement a given tModel—This part looks up and displays all business entities, their services, and binding templates, using the tModelkey as input. The output of the businesses and services is not necessary for calling the service, but it is interesting for our sample to see who implements services with the desired tModel.
Invoke the services—Use the bindings that were retrieved to invoke all the services that were found and show the results.

Start JSP The client1.jsp is the entry point for this sample (Figure 19-14). It asks for the key (UUID) of a tModel. There is already a default for the key. This is the key of the ITSO Weather Forecast tModel, which was published in the IBM test registry for this sample.

Figure 19-14 Client sample 1 for dynamic invocation using UDDI

The JSP simply contains some information text and an HTML form with one text field and a Submit button. When clicked, the StartClient1Servlet list called.

Chapter 19. Web services scenario: Architecture and implementation

455

Servlet The servlet (StartClient1Servlet) retrieves the tModelKey from the form and ensures that it starts with a UUID: prefix. It then does the lookup for bindings, and calls each of them.

Lookup businesses and services This lookup is similar to the lookup of the businesses and services described above, but it does not restrict to a certain name. The only input parameter is the tModelKey. The central method is the performTask method, which does the following:
Prepare tModelKey—Check if the prefix is OK, and store it in a TModelBag.
Call lookup—Find the businesses and services that have bindings.
Extract access URLs—Get the access points out of the binding objects to call the invokeAll method.
Call invokeAll—Retrieve the results of all services.
Call a JSP for output. The listing for performTask is shown in Example 19-11. Example 19-11 Sample client 1 performTask method protected void performTask(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { String tModelKeyString = (String) request.getParameter("tModelKey"); if (!tModelKeyString.toLowerCase().startsWith("uuid:")) tModelKeyString = "uuid:" + tModelKeyString; TModelKey tModelKey = new TModelKey(tModelKeyString); TModelBag tModelBag = new TModelBag(); tModelBag.add(tModelKey); Vector bindingTemplates = lookUp(tModelBag, request); Vector accessUrls = extractAccessUrls(bindingTemplates); invokeAll(accessUrls, request); forward("client1Response", request, response); }

The lookUp method is called by the performTask method and is shown in Example 19-12. Example 19-12 Look up businesses, services, and bindings protected String Vector Vector

456

Vector lookUp(TModelBag tModelBag, HttpServletRequest request) { message = ""; bindings = new Vector(); businesses = null;

WebSphere Version 5.1 Web Services Handbook

Vector bindingTemplates = null; int numberOfBusinesses = 0; int numberOfServices = 0; int numberOfBindings = 0; try { // first look up busines and their services matching the tModel BusinessList businessList = getUddiProxy(request). find_business(null, null, null, null, tModelBag, null, 0); businesses = businessList.getBusinessInfos().getBusinessInfoVector(); numberOfBusinesses = businesses.size(); // iterate through businesses for (int i = 0; i < numberOfBusinesses; i++) { BusinessInfo bi = (BusinessInfo) businesses.elementAt(i); Vector serviceInfos = bi.getServiceInfos().getServiceInfoVector(); numberOfServices += serviceInfos.size(); // iterate through services for (int j = 0; j < serviceInfos.size(); j++) { ServiceInfo si = (ServiceInfo) serviceInfos.elementAt(j); // find template for concrete service bindingTemplates = lookUpBinding(tModelBag, si.getServiceKey(), request); if (bindingTemplates != null) { bindings.addAll(bindingTemplates); numberOfBindings += bindingTemplates.size(); } } } } catch (Exception e) { trace(message = "" + e.toString() + ""); } message = "Found " + numberOfBusinesses + " business entries, " + numberOfServices + " services and " + numberOfBindings + " binding templates."; request.setAttribute("businesses", businesses); request.setAttribute("bindings", bindings); request.setAttribute("message", message); return bindings; }

Chapter 19. Web services scenario: Architecture and implementation

457

The lookUp method searches for all businesses and services that reference the tModel. With the service keys, a call to lookUpBindings is made in order to find the access points where the services can be called. And finally the performTask method calls the helper method extractAccessUrls, which prepares the resulting bindings for invocation. The lookUpBindings and extractAccessUrls methods are shown in Example 19-13. Example 19-13 Search for bindings and extract URLs from the result protected Vector lookUpBinding(TModelBag tModelBag, String serviceKey, HttpServletRequest request) { String message = ""; Vector bindingTemplates = null; try { BindingDetail bd = getUddiProxy(request). find_binding(null, serviceKey.toString(), tModelBag, 0); bindingTemplates = bd.getBindingTemplateVector(); } catch (Exception e) { trace(message = "" + e.toString() + ""); } request.setAttribute("messageBinding", message); return bindingTemplates; } protected Vector extractAccessUrls(Vector bindingTemplates) { Vector accessUrls = new Vector(); if (bindingTemplates == null || bindingTemplates.size() == 0) return accessUrls; Enumeration enum = bindingTemplates.elements(); while (enum.hasMoreElements()) { BindingTemplate bt = (BindingTemplate) enum.nextElement(); String accessUrl = bt.getAccessPoint().getText(); accessUrls.addElement(accessUrl); } return accessUrls; }

Invoke services The last action within the performTask method before forwarding to the response JSP is to invoke the service. This is done using the invokeAll method of the base class. This method was shown in Example 19-2 on page 443.

Response JSP The client1response.jsp presents the results, which are in two parts:
A list of businesses and services where bindings were found
The results of the invocation

458

WebSphere Version 5.1 Web Services Handbook

Displaying the bindings The first part shows all bindings that could be found using the tModel. Figure 19-15 shows how they are displayed. The bottom part shows the invocation of the services, which is identical to Figure 19-8 on page 444.

Figure 19-15 Presenting the businesses, services, and bindings for the tModelKey

The JSP code to display this information is shown in Example 19-14. Example 19-14 JSP code for displaying the businesses, services, and bindings <% for (int i=0; i <%= bi.getNameString() %>

Chapter 19. Web services scenario: Architecture and implementation

459

<%= bi.getBusinessKey() %> <% Vector serviceInfos = bi.getServiceInfos().getServiceInfoVector(); for (int j=0; j ----> <%= si.getNameString() %> <%= si.getServiceKey() %> <% Vector bindingTemplates = Util.extractBindingTemplatesWithServiceKey(bindings, si.getServiceKey()); Enumeration enum = bindingTemplates.elements(); while (enum.hasMoreElements()) { BindingTemplate bt = (BindingTemplate) enum.nextElement(); %> ----> <%= bt.getDefaultDescriptionString() %> <%= bt.getAccessPoint().getText() %> <%= bt.getBindingKey() %> <% } %> <% } %> <% } %>

The businesses and services are stored in a vector with BusinessInfo objects. These objects contain a collection of the services. The bindings, however, are not contained in these UDDI4J objects. They are stored in a separate vector after lookup. A helper method, Util.extractBindingTemplateWithServiceKey, fetches all bindings with a certain service key and puts them in a separate vector. This is useful to easily display the bindings right after their corresponding service. public static Vector extractBindingTemplatesWithServiceKey (Vector allBindingTemplates, String serviceKey) { Vector result = new Vector(); if (allBindingTemplates == null || allBindingTemplates.size() == 0) return result; Enumeration enum = allBindingTemplates.elements(); while (enum.hasMoreElements()) { BindingTemplate bt = (BindingTemplate) enum.nextElement(); if (bt.getServiceKey().equalsIgnoreCase(serviceKey)) result.add(bt); } return result;

460

WebSphere Version 5.1 Web Services Handbook

}

The second part of the response JSP shows the results of the actual invocation. This is not part of this JSP, but is implemented in a separate JSP fragment that is included by the response JSP. This part was described in “Invocation result JSP” on page 444.

Test the sample You can test the sample by providing a tModelKey in the start JSP. There is also a default value specifying the key of the tModel that is published in the IBM test registry. Using this you should find three implementations: http://www.flashandthunder.com/ItsoFlashWeb/services/WeatherForecast http://www.flashandthunder.com/ItsoThunderWeb/services/WeatherForecast http://www.siliconweather.com/ItsoSiliconWeatherWeb/services/WeatherForecast

Sample 2: Dynamic invocation using WSIL lookup The implementation details of the lookup with WSIL are contained in sample 2. This sample shows some of the possibilities available in two APIs, WSIL4J and WSDL4J. In this client, we provide an example of how we can use these APIs to retrieve the WSDL locations presented in a WSIL document and use those locations to also retrieve the different service endpoints presented in each of them.

Start JSP The client2.jsp is the entry point for this sample. It asks for the URL location of an inspection language document and also for a service name to look up in the WSIL document provided. The URL location is required and the service name is optional. There is already a default value for the URL location. This is the value of the WSIL document of the FlashAndThunder server. Note that this address does not follow the WSIL specification (see Chapter 8, “Web services inspection language” on page 141), but it sets to that because we only have one server with two WSIL documents, one for SiliconWeather and one for FlashandThunder. The start JSP is shown in Figure 19-16. The JSP simply contains some information text and an HTML form with one text field and a Submit button. When this button is clicked, the StartClient2Servlet is called.

Chapter 19. Web services scenario: Architecture and implementation

461

Figure 19-16 Starting client 2 for dynamic invocation using WSIL

Servlet The class responsible for these operations is the StartClient2Servlet. The central method is the performTask method:
Call the WSDL lookup—Get the URL locations of the WSDL document presented in the WSIL document.
Call the service endpoint lookup—Using the URL locations of the WSDL document, get the access points.
Call invokeAll—Using the access points, retrieve the results of all services. The listing for performTask is shown in Example 19-15. Example 19-15 Sample client 2 performTask method protected void performTask(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { Vector accessURLs = new Vector(); Hashtable access = getWSDLPort(lookUpWSDLlocations(request), request); for (Enumeration e = access.keys() ; e.hasMoreElements() ;) { Vector temp = (Vector) access.get((String)e.nextElement()); for (int i=0; i < temp.size(); i++) accessURLs.add((String)temp.get(i)); } invokeAll(accessURLs, request); forward("client2Response", request, response); }

462

WebSphere Version 5.1 Web Services Handbook

The two relevant methods in this servlet are:
LookUpWSDLlocations—Where we analyze a WSIL document and obtain all the URLs for the WSDL documents referenced by the inspection document. In this method, we have the possibility to restrict the lookup to only one specific service name (Example 19-16). Example 19-16 Method to look up WSDL locations protected Hashtable lookUpWSDLlocations(HttpServletRequest request) { Hashtable WSDLlocations = new Hashtable(); String wsilURL = (String) request.getParameter("wsilURL"); String serviceName = (String) request.getParameter("serviceName"); String message = ""; try { // Create a new instance of a WS-Inspection document proxy WSILProxy proxy = new WSILProxy(wsilURL); // Get the WSIL document WSILDocument iWsilDocument = proxy.getWSILDocument(); // Process the WSIL document to get the locations org.apache.wsil.Service[] iServices = iWsilDocument.getInspection().getServices(); for (int serviceCount = 0; serviceCount < iServices.length; serviceCount++) { ServiceName[] iServiceNames = iServices[serviceCount].getServiceNames(); for (int serviceNameCount = 0; serviceNameCount < iServiceNames.length; serviceNameCount++) { if (serviceName.equals("") || iServiceNames[serviceNameCount]. getText().equalsIgnoreCase(serviceName)) { Description[] iDescription = iServices[serviceCount].getDescriptions(); for (int descriptionCount = 0; descriptionCount < iDescription.length; descriptionCount++) { String location = iDescription[descriptionCount].getLocation(); //if the location is null is a UDDI service descriptor if (location != null) { WSDLlocations.put(iServiceNames[serviceNameCount]. getText(),location); } } } } } request.setAttribute("resultWSDLlocations", WSDLlocations); } catch (Exception e) { trace(message = e.toString()); }

Chapter 19. Web services scenario: Architecture and implementation

463

request.setAttribute("message", message); return WSDLlocations; }


GetWSDLPort—Where we retrieve all the service endpoints presented in the locations received for the WSDL documents. This method is very similar to the method shown in Figure 3-10 on page 63, but with the difference that in this case we are not interested in only one service. We retrieve every service and look into each for service endpoints (Example 19-17). Example 19-17 Method to get the WSDL port private Hashtable getWSDLPort(Hashtable WSDLFileLocations, HttpServletRequest request) { int endPointCounter = 0; Service service; Port port = null; Hashtable serviceEndpoints = new Hashtable(); String message = ""; try { // Read WSDL document and get definitions element WSDLFactory wsdlFactory = WSDLFactory.newInstance(); WSDLReader wsdlReader = wsdlFactory.newWSDLReader(); for (Enumeration e = WSDLFileLocations.keys() ; e.hasMoreElements() ;) { Vector endpoints = new Vector(); String serviceName = (String)e.nextElement(); Definition definition = wsdlReader.readWSDL(null, (String) WSDLFileLocations.get(serviceName)); //Get the services Map services = definition.getServices(); Collection serviceValues = services.values(); for (Iterator serviceIterator = serviceValues.iterator(); serviceIterator.hasNext();) { service = (Service) serviceIterator.next(); //Get the ports Map ports = service.getPorts(); Collection portsValues = ports.values(); for (Iterator portIterator = portsValues.iterator(); portIterator.hasNext();) { port = (Port) portIterator.next(); //Get the extensible elements List list = port.getExtensibilityElements(); for (Iterator iter = list.iterator(); iter.hasNext();) { // The SOAP binding is an extensibility element of the Port ExtensibilityElement element = (ExtensibilityElement) iter.next(); if (element instanceof SOAPAddress) { SOAPAddress soapAddress = (SOAPAddress) element; endpoints.add(soapAddress.getLocationURI());

464

WebSphere Version 5.1 Web Services Handbook

} } } serviceEndpoints.put(serviceName,endpoints); } request.setAttribute("resultServiceEndPoints", serviceEndpoints); } } catch (WSDLException e) { trace(message = e.toString()); } request.setAttribute("message", message); return serviceEndpoints; }

Finally, using the service endpoints, the performTask method configures the addresses and calls the invokeAll method to invoke the services to obtain the weather forecast results.

Response JSP The client2Response.jsp presents the results, which are in fact two parts:
A list of WSIL service names with the URL location of their WSDL documents and the access points presented in each WSDL document
The results of the invocation An example of the information shown in the first part can be seen in Figure 19-17.

Figure 19-17 Presenting the service names, WSDL locations, and access points

The second part of the response JSP shows the results of the actual invocation. This is not part of this JSP, but is implemented in a separate JSP fragment that is

Chapter 19. Web services scenario: Architecture and implementation

465

included in this response JSP. This part was described in “Invocation result JSP” on page 444.

Testing the sample To test the functionality of this client you can try this in the start JSP, shown in Figure 19-16 on page 462:
Provide the FlashAndThunder inspection document without filling in the service name and invoke Start lookup & invocation. In our example this address is: http://www.flashandthunder.com/ItsoFlashWeb/inspection.wsil The answer has two services, one each for the flash and thunder services (Figure 19-18).
Repeat the operation but this time fill in the service name as: ITSO WS Flash Weather Service The answer only presents the result for the flash service (Figure 19-19).

Figure 19-18 Weather result without the service name

466

WebSphere Version 5.1 Web Services Handbook

Figure 19-19 Weather result with the service name

General concepts of the IWA application The application of the fictitious association IWA is a simple Web application using a servlet and a JSP to update the weather information for all its members.

Application flow The general flow in the application is very similar to the UnitedSuns application, but with only one servlet (UpdateWeather) and JSP (updateResponse) to display a confirmation result. Note: The client does not have any possibility to know what happens once the weather information is set to the queue connection. Thus, although a successful message can be shown by the application, it refers only to the client side. The final process in the server may fail. Figure 19-20 shows this simple flow.

Chapter 19. Web services scenario: Architecture and implementation

467

Update enter information

update.html

Servlet process information set the information in the queue

Home page

index.html

Response JSP

UpdateWeather

display results

updateResponse.jsp

Figure 19-20 IWA application flow

Home page with update HTML The update.html is the entry point to provide the weather information for all the providers associated to IWA. This HTML page (Figure 19-21) collects weather information for one day and passes the values to the UpdateWeather servlet.

Figure 19-21 HTML page to update weather information

468

WebSphere Version 5.1 Web Services Handbook

Example 19-18 shows the code for the update.html file. Example 19-18 HTML code to load weather information ....

......

Provide Accurate Weather Forecast
	Date:
	Wind Speed:
... update weather information for providers

....

Update weather servlet The itso.jms.UpdateWeather servlet is responsible for:
Parsing the information received from the update.html into a Weather object
Creating a weather service interface to obtain the client stub to finally call the setWeather method in order to update the providers’ weather information
Forwarding the process comes out to the updateResponse.jsp Example 19-19 shows the performTask method of this servlet.

Chapter 19. Web services scenario: Architecture and implementation

469

Example 19-19 UpdateWeather servlet doGet method public void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { try { Weather w = new Weather(); //date String dateString = (String)req.getParameter("date"); DateFormat dateFormat = DateFormat.getDateInstance(DateFormat.MEDIUM, Locale.US); Date tempDate = dateFormat.parse(dateString); Calendar date = Calendar.getInstance(); date.setTime(tempDate); w.setDate(date); ...... //wind speed String windspeedString = (String)req.getParameter("windspeed"); int windspeed = Integer.parseInt(windspeedString); w.setWindSpeed(windspeed); //create a mangement client InitialContext ic = new InitialContext(); WeatherForecastJMSService wfsl = (WeatherForecastJMSService) ic.lookup("java:comp/env/service/WeatherForecastJMSService"); WeatherForecastJMS wf = (WeatherForecastJMS) wfsl.getWeather(); Weather[] weatherArray = new Weather[1]; weatherArray[0] = w; trace("UpdateWeather Servlet invoke Web Service set weather: " + w); wf.setWeather(weatherArray); req.setAttribute("weather", w); req.setAttribute("exception", null); trace("UpdateWeather Servlet invoke Web Service done."); } catch (Exception e) { req.setAttribute("exception", e.toString()); } RequestDispatcher rd = getServletContext().getRequestDispatcher("updateResponse.jsp"); rd.forward(req, resp); }

Response JSP The response JSP provides the success or not of the update process. We have to consider that the response that we received is based only on the success of the message set in the queue and not on a successful update of the weather information in the providers. Figure 19-22 shows a successful response.

470

WebSphere Version 5.1 Web Services Handbook

Figure 19-22 Successful response from the updateResponse JSP

Static client To show the simplicity of a static client against the complicated nature of a dynamic client, we also provide a static client application that invokes the three Web services of SiliconWeather and FlashAndThunder. The static client is a simple servlet, itso.servlet.WeatherClient, in the ItsoUnitedSunsClient project. Example 19-20 shows the abbreviated code. Example 19-20 Static client servlet package itso.servlet; import itso.bean.WeatherForecast; import itso.bean.WeatherForecastProxy; import itso.mapping.Weather; ...... public class WeatherClient extends HttpServlet implements Servlet { public void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { SimpleDateFormat sdf = new SimpleDateFormat("EEE. MMM d, yyyy"); try { PrintWriter out = resp.getWriter(); out.println(""); // Instantiate the WeatherForecast proxy WeatherForecastProxy proxy = new WeatherForecastProxy();

Chapter 19. Web services scenario: Architecture and implementation

471

proxy.setEndpoint("http://localhost:9080/ItsoSiliconWeatherWeb /services/WeatherForecast"); Weather[] ws = proxy.getForecast(Calendar.getInstance(), 2); proxy.setEndpoint("http://localhost:9080/ItsoFlashWeb /services/WeatherForecast"); Weather[] wf = proxy.getForecast(Calendar.getInstance(), 2); proxy.setEndpoint("http://localhost:9080/ItsoThunderWeb /services/WeatherForecast"); Weather[] wt = proxy.getForecast(Calendar.getInstance(), 2); for (int i=0; iWeather Forecast for "+sdf.format( ws[i].getDate().getTime() )+""); out.println(""); out.println(""); out.println(""); out.println(""); out.println(""); out.println("

Provider	Condition	Temperature	Wind
Silicon" +"	"+ws[i].getCondition() +"	"+ws[i].getTemperatureCelsius() +"	"+ws[i].getWindDirection()+" "+ws[i].getWindSpeed() +"
Flash" +"	"+wf[i].getCondition() +"	"+wf[i].getTemperatureCelsius() +"	"+wf[i].getWindDirection()+" "+wf[i].getWindSpeed() +"
Thunder" +"	"+wt[i].getCondition() +"	"+wt[i].getTemperatureCelsius() +"	"+wt[i].getWindDirection()+" "+wt[i].getWindSpeed() +"

"); } out.println(""); } catch (Exception e) { e.printStackTrace(); } } }

Invoke the static client from the link of the home page or with the URL: http://localhost:9080/ItsoUnitedSunsClient/WeatherClient

A sample run of the static client is shown in Figure 19-23.

472

WebSphere Version 5.1 Web Services Handbook

Figure 19-23 Static client output

Installing the scenario in Application Developer To run the dynamic application scenario in Application Developer, the system must be set up properly by following the instructions in this section.

Enterprise applications To run the scenario, we require two enterprise applications to simulate the client and the server:
Client—ItsoUnitedSuns with an ItsoUnitedSunsClient Web application represents the client (UnitedSuns).
Server—ItsoIWA with ItsoSiliconWeatherWeb, ItsoSiliconWeatherEJB, ItsoSiliconWeatherEJBRouter, ItsoFlashWeb, ItsoThunderWeb, and ItsoIWAUpdateWeatherClient applications. These applications represent the SiliconWeather and FlashAndThunder servers and the IWA update client.

Chapter 19. Web services scenario: Architecture and implementation

473

All applications are copies of applications as developed in Chapter 15, “WebSphere Studio Application Developer” on page 247, and completed with security as in Chapter 16, “Web services security with Application Developer” on page 303:
ItsoUnitedSunsClient—Same as ItsoWebService1WebClient, configured with security as in ItsoWebService6EJBClient, and static and dynamic client added
ItsoSiliconWeatherWeb, ItsoFlashWeb, ItsoThunderWeb—Same as ItsoWebService1Web, configured with security as in ItsoWebService6EJB, and a WSIL file (inspection.wsil) added: http://www.siliconweather.com/ItsoSiliconWeatherWeb/inspection.wsil http://www.flashandthunder.com/ItsoFlashWeb/inspection.wsil

Note that the WeatherForecast beans in ItsoFlashWeb and ItsoThunderWeb have been slightly modified to return weather values that are different from the ItsoSiliconWeatherWeb application.
ItsoSiliconWeatherEJB, ItsoSiliconWeatherEJBRouter—Same as ItsoWebService3EJB, configured with security
ItsoIWAUpdateWeatherClient—Same as ItsoWebService3EJBClient, configured with security as in ItsoWebService6EJBClient, and UpdateWeather client added All WSDL files are updated with the proper soap address, for example:

Importing the enterprise applications The enterprise applications are provided in: sg246891-01\sampcode\scenario

To import the ItsoUnitedSuns enterprise application, follow these steps:
Select File -> Import -> EAR file.
Click Browse and locate the EAR file: sg246891-01\sampcode\scenario\ItsoUnitedSuns.ear


Click Finish.
After the import, select the ItsoUnitedSunsClient project and Properties. On the Java Build Path -> Libraries page, add this JAR file (use Add Variable): WAS_50_PLUGINDIR/lib/uddi4jv2.jar

474

WebSphere Version 5.1 Web Services Handbook


Open the webservices.xml, select Port binding -> Security Request Sender Binding Configuration -> Login Binding, and click Edit. Modify the user and password values with valid values for the current environment (Local OS). Repeat the process for the ItsoIWA enterprise application:
Select File -> Import -> EAR file.
Click Browse and locate the EAR file: sg246891-01\sampcode\scenario\ItsoIWA.ear


Click Finish.
Select the ItsoSiliconWeatherEJBRouter project and Properties. On the Java Build Path -> Libraries page, add this JAR file (use Add Variable): WAS_50_PLUGINDIR/lib/webservices.jar

Server project To configure a server for testing, we require a server project. Define a server project named Servers:
Select File -> New -> Project -> Server -> Server Project. Click Next.
Enter Servers as the name and click Finish.

Configurating a server for testing A zip file to create the server in the Application Developer workspace directory is provided in: sg246891-01\sampcode\scenario\ScenarioServer.zip

To import that zip file into the workspace:
Select File -> Import -> Zip file and click Next.
Click Browse for From Zip file and locate the ServerScenario.zip. Select it and click Open.
Click Browse for Into folder and select Servers, click OK, and then Finish. To configure the server:
Open the Server perspective.
In the Server Configuration view, select the ScenarioServer and Switch Configuration -> ScenarioServer.
Open the ScenarioServer.

Chapter 19. Web services scenario: Architecture and implementation

475


Select the Variables tab. At the bottom of the Node Settings variables, select DB2UNIVERSAL_JDBC_DRIVER_PATH. Check that the value is according to the current environment. If it is not, modify it.
Select the Environment tab. Expand Class Path and verify the location of the urlprotocols.jar file in: \runtimes\base_v51\lib


Select the Ports tab. Notice that we configured port 80 in the Server Settings. The UDDI entries point to port 80, and by default the internal HTTP server listens to port 9080 only. Another way to route the Web services calls from port 80 to 9080 is to define a TCP/IP Monitor server.
Select the Data sources tab. The active data source is for DB2 8.1. A second data source (jdbc/weather2) is defined for DB2 7.2. If you run DB2 7.2, change the data source names so that jdbc/weather is the data source matching your DB2 system.
Select the Security tab. Select DB2User in JAAS Authentication Entries and click Edit.
Modify User ID and Password with the user information previously used to generate the WEATHER database. Click OK. This user ID must be authorized for DB2 access.
Modify the Current active authentication settings with a valid user ID and password for the operating system. Note: You can enable or disable security to run the application. With security enabled you must provide a valid user ID and password.
Save and close the ScenarioServer configuration window.

Configure the HOSTS file The application uses HTTP addresses such as www.flashandthunder.com. These addresses must point to the local machine. Edit the HOSTS file in: c:\WINNT\system32\drivers\etc\hosts

Configure one line as: 127.0.0.1

localhost www.siliconweather.com www.flashandthunder.com www.unitedsuns.com

Test in a command window: ping www.unitedsuns.com

476

WebSphere Version 5.1 Web Services Handbook

Run the samples Everything is configured and we can run the samples:
Start the ScenarioServer and wait for the ready message (Server server1 open for e-business).
Select the ItsoUnitedSunsClient project and Run on Server.

Static client Select Static Client (at the bottom) and wait for the response.

Sample 1 Select Start Sample 1, then select Start lookup & invocation. Be patient. UDDI lookup can be slow, but you should see the result of the three Web services.

Sample 2 Select Start Sample 2, then enter a URL location: http://www.flashandthunder.com/ItsoFlashWeb/inspection.wsil http://www.siliconweather.com/ItsoSiliconWeatherWeb/inspection.wsil

Select Start lookup & invocation and you should see the results of the Web services.

General UDDI lookup Select General UDDI lookup then select Start lookup. You should see three businesses, three services, and one tModel. You can also search for any other entries. For example, if you enter Weather, you will get over 20 business entries.

Weather update Select the ITSOIWAUpdateWeatherClient project and Run on Server. Provide the updated weather for today and Click Update Weather. Use the UnitedSuns application to see how the prediction turns into reality.

Chapter 19. Web services scenario: Architecture and implementation

477

Summary In this chapter we provided a Web services scenario and an implementation using Application Developer and Application Server. Also we incorporated the general concepts introduced in Part 1, “Web services concepts”. Although this scenario is simplistic in some ways, it is well suited to demonstrating how to build a Web services-based application. In this chapter we showed the development process for this application. In particular, we described which activities of the implementation have to be performed manually and which can be run automatically. We also showed the interaction of the various actors in the application. Next we described in detail the implementation issues of the solution when dynamically accessing a UDDI registry. We provided two types of dynamic clients. One client uses the UDDI registry to find a suitable implementation of the Web service in request, while the other accesses a WSIL file on the provider’s server. We presented relevant implementation issues regarding these two clients, including the security aspects. In addition, we described a static client to show the difference between dynamic and static client coding.

478

WebSphere Version 5.1 Web Services Handbook

20

Chapter 20.

Web services runtime and deployment in WebSphere This chapter describes Web services deployment in the IBM WebSphere Application Server environment. We cover the product installation and administration basics necessary to understand the deployment process. We describe Web service Java implementation packaging and SOAP enablement, as well as Web service administration. The WebSphere Version 5.0.2 and 5.1 enhancements in the area of Web services security, SOAP/JMS, and monitoring using Tivoli Performance Viewer (TPF) are also discussed. We also discuss some useful troubleshooting techniques. It is not the intention of this chapter to cover the application server details beyond the scope necessary to understand Web service deployment. However, we provide links to additional resources. In addition, the product overview is provided in Chapter 12, “IBM WebSphere product family” on page 203, and the product installation is covered in Appendix A, “Installation and setup” on page 515.

© Copyright IBM Corp. 2003, 2004. All rights reserved.

479

Overview In this section we cover IBM WebSphere Application Server as a Web service deployment platform of choice. We do not discuss all the product details. We only deal with the aspects necessary to understand Web services deployment, administration, and security.

WebSphere Application Server general concepts WebSphere Application Server—WebSphere for short—represents one of the basic building blocks of the enterprise e-business environment. It is a part of the IBM WebSphere product family, which we describe in Chapter 12, “IBM WebSphere product family” on page 203.

Administration basics In WebSphere 3.5 and WebSphere 4.0 Advanced Edition, the configuration was saved in a relational database. The administration server had to be installed and started on all the nodes in the domain to start and stop an application. The administrative console was a thick Java client. In addition, command-line tools such as XMLConfig and WSCP were available to automate the administration tasks. However, a Web-based administrative console was available for the WebSphere 4.0 Advanced Edition Single Server (AEs) and all the configuration information was saved in an XML file. WebSphere Version 5 adopts this concept and does not use a relational database for the administrative repository for configuration data, but stores the data in XML files instead. The administrative console Web application enables you to edit the configuration. The WSADMIN scripting facility can be used in interactive or batch mode to perform administrative console operations. The XMLConfig tool and the WSCP scripting tool are not available in Version 5.

WebSphere topology building blocks Before we discuss the details of Web application deployment, let us first cover some fundamental administrative concepts:
Managed process or server—Denotes any instance of a JVM that can be managed in a WebSphere environment. Application servers, JMS servers (a special type of server that supports JMS communication), node agents, and

480

WebSphere Version 5.1 Web Services Handbook

deployment managers are all examples of managed processes. We discuss node agents and deployment managers in the subsections that follow.
Node agent—Is responsible for controlling all the servers running on a certain machine. These servers could be application servers and/or a JMS server. In most cases we find a single node agent on one physical system, although it is also possible that on some very high-end systems, multiple node agents may be concurrently active.
Cell—A network of related node agents makes a cell. The concept of a cell is very similar to the concept of domain, which we know from the previous versions of WebSphere. In each cell, there is a single deployment manager. However, despite its similarity, this process is not equivalent to the administrative server of previous releases; its main purpose is to allow an administrator to manage the resources in the entire cell. Figure 20-1 shows an example of a WebSphere Version 5 topology.

Application Server XML config

Managed Process

Node Agent

Cell

Application Server XML config

Deployment Manager

Managed Process

Application Server XML config

Node Agent

Application Server XML config

Figure 20-1 WebSphere Version 5 example topology

Chapter 20. Web services runtime and deployment in WebSphere

481

Each physical machine holds a separate installation of the product that is not aware of installations on other machines. The configuration files are in XML. In the base application server, the node agent code is there although it performs no role until the node is added into a cell. WebSphere Application Server Network Deployment represents a single point of administration of multiple nodes. It is possible to install Network Deployment on any machine in the network to create a network deployment manager cell. A WebSphere Application Server installation on the same machine is not a prerequisite. Once we install and start the network deployment instance, we can use the addNode tool to add a WebSphere Application Server instance (node) to the network deployment cell. The network deployment manager assumes responsibility for the configuration of any application server nodes that belong to the cell. Each process keeps all the data necessary to start itself. The configuration data is in XML files, and the application data in enterprise application EAR files. In the Network Deployment environment, you can attach an administrative client to any managed process to make changes to the configuration. The deployment manager contains the master repository of XML files. Individual nodes and servers synchronize the files with the master configuration data and all the changes applied to them directly are lost after synchronization. It is best to change configuration data only through the deployment manager. In the following sections we cover the main functions of the Web administrative console.

Administrative console The WebSphere administrative console is a graphical, Web-based tool designed to manage the WebSphere Application Server administrative server. The administrative console builds upon the Admin Web application architecture and functions that were introduced in WebSphere Version 4.0 AEs. The administrative console Web application is installed by default during WebSphere installation. After we start the server (in the case of the base application server, the command is startserver server1), we can access the console using a Web browser: http://:9090/admin/

If global security is disabled, no password is required and the user ID we have to enter is used only to track and save user-specific configuration data.

482

WebSphere Version 5.1 Web Services Handbook

taskbar

workspace

celltree

status/messages Figure 20-2 WebSphere Administrative Console

The console window contains the following main areas: A taskbar, a cell tree view, a workspace, and a status messages area. We can resize these areas to fit our needs. They can be seen in Figure 20-2.
Taskbar—The taskbar helps a user to return to the console home page, access product information, save changes made to administrative configurations, and log out of the console.
Cell tree view—The tree view on the left side of the console is used to select and manage components in a WebSphere administrative cell.
Workspace—The console workspace is the main area to make changes to the configuration, such as creating application servers, installing an enterprise application, and configuring data sources. The console also provides a search function for locating and viewing resource objects.
Status messages area—The messages area at the bottom of the console lists messages returned by the administrative server as well as messages about events, such as successful completion and errors.

Chapter 20. Web services runtime and deployment in WebSphere

483

Enterprise application deployment Enterprise applications (or J2EE applications) are applications that conform to the Java 2 Platform Enterprise Edition specification. They consist of EJB modules (EJB JAR files), Web modules (WAR files), connector modules (RAR files), and application client modules (JAR files). None of these modules is mandatory and any combination of modules is allowed. Optionally, additional JAR files containing dependent classes or other components required by the application can be added to the application. An enterprise application is packaged in an enterprise archive (EAR) file. WebSphere Application Server provides the Assembly Toolkit, which replaces the Application Assembly Tool (AAT) of earlier Application Server versions:
The Assembly Toolkit consists of the J2EE Perspective of the WebSphere Studio Application Developer product. With the Assembly Toolkit, you can create and modify J2EE applications and modules, edit deployment descriptors, and map databases.
The Assembly Toolkit is one of the tools provided by the Application Server Toolkit (ASTK). Follow instructions available with the ASTK to install the Assembly Toolkit.

Installing an enterprise application Here we describe the steps needed to use the administrative console to install an application. We begin by selecting Applications -> Install New Application in the console navigation tree. The first of the Preparing for application install pages is shown.

Preparing for application install (first page) We have to specify the full path name of the enterprise application file (EAR file). We can also specify a stand-alone WAR or JAR file for installation. If we are installing a stand-alone WAR file, we have to specify the context root. Click Next to move to the second page.

Preparing for application install (second page) Select whether to generate default bindings. Using the default bindings causes any incomplete bindings in the application to be filled in with default values. Existing bindings are not altered. Click Next.

484

WebSphere Version 5.1 Web Services Handbook

Install new application pages The install new application pages are now shown, starting with the Provide options to perform the installation page. If we decide to generate default bindings, we can proceed to the Summary step.

Provide options to perform the installation page In this step, we provide values for the following settings specific to WebSphere Application Server. Default values are used if a value is not specified.
Pre-compile JSP—We specify whether to precompile JSP files as a part of installation. The default is not to precompile JSP files.
Directory to Install Application—We specify the directory in which the application EAR file will be installed. The default is the installedApps directory.
Distribute Application—We specify whether WebSphere Application Server expands or deletes application binaries in the installation destination.
Use Binary Configuration—We specify whether the application server uses the binding, extensions, and deployment descriptors located with the application deployment document, the deployment.xml file (default), or those located in the EAR file.
Deploy EJBs—We decide whether the EJBDeploy tool, which generates code required to run EJB files, runs during application installation. If the deployed code has been generated in Application Developer then this step can be skipped.
Application Name—We decide how to name the application. Application names must be unique within a cell and cannot contain characters that are not allowed in object names.
Create MBeans for Resources—We specify whether to create MBeans for various resources (such as servlets or JSP files) within an application when the application is started.
Enable class reloading—We specify whether to enable class reloading when application files are updated.
Reload Interval—We specify the number of seconds to scan the application's file system for updated files. The default is the value of the reload interval attribute in the IBM extension (META-INF/ibm-application-ext.xmi) file of the EAR file. This setting takes effect only if class reloading is enabled. The reload interval specified here overrides the value specified in the IBM extensions for each Web module in the EAR file (which in turn overrides the reload interval specified in the IBM extensions for the application in the EAR file).

Chapter 20. Web services runtime and deployment in WebSphere

485

Optional panels Several panes only appear under specific circumstances. We only briefly describe those here:
Provide JNDI Names for Beans—This panel appears when the application uses EJB modules. Here we can provide JNDI names for each enterprise bean in every EJB module.
Map resource references to resources—This panel appears if the application defines resource references.
Map virtual hosts for Web modules—This panel appears when the application uses Web modules. This is normally true for the applications containing Web services. Here we select a virtual host from the list that should map to a Web module defined in the application. The port number specified in the virtual host definition is used in the URL that is used to access artifacts such as servlets and JSP files in the Web module. Each Web module must have a virtual host to which it maps.
Map modules to application servers—This panel always appears. Here we select a target server or a cluster from the clusters and servers list for every module.
Map security roles to users/groups, specify users and groups that are mapped to each of the security roles—This panel appears when the application has security roles defined in its deployment descriptor.
Map RunAs roles to user—This panel appears when the application has RunAs roles defined in its deployment descriptor. Here we can specify the RunAs user name and password for every RunAs role.

Summary panel On the Summary panel we verify the cell, node, and server where the application modules will be installed. Then we start the deployment by clicking Finish.

Starting and stopping enterprise applications Once an enterprise application has been installed, it can be started and stopped from the administrative console.

Regenerate the HTTP server plug-in After installing enterprise applications, it is necessary to regenerate the plug-in. Select Environment -> Update Web Server Plugin and click OK. The HTTP server must be restarted to make the plug-in effective.

486

WebSphere Version 5.1 Web Services Handbook

Web services deployment in WebSphere environment Web services are contained in Web modules or EJB modules. When using Application Developer, the Web services are fully deployed in the modules and the containing EAR file. These Web services are defined in the deployment descriptors of the EJB and WEB modules, for example, created as described in “WebSphere Studio Application Developer” on page 247. While deploying these Web services into the WebSphere runtime, no special activities are required and the EAR file can be installed like any other (non Web service) EAR file. An exception to this is SOAP/JMS Web services, where you have to create and configure the JMS queue and queue connection factory prior to installing the Web server. We will discuss SOAP/JMS configuration in “Creating JMS resources for use with the SOAP/JMS Web service” on page 489.

Web services enabling with the SoapEarEnabler tool In the WebSphere/AppServer/bin directory you can find a command-line tool, SoapEarEnabler.bat, for enabling a set of SOAP services within an EAR file. We did not have to run this tool with our deployed EAR files, because they already contained the necessary SOAP servlets. For example, you have to use this tool when you create a Web service with tools that do not create a Web module with the SOAP router servlets. The SoapEarEnabler tool can add a Web router module to an existing EAR file.

Configuring a server for the ITSO Web services To illustrate deployment of the ITSO sample Web services we configure the default server, server1, with a data source, JMS resources, and security. These activities are similar to configuring the test environment in Application Developer, but the user interface is quite different.

Start the server and the administrative console Start the WebSphere Application Server from the Program group or from the First Steps application. When the server is ready, start the administrative console. This opens a browser at: http://:9090/admin/

Chapter 20. Web services runtime and deployment in WebSphere

487

Log in with your user ID. To make start/stop of the server faster, you may stop and uninstall all the sample applications by selecting Applications -> Enterprise Applications and stopping and uninstalling all samples except for the adminconsole application.

Define the data source for the weather forecast database We require a data source for the WEATHER database:
In the Navigation bar, select Resources -> JDBC Providers, then click Add. (Note that we define at the Node level.)
Select DB2 Universal JDBC Driver Provider (XA) and click Apply.
The panel expands, click Apply again, and an Additional Properties section is appended (Figure 20-3).

Figure 20-3 JDBC Provider

488

WebSphere Version 5.1 Web Services Handbook


Under Additional Properties select Data Sources, then click New. Enter WEATHER as the Name and jdbc/sjweather as the JNDI Name, and click Apply.
Under Related Items select J2C Authentication Data Entries, then click New.
Enter DB2User as the Alias, and a valid user ID and password with access to DB2.
In the selection line at the top, select Data Sources to get back to the data source definition: JDBC Providers > DB2 Universal JDBC Driver Provider (XA) > Data Sources > WEATHER >


Select the WEATHER data source, then select the new DB2User alias for the Component-managed and Container-managed Authentication Alias. Click Apply.
Under Additional Properties select Custom Properties. Select the databaseName property, set the value to WEATHER, and click OK.
Notice in Figure 20-3 the variables used to point to the DB2 JAR runtime JAR files. We have to define one of these variables. In the Navigation bar, select Environment -> Manage WebSphere Variables.
Select the DB2UNIVERSAL_JDBC_DRIVER_PATH variable and enter the location of the JAR files, for example, C:\SQLLIB\java, and click OK.
Select the DB2_JDBC_DRIVER_PATH variable and set the same value.
Save the configuration (select Save in the top menu). Note: For DB2 7.2 use the DB2 Legacy CLI-base Type 2 JDBC Driver.

Creating JMS resources for use with the SOAP/JMS Web service In WebSphere 5.0.2 and 5.1, we have the option of using the SOAP/JMS as the underlying transport medium for the SOAP clients to communicate with a SOAP server. The WebSphere runtime configuration has to be modified to work for SOAP over JMS. The steps are:
Create a queue connection factory and queue destination.
Create a listener port.
Activate the queue. We can define the JMS engine to be a WebSphere JMS Provider, a WebSphere MQ JMS Provider, or a Generic JMS Provider. Since the WebSphere JMS Provider is shipped along with WebSphere Application Server, we will use it for our sample application.

Chapter 20. Web services runtime and deployment in WebSphere

489

Create a queue connection factory and queue destination To define the JMS resources follow these steps:
In the Navigation bar, select Resources -> WebSphere JMS Provider. We define at the Node level.
Select WebSphere Queue Connection Factories, then click New. Enter WeatherQCF as the name and jms/WeatherQCF as the JNDI Name. For the Component-managed and Container-managed Authentication Alias select the DB2User entry. Click Ok.
Now go back to the WebSphere JMS Provider page and this time select WebSphere Queue Destinations and click New. Enter WeatherQueue for the Name and jms/WeatherQueue for the JNDI Name. Click Ok.

Create a listener port The SOAP/JMS communication is made possible by implementing a message driven bean within the Web services application. The MBD listens on a listener port that is associated with a queue and a queue connection factory. Here are the steps:
In the Navigation bar, select Servers -> Application Servers -> server1. Under Additional Properties select Message Listener Service. Select Listener Ports. Click New.
Enter WeatherPort as the Name, jms/WeatherQCF as the connection factory JNDI name and jms/WeatherQueue as the Destination JNDI name. Accept defaults for the remaining fields. Click OK (Figure 20-4).

Figure 20-4 JMS listener port for MDB (abbreviated)

490

WebSphere Version 5.1 Web Services Handbook

Activate the queue Now that we have created the queue connection factory, queue, and the listener port, we need to activate the queue for this JMS server. Here are the steps:
In the Navigation bar, select Servers -> Application Servers -> server1.
Under Additional Properties, select Server Components -> JMS Servers.
In the Configuration for Queue names, add a line with the WeatherQueue to the list. Verify that the initial state is Started. Click OK (Figure 20-5).

Figure 20-5 JMS Server configuration


Save the configuration.

Activating Web service security Our weather application is equipped with three types of security safeguards defined in the WS-Security specification. These safeguards are configured in the deployment descriptor files of the application and the WebSphere runtime configuration. The deployment descriptor configuration details have already been discussed in “Web services security with Application Developer” on page 303. Here we discuss the configuration changes to the WebSphere runtime. Prior to installing the weather application EAR files in the WebSphere runtime, we have to configure the security. These steps are similar to those performed in WSAD in “Web services security with Application Developer” on page 303.

Enable global security in WebSphere runtime To enable global security follow these steps:
In the Navigation bar, select Security -> User Registries -> Local OS.

Chapter 20. Web services runtime and deployment in WebSphere

491


Under General Properties, enter the Server user ID and Server password, which is a valid user and password on the that system. Other user registries such as remote LDAP servers or custom registries can also be used. Click Apply (Figure 20-6).

Figure 20-6 Global Security user ID


Select Global Security on the navigation bar. Select Enabled. Deselect Enforce Java 2 Security (which is selected automatically) because we do not use Java 2 security in our application. Lower on the page, ensure that Active User Registry is LocalOS. Click OK (Figure 20-7).

Figure 20-7 Enabling global security using the Administrative console

492

WebSphere Version 5.1 Web Services Handbook


Save the configuration.

Configure the server to decrypt the request As we have done for the private key in the client, we define the private key to decrypt the messages in the SampleReceiverEncryptionKeyLocator:
In the Navigation bar, select Servers -> Application Server -> server1.
Under Additional Properties select Web services: Default bindings for Web Services Security -> Key Locators -> SampleReceiverEncryptionKeyLocator.
Under Additional Properties select Keys and click New.
Enter CN=Bob, O=IBM, C=US as the Key Name, bob as the Key Alias, keypass as the Key Password, and click OK (Figure 20-8).

Figure 20-8 Private key configuration for receiver

Configure the server to encrypt the response We have to include the private key we use to decrypt the messages in the SampleSenderEncryptionKeyLocator:
Go back to Key Locators. Select SampleSenderEncryptionKeyLocator. Under Additional Properties select Keys and click New.
Enter CN=Alice, O=IBM, C=US as the Key Name, alice as the Key Alias, keypass as the Key Password, and click OK.
Save the configuration.

Configuring for the scenario application The scenario application described in Chapter 19, “Web services scenario: Architecture and implementation” on page 429, requires the configuration of host names.

Chapter 20. Web services runtime and deployment in WebSphere

493

Configure the HOSTS file The application uses HTTP addresses such as www.flashandthunder.com. These addresses must point to the local machine. Edit the HOSTS file in: c:\WINNT\system32\drivers\etc\hosts

Configure one line as: 127.0.0.1

localhost www.siliconweather.com www.flashandthunder.com www.unitedsuns.com

Configure the server with virtual host names The configuration of the virtual host is only required if you want to use HTTPS:
In the Navigation bar, select Environment -> Virtual Hosts, then select default_host and Host Aliases.
Click New, enter www.siliconweather.com as the host name, 443 as the port, and click OK.
Save the configuration.

Restart the application server with security Log out from the administrative console and close the browser window. Stop the server and restart it. Open the administrative console. Accept the certificate and you are prompted for a user ID and password. With security active you have to log in using a password. Use the user ID and password that were set up for the server. Important: When the server is started with security, you have to provide user ID and password to stop the server: stopserver server1 -user userID -password password

Install the enterprise applications We developed a number of enterprise applications using Application Developer. A number of them can be installed in the Application Server as configured above.

Install the scenario enterprise application To work with the scenario application, install the two enterprise applications, ItsoIWA and ItsoUnitedSuns, by following the instructions in “Installing an

494

WebSphere Version 5.1 Web Services Handbook

enterprise application” on page 484. Take all the defaults in the installation panels. The EAR files are provided in: sg246891-01\sampcode\scenario

Save the configuration, then start the two enterprise applications.

Regenerate the HTTP Server plug-in The WebSphere configuration of enterprise applications and virtual hosts must be known to the HTTP server so that requests can be forwarded:
In the Navigation bar, select Environment -> Update Web Server Plugin, then click OK.
Restart the IBM HTTP Server from the Windows Services list. The HTTP server will pick up the SSL configuration and the WebSphere plug-in.

Run the application After restarting the servers, you can test the application using the URLs: http://www.unitedsuns.com/ItsoUnitedSunsClient/ http://www.unitedsuns.com/ItsoIWAUpdateWeatherClient/

Experiment with the static and dynamic client applications.

Install the enterprise applications of Application Developer You can install these applications, exported as EAR files from Application Developer:






ItsoWebService1 ItsoWebService2 ItsoWebService4 ItsoWebService5 ItsoWebService6

The ItsoWebService3 application has conflicts with the scenario application because the same JMS resources are used.

Chapter 20. Web services runtime and deployment in WebSphere

495

Update the DADX group configuration To run in WebSphere we configure the group properties with a data source:
Edit the group.properties file (in ItsoWebService5Web\JavaSource) and change the lines in bold: #Tue Dec 16 16:34:01 PST 2003 namespaceTable=namespacetable.nst groupNamespaceUri= reloadIntervalSeconds=5 dbDriver=COM.ibm.db2.jdbc.app.DB2Driver dbURL=jdbc\:db2\:WEATHER enableXmlClob=true useDocumentStyle=false password= datasourceJNDI=jdbc/sjweather2 initialContextFactory=com.ibm.websphere.naming.WsnInitialContextFactory userID= autoReload=true

Define a JDBC driver and data source In the WebSphere administrative console define a JDBC provider and a data source. Follow the same steps as in “Define a JDBC driver and data source” on page 496:
For the JDBC Provider select the DB2 Legacy CLI-base Type 2 JDBC Driver.
For the data source enter WEATHER2 and jdbc/sjweather2.
Save the configuration.

Installing the WORF runtime The ItsoWebService5 application requires the WORF runtime. For testing in Application Developer the runtime was added automatically. For WebSphere Application Server we have to install it manually:
Copy the worf.jar file from Application Developer to the WebSphere Application Server: from: \wstools\eclipse\plugins\com.ibm.etools.webservice_5.1.1\runtime to: \lib


Stop and restart the application server. Remember that you need a user ID and password to stop the server.

Installing the enterprise applications We provide the EAR files in sg246891-01\sampcode\zEARfiles, or you can export the applications yourself from Application Developer. Install the applications you want to test, save the configuration, and start the applications.

496

WebSphere Version 5.1 Web Services Handbook

Running the sample enterprise applications Here are a few URLs that you can use to run the sample applications: http://localhost:9080/ItsoWebService1WebClient/sample/ WeatherForecastProxy/TestClient.jsp http://localhost:9080/ItsoWebService1WebClient/WeatherClient http://localhost:9080/ItsoWebService2EJBClient/sample/ WeatherForecastEJBProxy/TestClient.jsp http://localhost:9080/ItsoWebService2EJBClient/WeatherClientEJB http://localhost:9080/ItsoWebService4WebClient/WeatherClient http://localhost:9080/ItsoWebService5Web/admin/index.html http://localhost:9080/ItsoWebService5Web/WeatherForecastServlet http://localhost:9080/ItsoWebService5WebClient/sample/ GoodWeather/TestClient.jsp http://localhost:9080/ItsoWebService5Web/WeatherGroup/GoodWeather.dadx/TEST http://localhost:9080/ItsoWebService5WebClient/sample/ WeatherForecastServlet/TestClient.jsp http://localhost:9080/ItsoWebService6EJBClient/sample/ WeatherForecastEJBProxy/TestClient.jsp

Installing an application with transport channel security In Chapter 19, “Web services scenario: Architecture and implementation” on page 429, we secured an application using message-level security. Message-level security is defined by the WS-Security specification. It is possible to also secure Web services applications using transport channel security. In this section, we provide information on how to secure Web services using transport-channel security. Essentially, transport-level security is achieved by configuring the client (Web browser) to use HTTPS when communicating with the Web server. Note: We do not provide a client application that uses SSL. For a test environment, we run the Web service client and servers on one machine, although logically we have three servers:
www.siliconweather.com and www.flashandthunder.com, where the Web services run
www.unitedsuns.com, where the dynamic client runs

Chapter 20. Web services runtime and deployment in WebSphere

497

Configuring for HTTPS The HTTP server must be configured for HTTPS. This process requires a certificate and SSL configuration between the client and the HTTP server. This configuration is optional if you do not want to use HTTPS.

Create a self-signed certificate To create a self-signed certificate on the HTTP server where SiliconWeather is running:
Create a subdirectory keys under \conf. This is where we store the key database.
Launch the ikeyman tool by selecting Programs -> IBM HTTP Server 1.3.26 -> Start Key Management Utility. Note: The tool requires an environment variable, JAVA_HOME. You can define this variable to point to \java.
Select Key Database File -> New. Select CMS from the type drop-down, enter webservKeyring.kdb as the file name, enter \conf\keys for the location, and click OK.
Enter a password, for example, itsowebserv. Select Stash the password to a file and click OK.
Select Create -> New Self-Signed Certificate. Enter SiliconWeather (no spaces) as the label, accept X509 V3 as the version, and 1024 as the key size. For the names, enter the server name as the common name, and IBM, ITSO, San Jose, CA, US into the other fields. Enter 365 for the period, and click OK.
Close the key database (Key Database File -> Close) and exit the program.

Extract the certificate for installation into WebSphere We have to extract the certificate so that we can install it in WebSphere:
Click Extract Certificate (bottom right).
Select Base64-encoded ASCII data as the type, enter ItsoWebServ.arm as the file name, set the conf\keys directory as the location, and click OK.

Install the certificate in WebSphere To install the extracted certificate in WebSphere (the server where the UnitedSuns client is running):
Copy the extracted ItsoWebServ.arm file into \etc.
Start the ikeyman command-line tool (\bin\ikeyman.bat).

498

WebSphere Version 5.1 Web Services Handbook


Select Key Database File -> Open and select the DummyClientTrustFile.jks file in the etc directory.
At the password prompt, enter the password for the key file then click OK. The default password is usually WebAS.
Select Signer Certificates in the drop-down list and click Add. Select Base64-encoded ASCII data for the type, enter ItsoWebServ.arm as the file name, and \etc as the location, and click OK.
You are prompted for a label name by which the trusted signer public certificate will be known. Enter SiliconWeather as the label.
Close the key database (Key Database File -> Close) and exit the program.

Configure the HTTP server for SSL Follow the instructions in the HTTP server documentation to enable SSL for the www.siliconweather.com virtual host. You can find the instructions by selecting IBM HTTP Server -> How to -> Get started -> With secure connections. Also configure the other virtual hosts, www.unitedsuns.com and www.flashandthunder.com, but without SSL. After configuring SSL and the virtual hosts, the httpd.conf file should have a number of lines attached: LoadModule ibm_ssl_module modules/IBMModuleSSL128.dll Listen 443 FileETag none ServerName ServerPath c:/ibmhttpserver/htdocs/en_us SSLEnable SSLClientAuth none ServerName ServerPath c:/ibmhttpserver/htdocs/en_us FileETag none ServerName ServerPath c:/ibmhttpserver/htdocs/en_us FileETag none SSLDisable Keyfile c:/ibmhttpserver/conf/keys/webservKeyring.kdb SSLV2Timeout 100 SSLV3Timeout 1000

Chapter 20. Web services runtime and deployment in WebSphere

499

Accessing a Web service from a stand-alone Java client For illustration purposes we provide a stand-alone client application that accesses the Web service developed in Chapter 15, “WebSphere Studio Application Developer” on page 247. This is the stand-alone client developed in “Stand-alone Java client” on page 264. The client code has been exported to the sample code: sg24-6891\sampcode\was\StandaloneClient

A command file named RunAloneClient.bat is provided as well. You may have to tailor the command file with the WebSphere installation directory. You can run this client against the test environment or against the real WebSphere Application Server. A sample output is shown here: ** RUNNING THE STANDALONE JAVA CLIENT OF WEATHERFORECAST WEB SERVICE ** 1. Testing getDayForecast() method ... Mon Dec 22 00:00:00 PST 2003 Temperature = -6 getWindSpeed = 35 Condition = rainy getDayForecast() test successful 2. Testing getForecast() method ... Mon Dec 22 00:00:00 PST 2003 Temperature = -6 getWindSpeed = 35 Condition = rainy Tue Dec 23 00:00:00 PST 2003 Temperature = 32 getWindSpeed = 14 Condition = rainy Wed Dec 24 00:00:00 PST 2003 Temperature = 16 getWindSpeed = 17 Condition = cloudy getForecast() test successful

WindDirection = W

WindDirection = W WindDirection = N WindDirection = E

3. Testing getTemperatures() method ... Temperature = -6, Temperature = 32, Temperature = 16, getTemperatures() test successful

Using Tivoli Performance Viewer (TPF) Introduced with WebSphere 5.0.2 is new monitoring support for Web services. This monitoring is performed by Tivoli Performance Viewer, which is shipped as a part of WebSphere Application Server. Web services data such as the number of requests received, number of requests processed, and average response time is displayed in real time, both in graphical and non-graphical formats.

500

WebSphere Version 5.1 Web Services Handbook

In the default WebSphere configuration this service is disabled. We have to make the following configuration changes to enable it:
Enable the performance monitor interface (PMI) service in the server.
Restart the Application Server.
Start Tivoli Performance Viewer.

Enable PMI service in the application server To enable PMI in the Application Server:
In the Administrative console select Servers -> Application Servers -> server1.
Under Additional Properties, select Performance Monitoring Service.
On the Performance Monitoring Infrastructure page under General Properties, select Startup.
Under Initial specification level, select the custom radio button. In the text box below that change webServicesModule=N to webServicesModule=H. By doing this you are enabling Web services-related performance data to be visible to the Tivoli Performance Viewer (TPV). If you want to collect performance data for other modules as well, select the Standard radio button. This will convert all levels to H, including the one for Web services.
Click OK, then save the configuration.

Restart the server Restart the application server that houses the Web services application.

Start Tivoli Performance Viewer (TPV) TPV is a tool that connects to the Application Server and extracts performance information from it. It then displays that performance information in text and graphical formats. Start TPV by running the batch file \bin\tperfviewer.bat, or by selecting the program from the WebSphere program group:
In TPV’s navigation bar, expand Viewer and navigate to the Web services whose data you want to view.
Select the data you want charted in the bottom list.
The data is updated on the fly, and you can set a refresh interval.
A sample output is shown in Figure 20-9.

Chapter 20. Web services runtime and deployment in WebSphere

501

Figure 20-9 Tivoli Performance Viewer used to monitor Web services

Note: Disable security in the server when using TPV. If you want to run TPV with security enabled, you have to update the soap.client.props file in \properties with the server user ID and password: com.ibm.SOAP.securityEnabled=true com.ibm.SOAP.loginUserid=userid com.ibm.SOAP.loginPassword=password

502

WebSphere Version 5.1 Web Services Handbook

Implementing a private UDDI registry You must have WebSphere Application Server Network Deployment, which provides the private UDDI registry, which is a single-node registry. You also need at least one application server in which to deploy the registry.

Install the UDDI registry on an application server Follow the instructions in the InfoCenter under Installing -> Applications -> Web services servers -> Installing and setting up a UDDI Registry. You can select Cloudscape (testing) or DB2 (production) as the database:
Install the Network Deployment product to get access to the UDDI component.
Install UDDI into a stand-alone application server (for example, server1). For a production environment, you must configure WebSphere security.

Using the UDDI registry The UDDI registry can be accessed programmatically through the SOAP interface—for example, by using UDDI4J—or through the EJB client interface that is also provided. Details of these interfaces are provided in the InfoCenter. Refer to “UDDI4J overview” on page 114 for examples of the UDDI4J API. In addition, a UDDI GUI—also referred to as the UDDI User Console—is provided to allow users to familiarize themselves with the key concepts of UDDI. This UDDI GUI can be used both to publish and to inquire about UDDI entities. The GUI does not provide all the functions of the UDDI API; for some of the more complex operations, the programmatic interfaces should be used instead.

Using the UDDI GUI The following sections show how to perform some simple operations using the UDDI GUI.

Start the UDDI GUI Open a browser with the UDDI URL and the private UDDI home page opens (Figure 20-10). http://:9080/uddigui

Chapter 20. Web services runtime and deployment in WebSphere

503

Figure 20-10 Private UDDI home page

Publishing information To add a business use the Publish tab (left side), enter a business name in the Quick Publish field, and click Publish now (Figure 20-11). Note that the business radio button is selected. This operation will publish a business with the specified name using the Quick Publish option. With this option, no other information about the entity is provided. If you want to provide further details, such as a description and some categorization, you should use the Advanced Publish option.

504

WebSphere Version 5.1 Web Services Handbook

Without WebSphere security enabled all entries are owned by the user ID: UNAUTHENTICATED

Figure 20-11 Publishing a business

To locate and edit the entries you own, click Show owned entities (Figure 20-12).

Figure 20-12 Owned entities

You can edit the business and add a description, locators (classifications), and contacts.

Chapter 20. Web services runtime and deployment in WebSphere

505

You can add a service to the business by clicking Add service and completing the form (Figure 20-13). You have to click Add individually for each piece of information that you enter, and click Publish Service (bottom) when done.

Figure 20-13 Adding a service to a business

The access point is: http://www.flashandthunder.com/ItsoFlashWeb/services/WeatherForecast

Add a technical model using Quick Publish (Figure 20-14).

Figure 20-14 Publishing a technical model

506

WebSphere Version 5.1 Web Services Handbook

Edit the technical model from the owned entities panel (Figure 20-15):
Notice the Overview URL field that can point to a WSDL file on a provider server.
Click Update Technical Model when done.
You could alternatively provide the extra information about the technical model at the same time as you create it by using the Advanced Publish option.

Figure 20-15 Updating a technical model

The Overview URL for our sample service is: http://www.flashandthunder.com/ItsoFlashWeb/wsdl/itso/bean/WeatherForecast.wsdl

Chapter 20. Web services runtime and deployment in WebSphere

507

Finally you update the service to point to the technical model:
Select Show owned entities.
Click Show Services for the business entity.
Click Edit for the WeatherForecast service.
Click Add for Technical model name (Figure 20-16).

Figure 20-16 Assigning a technical model to a service (1)


Find the technical model by searching for ITSO. Click Find Technical Models.
Select the technical model from the list of results and click Update (Figure 20-17).

Figure 20-17 Assigning a technical model to a service (2)

Figure 20-18 shows the owned entities panel with the business, service, and technical model.

508

WebSphere Version 5.1 Web Services Handbook

Show services

Figure 20-18 Owned entities with services and technical models

Using the UDDI Explorer with the private UDDI registry When you are developing applications using Application Developer Version 5, you can perform these operations using the UDDI Explorer. Start the UDDI Explorer by clicking Run -> Launch the Web Services Explorer. In the home panel, click UDDI Main, assign a name to the private registry, and define the inquiry API (Figure 20-19): http://:9080/uddisoap/inquiryapi

Click Go to connect to the registry.

Chapter 20. Web services runtime and deployment in WebSphere

509

Figure 20-19 UDDI Explorer: Set up private UDDI registry

Publishing Click the Publish icon ( ) and fill in the form. You must provide the publishing API URL and a user ID and password (Figure 20-20).

The user ID becomes the owner of the entry. Without WebSphere security enabled you can type any user ID and leave the password empty.

Figure 20-20 Publishing a business

510

WebSphere Version 5.1 Web Services Handbook

Finding information Use the Find icon (

) to execute queries against the registry (Figure 20-21).

Figure 20-21 Exploring the UDDI registry

For more information on the UDDI Explorer, refer to “Publishing and exploring a UDDI registry” on page 295.

Chapter 20. Web services runtime and deployment in WebSphere

511

Summary In this chapter we covered IBM WebSphere Application Server as the basis for deployment of enterprise applications and Web services. We looked at the general concepts, the administration facilities, and then specifically at how to deploy our example applications and Web services into an application server. Finally we showed how to implement a private UDDI registry and access the registry using a browser interface and the Web Services Explorer of Application Developer.

More information For general information on the IBM WebSphere family of products, refer to: http://www.software.ibm.com/websphere/

For information on IBM WebSphere Application Server, refer to: http://www.ibm.com/webservers/appserv/

The WebSphere InfoCenter is one of the most valuable and up-to-date online resources: http://www.ibm.com/software/webservers/appserv/infocenter.html

The WebSphere Application Server product is also covered in detail in the publication IBM WebSphere Application Server Version 5.0 Handbook, SG24-6195. The security details are discussed in the publication IBM WebSphere V5.0 Security: WebSphere Handbook Series, SG24-6573.

512

WebSphere Version 5.1 Web Services Handbook

Part 3

Part

3

Appendixes

© Copyright IBM Corp. 2003, 2004. All rights reserved.

513

514

WebSphere Version 5.1 Web Services Handbook

A

Appendix A.

Installation and setup This appendix provides brief instructions for installing the products as used in this publication, which are:
IBM WebSphere Application Server Version 5.1
IBM WebSphere Studio Application Developer Version 5.1.1
IBM WebSphere SDK for Web Services Version 5.1
IBM alphaWorks Emerging Technologies Toolkit Version 1.2
IBM Universal Database DB2 Version 8.1, Fixpack 2 (or 7.2, with Fixpack 7)

© Copyright IBM Corp. 2003, 2004. All rights reserved.

515

Installation planning This section provides installation planning information for the products as used in this book.

WebSphere Application Server Version 5.1 requirements IBM WebSphere Application Server Base and Network Deployment have the following hardware and software requirements. For updated information on the requirements, please refer to WebSphere InfoCenter and documentation: http://www-3.ibm.com/software/webservers/appserv/infocenter.html http://www-3.ibm.com/software/webservers/appserv/doc/latest/prereq.html

Hardware Hardware requirements for Windows servers include:






Intel Pentium processor at 500 MHz, or faster Minimum 600 MB free disk space for installation of Version 5.1 Minimum 256 MB memory; 512 MB or more recommended CD-ROM drive Support for a communications adapter

Software The installation requires the following software to be installed:
Windows NT Server V4.0, SP 6a or later, Windows 2000 Server or Advanced Server SP 3, Windows Server 2003, Windows XP Pro SP 1
Netscape Communicator 4.79 or Microsoft Internet Explorer 5.5 SP 2 and 6.0
Web browser that supports HTML 4 and CSS For detailed hardware and software requirements, go to: http://www.ibm.com/software/webservers/appserv/doc/v50/prereqs/was_v51.htm

Database support For the WebSphere installation, the database does not have to be configured. Cloudscape can be used in test environment, but other databases are required for the production environment. Note: This publication includes sample code that uses a database and a data source server configuration that is for DB2 UDB V8.1, but also provides instructions how to reconfigure for a DB2 V7.2 Fixpack 7 data source.

516

WebSphere Version 5.1 Web Services Handbook

Installing WebSphere Application Server 5.1 The InstallShield Multi Platform (ISMP) is a new installer that is used to install WebSphere Application Server on Intel, AIX, Linux, Linux/390, and Solaris. It checks the installation prerequisites. It also generates the uninstall program after the product has been completely installed. The administrative database of WebSphere Version 4 does not exist any longer. All of the configuration information for the WebSphere Application Server Version 5 is now contained in XML files in the ${WAS_ROOT}\config directory. There are many files that contain all the configuration information.

Installation process for Version 5.1 base product First we start the LaunchPad (launchpad.bat) to access the product overview, the ReadMe file, and installation guides.
Select Install the product to launch the installation wizard (Figure A-1).
After confirming that we agree with the license agreement, we have to choose between two installation choices: Full and Custom. Full installs the entire product, whereas Custom installation options allows you to deselect components you do not want to install. We chose Full installation.
The installation directories for the selected components are entered in the next window. We chose: c:\WebSphere\AppServer c:\WebSphere\IBMHttpServer c:\WebSphere\WebSphere MQ


In the following panel we enter a node name and host name or IP address. In addition, we can select to install both WebSphere Application Server and IBM HTTP Server as a service on Windows NT, 2000, and XP.

Appendix A. Installation and setup

517

Figure A-1 WebSphere Application Server LaunchPad


After the Summary window, the installation starts.
The FirstSteps window is started automatically at the end of the installation.

Verifying the installation Installation verification can be started from the menu. In Windows 2000, select Start -> IBM WebSphere -> Application Server v5.1 -> First Steps. Then select Verify Installation. We can also start with the command ivc localhost. If the install was successful, you should see messages similar to the following: IVTL0095I: defaulting to host and port 9080 IVTL0010I: Connecting to the WebSphere Application Server on port: 9080 IVTL0020I: Could not connect to Application Server, waiting for server to start IVTL0025I: Attempting to start the Application Server IVTL0030I: Running cmd.exe /c "C:\WebSphere\AppServer\bin\startServer" server1 >ADMU0116I: Tool information is being logged in file > C:\WebSphere\AppServer\logs\server1\startServer.log >ADMU3100I: Reading configuration for server: server1 >ADMU3200I: Server launched. Waiting for initialization status. >ADMU3000I: Server server1 open for e-business; process id is 3056

518

WebSphere Version 5.1 Web Services Handbook

IVTL0050I: Servlet Engine Verification Status - Passed IVTL0055I: JSP Verification Status - Passed IVTL0060I: EJB Verification Status - Passed IVTL0070I: IVT Verification Succeeded IVTL0080I: Installation Verification is complete

Fixpack You should always check if Fixpacks are available to upgrade the code.

Installing WebSphere Application Server Network Deployment 5.1 To follow the examples in this publication Network Deployment is not required, unless you want to install the private UDDI registry, as described in “Implementing a private UDDI registry” on page 503. The InstallShield and update wizard are used for the Network Deployment product as well, which provides a similar look and feel across the product line. The Web services components (UDDI registry and Web Services Gateway) are bundled and shipped with the Network Deployment version. The EAR files for these components are placed into the installableApps subdirectory. The scripts and additional details on how to install these components are located in the UDDIReg and WSGW subdirectories, respectively.

Application Server Toolkit The Application Server Toolkit (ASTK) is a separate installable component that can be used, for example, for configuring enterprise applications with the Assembly Toolkit. We did not install and use the ASTK for this publication. We used Application Developer to configure all enterprise applications.

Appendix A. Installation and setup

519

Installation of Application Developer 5.1.1 The installation of the Application Developer is a very straightforward process. Perform the following steps:
Double-click setup.exe and the Installation Launcher window appears (Figure A-2).

Figure A-2 Application Developer Installation window


Select Install IBM WebSphere Studio Application Developer.
In the Welcome window, click Next.
In the License Agreement window, accept the agreement and click Next.
In the Destination Folder window, browse to a folder of your choice and then click Next. We used c:\WSAD511 as the installation folder.
In the Custom Setup window, accept the defaults and click Next.
In the next window, click Install.
After a rather long time period the next window tells you of the success of the installation. Click Finish.
The last window allows you to specify the location of your workspace. We use c:\WSAD511sg246819 for the workspace location.

520

WebSphere Version 5.1 Web Services Handbook

Installing optional components The optional components are not required to follow the samples in this publication. You can install these components:
IBM Agent Controller—If you want to test or debug applications running in a real WebSphere Application Server on the same or another machine.
Embedded messaging client and server—If you want to develop applications using WebSphere MQ. (The message-driven bean we use for Web services can be tested using the built-in MQ Simulator.)
Rational ClearCase LT—For team development as an alternative to Common Versions Systems (CVS).

Starting Application Developer with a dedicated workspace You can create icons to start Application Developer with multiple workspaces. In the Properties window of the icon, enter the target with the -data flag to indicate the workspace location, for example: C:\\wsappdev.exe -data C:\WSAD511sg246891

Appendix A. Installation and setup

521

Installation of Application Developer Integration Edition Important: You cannot install Integration Edition on the same machine as base Application Developer. You must remove Application Developer first. All the functions of Application Developer are included in Integration Edition. Installation of Application Developer Integration Edition is similar to Application Developer. An installation window very similar to Figure A-2 is presented, where you select to install the Integration Edition:
Follow the prompts as for Application Developer.
For features, be sure to select the WebSphere Version 5 Enterprise Edition test environment if you want to test business processes. When you start the product, you are prompted for a workspace. For example, enter d:\WSAD5sg246891-IE as the workspace location (Figure A-3):
Deselect the option Use this workspace as the default and do not show this window box again.
You are then prompted for the workspace location every time you start the product, which enables you to use multiple workspaces.

Figure A-3 Workspace location for Integration Edition

Optionally install the embedded messaging client and server and ClearCase LT.

CICS Transaction Gateway When you install Application Developer Integration Edition, the IBM CICS Transaction Gateway is automatically installed as well.

Agent Controller The IBM Agent Controller is also installed automatically for you.

522

WebSphere Version 5.1 Web Services Handbook

Installation of WebSphere SDK for Web Services 5.1 Download the zip file of WSDK (for the Windows platform) from developerWorks: http://www-106.ibm.com/developerworks/webservices/wsdk/

Eclipse plug-in If you want to use the Eclipse plug-in of WSDK, you have to download Eclipse 2.1.1 and install it before installing WSDK. The download site for Eclipse is at: http://www.eclipse.org http://www.eclipse.org/downloads/index.php

WSDK installation Unpack the WSDK ZIP file and start the executable installer (wsdksetup.exe). Figure A-4 shows the English version welcome screen of the installer.
Follow the prompts in the various panels. Exclude the Eclipse plug-in installation if you do not have Eclipse 2.1.1 installed on your machine.

Figure A-4 Installer for IBM WebSphere SDK for Web Services


Specify the installation target location, for example, d:\WSDK51.
The installation creates a program folder with three icons: Start Server, Stop Server, and WSDK Help. Start the help facility and familiarize yourself with the concepts and tools.

Appendix A. Installation and setup

523

Installation of the Emerging Technologies Toolkit (ETTK) The Emerging Technologies Toolkit (ETTK) evolved from the Web Services Toolkit (WSTK). The ETTK scope has been expanded to include emerging autonomic and grid-related technologies and Web services, and—at the same time—the ETTK has been split up into two tracks:
ETTK Autonomic Computing
ETTK Web Services Track The installations of the Emerging Technologies Toolkit is straightforward:
Download the executable install files from alphaWorks for either track and platforms—Windows or Linux—from: http://www.alphaworks.ibm.com/tech/ettk


Run the executables and follow the instructions and prompts of the InstallShield wizard. The wizard looks for the default JDK, but allows the user to browse for the appropriate JDK. Note: You require an application server to run the ETTK. This can be the WebSphere SDK for Web Services (WSDK) 5.1, WebSphere Application Server 5.0.2 or later, or Apache Tomkat 4.1.27 or later.

Installing the sample code The sample code is available from the ITSO Redbooks Web site: http://www.redbooks.ibm.com

Follow the link Additional Materials and look for the SG246891 directory matching this book. Download the sample code, sg246891-01code.zip, and extract the files to your hard drive, creating a directory c:\SG246891-01. The content of the sample code is described in “Web material content” on page 526.

Setting up the WEATHER database To work through the weather forecast samples you have to set up the WEATHER database as described in “Set up the WEATHER database” on page 528.

524

WebSphere Version 5.1 Web Services Handbook

B

Appendix B.

Additional material This redbook refers to additional material that can be downloaded from the Internet as described below.

Locating the Web material The Web material associated with this redbook is available in softcopy on the Internet from the IBM Redbooks Web server. Point your Web browser to: ftp://www.redbooks.ibm.com/redbooks/SG246891

Alternatively, you can go to the IBM Redbooks Web site at: ibm.com/redbooks

Select the Additional materials and open the directory that corresponds with the redbook form number, SG24-6891-01 (SG246891).

© Copyright IBM Corp. 2003, 2004. All rights reserved.

525

Using the Web material The additional Web material that accompanies this redbook includes the following files: File name Description sg246891-01code.zip Sample code for following the samples in the book corrections-01.txt Corrections to the book after publishing

System requirements for downloading the Web material The following system configuration is recommended: Hard disk space Operating System Processor Memory

3 GB Windows 2000 or Windows NT 700 MHz or better 512 MB, recommended 784 MB

Web material content Unzip the contents of the Web material sg246891-01code.zip file onto your hard drive. This creates a folder structure c:\SG246891-01\sampcode\xxxx, where xxxxx refers to a chapter or activity in the book: _setup

Database setup and initial EAR files

weatherforecast

Basic code of the weather forecast example

wsad51

Sample code for Web services development using WebSphere Studio Application Developer

wsad51security

Sample code for Web services with WS-Security 1.0

wsad-ie

Sample code for Application Developer Integration Edition (this code has not been updated for Version 5.1)

wsdk51

Sample code for WebSphere SDK for Web Services

scenario

Sample code for Web services scenario

was

Deployment into Application Server

z_EARfiles

Final EAR files from Application Developer

z_workspace

Application Developer workspace projects

ItsoXxxxxxx

526

- Projects for import into workspace

WebSphere Version 5.1 Web Services Handbook

Workspace projects Table B-1 lists the sample projects for Web service development with Application Developer. Projects prefixed with a dash (-) belong to the enterprise application listed above the project. Table B-1 Application Developer projects (part 1) Name

Description

ItsoWebService1

Web service from JavaBean

- ItsoWebService1Web

Web project with Web service

- ItsoWebService1WebClient

Client project to test Web service

- ItsoWebService1JavaClient

Stand-alone client application

ItsoWebService2

Web service from session EJB (HTTP-based)

- ItsoWebService2EJB

EJB project with session EJB

- ItsoWebService2EJBClient

Client project to test Web service

- ItsoWebService2RouterWeb

Router project to invoke EJB Web service

ItsoWebService3

Web service from session EJB (JMS-based)

- ItsoWebService3EJB

EJB project with session EJB

- ItsoWebService3EJBClient

Client project to test Web service

- ItsoWebService3RouterEJB

Router project with message-driven bean

ItsoWebService4

Web service top-down from WSDL

- ItsoWebService4Web

Web project with Web service

- ItsoWebService4WebClient

Client project to test Web service

ItsoWebService5

Web service from URL and DADX

- ItsoWebService5Web

Web project with Web service

- ItsoWebService5WebClient

Client project to test Web service

ItsoWebService6

WS-Security with EJB Web service

- ItsoWebService6EJB

EJB project with session EJB

- ItsoWebService6EJBClient

Client project to test Web service

- ItsoWebService6RouterWeb

Router project to invoke EJB Web service

Appendix B. Additional material

527

Table B-2 lists the sample projects of the scenario sample application for Web Application Developer. Projects prefixed with a dash (-) belong to the enterprise application listed above the project. Table B-2 Application Developer projects (part 2) Name

Description

ItsoIWA

International Weather Association EAR project

- ItsoFlashWeb

Web project for Flash Web service

- ItsoThunderWeb

Web project for Thunder Web service

- ItsoSiliconWeatherWeb

Web project for SiliconWeather Web service

- ItsoSiliconWeatherEJB

EJB project for SiliconWeather EJB Web service

- ItsoSiliconWeatherEJBRouter

EJB router project with message-driven bean

- ItsoIWAUpdateWeatherClient

Client Web project to update weather information

ItsoUnitedSuns

UnitedSuns EAR project

- ItsoUnitedSunsClient

Client Web project to invoke Web services

- ItsoWebService2EJBClient

Client project to test Web service

Installing the weather forecast application Here are short instructions for how to install the starting sample code in Application Developer 5.1.1. Create a workspace for the samples, for example, c:\WSAD511sg246891.

Set up the WEATHER database A DB2 command stream to define the WEATHER database is provided in sg246891-01\sampcode\_setup\Database\Itsoweather.ddl. There are two subdirectories with command files to execute the command stream, DB2V7 and DB2V8. Use the subdirectory that matches your DB2 installation:
Execute the createWeather.bat file to define the database and table.
Execute the loadWeather.bat file to delete the existing data and add two records.
Execute the listWeather.bat file to list the content of the database.

528

WebSphere Version 5.1 Web Services Handbook

Set up the WebSphere test server (WeatherServer) The best way to set up a server is to define a server and configure it.

Server project Definitions of servers are stored in a server project. To define such a project:
Select File -> New -> Project (or use the New icon ( toolbar).

) from the main


Select Server -> Server Project and click Next.
Enter Servers as the project name, and accept the default location.
Click Finish. The Confirm Perspective Switch window opens.
Click Yes and the Server perspective opens.

WebSphere Version 5.1 server Now we define a WebSphere server for testing the EJBs. Because we implement EJB 2.0 beans we must use the Version 5 server for testing.
Select File -> New -> Server and Server Configuration (or use the New icon ( ) from the main toolbar).
Select Server in the left pane and Server and Server Configuration in the right pane, and click Next.
Enter WeatherServer as the name. The Servers project is preselected. Expand WebSphere version 5.1 and select Test Environment.
Click Next. Check that the port is set to 9080 and click Finish. Note: Application Developer Version 5.1.1 includes a WebSphere Application Server Version 5.1.

Configuring the server We use the WeatherServer to access the WEATHER database using EJBs. We have to configure a data source for this access:
Open the WeatherServer in the Server Configuration view.
Look through the different pages of configuration information.

Define an authentication alias Go to the Security page to define a user ID and password for the data source. Click Add for JAAS Authentication Entries.

Appendix B. Additional material

529

Complete the window with a valid user ID and password (for example, the user ID that was used to install DB2) and click OK (Figure B-1).

A JAAS alias is required if the container does the authentication of the user ID.

Figure B-1 Defining a user ID for authentication

The entry appears in the list on the Security page (Figure B-2).

Figure B-2 Server configuration: Security

Define a data source Next, go to the Data source page. Note that there are Node Settings and Server Settings. In the test environment we only run one server on one node. Therefore, it does not matter where we define the data source for the WEATHER database. Depending on the version of DB2, we define a data source for Version 8.1 or for Version 7.2.

530

WebSphere Version 5.1 Web Services Handbook

DB2 Version 8.1 To define a data source follow these steps:
Scroll down to Server Settings. Click Add for JDBC Providers.
In the dialog, select IBM DB2 and DB2 Universal JDBC Driver Provider (XA).
Enter DB2 Universal JDBC Provider as the Name. Note that the classpath uses the variable ${DB2UNIVERSAL_JDBC_DRIVER_PATH}.
Click Finish.
Select the JDBC Provider and click Add for Data source.
Click Add next to the Data source list.
In the Create a Data Source window, select DB2 Universal JDBC Driver Provider for the type of JDBC provider and Version 5.0 data source for the type of data source. Click Next.
The Modify Data Source window opens (Figure B-3).

Figure B-3 Define the data source for the WEATHER database

Appendix B. Additional material

531


Complete the Modify Data Source window: – Enter WEATHER1 as the name to be displayed in the list of data sources. – Enter jdbc/sjweather as the JNDI name (this is what we specify in the EJB deployment descriptor to access the database). – Verify the Data store helper class name (DB2DataStoreHelper). – Select the DB2User for component- and container-managed authentication alias. – Deselect Use this data source in container-managed persistence (CMP). We are not using container-managed persistence. – Optionally enter a description. We do not specify the database name yet.
Click Next. In the Create Resource Properties window, select the databaseName property and change the value to WEATHER (Figure B-4).
Click Finish.

Figure B-4 Setting the database name


The data source is added to the list and displayed in the server configuration (Figure B-5).

532

WebSphere Version 5.1 Web Services Handbook

Figure B-5 Server configuration with data source

DB2 Version 7.2 Follow the instructions given for DB2 Version 8.1, but select the Default DB2 JDBC Provider (you do not have to define a provider):
Define the data source for the default provider.
Select DB2 JDBC Provider, otherwise the instructions are the same.

Verify the server variables We have to set up the server variables that point to the DB2 JDBC providers:
On the variables page check the two variables DB2_JDBC_DRIVER_PATH and DB2UNIVERSAL_JDBC_DRIVER_PATH. Both have to point to your DB2 installation java directory, for example: c:\SQLLIB\java c:\Program Files\SQLLIB\java

Save the server configuration and close the editor.

Appendix B. Additional material

533

Configure the JMS server We configure a JMS server inside the WeatherServer. We have to perform four modifications in the server configuration:






Define a QueueConnectionFactory object. Define a Queue object. Add the Queue to the list of queues of the JMS provider. Select the type of JMS server. Define the listener port.

Here are the steps to configure the server with JMS:
Open the configuration of the WeatherServer.
Go to the JMS page.
Scroll down to the JMS Connection Factories section. For JMS Connection Factories, click Add next to the WasQueueConnectionFactory entries. Supply the Name and JNDI Name as shown in Figure B-6. Accept the default values of the remaining fields.

Figure B-6 Add a QueueConnectionFactory to the server configuration


For JMS Destinations, click Add next to WASQueue. Supply the Name and JNDI Name values as shown in Figure B-7. Accept defaults for the remaining fields.

Figure B-7 Add a Queue to the server configuration


For JMS Server Properties, click Add next to Queue names. Enter WeatherQueue and click OK.
Select MQ Simulator for Java Developers under JMS Provider. For the sake of simplicity we use the built-in messaging simulator instead of WebSphere MQ.
After these additions, the JMS page should look like Figure B-8.

534

WebSphere Version 5.1 Web Services Handbook

Figure B-8 JMS server configuration


Go to the EJB page.
On the EJB page we add the listener port. Click Add and specify the values as shown in Figure B-9.

Appendix B. Additional material

535

Figure B-9 Add a Listener Port

Runtime classpath For JMS-based Web services, one JAR file is required in the server classpath:
On the Environment page, expand Class Path.
Click Add External JARs.
Navigate to c:\\runtimes\base_v51\lib\urlprotocols.jar and click Open (Figure B-10).

c:\WSAD511\runtimes\base_v51\lib\urlprotocols.jar

Figure B-10 Update the classpath

Important: Ensure that the urlprotocols.jar file is added to the Class Path field of the Environment tab. During our testing we observed that this or any other JMS samples do not run in WSAD 5.1 until this step is performed.

536

WebSphere Version 5.1 Web Services Handbook

At this point start the WeatherServer and watch the Console messages. The JMS Provider is started and the queue is bound: [...] ... JMSMQJDProvid A MSGS0656I: Starting the MQJD JMS Provider [...] ... JMSMQJDProvid A MSGS0650I: MQJD JMS Provider open for business [...] ... ResourceMgrIm I WSVR0049I: Binding WeatherQCF as jms/WeatherQCF

Stop the server when you have verified that the JMS server starts.

Set up the initial applications for Web services development Enterprise application EAR files to create the starting applications in the Application Developer workspace directory are provided in the sg246891-01\sampcode\_setup\EAR directory of the sample code (see “Web material content” on page 526). To import the EAR files into the workspace:
Start WebSphere Studio Application Developer if it is not already started.
Select File -> Import -> EAR file and click Next.
Click Browse for the EAR file and locate the ItsoWebService1.ear file (in sg246891-01\sampcode\_setup\EAR). Select the file and click Open, make sure the project name is ItsoWebService1, then click Finish.
Repeat this for the ItsoWebService2.ear and ItsoWebService3.ear files. Make sure the project names are ItsoWebService2 and ItsoWebService3.

Test the starting application To test the starting enterprise application:
Select the WeatherServer (in the Server Configuration or Servers view) and Add and remove projects. In the dialog select the three ItsoWebServiceX projects and click Add>, then click Finish.
Start the WeatherServer.
Expand the ItsoWebService1Web project, select the WeatherTester servlet and Run on Server: – Select the WeatherServer when prompted, then click Next. Deselect Deploy EJB beans (the code is already generated) and click Finish. – The servlet runs the methods of the WeatherForecast JavaBean and displays the weather results.

Appendix B. Additional material

537


Test the ItsoWebService2 application using the universal test client (UTC): – Expand EJB Modules -> ItsoWebService2EJB -> Session Beans (in the J2EE Hierarchy view). – Select the WeatherForecastEJB bean and Run on Server. – In the universal test client window, expand WeatherForecastEJB -> WeatherForecastEJBHome, select the create method, click Invoke. and afterwards click Work with Object. – Expand WeatherForecastEJB1 and select the getForecast(Calendar, int) method. Type 9 for the int value and click Invoke. – The result is an array with 10 Weather elements. Click Work with Object. – Expand Weather[10] and select Inspect Fields. There should be 10 weather predictions. – Optionally test the other methods (getDayForecast, getTemperatures).
Run the listWeather.bat command file (sampcode\_setup\Database\DB2Vx) and you should see the rows that were added with the current date and the next 9 days.

Installing the scenario sample application The scenario sample application is provided in two EAR files, ItsoIWA.ear and ItsoUnitedSuns.ear, and a server configuration (ScenarioServer). The instructions for installing and configuring the scenario sample application are provided in “Installing the scenario in Application Developer” on page 473.

Installing the sample applications into WebSphere The instructions for configuring a WebSphere Application Server for the scenario and sample applications are provided in “Configuring a server for the ITSO Web services” on page 487. The instructions for installing and configuring the scenario and sample applications into a WebSphere Application Server are provided in “Install the enterprise applications” on page 494.

538

WebSphere Version 5.1 Web Services Handbook

Importing solutions into Application Developer The z_workspace directory contains all the finished projects that can be imported into an Application Developer workspace. Import the projects in the sequence listed in Table B-1 on page 527 and Table B-2 on page 528.

Importing a sample project into Application Developer To import a sample project ItsoWebServiceXXX from the sample code into the Application Developer workspace, execute these steps:
Copy the desired project(s) from the sample code installation directory into the Application Developer workspace directory: From: sg246891-01\sampcode\z_workspace To: c:\WSAD511sg246891

Sample code Application Developer workspace


In Application Developer, select File -> Import.
In the Import wizard (Figure B-11) select Existing Project into Workspace and click Next.

Figure B-11 Application Developer Import Wizard

Appendix B. Additional material

539


In the Import Project window (Figure B-12) click Browse to select the project contents directory.

c:\WSAD511sg246891\ItsoWebServiceXX

Figure B-12 Import project


In the Browse For Folder window (Figure B-13) browse to the location of the desired project folder and click OK. c:\WSAD511sg246891\ItsoWebServiceXxx

Figure B-13 Browse for folder: Import a project

540

WebSphere Version 5.1 Web Services Handbook


Back in the import wizard, click Finish. The selected project is added into the Workspace. Tip: After importing several projects that have dependencies on each other, it may be necessary to rebuild all or selected projects:
Select a project and Project -> Rebuild Project (for one project).
Select Project -> Rebuild All (for all projects).

Importing a single source file into Application Developer To import a sample source code file execute these steps:
Select the target folder in the workspace and Import (context).
In the Import wizard select File System and click Next.
Click Browse and locate the folder that contains the desired file in the sg246891-01\sampcode\workspace\ItsoWebServiceXxxxx project directory (Figure B-14). Click OK.

Project folder

Source folder

Figure B-14 Import from directory: Import files

Appendix B. Additional material

541


In the Import wizard, select the desired file(s) in the right pane. Do not select the folder in the left pane (otherwise a subfolder is created in the workspace). Verify the destination folder (Figure B-15).

Figure B-15 Import file selection window


Click Finish.

Universal test client problem In Application Developer Version 5.1 you may get marshalling errors when running the universal test client after generating the Web services. A solution is to open the WeatherServer server configuration and on the Configuration page set the Application class loader policy to SINGLE. You have to restart the server.

542

WebSphere Version 5.1 Web Services Handbook

Abbreviations and acronyms AAT

Application Assembly Tool

EDI

Electronic data interchange

API

Application programming interface

EIS

Enterprise information system

EJB

Enterprise JavaBeans

ASTK

Application Server Toolkit

EJS

Enterprise Java Server

AXIS

Apache eXtensible Interaction System

EPI

External presentation interface

B2B

Business-to-business

ERP

Enterprise resource planning

B2C

Business-to-consumer

ETTK

B2E

Business-to-employee

Emerging Technologies Toolkit

BPEL

Business process execution language

FDML

Flow definition markup language

CCF

Common Connector Framework

FTP

File Transfer Protocol

GUI

Graphical user interface

CCI

Common client interface

HTML

Hypertext Markup Language

CICS

Customer Information Control System

HTTP

Hypertext Transfer Protocol

CORBA

Common Object Request Broker Architecture

IBM

International Business Machines Corporation

CRM

Customer relationship management

IDE

Integrated development environment

CTG

CICS Transaction Gateway

IIOP

Internet Inter-ORB Protocol

CVS

Common Versions System

IMS

Information Management System

DAD

Document access definition

ITSO

DADX

Document access definition extended

International Technical Support Organization

IWA

DBMS

Database management system

International Weather Association (fictitious0

JCA

J2EE connector architecture

DCOM

Distributed common object model

J2C

J2EE connector architecture

DII

Dynamic invocation interface

J2EE

Java 2 Enterprise Edition

DOM

Document object model

J2SE

Java 2 Standard Edition

DTD

Document type definition

JAR

Java archive

EAR

Enterprise application archive

JAX-RPC

Java APIs for XML based RPC

ECI

External call interface

JDBC

Java Database Connectivity

© Copyright IBM Corp. 2003, 2004. All rights reserved.

543

JDK

Java Developer’s Kit

SPO

Service provider offering

JMS

Java Messaging Service

SQL

Structured query language

JMX

Java Management eXtension

SSL

Secure Sockets Layer

JNDI

Java Naming and Directory Interface

TCP/IP

Transmission Control Protocol/Internet Protocol

JSP

JavaServer Page

TPV

Tivoli Performance Viewer

JSR

Java specification request

UDDI

LDAP

Lightweight Directory Access Protocol

Universal description, discovery, and integration

UNSPSC

MVC

Model-view-controller

Universal Standard Products and Services Classification

NAICS

North American Industry Classification System

URL

Uniform resource locator

URN

Uniform resource name

OMG

Object Management Group

UTC

Universal test client

PMI

Performance monitor interface

UUID

Universal unique identifier

WAR

Web application archive

PKI

Public key interface

WORF

QOS

Quality of service

Web service object runtime facility

RAD

Rapid application development

WSCA

Web services conceptual architecture

RAR

Resource adapter archive

WSDL

RDBMS

Relational database management system

Web service description language

WSDK

WebSphere SDK for Web Services

RMI

Remote Method Invocation

RPC

Remote procedure call

WSFL

Web services flow language

SAAJ

SOAP with Attachments API for Java

WSGW

Web Services Gateway

WS-I

Web services interoperability

SAML

Security assertion markup language

WSIF

Web services invocation framework

SAX

Simple API for XML

WSIL

SCM

Supply chain management

Web services inspection language

SDK

Software Development Kit

WSTK

Web Services Toolkit

SEI

Service endpoint interface

WWW

World Wide Web

SMTP

Simple Mail Transfer Protocol

XMI

XML metadata interchange

SOA

Service oriented architecture

XML

eXtensible Markup Language

SOAP

Simple Object Access Protocol (also known as Service Oriented Architecture Protocol)

XSD

XML schema definition

544

WebSphere Version 5.1 Web Services Handbook

Related publications The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook.

IBM Redbooks For information on ordering these publications, see “How to get IBM Redbooks” on page 548.
WebSphere Version 5 Application Development Handbook, SG24-6993
WebSphere Studio Application Developer Version 5 Programming Guide, SG24-6957
EJB 2.0 Development with WebSphere Studio Application Developer, SG24-6819
IBM WebSphere Application Server Version 5.0 Handbook, SG24-6195
IBM WebSphere V5.0 Security: WebSphere Handbook Series, SG24-6573
Legacy Modernization with WebSphere Studio Enterprise Developer, SG24-6806
WebSphere Studio Application Developer Programming Guide, SG24-6585
Web Services Wizardry with WebSphere Studio Application Developer, SG24-6292
Self-Study Guide: WebSphere Studio Application Developer and Web Services, SG24-6407
WebSphere Version 4 Application Development Handbook, SG24-6134
Programming J2EE APIs with WebSphere Advanced, SG24-6124
CICS Transaction Gateway V5 The WebSphere Connector for CICS, SG24-6133
Enterprise JavaBeans for z/OS and OS/390 CICS Transaction Server V2.1, SG24-6284
Design and Implement Servlets, JSPs, and EJBs for IBM WebSphere Application Server, SG24-5754
Integrating your Information, Getting stated with DB2 UDB, WebSphere MQ, XML and Web Services, SG24-6892

© Copyright IBM Corp. 2003, 2004. All rights reserved.

545

Other resources These publications are also relevant as further information sources:
WebSphere Bible, Kataoka et al, ISBN 0764548964, Wiley, John & Sons, 2002
Web Services: Building Blocks for Distributed Systems, Glass, ISBN 0130662569, Prentice Hall, 2001
SOAP Programming with Java, Brogden, ISBN 0782129285, Sybex, 2002
XML and Web Services Unleashed, Schmelzer et al, ISBN 0672323419, SAMS, 2002

Referenced Web sites These Web sites are also relevant as further information sources:
IBM Internet Web site http://www.ibm.com/webservices/


Web services on developerWorks http://www.ibm.com/developerworks/ http://www.ibm.com/developerworks/webservices


Web services on alphaWorks http://www.alphaworks.ibm.com/ http://www.alphaworks.ibm.com/webservices


Web services interoperability http://www.ws-i.org


IBM Software http://www.ibm.com/software/websphere http://www.ibm.com/software/webservers/ http://www.ibm.com/software/solutions/webservices http://www.ibm.com/software/integration/busconn/gateway.htm http://www.ibm.com/software/ad http://www.ibm.com/software/ts http://www.ibm.com/software/pervasive


IBM Tivoli http://www.tivoli.com/


Eclipse http://www.eclipse.org

546

WebSphere Version 5.1 Web Services Handbook


UDDI Web sites and registries http://www.uddi.org http://www.uddi4j.org http://www.ibm.com/services/uddi http://uddi.ibm.com http://uddi.microsoft.com http://uddi.sap.com http://www.ntt.com/uddi


Apache open-source Web site http://www.apache.org/ http://cvs.apache.org/


OASIS http://www.oasis-open.org


World Wide Web Consortium W3C http://www.w3.org/


XML schema http://schemas.xmlsoap.org/


Sun Java Web site http://java.sun.com/


Java Community Process http://www.jcp.org/en/jsr/


Microsoft SOAP http://msdn.microsoft.com/


XMethods http://www.xmethods.net/inspection.wsil

Related publications

547

How to get IBM Redbooks You can order hardcopy Redbooks, as well as view, download, or search for Redbooks at the following Web site: ibm.com/redbooks

You can also download additional materials (code samples or diskette/CD-ROM images) from that site.

IBM Redbooks collections Redbooks are also available on CD-ROMs. Click the CD-ROMs button on the Redbooks Web site for information about all the CD-ROMs offered, as well as updates and formats.

548

WebSphere Version 5.1 Web Services Handbook

Index A abbreviations 543 AbstractServlet 442 access point 105 acronyms 543 activity 160, 164, 166, 348 administrative console 480, 482 Agent Controller 522 alphaWorks 137, 167, 181, 524, 546 Apache Axis 20 Web site 44 SOAP 19 implementation 35 server 35 Apache eXtensible Interaction System see Axis 19 Application Assembly Tool 484 Application Developer import 539 Application Server Toolkit 484 Assembly Toolkit 484 ASTK 484 asynchroneous Web service 236 auditing 196, 198 authentication 94, 178–179, 191, 196, 198, 309 alias 529, 532 Application Developer 310 client 310 server 312 testing 314 authorization 94, 178, 196, 198, 337 availability 198 Axis 19–20, 40 client architecture 41 server architecture 41 subsystems 42

B B2B 100, 213 B2C 213 B2C Web application 13 B2E 213

© Copyright IBM Corp. 2003, 2004. All rights reserved.

basic authentication 190, 309 Bean2WebService 384, 388 binding HTTP 61 MIME 62 SOAP 60 stub 72 template 101, 104 UDDI 152 WSDL 57 WSIL 150 WS-Inspection 150 block activity 348 body 21, 26 SOAP 26 bottom-up Application Developer 248 development 223 Integration Edition 342 WSDK 394 BPEL 10, 159 Web site 168 BPEL4WS 165 concepts 165 BPWS4J Web site 168 breakpoint 374 broker 6 business 10 entity 101 publishing 296 information 12 integration 12 models 11 process 7, 10, 159–160, 166, 347 execution language 165 see BPEL externalization 12 Web client, 371 wizard 352 registry 107 relationships 102, 105 rule 7 service 101

549

Business Integration perspective 345 business-to-business 100, 213 business-to-consumer 12, 213 business-to-employee 213

C cell 481 certificate 195, 319, 498 certification agency 195 chain 41 channel 171, 173, 175 CICS 344 CICS Transaction Gateway 522 ClearCase LT 210 client application 441 programming model 79 Web service 264 Common Business Objects 219 Common Versions System 210 communication protocol 4 style 22, 28 compensation service 164 composable 11 compound type 30 confidentiality 94, 193, 196, 198, 326 client 327 server 331 configuration 333 testing 334 container 165 container-managed persistence 532 control link 161, 348, 369 CORBA 24 CrossWorlds 219 customer relationship management 213 CVS 210

data source configuration 488, 529, 531 DB2 Everyplace 215 Legacy CLI-base Type 2 JDBC Driver 496 Universal JDBC Driver Provider 488 XML Extender 249 DB2_JDBC_DRIVER_PATH 489 DB2DataStoreHelper 532 DB2UNIVERSAL_JDBC_DRIVER_PATH 489 DB2User 530, 532 DCOM 24 debugger 374 deployment 301 descriptor 82, 305 SOAP 32 enterprise application 484 manager 481 SOAP 36 description language 5 deserialization 31 deserializer 33, 35, 38 developerWorks 140, 546 Web site 44 digital signature 126 DII 73, 81 document access definition extension see DADX style SOAP 28 type definition 26 WSDL 47 DTD 26 dynamic binding 229 client 229 invocation interface 73, 81 proxy 73, 81 Web service 229 Web services 100, 131, 454

D DADX 248 file 292 group 290, 496 data link 162 model SOAP 28

550

E EAR export 301 e-business 11 Eclipse 208 WSDK plug-in 383, 416

WebSphere Version 5.1 Web Services Handbook

WSDK server 417 EJB authorization 337 client JAR 211 container programming model 88 EJB2WebService 384, 393, 410 electronic data interchange 4 e-marketplace UDDI 121 Emerging Technologies Toolkit 167, 382 encoding 22, 32 SOAP 32 encryption 186, 193 enterprise application deployment 301, 484 installation 473, 494 start/stop 486 information systems 342 security 197 services 342 Web services 77 entity promotion 125 envelope 21 SOAP 24 error handling 27 ETTK 382 installation 524 explorer 296 eXtensible Markup Language see XML extranet UDDI 122

F fault activity 348 code 27 element 26 handler 166 message 27 FDML 10, 159, 163 elements 164 example 368 filter 171, 173, 176 find_binding 118 find_business 116 find_service 117 find_tModel 118

FlashAndThunder 430 flow 355 definition markup language 163 model 161 flow definition markup language see FDML

G garbage collection 20 gateway 169–170 security 177 global security 191, 491

H handler 41, 93 header 25 SOAP 22 Host On Demand 344 HOSTS file 476, 494 hot method replace 210 HTTP 195 binding 61 extension framework 20 header 23 plug-in 495 server plug-in 486 HTTPS 195, 497 configuration 498

I ibm-webservices-bnd.xmi 305 ibm-webservicesclient-bnd.xmi 305 ibm-webservicesclient-ext.xmi 305 ibm-webservices-ext.xmi 305 ID assertion 309 identification 196, 198 IDL 47 IIOP 131, 206 ikeyman 498 import 539 WSDL 51 information center 208 set 64 installation ETTK 524 WebSphere Application Server 516

Index

551

WebSphere Studio Application Developer 520 WebSphere Studio Integration Edition 522 WSDK 523 InstallShield Multi Platform (ISMP) 517 integration 4 Integration Edition see WebSphere Studio Application Developer Integration Edition 341 Integrator Broker 218 integrity 94, 187, 191, 196, 198, 316 client 316 server 322 testing 324 interface definition language 47 International Weather Association 431 internationalization 107 interoperability 4, 15, 30, 282 interoperable 10 intranet 10 ItsoWebService1 251, 253 ItsoWebService1JavaClient 264 ItsoWebService1WebClient 253 ItsoWebService2 251, 271 ItsoWebService2RouterWeb 271 ItsoWebService3 251, 274 ItsoWebService3EJBRouter 274 ItsoWebService4 279 ItsoWebService5 285, 290 ItsoWebService6 308 ItsoWebService7 409 IWA 431 application 467

K key locator 318 keytool 319

J J2C 211 J2EE client 403 Connector Architecture see JCA role 85 security 94, 337 Web services 77 J2SE client 403 JAAS 310, 529 Java API for XML based Remote Procedure Call 67 APIs for WSDL 63 build path 267

552

Management Extensions 207 Messaging Service 47 SDK 1.4.1 208 security 492 snippet 164, 348, 369 snippets 362 JavaServer Faces 211 JAX-RPC 67, 382 client 69 deployment descriptor 82 mapping deployment descriptor 83 WSIF 135 JCA 131 adapters 344 Web services 131 JDBC provider 531 jdbc/sjweather 532 JDK 1.4.1 210 JMS 95, 132, 206, 212 provider 489 resources 489 JMX 207 JNDI 80 JSF 211 JSR 101 67, 210, 382–383 JSR 109 77, 210, 258, 382–383 security 94 JSR 110 63 Jython 208

L language-independent 10 LDAP 213 legacy systems 8, 13, 137, 215, 344 link 161, 348 Linux 205, 381, 383, 397 listener port 490 literal encoding 32 XML 32 loop activity 349 LTPA 309

WebSphere Version 5.1 Web Services Handbook

M managed client 74 process 480 mapping JAX-RPC 75 SOAP 33 marshalling 31 MDB 274 message oriented style 28 SOAP 21 WSDL 54 message-driven bean 274 message-oriented style 22 Microsoft SOAP Toolkit 20, 42 SOAP Microsoft 19 MIME binding 62 motivation 4 MQSeries see WebSphere MQ Workflow 219 mustUnderstand 25

N NAICS 102, 106 namespaces 24 SOAP 24 WSDL 52 WS-Inspection 145 Network Deployment 105, 123 node agent 481 non-repudiation 196, 198

O OASIS 100, 167, 188 operation 46 Oracle ERP 344

P palette 354 partner 166 PeopleSoft 344 plug-in 495 port 46

port type WSDL 55 private UDDI registry 120, 503 process breakpoint 376 business 160 debugger 374 editor 347 files 362 flow 355 interface 365 programming language 4, 15 model 78 EJB 88 Web 89 style 70 project server 529 protocol 196, 199 provider 132, 161 proxy 260 authentication 179 class 71 classes 263 secure 444 UDDI 115, 450 WSIF 135 public broker broker public 6 publisher assertions 102 publishing 104 Python 208

Q quality of service 130 queue connection factory 490 destination 490

R Redbooks Web site 548 Contact us xxviii registry UDDI 100 relationships 105

Index

553

remote procedure call 22 replication 107 request security handler 304 requirements 4 scenario 431 resource adapter 343 response security handler 305 RMI 20 role 85 RPC 22, 28, 35 style 60 rule engine 7

S SAAJ 138, 207 SAML Web site 200 save_business 120 SAX 40 scenario 429 build 438 client 441 deployment 439 enterprise applications 474 installation 473, 494 preferences 445 requirements 431 run 439, 477 sample 1 454 sample 2 461 server 475 setup 435 static client 471 scope 37 secure proxy 444 security 5, 185 enterprise 197 exposures 186 framework 199 gateway 177 global 191 role references 87 token 191, 309 generation architecture 309 tokens 304 transport channel 194 SEI 72, 80, 259 self-contained 10

554

self-describing 10 self-signed certificate 498 serialization 31 serializer 33, 35, 38 server configuration 333, 529, 532 decrypt 493 deployment descriptor 90 encrypt 493 programming model 86 project 529 security 494 service broker 5–6 compensation 164 endpoint interface 72, 79 implementation bean 87 interface 72, 79 locator 72 project 350 projection 105 provider 5–6 registry 6 requestor 5–6, 54, 64, 100, 103–104, 128, 170, 227, 386, 408, 431 WSDL 58 WSIL 148 WS-Inspection 148 service-oriented architecture 3, 19 concepts 5 session EJB 88 sg246891code.zip 526 Siebel 344 SiliconWeather 430 simple API for XML 40 Simple Object Access Protocol see SOAP SMTP 195 SOAP 8 1.1 specification 44 architecture 19 binding 60 body 21, 26 Call object 38 client API 38 communication style 28 data model 28, 30 deployment 36 deployment descriptor 32, 36

WebSphere Version 5.1 Web Services Handbook

encoding 22, 32 engine WebSphere 42 envelope 21 error handling 27 fault 26–27 fault response 306 header 22, 25 implementation 34 input message 270 intermediary 25 mapping 33 message 21, 24 authentication 189, 315 confidentiality 193, 334 encryption 193 integrity 192, 324 security 304 tracing 269 validation 283 Microsoft 20, 42 over HTTP 95 over JMS 95, 208, 236, 274 overview 20 response message 271 specification Web site 44 Toolkit 19–20 with Attachments API for Java 138 SOAP4J 35, 40 soapearenabler 487 SQL statement 290 SQLJ 210 SSL 178, 185, 195, 497, 499 staff activity 349 stand-alone client 264, 500 stateless session EJB 88 static stub 71, 80 Web service 100, 228 StringService 390 Struts 210 stub 136 stub-less 135 style 32 subscription API 127 supply chain management 213 SyncML standard 215

T taxonomy 5, 101 TCP/IP Monitor 269 view 270 monitoring 40 Monitoring Server 269 test registry 107–109, 295, 300, 405, 445, 455, 461 TestClient.jsp 262 Tivoli Access Manager 208 for Business Integration, 200 Tivoli Performance Viewer 479, 500 tModel 101 top-down Application Developer 249 development 223 Integration Edition 343 WSDK 388 topology 125 TPF 479, 500 transaction 186 transport channel security 187, 194, 497 listener 41 type mapping 83

U UBR 100 UDDI 8 API 114 binding 152 binding example 155 Business Registry 100, 107 client 115 cloud 120 data model 103 Explorer 295, 509 extranet 122 find 109 find binding 450 find business 448 find service 449 find tModel 450 find_binding 118 find_business 116 find_service 117 find_tModel 118

Index

555

GUI 503 IBM Web site 128 inquiry API 127 internationalization 107 introduction 99 library 115 lookup 454 lookup sample 446 policies 126 policy 126 pollution 121 private registry 120 proxy 115, 448, 450 publish 112 publishing 104 Application Developer 295 registry 147 installation 503 structure 101 replication 107 scenario 434 security 126 taxonomy 101 Test Registry 296 topology 125 Version 2 105 Version 3 124 Web front-end 109 Web site 128 UDDI4J 114, 230, 433, 439, 446, 448, 503 UDDIPublish 384, 403 UDDIUnpublish 384, 405 UML Visual Editor 210 unified resource name see URN UnitedSuns 431 universal description, discovery, and integration see UDDI universal resource identifier see URI universal test client 273 unmarshalling 31 unpublish 405 UNSPSC 102, 106 URI 24 URN 24, 38 UUID 110, 120

556

V view mapping 210 virtual host 494 Visual Editor 210 VisualAge for Java 208 VisualAge Generator 211

W W3C 20 WDO 211 Weather class 237 WEATHER database 235 weather forecast 233 WSDK 409 WeatherDataSource.jacl 409 WeatherForecast class 234, 238 WeatherForecast_mapping.xml 260 WeatherForecastEJB 234 WeatherForecastProxy 264 WeatherPredictor class 235, 244 Web container programming model 89 Web service from JavaBean 253 Web services authentication 309 build 222 client 227 client deployment descriptor 82 confidentiality 326 deployment 223, 479, 487 deployment descriptor 90, 305 development 221–222 EJB 271 enabling 487 enterprise 77 example 12 Explorer 256, 260, 295–296 WSDK 421 flow language 160 from DADX 290 from JavaBean WSDK 417 from session EJB WSDK 424 from SQL 290

WebSphere Version 5.1 Web Services Handbook

from URL 285 from WSDL 279 gateway 169–170 generate client 277 generated files 259 integrity 316 J2EE 78 JMS 274 management 223 object runtime facility 290 protocol stack 199 runtime 223, 479 scenario 429 scope 37 security 185, 303 bindings 321 language 188 model 196 security model 196 Toolkit 382 Web client 268 wizard 248, 253 WSDK 418 Web services description language see WSDL Web services flow language see WSFL Web Services Gateway see WSGW Web services inspection language see WSIL Web services invocation framework see WSIF webservices.xml 90, 259 webservicesclient.xml 82, 260 Website Builder 210 WebSphere administration 480 administrative console 482 Application Server 35, 205 Enterprise Edition 176, 206, 377 Express 206 installation 516 Network Deployment 105, 123, 206, 482 Business Connection 181 Web Services Gateway 183 Business Integration 218 certificates 319 Commerce 216

Business Edition 217 Professional Edition 217 Entry 217 Data Objects 211 Everyplace 214 Access 215 Embedded Edition 215 Server 215 Information Center 208 JMS Provider 489 MQ 212 Integrator Broker 218 JMS Provider 489 Portal Experience 214 Express 214 Extend 213 Portal Enable 213 Portal for Multiplatforms 213 product family 204 SOAP Engine 20, 42, 188 Studio 208 Application Developer 210, 247, 303 Integration Edition 211, 341, 522 Enterprise Developer 211 Site Developer 209 topology 480 Version 5.0.2 server 529 Voice Server 216 Workflow 139 WebSphere SDK for Web Services see WSDK WORF 290 runtime 496 test client 294 workflow 7, 159 workspace projects 527 WS-Authentication 197 WSDK 381 binding 57 build 408 client 403 documentation 385 generated files 391 installation 523 plug-in 416 samples 386

Index

557

server 384, 402 Eclipse 417 tools 384, 388 weather forecast 409 Web Service wizard 418 Web site 428 WS-Security 387 WSDL 8 API 62 binding 150 binding example 154 document 46–47 editor 346 files 51 introductory 45 message 54 operation 46, 55 port 46 port type 55 service 58 specification Web site 65 WS-I validation 283 WSDL to Java 389, 393 WSDL2Client 384, 399 WSDL2Java 389, 393 WSDL2WebService 384, 394 WSDL4J 62, 433 WS-Federation 196 WSFL 10, 159–160 concepts 160 example 162 specification Web site 168 WSGW 10, 139, 169 enhancements 182 security 177 WS-I 15, 250, 282, 382 Basic Profile 16 compliance preference 282 warning 256 SOAP message validation 283 validation tools 282 WSIF 9, 129, 171 API 132, 135 architecture 132 components 134 concepts 131

558

interaction 134 JAX-RPC 135 provider 132 proxy 135 SAAJ 138 stub 136 Web site 140 WSIFMessage 134 WSIFOperation 132 WSIFPort 133 WSIFProvider 132 WSIFService 132 WSIL 9, 141, 230, 435 binding 150 example 154 link link 149 lookup sample 461 scenario 434 see also WS-Inspection service 148 WSIL4J 156, 433 WS-Inspection 141 API 156 binding 150 definition 147 document 143 Java API 156 link 149 namespaces 145 overview 143 service 148 specification Web site 157 WS-Policy 197 WS-Privacy 197 WS-SecureConversation 196 WS-Security 94 authentication 189 confidentiality 193 extensions 195 integrity 191 see also Web services security specification 188 Web site 200 WSDK 387 ws-security.xml 306 WSTK 382 WS-Trust 197

WebSphere Version 5.1 Web Services Handbook

X X.509 309 XLANG 165, 168 XMethod 157 XMI 32 XML 8 digital signature 304 editor 346 encryption 304 Web site 200 Information Set 64 metadata interchange see XMI namespaces 24 Protocol Working Group 20 schema descriptor 22 signature Web site 200 XSD type 30

Index

559

560

WebSphere Version 5.1 Web Services Handbook

WebSphere Version 5.1 Application Developer 5.1.1 Web Services Handbook

Back cover

®

WebSphere Version 5.1 Application Developer 5.1.1 Web Services Handbook Web services overview and concepts Web services tools and development Web services runtime environment

This IBM Redbook describes the new concept of Web services from various perspectives. It presents the major building blocks Web services rely on. Here, well-defined standards and new concepts are presented and discussed. Whereas these concepts are described vendor-independent, this book also presents IBM’s view and illustrates with suitable demonstration applications how Web services can be implemented using IBM’s product portfolio, especially WebSphere Application Server Version 5.1 and WebSphere Studio Application Developer Version 5.1.1. This book is a major update to the IBM Redbook Web Services Wizardry with WebSphere Studio Application Developer, SG24-6292, and to WebSphere Version 5 Web Services Handbook, SG24-6891-00. This book is structured in two parts:
Part 1 presents the underlying concepts for the use of Web services: It presents the basic programming model, well-known concepts in an updated way, and new concepts that go beyond the scope of the earlier books.
Part 2 shows how Web services can be implemented using the latest IBM tools. Here we introduce a sample application that is demonstrated in various different ways.

SG24-6891-01

ISBN 0738498718

INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.

For more information: ibm.com/redbooks