sg246891 00

Front cover
WebSphere Version 5
Web Services Handbook
Web services overview and concepts
Web services tools and

development
Web services runtime

environment
Ueli Wahli
Matija Drobnic
Christian Gerber
Gustavo Garcia Ochoa
Michael Schramm
ibm.com/redbooks
International Technical Support Organization
WebSphere Version 5 Web Services Handbook
March 2003
SG24-6891-00
Note: Before using this information and the product it supports, read the information in
“Notices” on page xv.
First Edition (March 2003)
This edition applies to Version 5 of WebSphere Application Server, Version 5 of WebSphere

Studio Application Developer, Version 5 of WebSphere Studio Application Developer Integration
Edition, and Version 3.2.2 of the Web Services Toolkit.
© Copyright International Business Machines Corporation 2003. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
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
The concept of a service-oriented architecture . . . . . . . . . . . . . . . . . . . . . . . . . 5
Characteristics of the Web service architecture . . . . . . . . . . . . . . . . . . . . . . 6
Web services approach for a SOA architecture . . . . . . . . . . . . . . . . . . . . . . . . . 7
Other concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Properties of the service-oriented architecture . . . . . . . . . . . . . . . . . . . . . . . 9
Business models well supported by Web services. . . . . . . . . . . . . . . . . . . . . . 11
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 2. Introduction to SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
A deeper insight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
URN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
SOAP envelope. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Advanced topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Communication styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
SOAP implementation general architecture . . . . . . . . . . . . . . . . . . . . . . . . 30
IBM SOAP4J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Apache SOAP 2.3 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Microsoft SOAP Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
© Copyright IBM Corp. 2003. All rights reserved. iii

SOAP summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Chapter 3. Introduction to WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
WSDL document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
WSDL document anatomy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
WSDL definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Port types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Service definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Port definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
WSDL bindings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
SOAP binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
HTTP binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
MIME binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
WSDL API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Chapter 4. Introduction to UDDI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

UDDI overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Static versus dynamic Web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
UDDI registry structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Interactions with UDDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
UDDI support in WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . 67
Advanced features of UDDI Version 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Modeling features for complex business entities . . . . . . . . . . . . . . . . . . . . 67
More powerful categorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Enhanced inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Internationalization features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Peer-based replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
UDDI Business Registry on the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Web front ends for registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Finding information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Publishing information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Java API for dynamic UDDI interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
UDDI4J overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Writing UDDI clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
iv WebSphere Version 5 Web Services Handbook

Private UDDI registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Motivation for the use of private UDDI registries. . . . . . . . . . . . . . . . . . . . . 82
Possible scenarios for private UDDI registries . . . . . . . . . . . . . . . . . . . . . . 83
Benefits of private UDDI registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Additional considerations for private UDDI registries . . . . . . . . . . . . . . . . . 84
Private UDDI registry product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Future of UDDI Version 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Keys assigned by publisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Human-friendly URI-based keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Complex registry topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Advanced security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Data model updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Extended inquiry API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Subscription API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Registry management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Chapter 5. Web services invocation framework . . . . . . . . . . . . . . . . . . . . . 89

Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
General concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
WSIF architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Two invocation models using WSIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Sample scenarios for WSIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Current status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Integration into WebSphere products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Future versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Chapter 6. Web services inspection language . . . . . . . . . . . . . . . . . . . . . 101

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
WS-Inspection document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
WS-Inspection document anatomy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
WS-Inspection and UDDI relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
WS-Inspection definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
WS-Inspection bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
WSDL binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
UDDI binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Contents v
Inspection document publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
WSIL examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
WS-Inspection API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Chapter 7. Workflows and business processes . . . . . . . . . . . . . . . . . . . . 119

Web services flow language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Concepts and terms in WSFL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Sample WSFL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Flow definition markup language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Elements of FDML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
FDML sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Business process execution language for Web services . . . . . . . . . . . . . . . . 125
Concepts and terms in BPEL4WS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Business process execution language for Web services runtime . . . . . . . 127
Usage of BPEL4WS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Chapter 8. Web Services Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Motivation for a gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
General concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Managing your Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Administering the gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Managing channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Managing filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Working with UDDI references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Deploying Web services to the gateway . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Gateway-level authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Operation-level authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Implementation details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Chapter 9. Web services security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
General security requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Transport channel security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
XML-based Web services security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
vi WebSphere Version 5 Web Services Handbook

WS-Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Namespaces and terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
SOAP message securing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
WS-Security: an example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
WS-Security extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Web services security model proposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Part 2. Web services implementation and samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Chapter 10. IBM WebSphere product family . . . . . . . . . . . . . . . . . . . . . . . 159

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
WebSphere foundations and tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
WebSphere Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
WebSphere reach and user experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
WebSphere Portal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
WebSphere Everyplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
WebSphere Commerce. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
WebSphere Business Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
WebSphere MQ Integrator Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
WebSphere Business Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Chapter 11. Web services development overview . . . . . . . . . . . . . . . . . . 175

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Web services development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Build phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Deployment phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Run phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Management phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Paths for creating a new Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Bottom-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Top-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Multiple services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Types of Web services implementation . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Paths for creating a new Web services client. . . . . . . . . . . . . . . . . . . . . . . . . 181
Static client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Dynamic client with known service type . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Dynamic client with unknown service type . . . . . . . . . . . . . . . . . . . . . . . . 184
Contents vii
Types of client implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Chapter 12. Weather forecast application . . . . . . . . . . . . . . . . . . . . . . . . . 187

Weather forecast application components . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Business module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Data module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Back-end module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Information flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Base code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Weather class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Weather forecast class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Weather predictor class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Chapter 13. WebSphere Studio Application Developer . . . . . . . . . . . . . . 197

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Strategies for developing a Web service. . . . . . . . . . . . . . . . . . . . . . . . . . 198
Tool support by WebSphere Studio Application Developer . . . . . . . . . . . 198
Selected scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Creating a Web service from a JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Importing the WAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Test the weather forecast application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Creating the Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Generated files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Testing the Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Writing a client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Tracing SOAP messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Using the TCP/IP Monitoring server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
TCP/IP Monitor view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Target URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Creating a Web service top-down from WSDL. . . . . . . . . . . . . . . . . . . . . . . . 224
Create a Web project and import the WSDL . . . . . . . . . . . . . . . . . . . . . . . 224
Create the skeleton JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Generated files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Implementing the JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Testing the service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Creating a Web service from a URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Creating the servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Running the servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Creating the URL Web service for the servlet . . . . . . . . . . . . . . . . . . . . . . 228
Testing the URL Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
viii WebSphere Version 5 Web Services Handbook

Creating a Web service from DADX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
DADX group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Creating a Web service from DADX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Publishing and exploring a UDDI registry. . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Publishing a business entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Discovering business entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Publishing the weather forecast Web service . . . . . . . . . . . . . . . . . . . . . . 235
Discovering the weather forecast Web service . . . . . . . . . . . . . . . . . . . . . 237
Deployment of the sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Exporting the EAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Installing the enterprise application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Chapter 14. Application Developer Integration Edition . . . . . . . . . . . . . . 241

Enterprise services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Creating an enterprise service: bottom-up . . . . . . . . . . . . . . . . . . . . . . . . 242
Creating an enterprise service: top-down . . . . . . . . . . . . . . . . . . . . . . . . . 243
Resource adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Using Application Developer Integration Edition . . . . . . . . . . . . . . . . . . . . . . 244
Business Integration perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Services view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Enhanced WSDL editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Business process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Sample business process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Prepare existing services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Create a service project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Import existing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Setup WSDL files of existing services. . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Create the business process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Adding services to the process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Adding flow to the process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Messages and variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Process files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Adding Java snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Defining the process interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Generate deploy code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Flow definition markup language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Testing a business process in the test environment . . . . . . . . . . . . . . . . . . . 270
Business process Web client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Configuring a remote WebSphere Application Server . . . . . . . . . . . . . . . 273
Debugging business processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Contents ix
Setting breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Start debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Process debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Using the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Deployment to an application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Importing the process solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Importing the projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Defining the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Test the process sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Chapter 15. WebSphere SDK for Web Services . . . . . . . . . . . . . . . . . . . . 281

What is the difference between the packages? . . . . . . . . . . . . . . . . . . . . . . . 282
WebSphere SDK for Web Services Version 5 . . . . . . . . . . . . . . . . . . . . . . . . 282
Application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
WS-Security in WSDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Using the tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Bean2WebService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
EJB2WebService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
WSDL2WebService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
UDDIPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
UDDIUnpublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Sample 1—JavaBean request/response Web service . . . . . . . . . . . . . . . . . . 292
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Rebuilding sample 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Implementing the weather forecast Web service . . . . . . . . . . . . . . . . . . . . . . 294
Running the Bean2WebService tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Starting the Web service in the application server . . . . . . . . . . . . . . . . . . 296
Creating and running a stand-alone client . . . . . . . . . . . . . . . . . . . . . . . . 297
Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Chapter 16. Web Services Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
WSTK general concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
WSTK prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
IBM WebSphere SDK for Web Services (WSDK) . . . . . . . . . . . . . . . . . . . 303
WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
x WebSphere Version 5 Web Services Handbook

Jakarta Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Web Services Toolkit installation and configuration . . . . . . . . . . . . . . . . . . . . 304
Web Services Toolkit installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Web Services Toolkit configuration tool . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Uninstalling the Web Services Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Current status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Chapter 17. WebSphere Web Services Technology Preview. . . . . . . . . . 317

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
JAX-RPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Web services for J2EE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Technology preview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Web services creation using the technology preview. . . . . . . . . . . . . . . . . . . 320
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Web service from JavaBean (bottom-up) . . . . . . . . . . . . . . . . . . . . . . . . . 321
Web service from EJB (bottom-up) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Web service from EJB (top-down) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Web service from JavaBean (top-down) . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Deployment of applications to WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Using the command-line tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Using the administrative console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Start the enterprise applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Client creation using the technology preview . . . . . . . . . . . . . . . . . . . . . . . . . 344
Stand-alone client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Stand-alone client simplified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Chapter 18. Web services scenario: architecture and implementation . 353

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Scenario situation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Functional requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Non-functional requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Incorporating Web services concepts and technologies . . . . . . . . . . . . . . 357
Process to create the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Two types of service invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Contents xi
Setup phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Build phase of the client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Deployment phase of the client application. . . . . . . . . . . . . . . . . . . . . . . . 363
Run phase of the client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
General concepts of the client application . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Application flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Abstract servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Secure proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Invocation result JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
UDDI lookup sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Sample 1: dynamic invocation using UDDI lookup . . . . . . . . . . . . . . . . . . 383
Sample 2: dynamic invocation using WSIL lookup . . . . . . . . . . . . . . . . . . 389
Installing the application in Application Developer . . . . . . . . . . . . . . . . . . . . . 395
Configure the HOSTS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Import two enterprise applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Server project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Configuring a server for testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Run the samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Deployment to WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . 398
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Chapter 19. Web services runtime and deployment in WebSphere . . . . 401

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
WebSphere Application Server general concepts . . . . . . . . . . . . . . . . . . . . . 402
Administration basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
WebSphere topology building blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Administrative console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Enterprise application deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Installing an enterprise application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Starting and stopping enterprise applications . . . . . . . . . . . . . . . . . . . . . . 408
Regenerate the HTTP server plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Web services deployment in WebSphere environment . . . . . . . . . . . . . . . . . 409
Web services enabling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Web services administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Installing the scenario application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Configuring for HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Configure the HOSTS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Setting up the WebSphere server for the scenario sample. . . . . . . . . . . . 413
Run the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Installing the technology preview applications . . . . . . . . . . . . . . . . . . . . . . . . 414
Accessing a Web service from a stand-alone Java client . . . . . . . . . . . . . . . 414
xii WebSphere Version 5 Web Services Handbook

Implementing a private UDDI registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Install the UDDI registry on an application server . . . . . . . . . . . . . . . . . . . 416
Using the UDDI registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Using the UDDI GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Using the UDDI Explorer with the private UDDI registry . . . . . . . . . . . . . . 421
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Appendix A. Installation and setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

Installation planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Installing IBM WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . 429
Installation process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Verifying the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Installing IBM WebSphere Application Server Network Deployment . . . . 431
Installation of WebSphere Studio Application Developer . . . . . . . . . . . . . . . . 431
Installation of Application Developer Integration Edition . . . . . . . . . . . . . . . . 432
CICS Transaction Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Agent Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Installation of the WebSphere SDK for Web Services . . . . . . . . . . . . . . . . . . 433
Installation of the Web Services Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Installation of the Web Services Technology Preview . . . . . . . . . . . . . . . . . . 434
Appendix B. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437

Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
System requirements for downloading the Web material . . . . . . . . . . . . . 438
How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Related publications . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 441

IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 441
Other resources . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 442
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 442
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 444
IBM Redbooks collections . . . . . . . . . . . . . . . . . ...... ....... ...... . 444
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Contents xiii
xiv WebSphere Version 5 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. All rights reserved. xv

Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
AIX® IBM eServer™ S/390®

alphaWorks® IBM® SAA®
CICS® IMS™ Sametime®
Cloudscape™ Informix® SecureWay®
DB2 Universal Database™ Lotus® SP2®
DB2® MQSeries® Tivoli®
developerWorks™ OS/390® VisualAge®
Domino™ Redbooks (logo)™ WebSphere®
Everyplace™ Redbooks™ z/OS™
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.
xvi WebSphere Version 5 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 vendor-independent, the 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 and WebSphere Studio Application
Developer Version 5.
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 one year has passed that has 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 basics in an updated way,
and new concepts that go beyond the scope of the 2002 book.
򐂰 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.
© Copyright IBM Corp. 2003. All rights reserved. xvii

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, San Jose Center.
Ueli Wahli is a Consultant IT Specialist at the IBM International Technical

Support Organization in San Jose, California. Before joining the ITSO 18 years
ago, Ueli worked in technical support at IBM Switzerland. He writes extensively
and teaches IBM classes worldwide on application development, object
technology, VisualAge for Java, WebSphere Application Server, and lately
WebSphere Studio products. In his ITSO career, Ueli has produced over 25
Redbooks. Ueli holds a degree in Mathematics from the Swiss Federal Institute
of Technology.
Matija Drobnic is as an Advisory IT Specialist at IBM Global Services in

Ljubljana, Slovenia. He has been with IBM for more than four years. He started
as a technical sales support for WebSphere and VisualAge families of the
products, was an instructor for a year, and currently he is a member of a
WebSphere EMEA Back Office team. He is a certified WebSphere administrator.
xviii WebSphere Version 5 Web Services Handbook

Before joining IBM, Matija worked as a researcher at Jozef Stefan Institute in
Ljubljana, Slovenia, department of Artificial Intelligence, where his main field of
research was multistrategy learning and equation discovery. He holds a
Bachelor’s degree in Mathematical Physics as well as a Master’s degree and a
Ph.D. degree in Computer Science from the University of Ljubljana, Slovenia.
Christian Gerber is an IT Consultant at IBM Global Services in Munich,

Germany. He has been with IBM for three years, mainly working on the
specification and architecture of e-business solutions. He is certified as a
consultant in the Technical Integration competency. Before joining IBM, Christian
worked as a researcher at the German Research Center for Artificial Intelligence,
where he focused on distributed problem solving and negotiation strategies in
multi-agent systems. He holds a Master’s degree and a Ph.D. degree in
Computer Science from the Universität des Saarlandes, Saarbrücken, Germany.
Gustavo Garcia Ochoa is an IT Specialist at the IBM Center for e-business

Innovation in Madrid, Spain. He has been with IBM for three 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 the 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.
Michael Schramm is a Consulting IT Specialist at IBM Global Services in

Austria. He has eight years of experience in Java software development at IBM.
He worked in the Vienna Software Laboratory and in APDC for the first four
years. The last four years he spent as technical project leader and senior
developer in customer Web- and enterprise application development projects. He
also teaches classes for IBM Learning Services on application development
using WebSphere Studio Application Developer. He holds a Master’s degree in
Computer Science from Vienna University of Technology.
Thanks to the following people for their contributions to this project:

򐂰 Martin Keen is an Advisory IT Specialist in IBM UK and works for IBM
Learning Services in Hursley, UK.
򐂰 Eric Erpenbach of WebSphere Technology and Training, Rochester, is the
team lead of skill transfer education for WebSphere Studio Application
Developer Integration Edition.
򐂰 Olaf Zimmermann, a Consulting IT Architect in IBM Germany, Heidelberg,
provided the basis for the introductory chapters on SOAP, WSDL, and UDDI,
and reviewed the book in detail.
򐂰 Nirmal K. Mukhi, IBM T J Watson Research Lab.
Preface xix
򐂰 Anton (Tony) Fricko is a member of IBM's jStart team and is responsible for
assisting customers and Business Partners with the introduction of emerging
technologies in Europe.
򐂰 Bertrand Portier 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
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:
redbook@us.ibm.com
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HZ8 Building 80-E2
650 Harry Road
San Jose, California 95120-6099
xx WebSphere Version 5 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. All rights reserved. 1

2 WebSphere Version 5 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

Motivation for a services-oriented architecture
Although the rush of the dot-com era seems to have faded, there has been a
strong trend in recent years for companies to more and more integrate existing
systems in order to implement IT support for business processes that cover the
entire business value chain. 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 overarching 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.
򐂰 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.
The 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 15 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.
Legacy
system
2
1
Service Service
Requestor Internet Provider
3
Service
Broker
Figure 1-1 Web services roles and operations
Chapter 1. Web services introduction 5

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, 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.
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 (see for example WSIF in “Web
services invocation framework” on page 89).
򐂰 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.
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 (formerly referred to as Simple Object Access Protocol, or
Service-Oriented Architecture Protocol—in fact, similarly to JDBC, it is no
longer an acronym) is a network, transport, and programming
language-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.
XSD XML WSDL
Metadata/vocabulary Service description
UDDI
(Broker)
HTTP
Runtime
transports
SOAP other
Requestor Provider
SOA Runtime
J2EE other
Implementation
Figure 1-2 Main building blocks in an SOA approach based on Web services
򐂰 All elements use XML including XML namespaces and XML schemas.
򐂰 Service requestor and provider communicate with each other.
򐂰 WSDL is one alternative to make service interfaces and implementations
available in the UDDI registry.
򐂰 WSDL is the base for SOAP server deployment and SOAP client generation.

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.
򐂰 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 tool 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
redbook, 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.
򐂰 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 need to know the interfaces to Web services but do
not need 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.
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.
Image
renderer Intranet
Car con- Storing

figurator component
1 Dealer
locator
2
Client B2C Web
Application Production
system
3
Credit
history Banking ... Banking
checker system 1 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 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
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 to 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 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
submits the relevant customer data to the according 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.
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.
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/
http://xml.watson.ibm.com/
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

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 Apache eXtensible
Interaction System (Axis).
We also briefly touch upon other SOAP implementations, such as the Microsoft
SOAP Toolkit. Finally, we outline recent development and future trends in this
field.

Overview
Simple Object Access Protocol (SOAP) is a specification for 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: 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.
SOAP does not cover distributed garbage collection. SOAP clients also 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, another Java
implementation. There are other Java implementations as well as non-Java
implementations, such as Microsoft SOAP Toolkit, which we only briefly touch
upon.

A deeper insight
The SOAP standard specifies three aspects of XML-based message exchange.
Overall message format

򐂰 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.
Encoding rules
򐂰 Encoding rules 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 is not a part of a SOAP standard.
򐂰 The usage of this convention is optional. If the RPC 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-1 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/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.
Chapter 2. Introduction to SOAP 19

򐂰 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.
POST /servlet/rpcrouter HTTP/1.1

Host: www.messages.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: ""
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
<SOAP-ENV:Body>
<ns1:getMessage xmlns:ns1="urn:NextMessage"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<UserID xsi:type="xsd:string">JDoe</UserID>
<Password xsi:type="xsd:string">0JDOE0</Password>
</ns1:getMessage>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Figure 2-1 A SOAP message embedded in HTTP request
Figure 2-2 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
<SOAP-ENV:Envelope>
<SOAP-ENV:Body>
<return xsi:type="xsd:string">Call mom!</return>
</ns1:getMessage>
</SOAP-ENV:Body>
Figure 2-2 A SOAP message embedded in 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.
Namespaces
SOAP defines the 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 can be http://www.messages.com/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:
<SOAP-ENV:Envelope .... >
<SOAP-ENV:Header name="nmtoken">
<SOAP-ENV:HeaderEntry.... />
</SOAP-ENV:Header>
<SOAP-ENV:Body name="nmtoken">
[message payload]
</SOAP-ENV:Body>

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-1 on page 20 and Figure 2-2 on
page 20). 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:
<thens:qos xmlns:thens="someURI" SOAP-ENV:mustUnderstand="1">
1
</thens:qos>
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) level 1
(whatever qos=1 stands for in the actual invocation 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. The second 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).

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.
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.
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 is returned if the service

implementation throws a SOAPException. The exception text is transmitted in the
Faultstring field.
Advanced topics
In the following section, we discuss some more advanced SOAP concepts, such
as the different communication styles, 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 but not yet frequently
used communication style.
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. The main focus of this redbook is on the RPC
style.

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-3 shows the interactions between the client and server as well as the
server-side processing of a service invocation in RPC communication.
SOAP Client SOAP Server

Deployment
Descriptors
Call 2
ServiceManager
- target object
- encoding style
5
- method name
- parameters RPC Router Servlet
- transport SOAP
Message
- invoke() 1
3 PluggableProvider
4 SOAP Service
1. Send SOAP RPC Request Java Class

2. Lookup deployment descriptor Script
3. Pass request to provider EJB
4. Invoke service COM Application
5. Return response other
Figure 2-3 SOAP client and server interaction

Web service invocation using RPC involves the following steps:
1. A SOAP client generates 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.
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-1 on page 20 is
modeled as a struct containing an accessor for each in and in/out parameter. It
is shown in Figure 2-4.
</ns1:getMessage>
Figure 2-4 A SOAP request message
In the example in Figure 2-4, 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 namespaces
http://www.w3.org/2001/XMLSchema and
http://www.w3.org/2001/XMLSchema-instance respectively.
In the example shown in Figure 2-5, the argument is an array whose values are
structs.
<ns1:getSubscribers xmlns:ns1="urn:SubscriberList"
<SOAP-ENC:Array SOAP-ENC:arrayType="xxx:Subscribers[2]">
<Subscribers>
</Subscribers>
<Subscribers>
<UserID xsi:type="xsd:string">MDoe</UserID>
<Password xsi:type="xsd:string">0JMDOE0</Password>
</Subscribers>
</SOAP-ENC:Array>
</ns1:getSubscribers>
Figure 2-5 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:
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 particular Web service, we have to choose one of the tools
and programming or scripting languages that support 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.
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 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
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.

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 <built-in>/StringDeserializer
boolean xsd:boolean <built-in>/BooleanDeserializer
Boolean xsd:boolean <built-in>/BooleanObjectDeserializer
double xsd:double <built-in>/DoubleDeserializer
Double xsd:double <built-in>/DoubleObjectDeserializer
long xsd:long <built-in>/LongDeserializer
Long xsd:long <built-in>/LongObjectDeserializer
float xsd:float <built-in>/FloatDeserializer
Float xsd:float <built-in>/FloatObjectDeserializer
int xsd:int <built-in>/IntDeserializer
Integer xsd:int <built-in>/IntObjectDeserializer
short xsd:short <built-in>/ShortDeserializer
Short xsd:short <built-in>/ShortObjectDeserializer
byte xsd:byte <built-in>/ByteDeserializer
Byte xsd:byte <built-in>/ByteObjectDeserializer
BigDecimal xsd:decimal <built-in>/DecimalDeserializer
GregorianCalendar xsd:timeInstant CalendarSerializer
Date xsd:date DateSerializer
QName xsd:QName QNameSerializer

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 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-6 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 Service Provider
SOAP RPC Layer SOAP Server

Client Proxy
Pluggable Service
Mapping Providers Manager
Registry
Call
Para- Mapping
meter Deployment
Registry
Descriptor
SOAP Message Layer

RPC Message
Router Router
Servlet Servlet
SOAP Transport Layer
Transport Layer
(HTTP, HTTPS, SMTP, JMS, MQ, other)
Figure 2-6 High-level SOAP component model

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 SOAP server and then the SOAP client API.
SOAP server
Apache SOAP 2.3, which comes with 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-7 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 details about the configuration manager, and the administrative
GUI here. Refer to the Apache SOAP user documentation for more information.

SOAP4J ==> Type
Open Source Mapping
Registry Pluggable
Providers
(JavaBean, EJB,
BSF, COM, custom)
Transport
Listener SOAP
(rpcrouter and
messagerouter
Server
servlets for HTTP) Engine Service
Implementation
any type of
programming
SOAP Admin artifact
Pluggable
GUI
Configuration
(HTML Manager
based)
Web Service
Deployment
Descriptor
DeployedServices.ds
Figure 2-7 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-8.

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-8 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-9.
<root>
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
id="urn:NextMessage" checkMustUnderstands="1">
<isd:provider type="java" scope="Request" methods="getMessage">
<isd:java class="NextMessage" static="false"/>
</isd:provider>
</isd:service>
</root>
Figure 2-9 Web service deployment descriptor
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.

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-10). The message that travels if this
code is executed is the same message we inspected in Figure 2-1 on page 20.
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.

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-10 SOAP 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.

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.0 is available, and Version 1.1 is in beta.
Beside 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 generates 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.

Axis server architecture
The basic architecture of Axis in the server is shown in Figure 2-11.
Figure 2-11 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.

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-12 shows the layering of subsystems. The lower layers are independent
of the higher layers. The stacked boxes represent mutually independent,
although not necessary mutually exclusive, alternatives. For example, the HTTP,
SMTP, and JMS transports are independent of each other but may be used
together.
MDB SMTP
XML-RPC EJB JMS
deployment Java
SOAP HTTP
descriptor RPC
message
admin service provider transport encoding
model
message flow: handler, chain, message context, fault WSDL

AXIS ENGINE tools
Figure 2-12 Axis subsystems
Implementations
Axis 1.0 is implemented in the Web Services Toolkit (see Chapter 16, “Web
Services Toolkit” on page 301) and in the WebSphere Web Services Technology
Preview (see Chapter 17, “WebSphere Web Services Technology Preview” on
page 317).
We implement our sample application using the Axis tool provided with the
WebSphere SDK for Web Services and the WebSphere Web Services
Technology Preview.
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.

SOAP 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 W3C SOAP
specification. Its current version is V1.1 with V1.2 in preparation.
There are several SOAP implementations available at the moment. Apache

SOAP V2.X 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. 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. 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.
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 V1.0 was officially released. Among others, it
implements most of the SOAP 1.2 specification.

More information
The SOAP 1.1 specification can be downloaded from:
http://www.w3.org/TR/SOAP
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/
For information on Microsoft SOAP Toolkit, check out the user and API
documentation as well as the FAQ list at:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsoap/htm
l/soap_faq.asp?frame=true

3
Chapter 3. Introduction to WSDL

This chapter provides an introductory view to Web services description language
(WSDL) 1.1. WSDL specifies the characteristic 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 59.

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 reference to locate the different files of the WSDL document. We
recommend this split to maintain a clearer service definition based on their level
of abstraction.
WSDL document
The WSDL document contains the following top-level 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. Each operation defines an input and an output
message as well as an optional fault message.
Operation An abstract description of an action supported by the service.
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.
Port A single endpoint, which is defined as an aggregation of a
binding and a network address.
Service A collection of related ports.
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 IDL,
which has language bindings.
WSDL document anatomy

Figure 3-1 on page 43 shows the elements comprising a WSDL document as
well as the various relationships between them.
1 n 1 n 1 1
WSDL Protocol
Service Port
Document Extensions
1 n
style/transport
1 Protocol
1 Extensions 1 Protocol action
1 style
Binding Extensions
n 1 Operation 1
n Binding
n 1
Message encoding
n 1..3 Binding
1 1
1 n
Port Type Operation
n
n Type
1..3
1 n
Binding
Message Part
n
0..1 n Instance
n
Type XML
n
1 contains
n XML 1 n
XSD Type points to
Schema
Figure 3-1 WSDL elements and relationships
Chapter 3. Introduction to WSDL 43

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.
The containment relationships shown in the diagram directly map to the XML
schema for WSDL.
In practice a WSDL document can be split into multiples documents using the
import element (see “Physical files” on page 46).
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 on page 43 while examining
the example.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="http://address.jaxrpc.samples"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:apachesoap="http://xml.apache.org/xml-soap"
xmlns:impl="http://address.jaxrpc.samples"
xmlns:intf="http://address.jaxrpc.samples"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<wsdl:types>
<schema targetNamespace="http://address.jaxrpc.samples"
xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
<complexType name="AddressBean">
<sequence>
<element name="street" nillable="true" type="xsd:string"/>
<element name="zipcode" type="xsd:int"/>
</sequence>
</complexType>
<element name="AddressBean" nillable="true" type="impl:AddressBean"/>
</schema>
<schema targetNamespace="http://www.w3.org/2001/XMLSchema"
<element name="int" type="xsd:int"/>
<element name="string" type="xsd:string"/>
</schema>
</wsdl:types>
<wsdl:message name="updateAddressRequest">
<wsdl:part name="in0" type="intf:AddressBean"/>
<wsdl:part name="in1" type="xsd:int"/>
</wsdl:message>
<wsdl:message name="updateAddressResponse">
<wsdl:part name="return" type="xsd:string"/>
</wsdl:message>
<wsdl:portType name="AddressService">
<wsdl:operation name="updateAddress" parameterOrder="in0 in1">
<wsdl:input message="intf:updateAddressRequest"
name="updateAddressRequest"/>
<wsdl:output message="intf:updateAddressResponse"
name="updateAddressResponse"/>
</wsdl:operation>
</wsdl:portType>
Figure 3-2 WSDL simple example: part 1

<wsdl:binding name="AddressSoapBinding" type="intf:AddressService">
<wsdlsoap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="updateAddress">
<wsdlsoap:operation soapAction=""/>
<wsdl:input name="updateAddressRequest">
<wsdlsoap:body
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://address.jaxrpc.samples" use="encoded"/>
</wsdl:input>
<wsdl:output name="updateAddressResponse">
<wsdlsoap:body
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="AddressServiceService">
<wsdl:port binding="intf:AddressSoapBinding" name="Address">
<wsdlsoap:address
location="http://localhost:8080/axis/services/Address"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
Figure 3-3 WSDL simple example: part 2
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.
Figure 3-4 shows the same Web service described in one, two, or three files.
򐂰 One file, typically used in Axis
򐂰 Two files, typically used in Application Developer Version 4
򐂰 Three files, typically used in Application Developer Version 5
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.

.
WSDL
types
message
One file
portType
binding
services
port
WSDL document
Two files
Service Service
Implementation Interface
import types
service message
port portType
Three files
binding
WSDL document
Service binding Interface

Implementation file file
import import types

service binding message
port portType
WSDL document
Figure 3-4 WSDL document structure as one, two, or three files

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

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 namespace as

encoding/ defined by SOAP 1.1
soapenv http://schemas.xmlsoap.org/soap/ Envelope namespace as

envelope/ defined by SOAP 1.1
xsi http://www.w3.org/2000/10/ Instance namespace as

XMLSchema-instance defined by XSD
xsd http://www.w3.org/2000/10/ Schema namespace as

XMLSchema 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.
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:
<definitions .... >
<types>
<xsd:schema .... />(0 or more)
</types>
</definitions>
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).
<wsdl:types>
<schema targetNamespace="http://address.jaxrpc.samples"
<complexType name="AddressBean">
<sequence>
<element name="street" nillable="true" type="xsd:string"/>
<element name="zipcode" type="xsd:int"/>
</sequence>
</complexType>
<element name="AddressBean" nillable="true" type="impl:AddressBean"/>
</schema>
<schema targetNamespace="http://www.w3.org/2001/XMLSchema"
<element name="int" type="xsd:int"/>
<element name="string" type="xsd:string"/>
</schema>
</wsdl:types>
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:
<definitions .... >
<message name="nmtoken"> (0 or more)
<part name="nmtoken" element="qname"(0 or 1) type="qname" (0 or 1)/>
(0 or more)
</message>
</definitions>
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
updateAddressRequest is composed of an AddressBean part and an int part. The
response message updateAddressResponse is composed of a string part.
<wsdl:message name="updateAddressRequest">
<wsdl:part name="in0" type="intf:AddressBean"/>
<wsdl:part name="in1" type="xsd:int"/>
</wsdl:message>
<wsdl:message name="updateAddressResponse">
<wsdl:part name="return" type="xsd:string"/>
</wsdl:message>
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:
<wsdl:definitions .... >
<wsdl:portType name="nmtoken">
<wsdl:operation name="nmtoken" .... /> (0 or more)
</wsdl:portType>
</wsdl:definitions>

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.
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:
<wsdl:portType .... > (0 or more)
<wsdl:operation name="nmtoken" parameterOrder="nmtokens">
<wsdl:input name="nmtoken"(0 or 1) message="qname"/> (0 or 1)
<wsdl:output name="nmtoken"(0 or 1) message="qname"/> (0 or 1)
<wsdl:fault name="nmtoken" message="qname"/> (0 or more)
</wsdl:operation>
</wsdl:portType >
</wsdl:definitions>
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, or
򐂰 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 services provides to its possible
clients, with the input message, updateAddressRequest, and the output message,
updateAddressResponse, that are used in the transaction.

<wsdl:portType name="AddressService">
<wsdl:operation name="updateAddress" parameterOrder="in0 in1">
<wsdl:input message="intf:updateAddressRequest"
name="updateAddressRequest"/>
<wsdl:output message="intf:updateAddressResponse"
name="updateAddressResponse"/>
</wsdl:operation>
</wsdl:portType>
Figure 3-7 Port type and operation definition in our WSDL document example
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:
<wsdl:binding name="nmtoken" type="qname"> (0 or more)
<-- extensibility element (1) --> (0 or more)
<wsdl:operation name="nmtoken"> (0 or more)
<wsdl:input name="nmtoken"(0 or 1) > (0 or 1)
<-- extensibility element (3) -->
</wsdl:input>
<wsdl:output name="nmtoken"(0 or 1) > (0 or 1)
</wsdl:output>
<wsdl:fault name="nmtoken"> (0 or more)
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
</wsdl:definitions>
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 54.
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, and define both to be SOAP encoded.
<wsdl:binding name="AddressSoapBinding" type="intf:AddressService">

<wsdlsoap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="updateAddress">
<wsdlsoap:operation soapAction=""/>
<wsdl:input name="updateAddressRequest">
<wsdlsoap:body
</wsdl:input>
<wsdl:output name="updateAddressResponse">
<wsdlsoap:body
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
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:
<wsdl:service name="nmtoken"> (0 or more)
<wsdl:port .... /> (0 or more)
</wsdl:service>
</wsdl:definitions>
Multiple service definitions can appear in a single WSDL document.

Port definition
A port definition describes an individual endpoint by specifying a single address
for a binding:
<wsdl:service .... > (0 or more)
<wsdl:port name="nmtoken" binding="qname"> (0 or more)
<-- extensibility element (1) -->
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
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
http://localhost:8080/axis/services/Address.
<wsdl:service name="AddressServiceService">
<wsdl:port binding="intf:AddressSoapBinding" name="Address">
<wsdlsoap:address
location="http://localhost:8080/axis/services/Address"/>
</wsdl:port>
</wsdl:service>
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.

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
<soap:binding ...> Binding level, specifies defaults for all operations
transport="uri" Binding level, transport is the runtime transport

(0 or 1) protocol used by SOAP (HTTP, SMTP, ...)
style="rpc|document" The style is one of the two SOAP communication

(0 or 1) styles, rpc or document
<soap:operation ... > Extends operation definition
soapAction="uri" URN
(0 or 1)
style="rpc|document" See binding level

(0 or 1)
<soap:body ... > 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= List of supported message encoding styles

"uri-list"(0 or 1)
namespace="uri" URN of the service

(0 or 1)
<soap:fault ... > Extends operation definition, contents of fault

details element

Extension and attributes Explanation
name="nmtoken" Relates soap:fault to wsdl:fault for operation
use, encodingStyle, See soap:body

namespace
<soap:address ... > Extends port definition
location="uri" Network address of RPC router
<soap:header ... > Operation level, shaped after <soap:body ...>
<soap:headerfault ... > Operation level, shaped after <soap:body ...>
For an example of extensibility elements, refer to Figure 3-8 on page 53.
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
<http:address Extends the port definition and contains the base URL
location="uri"/>
<http:binding The HTTP operation to be performed (nmtoken=GET or

verb="nmtoken"/> POST)

Extension Explanation
<http:operation Extends the operation binding and specifies the relative

location="uri"/> URL
<http:urlEncoded/> Message parts are encoded into the HTTP request URI
using the standard URI-encoding rules
<http:urlReplacement/> 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
<mime:content Name and MIME type of WSDL message

part="nmtoken"? type="string"?/> part
<mime:multipartRelated> Describes each part of a multipart/related

message
<soap:body> Same as in SOAP binding
<mime:mimeXml part="nmtoken"?/> 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 (and also
pointed to from the Axis Web site):
http://www.ibm.com/developerworks/projects/wsdl4j/

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. This code is used in Chapter 17, “WebSphere Web Services
Technology Preview” on page 317 for the Web services client development.
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

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.
Basic tool support for WSDL is already available, as covered in Part 2, “Web
services implementation and samples” on page 157.
An example of a recent innovation in this 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 5, “Web services invocation framework” on page 89.
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 157.
More information
As of today, few WSDL tutorials or other supporting information are available. As
WSDL becomes more widespread, this will change.
The best sources for more information are the IBM Web Services Toolkit (WSTK)
and the WSDL 1.1 specification. WSDL 1.1 is contained in the IBM WSTK 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

4
Chapter 4. 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 an preview of Version 3.
Version 2 is implemented by WebSphere Version 5 tools and the major UDDI

registries currently in production.
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

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 by several sites 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 their business and the services they offer 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 directory,
or—more often—directly sent to the client application developer by the provider

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 out 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 4. Introduction to UDDI 63

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.
򐂰 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 4-1 displays this data model with the entities introduced above. It also
shows their relationships and the link to the WSDL documents.
Business Publisher contains

Entity Assertions
1 points to
n
Business Taxonomy
Service (Categorization)
1
n
Binding n m tModel
1
Template find (ServiceType)
1 n
0..1 0..1
Access Point WSDL

(URL) Document
Figure 4-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.
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 and services and tModels can contain zero to many references to
taxonomy entries to categorize their content.
These 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). 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:
1. Publishing information
2. Finding information
3. Using the obtained information
These typical steps of interacting with a UDDI registry are illustrated in

Figure 4-2.

1
Companies and Companies and
organizations organizations
describe publish their
themselves services
UDDI Registry
3
Services, Client applications
Business WSDL
bindings, WSDL
WSDL invoke remote
entities WSDL
tModels services using
WSDL information
2
Human users and Human users and
client applications client applications
search for search for
business entities services
Figure 4-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 76.

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 4, and WebSphere Application Server
Network Deployment Version 5 includes a UDDI Version 2 registry.
Advanced features of UDDI Version 2

In this section we describe the enhancements in 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.

More powerful categorization
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.
Enhanced 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

different levels of specificity, while at the same time allowing a single inquiry to
reference multiple different taxonomies.
Internationalization features
Services and entities can now have language-dependent names. There must be
at least one name in any language, but you can also provide different translations
for both entities and your services.
A new type of taxonomy, postalAddress, is introduced, which 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 them 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 4-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 reading information and need some sort of
registration for publishing information.
Beside 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 76. 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.

Table 4-1 UDDI registries
Hosting Access URL
organization type
IBM Web http://uddi.ibm.com

Business
Registry Inquiry http://uddi.ibm.com/ubr/inquiryapi
Publish https://uddi.ibm.com/ubr/publishapi
IBM Test Web http://uddi.ibm.com/testregistry/registry.html

Registry
Inquiry http://www-3.ibm.com/services/uddi/testregistry/inq
uiryapi
Publish https://uddi.ibm.com/testregistry/publishapi
Microsoft Web http://uddi.microsoft.com/

Business
Registry Inquiry http://uddi.microsoft.com/inquire
Publish https://uddi.microsoft.com/publish
Microsoft Web http://test.uddi.microsoft.com/

Test Registry
Inquiry http://test.uddi.microsoft.com/inquire
Publish https://test.uddi.microsoft.com/publish
SAP Web http://uddi.sap.com/

Business
Registry Inquiry http://uddi.sap.com/uddi/api/inquiry
Publish https://uddi.sap.com/uddi/api/publish
SAP Test Web http://udditest.sap.com/

Registry
Inquiry http://udditest.sap.com/UDDI/api/inquiry
Publish https://udditest.sap.com/UDDI/api/publish
NTT Web http://www.ntt.com/uddi/

Business
Registry Inquiry http://www.uddi.ne.jp/ubr/inquiryapi
Publish https://www.uddi.ne.jp/ubr/publishapi
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

– 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 business 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 4-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.

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 4-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 4-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 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).

Figure 4-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.

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 4-5).

Figure 4-5 Expanding business entities to explore existing or define new services
When you have finished defining your entities, services and tModels, your
publishing window looks like Figure 4-6.
Figure 4-6 Overview of published items

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.
Such companies 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 an API that can be used to interact
with a UDDI registry. This class library generates and parses messages sent to
and received from a UDDI server.
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
Important packages
򐂰 org.uddi4j.datatype
This package contains classes used to send or receive UDDI information.
򐂰 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
UDDI4J requires 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
Using the library

You have to do some preparations in order to use the UDDI library. First you have
to specify a set of system properties where your 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 need 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 4-7.
// --- 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 4-7 Creating a UDDI proxy object

The concrete values for the inquiryURL and publishURL are dependent on the
UDDI registry you use and can be obtained from Table 4-1 on page 70.
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 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).
򐂰 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,
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).
򐂰 findQualifiers—Used to alter the default behavior of search functionality.
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,
IdentifierBag identifierBag,
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.
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(
java.lang.String serviceKey,
int maxRows)
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 a parameter maxRows to
define the maximum number of results. There you can also specify 0 in order not
to 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.
If you want to register some information on a UDDI server, you have to use the
authorization token obtained when creating the proxy. Figure 4-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.
// 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 4-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.
Need for privacy

One requirement is that companies often do not want to show all 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. 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.
Replication
Hosting a private registry does not necessarily mean that there is no replication
with the business registry. There might be scenarios where it makes sense to do
one-way replication 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.

Private UDDI registry product
A private UDDI registry feature is shipped with WebSphere Application Server
Network Deployment 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 416:
򐂰 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
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.
Keys assigned by publisher

Every item in a 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 is not allowed,
thereby preserving that unique key.
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 a key is no
longer the private business of the registry, but a publisher can make a suggestion
for the key, and if it is not already given or other rules apply against that key, the
registry will accept it instead of generating a new one.

Human-friendly URI-based keys
Beside 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 from a DNS record 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.
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 in the internet
򐂰 Partly public in the extranet
򐂰 Private inside the intranet
򐂰 Small ones for development
򐂰 Stable ones for test areas
򐂰 Scalable ones 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:
򐂰 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
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.
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.

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 misunderstood
when talking about UDDI registries:
򐂰 In such a registry there are not only Web services with directly accessible
WSDL files published, but also any other kind of service, which cannot be
used programmatically.
򐂰 Second, there is an increasing need for specialized and partly private
registries that are hosted by standards bodies or industries. In addition,
internal intranet registries without any contact to other business partners or
clients 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 Web Services Toolkit or the IBM
UDDI Web site at:
http://uddi.ibm.com
For general UDDI information, use the Web site at:

http://www.uddi.org

5
Chapter 5. 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

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 the client code.
򐂰 The incorporation of new bindings into client code is complex.
As stated in Chapter 3, “Introduction to WSDL” on page 41, 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

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 41, 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 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 5. Web services invocation framework 91

WSIF architecture
In this section we describe the involved components in more detail. In “More
information” on page 99, 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 5-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.

...
<binding name="SOAPBinding" type="tns-int:WeatherforecastPT">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="getTemperature">
<soap:operation soapAction="http://example.com/GetTemperature"/>
<input>
<soap:body use="encoded"
namespace="urn:xmltoday-weather"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
</input>
<output>
<soap:body use="encoded"
namespace="urn:xmltoday-weather"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
</output>
</operation>
</binding>
...
<binding name="JavaBinding" type="tns-int:WeatherforecastPT">
<format:typeMapping encoding="Java" style="Java">
<format:typeMap typeName="xsd:string" formatType="java.lang.String" />
<format:typeMap typeName="xsd:float" formatType="java.lang.Float" />
</format:typeMapping>
<operation name="getQuote">
<java:operation methodName="getTemperature"/><input/><output/>
</operation>
<java:binding/>
</binding>
...
<service name="WeatherforecastService">
<documentation>Weather forecast service</documentation>
<port name="SOAPPort" binding="tns:SOAPBinding">
<soap:address location="http://localhost:8080/soap/servlet/rpcrouter"/>
</port>
...
<port name="JavaPort" binding="tns:JavaBinding">
<java:address class="services.weatherforecast.Weatherforecast"/>
</port>
</service>
...
Figure 5-1 Fragment of a WSDL example with multiple bindings
More concepts
򐂰 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.
򐂰 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 5-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
2 3
WSIF WSIF WSIF Service
service service operation
factory
4
5 WSIF
provider
Figure 5-2 Main WSIF components

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.

Figure 5-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 5-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 5-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 5-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
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
WSIF was initially released on the alphaWorks Web site
(http://www.alphaworks.ibm.com) in October 2001. WSIF is now an Apache
open-source project and is supported by the open-source community. For links
see “More information” on page 99.
WSIF has not been standardized so far. Enhancement of the Apache WSIF
project is continuing 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.
At the time this book was written (November 2002), the first Apache WSIF
release candidate was being worked on. The first release became available in
January 2003, including documentation of the WSIF Java and EJB bindings. The
WSIF documentation is being compiled with descriptions of the WSIF Java and
EJB bindings.

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.
Integration into WebSphere products

WSIF is used in WebSphere products such as WebSphere Workflow, the Web
Services Gateway (refer to Chapter 8, “Web Services Gateway” on page 129)
and in WebSphere Studio Application Developer Integration Edition (refer to
Chapter 14, “Application Developer Integration Edition” on page 241), 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.

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

6
Chapter 6. Web services inspection

language
This chapter provides an introduction to the Web services inspection language
(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.

Overview
A centralized service registry, which is described in Chapter 4, “Introduction to
UDDI” on page 61, 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.
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 6-1.

Service
Service UDDI
Description
Description Registry
find
WS-Inspection Service
Document
Service Service
WS-Inspection
Provider Requestor
Document http://itso.com/inspection.wsil
Web Services
Service
Description
Figure 6-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 description 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 description, 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 6. Web services inspection language 103

WS-Inspection document anatomy
Figure 6-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
inspection
If links = 0 If services = 0
then services > 0 1 then links> 0
n n n
service abstract link
1 1
n n n n
abstract name description abstract
Figure 6-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 service 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 isn’t any 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.

Example
Figure 6-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 6-2 while
examining this example.
<?xml version="1.0"?>
<inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
<service>
<abstract>A simple service with two descriptions</abstract>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="http://itso.com/train.wsdl"/>
<description referencedNamespace="urn:uddi-org:api_v2">
<wsiluddi:serviceDescription
location="http://itso.com/uddi/inquiryapi">
<wsiluddi:serviceKey>
4FA23580-5C39-14D5-9FCF-BB3200303F79
</wsiluddi:serviceKey>
</wsiluddi:serviceDescription>
</description>
</service>
<service>
location="ftp://itso.com/tools/plane.wsdl"/>
</service>
<link
referencedNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
location="http://itso.com/others/moreservices.wsil"/>
</inspection>
Figure 6-3 WS-Inspection document example
Namespaces
The namespaces used in a WS-Inspection document are shown in Table 6-1.
Table 6-1 WS-Inspection namespaces
Prefix Namespace URI Definition
wsil http://schemas.xmlsoap.org/ws/ WS-Inspection namespace for the

2001/10/inspection/ WS-Inspection framework.
wsilwsdl http://schemas.xmlsoap.org/ws/ WS-Inspection namespace for the

2001/10/inspection/wsdl/ WS-Inspection WSDL binding.

Prefix Namespace URI Definition
wsiluddi http://schemas.xmlsoap.org/ws/ WS-Inspection namespace for the

2001/10/inspection/uddi/ 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.

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 registryUDDI registry can be populated using
the WS-Inspection documents found in an Internet search. On the other hand, a
UDDI registryUDDI 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:
<wsil:inspection>
<wsil:abstract xml:lang=""(0 or 1)... /> (0 or more)
<wsil:service> (0 or more)
<wsil:abstract xml:lang=""(0 or 1) ... /> (0 or more)
<wsil:name xml:lang=""(0 or 1) ... /> (0 or more)
<wsil:description referencedNamespace="uri" location="uri"(0 or 1)>
(0 or more)
<-- extensibility element --> (0 or 1)
</wsil:description>
</wsil:service>
<wsil:link referencedNamespace="uri" location="uri"(0 or 1)/>
(0 or more)
<-- extensibility element --> (0 or more)
</wsil:link>
</wsil:inspection>

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 110 for more
information.
In our example, the service definition is shown in Figure 6-4, where we specify
two services, the first one about trains and the second one about planes.

<service>
<abstract>A simple service with two descriptions</abstract>
location="http://itso.com/train.wsdl"/>
<wsiluddi:serviceDescription
location="http://itso.com/uddi/inquiryapi">
<wsiluddi:serviceKey>
4FA23580-5C39-14D5-9FCF-BB3200303F79
</description>
</service>
<service>
location="ftp://itso.com/tools/plane.wsdl"/>
</service>
Figure 6-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 6-1 on page 103).
The link element helps service providers to create inspection documents with a
large number of services elements pointing to the same location in the

information registry. Using the link, they are able to indicate to the consumer that
they have to look in 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 the link definition, shown in Figure 6-5, is where we specify one
link to another WS-Inspection document providing the namespace
http://schemas.xmlsoap.org/ws/2001/10/inspection/ and the location of the
document http://itso.com/others/moreservices.wsil.
<link
referencedNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
location="http://itso.com/others/moreservices.wsil"/>
Figure 6-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.

The grammar for the binding extension elements is shown in Figure 6-6 and the
description of its element in Table 6-2.
<inspection
xmlns:wsilwsdl="http://schemas.xmlsoap.org/ws/2001/10/inspection/wsdl/ ...>
<service ...>
location="uri">
<wsilwsdl:reference endpointPresent="boolean"(0 or 1)>
<wsilwsdl:referencedService>
QName
</wsilwsdl:referencedService> (0 or 1)
<wsilwsdl:implementedBinding>
QName
</wsilwsdl:implementedBinding> (0 or more)
</wsilwsdl:reference>
</description>
</service>
</inspection>
Figure 6-6 WSDL binding extension elements grammar
Table 6-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.

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 6-7 and the
description of its element in Table 6-3.
<inspection
(xmlns:wsiluddi://schemas.xmlsoap.org/ws/2001/10/inspection/uddi/ |
xmlns:wsiluddi://schemas.xmlsoap.org/ws/2001/10/inspection/uddiv2/) ... >
<service ... >
<description ... >
<wsiluddi:serviceDescription location="uri"> (0 or 1)
<wsiluddi:discoveryURL useType="nmtoken"> (0 or 1)
<wsiluddi:serviceKey> (0 or 1)
</description>
</service>
<link ... >
<wsiluddi:businessDescription location="uri"(0 or 1)>
<wsiluddi:discoveryURL useType="nmtoken"> (0 or 1)
<wsiluddi:businessKey> (0 or 1)
</wsiluddi:businessDescription>
</link>
</inspection>
Figure 6-7 UDDI binding extension elements grammar

Table 6-3 UDDI extensibility elements in WS-Inspection
Element Extension name Explanation
description wsiluddi: Specifies a reference to a single UDDI service

serviceDescription description. Must contain a serviceKey and
may also contain a discoveryURL.
wsiluddi: Used to retrieve a UDDI business entity using

discoveryURL HTTP GET to obtain a single service
description using the serviceKey.
wsiluddi: Used to retrieve the UDDI service description.

serviceKey
link wsiluddi: Specifies a reference to a UDDI business entity.

businessDescription Must contain a discoveryURL, a businessKey or
both. The location attribute contains the UDDI
registry inquiry interface.
wsiluddi: Specifies a valid URL to retrieve the UDDI

discoveryURL business entity using HTTP GET.
wsiluddi: Specifies a business key that is used in

businessKey combination with the location attribute of the
business description to retrieve the UDDI
business entity using HTTP POST.
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.

WSIL examples
In this section we describe two examples of bindings that we use in the sample
application described in Chapter 18, “Web services scenario: architecture and
implementation” on page 353.
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 6-8).
<?xml version="1.0"?>
<inspection
targetNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
xmlns:wsiluddi="http://schemas.xmlsoap.org/ws/2001/10/inspection/uddi/"
xmlns:wsilwsdl="http://schemas.xmlsoap.org/ws/2001/10/inspection/wsdl/"
xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/">
<service>
<abstract>The Flash Weather forecast service description</abstract>
<name xml:lang="en-US">ITSO WS Flash Weather Service</name>
location="http://www.flashandthunder.com/ItsoFlashWeb/wsdl/
itso/wsoj/WeatherForecastService.wsdl">
<wsilwsdl:reference endpointPresent="true">
<wsilwsdl:implementedBinding xmlns:binding=
"http://wsoj.itso.wsdl/weatherforecastbinding">
binding:WeatherForecastBinding
</wsilwsdl:implementedBinding>
</wsilwsdl:reference>
</description>
</service>
<service>
<abstract>The Thunder Weather forecast service description</abstract>
<name xml:lang="en-US">ITSO WS Thunder Weather Service</name>
location="http://www.flashandthunder.com/ItsoThunderWeb/wsdl/
itso/wsoj/WeatherForecastService.wsdl">
......
</description>
</service>
</inspection>
Figure 6-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.

UDDI binding example
The second example shows the use of a UDDI binding, that is, the WSIL
document points to a UDDI registry (Figure 6-9).
......
<service>
<name xml:lang="en-US">ITSO WS Thunder Weather Service</name>
<wsiluddi:serviceDescription location=
"http://uddi.ibm.com/testregistry/inquiryapi">
<wsiluddi:serviceKey>F3362720-0C6D-11D7-AB70-000629DC0A53
<wsiluddi:discoveryURL useType="businessEntity">
http://uddi.ibm.com/testregistry/inquiryapi
?businessKey=F5082FA0-0BCB-11D7-AB70-000629DC0A53
</wsiluddi:discoveryURL>
</description>
</service>
<link referencedNamespace="urn:uddi-org:api_v2">
<wsiluddi:businessDescription
location="http://uddi.ibm.com/testregistry/inquiryapi">
<wsiluddi:businessKey>F5082FA0-0BCB-11D7-AB70-000629DC0A53
</wsiluddi:businessKey>
<wsiluddi:discoveryURL useType="businessEntity">
http://uddi.ibm.com/testregistry/inquiryapi
?businessKey=F5082FA0-0BCB-11D7-AB70-000629DC0A53
</wsiluddi:discoveryURL>
</wsiluddi:businessDescription>
</link>
......
Figure 6-9 WSIL example with UDDI binding
In this example the <service> tag points to a single business service in the UDDI
registry, whereas the <link> 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
<service> tag, and only the discoveryURL or the businesskey are required in the
<link> tag.

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 6-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 6-10 WS-Inspection API example

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 sources for more information are the IBM Web Services Toolkit (WSTK)
and 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

7
Chapter 7. 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)

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 services, 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.

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 7. Workflows and business processes 121

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, 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 7-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

<flowModel name="weatherForecast" serviceProviderType="totalSupply">
<serviceProvider name="MyWeatherGuru" type="weather">
<locator type="static" service="weather.com"/>
</serviceProvider>
<serviceProvider name="MyMathGuru" type="calculator">
<locator type="static" service="maths.com"/>
</serviceProvider>
<activity name="getDayForecast">
<performedBy serviceProvider="MyWeatherGuru"/>
<implement>
<export>
<target portType="WeatherForecast" operation="getDayForecast"/>
</export>
</implement>
</activity>
<activity name="convertCelsiusToFahrenheit">
<performedBy serviceProvider="MyMathGuru"/>
<implement>
<export>
<target portType="TemperatureCalculator"
operation="convertCelsiusToFahrenheit"/>
</export>
</implement>
</activity>
<controlLink source="getDayForecast" target="convertCelsiusToFahrenheit"/>
<dataLink source="getDayForecast" target="convertCelsiusToFahrenheit">

<map sourceMessage="getDayForecastResponse"
targetMessage="convertCelsiusToFahrenheitRequest"/>
</dataLink>
</flowModel>
Figure 7-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 14, “Application Developer Integration Edition” on page 241 for
further information on how to develop workflow and business processes using
the IBM tools.

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.
򐂰 Variables—Hold data within the process, for example messages.
For a more detailed description of the process elements, see “Business process”
on page 247.
FDML sample code

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

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 the 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 <containers> 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.

Partners
The <partners> 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 <receive> 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 <reply> activity is used to specify a synchronous response to the
request corresponding to a <receive> 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 <invoke> activity is used within the process that produces the
asynchronous response. The original requestor will use a <receive> activity to
process the response delivered by the <invoke> activity.
A more powerful mechanism is the usage of a <pick> 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
<pick> 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 <faultHandlers> 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.

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 127) offer 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
Usage of BPEL4WS
At the time of publication of this redbook in March 2003, the BPEL4WS
specification was still not a standard, but only a draft and therefore subject to
change. It is included in the Web Services 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
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.
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

8
Chapter 8. Web Services Gateway

This chapter describes the Web Services Gateway (WSGW), which is part of
WebSphere Application Server Version 5 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
򐂰 Security features
򐂰 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.

Overview
If you plan to externalize your Web services beyond the boundaries of your
enterprise network, you will be faced with a number of issues that you 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 you want to externalize your Web
services to let clients from outside your intranet, such as customers, suppliers
and business partners, access your services. The Web Services Gateway lets
clients from outside the firewall use Web services that are deployed on a server
deep inside your enterprise.
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 your server on the Internet. You 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.
Web service access to non-SOAP objects

If you have some functionality not defined as a Web service, but as a JavaBean
or EJB, then you may not want to wrap a new Web service around that function
manually, but you 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, you 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 you can administer:

򐂰 Web services—Register them to make them available either inside or
outside your 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 your gateway to UDDI registries.
Managing your 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.
Exposing Web services to the outside world

You can expose an internal service for outside consumption. 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 you have deployed Web services on a server inside the intranet, you might
want to allow access to clients from outside. You might also consider applying
Chapter 8. Web Services Gateway 131

special security constraints to restrict the access to either specific users and/or
specific methods of your service. This scenario is illustrated in Figure 8-1.
Internet DMZ Intranet
Web
Services
Gateway
Channel 1 Prefilter Channel 2 Web

deployed
Client Service
WS
Channel 1 Postfilter Channel 2 Implementation
UDDI external WSDL internal WSDL

URI = URI =
http://theGateWay.com/... http://myInternalServer/...
Figure 8-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 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 you 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
similar to the illustration in Figure 8-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 you need to

define a set of channels corresponding to the specific protocols that you 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, you can switch the protocol. This scenario is illustrated in Figure 8-2.
Channel 1 Web Channel 2 Web

Client Services Service
SOAP/HTTP Gateway SOAP/JMS Implementation
Figure 8-2 Using the gateway for protocol switching
Managing filters
You can develop and use one or more filters for your Web services, which means
that some specific task is done using the input and/or output messages to and
from your Web service. There are standard filters as well as the possibility of
creating your own. An illustration of filters, especially prefilters that manipulate
requests and postfilters that work on responses, is shown in Figure 8-1 on
page 132. Refer to “Managing filters” on page 133 for more information.
UDDI publication and lookup

The gateway facilitates working with UDDI registries. As you map a service for
external consumption using the gateway, you 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.
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 your HTTP server
is listening on. You should reach a menu that allows you to configure the
gateway and to administer (list, deploy and remove) 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 you should also do your configuration:
1. First, configure the URI for your gateway
2. Second, define channels, filters, and UDDI references
3. Finally, define your Web services.
Note: If you change your gateway URI, you have to redefine all services. If you
want a Web service to use any channel, filter or UDDI reference, define them
before adding them to the service. However, you may update the list of
channels, filters, and/or UDDI references for a service at any time.
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, then passed through filters that are registered for the
requested service, and finally forwarded to the actual service implementation.
Before you can use a channel, you must install the channel application in
WebSphere Application Server, then deploy the channel to the Web Services
Gateway.
Two versions of each type of channel are supplied with the gateway, so you 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 your
organization from the rights you give to users within your organization:
򐂰 To ensure that users outside your organization can only access those internal
services that you choose to publish externally, you deploy those services on
the inbound channel.
򐂰 To give users inside your organization access to the full range of internal and
external services, you deploy those services on the outbound channel.
A channel is in fact an application that is deployed to the application server.
The only channel that is shipped with the gateway is the SOAP channel, as
SOAPChannel 1 and SOAPChannel 2, one for inbound and one for outbound
messages.
Once you have successfully installed your channels (or are satisfied with the
existing ones) you 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 request.
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:
򐂰 Install the EAR file of the filter application
򐂰 Deploy that filter to the gateway using the admin tool
򐂰 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 filter
Restriction: Writing your own filters is supported only on WebSphere

Application Server Enterprise Edition.
A filter is in fact a session EJB that implements a specific interface. So if you

want to create your own filter, you 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 initialization, destroy, and—more important— intercepting
(filtering) requests and responses. After implementing the bean, you must do the
following:
򐂰 Install the application on the application server
򐂰 Deploy the filter to the gateway
򐂰 Specify the filter as pre- or postfilter in your Web service definition
Working with 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 69).
If you 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 you enter for user ID and password must match those of the
owner of the corresponding business in the registry. You can see the owning user
ID in the UDDI registry by looking at the business details under the authorized
name field.
Deploying Web services to the gateway
Important: Before you start to define any Web service, be sure that you 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 you configure a Web service, you 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
Each of these choices is made from a list of resources that have already been
deployed to the Web Services Gateway. So you should deploy your channels,
filters, and UDDI references before you deploy the Web services that use those
resources. However, you can go later update the channels, filters, and UDDI
references for the service if necessary.
When deploying a service, specify the following information:

򐂰 Name—Each Web service is identified by a unique name in the gateway.
򐂰 Message part representation:
– Generic classes—Select this option if there are no special EJB or Java
bindings.
– Deployed Java classes—Select this option if the target services for the
gateway service contain EJB bindings, or if the target services use the
LFT channel.
Note: When you choose this option, you must also ensure that the specific
Java classes that have been generated for the Web service are deployed
to the application server.
򐂰 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.

򐂰 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.
– 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—You only need to fill out these fields if you 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)
򐂰 Channels—Add or remove channels from the list of deployed channels
through which this service is available.
򐂰 Pre-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.
򐂰 Post-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 you 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.

Troubleshooting
To identify and resolve gateway-related problems, you can use the standard
WebSphere Application Server facilities. If you encounter a problem that you
think might be related to the gateway, you can check for error messages in the
WebSphere Application Server Administrative Console, and in the application
server’s stdout.log file. You can also enable the application server debug trace
to provide a detailed exception dump. Refer to the WebSphere InfoCenter or the
redbook WebSphere Application Server Version 5 Handbook, SG24-6195, for
details.
Security features
The Web Services Gateway provides a basic authentication and authorization
mechanism based upon the security features of WebSphere Application Server.
Security can be applied at two levels:
򐂰 Gateway-level authentication
򐂰 Operation-level authorization
Gateway-level authentication
For gateway-level authentication, you 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. You 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

you install any channels.
Operation-level authentication
For operation-level authorization, you apply security to individual methods in a
Web service. To do this, you 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.

Your target Web service is protected by wrapping it in an EAR file, and applying
role-based authorization to the EAR file:
򐂰 If you want to enable operation-level authorization, you must first enable
gateway-level authentication.
򐂰 After gateway-level authentication has been enabled, filters have access to
the requestor’s authentication information.
򐂰 You 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, you should
make a backup copy of it before you change it.
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. In the recent Version 1.0.1, the gateway is part of the Application
Server Version 5 Network Deployment.
The programming model extensions for writing filters are included in Application
Server Version 5 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,
you need a complete J2EE server providing Web and EJB containers.
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.
򐂰 The gateway does not support WSDL service definitions that contain
soap:header elements within their wsdl:definition element.

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. You
also can specify external Web services to use them inside your intranet. For both
types of services you can specify filters to be applied before and/or after a
specific service is called. When defining channels, you 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 your services in
UDDI registries and incorporate possibilities to apply security on Web services
and/or its methods.
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

9
Chapter 9. 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. Unfortunately, at the time of writing of this book there was no general
standard that would cover all the aspects of Web services security, although
partial solutions exist that provide a sufficient level of security for practical use.
In this chapter, we first address the main security requirements. We briefly cover
the transport channel security solutions as well as the current status of XML
document security. We also inspect the standardized Web services security
methods, as well as the current status of the work in progress in this field.

Overview
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.
General security requirements

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 9-1 shows the main components of a security framework (based upon
ISO standard 7498-2).
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 9-1 Main building blocks of a security framework
Most of the systems involved in Web services today only partially fulfill these
requirements. In the following sections we cover different security approaches
and their limitations.
Transport channel security

Technically, Web services are based on message exchange. Since no security
standard for Web services will cover all security aspects, it is tempting to exploit
the security solutions built into the channel used for SOAP message transport,
especially because these solutions are well understood and standardized, even
though they also have certain security limitations.
Chapter 9. Web services security 143

Mail transport
In principle, it is possible to exchange SOAP messages using mailing systems.
Although basic mail exchange protocols such as Post Office Protocol (POP) or
Simple Mail Transfer Protocol (SMTP) provide little or no security, most
commercially available mailing systems provide security mechanisms, such as
user authentication, message encryption, and digital signing. With these
mechanisms we achieve a sufficient security level in regards to identification and
authentication, as well as message integrity and confidentiality.
HTTP transport
HTTP (Hyper Text Transfer Protocol), the most commonly used protocol for
information exchange on the Internet, is an inherently insecure protocol, since 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.
Its successor 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. The client must
support SSL. 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, server and client
share a common key pair that allows them to encrypt and decrypt messages they
exchange.
Although HTTPS does not cover all the aspects of general security framework, it
provides a sufficient security level regarding party identification and
authentication, message integrity, and confidentiality. However, authorization,
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.
JMS transport
Message exchange between different applications and systems is a powerful
mechanism often used in different solution designs. However, different vendors of
messaging middleware could not standardize their APIs and therefore the
designers were often restricted to one of them. JMS (Java Messaging System),
introduced by Sun in 1999, represented the first platform-independent message

interchange. Unfortunately, JMS does not address security issues. Therefore, the
security depends on the underlying middleware such as IBM WebSphere MQ.
WebSphere MQ transport
IBM WebSphere MQ (formerly IBM MQSeries) is one of the most widely used
middleware solutions for message queuing. It is available on a wide range of
platforms. Its main component is queue manager, a server that manages the
queues and messages in them and takes care of message exchange with remote
queue managers. As we discuss in this section, several, though not all, of the
security requirements are addressed when using WebSphere MQ in SOAP
message transport, either directly or indirectly through JMS.
Identification and authentication are performed outside WebSphere MQ. When

sending a message to a remote queue manager, however, a local queue
manager is responsible for providing identification and authentication services so
that the origin of the message can be reliably determined.
A queue manager by itself does not provide services such as message integrity,
confidentiality and non-repudiation. However, the queue manager enables
channel encryption using SSL, thus providing message integrity and
confidentiality service. Also, it is possible to implement services such as remote
authentication, message integrity, confidentiality, and non-repudiation using
additional middleware, IBM Tivoli Access Manager for Business Integration
(formerly Tivoli SecureWay Policy Director for MQSeries).
XML-based Web services security

So far, we have only covered Web services security provided by the underlying
communication channel middleware. We have already mentioned that Web
services is about XML document exchange and therefore another level of
security can be achieved at the XML document level. Next, we provide a brief
overview of a set of security technologies that are being adopted as standards or
are in the process of adoption.
XML digital signatures

XML digital signatures is a standard for securely verifying the origins of
messages. It specifies a standard procedure for signing XML documents with a
variety of different digital signature algorithms. Digital signatures can be used for
validation of messages as well as for non-repudiation.
XML encryption
XML encryption is still a work in progress. Its aim is to allow encryption of digital
content, such as GIF images or XML fragments. XML encryption allows the parts
of an XML document to be encrypted while leaving other parts open, encryption

of the XML itself, or the super encryption of data (that is, encrypting an XML
document when some elements have already been encrypted).
Security assertion markup language

Security assertion markup language (SAML) is the first industry standard for
secure e-business transactions based on XML. SAML is being developed to
define a common way for sharing security services between companies engaged
in business-to-business and business-to-consumer transactions. SAML allows
companies to securely exchange authentication, authorization, and profile
information among their customers, partners, or suppliers regardless of their
security solutions or platforms. As a result, SAML supports the interoperability
between different security systems.
WS-Security
Now that we have discussed Web services security provided either by the
underlying communication channel middleware or at the XML document level, in
this section 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.
The specification is proposed by IBM, Microsoft, and VeriSign for review and
evaluation. In the future, it will replace existing Web services security
specifications from IBM and Microsoft including SOAP Security Extensions
(SOAP-SEC), Microsoft's WS-Security and WS-License, as well as IBM's
security token and encryption documents.
Namespaces and terminology

In this section we list the namespaces that a WS-Security implementation must
use. We also define some basic terminology.

WS-Security namespaces
The XML namespaces used in WS-Security are shown in Table 9-1.
Table 9-1 Namespaces used in WS-Security
s http://www.w3.org/2001/12/soap-envelope SOAP envelope
ds http://www.w3.org/2000/09/xmldsig# XML signature
xenc http://www.w3.org/2001/04/xmlenc# XML encoding
m http://schemas.xmlsoap.org/rp SOAP routing protocol
wsse http://schemas.xmlsoap.org/ws/2002/04/secext WS-Security schema
WS-Security terminology
The following is some basic WS-Security terminology used in this section:
Claim Statement that a client makes (for example, name,
identity, key, group, privilege, capability).
Security token A representation of a collection of claims.
Signed security token A security token that is asserted and cryptographically
endorsed by a specific authority (for example, an
X.509 certificate or a Kerberos ticket).
Proof-of-possession Data that is used in a proof process to demonstrate the
sender's knowledge of information that should only be
known to the claiming sender of a security token.
Integrity Process by which it is guaranteed that information is
not modified in transit.
Confidentiality Process by which data is protected such that only
authorized actors or security token owners can view
the data.
Digest A cryptographic checksum of an octet stream.
Signature A cryptographic binding of a proof-of-possession and a
digest. This covers both symmetric key-based and
public key-based signatures. Consequently,
non-repudiation is not always achieved.
Attachment A generic term referring to additional data that travels
with a SOAP message, but is not part of the SOAP
envelope.

SOAP message securing
When trying to secure a SOAP message, two types of threats should be
considered:
򐂰 The message could be modified or read by unauthorized persons.
򐂰 An unauthorized person could send messages to a service that, while
well-formed, lack appropriate security claims to warrant processing.
To deal with these threats we introduce a message security model.
Message security model

In this subsection we specify an abstract message security model in terms of
security tokens combined with digital signatures as a proof of possession of the
security token (key).
Security tokens assert claims, and signatures represent a mechanism for proving
the sender's knowledge of the key. The signature can also be used to bind or
associate the signature with the claims in the security token (assuming the token
is trusted). Note that such a binding is limited to those elements covered by the
signature. Furthermore note that this security model does not specify a particular
method for authentication, but simply indicates that security tokens may be
bound to messages.
A claim can be either endorsed or unendorsed by a trusted authority. A set of

endorsed claims is usually represented as a signed security token that is digitally
signed or encrypted by the authority. An X.509 certificate, claiming the binding
between one's identity and public key, is an example of a signed security token.
An endorsed claim can also be represented as a reference to an authority so that
the receiver can pull the claim from the referenced authority.
An unendorsed claim can be trusted if there is a trust relationship between the

sender and the receiver. For example, the unendorsed claim that the sender is
Bob is sufficient for a certain receiver to believe that the sender is in fact Bob, if
the sender and the receiver use a trusted connection and there is an out-of-band
trust relationship between them.
One special type of unendorsed claim is a proof of possession. Such a claim

proves that the sender has a particular piece of knowledge that is verifiable by
appropriate actors. For example, a user ID/password is a security token with this
type of claim. A proof-of-possession claim is sometimes combined with other
security tokens to prove the claims of the sender. Note that a digital signature
used for message integrity can also be used as a proof-of-possession claim,
although in this specification we do not consider such a digital signature as a
type of security token. It should be noted that this security model, by itself, is
subject to multiple security attacks.

Message protection
Protecting the message content from being intercepted (confidentiality) or
illegally modified (integrity) are primary security concerns. The WS-Security
specification provides a way to protect a message by encrypting and/or digitally
signing a body, a header, an attachment, or any combination of them (or parts of
them).
Message integrity is provided by using the XML digital signature together with
security tokens to ensure that messages are transmitted without modifications.
The integrity mechanisms are designed to support multiple signatures,
potentially by multiple actors, and to be extensible to support additional signature
formats.
Message confidentiality uses XML encryption together with security tokens to

keep portions of a SOAP message confidential. The encryption mechanisms are
designed to support additional encryption processes and operations by multiple
actors.
Missing or inappropriate claims

The message receiver should reject a message with an invalid signature or
missing or inappropriate claims, because it is an unauthorized (or malformed)
message. The WS-Security specification provides a flexible way for the message
sender to claim the security properties by associating zero or more security
tokens with the message. An example of a security claim is the identity of the
sender; the sender can claim that he is Bob, known as an employee of some
company, and therefore he has the right to send the message.
WS-Security: an example
We demonstrate the main aspects of WS-Security in the example in Figure 9-2.
After the SOAP <Envelope> tag comes the list of headers of this SOAP message.
򐂰 First comes routing information based on the SOAP routing protocol
namespace from Table 9-1 on page 147:
<m:path xmlns:m="http://schemas.xmlsoap.org/rp/">
<m:action>http://fabrikam123.com/getQuote</m:action>
<m:to>http://fabrikam123.com/stocks</m:to>
<m:id>uuid:84b9f5d0-33fb-4a81-b02b-5b760641c1d6</m:id>
</m:path>

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://www.w3.org/2001/12/soap-envelope"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<S:Header>
<m:path xmlns:m="http://schemas.xmlsoap.org/rp/">
<m:action>http://fabrikam123.com/getQuote</m:action>
<m:to>http://fabrikam123.com/stocks</m:to>
<m:id>uuid:84b9f5d0-33fb-4a81-b02b-5b760641c1d6</m:id>
</m:path>
<wsse:Security
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext">
<wsse:UsernameToken Id="MyID">
<wsse:Username>Zoe</wsse:Username>
</wsse:UsernameToken>
<ds:Signature>
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm=
"http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod Algorithm=
"http://www.w3.org/2000/09/xmldsig#hmac-sha1"/>
<ds:Reference URI="#MsgBody">
<ds:DigestMethod Algorithm=
"http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>LyLsF0Pi4wPU...</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>DJbchm5gK...</ds:SignatureValue>
<ds:KeyInfo>
<wsse:SecurityTokenReference>
<wsse:Reference URI="#MyID"/>
</wsse:SecurityTokenReference>
</ds:KeyInfo>
</ds:Signature>
</wsse:Security>
</S:Header>
<S:Body Id="MsgBody">
<tru:StockSymbol xmlns:tru="http://fabrikam123.com/payloads">
XXX
</tru:StockSymbol>
</S:Body>
</S:Envelope>
Figure 9-2 A secured SOAP message with a username security token
򐂰 Next comes the <Security> header block, which provides a mechanism for
attaching security-related information targeted at a specific receiver (SOAP
actor). This may be either the ultimate receiver of the message or an

intermediary. Consequently, this header block may be present multiple times
in a SOAP message:
<wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext">
...
</wsse:Security>
򐂰 A message may have multiple <Security> header blocks if they are targeted
for separate receivers. However, only one <Security> header block can omit
the S:actor attribute and no two <Security> header blocks can have the
same value for S:actor. Message security information targeted for different
receivers must appear in different <Security> header blocks. The <Security>
header block without a specified S:actor can be processed by anyone, but
must not be removed prior to the final destination.
򐂰 The next three lines specify a security token that is associated with the
message. In this case, it defines the user ID of the client using the
<UsernameToken>.
<wsse:UsernameToken Id="MyID">
<wsse:Username>Zoe</wsse:Username>
</wsse:UsernameToken>
򐂰 The security token is followed by a digital signature:
<ds:Signature>
...
</ds:Signature>
A digital signature provides a way to ensure the integrity of the signed
elements. The signature uses the XML signature specification. In this
example, the signature is based on a key generated from the user’s
password; typically stronger signing mechanisms would be used.
򐂰 The <SignedInfo> block contains information about the signed elements. The
first item describes the canonization (normalization) method, whereas the
second one determines the algorithm used to generate a signature.
<ds:SignedInfo>
<ds:CanonicalizationMethod
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod Algorithm=
"http://www.w3.org/2000/09/xmldsig#hmac-sha1"/>
...
</ds:SignedInfo>
򐂰 The next block contains the selection of the elements that are signed:
<ds:Reference URI="#MsgBody">
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>LyLsF0Pi4wPU...</ds:DigestValue>
</ds:Reference>

Specifically, the first item indicates that the <S:Body> element is signed. In this
simple example only the message body is signed. However, in realistic
scenarios additional elements of the message, such as parts of the routing
header, should also be included in the signature.
򐂰 The next line specifies the signature value of the canonical form of the data
that is being signed as defined in the XML signature specification:
<ds:SignatureValue>DJbchm5gK...</ds:SignatureValue>
򐂰 The next block includes a hint where to find the security token associated with
this signature. Specifically, the <SecurityTokenReference> block indicates
that the security token can be downloaded from the specified URL:
<ds:KeyInfo>
<wsse:SecurityTokenReference>
<wsse:Reference URI="#MyID"/>
</wsse:SecurityTokenReference>
</ds:KeyInfo>
򐂰 Finally, there is the SOAP body element with the information that has to be
passed to the recipient.
WS-Security extensions
Because the WS-Security standard addresses only a subset of security services,
a more general security model was 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.
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 9-3.

UsersWS-SecureConversation
SOAP Foundation Layer User Groups

WS-Federation
WS-Security Layer Passwords
WS-Authentication
Policies
Privileges WS-Policy
Encryption Keys
WS-Trust
Audit Logs
WS-Privacy
Today Future - specification in progress
Figure 9-3 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 Describes how to manage and broker the trust
relationships in a heterogeneous federated
environment, including support for federated
identities.
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 enable 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.
Status
An implementation of WS-Security is available in the Web Services Toolkit
Version 3.2.2. See Chapter 16, “Web Services Toolkit” on page 301 for more
information.
Summary
Web services technology enables a loosely coupled, language-neutral,
platform-independent way of linking applications within organizations, across
enterprises, and across the Internet. In order 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.
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/
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-strawman-
03.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.

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.

10
Chapter 10. 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

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 10-1.
WebSphere Portal Server WebSphere Business Integration
WebSphere Everyplace WebSphere MQ

Integrator Broker
WebSphere Commerce
WebSphere Application Server

WebSphere Studio
WebSphere MQ
Figure 10-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
development tool 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 customer to
interconnect their islands of information and make full use of the
message-based architecture.

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.

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 10. IBM WebSphere product family 161

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.

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), 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, and internationalization, and asynchronous processing. It delivers
more integration capabilities than WebSphere Application Server Network
Deployment through extensions beyond the limitations of the J2EE standards.

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.
More information
For more information on IBM WebSphere Application Server, refer to:
http://www-3.ibm.com/software/webservers/
WebSphere Studio
The WebSphere Studio family of products is a set of development tools for
enterprise e-business Java-based applications. Beside programming tools it also
enable the developers to test and deploy their application from the common
environment. The rich set of utilities and wizards help developers to simplify
common tasks so that they can concentrate on more creative parts of their job
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.
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 10-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.
Site Developer Application Developer

Core Java IDE
Create Web pages
Struts support, JSP tags
XML support EJB Development
JavaBean/DB Wizards J2EE Development
Web Services Wizards J2EE Deployment
Team Environment Profiling
Integrated WebSphere Integrated WebSphere
App Server Express App Server
Enterprise Developer Application Developer

Integration Edition
Enterprise Connectors
(CCF and J2C)
Enterprise Generation Web service flow
Language (EGL) modeling
COBOL and PL/I WSDL Editor
z/OS Development Integrated WebSphere
Environment App Server Enterprise
Figure 10-2 WebSphere Studio Product Suite
IBM 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, and Web services. The tools
inherited from the Workbench also support Java and JavaScript development. In
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 via JavaServer Pages (JSP).
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 and includes a ClearCase LT repository. A WebSphere test
environment is also part of the package.
IBM 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.
IBM 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.
IBM 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).

IBM WebSphere Studio Application Developer Version 5 became available at the
end of 2002. Other packages will follow in the first half of 2003.
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/

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.

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 business.

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
simplify and speed 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
򐂰 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 2.1.
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 which 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
WebSphere Everyplace group contains three different configurations.
IBM WebSphere Everyplace Embedded Edition

WebSphere Everyplace Suite 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
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,
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 Version 4.2 provides several new features which
include notification services, device management support, additional client
devices support and enhanced offline access to Web content.

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 (former Commerce Suite) represents 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.
IBM 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 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, IBM MQSeries, 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.4 which
introduced several improvements including better access control based on a
hierarchical policy and roles, advanced user, member, and organization
management, new security and collaboration features, and enhanced catalog
management.
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 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 of message augmentation, warehousing, and message
flow tools.

IBM WebSphere MQ Integrator Broker Version 2.1 provides the customers with
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 wall
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/
WebSphere Business Integration

The IBM WebSphere family includes business integration products and solutions
that help integrating either 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.1.
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.
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 customer moving their traditional selling
operations to the Internet in a controlled scalable manner.

The business integration group products help customer 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 products are regularly updated to cope with the
e-business environment that changes at a high pace. Therefore Internet
represents one of the best sources of up-to-date information.
For general information on IBM WebSphere family 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.

11
Chapter 11. Web services development

overview
This chapter provides a general introduction to Web services development. We
present the different techniques for developing a Web service, discussing the
development steps without getting into the specific implementation details.
This chapter contains the following topics:

򐂰 Paths for creating a new Web service
򐂰 Paths for creating a new Web services client

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 11-1.
Build Deploy Run Management
1 Service
build or definition assemble
have WSDL
WebSphere
Web deploy Web run Web manage Web
Initial build service service service service
build deploy run manage
build Java
or have code assemble publish invoke
1
Client
Service
registry find
Figure 11-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,

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.
Paths for creating 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 11. Web services development overview 177

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 11-2 we can see this path.
Service
definition
Generate
WSDL
Service
Application Web Service
Figure 11-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.
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 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.

Therefore, the providers have to adapt their current systems to follow the new
specification.
The top-down path is shown in Figure 11-3.
Service
Generate definition
WSDL
Service
Skeleton
Web
Application
Service
Code
Figure 11-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. Finally, we test the new Web service to check that it is
compliant to the specification.

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. This path is shown in
Figure 11-4.
Service
definition
WSDL
WS 3
WS 1 WS 4 WS 5
WS 2
Web Service
Figure 11-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. 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.
Types of Web services implementation

The base for the Java 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. In
Table 11-1 we can see the variations for the different tools and products used in
this book.

Table 11-1 Web services implementation facilities by products
Tool or Path Java EJB DADX ISD URL
product bean
WSAD Bottom-up Yes Yes Yes Yes Yes

(SOAP 2.3)
Top-down Yes No No No No
WSADIE Bottom-up Yes Yes Yes Yes Yes

(SOAP 2.3)
Top-down Yes Yes No No No
Multiple services (business process) implemented as an EJB service
WSDK, WSTK Bottom-up Yes Yes No No No

WSTP
(Axis) Top-down Yes Yes No No No
WSAD = WebSphere Studio Application Developer

WSADIE = WebSphere Studio Application Developer Integration Edition
WSDK = WebSphere SDK for Web Services
WSTK = Web Services Toolkit
WSTP = WebSphere Web Services Technology Preview
DADX = document access definition extensions
ISD = Web service deployment descriptor (points to implementation code)
URL = uniform resource locator (for a servlet)
Paths for creating a new Web services client

The built task for the generation of a Web service client (also known as a service
requestor) is dictated based on the method used for binding to a Web service
server. The WSDL document is used to generate a service proxy (also called a
stub). This service proxy contains all the needed information to invoke the Web
service. The clients use the proxy locally to access the business service. The
paths to binding to a service differ in the moment when the information required
to connect to a Web service is loaded (build time vs. runtime). These paths are:
򐂰 Static client
򐂰 Dynamic client with known service type
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. In Figure 11-5 we can see the process to generate a static
client.
e mail WSIL
UDDI
Service registry
1 definition
Find
WSDL
build time
2
Service Generate
definition 3 Bind
WSDL Web
Proxy Service
WS or
client Stub
Figure 11-5 Static client path
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. The 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. 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 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. In Figure 11-6 we can see the process to generate this dynamic client.
UDDI
Service definition
Registry
WSDL
1 Service Service
Find interface implementation
build time
Find
Generate 3
Service runtime
interface
2 Web
Proxy Bind Service
WS or 4
client Stub
Figure 11-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. 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.
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 5, “Web services invocation framework” on page 89).
Even more dynamic is when we do not know anything about the service in
advance. 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 implementation

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:
򐂰 As a stand-alone Java J2SE application client
򐂰 As a J2EE application on some middleware container

From the point of view of what kind of module or application is built, the
possibilities are:
򐂰 A Java class
򐂰 A JavaBean
򐂰 An EJB
򐂰 A servlet
򐂰 A JavaServer Page (JSP)
򐂰 A Java applet
The different tools and products used in this book offer varying facilities to
automatically generate some of the required code to create a client. Usually
some manual coding is required for most of the cases and is inevitable with a
dynamic client. In Table 11-2 we can see the facilities provided by the different
tools.
Table 11-2 Web services client implementation facilities by products

Tool or product Facilities
Application Developer Generates a proxy, the mapping parameters, and JSPs to test
(SOAP 2.3) the client visually.
Application Developer Generates a proxy, the mapping parameters, and JSPs to test
Integration Edition the client visually. Includes WSIF for dynamic invocation.
(SOAP 2.3) Includes business process flow modeling. Generates Web
services from EIS using connectors.
WebSphere SDK for Generates all the stubs needed to connect with the Web
Web Services service, including the mapping parameters and a service
(Axis) locator (XML file and Java code to locate the service).
Web Services Toolkit Same as WebSphere SDK.

(Axis)
WebSphere Same as WebSphere SDK.

Technology Preview
(Axis)
For further information about these tools or products and client generation,
please refer to 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, see the document “Web
Services Development Concepts 1.0" from the Web Services Toolkit. It is also
available at the following URL:
http://www.ibm.com/software/solutions/webservices/pdf/WSDC.pdf

12
Chapter 12. Weather forecast application

In this chapter we describe the base Java code of a weather forecasting
application that we use to demonstrate the Web services technology.

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.
Business module
The business module is implemented by the WeatherForecast class. This class
offers the business logic of our example providing three principal functions:
򐂰 Provide the weather forecast prediction for one specific day
򐂰 Provide the weather forecast prediction for a whole week
򐂰 Provide the temperatures prediction for a whole week
The data returned by the business methods is:

򐂰 A Java bean represented for the complex type Weather
򐂰 An array of Weather Java beans
򐂰 An array of integer numbers
Data module
The data module is implemented by the Weather class. This class provides the
content information of a weather prediction. The information contained in a
weather prediction is:
򐂰 The wind direction in an eight-point compass
򐂰 The wind speed in kilometers per hour
򐂰 The temperature in degrees Celsius
򐂰 The weather condition: sunny, partly cloudy, cloudy, rainy, stormy
򐂰 The date of the prediction
Back-end module
The back-end module is implemented by the WeatherPredictor class. This class
is responsible for making the simulated prediction about the weather conditions
using random values.

Information flow
The internal flow of the system information is shown in Figure 12-1.
create the
Weather elements
2
populate the
Weather elements
Weather
Weather
Weather
Weather 4
Weather
request weather
information
Weather
Client 1 3 Weather
Forecast
Weather
Weather
request the Predictor
Weather
Weather weather prediction
return the Weather elements

with the weather prediction
5
Figure 12-1 Weather forecast flow behavior
The steps for this flow are:

1. A client requests weather information from the WeatherForecast.
2. The WeatherForecast creates a Weather element (or elements) for the
response to the client weather request.
3. The WeatherForecast requests the weather prediction from the
WeatherPredictor, one Weather element at a time.
4. The WeatherPredictor creates the weather prediction and populates the
Weather element with that information.
5. The WeatherForecast provides 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.
Chapter 12. Weather forecast application 189

Base code
In this section we list the base code of the three modules.
Weather class
The Weather class is shown in Example 12-1.
Example 12-1 Weather class

package itso.wsoj;
import java.io.Serializable;
import java.text.SimpleDateFormat;
import java.util.Date;
/**
* class Weather
* This class encapsulate some weather artifacts for a specific day
*/
public class Weather implements Serializable {
private String windDirection = null;

private int windSpeed = 0;
private int temperatureCelsius = 0;
private String condition = null;
private Date date = null;
/**
* Default Constructor for Weather.
* initialize with today's date
*/
public Weather() {
super();
date = new Date();
}
/**
* Constructor for Weather.
* Initialize with a given date
* @param theDate
*/
public Weather(Date theDate) {
super();
date = theDate;
}
/**
* @see java.lang.Object#toString()

* used for debugging and testing purposes only
*/
public String toString() {
SimpleDateFormat sdf = new SimpleDateFormat("EEE. MMM d, yyyy");
return "Weather: "
+ sdf.format(date)
+ " '"
+ condition
+ "' wind: "
+ windDirection
+ " "
+ windSpeed
+ "km/h "
+ temperatureCelsius
+ " Celsius";
}
/**
* Returns the condition.
* @return String
*/
public String getCondition() {
return condition;
}
/**
* Returns the date.
* @return Date
*/
public Date getDate() {
return date;
}
/**
* Returns the windDirection.
* @return String
*/
public String getWindDirection() {
return windDirection;
}
/**
* Returns the windSpeed.
* @return int
*/
public int getWindSpeed() {
return windSpeed;
}

/**
* Sets the condition.
* @param condition The condition to set
*/
public void setCondition(String condition) {
this.condition = condition;
}
/**
* Sets the date.
* @param date The date to set
*/
public void setDate(Date date) {
this.date = date;
}
/**
* Sets the windDirection.
* @param windDirection The windDirection to set
*/
public void setWindDirection(String windDirection) {
this.windDirection = windDirection;
}
/**
* Sets the windSpeed.
* @param windSpeed The windSpeed to set
*/
public void setWindSpeed(int windSpeed) {
this.windSpeed = windSpeed;
}
/**
* Returns the temperatureCelsius.
* @return int
*/
public int getTemperatureCelsius() {
return temperatureCelsius;
}
/**
* Sets the temperatureCelsius.
* @param temperatureCelsius The temperatureCelsius to set
*/
public void setTemperatureCelsius(int temperatureCelsius) {
this.temperatureCelsius = temperatureCelsius;
}
}

Weather forecast class
The WeatherForecast class is shown in Example 12-2.
Example 12-2 WeatherForecast class

package itso.wsoj;
import java.io.Serializable;
import java.util.*;
/**
* class WeatherForecast
* This class is the main entry point into this service.
* It offers three different methods to query the weather.
* The three signatures represent three different "challenges" for the Web
* service, which are:
* - a complex type
* - an array
* - the combination of both
*/
public class WeatherForecast {
/**
* Constructor for WeatherForecast.
*/
public WeatherForecast() {
super();
}
/**
* Method getDayForecast returns one complex weather object for a day
* @param theDate
* @return Weather
*/
public Weather getDayForecast(Date theDate) {
// create a weather object and initialize with concrete day
Weather w = new Weather(theDate);
// fill with values from the predictor
WeatherPredictor.calculateWeatherValues(w);
return w;
}
/**
* Method getWeekTemperatures returns an array with 7 temperatures
* for the week following the start date.
* @param startDate
* @return int[]

*/
public int[] getWeekTemperatures(Date startDate) {
// ask predictor for an array for the given date
return WeatherPredictor.calculateTemperatureValues(startDate);
}
/**
* Method getWeekForecast returns an array with 7 complex objects
* describing the weather conditions for the week after the start date
* @param startDate
* @return Weather[]
*/
public Weather[] getWeekForecast(Date startDate) {
// if nothing is passed then use today's date
if (startDate == null)
startDate = new Date();
Calendar theDate = Calendar.getInstance();
theDate.setTime(startDate);
// create the result array

Weather[] weatherForeCast = new Weather[7];
// for each day in the following week....

for (int i = 0; i < weatherForeCast.length; i++) {
// get the day forecast
Weather w = getDayForecast(theDate.getTime());
// put it into the array
weatherForeCast[i] = w;
// increase day counter
theDate.add(Calendar.DAY_OF_MONTH, 1);
}
return weatherForeCast;
}
/**
* Method main is just used for testing and debugging purposes
* @param args
*/
public static void main(String[] args) {
System.out.println("Testing weekly weather forecast for next week...");
WeatherForecast fc = new WeatherForecast();
Weather[] theForecast = fc.getWeekForecast(new Date());
for (int i = 0; i < theForecast.length; i++) {
System.out.println(theForecast[i]);
}
}
}

Weather predictor class
The WeatherPredictor class is shown in Example 12-3.
Example 12-3 WeatherPredictor class

package itso.wsoj;
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 {
// 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 calculateTemperatureValues.
* This method takes a startdate and returns an array of temperatures for
* the following week
* @param startDate
* @return int[]
*/
public static int[] calculateTemperatureValues(Date startDate) {
// ignore startDate because this is only simulation !
int[] values = new int[7];
for (int i = 0; i < 7; i++) {
values[i] = random.nextInt(50) + 10;
}
return values;
}
/**
* 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)]);
}
}
Summary
In this chapter, we covered the weather forecast example used in the following
chapters to show how 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 following chapters, 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 13, “WebSphere Studio Application Developer” on page 197
provides an implementation using WebSphere Studio Application Developer.
򐂰 Chapter 14, “Application Developer Integration Edition” on page 241 provides
an implementation using WebSphere Studio Application Developer
Integration Edition.
򐂰 Chapter 15, “WebSphere SDK for Web Services” on page 281 provides an
implementation using the WebSphere SDK for Web Services.
򐂰 Chapter 16, “Web Services Toolkit” on page 301 provides an implementation
using the Web Services Toolkit.
򐂰 Chapter 17, “WebSphere Web Services Technology Preview” on page 317
provides an implementation using the Web Services Technology Preview.

13
Chapter 13. WebSphere Studio

Application Developer
This chapter describes the features of WebSphere Studio Application Developer
Version 5 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 Programming Guide, SG24-6585 (although this redbook is
about Version 4) 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
򐂰 Creating a Web service in a top-down fashion
򐂰 Exploring and publishing to a UDDI directory from WebSphere Studio
Application Developer

Overview
WebSphere Studio Application Developer provides a tool box 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:
1. Create a Web project
2. Create or import an artifact to be turned into a Web service
3. Create a Web service
4. Create a proxy and a test client
5. 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 already pointed out in Chapter 11, “Web services development overview” on
page 175, 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).

򐂰 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.
򐂰 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 can also be generated in bottom-up and
top-down approaches for testing of the generated Web service.
In summary, the tool offers many opportunities to create Web services from
bottom-up (starting from server-side code to generated the WSDL document and
the proxy code), but only limited opportunities to generate a service from
Chapter 13. WebSphere Studio Application Developer 199

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 or with the Technology Preview (see Chapter 14, “Application
Developer Integration Edition” on page 241 and Chapter 17, “WebSphere Web
Services Technology Preview” on page 317).
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 next four sections we focus on the following scenarios:
򐂰 Bottom-up development by generating a Web service from a JavaBean
򐂰 Top-down development by generating a JavaBean from an existing WSDL
򐂰 Bottom-up generation of a Web service from a URL
򐂰 Bottom-up Web service generation from DADX
In these scenarios, we do not focus on a dynamic invocation; this will be covered

in Chapter 18, “Web services scenario: architecture and implementation” on
page 353. For other types of Web service generation, refer to the online
documentation of Application Developer.
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 12, “Weather forecast application”
on page 187.
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 generated test
JSPs, the universal test client, and the built-in WebSphere test environment.
Importing the WAR file

The weather forecast code is provided as a Web project. Before we can work
with the bean, we must import the WAR file that contains the sample application

into a new Web project in the Workbench. Obviously, we can also generate a
new project from scratch and add the JavaBeans manually.
To import the WAR file, follow these steps in the Web perspective:
򐂰 Select File -> Import to open the Import wizard, then select WAR file and click
Next to open the import window (Figure 13-1).
򐂰 Enter the file name in the WAR file field. You can click Browse to locate and
select the file ItsoWebServADWEB.war file from the downloaded sample code
(d:\sg246891\sampcode\wsad\bottom-up\ItsoWebServADWEB.war).
򐂰 For the Web project select New and enter ItsoWebServADWEB as the project
name.
򐂰 For the enterprise application select New and enter ItsoWebServEAR as the
project name.
򐂰 Click Finish and the Web and EAR projects are created.
..code\wsad\bottom-up\ItsoWebServADWEB.war
Figure 13-1 Importing a WAR file

You can find the three imported Java classes ( Weather, WeatherForecast, and
WeatherPredictor) in the itso.wsoj package under Java Source in the Web
project.
Test the weather forecast application

You can test the application by selecting the WeatherForecast.java file in the
Java perspective and select Run -> Run as -> Java Application. The random
output is displayed in the Console view:
Testing weekly weather forecast for next week...
Weather: Mon. Jan 6, 2003 'stormy' wind: NE 21km/h 25 Celsius
Weather: Tue. Jan 7, 2003 'cloudy' wind: NE 39km/h -1 Celsius
Weather: Wed. Jan 8, 2003 'partly cloudy' wind: SW 1km/h 33 Celsius
Weather: Thu. Jan 9, 2003 'rainy' wind: SE 5km/h 31 Celsius
Weather: Fri. Jan 10, 2003 'sunny' wind: SE 26km/h -3 Celsius
Weather: Sat. Jan 11, 2003 'partly cloudy' wind: W 6km/h -4 Celsius
Weather: Sun. Jan 12, 2003 'partly cloudy' wind: SW 3km/h 0 Celsius
Next we create the weather forecast Web service using the Web service wizard.
Creating the Web service

To create the Web service, including the WSDL document, deployment
descriptor, proxy, and test sample, we use the Web Service wizard.
Select 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 window.
Web service wizard

From the Web service type drop-down menu, select Java bean Web service.
Ensure that Start Web service in Web project is selected (this will start the
server). Select all the following check boxes:
򐂰 Generate a proxy (for testing)
򐂰 Test the generated proxy
򐂰 Overwrite files without warning
򐂰 Create folders when necessary
From the Client proxy type drop-down menu, ensure that Java proxy is selected.
Figure 13-2 shows the window after making these selections.

Figure 13-2 Web service wizard
Deployment Settings
The Web Service Deployment Settings page allows you to select from supported
runtime protocols and deployment servers. Make sure that ItsoWebServADWEB is
selected as the Web project.
Java Bean Selection

The Web Service Java Bean Selection page allows you to specify the Java bean
to be turned into a Web service. Click Browse files (or Browse classes) and
locate the itso.wsoj.WeatherForecast from the Java Source folder and click OK.
Java Bean Identity

In the Web Service Java Bean Identity page, you specify the Web service
uniform resource identifier (URI), scope, and the names of the generated files.
We now briefly describe the options before we continue:
򐂰 Web service URI—A URI is a name that uniquely identifies a Web service to a
client. The URI for the Web service is automatically generated by the wizard
from the artifact you selected to turn into a Web service:
http://tempuri.org/itso.wsoj.WeatherForecast

You could overwrite the default name, for example, urn:WeatherForecast, but
we leave the default name.
򐂰 Web service scope—Three alternatives are available to define the scope of
the Web service:
– Request: A new service bean is constructed by the server for each SOAP
request. The object is available for the duration of the request.
– Session: One service bean is constructed by the server for each new
client session to the Web service, and is maintained by sending cookies to
the client side. The bean is available for the duration of the session in a
similar way to HTTP session data.
– Application: A single instance of the service bean is constructed for the
life of the Web application. This is the best option for good performance,
but requires that the JavaBean is written in reentrant fashion so that
multiple requests can run through the code in parallel. This is the default
for a JavaBean.
This information will be part of the deployment descriptor for the Web
service.
򐂰 Use static methods—If this option is selected, the bean’s static methods
become Web service operations and no object is instantiated.
򐂰 Enable SOAP security—The Web service wizard also provides an option to
apply security to the SOAP router servlet when deploying the Web services in
the project to a WebSphere instance and configuration.
Because one instance of the SOAP router exists for each Web application
(WAR file), this option can only be edited when creating the first Web service
for the project. When creating further Web services with the Web service
wizard, this option will be disabled, showing the status of the first selection.
This can be changed manually after generation by editing the deployment
descriptor (web.xml).
򐂰 The generated files include the ISD file and four WSDL files.
Java Bean Methods

The Web Service Java Bean Methods page (Figure 13-3) shows a summary of
public methods in your bean. For the example we select all methods, except for
the main method, which has only been provided for server-side testing purposes.
Also, select Show server (Java to XML) type mappings.
When you select a method, the input and output encoding are displayed. The
encoding style defines how the Java types in the client and server are mapped to
the XML types in the SOAP message:
򐂰 For all three methods, SOAP encoding is selected by default. SOAP encoding
covers all basic data types as well as JavaBeans containing basic data types.

򐂰 Literal XML encoding would be used for a document object model (DOM)
element (org.w3c.dom.Element). The XML source is then inserted directly into
the SOAP message.
Figure 13-3 Method selection
Java to XML Mappings

In the Web Service Java to XML Mappings page, review the Web service type
mappings. At runtime, the mappings govern serialization and deserialization.
Figure 13-4 illustrates the mappings between Java and XML for the Web service
to operate, assuming both a Java client and a Java server.
Input encoding style
Java to XML XML to Java

1 mapping 2 mapping
SOAP
Client Proxy messages Server
XML to Java Java to XML
4 mapping 3 mapping
Output encoding style
Figure 13-4 Mapping and encoding stages for a Web service

There are four steps in the process, indicated by the numbers in Figure 13-4:
1. Client input mapping (Java to XML)—This takes the parameter from the Java
client and maps it using the input encoding style.
2. Server input mapping (XML to Java)—The inbound parameters are
deserialized from the SOAP encoding 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 encoding 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.
The current page of the wizard shows the language mapping from Java types to
XML types (Figure 13-5).
Figure 13-5 Defining Java to XML bindings

Note: The types that are displayed are method input parameters (Date),
method results ( Weather, Weather[], int[]), as well as data types inside the
Weather bean (int, String).
Binding Proxy Generation

In the Web Service Binding Proxy Generation page, review the bindings that are
used in the WSDL. The client proxy provides a remote procedure call interface to
your Web service. Using the proxy, the application calls a remote method on the
Web service as if the method were a local one. Once the application makes the
remote call, the proxy handles all of the communication details between the
application and the Web service using SOAP.
Note that the proxy is generated into a separate Web project named
ItsoWebServADWEBClient. You could overtype the default project name. The
name of the proxy defaults to proxy.soap.WeatherForecastProxy. Select the
Show mappings check box.
XML to Java Mappings

In the Web Service XML to Java Mappings page (Figure 13-6), review the
mapping for deserialization from XML to Java types. For each XML type, the Java
type is displayed in the Class field.
Figure 13-6 Defining XML to Java bindings

SOAP Binding Mapping Configuration
In the Web Service SOAP Binding Mapping Configuration page, review the Web
service SOAP binding mapping configuration. These are set based on our
previous definitions in the wizard and cannot be changed in our example.
Test
In the Web Service Test page (Figure 13-7) you decide which facility to use to
test the Web service. The choices are:
򐂰 Web service sample JSPs—Generates a set of four JSPs into the folder
sample/WeatherForecast in the client Web project (default).
򐂰 Web tools Java bean JSPs—Generates an HTML page, a result JSP, and a
ViewBean class into the client Web project. Note that not all data types are
supported in this option.
򐂰 Universal Test Client—The universal test client is started and the proxy bean
is instantiated. In “Testing the Web service” on page 213, we describe in
detail the functionality of that test client.
The WebSphere v5.0 Test Environment is used as the server.
Figure 13-7 Testing options for the Web service

Publication
In the Web Service Publication page you can publish the Web service to a UDDI
registry. We describe publishing in detail in “Publishing and exploring a UDDI
registry” on page 233. For now, leave the boxes unchecked and click Finish.
The Web service is deployed in the Web project and the Web project is deployed
to a WebSphere test server:
򐂰 A server is created: WebSphere v5.0 Test Environment.
򐂰 The enterprise application is added to the configuration.
򐂰 The sample JSP test client is launched to test the Web service.
򐂰 The Web Service Explorer is launched in an external Web browser to publish
the Web service (only if you select publishing in the last step of the wizard).
If you have problems creating the Web service, consult the online documentation
and the d:\workspace\.metadata\.log file.
Generated files
Before we test the Web service, let’s look at the generated files (Figure 13-8).
JavaBean
Proxy
Admin
application
ISD
file test
sample
WSDL
and
XSD
files
deployment
descriptor
Server project Client project
Figure 13-8 J2EE Navigator view after the generation of the Web service

The Web service is installed in the ItsoWebServADWEB project and the proxy and
sample test client are in the ItsoWebServADWEBClient project.
Files generated in the server Web project

According to the settings made during the run of the wizard, the following files in
the ItsoWebServADWeb project have been created:
򐂰 The Web service deployment descriptor WeatherForecast.isd in Web
Content/WEB-INF/isd/java/itso/wsoj provides information about the
services that should be made available to clients. This information is then
used by the SOAP runtime.
򐂰 The Web Content/WEB-INF/lib folder is extended with three library files that
are part of the SOAP runtime code:
– soapcfg.jar
– webservice-runtime.jar
– xsd.bean.runtime.jar
򐂰 The Web Content folder contains the admin folder where SOAP administration
can be performed (select the index.html and Run on server).
򐂰 In the Web Content folder, a new folder wsdl/itso/wsoj contains the WSDL
files, as described in Chapter 3, “Introduction to WSDL” on page 41:
– WeatherForecast.wsdl—service interface
– WeatherForecastBinding.wsdl—service binding
– WeatherForecastJava.wsdl—service binding for Java (for WSIF)
– WeatherForecastService.wsdl—service implementation
In our example, we have used complex data types. Therefore, two XSD files
were also generated that specify the mapping between Java and XML:
– Weather.xsd defines how the Java Weather object is mapped to XML.
– WeatherForecast.xsd defines how the method results in the
WeatherForecast class are mapped to XML by introducing two
complexTypes ArrayOfWeather and ArrayOfInt.
򐂰 Finally, the Web Content folder itself contains the files:
– dds.xml, the deployment descriptor for SOAP, a concatenation of all the
ISD files (only one for now)
– soap.xml, the Apache SOAP server configuration file
Files generated in the client Web project

If the creation of a client-side proxy is selected, Application Developer generates
two classes in the new ItsoWebServADWebClient project:

򐂰 itso.wsoj.Weather contains the Weather object, mapped from the XML
representation into a Java class.
򐂰 proxy.soap.WeatherForecastProxy is the proxy class that contains the
methods getDayForecast, getWeekForecast, and getDayTemperature. These
methods can now be locally invoked by a client (see “Writing a client” on
page 218).
The test client is generated into the Web Content/sample/WeatherForecast folder.
Client Weather class

The generated client-side Weather class (Figure 13-9) is similar to the original
Weather class (Example 12-1 on page 190).
...
public class Weather extends AnyType
{
public Weather()
{
addElement("date", java.util.Date.class);
addElement("temperatureCelsius", java.lang.Integer.class);
addElement("windSpeed", java.lang.Integer.class);
addElement("windDirection", java.lang.String.class);
addElement("condition", java.lang.String.class);
}
public Date getDate()

{
return (Date)this.basicGet("date", 0);
}
public void setDate(Date date)

{
this.basicSet("date", 0, date);
}
public int getTemperatureCelsius()

{
Integer result = (Integer)this.basicGet("temperatureCelsius", 0);
return result == null ? 0 : result.intValue();
}
public void setTemperatureCelsius(int temperatureCelsius)

{
this.basicSet("temperatureCelsius", 0, new Integer(temperatureCelsius));
}
......
}
Figure 13-9 Generated weather class (extract)

Proxy class
Figure 13-10 shows the getDayForecast method of the proxy class as an
example of the processing in the proxy.
public class WeatherForecastProxy

{
private Call call;
private URL url = null;
private String stringURL =
"http://localhost:9080/ItsoWebServADWEB/servlet/rpcrouter";
private java.lang.reflect.Method setTcpNoDelayMethod;
......
public synchronized itso.wsoj.Weather getDayForecast(java.util.Date theDate)

throws Exception {
String targetObjectURI = "http://tempuri.org/itso.wsoj.WeatherForecast";
String SOAPActionURI = "";
if(getURL() == null) {
throw new SOAPException(Constants.FAULT_CODE_CLIENT,
"A URL must be specified via WeatherForecastProxy.setEndPoint(URL).");
}
call.setMethodName("getDayForecast");
call.setTargetObjectURI(targetObjectURI);
Parameter theDateParam = new Parameter("theDate", java.util.Date.class, theDate,
Constants.NS_URI_SOAP_ENC);
params.addElement(theDateParam);
Response resp = call.invoke(getURL(), SOAPActionURI); <==== Web service call
//Check the response.

if (resp.generatedFault())
{
Fault fault = resp.getFault();
call.setFullTargetObjectURI(targetObjectURI);
throw new SOAPException(fault.getFaultCode(), fault.getFaultString());
}
else
{
Parameter refValue = resp.getReturnValue();
return ((itso.wsoj.Weather)refValue.getValue());
}
}
......
Figure 13-10 Generated proxy class (extract)
A Call object is filled with the method name, encoding style, target URI, and
parameters. The Web service is invoked and the result examined. A good result
is converted into the required return type.

Testing the Web service
There are several ways to test the generated proxy code. We present two ways:
the first one is a small JSP application that has been generated, depending on
the selection in the wizard. The second uses the built-in universal test client.
Using the test JSPs

By selecting Test the generated proxy in the Web services wizard (Figure 13-7 on
page 208), the sample test client is started in a browser pane with this URL:
http://localhost:9080/ItsoWebServADWEBClient/sample/WeatherForecast/TestClient.jsp
If the browser does not launch automatically, follow these steps:

򐂰 Select the TestClient.jsp in sample/WeatherForecast and Run on Server
(context).
򐂰 In the Select Server window, select Use an existing server and select the
WebSphere v5.0 Test Environment server. Also select Set server as project
default, then click Finish.
Figure 13-11 shows the sample test client in the internal browser. You can also
type the URL into an external browser.
Figure 13-11 Starting the sample test client

To examine the methods of the sample Web application, select any of the three
methods, getDayForecast, getWeekForecast, and getWeekTemperatures, enter a
date, and click Invoke. Figure 13-12 display the results of the invocation of the
getDayForecast method.
Figure 13-12 Result of the sample test client
The getWeekTemperatures method displays an array of temperatures, for

example:
[35,45,12,13,24,59,45]
Note that the getWeekForecast method returns an array of Weather objects.

These are not displayed in detail when using the sample test client:
[itso.wsoj.Weather@c0761aa, itso.wsoj.Weather@366161ad,
itso.wsoj.Weather@6673e1ad, itso.wsoj.Weather@4e6da1ad,
itso.wsoj.Weather@5fe221ad, itso.wsoj.Weather@2c84a1ad,
itso.wsoj.Weather@312e61ad]

Improving the output
The Result.jsp produces the formatted output. It can be used in real clients as a
model. The code shows how the proxy is used to invoke the Web services, and
how output can be formatted into HTML.
For example, we can improve the output of the getWeekForecast method:

򐂰 Locate and edit the Result.jsp.
򐂰 Scan the source code and locate the section for the getWeekForecast method.
򐂰 Change the code as follows (the new code is shown in bold):
}else if (method.equals("getWeekForecast(java.util.Date)")) {
gotMethod = true;
String startDate2id= markup(request.getParameter("startDate28"));
java.text.DateFormat dateFormatstartDate28 = ......;
java.util.Date startDate2idTemp= ......;
itso.wsoj.Weather[] mtemp = ......;
if(mtemp == null){
%>
<%=mtemp %>
<%
}else{
java.util.List listresult26= java.util.Arrays.asList(mtemp);
String tempresult26 = listresult26.toString();
%>
<%=tempresult26%>
<TABLE border="1">
<TR>
<TH>Date</TH><TH>Temperature</TH><TH>Wind</TH><TH>Condition</TH>
</TR>
<% for (int i=0; i<mtemp.length; i++) {
itso.wsoj.Weather w = mtemp[i]; %>
<TR>
<TD><%= w.getDate().toString().substring(0,11) %></TD>
<TD><%= w.getTemperatureCelsius() %></TD>
<TD><%= w.getWindDirection() %> <%= w.getWindSpeed() %></TD>
<TD><%= w.getCondition() %></TD>
</TR>
<% } %>
</TABLE>
<%
}

򐂰 Figure 13-13 shows the improved output.
Figure 13-13 Output of improved test client
Using the universal test client

The universal test client (UTC) allows you to load classes, instantiate objects,
and run methods on those objects.
By selecting Universal Test Client in the Web services wizard (Figure 13-7 on
page 208), the universal test client is started in a browser pane with this URL:
http://localhost:9080/UTC/preload?object=proxy.soap.WeatherForecastProxy
To start the universal test client manually to test the Web service, select the
WeatherForecastProxy in Java Source/proxy/soap and Launch Universal Test
Client (context). This starts the program and instantiates the proxy object.
To test the getDayForecast method, follow these steps:

򐂰 Expand WeatherForecastProxy in the References pane to display all of the
methods of the weather forecast Web service. Select the getWeatherForecast
method, enter a date, and click Invoke. The result is displayed in abbreviated
form (Figure 13-14).

Figure 13-14 Using the universal test client to invoke a method
򐂰 To see the full result, click Work with Object. Expand the Weather object and
select Inspect Fields (Figure 13-15).
Figure 13-15 Inspecting fields in the universal test client

򐂰 Select the getWeekForeCast method, enter a date, click Invoke and Work with
Object (Figure 13-16). Expand the resulting Weather[7] array and select
Inspect Fields to see the details of the seven weather forecast objects.
You can also invoke any of the getter methods (getWindSpeed) to see
individual result values.
Figure 13-16 Working with a result array
Writing a client
In this section we develop a small Java client application that invokes the three
methods of the Web service using the proxy.
To incorporate client code you have to create or use a suitable project in which
you develop the client code; in our case we use the ItsoWebServADWEBClient
project. Figure 13-17 shows the client program:
򐂰 The main method invokes the three Web services.
򐂰 The niceFormat method is used to format a Weather object.

package itso.wsad;
import itso.wsoj.Weather;
import proxy.soap.WeatherForecastProxy;
public class WeatherForecastClient {
public static String niceFormat(Weather weather) {
return ("Weather: "
+ sdf.format( weather.getDate() ) + " '"
+ weather.getCondition() + "' wind: "
+ weather.getWindDirection() + " "
+ weather.getWindSpeed() + "km/h "
+ weather.getTemperatureCelsius() + " Celsius");
}
WeatherForecastProxy fcp = new WeatherForecastProxy();
try {
System.out.println(
"Remotely testing weather forecast for today...");
Weather dayForecast = fcp.getDayForecast(new Date());
System.out.println(niceFormat(dayForecast));
System.out.println(
"Remotely testing weather forecast for next week...");
Weather[] weekForecast = fcp.getWeekForecast(new Date());
for (int i = 0; i < weekForecast.length; i++) {
System.out.println(niceFormat(weekForecast[i]));
}
System.out.println(
"Remotely testing temperatures for next week...");
int[] weekTemperatures = fcp.getWeekTemperatures(new Date());
for (int i = 0; i < weekTemperatures.length; i++) {
System.out.print(" " + weekTemperatures[i]);
}
System.out.print(" Celsius");
} catch (Exception e) {
System.out.println("Something went wrong!" + e);
}
}
}
Figure 13-17 Simple Web service client
To incorporate this example, perform these steps:

򐂰 Locate the WeatherForecastClient.java file in the sample code.
򐂰 Create a package named itso.wsad under Java Source in the
ItsoWebServADWEBClient project.
򐂰 Select the new package and Import (context). Select File system, click Next,
and import the client program.

To run the application, the class path has to be extended:
򐂰 Select the ItsoWebServADWEBClient project and Properties (context).
򐂰 Select Java Build Path and go to the Libraries page (Figure 13-18).
򐂰 Click Add Variable, select the MAILJAR variable, and click OK.
򐂰 Click OK to close the properties window.
Figure 13-18 Setting the Java build path
Now you can run the server and client code.

򐂰 Start the WebSphere v5.0 Test Environment server from the Server
perspective (if the server was stopped). Wait until the server has started and
displays Server x open for e-business in the Console view.
򐂰 In the Java perspective, select the WeatherForecastClient and Run -> Run
As -> Java Application and enjoy the result in the Console view:
Remotely testing weather forecast for today...
Weather: Mon. Jan 6, 2003 'stormy' wind: SE 39km/h 18 Celsius
Remotely testing weather forecast for next week...
Weather: Mon. Jan 6, 2003 'sunny' wind: N 5km/h 10 Celsius
Weather: Tue. Jan 7, 2003 'stormy' wind: N 32km/h 0 Celsius
Weather: Wed. Jan 8, 2003 'rainy' wind: SE 15km/h 31 Celsius
Weather: Thu. Jan 9, 2003 'stormy' wind: N 20km/h 29 Celsius
Weather: Fri. Jan 10, 2003 'cloudy' wind: N 18km/h -7 Celsius
Weather: Sat. Jan 11, 2003 'partly cloudy' wind: NE 33km/h 24 Celsius
Weather: Sun. Jan 12, 2003 'stormy' wind: N 2km/h 39 Celsius
Remotely testing temperatures for next week...
26 21 51 27 11 51 19 Celsius

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 very
practical 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 TCP Monitor as name, select TCP/IP Monitoring Server as
server type, and click Finish.
Change the proxy

To intercept the SOAP messages, we change the proxy to send the requests to
port 9081 (instead of 9080).
Edit the WeatherForecastProxy class in the ItsoWebServADWEBClient project and

change the target URL:
Start the servers

Start the TCP Monitor server and the WebSphere v5.0 Test Environment server.
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.

TCP/IP Monitor view
The output of the TCP/IP Monitor is displayed in the TCP/IP Monitor view
(Figure 13-19).
Figure 13-19 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. The SOAP input message for the getDayForecast
operation is:
<SOAP-ENV:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<SOAP-ENV:Body>
<ns1:getDayForecast
xmlns:ns1="http://tempuri.org/itso.wsoj.WeatherForecast"
<theDate xsi:type="xsd:dateTime">2003-01-07T08:00:00.000Z</theDate>
</ns1:getDayForecast>
</SOAP-ENV:Body>

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:
<SOAP-ENV:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<SOAP-ENV:Body>
<ns1:getDayForecastResponse
xmlns:ns1="http://tempuri.org/itso.wsoj.WeatherForecast"
<return xmlns:ns2="http://wsoj.itso/" xsi:type="ns2:Weather">
<date xsi:type="xsd:dateTime">2003-01-07T08:00:00.000Z</date>
<temperatureCelsius xsi:type="xsd:int">3</temperatureCelsius>
<windSpeed xsi:type="xsd:int">1</windSpeed>
<windDirection xsi:type="xsd:string">N</windDirection>
<condition xsi:type="xsd:string">partly cloudy</condition>
</return>
</ns1:getDayForecastResponse>
</SOAP-ENV:Body>
The SOAP response for getWeekForecast is an array of seven weather objects,

and the response for getWeekTemperatures is an array of 7 integers:
<SOAP-ENV:Envelope ........>
<SOAP-ENV:Body>
<ns1:getWeekTemperaturesResponse .....>
<return xmlns:ns2="http://schemas.xmlsoap.org/soap/encoding/"
xsi:type="ns2:Array" ns2:arrayType="xsd:int[7]">
<item xsi:type="xsd:int">39</item>
</return>
</ns1:getWeekTemperaturesResponse>
</SOAP-ENV:Body>
Target URL
Do not forget to reset the target URL in the WeatherForecastProxy class. Note
that you can change the target URL dynamically by invoking the setEndpoint
method of the proxy object. This eliminates the change in the source code.

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 section, we could omit them. Generating the
proxy enables us to test the new Web service.
Create a Web project 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. For our
scenario, we start by creating a new ItsoWebServADWEBBean Web project:
򐂰 Select File -> New -> Project -> Web -> Web Project.
򐂰 Enter ItsoWebServADWEBBean as a project name. Make sure that J2EE Web
project is selected. Click Next.
򐂰 For the enterprise application project, select Existing and browse to
ItsoWebServEAR.
򐂰 The Module Dependencies page allows you to select dependent JARs for the
new module. Because there are none in our scenario, click Finish.
򐂰 Click OK in the Repair Server Configuration window to add the Web project to
the server.
Next we import the WSDL files into the new project:

򐂰 Create a new folder named wsdl under Web Content.
򐂰 Select the wsdl folder and Import (context). Select File system and locate the
\sg246891\sampcode\wsad\top-down\wsdl folder. Import all the WSDL and
XSD files.
Create the skeleton JavaBean

Now we can run the Web services wizard to create the Java code.
򐂰 Select File -> New -> Other -> Web Services Web Service on the right pane.
Click Next.
򐂰 In the Web Services page, select Skeleton Java bean Web service. Optionally
select Generate a proxy and Test the generated proxy. Click Next.
򐂰 In the Web Service Deployment Settings page, make sure to select the
ItsoWebServWSADWebBean project. Click Next.

򐂰 In the Web Service WSDL File Selection page, click Browse to locate the
WSDL document. In cases where the WSDL document is split into several
files, select either the binding (XxxxBinding.wsdl) or the service
(XxxxService.wsdl) file. In our example we do not provide the service file;
therefore select the binding file:
/ItsoWebServADWEBBean/Web Content/wsdl/WeatherForecastBinding.wsdl
Note: The service file contains the location where the service runs. This is
not required to create the skeleton JavaBean. All that is required is the
binding and the interface. The service file is generated for us.
򐂰 In the Web Service Skeleton Java Bean Configuration page, change the
skeleton class name to itso.service.WeatherForecast. Note that the WSDL
service document is generated into its own folder:
/ItsoWebServADWEBBean/Web Content/wsdl/service/WeatherForecastService.wsdl
򐂰 In the Web Service Building proxy Generation page, change the project name
to ItsoWebServADWEBBean (we don’t want an extra test project).
򐂰 In the Web Service Test page, select Web service sample JSPs. Leave the
other defaults.
򐂰 In the Web Service Publication page, click Finish.
Generated files
The generated files include:
򐂰 itso.service.WeatherForecast—The skeleton JavaBean
򐂰 itso.wsoj.Weather—The weather bean (same as in the bottom-up approach)
򐂰 proxy.soap.WeatherForecastProxy—The proxy bean
򐂰 The admin folder with the SOAP administrative application
򐂰 The WEB-INF/isd folder with the WeatherForecast.isd file
򐂰 The wsdl/service folder with the WeatherForecastService.wsdl file
If you started with an existing service file, then this file is the new service file
for your installation.
򐂰 The sample/WeatherForecast folder with the sample test client.
򐂰 The dds.xml deployment descriptor.
Implementing the JavaBean

Figure 13-20 shows the generated skeleton JavaBean code.

package itso.service;
import org.w3c.dom.*;
public class WeatherForecast

{
public itso.wsoj.Weather getDayForecast(java.util.Date theDate)
{
// implement your code here
return null;
}
public itso.wsoj.Weather[] getWeekForecast(java.util.Date startDate)

{
return null;
}
public int[] getWeekTemperatures(java.util.Date startDate)

{
return null;
}
Figure 13-20 Generated skeleton JavaBean
To implement a real server, replace the skeleton code with the implementation
that we provide in the sample code (WeatherForecast and WeatherPredictor):
򐂰 Select the itso.service package and Import (context). Select File system
and locate the \sg246891\sampcode\wsad\top-down\bean folder.
򐂰 Select the WeatherForecast and WeatherPredictor files. Be sure to select
Overwrite existing resources without warning.
These two files are basically the same as in the bottom-up solution. The minor
differences are:
򐂰 The package name is itso.service (instead of itso.wsoj).
򐂰 An import for the generated itso.wsoj.Weather class is added.
򐂰 The WeatherForecast code to instantiate a Weather object is changed:
old: Weather w = new Weather(theDate);
new: Weather w = new Weather(); w.setDate(theDate);
The generated Weather class does not have the Weather(Date) constructor.

Testing the service
After restarting the server, you can test the new service by selecting the
TestClient.jsp and Run on Server. The service reacts exactly the same as the
bottom-up service.
Tip: If you have to regenerate the client proxy, start the Web service wizard
with File -> New -> Other -> Web Services -> Web Service Client and select
the wsdl/service/WeatherForecastService.wsdl file.
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 the
ItsoWebServADWEB project and then turn it into a Web service.
Creating the servlet

To create the servlet and import the existing code into the Web project:
򐂰 In the Web perspective, select the Java Source folder and New -> Servlet
(context).
򐂰 Enter itso.wsoj.servlet as the package name and WeatherForecastServlet
as the class name.
򐂰 Select doGet and doPost methods, and make sure Add to web.xml is selected.
Click Finish.
򐂰 The servlet opens in the editor. Replace the code with the source provided in
\sg246891\sampcode\wsad\url\WeatherForecastServlet.java.
򐂰 Note that the servlet has been added to the deployment descriptor (web.xml).
The servlet accepts one parameter called method, with values day, week, or
weektemp, to invoke the three functions of the weather forecast application.

Running the servlet
We can test the servlet by starting the server and invoking the servlet using the
URL:
http://localhost:9080/ItsoWebServADWEB/WeatherForecastServlet
Tip: You can run the servlet by selecting the WeatherForecastServlet.java

file and Run on Server (context).
Figure 13-21 shows a sample run of the servlet.
Figure 13-21 Weather forecast servlet sample run
You can also invoke one of the methods directly with the URL:
http://localhost:9080/ItsoWebServADWEB/WeatherForecastServlet?method=day
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:
򐂰 Start the WebSphere server.
򐂰 Select File -> New -> Other -> Web Services -> Web Service and click Next.

򐂰 Select URL Web Service as service type, and select Start Web service in
Web project, Generate a proxy, and Test the generated proxy. Do not select
Launch the Web Services Explorer. Click Next.
򐂰 Make sure to select ItsoWebServADWEB as the Web project and click Next.
򐂰 In the Web Service URL page, one icon named NewURLWebService is
displayed (Figure 13-22). Starting from this icon we have to build the URL and
parameters to invoke the servlet.
Figure 13-22 URL Web services wizard: start
򐂰 Select the NewURLWebService and Properties (context), replace

NewURLWebService with WeatherForecastServlet in all fields and click OK
(Figure 13-23).
Figure 13-23 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/, and click OK.

򐂰 Select the WeatherPort and Add Operation, expand and a NewOperation is
displayed.
򐂰 Select the NewOperation and Properties. Enter forecast as name,
ItsoWebServADWEB/WeatherForecastServlet as 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 name, leave the
namespace and type, and click OK.
򐂰 Select the Return and Properties, change the mime type from mimeXML to
text/plain. The servlets HTML response is turned into a DOM tree if mimeXML
is chosen.
򐂰 Figure 13-24 shows the final tree.
Figure 13-24 URL Web services wizard: final tree
򐂰 Click Next to go through the pages of the Web services wizard:

– The server is started.
– A proxy named proxy.httpget.WeatherForecastServletProxy is
generated.
– Web service sample JSPs are generated into the folder
sample/WeatherForecastServlet.
򐂰 Click Finish and wait while the wizard generates the code and starts the
server.

Generated files
Note that no Web service is created in the ItsoWebServADWEB project. The servlet
itself is the Web service and it will be invoked directly using the URL we specified
in the wizard.
Two WSDL files are generated into the wsdl folder. Note that there is no separate
file for the service interface; the binding file includes the definition of the interface.
Open the files and study the content:
WeatherForecastServletBinding.wsdl <=== binding and interface
WeatherForecastServletService.wsdl <=== implementation
The rest of the code is generated into the ItsoWebServADWEBClient project:

򐂰 The proxy class: WeatherForecastServletProxy
򐂰 The sample test client folder: sample/WeatherForecastServlet
When you open the proxy class, you can see that the servlet is invoked directly
using HTTP-GET; SOAP is not involved.
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 13-25 shows the generated HTML markup as the result
of the invocation of the servlet with day as the parameter.
Figure 13-25 Result of the invocation of the test JSP

Creating a Web service from DADX
A document access definition extension (DADX) Web service enables you to
wrap the IBM DB2 XML Extender or regular SQL statements inside a standard
Web service. DADX is an XML document format that specifies how to create a
Web service using a set of operations that are defined by document access
definition (DAD) documents and SQL statements. The DADX file defines the
operations available to the DADX runtime environment, and the input and output
parameters for the SQL operation.
DADX group
DADX supports two types of Web service operations: XML collection operations
(in conjunction with DB2 XML Extender) and SQL operations.
A DADX group contains connection (JDBC and JNDI) and other information that
is shared between DADX files. To use DADX files as Web services, the Web
services object runtime framework (WORF) provides the runtime support. WORF
supports the specification of storage and retrieval operations on XML data.
WORF is shipped as part of Application Developer.
Creating a Web service from DADX

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 (for the latter three steps, Application
Developer offers wizards):
1. Create (or identify) the SQL statement to be used for the Web service.
2. Create a DADX Group (by selecting File -> New -> Web Services -> Web
Services DADX Group Configuration ).
3. Create the DADX file from the SQL statement (by selecting File -> New ->
Web Services -> DADX File).
4. Generate the Web service from the DADX file (by selecting File -> New ->
Web Services -> Web Service and then choosing DADX Web Service as the
Web Service type).
We do not provide a detailed scenario here, because such a scenario can be

found in Chapter 14 of the redbook Web Services Wizardry with WebSphere
Studio Application Developer, SG24-6292, and also in the redbook Integrating
your Information, SG24-6892.

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 IBM 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 4, “Introduction to
UDDI” on page 61.
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 18, “Web services scenario: architecture and
implementation” on page 353.
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.
Publishing a business entity

The IBM test registry allows only one business entity to be published per user ID.
If you 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 13-26 shows the status of the Web Services Explorer.
Figure 13-26 Web Services Explorer ready to enter the business entity
򐂰 In the toolbar of the Actions pane, click the Publish icon .

򐂰 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
redbook (Figure 13-27).
Figure 13-27 Web Services Explorer Search
򐂰 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 IBM Web Services Explorer:
򐂰 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 ItsoWebServWSADWEB project, then
select the correct WSDL file, and click Go:
http://localhost:9080/ItsoWebServWSADWEB/wsdl/itso/wsoj/
WeatherForecastService.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.
– 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 13-28 shows the
completed Actions pane.
– When you have finished entering the service information, click Go.
򐂰 The Web Services Explorer is automatically updated with your published Web
service. If your update is successful, the Status pane displays:
Service interface http://wsoj.itso.wsdl/weatherforecastbinding/ was
successfully published.
Service WeatherForecast was successfully published.

Figure 13-28 A Web service ready to be 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 18, “Web
services scenario: architecture and implementation” on page 353 shows how to
dynamically access a UDDI registry.
There are several ways to search for 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:
– In the Name of this query field, you can enter a name for the query you are
about to perform.
– Select Services in the Search for box and enter WeatherForecast in the
Names field.
– Click Go.
򐂰 Figure 13-29 shows the results of the search. Because we have an
informative description, we can easily identify our previously published Web
service as the first one.
Figure 13-29 Results of a UDDI query on weather forecasts
򐂰 Select the service of your choice.

򐂰 Now you can retrieve further information about this service (click the Get
service interfaces icon ) and modify 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 224.
Deployment of the sample application

To deploy the application means to export an EAR file from Application
Developer and install the enterprise application in a WebSphere Application
Server.
Exporting the EAR file

To export the EAR file, select the ItsoWebServEAR 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
ItsoWebServEAR.ear. For WebSphere, the target location is usually the
installableApps directory:
D:\WebSphere\AppServer\installableApps\ItsoWebServEAR.ear
Installing the enterprise application

Installation of enterprise applications into a WebSphere Application Server is
covered in Chapter 19, “Web services runtime and deployment in WebSphere”
on page 401.

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.
Second, we took a WSDL document and generated the server-side code for a
new 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 an insight into the tools provided by
Application Developer. However, that book refers to Application Developer
Version 4, where minor changes apply.
The IBM redbook WebSphere Studio Application Developer Programming Guide,

SG24-6585, provides detailed information about the 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 come with WebSphere Studio Application Developer
provides information and tutorials for creating and using Web services.

14
Chapter 14. Application Developer

Integration Edition
There are several products within the WebSphere Studio family. WebSphere
Studio Application Developer, introduced in the previous chapter, 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
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

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:
򐂰 CICS ECI
򐂰 CICS EPI
򐂰 Host On-Demand 3270
򐂰 IMS
򐂰 Imported customized EIS JCA resource adapters

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 in to 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 14. Application Developer Integration Edition 243

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 14-1 illustrates how resource adapters are used by services to access
legacy systems.
Client Application EIS

Server
Application
Enterprise
Front Service
end
CCI
Legacy
Resource application
adapter and data
native
Figure 14-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.

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 14-2 shows the Business Integration perspective with
two important parts that support Web services:
򐂰 Services view
򐂰 WSDL editor
Figure 14-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).

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 14-3 shows a
page of the WSDL editor viewing the weather forecast sample.
Figure 14-3 WSDL editor in Integration Edition

Note that the Outline view is connected to the editor and allows a quick
navigation within the file. 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 in 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

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 tis 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

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 lists of element with the description in “Business process execution
language for Web services” on page 125.

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 14-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.

Figure 14-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\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.

Existing Web services
The ItsoWebServWFWEB project contains the weather forecast service, the same
service we developed in Chapter 13, “WebSphere Studio Application Developer”
on page 197. 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.
Setup 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 14-5.
Copied from
ItsoWebServWFWeb
Copied from
ItsoWebServTCWeb
Figure 14-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 14-6.

Figure 14-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 14-7.
Figure 14-7 Initial state of new business process

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 14-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.

Figure 14-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 14-9.
input terminal
output terminal
Figure 14-9 Flow between the activities

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 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.
Figure 14-10 illustrates the chain of objects.

Java Variable Java Code or Java Variable
WSDL WSDL in Process Transformer in Process WSDL WSDL
Service A Response Request Service B

Variable1 Converter Variable2
Operation 1 Message 1 Message 2 Operation 2
Service:
Service: getDayForecast int tempC = convertCelsiusTo TemperatureCalculator
WeatherForecast
Operation:
Response Weather object weather. int FahrenheitRequest Operation:
(Weather object) getTemperature() (int) convertCelsius..
getDayForecast
ToFahrenheit
Figure 14-10 Using variables for conversion between messages
򐂰 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 14-11.
򐂰 There is also another—more general—way. You do not select the concrete
Weather.xsd file, because you might even not 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 14-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

(1)
(2)
Figure 14-11 Defining variables for in- and outbound messages of operations

Figure 14-12 shows the variables defined for the getDayForecast service.
Figure 14-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 14-13 shows the complete set of variables in the
Variables tab.
Figure 14-13 Process variables

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—retrieve 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—set the input variable for the getDayForecast
activity by passing a message variable:
public void setGetDayForecastRequest(
wsdl.itso.wsoj.WeatherForecast_msg.GetDayForecastRequestMessage message)
updateBPEVariable("getDayForecastRequest", message.message());
}
򐂰 getGetDayForecastResponse—retrieve the output variable of the
getDayForecast activity:
public wsdl.itso.wsoj.WeatherForecast_msg.GetDayForecastResponseMessage
getGetDayForecastResponse()
return new
wsdl.itso.wsoj.WeatherForecast_msg.GetDayForecastResponseMessage(
(WSIFMessage) readBPEVariable("getDayForecastResponse"));
}

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);
}
}
}
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");
}
public void setResult(itso.wsoj.Weather newValue) {
try {
super.setObjectPart("result", newValue);
}
}
}

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 268.
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 see and update the code that is executed in that process
step.

Figure 14-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 14-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);

򐂰 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 wsdl.itso.wsoj.WeatherForecast_msg.*;
import wsdl.itso.wstc.TemperatureCalculator_msg.*;
import java.util.Calendar;
import 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.

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 14-15) and more Java code is added to the process class.

<definitions name="temperatureInterface"
targetNamespace="http://wsie.itso/"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:interface="http://schemas.xmlsoap.org/wsdl/wsadie/messages/"
xmlns:tns="http://wsie.itso/">
<import
location="/org/xmlsoap/schemas/wsdl/wsadie/messages/BuiltinMessages.wsdl"
namespace="http://schemas.xmlsoap.org/wsdl/wsadie/messages/"/>
<portType name="temperaturePortType">
<operation name="InputOperation">
<input message="interface:Int" name="InputOperationRequest"/>
<output message="interface:Int" name="InputOperationResponse"/>
</operation>
</portType>
</definitions>
Figure 14-15 WSDL interface file of the business process

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.
The Deployment Code wizard is started by selecting Enterprise Services ->

Generate Deploy Code in the context menu of the process file (Figure 14-16).
Figure 14-16 Generate deployed code for a process
򐂰 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 already deployed the service before.
򐂰 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
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 14-17).
Process
WSDL
interface
binding
service
Figure 14-17 Deployable services
Explore the ItsoWebServBPServiceEJB and ItsoWebServBPServiceWeb projects

and study the generated code.

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 123.
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:
<fdml xmlns="http://www.ibm.com/schemas/workflow/wswf"
..............">
<wf:flowModel autoDelete="true" canRunInterrupted="false"
canRunSynchronous="true" name="temperature"
requiresCompensationSphere="false"
validFrom="2003-01-01T12:00:00">
<wf:description>microflow file</wf:description>
<wf:documentation>This is a long description.</wf:documentation>
..... activities, messages, links
</wf:flowModel>
</fdml>
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.
<wf:activity name="getDayForecast">
<wf:input messageType="MessageType_3" name="in"/>
<wf:output messageType="MessageType_4" name="out"/>
<wf:operation invocationType="WSDL2">
<service:wsdlOperation input="getDayForecastRequest"
operation="getDayForecast"
output="getDayForecastResponse"
portType="WeatherForecast"
portTypeNS="http://wsoj.itso.wsdl/WeatherForecast/"
service="WeatherForecastService"
serviceNS="http://wsoj.itso.wsdl/WeatherForecastService/">
<wf:wsdl
location="file:itso/wsoj/WeatherForecastService.wsdl"
resolutionTime="deployment"/>
</service:wsdlOperation>
</wf:operation>
</wf:activity>

Message
The input message for the Web service refers to the message in the WSDL file.
<wf:messageType name="MessageType_3" typeSystem="WSDL2">
<service:messageRef name="getDayForecastRequest"
namespace="http://wsoj.itso.wsdl/WeatherForecast/">
<service:import location="file:itso/wsoj/WeatherForecast.wsdl"/>
</service:messageRef>
</wf:messageType>
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.
<wf:activity name="prepareDate">
<wf:input messageType="MessageType_6" name="in"/>
<wf:operation invocationType="Java">
<wf:javaOperation className="itso.wsie.temperature"
methodName="javaSnippet_5"/>
</wf:operation>
</wf:activity>
<wf:messageType name="MessageType_6" typeSystem="Java">
<java:class name="org.apache.wsif.base.WSIFDefaultMessage"/>
</wf:messageType>
Data map
A data map refers to the internal method that prepares the message content.
<wf:dataMap name="DataMap0_4" target="getDayForecast" targetTerminal="in">
<wf:mapping type="WSDL2">
<service:mapping>
<service:mappingjava className="itso.wsie.temperature"
methodName="mappingOutputGetDayForecastRequest"/>
</service:mapping>
</wf:mapping>
</wf:dataMap>
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.
<wf:controlLink name="_wConditionalControlConnection_4"
source="prepareDate" sourceTerminal="out"
target="getDayForecast" targetTerminal="in">
<wf:transitionCondition type="Built-in">
<wf:true/>
</wf:transitionCondition>
</wf:controlLink>

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 14-18).
Figure 14-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!

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 14-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 14-19).
Figure 14-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 14-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.

13
Figure 14-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

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 14-18 on page 270) 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.
򐂰 In 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 14-21).
Figure 14-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.

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 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 14-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.

Breakpoint
Figure 14-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.

Figure 14-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 14-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 14-24
shows the Variables view at two breakpoints, just after beginning the process and
before ending.

Figure 14-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
Deployment to WebSphere Application Server is covered in Chapter 19, “Web

services runtime and deployment in WebSphere” on page 401. However, we did
not install the Enterprise Edition for deployment of the process application.

Importing the process solution
We provide the files of our solution in the directory:
\sg246891\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, click Browse to locate the file:
\sg246891\sampcode\wsadie\zSolution\ItsoWebServBPServiceEAR.ear
򐂰 Enter ItsoWebServBPServiceEAR as 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 either.
To fix the errors in the projects, a number of steps are required.
Web project
򐂰 Select the ItsoWebServBPServiceWeb project and Import -> File system.
Locate the directory:
\sg246891\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
򐂰 Select the ItsoWebServBPServiceEJB project and Import. -> File system.
Locate the directory:
\sg246891\sampcode\wsadie\zSolution\EJB
򐂰 Import the .classpath file (select Overwrite existing resources without
warning).

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\sampcode\wsadie\zSolution\ItsoWebServBPService.jar
򐂰 Select Overwrite existing resources without warning and click Finish.
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 270.
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.

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.

15
Chapter 15. WebSphere SDK for Web

Services
In this chapter we introduce the IBM WebSphere SDK for Web Services (WSDK),
Version 5.0, which enables early adopters to create and test Java-based Web
services applications. This entry-level developer kit contains everything
developers need in a single convenient package.
The WSDK is based on open specifications for Web services such as SOAP,
WSDL, and UDDI, and runs on Windows and Linux operating systems.
There is some confusion about the different packages for developing Web
services on top of WebSphere Application Server and in this chapter we explain
the differences between the three packages:
򐂰 IBM WebSphere SDK for Web Services (WSDK)
򐂰 IBM Web Services Toolkit (WSTK)
See Chapter 16, “Web Services Toolkit” on page 301.
򐂰 IBM WebSphere Web Services for J2EE Technology Preview
See Chapter 17, “WebSphere Web Services Technology Preview” on
page 317.

What is the difference between the packages?
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 is based on Axis but does not expose the Axis
programming model; it uses the WebSphere programming model based on
JAX-RPC (JSR 101) and Web services for J2EE (JSR 109).
The Web Services Toolkit (WSTK) delivers early implementations of new Web
services technology to developers, and acts as a consolidator of Web services
technologies from various IBM development and research labs. Unlike WSDK,
the WSTK does not have an embedded application server or private UDDI
registry. The WSDK is therefore ideal for running services developed with WSTK.
WSTK exposes the Axis programming model.
The WebSphere Web Services for J2EE Technology Preview does not come
with an application server and must be installed on top of WebSphere Application
Server Version 5. The technology preview is based on Axis but does not expose
the Axis programming model (same as for WSDK).
You can use WSDK without WSTK to develop industry-standard Web services
applications, or you can use it with WSTK if you want to explore the latest
emerging technology developments in Web services.
WebSphere SDK for Web Services Version 5

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). You 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 (Red Hat
Advanced Server 2.1 and SuSE SLES 7) and Windows (Windows 2000
Professional with Service Pack 2 and Windows XP Professional) 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. 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 with additional support for ORB 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.
򐂰 Tools to enable JavaBeans and stateless session EJBs as Web services,
create Web services from WSDL definitions, and publish and unpublish Web
services to a UDDI registry.
򐂰 Comprehensive documentation including Web services concepts, developer
tasks, and reference materials.
򐂰 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 server, used for publishing and
discovery of Web services using the UDDI protocols. The UDDI server itself runs
as an enterprise application (EAR) within the application server.
The application server provided with WSDK 5.0 is based on WebSphere

Application Server Version 5. It is a J2EE-based server that provides the
functions of an HTTP Web server, a servlet engine, and an EJB container.
It also includes WebSphere Web Services Technology Preview, which 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.
Chapter 15. WebSphere SDK for Web Services 283

Tools
The WSDK provides utility tools (in <WSDK-install-dir>/bin) that allow you to
enable, deploy, and publish your 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 enterprise bean 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.
򐂰 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.
In addition to the Web services development tools, WSDK provides tools to

monitor your Web services or administer your application server:
򐂰 tcpmon—Monitors and displays Web service messages (SOAP messages)
that are exchanged between a Web service client and a Web service.
򐂰 appserver—Provides basic administration of the application server and the
Web services running on it, the functions to start and stop the server, the
ability to install and uninstall a Web service to the server, and a list of the Web
services that are currently installed on the server.
򐂰 setProxy—Configures HTTP proxy information for the WSDK tools and
runtime server.
Documentation
WSDK documentation is divided into five sections:
򐂰 Learning paths—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 your J2EE
applications, or implement an existing Web service from its WSDL document.
It also tells how to secure your 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 eight Web services samples shipped
with the WSDK, tells you how to run them and what their expected behavior
is. It also includes a step-by-step guide to rebuilding the samples yourself.
To access the documentation for WSDK, use the wsdkHelp command, located in
the <WSDK-install-dir>/bin directory, or click the WSDK Help icon.
Sample applications
There are eight sample applications located in<WSDK-install-dir>/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 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—Demonstrate WS-Security digital signature, encryption,
authentication and ID assertion.
The sample applications are already built and deployed to the application server,
so that you can run them as soon as you have installed WSDK.

WS-Security in WSDK
The WSDK implements the WS-Security elements shown in Table 15-1.
Table 15-1 WS-Security elements implemented in WSDK

Element Notes
<UsernameToken> Both username/password and IDAssertion authentication

are implemented. Password digest is not implemented.
<BinarySecurityToken> X.509 certificates can be embedded, but Kerberos tickets

cannot.
<Signature> X.509 certificate in <BinarySecurityToken> can be

referenced by <SecurityTokenReference>.
<Encryption> Both <EncryptedKey> and <ReferenceList> are

implemented. <KeyIdentifier> is used to specify public
keys; <KeyName>, secret keys.
<Timestamp>
With WSDK, SOAP messages that include these security elements can be
exchanged by providing XML configuration files at both client and server sides.
Figure 15-1 shows the overall architecture of the WS-Security implementation in

the WSDK.
Figure 15-1 WS-Security implementation in the WSDK

Using the tools
In this section we describe the four tools provided with the WSDK.
Bean2WebService
The Bean2WebService tool generates a fully deployable Web service from a Java
class, and optionally deploys it onto the application server.
To use Bean2WebService, enter:

cd <WSDK-install-dir>\bin
Bean2WebService [<optional arguments>] -cp <Classpath>
-project <ProjectName> <BeanName>
Here is an example of how to use the Bean2WebService tool:

Bean2WebService -cp c:\Working\src -project MyBean com.ibm.wsdk.MyBean
The main output of the Bean2WebService tool is a file called <ProjectName>.ear in

the root of the generated directory structure. This file contains a fully deployable
Web service. META-INF and WEB-INF directories are also generated under
<ProjectName>. These directories hold the generated WSDL, Java classes, and
so forth. If you do not specify the -server-side-only option, a client-side
directory that contains some extra .java files is also created.
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, enter:

EJB2WebService [<optional arguments>] -project <ProjectName>
-ri <RemoteInterface> <EJB.ear>
The main output of this tool is a modified version of the original EAR file, which
contains a fully deployable Web service. If you do not specify the
-server-side-only option, a client-side directory that contains some extra .java
files is also created.

WSDL2WebService
The WSDL2WebService tool generates fully deployable Web services from one or
more WSDL documents and optionally deploys them onto the application server.
You use the tool in three stages:
򐂰 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 your implementation code in the templates and compile it
using a build 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 you can perform stage 1 several times to create related Web services
in the same project directory. In stage 3 you can then create a separate module
for each of these Web services and add them to the same EAR file.
Stage 1—Creating a skeleton Web service implementation

To create a skeleton Web service implementation:
WSDL2WebService [<optional arguments>] -createService <ServiceName>
-project <ProjectDir> <InputFile.wsdl>
After running the tool with the -createService <ServiceName> argument, a

directory named <ServiceName> containing several subdirectories is created
under the specified project. 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 help you compile all this code.
Stage 2—Compiling the implementation code

If your implementation code has dependencies such as a .jar file or a directory
containing .class files, edit the compile script, and add the full path names of
these dependencies to the USER_CLASSPATH variable, for example:
set USER_CLASSPATH = c:\MyJars\webservice.jar;c:\MyClasses
To compile the code:

cd <ServiceName>
compile

Stage 3—Creating a Web services-enabled archive
To create a Web services-enabled archive:
cd <WSDK-install-dir>/bin
WSDL2WebService [<optional arguments>] -createEar <File.ear>
-project <ProjectDir>
After you have written the implementation code, compiled it, and run the tool
again with the -createEar <File.ear> 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. You will also notice that the server-side
classes that implement the Web service have been moved to the
WEB-INF/classes directory, which is the normal location.
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.
Publishing a business entity

To publish a business entity:
UDDIPublish -business -businessName <name> [<optional arguments>]
A message is returned informing you 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:
UDDIPublish -service -serviceName <name> -businessName <name>
-wsdlLocation <URI of WSDL describing new service>
-accessPoint <URL of where the new service exists on the network>
[<optional arguments>]
A message is returned informing you that the publish operation completed

successfully. The unique keys for the new business service, binding template,
and tModel instance are also displayed.

Security
Because the application server is running with security on, default credentials
(user ID: admin, password: adminpwd) are flowed 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, you 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.
You 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 15-2):
<WSDK-install-dir>\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 15-2 Properties file for publishing

You can use the provided testregistry.properties file with UDDIPublish to
publish your businesses and services to the IBM UDDI V2 Business Test
Registry (but without the special categories for the IBM Speed Start program).
Similarly, you can use the businessregistry.properties file to enable you 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.
Unpublishing a business entity or business service

To unpublish a business entity:
UDDIUnpublish -business -businessName <name> [<optional arguments>]
UDDIUnpublish -service -serviceName <name> -businessName <name>
-removeTModels [<optional arguments>]
A message is returned informing you that the unpublish operation completed

successfully. The unique key for the deleted business entity or business service
is also displayed.
Security
Because the application server is running with security on, default credentials
(user ID: admin, password: adminpwd) are flowed by the tool to the UDDI registry
when an unpublish operation is attempted. These credentials can be overridden
by the -username and -password arguments, which can be entered when
unpublishing either a service or a business:
Additional properties
With the -uddiprops argument of UDDIUnpublish, you 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.

You 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 you an idea of what WSDK samples are.
Sample 1 is a simple request-response Web service. The request message
contains a string provided by the service requestor (that is, the user), usually
their name. The response message from the Web service is “Hello <name>!”,
where <name> is the argument passed in the request message. The scenario is
described in Figure 15-3.
Figure 15-3 Sample a scenario
򐂰 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, <name>, and returns
another string, “Hello <name>!”
򐂰 The WSDL document, containing service interface and implementation
definitions, is access in the WebSphere 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
documentation for a description of the service locator client.
򐂰 The Java client code is located in:
<WSDK-install-dir>\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 documentation
Usage
First, start the application server by invoking this command:
<WSDK-install-dir>\bin\appserver start
To run the sample client:

cd <WSDK-install-dir>/apps/Sample1/bin
runclient.bat <name>
The output from running this sample is shown below, where Bertrand is the value
of the <name> 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 you 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 <WSDK-install-dir>\apps\Sample1\src\provider
<WSDK-install-dir>\appserver\java\bin\javac
-d <WSDK-install-dir>\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 <WSDK-install-dir>\apps\Sample1
<WSDK-install-dir>\bin\Bean2WebService.bat -project Sample1WebService
-methods "getGreeting" -servicePortName Sample1 -style DOC
-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 you are prompted for
confirmation before overwriting the existing Sample1WebService application

that is already installed on the applications server, and the original EAR file is
backed up to Sample1WebService.ear.backup.
򐂰 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, which is 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:
<WSDK-install-dir>\apps\Sample1\bin\buildclient.bat
You 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:
<WSDK-install-dir>\bin\appserver.bat startapp Sample1WebService
Open up a browser and point to:
http://localhost:6080/Sample1WebService/services/Sample1
You should see the confirmation message that the Web service has been
deployed and is running successfully:
Hi there, this is an AXIS service!
Implementing the weather forecast Web service

We install the WSDK (see “Installation of the WebSphere SDK for Web Services”
on page 433) and use the Bean2WebService tool to implement the weather
forecast Web service.
We provide the WeatherForecast, Weather, and WeatherPredictor Java source

files under \SG246891\sampcode\wsdk\bean.
Running the Bean2WebService tool

Run the Bean2WebService tool using these commands:
cd \sg246891\sampcode\wsdk\bean
javac itso\wsoj\*.java
set PATH=d:\WSDK_v5\bin;%PATH%;
call Bean2WebService.bat -verbose -cp e:\sg246891\sampcode\wsdk\bean
-deploy -use encoded -project ItsoWebServWsdk1
itso.wsoj.WeatherForecast

Note: Installation of the enterprise application is automated using the -deploy
option of the Bean2WebService command. The -use encoded option is
necessary for the array of Weather objects.
The tool displays this output with the -verbose option (abbreviated):
Creating new project: ItsoWebServWsdk1....
Removed all existing classes from directories under
E:\SG246891\sampcode\wsdk\bean\ItsoWebServWsdk1\WEB-INF\classes\
Generating the service endpoint interface...
Generating WSDL:
com.ibm.ws.webservices.axis.ext.wsdl.Java2WSDL
-output E:\SG246891\sampcode\wsdk\bean\ItsoWebServWsdk1\WEB-INF
\WeatherForecast_SEI.wsdl
-location http://localhost:6080/ItsoWebServWsdk1/services/WeatherForecast
-style RPC -use ENCODED -implClass itso.wsoj.WeatherForecast
itso.wsoj.WeatherForecast_SEI
Generating server side classes:
com.ibm.ws.webservices.axis.ext.wsdl.WSDL2Java
-output E:\SG246891\sampcode\wsdk\bean\ItsoWebServWsdk1
-META-INF-Only -server-side Bean E:\SG246891\sampcode\wsdk\bean
\ItsoWebServWsdk1\WEB-INF\WeatherForecast_SEI.wsdl
Configuring webservices.xml...
Added web module with context root: ItsoWebServWsdk1
Web Service archive
"E:\SG246891\sampcode\wsdk\bean\ItsoWebServWsdk1\ItsoWebServWsdk1.ear"
has been successfully generated.
Checking server for existing application...
Deploying Web Service....
Deploy command:
D:\WSDK_v5\appserver\..\bin\appserver.bat install
\"E:/SG246891/sampcode/wsdk/bean/ItsoWebServWsdk1/ItsoWebServWsdk1.ear\"
{-usedefaultbindings -nodeployejb -appname \"ItsoWebServWsdk1\" }
......
ADMA5013I: Application ItsoWebServWsdk1 installed successfully.
Web service application was successfully deployed to application server.
Generating client side classes:
com.ibm.ws.webservices.axis.ext.wsdl.WSDL2Java
-output E:\SG246891\sampcode\wsdk\bean\ItsoWebServWsdk1\client-side
E:\SG246891\sampcode\wsdk\bean\ItsoWebServWsdk1\WEB-INF
\WeatherForecast_SEI.wsdl
All done.
Manual installation of the enterprise application would use this command:

appserver install
E:/SG246891/sampcode/wsdk/bean/ItsoWebServWsdk1/ItsoWebServWsdk1.ear

Generated output
A subdirectory with the project name (ItsoWebServWsdk1) is created. It contains:
򐂰 ItsoWebServWsdk1.ear—installable enterprise application with one Web
module (ItsoWebServWsdk1.war)
򐂰 META-INF folder with WeatherForecast_SEI_mapping.xml (a JAX-RPC Java
WSDL mapping file)
򐂰 WEB-INF folder with:
– webservices.xml and ibm-webservices-bnd.xml—deployment descriptor
and IBM bindings
– WeatherForecast_SEI_mapping.xml—JAX-RPC mapping file
– WeatherForecast_SEI.wsdl—WSDL file of the Web service
– classes folder with compiled code including the generated
WeatherForecast_SEI class
The WEB-INF folder is included in the ItsoWebServWsdk1.war file.
򐂰 client-side folder with:
– source code: Weather, Weather_Ser, Weather_Deser, Weather_Helper,
WeatherForecast_SEI, WeatherForecast_SEIService,
WeatherForecast_SEIServiceLocator, WeatherForecastSoapBindingStub
– META-INF folder with WeatherForecast_SEI_mapping.xml,
webservicesclient.xml and ibm-webservicesclient-bnd.xml
򐂰 The installed enterprise application can be found in:
d:\WSDK_v5\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, you must start the newly installed
enterprise application using the command:
appserver startapp ItsoWebServWsdk1
Enabling application ItsoWebServWsdk1

WASX7357I: By request, this scripting client is not connected .....
enabling ItsoWebServWsdk1
Enable process complete for application ItsoWebServWsdk1
WASX7209I: Connected to process "server1" on node DefaultNode using SOAP
connector; The type of process is: UnManagedProcess
starting ItsoWebServWsdk1
Start process complete for application ItsoWebServWsdk1

Creating and running a stand-alone client
A small stand-alone client uses the service locator to access the Web service
(Figure 15-4).
package itso.wsoj;
import java.util.Calendar;
public class Client {

Weather week[] = new Weather[7];
Weather today = null;
int temp[]= new int[7];
try {
WeatherForecast_SEIServiceLocator loc = new
WeatherForecast_SEIServiceLocator();
WeatherForecast_SEI port = loc.getWeatherForecast();
//gets today weather forecast

today = port.getDayForecast(Calendar.getInstance());
System.out.println("Today weather forecast...");
System.out.println(printWeather(today));
//gets weekly temperatures
temp = port.getWeekTemperatures(Calendar.getInstance());
System.out.println("Weekly temperatures forecast... week...");
for (int j = 0; j < temp.length; j++)
System.out.println("Day "+(j+1)+": "+ (temp[j]) + " Celsius");
//gets the weekly weather forecast
week = port.getWeekForecast(Calendar.getInstance());
System.out.println("Weekly weather forecast for next week...");
for (int i = 0; i < week.length; i++)
System.out.println(printWeather(week[i]));
}
catch (Exception e) { e.printStackTrace(); }
}
private static String printWeather(Weather w) {

return "Weather: " + sdf.format(w.getDate().getTime()) + " '"
+ w.getCondition() + "' wind: " + w.getWindDirection() + " "
+ w.getWindSpeed() + "km/h " + w.getTemperatureCelsius()
+ " Celsius";
}
}
Figure 15-4 Stand-alone client for weather forecast using service locator

Client logic
The main logic is very simple: a service locator is created, the port of the service
is retrieved, and one of the service methods is invoked.
WeatherForecast_SEI port = loc.getWeatherForecast();
Weather today = port.getDayForecast(Calendar.getInstance());
We provide the client code in \SG246891\sampcode\wsdk\clientstart. Copy all

the files into the generated client-side directory:
\SG246891\sampcode\wsdk\bean\ItsoWebServWsdk1\client-side
Compile and run client

Compile the client and all the generated code (use the RunCompile.bat file):
cd \sg246891\sampcode\wsdk\bean\ItsoWebServWsdk1\client-side
copy Client.java itso\wsoj\
javac -extdirs d:/WSDK_v5/appserver/lib itso\wsoj\*.java
Run the client using these commands (RunClient.bat file):

cd \sg246891\sampcode\wsdk\bean\ItsoWebServWsdk1\client-side
set LIB=d:\WSDK_v5\appserver\lib
set CLASSPATH=.;%LIB%\axis.jar;%LIB%\jaxrpc.jar;
%LIB%\commons-logging-api.jar;%LIB%\commons-discovery.jar;
%LIB%\j2ee.jar;%LIB%\qname.jar;%LIB%\xerces.jar;%LIB%\saaj.jar;
%LIB%\webservices.jar;%CLASSPATH%
java itso.wsoj.Client
Sample output
Today weather forecast...
Weather: Wed. Feb 19, 2003 'stormy' wind: SW 15km/h 31 Celsius
Weekly temperatures forecast for next week...
Day 1: 58 Celsius
Day 2: 49 Celsius
Day 3: 37 Celsius
......
Day 7: 11 Celsius
Weekly weather forecast for next week...
Weather: Wed. Feb 19, 2003 'cloudy' wind: SE 8km/h 36 Celsius
Weather: Thu. Feb 20, 2003 'cloudy' wind: W 28km/h -8 Celsius
Weather: Fri. Feb 21, 2003 'cloudy' wind: E 34km/h 12 Celsius
......
Weather: Tue. Feb 25, 2003 'rainy' wind: S 35km/h 15 Celsius

Service locator or service factory
Using the service locator (ServiceLocator class) may not work on all JAX-RPC
implementations. For portable client code, the ServiceFactory should be used
instead, as shown in WSDK's sample 5.
We provide a second client (Client2.java) that uses the service factory. An

extract of the code is shown in Figure 15-5.
import javax.xml.namespace.QName;
import javax.xml.rpc.Service;
import javax.xml.rpc.ServiceFactory;
public class Client2 {

String wsdlURL =
"http://localhost:6080/ItsoWebServWsdk1/services/WeatherForecast?wsdl";
String namespace = "http://wsoj.itso";
String serviceName = "WeatherForecast_SEIService";
String portName = "WeatherForecast";
......
try {
ServiceFactory factory = ServiceFactory.newInstance();
Service myService = factory.createService(
new java.net.URL(wsdlURL),
new QName(namespace, serviceName) );
WeatherForecast_SEI port = (WeatherForecast_SEI)myService.getPort
( new QName(namespace, portName), WeatherForecast_SEI.class);
......
// rest identical to Client.java
Figure 15-5 Stand-alone client for weather forecast using service factory
Conclusion
This simple weather forecast example shows the power of the WebSphere SDK,
especially when compared to the WebSphere Web Services Technology Preview,
where a number of manual steps are involved to accomplish the same task.
The Bean2WebService tool automates these tasks by generating the required

code, creating the enterprise application, and installing the EAR file into the
application server.

Summary
In this chapter we provided a short overview of the WebSphere SDK for Web
Services and described the differences between this package and the Web
Services Toolkit and the WebSphere Technology Preview.
We also implemented our weather forecast example with the WSDK by

generating the Web service using the Bean2WebService tool, installing it into the
application server, and using a simple client to run the Web service.
More information
The WSDK Web site contains additional information, FAQ list, a forum and
downloads. Check it out at:
http://www.ibm.com/developerworks/webservices/wsdk/
Speed-start program for Web services:

http://www.ibm.com/developerworks/offers/ws-speed-start/
After installing the product you can find more information about the WSDK in the
InfoCenter. Use the wsdkHelp command, located in the <WSDK-install-dir>/bin
directory, or click the WSDK Help icon from the program group.

16
Chapter 16. Web Services Toolkit

This chapter describes the IBM Web Services Toolkit (WSTK), a package that
provides a starting point for developers who want to explore Web services. It
contains a set of technologies related to Web services, together with tools,
examples, and tutorials.
In this chapter we discuss the content of the Web Services Toolkit. We describe
the prerequisites for the installation, the installation procedure, and the
configuration tasks. We also present an outlook of future additions to the
package.

Overview
The IBM Web Services Toolkit for dynamic e-business (WSTK) was created to
provide a starting point for developers who are interested in creating, locating,
and invoking Web services. The WSTK consolidates several Web services
technologies from various IBM development and research labs in one package.
Some of these technologies are later incorporated into IBM's product offerings.
As an IBM alphaWorks technology, the WSTK concentrates on supplying
prototypes and technology previews, not a production-ready environment. If your
intention is to run Web services in production, you should obtain IBM Web
services-enabled products, such as WebSphere Application Server.
Interoperability is one of the Web services’ key issues. IBM is actively working
with standards communities (such as the W3C) and open-source projects to
ensure Web services interoperability. Several technologies such as the UDDI for
Java API (UDDI4J), which was first developed and shipped as part of the WSTK,
have been open-sourced. WSTK functionality is based on open specifications
such as SOAP, WSDL, WS-Inspection, and UDDI, and runs on both Linux and
Windows operating systems. The SOAP engine is based on the open-source
Apache SOAP project and the WSDL object model uses the open-source Web
services description language for Java (WSDL4J) project.
WSTK general concepts

WSTK provides a package for developers who wish to work with the latest
technology developments in Web services. It includes the following components:
򐂰 An overview of Web services architecture, together with a white paper on
developing Web services, as well as tutorials.
򐂰 Documentation about the Web services architecture, WS-Inspection and
WSDL specifications.
򐂰 Pre-installed environment (Xerces, Xalan, SOAP) as well as instructions and
configuration utilities for using WSTK with the WebSphere SDK for Web
services, WebSphere Application Server, and Jakarta Tomcat.
򐂰 Client-side APIs for interfacing with a WSDL document, a UDDI registry, and
APIs for publishing and binding Web services.
򐂰 A set of utility Web services, such as user profile, metering, accounting,
contract, common data, and notification.
򐂰 Technology previews of security functions such as WS-Security, systems
management, and SOAP technologies.

򐂰 Demonstrations that can be used to test the Web Services Toolkit. The
demonstrations cover publishing a service and then using a client that
communicates with the UDDI registry to find the Web service and invoke it.
WSTK prerequisites
WSTK does not represent a stand-alone Web services environment. The WSTK
prerequisites include installation of other packages or products, such as
WebSphere SDK for Web services, WebSphere Application Server 4.02 (AE or
AEs), or Jakarta Tomcat.
IBM WebSphere SDK for Web Services (WSDK)

You can use the IBM WebSphere SDK for Web Services (WSDK) as the base
application server for the Web Services Toolkit. (WSTK).
See Chapter 15, “WebSphere SDK for Web Services” on page 281 for detailed
information about the WSDK and the differences between WSDK and WSTK.

IBM WebSphere Application Server provides an application deployment platform
on which Web services applications and other e-business applications can run,
with an emphasis on integration with business systems and applications, the
provision of application management, and enterprise quality of service including
security, scalability, and reliability.
We provide more detailed information on WebSphere Application Server Version

5 in Chapter 19, “Web services runtime and deployment in WebSphere” on
page 401.
Jakarta Tomcat
Tomcat is a servlet engine developed as a part of the Apache Jakarta
open-source project. It is used in the official Reference Implementation for the
Java servlet and JavaServer Pages technologies. Latest release is Version
4.1.12 with Version 5.0.x in preparation. You can read more about Tomcat at:
http://jakarta.apache.org/tomcat/index.html
Chapter 16. Web Services Toolkit 303

Web Services Toolkit installation and configuration
In this section, we cover the WSTK installation procedure as well as WSTK
administration tasks.
Web Services Toolkit installation

Although we generally cover product installation in Appendix A, “Installation and
setup” on page 427, we make an exception here because the WSTK installation
is a straightforward process.
All we need to do is to download the executable file (for example,

WSTKWIN322.EXE in case of WSTK V3.2.2. for Windows or wstklinux322.bin in
the case of WSTK V3.2.2 for Linux, native installation) and run it. The
InstallShield wizard searches for the appropriate JDK and then starts the Java
installer. It is also possible for the user to browse for the JDK. After the
installation is finished, Web Services Toolkit configuration tool is started.
Web Services Toolkit configuration tool

The Web Services Toolkit configuration tool is a central point of WSTK
configuration and management. It is started automatically during the installation
process but it is possible to run it later through a command:
򐂰 wstkconfig.bat command on Windows
򐂰 wstkconfig.sh command on Linux
This command is located in the WSTK_HOME/bin directory. A desktop icon or menu

item is also provided for running the Web Services Toolkit configuration tool.
The configuration process comprises seven different steps, which we cover in

the following sections.

Server Info
The Server Info tab is shown in Figure 16-1.
Figure 16-1 Server Info tab
WSTK no longer comes with an embedded servlet engine. Therefore, we have to

install one of the supported engines (WSDK, WebSphere Application Server, or
Apache Tomcat) and make the appropriate selection in the Server Info tab.

Configure WebServers
The Configure WebServers tab is shown in Figure 16-2.
Figure 16-2 Configure WebServers
Once we select the server, we have to enter the related information, such as the
listening port and location.

Configure Services
The Configure Services tab is shown in Figure 16-3.
Figure 16-3 Configure Services tab
In the Configure Services tab, we decide which services we want to run on the
specified server. The preconfigured services fall into one of the following three
groups: utilities, applications, and demonstrations.

Configure Client
The Configure Client tab is shown in Figure 16-4.
Figure 16-4 Configure Client tab
Here we enter the server host name and the listening port. It is this address and
port the generated service client will try to contact.

Configure WS-Inspection
The Configure WS-Inspection tab is shown in Figure 16-5.
Figure 16-5 Configure WS-Inspection tab
Here we enter the address and port where the client is looking for WS-Inspection
services, a WSIL description of services.

Configure Proxies
The Configure Proxies tab is shown in Figure 16-6.
Figure 16-6 Configure Proxies tab
When using the toolkit, there are times when we have to access servers that are
protected by a firewall. For example, some of the demonstration Web services
access servers behind the firewall, and the public UDDI registries may have to be
accessed through a firewall. To access servers through a firewall, your system
must be configured to use a SOCKS client, or a SOCKS or HTTP proxy must be
specified when running the Toolkit demonstrations. This configuration is entered
in the Configure Proxies tab.

Configure UDDI
The Configure UDDI tab is shown in Figure 16-7.
Figure 16-7 Configure UDDI tab
In the Configure UDDI tab, we enter the information related to the public UDDI
we intend to use. To use a public UDDI registry such as the IBM UDDI V2
Business Test Registry, we must first register to use the site. After registration,
we are sent an activation key by e-mail.
We have to first manually log on using the provided user ID and password and
then use the activation key to activate the account prior to running the
demonstrations. Once registered, we start the wstkconfig tool to set the user ID
and password that will be used with the UDDI registry.

Uninstalling the Web Services Toolkit
WSTK can be completely and safely removed from the system. First we have to
run the uninstall program.
If the Web Services Toolkit was deployed on WebSphere Application Server 4.01
or 4.02, we have to use the WebSphere Application Server administrative
console to remove the WSTK:
򐂰 Using the topology view on the server node where the Web Services Toolkit
was installed, there should be one or more Application Server engines that
were installed with the Web Services Toolkit.
򐂰 The WebServicesServer and some demonstrations also install Application
Server engines such as the G2GServer.
򐂰 Select these Application Server engines and click Stop. When the servers are
stopped, select them again and click Remove.
Finally we have to manually delete all of the files and directories in the wstk-3.2
directory, and then remove the wstk-3.2 directory.
Examples
We started to implement examples with the WSTK, but we realized that the
examples were basically the same examples implemented using the WebSphere
Web Services Technology Preview.
Therefore, refer to Chapter 17, “WebSphere Web Services Technology Preview”

on page 317 for examples.
Current status
In August 2002, WSTK Version 3.2.2 was released. New features include:
򐂰 Demonstrations for Web services coordination (WS-C), transaction (WS-Tx),
and business process execution language for Web services (BPEL4WS).
WS-C/WS-Tx defines an infrastructure for transaction flows between various
business components. Building on this, BPEL4WS simplifies the modeling of
business interactions through the definition of flows, which describe the
manner in which these interactions take place and the relationships among
the involved partners.

򐂰 Web services matchmaking engine (WSME).
This is a technology that matches Web service providers and customers
according to the requirements that both providers and customers place on
each other, based on a finite set of descriptive properties. The types of
entities to be matched and their properties are specified in a data dictionary
that is supplied to WSME. Advertisements are submitted to WSME.
Subsequent queries trigger the matchmaking process, which finds,
configures, and returns matching advertisements. WSME can be an
alternative to a UDDI registry.
򐂰 JMX-based management update.
An update of the Web service management technology, which allows a single
console to monitor the status of JMX-enabled services and components
throughout an enterprise through an AXIS (SOAP) client interface.
򐂰 Direct Internet message encapsulation (DIME) attachments.
This demonstration explains use of SOAP attachments in both RPC and
document-messaging styles of SOAP interactions. SOAP attachments are
non-XML files that accompany the XML SOAP message. The DIME
specification was co-written by IBM and Microsoft and was recently submitted
to the IETF organization.
򐂰 Web services experience language (WSXL).
This technology allows Web service developers to wrap their service's output
with additional XML tags that enable portals to more easily customize the
data for their specific needs. WSXL is designed to achieve two main goals:
– Enable businesses to deliver interactive Web applications through multiple
distribution channels.
– Enable new services or applications to be created by taking advantage of
other interactive applications across the Web.
The WSXL specification has been submitted to the OASIS Web services for
interactive applications (WSIA) technical committee.
򐂰 WS-Security implementation.
The WSTK provides an implementation of the WS-Security specification that
secures SOAP messaging through three mechanisms: security token
propagation, message integrity through use of digital signatures, and
message confidentiality.
The WSTK uses Version 2 UDDI registries for all its demonstrations and makes
use of the UDDI4J 2.0 code. The WSTK no longer ships WebSphere Micro
Edition as part of its base installation package because the Micro Edition is now
available in the WebSphere SDK for Web Services package.

All the WSTK demonstrations have been updated to use the new Apache Axis
beta 3 release, the successor to the Apache SOAP project. This latest version
adds support for DIME and is almost a complete implementation of the
JAX-RPC, SOAP with Attachments API for Java (SAAJ), and SOAP 1.2
specifications.
Outlook
Web services technology is evolving at a very fast pace and many people at IBM
are working on new technologies to enhance the Web services technology.
Although many aspects of Web services infrastructure are now solid and these
functions are provided in several products from IBM and other companies, there
are currently unresolved Web services standardization issues, such as security
(encryption, authorization, authentication), reliability, metering, accounting, and
systems management, which are getting more and more important now that Web
services are becoming more widely used.
There are various draft specifications available that are trying to solve these
problems. Security, reliability, metering, notification, accounting, and systems
management are some of the issues that the WSTK team plans to prototype in
future releases. Also, full compliance with WebSphere Application Server Version
5 has to be achieved.
Summary
The IBM Web Services ToolKit for dynamic e-business (WSTK) represents a
consolidated IBM offering in the field of Web services. Its aim is to help the
developers to start working with Web services. It provides technologies from
various IBM development and research labs together with a set of tutorials,
examples, and useful tools.
WSTK functions is based on open specifications such as SOAP, WSDL,

WS-Inspection, and UDDI, and run on both Linux and Windows operating
systems. Therefore, interoperability is one of the key issues here.
WSTK includes latest technologies such as Apache Axis and WS-Security.

Several technologies such as the UDDI Java API (UDDI4J), which was first
developed and shipped as part of the WSTK, have been open-sourced later.
Many of the technologies that are present in WSTK will be incorporated into IBM
software packages in the future, when they reach the stability and maturity
required for the production environment.

On the other hand, new technologies, such as reliability, metering, notification,
accounting, and systems management, will be implemented in future releases of
the WSTK.
More information
For information on IBM WSTK, check out the user and API documentation,
downloads, and the FAQ list:
http://www.alphaworks.ibm.com/tech/webservicestoolkit
Recent information on Apache Jakarta Tomcat project is available from:

http://jakarta.apache.org/tomcat/index.html

17
Chapter 17. WebSphere Web Services

Technology Preview
In this chapter we introduce the IBM WebSphere Web Services for J2EE
Technology Preview, which represents an early effort by IBM to incorporate the
new Java development process standards for Web services generation. These
Java Web services standards have been defined for Java under the JCP process
and cover the standards provided by JAX-RPC (JSR 101) and Web services for
J2EE (JSR 109).
JAX-RPC provides the core programming model and bindings for developing and
deploying Web services on the Java platform. JAX-RPC is a required part of the
J2EE 1.4 platform, but can also be developed and deployed on J2EE 1.3, as in
this technology preview.
Web services for J2EE provides the use of JAX-RPC in a J2EE environment
defining the runtime architecture, as well as the implementation and deployment
of Web services in a generic J2EE server.
We will use technology preview as the short name for the IBM WebSphere Web
Services for J2EE Technology Preview in this chapter.
See Chapter 15, “WebSphere SDK for Web Services” on page 281 for detailed
information about the WSDK and the differences between WSDK and the
technology preview.

Overview
To prepare for the J2EE 1.4 platform, which introduces new APIs that implement
core Web services protocols developed for Java under the JCP process, IBM
introduced the Web Services Technology Preview. The main protocols related to
Web services are:
򐂰 JAX-RPC (JSR 101)
򐂰 Web services for J2EE (JSR 109)
JAX-RPC
Some of the fundamental features of the JAX-RPC are:
򐂰 Defines a Java API that is XML-based, but maintains the extensible and
modular mechanisms to support future version of various XML specifications.
This API is designed for Web service and client development in which the use
of remote procedure calls (RPC) is presented. This remote procedure call is
represented by an XML-based protocol, as for example SOAP.
򐂰 Defines the needed support for translating WSDL into Java mapping and vice
versa.
򐂰 Defines APIs that are simple to use for Java developers, hiding the complexity
of the complex protocols. On the server side, developers specify the remote
procedures by defining methods in a Java interface. On the client side,
developers provide the service endpoint by specifying a URL and invoking the
methods on a local object that represent the remote object.
򐂰 Supports interoperability across heterogeneous platforms and environments,
allowing interaction between client and server in a synchronous
request-response mode or in a one-way mode.
Web services for J2EE

The Web services for J2EE specification defines the programming model and
architecture for implementing Web services in Java based on JSRs 67, 93, 101,
and future JSRs related to Web services standards. The list of JSRs may be
found at:
http://www.jcp.org/en/jsr/all
Web services for J2EE focuses on:

򐂰 The server side programming model and framework for implementing Web
services.
򐂰 The client side programming for using a Web service from Java.

򐂰 The use of known concepts, such as the EJB transaction model, security for
servlets, EJBs, or HTTP session state, for Web services usage and
implementation.
򐂰 How to extend the basic servlet/HTTP model to include dispatching of Web
services.
򐂰 The concrete model for developing and deploying a Web service on top of
J2EE.
Technology preview
One of the most important advantages of using the technology preview is that the
applications created are fully portable to other J2EE platforms. Therefore, we do
not have to worry about the J2EE platform that we are using if the platform
conforms to the J2EE specifications. The standard J2EE deployment files for
Web services are:
򐂰 Server side:
– webservices.xml—deployment descriptor
– ibm-webservices-bnd.xml—WebSphere-specific information
򐂰 Client side:
– webserviceclient.xml—deployment descriptor
– ibm-webservicesclient-bnd.xml—WebSphere-specific information
The Web service server can be based on a stateless session EJB or a

JavaBean. Meanwhile, the clients can be created using either an EJB, a servlet,
or an independent application client.
The technology preview is based on Apache Axis as a runtime engine, but also
incorporates some modifications to enhance its engine. Among these
enhancements it includes specialized serializers/deserializers for complex
objects to obtain better performance. Axis is SAX-based, which makes it faster
than other implementations that are based on DOM parsers (such as SOAP 2.3).
However, we have to work with a command-line tool, which is harder than using a
graphical tool such as WebSphere Studio Application Developer.
Installation
The code is available through developerWorks:
http://www7b.software.ibm.com/wsdd/downloads/web_services.html
The installation process for this tool can be found in Appendix A, “Installation and
setup” on page 427. Once the tool is installed we are ready to implement Web
services.
Chapter 17. WebSphere Web Services Technology Preview 319

Web services creation using the technology preview
In this section we demonstrate how we can create Web services using the
technology preview. We use the same weather forecast example that was
introduced in Chapter 12, “Weather forecast application” on page 187.
Important: The weather forecast example had to be modified to follow the

specifications provided by JAX-RPC (JSR 101) about the mapping of simple
types, where it is said that an xsd:dateTime type must be implemented by the
java.util.Calendar class. Check the specification in order to obtain a general
idea about every mapping.
We replaced the java.utilDate with java.util.Calendar in the Weather and

WeatherForecast classes for the examples in this chapter.
We divide this section into two blocks:

1. We create the Web service from an already developed JavaBean. We also
briefly discuss how to create a Web service from an EJB.
2. We create an EJB Web service from the WSDL file generated in the first
block. We also briefly discuss how to create a JavaBean Web service from a
WSDL file.
Therefore, we have one implementation bottom-up, starting with Java code and
generating the corresponding WSDL file, and one implementation top-down,
starting with a WSDL file and generating the corresponding Java code.
Configuration
The first thing to do is to configure the environment. We set the PATH and
include some JAR files in the class path of our machine to complete this task.
The command scripts used with the technology preview are located in the bin
subdirectory of the WebSphere Application Server Version 5 home directory.
A batch file as shown in Figure 17-1 can be used to configure this environment.
The TPsetup.bat and TPSetupClient.bat files are provided in the sample code:
\sg246891\sampcode\techprev\TPsetup.bat
\sg246891\sampcode\techprev\TPsetupClient.bat
The TPsetup.bat file is used for Web service implementation compiles and the
TPSetupClient.bat file is used for Web service client compile and run.

@echo off
set WAS_INSTALL_ROOT=d:\WebSphere\AppServer
@rem TP TechPreview
set TP=%WAS_INSTALL_ROOT%\lib\j2ee.jar
// these additions are only required for client compile and run
set TP=%TP%;%WAS_INSTALL_ROOT%\lib\jaxrpc.jar
set TP=%TP%;%WAS_INSTALL_ROOT%\lib\xerces.jar
set TP=%TP%;%WAS_INSTALL_ROOT%\lib\axis.jar
set TP=%TP%;%WAS_INSTALL_ROOT%\lib\commons-logging-api.jar
set TP=%TP%;%WAS_INSTALL_ROOT%\lib\ws-commons-logging.jar
set TP=%TP%;%WAS_INSTALL_ROOT%\lib\commons-discovery.jar
set TP=%TP%;%WAS_INSTALL_ROOT%\lib\qname.jar
set TP=%TP%;%WAS_INSTALL_ROOT%\lib\wsdl4j.jar
set TP=%TP%;%WAS_INSTALL_ROOT%\lib\webservices.jar
set TP=%TP%;%WAS_INSTALL_ROOT%\lib\saaj.jar
// this is required for all

set CLASSPATH=.;%TP%;%CLASSPATH%
set PATH=%WAS_INSTALL_ROOT%\bin;%WAS_INSTALL_ROOT%\java\bin;%PATH%;
Figure 17-1 Batch file to configure the environment: TPsetupClient.bat
Web service from JavaBean (bottom-up)

The process to generate a Web service from a Java bean using the Technology
preview tool is summarized by the steps presented in Figure 17-2.
The sample code is provided in the directory:

\sg246891\sampcode\techprev\bean
\sg246891\sampcode\techprev\bean\itso\wsoj\*.java
The starting point is a WAR file that contains the Java code:
\sg246891\sampcode\techprev\bean\ItsoWebServTechPrevWebStarter.war
We use the WebSphere Application Assembly Tool (AAT) to edit the WAR file.

J2EE EAR WebSphere 5
J2EE WAR file Web
Install the EAR J2EE EAR
JavaBean services
WS DD 8 J2EE WAR file support
JavaBbean
WSDL
WS DD
SEI class WSDL
SEI class
Package WAR in
7 EAR
Javabean added
as part of web.xml
Add SEI, WSDL,
J2EE WAR file 6 WS-DD to WAR
J2EE WAR file
JavaBean JavaBean
WS DD Copy in WEB-INF/ dir

CONFIGURED
WSDL WebServices DD
IBM binding
SEI class
1
Copy in WEB-INF/ dir
5
2 3 4
Service
endpoint WebServices DD
JavaBean Manually create
interface Java2WSDL WSDL WSDL2Java
IBM binding
class
Javabean in
WAR package (SEI) Options "-META-INF-Only
-server-side Bean"
Figure 17-2 Process to create a Web service from a JavaBean (bottom-up)
Follow these steps to create the Web service.
Step 1—Add bean as servlet to WAR file

Adding our bean to a WAR file is done as a servlet to the web.xml file, although
we know that it is a JavaBean and not a real servlet.
Consequently, we add the servlet name ( WeatherForecastServlet), and the

implementation class, itso.wsoj.WeatherForecast. The modifications done in
the web.xml are shown in bold in Figure 17-3.

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app id="WebApp">
<display-name>ItsoWebServTechPrevWeb</display-name>
<servlet id="Servlet_1042069331785">
<servlet-name>WeatherForecastServlet</servlet-name>
<servlet-class>itso.wsoj.WeatherForecast</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
</web-app>
Figure 17-3 Web.xml file with our bean setting as a servlet
To make the changes to the WAR file:

򐂰 Start the Application Assembly Tool from the WebSphere programs folder.
򐂰 Open the ItsoWebServTechPrevWebStarter.war file (Figure 17-4).
Figure 17-4 Application Assembly Tool to edit a WAR file

򐂰 You can see the three Java classes by expanding Files -> Resource Files.
򐂰 Select Web Components -> New (context):
– Enter WeatherForecastServlet as name.
– Enter itso.wsoj.WeatherForecast as servlet class name.
– Select Load on startup.
– Click OK.
򐂰 Select the ItsoWebServTechPrevWeb module. On the IBM Extensions page,
select Serve servlets by classname. Click Apply.
򐂰 Select File -> Save As and enter ItsoWebServTechPrevWeb.war as the file
name.
Step 2—Create service endpoint interface

In Step 2 we manually create our service endpoint interface (SEI) from the
JavaBean. This SEI represents the Web service port type to be published.
Alternatively the SEI may be one of the interfaces that the JavaBean implements.
The SEI contains the methods that we want to expose as a Web service. The
rules to create the SEI are:
򐂰 The interface must extend java.rmi.Remote.
򐂰 Each method must throw java.rmi.RemoteException.
򐂰 Only methods that conform with the JAX-RPC are allowed.
򐂰 Compile the SEI Java program.
The WeatherForecast class methods that we want to turn into Web services are:
public itso.wsoj.Weather getDayForecast(java.util.Calendar theDate)
public itso.wsoj.Weather[] getWeekForecast(java.util.Calendar startDate)
public int[] getWeekTemperatures(java.util.Calendar startDate)
From these method signatures we create the WeatherForecast_SEI class

(Figure 17-5).
package itso.wsoj;
public interface WeatherForecast_SEI extends java.rmi.Remote {
public Weather getDayForecast(java.util.Calendar theDate)

throws java.rmi.RemoteException;
public Weather[] getWeekForecast(java.util.Calendar startDate)
}
Figure 17-5 SEI for the weather forecast bean

Step 3—Generate WSDL from SEI
In this step we generate the WSDL file from the SEI class using the Java2WSDL
command tool located in the directory <was_install_root>\bin. The steps are:
򐂰 Include the SEI interface, and every referenced classes, in the class path so
that the Java2WSDL command can find them. Note that these must be the
.class files. We provide the source and class files in the itso subdirectory.
򐂰 Run the Java2WSDL command.
Tip: We provide skeleton .bat files in the techprev\xxxx directories for each
step that requires commands to be executed. Tailor the files with your drive
letter to make them work.
򐂰 Here is the sequence of commands to perform this step (you can find the
commands in the Runjava2wsdl.bat file in the bean directory, but you must
tailor it before running):
e:
cd \sg246891\sampcode\techprev\bean
e:\sg246891\sampcode\techprev\TPsetup.bat
set classpath=e:\sg246891\sampcode\techprev\bean;%CLASSPATH%
java2wsdl.bat itso.wsoj.WeatherForecast_SEI
򐂰 You will receive this message:
WSWS3006W: Warning: The -location was not set, the value
"file:undefined_location" is used instead.
This is because we do not specify the location point, the URL where our Web
service is available. This is automatically modified later when we install the
application in WebSphere Application Server Version 5.
򐂰 A WSDL file with the name WeatherForecast_SEI.wsdl is generated in the
directory \sg246891\sampcode\techprev\bean.
򐂰 Edit the WSDL to replace names such as in0 or out0 to the real Java name
values. This step can be avoided if we run the command Java2WSDL
-implClass itso.wsoj.WeatherForecast. The bean has to be compiled with
the debugger information on, in order to know the Java names. The
implementation class must contain methods having the same signatures as
those in the SEI (we created the SEI with the same signatures).
Note: Because the SEI is derived from the implementation class, the
implementation class is not required to list the SEI interface in the implements
clause of its class definition.
Figure 17-6 shows how to make these changes in our example.

...
<wsdl:message name="getDayForecastResponse">
<wsdl:part name="getDayForecastReturn" type="intf:Weather"/>
</wsdl:message>
<wsdl:message name="getDayForecastRequest">
<wsdl:part name="in0theDate" type="xsd:dateTime"/>
</wsdl:message>
<wsdl:message name="getWeekTemperaturesRequest">
<wsdl:part name="in0startDate" type="xsd:dateTime"/>
</wsdl:message>
<wsdl:message name="getWeekForecastResponse">
<wsdl:part name="getWeekForecastReturn" type="intf:ArrayOfWeather"/>
</wsdl:message>
<wsdl:message name="getWeekForecastRequest">
<wsdl:part name="in0startDate" type="xsd:dateTime"/>
</wsdl:message>
<wsdl:message name="getWeekTemperaturesResponse">
<wsdl:part name="getWeekTemperaturesReturn"
type="intf:ArrayOf_xsd_int"/>
</wsdl:message>
<wsdl:portType name="WeatherForecast_SEI">
<wsdl:operation name="getWeekTemperatures"
parameterOrder="in0startDate">
<wsdl:input message="intf:getWeekTemperaturesRequest"
name="getWeekTemperaturesRequest"/>
<wsdl:output message="intf:getWeekTemperaturesResponse"
name="getWeekTemperaturesResponse"/>
</wsdl:operation>
<wsdl:operation name="getWeekForecast" parameterOrder="in0startDate">
<wsdl:input message="intf:getWeekForecastRequest"
name="getWeekForecastRequest"/>
<wsdl:output message="intf:getWeekForecastResponse"
name="getWeekForecastResponse"/>
</wsdl:operation>
<wsdl:operation name="getDayForecast" parameterOrder="in0theDate">
<wsdl:input message="intf:getDayForecastRequest"
name="getDayForecastRequest"/>
<wsdl:output message="intf:getDayForecastResponse"
name="getDayForecastResponse"/>
</wsdl:operation>
</wsdl:portType>
...
Figure 17-6 Generated WSDL file modified

Step 4—Generate Web service deployment descriptors
In this step we generate the Web service deployment descriptor templates from
the WSDL file generated in step 3.
The steps to follow are:

򐂰 Generate the deployment description using the WSDL2Java command tool.
Options for the WSDL2Java command are:
WSDL2Java -verbose -META-INF-Only -server-side Bean -output dir wsdlURL
– verbose —to see a list of the generated files

– META-INF-Only—to not generate any Java classes, only the descriptors
– server-side Bean—to generate the server-side descriptors for a
bean-based Web service
– output—the output directory
– wsdlURL—URL or file system where the WSDL can be located
򐂰 Here is the sequence of commands to perform this step (you can use the
RunWsdl2Java.bat file):
wsdl2java.bat -verbose -META-INF-Only -server-side Bean

-output e:\sg246891\sampcode\techprev\bean
e:\sg246891\sampcode\techprev\bean\WeatherForecast_SEI.wsdl
򐂰 A sample output is shown here:
Parsing XML file: e:\sg246891\sampcode\techprev\bean\WeatherForecast_SEI.wsdl
Generating e:\sg246891\sampcode\techprev\bean\META-INF\webservicesclient.xml
Generating
e:\sg246891\sampcode\techprev\bean\META-INF\WeatherForecast_SEI_mapping.xml
Generating e:\sg246891\sampcode\techprev\bean\META-INF\ibm-webservicesclient-bnd.xml
Generating e:\sg246891\sampcode\techprev\bean\WEB-INF\webservices.xml
Generating e:\sg246891\sampcode\techprev\bean\WEB-INF\WeatherForecast_SEI_mapping.xml
Generating e:\sg246891\sampcode\techprev\bean\WEB-INF\ibm-webservices-bnd.xml
򐂰 The output files are the Web service deployment descriptors. Refer to
“Technology preview” on page 319 for further explanations about these files.
Step 5—Configure deployment descriptor

In this step we manually configure the Web service deployment descriptor file
webservices.xml. We modify the <servlet-link> tag with the proper value of the
servlet name, WeatherForecast in our case (Figure 17-7).

<!DOCTYPE webservices PUBLIC "....." ".....">
<webservices>
<webservice-description>
<webservice-description-name>WeatherForecast_SEIService
</webservice-description-name>
<wsdl-file>WEB-INF/WeatherForecast_SEI.wsdl</wsdl-file>
<jaxrpc-mapping-file>WEB-INF/WeatherForecast_SEI_mapping.xml
</jaxrpc-mapping-file>
<port-component>
<port-component-name>WeatherForecast_SEI</port-component-name>
<wsdl-port>
<namespaceURI>http://wsoj.itso</namespaceURI>
<localpart>WeatherForecast_SEI</localpart>
</wsdl-port>
<service-endpoint-interface>itso.wsoj.WeatherForecast_SEI
</service-endpoint-interface>
<service-impl-bean>
<servlet-link>WeatherForecastServlet</servlet-link>
</service-impl-bean>
</port-component>
</webservice-description>
</webservices>
Figure 17-7 webservices.xml with modified servlet-link
Step 6—Assemble the application WAR file

In this step we assemble the application WAR file by adding the generated files:
򐂰 The Java class for the SEI in its directory structure (itso.wsoj)
򐂰 The WSDL file into the WEB-INF directory (copy the generated file into the
generated WEB-INF directory)
򐂰 The Web services deployment descriptors in the WEB-INF directory.
To generate the WAR file, use the tool that is most convenient for it, for example:
򐂰 WebSphere Application Assembly Tool
򐂰 Application Developer
򐂰 JAR command (jar.exe) from <WAS-ROOT>\java\bin
To add these files to the WAR file we use these commands:

cd \sg246891\sampcode\techprev\bean
copy WeatherForecast_SEI.wsdl WEB-INF\
jar -uvf ItsoWebServTechPrevWeb.war itso WEB-INF/*

Step 7—Assemble an EAR file
In this step we assemble the WAR file into an enterprise application EAR file.
This step can be performed using Application Developer or the WebSphere
Application Assembly Tool.
The steps to create an EAR file with the Application Assembly Tool are:
1. Start the tool.
2. Open a new enterprise application.
3. Set the name to ItsoWebServTechPrev1.ear (click Apply).
4. Select Web Modules -> Import.
5. Locate the ItsoWebServTechPrevWeb.war file.
6. Set the context root to ItsoWebServTechPrevWeb.
7. Save the application as ItsoWebServTechPrev1.ear.
8. Close the tool (Figure 17-8).
Figure 17-8 Application Assembly Tool to create an EAR file
Step 8—Deploy the enterprise application to WebSphere

In this step we deploy the enterprise application into the WebSphere Application
Server Version 5. Refer to “Deployment of applications to WebSphere” on
page 340 to see the steps to perform this operation. The WSADMIN tool can be
used for interactive deployment:
$AdminApp installInteractive
e:/sg246891/sampcode/techprev/bean/ItsoWebServTechPrev1.ear
"-usedefaultbindings"

Web service from EJB (bottom-up)
The process to generate an EJB Web service bottom-up is very similar to the
process that we used in “Web service from JavaBean (bottom-up)” on page 321.
The steps to complete this Web service are shown in Figure 17-9.
J2EE EAR J2EE EAR

8 WebSphere 5
EJB Jar
EJB Jar J2EE WAR 9
EJB Enable
EJB
endptEnabler
WsRouterServlet Web
WS DD J2EE EAR
WS DD
Install services
WSDL
WSDL
EAR EJB Jar support
SEI class EJB
SEI class
WS DD
7 Package EJB Jar

WSDL
SEI class
in EAR
Add SEI, WSDL,

EJB Jar 6 WS-DD to EJB Jar
EJB Jar
EJB EJB
WS DD Copy in META-INF/ dir

CONFIGURED
WSDL WebServices DD
IBM binding
SEI class
1
Copy in META-INF/ dir
5
2 3 4
Service
endpoint WebServices DD
EJB Manually create interface Java2WSDL WSDL WSDL2Java
IBM binding
class
Staeteless (SEI) Options "-META-INF-Only
Session Bean -server-side EJB"
Figure 17-9 Process to create a Web service from an EJB (bottom-up)
We briefly describe these steps:

򐂰 Step 1—Take the stateless session bean that we want to turn into a Web
service.
򐂰 Step 2—Manually create the SEI Java code from the EJB with the methods
that are going to 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
<ejb-link> tag in webservices.xml with the value of the <ejb-name> 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 (in the EJB JAR file(
򐂰 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.
Web service from EJB (top-down)

The process to generate a Web service based on an EJB from a WSDL using the
technology preview tool is summarized in Figure 17-10.
J2EE EAR J2EE EAR WebSphere 5

6
EJB Jar EJB Jar J2EE WAR
Enable
EJB endptEnabler EJB
Web
WsRouterServlet J2EE EAR
WSDD
WS DD WS DD services
WSDL WSDL
EJB Jar support
SEI class
7 EJB
SEI class
WS DD
WSDL
SEI class
EJB Jar
4 EJB
WS DD
WSDL CONFIGURED
SEI class WebServices DD
IBM binding
3
1
*SEI Stateless
Implement Web
WSDL WSDL2Java *Web service implementation service from template
Session
EJB template EJB
*WS DD + Binding
Options "-server-side EJB" 2
Figure 17-10 Process to create an EJB Web service from a WSDL (top-down)
We are going to follow these steps in order to create our EJB Web service from
the WSDL generated previously.

The sample code is provided in the directory:
\sg246891\sampcode\techprev\ejb
\sg246891\sampcode\techprev\ejb\WeatherForecast_EJB.wsdl
\sg246891\sampcode\techprev\ejb\ItsoWebServTechPrevEJBStarter.jar
\sg246891\sampcode\techprev\ejb\wsoj\WeatherPredictor.java
The WSDL file includes the endpoint location:

<wsdlsoap:address location="http://localhost:9080/ItsoWebServTechPrevWeb2
/services/WeatherForecast_SEI"/>
Step 1—Generate Java code from the WSDL file

The first thing that we do in this step is locate the WSDL that we use to generate
the Web service. The location has to be a URL or the local file system.
To generate the Java code we use the WSDL2Java command:

WSDL2Java -verbose -server-side EJB -output directory wsdlURL
– verbose —to see a list of the generated files

– server-side EJB—to generate the server-side descriptors for an
EJB-based Web service
– output—the output directory
– wsdlURL—URL or file system where the WSDL can be located
򐂰 Here is a sequence of commands (RunWsdl2Java.bat) to perform this step:
wsdl2java.bat -verbose -server-side EJB

-output e:\sg246891\sampcode\techprev\ejb
e:\sg246891\sampcode\techprev\ejb\WeatherForecast_EJB.wsdl
Parsing XML file: e:\sg246891\sampcode\techprev\ejb\WeatherForecast_EJB.wsdl
Generating e:\sg246891\sampcode\techprev\ejb\itso\wsoj\Weather.java
Generating e:\sg246891\sampcode\techprev\...\Weather_Helper.java
Generating e:\sg246891\sampcode\techprev\...\Weather_Ser.java
Generating e:\sg246891\sampcode\techprev\...\Weather_Deser.java
Generating e:\sg246891\sampcode\techprev\...\WeatherForecast_SEI.java
Generating e:\sg246891\sampcode\techprev\...\WeatherForecast_SEISoapBindingStub.java
Generating e:\sg246891\sampcode\techprev\...\WeatherForecast_SEISoapBindingImpl.java
Generating e:\sg246891\sampcode\techprev\...\WeatherForecast_SEI_RI.java
Generating e:\sg246891\sampcode\techprev\...\WeatherForecast_SEIHome.java
Generating e:\sg246891\sampcode\techprev\...\WeatherForecast_SEIService.java
Generating e:\sg246891\sampcode\techprev\...\WeatherForecast_SEIServiceLocator.java
Generating e:\sg246891\sampcode\techprev\ejb\META-INF\webservicesclient.xml
Generating e:\sg246891\sampcode\techprev\ejb\...\WeatherForecast_EJB_mapping.xml
Generating e:\sg246891\sampcode\techprev\ejb\...\ibm-webservicesclient-bnd.xml
Generating e:\sg246891\sampcode\techprev\ejb\...\webservices.xml
Generating e:\sg246891\sampcode\techprev\ejb\...\ibm-webservices-bnd.xml

򐂰 A brief explanation of the different files is provided in Table 17-1.
Table 17-1 Server files explanation

File Explanation
Weather.java Class to represent the complex type

Weather
Weather_Helper.java Class to manage the serialization and

deserialization of the type Weather
Weather_Ser.java Classes to serialize and deserialize the

Weather_Deser.java type Weather
WeatherForecast_SEI.java Service endpoint interface of the

weather forecast Web service
WeatherForecast_SEI_RI.java EJB remote interface, extends the SEI

implementation
WeatherForecast_SEIHome.java EJB home interface
WeatherForecast_SEIService.java Service interface to specify the way to

return the SEI interface
WeatherForecast_SEISoapBindingImpl.java EJB bean implementation
WeatherForecast_SEIServiceLocator.java Localize and return the SEI interface,

implements the _SEIService
WeatherForecast_SEISoapBindingStub.java Stub class to be used by the client to

interact with the Web service
webservices.xml Server-side deployment descriptor and

ibm-webservices-bnd.xml IBM binding
WeatherForecast_EJB_mapping.xml JAX-RPC mapping file
webservicesclient.xml Client-side deployment descriptor and

ibm-webservicesclient-bnd.xml IBM binding, not used on server
Step 2—Complete EJB implementation

In step 2 we complete the EJB implementation in the skeleton files:
򐂰 Check that the Java file portType_RI.java corresponds to the name of the
port type defined in the WSDL <portType> element. In our case, the portType
is called WeatherForecast_SEI and the Java code generated is
WeatherForecast_SEI_RI.
򐂰 Check the EJB home interface, WeatherForecast_SEIHome, and make any
required modifications. No changes are required in our case.

򐂰 Edit the EJB implementation file WeatherForecast_SEISoapBindingImpl.
Complete all the template methods with the appropriate code and make any
other required changes.
It is really convenient to modify the name, because the word binding is not
desired. We rename the class to WeatherForecast_SEIBean.
Note: Remove the throw clause for java.rmi.RemoteException from the

implementation file because it is deprecated for an EJB.
In Figure 17-11, we see the original binding implementation and in Figure 17-12,
the modifications that we did to the methods to support our weather forecast
sample.
package itso.wsoj;
public class WeatherForecast_SEISoapBindingImpl implements javax.ejb.SessionBean{

private javax.ejb.SessionContext sessionContext = null;
public void ejbActivate() throws java.rmi.RemoteException {

}
public void ejbCreate() throws java.rmi.RemoteException {
}
public void ejbPassivate() throws java.rmi.RemoteException {
}
public void ejbRemove() throws java.rmi.RemoteException {
}
public javax.ejb.SessionContext getSessionContext() {
return sessionContext;
}
public void setSessionContext(javax.ejb.SessionContext sc) {
sessionContext = sc;
}
throws java.rmi.RemoteException {
return null;
}
public itso.wsoj.Weather[] getWeekForecast(java.util.Calendar startDate)
return null;
}
public itso.wsoj.Weather getDayForecast(java.util.Calendar theDate)

return null;
}
}
Figure 17-11 Original EJB skeleton generated by the WSDL2Java command

package itso.wsoj;
import jaa.util.*;
public class WeatherForecast_SEIBean implements javax.ejb.SessionBean{
private javax.ejb.SessionContext sessionContext = null;
public void ejbActivate() {}

public void ejbCreate() throws javax.ejb.CreateException {}
public void ejbPassivate() {}
public void ejbRemove() {}
public javax.ejb.SessionContext getSessionContext() {
return sessionContext;
}
public void setSessionContext(javax.ejb.SessionContext sc) {
sessionContext = sc;
}
public int[] getWeekTemperatures(java.util.Calendar startDate) {

// ask predictor for an array for the given date
return WeatherPredictor.calculateTemperatureValues(startDate.getTime());
}
public itso.wsoj.Weather[] getWeekForecast(java.util.Calendar startDate) {

// if nothing is passed then use today's date
if (startDate == null)
startDate = Calendar.getInstance();
Calendar theDate = startDate;
// cretate the result array
Weather[] weatherForeCast = new Weather[7];
// for each day in the following week....
//...... rest of the code from WeatherForecast class
return weatherForeCast;
}
public itso.wsoj.Weather getDayForecast(java.util.Calendar theDate) {

// create a weather object and initialize with concrete day
Weather iWeather = new Weather();
iWeather.setDate(theDate);
// fill with values from the predictor
WeatherPredictor.calculateWeatherValues(iWeather);
return iWeather;
}
}
Figure 17-12 Modified EJB implementation
Step 3—Update the deployment descriptors

In this step we are going to configure the deployment descriptor. The only
change is the <ejb-link> tag in the webservices.xml file. The value of this
element has to be the same as the value of the <ejb-name> tag in the
ejb-jar.xml (Figure 17-13).

<!DOCTYPE webservices PUBLIC "..." "...">
<webservices>
<webservice-description>
<webservice-description-name>WeatherForecast_SEIService
</webservice-description-name>
<wsdl-file>META-INF/WeatherForecast_EJB.wsdl</wsdl-file>
<jaxrpc-mapping-file>META-INF/WeatherForecast_EJB_mapping.xml
</jaxrpc-mapping-file>
<port-component>
<port-component-name>WeatherForecast_SEI</port-component-name>
<wsdl-port>
<namespaceURI>http://wsoj.itso</namespaceURI>
<localpart>WeatherForecast_SEI</localpart>
</wsdl-port>
<service-endpoint-interface>itso.wsoj.WeatherForecast_SEI
</service-endpoint-interface>
<service-impl-bean>
<ejb-link>WeatherForecast_SEI</ejb-link>
</service-impl-bean>
</port-component>
</webservice-description>
</webservices>
Figure 17-13 webservices.xml modified with the ejb-link change
You can safely delete the two client deployment descriptors. They are not
required inside the EJB JAR file:
򐂰 webservicesclient.xml
򐂰 ibm-webservicesclient-bnd.xml
Step 4—Assemble an EJB JAR file

In this step we assemble the application into an EJB JAR file. To complete this
step, we add the following files to the starter EJB JAR file:
򐂰 All classes generated by WSDL2Java in the previous step with the
modifications.
򐂰 The WeatherForecastPredictor class (used by the session EJB).
򐂰 The WSDL file (into META-INF).
򐂰 The webservices.xml and ibm-webservices-bnd.xml deployment descriptors.

This step can be performed by the Application Developer or the Application
Assembly Tool. Alternatively we can use commands to compile the files and add
them to the starter JAR file (see RunCreateEjbJar.bat file):
e:\sg246891\sampcode\techprev\TPsetupClient.bat
e:
cd \sg246891\sampcode\techprev\ejb
copy ItsoWebServTechPrevEJBStarter.jar ItsoWebServTechPrevEJB.jar

copy WeatherForecast_EJB.wsdl META-INF\WeatherForecast_EJB.wsdl
copy WeatherPredictor.java itso\wsoj\WeatherPredictor.java
jar -uvf ItsoWebServTechPrevEJB.jar itso META-INF/*
Step 5—Assemble an enterprise application EAR file

In this step we assemble the EJB JAR file into an enterprise application EAR file.
This step can be performed using Application Developer or the WebSphere
Application Assembly Tool.
The steps to create an EAR file with the Application Assembly Tool are:
1. Start the tool.
2. Open a new enterprise application.
3. Set the name to ItsoWebServTechPrev2.ear (click Apply).
4. Select EJB Modules -> Import.
5. Locate the ItsoWebServTechEJB.jar file.
6. Save the application as ItsoWebServTechPrev2.ear.
7. Close the tool.
Step 6—Enable the endpoint

In this step we add the service endpoint Web module (WAR) to the Web services
enabled application (EAR). The endptEnabler command is the tool that we use to
perform this addition.
We create one WAR file for each Web services-enabled EJB JAR. This WAR file
contains the Web services router servlet, which is responsible for receiving the
Web services request, making all the intermediate treatments of the information,
and returning the response.
The endptEnabler command can run in prompt mode or you can provide all the
parameters to the command. The three parameters are the EAR file, the name of
the generated Web model, and the context root of the Web module.

򐂰 A sample set of command is shown here (see RunEndptEnabler.bat):
endptEnabler.bat e:\sg246891\sampcode\techprev\ejb\ItsoWebServTechPrev2.ear
ItsoWebServTechPrevWeb2.war /ItsoWebServTechPrevWeb2
IBM WebSphere Application Server Release 5
Web Services Enterprise Archive Enabler Tool.
Copyright IBM Corp., 1997-2002
*** Backing up EAR file to:

e:\sg246891\sampcode\techprev\ejb\ItsoWebServTechPrev2.ear~
JSR 109 enabled EJB Jar file at name ItsoWebServTechPrevEJB.jar
Adding Endpoint WAR w/name = ItsoWebServTechPrevWeb2.war and contextRoot =

/ItsoWebServTechPrevWeb2
򐂰 The resulting URL to invoke the Web Service is:
http://host[:port]/context-root/services/port-component-name
http://localhost:9080/ItsoWebServTechPrevWeb2/services/WeatherForecast_SEI
Note: The endptEnabler command cannot be run on the same EAR file more
than once.
Step 7—Deploy the enterprise application to WebSphere

In this step we deploy the enterprise application into the WebSphere Application
Server Version 5. Refer to “Deployment of applications to WebSphere” on
page 340 to see the steps to perform this operation.
Web service from JavaBean (top-down)

The process to generate a Web service based on a Java Bean from a WSDL
using the technology preview tool is summarized in Figure 17-14.
This process is very similar to “Web service from JavaBean (bottom-up)” on

page 321 and “Web service from EJB (top-down)” on page 331.

J2EE EAR WebSphere 5
EJB WAR
J2EE Jar
JavaBean
EJB Web
J2EE EAR
WSDD
WS DD services
WSDL
6 J2EE WAR support
JavaBean
SEI class
WS DD
WSDL
SEI class
J2EE WAR
4 JavaBean
WS DD
WSDL CONFIGURED
SEI class WebServices DD
IBM binding
3
1
*SEI
Implement Web
WSDL WSDL2Java *Web service implementation service from template JavaBean
Java Bean template
*WS DD + Binding
Options "-server-side Bean" 2
Figure 17-14 Process to create a JavaBean Web service from a WSDL (top-down)
Now, we briefly describe these steps:

򐂰 Step 1—Generate the Web service deployment descriptor templates and the
implementation files from the WSDL using the WSDL2Java command.
򐂰 Step 2—Complete the implementation of the bean.
򐂰 Step 3—Configure the Web service deployment descriptor. Modify the
<servlet-link> tag in webservices.xml with the value of the <servlet-name>
tag in the web.xml.
򐂰 Step 4—Assemble all the files previously generated 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).
򐂰 Step 6—Deploy the application into WebSphere Application Server Version 5.

Deployment of applications to WebSphere
Deployment of an enterprise application generated by the technology preview is
the same as for any other enterprise application. See Chapter 19, “Web services
runtime and deployment in WebSphere” on page 401 for information about
deployment tools.
However, installing the technology preview introduces changes to the enterprise

application installation window and GUI.
Using the command-line tool

For illustration purposes, we describe here how to install the generated
applications using the WSADMIN command tool.
The commands to install the two applications are:

rem Be sure to start the WebSphere Server before running the commands
rem You must use forward slashes / where indicated
d:\WebSphere\AppServer\bin\wsadmin
e:/sg246891/sampcode/techprev/bean/ItsoWebServTechPrev1.ear
"-usedefaultbindings"
e:/sg246891/sampcode/techprev/ejb/ItsoWebServTechPrev2.ear
"-usedefaultbindings -deployejb"
$AdminConfig save
During execution of this command, you are prompted for input at each step, but
you can just press Enter to accept the default.
The only prompt where you may want to change the default is when asked about
a directory for a modified WSDL file that includes the endpoint address. The
default is no output; only if you enter a directory name—which must exist— is the
WSDL file published.
Example 17-1 shows the prompt window for the installation of the EJB example.
Example 17-1 Installation of the EJB enterprise application (abbreviated)

D:\WebSphere\AppServer\bin>wsadmin
WASX7209I: Connected to process "server1" on node FUNDY using SOAP connector;
The type of process is: UnManagedProcess
WASX7029I: For help, enter: "$Help help"

wsadmin>$AdminApp installInteractive
m:/sg246891/sampcode/techprev/ejb/ItsoWebServTechPrev2.ear
"-usedefaultbindings -deployejb"
JNDI prefix for EJBs: [ejb]:
Default virtual host name: [default_host]:
Overwrite existing bindings: [No]:
File name for custom strategy: [null]:
Task[4]: Binding Enterprise Beans to JNDI Names ...

EJB Module: ItsoWebServTechPrevEJB
EJB: WeatherForecast_SEI
URI: ItsoWebServTechPrevEJB.jar,META-INF/ejb-jar.xml
JNDI Name: [ejb/itso/wsoj/WeatherForecast_SEIHome]:
Task[13]: Selecting Virtual Hosts for Web Modules ...

Web Module: WebSphere Web Service
URI: ItsoWebServTechPrevWeb2.war,WEB-INF/web.xml
Virtual Host: [default_host]:
Task[14]: Selecting Application Servers ...

Module: ItsoWebServTechPrevEJB
Server: [WebSphere:cell=FUNDY,node=FUNDY,server=server1]:
Module: WebSphere Web Service
URI: ItsoWebServTechPrevWeb2.war,WEB-INF/web.xml
Server: [WebSphere:cell=FUNDY,node=FUNDY,server=server1]:
Task[15]: Selecting Method Protections for Unprotected Methods for 1.x EJB ...
EJB Module: ItsoWebServTechPrevEJB
Deny All Access: []:
Task[18]: Specifying Application Options ...

Pre-compile JSP: [No]:
Directory to Install Application: []:
Distribute Application: [Yes]:
Use Binary Configuration: [No]:
Deploy EJBs: [Yes]:
Application Name: [ItsoWebServTechPrev2.ear]:
Create MBeans for Resources: [Yes]:
Enable class reloading: [No]:
Reload Interval: [3]:
Task[19]: Specifying EJB Deploy Options ...

Deploy EJBs Option - Classpath: []:
Deploy EJBs Option - RMIC: []:
Deploy EJBs Option - Database Type: [DB2UDB_V72]:
Deploy EJBs Option - Database Schema: []:

Task[20]: Get the directory into which an application's WSDL files are to be
published. Each WebService enabled JAR or WAR in an application has one or more
associated WSDL files. If you wish to create a published version of these WSDL
files, provide the name of a directory into which they should be published. If
no directory name is provided then no WSDL files will be published.
Directory for published WSDL files: []: d:\wsdl
Setting "Directory for published WSDL files" to "d:\wsdl"
Task[21]: Get the protocol, host, and port for the Web Services server
Get the protocol, host, and port for the Web Services server
Module: ItsoWebServTechPrevEJB
Protocol (http or https): [http]:
host name: [FUNDY]:
port : [9080]:
Retrieving document at 'file:C:\DOCUME~1\FUNDY\LOCALS~1\Temp\
DeployUtilsTmpDir1042912697562/META-INF/WeatherForecast_EJB.wsdl'.
ADMA5016I: Installation of ItsoWebServtechPrev2.ear started.
ADMA5018I: Starting EJBDeploy on ear C:\Documents and Settings\FUNDY\
Local Settings\Temp\app2649.ear..
Starting workbench.
Creating the project.
Building: /ItsoWebServTechPrevEJB.
Deploying jar ItsoWebServTechPrevEJB
Generating deployment code
Building: /ItsoWebServTechPrevEJB.
Invoking RMIC.
Writing output file
Shutting down workbench.
EJBDeploy complete.
0 Errors, 0 Warnings, 0 Informational Messages
ADMA5007I: EJBDeploy completed on C:\DOCUME~1\FUNDY\LOCALS~1\Temp\
app_f2d270e069\dpl\dpl_ItsoWebServtechPrev2_ear.ear
ADMA5005I: Application ItsoWebServtechPrev2.ear configured in WebSphere
repository
ADMA5001I: Application binaries saved in
D:\WebSphere\AppServer\wstemp\Scriptf2cd8d08ac\workspace\cells\FUNDY\
applications\ItsoWebServtechPrev2.ear.ear\ItsoWebServtechPrev2.ear.ear
ADMA5011I: Cleanup of temp dir for app ItsoWebServtechPrev2.ear done.
ADMA5013I: Application ItsoWebServtechPrev2.ear installed successfully.

Using the administrative console
When you install the technology preview, the administrative GUI is modified to
include additional steps for publishing of the modified WSDL file and the protocol
and port of the installed Web service (Figure 17-15).
Figure 17-15 Installing an enterprise application with the administrative console
The other installation steps are the same as without the technology preview.
Do not forget to save the configuration after installing enterprise applications.
Start the enterprise applications

A newly installed enterprise application is in stopped status and must be started.
You can use the administrative console or the WSADMIN tool. The commands in
WSADMIN are:
set appManager [$AdminControl queryNames
cell=mycell,node=mynode,type=ApplicationManager,process=server1,*]
$AdminControl invoke $appManager startApplication ItsoWebServTechPrev1.ear

Client creation using the technology preview
Once that the Web services are created, we can develop the clients for those
Web services. In this section, we provide enough information to perform this
operation.
The client programming model follows the Web services for J2EE specification.
In this model, there is a remote interface or stub that is used by the client to
interact with the Web service. Therefore, the client cannot distinguish whether
the methods are being performed locally or remotely. It only accesses using a
service endpoint interface as defined by the JAX-RPC specification. When the
client runs inside a J2EE application, the service is located using a JNDI lookup.
There are four places where a Java Web services client can reside:
򐂰 As an unmanaged stand-alone Java (J2SE) application.
򐂰 In an application client container (J2EE).
򐂰 A JavaBean or servlet running in a J2EE Web container acting as a client.
򐂰 An EJB or JavaBean running in a J2EE EJB container acting as a client.
Except for minor differences, all of them use similar techniques in their
development.
Stand-alone client
We provide a stand-alone client example that can run with both Web services
developed in this chapter: the bean Web service created in “Web service from
JavaBean (bottom-up)” on page 321 and the EJB Web service created in “Web
service from EJB (top-down)” on page 331.
Note: We develop the client using the WSDL file of the EJB example.
However, because the interface of both Web service examples is the same,
we can use the generated client to access either of the two deployed Web
services by using the appropriate WSDL file as input at runtime.
Figure 17-16 provides a summary of the steps necessary to create the client.

Manually create Java client
WebSphere 5
2
Java client SOAP request and
respose Web Service Enabled
J2EE EAR
Client
supporting
classes
3
Web services
WSDL support
Ignore Client Deployment

Description; it is not used in
a stand-alone Java client
1
WS Client DD
WSDL2Java WS Client IBM Binding DD
WSDL
Java code for Client SEI,
ServiceLocator, etc
Figure 17-16 Process to create a stand-alone Java client
Step 1—Generate skeleton Java client code

In this step, we generate all the required templates for the client implementation
and the deployment descriptors. In this case, the client is a stand-alone Java
client application and thus the deployment descriptors can be ignored.
To create the skeleton code we use the WSDL2Java command (you can use the
RunWsdl2java.bat file). As input we use the WSDL file from the EJB example:
wsdl2java.bat -verbose -output e:\sg246891\sampcode\techprev\client

򐂰 Sample output is shown here:
Parsing XML file:
Generating e:\sg246891\sampcode\techprev\client\itso\wsoj\Weather.java
Generating e:\sg246891\...\Weather_Helper.java
Generating e:\sg246891\...\Weather_Ser.java
Generating e:\sg246891\...\Weather_Deser.java
Generating e:\sg246891\...\WeatherForecast_SEI.java
Generating e:\sg246891\...\WeatherForecast_SEISoapBindingStub.java
Generating e:\sg246891\...\WeatherForecast_SEIService.java
Generating e:\sg246891\...\WeatherForecast_SEIServiceLocator.java

Generating e:\sg246891\...\client\META-INF\webservicesclient.xml
Generating e:\sg246891\...\client\META-INF\WeatherForecast_EJB_mapping.xml
Generating e:\sg246891\...\client\META-INF\ibm-webservicesclient-bnd.xml
򐂰 The meaning of the generated elements is explained in Table 17-2.
Table 17-2 Client files explanation

File Explanation
Weather.java Class to represent the complex type

Weather in the client side
Weather_Helper.java Class to manage the serialization and

deserialization of the type Weather
Weather_Ser.java Class to serialize and deserialize the

Weather_Deser.java type Weather
WeatherForecast_SEI.java Service endpoint interface of the

weather forecast Web service
WeatherForecast_SEISoapBindingStub.java Stub class to be used by the client to

interact with the Web service
WeatherForecast_SEIService.java Service interface to specify the way to

return the SEI Interface
WeatherForecast_SEIServiceLocator.java Localize and return the SEI Interface,

implements the _SEIService
webservicesclient.xml Client-side deployment descriptor and

ibm-webservicesclient-bnd.xml IBM binding
WeatherForecast_EJB_mapping.xml JAX RPC mapping
Step 2—Create Java client

In this step, we manually create the stand-alone client using the Java code
classes generated in the previous step. The main functionality of our client code
can be split into three operations:
1. Retrieve a vector with the endpoint addresses for SOAP binding presented in
the WSDL document provided.
2. Use the first of these endpoint addresses to create a service stub to connect
to the Web service.
3. Interact with the stub to retrieve the information that we request.

An extract of the client code is shown in Figure 17-17.
....
public class Client {
....
try {
....
Vector endPoint =
getWSDLPort(args[0],"WeatherForecast_SEIService");
//get the first address connection
URL serviceEndPoint = new URL((String)endPoint.get(0));
System.out.println("Endpoint "+serviceEndPoint.toString());
//create the stub to connect to the Web service
service = new WeatherForecast_SEIServiceLocator();
soap = service.getWeatherForecast_SEI(serviceEndPoint);
week = soap.getWeekForecast(Calendar.getInstance());
....
//gets today weather forecast
today = soap.getDayForecast(Calendar.getInstance());
....
//gets weekly temperatures
temp = soap.getWeekTemperatures(Calendar.getInstance());
....
}
....
Figure 17-17 Stand-alone client implementation (extract)
The client code is provided in the directory:

\sg246819\sampcode\techprev\client
Step 3—Compile and run the client

Before you can run the client, the enterprise application must be installed in
WebSphere Application Server. In addition:
򐂰 The client code must be copied to the itso\wsoj directory and all the source
code must be compiled. Use the RunCompile.bat file to compile the code.
򐂰 The WSDL documents must have valid endpoints (SOAP addresses):
– For WeatherForecast_SEI.wsdl:
<wsdlsoap:address location="http://localhost:9080/
ItsoWebServTechPrevWeb/services/WeatherForecast_SEI"/>

– For WeatherForecast_EJB.wsdl:
<wsdlsoap:address location="http://localhost:9080/
ItsoWebServTechPrevWeb2/services/WeatherForecast_SEI"/>
To run the client use these commands (use the command files RunClientWeb.bat
and RunClientEJB.bat):
e:
cd \sg246891\sampcode\techprev\client
e:\sg246891\sampcode\techprev\client\WeatherForecast_SEI.wsdl
e:\sg246891\sampcode\techprev\client\WeatherForecast_EJB.wsdl
An example of the result generated is shown here:

Retrieving document at
'e:\sg246891\sampcode\techprev\client\WeatherForecast_SEI.wsdl'.
Endpoint http://localhost:9080/ItsoWebServTechPrevWeb
/services/WeatherForecast_SEI
Weekly weather forecast for next week...
Weather: Fri. Jan 10, 2003 'stormy' wind: NE 31km/h 9 Celsius
Weather: Sat. Jan 11, 2003 'rainy' wind: SE 13km/h 14 Celsius
Weather: Sun. Jan 12, 2003 'partly cloudy' wind: SW 27km/h -7 Celsius
Weather: Mon. Jan 13, 2003 'sunny' wind: S 25km/h 1 Celsius
Weather: Tue. Jan 14, 2003 'stormy' wind: N 18km/h 6 Celsius
Weather: Wed. Jan 15, 2003 'rainy' wind: NE 21km/h -8 Celsius
Weather: Thu. Jan 16, 2003 'partly cloudy' wind: SW 27km/h 23 Celsius
Today weather forecast...
Weather: Fri. Jan 10, 2003 'cloudy' wind: SW 31km/h 0 Celsius
Weekly temperatures forecast for next week...
Day 1: 46 Celsius
Day 2: 20 Celsius
Day 3: 23 Celsius
Day 4: 17 Celsius
Day 5: 26 Celsius
Day 6: 45 Celsius
Day 7: 18 Celsius
A stand-alone Java client can have a variety of applications, especially when it is

not possible to use an application server. To a more complex and also more
dynamic client development, refer to Chapter 18, “Web services scenario:
architecture and implementation” on page 353.

Stand-alone client simplified
The parsing of the WSDL file is quite complicated. The client code can be
simplified very much by using the address that is generated into the
WeatherForecast_SEIServiceLocator source code:
private final java.lang.String WeatherForecast_SEI_address =
"http://localhost:9080/ItsoWebServTechPrevWeb2/services/WeatherForecast_SEI";
The WeatherForecast_SEIServiceLocator class also provides two methods to

get the port:
getWeatherForecast_SEI() uses default address
getWeatherForecast_SEI(java.net.URL portAddress) pass address
Using these methods the client code can be simplified as shown in Figure 17-18.
public class Client1 {

Weather week[] = new Weather[7];
Weather today = null;
int temp[]= new int[7];
try {
WeatherForecast_SEI soap = null;
if (args.length == 0)
soap = loc.getWeatherForecast_SEI(); ==> default
else
soap = loc.getWeatherForecast_SEI( new java.net.URL(args[0]) );

week = soap.getWeekForecast(Calendar.getInstance());
System.out.println("Weekly weather forecast for next week...");
for (int i = 0; i < week.length; i++)
System.out.println(printWeather(week[i]));
...............
}
catch (Exception e) {
e.printStackTrace();
}
}
Figure 17-18 Simplified stand-alone client

To run the simplified client use these commands (RunClient1.bat):
e:
cd \sg246891\sampcode\techprev\client
echo EJB service

java itso.wsoj.Client1
echo JavaBean service

java itso.wsoj.Client1
http://localhost:9080/ItsoWebServTechPrevWeb/services/WeatherForecast_SEI
Outlook
In the future releases of the Web Services Technology Preview, more features
will be added, including the update of the protocols related to Web services.
Some of these upgrade features are:
򐂰 Technology preview incorporated into WebSphere Application Server
򐂰 Update to latest specifications:
– SOAP 1.2
– WSDL 1.2
– WS-Security, WS-Transactions, WS-Coordination, WS-*
– Web services metadata for the Java platform (JSR 181)
򐂰 Additional transport/protocol support
򐂰 Tighter integration with WebSphere Application Server, for example
Application Assembly Tool (AAT) and enhanced systems management
򐂰 Performance enhancements
򐂰 Protocol/transport autonomy
򐂰 Registry publication (UDDI, WSIL, etc.)
򐂰 Load management of Web services
򐂰 Simplified deployment model
򐂰 Additional caching support

Summary
In this chapter we have learned how to create Web services using the Web
Services Technology Preview. This preview supposes an early adoption of J2EE
1.4 standards. We have learned the process to create bottom-up and top-down
Web services. We have also learned how we can create a client to use the Web
services previously created. This client provides also an example of how we can
use the WSDL4J to retrieve the information about the endpoint where the
services are available.
We have discovered and used the command tools provided to assist us in the
generation process of these applications. These command tools reduce the time
required to create the clients and Web services applications.
More information
After installing the code you can find more information about the Web Services
Technology Preview in the online documentation at:
<was_install_root>\TechPreview\WebServices\docs\index.html
This documentation provides pointers to other interesting resources and covers

in detail the generation of Web services applications and clients. Other useful
resources can be found at:
򐂰 JAX-RPC:
http://java.sun.com/xml/jaxrpc
򐂰 Web services in J2EE (JSR 109):
http://jcp.org/jsr/detail/109.jsp
http://www.ibm.com/developerworks/offers/webservices/JSR109/

18
Chapter 18. 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 two different client implementations

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 12,
“Weather forecast application” on page 187. This example contains a Web
service to be created from a JavaBean. Now we extend this by introducing
several providers for that service and a requestor that integrates the services into
a local application. Furthermore, security features are applied.
We decided to focus on a single tool, WebSphere Studio Application Developer.

It is the tool to use for tasks in a standard project:
򐂰 Application Developer Integration Edition offers the same functionality plus
extra features, such as work flow (see Chapter 10-1, “WebSphere product
family” on page 160 for details). These additional tools, however, are not
commonly used.
򐂰 The other tools presented in the book (Web Services Toolkit and the
Technology Preview) provide new technologies that will be incorporated into
further versions of Application Developer. These technologies are also due to
change. Neither tool offers the basic 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 service and discuss the challenges in creating
a client. (We do not cover the creation of the service.)
We assume the following situation:

򐂰 There are several companies that provide weather forecasts. We introduce
two companies:1
– SiliconWeather (siliconweather.com)
– FlashAndThunder (flashandthunder.com).
1
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.

򐂰 Furthermore, there is an umbrella organization 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. Both service providers are members of IWA.
򐂰 Finally, our scenario contains an integrator, UnitedSuns (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. Here we use the functionality used in the previous chapters
and described in Chapter 11, “Web services development overview” on
page 175. 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 the service
providers, while UnitedSuns acts as the service requestor. Furthermore, a
UDDI registry is used to publish and retrieve Web services.
򐂰 Providers generate Web services, WSIL documents, and WSDL documents
according to a given 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 interface and publish their own
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).
Chapter 18. Web services scenario: architecture and implementation 355

򐂰 Invoke the services of the providers and process the result into a Web page.
Figure 18-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.
IWA
Silicon FlashAnd
publish reference Weather Thunder
retrieve
to defined standard reference
publish
service
UDDI
invoke service
find services
United
Suns
Figure 18-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. We focus only on security, where we identify the
following requirements:
򐂰 Authentication and authorization for accessing a service
򐂰 Secure transmission of requests and responses
Furthermore, both providers would like to be able to change their implementation

and binding 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 dynamic service invocation.
򐂰 HTTP security (SSL) and WebSphere security. For experimental purposes,
only SiliconWeather uses HTTPS.
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 and the business logic that uses the proxies.
3. Deployment phase of the client application—Next the developed application
is deployed into an environment that supports 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.
These phases refer to the four phase model described in Chapter 11, “Web
services development overview” on page 175. For our example, we do not focus
on the management phase presented in that chapter.

Two 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):
򐂰 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.
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 bindings change quite
often. Otherwise, a static invocation only during build time is acceptable.
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 make sense in cases where the
provider is fixed and offers several implementations of the same service, or the
binding 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. In particular, the actions shown in Figure 18-2
are performed.

service
IWA providers UDDI
define and store

interface WSDL
publish business entity, tModel
retrieve tModelKey
retrieve interface WSDL
generate Web service;

store service
WSDL locally
deploy
Web service
publish business entity,
publish service
generate and store

WSIL locally
Figure 18-2 Setup phase
򐂰 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 WeatherForecastBinding.wsdl and WeatherForecast.wsdl files
have to be provided. (The WeatherForecastService.wsdl file 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.
This publishing processes is 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 13, “WebSphere Studio Application
Developer” on page 197 describes these steps in much detail. The automated
process also generates an implementation WSDL document
(WeatherForecastService.wsdl), which includes the service element that
contains the actual bindings.
򐂰 Each provider deploys the Web service(s) to a WebSphere Application
Server. See Chapter 19, “Web services runtime and deployment in
WebSphere” on page 401 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 13, “WebSphere Studio Application Developer” on page 197 for
details.) The service document, together with a binding template, describes
the implemented service. The binding template contains the access point of
the service (in our case the URL of the RPC router of the service). Again, no
WSDL is published to the registry.
򐂰 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 18-3 shows the entities and their relationship created during the setup
phase.

IWA UDDI registry Silicon
SW F&T
Weather
IWA
Business Business Business
Entity Entity Service
Entity
WSDL
SW F&T
WSIL
Business Business
Service Service
Interface
WSDL
Binding Binding FlashAnd
Template Template Thunder
flash
tModel Service
WSDL
thunder
Service
link WSDL
WSDL URL
access point
WSIL
Figure 18-3 Relationship of entities provided by IWA and the two providers
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.
We perform the steps shown in Figure 18-4.

UnitedSuns service
clerk UDDI IWA providers
find IWA business entry
Sample 1:
Lookup
over UDDI retrieve IWA tModel
retrieve interface WSDL
retrieve WSIL
Sample 2:
Lookup
retrieve WSDL
over WSIL
Figure 18-4 Retrieving the WSDL implementation file in the build phase
򐂰 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 download the WSIL files, which are by definition located at:
http://siliconweather.com/inspection.wsil
http://flashandthunder.com/inspection.wsil
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 13, “WebSphere Studio Application Developer” on
page 197, we generate the client proxy.

򐂰 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 363 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 19, “Web services runtime and deployment in WebSphere” on
page 401. In this chapter we focus on how to ensure security of a deployed
application.
Run phase of the client application

Once UnitedSuns’ application has gone live, the automated steps are performed
as shown in Figure 18-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 (in our case the URL
of the RPC routers of the services).
򐂰 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.
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.

UnitedSuns service
application UDDI providers
retrieve service binding
Sample 1:
Lookup
over UDDI extract service
access point
invoke service
retrieve WSIL
Sample 2:
parse WSIL
Lookup
over WSIL retrieve WSDL
parse WSDL
invoke service
Figure 18-5 Run phase
After an Internet user has entered UnitedSuns (unitedsuns.com) and initiated the
integrated weather forecast, the client performs the following steps:
򐂰 Using the gained endpoint information, the client applies the proxy’s
setEndPoint(URL) method for each of the WSDL documents.
򐂰 The client uses the proxy’s getDayForecast, getWeekForecast, and
getWeekTemperatures methods to build its own content.
򐂰 The markup is returned to the browser.
In the next two section we provide more details on the implementation of sample
1 and sample 2.

General concepts of the 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 18-6).
Start JSP
enter information
preferences.jsp Servlet
lookup.jsp
process
client1.jsp information
Menu JSP client2.jsp access
choose sample UDDI and
or preferences Web
services
menu.jsp
SavePreferencesServlet
Response JSP LookupServlet
display results StartClient1Servlet
StartClient2Servlet
preferences.jsp
lookupResponse.jsp
Home page client1Response.jsp
present menu client2Response.jsp
index.html
Included page
reusable results
weatherObjects.jsp
UDDIremark.html
Figure 18-6 Application flow
Frames
When starting the application, a frame set displays a menu bar 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. The welcome window is shown in
Figure 18-7.

Figure 18-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.
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 (Figure 18-8) checks if security should be used,

creates the correct proxy, and invokes the method. The resulting Weather object
is returned, or an exception is thrown if a problem occurs.
protected Weather invokeService(String accessUrl) throws

MalformedURLException, Exception {
Weather w = null;
if(accessUrl.startsWith("https")) {
WeatherForecastSSLSecureProxy proxy=new WeatherForecastSSLSecureProxy(
getPreferences().getUserid(),
getPreferences().getPassword(),
getPreferences().getWebSphereInstallRoot());
proxy.setSecureEnvirontment();
proxy.setEndPoint(new URL(accessUrl));
w = proxy.getDayForecast(new Date());
}
else {
WeatherForecastProxy proxy = new WeatherForecastProxy();
proxy.setEndPoint(new URL(accessUrl));
w = proxy.getDayForecast(new Date());
}
trace("StartClient1Servlet.invokeService: proxy returned weather: " + w);
return w;
}
Figure 18-8 AbstractServlet: invokeService method
The invokeAll method (Figure 18-9) 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.

protected void invokeAll(Vector accessUrls) {
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);
invocations.add(w);
trace(aMessage= "<FONT color=\"red\">"+e.toString()+"</FONT>");
invokeMessage = "There were exceptions.";
invocations.add(aMessage);
}
}
getRequest().setAttribute("invocations", invocations);
getRequest().setAttribute("invokeMessage", invokeMessage);
}
Figure 18-9 AbstractServlet: invokeAll method
Secure proxy
We create a WeatherForecastSSLSecureProxy class to support the user
authentication and the use of an HTTP secure connection, HTTPS. This class
extends from the proxy class (WeatherForecastProxy) generated by Application
Developer.
The proxy class has been slightly modified to allow the secure proxy the required
access to the Call object, so that attributes can be set to invoke the Web service.
The Call object is changed from private to protected.
The secure proxy mainly adds two important methods, one to authenticate the
user, and one to set the secure connection environment. The methods are:
򐂰 GetSOAPConnection—this method uses a SOAPHTTPConnection object (from
org.apache.soap.transport.http) to set the user identification and password
to connect to the service (Figure 18-10).

private SOAPHTTPConnection getSOAPConnection() {
if (httpconn == null) {
httpconn = new SOAPHTTPConnection();
httpconn.setUserName(getUserid());
httpconn.setPassword(getPassword());
}
return httpconn;
}
Figure 18-10 Secure proxy: SOAPHTTPConnection method
򐂰 InitializeSSLEnvironment—this method sets the environment properties to

allow the proxy to create a secure connection using HTTPS (Figure 18-11).
For our example, we use the dummy keyrings certificates provided with
WebSphere Application Server and include in the preferences the possibility
to provide the WebSphere Application Server installation root. The dummy
keyrings can be found in the was_install_root/etc directory.
Notes:
򐂰 If you create your own self-signed certificate for the SiliconWeather HTTP
server, you have to include the server as a trusted authority in the
was_install_root/etc/DummyClientTrustFile.jks file for the server
where the SiliconWeather application is running.
򐂰 On the other hand, if you use a certificate from a trusted authority you do
not have to make any changes. More information on managing security
and certificates can be found in the redbook IBM WebSphere V5.0
Security: WebSphere Handbook Series, SG24-6573.

private void initializeSSLEnvironment(String wasRoot) {
clientkeyfile = wasRoot + "etc/DummyClientKeyFile.jks";
keypassword = "WebAS";
clienttrustfile = wasRoot + "etc/DummyClientTrustFile.jks";
trustpassword = "WebAS";
try {
if (Security.getProvider("com.ibm.jsse.JSSEProvider") == null) {
Security.addProvider(new com.ibm.jsse.JSSEProvider());
}
}
return;
}
// Update the system properties
Properties properties = System.getProperties();
properties.put("java.protocol.handler.pkgs",
"com.ibm.net.ssl.internal.www.protocol");
properties.put("javax.net.ssl.keyStore",clientkeyfile);
properties.put("javax.net.ssl.keyStorePassword",keypassword);
properties.put("javax.net.ssl.trustStore",clienttrustfile);
properties.put("javax.net.ssl.trustStorePassword",trustpassword);
System.setProperties(properties);
try {
// Load the JKS format KeyStore
KeyStore ks = KeyStore.getInstance(keyStoreFormat);
ks.load(new FileInputStream(wasRoot + "etc/DummyClientKeyFile.jks"),
keypassword.toCharArray());
// Create and initialize the KeyManagerFactory
KeyManagerFactory kmf =
KeyManagerFactory.getInstance(keyMgrFactoryType);
kmf.init(ks, keypassword.toCharArray());
// Create and initialize the TrustManagerFactory
TrustManagerFactory tmf =
TrustManagerFactory.getInstance(keyMgrFactoryType);
tmf.init(ks);
// Get and init the SSLContext that supports SSL
sslCtx = SSLContext.getInstance(protocolType);
sslCtx.init(kmf.getKeyManagers(), tmf.getTrustManagers(), null);
}
}
}
Figure 18-11 The initializeSSLEnvironment method

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 18-12.
Figure 18-12 Displaying result weather objects returned by invoked services
The JSP code to display the results is shown in Figure 18-13.
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.

<jsp:useBean id="invokeMessage" class="java.lang.String" scope="request" />
<jsp:useBean id="invocations" class="java.util.Vector" scope="request" />
......
<%
Enumeration enum = invocations.elements();
String accessUrl = (String) enum.nextElement();
Object o = enum.nextElement();
%>
<TR>
<TD valign="top"><%= accessUrl %></TD>
<TD>
<%
/* distinguish between Weather result or String with exception*/
if (o instanceof String) { out.print(o); } else {
itso.wsoj.Weather w = (itso.wsoj.Weather) o;
%>
<%= w.getDate() %><BR>
<%= w.getCondition() %> <%= w.getTemperatureCelsius() %>°<BR>
Wind: <%= w.getWindDirection() %> <%= w.getWindSpeed() %>km/h
<% } %>
</TD>
</TR>
<% } %>
Figure 18-13 JSP code for displaying results of invoked services
Preferences
The preferences hold all settings that are used during runtime. The settings can
be changed by the user in an online window. These settings are:
򐂰 UDDI registry—specifying which registry to be used for all UDDI interactions.
You can choose one of the list, and you can also specify the inquire URL of
another registry if it is not listed. Note that for the sample in the redbook, all
UDDI interactions were done with the IBM test registry.
򐂰 Security—specifying if security features on client side will be used. This
affects the way the client connects to the Web Services. In our scenario one
server secures its Web service using HTTPS and authentication; therefore a
user ID and password have to be provided to access the implementer’s site.

Preferences class
The preferences are stored in a class called itso.wsdc.Preferences and can be
retrieved in any servlet by getPreferences().get<DesiredValue>. 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.
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 18-14 shows the JSP.
Figure 18-14 Preferences window

Preferences servlet
The servlet called itso.wsdc.SavePreferencesServlet is called when the form in
the preferences.jsp is submitted. It takes all the parameters of the form using
the getParameter method of the HTTPRequest object, such as registry and
security options, and stores them in the current preferences object in the HTTP
session. It then forwards the request to the preferences.jsp again to redisplay
the changed values.
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).
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 18-15 shows the lookup window.

Figure 18-15 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.
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 4, “Introduction to UDDI” on page 61.
Look up businesses
To look up a business entity, the find_business method of the UDDI4J API is
used. Figure 18-16 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)

protected boolean lookUpBusiness() {
// get the search string from the form
String business=
(String) getRequest().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()
.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
getRequest().setAttribute("resultBusiness", businesses);
success = true;
// trace any exception to the console
trace(message = "<FONT color=\"red\">" + e.toString() + "</FONT>");
}
// add the message to the request for the JSP to display
getRequest().setAttribute("messageBusiness", message);
return success;
}
Figure 18-16 Finding a business by name
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 18-17 shows an excerpt of the code of the lookUpService method in the
򐂰 Call the find_service method
򐂰 Retrieve the vector with service information (getServiceInfoVector)
򐂰 Pass the vector together with the message to the JSP
protected boolean lookUpServices() {

String searchString =
(String) getRequest().getParameter("searchStringService");
ServiceList allServices = null;
try {
Vector names = new Vector();
names.addElement(new Name(searchString));
allServices = getUddiProxy().find_service("",names,null,null,null,0);
Vector resultServices =
allServices.getServiceInfos().getServiceInfoVector();
message = "Found " + resultServices.size() + " service entries.";
getRequest().setAttribute("resultService", resultServices);
success = true;
}
getRequest().setAttribute("messageService", message);
return success;
}
Figure 18-17 Finding a service by name
Lookup tModels
When searching for a tModel entity, the find_tmodel method is used.
Figure 18-18 shows an extract of the code of the lookUpTModel method in the
򐂰 Call the find_tmodel method
򐂰 Retrieve the vector with tModel information (gettModelInfoVector)

protected boolean lookUpTModel() {
String searchString = (String)
getRequest().getParameter("searchStringTModel");
try {
TModelList tModelList =
getUddiProxy().find_tModel(searchString, null, null, null, 0);
Vector tModels = tModelList.getTModelInfos().getTModelInfoVector();
message = "Found " + tModels.size() + " tModel entries.";
getRequest().setAttribute("resultTModel", tModels);
success = true;
}
getRequest().setAttribute("messageTModel", message);
return success;
}
Figure 18-18 Finding a tModel by name
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. Figure 18-19
shows an extract of the code of the lookUpBinding method in the LookupServlet,
which shows how to:
򐂰 Call the find_binding method
򐂰 Retrieve the vector with binding information (getBindingTemplateVector)

protected boolean lookUpBinding() {
try {
// check in input parameters
String serviceKey = (String)
getRequest().getParameter("bindingServiceKey");
String tModelKey = (String)
getRequest().getParameter("bindingTModelKey");
if (serviceKey.trim().length()==0||tModelKey.trim().length()==0) {
message = "Need to specify search strings. Lookup skipped.";
getRequest().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().find_binding(null, serviceKey, tModelBag, 0);
// extract the bindings vector
Vector bindingTemplates = bd.getBindingTemplateVector();
// provide vector for JSP
getRequest().setAttribute("resultBinding", bindingTemplates);
success = true;
}
// provide message to JSP
return success;
}
Figure 18-19 Finding a binding for a given tModel and service
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 18-20.
Figure 18-20 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).
Figure 18-21 shows a code snippet of the JSP.
<%
for (int i=0; i<resultBusiness.size(); i++) {
BusinessInfo bi = (BusinessInfo) resultBusiness.elementAt(i);
%>
<TR class="business">
<TD colspan="2"><%= bi.getNameString() %></TD>
<TD nowrap><%= bi.getBusinessKey() %></TD>
<%
Vector serviceInfos = bi.getServiceInfos().getServiceInfoVector();
for (int j=0; j<serviceInfos.size(); j++) {
ServiceInfo si = (ServiceInfo) serviceInfos.elementAt(j);
%>
</TR><TR class="service">
<TD align="right">--Service--></TD>
<TD><%= si.getNameString() %></TD>
<TD nowrap><%= si.getServiceKey() %></TD>
<% } %>
</TR>
<% } %>
Figure 18-21 JSP code to display businesses and their services

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 18-22.
Figure 18-22 Services and associated tModels
The JSP code that is used to display the services and tModels is shown in
Figure 18-23.
<%
for (int j = 0; j < resultService.size(); j++) {
ServiceInfo serviceInfo = (ServiceInfo) resultService.elementAt(j);
%>
<TR class="service">
<TD nowrap><%= serviceInfo.getNameString()%></TD>
<TD nowrap><%= serviceInfo.getServiceKey()%></TD>
<TD nowrap><%= serviceInfo.getBusinessKey()%></TD>
</TR>
<% } %>
(...)
<%
for (int i=0; i<resultTModel.size(); i++) {
TModelInfo ti = (TModelInfo) resultTModel.elementAt(i);
%>
<TR class="tmodel">
<TD nowrap><%= ti.getNameString() %></TD>
<TD nowrap><%= ti.getTModelKey() %></TD>
</TR>
<% } %>
Figure 18-23 JSP code that extracts and displays services and tModels

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 18-24.
Figure 18-24 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 Figure 18-25.
<%
for (int i=0; i<resultBinding.size(); i++) {
BindingTemplate bt = (BindingTemplate) resultBinding.elementAt(i);
%>
<TR class="binding">
<TD><%= bt.getDefaultDescriptionString() %></TD>
<TD><%= bt.getBindingKey() %></TD>
<TD><%= bt.getAccessPoint().getURLType() %></TD>
<TD><%= bt.getAccessPoint().getText() %></TD>
<TD><%= bt.getServiceKey() %></TD>
<TD><%= bt.getHostingRedirector() %></TD>
</TR>
<% } %>
Figure 18-25 JSP part the presents the binding
Testing the UDDI lookup sample

The fields in the start page (Figure 18-15 on page 375) 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.
This client application already knows the interface WSDL and has a proxy object,
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 18-26). 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 18-26 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 ist called.
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 Figure 18-27.
protected void performTask() throws ServletException, IOException {

String tModelKeyString = (String) getRequest().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);
Vector accessUrls = extractAccessUrls(bindingTemplates);
invokeAll(accessUrls);
forward("client1Response");
}
Figure 18-27 The performTask method
The lookUp method is called by the performTask method and is shown in

Figure 18-28.

protected Vector lookUp(TModelBag tModelBag) {
Vector bindings = new Vector();
Vector businesses = null;
Vector bindingTemplates = null;
int numberOfBusinesses = 0;
int numberOfServices = 0;
int numberOfBindings = 0;
try {
// first look up business and their services matching the tModel
BusinessList businessList = getUddiProxy()
.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);
numberOfServices += serviceInfos.size();
// iterate through services
for (int j = 0; j < serviceInfos.size(); j++) {
// find template for concrete service
bindingTemplates =
lookUpBinding(tModelBag, si.getServiceKey());
if (bindingTemplates != null) {
bindings.addAll(bindingTemplates);
numberOfBindings += bindingTemplates.size();
}
}
}
}
message="Found "+numberOfBusinesses+" business entries,"+numberOfServices
+ " services and "+numberOfBindings+" binding templates.";
getRequest().setAttribute("businesses", businesses);
getRequest().setAttribute("bindings", bindings);
getRequest().setAttribute("message", message);
return bindings;
}
Figure 18-28 Look up bindings for a specific tModel

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 Figure 18-29.
protected Vector lookUpBinding(TModelBag tModelBag, String serviceKey) {

Vector bindingTemplates = null;
try {
BindingDetail bd = getUddiProxy()
.find_binding(null, serviceKey.toString(), tModelBag, 0);
bindingTemplates = bd.getBindingTemplateVector();
}
return bindingTemplates;
}
protected Vector extractAccessUrls(Vector bindingTemplates) {

Vector accessUrls = new Vector();
if (bindingTemplates == null || bindingTemplates.size() == 0)
return accessUrls;
Enumeration enum = bindingTemplates.elements();
BindingTemplate bt = (BindingTemplate) enum.nextElement();
String accessUrl = bt.getAccessPoint().getText();
accessUrls.addElement(accessUrl);
}
return accessUrls;
}
Figure 18-29 Search for bindings and extract URLs from the result
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 Figure 18-9 on page 368.
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

Displaying the bindings
The first part shows all bindings that could be found using the tModel.
Figure 18-30 shows how they are displayed.
The bottom part shows the invocation of the services, which is identical to
Figure 18-12 on page 371.
Figure 18-30 Presenting the businesses, services, and bindings for the tModelKey
The JSP code to display this information is shown in Figure 18-31.

<%
for (int i=0; i<businesses.size(); i++) {
BusinessInfo bi = (BusinessInfo) businesses.elementAt(i);
%>
<TR class="business">
<TD colspan="4"><%= bi.getNameString() %></TD>
<TD nowrap><%= bi.getBusinessKey() %></TD>
<%
for (int j=0; j<serviceInfos.size(); j++) {
%>
</TR><TR class="service">
<TD align="right">----></TD>
<TD colspan="3"><%= si.getNameString() %></TD>
<TD nowrap><%= si.getServiceKey() %></TD>
<%
Vector bindingTemplates =
Util.extractBindingTemplatesWithServiceKey(bindings,
si.getServiceKey());
Enumeration enum = bindingTemplates.elements();
%>
</TR><TR class="binding">
<TD></TD>
<TD align="right">----></TD>
<TD><%= bt.getDefaultDescriptionString() %>
<TD><%= bt.getAccessPoint().getText() %>
<TD><%= bt.getBindingKey() %>
<% } %>
<% } %>
</TR>
<% } %>
Figure 18-31 JSP code for displaying the businesses, services and bindings
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();
if (bt.getServiceKey().equalsIgnoreCase(serviceKey))
result.add(bt);
}
return result;
}
The second part of the response JSP shows the results of the actual invocation.
This is not part of this JSP, but implemented in a separate JSP fragment that is
included by the response JSP. This part was described in “Invocation result JSP”
on page 371.
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/servlet/rpcrouter
http://www.flashandthunder.com/ItsoThunderWeb/servlet/rpcrouter
http://www.siliconweather.com/ItsoWebServADWEB/servlet/rpcrouter
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.
The start JSP is shown in Figure 18-32. 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 ist called.

Figure 18-32 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 Figure 18-33.
protected void performTask() throws ServletException, IOException {

Vector accessURLs = new Vector();
Hashtable access = getWSDLPort(lookUpWSDLlocations());
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);
forward("client2Response");
}
Figure 18-33 performTask method

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 (Figure 18-34).
protected Hashtable lookUpWSDLlocations() {

Hashtable WSDLlocations = new Hashtable();
String wsilURL = (String) getRequest().getParameter("wsilURL");
String serviceName = (String) getRequest().getParameter("serviceName");
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);
} } } } }
getRequest().setAttribute("resultWSDLlocations", WSDLlocations);
trace(message = e.toString());
}
return WSDLlocations;
}
Figure 18-34 Method to look up WSDL locations

򐂰 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 58, but with the difference that in
this case we are not interested in only one service. We retrieve every service
and look into them for service endpoints (Figure 18-35).
private Hashtable getWSDLPort(Hashtable WSDLFileLocations) {

int endPointCounter = 0;
Service service; Port port = null; String message = "";
Hashtable serviceEndpoints = new Hashtable();
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));
Map services = definition.getServices();
Collection serviceValues = services.values();
for (Iterator serviceIterator = serviceValues.iterator();
serviceIterator.hasNext();) {
service = (Service) serviceIterator.next();
Map ports = service.getPorts();
Collection portsValues = ports.values();
for (Iterator portIterator = portsValues.iterator();
portIterator.hasNext();) {
port = (Port) portIterator.next();
List list = port.getExtensibilityElements();
for (Iterator iter = list.iterator(); iter.hasNext();) {
ExtensibilityElement element = (...)iter.next();
if (element instanceof SOAPAddress) {
SOAPAddress soapAddress = (SOAPAddress) element;
endpoints.add(soapAddress.getLocationURI());
} } }
serviceEndpoints.put(serviceName,endpoints);
}
getRequest().setAttribute("resultServiceEndPoints", serviceEndpoints);
}
} catch (WSDLException e) { trace(message = e.toString()); }
return serviceEndpoints;
}
Figure 18-35 Method to get the WSDL port

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 18-36.
Figure 18-36 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 implemented in a separate JSP fragment that is
included in this response JSP. This part was described in “Invocation result JSP”
on page 371.
Testing the sample

To test the functionality of this client you can try this in the start JSP, shown in
Figure 18-32 on page 390:
򐂰 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/inspection.wsil
The answer has two services, one each for the flash and thunder services.

򐂰 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.
In Figure 18-37 we can see the difference between the two results.
Figure 18-37 Weather result without and with the service name

Installing the application 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.
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:
c:\WINNT\system32\drivers\etc\hosts
Configure one line as:

127.0.0.1 localhost www.siliconweather.com www.flashandthunder.com
www.unitedsuns.com
Import two enterprise applications

To run the scenario, we require two enterprise applications to simulate the client
and the server:
򐂰 ItsoWebServDynamicClientEAR with an ItsoWebServDynamicClientWeb Web
application represents the client (UnitedSuns).
򐂰 ItsoWeatherAssociationEAR with ItsoSiliconWeatherWeb, WebItsoFlashWeb,
and ItsoThunderWeb Web applications. These applications represent the
SiliconWeather and FlashAndThunder servers.
All three Web applications are copies of the ItsoWebServADWeb Web
application that was developed in Chapter 13, “WebSphere Studio Application
Developer” on page 197, with minor changes:
– For sample 2, a WSIL file named inspection.wsil is added to the Web
Content of the three server Web projects.
– The service WSDL files <soap:address> tag points to the proper location,
for example:
<soap:address
location="http://localhost:9080/ItsoFlashWeb/servlet/rpcrouter"/>
– The context root of ItsoSiliconWeatherWeb is set to ItsoWebServADWeb as
required by the Web service that was published.
To import the ItsoWebServDynamicClientEAR project, follow these steps:

򐂰 Select File -> Import -> EAR file.
򐂰 Click Browse and locate the EAR file:
\SG246891\sampcode\scenario\ItsoWebServDynamicClientEAR.ear

򐂰 Enter ItsoWebServDynamicClientEAR as project name.
򐂰 On the Import Defaults page, select Expanded: extract project content for
development.
򐂰 Accept the project name for the Web project.
򐂰 Click Finish.
򐂰 After the import, select the ItsoWebServDynamicClientWeb project and
Properties. On the Java Build Path -> Libraries page, add these JAR files (use
Add Variable):
WAS_50_PLUGINDIR/lib/uddi4jv2.jar
WAS_50_PLUGINDIR/lib/wsdl4j.jar
SOAPJAR
Repeat the process for the ItsoWeatherAssociationEAR project:

򐂰 Select File -> Import -> EAR file.
򐂰 Click Browse and locate the EAR file:
\SG246891\sampcode\scenario\ItsoWeatherAssociationEAR.ear
򐂰 Enter ItsoWeatherAssociationEAR as project name.
򐂰 On the Import Defaults page, select Expanded: extract project content for
development.
򐂰 Accept the project names for the Web projects.
򐂰 Click Finish.
򐂰 After the import, select each Web project and select Properties. On the Java
Build Path -> Libraries page, add the SOAPJAR file (use Add Variable).
Server project
To configure a server for testing, we require a server project. If you followed
Chapter 13, “WebSphere Studio Application Developer” on page 197, then you
already have a server project named Servers. If not, define a server project
named Servers:
򐂰 Select File -> New -> Project -> Server -> Server Project.
򐂰 Enter Servers as the name and click Finish.
Configuring a server for testing

In the Servers project, create a server and configuration (select the Create
Server and Server Configuration icon or File -> New):
򐂰 Enter ItsoWebServServer as the name.

򐂰 Select WebSphere Version 5.0 -> Test Environment and click Finish.
򐂰 Select the server and Add -> ItsoWebServDynamicClientEAR.
򐂰 Repeat and add ItsoWeatherAssociationEAR.
The Web services are invoked using addresses such as:

http://www.flashandthunder.com/ItsoFlashWeb/servlet/rpcrouter
By default, the internal HTTP server listens to port 9080 only. We have to
configure the default port 80 as well:
򐂰 Select the ItsoWebServServer and open the server configuration
(double-click).
򐂰 On the Ports page, under Server Settings, click Add and define a new port
with an empty hostname and 80 as port. Deselect Enable SSL and deselect
External.
򐂰 Save and close the configuration.
Run the samples

Eevrything is configured and we can run the samples:
򐂰 Start the server and wait for the ready message (Server server1 open for
e-business).
򐂰 Expand the ItsoWebServDynamicClientWeb project, select the index.html file,
and Run on Server.
Preferences
򐂰 Select Preferences and set the Username field to an empty string. Click Save
preferences.
Note: Our code in WeatherForecastSSLSecureProxy changes https:// to

http:// if the username field is empty. We have not configured SSL in the
test environment and this bypass enables us to test all the Web services.
public synchronized void setEndPoint(URL url)
{
String accessUrl = url.toString();
if ( getUserid().equals("") ) {
accessUrl = "http" + accessUrl.substring(5);
System.out.println("SSL disabled ==> "+accessUrl);
}
try { super.setEndPoint(new java.net.URL(accessUrl)); }
catch (java.net.MalformedURLException e) {super.setEndPoint(url);}
}

Sample 1
򐂰 Click Start Sample 1.
򐂰 Click Start lookup & invocation. Be patient. UDDI lookup can be slow, but you
should see the result of the three Web services.
Sample 2
򐂰 Click Start Sample 2.
򐂰 For the URL location enter:
http://www.flashandthunder.com/ItsoFlashWeb/inspection.wsil
http://www.siliconweather.com/ItsoWebServADWEB/inspection.wsil
򐂰 Click Start lookup & invocation and you should see the results of the Web
services.
General UDDI lookup

򐂰 Click General UDDI lookup.
򐂰 Click 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 get over 20 business entries.
Deployment to WebSphere Application Server

Deployment of this sample application is basically the same as described in
“Deployment of the sample application” on page 239. However, it is more
complicated if we implement the secure access using HTTPS.
The basic steps are:

򐂰 Export the EAR files from Application Developer.
򐂰 Install the enterprise application in WebSphere Application Server.
򐂰 Define a virtual host aliases for www.siliconweather.com, port 443.
򐂰 Regenerate the plug-in.
򐂰 Configure the HTTP server for HTTPS and the virtual hosts.
See “Installing the scenario application” on page 410 for detailed instructions.

Summary
In this chapter we provided a Web services scenario and an implementation
using WebSphere Studio Application Developer and WebSphere 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.

19
Chapter 19. 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. We discuss some useful troubleshooting
techniques. We also cover the Web service resource security.
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 10, “IBM WebSphere product family” on page 159 and the
product installation is covered in Appendix A, “Installation and setup” on
page 427.

򐂰 WebSphere Application Server V5.0 general concepts including
administration and application deployment
򐂰 Web services packaging and SOAP enablement.
򐂰 Securing Web services
򐂰 Private UDDI registry

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 10, “IBM
WebSphere product family” on page 159.
Administration basics
In WebSphere 3.5 and WebSphere 4.0 Advanced Edition, the configuration was
saved in a relational database. The Admin Server had to be installed and started
on all the nodes in the domain to start and stop an application. In WebSphere
V3.0, V3.5 and V4.0 Advanced Edition, 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

V4.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 support JMS), node agents, and deployment

managers are all examples of managed processes. We discuss node agents
and deployment managers in the following subsections.
򐂰 Node agent—Is responsible for controlling all the remaining servers running
on a certain machine. 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 that 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 19-1 shows an example of a WebSphere Version 5 topology.
Managed application
Process server
XML
config
application
node
server
agent XML
Cell config
application
deployment server
manager XML
config
application
node server
Managed agent XML
config
Process
Figure 19-1 WebSphere Version 5 example topology
Chapter 19. Web services runtime and deployment in WebSphere 403

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 EARs. 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 Admin 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://<hostname>: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.

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 19-2.
Figure 19-2 The Web administrative console
Taskbar
The taskbar helps a user to return to the console home page, to access product
information, to save changes made to administrative configurations, and to 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. It
provides links to pages with instructions for installing application, updating
applications, and creating application servers. The console also provides a

search function for locating and viewing resource objects and some information
about adjusting the console to meet our requirements.
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.
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 Application Assembly Tool (AAT),

which can be used to manage the files within the application. Other tools such as
WebSphere Application Developer can also be used in enterprise application
development and packaging.
Installing an enterprise application

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.

Install new application pages
The install new application pages are now shown, starting with the Provide
options to perform the installation page. Since we decided 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
needed to run EJB files, runs during application installation.
򐂰 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).

Optional panels
Several panes only appear under specific circumstances. We only briefly
describe those here:
򐂰 Provide JNDI Names for Beans 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 panel—appears if the application
defines resource references.
򐂰 Map virtual hosts for Web modules 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 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 panel—appears when the application
has security roles defined in its deployment descriptor.
򐂰 Map RunAs roles to user 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.
The status is remembered over stop and restart of the server. A call to a stopped
Web service results in an error that is sent back to the client.
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.

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. In this case no special activities are required for
deployment to WebSphere.
Web services enabling

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
WebSphere Studio Version 4.0. Typically, with WebSphere Studio Version 4.0,
you export the Web application in a WAR file. Then you assemble the WAR file
into an EAR file using the Application Assembly Tool. Then you run the
soapearenabler tool, which adds a Web module containing the SOAP router
servlets to the EAR file. If desired, the tool can add the SOAP admin Web
application as well.
Web services administration

Web services can be administered using a small GUI tool. The Application
Developer wizard automatically adds the GUI tool to a Web module when Web
services are generated and installed.
The XML-SOAP Admin Tool is started in a browser:

http://localhost:9080/ItsoWebServADWEB/admin/index.html
Using the tool we can:

򐂰 Display a list of installed Web services
򐂰 Stop a Web service (initially all are started)
򐂰 Start a Web service
򐂰 Display the details of a Web service
Figure 19-3 shows the list of Web services in the GUI tool.

Figure 19-3 Soap administration interface
Installing the scenario application

For the sample application developed in Chapter 18, “Web services scenario:
architecture and implementation” on page 353, we have to configure the system
with HTTPS transport between the HTTP server and WebSphere Application
Server.
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
The applications are packaged into two EAR files:

򐂰 ItsoWeatherAssociationEAR.ear (both servers)
򐂰 ItsoWebServDynamicClientEAR.ear (client)
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 d:\IBMHttpServer\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.
򐂰 Select Key Database File -> New. Select CMS key database file from the type
drop-down, enter webservKeyring.kdb as file name, select the
d:\IBMHttpServer\conf\keys directory 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 version and 1024 as key size. For the
names, enter the server name as common name, and IBM, ITSO, San Jose, CA,
US into the other fields. Enter 365 for the period, and click OK.
Extract the certificate for installation into WebSphere

We have to extract the certificate so that we can install it in WebSphere:
򐂰 Click Extract Certificate.
򐂰 Select Base64-encoded ASCII data as the type, enter ItsoWebServ.arm as
the file name, keep the 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 <WAS_ROOT>\etc.
򐂰 Start the ikeyman command-line tool (<WAS_ROOT>\bin\ikeyman.bat).
򐂰 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 <WAS_ROOT>\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 ikeyman.

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
<VirtualHost your.server.name:443>
ServerName www.siliconweather.com
ServerPath d:/ibmhttpserver/htdocs
SSLEnable
</VirtualHost>
<VirtualHost your.server.name>
ServerName www.unitedsuns.com
</VirtualHost>
ServerName www.flashandthunder.com
</VirtualHost>
ServerName www.siliconweather.com
</VirtualHost>
SSLDisable
SSLClientAuth none
Keyfile d:/ibmhttpserver/conf/keys/webservKeyring.kdb
SSLV2Timeout 100
SSLV3Timeout 1000
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:
c:\WINNT\system32\drivers\etc\hosts
Configure one line as:

127.0.0.1 localhost www.siliconweather.com www.flashandthunder.com
www.unitedsuns.com

Setting up the WebSphere server for the scenario sample
The setup for WebSphere includes the definition of a virtual host for the SSL
connection, the installation of the enterprise applications, and the generation of
the HTTP server plug-in.
Start the WebSphere server if it is not running.
Configure a virtual host in WebSphere

The configuration of the virtual host is only required if you want to use HTTPS.
Using the administrative console, we have to define a virtual hosts alias for
www.siliconweather.com:
򐂰 Select Environment -> Virtual Hosts, then click default_host and select Host
Aliases.
򐂰 Click New, enter www.siliconweather.com as host name, 443 as port, and
click OK.
Install the enterprise applications

򐂰 Install the two enterprise applications, ItsoWeatherAssociationEAR and
ItsoWebServDynamicClientEAR by following the instructions in “Installing an
enterprise application” on page 406. Take all the defaults in the installation
panels.
򐂰 Start the two enterprise applications.
Regenerate the plug-in

The WebSphere configuration of enterprise applications and virtual hosts must
be known to the HTTP server so that requests can be forwarded:
򐂰 Select Environment -> Update Web Server Plugin, then click OK.
򐂰 Save the configuration.
Restart the servers

Both the HTTP server and the application server must be restarted to make all
the changes effective:
򐂰 The HTTP server will pick up the SSL configuration and the WebSphere
plug-in.
򐂰 The WebSphere server must be restarted if you define a virtual host for
HTTPS.

Run the application
After restarting the servers, you can test the application using the URL:
http://www.unitedsuns.com/ItsoWebServDynamicClientWeb/index.html
If SSL does not work for www.siliconweather.com you can always use the
Preferences page and set the user ID to empty (see “Preferences” on page 397).
The call is then made without SSL.
For sample 2, you have to add the Web context root to look for the
inspection.wsil files, because we cannot easily install multiple files with the
same name in the HTTP server root.
http://www.flashandthunder.com/ItsoFlashWeb/inspection.wsil
http://www.siliconweather.com/ItsoWebServADWEB/inspection.wsil
Note that the user ID and password of the preferences are not checked.
Installing the technology preview applications

Installation of the enterprise applications created using the technology preview
can only be performed on a system where the technology preview is installed.
The actual installation process is covered in “Deployment of applications to

WebSphere” on page 340.
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 13, “WebSphere Studio
Application Developer” on page 197.
The WeatherForecastClient is provided in the sample code directory, together

with a command file to set up the class path and execute the client:
\sg246891\sampcode\was\standaloneClient
The client code is based on the proxy class generated by Application Developer.
We therefore only show an extract of the code that illustrates one of the services
and the main method calling the services (Figure 19-4).

...
public class WeatherForecastClient implements Serializable
{
......
public synchronized itso.wsoj.Weather getDayForecast(java.util.Date theDate) ... {

String targetObjectURI = "http://tempuri.org/itso.wsoj.WeatherForecast";
String SOAPActionURI = "";
call.setMethodName("getDayForecast");
call.setTargetObjectURI(targetObjectURI);
Parameter theDateParam = new Parameter("theDate", java.util.Date.class, theDate,
Constants.NS_URI_SOAP_ENC);
params.addElement(theDateParam);
Response resp = call.invoke(getURL(), SOAPActionURI);
//Check the response.
if (resp.generatedFault()) {
Fault fault = resp.getFault();
call.setFullTargetObjectURI(targetObjectURI);
throw new SOAPException(fault.getFaultCode(), fault.getFaultString());
} else {
Parameter refValue = resp.getReturnValue();
return ((itso.wsoj.Weather)refValue.getValue());
}
}
// ...... other methods

WeatherForecastClient fcp = new WeatherForecastClient();
try {
System.out.println("Remotely testing weather forecast for today...");
Weather dayForecast = fcp.getDayForecast(new Date());
System.out.println(niceFormat(dayForecast));
System.out.println("Remotely testing weather forecast for next week...");
Weather[] weekForecast = fcp.getWeekForecast(new Date());
for (int i = 0; i < weekForecast.length; i++) {
System.out.println(niceFormat(weekForecast[i]));
}
System.out.println("Remotely testing temperatures for next week...");
int[] weekTemperatures = fcp.getWeekTemperatures(new Date());
for (int i = 0; i < weekTemperatures.length; i++) {
System.out.println(weekTemperatures[i] + " Celsius");
}
} catch (Exception e) { System.out.println("Something went wrong!" + e); }
}
}
Figure 19-4 Stand-alone Java SOAP client accessing the weather forecast service

An extract of sample output is shown here:
Remotely testing weather forecast for today...
Weather: Fri. Jan 10, 2003 'cloudy' wind: NE 10km/h 30 Celsius
Remotely testing weather forecast for next week...
Weather: Fri. Jan 10, 2003 'rainy' wind: S 32km/h -9 Celsius
Weather: Sat. Jan 11, 2003 'partly cloudy' wind: NW 19km/h 10 Celsius
Weather: Sun. Jan 12, 2003 'partly cloudy' wind: S 5km/h 19 Celsius
...
Remotely testing temperatures for next week...
15 Celsius
...
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 Servers -> Web services servers
-> Installing and setting up a UDDI Registry. You can select Cloudscape or DB2
as the database.
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.
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 19-5).
http://<yournode>:9080/uddigui
Figure 19-5 Private UDDI home page
To add a business use the Publish tab (left side), enter a business name in the
Quick Publish field, and click Publish now (Figure 19-6).
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.

Without WebSphere security
enabled all entries are owned by
the user ID: UNAUTHENTICATED
Figure 19-6 Publishing a business
.To locate and edit the entries you own, click Show owned entities (Figure 19-7).
Figure 19-7 Owned entities
You can edit the business and add a description, locators (classifications), and
contacts.

You can add a service to the business by clicking Add service and completing the
form (Figure 19-8). You have to click Add individually for each piece of
information that you enter.
Figure 19-8 Adding a service to a business
Add a technical model using Quick Publish (Figure 19-9).
Figure 19-9 Publishing a technical model
Edit the technical model from the owned entities panel (Figure 19-10). 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 19-10 Updating a technical model
Finally you update the service to point to the technical model (Figure 19-11 and
Figure 19-12).
Figure 19-11 Assigning a technical model to a service (1)

Figure 19-12 Assigning a technical model to a service (2)
The owned entities panel now shows the service and the technical model
(Figure 19-13).
Show services
Figure 19-13 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 19-14):
http://<yournode>:9080/uddisoap/inquiryapi

Figure 19-14 UDDI Explorer: setup private UDDI registry
Click Go to connect to the 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 19-15).
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 19-15 Publishing a business

Finding information
Use the Find icon to execute queries against the registry (Figure 19-16).
Figure 19-16 Exploring the UDDI registry
For more information on the UDDI Explorer, refer to “Publishing and exploring a
UDDI registry” on page 233.
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.

More information
For general information on the IBM WebSphere family 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

redbook IBM WebSphere Application Server Version 5.0 Handbook, SG24-6195.
The security details are discussed in the redbook IBM WebSphere V5.0 Security:
WebSphere Handbook Series, SG24-6573.

Part 3
Part 3 Appendixes

A
Appendix A. Installation and setup

This appendix provides brief instructions for installing the products used in this
redbook.

Installation planning
IBM WebSphere Application Server Base and Network Deployment have the
following hardware and software requirements.
Hardware
Hardware requirements include:
򐂰 Any Intel-based PC running Windows NT Server V4.0, SP 6a or later,
Windows 2000 Server, or Advanced Server SP 2
򐂰 Intel Pentium processor at 500 MHz, or faster
򐂰 Support for a communications adapter
򐂰 Minimum 180 MB free disk space for installation (includes SDK)
򐂰 CD-ROM drive
򐂰 Minimum 384 MB memory; 512 MB recommended
Software
The installation requires the following software to be installed:
򐂰 Windows NT Server or Windows 2000 Server
򐂰 Netscape Communicator 4.7.9 or Microsoft Internet Explorer 5.5 SP 2 and 6.0
򐂰 Web browser that supports HTML 4 and CSS
For updated information on the hardware and software requirements, please

refer to WebSphere Version 5 InfoCenter.
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. The following databases are supported with
WebSphere Application Server V5 and WebSphere Network Deployment V5 on
Windows platforms:
򐂰 Cloudscape 5.06
򐂰 DB2 UDB V7.2 Fixpack 7
򐂰 Informix Dynamic Server Versions 7.31 and 9.3
򐂰 Oracle Enterprise Edition 8i Release 3 (8.1.7)
򐂰 Oracle Enterprise Edition 9i Release 2 (9.2)
򐂰 SQL Server Enterprise 7.0 SP 4 and 2000 SP 2
IBM HTTP Server is bundled with base WebSphere Application Server V5.
These HTTP servers can also be installed and configured:
򐂰 Apache Server 1.3.26
򐂰 HTTP Server 1.3.26 AIX, Linux/390, Linux/Intel, Windows NT
򐂰 Internet Information Server 4.0
򐂰 Sun ONE Web Server, Enterprise Edition (formerly iPlanet) 6.0 SP 4
򐂰 Lotus Domino Enterprise Server (as HTTP Server) 5.0.9a

Installing IBM WebSphere Application Server
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
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).
Figure A-1 WebSphere Application Server LaunchPad
򐂰 In the first window select the language and click OK.

򐂰 Click Next in the Welcome window.
Appendix A. Installation and setup 429

򐂰 After confirming that we agree with the license agreement, we have to choose
between two installation choices: Typical and Custom. Typical installs the
entire product, whereas Custom installation options allows you to deselect
components you do not want to install. We chose Typical installation.
򐂰 The installation directories for the selected components are entered in the
next window. We chose:
d:\WebSphere\AppServer
d:\IBMHttpServer
d:\WebSphere MQ
򐂰 In the following window 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 or 2000.
򐂰 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.0 -> 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:
OS: Windows 2000
locale: en_US
hostname: NODENAME
cmd.exe /c "D:\WebSphere\AppServer\bin\ivt" NODENAME 9080
C:\WebSphere\AppServer
IVT0006I: Connecting to the WebSphere Server NODENAME on Port:9080
IVT0007I:WebSphere Server NODENAME is running on Port:9080
IVT0060I: Servlet Engine Verification: Passed
IVT0065I: JSP Verification: Passed
IVT0066I: EJB Verification: Passed
IVT00100I: IVT Verification Succeeded
IVT0015I: Scanning the file
D:\WebSphere\AppServer\logs\server1\SystemOut.log for
errors and warnings
IVT0020I: 0 Errors/Warnings were detected in the file
D:\WebSphere\AppServer\logs\server1\SystemOut.log
IVT0110I: Installation Verification is complete.

Installing IBM WebSphere Application Server Network Deployment
The InstallShield is 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.
Installation of WebSphere Studio Application Developer

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).
1. Install Application
Developer
2. Install embedded
messaging
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 d:\WSAD5 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 about the success of
the installation. Click Finish.
򐂰 The last window allows you to specify the location of your workspace. We use
d:\WSAD5sg246819 for the workspace location.
Restart the installation launcher window and select Install embedded messaging
client and server. This component is required for JMS messaging to feed a
message-driven bean.
򐂰 If you installed WebSphere Application Server, installing the embedded
messaging locates the existing WebSphere MQ installation and only tailors
the Application Developer to use the existing code.
򐂰 If WebSphere MQ is not installed on this machine, then it will be installed now
Optionally install the IBM Agent Controller and ClearCase LT.
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:
D:\<WSAD-HOME>\wsappdev.exe -data E:\WSAD5sg246891
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):
Figure A-3 Workspace location for Integration Edition
򐂰 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.
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.
Installation of the WebSphere SDK for Web Services

Download the executable file from developerWorks:
http://www-106.ibm.com/developerworks/webservices/wsdk/
Start the executable (wsdkSetup.exe) and follow the prompts. The only selection
is for the target location, for example, d:\WSDK_v5.
A program folder with three icon is created: Start Server, Stop Server, and WSDK
Help. Start the help facility and familiarize yourself with the concepts and tools.

Installation of the Web Services Toolkit
The installation of the Web Services Toolkit is straightforward:
򐂰 Download the executable file from alphaWorks:
򐂰 Select the platform (Linux or Windows).
򐂰 Run the executable. The InstallShield wizard searches for the appropriate
JDK and then starts the Java installer. It is also possible for the user to browse
for the JDK.
򐂰 A minimum of 384 MB memory is required; 512 MB is recommended.
򐂰 Select either Ethernet or token-ring network.
Installation of the Web Services Technology Preview

The installation of the Web services technology preview is a straightforward
process. The installation of the WebSphere Application Server Version 5.0 or
WebSphere Application Client Version 5.0. is a prerequisite before installing the
technology preview. Depending on where we install the technology preview, we
enable one or the other of the following:
򐂰 WebSphere Application Server—Implementation of Web services and use of
Web services
򐂰 WebSphere Application Client—Use of Web services as a client
The technology preview is installed in the same directory as WebSphere

Application Server or Application Client:
򐂰 Download the technology preview from:
http://www7b.software.ibm.com/wsdd/downloads/web_services.html
򐂰 Unzip the downloaded file into a temporary directory.
򐂰 Change to the WebServices subdirectory of the temporary directory.
򐂰 Run the command:
installWebServices.bat was_install_root
where was_install_root is the full path of the WebSphere Application Server
or Client installation directory.
򐂰 The installation window appears (Figure A-4). Click Next.

Figure A-4 Technology preview installation
򐂰 Accept the license agreement and click Next.

򐂰 Verify that the directory name field indicates the correct installation directory
of either WebSphere Application Server 5.0 or WebSphere Application Client
5.0. Click Next.
򐂰 Click either Typical or Custom install. Custom allows you to deselect samples.
Click Next.
򐂰 If you selected custom install, make your installation choices. Click Next to
start the installation process.
򐂰 The installation process takes several minutes depending upon the system.
Click Next and read the late-breaking news.
򐂰 Click Finish to conclude.
You can find the installed technology preview in the WebSphere home directory
in the subdirectories:
<WAS-HOME>\TechPreview\WebServices
<WAS-HOME>\installedApps\<node>\TechnologySamples.ear
<WAS-HOME>\bin: additional commands (java2wsdl, wsdl2java, endptEnabler
<WAS-HOME>\lib: additional JAR files (axis.jar, webservices.jar, ...)

Installation check
Review the two files in the <WAS-HOME>\TechPreview\WebServices\logs directory. If
anything goes wrong during installation you might not get any messages, but the
errors are recorded in the DeployGUIstderr.txt file.
Documentation
Read the documentation at:
<WAS-HOME>\TechPreview\WebServices\docs\index.html
Removing the technology preview

The technology preview can be uninstalled from the Control Panel (Add/Remove
Programs) or by running TechPreview\WebServices\_uninst\unistaller.exe.

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, SG246891.

Using the Web material
The additional Web material that accompanies this redbook includes the
following files:
File name Description
sg246891code.zip Sample code for following the samples in the book
corrections.txt Corrections to the book after publishing
System requirements for downloading the Web material

The following system configuration is recommended:
Hard disk space 3 GB
Operating System Windows 2000 or Windows NT
Processor 700 MHz or better
Memory 512 MB, recommended 784 MB
How to use the Web material

Unzip the contents of the Web material sg246891code.zip file onto your hard
drive. This creates a folder structure c:\SG246891\sampcode\xxxx, where
xxxxx refers to a chapter in the book:
sample Basic code of the weather forecast example
wsad Develop Web services using Application Developer:
From JavaBean (bottom-up), from WSDL (top-down), from
servlet URL, and solution
wsadie Develop Web services using Application Developer.
Integration Edition
wsdk Develop Web services using WebSphere SDK for Web
Services:
From JavaBean and a client
techprev Develop Web services using WebSphere Web Services
Technology Preview:
From JavaBean (bottom-up), from session EJB (top-down),
and a client
scenario Web services scenario and architecture:
Using WSIL and WSDL
was Deployment to WebSphere Application Server

Abbreviations and acronyms
AAT Application Assembly Tool IBM International Business
API application programming Machines Corporation
interface IDE integrated development
AXIS Apache eXtensible Interaction environment
System IIOP Internet Inter-ORB Protocol
B2B business-to-business IMS Information Management
B2C business-to-consumer System
B2E business-to-employee ITSO International Technical

Support Organization
BPEL business process execution
language J2CA J2EE connector architecture
CCF Common Connector J2C J2EE connector architecture

Framework J2EE Java 2 Enterprise Edition
CICS Customer Information Control JAR Java archive
System JDBC Java Database Connectivity
CRM customer relationship JDK Java Developer’s Kit
management
JNDI Java Naming and Directory
CTG CICS Transaction Gateway Interface
DBMS database management JSP JavaServer Page
system
LDAP Lightweight Directory Access
DOM document object model Protocol
EAR enterprise application archive MVC model-view-controller
ECI external call interface PKI public key interface
EIS enterprise information system RAD rapid application development
EJB Enterprise JavaBeans RAR resource adapter archive
EJS Enterprise Java Server RDBMS relational database
EPI external presentation management system
interface RMI Remote Method Invocation
ERP enterprise resource planning SAML security assertion markup
FDML flow definition markup language
language SAX Simple API for XML
FTP File Transport protocol SCM supply chain management
GUI graphical user interface SDK Software Development Kit
HTML Hypertext Markup Language SMTP Simple Mail Transfer Protocol
HTTP Hypertext Transfer Protocol

SOAP Simple Object Access
Protocol (also known as
Service Oriented Architecture
Protocol)
SPO service provider offering
SQL structured query language
SSL Secure Sockets Layer
TCP/IP Transmission Control
Protocol/Internet Protocol
UDDI universal description,
discovery, and integration
URL uniform resource locator
UTC universal test client
WAR Web application archive
WSDL Web service description
language
WSFL Web services flow language
WSGW Web Services Gateway
WSIF Web services invocation
framework
WSIL Web services inspection
language
WSTK Web Services Toolkit
WWW World Wide Web
XMI XML metadata interchange
XML eXtensible Markup Language
XSD XML schema definition

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 444.
򐂰 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

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/
򐂰 IBM research: XML and Web services
http://xml.watson.ibm.com
򐂰 Web services on developerWorks
http://www.ibm.com/developerworks/
http://www.ibm.com/developerworks/webservices
򐂰 Web services on alphaWorks
http://www.alphaworks.ibm.com/tech/wsif
򐂰 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/products/index/access-mgr-bus-integration
򐂰 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/
򐂰 World Wide Web Consortium W3C
http://www.w3.org/
򐂰 XML schema
http://schemas.xmlsoap.org/
򐂰 Security
http://www.oasis-open.org/committees/security/docs/draft-sstc-use-strawman-
03.html
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwssecur/
html/securitywhitepaper.asp
򐂰 Sun Web sites
http://java.sun.com/dtd/web-app_2_3.dtd
http://java.sun.com/xml/jaxrpc
http://java.sun.com/j2ee/connector/products.html
򐂰 Java Community Process
http://www.jcp.org/en/jsr/all
򐂰 Microsoft SOAP
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsoap/htm
l/soap_faq.asp?frame=true
򐂰 XMethods
http://www.xmethods.net/inspection.wsil
Related publications 443

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.

Index
WS-Inspection 110
A block activity 248
abbreviations 439
body 23
AbstractServlet 366
SOAP 23
access point 67
bottom-up
acronyms 439
Application Developer 198
activity 120, 124, 126, 248
development 177
administrative console 343, 402, 404
Integration Edition 242
Agent Controller 433
technology preview 321, 330
alphaWorks 97, 127, 139, 302, 434, 442
WSDK 288
Apache
BPEL 9, 119
Axis 18, 319
Web site 128
Web site 40
BPEL4WS 125, 312
Jakarta 303
concepts 125
SOAP 17
BPWS4J
implementation 31
Web site 128
server 31
breakpoint 274
WSIF 97
business 9
Apache eXtensible Interaction System
entity 63
see Axis 17
information 11
Apache Server 428
integration 11
Application Assembly Tool 321, 337, 406
process 119–120, 126, 247
auditing 142
externalization 11
authentication 142
Web client, 271
authorization 142
wizard 252
Axis 17–18, 36
registry 69
client architecture 37
relationships 64, 67
server architecture 37
service 63
subsystems 38
Business Integration
technology preview 319
perspective 245
business process execution language
B see BPEL
B2B 62, 167 business-to-business 62, 167
B2C 167 business-to-consumer 12, 167
B2C Web application 13 business-to-employee 167
B2E 167
Bean2WebService 287
binding
C
categorization 68
HTTP 56
cell 403
MIME 57
certificate 411
SOAP 55
channel 131, 134
template 63, 66
CICS 244
UDDI 112
CICS Transaction Gateway 433
WSDL 52

claim 148 EJB2WebService 287
client electronic data interchange 4
application 365 e-marketplace UDDI 83
Web service 218 encoding 19
Cloudscape 428 SOAP 28
Common Business Objects 173 encryption 145
communication style 24 endpoint interface 324
compensation service 124 endptEnabler 337
compound type 26 enterprise
confidentiality 142, 147 application 343
container 125 installation 395
control link 121, 248, 269 information systems 242
CORBA 21 services 242
CrossWorlds 173 enterprise application
deployment 406
envelope 19, 21
D SOAP 21
DADX 198, 232
error handling 23
data
explorer 233
link 122
eXtensible Markup Language
model
see XML
SOAP 24
extranet UDDI 84
DB2
XML Extender 199, 232
DCOM 21 F
dds.xml 210 fault activity 248
debugger 274 fault code 23
deployment 239, 340, 398 fault message 24
descriptor 210, 327 FDML 9, 119
SOAP 28 elements 124
enterprise application 406 example 268
manager 403 filter 131, 135
deserialization 28 find_binding 80
deserializer 29, 31, 34 find_business 78
developerWorks 99 find_service 79
Web site 40 find_tModel 79
digital signatures 145 FlashAndThunder 354
direct Internet message encapsulation (DIME) 313 flow 255
document access definition extension flow definition markup language
see dADX see FDML
document style
SOAP 24
DOM parsers 319
G
gateway 130
dynamic
client 183
Web services 62, 91, 383 H
header 22
SOAP 19
E Host On Demand 244
Eclipse 163

HOSTS file 412 JMS 144
HTTP 144 JMX 163
binding 56 JSR 09 282
extension framework 18 JSR 101 282, 317, 320
header 20 JSR 109 317, 351
plug-in 413 JSR 110 58
HTTP Server 428 JSR 181 350
HTTPS 144
configuration 410
L
language-independent 10
I legacy systems 7, 13, 97, 169, 244
IBM HTTP Server 428 link 121, 248
identification 142 Linux 161, 281–282, 288, 302, 304, 314, 428
IETF 313 literal XML 28
information set 59 loop activity 249
Informix Dynamic Server 428 Lotus Domino Enterprise Server 428
installation
technology preview 434
WebSphere Application Server 428
M
mapping
WebSphere Studio Application Developer 431
SOAP 29
WebSphere Studio Integration Edition 432
marshalling 28
WSTK 434
matchmaking 313
InstallShield Multi Platform (ISMP) 429
message
Integration Edition
oriented style 24
see WebSphere Studio Application Developer
SOAP 19
Integration Edition 241
WSDL 50
integrity 142
Microsoft SOAP Toolkit 18, 38, 40
International Weather Association 355
SOAP
Internet Information Server 428
Microsoft 17
interoperability 4, 26
MIME
binding 57
J motivation 4
J2EE Connector Architecture MQSeries
see JCA see WebSphere MQ
Jakarta Tomcat 302–303 Workflow 173
Web site 315
Java
Management Extensions 163
N
NAICS 64
Messaging Service 43
namespaces 21
snippet 124, 248, 269
SOAP 21
snippets 262
WSDL 48
Java to WSDL 325
WS-Inspection 105
Java2WSDL 325
WS-Security 146
JAX-RPC 95, 282, 317–318
Network Deployment 67, 85
Web site 351
non-repudiation 142
JCA 91
adapters 244
Web services 91
Index 447
O RMI 18
OASIS 62 RPC 19, 24, 31
Oracle Enterprise Edition 428 style 55
Oracle ERP 244
S
P SAAJ 314
palette 254 SAML 146
partner 126 Web site 155
PeopleSoft 244 SAX 36, 319
plug-in 413 scenario 353
POP 144 scope 33, 204
port type secure proxy 368
WSDL 50 security 141
private UDDI registry 82, 416 token 147
process WSGW 138
breakpoint 276 security assertion markup language
business 120 see SAML
debugger 274 SEI 324
editor 247 self-signed certificate 411
files 262 serialization 28
flow 255 serializer 29, 31, 34
interface 265 service
proof-of-possession 147 compensation 124
protocol 143, 153 project 250
provider 92, 121 projection 67
proxy 210, 212 WSDL 53
secure 368 WS-Inspection 108
UDDI 77, 377 service broker 5–6
WSIF 95 service endpoint interface 324
publisher service provider 5–6
assertions 64 service requestor 5–6, 50, 59, 62, 65–66, 88, 130,
publishing 66 181, 285, 294, 355
service-oriented architecture 3, 17
concepts 5
Q sg246891code.zip 438
quality of service 90
Siebel 244
SiliconWeather 354
R simple API for XML 36
Red Hat 282 Simple Object Access Protocol
Redbooks Web site 444 see SOAP
Contact us xx SMTP 144
registry SOAP 7
UDDI 62 1.1 specification 40
relationships 67 administration 210
remote procedure call 19 architecture 17
replication 84 binding 55
requirements 4 body 23
resource adapter 243 Call object 34

client API 34 top-down
communication style 24 Application Developer 199
data model 24, 26 development 177
deployment descriptor 28, 32 Integration Edition 243
encoding 19, 28 technology preview 331, 338
envelope 19 WSDK 287
error handling 23
fault 23
header 19, 22
U
UDDI 8
implementation 30
API 76
mapping 29
binding 112
message 19
Business Registry 62, 69
Microsoft 18, 38
categorization 68
overview 18
client 77
security 204
cloud 82
specification
data model 65
Web site 40
Explorer 233, 421
SOAP Toolkit 17–18, 40
extranet 84
SOAP with Attachments API for Java (SAAJ) 314
find 71
SOAP4J 31, 36
find_binding 80
soapearenabler 409
find_business 78
SQL Server 428
find_service 79
SSL 144, 357, 412
find_tModel 80
staff activity 249
GUI 416
stand-alone client 414
IBM Web site 88
static Web service 62, 181
introduction 61
stub-less 95
lookup sample 374
Sun ONE Web Server 428
policy 86
SuSE 282
pollution 82
SyncML standard 169
private registry 82
proxy 77, 377
T publish 74
taxonomy 63 publishing 66
TCP/IP Application Developer 233
monitoring 36 replication 84
Monitoring Server 221 taxonomy 63
technology preview 281–282 Test Registry 234
client 344 Version 2 67
configuration 320 Version 3 85
installation 434 Web front-end 71
installing applications 414 Web site 88
test registry 69–71, 233, 237, 290, 311, 372, 383, UDDI4J 76, 357, 363, 374, 416
389 UDDIPublish 289
Tivoli Access Manager for Business Integration, UDDIUnpublish 291
154 unified resource name
tModel 63 see URN
Tomcat 303 UnitedSuns 355
Web site 315 universal description, discovery, and integration
Index 449
see UDDI see WSDL
universal resource identifier Web services flow language
see URI see WSFL
universal test client 208, 216 Web Services Gateway
unmarshalling 28 see WSGW
unpublish 291 Web services inspection language
UNSPSC 64 see WSIL
URI 21 Web services invocation framework
URN 21, 34 see WSIF
WebSphere
Application Assembly Tool 328
V Application Server 31, 161
virtual host 413
Enterprise Edition 135, 162, 277
VisualAge for Java 163
Express 162
installation 428
W Network Deployment 67, 85, 162, 404
W3C 18 Business Connection 139
Weather class 190 Web Services Gateway 140
weather forecast 187 Business Integration 172
WeatherForecast class 193 Commerce 170
WeatherPredictor class 195 Everyplace 168
Web service MQ 145, 166
deployment descriptor templates 327 Integrator Broker 172
from DADX 232 Portal for Multiplatforms 167
from JavaBean 200 product family 160
from URL 227 Studio 163
from WSDL 224 Application Developer 165, 197
Web services installation 431
administration 409 Integration Edition 165, 241, 432
build 176 Enterprise Developer 165
client 181 Site Developer 164
deployment 177, 401 Workflow 98
development 175 WebSphere SDK for Web Services
enabling 409 see WSDK
experience language (WSXL) 313 WebSphere Web Services for J2EE Technology
Explorer 233 Preview
for J2EE 318 see technology preview
gateway 130 WORF 232
interactive applications (WSIA) 313 workflow 119
management 177 wsadmin 340
matchmaking engine 313 WS-Authentication 153
protocol stack 143 WSDK 281, 303
runtime 177, 401 binding 52
scenario 353 documentation 284
scope 33 samples 285
security 141 tools 284
security model 152–153 Web site 300
wizard 198, 202 WS-Security 286
Web services description language WSDL 7

API 57 WS-Policy 153
binding 110 WS-Privacy 154
document 42 WS-SecureConversation 153
editor 246 WS-Security
files 46 namespaces 147
introductory 41 specification 146
message 50 Web site 155
operation 51 WSDK 286
port type 50 WSTK 281, 301
service 53 configuration 304
specification installation 434
Web site 60 Web site 315
WSDL to Java 330, 332 WS-Trust 153
WSDL2Java 327, 330, 332, 345 WSXL 313
WSDL2WebService 288
WSDL4J 57, 357
WS-Federation 153
X
Xalan 302
WSFL 9, 119–120
Xerces 302
concepts 120
XLANG 128
example 122
XMethod 117
specification
XMI 28
Web site 127
XML 7
WSGW 9, 98, 129
digital signatures 145
WSIA 313
editor 246
WSIF 9, 89
encryption 145
Apache 97
Web site 155
API 92, 95
Information Set 59
architecture 92
metadata interchange
components 94
see XMI
concepts 91
namespaces 21
interaction 94
Protocol Working Group 18
provider 92
schema descriptor 19
proxy 95
signature
Web site 99
Web site 154
WSIL 9, 358
SOAP Admin Tool 409
lookup sample 389
XSD
see also WS-Inspection
type 26
WSIL4J 116, 357
WS-Inspection 101
API 116
binding 110
definition 107
document 103
link 109
namespaces 105
overview 103
service 108
specification
Web site 117
Index 451
WebSphere Version 5
(1.0” spine)
0.875”<->1.498”
460 <-> 788 pages
Back cover ®
WebSphere Version 5
Web services This IBM Redbook describes the new concept of Web services from
overview and various perspectives. It presents the major building blocks Web
INTERNATIONAL
concepts services rely on. Here, well-defined standards and new concepts TECHNICAL
are presented and discussed. SUPPORT
Web services tools ORGANIZATION
Whereas these concepts are described vendor-independent, the
and development
book also presents IBM’s view and illustrates with suitable
demonstration applications how Web services can be implemented
Web services using IBM’s product portfolio, especially WebSphere Application BUILDING TECHNICAL
runtime environment Server Version 5 and WebSphere Studio Application Developer INFORMATION BASED ON
PRACTICAL EXPERIENCE
Version 5.
This book is a major update to the IBM Redbook Web Services IBM Redbooks are developed by
Wizardry with WebSphere Studio Application Developer, the IBM International Technical
SG24-6292, published in 2002. Support Organization. Experts
from IBM, Customers and
Partners from around the world
This book is structured in two parts: create timely technical
򐂰 Part 1 presents the underlying concepts for the use of Web information based on realistic
scenarios. Specific
services. It presents the basic programming model, recommendations are provided
well-known basics in an updated way, and new concepts that to help you implement IT
go beyond the scope of the 2002 book. solutions more effectively in
your environment.
򐂰 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.
For more information:
ibm.com/redbooks
SG24-6891-00 ISBN 0738427748

sg246891 00

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

sg246891 00

Transféré par

Droits d'auteur :

Formats disponibles

Front cover

Web services tools and

Web services runtime

WebSphere Version 5 Web Services Handbook

First Edition (March 2003)

This edition applies to Version 5 of WebSphere Application Server, Version 5 of WebSphere

© Copyright International Business Machines Corporation 2003. All rights reserved.

Part 1. Web services concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. Web services introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2. Introduction to SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

© Copyright IBM Corp. 2003. All rights reserved. iii

Chapter 3. Introduction to WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 4. Introduction to UDDI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

iv WebSphere Version 5 Web Services Handbook

Chapter 5. Web services invocation framework . . . . . . . . . . . . . . . . . . . . . 89

Chapter 6. Web services inspection language . . . . . . . . . . . . . . . . . . . . . 101

Chapter 7. Workflows and business processes . . . . . . . . . . . . . . . . . . . . 119

Chapter 8. Web Services Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Chapter 9. Web services security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

vi WebSphere Version 5 Web Services Handbook

Part 2. Web services implementation and samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Chapter 10. IBM WebSphere product family . . . . . . . . . . . . . . . . . . . . . . . 159

Chapter 11. Web services development overview . . . . . . . . . . . . . . . . . . 175

Chapter 12. Weather forecast application . . . . . . . . . . . . . . . . . . . . . . . . . 187

Chapter 13. WebSphere Studio Application Developer . . . . . . . . . . . . . . 197

viii WebSphere Version 5 Web Services Handbook

Chapter 14. Application Developer Integration Edition . . . . . . . . . . . . . . 241

Chapter 15. WebSphere SDK for Web Services . . . . . . . . . . . . . . . . . . . . 281

Chapter 16. Web Services Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

x WebSphere Version 5 Web Services Handbook

Chapter 17. WebSphere Web Services Technology Preview. . . . . . . . . . 317

Chapter 18. Web services scenario: architecture and implementation . 353

Chapter 19. Web services runtime and deployment in WebSphere . . . . 401

xii WebSphere Version 5 Web Services Handbook

Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

Appendix A. Installation and setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

Appendix B. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437

Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

Related publications . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 441

© Copyright IBM Corp. 2003. All rights reserved. xv

AIX® IBM eServer™ S/390®

The following terms are trademarks of other companies:

xvi WebSphere Version 5 Web Services Handbook

Whereas these concepts are described vendor-independent, the book also

This book is structured in two parts:

© Copyright IBM Corp. 2003. All rights reserved. xvii

Ueli Wahli is a Consultant IT Specialist at the IBM International Technical

Matija Drobnic is as an Advisory IT Specialist at IBM Global Services in

xviii WebSphere Version 5 Web Services Handbook

Christian Gerber is an IT Consultant at IBM Global Services in Munich,

Gustavo Garcia Ochoa is an IT Specialist at the IBM Center for e-business

Michael Schramm is a Consulting IT Specialist at IBM Global Services in

Thanks to the following people for their contributions to this project:

Become a published author

We want our Redbooks to be as helpful as possible. Send us your comments

xx WebSphere Version 5 Web Services Handbook

Part 1 Web services

© Copyright IBM Corp. 2003. All rights reserved. 1

Chapter 1. Web services introduction

In this introductory chapter we present the approach from a conceptual

The chapter is structured in the following way:

© Copyright IBM Corp. 2003. All rights reserved. 3

Furthermore, there is a need to further structure large applications into building