WebSphere Version 5.1 Application Developer 5.1.1 Web Services Handbook k

WebSphere Version 5.1 Application Developer 5.1.1 Web Services Handbook k
Front cover
WebSphere Version 5.1
Application Developer 5.1.1
Web Services Handbookk
Web services overview and concepts
Web services tools and
development
Web services runtime
environment
Ueli Wahli
Gustavo Garcia Ochoa
Sharad Cocasse
Markus Muetschard
ibm.com/redbooks
International Technical Support Organization
WebSphere Version 5.1
Application Developer 5.1.1
Web Services Handbook
February 2004
SG24-6891-01
Note: Before using this information and the product it supports, read the information in
“Notices” on page xxiii.
Second Edition (February 2004)
This edition applies to WebSphere Application Server Version 5.1 and WebSphere Studio
Application Developer Version 5.1.1, for use with the Windows NT and Windows 2000
Operating System.
© Copyright International Business Machines Corporation 2003, 2004. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP
Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
Changes to the previous version of this redbook . . . . . . . . . . . . . . . . . . . . . . xxvi
The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxvii
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Part 1. Web services concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Chapter 1. Web services introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Motivation for a services-oriented architecture. . . . . . . . . . . . . . . . . . . . . . . . . . 4
Requirements for a service-oriented architecture . . . . . . . . . . . . . . . . . . . . . 4
Concept of a service-oriented architecture . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Characteristics of the Web service architecture . . . . . . . . . . . . . . . . . . . . . . 7
Web services approach for a SOA architecture . . . . . . . . . . . . . . . . . . . . . . . . . 7
Other concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Properties of the service-oriented architecture . . . . . . . . . . . . . . . . . . . . . . 10
Business models well supported by Web services. . . . . . . . . . . . . . . . . . . . . . 11
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Car selection sub-process (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Purchase sub-process (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Financing sub-process (3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Web services interoperability (WS-I) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 2. Introduction to SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
The three pillars of SOAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Overall message format - Envelope with header and body . . . . . . . . . . . . 21
Encoding rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
RPC representation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
SOAP elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
URN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
SOAP envelope. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
© Copyright IBM Corp. 2003, 2004. All rights reserved.
iii
Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Advanced topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Communication styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Style and encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
SOAP implementation general architecture . . . . . . . . . . . . . . . . . . . . . . . . 34
IBM SOAP4J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Apache SOAP 2.3 implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
SOAP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Server deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
SOAP client API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Axis server architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Axis client architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Axis subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Implementations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
WebSphere SOAP Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Microsoft SOAP Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Other toolkits and server implementations . . . . . . . . . . . . . . . . . . . . . . . . . 43
Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Chapter 3. Introduction to WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
WSDL document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
WSDL document anatomy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Physical files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
WSDL definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Port types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Service definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Port definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
WSDL bindings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
iv
WebSphere Version 5.1 Web Services Handbook
SOAP binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
HTTP binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
MIME binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
WSDL API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Chapter 4. JAX-RPC (JSR 101). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Terminology: JAX-RPC and JSR 101 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
JAX-RPC basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
JAX-RPC client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
JAX-RPC client programming styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Static stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Dynamic Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Dynamic invocation interface (DII) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Which style to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Managed and unmanaged JAX-RPC clients. . . . . . . . . . . . . . . . . . . . . . . . 74
JAX-RPC specification details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Data type mapping: XML -> Java, Java -> XML . . . . . . . . . . . . . . . . . . . . . 75
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Chapter 5. Implementing Enterprise Web Services (JSR 109) . . . . . . . . . 77
JSR 109 overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Client programming model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Client types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Static stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Dynamic proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Dynamic invocation interface (DII) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Web service client deployment descriptor . . . . . . . . . . . . . . . . . . . . . . . 82
JAX-RPC mapping deployment descriptor . . . . . . . . . . . . . . . . . . . . . . 83
Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Server programming model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Service implementation bean. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Server container responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Deployment descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Web service deployment descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
JAX-RPC mapping deployment descriptor . . . . . . . . . . . . . . . . . . . . . . 92
Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Contents
v
Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
SRJ 109 implementations in WebSphere. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
SOAP over HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
SOAP over JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Chapter 6. Introduction to UDDI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
UDDI overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Static versus dynamic Web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
UDDI registry structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Interactions with UDDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Publishing information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Finding information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Using the information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
UDDI support in WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . 105
Advanced features of UDDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Modeling features for complex business entities . . . . . . . . . . . . . . . . . . . 105
External taxonomies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Powerful inquiry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Combining categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Advanced search using categorization . . . . . . . . . . . . . . . . . . . . . . . . 106
Qualifier for searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Internationalization features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Peer-based replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
UDDI Business Registry on the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Web front ends for registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Finding information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Publishing information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Java API for dynamic UDDI interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
UDDI4J overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Using the library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Writing UDDI clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Creating a proxy object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Finding information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Publishing information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Private UDDI registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Motivation for the use of private UDDI registries. . . . . . . . . . . . . . . . . . . . 120
Need for privacy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Getting rid of UDDI pollution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Standards and guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Possible scenarios for private UDDI registries . . . . . . . . . . . . . . . . . . . . . 121
vi
WebSphere Version 5.1 Web Services Handbook
Internal registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
e-marketplace UDDI registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Extranet UDDI registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Benefits of private UDDI registries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Additional considerations for private UDDI registries . . . . . . . . . . . . . . . . 122
Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Securing APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
WebSphere private UDDI registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
WebSphere Application Server 5.0.2 update . . . . . . . . . . . . . . . . . . . . 123
WebSphere Application Server 5.1 update . . . . . . . . . . . . . . . . . . . . . 124
Future of UDDI Version 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Keys assigned by publisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Human-friendly URI-based keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Complex registry topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Advanced security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Data model updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Extended inquiry API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Subscription API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Registry management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Chapter 7. Web services invocation framework . . . . . . . . . . . . . . . . . . . . 129
Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
General concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
WSIF architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Provider class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Operation class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
WSDL documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
More concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Interaction flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Definition or modification of the binding selection algorithm . . . . . . . . 135
Modification of a binding implementation at runtime . . . . . . . . . . . . . . 135
Two invocation models using WSIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Stub-less (dynamic) invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Invocation using stubs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Sample scenarios for WSIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Current status and future . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
WebSphere Application Server 5.0.2 update . . . . . . . . . . . . . . . . . . . . . . 138
Integration into WebSphere products . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Future versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Contents
vii
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Chapter 8. Web services inspection language . . . . . . . . . . . . . . . . . . . . . 141
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
WS-Inspection document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
WS-Inspection document anatomy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
WS-Inspection and UDDI relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
WS-Inspection definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Service name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Service description references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
WS-Inspection bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
WSDL binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
UDDI binding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Inspection document publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
WSIL examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
WSDL binding example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
UDDI binding example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
WS-Inspection API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Chapter 9. Workflows and business processes . . . . . . . . . . . . . . . . . . . . 159
Web services flow language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Concepts and terms in WSFL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Business process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Flow model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Recursive composition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Service provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Control link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Data link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Transition condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Life cycle interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Sample WSFL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Flow definition markup language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Elements of FDML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
FDML sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Business process execution language for Web services . . . . . . . . . . . . . . . . 165
viii
WebSphere Version 5.1 Web Services Handbook
Concepts and terms in BPEL4WS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Partners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Fault handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Data containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Business process execution language for Web services runtime . . . . . . . 167
BPEL future. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Chapter 10. Web Services Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Motivation for a gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Externalizing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Return on investment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Securing access to Web service providers . . . . . . . . . . . . . . . . . . . . . 170
Protocol transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Web service access to non-SOAP objects . . . . . . . . . . . . . . . . . . . . . 171
General concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Managing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Exposing Web services to the outside world . . . . . . . . . . . . . . . . . . . . 172
Importing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Managing channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Managing filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
UDDI publication and lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Administering the gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Managing namespace URI and WSDL URI . . . . . . . . . . . . . . . . . . . . . . . 175
Managing channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Managing filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Writing your own filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Managing UDDI references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Managing security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Web service security (WS-Security) . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Gateway-level authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Operation-level authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
SSL protocol using HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Proxy authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Deploying Web services to the gateway . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Implementation details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Enhancements in Version 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Contents
ix
Chapter 11. Web services security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Common security exposures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
WS-Security concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Evolution of the WS-Security specification . . . . . . . . . . . . . . . . . . . . . . . . 188
WS-Security authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Alternatives to using a username/password mechanism . . . . . . . . . . . 190
Enable authentication in your application . . . . . . . . . . . . . . . . . . . . . . 191
WS-Security integrity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Steps to enable integrity in your application . . . . . . . . . . . . . . . . . . . . 193
WS-Security confidentiality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Steps to enable confidentiality in your application . . . . . . . . . . . . . . . . 194
Transport channel security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
SOAP/HTTP transport channel security . . . . . . . . . . . . . . . . . . . . . . . . . . 195
WS-Security extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Web services security model proposition . . . . . . . . . . . . . . . . . . . . . . . . . 196
End-to-end enterprise security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Part 2. Web services implementation and samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Chapter 12. IBM WebSphere product family . . . . . . . . . . . . . . . . . . . . . . . 203
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
WebSphere foundations and tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
WebSphere Application Server - Express . . . . . . . . . . . . . . . . . . . . . . 206
WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
WebSphere Application Server Network Deployment . . . . . . . . . . . . . 206
WebSphere Application Server Enterprise Edition . . . . . . . . . . . . . . . 206
Current status and outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
WebSphere Application Server Version 5.0.2 updates . . . . . . . . . . . . 207
WebSphere Application Server Version 5.1 updates . . . . . . . . . . . . . . 208
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Information Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
WebSphere Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
WebSphere Studio Site Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
WebSphere Studio Application Developer . . . . . . . . . . . . . . . . . . . . . . 210
WebSphere Studio Application Developer Integration Edition . . . . . . . 211
WebSphere Studio Enterprise Developer . . . . . . . . . . . . . . . . . . . . . . 211
Current status and outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
x
WebSphere Version 5.1 Web Services Handbook
Current status and outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
WebSphere reach and user experience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
WebSphere Portal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Portal Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Portal Extend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Portal Experience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Current status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
WebSphere Everyplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
IBM WebSphere Everyplace Embedded Edition . . . . . . . . . . . . . . . . . 215
WebSphere Everyplace Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
WebSphere Everyplace Server, Service Provider Offering . . . . . . . . . 215
Current status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
WebSphere Commerce. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
WebSphere Commerce Professional Entry . . . . . . . . . . . . . . . . . . . . . 217
WebSphere Commerce Professional Edition. . . . . . . . . . . . . . . . . . . . 217
WebSphere Commerce Business Edition . . . . . . . . . . . . . . . . . . . . . . 217
Current status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
WebSphere Business Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
WebSphere MQ Integrator Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Current status and outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
WebSphere Business Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Current status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Chapter 13. Web services development overview . . . . . . . . . . . . . . . . . . 221
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Web services development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Build phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Deployment phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Run phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Management phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Building a new Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Bottom-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Top-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Contents
xi
Multiple services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Types of Web services implementation . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Building a new Web service client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Static client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Dynamic client with known service type . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Dynamic client with unknown service type . . . . . . . . . . . . . . . . . . . . . . . . 231
Types of client implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Chapter 14. Weather forecast application. . . . . . . . . . . . . . . . . . . . . . . . . 233
Weather forecast application components . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Business module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Data module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Back-end module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Information flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Base code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Weather data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Weather forecast JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Weather forecast session EJB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Weather predictor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Environment variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Chapter 15. WebSphere Studio Application Developer . . . . . . . . . . . . . . 247
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Strategies for developing a Web service. . . . . . . . . . . . . . . . . . . . . . . . . . 248
Tool support by WebSphere Studio Application Developer . . . . . . . . . . . 248
Bottom-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Top-down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Client development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Selected scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Preparing the enterprise applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Installing the weather forecast application . . . . . . . . . . . . . . . . . . . . . . . . 251
Creating a Web service from a JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Create a Web project for the test client. . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Web Service wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Service Deployment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Web Service Java Bean Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Web Service Java Bean Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Web Service Test Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Web Service Proxy Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Web Service Client Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Generated files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
xii
WebSphere Version 5.1 Web Services Handbook
Files generated in the server-side Web project . . . . . . . . . . . . . . . . . . 259
Files generated in the client-side Web project . . . . . . . . . . . . . . . . . . . 260
Testing the Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Web Services Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Test using generated JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Proxy classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Writing Web service clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Stand-alone Java client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Running the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Web client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Tracing SOAP messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Using the TCP/IP Monitoring server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Define the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Change the endpoint port number . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Start the servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Run a client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
TCP/IP Monitor view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Target URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Creating a Web service from a session bean. . . . . . . . . . . . . . . . . . . . . . . . . 271
Running the Web Service wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Testing the EJB Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Web Services Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Universal test client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Client servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Web services and JMS protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
SOAP over JMS example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Configuring the JMS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Projects for the Web service and sample client . . . . . . . . . . . . . . . . . . . . 274
Create the SOAP over JMS Web service . . . . . . . . . . . . . . . . . . . . . . . . . 275
Creating a Web service client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Create the Java proxy classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Create the test servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Creating a Web service top-down from WSDL. . . . . . . . . . . . . . . . . . . . . . . . 279
Create Web projects and import the WSDL . . . . . . . . . . . . . . . . . . . . . . . 279
Create the skeleton JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Generated files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Client proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Implementing the JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Web services interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
WS-I preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Web service generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
WSDL validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Contents
xiii
Validating SOAP messages with the TCP/IP Monitor . . . . . . . . . . . . . . . . 283
Creating a Web service from a URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Importing the servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Creating a server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Running the servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Creating the URL Web service for the servlet . . . . . . . . . . . . . . . . . . . . . . 286
Testing the URL Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Creating a Web service from DADX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
DADX group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Creating a Web service from an SQL statement. . . . . . . . . . . . . . . . . . . . 290
Create an SQL statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Create a DADX group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Creating a DADX file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Create the Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Testing the Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Publishing and exploring a UDDI registry. . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Publishing a business entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Web Services Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Discovering business entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Publishing the weather forecast Web service . . . . . . . . . . . . . . . . . . . . . . 298
Discovering the weather forecast Web service . . . . . . . . . . . . . . . . . . . . . 299
Deployment of the sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Exporting the EAR file and installing the enterprise application . . . . . . . . 301
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Chapter 16. Web services security with Application Developer . . . . . . . 303
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Architecture and deployment model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Securing Web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Implementing security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Defining client authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Defining server authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Testing authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Defining client integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Defining server integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Testing integrity and authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Confidentiality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Defining client confidentiality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Defining server confidentiality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Configuring the server for confidentiality . . . . . . . . . . . . . . . . . . . . . . . 333
Testing confidentiality, integrity, and authentication . . . . . . . . . . . . . . 334
xiv
WebSphere Version 5.1 Web Services Handbook
Resetting the server configuration and client proxy . . . . . . . . . . . . . . . . . 336
Trace output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
J2EE security and WS-Security relationship . . . . . . . . . . . . . . . . . . . . . . . . . 337
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Chapter 17. Application Developer Integration Edition . . . . . . . . . . . . . . 341
Enterprise services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Creating an enterprise service: Bottom-up . . . . . . . . . . . . . . . . . . . . . . . . 342
Creating an enterprise service: Top-down . . . . . . . . . . . . . . . . . . . . . . . . 343
Resource adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Using Application Developer Integration Edition . . . . . . . . . . . . . . . . . . . . . . 344
Business Integration perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Services view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Enhanced WSDL editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Business process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Process editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Elements of the process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Dynamic process properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Sample business process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Prepare existing services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Create a service project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Import existing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Existing Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Set up WSDL files of existing services . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Create the business process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Adding services to the process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Adding flow to the process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Messages and variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Extract of generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Process files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Process file: temperature.process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
FDML file: temperature.fdml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Adding Java snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Defining the process interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Generate deploy code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Flow definition markup language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Testing a business process in the test environment . . . . . . . . . . . . . . . . . . . 370
Web service client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Business process Web client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Configuring a remote WebSphere Application Server . . . . . . . . . . . . . . . 373
Debugging business processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Contents
xv
Setting breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Start debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Process debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Using the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Deployment to an application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Importing the process solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Importing the projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Web project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
EJB project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Service project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
EAR project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Defining the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Test the process sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Chapter 18. WebSphere SDK for Web Services . . . . . . . . . . . . . . . . . . . . 381
The difference between the packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
WebSphere SDK for Web Services Version 5.1 . . . . . . . . . . . . . . . . . . . . . . 383
Application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
WS-Security in WSDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Using the tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Bean2WebService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Generation steps explained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Sample setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Bean2WebService at work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Command line help and options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
EJB2WebService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
WSDL2WebService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Generation stages explained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Sample setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
WSDL2WebService at work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
WSDL2Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Sample setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
WSDL2Client at work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Working with the application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Installing the StringService enterprise application . . . . . . . . . . . . . . . . 402
Starting the server and listing the applications . . . . . . . . . . . . . . . . . . 402
Running a J2SE Web-service client. . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Running the J2EE client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
UDDIPublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
xvi
WebSphere Version 5.1 Web Services Handbook
Publishing a business entity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Publishing a business service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Security for publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Additional properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
UDDIUnpublish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Unpublishing a business entity or service . . . . . . . . . . . . . . . . . . . . . . 406
Security for unpublishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Additional properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Sample 1—JavaBean request/response Web service . . . . . . . . . . . . . . . . . . 406
Using sample 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Rebuilding sample 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Implementing the weather forecast Web service . . . . . . . . . . . . . . . . . . . . . . 409
Setting up the environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Running the EJB2WebService tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Generated output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Starting the Web service in the application server . . . . . . . . . . . . . . . . . . 412
Creating and running a stand-alone client . . . . . . . . . . . . . . . . . . . . . . . . 413
Client logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Service locator or service factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Compile and run the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Sample client output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Cleanup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Using the WSDK plug-in for Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Starting Eclipse with the WSDK plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Preparing a server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Creating a Web service from a JavaBean. . . . . . . . . . . . . . . . . . . . . . . . . 417
Create a Web project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Import the weather forecast application . . . . . . . . . . . . . . . . . . . . . . . . 417
Run the Web Service wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Testing the Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Using the Web Services Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Creating and running a client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Creating a Web service from a session EJB . . . . . . . . . . . . . . . . . . . . . . . 424
Import an EJB JAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Create a Web project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Run the Web Service wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Testing the EJB Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Creating a stand-alone client application . . . . . . . . . . . . . . . . . . . . . . . . . 426
Exporting the proxy and mapping classes . . . . . . . . . . . . . . . . . . . . . . 427
Compile and run the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Contents
xvii
Chapter 19. Web services scenario: Architecture and implementation . 429
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Scenario situation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Functional requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Non-functional requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Incorporating Web services concepts and technologies . . . . . . . . . . . . . . 433
Process to create the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Types of service invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Setup phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Build phase of the client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Deployment phase of the client application. . . . . . . . . . . . . . . . . . . . . . . . 439
Run phase of the client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
General concepts of the UnitedSuns client application . . . . . . . . . . . . . . . . . 441
Application flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Abstract servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
Invocation result JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Preferences class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Preferences JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Preferences servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
UDDI lookup sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
UDDI lookup JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
UDDI lookup servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Response JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Testing the UDDI lookup sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
Sample 1: Dynamic invocation using UDDI lookup . . . . . . . . . . . . . . . . . . 454
Start JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Response JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
Test the sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Sample 2: Dynamic invocation using WSIL lookup . . . . . . . . . . . . . . . . . . 461
Start JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Response JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Testing the sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
General concepts of the IWA application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Application flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Home page with update HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
Update weather servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
Response JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Static client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
xviii
WebSphere Version 5.1 Web Services Handbook
Installing the scenario in Application Developer . . . . . . . . . . . . . . . . . . . . . . . 473
Enterprise applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
Importing the enterprise applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
Server project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Configurating a server for testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Configure the HOSTS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
Run the samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Static client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Sample 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Sample 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
General UDDI lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Weather update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
Chapter 20. Web services runtime and deployment in WebSphere . . . . 479
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
WebSphere Application Server general concepts . . . . . . . . . . . . . . . . . . . . . 480
Administration basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
WebSphere topology building blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Administrative console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
Enterprise application deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Installing an enterprise application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Preparing for application install (first page) . . . . . . . . . . . . . . . . . . . . . 484
Preparing for application install (second page) . . . . . . . . . . . . . . . . . . 484
Install new application pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Starting and stopping enterprise applications . . . . . . . . . . . . . . . . . . . . . . 486
Regenerate the HTTP server plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Web services deployment in WebSphere environment . . . . . . . . . . . . . . . . . 487
Web services enabling with the SoapEarEnabler tool . . . . . . . . . . . . . . . 487
Configuring a server for the ITSO Web services . . . . . . . . . . . . . . . . . . . . . . 487
Start the server and the administrative console . . . . . . . . . . . . . . . . . . . . 487
Define the data source for the weather forecast database . . . . . . . . . . . . 488
Creating JMS resources for use with the SOAP/JMS Web service . . . . . 489
Create a queue connection factory and queue destination . . . . . . . . . 490
Create a listener port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
Activate the queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
Activating Web service security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
Enable global security in WebSphere runtime . . . . . . . . . . . . . . . . . . . 491
Configure the server to decrypt the request. . . . . . . . . . . . . . . . . . . . . 493
Configure the server to encrypt the response . . . . . . . . . . . . . . . . . . . 493
Configuring for the scenario application . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Configure the HOSTS file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Configure the server with virtual host names . . . . . . . . . . . . . . . . . . . . 494
Restart the application server with security. . . . . . . . . . . . . . . . . . . . . . . . 494
Contents
xix
Install the enterprise applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Install the scenario enterprise application . . . . . . . . . . . . . . . . . . . . . . . . . 494
Regenerate the HTTP Server plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Run the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Install the enterprise applications of Application Developer . . . . . . . . . . . 495
Update the DADX group configuration. . . . . . . . . . . . . . . . . . . . . . . . . 496
Define a JDBC driver and data source . . . . . . . . . . . . . . . . . . . . . . . . 496
Installing the WORF runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Installing the enterprise applications . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Running the sample enterprise applications . . . . . . . . . . . . . . . . . . . . 497
Installing an application with transport channel security . . . . . . . . . . . . . . . . 497
Configuring for HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Create a self-signed certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Extract the certificate for installation into WebSphere . . . . . . . . . . . . . 498
Install the certificate in WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Configure the HTTP server for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Accessing a Web service from a stand-alone Java client . . . . . . . . . . . . . . . 500
Using Tivoli Performance Viewer (TPF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Enable PMI service in the application server . . . . . . . . . . . . . . . . . . . . 501
Restart the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
Start Tivoli Performance Viewer (TPV) . . . . . . . . . . . . . . . . . . . . . . . . 501
Implementing a private UDDI registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Install the UDDI registry on an application server . . . . . . . . . . . . . . . . . . . 503
Using the UDDI registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Using the UDDI GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Start the UDDI GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Publishing information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
Using the UDDI Explorer with the private UDDI registry . . . . . . . . . . . . . . 509
Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
Finding information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
More information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
Appendix A. Installation and setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
Installation planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
WebSphere Application Server Version 5.1 requirements . . . . . . . . . . . . 516
Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Database support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Installing WebSphere Application Server 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . 517
Installation process for Version 5.1 base product . . . . . . . . . . . . . . . . . . . 517
Verifying the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
xx
WebSphere Version 5.1 Web Services Handbook
Fixpack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
Installing WebSphere Application Server Network Deployment 5.1 . . . . . 519
Application Server Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
Installation of Application Developer 5.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Installing optional components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Starting Application Developer with a dedicated workspace. . . . . . . . . . . 521
Installation of Application Developer Integration Edition . . . . . . . . . . . . . . . . 522
CICS Transaction Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
Agent Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
Installation of WebSphere SDK for Web Services 5.1 . . . . . . . . . . . . . . . . . . 523
Eclipse plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
WSDK installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
Installation of the Emerging Technologies Toolkit (ETTK) . . . . . . . . . . . . . . . 524
Installing the sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
Setting up the WEATHER database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
Appendix B. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
System requirements for downloading the Web material . . . . . . . . . . . . . 526
Web material content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Workspace projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Installing the weather forecast application . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
Set up the WEATHER database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
Set up the WebSphere test server (WeatherServer) . . . . . . . . . . . . . . . . 529
Server project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
WebSphere Version 5.1 server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Configuring the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Define an authentication alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Define a data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Verify the server variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Configure the JMS server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Runtime classpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Set up the initial applications for Web services development . . . . . . . . . . 537
Test the starting application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Installing the scenario sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
Installing the sample applications into WebSphere . . . . . . . . . . . . . . . . . . . . 538
Importing solutions into Application Developer . . . . . . . . . . . . . . . . . . . . . . . 539
Importing a sample project into Application Developer . . . . . . . . . . . . . . . 539
Importing a single source file into Application Developer . . . . . . . . . . . . . 541
Universal test client problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Contents
xxi
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
IBM Redbooks collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
xxii
WebSphere Version 5.1 Web Services Handbook
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information on the products and services currently available in your area.
Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product, program, or service that
does not infringe any IBM intellectual property right may be used instead. However, it is the user's
responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document.
The furnishing of this document does not give you any license to these patents. You can send license
inquiries, in writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer
of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may
make improvements and/or changes in the product(s) and/or the program(s) described in this publication at
any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the
materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm
the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on
the capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them
as completely as possible, the examples include the names of individuals, companies, brands, and products.
All of these names are fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrates programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the
sample programs are written. These examples have not been thoroughly tested under all conditions. IBM,
therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to IBM for the purposes of
developing, using, marketing, or distributing application programs conforming to IBM's application
programming interfaces.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
xxiii
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
AIX®
alphaWorks®
CICS®
Cloudscape™
CrossWorlds®
DB2 Universal Database™
DB2®
developerWorks™
Domino™
eServer™
Everyplace™
IBM eServer™
IBM®
ibm.com®
IMS™
Informix®
Lotus®
MQSeries®
Notes®
OS/390®
Redbooks (logo)™
Redbooks™
S/390®
SAA®
Sametime®
SecureWay®
SLC™
SP2®
Tivoli®
VisualAge®
WebSphere®
z/OS™
The following terms are trademarks of International Business Machines Corporation and Rational Software
Corporation, in the United States, other countries or both:
ClearCase®
Rational®
The following terms are trademarks of other companies:
ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United
States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.
C-bus is a trademark of Corollary, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure
Electronic Transaction LLC.
Other company, product, and service names may be trademarks or service marks of others.
xxiv
WebSphere Version 5.1 Web Services Handbook
Preface
This IBM® Redbook describes the new concept of Web services from various
perspectives. It presents the major building blocks Web services rely on. Here,
well-defined standards and new concepts are presented and discussed.
Whereas these concepts are described as vendor independent, this book also
presents IBM’s view and illustrates with suitable demonstration applications how
Web services can be implemented using IBM’s product portfolio, especially
WebSphere® Application Server Version 5.1 and WebSphere Studio Application
Developer Version 5.1.1.
The IBM Redbook Web Services Wizardry with WebSphere Studio Application
Developer, SG24-6292, published in April 2002, has already covered the basics
of Web services and how they can be implemented using the corresponding IBM
tools. Thus, this new book goes beyond the scope of the 2002 release. Two
major focus areas are defined:
Description of the underlying concepts—While the 2002 book mainly
describes implementation aspects for J2EE, we concentrate more on the
underlying principles and new concepts that are about to emerge, and their
impact for the implementation of new application types.
Update of the information provided—Since the release of the first book,
roughly two year have passed that have brought a new generation, not only of
basically all WebSphere products, but also on all standards on Web services.
Thus, we update the provided information.
Although this book uses the 2002 book as a basis, it is written as a stand-alone
release. All relevant concepts are introduced in reasonable depth. Reading
SG24-6292 is thus not mandatory, but it deepens some aspects and is therefore
still a useful source of information.
This book is structured in two parts:
Part 1 presents the underlying concepts for the use of Web services: It
presents the basic programming model, well-known concepts in an updated
way, and new concepts that go beyond the scope of the earlier books.
Part 2 shows how Web services can be implemented using the latest IBM
tools. Here we introduce a sample application that is demonstrated in various
ways.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
xxv
Changes to the previous version of this redbook
New in this version of the publication are the discussion and application of the
two new specifications, JSR-101 Java API for XML-Based RPC (JAX-RPC), and
JSR-109 Implementing Enterprise Web Services, discussion of the Business
Process Execution Language (BPEL4WS) specification, extended coverage of
Web service security, and an extended sample with database access.
All the samples have been tested on Application Server 5.0.2 and 5.1 and
Application Developer 5.1 and 5.1.1. Only minor changes were necessary to
move to Application Server 5.1 and Application Developer 5.1.1.
The team that wrote this redbook
This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization, Raleigh Center.
Ueli Wahli is a Consultant IT Specialist at the IBM International Technical
Support Organization in San Jose, California. Before joining the ITSO 19 years
ago, Ueli worked in technical support at IBM Switzerland. He writes extensively
and teaches IBM classes worldwide on application development, object
technology, WebSphere Application Server, and lately WebSphere Studio
products. In his ITSO career, Ueli has produced over 30 IBM Redbooks™. Ueli
holds a degree in Mathematics from the Swiss Federal Institute of Technology.
Sharad Cocasse is a Staff Software Engineer on the WebSphere Execution
Team. His experience includes over five years of developing object-oriented
applications, supporting WebSphere customers, and developing/delivering
WebSphere education to customers and IBM field technical personnel. Most
recently, he has been assisting customers with advanced technical support for
mission-critical WebSphere deployments. He has also coauthored a number of
WebSphere-related publications. Sharad holds a Master Degree in Electrical
Engineering from the University of Alabama and lives and works in Rochester,
Minnesota.
Markus Muetschard is a Technical Leader with a focus on IBM WebSphere
technologies and product set in the Advanced Technology Support department of
Perficient, Inc. Markus has a ABS in Mathematics and BS in Computer Science
and Engineering. His expertise includes application and system design, and
end-to-end implementations applying object-oriented, Web, and e-Business
technologies. Before joining Perficient, Inc., Markus held various leading
positions in IT development and service companies, including 13 years with IBM
in Switzerland and the ITSO in San Jose, CA, USA, as mentor, consultant,
project leader, author, and instructor.
xxvi
WebSphere Version 5.1 Web Services Handbook
Gustavo Garcia Ochoa is an IT Specialist at IBM Global Services Madrid,
Spain. He has been with IBM for four years, focusing on the design and
development of e-business solutions. Before joining IBM, he worked as a
researcher at the División de Ingeniería de Sistemas y Automática in Madrid,
where he concentrated on the authentication and recognition of video streaming.
His areas of interest include e-business architecture and solutions, computer
vision, and industrial and utilities businesses. Gustavo holds a Bachelor’s and a
Master's degree in Industrial Engineering, with a major in Electrical Engineering,
both from the Universidad Politécnica de Madrid, Spain. Gustavo is also
co-author of the publication WebSphere Version 5 Web Services Handbook,
SG24-6891.
Thanks to the following people for their contributions to this project:
Matija Drobnic, IBM Slovenia, Christian Gerber, IBM Germany, and
Michael Schramm, IBM Austria, who were part of the team that wrote the
orginial IBM Redbook
Andre Tost of the WebSphere Business Developement Team for general
Web with Web services technology and trends
Eric Erpenbach and Michele Chilanti of the WebSphere Skills Transfer
Team, Rochester, for the help with SOAP/JMS and Studio Application
Developer Integration Edition
Olaf Zimmermann, a Consulting IT Architect in IBM Germany, Heidelberg,
who provided the basis for the introductory chapters on SOAP, WSDL, and
UDDI
Bertrand Portier, Andy J Clarke, and Simon Nash of IBM Hursley for their
input and help on the WebSphere SDK for Web Services
Become a published author
Join us for a two- to six-week residency program! Help write an IBM Redbook
dealing with specific products or solutions, while getting hands-on experience
with leading-edge technologies. You'll team with IBM technical professionals,
Business Partners and/or customers.
Your efforts will help increase product acceptance and customer satisfaction. As
a bonus, you'll develop a network of contacts in IBM development labs, and
increase your productivity and marketability.
Find out more about the residency program, browse the residency index, and
apply online at:
ibm.com/redbooks/residencies.html
Preface
xxvii
Comments welcome
Your comments are important to us!
We want our Redbooks to be as helpful as possible. Send us your comments
about this or other Redbooks in one of the following ways:
Use the online Contact us review redbook form found at:
ibm.com/redbooks
Send your comments in an Internet note to:
[email protected]
Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HZ8 Building 662
P.O. Box 12195
Research Triangle Park, NC 27709-2195
xxviii
WebSphere Version 5.1 Web Services Handbook
Part 1
Part
1
Web services
concepts
In this part we introduce the underlying concepts of Web services:
Simple Object Access Protocol (SOAP)
Web services description language (WSDL)
Universal description, discovery, and integration (UDDI)
Web services invocation framework (WSIF)
Web services inspection language (WSIL)
Workflows and business processes: Web services flow language (WSFL),
flow definition markup language (FDML), and business process execution
language (BPEL)
Web Services Gateway
Web services security
© Copyright IBM Corp. 2003, 2004. All rights reserved.
1
2
WebSphere Version 5.1 Web Services Handbook
1
Chapter 1.
Web services introduction
This chapter presents the concept of the service-oriented architecture (SOA) for
complex distributed Web-based systems. We introduce the concept of Web
services, discuss its properties, and show how this approach implements the
SOA paradigm. Finally, we sketch what new business models can be
implemented with the use of the Web services concept.
In this introductory chapter we present the approach from a conceptual
perspective. The three subsequent chapters present the major concepts in more
technical detail.
The chapter is structured in the following way:
Business motivation for a service-oriented architecture
Overview of the service-oriented architecture
Overview of the relevant building blocks for Web services (SOAP, WSDL, and
UDDI)
Business models that make use of the new architecture
© Copyright IBM Corp. 2003, 2004. All rights reserved.
3
Motivation for a services-oriented architecture
There is a strong trend for companies to integrate existing systems to implement
IT support for business processes that cover the entire business cycle. Today,
interactions already exist using a variety of schemes that range from very rigid
point-to-point electronic data interchange (EDI) interactions to open Web
auctions. Many companies have already made some of their IT systems available
to all of their divisions and departments, or even their customers or partners on
the Web. However, techniques for collaboration vary from one case to another
and are thus proprietary solutions; systems often collaborate without any vision
or architecture.
Thus, there is an increasing demand for technologies that support the connecting
or sharing of resources and data in a very flexible and standardized manner.
Because technologies and implementations vary across companies and even
within divisions or departments, unified business processes could not be
smoothly supported by technology. Integration has been developed only between
units that are already aware of each other and that use the same static
applications.
Furthermore, there is a need to further structure large applications into building
blocks in order to use well-defined components within different business
processes. A shift towards a service-oriented approach will not only standardize
interaction, but also allows for more flexibility in the process. The complete value
chain within a company is divided into small modular functional units, or services.
A service-oriented architecture thus has to focus on how services are described
and organized to support their dynamic, automated discovery and use.
Companies and their sub-units should be able to easily provide services. Other
business units can use these services in order to implement their business
processes. This integration can be ideally performed during the runtime of the
system, not just at the design time.
Requirements for a service-oriented architecture
For an efficient use of a service-oriented scenario, a number of requirements
have to be fulfilled:
Interoperability between different systems and programming languages—The
most important basis for a simple integration between applications on
different platforms is a communication protocol, which is available for most
systems and programming languages.
4
WebSphere Version 5.1 Web Services Handbook
Clear and unambiguous description language—To use a service offered by a
provider, it is not only necessary to be able to access the provider system, but
also the syntax of the service interface must be clearly defined in a
platform-independent fashion.
Retrieval of the service—To allow a convenient integration at design time or
even runtime of the system, we require a mechanism that provides search
facilities to retrieve suitable available services. Such services should be
classified into computer-accessible, hierarchical categories, or taxonomies,
based upon what the services in each category do and how they can be
invoked.
Security—Protection of the services, including the information passed to and
received from the service against unauthorized and malicious access, must
be supported by the platform to win the confidence of the requestor
(chain)—at the end the business customer(s). The type and extent of security
depends on the type and placement of the participants—service requestors
and service providers—and the services themselves. Service usage
monitoring and security incident action plans have to be in place to detect
unauthorized access (attempts) and trigger counter measures. Even though
security feels kind of contradictory to the service idea, it is required to
empower and retain authenticated and authorized requestors/customers
while fencing off everything and everyone.
Concept of a service-oriented architecture
This is a short introduction to the key concepts of a service-oriented architecture.
References for more information are given in “More information” on page 17 at
the end of this chapter.
Each component in a service-oriented architecture can play one (or more) of
three roles: Service provider, broker, and requestor, which perform the
operations shown in Figure 1-1.
Chapter 1. Web services introduction
5
2
Service
Requestor
1
Internet
Service
Provider
3
Service
Broker
Legacy
system
Figure 1-1 Web services roles and operations
1. The service provider creates a Web service and possibly publishes its
interface and access information to the service registry.
Each provider must decide which services to expose, how to make trade-offs
between security and easy availability, and how to price the services (or, if
they are free, how to exploit them for other value). The provider also has to
decide what category the service should be listed in for a given broker service
and what sort of trading partner agreements are required to use the service.
2. The service broker (also known as service registry) is responsible for making
the Web service interface and implementation access information available to
any potential service requestor.
The implementers of a broker have to decide about the scope of the broker.
Public brokers are available all over the Internet, while private brokers are
only accessible to a limited audience, for example, users of a company-wide
intranet. Furthermore, the width and breadth of the offered information has to
be decided. Some brokers will specialize in breadth of listings. Others will
offer high levels of trust in the listed services. Some will cover a broad
landscape of services, and others will focus within a given industry. Brokers
will also arise that simply catalog other brokers. Depending on the business
model, a broker may attempt to maximize look-up requests, number of
listings, or accuracy of the listings.
3. The service requestor locates entries in the broker registry using various
find operations and then binds to the service provider in order to invoke one of
its Web services.
6
WebSphere Version 5.1 Web Services Handbook
One important issue for users of services is the degree to which services are
statically chosen by designers compared to those dynamically chosen at
runtime. Even if most initial usage is largely static, any dynamic choice opens
up the issues of how to choose the best service provider and how to assess
quality of service. Another issue is how the user of services can assess the
risk of exposure to failures of service suppliers.
Characteristics of the Web service architecture
The presented service-oriented architecture employs a loose coupling between
the participants. Such a loose coupling provides greater flexibility:
In this architecture, a client is not coupled to a server, but to a service. Thus,
the integration of the server to use takes place outside of the scope of the
client application programs.
Old and new functional blocks are encapsulated into components that work
as services.
Functional components and their interfaces are separated. Therefore, new
interfaces can be plugged in more easily (for example, refer to WSIF in “Web
services invocation framework” on page 129).
Within complex applications, the control of business processes can be
isolated. A business rule engine can be incorporated to control the workflow
of a defined business process. Depending on the state of the workflow, the
engine calls the respective services.
Services can be incorporated dynamically during runtime.
Bindings are specified using configuration files and can thus easily be
adapted to new needs.
Web services approach for a SOA architecture
Web services are a rather new technology that implements the above
service-oriented architecture. During the development of this technology, a major
focus was put on making functional building blocks accessible over standard
Internet protocols that are independent from platforms and programming
languages.
Web services are self-contained, modular applications that can be described,
published, located, and invoked over a network. Web services perform
encapsulated business functions, ranging from simple request-reply to full
business process interactions.
Chapter 1. Web services introduction
7
These services can be new applications or just wrapped around existing legacy
systems to make them network-enabled. Services can rely on other services to
achieve their goals.
The following are the core technologies used for Web services. These
technologies are covered in detail in the subsequent chapters.
XML (eXtensible Markup Language) is the markup language that underlies
most of the specifications used for Web services. XML is a generic language
that can be used to describe any kind of content in a structured way,
separated from its presentation to a specific device.
SOAP (Simple Object Access Protocol), similar to JDBC, is a network,
transport, and programming language and platform neutral protocol that
allows a client to call a remote service. The message format is XML.
WSDL (Web services description language) is an XML-based interface and
implementation description language. The service provider uses a WSDL
document in order to specify the operations a Web service provides, as well
as the parameters and data types of these operations. A WSDL document
also contains the service access information.
UDDI (universal description, discovery, and integration) is both a client-side
API and a SOAP-based server implementation that can be used to store and
retrieve information on service providers and Web services.
Figure 1-2 shows the relationship between the core elements of the SOA.
All elements use XML including XML namespaces and XML schemas.
The service requestor and provider communicate with each other.
WSDL is one alternative to make service interfaces and implementations
available in the UDDI registry.
WSDL includes the workflow description (business process execution
language for Web services, BPEL4WS)
WSDL is the base for SOAP server deployment and SOAP client generation.
8
WebSphere Version 5.1 Web Services Handbook
XSD
XML
WSDL
BPEL4WS
Service description
(including Worklflow)
Metadata/vocabulary
UDDI
(Broker)
HTTP
Runtime
transports
other
SOAP
Requestor
Provider
J2EE
other
SOA Runtime
Implementation
Figure 1-2 Main building blocks in an SOA approach based on Web services
Other concepts
Besides WSDL, SOAP, and UDDI, there have been a number of other concepts
developed to define certain sub-aspects. However, they are not considered to be
the major building blocks of the new Web services approach (at least at the time
this book was being written). Some of them are already well-defined standards,
while others are just about to emerge. Some are already introduced into
commercial products while others are available as alpha versions on the Web, if
at all. The following concepts are presented in more detail in the later sections of
this chapter:
WSIL (Web services inspection language) is another service discovery
mechanism that addresses a different set of requirements using a distributed
usage model. WSIL is designed around an XML-based model for building an
aggregation of references to existing Web service descriptions.
WSIF (Web services invocation framework) is a means for a more flexible way
to invoke Web services that allows the developer to develop services for
transport protocols and service environments of his choice.
Chapter 1. Web services introduction
9
WSGW (Web Services Gateway) can be seen as a kind of proxy that acts as
an additional layer between the Web service client and the Web service
provider. It enables a flexible way to call Web services located in an intranet
from the Internet, as well as calling Internet Web services from the intranet.
WSFL (Web services flow language), FDML (flow definition markup
language), and BPEL (business process execution language)—connecting
Web services and specifying how collections of Web services are jointly used
to implement more complex functionality, typically a business process or a
workflow.
Properties of the service-oriented architecture
The service-oriented architecture offers the following properties:
Web services are self-contained.
On the client side, no additional software is required. A programming
language with XML and HTTP client support is enough to get you started. On
the server side, merely a Web server and a SOAP server are required. It is
possible to Web services enable an existing application without writing a
single line of code.
Web services are self-describing.
Neither the client nor the server knows or cares about anything besides the
format and content of request and response messages (loosely coupled
application integration). The definition of the message format travels with the
message; no external metadata repositories or code generation tools are
required.
Web services can be published, located, and invoked across the Web.
This technology uses established lightweight Internet standards such as
HTTP. It leverages the existing infrastructure. Some additional standards that
are required to do so include SOAP, WSDL, and UDDI.
Web services are language-independent and interoperable.
Client and server can be implemented in different environments. Existing
code does not have to be changed in order to be Web service enabled. In this
publication, however, we assume that Java is the implementation language for
both the client and the server side of the Web service.
Web services are inherently open and standard-based.
XML and HTTP are the major technical foundation for Web services. A large
part of the Web service technology has been built using open-source projects.
Therefore, vendor independence and interoperability are realistic goals this
time.
10
WebSphere Version 5.1 Web Services Handbook
Web services are dynamic.
Dynamic e-business can become reality using Web services because, with
UDDI and WSDL, the Web service description and discovery can be
automated.
Web services are composable.
Simple Web services can be aggregated to more complex ones, either using
workflow techniques or by calling lower-layer Web services from a Web
service implementation. Web services can be chained together to perform
higher-level business functions. This shortens development time and enables
best-of-breed implementations.
Web services build on proven mature technology.
There are a lot of commonalities, as well as a few fundamental differences to
other distributed computing frameworks. For example, the transport protocol
is text based and not binary.
Web services are loosely coupled.
Traditionally, application design has depended on tight interconnections at
both ends. Web services require a simpler level of coordination that allows a
more flexible re-configuration for an integration of the services in question.
Web services provide programmatic access.
The approach provides no graphical user interface; it operates at the code
level. Service consumers have to know the interfaces to Web services but do
not have to know the implementation details of services.
Web services provide the ability to wrap existing applications.
Already existing stand-alone applications can easily be integrated into the
service-oriented architecture by implementing a Web service as an interface.
Business models well supported by Web services
Due to the properties described above, Web services are well suited for the
encapsulation of rather small modules that perform independent tasks within a
highly heterogeneous e-business landscape. Thus, they can easily be used to
wrap applications that need little or no information concerning the state of the
current business process and thus can be plugged easily into different business
processes.
For connecting to a large monolithic system that does not allow the
implementation of different flexible business processes, other approaches might
be better suited, for example, to satisfy specialized features, such as
performance and security.
Chapter 1. Web services introduction
11
The use of the service-oriented architecture in general, and Web services in
particular, enables an easy implementation of business models of the following
kinds:
Business information—Sharing of information with consumers or other
businesses. Web services can be used to expand the reach through such
services as news streams, local weather reports, integrated travel planning,
intelligent agents, and so forth.
Business integration—Providing transactional, fee-based services for
customers. A global value network of suppliers can be easily created. Web
services can be implemented in auctions, e-marketplaces, reservation
systems, and so forth.
Business process externalization—Web services can be used to model
value chains by dynamically integrating processes to a new solution within an
organizational unit or even with those of other e-businesses. This can be
achieved by dynamically linking internal applications to new partners and
suppliers, to offer their services to complement internal services.
Example
In this section, we present a sample scenario that illustrates the use of Web
services in a service-oriented environment. This example is partially
over-simplified and thus does not claim completeness or overall soundness.
However, it gives an understanding of how to use this technology beyond
simplistic scenarios such as stock quote examples. The scenario covers the
buying process in a business-to-consumer (B2C) environment, say in the
automotive industry.
The following sub-processes are defined:
1. Selection of a car model
2. Purchase
3. Financing
Figure 1-3 shows the different units that run these processes. Note that some
parts of the first two processes are run through units within the company’s
intranet, while the last process integrates units from different companies over the
Internet.
12
WebSphere Version 5.1 Web Services Handbook
Image
renderer
Intranet
Car configurator
Storing
component
1
Dealer
locator
B2C Web
Application
Client
Credit
history
checker
2
Production
system
3
Banking
system 1
...
Banking
system n
Figure 1-3 Components in a B2C scenario
Car selection sub-process (1)
The user enters the general B2C portal site of the car manufacturer of choice.
After having surfed on the public part of the site, he enters the car configuration
area, where he can model a car with the features he is interested in (model,
engine, color, equipment, and so on).
As Figure 1-3 shows, in this scenario the B2C Web application makes use of a
car configurator legacy system, which is wrapped by a Web service. The B2C
Web application passes control to that application. The car configurator in turn
uses another system, which is responsible for an online generation of images
that show the car in the selected configuration. After every user’s change in the
Chapter 1. Web services introduction
13
configuration, the car configurator requests a new image from the renderer. This
transaction is again performed with Web services.
Once the user has finished the configuration process, he can store the particular
configuration on the server side. Therefore, he first has to register for a login
account and then actually log in (which we do not cover here in depth). In the
scenario, the component for storing the configuration is a system that serves
storing facilities to many other components. It offers Web services for storing,
retrieving, and deleting configurations of any kind (not restricted to a modeled
car). The B2C Web application contacts the storing component and makes use
of the store Web service.
The user might leave the portal and return another day. Then he can load the
configured car (the B2C Web application retrieves the data from the storing
module via the Web service), modify it, and store it again.
Purchase sub-process (2)
After having finished the configuration process, the authenticated user decides to
buy the configured car and initiates the purchase process. The B2C Web
application asks the user to enter additional data, for instance delivery details, or
the dealer he wishes to use as a contact person.
In our scenario, a list of all available dealers may be stored in a remote
catalogue, which can be accessed over a Web service. The B2C Web application
transmits the user’s preferences as parameters and in return gets contact data
for a selected dealer.
Once all relevant data is inserted, the B2C Web application initiates the
production of the ordered car. The responsible system is also accessible through
a Web service.
Financing sub-process (3)
The user decides to find a financing model for his purchase. Let us assume for
our scenario that the car manufacturer does not provide any financing service.
The B2C Web application collects relevant data from the user, such as the
budget he wishes to spend per month. Furthermore, the B2C Web application
contacts an external credit history check institution via a Web service in order to
clarify the user’s credibility.
After having collected these pieces of data, the B2C Web application contacts
several banking systems through Web services and initiates an auction for this
case. All connected banking systems may release a bid. The B2C Web
application compares the offers, selects the best choice, grants the bid and
14
WebSphere Version 5.1 Web Services Handbook
submits the relevant customer data to the appropriate banking system. All other
banking systems are sent a rejection.
Discussion
This scenario is well suited to be implemented using Web services technology:
All components (except for the central B2C Web application) already existed
beforehand and were easily wrapped to work as Web services.
The components deliver small, well-defined and independent pieces of
functionality, which could be used for many business processes, because the
components do not require any status data of a certain process as input.
Some of the integrated components run on the car manufacturer’s intranet,
while others are run by different enterprises and are accessed over the
Internet.
Web services interoperability (WS-I)
WS-I is an organization designed to promote Web service interoperability across
platforms, operating systems, and programming languages. For more information
on WS-I, refer to their Web site:
http://www.ws-i.org/
This site contains resources such as an overview of Web services
interoperability, usage scenarios, and specifications.
Here is a quote from Rod Smith, Vice President of Emerging Internet Technology,
Software Group, IBM Corporation:
“IBM is delighted with the broad industry support for WS-I's first profile, WS-I
Basic Profile 1.0. Interoperability is a "must have" characteristic/attribute for
the viability and growth of our industry and to the emerging technical
infrastructures of grid and IBM's e-business on demand computing initiatives.
With the availability of the Basic Profile 1.0, IBM continues its commitment to
the development of open standards for Web services and their incorporation
into products, thus ensuring the interoperability and viability of solutions for
our customers.”
Here an extract from the WS-I Web site:
WS-I is an open industry organization chartered to promote Web services
interoperability across platforms, operating systems, and programming
languages. The organization works across the industry and standards
organizations to respond to customer needs by providing guidance, best
practices, and resources for developing Web services solutions.
Chapter 1. Web services introduction
15
WS-I was formed specifically for the creation, promotion, or support of
Generic Protocols for Interoperable exchange of messages between services.
Generic Protocols are protocols that are independent of any specific action
indicated by the message beyond actions necessary for the secure, reliable,
or efficient delivery of messages; “Interoperable” means suitable for and
capable of being implemented in a neutral manner on multiple operating
systems and in multiple programming languages.
The WS-I Basic Profile is an outline of requirements to which WSDL and Web
service protocol (SOAP/HTTP) traffic must comply in order to claim WS-I
conformance. The Web services WS-I validation tools currently support WS-I
Basic Profile 1.0. To view the specifications, refer to the WS-I Web site, under
Resources select Documentation.
Depending on the type of Web service being created, you may or may not want
your Web service to comply with the WS-I Basic Profile. WebSphere Studio
Application Developer allows you to set your level of compliance. The default
level of compliance is to generate a warning if a non-complaint Web service
option is selected.
See “Web services interoperability” on page 282 for support of WS-I in
Application Developer Version 5.1.1.
Summary
In this chapter we have presented the general business and programming
concepts that Web services are built on. A service-oriented architecture provides
a loose coupling between components that provide and use services. As
discussed, this flexible approach gives a wide range of advantages in business
scenarios, where reusable components are employed for different business
processes.
We have also sketched the core building blocks to run Web services. These
building blocks are presented in more detail in the next chapters.
Finally, we have outlined a scenario that is well suited to the use of Web services
in order to give a taste of how new business processes could be modeled using
the new technology.
The scenario showed that new business processes can be implemented with
components that were originally not necessarily intended for such processes. For
instance, the interfaces of the banking systems provide the functionality to give
financing offers. The new application uses these services to run an auction on
top.
16
WebSphere Version 5.1 Web Services Handbook
The next three chapters introduce the main building blocks for Web services in
more detail: SOAP, WSDL, and UDDI. The remaining chapters of Part 1 describe
other concepts, which build on the base.
More information
General introductions to Web services can be found at:
http://www.ibm.com/developerworks/webservices/
The following Web site provides a collection of IBM resources on the topic at
hand. For example, you can find an introduction to the SOA in a white paper titled
Web Services Conceptual Architecture (WSCA 1.0):
http://www.ibm.com/software/solutions/webservices/resources.html
More information is provided in the article Energize e-business with Web
services from the IBM WebSphere software platform at:
http://www.ibm.com/developerworks/library/ibm-lunar.html
Chapter 1. Web services introduction
17
18
WebSphere Version 5.1 Web Services Handbook
2
Chapter 2.
Introduction to SOAP
In this chapter we introduce SOAP, the specification covering the exchange of
XML-based messages between the three main actors in the service-oriented
architecture (SOA).
We cover the SOAP 1.1 specification in detail and present a couple of examples
of SOAP messages. We cover the details of the SOAP architecture. We explore
SOAP implementations such as Apache SOAP 2.3 and its successor, Apache
eXtensible Interaction System (Axis).
We also briefly touch upon other SOAP implementations, such as the Microsoft
SOAP Toolkit. Finally, we outline recent developments and future trends in this
field.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
19
Overview
Simple Object Access Protocol (SOAP) is a specification for the exchange of
structured information in a decentralized, distributed environment. As such, it
represents the main way of communication between the three main actors in
SOA: The service provider, service requestor and service broker. The main goal
of its design is to be simple and extensible. Originally proposed by Microsoft, it is
now submitted to W3C as the basis of the XML Protocol Working Group by
several companies including IBM and Lotus®. At the time of writing of this book,
the current standard version is 1.1 with 1.2 being in preparation. You can get
more details at:
http://www.w3.org/TR/SOAP
SOAP is an XML-based protocol that consists of three parts: An envelope that
defines a framework for describing message content and process instructions, a
set of encoding rules for expressing instances of application-defined data types,
and a convention for representing remote procedure calls and responses.
SOAP is, in principle, transport protocol-independent and can therefore
potentially be used in combination with a variety of protocols. In this book, we
describe how to use SOAP in combination with HTTP, HTTP extension
framework, and JMS. SOAP is also operating system independent and not tied to
any programming language or component technology.
Because SOAP deals with objects serialized to plain text and not with stringified
remote object references (interoperable object references, IORs, as defined in
CORBA), distributed garbage collection has no meaning and is not covered. For
the same reason, SOAP clients do not hold any stateful references to remote
objects, and without this, activation in a Java RMI way is also impossible.
Due to these characteristics, it does not matter what technology is used to
implement the client, as long as the client can issue XML messages. Similarly,
the service can be implemented in any language, as long as it can process XML
messages. Also, both server and client sides can reside on any suitable platform.
In this chapter we discuss the W3C SOAP 1.1 specification and the SOAP 2.3
implementation from Apache. We also discuss Apache Axis, the SOAP 2.3
successor, and the IBM WebSphere SOAP Engine. There are other Java
implementations as well as non-Java implementations, such as Microsoft SOAP
Toolkit, which we only briefly touch upon.
20
WebSphere Version 5.1 Web Services Handbook
The three pillars of SOAP
This section discusses the key aspects of XML-based message exchange.
Overall message format - Envelope with header and body
A SOAP message is an envelope containing zero or more headers and exactly
one body.
The envelope is the top element of the XML document, providing a container
for control information, the addressee of a message, and the message itself.
Headers contain control information, such as quality of service attributes.
The body contains the message identification and its parameters.
Both the headers and the body are child elements of the envelope.
Envelope
Header
[0..n]
Body
[1]
<Envelope>
<Header>
<actor>http://...org/soap/actor/next</actor>
<qos mustUnderstand="1">log</qos>
</Header>
<Body>
<getMessage ns1="urn:NextMessage" ...>
<UserID type="string">JDoe</UserID>
<Password type="string">0JDOE0</Password>
</getMessage>
</Body>
</Envelope>
Figure 2-1 Example of a conceptualized SOAP message
Figure 2-1 shows a conceptualized SOAP request message based on a scenario
of a personal text message recorder, similar to a recording phone answering
machine, where the user can listen to the recorded messages:
The header tells who and how to deal with the message. The actor next (or
omitted actor) is the default actor and declares the receiver as the server who
has to do what the body says. Furthermore, the server must understand the
application-defined quality of service log (and implement and execute it, as
the name implies: Log the service request).
The body tells what has do be done: Get and return the next message for Jon
Doe—in detail—invoke the getMessage method on the service object instance
NextMessage passing the two string arguments UserID and Password with the
values JDoe and 0JDOE0.
Chapter 2. Introduction to SOAP
21
More on envelope, header, and body is coverd in the section “SOAP elements”
on page 24.
Encoding rules
Encoding rules (of course included in a real SOAP message) define a
serialization mechanism that can be used to exchange instances of
application-defined data types.
SOAP defines a programming language-independent data type schema based
on the XML schema descriptor (XSD), plus encoding rules for all data types
defined according to this model.
RPC representation
The remote procedure call (RPC) representation is a convention suited to
represent remote procedure calls and the related response messages. As
arguments in remote method invocation, we normally use relatively simple data
structures, although, with conventions such as XML Literal, it is possible to
transfer more complex data. This convention, however, is only covered by SOAP
implementations and standards beyond SOAP, such as the JSR-101 Java APIs
for XML based RPC—or briefly, JAX-RPC—and is not a part of the SOAP
standard. For more information on JAX-RPC see Chapter 4, “JAX-RPC (JSR
101)” on page 67.
The usage of this RPC representation in a plain SOAP context is optional. If the
convention is not used, the communication style is purely message oriented.
When working with the message-oriented style, also called document-oriented
communication, almost any XML document can be exchanged.
Figure 2-2 shows an example of a SOAP request message embedded in an
HTTP request:
The standard HTTP header contains the URL of the SOAP server, which in
this case is /www.messages.com/webapp/servlet/rpcrouter. Relative to this
URL, the Web service is identified by urn:NextMessage.
After the header comes a SOAP envelope that contains the message to be
transmitted. Here the method invocation is the SOAP RPC representation of a
call to the method getMessage(UserID, Password) of a Web service called
urn:Nextmessage residing on the SOAP server.
http://schemas.xmlsoap.org/soap/encoding/ specifies the encoding that is
used to convert the parameter values from the programming language on
both the client side and the server side to XML and vice versa.
22
WebSphere Version 5.1 Web Services Handbook
POST /webapp/servlet/rpcrouter HTTP/1.1
Host: www.messages.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: ""
<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-2 A SOAP message embedded in an HTTP request
Figure 2-3 shows a (possible) response to the above request:
First comes the standard HTTP header.
After the header comes a SOAP envelope that contains the message to be
transmitted. In this message, the service returned the requested message.
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
<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/">
<return xsi:type="xsd:string">Call mom!</return>
</ns1:getMessage>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Figure 2-3 A SOAP message embedded in an HTTP response
SOAP messages are fundamentally one-way transmissions from a sender to a
receiver, but, as illustrated above, SOAP messages are often combined to
implement patterns such as request/response.
Chapter 2. Introduction to SOAP
23
SOAP elements
This section discusses the major elements of a SOAP message.
Namespaces
SOAP defines the two XML namespaces shown in Table 2-1.
Table 2-1 SOAP namespaces
Prefix
Namespace URI
Explanation
SOAP-ENV
http://schemas.xmlsoap.org/soap/envelope/
SOAP envelope
SOAP-ENC
http://schemas.xmlsoap.org/soap/encoding/
SOAP serialization
URN
A unified resource name (URN) uniquely identifies the service to clients. It must
be unique among all services deployed in a single SOAP server, which is
identified by a certain network address. A URN is encoded as a universal
resource identifier (URI). We commonly use the format urn:UniqueServiceID.
urn:NextMessage is the URN of our message exchange Web service.
All other addressing information is transport dependent. When using HTTP as
the transport, for example, the URL of the HTTP request points to the SOAP
server instance on the destination host. For the message exchange service, the
URL could be http://www.messages.com/webapp/servlet/rpcrouter.
This namespace URI identifying the method name in SOAP is very similar to the
interface ID scoping a method name in distributed computing environments such
as DCOM or CORBA, or the name and the associated remote interface of an
Enterprise JavaBean (EJB).
SOAP envelope
The envelope is the top element of the XML document representing the message
with the following structure:
<SOAP-ENV:Envelope .... >
<SOAP-ENV:Header name="nmtoken">
<SOAP-ENV:HeaderEntry.... />
</SOAP-ENV:Header>
<SOAP-ENV:Body name="nmtoken">
[message payload]
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
24
WebSphere Version 5.1 Web Services Handbook
In general, a SOAP message is a (possibly empty) set of headers plus one body.
The SOAP envelope also defines the namespace for structuring messages. The
entire SOAP message (headers and body) is wrapped in this envelope.
Note that the message body uses a service-specific namespace,
urn:NextMessage, in our examples (Figure 2-2 on page 23 and Figure 2-3 on
page 23). This namespace is different from SOAP-ENV, the namespace used by
the envelope, which is defined by the SOAP specification. Therefore, the
application can use its own domain-specific vocabulary when creating message
bodies.
Headers
Headers are a generic and flexible mechanism for extending a SOAP message in
a decentralized and modular way without prior agreement between the parties
involved. They allow control information to pass to the receiving SOAP server
and provide extensibility for message structures as well.
Headers are optional elements in the envelope. If present, the element must be
the first immediate child element of a SOAP envelope element. All immediate
child elements of the header element are called header entries.
There is a predefined header attribute called SOAP-ENV:mustUnderstand. The
value of the mustUnderstand attribute is either “1” or “0”. The absence of the
SOAP mustUnderstand attribute is semantically equivalent to the value “0”.
If it is present in a header element and set to “1”, the service provider must
implement the semantics defined by the element:
<thens:qos xmlns:thens="someURI" SOAP-ENV:mustUnderstand="1">
3
</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) 3 (whatever
qos=3 stands for in the actual invocation and servicing context).
A SOAP intermediary is an application that is capable of both receiving and
forwarding SOAP messages on their way to the final destination. In realistic
situations, not all parts of a SOAP message may be intended for the ultimate
destination of the SOAP message, but, instead, may be intended for one or more
of the intermediaries on the message path. Therefore, a second predefined
header attribute, SOAP-ENV:actor, is used to identify the recipient of the header
information. The value of the SOAP actor attribute is the URI of the mediator,
which is also the final destination of the particular header element (the mediator
does not forward the header).
Chapter 2. Introduction to SOAP
25
If the actor is omitted or set to the predefined default value, then the header is for
the actual recipient and the actual recipient is also the final destination of the
message (body). The predefine value is:
http://schemas.xmlsoap.org/soap/actor/next
Headers can also carry authentication data, digital signatures, encryption
information, and transactional settings.
Headers can also carry client- or project-specific controls and extensions to the
protocol; the definition of headers is not just up to standard bodies.
Note: The header must not include service instructions (that would be used by
the service implementation).
Body
The SOAP body element provides a mechanism for exchanging information
intended for the ultimate recipient of the message. The body element is encoded
as an immediate child element of the SOAP envelope element. If a header
element is present, then the body element must immediately follow the header
element. Otherwise it must be the first immediate child element of the envelope
element.
All immediate child elements of the body element are called body entries and
each body entry is encoded as an independent element within the SOAP body
element. In the most simple case, the body of a basic SOAP message
comprises:
A message name.
A reference to a service instance. In Apache SOAP, a service instance is
identified by its URN. This reference is encoded as the namespace attribute.
One or more parameters carrying values and optional type references.
Typical uses of the body element include invoking RPC calls with appropriate
parameters, returning results, and error reporting. Fault elements are used in
communicating error situations. The messages can contain almost any XML
construct except document type definitions (DTDs) and processing instructions.
26
WebSphere Version 5.1 Web Services Handbook
Error handling
SOAP itself predefines one body element, which is the fault element used for
reporting errors. If present, the fault element must appear as a body entry and
must not appear more than once within a body element. The fields of the fault
element are defined as follows:
Faultcode—is a code that indicates the type of the fault. SOAP defines a
small set of SOAP fault codes covering basic SOAP faults:
– SOAP-ENV:Client, indicating incorrectly formatted messages
– SOAP-ENV:Server, for delivery problems
– SOAP-ENV:VersionMismatch, which can report any invalid namespaces for
envelope element
– SOAP-ENV:MustUnderstand, for errors regarding the processing of header
content
Faultstring—is a human-readable description of the fault. It must be present
in a fault element.
Faultactor—is an optional field that indicates the URI of the source of the
fault. It is similar to the SOAP actor attribute, but instead of indicating the
destination of the header entry, it indicates the source of the fault. The value
of the faultactor attribute is a URI identifying the source that caused the
error. Applications that do not act as the ultimate destination of the SOAP
message must include the faultactor element in a SOAP fault element.
Detail—is an application-specific field that contains detailed information
about the fault. It must not be used to carry information about errors belonging
to header entries. Therefore, the absence of the detail element in the fault
element indicates that the fault is not related to processing of the body
element (the actual message).
For example, a SOAP-ENV:Server fault message that is returned if the service
implementation throws a SOAPException. The exception text is transmitted in the
Faultstring field.
Chapter 2. Introduction to SOAP
27
Advanced topics
In the following section, we discuss more advanced SOAP concepts, such as the
different communication styles, the SOAP data model, the available encodings,
and the corresponding type mappings. Although these concepts are rarely a
concern in simple SOAP architectures, you will very quickly find them useful once
you try to implement a nontrivial Web service.
Communication styles
SOAP supports two different communication styles:
Document
Also known as message-oriented style: This style provides a
lower layer of abstraction, and requires more programming work.
The in parameter is any XML document; the response can be
anything (or nothing). This is a very flexible communication style
that provides the best interoperability.
RPC
The remote procedure call is a synchronous invocation of
operation returning a result, conceptually similar to other RPCs.
This style is exploited by many Web service tools and featured in
many tutorials.
Messages, parameters, and invocation APIs look different for RPC and
document styles. The decision about which style to use is made at design time; a
different client API and server-side router servlet are used.
SOAP enables applications to encapsulate and exchange RPC calls using the
extensibility and flexibility of XML. To make a method call, the following
information is needed:
The URI of the target object
A method name
An optional method signature
The parameters of the method
Optional header data
Using SOAP for RPC does not imply any specific SOAP protocol binding; using
SOAP for RPC is not limited to the HTTP protocol binding. When using HTTP as
the protocol binding, however, an RPC call maps naturally to an HTTP request
and an RPC response maps to an HTTP response.
Figure 2-4 shows the interactions between the client and server as well as the
server-side processing of a service invocation in RPC communication.
28
WebSphere Version 5.1 Web Services Handbook
SOAP Client
SOAP Server
Call
- target object
- encoding style
- method name
- parameters
- transport
- invoke()
2
Deployment
Descriptors
ServiceManager
5
RPC Router Servlet
1
SOAP
Message
3
PluggableProvider
4
1. Send SOAP RPC Request
2. Lookup deployment descriptor
3. Pass request to provider
4. Invoke service
5. Return response
SOAP Service
Java Class
Script
EJB
COM Application
other
Figure 2-4 SOAP client and server interaction
Web service invocation using RPC involves the following steps:
1. A SOAP client generates a SOAP RPC request document and sends it to a
RPC router.
2. The router contacts the service manager to obtain a deployment descriptor.
3. Based on routing information form the deployment descriptor, the router
forwards the request to a service provider.
4. The service provider invokes the requested service and returns a result to the
router.
5. The router sends the service result message to the client.
It is worth noting that this is a very simple scenario. More sophisticated scenarios
would use additional steps, such as the ones related to security policy.
Chapter 2. Introduction to SOAP
29
Data model
One of the promises of SOAP is interoperability between different programming
languages. That is the purpose of the SOAP data model, which provides a
language-independent abstraction for common programming language types. It
consists of:
Simple XSD types
Basic data types found in most programming languages
such as int, String, Date, and so forth.
Compound types
There are two kinds of compound types, structs and
arrays:
Structs
Named aggregated types. Each element has a unique
name, its accessor. An accessor is an XML tag. Structs are
conceptually similar to records in languages such as
Pascal or methodless classes with public data members in
object-based programming languages.
Arrays
Elements in an array are identified by position, not by
name. This is the same concept found in languages such
as C and Java. SOAP also supports partially transmitted
and sparse arrays. Array values may be structs or other
compound values. Also, nested arrays (which means
arrays of arrays) are allowed.
All elements and identifiers comprising the SOAP data model are defined in the
namespace SOAP-ENC. It is worth noting that the SOAP standard only defines the
rules of how data types can be constructed; a project-specific XML schema has
to define the actual data types.
A SOAP request message such as getMessage in Figure 2-2 on page 23 is
modeled as a struct containing an accessor for each in and in/out parameter. It
is shown in Figure 2-5.
<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>
Figure 2-5 A SOAP request message
In the example in Figure 2-5, the accessors are UserID and Password. The
accessor names correspond to the names of the parameters, and the message
types to the programming language data types (xsd:string and
java.lang.String). The parameters must appear in the same order as in the
method signature. The prefixes xsd and xsi reference the namespaces
30
WebSphere Version 5.1 Web Services Handbook
http://www.w3.org/2001/XMLSchema and
http://www.w3.org/2001/XMLSchema-instance, respectively.
In the example shown in Figure 2-6, the argument is an array whose values are
structs.
<ns1:getSubscribers xmlns:ns1="urn:SubscriberList"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENC:Array SOAP-ENC:arrayType="xxx:Subscribers[2]">
<Subscribers>
<UserID xsi:type="xsd:string">JDoe</UserID>
<Password xsi:type="xsd:string">0JDOE0</Password>
</Subscribers>
<Subscribers>
<UserID xsi:type="xsd:string">MDoe</UserID>
<Password xsi:type="xsd:string">0JMDOE0</Password>
</Subscribers>
</SOAP-ENC:Array>
</ns1:getSubscribers>
Figure 2-6 A SOAP request message with an array of structs
The SOAP data model makes self-describing messages possible. No external
schema is needed to understand an XML element such as:
<UserID xsi:type="xsd:string">JDoe</UserID>
SOAP provides a preferred encoding for all data types defined according to this
model. We cover this subject in the next section.
Note: The use of a data model and associated encoding is optional.
Encodings
In distributed computing environments, encodings define how data values
defined in the application can be translated to and from a protocol format. We
refer to these translation steps as serialization and deserialization, or,
synonymously, marshalling and unmarshalling (even Apache SOAP uses both
pairs of terms).
When implementing a Web service, we have to choose one of the tools and
programming or scripting languages that support the Web services model, for
example Java. On the other hand, the protocol format for Web services is XML,
which is independent of the programming language. Thus, SOAP encodings tell
the SOAP runtime environment how to translate from data structures constructed
in a specific programming language into SOAP XML, and vice versa.
Chapter 2. Introduction to SOAP
31
The following encodings are defined:
SOAP encoding
The SOAP encoding enables marshalling/unmarshalling of
values of data types from the SOAP data model. This
encoding is defined in the SOAP 1.1 standard.
Literal
The literal encoding is a simple XML message that does not
carry encoding information. Usually an XML Schema
describes the format and data types of the XML message.
Literal XML
The literal XML encoding enables direct conversion of
existing XML DOM tree elements into SOAP message
content and vice versa. This encoding style is not defined by
the SOAP standard, but is in the Apache SOAP 2.3
implementation.
XMI
XML metadata interchange (XMI) is defined by the Apache
SOAP implementation. We do not use this encoding in this
document.
The encoding to be used by the SOAP runtime can be specified at deploy time or
at runtime. If it is specified at deploy time, it appears in the WSDL specification of
the Web service. Tools can then analyze this specification and configure the
SOAP runtime to use the desired encoding.
At runtime, the SOAP client API allows the specification of the encoding for the
entire message and for each of its parameters. On the server side, the encoding
style is specified in the deployment descriptor of the Web service, an XML
document that provides information to the SOAP runtime about the services that
should be made available to clients. It contains information such as the URN for
the service and method and class details (in case the service is implemented in
Java) or the name of a script. The settings on the client and the server side have
to match.
Style and encoding
The two styles (RPC, document) and two encodings (encoded, literal) can be
freely intermixed, but only three of the four combinations are generally used:
Document/literal—Provides the best interoperability between Java and
non-Java implementations.
RPC/literal—Good choice between Java implementations.
RPC/encoded—Early Java implementations (WebSphere Version 4 and 5.0)
supported this combination, but it does not provide interoperability with
non-Java.
Document/encoded—Not used in practice.
32
WebSphere Version 5.1 Web Services Handbook
Mappings
A mapping defines an association between a qualified XML element name, a
Java class name, and one of the encodings as introduced above. Hence,
mappings are not implementation language-independent.
A mapping specifies how, under the given encoding, an incoming XML element
with a fully qualified name is to be converted to a Java class, and vice versa. We
refer to the two mapping directions as XML to Java and Java to XML, respectively.
Any SOAP runtime environment holds a table of such mapping entries, the
SOAPMappingRegistry. Standard Java-related mappings are shown in Table 2-2.
Table 2-2 SOAP Java-related mappings
Java
SOAP
serializer/deserializer
String
xsd:string
<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
Chapter 2. Introduction to SOAP
33
If a data type is supposed to be used under a certain encoding, exactly one
mapping must exist for it in this registry. Most standard Java types as well as
JavaBeans are supported by default. Non-standard (custom) data types require
the introduction of custom mappings on the client and on the server side.
Implementations
So far we have discussed only SOAP specification. To build a Web
services-based solution, the standard should be implemented in one of the
programming languages. In the following sections, we discuss some of the most
popular SOAP implementations.
SOAP implementation general architecture
Figure 2-7 contains a high-level component model showing the conceptual
architecture of both the service provider (SOAP server) and the service
requestor (SOAP client).
Service Requestor
SOAP RPC Layer
Client Proxy
Mapping
Registry
Service Provider
SOAP Server
Pluggable
Providers
Service
Manager
Call
Parameter
SOAP Message Layer
SOAP Transport Layer
Mapping
Registry
RPC
Router
Servlet
Transport Layer
(HTTP, HTTPS, SMTP, JMS, MQ, other)
Figure 2-7 High-level SOAP component model
34
WebSphere Version 5.1 Web Services Handbook
Deployment
Descriptor
Message
Router
Servlet
The client can invoke SOAP messages through the RPC layer (RPC style) or
directly against the message layer (document style). Various transport protocols
such as HTTP, SMTP, and others connect the requestor and the provider.
On the provider side, RPC and message router servlets receive the incoming
requests. Providers route them to the Java service implementation. The server is
configured through deployment descriptor files.
Both on the requestor and on the provider side, there are mapping registries
providing access to serializer/deserializer classes implementing an encoding
scheme.
IBM SOAP4J
IBM’s SOAP for Java implementation became the basis of the Apache SOAP
project.
Apache SOAP 2.3 implementation
The basis of the Apache SOAP implementation is IBM SOAP for Java, the
Java-based SOAP implementation that was submitted to the open-source
community.
Let us investigate the details of the SOAP server and then the SOAP client API.
SOAP server
Apache SOAP 2.3, included with other implementations in WebSphere
Application Server Version 5 and Application Developer Version 5, provides an
implementation of a SOAP server for deploying and invoking Web services.
Figure 2-8 gives an overview of the Apache SOAP server components.
For now, the important elements in this architecture are the rpcrouter and
messagerouter servlets, the deployment descriptor (explained below), and the
type mapping registry. These components implement the SOAP concepts
introduced so far.
The pluggable providers link a Web service and its implementation. The service
implementation is your Java code actually executing the invoked Web service.
We do not go into detail about the configuration manager and the administrative
GUI here. Refer to the Apache SOAP user documentation for more information.
Chapter 2. Introduction to SOAP
35
SOAP4J ==>
Open Source
Transport
Listener
(rpcrouter and
messagerouter
servlets for HTTP)
SOAP Admin
GUI
(HTML
based)
Type
Mapping
Registry
SOAP
Server
Engine
Pluggable
Configuration
Manager
DeployedServices.ds
Pluggable
Providers
(JavaBean, EJB,
BSF, COM, custom)
Service
Implementation
any type of
programming
artifact
Web Service
Deployment
Descriptor
Figure 2-8 Components of Apache SOAP server implementation
Server deployment
Deployment stands for configuring a Web service implementation so that it
becomes available within a hosting SOAP server. The following steps have to be
performed when a Web service is deployed to the SOAP server:
Create a code artifact that is supported by one of the Apache SOAP
providers.
Ensure that parameters to the method/function are serializable by SOAP, and
exist within the SOAP type mapping registry. Otherwise, develop and register
custom mappings.
Create an entry in the Apache SOAP deployment descriptor for the service.
A Web service implementation Java class implementing the first step for the
Exchange Web service is shown in Figure 2-9.
36
WebSphere Version 5.1 Web Services Handbook
public class NextMessage{
public String getMessage(String UserID, String Password) {
System.out.println("getMessage(" + UserID + ", " + Password + ")");
return "Call mom!"; // fixed value for now
}
}
Figure 2-9 Java class implementing the Web service
The corresponding deployment descriptor, which is read by the SOAP server at
startup time, is shown in Figure 2-10.
<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-10 Web service deployment descriptor (SOAP 2.3)
This deployment descriptor defines the URN, urn:NextMessage, and the name of
the Java implementation class, NextMessage. There is one accessible method,
getMessage.
The Web service scope is request. This scope attribute can be set to application,
request, or session:
If the scope is application, a singleton instance of the service is created at
server startup time (like a servlet).
A service with request scope is instantiated whenever a message for it is
received.
If the scope is session, the lifetime of the service instance is bound to the
duration of the underlying transport session (for example, the HttpSession in
case HTTP is the transport protocol).
The actual deployment step can either be performed using the administrative
GUI that comes with Apache SOAP or programmatically.
Chapter 2. Introduction to SOAP
37
SOAP client API
There are two key abstractions in the SOAP client API, which is defined in the
org.apache.soap package and its sub-packages:
Call
Contains the URN, the SOAP address of the router
servlet on the SOAP servers, as well as the name of
the method to be called. A call object contains
Parameter instances as data members.
Parameter
Contains the parameter value, type, and encoding
style.
As a SOAP developer, you might have to use the following classes as well:
QName
Qualified name: Combination of an XML namespace
and a local name. QName instances are used to identify
XML data types and other elements in an XML
document.
SOAPMappingRegistry
Maps types and encoding styles to the available
serializer and deserializer classes.
SOAPHttpTransport
Provides access to the HTTP transport layer. For
example, this class can be used to modify proxy and
authentication settings.
Let us take a look at an example (Figure 2-11). The message that travels if this
code is executed is the same message we inspected in Figure 2-2 on page 23.
You have to perform the following steps when developing a SOAP client:
Obtain the interface description of the SOAP service, so that you know what
the signatures of the methods that you want to invoke are. Either contact the
service provider directly, or use UDDI to do so (note that this step is not
shown in the example).
Make sure that there are serializers registered for all parameters that you will
be sending, and deserializers for all information that you will be receiving (this
holds true for the example). Otherwise, develop and register the custom
mapping.
Create and initialize the org.apache.soap.rpc.Call object.
– Set the target URI in the Call object using the setTargetObjectURI
method.
– Set the method name that you wish to invoke into the Call object using the
setMethodName method.
– Create any Parameter objects necessary for the RPC call, and add them to
the Call object using the setParams method.
38
WebSphere Version 5.1 Web Services Handbook
public class MySoapClient {
public static void main(String[] args){
Call call = new Call();
call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
call.setTargetObjectURI ("urn:NextMessage");
call.setMethodName ("getMessage");
Vector params = new Vector();
Parameter userIDParam = new Parameter(
"UserID", String.class, "JDoe", Constants.NS_URI_SOAP_ENC);
params.addElement(userIDParam);
Parameter passwordParam = new Parameter(
"Password", String.class, "0JDOE0", Constants.NS_URI_SOAP_ENC);
params.addElement(passwordParam);
call.setParams(params);
Response resp = null;
URL url = new URL ("http://www.messages.com/soap/servlet/rpcrouter");
resp = call.invoke (url, "urn:NextMessage"); // url, soapActionURI
// soapActionURI is URN for Apache, "" for most other servers
if (resp.generatedFault()) {
Fault fault=resp.getFault();
System.out.println(" Fault code: " + fault.getFaultCode());
System.out.println(" Fault string: " + fault.getFaultString());
} else {
Parameter result=resp.getReturnValue();
Object o = result.getValue();
System.out.println("Result: " + o);
}
}
}
Figure 2-11 SOAP 2.3 client
Execute the Call object's invoke method and capture the Response object
that is returned from invoke.
Check the Response object to see if a fault was generated using the
generatedFault method.
If a fault was returned, retrieve it using the getFault method. Otherwise,
extract any result or returned parameters using the getReturnValue and
getParams methods, respectively.
The SOAP client API is a string-oriented, weakly typed interface. This is due to
the fact that it is a fixed API that is unaware of the signatures of the messages
that are exchanged over it.
Chapter 2. Introduction to SOAP
39
Usually programmers do not have to work with this rather cumbersome API
directly because there are tools wrapping it. For example, code generated from
WSDL-aware tools can provide a more type-oriented, easier-to-code interface.
Apache SOAP implementation also represents the basis of another open-source
project, Axis, which we cover in the next section.
Axis
The Apache eXtensible Interaction System (Axis) is basically a SOAP engine. It
represents a framework for constructing SOAP processors such as clients,
servers, or gateways. Axis is an Apache open-source project and is written in
Java. Axis Version 1.1 is available, and Version 1.2 is in alpha.
Besides being a SOAP engine, Axis also includes the following features:
A server that plugs into servlet engines such as WebSphere Application
Server or Apache Tomcat
Extensive support for the Web service description language (WSDL)
Tools that generate Java classes from WSDL and vice versa (WSDL2Java and
Java2WSDL)
A tool for monitoring TCP/IP packets
TCP/IP monitoring is a very efficient tool for Web services’ debugging and
troubleshooting.
Axis represents the third generation of Apache SOAP, which began at IBM as
SOAP4J, and is often referred to as Apache SOAP 3.x. However, it does not
share the code of the Apache SOAP 2.x project, but has been redesigned from
scratch. It is based on the idea of configurable chains of message handlers,
which would implement small bits of functionality in a flexible manner.
Axis uses the event-based simple API for XML (SAX) instead of DOM parsing to
perform significantly better than earlier versions of Apache SOAP. The
extendable Axis architecture enables the developer to insert extensions into the
engine.
Axis defines a set of published interfaces that change relatively slowly compared
to the rest of Axis and therefore provide a higher level of stability from the
developer’s point of view.
The core of the Axis SOAP engine is completely transport-independent.
Therefore it enables SOAP message exchange using different communication
channels such as SMTP, FTP, or message-oriented middleware.
40
WebSphere Version 5.1 Web Services Handbook
Axis server architecture
The basic architecture of Axis in the server is shown in Figure 2-12.
Figure 2-12 Axis architecture
The large cylinders represent chains and the small cylinders represent handlers
within a chain. The main flow elements are:
The transport listener puts the protocol-specific data into a Message object and
the message data into a MessageContext object.
The Axis engine looks up the transport, which may contain a request chain, a
response chain, or both. Each chain is a sequence of handlers that are
invoked in turn.
After the transport chain, the global chain of handlers is invoked.
One of the handlers sets the serviceHandler field in the MessageContext and
the Axis engine invokes that service (an instance of SOAPService).
The service invokes its request chain (if present) and finally the provider,
which is the handler responsible for invoking the back-end logic.
The response is processed by the respective response handlers in the
service, global, and transport chains.
Axis client architecture
The client architecture is basically a mirror image of the server architecture:
The client application sends a message.
The Axis engine invokes the service chain, then the global chain, and then the
transport chain, where the final handler, the sender, sends the message to
the target.
Chapter 2. Introduction to SOAP
41
Axis subsystems
Axis comprises several subsystems working together with the aim of separating
responsibilities cleanly and making Axis modular. Subsystems that are properly
layered enable parts of a system to be used without having to use all the parts.
Figure 2-13 shows the layering of subsystems. The lower layers are independent
of the higher layers. The stacked boxes represent mutually independent,
although not necessary exclusive, alternatives. For example, the HTTP, SMTP,
and JMS transports are independent of each other but may be used together.
MDB
XML-RPC
deployment
descriptor
admin
SOAP
service
EJB
SMTP
JMS
Java
RPC
HTTP
provider
transport
encoding
message flow: handler, chain, message context, fault
AXIS ENGINE
message
model
WSDL
tools
Figure 2-13 Axis subsystems
Implementations
Axis 1.0 is implemented in the Emerging Technologies Toolkit (see “Emerging
Technologies Toolkit” on page 382).
WebSphere SOAP Engine
With Versions 5.0.2 and 5.1 of WebSphere Application Server comes a new
SOAP engine written by IBM. This engine, commonly referred to as WebSphere
SOAP Engine, is based on Axis principles but extended for performance and for
enterprise Web services.
We implement our sample application using WebSphere Application Server
Version 5.1, WebSphere Studio Application Developer Version 5.1.1, and
WebSphere SDK for Web Services Version 5.1, all of which come with the
WebSphere SOAP Engine.
Microsoft SOAP Toolkit
Microsoft has its own SOAP implementation in the Microsoft SOAP Toolkit. At the
time of writing of this book, the current version was V3.0. SOAP is also part of
.NET, Microsoft’s strategic platform for Web services.
42
WebSphere Version 5.1 Web Services Handbook
Other toolkits and server implementations
Currently, Web service engines and development tools pop up like mushrooms in
the market, for all kinds of platforms written in all kinds of languages for all kinds
of devices to get simple connectivity. In addition, manu SOAP and SOAP-RPC
user communities came into Web lives that you can join and participate in. Use,
for example, this link as a starting point for you own research:
http://www.google.com/search?q=soap+web+service+server
Outlook
At the time of writing this book, the SOAP 1.2 specification was in its final phase.
It introduces several changes to SOAP 1.1. It is beyond the scope of this book to
go into the details of differences between SOAP 1.1 and SOAP 1.2
specifications. Recent information on this subject is available at:
http://www.w3.org/TR/soap12-part0/#L4697
In October 2002, Apache Axis 1.0 was officially released; in June 2003 Axis 1.1
became available. Among other functions, Axis implements most of the SOAP
1.2 specification.
Summary
SOAP represents the information exchange mechanism between the three main
actors in the Web service model: A Web service provider, a Web service
requestor, and a Web service broker. It is based on XML documents and is
designed to be simple and extensible. It is also independent of actual Web
services implementation and therefore enables interoperability between Web
services implementations on different platforms. SOAP is defined by the W3C
SOAP specification. Its current version is V1.1, with V1.2 in preparation.
Currently, there are several SOAP implementations available:
The Apache SOAP 2.3 implementation is an open-source Java-based
implementation based on IBM SOAP4J implementation and is a part of
several commercial packages including WebSphere Application Server
Version 5 and WebSphere Application Developer Version 5.
The Apache Axis implementation is a follow-up project of the Apache SOAP
V2.X project and is often referred to as Apache SOAP 3.0 implementation.
IBM WebSphere Application Server Version 5.0.2 and 5.1 have their own
WebSphere SOAP Engine.
Chapter 2. Introduction to SOAP
43
Other companies (for example, Microsoft) have other SOAP implementations
based on different programming and scripting languages.
As a communication protocol, SOAP enables the publication and invocation of
Web services and represents the basic plumbing of a Web services
infrastructure. However, this is not enough for the successful implementation of
Web services:
A client has to obtain the information about the interface of a service, the
server URL, the URN, the methods, the types, and type mappings. This is
provided by WSDL.
A client has to learn about the existence of a service and its characteristics,
which is the function of UDDI.
A Web services inspection language (WSIL) document provides location
information to invoke Web services.
We introduce these three technologies in the chapters that follow.
More information
The SOAP specification can be downloaded from:
http://www.w3.org/TR/SOAP
http://www.w3.org/TR/soap12-part0/
http://www.w3.org/TR/soap12-part1/
For information on Apache SOAP, check out the user and API documentation as
well as the FAQ list at:
http://www.apache.org/soap
For information on Apache Axis, check out the user and API documentation as
well as the FAQ list at:
http://xml.apache.org/axis/index.html
IBM’s developerWorks™ Web site provides many articles on SOAP (enter SOAP
into the search engine):
http://www.ibm.com/developerworks
For example, here are two articles about SOAP type mapping:
http://www.ibm.com/developerworks/library/ws-soapmap1/
http://www.ibm.com/developerworks/library/ws-soapmap2/
44
WebSphere Version 5.1 Web Services Handbook
3
Chapter 3.
Introduction to WSDL
This chapter provides an introductory view to Web services description language
(WSDL) 1.1. WSDL specifies the characteristics of a Web service using an XML
format, describing what a Web service can do, where it resides, and how it is
invoked. WSDL is extensible to allow descriptions of different bindings,
regardless of what message formats or network protocols are used to
communicate.
WSDL 1.1 provides a notation serving these purposes. The WSDL specification
is a joint effort by Ariba, IBM, and Microsoft. It is not yet an official standard; at
the time of the writing of this book, its status was “submission acknowledged” by
the W3C.
The Web services description language specification 1.2 is a working draft at this
time. Therefore, we do not make any specific reference to WSDL 1.2, but we
include some information in “Outlook” on page 64. On the other hand, some of
the current implementations already implement selected features of the 1.2 draft
specification.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
45
Overview
WSDL allows a service provider to specify the following characteristics of a Web
service:
Name of the Web service and addressing information
Protocol and encoding style to be used when accessing the public operations
of the Web service
Type information: Operations, parameters, and data types comprising the
interface of the Web service, plus a name for this interface
A WSDL specification uses XML syntax; therefore, there is an XML schema for it.
A valid WSDL document consists of one or more files. If there is more than one
file, the use of the import element is required. This import element creates the
needed references to locate the different files of the WSDL document. We
recommend this split to maintain a clearer service definition based on level of
abstraction of the parts.
WSDL document
The WSDL document contains the following main elements:
Types
A container for data type definitions using some type system,
such as XML schema.
Message
An abstract, typed definition of the data being communicated. A
message can have one or more typed parts.
Port type
An abstract set of one or more operations supported by one or
more ports.
Operation
Binding
A concrete protocol and data format specification for a particular
port type. The binding information contains the protocol name,
the invocation style, a service ID, and the encoding for each
operation.
Service
A collection of related ports.
Port
46
An abstract description of an action supported by the
service that defines the input and output message as well
as optional fault message.
A single endpoint, which is defined as an aggregation of a
binding and a network address.
WebSphere Version 5.1 Web Services Handbook
Note that WSDL does not introduce a new type definition language. WSDL
recognizes the need for rich type systems for describing message formats, and
supports the XML schema specification (XSD).
WSDL 1.1 introduces specific binding extensions for various protocols and
message formats. There is a WSDL SOAP binding, which is capable of
describing SOAP over HTTP, a direct HTTP interface (any plain servlet, for
example), and a MIME binding. The language is extensible and allows the
definition of other binding mechanisms, such as Java and SOAP over Java
Messaging Service (JMS).
It is worth noting that WSDL does not define any mapping-to-programming
languages such as Java; rather the bindings deal with transport protocols. This is
a major difference from interface description languages, such as CORBA
interface definition language (IDL), which has language bindings.
WSDL document anatomy
Figure 3-1 on page 48 shows the elements comprising a WSDL document as
well as the various relationships between them.
The diagram should be read in the following way:
One WSDL document contains zero or more services. A service contains
zero or more port definitions (service endpoints), and a port definition
contains a specific protocol extension.
The same WSDL document contains zero or more bindings. A binding is
referenced by zero or more ports. The binding contains one protocol
extension, where the style and transport are defined, and zero or more
operations bindings. Each of these operation bindings is composed of one
protocol extension, where the action and style are defined, and one to three
messages bindings, where the encoding is defined.
The same WSDL document contains zero or more port types. A port type is
referenced by zero or more bindings. This port type contains zero or more
operations, which are referenced by zero or more operations bindings.
The same WSDL document contains zero or more messages. One to three
messages are required to define an operation. The message is composed of
zero or more parts.
The same WSDL document contains zero or more types. A type can be
referenced by zero or more parts.
The same WSDL document points to zero or more XML schemas. An XML
schema contains zero or more XSD types that define the different data types.
Chapter 3. Introduction to WSDL
47
The containment relationships shown in the diagram directly map to the XML
schema for WSDL.
WSDL
Document
1
n
Service
1
n
Port
1
1
Protocol
Extensions
n
1
1
1
n
Binding
1
1
n
Operation
Binding
n
n 1
1
n
Port Type
1
n
1
n
n
0..1
n
n
Type
1
1
1..3
Protocol
Extensions
Message
Binding
action
style
encoding
Part
Binding
n
Instance
XML
1
XML
Schema
1
Type
n
1
style/transport
Operation
n
1..3
Message
Protocol
Extensions
n
XSD Type
contains
points to
Figure 3-1 WSDL elements and relationships
In practice a WSDL document can be split into multiple documents using the
import element (see “Physical files” on page 51).
Example
Let us now give an example of a simple, complete, and valid WSDL file. As we
will see, even a simple WSDL document contains quite a few elements with
various relationships to each other. Figure 3-2 and Figure 3-3 contain the WSDL
file example. This example is analyzed in detail later in this chapter.
The example is provided as one unique file. We will see later on that it is possible
to fragment this WSDL document in more than one part. As an exercise, you can
try identifying the different elements in Figure 3-1 while examining the example.
48
WebSphere Version 5.1 Web Services Handbook
<?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"
xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
<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:message name="updateAddressFaultInfo">
<wsdl:part name="fault" type="xsd:string"/>"
</wsdl:message>
Figure 3-2 WSDL simple example: Part 1
Chapter 3. Introduction to WSDL
49
<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:fault message="intf:updateAddressFaultInfo"
name="updateAddressFaultInfo"/>
</wsdl:operation>
</wsdl:portType>
<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
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://address.jaxrpc.samples" use="encoded"/>
</wsdl:output>
<wsdl:fault name="updateAddressFaultInfo">
<wsdlsoap:body
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://address.jaxrpc.samples" use="literal"/>
</wsdl:fault>
</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
50
WebSphere Version 5.1 Web Services Handbook
Physical files
A WSDL document can be created in one or more physical files. If they are more
than one, we need to connect these files using an import element. This
separation of files can be convenient to hold the abstraction of concepts and to
allow better maintenance.
WSDL
WSDL document
Service
Implementation
import
service
port
WSDL document
Service
Implementation
import
service
port
One file
types
message
portType
binding
services
port
Two files
Service
Interface
types
message
portType
binding
binding
file
Interface
file
import
types
binding
message
portType
Three files
WSDL document
Figure 3-4 WSDL document structure as one, two, or three files
Figure 3-4 shows the same Web service described in one, two, or three files:
One file, typically used in Axis and in Application Developer Version 5.1
Two files, typically used in Application Developer Version 4
Three files, typically used in Application Developer Version 5.0
Chapter 3. Introduction to WSDL
51
All three examples stand for the same Web service. Therefore, it is important not
to be confused by the number of files used to define the WSDL document. There
is only one WSDL specification that defines the elements of a WSDL document;
how many files are used to store the document is up to the implementer.
Namespaces
WSDL uses the XML namespaces listed in Table 3-1.
Table 3-1 WSDL namespaces
Prefix
Namespace URI
Explanation
wsdl
http://schemas.xmlsoap.org/wsdl/
Namespace for WSDL
framework.
soap
http://schemas.xmlsoap.org/wsdl/soap/
SOAP binding.
http
http://schemas.xmlsoap.org/wsdl/http/
HTTP binding.
mime
http://schemas.xmlsoap.org/wsdl/mime/
MIME binding.
soapenc
http://schemas.xmlsoap.org/soap/
encoding/
Encoding namespace as
defined by SOAP 1.1.
soapenv
http://schemas.xmlsoap.org/soap/
envelope/
Envelope namespace as
defined by SOAP 1.1.
xsi
http://www.w3.org/2000/10/
XMLSchema-instance
Instance namespace as
defined by XSD.
xsd
http://www.w3.org/2000/10/
XMLSchema
Schema namespace as
defined by XSD.
tns
(URL to WSDL file)
The this namespace (tns)
prefix is used as a convention
to refer to the current
document. Do not confuse it
with the XSD target
namespace, which is a
different concept.
The first four namespaces are defined by the WSDL specification itself; the next
four definitions reference namespaces that are defined in the SOAP and XSD
standards. The last one is local to each specification. Note that in our example
we do not use real namespaces; the URIs contain localhost.
52
WebSphere Version 5.1 Web Services Handbook
WSDL definition
The WSDL definition contains types, messages, operations, port types, bindings,
ports and services.
Also, WSDL provides an optional element called wsdl:document as a container
for human-readable documentation.
Types
The types element encloses data type definitions used by the exchanged
messages. WSDL uses XML schema definitions (XSDs) as its canonical and
built-in type system:
<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).
Chapter 3. Introduction to WSDL
53
<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"
xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
<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
54
WebSphere Version 5.1 Web Services Handbook
updateAddressRequest is composed of an AddressBean part and an int part. The
response message updateAddressResponse is composed of a string part. The
fault message updateAddressFaultInfo is composed of a string part.
<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:message name="updateAddressFaultInfo">
<wsdl:part name="fault" 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.
Chapter 3. Introduction to WSDL
55
Each of these operation types can be supported with variations of the following
syntax. Presence and order of the input, output, and fault messages
determine the type of message:
<wsdl:definitions .... >
<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
As two independent transport-level operations, which can be required if the
transport protocol only supports one-way communication
In our example the port type and operation definition, shown in Figure 3-7, are
where we specify the port type, called AddressService, and a set of operations.
In this case, there is only one operation, called updateAddress.
We also specify the interface that the Web service provides to its possible clients,
with the input message updateAddressRequest, the output message
updateAddressResponse, and the updateAddressFaultInfo that are used in the
transaction.
<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:fault message="intf:updateAddressFaultInfo"
name="updateAddressFaultInfo"/>
</wsdl:operation>
</wsdl:portType>
Figure 3-7 Port type and operation definition in our WSDL document example
56
WebSphere Version 5.1 Web Services Handbook
Bindings
A binding contains:
Protocol-specific general binding data, such as the underlying transport
protocol and the communication style for SOAP, for example.
Protocol extensions for operations and their messages include the URN and
encoding information for SOAP, for example.
Each binding references one port type; one port type can be used in multiple
bindings. All operations defined within the port type must be bound in the
binding. The pseudo XSD for the binding looks like this:
<wsdl:definitions .... >
<wsdl:binding name="nmtoken" type="qname"> (0 or more)
<-- extensibility element (1) --> (0 or more)
<wsdl:operation name="nmtoken"> (0 or more)
<-- extensibility element (2) --> (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)
<-- extensibility element (4) --> (0 or more)
</wsdl:output>
<wsdl:fault name="nmtoken"> (0 or more)
<-- extensibility element (5) --> (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 59.
In our example, the binding definition, shown in Figure 3-8, is where we specify
our binding name, AddressSoapBinding. The connection must be SOAP HTTP
and the style must be rpc. We provide a reference to our operation,
updateAddress; define the input message updateAddressRequest and the output
message updateAddressResponse, both to be SOAP encoded; and the fault
Chapter 3. Introduction to WSDL
57
message, which is literal. Because the fault information is always one string
only, it is suitable to use literal for the encoding.
<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
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://address.jaxrpc.samples" use="encoded"/>
</wsdl:output>
<wsdl:fault name="updateAddressFaultInfo">
<wsdlsoap:body
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://address.jaxrpc.samples" use="literal"/>
</wsdl:fault>
</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:definitions .... >
<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.
58
WebSphere Version 5.1 Web Services Handbook
Port definition
A port definition describes an individual endpoint by specifying a single address
for a binding:
<wsdl:definitions .... >
<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, for example,
http://localhost:9080/Router/services/Address.
<wsdl:service name="AddressServiceService">
<wsdl:port binding="intf:AddressSoapBinding" name="Address">
<wsdlsoap:address
location="http://localhost:9080/Router/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.
Chapter 3. Introduction to WSDL
59
SOAP binding
WSDL includes a binding for SOAP 1.1 endpoints, which supports the
specification of the following protocol-specific information:
An indication that a binding is bound to the SOAP 1.1 protocol
A way of specifying an address for a SOAP endpoint
The URI for the SOAPAction HTTP header for the HTTP binding of SOAP
A list of definitions for headers that are transmitted as part of the SOAP
envelope
Table 3-2 lists the corresponding extension elements.
Table 3-2 SOAP extensibility elements in WSDL
Extension and attributes
Explanation
<soap:binding ...>
Binding level; specifies defaults for all operations.
transport="uri"
(0 or 1)
Binding level; transport is the runtime transport
protocol used by SOAP (HTTP, SMTP, ...).
style="rpc|document"
(0 or 1)
The style is one of the two SOAP communication
styles, rpc or document.
<soap:operation ... >
soapAction="uri"
(0 or 1)
URN.
style="rpc|document"
(0 or 1)
See binding level.
<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=
"uri-list"(0 or 1)
List of supported message encoding styles.
namespace="uri"
(0 or 1)
URN of the service.
<soap:fault ... >
60
Extends operation definition.
Extends operation definition; contents of fault
details element.
WebSphere Version 5.1 Web Services Handbook
Extension and attributes
Explanation
name="nmtoken"
Relates soap:fault to wsdl:fault for operation.
use, encodingStyle,
namespace
See soap:body.
<soap:address ... >
location="uri"
Extends port definition.
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 58.
Note that the WSDL specification deals with encoding only. The mappings to be
used for a specific type under a certain encoding are beyond the scope of this
book. They are part of the SOAP client and server runtime configuration (client
API and deployment descriptor, respectively).
HTTP binding
WSDL includes a binding for HTTP 1.1 GET and POST verbs to describe the
interaction between a Web browser and a Web application. This allows
applications other than Web browsers to interact with the application (its
controller servlets, for example).
The following protocol-specific information is required to describe a Web service
that can be accessed through HTTP:
An indication that a binding uses HTTP GET or POST
An address for the port
A relative address for each operation (relative to the base address defined by
the port)
Table 3-3 lists the defined extension elements.
Table 3-3 HTTP extension elements in WSDL
Extension
Explanation
<http:address
location="uri"/>
Extends the port definition and contains the base URL.
<http:binding
verb="nmtoken"/>
The HTTP operation to be performed (nmtoken=GET or
POST).
Chapter 3. Introduction to WSDL
61
Extension
Explanation
<http:operation
location="uri"/>
Extends the operation binding and specifies the relative
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
part="nmtoken"? type="string"?/>
Name and MIME type of WSDL message
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:
http://www-124.ibm.com/developerworks/projects/wsdl4j/
http://www-136.ibm.com/developerworks/opensource
62
WebSphere Version 5.1 Web Services Handbook
WSDL4J will be a reference implementation for JSR 110 (Java APIs for WSDL).
Primarily it is a set of Java interfaces that can be implemented by anyone. The
Java package name is javax.wsdl.
Figure 3-10 is an example in which we provide a function to obtain all the port
addresses available for a specific SOAP binding in a specified WSDL document.
These addresses are returned in a vector element of strings with the URL
locations.
private Vector getWSDLPort(String fileName, String serviceName) {
final String serviceNameSpace = "http://wsoj.itso";
int endPointCounter = 0;
Service service;
Port port = null;
Vector serviceEndpoint = new Vector();
try {
// Read WSDL document and get definitions element
WSDLFactory wsdlFactory = WSDLFactory.newInstance();
WSDLReader wsdlReader = wsdlFactory.newWSDLReader();
Definition definition = wsdlReader.readWSDL(null,fileName);
// Get the ports for the WeatherForecast_SEIService
service = definition.getService(new
QName(serviceNameSpace,serviceName));
Map ports = service.getPorts();
Collection values = ports.values();
for (Iterator iterator = values.iterator(); iterator.hasNext();) {
port = (Port) iterator.next();
List list = port.getExtensibilityElements();
for (Iterator iter = list.iterator(); iter.hasNext();) {
// The SOAP binding is an extensibility element of Port
ExtensibilityElement element =
(ExtensibilityElement) iter.next();
if (element instanceof SOAPAddress) {
SOAPAddress soapAddress = (SOAPAddress) element;
serviceEndpoint.add(soapAddress.getLocationURI());
}
}
}
} catch (WSDLException e) { e.printStackTrace(); }
return serviceEndpoint;
}
Figure 3-10 WSDL API example
Chapter 3. Introduction to WSDL
63
Outlook
The WSDL 1.1 is currently in the process of being standardized by the W3C. On
the other hand, new working draft specifications Web services description
language (WSDL) Version 1.2 and Web services description language (WSDL)
Version 1.2: Bindings have been released. These specifications provide a new
conceptual framework approach to improve the operability and the components
definition.
Version 1.2 enhancements to Version 1.1 are:
WSDL 1.2 includes language clarifications that make it easier for developers
to understand and use WSDL.
WSDL 1.2 provides support for W3C recommendations, including XML
Schemas and XML Information Set.
XML Information Set (Infoset) is an abstract data set that provides a
consistent set of definitions for use in other specifications that need to refer to
the information in a well-formed XML document. See:
http://www.w3.org/TR/xml-infoset/
WSDL 1.2 adopts a conceptual framework approach to define the description
components, which makes them simpler and more flexible.
WSDL 1.2 provides a better definition for the HTTP 1.1 binding and will soon
provide a binding for SOAP 1.2, which allows description of services using the
most current version of SOAP.
Tool support for WSDL is already available, as covered in Part 2, “Web services
implementation and samples” on page 201.
An example of another innovation in the WSDL area is the Web services
invocation framework (WSIF), providing a WSDL-centric service requestor API.
WSIF is transport agnostic; thus a single WSIF client can support multiple
runtime protocols simultaneously, such as SOAP, a direct HTTP connection, and
a local Java call. See Chapter 7, “Web services invocation framework” on
page 129.
64
WebSphere Version 5.1 Web Services Handbook
Summary
This introduction has shown the power of WSDL. WSDL provides an abstract
part that is language and protocol independent, as well as bindings for the
runtime protocols used in the service-oriented architecture (SOA).
This chapter has also shown that even a simple Web service definition has to
cover many interrelated aspects yielding a rather complex specification file.
Writing WSDL documents from scratch is an error-prone task; therefore, there is
a strong need for tool support. We cover these tools in Part 2, “Web services
implementation and samples” on page 201.
More information
As of today, few WSDL tutorials or other supporting information are available. As
WSDL becomes more widespread, this will change.
Good sources for more information are the IBM WebSphere Development Kit for
Web Service (WSDK, see Chapter 18, “WebSphere SDK for Web Services” on
page 381) and the WSDL 1.1 specification. WSDL 1.1 is contained in the IBM
WSDK and can also be found at:
http://www.w3.org/TR/wsdl
For further information about WSDL Version 1.2, visit:
http://www.w3.org/TR/wsdl12
http://www.w3.org/TR/wsdl12-bindings
Chapter 3. Introduction to WSDL
65
66
WebSphere Version 5.1 Web Services Handbook
4
Chapter 4.
JAX-RPC (JSR 101)
This chapter explains the Java API for XML-based Remote Procedure Call
(JAX-RPC) style programming model. The JAX-RPC programming model is
defined by the Web services standard JSR 101.
JSR 101 formalizes the procedure for invoking Web services in an RPC-like
manner. It is a required part of the J2EE 1.4 specification, but due to huge
demand of this programming model, IBM it also provides on the J2EE 1.3
platform. This support has been provided out-of-the-box in WebSphere 5.0.2 and
later.
JSR 101 is not new to WebSphere. A sneak preview of JSR 101 was available in
the WebSphere Web Services Technology Preview, which was based on
WebSphere 5.0 and was intended to be a development level add-on. In
WebSphere 5.0.2 and 5.1, JSR 101 is not only fully supported for production, but
it also forms the default runtime infrastructure.
JAX-RPC is a newly defined specification of distributed computing. Some of the
earlier specifications of distributed computing are Java’s RMI-IIOP, OMG’s
CORBA, Microsoft’s COM, and so forth.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
67
Terminology: JAX-RPC and JSR 101
Let us start with discussing the terminology. In Web services discussions, the
terms JAX-RPC and JSR 101 are used quite interchangeably. This chapter also
uses both the terms. However, at their core, they do not mean the same thing.
There is a distinction between these terms. JAX-RPC is the programming style
and JSR 101 is the specification document. JSR 101 lays down the requirements
of JAX-RPC 1.0. Over time, as JAX-RPC picks up more momentum, it will
encompass wider usage scenarios and may at that point implement newer JSRs
in addition to or instead of JSR 101.
JAX-RPC basics
Java API for XML-based RPC (JAX-RPC), as the name suggests, is a Java API
that facilitates distributed computing in a Web services environment. JAX-RPC
based Java applications can easily communicate with non-Java based
technologies in the RPC style fashion.
JAX-RPC compliance mandates client-side requirements as well as server-side
requirements. Figure 4-1 and Figure 4-2 show JSR 101 clients and the JSR 101
server, respectively. JSR 101 clients can interoperate with any JAX-RPC
compliant server.
JAX-RPC Clients
(JSR 101 based)
In a J2EE SERVER Container
Servlet orJavaBean or session EJB
(managed or unmanaged)
In a J2EE CLIENT Container
Web Services
Provider
(SOAP-RPC
compliant)
Java class with main() method
using
<WAS_HOME>/bin/launchclient
(managed or unmanaged)
Standalone Java Client
Based on J2EE,
.NET or any
WS-RPC compliant
technology
Java class with a main() method
using <JAVA_HOME>/bin/java
(unmanaged only)
Figure 4-1 JSR 101 client interoperates with any SOAP-RPC compliant server
68
WebSphere Version 5.1 Web Services Handbook
A JAX-RPC server can interoperate with any SOAP-RPC client, Java based or
otherwise.
JSR 101 client
In a J2EE SERVER container
In a J2EE CLIENT container
STANDALONE Java client
JAX-RPC Server
"endpoint"
(JSR 101 based)
.NET client
WS-RPC compliant client
Non-Java,
non-MicroSoft
WS-RPC compliant
client
JSR 101
compliant J2EE
engine such as
WebSphere
5.0.2 or 5.1
Figure 4-2 JSR 101 server interoperates with any SOAP-RPC compliant client
A JAX-RPC server application’s entry point is also known as an endpoint. A Web
service endpoint is described using a Web services description language
(WSDL) document. JAX-RPC is about Web services interoperability across
heterogeneous platforms and languages. This makes JAX-RPC a key technology
for Web services based integration.
JAX-RPC client
A JAX-RPC client is capable of invoking a Web service irrespective of whether
the service has been defined on the J2EE platform or on a non-Java platform.
JAX-RPC clients do not necessarily have to be Java clients. For Java clients to
be JAX-RPC compliant, they have to comply with JSR 101. Figure 4-1 explains
the various forms of JAX-RPC clients.
JAX-RPC clients can run inside a J2EE container or as a standalone Java client.
If running inside a J2EE container, they can be coded as managed or
unmanaged clients. If running as a standalone Java client, they can only be
unmanaged. We will discuss unmanaged and managed clients in “Managed and
unmanaged JAX-RPC clients” on page 74.
Example 4-1 shows the most simple example of a JAX-RPC client.
Chapter 4. JAX-RPC (JSR 101)
69
Example 4-1 Simple JAX-RPC client
package itso.test;
import java.io.*;
import java.util.*;
import itso.test.*;
public class WeatherForecastClient {
public static void main(String [] args){
try{
WeatherForecastServiceLocator wsl = new WeatherForecastServiceLocator();
WeatherForecastService ws = (WeatherForecastService) wsl.getWeather();
String temperature = ws.getTemperature();
System.out.println(temperature);
System.out.println("WeatherForecastClient completed");
} catch (Exception e) {
e.printStackTrace();
}
}
}
In this example, we have highlighted the three essential operations of a JAX-RPC
client:
Instantiate the locator class. The locator class has information about the Web
service. The locator class is populated based on the content of the Web
service’s WSDL file.
Instantiate the service using the locator class. The service interface is a local
representation of the Web service. The service interface is implemented by
the so-called stub class.
Invoke a method on the service interface.
JAX-RPC client programming styles
If the Web service is not expected to ever change, the above mechanism of
Example 4-1 works very well. This mechanism is known as static stub based
invocation of a Web service. But if the Web service were to change, the client
would have to be changed accordingly. We therefore provide capability for clients
to be dynamic. There are three types of Web services clients (Figure 4-3):
Static stub
Dynamic proxy
Dynamic invocation interface (DII)
70
WebSphere Version 5.1 Web Services Handbook
JAX-RPC
clients
Proxy based
No proxy
1. Static Stub
2. Dynamic Proxy
Tightly bound to the
locator class
Not dynamic
Loosely bound to the
locator class
Partially dynamic
3. Dynamic Invocation
Interface (DII)
Locator class not used
Fully dynamic
Figure 4-3 Static and dynamic JAX-RPC clients
Static stub
Let us fully understand the static stub client of Example 4-1 on page 70. A static
stub-based JAX-RPC client uses proxy classes to communicate with the Web
service (Figure 4-4). These proxy classes are generated from the WSDL of the
Web service. In the WebSphere Application Server, the proxy classes can be
generated by the tool <WAS_HOME>/bin/WSDL2JAVA.
Once the proxy classes have been generated, they are copied to the client
machine. The client can then invoke the Web service based only on these proxy
classes.
Proxy based
JSR 101 client
WeatherForecastClient.java
Proxy classes
JSR 101
compliant Web
service
WeatherForecast.java
WeatherForecastService.java
WeatherForecastServiceLocator.java
WeatherForecastSoapBinding.java
Figure 4-4 Proxy-based JAX-RPC client
Chapter 4. JAX-RPC (JSR 101)
71
The four proxy classes are:
Service endpoint interface (SEI): WeatherForecast—defines the method
signatures of the Web service
Service interface: WeatherForecastService—defines the service methods of
the locator class (for example, retrieving the SEI)
Service locator class: WeatherForecastServiceLocator—implements the
service interface (provides access to the SEI)
Binding stub: WeatherForecastSoapBinding—implements the SEI (makes the
actual calls to the Web service)
J2SE
Supports JavaBean
Web services only
J2EE
JavaBean
instance
1
Service
Object
(Factory)
Service
Client
Client
Stub
3
2
Service
Interface
Transport
Service
Endpoint
Implementation
WSDL
Service
Endpoint
Interface
3
Service
Endpoint
Interface
JAX-RPC runtime
Figure 4-5 JAX-RPC static client calling sequence
At runtime, the client instantiates the service locator class, calls it to retrieve the
SEI (actually the binding stub), then calls the SEI to invoke the Web service.
Figure 4-5 shows the calling sequence in a Java implementation.
1. The client instantiates the service locator.
2. The client calls the service locator to retrieve the SEI (an instance of the client
stub that implements the SEI is returned).
3. The client invokes a Web service through the SEI.
The client can be a J2SE client that invokes a Web service in a J2EE-compliant
application server. The Web service implementation is a JavaBean. To support
an EJB Web service, refer to Chapter 5, “Implementing Enterprise Web Services
(JSR 109)” on page 77.
72
WebSphere Version 5.1 Web Services Handbook
Dynamic Proxy
Let us see an example of a dynamic proxy-based JAX-RPC client (Example 4-2).
In dynamic proxy clients, the default destination of the Web service can be
changed in the client by specifying a different destination in the client application.
Example 4-2 Dynamic proxy client - only partially dynamic
import javax.xml.namespace.QName;
import java.io.*;
import java.util.*;
public class WeatherForecastDynamicProxyClient {
public static void main(String [] args){
try{
WeatherForecastServiceLocator wsl = new WeatherForecastServiceLocator();
QName qn = new QName("http://www.somewhere.com", "WeatherForecast");
WeatherForecast ws = (WeatherForecast)
wsl.getPort(qn,WeatherForecast.class);
String temperature = ws.getTemperature();
System.out.println(temperature);
System.out.println("DynamicProxyJavaClient completed");
} catch (Exception e){
e.printStackTrace();
}
}
}
At runtime the service locator is instantiated. The SEI is retrieved using a
destination (QName).
Dynamic invocation interface (DII)
DII is used when the WSDL of the Web service can change considerably over
time. DII-based clients do not use proxy classes, but instead read the entire
WSDL file during runtime:
Instantiate a DII service class.
Instantiate a Call object (Call is a class provided by JAX-RPC).
Populate the Call object.
Invoke the Web service operation on the Call object.
Chapter 4. JAX-RPC (JSR 101)
73
Which style to use
Table 4-1 lists the usage scenarios of the three styles.
Table 4-1 Client styles
Static stub
Dynamic proxy
DII
Web service not expected
to change
Some changes to the Web
service expected, such as
the location of the service
Considerable changes to
the Web service expected,
such as:
- Location of the service
- Request/response format
- Data types
Most common scenario
Less common
Less common
Managed and unmanaged JAX-RPC clients
So far we have discussed unmanaged JAX-RPC clients. Managed clients allow
the J2EE container to instantiate the proxy classes. Example 4-3 shows a code
snippet of a managed, dynamic proxy-based JAX-RPC client. A static stub-based
client can also be coded as managed clients.
Example 4-3 Managed, dynamic proxy-based client
InitialContext ic = new InitialContext();
WeatherForecastServiceLocator wsl =
(WeatherForecastServiceLocator)
ic.lookup("java:comp/env/service/WeatherForecastService");
QName qn = new QName("http://www.somwhere.com", "WeatherForecast");
WeatherForecast ws = (WeatherForecast)
wsl.getPort(qn,WeatherForecast.class);
String temperature = ws.getTemperature();
System.out.println(temperature);
System.out.println("DynamicProxyJavaClient completed");
The main difference in a managed client and unmanaged client (Example 4-2 on
page 73 versus Example 4-3) is the way the WeatherForecastServiceLocator
class is instantiated:
For a managed client the locator class is instantiated by the container, by
calling the lookup method on the default InitialContext.
For an unmanaged client the locator class is instantiated by calling a
constructor of the locator class.
74
WebSphere Version 5.1 Web Services Handbook
JAX-RPC specification details
JSR 101 provides details about JAX-RPC. Here we provide a brief idea of what
lies therein.
Data type mapping: XML -> Java, Java -> XML
JAX-RPC data flows as XML. For this purpose, the JAX-RPC client has to
convert Java data types into XML and the JAX-RPC server has to convert XML
data into Java data types, and vice versa on the result flow (Figure 4-6).
Java to XML
1 mapping
JAX-RPC
Client
Input
XML to Java
2 mapping
SOAP
messages
XML to Java
4 mapping
Output
Java to XML
3 mapping
JAX-RPC
Server
Figure 4-6 Mapping and encoding stages for a Web service
Support is provided to convert simple data types, such as xsd:string and
xsd:integer to java.lang.String and java.math.BigInteger, and so on. The
complete list is available at http://schemas.xmlsoap.org/soap/encoding/.
In addition to simple data types, JAX-RPC also specifies the mapping of data
structures such as arrays. These arrays can contain elements of simple data
types or of user-defined data types (JavaBeans). Refer to the specification for
details about the mappings.
There are four steps in the process, indicated by the numbers in Figure 4-6:
1. Client input mapping (Java to XML)—This takes the parameter from the Java
client and maps it using the input mapping style.
2. Server input mapping (XML to Java)—The inbound parameters are
deserialized from the XML style in the message to Java types, which are then
used to invoke the method in the JavaBean.
3. Server output mapping (Java to XML)—Once the JavaBean has completed its
method execution, the return value is inserted into the SOAP reply using the
output mapping style.
4. Client output mapping (XML to Java)—The final stage is performed by SOAP
for the client proxy, which maps the returned XML elements into Java types.
Chapter 4. JAX-RPC (JSR 101)
75
Summary
In this chapter we described JAX-RPC, as defined by the Web services standard
JSR 101.
We looked at JAX-RPC servers and clients, and the different styles of clients,
static and dynamic.
More information
The complete JSR 101 specification is at:
http://www.jcp.org/en/jsr/detail?id=101
These are some informative article on the IBM developerWorks Web site:
http://www-106.ibm.com/developerworks/webservices/library/ws-jsrart/
http://www-106.ibm.com/developerworks/webservices/library/ws-jaxrpc1
http://www-106.ibm.com/developerworks/xml/library/x-tipjaxrpc/
76
WebSphere Version 5.1 Web Services Handbook
5
Chapter 5.
Implementing Enterprise
Web Services (JSR 109)
This chapter provides a general view to introduce the Web Services for J2EE
architecture, JSR 109. This is an architecture that standardizes the deployment
of Web services in a Java 2 Platform, Enterprise Edition (J2EE) to create
portable and interoperable services across different server platforms.
At the time of the writing of this book, there is a public draft version 1.1 that
removed J2EE 1.3 deployment requirements, but this chapter concentrates more
on the final release 1.0.
In this chapter, we discuss the following topics:
JSR 109 overview
Client programming model
Server programming model
Handlers
Security
© Copyright IBM Corp. 2003, 2004. All rights reserved.
77
JSR 109 overview
Prior to the appearance of the Web Services for J2EE specification (JSR 109)
there was no standard definition of how deploy a Web service in a J2EE platform.
Thus, the process to do so was largely dependant on the destination runtime.
JSR 109 standardizes the process, making it portable to every compliance J2EE
server platform.
JSR 109 leverages J2EE technology defining the needed mechanism to
standardize a deployment model for Web services. This standardization wants to
achieve the interoperability across different compliance J2EE platforms,
transforming the migration among them into a routine process ensuring that
vendors interoperate.
JSR 109 defines the minimal new concepts, interface, file formats, and so forth,
to support a simple model for defining and deploying Web services.
Programmers ensure that their Web services can be deployed later in servers
that comply with J2EE and JSR 109 specifications; meanwhile, the complexity of
the process is hidden from them. JSR 109 also defines the required roles and
their functions, and perform and their mapping to the J2EE platform roles.
JSR 109 adds additional artifacts to those defined by JAX-RPC (see Chapter 4,
“JAX-RPC (JSR 101)” on page 67), bringing JAX-RPC to the J2EE container
components. Although the JSR 109 does not restrict any implementation, it is
only defined for two implementations:
Stateless session EJB in an EJB container
Java class in a Web container
For these two implementation models and for both client and server sides, the
specification details are:
The programming model for J2EE components with Web services
– How J2EE server components can be defined to be accessible as Web
services
– How J2EE client components and applications can use JAX-RPC to
access Web services
The assembly of the components with Web services
The deploying of these components as Web services components
– How J2EE server components can be described as Web services
– How J2EE client components can be described for accessing Web
services using JAX-RPC
78
WebSphere Version 5.1 Web Services Handbook
JSR 109 and JAX-RPC provide the standard programming and deployment
model that will be an integral part of the J2EE 1.4 specification.
Client programming model
In this section we describe the client programming model. We provide an
overview of the characteristics of the client, a description of the different clients,
an explanation of the deployment descriptors used in the client side, and a
description of the roles that take part in the application development cycle.
Overview
The client programming model provides the client guidelines for access to Web
services in a J2EE environment. This client should be conformant with the client
programming model defined by JAX-RPC (see Chapter 4, “JAX-RPC (JSR 101)”
on page 67). However, Web services clients are not limited to those defined in
this specification, which only covers those who run in a J2EE environment.
Programmers can be sure that clients conformant to this specification can access
any Web service running in a Web Services for J2EE container and can call any
SOAP 1.1 Web service through HTTP/S SOAP Binding. How the service
implementation is realized has to be transparent to the client.
The client can be another Web service, J2EE component, or an arbitrary Java
application. The client invokes Web service methods without distinguishing
whether those are performed locally or remotely in a J2EE runtime environment.
The client has not control the life cycle of the Web service only access to it.
The port provider and the container configure the view of the client that includes:
Service interface—Defines the methods to access a port of a Web service
Service endpoint interface—Defines the methods to call a Web service
Figure 5-1 shows an architectural model of a general client.
Chapter 5. Implementing Enterprise Web Services (JSR 109)
79
J2EE Client Container
JNDI
Context
Client
Application
Service
Implementation
Stub
Implementation
Service
Interface
Service
Endpoint
Interface
Figure 5-1 General client architectural model
Client types
The client uses a JNDI lookup to find the service interface. The container is
responsible for the boundary between the JNDI name and the service
implementation. With the service interface the client can get:
Static stub—Requires WSDL knowledge that has service location included
Dynamic proxy—May have only partial WSDL definition
Dynamic invocation interface (DII)—Does not require WSDL knowledge
Static stub
The static stub client uses a defined service endpoint interface (SEI) based on
the WSDL document to get a stub for a specific Web service. The stub is the
local representation of the remote Web service and is used by the client to invoke
the Web service.
This client is the easiest of the three of them, but the small change in the WSDL
document provokes the client useless; the stub has to be regenerated.
Consequently, the use of this client is only recommended for stable and reliable
Web service, where the probability for a modification in the Web service definition
is practically zero.
Figure 5-2 shows the static client calling sequence in a Java environment:
The client uses JNDI to get an instance of the service locator. The JNDI name
is defined in the client deployment descriptor.
The client invokes the service locator to retrieve the SEI (actually an instance
of the client stub that implements the SEI is returned).
The client invokes a Web service through the SEI.
80
WebSphere Version 5.1 Web Services Handbook
J2EE
Supports EJB
Web services
J2EE
JavaBean
JNDI
1
Service
Object
(Factory)
Client
Stub
2
3
Service
Client
Service
Interface
Transport
EJB
Service
Endpoint
Implementation
WSDL
Service
Endpoint
Interface
3
Service
Endpoint
Interface
JAX-RPC runtime
Client DD
Deployment Descriptor
Server DD
Figure 5-2 JSR 109 static client calling sequence
A simple coding sequence is shown here:
InitialContext ic = new InitialContext();
BankEJBServiceLocator locator = (BankEJBServiceLocator)ic.lookup
("java:comp/env/service/BankEJBService");
BankEJB proxy = (BankEJB)locator.getBankEJB();
Account account = proxy.getAccount(accountId); // call Web service
Dynamic proxy
The dynamic proxy client uses a generic service endpoint interface (SEI).
Therefore, the client is not bound to an implemented stub and it is in runtime
when a specific SEI is instantiated. From here, the client uses the same
mechanism used by the static stub to invoke the Web service.
This client presents some advantage to the static client for testing purposes,
when the Web service definition is not perfectly closed.
Dynamic invocation interface (DII)
The dynamic invocation interface uses a javax.xml.rpc.Call instance for
dynamic invocation. Unlike the two previous clients, the DII has to previously
configure the Call object, providing the following information:
Operation name
Parameters names, types and modes
Chapter 5. Implementing Enterprise Web Services (JSR 109)
81
Port type and address of a target service endpoint
Protocol and transport properties
Deployment descriptors
The deployment descriptors used for the client programming model are the Web
service client deployment descriptor, webservicesclient.xml, and the JAX-RPC
mapping deployment descriptor (without a standard name).
Web service client deployment descriptor
This deployment descriptor contains the service reference entries. The
references are used by a J2EE component container to deploy the client.
Example 5-1 shows a sample webservicesclient.xml file.
Example 5-1 webserviceclient.xml of Weather service
<webservicesclient>
<service-ref>
<description>WSDL Service WeatherForecastService</description>
<service-ref-name>service/WeatherForecastService</service-ref-name>
<service-interface>
itso.session.WeatherForecastService
</service-interface>
<wsdl-file>WEB-INF/wsdl/WeatherForecast.wsdl</wsdl-file>
<jaxrpc-mapping-file>
WEB-INF/WeatherForecast_mapping.xml
</jaxrpc-mapping-file>
<service-qname>
<namespaceURI>http://session.itso</namespaceURI>
<localpart>WeatherForecastService</localpart>
</service-qname>
<port-component-ref>
<service-endpoint-interface>
itso.session.WeatherForecast
</service-endpoint-interface>
</port-component-ref>
</service-ref>
</webservicesclient>
Each Web service used by a client has to be defined in a service-ref element. A
service-ref element has:
Description
82
The human-readable description of our Web service. In
our example, WSDL Service WeatherForecastService.
WebSphere Version 5.1 Web Services Handbook
Service ref name
The logical name of the reference used by JNDI to look
up the service reference. In our example,
service/WeatherForecastService.
Service type
The fully qualified name of the service interface returned
by the JNDI lookup. In our example,
itso.session.WeatherForecastService.
WSDL definition
The location of the WSDL description of the service. In
our example, WEB-INF/wsdl/WeatherForecast.wsdl.
JAX-RPC mapping
The location of the WSDL-Java mapping file. In our
example, WEB-INF/WeatherForecast_mapping.xml.
Service port
The qualified name of the referenced WSDL service. In
our example, the namespace URI is
http://session.itso and the service is
WeatherForecastService.
Ports
The port component provides the local representation of
our Web service, the service endpoint interface. In our
example, itso.session.WeatherForecast.
Scope
If the client is an EJB, the scope provides the association
between the service and the EJB client using the
component-scope-refs. Our example is a servlet client;
scope is not needed.
Handlers
The handlers associated with the Web service reference.
In our example, there is no one.
JAX-RPC mapping deployment descriptor
This deployment descriptor contains the mapping information between the
WSDL definition and the Java interfaces. The main elements that compose a
JAX-RPC mapping deployment descriptor are:
The package mapping—Contains the relation between the XML namespace
and Java packages:
<package-mapping>
<package-type>itso.mapping</package-type>
<namespaceURI>http://mapping.itso</namespaceURI>
</package-mapping>
The type mapping—Contains the type mapping between Java types and XML
types. It is the most remarkable component:
<java-xml-type-mapping>
<class-type>itso.mapping.Weather</class-type>
<root-type-qname>
<namespaceURI>http://mapping.itso</namespaceURI>
Chapter 5. Implementing Enterprise Web Services (JSR 109)
83
<localpart>Weather</localpart>
</root-type-qname>
<qname-scope>complexType</qname-scope>
<variable-mapping>
<java-variable-name>condition</java-variable-name>
<xml-element-name>condition</xml-element-name>
</variable-mapping>
....
<variable-mapping>
<java-variable-name>windSpeed</java-variable-name>
<xml-element-name>windSpeed</xml-element-name>
</variable-mapping>
....
</java-xml-type-mapping>
The four fundamental elements are:
– Class type—Contains the fully qualified name of the Java bean that stands
for the type (in our example, itso.mapping.Weather).
– Root qname—Contains the qualified name of the bean as it appears in the
WSDL definition (in our example, the namespace URI is
http://mapping.itso and the local name is Weather).
– Scope—Contains the scope of the type. Possible values are simpleType,
complexType and element (in our example, complexType).
– Variables—Contains the mappings between the data members of the Java
bean and the XML elements (in our example, condition, windSpeed and
others).
The service interface mapping—Contains the mapping for the WSDL service
definition:
<service-interface-mapping>
<service-interface>
itso.session.WeatherForecastService
</service-interface>
<wsdl-service-name>
<namespaceURI>http://session.itso</namespaceURI>
<localpart>WeatherForecastService</localpart>
</wsdl-service-name>
<port-mapping>
<port-name>WeatherForecast</port-name>
<java-port-name>WeatherForecast</java-port-name>
</port-mapping>
</service-interface-mapping>
84
WebSphere Version 5.1 Web Services Handbook
The three fundamental elements are:
– Service interface—Contains the fully qualified name of the service
interface Java class (in our example,
itso.session.WeatherForecastService)
– Service name—Contains the qualified name of the service as it appears in
the WSDL definition (in our example, the namespace URI is
http://session.itso and the local name is WeatherForecastService)
– Port mapping—Contains the mapping for the WSDL ports (in our example,
WeatherForecast)
The service endpoint interface mapping—Contains the fully qualified class
name of the service endpoint interface. It also contains the mappings for
WSDL messages, port types and bindings:
<service-endpoint-interface-mapping>
<service-endpoint-interface>
itso.session.WeatherForecast
</service-endpoint-interface>
<wsdl-port-type>
<namespaceURI>http://session.itso</namespaceURI>
<localpart>WeatherForecast</localpart>
</wsdl-port-type>
<wsdl-binding>
<namespaceURI>http://session.itso</namespaceURI>
<localpart>WeatherForecastSoapBinding</localpart>
</wsdl-binding>
<service-endpoint-method-mapping>
<java-method-name>getDayForecast</java-method-name>
<wsdl-operation>getDayForecast</wsdl-operation>
<method-param-parts-mapping>
........
</service-endpoint-method-mapping>
</service-endpoint-interface-mapping>
Roles
There are no new J2EE roles defined for the JSR 109 specification. The roles are
mapped to existing J2EE roles. The three roles presented in the JSR 109 are:
Developer—Responsible for client definition, implementation and packaging
within J2EE modules
Assembler—Responsible for assembling the modules into an application
Deployer—Responsible for publishing the deployed clients and resolving
client references
A more detailed description of the roles’ responsibilities is shown in Table 5-1.
Chapter 5. Implementing Enterprise Web Services (JSR 109)
85
Table 5-1 Roles’ responsibilities for client side
Developer
Client
implementation
Implement the
client.
May implement
handlers.
Web services
client DD
Define service
references.
May define handler
references.
JAX-RPC
mapping DD
Provide the
mapping.
Application
server
Assembler
Deployer
Generate the stubs
from the JAX-RPC
mapping DD
information.
May configure
handlers.
Assembly modules
in an EAR file.
Resolve service
and port references.
Deploy the
application.
Server programming model
In this section we describe the server programming model. We provide an
overview about the characteristic of the server, a description of the different
server implementations, an explanation of the deployment descriptors used on
the server side, and a description of the roles that take part in the application
development cycle.
Overview
The server programming model provides the server guidelines for standardizing
the deployment of Web services in a J2EE environment. Depending on the
runtime environment, two implementation models are described:
Web container—A Java class according to a JAX-RPC servlet based service
EJB container—A stateless session EJB
Either of them provides the information to define a port component. A port
component defines the server view of a Web service providing a portable Web
services programming model. A port component makes available a service entry
point defined in a WSDL port address to grant access to the operations stated in
the WSDL definition.
Each port model has a service endpoint interface that defines the operations
exposed by a Web service and a service implementation bean that implements
the business logic for all the operations defined in the service endpoint interface.
86
WebSphere Version 5.1 Web Services Handbook
The implementation and the packaging of that service depend upon the
container where the port is deployed in.
The life cycle can vary based on the implementation methodology used and is
totally controlled by the associated container. In general, the life cycle of a Web
service follows the same steps of its container. A port is created, initialized,
executed and destroyed following the container criteria and without port
operations interference.
Figure 5-3 shows an architectural model of a general server.
J2EE Server Container
Port
Web
Service
Client
Listener
Service
Endpoint
Implementation
Service
Endpoint
Interface
WSDL
Figure 5-3 General server architectural model
Server
The fundamental part of a Web service is the port component. A port component
defines the programming model artifacts that make the Web service a portable
server application. That programming model includes:
WSDL definition—Provides the description of a Web service.
Service endpoint interface (SEI)—Defines the operations available for a Web
service. Must follow JAX-RPC mapping rules.
Service implementation bean—Implements the SEI methods to provide the
business logic of a Web service.
Security role references—Provides instance level security check across the
different modules.
Chapter 5. Implementing Enterprise Web Services (JSR 109)
87
Service implementation bean
The service implementation bean can be implemented in two different ways: A
stateless session EJB or a JAX-RPC servlet-based service, depending on the
container where the service implementation bean is deployed in.
EJB container programming model
A stateless session EJB can be used to implement a Web service. That stateless
session EJB has to follow some requirements:
The stateless session EJB must have a default public constructor, a default
EJB create method, and an EJB remote method.
The service endpoint interface has to be a subset of the methods stated in the
remote interface of the stateless session EJB. Those methods must be public,
but neither final nor static.
The stateless session EJB must be a stateless object.
The class must be public, but neither final nor abstract.
The class must not a defined finalize method.
Because the stateless session EJB runs in an EJB container, the life cycle of the
implementation bean is the same as is stated in the Enterprise JavaBeans
specification. This life cycle is shown in Figure 5-4.
does not exit
1. newInstance()
2. setSessionContest(sc)
3. ejbCreate()
SEI method
Action initiated by
Web service client
Action initiated by
EJB container
ejbRemove()
method
ready
ejbTimeout(arg)
Figure 5-4 Life cycle of a service implementation bean in an EJB container
The EJB container uses the ejbCreate and the ejbRemote methods to notify a
service implementation bean instance of a change in its state. Once the
container has called the ejbCreate method, the service implementation bean is
ready for dispatching a request to clients using any of the SEI methods defined for
the Web service. The dispatching of these SEI methods is initiated by the client.
88
WebSphere Version 5.1 Web Services Handbook
The stateless session EJB is packaged in an EJB JAR file that contains all the
required classes, the WSDL definition, and the Web services deployment
descriptors. Finally, the modules containing the port components are packaged
in an EAR file following the J2EE specifications.
Web container programming model
A Java class can be used to implement a Web service. That Java class follows
the JAX-RPC specifications to create a service implementation bean that runs
within a Web container (see Chapter 4, “JAX-RPC (JSR 101)” on page 67). Thus,
the Java class requirements are:
The Java class must have a default public constructor.
The Java class must implement the method signatures of the service
endpoint interface. Only those methods are exposed to the client.
The Java class must be stateless.
The Java class must be public, but neither final nor abstract.
The Java class must not be defined finalize method.
The Java class life cycle is controlled by a Web container, as is shown in
Figure 5-5.
does not exit
1. newInstance()
2. init()
SEI method
Action initiated by
Web service client
Action initiated by
Web container
destroy()
method
ready
Figure 5-5 Life cycle of a service implementation bean in a Web container
The Web container uses the init and the destroy methods to notify a service
implementation bean instance of a change in its state. Once the container has
called the init method, the service implementation bean is ready for dispatching
requests to clients using any of the SEI methods defined for the Web service. The
dispatching of these SEI methods is initiated by the client.
The Java class is packaged in a WAR file that contains all the required classes,
the WSDL definition, and the Web services deployment descriptors. Finally, the
Chapter 5. Implementing Enterprise Web Services (JSR 109)
89
modules containing the port components are packaged in an EAR file following
the J2EE specifications.
Server container responsibilities
A server container provides a JAX-RPC runtime environment for invoking Web
services ports. The container is responsible for:
Listening to Web services SOAP HTTP request
Parsing the inbound message
Mapping the messages to the implementation class and method
Creating Java objects from the SOAP envelope
Invoking the service implementation bean handlers and instance methods
Capturing the response
Mapping the Java response objects into a SOAP message
Creating the message envelope
Sending the message to the client
Deployment descriptors
The deployment descriptors used for the server programming model are the Web
service deployment descriptor, webservices.xml, and the JAX-RPC mapping
deployment descriptor without a standard name.
Web service deployment descriptor
This deployment descriptor defines the Web services to deploy in a J2EE
container and defines the mapping between WSDL ports and port components.
The deployment information is presented in the module-specific deployment
descriptor, ejb-jar.xml or web.xml, and in the Web service deployment
descriptor.
Example 5-2 shows a sample webservices.xml file.
Example 5-2 webservice.xml of Weather service
<webservices>
<webservice-description>
<webservice-description-name>
WeatherForecastService
</webservice-description-name>
<wsdl-file>META-INF/wsdl/WeatherForecast.wsdl</wsdl-file>
<jaxrpc-mapping-file>
META-INF/WeatherForecast_mapping.xml
</jaxrpc-mapping-file>
90
WebSphere Version 5.1 Web Services Handbook
<port-component>
<port-component-name>WeatherForecast</port-component-name>
<wsdl-port>
<namespaceURI>http://session.itso</namespaceURI>
<localpart>WeatherForecast</localpart>
</wsdl-port>
<service-endpoint-interface>
itso.session.WeatherForecast_SEI
</service-endpoint-interface>
<service-impl-bean>
<ejb-link>WeatherForecast</ejb-link>
</service-impl-bean>
</port-component>
</webservice-description>
</webservices>
Each Web service used by a client has to be defined in a
webservice-description element. A webservice-description element has:
Service name
The unique name of the WSDL service. This name is the
same name of the wsdl:sevice element. In our example,
WeatherForecastService.
WSDL file
The location of the WSDL description of the service. In
our example, META-INF/wsdl/WeatherForecast.wsdl.
JAX-RPC mapping
The location of the WSDL-Java mapping file. In our
example, WEB-INF/WeatherForecast_mapping.xml.
Port
The port component defines the server view, providing
the access point and implementation details.
name
The unique name of the WSDL port element for this
service. This name is the same name of the wsdl:port
element. In our example, WeatherForecast.
qname
The qualified name of the referenced WSDL port. In our
example, the namespace URI is http://session.itso
and the port is WeatherForecast.
SEI
The fully qualified class name of the service endpoint
interface. In our example,
itso.session.WeatherForecast_SEI.
bean class
The implementation name of the Web service. In our
example, WeatherForecast. This name must match the
name of the ejb-name element stated in the ejb-jar.xml
file. For the Web container programming model the
servlet-link element is used in the webservices.xml
Chapter 5. Implementing Enterprise Web Services (JSR 109)
91
and the name must match the name of the servlet-name
stated in the web.xml file.
Handlers
The handlers associated with the Web service reference.
In our example, there is no one.
JAX-RPC mapping deployment descriptor
This deployment descriptor contains the mapping information between the
WSDL definition and the Java interfaces. There are not differences from the
deployment descriptor of the client, because both of them are mapping to the
WSDL file that it is the same for both sides.
Please refer to “JAX-RPC mapping deployment descriptor” on page 83 for a
JAX-RPC mapping deployment descriptor explanation.
Roles
There are no new J2EE roles defined for the JSR 109 specification. The roles are
mapped to existing J2EE roles. The three roles presented in the JSR 109 are:
Developer—Responsible for service definition, implementation, and
packaging within J2EE modules
Assembler—Responsible for assembling the modules into an application
Deployer—Responsible for publishing the deployed services and resolving
server references
More detailed descriptions of the roles’ responsibilities are shown in Table 5-2.
Table 5-2 Roles’ responsibilities for server side
Developer
92
Service
implementation
Implement the
server.
May implement
handlers.
WSDL
Provide WSDL
document.
Web services
DD
Provide port
components
definitions.
May define handler
references.
WebSphere Version 5.1 Web Services Handbook
Assembler
Deployer
Resolve endpoint
addresses.
Resolve module
dependencies.
May configure
handlers.
Assemble modules in
an EAR file.
Developer
JAX-RPC
mapping DD
Assembler
Deployer
Provide the
mapping.
Application
server
Deploy the
application.
Handlers
Handlers provide a mechanism for intercepting the SOAP message. The use of
handlers is allowed in both sides, client and server, and has to be transport
independent. A handler can examine and potentially modify the content of a
SOAP message.
A handler can operate in both directions of a message. A handler can preprocess
a message before this one arrives to the business logic of a Web service or a
client. A handler can also post process a message later on in the business
process, but before the message is sent to its receiver.
A handler is always associated with a particular port component and is
processed in a strict order, called a handler chain. Handlers can manage
encryption and decryption, logging, auditing and so forth. The client and server
have to agree on the functionality of these handlers.
A handler’s life cycle is controlled by the container and, thus, runs under the
execution context of the application. Handlers have access to the resources and
environment variables. Handlers cannot divert a message and cannot modify the
WSDL operation and the part types associated with that operation.
The handler life cycle is shown in Figure 5-6.
The container uses the init and the destroy methods to notify a handler
instance of a change in its state. Once the container has called the init method,
the handler is ready for dispatching a request using the handleRequest,
handleResponse and handleFault methods.
Chapter 5. Implementing Enterprise Web Services (JSR 109)
93
does not exit
1. newInstance()
2. init()
handleRequest()
handleResponse()
handleFault()
Action initiated by
the container
destroy()
method
ready
Figure 5-6 Life cycle of a handler
Security
The security specifications provided by the JSR 109 are not based on
WS-Security specification. The security is based in the J2EE security and only
valid for a specific communication protocol, HTTP, to which the specification is
designed. The inclusion of security credentials in the SOAP message is left for
future works.
Authentication—Basic authentication is provided in the HTTP header of the
message.
Authorization—Is provided by the J2EE container, securing the HTTP POST
access of the JAX-RPC service endpoint.
Integrity and confidentiality—Relies on the HTTPS protocol.
For more information on Web service security refer to Chapter 11, “Web services
security” on page 185.
SRJ 109 implementations in WebSphere
WebSphere Application Server 5.0.2 and 5.1 provide implementations for JSR
109 for JavaBean and EJB Web services. Both SOAP over HTTP and SOAP
over JMS are supported.
94
WebSphere Version 5.1 Web Services Handbook
SOAP over HTTP
Figure 5-7 shows the implementation of SOAP over HTTP:
The client request to the Java proxy is handled by the SOAP client and is
routed to the server over HTTP.
In the server, the WebSphere SOAP Engine calls a JavaBean Web service as
a servlet, or uses a servlet in a Web router module to invoke an EJB Web
service.
Application Server
J2EE Client
Java Client
WSDL
EJB
session
Servlet
Web Router
Web
Service
Java Proxy
Web Services Engine
SOAP Client
HTTP Client
Web
JavaBean
SOAP
HTTP Server
Figure 5-7 JSR 109 with SOAP over HTTP
SOAP over JMS
Figure 5-8 shows the implementation of SOAP over JMS:
The client request to the Java proxy is handled by the SOAP client and is
placed into a JMS queue through a JMS sender.
In the server, a message-driven EJB (MDB) listens to the JMS queue and
routes the message to the WebSphere SOAP Engine.
The WebSphere SOAP Engine invokes an EJB Web service.
Replies to the client are currently not supported.
Chapter 5. Implementing Enterprise Web Services (JSR 109)
95
Application Server
J2EE Client
Java Client
Java Proxy
WSDL
EJB session bean
Web
Service
Reply
Web Services Engine
SOAP Client
Queue
JMS Sender
EJB
MDB
Listener
Figure 5-8 JSR 109 with SOAP over JMS
Summary
In this chapter we have presented the Web services for J2EE specification, JSR
109. This specification standardizes the deployment of Web services and Web
services clients in a Java 2 Platform, Enterprise Edition (J2EE).
We have reviewed the new concepts, interfaces, and file formats introduced by
the JSR 109 specification. We have introduced the requirements to create a Web
service client, analyzing its different phases, deployment characteristics, life
cycle, and roles.
We have introduced the deployment of Web service in a similar way and
discussed the two runtime possibilities developed by the specification:
EJB container
Web container
Finally, we have also introduced the handlers to show the role played by them in
the JSR 109 specification, and described the poor quality standard security
offers around Web services.
96
WebSphere Version 5.1 Web Services Handbook
More information
The best source for more information is the Web Services for J2EE specification,
JSR 109, which can be download from:
http://www-124.ibm.com/developerworks/downloads/index.php?group_id=116
There is also a foundation article that helps to understand the JSR 109:
Build interoperable Web services with JSR-109
http://www-106.ibm.com/developerworks/webservices/library/ws-jsrart/
Chapter 5. Implementing Enterprise Web Services (JSR 109)
97
98
WebSphere Version 5.1 Web Services Handbook
6
Chapter 6.
Introduction to UDDI
This chapter provides an introduction to universal description, discovery, and
integration (UDDI), as well as some advanced topics. We describe UDDI Version
2.0.4, followed by a preview of Version 3.
Version 2 of UDDI is implemented by the major UDDI registries currently in
production. UDDI V2 is also supported by the Web services tooling in Application
Developer Version 5.1 and a private UDDI V2 registry implementation is shipped
with WebSphere Application Server Network Deployment Version 5.1.
In this chapter we discuss the following topics:
UDDI overview
New features in UDDI Version 2
UDDI repositories on the Web
Web front-ends for registries
Java API for dynamic UDDI interactions
Private UDDI registries
Future of UDDI Version 3
© Copyright IBM Corp. 2003, 2004. All rights reserved.
99
UDDI overview
UDDI stands for universal description, discovery, and integration, and is the
name for a specification that defines a way to store and retrieve information
about a business and its technical interfaces, in our case Web services. One
implementation of this specification is the UDDI Business Registry, or UBR. This
is a group of Web-based UDDI nodes, which together form a UDDI registry.
These nodes are run on separate sites by several companies and can be used by
anyone who wants to make information available about a business or entity, as
well as anyone who wants to find that information.
A UDDI registry makes it possible to discover what technical programming
interfaces are provided for interacting with a business for such purposes as
electronic commerce, information retrieval, or others.
UDDI addresses a number of business problems. First, it helps broaden and
simplify business-to-business (B2B) interaction. For the manufacturer who needs
to create many relationships with different customers, each with its own set of
standards and protocols, UDDI provides a highly flexible description of services
using virtually any interface. The specifications allow the efficient and simple
discovery of a business and the services it offers by publishing them in the
registry.
UDDI is based on existing standards, such as XML and SOAP. It is a technical
discovery layer. It defines:
The structure for a registry of service providers and services
The API that can be used to access registries with this structure
The organization and project defining this registry structure and its API
In fact, UDDI is a search engine for application clients rather than human beings;
however, many implementations provide a browser interface for human users.
The central source of information about UDDI is the Web site:
http://www.uddi.org
This site is operated by OASIS, which is a not-for-profit, global consortium that
drives the development, convergence, and adoption of e-business standards.
Static versus dynamic Web services
You often read about static and dynamic Web services. Static Web services
mean that the service provider and the service requestor know about each other
at design time. There is a WSDL document that was found in a UDDI registry,
or—more often—directly sent to the client application developer by the provider
100
WebSphere Version 5.1 Web Services Handbook
for further use in the development tool. During runtime it is very clear (mostly
hard coded) what the URL (access point) of the partner is.
Dynamic Web services describe the fact that at design and development time the
client does not know the explicit server and business entity where it will invoke a
service. The client only knows an interface to call, and finds one or more
concrete providers for that kind of service through exploring UDDI registries at
runtime.
UDDI registry structure
There are several types of information that have to be stored in such a registry,
including information about the company—in UDDI called a business entity—that
offers services, as well as the description of each service including interface
specifications and pointers to servers where those services can be invoked.
The data to be stored can be divided into six types of information that build up the
data model of the registry:
Business entity—The list of business entities is similar to the white and
yellow pages. A business entity describes a company or organization. Those
entities provide information such as business name, contacts, descriptions,
identifiers, and categorization.
Business service—This is non-technical information about a service that is
provided. A business service is a descriptive container used to group a set of
Web services related to a business process or group of services. Also,
categorization is available on this level. A business service maps to a WSDL
service.
Binding template—This contains service access information. These are the
technical Web service descriptions relevant for application developers who
want to find and invoke a Web service. In many cases a binding template
points to an implementation address (for example, a URL) and maps to a
WSDL port. This entity is sometimes also called an access locator.
tModel—A tModel (technical model) is a technical fingerprint holding
metadata about type specifications, as well as categorization information. Its
attributes are key, name, optional description, and URL. The simplest tModel
contains some text characterizing a service.
One type of tModel is sometimes referred to as a service type. In this case,
the tModel points to a service description document (for example, through a
URL). The type specification itself, which can be a WSDL document or any
other formal specification, is not part of the UDDI model.
Taxonomy—A taxonomy is a scheme for categorization. There is a set of
standard taxonomies, such as the North American Industry Classification
Chapter 6. Introduction to UDDI
101
System (NAICS) or the Universal Standard Products and Services
Classification (UNSPSC). In specific circumstances you can publish your own
taxonomies, but this is typically not possible using the Web client or publishing
APIs because it needs special authorization and actions by the UDDI registry
operator. The UDDI registry included with WebSphere Application Server
Version 5.0.2 and 5.1 introduces the ability to add user-defined taxonomies.
UDDI Version 3 uses the term value set for taxonomy.
Publisher assertions—These are also called business relationships. There
are different kinds of relationships: Parent-child, peer-peer, and identity. This
makes it possible to model complex businesses, such as subsidiaries,
external business partners, or internal divisions.
Figure 6-1 displays this data model with the entities introduced above. It also
shows their relationships and the link to the WSDL documents.
Business
Entity
Publisher
Assertion
contains
points to
1
n
Business
Service
Taxonomy
(Categorization)
Keyed
Reference
1
n
Binding
1
Template
m
n
find
tModel
(ServiceType)
1
n
0..1
0..1
Access Point
(URL)
WSDL
Document
Figure 6-1 UDDI entities and their relationships
The business entity tops the containment hierarchy, containing one or more
business service entities. Those services in turn contain binding template
entities. The tModel instances (service types) are not contained by the business
entity, but referenced by the binding template entities.
102
WebSphere Version 5.1 Web Services Handbook
A binding template points to an access point URL where the service can be
invoked. This is a common use of the binding template, but not required. The
binding template could point to a phone number as a contact point.
A service type entity (tModel) has a reference to a Web service type
specification, which typically is a WSDL document. Note that the UDDI registry
merely contains a URL pointing to the Web site of the service provider where the
document can be found, not the WSDL document itself.
Businesses, services, and tModels can contain zero to many references to
taxonomy entries to categorize their content.
WSDL references are implemented as URLs; therefore, any other specification
format can easily be supported as well. UDDI is not bound to WSDL. In general,
you do not work with WSDL files at all when working with UDDI registries.
There is an m:n relationship between the binding template and the tModel. Keep
in mind that a tModel is just a technical fingerprint containing quite abstract
metadata. Even if a service points to several tModels, it does not necessarily
have to implement multiple interfaces on a technical level.
The UDDI data model is designed to be flexible. Hence, there can be more than
one technical description for one service (a formal specification and a supporting
tutorial, for example) and vice versa, one tModel can be used to describe several
similar business services.
The possibility for the requestor to dynamically bind to a provided service through
a given tModel is a real benefit of the Web service architecture.
Interactions with UDDI
Using UDDI registries in general contains three different tasks, because on one
side there are service providers who want to publish some information, and on
the other side there are service requestors who want to find some services and
finally use them. So the tasks using a UDDI registry are:
Publishing information
Finding information
Using the obtained information
These typical steps of interacting with a UDDI registry are illustrated in
Figure 6-2.
Chapter 6. Introduction to UDDI
103
1
Companies and
organizations
describe
themselves
Companies and
organizations
publish their
services
UDDI Registry
Services,
bindings,
tModels
Business
entities
3
WSDL
WSDL
WSDL
WSDL
Client applications
retrieve WSDL file
and invoke
remote Web
services
2
Human users and
client applications
search for
business entities
Human users and
client applications
search for
services
Figure 6-2 Interactions with UDDI registries
Publishing information
There are the six types of information that can be published to UDDI registries:
Business entity information
Business service information
Binding templates
tModels
Taxonomy information
Publisher assertions (business relationships)
Finding information
After business entities have published their entity descriptions and services,
clients (service requestors) might try to find this information.
Clients have a number of possible ways to explore a registry. Either humans do
that by using HTML clients of the registry, or applications use UDDI APIs to do
that automatically, as described in “Java API for dynamic UDDI interactions” on
page 114.
104
WebSphere Version 5.1 Web Services Handbook
In any case, the most likely strategy will be one of the following:
Find concrete business entities and explore their services.
Find services of a certain type regardless of which entity provides them.
Using the information
After finding the services, the final step is to use the service that was obtained by
the exploration step. This is typically done by accessing the service provider
using the interface (messages and parameters) found in the downloaded WSDL
file, and the access point information (URL). Details on this step are described in
the second part of this book.
UDDI support in WebSphere Application Server
A version of the UDDI registry that supported Version 2 of the specification runs
on WebSphere Application Server Version 5.0.2 and 5.1 and it shipped with
WebSphere Application Server Network Deployment.
Advanced features of UDDI
In this section we describe the enhancements provided with UDDI Version 2.
Important: The UDDI Version 2 API is not fully backward compatible to UDDI
Version 1; some programs accessing a UDDI registry may not run correctly.
Modeling features for complex business entities
This feature allows companies that might be spread over several countries to
present themselves as many business entities that are related to each other.
There are different kinds of relationships: Parent-child, peer-peer, and identity.
This makes it possible to model relationships such as subsidiaries, external
business partners, or internal divisions.
Also, the inquiry API offers new functions, such as find_relatedBusinesses, to
allow searches for related businesses of one company.
The feature called service projection allows one business entity to reference a
service that another (related) business entity offers. So it is possible to define a
service that is offered by, for example, more than one department of a large
company. The creator of a projected service is not allowed to alter anything in
that service, but to the service requestor it looks as if the service is owned by that
business entity.
Chapter 6. Introduction to UDDI
105
External taxonomies
In Version 1 there were only three taxonomies that could be used to categorize
services: NAICS (North American Industry Classification System), UNSPSC
(international project and service categorization), and geographic taxonomies.
These categorization standards were checked internally in the UDDI registry to
avoid the setting of invalid codes.
In Version 2 there is the possibility for companies to specify their own external
taxonomy, which is not checked internally by the UDDI server. The provider of the
taxonomy must also offer a standardized Web service to validate values against.
The use of external taxonomies is a controlled process, so the UDDI Business
Registry operator has to approve it.
Powerful inquiry
The inquiry API allows the dynamic exploration of the UDDI registry, especially
the search for services. This API was extended to support more powerful
features dealing with more complex query requirements.
Combining categories
The combineCategoryBags qualifier allows you to group all of the taxonomy data
associated with a business and all of its contained services (including any
service projections) into a single collection that the search is performed against.
This is useful because it reduces the steps in finding a business of interest by
looking in both the business and its constituent services at the same time. So you
could, for example, in one step look up services that are categorized both as
Construction, as per NAICS, and contain a geographic locator such as AT,
stating that it is an Austrian company.
Advanced search using categorization
Similarly, the serviceSubset filter allows you to search for businesses using
taxonomy criteria, which are tested only against the categorizations associated
with a business' constituent services. Categorizations associated with the
business itself are not included in the search.
Qualifier for searching
Finally, the orLikeKeys qualifier is particularly useful because it enables
pseudo-complex queries. It allows you to combine search criteria with OR and
not only with AND. For example, you can find businesses located in the United
States, Mexico, or Canada that also offer cold storage or generic shipping
services. This enables you to search for businesses that are categorized with
106
WebSphere Version 5.1 Web Services Handbook
different levels of specificity, while at the same time allowing a single inquiry to
reference multiple different taxonomies.
Internationalization features
Services and business entities can have language-dependent names. There
must be at least one name in any language, but you can also provide different
translations for both business entities and your services.
A new type of taxonomy, postalAddress, allows you to specify addresses in
different international formats.
Peer-based replication
As the number of UDDI registries increases, a simple file-based replication
scheme is not appropriate anymore. The new peer-based replication features do
not require that each UDDI registry has to communicate with all the others for
replicating the information.
UDDI Business Registry on the Web
Currently there are four organizations hosting nodes in the UDDI Business
Registry. All four of the nodes are replicated and therefore contain the same
information. Most of the companies also host a test registry in addition to the
business registry. Those test instances can be used by anyone for test purposes.
Web services found there are often subject to change and lack of availability.
They are not meant for production use.
Table 6-1 specifies three URLs for each registry. The first is the URL for the Web
client that can be used by humans for exploring and publishing any information.
Typically you have unlimited access for reading information and need some sort
of registration for publishing information.
Besides the Web client URL, you also find URLs for API access using a UDDI
API implementation, such as UDDI4J, as described in “Java API for dynamic
UDDI interactions” on page 114. There are always two different URLs for inquiry
(reading information) and publishing (writing information). The latter one is using
HTTPS as a secure connection to ensure that the publishing information is not
corrupted or altered.
Chapter 6. Introduction to UDDI
107
Table 6-1 UDDI registries
Hosting
organization
Access
type
URL
IBM
Business
Registry
Web
http://uddi.ibm.com
Inquiry
http://uddi.ibm.com/ubr/inquiryapi
Publish
https://uddi.ibm.com/ubr/publishapi
Web
http://uddi.ibm.com/testregistry/registry.html
Inquiry
http://www-3.ibm.com/services/uddi/testregistry/inq
uiryapi
Publish
https://uddi.ibm.com/testregistry/publishapi
Web
http://uddi.microsoft.com/
Inquiry
http://uddi.microsoft.com/inquire
Publish
https://uddi.microsoft.com/publish
Web
http://test.uddi.microsoft.com/
Inquiry
http://test.uddi.microsoft.com/inquire
Publish
https://test.uddi.microsoft.com/publish
Web
http://uddi.sap.com/
Inquiry
http://uddi.sap.com/uddi/api/inquiry
Publish
https://uddi.sap.com/uddi/api/publish
Web
http://udditest.sap.com/
Inquiry
http://udditest.sap.com/UDDI/api/inquiry
Publish
https://udditest.sap.com/UDDI/api/publish
Web
http://www.ntt.com/uddi/
Inquiry
http://www.uddi.ne.jp/ubr/inquiryapi
Publish
https://www.uddi.ne.jp/ubr/publishapi
IBM Test
Registry
Microsoft
Business
Registry
Microsoft
Test Registry
SAP
Business
Registry
SAP Test
Registry
NTT
Business
Registry
In general, all of the UDDI registry nodes have the same functionality, although
there are significant differences in user interface and usability. Functions that are
typically performed by users are:
Find businesses, services, and tModels:
– By name
108
WebSphere Version 5.1 Web Services Handbook
– By categorization
– By key (UUID)
Browse through businesses, services, and tModels:
– Show services for businesses
– Show binding informations for services
– Show tModels for services
Publish/change/unpublish:
–
–
–
–
Business entities
Business relationships
Services
tModels
Web front ends for registries
Each of the UDDI registries listed above has its own Web interface for human
users. They have very different user interfaces with a different look and feel, and
therefore the usability varies. The functionality itself is the same for all of them,
since they are all implementing the UDDI Version 2 features.
As an example, we introduce the Web client of the IBM UDDI Registry.
When accessing the site using http://uddi.ibm.com, you reach a page with
several links to articles regarding UDDI. You can choose between the business
registry and the test registry using the linked images on the right. After you have
chosen the UDDI registry, you will find the tasks on the left-side menu, for
example, Find and Register.
Note: A reading task—for example, finding businesses or services—does not
require a registration. Whenever you want to publish some information about
your business, service, or interfaces, you have to register. This is, in general,
free and requires just your name, country of residence, and a valid e-mail
address.
Finding information
If you want to find published UDDI information, you can choose between a set of
finders, depending on what you are searching on, as shown in Figure 6-3. The
simple approach is just to specify the type of entry you are looking for and a
string that is contained in the name of that entry.
Chapter 6. Introduction to UDDI
109
For more advanced searches you can use one of the links named Find a
Business/Service/Technical Model, which allows you to use categorization
information and combinations of search criteria.
Figure 6-3 Options for searching the UDDI registry
After you have successfully submitted a search query, you can navigate through
the results, such as displaying services that were published by a specific
business, or showing services that implement a certain tModel specification, and
so on.
Important: Unfortunately, there are a large number of experimental and test
entries not only in the test registry, but also in the official business registry. So
when locating services be sure you do not try to call a service with access
points showing server names such as localhost, and be aware that there is no
guarantee about availability of the services.
Figure 6-4 shows an example of a service found in UDDI with detailed
information that might be interesting to the client of the service. First of all, there
is a unique ID (UUID) specifying the service, as well as the business owning the
service, including its key. You could also use these keys in the advanced search
feature.
Names and descriptions of services can be specified in several languages. You
will find the entries of all languages in the details view, including an ISO code of
the language used. Two essential pieces of information are the access points
and service locators. The first one is a pointer to concrete implementations of this
service. The latter one describes the service using categorizations (taxonomies).
110
WebSphere Version 5.1 Web Services Handbook
Figure 6-4 Exploring details of a published service
Note: The UDDI registry does not contain only Web services. For example,
IBM also publishes other services, such as phone numbers and URLs for Web
sites, where to order IBM products, and e-mail addresses.
Once you have identified a Web service you want to use, you can follow the
tModel link to download the WSDL file. This WSDL file includes all the necessary
interface descriptions that can be used by such tools as WebSphere Studio
Application Developer to develop client applications that call the Web service
statically. The binding template link provides the URL where you invoke the Web
service.
Chapter 6. Introduction to UDDI
111
Publishing information
The second task you might want to do using UDDI registries is to publish your
company’s information and services, so that potential clients can use your
services.
After you have selected the desired registry and have successfully logged in, you
will find an additional menu item on the left side called Publish. By clicking that,
you reach a window with all the items that you ever published into the registry
using this user name.
The typical order in which you publish your information is the following:
1. Define a business.
Describe your company or organization, and optionally assign some
categorizations, describe your business domain, and add relationships to
other business entities.
2. Define tModel(s).
Define technical models, referencing WSDL files for Web services or simpler
tModels such as mailto or ftp. Note that a tModel does not always reference a
WSDL file on a provider’s site. tModels contain a unique key, a description,
and classification locators. If a business provides public access to a WSDL
file, it makes sense to specify that URL in the tModel description.
3. Define services and bindings.
Finally define your services. They consist of a name, key, and some
descriptive information. You also immediately provide the binding information,
which in general is composed of an access point, where the service can be
activated, and binding details such as the protocols used to connect (for
example, SOAP over HTTP). You also have to reference one or more tModels
to describe your interface.
The path through the different steps is quite straightforward and not described in
more detail here. There is only one interesting fact to point out:
When looking at the publishing window, you will immediately find your
business entities, relationships, and tModels, including all the links to create
new ones. But you do not initially see the business services. This is because
a service (other than tModels) can only exist for a specific business entity. So
you have to first expand one business entry to see the definitions and links
regarding services (Figure 6-5).
112
WebSphere Version 5.1 Web Services Handbook
Figure 6-5 Expanding business entities to explore or define services
When you have finished defining your entities, services, and tModels, your
publishing window looks like Figure 6-6.
Figure 6-6 Overview of published items
Chapter 6. Introduction to UDDI
113
Java API for dynamic UDDI interactions
As described above, it is possible to use UDDI repositories as a human user by
using Web front ends. A second possibility is to explore them using client
applications. Therefore there is a standardized set of APIs defined for each
version of UDDI registries.
There are many implementations of that API. For example, Microsoft provides a
UDDI SDK that is a collection of client development components, sample code,
and reference documentation that enables developers to interact
programmatically with UDDI-compliant servers. This is available for Visual Studio
.NET and separately for Visual Studio 6.0 or any other COM-based development
environment.
A number of companies, such as IBM, HP, and SAP, officially support the UDDI4J
implementation, which we discuss in the following section.
UDDI4J overview
UDDI4J is a Java class library that provides support for an API that can be used
to interact with a UDDI registry. This class library provides classes that can be
used to generate and parse messages sent to and received from a UDDI server.
Note: The UDDI4J API can be used against any of the registries (Business
Registry, test registry, private UDDI registry of WebSphere Version 5).
The central class in this set of APIs is org.uddi4j.client.UDDIProxy. It is a proxy
for the UDDI server that is accessed from client code. You can use this proxy to
interact with the server and possibly find and download WSDL files. You might
then want to use such APIs as WSDL4J or Apache Axis to interpret these
WSDLs and invoke remote Web services. This section describes the first part,
which is exploring and publishing to the UDDI.
Detailed information as well as download possibilities (including source code)
can be found at:
http://www.uddi4j.org
The important packages are:
org.uddi4j.datatype
This package contains classes used to send or receive UDDI information.
114
WebSphere Version 5.1 Web Services Handbook
org.uddi4j.request
This package contains messages sent to the server. These classes are
typically not used directly; rather the UDDIProxy class uses these classes.
org.uddi4j.response
This package represents response messages from a UDDI server.
Prerequisites
Clients written using UDDI4J require a Java runtime environment of at least
Version 1.2.2 and a SOAP transport, which at the moment can be one of the
following:
Apache Axis
Apache SOAP 2.3
HP SOAP
The WebSphere Version 5.0.2 Web services runtime is currently not a SOAP
transport that can be used by UDDI4J on the client side, even though the UDDI
registry (server side) itself could be running inside a WebSphere 5.0.2 runtime.
Using the library
You have to do some preparations to use the UDDI library. First you have to
specify a set of system properties where you define which SOAP implementation
you are using and if there are proxies to cross.
If you not only want to explore a UDDI server but also want to publish
information, you have to activate the HTTPS transport protocol by adding an
implementation of JSSE to your class path. Refer to the documentation on the
UDDI4J Web site for detailed information.
Writing UDDI clients
A typical application client to UDDI registries consists of three parts:
Connect to the server by creating a proxy object.
Find entities using this proxy.
Publish entities using this proxy.
Creating a proxy object
When writing a UDDI client you typically first create a UDDIProxy object by setting
the server URLs to access, as shown in Figure 6-7.
The concrete values for the inquiryURL and publishURL are dependent on the
UDDI registry you use and can be obtained from Table 6-1 on page 108.
Chapter 6. Introduction to UDDI
115
// --- Add SSL support (only needed for publishing)
System.setProperty("java.protocol.handler.pkgs",
"com.ibm.net.ssl.internal.www.protocol");
java.security.Security.addProvider(new com.ibm.jsse.JSSEProvider());
// --- Create UDDI proxy
UDDIProxy uddiProxy = new UDDIProxy();
uddiProxy.setInquiryURL(inquiryURL);
uddiProxy.setPublishURL(publishURL);
// --- Cache authorization token for publishing
AuthToken token = proxy.get_authToken("userid", "password")
Figure 6-7 Creating a UDDI proxy object
Finding information
Once you have created a proxy object, you can easily find any kind of
information, such as business entities, services, bindings, or tModels.
Finding business entities
The find_business method is used to find business entities by name. The
method returns a BusinessList object, a collection that can be used to find
specific information about all of the businesses that match the search parameter.
BusinessList UDDIProxy.find_business(
java.util.Vector names,
DiscoveryURLs discoveryURLs,
IdentifierBag identifierBag,
CategoryBag categoryBag,
TModelBag tModelBag,
FindQualifiers findQualifiers,
int maxRows)
Parameters:
names—A vector of names. You can use the % character as a wildcard.
discoveryURLs—This is a list of URLs to be matched against the data
associated with the discoveryURLs contents of registered business entity
information. The returned BusinessList contains BusinessInfo structures
matching any of the URLs passed (logical OR).
identifierBag—This is a list of business identifier references. The result
contains businesses matching any of the identifiers passed (logical OR).
categoryBag—This is a list of category references. The result contains
businesses matching all of the categories passed (logical AND).
116
WebSphere Version 5.1 Web Services Handbook
tModelBag—The registered business entity data contains binding templates
that in turn contain specific tModel references. The tModelBag argument lets
you search for businesses that have bindings that are compatible with a
specific tModel pattern. The result contains businesses matching all of the
tModel keys passed (logical AND). tModel key values must be formatted as
URN-qualified UUID values prefixed with "uuid:".
findQualifiers—Can be used to alter the default behavior of search
functionality
maxRows—Allows the requesting program to limit the number of results
returned
Finding services
To find a service using whatever search criteria, you use the find_service
method:
ServiceList UDDIProxy.find_service(
java.lang.String businessKey,
java.util.Vector names,
CategoryBag categoryBag,
TModelBag tModelBag,
FindQualifiers findQualifiers,
int maxRows)
This function returns a ServiceList on success. In the event that no matches
were located for the specified criteria, the ServiceList structure returned will
contain an empty structure.
Parameters:
businessKey—This optional uuid_key is used to specify a particular business
entity instance. This argument may be used to specify an existing business
entity in the registry or may be specified as "" (empty string) to indicate that all
business entities are to be searched.
names—This optional vector of names represents one or more partial names.
A wildcard character % may be used to signify any number of any characters.
Up to five name values may be specified. If multiple name values are passed,
the match occurs on a logical OR basis within any names supplied.
categoryBag—This is a list of category references. The returned ServiceList
contains BusinessService structures matching all of the categories passed
(logical AND by default).
tModelBag—This is a list of tModel uuid_key values that represent the
technical fingerprint of a BindingTemplate structure to find. If more than one
tModel key is specified in this structure, only BusinessService structures that
contain BindingTemplate structures with fingerprint information that matches
all of the tModel keys specified will be returned (logical AND only).
Chapter 6. Introduction to UDDI
117
findQualifiers—Used to alter the default behavior of search functionality.
maxRows—Allows the requesting program to limit the number of results
returned.
Finding tModels
To find tModels, use the find_tModel method. This method is for locating a list of
tModel entries that match a set of specific criteria. The response will be a list of
abbreviated information about tModels that match the criteria (tModelList).
TModelList UDDIProxy.find_tModel(
java.lang.String name,
CategoryBag categoryBag,
IdentifierBag identifierBag,
FindQualifiers findQualifiers,
int maxRows)
Parameters:
name—This string value represents a partial name. Because tModel data only
has a single name, only a single name may be passed. A wildcard character
(%) may be used. The returned tModelList contains tModelInfo elements for
tModels whose name matches the value passed.
categoryBag—This is a list of category references. The result contains
tModels matching all of the categories passed (logical AND by default).
FindQualifiers can be used to alter this logical AND behavior.
identifierBag—This is a list of business identifier references. The result
contains tModels matching any of the identifiers passed (logical OR).
findQualifiers—Used to alter the default behavior of search functionality.
maxRows—Allows the requesting program to limit the number of results
returned.
The three methods enable you to explore businesses, services, and tModels. As
a typical dynamic client, you are not really interested in the name of a business or
a service, but much more in the binding templates that tell you where you can
access a service. A typical scenario would be to search for a binding using a
tModel key, extract the access point, and invoke a service at that URL.
Finding bindings
You can find bindings using the find_binding method:
BindingDetail UDDIProxy.find_binding(
FindQualifiers findQualifiers,
java.lang.String serviceKey,
TModelBag tModelBag,
int maxRows)
118
WebSphere Version 5.1 Web Services Handbook
This method returns a BindingDetail object that contains zero or more
BindingTemplate structures matching the criteria specified in the argument list.
Parameters:
findQualifiers—This collection can be used to alter the default behavior of
search functionality.
serviceKey—Used to specify a particular instance of a BusinessService
element in the registered data. Only bindings in the specific BusinessService
data identified by the serviceKey passed will be searched.
tModelBag—This is a list of tModel uuid_key values that represent the
technical fingerprint to locate in a BindingTemplate structure contained within
the BusinessService instance specified by the serviceKey value. If more than
one tModel key is specified in this structure, only BindingTemplate information
that exactly matches all of the tModel keys specified will be returned (logical
AND).
maxRows—This optional integer value allows the requesting program to limit
the number of results returned.
This function returns a BindingDetail object on success. In the event that no
matches were located for the specified criteria, the BindingDetail structure
returned in the response will be empty and contain no BindingTemplate data.
In all the find methods described above, you can set the parameter maxRows to
define the maximum number of results. There you can also specify 0 in order to
not limit the result. Keep in mind that, in the event of a large number of matches,
an operator site may truncate the result set. If this occurs, the response message
will contain the truncated attribute set to true.
Publishing information
If you want to register some information on a UDDI server, you have to use the
authorization token obtained when creating the proxy.
Figure 6-8 shows how to publish a business entity. This example only fills the
required name field. Of course in real scenarios you might also consider adding
categorization information and descriptions.
Chapter 6. Introduction to UDDI
119
// create business entities and store them in a vector
Vector businessEntities = new Vector();
BusinessEntity be = new BusinessEntity("");
be.setName("IBM ITSO");
entities.addElement(be);
// save the entities on the UDDI server
BusinessDetail bd = proxy.save_business
(token.getAuthInfoString(), entities);
Figure 6-8 Publishing a business entity
The BusinessDetail object returned by the save method holds the unique
identifiers (UUID) that were given to the new entities by the UDDI registry.
Similar to business entities, you can also create business services, and tModels,
by using the classes BusinessService or TModel. Whenever you have to specify
URLs or access points, you also find wrapper classes, such as OverviewURL or
AccessPoint, that provide a very easy and intuitive way to model your registry
entries.
For more details and examples, refer to the UDDI4J documentation and to
several articles published at the library section of the developerWorks site:
http://www.ibm.com/developerworks
Private UDDI registries
The first implementation of UDDI was the business registry, which sometimes is
also called the UDDI cloud. This cloud consists of nodes operated by IBM,
Microsoft, SAP, and others, which are replicated and hold exactly the same
information. They can be accessed by everyone, both for exploring information
as well as publishing information.
But in fact there are other usage scenarios that seem to gain even more
importance than the public registry, namely totally or partly private UDDI
registries. There are a number of possible requirements that encourage
companies and organizations to establish those UDDI registries outside the
cloud.
Motivation for the use of private UDDI registries
There are a number of problems that arise in some environments when using
public UDDI registries, especially the business registry.
120
WebSphere Version 5.1 Web Services Handbook
Need for privacy
One requirement is that companies often do not want to show all of their
interfaces to the whole world, and therefore also open the possibility that
everyone can (try to) communicate with their services.
Getting rid of UDDI pollution
Because the UDDI cloud is public and free to be used by everyone, it is obvious
that there is often inaccurate, outdated, wrong, or misleading information in the
registries. There is no concept of expiration date for published information or any
review mechanisms to ensure the quality of the content. This is a problem similar
to Web sites on the Internet, with the main difference being that the users of Web
sites are human and should be able to easily separate good or usable content
from bad content. The clients of UDDI registries are often applications. This fact
can lead to severe problems.
Standards and guidelines
In UDDI you can publish businesses or services with very little information, and
when entering URLs for access points, you can specify WSDL files, as well as
Web sites, or documents that describe a service in prose. This is allowable in
UDDI and may be exactly what is required in some cases.
However, to make automatic (application client) inquiries (dynamic Web services)
easier, you might want to set up some standards restricting the information that is
set on specific places of the registry.
Possible scenarios for private UDDI registries
In this section we list some scenarios where private registries are suitable.
Internal registry
A company or organization might want to consider a totally private registry, which
resides inside the firewall and can only be accessed from inside the intranet, both
programmatically and Web-based.
This scenario helps large organizations to provide internal services for other
departments and divisions. It is very easy to mandate guidelines and restrictions,
because no other company interacts with your registry.
e-marketplace UDDI registries
Another scenario could be a registry that is in fact totally public, but specializes in
a very specific topic, or a group of companies, or an industry. Those registries
would be perfect candidates for using specialized taxonomies, which have been
supported since UDDI Version 2.
Chapter 6. Introduction to UDDI
121
For example, the automotive industry might consider setting up a specialized
registry with their own detailed categorization system.
Another advantage would be to restrict the usage to some special set of tModels.
In order not to allow every company to publish their own service interfaces, the
organization hosting the registry might want to consider defining standardized
tModels and WSDLs that are supported by this registry.
Using those specialized registries would very much increase the possibility of
automatically discovering and invoking Web services by application clients.
Extranet UDDI registries
A third scenario is a usage of UDDI where one company or organization hosts
one registry for the communication between the owning company and the
business partners, so the registry is on the Internet, but access is restricted to
the owning company and partners with previously negotiated business contracts.
This enables a good compromise between the privacy of a company and the
ability to communicate easily with its partners. All the advantages of private
registries apply, keeping the registry clean and uniform.
Benefits of private UDDI registries
The usage scenarios of UDDI registrations are not restricted to the public
business registry already discussed. There are many reasons why an
organization might want to consider establishing a registry that is not part of the
official registries. That makes it possible to restrict one or more of the following
points:
Who is allowed to explore the registry
Who can publish information
What kind of information is published (guidelines, standards)
Another important point about private registries is that the success rate for
dynamic exploration performed by application clients increases dramatically.
Additional considerations for private UDDI registries
There are two considerations when thinking of any registry that is not part of the
central business registry.
122
WebSphere Version 5.1 Web Services Handbook
Propagation
Hosting a private registry does not necessarily mean that there is no propagation
with the business registry. There might be scenarios where it makes sense to do
one-way propagation from the private registry into the cloud. Especially in the
e-marketplace scenario, this could make a lot of sense.
Securing APIs
In each case you might consider enabling or disabling the inquiry and publishing
APIs. So, in the partner scenario it could be required that everyone is allowed to
explore the Web services, but nobody should be able to publish a service except
the hosting company itself.
WebSphere private UDDI registry
A private UDDI registry feature is shipped with WebSphere Application Server
Network Deployment Version 5 and can be installed on a WebSphere server.
Important: Installation and usage of the private UDDI registry is described in
“Implementing a private UDDI registry” on page 503:
Installing the registry in a WebSphere Application Server
Using the UDDI GUI for publish and find operations
Using the UDDI Explorer of Application Developer to access the private
UDDI registry
WebSphere Application Server 5.0.2 update
WebSphere Application Server Version 5.0.2 introduces the ability to add
user-defined taxonomies, with available allowed values presented in the existing
GUI taxonomy tree display.
WebSphere Studio Application Developer Version 5.1 has a Web Services
Explorer user interface that also allows the addition and display of
custom-checked taxonomies. The publisher of a custom taxonomy's
categorization tModel may specify a display name for use in GUI
implementations.
For more information go to:
http://publib.boulder.ibm.com/infocenter/wasinfo/topic/com.ibm.wasee.doc/in
fo/ee/ae/rwsu_tax.html
Chapter 6. Introduction to UDDI
123
WebSphere Application Server 5.1 update
WebSphere Application Server Version 5.1 introduces UDDI utility tools that
provide these functions as commands and as a programmatic API (Figure 6-9):
Export—Export a UDDI entity (or list of entities) from a registry into an entity
definition file (XML format).
Import—Import UDDI entities from an entity definition file or programmatically
into a registry (add entities or update existing entities).
Promote—Combines export and import to copy entities from one registry to
another. Generation of an entity definition file is optional.
Delete—Delete an entity or a list of entities.
Find—Search for matching entities based on inquiry API objects (only
programmatic API). The resulting entity list can be used in subsequent export,
promote, and delete requests.
find
find
delete
entity keys
Source
Registry
get
export
API
promote
entity
definition file
import
delete
publish
Target
Registry
API
Figure 6-9 UDDI utility tools
Future of UDDI Version 3
At the time this book was written, the business registry was implementing the
UDDI Version 2 standard, and WebSphere 5 was also supporting Version 2.
Since July 2002, there has been a new specification of UDDI called Version 3.
The enhancements specified by this new version include multi-registry
topologies, increased security features, improved WSDL support, a new
subscription API, and core information model advances.
Note that some of the features in the UDDI Version 3 specification are optional,
and an implementor can choose not to implement them.
124
WebSphere Version 5.1 Web Services Handbook
Keys assigned by publisher
Every item in a Version 2 UDDI registry, such as business entities, services, and
tModels is assigned a key (UUID), which uniquely identifies that entity within the
registry. In Version 2, copying a UDDI entry from one registry to another and
preserving the unique key is not allowed.
Version 3 of UDDI enables you to copy entries using the same key, because the
key generation feature is extended. The behavior of copying entities is known as
entity promotion. The solution to the problem is that the generation of entity keys
is no longer exclusively performed by registry nodes. Depending on policies,
publishers may request permission to use a partition of the registry’s root
keyspace (using a tModel:keyGenerator request). If this request is successful,
publishers can publish entities by supplying an entity key within the partition they
own. If the publisher supplies a key—if it is allowed by policy—the supplied entity
key is used instead of the node generating a new key.
Human-friendly URI-based keys
Besides the new ability to promote keys across registries, a new format for UDDI
keys is introduced in Version 3. Prior versions mandated that keys had to be a
formatted universally unique identifier (UUID). Version 3 removes this restriction
and recommends the usage of a key scheme based on DNS names. This allows
publishers to establish a key partition of the registry’s root key space and then
generate keys based on that partition. For example, a valid Version 3 key might
look like this:
uddi:mycompany.com:4711
uddi:ibm.com:itso:0815
These human-friendly keys allow organizations to manage their own key space
using internally established conventions and structures.
Complex registry topologies
In order to support these more complex topologies of UDDI registries, there are
new possibilities for setting a UDDI registration in certain relationships to another.
UDDI Version 3 introduces the notions of root and affiliate registries as part of its
guidance on inter-registry associations. The existence of a root registry enables
its affiliates to share data with the root registry and among themselves with the
assurance that keys remain unique.
Chapter 6. Introduction to UDDI
125
Advanced security features
Another advancement is the support for digital signatures. Entities can be
digitally signed to provide better data integrity and authenticity. When exploring
the registry, you can filter for signed entries to be sure you get the originally
published information that came from a trusted source. These digital signatures
are also kept when promoting entities to different registries.
Policies
There are many different scenarios in which a UDDI registry can be used:
Public registry on the Internet
Partly public registry in the extranet
Private registry inside the intranet
Private registry for development (for example, inside Application Developer)
Stable private registry for test areas
Scalable registry for production environments
Each of these registries requires slightly different behavior, because of its
intended use, so there are a set of policies that can be applied to the registry that
changes the actual behavior regarding:
Authorization models
Data custody and confidentiality
Key generation
Value set validation
Subscription
User publication limits
Audit policy
Data model updates
Version 3 also introduces a set of improvements in the data model, which defines
how the entities are stored in the registry. Some of the most important extensions
are:
126
Categorization of binding templates.
More complex categorization features such as derivation of taxonomies.
XML schemas define more precisely the possible values stored in UDDI.
Advanced support for internationalization.
WebSphere Version 5.1 Web Services Handbook
Extended inquiry API
The programmatic exploration was extended to support more complex queries by
nesting queries into one round-trip call. Wildcards can be used more flexibly, and
special result set features allow processing of very large query results. In
addition, more find qualifiers are supported by the API.
Subscription API
The new subscription API includes robust support for notification of changes in
the registry. Users can establish a subscription based on a specific query or set
of entities that the user is interested in. This makes it possible to be notified of
new businesses or services that are registered, as well as to monitor existing
businesses or services.
Registry management
To be more independent of the external taxonomy provider’s server availability
and to improve performance, the UDDI registry contains some caching
mechanisms for external taxonomies. Also, replication between UDDI registries
is improved.
Chapter 6. Introduction to UDDI
127
Summary
UDDI is a standard that provides the ability to use dynamic Web services, which
means that the service requestor and service provider do not necessarily know
about each other up front. An organization that wants to provide some service
publishes this service in any UDDI registry.
There are two ways a client can find a Web service:
This is a human exploring the UDDI at design time, who might search for
service or a WSDL, and use that information when programming the client.
Another possibility would be a programmatic exploration by the client
application, which allows dynamic binding and changing service providers at
runtime.
There are three major points that are often not considered or are misunderstood
when talking about UDDI registries:
UDDI registries cannot only contain details of published Web services, but
also details of other kinds of service, for example, services that cannot be
used programmatically.
There is an increasing need for specialized and partly private registries that
are hosted by standards bodies or industries. In addition, internal intranet
registries (with or without contact to business partners) are gaining more and
more importance.
When publishing or finding tModels, you never publish or store WSDL
interface files. The tModel is just a logical link to a concrete interface. When a
service references a tModel, you cannot directly find out the real interface.
More information
For more information on UDDI, consult the IBM UDDI Web site at:
http://uddi.ibm.com
For general UDDI information, use the Web site at:
http://www.uddi.org
Fir more information about the WebSphere private registry, consult the
WebSphere InfoCenter:
http://publib.boulder.ibm.com/infocenter/ws51help/index.jsp
128
WebSphere Version 5.1 Web Services Handbook
7
Chapter 7.
Web services invocation
framework
In this chapter we introduce the Web service invocation framework (WSIF). It is a
more flexible way to invoke Web services. The developer is no longer restricted
to developing services for particular transport protocols or service environments.
WSIF comes as a Java API that supports either the use of generated stubs or
provides the stub-less and completely dynamic invocation of Web services,
where the binding can be selected and updated at runtime.
Furthermore, WSIF allows late binding, where a new provider and description
are made available at runtime, and the existing client can then utilize the new
implementation.
The chapter is structured as follows:
Motivation of the need for WSIF
General concept, including architecture
Sketch of scenarios where the use of WSIF is reasonable
Current status, outlook, and references
© Copyright IBM Corp. 2003, 2004. All rights reserved.
129
Motivation
As we have pointed out before, the main building blocks for Web services are
SOAP, WSDL, and UDDI. Thus, a straightforward way to implement Web
services is to use just these concepts, which leads to the following binding
procedure: assembling a SOAP message, sending it to the service provider, and
getting a SOAP message back. This protocol has implementations and tools
available in most programming languages. However, using only SOAP has some
drawbacks:
The use of one particular protocol implementation may be too restricting.
A stringent integration of client code to a client library for a particular protocol
implementation can become hard to maintain. For instance, if the developer of
the client code wants to take advantage of new features and bug fixes that
came out in a new version of the transmitting protocol, he or she has to
update all of the client code.
The incorporation of new bindings into client code is complex.
As stated in Chapter 3, “Introduction to WSDL” on page 45, WSDL allows
developers of the service provider code to define bindings for whatever
protocol is available. To incorporate new bindings, the client APIs for using
this protocol would have to be written from scratch. This may be a
time-consuming task, especially if it has to be done repeatedly. Thus, an
invocation mechanism is needed that supports bindings to be updated or new
bindings to be plugged in easily.
A singular binding prevents flexible solutions.
There are cases where a SOAP-based binding is quite inefficient, for
instance, if a local binding directly using Java calls is possible. However, there
might be reasons why the developer wants to make use of the Web services
framework. Thus, it would be favorable to treat the local service
implementation (a Java class) as a Web service. Clients would then have the
ability to switch the binding based on runtime information. So another
requirement to an invocation framework is a mechanism that allows you to
switch between the available service bindings at runtime, without having to
generate or recompile a stub.
Existing transport mechanisms may have technical advantages over SOAP
and may be already established in businesses.
In recent decades, a number of different data transport technologies have
been developed and established that offer more than SOAP does
today—especially in terms of management, transactions, security, and other
quality of service (QoS) features. Many companies have already invested in
technologies, such as CORBA, that they wish to use and keep. Thus, the goal
must be to provide a concept that is so flexible that the transportation protocol
130
WebSphere Version 5.1 Web Services Handbook
can be adapted to the current needs within an application scenario, ideally
even during runtime of the system.
As we have pointed out in Chapter 3, “Introduction to WSDL” on page 45, the
provider of a Web service uses WSDL to describe the properties of the service
he offers. WSDL has been designed to allow multiple implementations for a Web
service, and multiple ports that share the same PortType. For instance, a WSDL
document can be written that allows the same interface to have bindings to
SOAP and, say, IIOP. You can even treat a single Java class as a Web service,
with in-thread Java method invocations as the access protocol.
Having a flexible WSDL description of the service that offers multiple bindings,
you need a framework that allows you to incorporate the service in any way that
the requestor prefers and the provider offers. Thus the following requirements
have to be fulfilled by such a framework:
Provide an API that frees code from the complexities of any particular
protocol used to access a Web service.
Provide a binding-independent mechanism for Web service invocation.
Support dynamic invocation of services by choosing between multiple
bindings to a Web service during runtime.
General concept
The Web service invocation framework (WSIF) is a toolkit that provides all of the
features we have identified in the previous discussion:
It provides an API to bind to and invoke any Web service.
J2SE 1.3 dynamic proxy support is used to generate stubs for the invocation.
WSIF supports the stub-less (completely dynamic) invocation of Web
services.
An updated implementation of a binding can be plugged into WSIF at runtime.
The decision of which binding to use need only be made at runtime.
WSIF provides a WSDL-driven API to invoke Web services.
WSIF enables easy encapsulation of back-end systems connected through
the J2EE Connector Architecture (JCA) as Web services.
The introduction of WSIF leads to a shift in the programming paradigm. The
invocation of a Web service is moved from a binding-centric approach to a more
encapsulated and thus abstract level. This enables service bindings to be viewed
as pieces of code required for invocation according to a particular protocol.
Chapter 7. Web services invocation framework
131
WSIF architecture
In this section we describe the involved components in more detail. In “More
information” on page 140, we point to relevant references that expand on the
description of the architecture.
Provider class
A WSIFProvider is an implementation of a WSDL binding. It can run a WSDL
operation through a protocol that depends on a specific binding. WSIF providers
implement the bridge between the WSIF API and the actual implementation of a
service.
WSIF providers are currently available for SOAP over HTTP, SOAP over JMS,
Java, EJB, and native JMS. New providers can easily be added to the WSIF
framework.
The SOAP provider allows WSIF stubs and dynamic clients to invoke SOAP
services.
JMS is a messaging technology. The mapping to a JMS destination is defined
during deployment and maintained by the container.
The WSIF Java provider allows WSIF to invoke Java classes and JavaBeans.
Local Java code running on a JVM can be incorporated easily.
The EJB provider allows WSIF clients to invoke Enterprise JavaBeans. The
EJB client JAR must be available in the client runtime with the current
provider.
Operation class
The WSIFOperation is the runtime representation of an operation. Based on a
specific binding, it invokes the corresponding service.
Service
The task of WSIFService is to generate an instance of WSIFOperation that is used
for a specific invocation of a service operation.
WSDL documents
The WSDL document specifies the location of the Web service, possible binding
protocols, and formats for operations and messages. Figure 7-1 shows a
fragment of a WSDL document for a fictious service. This fragment offers not just
that SOAP binding, but also a Java binding, and ports for both bindings.
132
WebSphere Version 5.1 Web Services Handbook
...
<binding name="SOAPBinding" type="tns-int:WeatherforecastPT">
<soap:binding style="rpc" transport="http://schemas.xml- soap.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 7-1 Fragment of a WSDL example with multiple bindings
More concepts
More concepts are:
WSIFPort—The task of this class is to perform the actual invocation,
depending on a given binding. For instance, a WSIFSOAPPort has been
designed to use the SOAP binding as it is specified in the WSDL.
Chapter 7. Web services invocation framework
133
WSIFMessage—In WSDL, messages are composed of named parts tied to
some type system, normally an XML schema. To invoke such services, this
schema type is mapped to possibly more sophisticated type systems provided
by the programming language in use. For instance, the schema type is
mapped to certain Java classes by serialization and de-serialization in cases
where Java is the native type system.
The design of WSIFMessage allows you to employ any native type system as a
message part. Parts in a message can be typed by employing different type
systems. This is needed if parts from multiple separate WSDL messages are
associated with different native type systems and have to be combined into a
single message.
Interaction flow
Figure 7-2 shows the main components of WSIF and their interaction. A Web
service is invoked through the following steps:
1. A WSDL document is loaded.
2. A WSIF service is generated.
3. The new WSIFService is used to get the operation.
4. The message is created.
5. The service is invoked by supplying the port with the name of the operation to
be invoked, along with an input and/or output message as required by the
operation.
WSDL
document
1
WSIF
service
factory
3
2
WSIF
service
WSIF
operation
Service
4
5
Figure 7-2 Main WSIF components
134
WebSphere Version 5.1 Web Services Handbook
WSIF
provider
Definition or modification of the binding selection algorithm
The WSIF architecture allows a convenient exchange or modification of the
binding selection algorithm. Only the implementation of WSIFService has to be
changed or written from scratch.
Modification of a binding implementation at runtime
In order to change from one binding implementation to another, there is no longer
a re-compilation of user code or stub code necessary, because the WSIF API
remains the same. The approach follows the factory pattern; thus, only a new
WSIFPort implementation and a provider is needed. The new WSIFPort
implementation has to be capable of making invocations using the modified client
API that is provided by the new binding implementation. The provider has to
translate a WSDL port to the new WSIFPort implementation. The provider
replaces the previous provider, and the invocation for all WSDL ports takes place
through the new WSIFPort implementation.
Two invocation models using WSIF
WSIF supports the invocation of Web services in two different ways: Either they
can be invoked by using a stub-less dynamic approach, or they are incorporated
with a generated stub. A direct invocation requires using the WSIF API directly,
while the generated stub allows the application to work with Java interfaces and
hides the WSIF API.
Stub-less (dynamic) invocation
WSDL provide all necessary information to incorporate a Web service, such as
the abstract interface, the binding, and the service endpoint. Thus once the
location of the WSDL file is known to a service requestor, the WSFL API can be
used to invoke this service at runtime. For this procedure, no stub classes have
to be generated. The following steps have to be performed:
Select a port.
Create an operation.
Create and populate the in-message.
Execute the operation.
Read the response data from the out-message.
For stub invocations, WSIF uses Java's dynamic proxy mechanism. The dynamic
proxy must be supplied with a Java interface reflecting the port type that is
invoked. The Java interface corresponding to a WSDL port type is defined by
JAX-RPC, a J2EE standard. Thus, WSIF can be used to invoke services through
the standard stub interface defined by JAX-RPC.
Chapter 7. Web services invocation framework
135
Figure 7-3 presents a sample for the invocation code. In the example, the call of
the procedure getTemperature is hardcoded for simplicity reasons. Obviously,
invocation code can be written that first parses the retrieved WSDL document to
extract the correct name and syntax of the provided methods.
WSIFService sq = WSIFServiceFactory.newInstance()
.getService("http://my.com/forecast.wsdl",null,null,null,null);
WSIFPort defPort = sq.getPort();
WSIFOperation getQ = defPort.createOperation("getTemperature");
WSIFMessage inMessage = getQ.createInputMessage();
inMessage.setStringPart("symbol", "Saarbruecken");
...
getQ.executeRequestResponse(inMessage, outMsg, fltMsg);
outMessage.getFloatPart("value");
Figure 7-3 Example for the dynamic invocation
Note: We make no comment about the usefulness of the invocation of
methods of which only their syntax but not their semantics is known.
Invocation using stubs
Besides the dynamic invocation, there is another way to invoke Web services.
This way is favorable in situations where the architecture defines services to be
more encapsulated. Thus, a more abstract view on the service is provided,
because the WSIF API is not directly addressed. Figure 7-4 shows a simple
example.
WSIFService sq = WSIFServiceFactory.newInstance()
.getService("http://my.com/forecast.wsdl",null,null,null,null);
MyService mySvcStub = sq.getStub("soap", MyService.class);
mySvcStub.myMethod();
Figure 7-4 Example using the stub model in WSIF
WSIF uses the J2SE 1.3 dynamic proxy support that generates a client stub for
each port type depending on the given WSDL document. To use the generated
stubs, applications use the abstract service interface. Therefore, they are more
isolated from the protocol and the WSIF client API.
A major advantage of the stub architecture is that the same stub can be used,
while the managed environment may change in the plumbing without having to
136
WebSphere Version 5.1 Web Services Handbook
recompile anything. Furthermore, the stub-based model allows using the normal
programming model to call business methods on Web services.
Sample scenarios for WSIF
Remember that Web services are no longer tied to SOAP. In situations where the
service provider resides in the same environment, a local call performs better
than a call through a Web server and servlet engine into the SOAP router.
In large projects, the technique of rapid prototyping is often used, where the first
system has limited functionality, but can already serve as a proof of concept.
Later, the prototype can be continuously enhanced. Web services in such a
project will also be continuously redeveloped and possibly redeployed. If WSIF is
used, the same API calls are used; however, the underlying technologies differ.
Still, client code does not have to be rewritten.
Another aspect is outsourcing, where an internal implementation of Web
services using local calls is replaced by a service provider, and the Web services
must be invoked using SOAP.
Furthermore, WSIF development can be done remotely, but system test and
maintenance is done in-house. Using WSIF, the same API can be used for
development, testing, and maintenance.
Current status and future
WSIF was initially released on the alphaWorks® Web site in October 200:
http://www.alphaworks.ibm.com
WSIF is now an Apache open-source project and is supported by the
open-source community. For links see “More information” on page 140.
WSIF has not been standardized so far. Enhancement of the Apache WSIF
project is continued in 2003. It is practical to employ a standard API to access
Web services as well as back-end legacy applications through WSDL and WSIF.
Therefore, it will be used in IBM products wherever appropriate; mostly as a
behind-the-scenes middleware piece.
The first release of WSIF became available in January 2003, including
documentation of the WSIF Java and EJB bindings. The WSIF documentation is
compiled with descriptions of the WSIF Java and EJB bindings.
Chapter 7. Web services invocation framework
137
Enhancements
The main enhancements since the alphaWorks release are:
The WSIFPart interface has been removed and merged into WSIFMessage.
The WSIFPortFactory object has been renamed to WSIFService.
A new interface, WSIFServiceFactory, has been added.
The PortTypeCompiler is no longer used. Instead, the J2SE 1.3 dynamic
proxy is supported.
New bindings and transports have been added: SOAP over JMS, EJB
binding, and Apache Axis-based SOAP provider.
Tracing and logging activities are now supported.
A dynamic registration of new providers using the J2SE JAR service provider
specification is now supported.
WSIF has been changed so that the Apache Axis provider is now used for the
default SOAP binding. WSIF has two SOAP providers: One based on Apache
SOAP 2.3, the other on Apache Axis (SOAP 3.x). Recently, a JCA provider
has been added that allows applications accessible via JCA to be exposed
through WSDL and invoked using WSIF APIs.
WebSphere Application Server 5.0.2 update
WebSphere 5.0.2 introduces the following enhancements:
WSIF support for SOAP with Attachments API for Java (SAAJ)
The SAAJ API provides a standard way to associate a SOAP message with
one or more attachments in their native format (for example, GIF or JPEG) by
using a multipart MIME structure for transport. It defines specific usage of the
multipart/related MIME media type, and rules for the usage of URI references
to refer to entities bundled within the MIME package. It thereby outlines a
technique for a SOAP 1.1 message to be carried within a MIME
multipart/related message in such a way that the SOAP processing rules for a
standard SOAP message are not changed.
WSIF supports passing attachments in a MIME message using the SOAP
provider. The attachment is a javax.activation.DataHandler. The
mime:multipartRelated, mime:part and mime:content tags are used to
describe the attachment in the WSDL.
For more information go to:
http://publib.boulder.ibm.com/infocenter/wasinfo/topic/com.ibm.wasee.doc/in
fo/ee/ae/twsf_attach.html
138
WebSphere Version 5.1 Web Services Handbook
WSIF support for automatic mapping of complex types
For complex types defined in the WSDL, where a generated bean is used to
represent this in Java, the WSIF programming model requires that a call is
made to WSIFService.mapType(). This call tells WSIF the package and class
name of the bean representing the XML schema type that is identified with a
QName. To make things easier, WSIFService.mapPackage() provides a
mechanism to specify a wildcard version of this, where any class within a
specified package is mapped to the namespace of a QName. This is a
mechanism for manually mapping an XML schema type to a Java class and
back again (one mapping entry provides a bi-directional mapping).
For more information go to:
http://publib.boulder.ibm.com/infocenter/wasinfo/topic/com.ibm.wasee.doc/in
fo/ee/ae/cwsf_comt.html
Integration into WebSphere products
WSIF is used in WebSphere products such as WebSphere Workflow, the Web
Services Gateway (refer to Chapter 10, “Web Services Gateway” on page 169),
and in WebSphere Studio Application Developer Integration Edition (refer to
Chapter 17, “Application Developer Integration Edition” on page 341), and is
supported in WebSphere Application Server Version 5.
In WebSphere Application Server, WSIF is provided as a stand-alone JAR file
called wsif.jar. The JAR file contains the core WSIF classes, as well as the
Java, EJB, SOAP over HTTP, and SOAP over JMS providers. Additional
providers are packaged as separate JAR files. WSIF makes use of the WSDL4J
API to parse WSDL files.
Future versions
Besides the first Apache release, there are some other areas of further
development on WSIF. A mechanism is envisaged to separate the transport from
message formatting. Furthermore, some work has been done to implement an
abstract tree representation of the data in a message. Also, there will be support
for better providers for the many types of transports and object systems that
exist. Finally, implementations of WSIF in C or C++ are considered.
Chapter 7. Web services invocation framework
139
Summary
The Web services invocation framework is a Java API that supports
SOAP-based and non-SOAP-based services to be described in WSDL and
invoked in a common way. It specifies a provider interface that can be extended
by new transports and protocols.
WSIF supports two ways of service invocation: Dynamic invocation or by using a
stub. Furthermore, it supports late binding, so that services can be adjusted to
new protocol types without modifying and compiling client code.
WSIF moves the issue of Web service invocation from a binding-centric
viewpoint to a more abstract, encapsulated level, driven by the WSDL description
of the service. Thus, service bindings are perceived as pieces of code needed for
invocation according to a particular protocol.
More information
The developerWorks Web site provides updated information on many activities
concerning Web services, including WSIF:
http://www.ibm.com/developerworks/webservices/
In particular, the following articles provide more detailed information:
Applying the Web Services Invocation Framework:
http://www.ibm.com/developerworks/library/ws-appwsif.html
Web Service Invocation Sans SOAP:
http://www.ibm.com/developerworks/webservices/library/ws-wsif
Web Service Invocation Sans SOAP2:
http://www.ibm.com/developerworks/webservices/library/ws-wsif2
The home page of the WSIF open-source project on Apache is at:
http://ws.apache.org/wsif/
The xml-axis-wsif code can be browsed at:
http://cvs.apache.org/viewcvs.cgi/xml-axis-wsif
IBM’s contribution on WSIF from October 2001 can be found at:
http://www.alphaworks.ibm.com/tech/wsif
140
WebSphere Version 5.1 Web Services Handbook
8
Chapter 8.
Web services inspection
language
This chapter provides an introduction to the Web services inspection language
(WSIL or WS-Inspection) 1.0. A complement to UDDI, WS-Inspection is another
service discovery mechanism that addresses a different subset of requirements
using a distributed usage model.
We discuss the principal features and taxonomy, as well as its business
application. The WS-Inspection specification is designed around an XML-based
model for building an aggregation of references to existing Web service
descriptions.
WS-Inspection 1.0 provides a notation serving these purposes. The
WS-Inspection specification is a joint effort by IBM and Microsoft. It was a draft
document at the time of writing this book, and represents the current status with
regard to locating and inspecting services.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
141
Overview
A centralized service registry, which is described in Chapter 6, “Introduction to
UDDI” on page 99, is not the only model for Web services discovery. The
simplest form of services discovery is requesting a copy of the service
description from the provider. This is not very efficient because it requires a prior
knowledge of the Web service. The most complex form is connecting to a UDDI
registry that provides a more business-centric perspective.
Between these two extremes, there is a need for a distributed service discovery
method that provides references to service descriptions at the service provider's
point-of-offering. The Web services inspection language provides this type of
distributed discovery method by specifying how to inspect a Web site for
available Web services. The WS-Inspection specification defines the locations on
a Web site where you may find Web service descriptions.
The WS-Inspection specification does not define a service description language,
which is left to other languages such as WSDL. WS-Inspection documents
provide a method for aggregating different types of service descriptions. Within a
WS-Inspection document, a single service can have more than one reference to
a service description. For example, a single Web service might be described
using both a WSDL file and within a UDDI registry. References to these two
service descriptions may be put into a WS-Inspection document. If multiple
references are available, it is beneficial to put all of them in the WS-Inspection
document so that the document user can select the type of service description
that they can understand and want to use.
The WS-Inspection specification contains two primary functions:
It defines an XML format for listing references to existing service descriptions.
It defines a set of conventions so that it is easy to locate WS-Inspection
documents.
The WS-Inspection specification complements a UDDI registry by facilitating the
discovery of services available on Web sites, which may not be listed yet in a
UDDI registry. An overview of WS-Inspection is shown in Figure 8-1.
142
WebSphere Version 5.1 Web Services Handbook
Service
Description
Service
Description
UDDI
Registry
WS-Inspection
Document
find
service
Service
Provider
WS-Inspection
Document
Service
Description
http://itso.com/inspection.wsil
Service
Requestor
Web Service
Figure 8-1 WS-Inspection overview
WS-Inspection document
The most important objectives of the inspection language are simplicity and
extensibility. A WS-Inspection document is an aggregation of pointers to service
description documents. Examples of service descriptions are WSDL files, UDDI
entries, or simple plain text, for example, an HTML page. The WS-Inspection
document is usually available at the point-of-offering (service provider) and
allows the consumer to pick and choose from the available service descriptions
using the access method that is most useful.
The WS-Inspection document contains an inspection element at the root that
provides a wrapper to the two main elements:
service
Contains the references to different types of service descriptions for
the same Web service.
link
Allows a WS-Inspection document to reference additional
aggregation of services descriptions, such as other WS-Inspection
documents or UDDI entries.
The optional abstract element is used as a container to provide a small textual
description for human consumption. This element is allowed inside any other
base element that allows child elements.
Chapter 8. Web services inspection language
143
WS-Inspection document anatomy
Figure 8-2 shows the anatomy and the relationship among the different elements
in a WS-Inspection document. The structure is quite simple and, therefore, it can
be easily maintained.
WS-Inspection
Document
1
1
inspection
If links = 0
then services > 0
If services = 0
then links> 0
1
n
n
n
service
link
abstract
1
n
abstract
1
n
n
name
description
n
abstract
Figure 8-2 WS-Inspection document elements and relationship
The diagram should be read in the following way:
One WS-Inspection document contains one inspection element.
One inspection element contains zero or more abstract elements and zero or
more links and/or services with one restriction. This restriction means that the
inspection element must contain at least either one service or one link, but
never none of them. For example, if there is no service, there has to be at
least one link, and vice versa. A combination of links and services is possible.
One service contains zero or more abstract, name and description elements.
One link contains zero or more abstract elements.
The containment relationship shown in the diagram directly maps to the XML
schema for WS-Inspection.
144
WebSphere Version 5.1 Web Services Handbook
Example
Figure 8-3 contains a simple WS-Inspection document example. As we see, the
syntax used in this file is not very complex, but rather easy to understand. We
analyze this example in detail in this chapter, but the whole document is
presented here to obtain a complete picture.
As an exercise, you can try identifying the different elements in Figure 8-2 while
examining this example.
<?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>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
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 8-3 WS-Inspection document example
Namespaces
The namespaces used in a WS-Inspection document are shown in Table 8-1.
Table 8-1 WS-Inspection namespaces
Prefix
Namespace URI
Definition
wsil
http://schemas.xmlsoap.org/ws/
2001/10/inspection/
WS-Inspection namespace for the
WS-Inspection framework.
wsilwsdl
http://schemas.xmlsoap.org/ws/
2001/10/inspection/wsdl/
WS-Inspection namespace for the
WS-Inspection WSDL binding.
Chapter 8. Web services inspection language
145
Prefix
Namespace URI
Definition
wsiluddi
http://schemas.xmlsoap.org/ws/
2001/10/inspection/uddi/
WS-Inspection namespace for the
WS-Inspection UDDI binding.
uddi
urn:uddi-org:api
API and document namespace
defined by the UDDI V1
specification.
uddiv2
urn:uddi-org:api_v2
API and document namespace
defined by the UDDI V2
specification.
(other)
(various)
All other namespace prefixes are
samples only. In particular, URIs
starting with "http://itso.com"
represent some
application-dependent or
context-dependent URI.
WS-Inspection and UDDI relationship
WS-Inspection and UDDI specifications address issues related to Web service
discovery. Even so, they were designed with different goals in mind, and thus
exhibit different characteristics.
One of the fundamental points of a successful Web service is related to the
discovery of the service. We illustrate how the two specifications may be used
jointly to solve a variety of requirements.
The information can be extracted either straight from the source of information,
WS-Inspection, or from a third-party UDDI registry. The two possibilities have
some characteristic features.
WS-Inspection
Retrieving the information directly from the source increases the possibilities
of obtaining accurate information.
The use of a distributed model allows the service descriptions to be stored at
any location.
They are very lightweight, easy to create, and easy to maintain.
They allow the provider to present its services in a proactive fashion.
They do not stipulate any particular format for the service and rely on other
standards, including UDDI.
They do not provide a rich mechanism to execute any focus discovery.
146
WebSphere Version 5.1 Web Services Handbook
UDDI registry
Retrieving the information indirectly provides the opportunity for more
developed and advanced services and does not require that the original
source be available or easily accessible.
Uses a centralized model.
Provides high-level functionality in the discovery (search facility).
Both systems address different sets of issues in the discovery problem space.
Whereas the UDDI provides a high degree of functionality, the WS-Inspection
document adopts it at a lower level. Therefore, both specifications should be
understood as complementary technologies to be used either together or
separately, depending upon the situation.
There is a whole range of mutual benefit in the combined use of the
technologies. For example, a UDDI registry can be populated using the
WS-Inspection documents found in an Internet search. On the other hand, a
UDDI registry can be discovered when a requestor retrieves a WS-Inspection
document that references an entry in the repository. Thus, they should not be
viewed as competing mechanisms; for example, a business card does not
compete with the yellow pages in disseminating personal information.
WS-Inspection definition
The WS-Inspection definition contains a detailed explanation of the core
elements of the WS-Inspection language. The document contains an inspection
element at the root, and references to individual service descriptions or links as
descendants. The grammar of a WS-Inspection document is as follows:
<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)
<wsil:abstract xml:lang=""(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)
<wsil:abstract xml:lang=""(0 or 1) ... /> (0 or more)
<-- extensibility element --> (0 or more)
</wsil:link>
</wsil:inspection>
Chapter 8. Web services inspection language
147
The inspection element must contain at least one service or one link.
To provide the possibility to include documentation, the specification uses the
optional abstract element. This element contains a small textual description to be
exploited by a human reader. The abstract element is allowed inside any base
WS-Inspection language element that allows child elements. An optional
xml:lang attribute specifies on the element the language in which the abstract
element has been written.
Services
The service element provides the mechanisms to include a collection of
description references for services. An inspection element may contain any
number of service elements within it. Each service element may have one or
more abstract elements and one or more name elements, and must have at least
one description element, but may have more.
Service name
The name is used to associate the service with a particular name. The reason for
this element is only for human consumption as the abstract element. In the same
way used in the abstract element, an optional element, xml:lang, can be used to
specify the language in which the name has been written.
Service description references
The most important and useful part of the inspection is the information contained
within the description element. This element is used to provide pointers to
service description documents of various forms. The service description element
contains the following attributes:
referencedNamespace
Identifies the namespace to which the reference
document belongs, such as WSDL or UDDI.
location
Provides the actual reference to the description. It
has to be a valid URL.
extensible
Provides additional information that is needed to
retrieve or process the service description. See
“WS-Inspection bindings” on page 150 for more
information.
In our example, the service definition is shown in Figure 8-4, where we specify
two services, the first one about trains and the second one about planes.
148
WebSphere Version 5.1 Web Services Handbook
<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>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="ftp://itso.com/tools/plane.wsdl"/>
</service>
Figure 8-4 Service definition in our WS-Inspection document example
In the first service, we provide an abstract element explaining that it is a simple
example that contains two descriptions:
One description makes a reference to a WSDL document, which is specified
using the namespace http://schemas.xmlsoap.org/wsdl/ and the URL
location http://itso.com/train.wsdl.
Another description for the same Web service is provided using a UDDI
registry Version 2 that we specify with the namespace urn:uddi-org:api. The
location for the query is http://itso.com/uddi/inquiryapi, and the service
key 4FA23580-5C39-14D5-9FCF-BB3200303F79 can be used to retrieve the
service description.
In the second service, we provide a reference to a WSDL document, which is
specified using the namespace http://schemas.xmlsoap.org/wsdl/ and the
URL location ftp://itso.com/tools/plane.wsdl.
Links
The link element allows WS-Inspection documents to reference additional
aggregations of service descriptions, such as other WS-Inspection documents or
UDDI repositories. Therefore, we can create a hierarchy of documents (see
Figure 8-1 on page 143).
The link element helps service providers to create inspection documents with a
large number of services elements pointing to the same location in the
Chapter 8. Web services inspection language
149
information registry. Using the link, the providers are able to indicate to the
consumers that they have to look at the indicated location for additional service
description aggregations.
The referencedNamespace attribute identifies the namespace of the linked
aggregation source, such as another inspection document or a UDDI registry, but
there is no specification of how this link element has to be processed. This
means that there is no predefined rule of how this information has to be used.
In our example (Figure 8-5), the link definition is where we specify one link to
another WS-Inspection document providing the namespace and the location
(http://itso.com/others/moreservices.wsil) of the document.
<link
referencedNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
location="http://itso.com/others/moreservices.wsil"/>
Figure 8-5 Link references in our WS-Inspection document example
WS-Inspection bindings
We now introduce the characteristics of the extension elements related to the
different bindings.
WSDL binding
The WS-Inspection language includes a binding for WSDL 1.1, providing the
following capabilities:
Indication of the type(s) of WSDL bindings that appear in the referenced
WSDL document
Specification of which WSDL service is being referenced if several services
exist within the same document
Indication of whether or not a particular referenced WSDL document provided
endpoint information
The use of the WSDL binding is optional if the referenced WSDL document has
one service element or none. In these cases, a reference to a WSDL document
may be made with only one description element. In cases where the WSDL
document has more than one service, the binding must be used to indicate which
service element is being referenced.
150
WebSphere Version 5.1 Web Services Handbook
The grammar for the binding extension elements is shown in Figure 8-6 and the
description of its element in Table 8-2.
<inspection
xmlns:wsilwsdl="http://schemas.xmlsoap.org/ws/2001/10/inspection/wsdl/ ...>
<service ...>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
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 8-6 WSDL binding extension elements grammar
Table 8-2 WSDL extensibility elements in WS-Inspection
Extension name
Explanation
wsilwsdl:reference
The container element for the rest of the binding
information. The endpointPresent is a boolean
attribute that indicates whether the referenced
WSDL contains endpoint information.
wsilwsdl:referencedService
Specifies which service is being referenced when
there are more than one. The QName specified must
be a valid service name in the referenced WSDL
document.
wsilwsdl:implementedBinding
Used to indicate the type(s) of binding that appear in
a referenced WSDL document. The QName specified
must be a valid binding name in the referenced
WSDL document.
Chapter 8. Web services inspection language
151
UDDI binding
The WS-Inspection language provides a set of usage patterns for references to
business service or business entity information presented in a UDDI registry.
This set of elements can refer to entries in a UDDI Version 1.0 or Version 2.0
registry, depending upon the referenceNamespace used. The UDDI extension
elements can be included in the description or link elements, in contrast to the
WSDL extension elements, which are only in the description element.
The extension elements included in the link can only reference a UDDI business
entity. Meanwhile, the extension elements included in the description may only
reference a single UDDI business service.
The grammar for the binding extension elements is shown in Figure 8-7, and the
description of its element in Table 8-3.
<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)
</wsiluddi:serviceDescription>
</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 8-7 UDDI binding extension elements grammar
152
WebSphere Version 5.1 Web Services Handbook
Table 8-3 UDDI extensibility elements in WS-Inspection
Element
Extension name
Explanation
description
wsiluddi:
serviceDescription
Specifies a reference to a single UDDI service
description. Must contain a serviceKey and
may also contain a discoveryURL.
wsiluddi:
discoveryURL
Used to retrieve a UDDI business entity using
HTTP GET to obtain a single service
description using the serviceKey.
wsiluddi:
serviceKey
Used to retrieve the UDDI service description.
wsiluddi:
businessDescription
Specifies a reference to a UDDI business entity.
Must contain a discoveryURL, a businessKey, or
both. The location attribute contains the UDDI
registry inquiry interface.
wsiluddi:
discoveryURL
Specifies a valid URL to retrieve the UDDI
business entity using HTTP GET.
wsiluddi:
businessKey
Specifies a business key that is used in
combination with the location attribute of the
business description to retrieve the UDDI
business entity using HTTP POST.
link
Inspection document publishing
The WS-Inspection grammar only provides a partial solution to the problem of
advertising services. We need some rules to easily locate these WS-Inspection
documents, because if not, their added value is lost. Consequently, the
WS-Inspection language provides two conventions for the location where the
document should be placed and how it should be found.
Fixed name WS-Inspection documents
They have to be called inspection.wsil and may be placed where the most
common entry points to Web sites or applications deployed on the server are
located. For instance, in the example used in this chapter, our document is
placed in http://itso.com/inspection.wsil.
Linked WS-Inspection documents
They allow for a mechanism to inform users about services inspection-related
documents using other types of content, such as HTML pages.
Chapter 8. Web services inspection language
153
WSIL examples
In this section we describe two examples of bindings that we use in the sample
application described in Chapter 19, “Web services scenario: Architecture and
implementation” on page 429.
WSDL binding example
The first example shows the use of a WSDL binding, that is, the WSIL document
points to a WSDL file on a server (Figure 8-8).
<?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>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="http://www.flashandthunder.com/ItsoFlashWeb/wsdl/
itso/bean/WeatherForecast.wsdl">
<wsilwsdl:reference endpointPresent="true">
<wsilwsdl:implementedBinding xmlns:binding="http://bean.itso">
intf:WeatherForecastSoapBinding
</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>
<description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
location="http://www.flashandthunder.com/ItsoThunderWeb/wsdl/
itso/bean/WeatherForecast.wsdl">
......
</description>
</service>
</inspection>
Figure 8-8 WSIL example with WSDL binding
In this example the WSIL document refers to two services by pointing to the
WSDL files on two provider servers using URLs.
154
WebSphere Version 5.1 Web Services Handbook
UDDI binding example
The second example shows the use of a UDDI binding, that is, the WSIL
document points to a UDDI registry (Figure 8-9).
......
<service>
<name xml:lang="en-US">ITSO WS Thunder Weather Service</name>
<description referencedNamespace="urn:uddi-org:api_v2">
<wsiluddi:serviceDescription location=
"http://uddi.ibm.com/testregistry/inquiryapi">
<wsiluddi:serviceKey>F3362720-0C6D-11D7-AB70-000629DC0A53
</wsiluddi:serviceKey>
<wsiluddi:discoveryURL useType="businessEntity">
http://uddi.ibm.com/testregistry/inquiryapi
?businessKey=F5082FA0-0BCB-11D7-AB70-000629DC0A53
</wsiluddi:discoveryURL>
</wsiluddi:serviceDescription>
</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 8-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.
Chapter 8. Web services inspection language
155
WS-Inspection API
There is a WS-Inspection Java API called WSIL4J. This API can be used to
locate and process WS-Inspection documents. The class library provides
functionality to read and parse WS-Inspection documents and to generate new
documents. The primary classes are:
org.apache.wsil.WSILDocument
Interacts with the WS-Inspection
documents.
org.apache.wsil.client.WSILProxy
Accesses specific service descriptions
within a WS-Inspection document.
Currently, WSIL4J is an open-source project available on the Apache Software
Foundation as a part of the Apache Axis work:
http://xml.apache.org/axis/index.html
Figure 8-10 contains an example of how to use this API. In this sample code, a
WS-Inspection document is read and the service elements are searched for
references to WSDL service descriptions. When a WSDL service description is
found, its location is saved in a list.
...
// Create a new instance of a WS-Inspection document
WSILDocument document = WSILDocument.newInstance();
// Read and parse the WS-Inspection document
document.read(wsinspectionURL);
// Get the inspection element from the document
Inspection inspection = document.getInspection();
// Obtain a list of all service elements
Service[] services = inspection.getServices();
// Process each service element to find all WSDL document references
for (int serviceCount = 0; serviceCount < services.length; serviceCount++) {
// Get the next set of description elements
descriptions = services[serviceCount].getDescriptions();
// Process each description to find the WSDL references
for (int descCount = 0; descCount < descriptions.length; descCount++) {
//If the referenced is WSDL, then save the location reference
if(descriptions[descCount].
getReferencedNamespace().equals(WSDLConstants.NS_URI_WSDL)) {
// Add WSDL location to the list
wsdlList.add(descriptions[descCount].getLocation());
}
}
...
Figure 8-10 WS-Inspection API example
156
WebSphere Version 5.1 Web Services Handbook
Outlook
At the time this book was written, this technology was in its first use as a new
service discovery mechanism. The population of WS-Inspection documents
should greatly increase in coming months. There are few examples of published
WS-Inspection documents on the Internet. One example is at the XMethod Web
site:
http://www.xmethods.net/inspection.wsil
Based on the contribution of WSIL4J to Apache Axis, we may soon see a
WS-Inspection API in Axis. This technology will be used for other applications,
such as a Web service crawler. A service crawler would search through Web
sites for WS-Inspection documents and then aggregate the service description
references from multiple sites.
Consequently, and based on the current and future applications of the Web
services inspection language, the WS-Inspection documents will play a
fundamental role in the overall development of the Web services technology.
Summary
In this chapter we have described the Web services inspection language and
how this specification provides a simple method to discover any type of Web
service description document. We analyzed its grammar and how these
WS-Inspection documents can be found. We also saw that this technology does
not try to replace present technologies regarding service discovery, but is a
complementary discovery method that can be integrated to work together with
UDDI repositories, for example.
Finally, we briefly reviewed the ways that the open-source WSIL4J API can
facilitate the reading, parsing, and generation of WS-Inspection documents.
More information
At present, this technology is not widespread, and real examples may be found in
no more than a few documents.
The best source for more information is the Web services inspection language
(WS-Inspection) 1.0 specification that can be found at:
http://www.ibm.com/developerworks/webservices/library/ws-wsilspec.html
Chapter 8. Web services inspection language
157
158
WebSphere Version 5.1 Web Services Handbook
9
Chapter 9.
Workflows and business
processes
Web services enable users to connect different components across
organizational boundaries in a platform- and language-independent manner.
However, none of these standards allow defining the business semantics of Web
services. Today’s Web services are isolated. Breaking this isolation means
connecting Web services and specifying how collections of Web services are
jointly used to implement more complex functionality—typically a business
process or a workflow.
In this chapter we cover some concepts regarding workflows. Because a set of
services can be composed to a workflow or business process, there are some
conceptional topics to discuss. This chapter introduces two specifications dealing
with workflows and business processes.
The sections in this chapter include:
Web services flow language (WSFL)
Flow definition markup language (FDML)
Business process execution language (BPEL)
© Copyright IBM Corp. 2003, 2004. All rights reserved.
159
Web services flow language
In 2001 IBM introduced a new language for describing business processes,
which is called the Web services flow language (WSFL).
WSFL is a language used to model workflows or processes using an XML syntax
that can be read by both humans and machines. By interpreting WSFL, a
workflow engine can walk through the business processes using such constructs
as activities and control links. There are already a number of workflow systems
available, but the power of WSFL lies in its ability to model business processes
that span technology and business boundaries—a limitation that most workflow
engines suffer from.
A WSFL flow model defines the structure of the business process. Activities
describe the processing steps, and data and control links represent the
sequencing rules and information flows between these activities. For each
activity, they would identify the WSFL service provider responsible for the
execution of the process step and define the association between activities in the
flow model and operations offered by the service provider using WSFL export
and plug link elements.
The purpose of a WSFL document is to define the composition of Web services
as a flow model or a global model. Both models have a declared public interface
and an internal compositional structure. The composition assumes that the Web
services being composed support certain public interfaces, which can be
specified as a single port type or as a collection of port types.
Concepts and terms in WSFL
WSFL, like workflow in general, introduces a whole set of new terms that
describe artifacts within the process and result in certain elements that you can
use while modeling your workflow.
Activity
An activity is one atomic step in a workflow. This can be a simple Java method,
an EJB call, the invocation of another Web service, or even a complex business
process itself.
Business process
A business process is any collection of activities that, when combined,
accomplish a given business objective. For example, processing a credit card
number, hiring a new employee, and submitting a patent are all examples of
business processes.
160
WebSphere Version 5.1 Web Services Handbook
Flow model
The flow model is the actual XML representation of the directed graph that
models the business process. It is the structure that is used to compose Web
services, as defined by their individual WSDL documents, into workflows. Flow
models are sometimes known as flow composition, orchestration, and
choreography, to name three common synonyms.
Simply modeling the processing flow between activities/services within a
workflow is not enough. In addition to the flow model, there needs to be a way of
specifying exactly how the Web services involved in the process are expected to
interact with each other. That is where the global model comes in. The global
model is a set of necessary links that specify how messages can be sent
between the Web services in the flow model as the workflow is executed.
Recursive composition
Recursive composition is the possibility that once you have defined both the
global and flow models for a given business process, it is then possible to define
the whole business process as a single Web service that may be used by other
business processes. In other words, you can recursively compose business
processes within existing business processes. This provides a great deal of
flexibility and fine granularity in the models that you define.
Service provider
A service provider is the party responsible for performing a particular activity
within a business process. In WSFL, every activity is a Web service. Therefore,
every service provider is a Web service provider. To maintain a clear separation
between the definition of the business process and its implementation, WSFL's
flow and global models define each activity as being implemented by specific
types of service providers rather than by the specific service providers
themselves.
The service provider type is defined by a Web service interface document using
WSDL. Service providers must properly implement the appropriate Web service
interface in order to be classified as the appropriate type of service provider to
handle a particular activity in the business process.
Control link
A control link is a connection between two activities. It is the mechanism by which
the workflow processor walks through each of the activities in the business
process.
Chapter 9. Workflows and business processes
161
Data link
The data link is the mechanism that the workflow processor uses to control the
flow of data through the business process. While in most cases, the data flow will
closely follow the control flow, it is quite possible that the way that information
flows through the process is different from the sequence of activities that are
invoked.
Transition condition
As a business process is being run, the workflow processor must be able to
recognize when a particular activity is finished and when the next activity can be
determined and invoked. A transition condition is a true or false statement that
the processor may use to determine the current state of any particular activity.
Life cycle interface
As mentioned earlier, WSFL business processes are themselves capable of
being defined as Web services. The life cycle interface is the WSDL-defined Web
service interface that describes the basic set of operations that all WSFL Web
services support within a particular Web services application. These operations
include the ability to invoke, suspend, resume, stop, and terminate the business
process as well as inquire about its current state.
Sample WSFL
The essential entities are the activities and control links. Figure 9-1 shows how
they are specified in WSFL.
The concept that is important to understand here is simple:
Each activity is an individual Web service described by a WSDL document.
A control link connects these Web services together in a sequential order.
In this example we find:
A flow model: WeatherForecast
Two service providers: MyWeatherGuru and MyMathGuru
A first activity, getDayForecast, which calls the weather forecast Web service
A second activity, convertCelsiusToFahrenheit, which calls the temperature
conversion Web service
A control link that connects the first activity with the second activity
A datalink that connects the output message of the first activity to the input
message of the second activity
162
WebSphere Version 5.1 Web Services Handbook
<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 9-1 Activities and control links in WSFL
Flow definition markup language
WebSphere Studio Application Developer Integration Edition uses the flow
definition markup language (FDML) to describe business processes.
This markup language is based on WSFL, but also introduces some extensions.
Read Chapter 17, “Application Developer Integration Edition” on page 341, for
further information on how to develop workflow and business processes using
the IBM tools.
Chapter 9. Workflows and business processes
163
Elements of FDML
The elements used in FDML are basically the same as in WSFL, with extensions:
Flow model—Represents a business process.
Activity—There are a number of activity types:
–
–
–
–
–
–
–
–
–
–
–
–
Input—Starting point of the business process
Output—End of the process, delivers the result to the caller
Java—Invokes a Java class
EJB—Invokes an EJB
Service—Invokes an external Web service
Process—Invokes another business process (nested)
Java snippet—Invokes a Java method that is part of the process
Loop—Iteration with conditional expression
Block—Decomposition of process to simplify the diagram
Receive event—Stops process and waits for an event
Staff—Stops execution and solicits human interaction
Throw fault—Abnormal end of process, returns a message
Control link—Dictates the sequence of activities. Links can have transition
conditions that decide which link should be followed after an activity.
Compensation—A service process can have a compensation service process
that is executed if the service process throws a fault.
Message—Each activity has an input and an output message.
Variable—Holds data within the process, for example, messages.
For a more detailed description of the process elements, see “Business process”
on page 347.
FDML sample code
We develop a sample business process with Application Developer Integration
Edition in “Sample business process” on page 350.
Integration Edition stores the process flow in an FDML file. Extracts of the FDML
file are described in “Flow definition markup language” on page 368.
164
WebSphere Version 5.1 Web Services Handbook
Business process execution language for Web services
This section describes another notation for specifying business process behavior
based on Web Services. This notation is called business process execution
language for Web services (BPEL4WS, or BPEL for short). Processes in
BPEL4WS export and import functionality by using Web service interfaces
exclusively. It represents a convergence of the ideas in Microsoft’s XLANG and
IBM WSFL specifications. Both XLANG and WSFL are superseded by the
BPEL4WS specification.
BPEL4WS allows specifying business processes and how they relate to Web
services. This includes specifying how a business process makes use of Web
services to achieve its goal, as well as specifying Web services that are provided
by a business process. Business processes specified in BPEL are fully
executable and portable between BPEL-conforming environments. A BPEL
business process interoperates with the Web services of its partners, whether or
not these Web services are implemented based on BPEL. Finally, BPEL
supports the specification of business protocols between partners and views on
complex internal business processes.
Business processes can be described in two ways:
Executable business processes model actual behavior of a participant in a
business interaction.
Business protocols use process descriptions that specify the mutually visible
message exchange behavior of each of the parties involved in the protocol,
without revealing their internal behavior. The process descriptions for
business protocols are called abstract processes.
BPEL4WS is meant to be used to model the behavior of both executable and
abstract processes.
Concepts and terms in BPEL4WS
There are five major elements in the process definition.
Containers
The <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.
Chapter 9. Workflows and business processes
165
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.
166
WebSphere Version 5.1 Web Services Handbook
In BPEL4WS this data is stored in variables that are held in a container and can
be accessed by several parts of the flow. The current version of BPEL4WS
supports only global data containers, but future versions will include locally
scoped data as well.
Business process execution language for Web services runtime
The alphaWorks Web site (see “More information” on page 168) offers a runtime
facility for BPEL. This platform:
Can execute business processes written in the business process execution
language for Web services
Offers a set of samples demonstrating the use of BPEL4WS
Contains a tool that validates BPEL4WS documents
Includes an Eclipse plug-in that provides a simple editor for creating and
modifying BPEL4WS files, supporting top-down and bottom-up approaches
BPEL future
A new Web Services Business Process Execution Language technical council is
being formed at OASIS to continue work on the business process language
published in the Business Process Execution Language for Web Services
(BPEL4WS) 1.0 specification. Refer to:
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsbpel
BPEL4WS is included in the Emerging Technologies Toolkit and it is possible that
future releases of business process model tools, such as Application Developer
Integration Edition, will use BPEL4WS to internally describe the workflows.
Summary
There are a number of running workflow systems on the market. The current
specifications for XML-based workflow languages are in an early stage and are
subject to be consolidated between different tool and runtime providers. The
significant advantage of new XML-based workflow languages is that they support
the usage of Web services in their processes and therefore provide a standard
means of combining the services of different systems, programming languages,
and protocols.
Chapter 9. Workflows and business processes
167
More information
The WSFL specification:
http://www.ibm.com/software/solutions/webservices/pdf/WSFL.pdf
“The Web services insider: Introducing the Web Services Flow Language”:
http://www.ibm.com/developerworks/library/was-ref4
“The Web services insider: Getting into the Flow”:
http://www.ibm.com/developerworks/webservices/library/was-ref5
“Business process execution language for Web services, Version 1.0”:
http://www.ibm.com/developerworks/library/was-bell
“Business processes in a Web services world”:
http://www.ibm.com/developerworks/webservices/library/was-burlap
IBM business process execution language for Web services Java runtime
(BPWS4J):
http://www.alphaworks.ibm.com/tech/bpws4j
“XLANG— Web services for business process design”:
http://www.gotdotnet.com/team/xml_wsspecs/xlang-c/default.htm
168
WebSphere Version 5.1 Web Services Handbook
10
Chapter 10.
Web Services Gateway
This chapter describes the Web Services Gateway (WSGW), which is part of
WebSphere Application Server Version 5.0.2 Network Deployment.
This gateway can be seen as a kind of proxy that acts as an additional layer
between a Web service client and Web service provider. The gateway is useful
for enabling a flexible way to call Web services located in an intranet from the
Internet, as well calling Internet Web services from the intranet. Another function
of the gateway is the possibility for protocol switching and security for Web
service calls.
This chapter is divided into the following sections:
Overview
General concepts
Administrating the gateway
Installation details
Summary
Note: The Web Services Gateway is a product feature implemented in
WebSphere Application Server Version 5 Network Deployment. We include
this chapter in Part 1 because the gateway can also be looked at as a
technology for distributed Web service invocation.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
169
Overview
If we plan to externalize our Web services beyond the boundaries of our
enterprise network, we will be faced with a number of issues that we need to
address. These issues include security, reliability, quality of service,
communications compatibility, and more.
Motivation for a gateway
In this section we describe the reasons for an additional gateway layer.
Externalizing Web services
Businesses often deploy their Web services to servers inside the intranet for use
by other intranet applications. Sometimes we want to externalize Web services to
let clients from outside our intranet, such as customers, suppliers, and business
partners, access our services. The Web Services Gateway lets clients from
outside the firewall use Web services that are deployed on a server deep inside
our enterprise.
Return on investment
Processes that we already develop as Web services can be easily reused by our
partners. Using the gateway, we can take advances from the existing messaging
infrastructure to make Web services requests and use our existing Web services
for external process integration.
Securing access to Web service providers
The gateway also allows setting access control on each of these internal
services, so that not every client can access every service, as would be the case
when locating our server on the Internet. We might want to restrict access for all
Web services or only certain operations.
Protocol transformation
The service requestor might use one particular communication protocol to invoke
Web services, while partners use some other protocol. Using the Web services
gateway, it is possible to trap the request from the client and transform it to
another messaging protocol. For example, a service provider might have
implemented a service using SOAP/JMS because of the existing infrastructure,
but it should also be possible to offer the service to clients that only understand
SOAP/HTTP.
170
WebSphere Version 5.1 Web Services Handbook
Web service access to non-SOAP objects
If we have some functionality not defined as a Web service, but as a JavaBean or
EJB, then we may not want to wrap a new Web service around that function
manually, but we want to do that implicitly by just defining the Java class or EJB
in the gateway.
General concepts
The gateway builds upon the Web services definition language (WSDL) and the
Web services invocation framework (WSIF) for deployment and invocation. In
general, we deploy a Web service not only to the server where it is actually
running, but also to the Web Services Gateway by deploying a WSDL file that
describes how the gateway should access the real implementation.
A request to the Web Services Gateway arrives through a channel, is translated
into an internal form, then passed through any filters that are registered for the
requested service, and finally sent on to the service implementation. Responses
follow the same path in reverse.
With the Web Services Gateway we can administer:
Web services—Register them to make them available either inside or outside
our intranet.
Channels—Define protocols that Web services can use, and also allow
switching of these protocols between client and server.
Filters—Apply filters that act upon the services, for example, logging and
data manipulation. In earlier releases of the gateway they were called
Interceptors.
References to UDDI registries—Use them in order to automatically publish
Web services from our gateway to UDDI registries.
Managing Web services
The primary function of the Web Services Gateway is to map an existing
WSDL-defined Web service to a new service that is offered by the gateway to
others. The gateway thus acts as a proxy. External services are imported into the
gateway and made available to the enterprise as internal proxy services.
Likewise, internal services are imported into the gateway and made available as
external proxy services. These services are also published to the relevant UDDI
registries where required.
Chapter 10. Web Services Gateway
171
Exposing Web services to the outside world
We can expose an internal service for outside use. Given the WSDL file, the
gateway will generate a new WSDL file that can be shared with outside
requestors. Of course the interface described in the WSDL will be exactly the
same, but the service endpoint will be changed to the gateway, which is now the
official endpoint for the service client.
If we have deployed Web services on a server inside the intranet, we might want
to allow access to clients from outside. We might also consider applying special
security constraints to restrict the access to either specific users and/or specific
methods of our service. This scenario is illustrated in Figure 10-1.
DMZ
Internet
Intranet
Web
Services
Gateway
Channel 1
Prefilter
Client
Channel 1 Postfilter
UDDI
deployed
WS
Channel 2
Web
Service
Channel 2 Implementation
external WSDL
internal WSDL
URI =
http://theGateWay.com/...
URI =
http://myInternalServer/...
Figure 10-1 Exposing Web services through the gateway
Importing Web services
An external service may be imported and made available as an internal service.
This will help the internal service requestors invoke the service as if it were
running on the gateway. Again, a new WSDL is generated by the gateway
showing the same interface but naming the gateway as the service provider
rather than the real internal server. The gateway then reroutes all requests to the
actual implementation specified in the original WSDL.
Of course, every client could access external Web services by traditional means,
but if we add the gateway as an additional layer in between, clients do not have to
change anything if the service implementor changes. This scenario is very
172
WebSphere Version 5.1 Web Services Handbook
similar to the illustration in Figure 10-1, with the difference that the client resides
in the intranet and the Web service implementation is located at a site on the
Internet.
Managing channels
A request for a service may originate in one protocol, but the service may be
invoked in some other protocol by using the transformation function. Let us
consider the case that an internal service is available on SOAP over JMS, but it
should be invoked using SOAP over HTTP. To handle such cases we need to
define a set of channels corresponding to the specific protocols that we wish the
gateway to receive messages on. The outbound channels over which the
gateway invokes the target Web services are defined implicitly by the bindings in
the WSDL imported in the gateway and do not have to be explicitly configured.
By using a different inbound channel to those defined in the imported WSDL
bindings, we can switch the protocol. This scenario is illustrated in Figure 10-2.
Client
Channel 1
SOAP/HTTP
Web
Services
Gateway
Channel 2
SOAP/JMS
Web
Service
Implementation
Figure 10-2 Using the gateway for protocol switching
Managing filters
We can develop and use one or more filters for our Web services, which means
that some specific task is done using the input and/or output messages to and
from our Web service. There are standard filters as well as the possibility of
creating our own. An illustration of filters, especially prefilters that manipulate
requests and postfilters that work on responses, is shown in Figure 10-1 on
page 172. Refer to “Managing filters” on page 173 for more information.
UDDI publication and lookup
The gateway facilitates working with UDDI registries. As we map a service for
external consumption using the gateway, we can publish the exported WSDL in
the UDDI registry. When the services in the gateway are modified, the UDDI
registry is updated with the latest changes.
Chapter 10. Web Services Gateway
173
Administering the gateway
To administer the Web Services Gateway, first start the WebSphere Application
Server Administrative Server. After that, start the administrative tool of the
gateway by opening a browser with the URL:
http://host:port/wsgw/admin/index.html
Where host and port are the host name and port number that our HTTP server is
listening on. We should reach a menu that allows us to configure the gateway:
Configure
Security
Back up
Restore
About
The gateway incorporates a facility to back up and restore the configuration. The
back up option writes the deployment details for all the channels, filters, UDDI
references and Web services deployed to the gateway. The restore option uses
the information contained in a previously saved file to update an empty
installation of the gateway with the same deployment details for those channels,
filters, UDDI references and Web services. Also, the gateway can improve its
performance and availability, if is configured so that a set of gateways acts as a
cluster.
We should also have a menu that allows administering (listing, deploying, and
removing) the artifacts:
Channels
Filters
UDDI references
Web services
Pay attention to the order in which the menu shows the options. This is exactly
the order in which we should also do our configuration:
1. Configure the URI for our gateway.
2. Define channels, filters, and UDDI references.
3. Define our Web services.
Note: If we change our gateway URI, we have to redefine all services. If we
want a Web service to use any channel, filter or UDDI reference, define them
before adding them to the service. However, we may update the list of
channels, filters, and/or UDDI references for a service at any time.
174
WebSphere Version 5.1 Web Services Handbook
Managing namespace URI and WSDL URI
Initial values for the namespace URI and WSDL URI are automatically
configured when we install the Web Services Gateway. This URIs are used by
the gateway:
Namespace URI—The namespace for the gateway services in exported
WSDL documents
WSDL URI—To generate the URL in import statements within exported
WSDL documents
To modify these values with the appropriate values of our environment, we have
to change the default values in the gateway administrative console under
configuration.
Managing channels
Channels are the entry points to the Web Services Gateway and transport
requests and responses between Web services and the Web Services Gateway.
A request to the Web Services Gateway arrives through a channel, is translated
into a WSIF message, and then passed through filters that are registered for the
requested service, and finally forwarded to the actual service implementation.
Before we can use a channel, we must install the channel application in
WebSphere Application Server, and then deploy the channel to the Web
Services Gateway.
Two versions of each type of channel are supplied with the gateway, so we can
set up separate channels for inbound and outbound requests. This also provides
a simple mechanism for giving different access rights to users from outside our
organization from the rights we give to users within our organization:
To ensure that users outside our organization can only access those internal
services that we choose to publish externally, we deploy those services on the
inbound channel.
To give users inside our organization access to the full range of internal and
external services, we deploy those services on the outbound channel.
A channel is in fact an application that is deployed to the application server.
Two channels are shipped with the gateway, both SOAP 1.1 compatible:
Apache SOAP channel—The SOAP message format must be RPC style.
SOAP/HTTP channel—The SOAP message format will be RPC or document
style and supports SOAP messages with attachments.
Chapter 10. Web Services Gateway
175
Once we have successfully installed our channels (or are satisfied with the
existing ones) we can use them when specifying Web services.
Managing filters
Filters are used to manipulate service invocations that reach the Web Services
Gateway, and responses that leave it. Filters can perform a wide range of tasks,
including logging messages, transforming their contents, and terminating
incoming requests.
Filters are in fact session beans that reside in a separate enterprise application.
To use a filter for a Web service, do the following steps:
1. Install the EAR file of the filter application.
2. Deploy that filter to the gateway using the admin tool.
3. Add this filter to the Web service definition in the gateway.
When deploying a filter to the gateway, specify a name and a home. This home is
the home interface of the session bean implementing the filter functionality.
Writing your own filters
Restriction: Writing your own filters is supported only by WebSphere
Application Server Enterprise Edition.
A filter is in fact a session EJB that implements a specific interface. So if we want
to create our own filter, we must develop a session bean that uses
com.ibm.wsgw.beans.FilterHome as the home interface and
com.ibm.wsgw.beans.FilterRemote as the remote interface.
The bean class must implement the filter interface and is therefore provided with
callback functions for initializing, destroying, and—more importantly—
intercepting (filtering) requests and responses. After implementing the bean, we
must do the following:
1. Install the application on the application server.
2. Deploy the filter to the gateway.
3. Specify the filter as pre- or postfilter in our Web service definition.
Managing UDDI references
A UDDI reference is a pointer to a UDDI registry. This may be a private or a
public UDDI registry, such as the IBM Business Registry (see “UDDI Business
Registry on the Web” on page 107).
176
WebSphere Version 5.1 Web Services Handbook
If we want any Web service to use a UDDI reference, define the reference first.
When specifying the reference, enter the information needed for accessing the
UDDI registry, such as inquiry API, user ID, and password.
Note that the values we enter for user ID and password must match those of the
owner of the corresponding business in the registry. We can see the owning user
ID in the UDDI registry by looking at the business details under the authorized
name field.
Managing security
The gateway provides facilities for secure communication between the service
requester and the gateway, and between the gateway and the target service.
These facilities go from transport level security to message level security.
Security can be applied at different levels:
Web service security (WS-Security)
Gateway-level authentication
Operation-level authorization
SSL protocol using HTTPS
Proxy authentication
Web service security (WS-Security)
We can configure the gateway for secure transmission of SOAP messages using
tokens, keys, signatures, and encryption in accordance with the Web Services
Security (WS-Security) draft recommendation. See Chapter 11, “Web services
security” on page 185.
The gateway sits between the client and the target Web service. When the
gateway is introduced, it can be thought of as two separate request/response
invocations: Client to gateway and gateway to target service. Thus, we need to
get, from the owning parties, the WS-Security configurations for both the client
and the Web service.
The configuration of the gateway is exactly the same as explained in Chapter 16,
“Web services security with Application Developer” on page 303. We have to
create a new security binding and configure with the required information:
Signing information
Encrypting information
Trust anchors
Certificates stores
Key locators
Trusted ID evaluators
Login mappings
Login bindings
Chapter 10. Web Services Gateway
177
Gateway-level authentication
For gateway-level authentication, we set up a role and realm for the gateway on
WebSphere Application Server’s Web server and servlet container, and define
the user ID and password that is used by the gateway to access the role and
realm. We also modify the gateway’s channel applications so that they only give
access to the gateway to service requestors that supply the correct user ID and
password for that role and realm.
Note: This means that gateway-level authentication must be enabled before
we install any channels.
Operation-level authorization
For operation-level authorization, we apply security to individual methods in a
Web service. To do this, we create an enterprise bean with methods matching
the Web service operations. These EJB methods perform no operation and are
just dummy entities for applying security. Existing WebSphere Application Server
authentication mechanisms can be applied to the enterprise bean. Before any
Web service operation is invoked, a call is made to the EJB method. If
authorization is granted, the Web service is invoked.
The target Web service is protected by wrapping it in an EAR file, and applying
role-based authorization to the EAR file:
If we want to enable operation-level authorization, we must first enable
gateway-level authentication.
After gateway-level authentication has been enabled, filters have access to
the requestor’s authentication information.
We can only apply operation-level authorization to a Web service that has
already been deployed to the gateway by enabling the option Authorization
Policy - Control access to this service.
Enabling operation-level authorization involves making changes to the file
/lib/wsgwauth.ear. To protect the installation version of this file, we should
make a backup copy of it before we change it.
SSL protocol using HTTPS
The Web services gateway can invoke Web services that include https:// in
their addresses, if the Java and WebSphere security properties have been
configured to allow it. This means that one gateway can send a SOAP/HTTPS
message directly to another gateway, rather than having to export services and
have clients invoke them using HTTPS.
178
WebSphere Version 5.1 Web Services Handbook
Proxy authentication
The gateway requires access to the Internet for invoking Web services and for
retrieval of WSDL files. Many enterprise installations use a proxy server in
support of Internet routing, and many proxy servers require authentication before
they grant access to the Internet.
For messages passing through the gateway, we can enable and disable proxy
authentication, and specify whether the authentication credentials are supplied
by the service requester or by the gateway. If we specify requester-supplied
credentials, the credentials in the HTTP message that the gateway receives are
re-instantiated by the gateway in the equivalent message that it sends on to the
proxy. If we specify gateway-supplied credentials, the gateway ignores any
credentials in the incoming HTTP message and supplies its own credentials in
the equivalent message that it sends on to the proxy.
Deploying Web services to the gateway
Important: Before we start to define any Web service, be sure that we have
correctly set up the gateway definition, which is the first menu item in the
admin portal. Any change to the Namespace URI there will mean that existing
Web services can no longer be found.
When we configure a Web service, we choose the following resources:
The channels on which the service is available
Any filters that apply to the service
Any UDDI references to UDDI registries in which the service is published
Security bindings that apply to the service
Each of these choices is made from a list of resources that have already been
deployed to the Web Services Gateway. So we should deploy our channels,
filters, and UDDI references before we deploy the Web services that use those
resources. However, we can later update the channels, filters, UDDI references
and security bindings for the service if necessary.
When deploying a service, specify the following information:
Gateway service name—Each Web service is identified by a unique name
without spaces in the gateway.
Message part representation:
– Generic classes—Select this option if there are no special EJB or Java
bindings.
Chapter 10. Web Services Gateway
179
– Deployed Java classes—Select this option if the target services for the
gateway service use Vectors, Enumerations, Hashtables or Maps, or
contain EJB or Java bindings.
Note: When we choose this option, we must also ensure that the specific
Java classes that have been generated for the Web service are available
to the gateway.
Authorization policy—Control access to this service. Use this check box to
enable or disable security for this gateway service.
Audit policy—Log requests to this service. The audit policy indicates whether
to log requests and responses for this Web service.
Channels—Add or remove channels from the list of deployed channels
through which this service is available.
Request filters—Add or remove filters from the list of deployed filters that are
applied to the request. Note: The filters are executed in the order shown.
Response filters—Add or remove filters from the list of deployed filters that
are applied to the response. Note: The filters are executed in the order
shown.
UDDI references—Add or remove UDDI references from the list of deployed
UDDI references to UDDI registries in which this service is registered. Note:
After we add or remove UDDI references, the gateway publishes this service
to (or removes it from) the UDDI registries that correspond to the added or
removed references.
Target services—Add or remove single instances of multiple target services
for this gateway service. To add a new target service instance, provide the
following information:
– WSDL location and type—Location of the internal WSDL file that
describes the Web service to be deployed. This value is either a URL or
the UDDI lookup information in the form:
uddi_reference_name,tmodel_key,key_name,key_value
Note: When the Web Services Gateway deploys the Web service, it
generates a matching external WSDL file that is made available to
gateway users. This external WSDL file also describes the service, but
is located at a new URL and is generated and maintained by the Web
Services Gateway itself.
– Target service name and namespace—If the Web service WSDL contains
more than one service, type the name and namespace of the target
service.
180
WebSphere Version 5.1 Web Services Handbook
– Target service identity information—Type the identity by which the target
service is known within the Web Services Gateway. This identity does not
have to be unique. This field is intended to be used within a routing filter to
select a target service by its identity value.
UDDI publication properties—We only need to fill out these fields if we use
UDDI references to automatically publish and update a registry:
–
–
–
–
–
Service provider name
Service provider description
tModel
tModel key name
tModel key value (for update only)
Security bindings—Select the security settings that are applied between the
target Web service and the gateway.
Troubleshooting
To identify and resolve gateway-related problems, we can use the standard
WebSphere Application Server facilities. If we encounter a problem that we think
might be related to the gateway, we can check for error messages in the
WebSphere Application Server Administrative Console, and in the application
server’s stdout.log file. We can also enable the application server debug trace
to provide a detailed exception dump. Refer to the WebSphere InfoCenter or the
publication WebSphere Application Server Version 5 Handbook, SG24-6195, for
details.
Implementation details
The gateway was first introduced on the alphaWorks Web site as Version 1.0 in
December 2001 (http://www.alphaworks.ibm.com) and later became part of the
IBM WebSphere Business Connection.
This package can be installed on top of IBM WebSphere Application Server
Version 4. The gateway is part of Application Server Version 5.0.2 and 5.1
Network Deployment.
The programming model extensions for writing filters are included in Application
Server Version 5.0.2 Enterprise Edition.
Note that the recent version of the gateway is rewritten using EJBs. Therefore, it
is no longer possible to use it on pure Web containers such as Tomcat; rather, we
need a complete J2EE server providing Web and EJB containers.
Chapter 10. Web Services Gateway
181
When installing and configuring the Web Services Gateway be sure to pay
attention to the following tips:
WSDL definitions for target services must use XML Schema Version 2001.
The gateway application (wsgw.ear) must be installed before channel and filter
applications. If the gateway application needs to be reinstalled, all channels
and filters must be uninstalled first, then reinstalled after the gateway
application.
Enhancements in Version 5.1
WebSphere Application Server Network Deployment 5.1 provides a number of
enhancements for the gateway:
Selective SOAP Parsing—Only the header is parsed for better performance.
Local EJB Calls—Internal change to use the local interface between WSGW
components (performance improvement).
JAX-RPC handlers—JAX_RPC handlers provided by the WebSphere SOAP
Engine can be used in the WSGW.
Proxy operation—Using the JAX-RPC handler, multiple services can be
invoked without having to be deployed to the WSGW.
SOAP over JMS—Limited support for SOAP over JMS Web services.
Security—Basic authentication, HTTPS, and Web services security.
Summary
The Web Services Gateway is a middleware component that bridges the gap
between Internet and intranet environments during Web service invocations. It
can be used to expose Web services from the intranet to the outside world. We
also can specify external Web services to use them inside our intranet. For both
types of services we can specify filters to be applied before and/or after a specific
service is called. When defining channels, we can translate from one protocol to
another, if the client and server do not use the same.
The gateway also automates the publishing and updating of our services in UDDI
registries and incorporates possibilities to apply security on Web services and/or
its methods.
182
WebSphere Version 5.1 Web Services Handbook
More information
An introduction to Web Services Gateway:
http://www.ibm.com/developerworks/library/ws-gateway/
WebSphere Business Connection - Web Services Gateway:
http://www.ibm.com/software/integration/busconn/gateway.html
Download the Web Services Gateway:
http://www7b.boulder.ibm.com/wsdd/downloads/wsgw/wsgw.html
Chapter 10. Web Services Gateway
183
184
WebSphere Version 5.1 Web Services Handbook
11
Chapter 11.
Web services security
Web services security is one of the most important Web services issues. It is
hard to believe that one would be ready to publish or use a business service such
as a stock purchase or bank account transfer without a proper security
framework. In WebSphere 5.0.2 and 5.1, Web services security can be provided
at the transport level (SSL) and at the message level (WS-Security specification).
Highly secure client-server designs can be architected using these security
levels.
In this chapter we first address the main security requirements in a Web
services-based application. We briefly cover the transport channel security
solutions and then devote most of this chapter to the discussion on how the
WS-Security specification support in WebSphere Application Server 5.0.2 and
5.1 can be fully utilized.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
185
Common security exposures
First let us highlight the major security risk factors of concern when designing
mission critical Web services-based applications. Let us use a bank teller
scenario as a starting point. It is a simple client/server application where a bank
teller (client) connects to the bank’s data center (server) using a Web services
application (Figure 11-1).
Bank
Data Center
Bank Teller 1
Network
Bank Teller 2
Figure 11-1 A sample bank teller application based on Web services
If no security has been applied, the three major risk factors are:
Unauthorized transactions: Someone posing as a bank teller sends a
SOAP message to the data center requesting to withdraw money.
This transaction is unauthorized. We fix this problem using the authentication
mechanism of the WS-Security specification. An example of authentication is
to include a user ID/password combination in the SOAP message.
Readable messages in clear text—no encryption: The account number
and balance in the SOAP packet is read by a sniffer on the network.
This exposure exists because the account and balance information is sent
over the wire in plain text. As solution to this problem, plain text can be
converted to unreadable form by encrypting the message either at the
transport level (SSL) or at the message level (WS-Security).
186
WebSphere Version 5.1 Web Services Handbook
SOAP message susceptible to modification—no integrity: While the
SOAP message is travelling from the teller to the data center, it is intercepted
on the way. The interceptor modifies the message, and deposits the money in
account number 1234 instead of account number 9876.
The security exposure is due to lack of message integrity. This can be solved
by applying a message integrity mechanisms as described in the WS-Security
specification. An example is to use security tokens.
In the above scenarios, we have described security concerns that fall under the
areas of authentication, confidentiality, and integrity. We will discuss each of
these terms in detail in this chapter and provide various options on how to ensure
fully secure environments that safe-guard you against such risks. All these
security mechanisms are fully supported in WebSphere 5.0.2 and later.
Making Web services communications secure is not a question of if it can be
done, but more of a question of how much processing power it will require. What
we mean by that is that we can make applications fully secure, but the more
security we apply, the more CPU time will be required by the application.
Prior to the WS-Security specification, transport channel security was very
commonly used. Transport channel security encrypts the entire message,
resulting in higher CPU utilization. The recent advancements in the WS-Security
specification provide ways to optimize security operations, which in turn require
less CPU time. The security techniques are summarized in Figure 11-2.
Applying security to
Web Services
SOAP message level
security
(WS-Security)
Authorization
Confidentiality
example:
username
password
example:
message
encryption
Transport Channel security
(SSL)
example: encrypt the entire message
(for HTTP this means encrypting the
entire HTTP message)
Integrity
example:
security token
Figure 11-2 Overview of applying security to Web services
Chapter 11. Web services security
187
Based on the level of security required, one or more of these security features
may be applied to an application.
In the following sections we cover different security approaches and their
limitations.
WS-Security concepts
Now that we have discussed Web services security provided either by the
underlying communication channel middleware or at the XML document level, we
give an overview of WS-Security, a standard proposition that covers security
requirements at the Web services level.
The WS-Security specification covers a standard set of SOAP extensions that
can be used when building secure Web services to provide integrity and
confidentiality. It is designed to be open to other security models including PKI,
Kerberos, and SSL. WS-Security provides support for multiple security tokens,
multiple signature formats, multiple trust domains, and multiple encryption
technologies.
The specification includes security token propagation, message integrity, and
message confidentiality. However, these mechanisms by themselves do not
address all the aspects of complete security solution. Therefore, WS-Security
represents only one of the layers in a complex secure Web services solution
design.
Evolution of the WS-Security specification
The WS-Security support provided in WebSphere 5.0.2 and later is based on the
Web services security language (WS-Security) proposed by IBM, Microsoft, and
Verisign in April 2002. In WebSphere 5.0.2 and 5.1, this support is provided by
the IBM WebSphere SOAP Engine.
After the formalization of the April 2002 specification, more specifications have
been added in this area. Some of the more recent advancements in this area
have been performed under the OASIS consortium:
http://www.oasis-open.org
Figure 11-3 shows the evolution of WS-Security.
188
WebSphere Version 5.1 Web Services Handbook
April 2002
WS-Security
August 2002
WS-Security
Addendum
September 2002
WS-Core Draft 1
May 2003
WSS: Soap
Message Security
Draft 13
Oasis
Activities
February 2003
WSS:Username
Toke
Profile Draft 2
Figure 11-3 Evolution of Web services security
To read more about these standards, refer to:
Specification: Web Services Security (WS-Security) Version 1.0 (April 2002):
http://www-106.ibm.com/developerworks/webservices/library/ws-secure/
Web Services Security Addendum (August 2002):
http://www-106.ibm.com/developerworks/webservices/library/ws-secureadd.html
Web Services Security: SOAP Message Security Working (May 2003):
http://www.oasis-open.org/committees/download.php/2314/WSS-SOAPMessageSecur
ity-13-050103-merged.pdf
Note: If you develop the Web services application using WebSphere Studio
Application Developer Version 5.1.1, tools are provided for easily specifying
security information. With the help of these tools you do not have to
understand the SOAP format in detail.
WS-Security authentication
In Example 11-1 and Example 11-2 we show a SOAP message with and without
authentication. As you can see, with the authentication information in the SOAP
message, we have a username and password information in the message.
Example 11-1 SOAP message without security
<soapenv:Envelope xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
Chapter 11. Web services security
189
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body
soapenc:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<getDayForecast xmlns="http://session.itso">
<theDate xmlns="" xsi:type="xsd:dateTime">2003-09-05T07:00:00.000Z</theDate>
</getDayForecast>
</soapenv:Body>
</soapenv:Envelope>
Example 11-2 SOAP message with authentication
<soapenv:Envelope xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<wsse:Security
xmlns:wsse="http://schemas.xmlsoap.org/ws/2003/06/secext"
soapenv:mustUnderstand="1">
<wsse:UsernameToken>
<wsse:Username>stade2</wsse:Username>
<wsse:Password>PassWordHere</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body
soapenc:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<getDayForecast xmlns="http://session.itso">
<theDate xmlns="" xsi:type="xsd:dateTime">2003-09-05T07:00:00.000Z</theDate>
</getDayForecast>
</soapenv:Body>
</soapenv:Envelope>
When the username and password reach the Web service server, the message
will be processed only if the username/password combination is a valid
combination.
Alternatives to using a username/password mechanism
Username and password validation is just one of the ways of implementing
authentication. This mechanism is also known as basic authentication. Other
forms of authentication are digital signature, ID assertion, LTPA, and custom
tokens.
190
WebSphere Version 5.1 Web Services Handbook
Enable authentication in your application
Application Developer provides user friendly screens that help you define
authentication for the Web services application. Many of these steps can be
performed using “drop/select”. In a typical application, the following tasks have to
be performed to enable the application for authentication.
Client side:
Provide a security token in the client’s deployment descriptors file. An
example of security tokens is a username and password combination. This
security token is sent inside the SOAP message to the server.
Specify a callback handler in the client’s deployment descriptor. The callback
handler is a class file in the classpath of the client. The role of the callback
handler is to grab the username and password from the deployment
descriptor and insert them into the SOAP message. Callback handlers are
provided by the WebSphere Web services runtime.
Server side:
Configure the server to expect a SOAP message containing a valid security
token. Without the security token, the request will fail.
Specify a callback handler that will read the security token in the request and
then validate it.
Turn on global security in the WebSphere Application Server where the
application is deployed.
More information about using Application Developer to implement authentication
is in Chapter 16, “Web services security with Application Developer” on
page 303.
WS-Security integrity
Integrity safeguards are applied to the application to ensure that no one illegally
modifies the message while it is in transit. Essentially what integrity does is that it
creates an XML digital signature based on the contents of the message. If the
message data changes illegally, it would no longer be compatible with the XML
digital signature.
A signature is created based on a key that the sender is authorized to have.
Unauthorized sniffers do not have this key. When the recipient gets the message
it too creates a signature using the message contents. Only if the two signatures
match does the receiver honor the message. If the signatures are different, an
error is returned to the sender.
Chapter 11. Web services security
191
Example 11-3 shows a sample SOAP message with integrity. Different parts of
the message can be digitally signed, parts such as message body, security
token, and timestamp. In this example we digitally signed the security token and
message body.
Example 11-3 SOAP message with Integrity
<soapenv:Header>
<wsse:Security
xmlns:wsse="http://schemas.xmlsoap.org/ws/2003/06/secext"
soapenv:mustUnderstand="1">
<Signature>
<SignatureValue>
G+p3CZiiT/yYmkzORKt2m4KSEybc+dYEBUqbPUxA+L5epHSsy5FuxCW2XCJf
ner5nov80OJdadyHCf0qfLI2Wzrx09JL0k4t+BtzgSY2B1tTIdgO770NcIIf
Uq3uD9mAdVGuwKFqIofG0Kuh78ae1OjQk+Ty37FJqpVQCwxeSj0=
</SignatureValue>
<KeyInfo>
<wsse:SecurityTokenReference>
<wsse:Reference
URI="#wssecurity_binary_security_token_id_3202627907101346821">
</wsse:Reference>
</wsse:SecurityTokenReference>
</KeyInfo>
</Signature>
</wsse:Security>
</soapenv:Header>
<soapenv:Body xmlns:wsu="http://schemas.xmlsoap.org/ws/2003/06/utility"
soapenc:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
wsu:Id="wssecurity_body_id_6085481372815191153">
<getDayForecastResponse xmlns="http://session.itso">
<getDayForecastReturn xmlns="" href="#id0"></getDayForecastReturn>
</getDayForecastResponse>
<multiRef xmlns:ns-239399687="http://mapping.itso" id="id0" soapenc:root="0"
soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xsi:type="ns-239399687:Weather">
<condition xsi:type="xsd:string">rainy</condition>
<date xsi:type="xsd:dateTime">2003-09-05T07:00:00.000Z</date>
<windDirection xsi:type="xsd:string">NE</windDirection>
<windSpeed xsi:type="xsd:int">2</windSpeed>
<temperatureCelsius xsi:type="xsd:int">3</temperatureCelsius>
<dbflag xsi:type="xsd:boolean">1</dbflag>
</multiRef>
</soapenv:Body>
192
WebSphere Version 5.1 Web Services Handbook
Steps to enable integrity in your application
The client and the server have to be equipped with integrity information. This can
be performed with considerable ease using Application Developer as discussed
in Chapter 16, “Web services security with Application Developer” on page 303.
Client side:
Specify the parts of the message that have to be digitally signed. The
message parts that can be signed are body, security token, and timestamp.
Specify a key on the file system that will sign the message. Only authorized
clients are in the possession of this key.
Specify algorithms that will be used by the key to sign the message.
If a client expects a response that includes integrity information, then the
client has to be configured to validate the integrity of the response message.
Server side:
Configure the server to expect a SOAP message that contains integrity
information. Specify the parts of the message that are signed. If the incoming
message does not have a valid signature, the request will fail.
Specify a key that validates the signature of the incoming message.
Specify the algorithm that the key uses to validate the integrity of the incoming
message.
If the response message has to be signed as well, provide similar signing
information in the response.
WS-Security confidentiality
Confidentiality is the process by which a SOAP message is protected so that only
authorized recipients can view the SOAP message. The WS-Security
specification allows encryption of any combination of body blocks, header blocks,
their substructures, and attachments of a SOAP message.
In Example 11-4 you can see the SOAP body with encryption.
Example 11-4 SOAP body with encyption
<soapenv:Body
xmlns:wsu="http://schemas.xmlsoap.org/ws/2003/06/utility"
soapenc:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
wsu:Id="wssecurity_body_id_4015458811382627755"><EncryptedData
xmlns="http://www.w3.org/2001/04/xmlenc#"
Id="wssecurity_encryption_id_4611467978057449038"
Type="http://www.w3.org/2001/04/xmlenc#Content">
<EncryptionMethod
Chapter 11. Web services security
193
Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc">
</EncryptionMethod>
<EncryptedData>
<CipherData>
<CipherValue>
cc1V//9/+mT2GerGLrCb2q7cur79S2RSx/g8V2CytHuO/KeGbGms88OKadFZB144zGSgDFggSvR7gao
eJWU6ZsBM5uKvdN1yDxSiYBWXZ3e8rBByYa3N9PW1BaHFVOdTMOlc4m9MLpVyzhGb/t6utrpIdgaVrp
p9Pi1s1MN7oFn/CUbCH6V5FsQFDNOkpd8dULAtArgNw4I4I3YfHO8v/A==
</CipherValue>
</CipherData>
</EncryptedData>
</soapenv:Body>
Steps to enable confidentiality in your application
The steps to enable confidentiality follow.
Client side:
Specify the parts of the message that are to be encrypted.
Specify a key on the file system that will encrypt the message. Only
authorized clients posses this key.
Specify algorithms that are used by the key to encrypt the message.
If the response message is also encrypted, the client has to be configured
with the location of the decryption key and decryption algorithms.
Server side:
Specify the parts of the incoming message that are encrypted.
Configure the WebSphere runtime so that it is able to use the decryption key.
This configuration change is made using an administrative tool such as the
Administrative Console.
Specify a key on the file system that will decrypt the message.
Specify algorithms that will be used by the key to encrypt the message.
If the response message is also encrypted, the server has to be configured
with the location of the encryption key and encryption algorithms.
Transport channel security
Prior to the message level WS-Security, a popular means of securing Web
services messages was transport channel security. It is implemented for
SOAP/HTTP-based messages by using the HTTPS protocol. Unlike message
level security, HTTPS provides security to the entire HTTP data packet.
194
WebSphere Version 5.1 Web Services Handbook
Therefore, we do not have an option to apply security selectively only on certain
parts of the message.
SOAP/HTTP transport channel security
HTTP, the most commonly used protocol for information exchange on the
Internet, is an inherently insecure protocol, because all information is sent in
clear text between unauthenticated peers over an insecure network. It belongs to
the group of protocols, such as SMTP, telnet, and FTP, that were designed in the
earlier stages of the Internet, when security seemed not to be an issue, and will
eventually be replaced by transfer protocols that allow authentication and
encryption.
An evolution of HTTP is HTTPS, which stands for HTTP via SSL (Secure Sockets
Layer). HTTPS allows client and server-side authentication through certificates,
which have been either self-signed or signed by a certification agency.
Upon establishing a secure connection, the server and the client negotiate the
SSL protocol version to use, and a unique session ID is established. If the
certificate presented by the server is unknown to the client, the client is free to
accept or reject the certificate. In turn, the server can also demand a certificate
from the client. During a secure session, the server and client share a common
key pair that allows them to encrypt and decrypt messages they exchange.
Although HTTPS does not cover all aspects of a general security framework, it
provides a sufficient security level regarding party identification and
authentication, message integrity, and confidentiality. However, authentication,
auditing, and non-repudiation are not provided. Also, it is protocol-based and
therefore all the security disappears once the message has passed the HTTP
server. In addition, the encryption is message-wise and not element-wise; to
access the routing information, we have to decrypt the entire message.
WS-Security extensions
Because the WS-Security standard addresses only a subset of security services,
a more general security model is needed to cover other security aspects such as
logging and non-repudiation. This resulted in a common Web services security
model framework, a proposition developed by IBM and Microsoft, which we
describe in the following section.
Chapter 11. Web services security
195
Web services security model proposition
The Web services security model introduces a set of individual interrelated
specifications to form a layering approach to security. It includes several aspects
of security: Identification, authentication, authorization, integrity, confidentiality,
auditing, and non-repudiation. It is based on the WS-Security specification,
co-developed by IBM, Microsoft, and VeriSign.
The Web services security model is schematically shown in Figure 11-4.
WS-Security Layer
SOAP Foundation Layer
UsersWS-SecureConversation
User Groups
WS-Federation
Passwords
WS-Authentication
Policies
WS-Policy
Privileges
Encryption Keys
WS-Trust
Audit Logs
WS-Privacy
Today
Future - specification in progress
Figure 11-4 Web services security model
The specification includes different aspects of Web services security:
WS-SecureConversation Describes how to manage and authenticate
message exchanges between parties, including
security context exchange and establishing and
deriving session keys.
WS-Federation
196
Describes how to manage and broker the trust
relationships in a heterogeneous federated
environment, including support for federated
identities.
WebSphere Version 5.1 Web Services Handbook
WS-Authentication
Describes how to manage authentication data and
authentication policies.
WS-Policy
Describes the capabilities and constraints of the
security (and other business) policies on
intermediaries and endpoints (for example, required
security tokens, supported encryption algorithms,
and privacy rules).
WS-Trust
Describes a framework for trust models that enables
Web services to securely interoperate.
WS-Privacy
Describes a model for how Web services and
requestors state privacy preferences and
organizational privacy practice statements.
The combination of these security specifications enables many scenarios that
are difficult or impossible to implement with today's more basic security
mechanisms such as transport securing or XML document encryption. At the
time this book was written, the above specification was a proposal under review.
End-to-end enterprise security
Since the early days of the Internet as a universal network open to anyone, there
has been a concern for secure information exchange. Although it is worth noting
that there is no absolute security, developments in this field were very quick and
fruitful because they were driven by urgent business needs. Without an
appropriate level of security, the commercial exploitation of the Internet would not
be feasible.
Networks must be designed to provide a high level of security for information that
travels across the Internet or privately managed intranets or extranets.
Algorithms such as third-party authentication, public key encryption, and digital
signature can provide a sufficient level of security. However, security not only
depends on algorithms, standards, and products, but companies must also follow
security best-practice recommendations.
Note: A company’s security policy should reasonably cover the most
important procedures, such as user management (adding/removing users and
granting their rights and access levels), network use guidelines (private mail,
Web site access policy, and antivirus protection), user authentication
procedure (user ID/password, key cards), system monitoring procedures, and
procedures in case of attack.
Chapter 11. Web services security
197
A general security framework should address the following requirements:
Identification—The party accessing the resource is able to identify itself to
the system.
Authentication—There exists a procedure to verify the identity of the
accessing party.
Authorization—There exists a set of transactions the authenticated party is
allowed to perform.
Integrity—The information is not changed on its way.
Confidentiality—Nobody is able to read the information on its way.
Auditing—All transactions are recorded so that problems can be analyzed
after the fact.
Non-repudiation—Both parties are able to provide legal proof to a third party
that the sender did send the information, and the receiver received the
identical information.
Some classifications also include availability to be a part of the above schema,
meaning that hostile attack cannot achieve denial-of-service by allocating too
many system resources. In this chapter, we do not deal with this security aspect.
Figure 11-5 shows the main components of a security framework (based upon
ISO standard 7498-2).
Most of the systems involved in Web services today only partially fulfill these
requirements.
198
WebSphere Version 5.1 Web Services Handbook
SECURITY MANAGEMENT
Service Management
Policy Management
Mechanism Management
Audit & Alert Management
Object Management
SEC. SERVICES
SEC. MECHANISMS
SEC. OBJECTS
Identification
Entity Authentication
Users
Authentication
Message Authentication
User Groups
Authorization
Enchiper/Dechiper
Passwords
Integrity
Access Control List
Policies
Confidentiality
Security Objects
Privileges
Auditing
Modification Detection
Encryption Keys
Non-repudiation
Digital Signature
Audit Logs
Figure 11-5 Main building blocks of a security framework
Summary
Web services technology enables a loosely coupled, language-neutral,
platform-independent way of linking applications within organizations, across
enterprises, and across the Internet. To achieve the target, however, it is
essential for Web services to provide a sufficient level of security to support
business transactions. Ensuring the integrity, confidentiality, and security of Web
services through the application of a comprehensive security model is critical,
both for organizations and their customers.
More information
Because Web services security is a quickly evolving field, it is essential for
developers and designers to regularly check for recent updates. In this section,
we provide some of the most important entry points for your exploration.
Chapter 11. Web services security
199
For information on IBM Tivoli® Access Manager for Business Integration, refer to
this Web site:
http://www.tivoli.com/products/index/access-mgr-bus-integration/
For information on IBM WebSphere MQ, refer to the standard proposition
overview on developerWorks:
http://www.ibm.com/software/ts/mqseries/messaging/
XML Signature Workgroup home page can be found at:
http://www.w3.org/Signature/
XML Encryption Workgroup home page can be found at:
http://www.w3.org/Encryption/
The SAML (security assertions markup language) Oasis Security Services
Technical Committee home page can be found at:
http://www.oasis-open.org/committees/security/docs/draft-sstc-use-strawman03.html
For information on WS-Security, refer to the standard proposition overview on
developerWorks:
http://www.ibm.com/developerworks/library/ws-secure/
The Web services security model proposition can be found at:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwssecur/
html/securitywhitepaper.asp
There are several commercial and non-commercial information sources that
cover more general subjects, such as SSL encoding and HTTPS protocol.
200
WebSphere Version 5.1 Web Services Handbook
Part 2
Part
2
Web services
implementation
and samples
In this part we describe practical examples using the IBM WebSphere products
and tools and the Web Services Toolkit.
We introduce the products and a simple Web service example that we then
implement in various stages using the products.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
201
202
WebSphere Version 5.1 Web Services Handbook
12
Chapter 12.
IBM WebSphere product
family
This chapter provides an overview of the WebSphere product family. We
describe the software packages that represent the core of IBM’s e-business
offerings.
We provide more details on WebSphere Application Server and WebSphere
Studio products in the chapters that follow, but in this chapter we provide a
general technical feature overview as well as the positioning information for the
other WebSphere family packages.
The WebSphere family products fall into one of these groups:
Foundation and tools—WebSphere Application Server, WebSphere MQ,
WebSphere Studio
Reach and user experience—WebSphere Portal, WebSphere Everyplace™,
WebSphere Commerce
Business integration—WebSphere Business Integration, WebSphere MQ
Integrator Broker
© Copyright IBM Corp. 2003, 2004. All rights reserved.
203
Overview
The IBM WebSphere family of products represents the core IBM offering for
customers who want to transform their business to e-business. The main groups
and products are shown in Figure 12-1.
WebSphere Portal Server
WebSphere Business Integration
WebSphere Everyplace
WebSphere MQ
Integrator Broker
WebSphere Commerce
WebSphere Application Server
WebSphere Studio
WebSphere MQ
Figure 12-1 WebSphere product family
In general, the WebSphere family of products are in one of the following groups:
Foundation and tools—This group contains products that represent the
basic functional infrastructure for other products, such as WebSphere
Application Server and WebSphere MQ. It also contains WebSphere Studio, a
set of development tools for enterprise Web-based applications.
Reach and user experience—In this group we find the products that help the
applications extend their range and reach new customers, such as
WebSphere Portal and WebSphere Everyplace. WebSphere Commerce, on
the other hand, enables customers to create online stores and move their
business from traditional channels to the Internet.
Business integration—Products such as WebSphere MQ Integrator Broker
and its extension, WebSphere Business Integration, help customers to
interconnect their islands of information and make full use of the
message-based architecture.
204
WebSphere Version 5.1 Web Services Handbook
The products of the first group are directly involved with Web services
technology. WebSphere Application Server is the runtime environment of choice,
WebSphere Studio provides the development environment, and WebSphere MQ
provides JMS support as well as an alternative way of SOAP message
interchange. The products from the other groups, on the other hand, represent a
vehicle for extending Web services to enterprise environments and users.
We cover these groups and products in the following sections.
WebSphere foundations and tools
The products from this group are most directly related to Web services.
WebSphere Studio products provide a range of tools and functions for the
development and testing of Web services solutions. WebSphere Application
Server represents an enterprise-level runtime environment for Web
services-enabled applications and provides workload management, scalability,
and security. WebSphere MQ provides an underlying message-oriented
infrastructure as well as a channel for SOAP message exchange, in addition to
other options such as HTTP and HTTPS.
WebSphere Application Server
IBM WebSphere Application Server represents one of the IBM foundations of a
business on demand infrastructure. It is the Java 2 Enterprise Edition (J2EE) and
Web services technology-based application platform, offering one of the first
production-ready application servers for the deployment of enterprise Web
services solutions for dynamic e-business.
WebSphere Application Server Version 5 provides an integration of deployment
model, administration point, programming model, and integrated application
development environment. It is fully J2EE 1.3 compatible. It delivers multiple
configuration options for a wide range of scenarios, from simple administration of
a single server to a clustered, highly available, high-volume environment with
edge-of-network services. It offers advanced server technology, a
production-ready environment, and visual workflow support for key Web services
standards.
The product is available for a broad range of platforms, including Windows
NT/2000/XP, Linux, AIX®, Sun Solaris, HP-UX, and z/OS™.
Packaging
WebSphere Application Server is available in several different configurations
tailored to cover different levels of user requirements.
Chapter 12. IBM WebSphere product family
205
WebSphere Application Server - Express
Express offers an affordable solution for managing simple dynamic Web sites
with a simplified Web application server and a development environment based
on WebSphere Studio. It is based on the latest Java technology and Web
services standards. It allows you to convert static Web sites into dynamic Web
applications that improve the customer experience. It provides a five-click
wizard-driven installation. It is an entry-level configuration that offers a smooth
migration path to other WebSphere Application Server and WebSphere Studio
configurations.
WebSphere Application Server
The basic WebSphere Application Server represents the production-ready
Java-based application server with integrated enterprise data and transaction
support for the e-business world. It offers a set of application services that
include enhanced capabilities for enablement and management of
heterogeneous Web services, increased security, performance, availability,
connectivity, and scalability.
It supports such core Web services standards as XML, Simple Object Access
Protocol (SOAP), JAX-RPC and Web services description language (WSDL). It
also extends the Java 2 Enterprise Edition (J2EE) 1.3 programming model by
providing an infrastructure to support production-ready deployment of Web
services-based applications. This makes it possible to deploy Web services with
the communication mechanism of your choice, including SOAP and HTTP, Java
Message Service (JMS), or Remote Method Invocation Internet Inter-ORB
Protocol (RMI-IIOP).
WebSphere Application Server Network Deployment
The Network Deployment Edition provides advanced Web services and
clustering capabilities. It offers a private UDDI registry for easier deployment of
internal Web services applications and the Web Services Gateway for external
applications that request Web services from an internal Web services provider
application.
WebSphere Application Server Enterprise Edition
The Enterprise Edition provides an advanced application server configuration
that simplifies build-to-integrate tasks, accelerates application development, and
enables dynamic application flexibility. It offers build-to-integrate capabilities such
as advanced application adapters, application workflow composition and
choreography, extended messaging, dynamic rules-based application
adaptability, internationalization, and asynchronous processing. It delivers more
integration capabilities than WebSphere Application Server Network Deployment
through extensions beyond the limitations of the J2EE standards.
206
WebSphere Version 5.1 Web Services Handbook
Current status and outlook
WebSphere Application Server Version 5 became available at the end of 2002.
Version 5 offers a variety of key benefits:
Full J2EE 1.3 compatibility together with the support of the latest stable
versions of J2EE components (EJB 2.0, Servlet 2.3, JSP 1.2). The
development of enterprise applications is easier when they are based on
standardized, modular components.
Seamless configurations and administration, based on Java Management
Extensions (JMX). The administration facility is browser-based across all
deployment options.
Improved programmer productivity and simplified enterprise development with
JMS API. It also supports core Web services standards, such as XML, SOAP,
and WSDL, as well as enhanced options, such as the Web Services Gateway
and a private UDDI registry.
Enhanced security model provides extensive support of open
standards-based Java specifications, such as Java 2 Security and JAAS, as
well as WebSphere’s pluggable security architecture.
WebSphere Application Server Version 5.0.2 updates
WebSphere 5.0.2 (WebSphere Version 5 Fix Pack 2) provides not only fixes, but
also adds new functionality to the WebSphere platform. Here are the major
enhancements in WebSphere 5.0.2:
Web services updates
– JSR 101 and JSR 109 support—Explained in Chapter 4, “JAX-RPC (JSR
101)” on page 67, and Chapter 5, “Implementing Enterprise Web Services
(JSR 109)” on page 77
– SOAP/JMS support—Explained in Chapter 15, “WebSphere Studio
Application Developer” on page 247, and “Web services runtime and
deployment in WebSphere” on page 479
– WS-Security—Explained in Chapter 11, “Web services security” on
page 185
– SOAP with Attachments API for Java (SAAJ) 1.1 support:
http://java.sun.com/xml/saaj/
– WebSphere SOAP Engine—New SOAP engine to support JSR 101, JSR
109, and WS-Security
Expanded operating system and database support
Usability and performance improvements
Chapter 12. IBM WebSphere product family
207
WebSphere Application Server Version 5.1 updates
WebSphere Application Server Version 5.1 provides these enhancements:
Support for Java SDK 1.4.1, without exploitation of new functions.
– Applications compiled with 1.3 will run on 1.4.
UDDI utility tools (export, import, find, delete, promote from one registry to
another). Refer to “WebSphere Application Server 5.1 update” on page 124
for more details.
Web Service Gateway enhancements, including JAX-RPC handler support
and SOAP over JMS.
Tivoli Access Manager (TAM) Version 5.1 integration; TAM can be used to
authenticate users in LDAP.
Support for Jython as scripting language in wsdadmin (Jython is a Java
implementation of Python).
An application server can start without the node agent running.
More information
For more information on IBM WebSphere Application Server, refer to:
http://www.ibm.com/software/webservers/
Information Center
The WebSphere Information Center is available online at:
http://www.ibm.com/software/webservers/appserv/infocenter.html
WebSphere Studio
The WebSphere Studio family of products is a set of development tools for
enterprise e-business Java-based applications. Besides programming tools, it
also enables the developers to test and deploy their application from the common
environment. The rich set of utilities and wizards helps developers to simplify
common tasks so that they can concentrate on more creative parts of their jobs
and be more productive.
The new WebSphere family of the products combines the functionality of the two
former lines of IBM development tools, VisualAge® for Java, and WebSphere
Studio (classic). The entire family is based on the WebSphere Studio
Workbench, which contains a released level of the Eclipse Workbench. The
Eclipse Workbench is an open-source project (IBM contributed the initial
Workbench to Eclipse) that provides a general platform for different tools that will
enable them to share the same look-and-feel and to integrate more smoothly.
208
WebSphere Version 5.1 Web Services Handbook
The WebSphere Studio Workbench will continually incorporate the features of
new releases of the Eclipse Workbench as the open-source community makes
them available.
Packaging
The WebSphere Studio family has several member products (Figure 12-2). They
are all based on the common Eclipse Workbench, whereas the many
accompanying tools and plug-ins are tailored to the different needs of the
developers.
Application Developer
Site
Site Developer
Developer
Core Java IDE
Create Web pages
Struts support, JSP tags
XML support
JavaBean/DB Wizards
Web Services Wizards
Team Environment
Integrated WebSphere
App Server Express
EJB Development
J2EE Development
J2EE Deployment
Profiling
Integrated WebSphere
App Server
Enterprise Developer
Application Developer
Integration Edition
Enterprise Connectors
(CCF and J2C)
Web service flow
modeling
WSDL Editor
Integrated WebSphere
App Server Enterprise
Enterprise Generation
Language (EGL)
COBOL and PL/I
z/OS Development
Environment
Figure 12-2 WebSphere Studio Product Suite
WebSphere Studio Site Developer
The Site Developer package is a set of tools and perspectives targeted for
developers of Web sites and Web applications. The tools support open Web
standards such as XML, JavaServer Pages (JSPs), and Web services. The tools
inherited from the Workbench also support Java and JavaScript development. In
Chapter 12. IBM WebSphere product family
209
addition, there is a rich set of media tools required for developing a high-quality
user interface.
The Web services tools include those for creating services from Java
components and publishing their descriptions to a UDDI registry. It is also
possible to browse a UDDI registry for available services and link to them from
the Web application through JSPs.
The Common Versions System (CVS) repository interface is a part of the Studio
Workbench. In addition, Site Developer provides an interface to Rational®'s
ClearCase® LT product. A WebSphere Express test environment is also part of
the package.
WebSphere Studio Application Developer
Application Developer contains all the functionality of the Site Developer. In
addition, it contains the tools for J2EE 1.2 and J2EE 1.3 development as well as
a set of profiling tools. The WebSphere test environment provides full J2EE
support including EJBs.
Application Developer Version 5.1 introduced new functions to match
WebSphere Application Server Version 5.0.2:
Web services enhancements—Support for JSR 101 (JAX-RPC), JSR 109
(Implementing Enterprise Web Services), and WS-Security 1.0
Built-in Application Server 5.0.2
Performance improvements—Especially install, uninstall, EJB code
generation
UML Visual Editor—Visualize Java and J2EE components in UML
Website Builder—Graphically building Web pages and their relationships
Page Designer enhancements—Free layout mode, improved taglib support
Struts—Support for Struts 1.1
Container-managed entity EJB—Mapping to view
Visual Editor—Event support
SQLJ—Support for SQLJ applications and usage of SQLJ for EJBs
Debugger—Hot method replace through new JVM
Application Developer Version 5.1.1 introduced new functions to match
WebSphere Application Server Version 5.1:
Built-in Application Server 5.1
Support for JDK 1.4.1 (although Application Developer runs on JDK 1.3.1)
210
WebSphere Version 5.1 Web Services Handbook
J2EE enhancements—Server targeting (for servers running on different
JDKs), EJB Client JAR support
Beta support for JavaServer Faces (JSF) and WebSphere Data Objects
(WDO)
– JSF—GUI framework for J2EE applications
– WDO—JSF objects for relational database access
WebSphere Studio Application Developer Integration Edition
Application Developer Integrated Edition is targeted for professional developers
of J2EE applications and Enterprise Extensions. It contains all the functionality of
the Application Developer. In addition, it contains J2C support, Web services
invocation framework, workflow and Web flow modeling tools, an enhanced
WSDL editor, and an integrated WebSphere Application Server Enterprise
Edition.
WebSphere Studio Enterprise Developer
Enterprise Developer is targeted to developers and integrators, who can make
use of advanced tooling such as RAD or visual modeling. It contains all the
functionality of the Application Developer. In addition, it provides tools for remote
edit-compile-debug for host COBOL and PL/I applications, a visual builder for
adapters and microflows, and tools for visual modeling and RAD (based on
VisualAge Generator technology).
Current status and outlook
Application Developer Version 5 became available at the end of 2002. Application
Developer Version 5.1 was released in the third quarter of 2003 and is the
development environment for WebSphere Application Server 5.0.2. Application
Developer Version 5.1.1 was released in December of 2003 and is the
development environment for WebSphere Application Server 5.1.
More information
For more information on IBM WebSphere Studio Site Developer, refer to:
http://www.ibm.com/software/ad/studiositedev/
For more information on IBM WebSphere Studio Application Developer, refer to:
http://www.ibm.com/software/ad/studioappdev/
Chapter 12. IBM WebSphere product family
211
WebSphere MQ
IBM WebSphere MQ is a member of the IBM WebSphere MQ family (formerly
MQSeries® family), which includes integrated middleware providing the
intelligence and infrastructure to drive rapid and flexible business change to
transform and integrate business application and processes across the extended
enterprise.
IBM WebSphere MQ represents the core of the WebSphere MQ family. It is
available on more than 35 platforms. It provides the base messaging functions for
servers and clients, and assures once-only message delivery. It can be used
alone or with other members of the family. It also represents the infrastructure of
WebSphere Application Server JMS, and this is the reason that it is part of the
foundations and tools group.
WebSphere MQ supports application integration by helping business
applications to exchange information across different platforms, sending and
receiving data as messages. WebSphere MQ hides network interfaces from the
developer, assures once and once only delivery of messages, deals with
communications protocols, dynamically distributes workload across available
resources, handles recovery after system problems, and helps make programs
portable. So programmers can use their skills to handle key business
requirements, instead of wrestling with underlying network complexities.
Current status and outlook
The latest release is WebSphere MQ Version 5.3. It maintains compatibility with
the previous release, IBM MQSeries Version 5.2. In addition, it provides security
using secure sockets layer (SSL), the Internet standard for secure
communication. It also implements enhanced features for performance,
especially for JMS applications, making WebSphere MQ the JMS provider of
choice. Other features have been added to enhance system scalability and
reliability, particularly useful for clustering of systems that can share workload.
More information
For more information on IBM WebSphere MQ refer to:
http://www.ibm.com/software/ts/mqseries/
WebSphere reach and user experience
Products and offerings from this group provide smooth operation and continued
scalable business growth with the support of commerce transactions. They help
customers to extend and personalize their businesses.
212
WebSphere Version 5.1 Web Services Handbook
WebSphere Portal
IBM WebSphere Portal for Multiplatforms provides a single point of interaction
with dynamic information, applications, processes and people to help build
successful business-to-employee (B2E), business-to-business (B2B) and
business-to-consumer (B2C) portals. WebSphere Portal also supports a wide
variety of pervasive devices enabling users to interact with their portal anytime,
anywhere, using any device, wired or wireless.
Packaging
WebSphere Portal provides three different configurations. The Portal Enable
package is the base offering. Portal Extend and Portal Experience provide
additional functionality for advanced customers.
Portal Enable
WebSphere Portal Enable represents an entry level portal technology that
simplifies and speeds your access to personalized information and application.
It provides several common services including:
Connectivity and integration to allow access to enterprise data or external
information by connecting to partners’ applications.
Presentation and administration to enable information access customization
while providing access to enterprise resource planning (ERP), customer
relationship management (CRM), and supply chain management (SCM)
applications.
Security features that include an authentication layer to provide controlled
access to the portal. User information is stored in a Lightweight Directory
Access Protocol (LDAP) directory.
Portal Enable provides two personalization technologies:
Rules-based filtering that determines which Web content is displayed for a
particular user.
Statistical models and matching techniques that extract visitor behavior and
trends. This way the displayed content can be tailored to different users and
groups.
Portal Extend
WebSphere Portal Extend extends the functionality of the Portal Enable by
adding collaborative components and Web usage analysis tools together with
tools to access, organize, and share information. Features include:
Parallel, distributed searching capability
Chapter 12. IBM WebSphere product family
213
Individual and shared team workspaces with built-in collaborative capabilities
Collaboration software components
Web site analysis tools
Portal Experience
WebSphere Portal Experience provides new tools and functionality in addition to
all the tools and capabilities contained in Portal Extend. This includes:
Advanced collaboration features for e-meetings, application sharing and white
boarding
Data storage for a broad spectrum of digital information including Facsimiles,
images, PC files, XML, and multimedia.
Content infrastructure for applications such as call centers.
Folder management and document workflow.
Sample Java applications as well as advanced application development tools.
Current status
The most recent version of the WebSphere Portal offerings is Version 5.0. With
this, a lightweight version of WebSphere portal called Portal Express has been
released. Portal Express provides an easy-to-use, single-server installation, and
quick, out-of-the-box operations demanded by smaller firms and departmental
groups.
More information
For more information on IBM WebSphere Portal refer to:
http://www.ibm.com/software/webservers/portal/
WebSphere Everyplace
IBM WebSphere Everyplace products are part of the larger pervasive computing
products that enable users to interchange any information over any network
using any device, not only the traditional desktop.
WebSphere Everyplace focuses on the users of Web-enabled cellular phones
and other mobile devices. It provides both server- and client-side technology to
move the e-business solutions from the standard desktop environment to
portable devices.
Products
The WebSphere Everyplace group contains three different configurations.
214
WebSphere Version 5.1 Web Services Handbook
IBM WebSphere Everyplace Embedded Edition
WebSphere Everyplace Embedded Edition integrates essential software to
enable device manufacturers, developers and service providers to Web-enable
their products. It includes built-in middleware, content development tools,
customization services, and server integration for a variety of devices. It is based
on the Java programming language and uses open standards to create a flexible
platform.
Embedded Edition includes an embedded, real-time operating system (RTOS); a
Java Virtual Machine (JVM) environment built for embedded applications; a
framework for managing the life cycle of network-delivered services and
applications; network connection management for both wired and wireless
connections; integrated support for a hybrid application environment using both
Java and native code; integration with IBM content management and delivery
technologies; as well as security mechanisms, like VPN, SSL, encryption and
authentication.
WebSphere Everyplace Access
WebSphere Everyplace Access supports mobile devices with the respect of
device and network capabilities. The package features include PIM and e-mail
synchronization using the SyncML standard, device-specific content tailoring
through the use of portlets and transcoding, device support for PDAs and
Internet-enabled phones, integration into your existing IT infrastructure through
third-party directory support and authentication proxy, as well as well-defined
APIs for application enablement.
DB2® Everyplace and Lotus Domino™ Everyplace Enterprise Server are also
part of the package.
WebSphere Everyplace Server, Service Provider Offering
WebSphere Everyplace Server, Service Provider Offering (SPO) combines all of
the middleware infrastructure needed to connect, adapt, manage, transform, and
scale today's Web applications and legacy data into the pervasive computing
environment. It extends the reach of Web applications to a broad range of
wireless and mobile devices, including Wireless Application Protocol (WAP)
phones and wireless connected PCs; sometimes connected devices such as
PalmPilots and PocketPCs; and always connected devices such as residential
gateways, Internet access devices, and digital set-top boxes.
WebSphere Everyplace Server SPO is the most complete offering in the
WebSphere Everyplace Server family. It provides tools and middleware
infrastructure required for rapid development, deployment and management of
mobile services. The solution also provides centralized management capabilities,
Chapter 12. IBM WebSphere product family
215
as well as network independence over a broad range of mobile and/or line
networks for TCP/IP and WAP applications.
Current status
WebSphere Everyplace Access V4.3 is being released in two phases. The first,
V4.3.0, supports Windows 2000 and AIX. It includes enhancements in the area
of Lotus SameTime messaging support for mobile devices and added support for
palm devices. The second release, V4.3.1, will replace V4.3.0 and add further
enhancements in the area of support for Solaris 8 and Oracle 8 plus support for
selected Sharp devices.
WebSphere Everyplace Server, SPO Version 2.1 replaces IBM WebSphere
Everyplace Suite Version 1.1 (both the Service Provider Edition and the
Enterprise Edition). Version 2.1 expands the capabilities of Version 1.1 editions
by adding several new features. Among others, it allows users or applications to
more easily manage information with intelligent notifications that are triggered
when events occur and/or content is available based on preferences. It supports
location-based information to dynamically determine the user's device position
information, pass that information to an application, and manage the privacy of
location information. It extends hands-free access to applications through the
IBM WebSphere Voice Server, giving users voice recognition and voice access to
application content. It integrates with Domino application adapters in Domino
Everyplace Server. It also incorporates encryption and authentication capabilities
in integration with Policy Director for enhanced authorization and access control.
More information
For more information on IBM WebSphere Everyplace and other pervasive
computing technologies and products refer to:
http://www.ibm.com/software/pervasive/
WebSphere Commerce
IBM WebSphere Commerce software helps you sell goods and services online. It
supports B2C, B2B, or private exchange business models.
WebSphere Commerce (formerly Commerce Suite) represents the IBM online
trading solution. It enables customers to start small and grow fast once their
business is established. It combines several middleware products from the
WebSphere family, such as WebSphere Application server, with other products
and applications into a complex e-trading environment.
Packaging
WebSphere Commerce comes in three different configurations.
216
WebSphere Version 5.1 Web Services Handbook
WebSphere Commerce Professional Entry
Professional Entry Edition provides an entry-level solution for a quick start of
Web-based training. The features include tools for creation and management of
online catalog information, marketing and reporting tools, filtering engines to
discover customer buying patterns and preferences, as well as advanced
inventory and order management capability to automate and optimize the
processing of customer orders.
The offering includes WebSphere Commerce Accelerator to provide a single
point of administration for store and product management, marketing and
merchandising, order management and customer service. In also includes IBM
DB2 Universal Database™. The growth path to WebSphere Commerce
Professional Edition is also provided.
WebSphere Commerce Professional Edition
Professional Edition provides an online selling solution for a more demanding
customer. It can handle high transaction volumes and provides the connectivity
to existing back-end systems.
The product provides enhanced features and functions including advanced order
management capabilities to optimize movement of products through the supply
chain, dynamic collaborative technology through Lotus Sametime®, portal
add-on capability to provide customers with a personalized single
point-of-access, and localization to meed the demands of the customers from
different locations.
The bundled product list includes WebSphere Catalog Manager and WebSphere
Payment Manager. The product supports industry standards like Java, JSP, EJB
and XML, therefore providing the connectivity with other middleware and
systems including IBM CICS®, WebSphere MQ, and SAP R/3.
WebSphere Commerce Business Edition
Business Edition is based on IBM’s enterprise technology, thus providing high
reliability, scalability, and performance. Its features include B2B personalization
to manage business relationships, assisted selling technology to walk customers
and partners through the requirements gathering and product selection process,
online collaboration and virtual teaming tools, as well as integrated contract
management. It offers multi-cultural capabilities to reach global customers and
business intelligence functionality.
Current status
The latest product version is IBM WebSphere Commerce Version 5.5, which has
introduced several improvements. V5.5 also introduces WebSphere Commerce
Express - a lightweight solution for small- and medium-sized projects.
Chapter 12. IBM WebSphere product family
217
More information
For more information on IBM WebSphere Commerce refer to:
http://www.ibm.com/software/webservers/commerce/
WebSphere Business Integration
In the WebSphere Business Integration group we meet the rest of the
WebSphere MQ family: WebSphere MQ Integrator Broker and its extension
WebSphere Business Integration.
WebSphere MQ Integrator Broker
IBM WebSphere MQ Integrator Broker for Multiplatforms provides an
infrastructure for business processes to control information flows according to
their specific business needs. Thus, the necessary flexibility and control of their
business data is achieved.
WebSphere MQ Integrator Broker architecture provides an open framework
where functions defined as nodes can be joined together to operate on the
content of the messages. A set of prepared functions is available as a part of the
product, and open API provides the extension possibility. Additionally, the
WebSphere MQ Integrator Broker shares the functionality of relational database
technology with respect to message augmentation, warehousing, and message
flow tools.
Current status and outlook
IBM WebSphere MQ Integrator Broker Version 2.1 provides customers with the
necessary basis for application integration solutions architecture. It enables them
to integrate existing applications to other existing or new applications. They can
visually check the application flow through the use of a graphical development
environment. The architecture includes rules for message transformation as well
as routing and distributing between different systems. It enables integration of
application and business data using dynamic content. It also supports
topic-based publish/subscribe functions. The advanced message format
dictionary and manipulation tools support multiple formats including XML and
plug-in, third-party dictionaries, and formats. GUI-based tooling helps users
designing, using and manipulating business rules.
More information
For more information on IBM WebSphere MQ Integrator Broker refer to:
http://www.ibm.com/software/ts/mqseries/integrator/broker/
218
WebSphere Version 5.1 Web Services Handbook
WebSphere Business Integration
The IBM WebSphere family includes business integration products and solutions
that help integrate either a single department or entire companies with the
partners and Web customers.
In addition to WebSphere MQ Integrator Broker, IBM WebSphere Business
Integration contains the following products:
IBM CrossWorlds®—A freshly acquired process integration software based
on pre-built, reusable components.
Collaborations— Process templates of many common operational activities
such as synchronizing products or customer files, handling customer or
supplier orders, or managing information about employees and departments
across a company.
Connectors and Adapters—Pieces of software designed to access
application data, or to link with business partner systems.
Common Business Objects—The components that simplify the
implementation of an integration infrastructure and reduce maintenance of
application interfaces.
IBM MQSeries Workflow—A process engine for model-driven e-business
process automation and tracking.
Current status
At the time of writing of this book, the recent version of the product is IBM
WebSphere Business Integration Version 4.2.
More information
For more information on IBM WebSphere Business Integration refer to:
http://www.ibm.com/software/ts/wbi/
Summary
In this chapter we covered the IBM WebSphere product family, which represents
the basis of the IBM e-business strategy.
The foundation and tools group covers the basic plumbing of the complex
Web-based enterprise applications: Java-based application servers and
message queuing middleware. It also contains tools for rapid application
development.
Chapter 12. IBM WebSphere product family
219
In the reach and user experience group we find the products that extend
enterprise applications to portals, where they can be reached by the growing
Internet population. They can also extend the reach to users of handheld devices
and cellular phones. Other products help customers moving their traditional
selling operations to the Internet in a controlled scalable manner.
The business integration group products help customers to integrate existing
separate software and hardware assets and make the best use of them.
The WebSphere family products are available for a wide range of software and
hardware platforms and they are regularly enhanced to meet the growing and
quickly changing demands of e-business.
More information
The WebSphere family of products are regularly updated to cope with the
e-business environment that changes at a high pace. Therefore the Internet
represents one of the best sources of up-to-date information.
For general information on the IBM WebSphere family of products refer to:
http://www.software.ibm.com/websphere/
Sources of additional information on particular products can be found at the end
of the corresponding subsection.
220
WebSphere Version 5.1 Web Services Handbook
13
Chapter 13.
Web services development
overview
This chapter provides a general introduction to Web services development. We
present the different paths for developing a Web service and types of clients
without getting too specific regarding implementation details.
For implementation details regarding J2EE environments see Chapter 4,
“JAX-RPC (JSR 101)” on page 67, and Chapter 5, “Implementing Enterprise
Web Services (JSR 109)” on page 77.
This chapter contains the following topics:
Building a new Web service
Building a new Web service client
© Copyright IBM Corp. 2003, 2004. All rights reserved.
221
Overview
There are four main phases in developing a Web service: Build, deployment, run,
and management.
The build phase includes development and testing of the Web service
application, including the functionality and definition of the service.
The deployment phase includes publication of the service definition, the
WSDL document, and deployment of the runtime code of the Web service.
The run phase includes finding and invoking of the Web service.
The management phase includes management and administration of the
Web service application.
Web services development
The build cycle for a Web service involves some common steps that have to be
followed to create a new Web service. During its development the Web service
passes between different states. These states are shown in Figure 13-1.
Build
build or
have
Initial
build
or have
1 Service
definition
WSDL
build
Java
1 code
Deploy
Run
Management
assemble
WebSphere
Web
service
build
deploy
assemble
Web
service
deploy
run
Web
service
run
manage
Web
service
manage
invoke
publish
Service
registry
Client
find
Figure 13-1 Web services development
Build phase
The first phase is the build phase, when we create a Web service. There are two
possible paths:
The red path (solid)—From the initial state we build or already have Java
code. Using this Java code we build the service definition (WSDL document)
222
WebSphere Version 5.1 Web Services Handbook
with the business methods that we want to expose. Once we have generated
the WSDL document, we assemble the Web service application.
The blue path (dashed)—From the initial state we build or already have a
service definition, WSDL document. Using this WSDL document we build or
adapt the Java code to implement that service. Once we have implemented
the code, we assemble the Web service application.
Deployment phase
The second phase of a Web service is deployment. In this phase we deploy the
Web service to an application server. After that, we publish the Web service to be
found by the clients. The publication can be done using a UDDI registry, using a
WSIL document, or by directly providing the information about the new service to
future consumers, for example, with e-mail. A combination of all these publishing
methods is also possible.
Run phase
The third phase is the runtime. In this phase the Web service is operative and is
invoked by several clients that require the functionality offered by this service.
Management phase
The final phase is the management phase where we cover all the management
and administration tasks of the Web service application.
In the following sections, we concentrate on the different possible paths to create
a Web service and a Web service client within the build phase.
Building a new Web service
In this section, we describe the different paths to use in the generation of a Web
service. We find three principal approaches, depending upon the elements that
we use to start the creation of the service. A Web service can be implemented
from:
An existing application (bottom-up)
Transforming an existing application into Web services includes the
generation of service wrappers to expose the business functionality.
An existing service definition, WSDL, to generate a new application
(top-down)
Chapter 13. Web services development overview
223
Generating a new application includes using a specific programming
language and model.
An existing group of already generated Web services to provide a new
combination of functionality (multiple services)
Composing a new Web service may include the use of workflow technologies.
Bottom-up
The bottom-up approach is the most common way to build a Web service. We
start with a business application that is already developed, tested and is running
on the company systems. In Figure 13-2 we can see this path.
Generate
Service
Application
Service
definition
WSDL
Deployment
descriptors
Web Service
Figure 13-2 Bottom-up path
We start with the service application and generate the WSDL document for it,
providing all the functionality that we desire to externally expose as a Web
service. Depending of the implementation model (J2EE, for example), we also
have to generate the deployment descriptors.
Top-down
The top-down approach is commonly used when we have a standard service
definition and we want to implement this definition to provide the requested
service.
The service definition may, for instance, come from an industry-sector agreement
and may be implemented by any number of providers, for example, when a group
of airlines agree on how to provide their plane schedules. In that case, there is a
strict definition of what the providers receive and how they have to respond.
224
WebSphere Version 5.1 Web Services Handbook
Therefore, the providers have to adapt their current systems to follow the new
specification.
The top-down path is shown in Figure 13-3.
Generate
Service
definition
WSDL
Service
Skeleton Deployment
descriptors
Web
Application
Service
Code
Figure 13-3 Top-down path
The process of creating a Web service using this path can be divided into the
following steps:
Find the service interface.
We localize the service definition to use it as the entry point for the
implementation. We obtain the WSDL document through a proprietary
channel from the service provider (e-mail, for example) or through a WSIL
document or by searching a UDDI registry.
Generate the implementation skeleton.
Using the service definition, we generate a skeleton with the methods and
parameters that we have to fill in to implement the Web service.
Develop the new Web service.
Using the skeleton, we complete all the methods with the appropriate logic.
Depending upon the amount of code that we can reuse from other
applications and the complexity of the service definition, we develop more or
less new code. In a J2EE environment, we also generate deployment
descriptors. Finally, we test the new Web service to check that everything
runs smoothly.
Chapter 13. Web services development overview
225
Multiple services
The multiple services approach is commonly used when we have a collection of
Web services running in one or more systems and we want to provide new
functionality reusing the existing features provided by these Web services. In this
path we create a new integrated Web service combining some of the individual
characteristics provided by the existing Web services and also other business
modules. This path is shown in Figure 13-4.
Service
Business
module
Deployment
definition
descriptors
WSDL
WS 3
WS 1
WS 4
WS 2
WS 5
Web Service
Figure 13-4 Multiple services path
The individual Web services, WS n, are linked sequentially. Therefore, the output
of one service is the input for the following service or business module. We can
also create different outputs at runtime depending on the flow characteristics and
the input data.
The multiple services path can have both previous approaches, bottom-up and
top-down, in its implementation. The most common is the bottom-up alone or
combined with the generation of one or more top-down services to complete the
sequence. On the other hand, we can consider the creation of a top-down Web
service dividing the resulting service into multiple sub-services that can be useful
for other applications.
226
WebSphere Version 5.1 Web Services Handbook
Types of Web services implementation
The base for the J2EE implementation of a Web service can be varied from
different modules and applications. These possibilities in the creation of a Web
service depend upon the tools and products that we are using in the generation
process and the facilities that they provide to easily complete the creation task.
Table 13-1 lists the tools and which Web services implementation types they
facilitate on a particular path.
Table 13-1 Web services implementation facilities by products
Tool or
product
Path
Java
bean
EJB
DADX
ISD
URL
WSAD
(WebSphere
Soap Engine)
Bottom-up
Yes
Yes
Yes
Yes
Yes
Top-down
Yes
Yes
No
No
No
WSADIE
(SOAP 2.3)
Bottom-up
Yes
Yes
Yes
Yes
Yes
Top-down
Yes
Yes
No
No
No
Multiple services (business process) implemented as an EJB service
WSDK
(WebSphere
Soap Engine)
ETTK (Axis)
Bottom-up
Yes
Yes
No
No
No
Top-down
Yes
Yes
No
No
No
WSAD = WebSphere Studio Application Developer V5.1
WSADIE = WebSphere Studio Application Developer Integration Edition V5.0
WSDK = WebSphere SDK for Web Services V5.0.2
ETTK = Emerging Technologies Toolkit
DADX = Document access definition extensions
ISD = Web service deployment descriptor (points to implementation code)
URL = Uniform resource locator (for a servlet)
Building a new Web service client
Web services for J2EE specifies three different types of clients (see “Client
programming model” on page 79). In this section, we explain types from a more
general point of view.
The task to build or generate a Web service client (also known as a service
requestor) depends on the methods of how the client is binding to a Web service
server. The client uses a local service stub or proxy to access the remote server
and service. The WSDL document is used to generate or set up this particular
Chapter 13. Web services development overview
227
stub or proxy. The stub or proxy knows at request time how to invoke the Web
service based on the binding information.
The methods of binding to a service are defined by the time when the various
elements of binding information are available and used, namely at build time vs.
at runtime. This results in three client types:
Static client
Dynamic client with known service type
Dynamic client with unknown service type
Note: In this context, the term binding information is used in a general sense
and is not limited to the <wsdl:binding> section of a WSDL document.
Static client
The static client has a static binding created in the build time. This is made
possible because in the development phase we know the interface, the binding
method, and the service endpoint of the Web service that we are going to invoke.
We also decide that we only use this client for that specific service and nothing
else. Therefore, in these cases, the best solution is to use a static client.
No public, private, or shared UDDI registry or WSIL document is involved in the
runtime process. Figure 13-5 shows the process to generate a static client.
WSIL
e mail
Service
definition
WSDL
1
Find
build time
Service
definition
WSDL
WS
client
2
Generate
Deployment
descriptors
3
Proxy
or
Stub
Figure 13-5 Static client path
228
UDDI
registry
WebSphere Version 5.1 Web Services Handbook
Bind
Web
Service
The steps to build a static service client are:
1. Manually find the service definition or WSDL.
We obtain the WSDL document through a proprietary channel from the
service provider (e-mail, for example) or through a WSIL or looking in a UDDI
registry. An important point is that we store the WSDL document into a local
configuration file. Therefore, we have all the information previously defined
before we start to code the client.
2. Generate the service proxy or stub.
Using the information contained in the WSDL document, we generate the
proxy or stub and probably the deployment descriptors. This stub is a local
representation of the remote Web service. Depending upon the tool or
product we use in this step, the generation is performed automatically.
3. Test the client.
We test the code to check that the client correctly operates and binds to the
Web service.
Dynamic client with known service type
The dynamic client has a dynamic binding that is only known and decided at
runtime. This client is used when we know the interface of the service but not the
implementation (the service endpoint). This means that the operation, the
parameters associated with the operation, and the way to bind to the service are
already known, but the address where this service is provided is not known.
An example of this is when an industry defines a service interface and the
partner companies implement the specification. In that case, we only want to
have one client that can dynamically change between the different providers
based on certain criteria (performance, cost, and so forth).
The use of a public, private, or shared UDDI registry is involved in the process to
dynamically provide to the client a range of entry points available at a specific
time. Figure 13-6 shows the process to generate such a dynamic client.
Chapter 13. Web services development overview
229
Service definition
WSDL
1
Find
build time
Service
interface
Service
interface
Generate
UDDI
Registry
Service
implementation
3
Find
runtime
2
WS
client
Deployment
descriptors
Proxy
or
Stub
4
Bind
Web
Service
Figure 13-6 Dynamic client path
Note: Instead of a UDDI registry, Web services inspection language (WSIL)
can also be used to create dynamic clients.
The steps to build a dynamic service client are:
1. Manually find the service interface definition of the WSDL.
We obtain the service interface definition, the types, the messages, the port
type with the operations, and the binding of the WSDL document through the
same mechanism used with the static client. In this case we are only
interested in the service interface, which is what we load into a local
configuration file. Therefore, the information of how to invoke the Web service
is previously defined before we start to code the client.
2. Generate the generic service proxy or stub.
Using the information contained in the service interface, we generate the
generic proxy or stub and probably the deployment descriptors. This generic
proxy or stub can be used to access any implementation of the service
interface used in the generation process.
3. The proxy or stub (or a helper class) contains the necessary code to locate a
service implementation by searching a UDDI registry. This UDDI lookup code
is currently not generated by tools and must be hand-coded using the UDDI4J
API.
230
WebSphere Version 5.1 Web Services Handbook
4. Test the client.
We test the code to check that the client correctly operates and binds to any
Web services that implement the service interface dynamically.
Dynamic client with unknown service type
There are other, more dynamic ways to connect to a Web service. For example,
at build time we do not know the binding to connect to a Web service, or the
binding is decided at runtime from among different possibilities. The steps to
create this client are the same as for the previously described client, with the only
difference being that the proxy is created at runtime with the binding information
collected just before the connection. To create such a client, we use WSIF (see
Chapter 7, “Web services invocation framework” on page 129).
Even more dynamic is when we do not know anything about the service in
advance, as it is in a dynamic invocation interface (see “Dynamic invocation
interface (DII)” on page 81). In these cases, the service client obtains the service
definition WSDL document from a UDDI registry or WSIL document at runtime.
There is no proxy code generation at build time; it is generated at runtime to bind
and invoke the Web service. This kind of binding requires the presence of a user
interface that can provide the input data and understand the meaning of the
output. Therefore, this last path, totally dynamic, hardly has any real business
application.
Types of client implementations
The base for the Java implementation of a Web services client can vary
depending on where the client can reside and what kind of module or application
is built.
From the point of view of where the client can reside, the possibilities are:
Stand-alone Java J2SE application client
J2EE application in some middleware container
From the point of view of what kind of module or application is built, the
possibilities are:
Java class
JavaBean
EJB session bean
Servlet
JavaServer Page (JSP)
Java applet
Chapter 13. Web services development overview
231
The different tools and products that this publication refers to offer various
facilities to automatically generate code required to build a client. Usually, there is
always some manual coding required and is inevitable for dynamic clients.
Table 13-2 lists the facilities provided by the tools.
Table 13-2 Web services client implementation facilities by products
Tool or product
Facilities
Application Developer
(WebSphere Soap Engine)
Generates services and stubs as it is defined by JSR 101
and JSR 109, the mapping parameters, and JSPs to test
the client visually.
Application Developer
Integration Edition
(SOAP 2.3)
Generates a proxy, the mapping parameters, and JSPs
to test the client visually. Includes WSIF for dynamic
invocation. Includes business process flow modeling.
Generates Web services from EIS using connectors.
WebSphere SDK for Web
Services
(WebSphere Soap Engine)
Generates all the stubs needed to connect with the Web
service, including the mapping parameters and a service
locator (XML file and Java code to locate the service).
Emerging Technologies
Toolkit (Axis)
Axis facilities.
For further information about the listed tools, products, and client generation, see
the respective chapters.
Summary
In this chapter we have presented the development concepts to create a Web
service and a Web service client. We have studied the different paths to follow or
choose when we want to create a Web service. We have also learned how to
select these paths, depending upon the starting situation in the case of Web
services or the functional objectives in the case of the Web service clients.
More information
For a more comprehensive discussion of the topic, refer to the document Web
Services Development Concepts 1.0 from the Emerging Technologies Toolkit. It
is also available at the following URL:
http://www.ibm.com/software/solutions/webservices/pdf/WSDC.pdf
232
WebSphere Version 5.1 Web Services Handbook
14
Chapter 14.
Weather forecast application
In this chapter we describe the base Java code of a weather forecast application,
which we use to demonstrate the Web services technology.
Note: The weather forecast application was extended from the previous
version of the publication:
Web service provider as session EJB or JavaBean
Includes a database to store weather information
© Copyright IBM Corp.2003, 2004. All rights reserved.
233
Weather forecast application components
The weather forecast application is the example that we use in the following
chapters to demonstrate how to create a Web service with different tools and
programs. The weather forecast is an application that simulates weather forecast
predictions.
This weather forecast application is composed of three main modules: Business
module, data module, and back-end module. It also provides two different
implementations, as a session EJB in an EJB project and as a JavaBean in a
Web project.
Business module
The business module is implemented by the WeatherForecast class in a Web
module and by the WeatherForecastEJB session bean in an EJB module. These
classes offer the business logic of our example providing four principal functions:
Provides the weather forecast prediction for one specific day
Provides the weather forecast prediction for a period of time
Provides the temperature prediction for a period of time
Provides the functionality to load new weather information
The data returned by the business methods is:
A JavaBean representing the complex type Weather
An array of Weather JavaBeans
An array of integer numbers (temperatures)
None (void)
Data module
The data module is implemented by the Weather class in both implementations.
This class provides the content information of a weather prediction. The
information contained in a weather prediction is:
234
Wind direction in an eight-point compass (String)
Wind speed in kilometers per hour (int)
Temperature in degrees Celsius (int)
Weather condition: Sunny, partly cloudy, cloudy, rainy, stormy (String)
Date of the prediction (Calendar)
Database flag, info from database or not (boolean)
WebSphere Version 5.1 Web Services Handbook
Back-end module
The back-end module is contained in the WEATHER database. This database
contains the SANJOSE table, where the weather information for San Jose is
loaded.
The back-end module is supported by the WeatherPredictor class. This class is
responsible for making a simulated prediction about weather conditions, using
random values when no information for the requested day is contained in the
database.
Information flow
Figure 14-1shows the internal flow of the system information for one of the query
methods.
create the Weather
elements
2
populate the
Weather elements
Weather
Weather
Weather
Weather
Weather
request weather
information
Client
1
4
query the DB for
weather prediction
Weather
Forecast
3
6
populate the DB with
new Weather elements
WEATHER
Database
Weather
Predictor
Weather
Weather
Weather
Weather
return the Weather elements
with the weather prediction
7
generate random
Weather if no
information in DB
5
Figure 14-1 Weather forecast query flow behavior
The steps for this flow are:
1. A client requests weather information from the WeatherForecast bean.
Chapter 14. Weather forecast application
235
2. The WeatherForecast creates a Weather element (or elements) for the
response to the client’s weather request.
3. The WeatherForecast queries the weather prediction from the WEATHER
database.
4. The WeatherForecast populates the Weather element(s) based on the
information present at that moment in the database.
5. The weather information that is not in the database is requested from the
WeatherPredictor.
6. The database is populated by the WeatherForecast with the new Weather
element(s) generated by the WeatherPredictor.
7. The WeatherForecast returns the Weather element(s) to the client.
Note: The WeatherPredictor class uses a random number algorithm to
populate weather information. This makes our example very simple, but
enables us to concentrate on the important Web services aspects instead of
trying to write a sophisticated back-end application.
Figure 14-2 shows the internal flow of the system information for the load
method.
send weather
information
Client
1
Weather
Forecast
Weather
Weather
Weather
Weather
2
load the weather
predictions
into the database
WEATHER
Database
Figure 14-2 Weather forecast load flow behavior
The steps for this flow are:
1. A client sends weather information to the WeatherForecast bean to load the
database.
2. The WeatherForecast populates the database with the Weather element (or
elements).
Note: The load operation does not return any data. It can be used to
implement an asynchroneous Web service using SOAP over JMS.
236
WebSphere Version 5.1 Web Services Handbook
Base code
In this section we list the base code of the main modules.
Weather data
The Weather class is shown in Example 14-1.
Example 14-1 Weather class
package itso.mapping;
import java.io.Serializable;
import java.text.SimpleDateFormat;
import java.util.Calendar;
/**
* class Weather
* This class encapsulate some weather artifacts for a specific day
*/
public class Weather implements Serializable {
private
private
private
private
private
private
String windDirection = null;
int windSpeed = 0;
int temperatureCelsius = 0;
String condition = null;
Calendar date = null;
boolean dbflag = false;
/**
* Default Constructor for Weather.
* initialize with today's date
*/
public Weather() {
super();
}
/**
* Constructor for Weather.
* Initialize with a given date
* @param theDate
*/
public Weather(Calendar theDate) {
super();
date = theDate;
}
/**
* @see java.lang.Object#toString()
* used for deugging and testing purposes only
*/
public String toString() {
SimpleDateFormat sdf = new SimpleDateFormat("EEE. MMM d, yyyy");
Chapter 14. Weather forecast application
237
return "Weather: "
+ sdf.format(date.getTime())
+ " '"
+ condition
+ "' wind: "
+ windDirection
+ " "
+ windSpeed
+ "km/h "
+ temperatureCelsius
+ " Celsius";
}
// getter and setter methods abbreviated
public
public
public
public
public
public
public
public
public
public
public
public
String getCondition() { return condition; }
Calendar getDate() { return date; }
String getWindDirection() { return windDirection; }
int getWindSpeed() { return windSpeed; }
void setCondition(String condition) { this.condition = condition; }
void setDate(Calendar date) { this.date = date; }
void setWindDirection(String windDirection) { this.windDirection =
windDirection; }
void setWindSpeed(int windSpeed) { this.windSpeed = windSpeed; }
int getTemperatureCelsius() { return temperatureCelsius; }
void setTemperatureCelsius(int temperatureCelsius) { this.temperatureCelsius =
temperatureCelsius; }
boolean isDbflag() { return dbflag; }
void setDbflag(boolean b) { dbflag = b; }
}
Weather forecast JavaBean
The WeatherForecast class, a JavaBean, is shown in Example 14-2.
Example 14-2 WeatherForecast class
package itso.bean;
import java.util.Calendar;
import java.util.Vector;
import itso.mapping.Weather;
import itso.mapping.WeatherPredictor;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
238
WebSphere Version 5.1 Web Services Handbook
/**
* This class is the main entry point into this service.
* It offers four different methods to query and update the weather.
* The four signatures represent different "challenges" for the Web service, which are:
* - a complex type
* - an array
* - the combination of both
*/
public class WeatherForecast {
private
private
private
private
DataSource ds = null;
String db2Select = null;
String db2Insert = null;
String db2Delete = null;
public WeatherForecast() throws java.lang.Exception {
try {
InitialContext envCtx = new InitialContext();
String dataSourceName = (String)envCtx.lookup("java:comp/env/dataSource");
ds = (DataSource)envCtx.lookup("java:comp/env/"+dataSourceName);
db2Select = (String)envCtx.lookup("java:comp/env/getDB2Weather");
db2Insert = (String)envCtx.lookup("java:comp/env/setDB2Weather");
db2Delete = (String)envCtx.lookup("java:comp/env/removeDB2Weather");
} catch (Exception e) {
System.out.println("WeatherForecast exception: ");
e.printStackTrace();
throw (e);
}
}
/**
* Method getDayForecast returns one complex weather object for a specific day
* @param theDate The chosen day to obtain the weather forecast
* @return Weather The weather for that day
* @throws Exception If any probem occurs during the process to retrieve the weather
*/
public Weather getDayForecast(Calendar theDate) throws Exception {
if (theDate == null)
theDate = Calendar.getInstance();
Weather [] iWeather = executeQuery(theDate, 0);
return iWeather[0];
}
/**
* Method getForecast returns an array of complex weather object for a specific
* period of time
* @param startDate The chosen day to start with the weather forecast
* @param days The number of days to include in the weather prediction
* @return Weather[] An array with the weather forecast
* @throws Exception If any probem occurs during the process to retrieve the weather
*/
public Weather[] getForecast(Calendar startDate, int days) throws Exception {
if (startDate == null)
Chapter 14. Weather forecast application
239
startDate = Calendar.getInstance();
Weather [] iWeather = executeQuery(startDate, days);
return iWeather;
}
/**
* Method getTemperatures returns an array of temperatures ...
* @param startDate The chosen day to start with the temperatures forecast
* @param days The number of days to include in the temperatures prediction
* @return Weather[] An array with the temperatures values
* @throws Exception If any probem occurs during the process
*/
public int[] getTemperatures(Calendar startDate, int days) throws Exception {
if (startDate == null)
startDate = Calendar.getInstance();
Weather [] iWeather = getForecast(startDate, days);
int[] temperatures = new int[iWeather.length];
for(int i=0; i<iWeather.length ; i++)
temperatures[i] = iWeather[i].getTemperatureCelsius();
return temperatures;
}
/**
* Method setWeather set a day weather forecast
* @param dayWeather The weather information to set
* @throws Exception If any probem occurs during the process to set the weather ...
*/
public void setWeather(Weather [] dayWeather) throws Exception {
Connection conn = null;
PreparedStatement ps = null;
try {
if (dayWeather == null)
throw new Exception("Please provide a valid weather element");
//Get the connection
conn = ds.getConnection();
for (int i = 0; i < dayWeather.length; i++) {
//delete old weather information
ps = conn.prepareStatement(db2Delete);
ps.setDate(1, new
java.sql.Date(dayWeather[i].getDate().getTime().getTime()));
ps.execute();
// Insert the new weather information
ps = conn.prepareStatement(db2Insert);
//check if the weather object is valid
if (dayWeather[i].getDate() == null)
dayWeather[i].setDate(Calendar.getInstance());
ps.setDate(1, new
java.sql.Date(dayWeather[i].getDate().getTime().getTime()));
ps.setString(2,dayWeather[i].getCondition());
ps.setInt(3,dayWeather[i].getTemperatureCelsius());
ps.setString(4,dayWeather[i].getWindDirection());
ps.setInt(5,dayWeather[i].getWindSpeed());
ps.executeUpdate();
240
WebSphere Version 5.1 Web Services Handbook
}
} catch(Exception e) {
throw (e);
}
finally {
try {
if (ps != null) ps.close();
if (conn != null) conn.close();
} catch (Exception e) { }
}
}
/**
* Method executeQuery returns an array of complex weather object ...
* @param startDate The chosen day to start with the weather forecast
* @param days The number of days to include in the weather prediction
* @return Weather[] An array with the weather forecast
* @throws Exception If any probem occurs during the process to retrieve the weather
*/
private Weather [] executeQuery (Calendar startDate, int days) throws Exception {
Vector result = new Vector();
Connection conn = null;
PreparedStatement ps = null;
ResultSet rs = null;
int i = 0;
try {
conn = ds.getConnection();
ps = conn.prepareStatement(db2Select);
ps.setDate(1, new java.sql.Date(startDate.getTime().getTime()));
Calendar futureDate = (Calendar)startDate.clone();
futureDate.add(Calendar.DAY_OF_MONTH,days);
ps.setDate(2,new java.sql.Date(futureDate.getTime().getTime()));
rs = ps.executeQuery();
Calendar correctDay = (Calendar)startDate.clone();
while(rs.next()) {
Weather iWeather = new Weather();
Calendar theDBDate = Calendar.getInstance();
theDBDate.setTime(rs.getDate("WEATHERDATE"));
//check if it is the correct date
while(theDBDate.after(correctDay)) {
// one day miss
Weather missWeather = new Weather();
missWeather.setDate((Calendar)correctDay.clone());
WeatherPredictor.calculateWeatherValues(missWeather);
result.add(missWeather);
//increase the expected day
correctDay.add(Calendar.DAY_OF_MONTH,1);
}
iWeather.setDate(theDBDate);
Chapter 14. Weather forecast application
241
iWeather.setCondition(rs.getString("CONDITION"));
iWeather.setTemperatureCelsius(rs.getInt("TEMPERATURE"));
iWeather.setWindDirection(rs.getString("WINDDIR"));
iWeather.setWindSpeed(rs.getInt("WINDSPEED"));
iWeather.setDbflag(true);
result.add(iWeather);
//increase the expected day
correctDay.add(Calendar.DAY_OF_MONTH,1);
}
//check if there are still remaining days
while(result.size() < days+1) {
//one day miss
Weather missWeather = new Weather();
missWeather.setDate((Calendar)correctDay.clone());
WeatherPredictor.calculateWeatherValues(missWeather);
result.add(missWeather);
//increase the expected day
correctDay.add(Calendar.DAY_OF_MONTH,1);
}
}
catch(Exception e) {
throw (e);
}
finally {
try {
if (rs != null) rs.close();
if (ps != null) ps.close();
if (conn != null) conn.close();
} catch (Exception e) { }
}
Weather[] arrayWeather = new Weather[result.size()];
Vector dbWeather = new Vector();
for (int j = 0; j < arrayWeather.length; j++) {
arrayWeather[j] = (Weather)result.get(j);
if(!arrayWeather[j].isDbflag())
dbWeather.add(arrayWeather[j]);
}
//load the database with the new predictions
Weather[] arraydbWeather = new Weather[dbWeather.size()];
for (int k = 0; k < arraydbWeather.length; k++)
arraydbWeather[k] = (Weather)dbWeather.get(k);
if (arraydbWeather.length > 0)
setWeather(arraydbWeather);
return arrayWeather;
}
}
242
WebSphere Version 5.1 Web Services Handbook
Weather forecast session EJB
The WeatherForecastEJB implementation class is shown in Example 14-3.
Note: We provide two identical session EJBs:
WeatherForecastEJB—To create an HTTP-based Web service
WeatherForecastJMS—To create a JMS-based Web service
Example 14-3 WeatherForecastEJBBean class
package itso.session;
import java.util.Calendar;
import java.util.Vector;
import itso.mapping.Weather;
import itso.mapping.WeatherPredictor;
import javax.naming.InitialContext;
import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
/**
* Bean implementation class for Enterprise Bean: WeatherForecastEJB
*/
public class WeatherForecastEJBBean implements javax.ejb.SessionBean {
private
private
private
private
DataSource ds = null;
String db2Select = null;
String db2Insert = null;
String db2Delete = null;
private javax.ejb.SessionContext mySessionCtx;
/**
* getSessionContext
*/
public javax.ejb.SessionContext getSessionContext() {
return mySessionCtx;
}
/**
* setSessionContext
*/
public void setSessionContext(javax.ejb.SessionContext ctx) {
mySessionCtx = ctx;
}
/**
* ejbCreate
*/
Chapter 14. Weather forecast application
243
public void ejbCreate() throws javax.ejb.CreateException {
try {
InitialContext envCtx = new InitialContext();
String dataSourceName = (String)envCtx.lookup("java:comp/env/dataSource");
ds = (DataSource)envCtx.lookup("java:comp/env/"+dataSourceName);
db2Select = (String)envCtx.lookup("java:comp/env/getDB2Weather");
db2Insert = (String)envCtx.lookup("java:comp/env/setDB2Weather");
db2Delete = (String)envCtx.lookup("java:comp/env/removeDB2Weather");
} catch (Exception e) {
System.out.println("WeatherForecastBean exception in ejbCreate: ");
e.printStackTrace();
throw ( new javax.ejb.CreateException("Exception: "+e.getMessage()) );
}
}
/**
* ejbActivate
*/
public void ejbActivate() {
}
/**
* ejbPassivate
*/
public void ejbPassivate() {
}
/**
* ejbRemove
*/
public void ejbRemove() {
}
// the rest of the code is identical to the WeatherForecast JavaBean
// ...... getDayForecast(......)
Weather predictor
The WeatherPredictor class is shown in Example 14-4.
Example 14-4 WeatherPredictor class
package itso.mapping;
import java.util.Calendar;
import java.util.Random;
/**
* class WeatherPredictor
* This class predicts several weather artifacts
* for a given date on a daily or weekly base.
* Random values are used for the simulation.
*/
public class WeatherPredictor {
244
WebSphere Version 5.1 Web Services Handbook
// possible conditions for weather in general and wind directions
private static final String[] possibleConditions =
new String[] { "sunny", "partly cloudy", "cloudy", "rainy", "stormy" };
private static final String[] possibleWinds =
new String[] { "N", "NE", "E", "SE", "S", "SW", "W", "NW" };
// random number generator
private static final Random random = new Random(System.currentTimeMillis());
/**
* Method calculateWeatherValues.
* This method takes a weather object and fills it with predicted values
* @param w Weather object to fill with calculated values
*/
public static void calculateWeatherValues(Weather w)
{
w.setWindDirection(possibleWinds[random.nextInt(possibleWinds.length)]);
w.setWindSpeed(random.nextInt(40) + 1);
w.setTemperatureCelsius(random.nextInt(50) - 10);
w.setCondition(possibleConditions[random.nextInt(possibleConditions.length)]);
}
}
Environment variables
The weather forecast beans use a resource reference and environment variables
to connect to the WEATHER database. Projects that contain the weather forecast
beans must have a resource reference defined:
Name—ItsoWeatherDB
Type—javax.sql.DataSource
JNDI name—jdbc/sjweather
A data source with the name jdbc/sjweather must be defined in the server.
Table 14-1 lists the environment variables.
Table 14-1 Environment variables
Environment variable
Value
dataSource
ItsoWeatherDB
getDB2Weather
select * from itso.sanjose where weatherdate >= ? and
weatherdate <= ?
setDB2Weather
insert into itso.sanjose (weatherdate, condition,
temperature, winddir, windspeed) values (?,?,?,?,?)
removeDB2Weather
delete from itso.sanjose where weatherdate = ?
Chapter 14. Weather forecast application
245
Summary
In this chapter we covered the weather forecast example base code that will be
used to create a Web service using the different tools or products. We discussed
the different components and how they interact to provide the weather forecast
functionality.
In the chapters that follow, we cover in detail the information required to create a
Web service using the different tools and products and following the paths
presented in this chapter:
Chapter 15, “WebSphere Studio Application Developer” on page 247,
provides an implementation using Application Developer.
Chapter 16, “Web services security with Application Developer” on page 303,
provides an implementation using WS-Security.
Chapter 17, “Application Developer Integration Edition” on page 341, provides
an implementation using Application Developer Integration Edition.
Chapter 18, “WebSphere SDK for Web Services” on page 381, provides an
implementation using the WebSphere SDK for Web Services.
246
WebSphere Version 5.1 Web Services Handbook
15
Chapter 15.
WebSphere Studio
Application Developer
This chapter describes the features of WebSphere Studio Application Developer
Version 5.1 as they relate to Web services.
If you are not familiar with the basic steps of how to create Web applications
using Application Developer, refer to the redbooks WebSphere Studio
Application Developer Version 5 Programming Guide, SG24-6957, (although this
publication is about Version 5.0) and EJB 2.0 Development with WebSphere
Studio Application Developer, SG24-6819.
This chapter covers the following topics:
Overview of Web services-related features in WebSphere Studio Application
Developer, including strategies for developing a new Web service
Creating a Web service in a bottom-up way, using HTTP and JMS protocols
Creating a Web service in a top-down fashion
Exploring and publishing to a UDDI directory from WebSphere Studio
Application Developer
© Copyright IBM Corp. 2003, 2004. All rights reserved.
247
Overview
WebSphere Studio Application Developer provides a toolbox for discovering,
creating, and publishing Web services that are created from JavaBeans, DADX
files, Enterprise JavaBeans, and URLs. You can also use Web service tools to
create a skeleton JavaBean and a sample application from a WSDL document.
The development path that you would typically follow to create and publish a Web
service is as follows:
Create router projects.
Create or import an artifact to be turned into a Web service.
Create a Web service.
Create a proxy and a test client.
Publish a business entity and a Web service.
Web tools assist you in developing Web applications that you can configure as a
Web service. Web applications are developed in a Web project, and server tools
enable you to use the unit test environment to test and deploy your Web services.
Strategies for developing a Web service
As pointed out in Chapter 13, “Web services development overview” on
page 221, there are several different ways to develop Web services:
There is the distinction between a bottom-up and a top-down development of
Web services, which addresses development issues for the provider part.
Furthermore, there is a question about which application and data structure
the Web service is generated from.
Finally, on the requestor side, the invocation can be implemented either
statically or dynamically.
Tool support by WebSphere Studio Application Developer
Application Developer supports a wide range of the above options.
Bottom-up
For bottom-up development (the most common case), the following data
structures can be used to build a Web service:
JavaBean—The Web service wizard assists you in creating a new Web
service, configuring it for deployment, and deploying the Web service to a
server (which can be the test environment that comes with Application
Developer, or an external application server).
248
WebSphere Version 5.1 Web Services Handbook
EJB—The Web service wizard assists you in creating a new Web service,
configuring it for deployment, and deploying the Web service to a server. With
Application Developer 5.1, SOAP/JMS support has been added for EJBs.
DADX—Document access definition extension (DADX) is an XML document
format that specifies how to create a Web service using a set of operations
that are defined by DAD documents and SQL statements. A DADX Web
service enables you to wrap DB2 XML Extender or regular SQL statements
inside a standard Web service. The DADX file defines the operations
available to the DADX runtime environment, and the input and output
parameters for the SQL operation.
URL—The Web service wizard assists you in creating a new Web service that
directly accesses a servlet running on a remote server.
ISD—An ISD file is a Web service deployment descriptor and provides
information to the SOAP runtime about the service that should be made
available to clients, for example, URI, methods, implementation classes
(JavaBean, EJB), serializers, and deserializers. ISD files are concatenated
into the SOAP deployment descriptor, dds.xml.
Top-down
For top-down development, Application Developer provides these functions:
JavaBean from WSDL—The Web service wizard assists you in creating a
skeleton JavaBean from an existing WSDL document. The skeleton bean
contains a set of methods that correspond to the operations described in the
WSDL document. When the bean is created, each method has a trivial
implementation that you replace by editing the bean.
JavaBean from XSD—The Web services tools support the generation of
JavaBeans from an XML schema. Using these beans, you can create a
JavaBean Web service.
Client development
To assist in the development of Web service clients, Application Developer
provides this function:
Java client proxy and sample application from WSDL—The Web service
client wizard assists you in generating a proxy JavaBean and a sample
application. The sample Web application demonstrates how to use the proxy
bean in a client program.
Note that the proxy and sample application can also be generated in
bottom-up and top-down approaches for testing of the generated Web
service.
Chapter 15. WebSphere Studio Application Developer
249
In summary, the tool offers many opportunities to create Web services from
bottom-up (starting from server-side code to generating the WSDL document
and the proxy code), but only limited opportunities to generate a service from
top-down (creating a JavaBean skeleton from a Web service description). In
particular, with the standard edition of Application Developer, an EJB cannot be
created from a WSDL document; however, this can be achieved with the
Integration Edition (see Chapter 17, “Application Developer Integration Edition”
on page 341).
On the client side, the invocation can be implemented in a static or dynamic way.
Both options can be implemented using Application Developer.
Furthermore, we show how Application Developer supports the developer in
testing and accessing a UDDI registry.
Selected scenarios
In the sections that follow we focus on the following scenarios:
Bottom-up development by generating a Web service from a JavaBean using
HTTP as the transport for the SOAP messages
Bottom-up development by generating a Web service from a session EJB
using HTTP as the transport for the SOAP messages
Bottom-up development by generating a Web service from an EJB using JMS
as the transport for SOAP messages
Top-down development by generating a JavaBean from an existing WSDL
Implementing interoperable Web services (WS-I convention)
Bottom-up generation of a Web service from a URL
Bottom-up Web service generation from DADX
Publishing of Web services into a UDDI registry
In these scenarios we do not focus on a dynamic invocation; this will be covered
in Chapter 19, “Web services scenario: Architecture and implementation” on
page 429.
For other types of Web service generation, refer to the online documentation of
Application Developer.
250
WebSphere Version 5.1 Web Services Handbook
Preparing the enterprise applications
To make it very clear which projects belong together for a Web service solution
we use different enterprise applications for each Web service generation:
ItsoWebService1—Contains one Web project, ItsoWebService1Web, with a
JavaBean, WeatherForecast. A Web service is generated from the JavaBean,
which also generates a client project.
ItsoWebService2—Contains one EJB project, ItsoWebService2EJB, with a
session bean, WeatherForecastEJB. A Web service is generated from the
session bean, which also generates a Web router project and a client project.
ItsoWebService3—Contains one EJB project, ItsoWebService3EJB, with a
session bean, WeatherForecastJMS. A JMS-based Web service is generated
from the session bean, which requires an EJB router project, and which
generates a client project.
Installing the weather forecast application
The Web services examples are based on the weather forecast application,
which was discussed in Chapter 14, “Weather forecast application” on page 233.
Although a thorough understanding of this application will be helpful in moving
forward, it is certainly not a requirement.
Important: To get started quickly, install the sample code available with this
book. Follow the instructions in “Installing the weather forecast application” on
page 528. You have to complete these steps:
“Set up the WEATHER database” on page 528
“Set up the WebSphere test server (WeatherServer)” on page 529
“Set up the initial applications for Web services development” on page 537
Optionally: “Test the starting application” on page 537
After installing the application, open the J2EE perspective, and in the J2EE
Hierarchy view, verify that your workspace looks like Figure 15-1.
Chapter 15. WebSphere Studio Application Developer
251
Enterprise applications
JavaBean Web service (HTTP)
Session EJB Web service (HTTP)
Session EJB Web service (JMS)
Server for testing
Figure 15-1 Weather forecast sample imported into the workspace
We will create three Web services:
JavaBean Web service from the itso.bean.WeatherForecast class in the
ItsoWebService1Web project
EJB Web service from the itso.session.WeatherForecastEJB session bean
in the ItsoWebService2EJB project
EJB Web service from the itso.jms.WeatherForecastJMS session bean in the
ItsoWebService3EJB project (JMS-based Web service)
If you want to examine the source code, navigate to the classes as seen in
Figure 15-2.
EJB
JavaBean
EJB
Figure 15-2 Navigating to the source code
252
WebSphere Version 5.1 Web Services Handbook
Creating a Web service from a JavaBean
In this section we create a Web service from an existing JavaBean, the
WeatherForecast bean introduced in Chapter 14, “Weather forecast application”
on page 233.
We describe how to use WebSphere Studio wizard to create a Web service that
returns information from the weather forecast service. The wizard guides us
through generating the WSDL document from the JavaBean, creating a proxy
bean, and testing the Web service in a Web browser using the Web Services
Explorer, the generated test JSPs, the universal test client, and the built-in
WebSphere test environment.
Out first approach is to create a Web service from a JavaBean in a bottom-up
way. We use the ItsoWebService1 enterprise application.
To create the Web service, including the WSDL document, deployment
descriptor, proxy, and test sample, we use the Web Service wizard. The Web
service proxy and test client is created in a separate Web project. This client
project can be created in advance, or quickly by the wizard. In this first example
we create the client project in advance.
Create a Web project for the test client
Here are the steps to create a Web project for the client code:
Select File -> New -> Other. Select Web in the left pane and Dynamic Web
Project in the right pane, and click Next.
Enter ItsoWebService1WebClient as the project name. In the bottom left
corner select Configure advanced options. Click Next.
From the EAR project drop-down menu, select ItsoWebService1. Click Finish.
Click Yes when prompted to repair the server configuration.
Web Service wizard
Select the WeatherForecast class in the ItsoWebService1Web project and File ->
New -> Other. Select Web Services to display the various Web service wizards.
Select Web Service and click Next to start the Web Service wizard.
We go through all the pages of the wizard. Click Next on each page to get to the
next page.
Chapter 15. WebSphere Studio Application Developer
253
In the Web service type drop-down menu, Java bean Web service is preselected.
Ensure that the following boxes are selected:
Start Web service in Web project
Test the Web service
Generate a proxy
Test the generated proxy
Overwrite files without warning (needed in case you rerun the wizard)
Create folders when necessary
From the Client proxy type drop-down menu, ensure that Java proxy is selected.
Figure 15-3 shows the window after making these selections.
Figure 15-3 Web Service wizard: Initial
Service Deployment Configuration
The Service Deployment Configuration page allows you to specify the server and
the project names. Make sure that the WeatherServer is selected as the Server,
ItsoWebService1Web as the Service Web Project, and
ItsoWebService1WebClient as Client Web Project.
Web Service Java Bean Selection
The Web Service Java Bean Selection page allows you to specify the Java bean
to be turned into a Web service. The itso.bean.WeatherForecast bean should be
254
WebSphere Version 5.1 Web Services Handbook
preselected; if not, click Browse classes and locate the class from the
JavaSource folder and click OK.
Web Service Java Bean Identity
In the Web Service Java Bean Identity page, the three main items are the WSDL
file name, methods to be exposed in the Web service, and the SOAP format of
the Web service. This is illustrated in Figure 15-4.
Figure 15-4 Web Service wizard: Java Bean Identity options
We now briefly describe these options before we continue:
Web service URI—Specifies the target URL that a Web service client will use
to access the Web service.
WSDL Folder—The WSDL file is written into this folder. This folder is relative
to the workspace.
WSDL File—Here we can specify a WSDL file name of our choice. The
default file name should work fine for most applications.
Methods—A listing of public methods in the Java bean that are available to be
exposed to the Web service. Select the methods that you want to expose. For
our application, we select all the get methods of the WeatherForecast bean.
We will use the setWeather method later in a JMS-based Web service.
JMS-based Web services are discussed in “Web services and JMS protocol”
on page 274.
Chapter 15. WebSphere Studio Application Developer
255
Style and Use—The SOAP format to be expected by the Web service. In our
example, we will use the Document/Literal format.
Attention: If you are creating an RPC/Encoded Web service, you are presented
with a warning (Figure 15-5) indicating non-compliance with WS-I. We are
creating a Document/Literal Web service here so you will not see this
message. If your client and server are both WebSphere based, the WS-I
warning is unlikely to be an issue. When presented with this warning, click
Ignore and continue with creating the Web service.
Figure 15-5 WS-I compliance warning
Web Service Test Page
This page allows you test a Web service using the Web Services Explorer. The
Web Services Explorer is a new Web-based tool introduced with Application
Developer 5.1. The tool uses the WSDL file to dynamically test the Web service.
The Web Services Explorer can also be invoked manually after the Web service
has been created. We will discuss the Web Services Explorer in “Web Services
Explorer” on page 296. We skip this step for now.
Note: in Application Developer 5.1.1 the Web Service Explorer is started even
if you do not click Launch.
Web Service Proxy Page
On this page, select options as shown in Figure 15-6.
Generate proxy—This creates JSR 101-compliant proxy classes for the Web
service. Web service clients can then be written based on the proxy classes.
Output folder—The location of the proxy classes (in the client project).
Accept the Security Configuration as No Security, and do not select Define
custom mapping for namespace to package.
256
WebSphere Version 5.1 Web Services Handbook
Figure 15-6 Web Service wizard: Proxy page
Web Service Client Test
The wizard offers to create a test client for you. This test client is JSP based and
uses the proxy classes that were created in the previous step. We want to test all
the methods exposed in the Web service, so select all the methods available in
the Web service. Select the remaining options as shown in Figure 15-7. By
selecting Run test on server, we launch these JSPs.
Figure 15-7 Web Service wizard: Test client
Chapter 15. WebSphere Studio Application Developer
257
Note: The first and last three method selections are new in Application
Developer 5.1.1. The useJNDI method enables the test client to use or not to
use JDNI to retrieve the service factory (JSR 109).
Click Finish.
The Web service is installed in the ItsoWebService1Web project (server-side
project) and the proxy and sample test client are generated into the
ItsoWebService1WebClient project (client-side project).
The WeatherServer is started (be patient). A Web browser window with the test
client is displayed (Figure 15-8).
You can now test your newly created Web service using the three methods from
the left frame. We will discuss the test JSPs and the procedure for invoking the
tests in detail in “Test using generated JSPs” on page 262.
Figure 15-8 Testing the Web service using the test client
Note: In case the test JSPs do not work and return an error, restart the
WeatherServer and rerun the JSPs.
258
WebSphere Version 5.1 Web Services Handbook
Generated files
Let us take a moment to look at the generated files (Figure 15-9).
JavaBean
SEI
Data
mapping
files
Proxy files
(JSR 101)
Test JSPs
WSDL
Deployment
descriptor
(JSR 109),
bindings and
extensions
Server Project
Client Project
Figure 15-9 Project Navigator view after the generation of the Web service
Files generated in the server-side Web project
According to the settings made during the run of the wizard, the following files in
the ItsoWebService1Web project have been created:
Service endpoint interface (SEI): itso.bean.WeatherForecast_SEI.java is
the interface defining the methods of the Web service.
WSDL file: /WebContent/WEB-INF/wsdl/WeatherForecast.wsdl describes the
Web service to the clients. A copy is also in the WebContent folder.
Deployment descriptor: webservices.xml, ibm-webservices-ext.xml, and
ibm-webservices-bnd.xml. These files describe the Web service according to
Chapter 15. WebSphere Studio Application Developer
259
the Web services for J2EE style (JSR 109). The mapping is described in the
WeatherForecast_mapping.xml file.
Data mapping files: The files in the itso.mapping package perform the data
conversion from XML to Java and back.
Files generated in the client-side Web project
If the creation of a client-side proxy is selected, two packages are generated in
the ItsoWebService1ClientWeb project:
itso.mapping contains the Java -> XML and XML -> Java data mapping logic.
itso.bean contains the proxy classes. These classes are used by the client to
make remote calls as per JSR 101. See “Proxy classes” on page 263 for a
detailed description. With the help of these classes, the client can instantiate
local representations of the remote classes (see “Writing Web service clients”
on page 264). The generated test JSPs also use these proxy classes.
Test client: JSPs to test each method exposed as a Web service. The test
client is generated in the WebContent/sample/WeatherForecastProxy folder.
Deployment descriptor: webservicesclient.xml and extension. These files
describe the Web service in the client according to the Web services for J2EE
style (JSR 109). The mapping file is also there.
A copy of the WSDL file (in WEB-INF\wsdl).
Testing the Web service
We present two ways of testing the Web service and its generated proxy:
Test using the Web Services Explorer.
Test using generated JSPs.
To test the Web service, you must have a Web service-enabled weather forecast
application as generated in the previous step.
Web Services Explorer
Application Developer 5.1 introduces the Web Services Explorer tool, which
allows testing of a Web service. Ensure that the WeatherServer is running. Here
are instructions for using the Explorer.
Navigate to the WSDL file of the Web service. For the weather application,
this file is WeatherForecast.wsdl, as shown in Figure 15-9.
Select the WSDL file and Web Services -> Test with Web Services Explorer
(context). This launches the tool (Figure 15-10).
260
WebSphere Version 5.1 Web Services Handbook
Figure 15-10 Web Services Explorer: Browser page
In the top right frame select the Web services method you want to test, for
example, getForecast. Sample input values as shown in Figure 15-11.
Figure 15-11 Web Services Explorer: Testing a Web service method
Tip: Click Browse to open a calendar. Click any day and a suitable value is
inserted into the parameter prompt.
Chapter 15. WebSphere Studio Application Developer
261
Click Go.
The result can be seen in the Status window (bottom right frame). Some
results cannot be formatted and you have to select the Source link to view the
SOAP request and response (Figure 15-12).
Note that this is a
result of the
getTemperatures
method.
Figure 15-12 Web Services Explorer: SOAP message results
Test using generated JSPs
Selecting Test the generated proxy in the Web services wizard (Figure 15-7)
creates a JSP-based test client.
To run the test, select the TestClient.jsp in the ItsoWebServiceTestClientWeb
project (WebContent/sample/WeatherForecast) and Run on Server. The JSP
opens in a browser pane with this URL:
http://localhost:9080/ItsoWebService1WebClient/sample/WeatherForecastProxy
/TestClient.jsp
If prompted to select a server, select the WeatherServer and select Set server
as project default, then click Finish.
To examine the Web service application, select any of the three Web service
methods, enter a date, and click Invoke. Figure 15-13 displays the results of
the invocation of the getTemperatures method.
262
WebSphere Version 5.1 Web Services Handbook
Figure 15-13 Sample test client result
Note that the getForecast method returns an array of Weather objects. These are
displayed as object references:
[[email protected], [email protected],
[email protected], [email protected],
[email protected]]
To get a nicer result you could copy the toString method from the original
Weather class (in ItsoWebService1Web) to the generated Weather class in the
ItsoWebService1WebClient project.
Proxy classes
The generated proxy classes include:
WeatherForecast—Service endpoint interface.
WeatherForecastSoapBindingStub—SOAP proxy class that implements the
service endpoint interface and communicates with the SOAP runtime.
WeatherForecastService—Service interface.
WeatherForecastServiceLocator—Service locator class that implements the
service interface and provides methods to acquire the service endpoint
interface. This class also contains the service address:
http://localhost:9080/ItsoWebService1Web/services/WeatherForecast
Chapter 15. WebSphere Studio Application Developer
263
WeatherForecastProxy—Simple proxy class for the client. This proxy class
uses either JSR 101 (instantiate the WeatherForecastServiceLocator) or JSR
109 (use JNDI to find the WeatherForecastServiceLocator) to get the service
endpoint interface. The useJNDI(boolean) method is provided to switch
between JSR 101 and JSR 109 clients (JSR 109 is the default).
The proxy also provides the Web service methods (getDayForecast,
getForecast, getTemperatures) for easy invocation by a client.
Note: The simple proxy class is new in Application Developer 5.1.1.
A Web service client can use the service locator directly or the simple proxy
class, as illustrated here:
// Client using JSR 101
WeatherForecastServiceLocator loc = new WeatherForecastServiceLocator();
WeatherForecast proxy = loc.getWeatherForecast();
Weather w = proxy.getDayForecast(...date...);
<=== invoke Web service
// Client using JSR 109
InitialContext ctx = new InitialContext();
WeatherForecastServiceLocator loc = (WeatherForecastServiceLocator)
ctx.lookup("java:comp/env/service/WeatherForecastService");
WeatherForecast proxy = loc.getWeatherForecast();
Weather w = proxy.getDayForecast(...date...);
<=== invoke Web service
// Client using simple proxy
WeatherForecastProxy proxy = new WeatherForecastProxy();
Weather w = proxy.getDayForecast(...date...);
<=== invoke Web service
Writing Web service clients
In this section we develop two small Web service clients that invoke the methods
of the Web service using the generated proxy classes:
Stand-alone Java client
Web client servlet
Stand-alone Java client
The stand-alone Java client is a Java main program. To incorporate client code
you have to create or use a suitable project in which you develop the client code;
we use a new ItsoWebService1JavaClient project (Java project). The client code
is shown in Example 15-1 and is available in the sample code:
sg246891-01\sampcode\wsad51\JavaClient\WebServiceTestClientMain.java
264
WebSphere Version 5.1 Web Services Handbook
Example 15-1 Web service Java client
package itso.client;
import java.util.*;
import itso.bean.*;
import itso.mapping.*;
public class WebServiceTestClientMain {
public static void main(String[] args) {
System.out.println(
"** RUNNING THE STANDALONE JAVA CLIENT OF WEATHERFORECAST WEB SERVICE **\n");
try {
// Instantiate the WeatherForecast object
WeatherForecastServiceLocator wfsl =
new WeatherForecastServiceLocator();
WeatherForecast wf = (WeatherForecast) wfsl.getWeatherForecast();
// Call each method one by one
System.out.println("1. Testing getDayForecast() method ...");
Weather retGetDF = wf.getDayForecast(Calendar.getInstance());
System.out.println(retGetDF.getCondition().toString());
System.out.println(
retGetDF.getDate().getTime().toString()
+ "\t"
+ "Temperature = "
+ retGetDF.getTemperatureCelsius()
+ "\t"
+ "WindDirection = "
+ retGetDF.getWindDirection().toString()
+ "\t"
+ "getWindSpeed = "
+ retGetDF.getWindSpeed()
+ "\t"
+ "Condition = "
+ retGetDF.getCondition().toString());
System.out.println("getDayForecast() test successful\n");
System.out.println("2. Testing getForecast() method ...");
int numDays = 2;
Weather retGF[] = wf.getForecast(Calendar.getInstance(), numDays);
for (int loopCount = 0; loopCount <= numDays; loopCount++) {
System.out.println(
retGF[loopCount].getDate().getTime().toString()
+ "\t"
+ "Temperature = "
+ retGF[loopCount].getTemperatureCelsius()
+ "\t"
+ "WindDirection = "
+ retGF[loopCount].getWindDirection().toString()
+ "\t"
+ "getWindSpeed = "
Chapter 15. WebSphere Studio Application Developer
265
+
+
+
+
retGF[loopCount].getWindSpeed()
"\t"
"Condition = "
retGF[loopCount].getCondition().toString());
}
System.out.println("getForecast() test successful\n");
System.out.println("3. Testing getTemperatures() method ...");
int retGT[] = wf.getTemperatures(Calendar.getInstance(), numDays);
for (int loopCount = 0; loopCount <= numDays; loopCount++) {
System.out.print("Temperature = " + retGT[loopCount] + ", ");
}
System.out.println("\ngetTemperatures() test successful\n");
} catch (Exception e) {
System.out.println(
"Request failed. For more information see the stack trace");
e.printStackTrace();
}
}
}
Running the client
To run this client perform these steps:
Locate the WebServiceTestClientMain.java file in the sample code:
sg246891-01\sampcode\wsad51\JavaClient\
Create a Java project named ItsoWebService1JavaClient. Create a package
named itso.client.
Select the new package and Import (context). Select File system, click Next,
and import the WebServiceTestClientMain client program. Many errors are
reported in the Tasks view.
Copy the proxy (itso.bean) and mapping (itso.mapping) packages from the
ItsoWebService1WebClient project to the ItsoWebService1JavaClient
project.
Set up the classpath with the required libraries:
– Select the ItsoWebServiceClientJava project and Properties (context).
– Select Java Build Path and go to the Libraries tab (Figure 15-14).
– Click Add Variable, locate WAS_50_PLUGINDIR, and click Extend. Expand
the lib folder and select the j2ee.jar file. Click OK.
– Repeat this and add the qname.jar, webservices.jar, and wsdl4j.jar
files.
– Click OK to close the properties window; the errors should disappear.
266
WebSphere Version 5.1 Web Services Handbook
Figure 15-14 Setting the Java Build Path
Make sure the WeatherServer is started.
In the Java perspective, select the WebServiceTestClientMain and Run ->
Run As -> Java Application and enjoy the result in the Console view (select
the correct Console output by using the drop-down menu):
** RUNNING THE STANDALONE JAVA CLIENT OF WEATHERFORECAST WEB SERVICE **
1. Testing getDayForecast() method ...
Wed Nov 19 00:00:00 PST 2003Temperature = 17WindDirection = SEgetWindSpeed = 17
Condition = partly cloudy
getDayForecast() test successful
2. Testing getForecast() method ...
Wed Nov 19 00:00:00 PST 2003Temperature = 17WindDirection = SEgetWindSpeed = 17
Condition = partly cloudy
Thu Nov 20 00:00:00 PST 2003Temperature = 21WindDirection = NWgetWindSpeed = 22
Condition = partly cloudy
Fri Nov 21 00:00:00 PST 2003Temperature = 22WindDirection = SEgetWindSpeed = 32
Condition = stormy
getForecast() test successful
3. Testing getTemperatures() method ...
Temperature = 17, Temperature = 21, Temperature = 22,
getTemperatures() test successful
See “Accessing a Web service from a stand-alone Java client” on page 500 for
how to run this client outside of Application Developer.
Chapter 15. WebSphere Studio Application Developer
267
Web client
The Web client is a simple servlet that uses the proxy classes to invoke one of
the Web service methods. We develop this client in the existing client project
(ItsoWebService1WebClient).
The code is available in:
sg246891-01\sampcode\wsad51\WebClient\WeatherClient.java
To install and run the servlet:
Create an itso.servlet package in the ItsoWebService1WebClient project.
Import the WeatherClient file into the new package. Here is an extract of the
servlet code:
WeatherForecastServiceLocator wfsl = new WeatherForecastServiceLocator();
WeatherForecast wf = (WeatherForecast) wfsl.getWeatherForecast();
Weather[] wa = wf.getForecast(Calendar.getInstance(), 3);
out.println("<html><body><h1>Weather Results</h1><table border=1 cellpadding=5>");
out.println("<tr><th>Date</th><th>Condition</th><th>Temperature</th>...</tr>");
for (int i=0; i<wa.length; i++)
out.println("<tr><td>"+sdf.format( wa[i].getDate().getTime() )
+"</td><td>"+wa[i].getCondition() + ... +"</td></tr>");
out.println("</table></body></html>");
Open the deployment descriptor of the Web project. On the Servlets page
add the WeatherClient servlet. Also set the URL mapping to /WeatherClient.
Select the WeatherServer and Restart Project -> ItsoWebService1 (context).
Select the WeatherClient servlet and Run on Server. The output is displayed
in an HTML table (Figure 15-15).
Figure 15-15 Web service client servlet output
268
WebSphere Version 5.1 Web Services Handbook
Tracing SOAP messages
In this section we describe how you can watch the SOAP messages that are
received and sent by the WebSphere server.
Application Developer provides a TCP/IP Monitoring Server that can be used to
watch the HTTP traffic, that is, the messages that are received by the server and
the responses that are sent back.
Using the TCP/IP Monitoring server
The TCP/IP Monitor intercepts the messages at a given port (9081 by default)
and then forwards the messages to the server (port 9080 by default). This is a
very practical way to study the SOAP messages that are received by the server
and the responses that are sent back to the client.
Define the server
First we have to define the server. Select File -> New -> Server and Server
Configuration, enter WeatherMonitor as the name, select Other -> TCP/IP
Monitoring Server as the server type, and click Finish.
Change the endpoint port number
To intercept the SOAP messages, we change the proxy to send the requests to
port 9081 (instead of 9080).
Edit the WeatherForecastServiceLocator class in the client project
(ItsoWebService1WebClient), and change the target URL to point to port 9081:
private final java.lang.String weatherForecast_address =
"http://localhost:9081/ItsoWebService1Web/services/WeatherForecast";
Note: After running this sample, change the port number back to 9080.
Start the servers
Start the WeatherMonitor and the WeatherServer.
Run a client
Run any of the clients, for example, the sample test client. When you select Run
on Server you are prompted to select to run the browser with or without the
TCP/IP Monitor.
Note that this affects only the HTTP traffic from HTML pages and JSPs; the
SOAP traffic from the proxy is already routed to port 9081. If we only want to
watch the SOAP traffic, we can select the normal Web browser.
Chapter 15. WebSphere Studio Application Developer
269
TCP/IP Monitor view
The output of the TCP/IP Monitor is displayed in the TCP/IP Monitor view
(Figure 15-16).
Figure 15-16 TCP/IP Monitor output
For each request you can see the input message in the left pane and the output
message in the right pane. You need to scroll to the right to view the entire SOAP
message (or copy/paste the message into an editor).
The SOAP input message for the getDayForecast operation is:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<getDayForecast xmlns="http://bean.itso">
<theDate>2003-11-26T08:00:00.000Z</theDate>
</getDayForecast>
</soapenv:Body>
</soapenv:Envelope>
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:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<getDayForecastResponse xmlns="http://bean.itso">
270
WebSphere Version 5.1 Web Services Handbook
<getDayForecastReturn>
<condition xmlns="http://mapping.itso">rainy</condition>
<date xmlns="http://mapping.itso">2003-11-26T08:00:00.000Z
</date>
<windDirection xmlns="http://mapping.itso">NW</windDirection>
<windSpeed xmlns="http://mapping.itso">10</windSpeed>
<temperatureCelsius xmlns="http://mapping.itso">17
</temperatureCelsius>
<dbflag xmlns="http://mapping.itso">1</dbflag>
</getDayForecastReturn>
</getDayForecastResponse>
</soapenv:Body>
</soapenv:Envelope>
The SOAP response message for getWeekForecast is an array of seven Weather
objects, and the response for getWeekTemperatures is an array of seven integers.
Target URL
Do not forget to reset the target URL in the WeatherForecastServiceLocator
class back to port 9080.
Note that you can also change the target URL dynamically by invoking the
setEndpoint method of the proxy object. The test JSPs provide a link to execute
the method. This eliminates the change in the source code.
The easiest way is to invoke the getEndpoint method and copy the result. Then
select the setEndpoint method, paste the copied URL, and change the port to
9081 before invoking the method.
Creating a Web service from a session bean
We provide a session bean, WeatherForecastEJB, that has the same methods as
the WeatherForecast JavaBean. In this section we create a Web service from the
session bean. We use the ItsoWebService2 enterprise application.
Running the Web Service wizard
This process is very similar to what we did with the JavaBean, so the instructions
are shorter. Note that we create a router Web project in advance, and a client
project while running the wizard:
Stop the WeatherServer if it is running.
Create a new Web project named ItsoWebService2RouterWeb in the
ItsoWebService2 EAR project. The router project is used to route a Web
Chapter 15. WebSphere Studio Application Developer
271
service call to the session EJB. Such a project should not be used for
anything else.
In the J2EE Hierarchy view for the ItsoWebService2EJB project, select the
WeatherForecastEJB session bean and New -> Other -> Web Services ->
Web Service. Click Next.
The Web service type is preselected (EJB Web service). Select Start Web
service in Web project, Generate a proxy, Test the generated proxy, Overwrite
files without warning, and Create folders when necessary.
For the Router project enter ItsoWebService2RouterWeb, and for the Client
Web project enter ItsoWebService2EJBClient. This Web client project is
created by the wizard.
The EJB is preselected and all defaults are fine (SOAP over HTTP is the only
option).
Deselect the setWeather method, and leave the other three methods
selected. Select Document/Literal.
Select Generate proxy (preselected).
Select Test the generated proxy, and click Finish.
The code is generated and the WeatherServer is started. You can test the Web
service using the generated test client.
Generated code
In the ItsoWebService2EJB project you will find:
Service endpoint interface: itso.session.WeatherForecastEJB_SEI
Mapping classes in itso.mapping
WSDL file in META-INF/wsdl: WeatherForecastEJB.wsdl
Web service deployment descriptor: webservices.xml in META-INF
In the ItsoWebService2RouterWeb project you will find:
Router servlet named WeatherForecastEJB, pointing to
com.ibm.ws.webservices.engine.transport.http.WebServicesServlet, with
a URL named services/WeatherForecastEJB
WSDL file in WebContent/wsdl
In the ItsoWebService2EJBClient project you will find:
272
Proxy and mapping classes (itso.session and itso.mapping)
Sample test client in WebContent/sample/WeatherForecastEJBProxy
WSDL file in WebContent/WEB-INF/wsdl
Web service deployment descriptor: webservicesclient.xml in WEB-INF
WebSphere Version 5.1 Web Services Handbook
Testing the EJB Web service
We have a number of choices to test the EJB Web service.
Web Services Explorer
You can run the Web Services Explorer from the WeatherForecastEJB.wsdl file
(see “Web Services Explorer” on page 260).
You can use the generated test client by running the TestClient.jsp in
ItsoWebService2EJBClient/WebContent/sample/WeatherForecastEJBProxy.
Universal test client
You can also use the universal test client to test a Web service:
Select the WeatherForecastEJBServiceLocator class in the client project and
Web Services -> Launch Universal Test Client.
Expand the WeatherForecastEJBServiceLocator and invoke the
getWeatherForecastEJB() method. Click on Work with Object and the result
object, WeatherForecastEJBSoapBindingStub, is added to the object
references.
Expand the WeatherForecastEJBSoapBindingStub object and run the Web
service methods.
Alternatively, you can select the WeatherForecastEJBProxy class in the client
project and Web Services -> Launch Universal Test Client. Expand the class
and run the Web service methods.
Client servlet
Create a servlet, WeatherClientEJB, in the ItsoWebService2EJBClient project.
The code is the same as the WeatherClient in the ItsoWebService1WebClient
project, but using the WeatherForecastEJBServiceLocator class:
// Instantiate the WeatherForecast object
WeatherForecastEJBServiceLocator wfsl =
new WeatherForecastEJBServiceLocator();
WeatherForecastEJB wf = (WeatherForecastEJB) wfsl.getWeatherForecastEJB();
Weather[] wa = wf.getForecast(Calendar.getInstance(), 3);
......
The servlet is provided in sg246891-01\sampcode\wsad51\EJBClient and must be
imported into an itso.servlet package and added to the deployment descriptor.
Chapter 15. WebSphere Studio Application Developer
273
Web services and JMS protocol
Starting with Application Developer 5.1, we can develop Web services that use
SOAP/JMS as the transport mechanism. Prior to this release, we could develop
Web services based only on SOAP/HTTP.
SOAP over JMS example
JMS-based Web services cannot return any result to the caller. We will use the
setWeather method of the session EJB to create a SOAP over JMS Web service.
Here are the main steps of how a JMS service is developed:
Configure the JMS server with JMS resources (QueueConnectionFactory,
Queue, ListenerPort).
Create a JMS-based Web service.
Create a client to test the Web service.
You can also create the Web service first and then configure the server for
testing.
Configuring the JMS Server
To run a JMS-based Web service the WeatherServer must be configured with a
JMS Server. Follow the instructions in “Configure the JMS server” on page 534.
Make sure the WeatherServer is stopped before continuing.
Projects for the Web service and sample client
When creating a JMS-based Web service, an EJB router project is required. In
this project a message-driven bean (MDB) is created. The MDB reads JMS
messages from the queue and invokes the Web service. We will use a project
named ItsoWebService3EJBRouter to house the MDB.
To test the JMS-based Web service we use a new client Web project named
ItsoWebService3EJBClient.
The router EJB project must be defined in advance under the enterprise
application, whereas client Web projects can be created dynamically when
running the Web Service wizard.
Create a new EJB project named ItsoWebService3EJBRouter under the
ItsoWebService3 enterprise application (select File -> New -> EJB Project).
274
WebSphere Version 5.1 Web Services Handbook
Create the SOAP over JMS Web service
We will create a Web service from of the WeatherForecastJMS session EJB. The
setWeather method of this EJB will be exposed as a Web service:
In the J2EE Hierarchy view for the ItsoWebService3EJB project, select the
WeatherForecastJMS session bean and New -> Other -> Web Services ->
Web Service. Click Next.
We only create the Web service. We will start the Web service and create a
client later (Figure 15-17). Click Next.
Figure 15-17 Create a JMS Web service
On the Service Deployment Configuration page, select ItsoWebService3EJB
for the EJB Project and ItsoWebService3EJBRouter for the Router Project.
Click Next.
On the Web Service EJB Selection pane, specify the values as shown in
Figure 15-18 and click Next. Everything is prefilled, except for the port
component value Weather.
Chapter 15. WebSphere Studio Application Developer
275
Figure 15-18 Specify the JMS settings of the Web service
On the Web Service Java Bean identity page, deselect all the get methods and
select only the setWeather method. Select RPC/Encoded as the SOAP format.
When prompted with the warning, as in Figure 15-19, click Ignore.
Figure 15-19 Warning issued when creating a JMS Web service
276
WebSphere Version 5.1 Web Services Handbook
At this point we are ready to generate the Web service. Click Finish. In the next
section we will now create a test client to test this SOAP/JMS Web service.
Creating a Web service client
In the previous examples we had a test client generated. This time we create the
proxy classes from a WSDL file, and then we create a real client.
Create the Java proxy classes
The client that we create later uses these proxy files to connect with the Web
service. To create the proxy files, follow these steps:
Create a new Web project named ItsoWebService3EJBClient in the
ItsoWebService3 enterprise application.
Select the WeatherForecastJMS.wsdl file (in the ItsoWebService3EJB project
under META-INF) and Web Services -> Generate Client.
Select Java proxy and click Next. (Do not select Test the generated proxy.)
For the Client Web Project select ItsoWebService3EJBClient and click Next.
The WSDL file is preselected, so click Next.
Click Finish to generate the proxy classes.
If you look in the Tasks view, you will see several warnings. The warnings are
Web services interoperability items that we can ignore for the purpose of this
sample application.
If you see an error, select the ItsoWebService3EJBClient project and Project
-> Rebuild Project.
Create the test servlet
We now create a test client in the form of a servlet that invokes the JMS Web
service:
In the ItsoWebService3EJBClient project create an itso.servlet package.
In the new package create a servlet named JmsSetWeatherServlet.
Replace the servlet code with the sample code in Figure 15-20, which is
available in sg246891-01\sampcode\wsad51\JMSClient.
Chapter 15. WebSphere Studio Application Developer
277
package itso.servlet;
import
import
import
import
itso.jms.WeatherForecastJMS;
itso.jms.WeatherForecastJMSServiceLocator;
itso.mapping.Weather;
...;
public class JmsSetWeatherServlet extends HttpServlet implements Servlet {
public void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
PrintWriter out = resp.getWriter();
out.println("<html><body><h1>JMS Set Weather Servlet</h1>");
out.println("<h2>Calling the JMS Web service ...</h2>");
try {
// Get the initial context and the local representation of the Web Service
InitialContext ic = new InitialContext();
WeatherForecastJMSServiceLocator wfsl =
(WeatherForecastJMSServiceLocator) ic.lookup(
"java:comp/env/service/WeatherForecastJMSService");
WeatherForecastJMS wf =
(WeatherForecastJMS) wfsl.getPort(WeatherForecastJMS.class);
// The setWeather() method takes in a Weather[] as input.
// Initializing an array with two sample elements ...
Weather[] wObj = new Weather[2];
wObj[0] = new Weather();
wObj[0].setDate( new GregorianCalendar(2005,4,5) );
wObj[0].setCondition("sunny");
wObj[0].setTemperatureCelsius(15);
wObj[0].setWindDirection("NE");
wObj[0].setWindSpeed(10);
wObj[1] = new Weather();
wObj[1].setDate( Calendar.getInstance() );
wObj[1].setCondition("rainy");
wObj[1].setTemperatureCelsius(44);
wObj[1].setWindDirection("NE");
wObj[1].setWindSpeed(44);
// Calling the Web Service
wf.setWeather(wObj);
out.println("<p>JMS Set Weather Servlet call completed!</p>");
out.println("<p>Verify that 2 rows are inserted in the DB with date
5/5/2005 and current date.</p>");
out.println("<p>For example run: SELECT * from ITSO.SANJOSE</p>");
} catch (Exception e) {
out.println("<p>Request failed. Check logs for details.</p>");
e.printStackTrace();
}
}
}
Figure 15-20 Sample JMS test client
278
WebSphere Version 5.1 Web Services Handbook
Start the WeatherServer and run the servlet. Upon successful completion of
the servlet, you will see a success message in the Web browser
(Figure 15-21). If you get an error messsage, check the WeatherServer logs.
Figure 15-21 Output of JMS servlet client
Creating a Web service top-down from WSDL
In this section we create a Java Bean on the server side from an existing WSDL
document. The wizard for this procedure is structured in the same way as for the
previous example. Therefore, it also offers opportunities to create a proxy on the
client side and to test the generated code. Because we have explored these
features already in the previous sections, we could omit them. Generating the
proxy enables us to test the new Web service.
Create Web projects and import the WSDL
The wizard asks for a given WSDL document that can be placed anywhere on
the workspace, and for a Web project into which the code is generated. In
addition we can generate a proxy into a client project.
For our scenario, we start by creating a new enterprise application,
ItsoWebService4, with two Web projects, ItsoWebService4Web and
ItsoWebService4WebClient.
Next we import the WSDL files into the ItsoWebService4Web project:
Create a new folder named wsdl under WebContent.
Select the wsdl folder and Import to import the WSDL file:
sg246891-01\sampcode\wsad51\top-down\WeatherForecastTD.wsdl
Chapter 15. WebSphere Studio Application Developer
279
Create the skeleton JavaBean
Now we can run the Web services wizard to create the Java code. We could use
the full Web Service wizard and generate the skeleton bean, the test client, and
install the service in a server. We use a simpler approach here:
Select the WeatherForecastTD.wsdl file and Web Services -> Generate Java
bean skeleton.
Make sure that ItsoWebService4Web is selected for the Web project.
The WSDL file is preselected.
The skeleton folder is set to /ItsoWebService4Web/JavaSource.
Click Finish.
Generated files
The generated files in the ItsoWebService4Web project are:
Skeleton files in the itso.bean package: WeatherForecast (an interface) and
WeatherForecastSoapBindingImpl, the implementation class.
Mapping classes in itso.mapping.
A copy of the WSDL file in WEB-INF/wsdl and in WebContent/wsdl, with an
updated target address:
<wsdlsoap:address
location="http://localhost:9080/ItsoWebService4Web/services/WeatherForecast"/>
You may want to delete the original WSDL file (with the old address).
Deployment descriptor files (webservices.xml, ...) in WEB-INF.
Client proxy
To generate a proxy and a test client, select the new WSDL file (under WEB-INF)
and Web Services -> Generate Client.
Select Test the generated proxy to create the test client.
Make sure that the output goes into the ItsoWebService4WebClient project.
Tip: If you see warnings in the Tasks view, select the project and Project ->
Rebuild Project.
Implementing the JavaBean
Figure 15-22 shows the generated skeleton JavaBean code.
280
WebSphere Version 5.1 Web Services Handbook
package itso.bean;
public class WeatherForecastSoapBindingImpl
implements itso.bean.WeatherForecast {
public itso.mapping.Weather getDayForecast(java.util.Calendar theDate)
throws java.rmi.RemoteException {
return null;
}
public itso.mapping.Weather[] getForecast(java.util.Calendar startDate,
int days) throws java.rmi.RemoteException {
return null;
}
public int[] getTemperatures(java.util.Calendar startDate, int days)
throws java.rmi.RemoteException {
return null;
}
}
Figure 15-22 Generated skeleton JavaBean
To implement a real Web service in place of this skeleton, replace the skeleton
code with the implementation code similar to what is provided in
ItsoWebService1Web project. Here are short instructions:
Add the method code to the skeleton methods.
Add the variables and helper methods.
The java.lang.Exception must be changed to java.rmi.RemoteException.
You will see several errors in the Tasks pane. To eliminated the errors the Web
project must be configured:
– Copy the WeatherPredictor.java file into the itso.mapping package.
– Add a resource reference (ItsoWeatherDB) with JNDI name
jdbc/sjweather for the data source.
– Add four environment variables (dataSource, getDB2Weather, setDB2Weather,
removeDB2Weather).
For the last two steps copy the entries from the ItsoWebService1Web project.
Note: You end up with the same Web service as in ItsoWebService1Web.
Therefore, it is hardly worth the effort.
Chapter 15. WebSphere Studio Application Developer
281
Web services interoperability
Application Developer provides facilities to generate WS-I compliant Web
services and to test the generated Web services for WS-I compliance. See “Web
services interoperability (WS-I)” on page 15 for a general introduction to WS-I.
WS-I preferences
The WS-I compliance preference can be set in the Windows -> Preferences
dialog (workspace level) or in the Properties for a project (Figure 15-23).
Figure 15-23 WS-I preference and project properties
The Web services WS-I validation tools support the level of WS-I compliance
outlined in the WS-I Basic Profile 1.0. You can choose to make your Web service
compliant or non-compliant, depending on your needs. For example, encoded
and SOAP over JMS protocols, as well as secured Web services, are not
supported by the WS-I specifications.
You can select three levels of compliance with WS-I Basic Profile 1.0:
Require WS-I compliance—This level prevents you from creating a
non-compliant Web service.
Suggest WS-I compliance—This level allows you to create a non-compliant
Web service, but provides a visible warning stating how the service is
non-compliant.
Ignore WS-I compliance—This level allows you to create a non-compliant
Web service and does not notify you of non-compliance.
282
WebSphere Version 5.1 Web Services Handbook
Web service generation
When generating a Web service that is not WS-I compliant and the preference
has been set to Suggest WS-I compliance, you get a warning message, as
shown in Figure 15-5 on page 256.
WSDL validation
A WSDL file can be validated against WS-I. Set the workspace preference or
project properties to Require WS-I compliance, select a WSDL file and Validate
WSDL File (context), and you are notified with a message and errors in the Tasks
view if the WSDL file is not WS-I compliant.
For example, set the project preference for the ItsoWebService3EJB project to
Require WS-I compliance, select the WeatherForecastJMS.wsdl file and Validate
WSDL File, and you get the error message shown in Figure 15-24.
Figure 15-24 WS-I compliance validation error
If the preferences are set to Suggest WS-I compliance, the WSDL validation
succeeds, but warning messages are shown in the Tasks view.
Validating SOAP messages with the TCP/IP Monitor
To validate actual SOAP messages for WS-I compliance, start the TCP/IP
Monitor and route the SOAP messages to port 9081 by changing the port in the
service locator class; for example:
private final java.lang.String weatherForecast_address =
"http://localhost:9081/ItsoWebService1Web/services/WeatherForecast";
Start the WeatherServer, run a client, then check the SOAP messages in the
TCP/IP Monitor view (Figure 15-25):
Open the TCP/IP Monitor view.
Click the Validate WS-I Message Log File icon (top right).
You are prompted for the location to store the log file. Select the WebContent
folder, for example.
The log file is saved and validated; error messages are shown in the Tasks
view.
Chapter 15. WebSphere Studio Application Developer
283
Figure 15-25 Validate SOAP messages for WSI-I compliance in TCP/IP Monitor
For example, when validating the SOAP messages sent by the DB2 DADX Web
service (in ItsoWebService5WebClient), you get the error message shown in
Figure 15-26.
Figure 15-26 SOAP message validation error
The Tasks view shows this error message:
A child of the soap:Body element has a soap:encodingStyle attribute
The log file that is produced by the TCP/IP Monitor is an XML file, by default
named log.wsimsg. The log file contains <messageEntry> tags for each input and
output message with <messageContent> and <httpHeaders> tags containing the
full SOAP message and HTTP headers.
Conclusion: Application Developer makes WS-I compliance easy by
providing the tools required for generation of WS-I compliant Web services
and for validating the generated code and runtime SOAP messages.
284
WebSphere Version 5.1 Web Services Handbook
Creating a Web service from a URL
The purpose of a URL Web service is to provide a mechanism to easily
incorporate remotely running servlets into a client application, which can further
process the markup generated by the servlet.
The Application Developer wizard generates a Web service and optionally a
client proxy from an existing servlet, which can be located anywhere on the Web.
During that process, the implementer can specify the syntax of the servlet
parameters.
We provide a servlet named WeatherForecastServlet that executes the same
functions as the WeatherForecast JavaBean. We import this servlet into a new
Web project named ItsoWebService5Web and then turn it into a Web service.
Importing the servlet
To create the servlet and import the existing code into the Web project:
Import the ItsoWebService5 enterprise application provided in:
sg246891-01\sampcode\wsad51\URL\ItsoWebService5.ear
This creates an enterprise application (ItsoWebService5) with a Web project
(ItsoWebService5Web).
Study the content of the ItsoWebService5Web project. It contains the
WeatherForecastServlet, and supporting classes (WeatherPredictor and
Weather).
Study the WeatherForecastServlet. The servlet accepts one parameter
called method, with values day, week, or weektemp, to invoke the three functions
of the weather forecast application.
Note: Ignore the WEB-INF\databases folder; it will be used in “Creating a Web
service from DADX” on page 290.
Creating a server
We could add the ItsoWebService5 enterprise application to the WeatherServer,
but that server is already heavily loaded with data source and JMS.
It is much easier to create a new Version 5 server, WeatherServletServer. This
new server does not require any configuration. Create the server and add the
ItsoWebService5 enterprise application.
Chapter 15. WebSphere Studio Application Developer
285
Running the servlet
Start the WeatherServletServer and test the servlet using the URL:
http://localhost:9080/ItsoWebService5Web/WeatherForecastServlet
Tip: You can run the servlet by selecting the WeatherForecastServlet.java
file and Run on Server (context).
Figure 15-27 shows a sample run of the servlet.
Figure 15-27 Weather forecast servlet sample run
You can also invoke one of the methods directly with the URL:
http://localhost:9080/ItsoWebService5Web/WeatherForecastServlet?method=day
Note that this servlet does not query the database for weather information, but
instead used a random number generator for simplicity.
Creating the URL Web service for the servlet
To create a Web service that can access the three functions of the servlet we run
the Web services wizard:
Select File -> New -> Other -> Web Services -> Web Service and click Next.
Select URL Web Service as the service type, and select Start Web service in
Web project, Generate a proxy, and Test the generated proxy. Do not select
Test the Web service. Click Next.
286
WebSphere Version 5.1 Web Services Handbook
Make sure to select ItsoWebService5Web as the Web project and
ItsoWebService5WebClient as the Client Web project (this project will be
created). Click Next. Click Ignore for the WS-I compliance warning.
In the Web Service URL page, one icon named NewURLWebService is
displayed (Figure 15-28). Starting from this icon we have to build the URL and
parameters to invoke the servlet.
Figure 15-28 URL Web services wizard: Start
Select the NewURLWebService and Properties (context), replace
NewURLWebService with WeatherForecastServlet in all fields, and click OK
(Figure 15-29).
Figure 15-29 URL Web services wizard: Service properties
Select the WeatherForecastServlet and Add Port, expand the service, and a
NewPort is displayed.
Select the NewPort and Properties. Change the name to WeatherPort, the
HTTP address to http://localhost:9080/, accept the default HTTP method
as Get, and click OK.
Chapter 15. WebSphere Studio Application Developer
287
Select the WeatherPort and Add Operation, expand, and a NewOperation is
displayed.
Select the NewOperation and Properties. Enter forecast as the name,
ItsoWebService5Web/WeatherForecastServlet as the URI location, and click
OK.
Select forecast and Add Parameter, expand, and Return and NewParameter
are displayed.
Select the NewParameter and Properties. Enter method as the name, leave the
namespace and type, and click OK.
Select the Return and Properties, change the mime type from mimeXML to
text/plain:
– text/plain—The servlets returns HTML.
– text/xml—The servlet returns valid XML (this could be HTML with
properly nested matching begin/end tags); the proxy only returns the first
text element.
– mimeXML—Same as text/xml.
Note: A DOM element of the complete XML should be returned for
text/xml, but the proxy currently only returns the first text element.
Figure 15-30 shows the final tree.
Figure 15-30 URL Web services wizard: Final tree
Click Next to go through the pages of the wizard. Accept all the defaults.
Click Finish and wait while the wizard generates the code and starts the
server.
288
WebSphere Version 5.1 Web Services Handbook
Note that no Web service is created in the ItsoWebService5Web project. The
servlet itself is the Web service and it will be invoked directly using the URL we
specified in the wizard.
Let us take a look at the generated files:
Two WSDL files are generated in the ItsoWebService5Web project into
WebContent/wsdl:
WeatherForecastServletBinding.wsdl
WeatherForecastServletService.wsdl
<=== binding and interface
<=== implementation
A proxy named proxy.httpget.WeatherForecastServletProxy is generated in
the ItsoWebService5WebClient project.
When you open the proxy class, you can see that the servlet is invoked
directly using HTTP-GET; SOAP is not involved.
Web service sample JSPs are generated into the folder
WebContent/sample/WeatherForecastServlet.
Testing the URL Web service
The sample test client should have started automatically; otherwise, select the
sample/WeatherForecastServlet/TestClient.jsp file and Run on Server:
In the Methods pane select the forecast method. Enter day, week, or weektemp
and select Invoke. Figure 15-31 shows the generated HTML markup as the result
of the invocation of the servlet with day as the parameter.
Figure 15-31 URL Web service invocation
Chapter 15. WebSphere Studio Application Developer
289
Creating a Web service from DADX
A document access definition extension (DADX) Web service enables you to
wrap a DB2 XML Extender document access definition (DAD), an SQL
statement, or a stored procedure call as a Web service.
DADX is an XML document that is used by the Web Service Object Runtime
Facility (WORF) that comes with DB2. WORF executes the SQL statement (or
DAD file or stored procedure) and returns the output in XML as a Web service
result.
WORF comes with Application Developer and with DB2 Version 8.1; it can be
downloaded for free for DB2 Version 7.2.
DADX group
Multiple DADX files are stored in a DADX group. A DADX group is a folder with
DADX files and a group.properties file that specifies the connection information
for the DB2 database (JDBC driver or data source). WORF provides a servlet
(DxxInvoker) that is mapped to all the requests of a group.
Creating a Web service from an SQL statement
To create DB2 Web services, you can either directly use WORF and a text editor
or you can use the wizard that comes with Application Developer.
The following steps have to be performed:
Create an SQL statement.
Create a DADX group.
Create a DADX file from the SQL statement.
Create a Web service from the DADX file.
We provide the SQL statement for the DADX Web service in the
ItsoWebService5 enterprise application. Import the application if not already
done so for the URL Web service.
Create an SQL statement
Application Developer provides a wizard to create an SQL statement. Refer to
the WebSphere Studio Application Developer Version 5 Programming Guide,
SG24-6957, for details on how to create an SQL statement.
In short, select the ItsoWebService5Web project and New -> Other -> Data ->
SQL Statement. Then select Create an SQL resource and invoke the SQL
Builder. Create a database connection and name the statement GoodWeather.
290
WebSphere Version 5.1 Web Services Handbook
To make it easy, we provide the WEATHER_GoodWeather.sqx SQL statement in the
WEB-INF\databases folder:
SELECT ITSO.SANJOSE.WINDSPEED, ITSO.SANJOSE.TEMPERATURE,
ITSO.SANJOSE.WINDDIR, ITSO.SANJOSE.CONDITION, ITSO.SANJOSE.WEATHERDATE
FROM ITSO.SANJOSE
WHERE
ITSO.SANJOSE.TEMPERATURE > :temp AND ITSO.SANJOSE.WINDSPEED < :wind
ORDER BY TEMPERATURE DESC
You may have to tailor the ConWEATHER.comxmi connection file with the correct
location of the db2java.zip file, or recreate a ConWEATHER connection.
Create a DADX group
To create a DADX group:
Select File -> New -> Web Services -> Web Services DADX Group
Configuration.
Select the ItsoWebService5Web project and click Add group. Name the group
WeatherGroup.
Select the group and click Group properties. Complete the dialog as shown in
Figure 15-32.
To use a data source, set the
context factory to:
com.ibm.websphere.naming.
WsnInitialContextFactory
And the data source to:
jdbc/sjweather
Then you have to configure the
server with the data source.
Figure 15-32 DADX group properties
Click Finish to create the group under JavaSource.
Chapter 15. WebSphere Studio Application Developer
291
Creating a DADX file
To create the DADX file from the SQL statement:
Select File -> New -> Web Services -> DADX File.
Select the GoodWeather SQL statement under ItsoWebService5Web (expand
WebContent/WEB-INF/databases/WEATHER/Statements).
Click Next twice. Enter GoodWeather.dadx as the statement name and set the
output folder to /ItsoWebService5Web/JavaSource/groups/WeatherGroup.
Click Finish. The GoodWeather.dadx file opens in the editor (Example 15-2).
Example 15-2 DADX file
<?xml version="1.0" encoding="UTF-8"?>
<dadx:DADX xmlns:dadx="http://schemas.ibm.com/db2/dxx/dadx"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xsi:schemaLocation="http://schemas.ibm.com/db2/dxx/dadx dadx.xsd">
<dadx:operation name="GoodWeather">
<dadx:documentation xmlns="http://www.w3.org/1999/xhtml">
<![CDATA[
]]>
</dadx:documentation>
<dadx:query>
<dadx:SQL_query>
<![CDATA[
SELECT ITSO.SANJOSE.WINDSPEED, ITSO.SANJOSE.TEMPERATURE,
ITSO.SANJOSE.WINDDIR, ITSO.SANJOSE.CONDITION, ITSO.SANJOSE.WEATHERDATE FROM
ITSO.SANJOSE WHERE ITSO.SANJOSE.TEMPERATURE > :temp AND ITSO.SANJOSE.WINDSPEED
< :wind ORDER BY TEMPERATURE DESC
]]>
</dadx:SQL_query>
<dadx:parameter name="temp" type="xsd:int"/>
<dadx:parameter name="wind" type="xsd:int"/>
</dadx:query>
</dadx:operation>
</dadx:DADX>
Notice the SQL statement and the parameter definitions.
Create the Web service
To generate the Web service we use the Web Services wizard:
Select the GoodWeather.dadx file and New -> Web Services -> Web Service.
The DADX Web Service type is preselected. Select Start the Web service,
Generate a proxy, and Test the generated proxy.
292
WebSphere Version 5.1 Web Services Handbook
Make sure the projects are ItsoWebService5Web and
ItsoWebService5WebClient.
Go through the pages, accept all the defaults (soap binding), and click Finish.
Testing the Web service
The test client opens automatically. Notice that two methods are generated in the
proxy:
GoodWeather_—Returns a DOM element (the test client generates XML from
the DOM element).
GodoWeather—Returns an object (GoodWeatherResultElement) that contains
row objects.
A sample run is shown in Figure 15-33.
Figure 15-33 DADX Web service result
Note: You may have to restart the ItsoWebService5 project in the server.
Chapter 15. WebSphere Studio Application Developer
293
A WORF test client is also generated. To run the WORF test client enter this URL
into a browser window and play with the different functions:
http://localhost:9080/ItsoWebService5Web/WeatherGroup/GoodWeather.dadx/TEST
A sample run is shown in Figure 15-34. You can also generate WSDL and XML
Schema files using the WORF runtime.
Figure 15-34 DADX Web service WORF client
DADX Web services use the “old” SOAP engine (Apache SOAP 2.3). Running
such Web services require:
A deployment descriptor file, dds.xml, in WebContent
A SOAP configuration file, soap.xml
A number of runtime files (in lib and in the classpath)
An admin folder (in WebContent) to administer the deployed services (select
the index.html file and Run on Server)
294
WebSphere Version 5.1 Web Services Handbook
For the WORF runtime, these definition and files are created:
A servlet, WeatherGroup, configured in web.xml, pointing to:
com.ibm.etools.webservice.rt.dxx.servlet.DxxInvoker
A worf folder with the WORF test client
Publishing and exploring a UDDI registry
In this section we describe how to use the built-in features of Application
Developer to publish the recently generated Web service and how to import
services listed in a UDDI registry.
Application Developer provides the Web Services Explorer tool—also called the
UDDI Explorer—that enables you to publish and maintain your business entity,
business services, and service interfaces. We do not describe UDDI basics here
because they are presented in detail in Chapter 6, “Introduction to UDDI” on
page 99.
In this section we show:
How to create a business entity at a UDDI registry. The business entity
contains information about the business, for example, contact information and
URLs.
How to publish a Web service to a UDDI registry.
How to access a Web service with the Web Services Explorer. A complete
scenario, where a Web service is invoked dynamically using UDDI4J, is
presented in Chapter 19, “Web services scenario: Architecture and
implementation” on page 429.
Before you work with a UDDI registry, you must get an ID and password for that
registry. To register with the IBM test registry, use a Web browser and enter:
http://www.ibm.com/services/uddi
Click the icon for the UDDI V2 Business Test Registry and follow the link Get an
IBM user ID and password. The procedure for getting this user ID and password
is asynchronous now. After filling in the online request for a user ID, you will get
an e-mail (to the address specified in the request form). In this e-mail you will be
sent a URL, which will need to be copied and pasted into a Web browser to
complete the registration. Remember, without completing this registration, some
of the next steps in this exercise will not work.
Chapter 15. WebSphere Studio Application Developer
295
Publishing a business entity
The IBM test registry allows only one business entity to be published per user ID.
If you have previously published a business entity to the test registry, you can
either remove the existing business entity, or publish the WeatherForecast
service using your existing business entity.
Web Services Explorer
The Web Services Explorer can be launched from the Web Services wizard
described earlier in this chapter. It can also be started anytime by clicking the
Launch Web Services Explorer icon ( ) on the main toolbar of Application
Developer or by selecting Run -> Launch the Web Services Explorer.
Once you have started the Web Services Explorer, perform these steps:
In the Navigator pane, select the UDDI Main node.
In the Actions pane, IBM UDDI Test Registry appears in the Registry Name
field. Click Go.
Figure 15-35 shows the status of the Web Services Explorer.
Figure 15-35 Web Services Explorer ready to enter the business entity
In the toolbar of the Actions pane, click the Publish icon (
296
WebSphere Version 5.1 Web Services Handbook
).
Select Business in the Publish list, Simple for the format, and keep the default
URL. Enter your user ID, password, business name, and a description of your
business entity in the respective fields. Click Go.
The IBM Web Services Explorer is automatically updated with your published
business entity.
Discovering business entities
To discover your business entity or any other business entities using the Web
Services Explorer, perform these steps:
In the Navigator pane, select the IBM UDDI Test Registry node.
In the toolbar of the Actions pane, click the Find icon (
):
– For the Name of this query, you can enter any name that you can
associate with the search you are currently performing.
– In the Search For drop-down list select Businesses.
– For Type of Search select Simple.
– In the Name field enter the name of your business entity.
– Click Go.
A search for ITSO WS% finds three businesses that were added for this
publication (Figure 15-36) and potentially business from other people.
Figure 15-36 Web Services Explorer search
Chapter 15. WebSphere Studio Application Developer
297
Select a business to retrieve detailed information about that business entity.
With proper authorization (user ID and password), you can also update the
information.
Publishing the weather forecast Web service
Once you have found your business entity in the UDDI, you can publish a Web
service using the Web Services Explorer:
Make sure that the WeatherServer is started (the server that runs the service
you want to publish).
In the Navigator pane, select your business entity under the Published
Businesses folder or after executing a query to find the business.
In the toolbar of the Actions pane, click the Publish Service icon (
):
– For the Publication Format, select Simple.
– Enter your user ID and password.
– To enter the WSDL URL, click Browse. In the window, select Web Projects
as the source for the WSDL, select the ItsoWebService5Web project, then
select the correct WSDL file, and click Go:
http://localhost:9080/ItsoWebService1Web/wsdl/itso/bean
/WeatherForecast.wsdl
Note: Because we are using the WebSphere test environment, no
concrete IP address but localhost is used. For this example, we did not
run into difficulties retrieving the service, because this action is also
done on the same machine (the WebSphere server must be running).
For distributed scenarios, the host name can be changed here, but it
can also be changed easily after publication in the registry.
298
WebSphere Version 5.1 Web Services Handbook
– Back in the Web Services Explorer window, in the Name field of the
Actions pane, type WeatherForecast.
– In the Description field of the Actions pane, type a description that helps
you identify the service more easily, because there is a chance that some
other forecasts have been published before. Figure 15-37 shows the
completed Actions pane.
– When you have finished entering the service information, click Go.
Figure 15-37 A Web service ready to be published
The Web Services Explorer is automatically updated with your published Web
service. If the update is successful, the Status pane displays:
IWAB0160I Service interface http://bean.itso was successfully published.
IWAB0159I Service WeatherForecast was successfully published.
Discovering the weather forecast Web service
Finally, we show how the Web Services Explorer can be used to find Web
services in the registry. We cover here only the static case. Chapter 19, “Web
services scenario: Architecture and implementation” on page 429, shows how to
dynamically access a UDDI registry.
Chapter 15. WebSphere Studio Application Developer
299
There are several ways to search for a Web service. You can discover a Web
service by searching for a business entity, business service, or service interface.
Here is how to search directly for the name of the service:
Start the Web Services Explorer icon on the main toolbar.
In the Web Services Explorer toolbar, select the Favorites icon (
).
Expand Favorite UDDI Registries. Here you can choose any registry you want
to browse. Because we have published our Web service on the IBM UDDI test
registry, click IBM UDDI Test Registry.
In the Actions toolbar, click the Add to UDDI Page icon (
).
In the Actions toolbar, click the Find icon:
– Select Services in the Search for box.
– Select Advanced for type of search (there are more than 10 services with
the name WeatherForecast in the test registry).
– Click Add for Names and enter WeatherForecast.
– Enter 50 for Maximum number of results.
– Click Go.
Figure 15-38 shows the results of the search. Because we have an
informative description, we can easily identify our previously published Web
service.
Click the service of your choice. Now you can modify information or even
unpublish it, if you have the rights.
You can download the WSDL file by clicking the Import WSDL to file system
icon (
), or even import it directly to the Application Developer Workbench.
Click the Import WSDL to workbench icon (
).
Select one of the projects in your Workbench and a file name for the new
WSDL document and click Go. If the import was successful, you get a
successful confirmation message. You can find the imported file in the
selected project.
Once you have accessed the WSDL document, you can start to build a Web
service from the top down, as described in “Creating a Web service top-down
from WSDL” on page 279.
300
WebSphere Version 5.1 Web Services Handbook
Figure 15-38 Results of a UDDI query on weather forecast
Deployment of the sample applications
To deploy the application means to export an EAR file from Application
Developer and install the enterprise application in an Application Server.
Exporting the EAR file and installing the enterprise application
To export an EAR file, select the ItsoWebServiceX project and Export (context).
Select EAR file as the destination and click Next.
Click Browse to locate the target directory. By default the output file is named
ItsoWebServiceX.ear. For WebSphere, the target location is usually the
installableApps directory (C:\WebSphere\AppServer\installableApps).
Installation of enterprise applications into a WebSphere Application Server is
covered in Chapter 20, “Web services runtime and deployment in WebSphere”
on page 479.
Chapter 15. WebSphere Studio Application Developer
301
Summary
In this chapter we have provided two Web services generation walk-throughs
using Application Developer.
First we generated a Web service for a given server-side application (JavaBean),
the corresponding WSDL documents, and the client code. We also tested the
Web service and traced the SOAP messages. We also developed a client
application that uses the Web service.
We repeated the process for a session EJB and generated both an HTTP Web
service and a SOAP over JMS Web service.
Then we took a WSDL document and generated the server-side skeleton code
for a new Web service.
We took a short look at Web services interoperability (WS-I) and the Application
Developer tooling that can be used for WS-I compliance.
We described how to generate a URL Web service and a DADX Web service.
Finally, we discussed how to publish a service to a UDDI registry and how to
incorporate services from a UDDI registry.
More Information
The IBM Redbook Web Services Wizardry with WebSphere Studio Application
Developer, SG24-6292, also provides insight into the tools provided by
Application Developer. However, that book refers to Application Developer
Version 4, where a number of changes apply.
The IBM Redbook WebSphere Studio Application Developer Version 5
Programming Guide, SG24-6957, provides detailed information about using
Application Developer, not only on Web services issues.
The IBM Redbook Integrating Your Information, SG24-6892, gives detailed
information on how to create Web services from DB2 SQL queries.
Also, the online help that comes with WebSphere Studio Application Developer
provides information and tutorials for creating and using Web services.
302
WebSphere Version 5.1 Web Services Handbook
16
Chapter 16.
Web services security with
Application Developer
This chapter describes the functionality offered by WebSphere Studio Application
Developer Version 5.1 to secure Web services following the Web services
security specification (refer to Chapter 11, “Web services security” on page 185).
This chapter does not teach any basic feature of Application Developer 5.1; refer
to Chapter 15, “WebSphere Studio Application Developer” on page 247, to
understand the creation of Web services. This chapter concentrates on the
supporting features provided by Application Developer 5.1 to apply
authentication, integrity, and confidentiality to Web services.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
303
Overview
The security that we apply in this chapter to Web services is purely SOAP
message security. This means that the security is an integrated part of the SOAP
message and travels with the message, making this kind of security platform and
transport independent. It applies to SOAP over HTTP or SOAP over JMS.
This security is based on:
XML digital signature—Provides message integrity
XML encryption—Provides message confidentiality
Security tokens—Provides message authentication
Architecture and deployment model
The security is implemented using system handlers. These system handlers are
registered to different parts of a Web service. Figure 16-1 shows the handlers
and their responsibilities.
Decrypt message
Digital Signature validation
Security Token validation and setup security context
Security Token generation
Digital Signature generation
Encrypt message
Client
2
1
Request
App.
client
Request
Security Handlers
SOAP message =
WS-Security headers +
body content
Security Handlers
J2EE
container
Response
Response
4
Configuration DD
and service
bindings
Server
Decrypt message
Digital Signature
validation
3
Digital Signature
generation
Encrypt message
webservicesclient.xml
Configuration DD
and service
bindings
webservices.xml
Figure 16-1 Web services message security architecture
The message follows these steps:
1. At the client side, the request security handler is used to generate the
required security headers in the SOAP message before the SOAP message
304
WebSphere Version 5.1 Web Services Handbook
is sent out to the server. These security constraints are defined in the client
configuration deployment descriptor.
2. At the server side, the request security handler is invoked to check that the
SOAP message complies with all the security constraints specified by the
server deployment descriptors prior to dispatching the message to the Web
service implementation.
3. At the server side, the response security handler is invoked to generate the
SOAP security header information before the message is sent back to the
client. The nature of that information is also specified in the server
deployment descriptors.
4. At the client side, the response security handler is called to manage the
SOAP message security information to know whether the message complies
with the client deployment descriptor specifications before the message is
passed to the client implementation.
Therefore, the security constraints specified by the server and client must match,
allowing both sides to understand each other (Figure 16-2).
matching
matching
ibm-webservicesclient-ext.xmi
securityResponseReceiverServiceConfig
securityRequestReceiverServiceConfig
securityRequestSenderServiceConfig
securityResponseSenderServiceConfig
ibm-webservices-ext.xmi
ibm-webservicesclient-bnd.xmi
securityResponseReceiverBindingConfig
securityRequestReceiverBindingConfig
securityRequestSenderBindingConfig
securityResponseSenderBindingConfig
ibm-webservices-bnd.xmi
Figure 16-2 Value compatibility between client and server deployment descriptor
The security requirements are specified in the deployment descriptors of the
Web service or client. The assembler role is responsible for the definition of that
information. Currently, there is no standard deployment model for Web services
security. IBM uses these deployment descriptors for the server and client:
ibm-webservices-ext.xmi—Defines the security constraints to apply
ibm-webservices-bnd.xmi—Defines how to apply these constraints
ibm-webservicesclient-ext.xmi—Defines the security constraints to apply
ibm-webservicesclient-bnd.xmi—Defines how to apply these constraints
Chapter 16. Web services security with Application Developer
305
The IBM deployment descriptor extensions and bindings are associated with
each EJB module or Web module where the Web service server or client resides.
Some of the binding information could be shared among various applications. To
provide this capability, IBM defines some default elements at the server level in
the ws-security.xml file, where elements such as key locators, trust anchors,
certificates, and so forth are declared to be referenced from EJB or Web
modules. When the same elements are defined at the application level, they have
priority over the global definitions.
Application Developer 5.1 provides an editor to graphically modify the
deployment descriptor files. The editor functionality is exactly the same for client
and server. Figure 16-3 shows the editors for the client side.
ibm-webservicesclient-bnd.xmi
ibm-webservicesclient-bnd.xmi
-
HOW TO DO
ibm-webservicesclient-ext.xmi
WHAT TO DO
Figure 16-3 Editors to modify the security deployment descriptors
When the requirements of the security constraints are not satisfied for a SOAP
message, a SOAP fault response, as defined in the SOAP specification, is sent
to the requester. This behavior is perfectly valid when no security constraints are
applied to the server answer.
306
WebSphere Version 5.1 Web Services Handbook
If any security information is required in the server response, the client receives
the fault fired by its own response handler. This handler generates a new SOAP
fault with the lack of security information received by the server response.
Although the original fault usually accompanies the message, we have lost the
security constraints. Figure 16-4 shows this inappropriate behavior.
Server
Client
SOAP message =
WS-Security headers +
body content
Request
App.
client
Security Handlers
1
Request
Security Handlers
2
Response
J2EE
container
SOAP Fault
No WS-Security headers
4
3
Configuration DD
and service
bindings
Generate a SOAP
security Fault
Configuration DD
and service
bindings
Figure 16-4 SOAP message flow with a SOAP fault error in the server
The steps are:
1. The client request handler generates the security information filling the
header of the SOAP message.
2. The server request handler validates the security information provided by the
client. If this information does not match the requirements, a SOAP fault
message is sent to the client. This message is sent without passing through
the server response handler. Therefore, there is no security header in the
SOAP message sent to the client. The same behavior is applied when an
error occurs in the Web service implementation.
3. The client response handler validates the security constraints, but there is
nothing to validate because the security constraints do not come with the
SOAP fault message. Consequently, the client response handler generates a
new SOAP fault message to inform about the security fault in the incoming
message. That message fault usually includes the original fault fired in the
server. On the other hand, the security constraints are lost in the response
message; no integrity and no confidentiality.
4. The client processes the SOAP fault message, obtaining as the primary error
the one generated by its response handler and as the secondary error the
real one. Therefore, the client does not have any mechanism to know if the
message has been modified in its travel.
Chapter 16. Web services security with Application Developer
307
Securing Web services
In this section we illustrate with an example how we can protect a Web service
with authentication, integrity, and confidentiality using WebSphere Studio
Application Developer.
We start from the EJB-based Web service created in “Creating a Web service
from a session bean” on page 271. We provide a copy of the ItsoWebService2
enterprise application as ItsoWebService6 to implement security.
Import the ItsoWebService6 enterprise application from the file:
sg246891-01\sampcode\wsad51security\start\ItsoWebService6.ear
This creates the ItsoWebService6EJB, ItsoWebService6RouterWeb, and
ItsoWebService6EJBClient projects.
Open the Properties of the ItsoWebService6RouterWeb project. On the Java
Build Path, Libraries page, click Add Variable, select the WAS_50_PLUGINDIR,
click Extend, and add the lib\webservices.jar file to the classpath.
Add the ItsoWebService6 application to the WeatherServer. To limit the
number of projects loaded, remove all other applications from the server. You
can start the server and run the test client (in ItsoWebService6EJBClient).
Implementing security
The three security constraints that can be applied to Web services are:
Authentication—Using security tokens
Integrity—Using XML digital signature
Confidentiality—Using XML encryption
Note: Although Application Developer can generate a client with security, it
forces the user to choose one type of security (integrity or confidentiality), and
only one. However, Application Developer does not allow the user to define to
what part of the message and how security is applied.
Consequently, if that limited option does not satisfy the requirements, the user
has to remove the security features generated, which is more work than
making a simple change in the client code.
The security option is specified in the proxy page of the client creation (see
Figure 15-6 on page 257), where you can choose between XML Digital
Signature and XML Encryption.
308
WebSphere Version 5.1 Web Services Handbook
Authentication
The authentication process creates a security token in a SOAP message. This
security token is inserted in the message, authenticating the caller. Web services
security offers these possibilities to provide a security token:
Basic authentication
Includes user name and password information, and
generates <wsse:UsernameToken> with
<wsse:Username> and <wsse:Password>
Signature
Includes an X.509 certificate and generates
<ds:Signature> with <wsse:BinarySecurityToken>
ID assertion
Includes a user name and generates
<wsse:UsernameToken> with <wsse:Username>
LTPA
Includes a Light-weight Third Party Authentication
(LTPA) token and generates <wsse:UsernameToken>
with <wsse:Username>
Custom
Includes a custom-defined token
Figure 16-5 shows the architecture diagram of how a security token is generated.
Callback Handler
Configuration
Security Token
JAAS Login
Callback Handler
Configuration
1
Security
SecurityToken
Tokengeneration
generation
3
Security Token
Security Token validation
Set security context
JAAS Subject
Server
Client
2
Request
App.
client
Security Handlers
Request
SOAP message =
WS-Security headers +
body content
Response
Configuration DD
and service
bindings
Security Handlers
J2EE
container
Response
Configuration DD
and service
bindings
Figure 16-5 Security token generation architecture
Chapter 16. Web services security with Application Developer
309
The complete process for the authentication of the client is:
1. The client security request handler uses a callback handler to generate the
security token. This security token is inserted in the SOAP message.
2. The SOAP message is sent to the server.
3. The server security request handler takes the information from the SOAP
message and validates it using a JAAS login module. If the validation is
successful, a JAAS subject is returned; if not, a SOAP fault exception is
generated.
Defining client authentication
The definition of the authentication is performed using of the Web service
deployment descriptor editor. Expand ItsoWebService6EJBClient -> WebContent
-> WEB-INF, open the webservicesclient.xml file using the Web Services Client
Editor, and select the Security Extensions page (Figure 16-6).
Figure 16-6 Web service client security extensions
310
WebSphere Version 5.1 Web Services Handbook
Select the WeatherForecastEJB port binding to apply the security constrictions to
that port. Under Request Sender Configuration, expand Login Config. The
available choices are:
BasicAuth
IDAssertion
Signature
LTPA (Application Developer 5.1.1)
We use basic authentication for our example. Select BasicAuth for the
authentication method and save. This selection produces the inclusion of that
information in the ibm-webservicesclient-ext.xmi file:
<securityRequestSenderServiceConfig>
<loginConfig authMethod="BasicAuth"/>
</securityRequestSenderServiceConfig>
Now we have to define the callback handler responsible for inserting the security
token in the SOAP message.
On the Port Binding page select the WeatherForecastEJB port under Port
Qualified Name Binding. Expand Security Request Sender Binding
Configuration and Login Binding and click Enable. The login dialog opens
(Figure 16-7).
Figure 16-7 Login binding dialog
Chapter 16. Web services security with Application Developer
311
In the dialog:
Select BasicAuth as Authentication method.
Enter com.ibm.wsspi.wssecurity.auth.callback.NonPromptCallbackHandler
as Callback handler to provide the user ID and password hardcoded in the
binding file. Other possibilities are:
– com.ibm.wsspi.wssecurity.auth.callback.GUIPromptCallbackHandler to
prompt for user ID and password in standard input
– com.ibm.wsspi.wssecurity.auth.callback.StdinPromptCallbackHandler
to prompt for user ID and password in a GUI panel
– com.ibm.wsspi.wssecurity.auth.callback.GUIPromptCallbackHandler
to generate LTPA token as binary security
Enter a valid user ID and password for the security environment.
Click OK and save.
This callback handler definition produces the inclusion of the method type, the
class of the callback handler, and the user name and password in the
ibm-webservicesclient-bnd.xmi file:
<securityRequestSenderBindingConfig>
<loginBinding authMethod="BasicAuth" callbackHandler=
"com.ibm.wsspi.wssecurity.auth.callback.NonPromptCallbackHandler">
<basicAuth userid="db2admin" password="{xor}Oz1tPjsyNjFp"/>
</loginBinding>
</securityRequestSenderBindingConfig>
Defining server authentication
Once the client is configured, we have to configure the server to match both
configurations. Expand ItsoWebService6EJB -> ejbModule -> META-INF, open the
webservices.xml file using the Web Services Editor, and select the Security
Extensions page.
Select the WeatherForecastEJB port to apply the security constraints to that port.
Under Request Receiver Service Configuration Details, expand Login Config and
click Add. In the Add Authentication Dialog (Figure 16-8) select BasicAuth and
click OK.
The dialog has
more fields in
Version 5.1.1.
Figure 16-8 Add authentication dialog
312
WebSphere Version 5.1 Web Services Handbook
The available choices are the same as for the client: BasicAuth, IDAssertion,
Signature, and LTPA.
The ibm-webservices-ext.xmi file is modified with:
<securityRequestReceiverServiceConfig >
<loginConfig>
<authMethods text="BasicAuth"/>
</loginConfig>
</securityRequestReceiverServiceConfig>
We have to define the callback handler responsible for processing the incoming
authentication using the JAAS login configuration, which is responsible for user
validation:
On the Binding Configurations page select the WeatherForecastEJB port.
Expand Request Receiver Binding Configuration Details and Login Mapping,
and click Add. The login mapping dialog opens (Figure 16-9).
The dialog
has more
fields in
Version 5.1.1.
Figure 16-9 Login mapping dialog
In the dialog:
Select BasicAuth as Authentication method.
Enter WSLogin as Configuration name and
com.ibm.wsspi.wssecurity.auth.callback.WSCallbackHandlerFactoryImpl
as Callback Handler Factory Class name.
Click OK and save.
The login mapping definition produces the following changes in the
ibm-webservices-bnd.xmi file:
<securityRequestReceiverBindingConfig>
<loginMappings authMethod="BasicAuth" configName="WSLogin">
<callbackHandlerFactory classname=
Chapter 16. Web services security with Application Developer
313
"com.ibm.wsspi.wssecurity.auth.callback.WSCallbackHandlerFactoryImpl"
/>
</loginMappings>
</securityRequestReceiverBindingConfig>
Testing authentication
To test the authentication that we configured, we have to change the server
configuration. We secure the server where the Web service and client will run,
using local OS security:
Open the WeatherServer configuration. On the Security page, select Enable
Security, enter a valid user ID and password for the local OS (Figure 16-10),
and save.
Figure 16-10 Setting Local OS security
Create a TCP/IP Monitoring Server if you have not done so already (see
“Using the TCP/IP Monitoring server” on page 269).
Modify the URI of the Web service in the WeatherForecastEJBServiceLocator
class in the ItsowebService6EJBClient project (JavaSource\itso.session)
and set the port to 9081:
http://localhost:9081/ItsoWebService6RouterWeb/services/WeatherForecastEJB
In addition, we can include a Web service security trace in the WeatherServer
configuration on the Trace page:
Select Enable trace and enter this single line as the Trace string:
com.ibm.xml.soapsec.*=all=enabled:com.ibm.ws.webservices.*=all=enabled:com.
ibm.wsspi.wssecurity.*=all=enabled:com.ibm.ws.security.*=all=enabled:SASRas
=all=enabled
314
WebSphere Version 5.1 Web Services Handbook
Container-managed client
In Application Developer 5.1.1 the WeatherForecastEJBProxy uses JNDI by
default to acquire the service locator and no change is required to support Web
services security.
Note: In Application Developer 5.1 the result.jsp instantiates the service
locator. This does not work with security enabled and must be manually
changed to use JNDI. Sample code would be:
<%
itso.session.WeatherForecastEJB WeatherForecastEJBid =
(itso.session.WeatherForecastEJB)session.getAttribute
("itso.session.WeatherForecastEJB");
if(WeatherForecastEJBid == null){
// Get initial context and the local representation of the Web Service
javax.naming.InitialContext ic = new javax.naming.InitialContext();
itso.session.WeatherForecastEJBServiceLocator weatherEJBLocator =
(itso.session.WeatherForecastEJBServiceLocator)
ic.lookup("java:comp/env/service/WeatherForecastEJBService");
WeatherForecastEJBid = weatherEJBLocator.getWeatherForecastEJB();
session.setAttribute("itso.session.WeatherForecastEJB",
WeatherForecastEJBid);
}
%>
Starting the servers
Start the TCP/IP Monitor and the WeatherServer. Select the Testclient.jsp (in
ItsoWebService6EJBClient\WebContent\sample) and Run on Server, select the
getDayForecast method, enter a date, and click Invoke.
We see in the TCP/IP Monitor view the SOAP messages, and how the security
authentication is included in the header of the SOAP message. Example 16-1
and Example 16-2 show the SOAP messages sent by the client and server,
respectively.
Example 16-1 Message sent by the client with authentication
<soapenv:Envelope ....">
<soapenv:Header>
<wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2003/06/secext"
soapenv:mustUnderstand="1">
<wsse:UsernameToken>
<wsse:Username>db2admin</wsse:Username>
<wsse:Password>xxxxxxxx</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
Chapter 16. Web services security with Application Developer
315
</soapenv:Header>
<soapenv:Body>
<getDayForecast xmlns="http://session.itso">
<theDate>2003-11-24T08:00:00.000Z</theDate>
</getDayForecast>
</soapenv:Body>
</soapenv:Envelope>
Example 16-2 Message response delivered by the server
<soapenv:Envelope ...>
<soapenv:Body>
<getDayForecastResponse xmlns="http://session.itso">
<getDayForecastReturn>
<condition xmlns="http://mapping.itso">sunny</condition>
<date xmlns="http://mapping.itso">2003-11-24T08:00:00.000Z</date>
<windDirection xmlns="http://mapping.itso">SE</windDirection>
<windSpeed xmlns="http://mapping.itso">31</windSpeed>
<temperatureCelsius xmlns="http://mapping.itso">38</temperatureCelsius>
<dbflag xmlns="http://mapping.itso">1</dbflag>
</getDayForecastReturn>
</getDayForecastResponse>
</soapenv:Body>
</soapenv:Envelope>
Integrity
The integrity process ensures that data has not been manipulated in an
unauthorized or accidental manner. By providing integrity to a SOAP message
we ensure the message content in a multi-hop environment, while SSL provides
integrity only in a one-hop scenario.
XML digital signature is the mechanism used to provide that integrity in a
multi-hop scenario. The signature appends information to a SOAP message that
ensured that the SOAP information has not been manipulated.
The different parts that can be digitally signed are:
Body
Security token
Timestamp
Defining client integrity
As we did for the authentication, we use the Web service deployment editor.
Open the webservicesclient.xml file (ItsoWebService6EJBClient) and select
the Security Extensions page.
316
WebSphere Version 5.1 Web Services Handbook
Select the WeatherForecastEJB port to apply security to that port. Under Request
Sender Configuration, expand Integrity. The available reference parts are:
body
timestamp
securitytoken
Click Add, select body, and click OK. Click Add again, select securitytoken, and
click OK (Figure 16-11, left).
We also want to receive the response from the server digitally signed. Under
Response Receiver Configuration, expand Required Integrity and add the body
reference part (Figure 16-11, right).
Figure 16-11 Integrity parts to digitally sign
Save the changes. These changes produce the inclusion of following information
in the ibm-webservicesclient-ext.xmi file:
<securityRequestSenderServiceConfig>
<integrity>
<references part="body"/>
<references part="securitytoken"/>
</integrity>
...
</securityRequestSenderServiceConfig>
<securityResponseReceiverServiceConfig>
<requiredIntegrity>
<references part="body"/>
</requiredIntegrity>
</securityResponseReceiverServiceConfig>
Chapter 16. Web services security with Application Developer
317
We have to provide the specific details of how these parts are digitally signed.
First, we have to create a key locator where the key is to digitally sign the
certificates is loaded:
On the Port Binding page select WeatherForecastEJB port. Expand Security
Request Sender Binding Configuration and Key Locators and click Add. The
key locator dialog opens (Figure 16-12).
Figure 16-12 Key locator dialog
In the dialog:
Enter SampleClientSignerKey as Key locator name.
Select com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator as Key
locator class.
Select Use key store.
Enter client as Key store storepass.
Enter ${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-sender.ks for
the Key store path.
Enter JKS as Key store type (overtype).
318
WebSphere Version 5.1 Web Services Handbook
Click Add under Key. Enter soaprequester as Alias, client as Key pass, and
clientsignerkey as Key name.
Click OK.
Note: In this book we use the sample certificates provided with WebSphere
Application Server 5.1. These certificates are already loaded and matched in
the application server with the names we enter in the example. We only
provide them as examples of how we can create our own key locators. Local
key locators have priority over global key locators with the same name.
Exploring a key store file using the keytool
Using the Java keytool we can see the content of the key store file:
In a DOS command window go to the directory of the dsig-sender.ks file:
<wsad-home>\runtimes\base_v51\etc\ws-security\samples
Run the command:
\wsad-home>\runtimes\base_v51\java\jre\bin\keytool
-list -keystore dsig-sender.ks -v
When prompted, provide the keystore password (client).
Example 16-3 shows the information contained in the key store. There is a
key entry called soaprequester with a certificate authority called soapca. That
is the reason to provide the soaprequester key in the key locator dialog.
Example 16-3 dsig-sender.ks key information
Keystore type: jks
Keystore provider: IBMJCE
Your keystore contains 2 entries:
Alias name: soaprequester
Creation date: Mon Oct 01 02:54:42 PDT 2001
Entry type: keyEntry
Certificate chain length: 3
....
*******************************************
*******************************************
Alias name: soapca
Creation date: Mon Oct 01 02:54:33 PDT 2001
Entry type: trustedCertEntry
....
Chapter 16. Web services security with Application Developer
319
Second, we have to specify the algorithm that we use to sign the information.
Expand Security Request Sender Binding Configuration and Signing Information
and click Enable. The Signing info dialog opens (Figure 16-13).
Figure 16-13 Signing info dialog client request
In the dialog:
Leave the default algorithm methods.
Enter clientsignerkey as the Signing key name.
Select SampleClientSignerKey as the Signing key locator.
Click OK.
Save the changes. The modifications in the ibm-webservicesclient-bnd.xmi file
are shown here:
<securityRequestSenderBindingConfig>
<signingInfo>
<signatureMethod algorithm=
"http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<signingKey name="clientsignerkey"
locatorRef="SampleClientSignerKey"/>
<canonicalizationMethod algorithm=
"http://www.w3.org/2001/10/xml-exc-c14n#"/>
<digestMethod algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
</signingInfo>
<keyLocators name="SampleClientSignerKey"
classname="com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator">
<keyStore storepass="{xor}PDM2OjEr"
path="${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-sender.ks"
type="JKS"/>
<keys alias="soaprequester" keypass="{xor}PDM2OjEr"
name="clientsignerkey"/>
</keyLocators>
.......
</securityRequestSenderBindingConfig>
320
WebSphere Version 5.1 Web Services Handbook
Third, we have to configure the signing information to receive the response from
the server. Expand Security Response Receiver Binding Configuration and
Signing Information and click Add. The signing info dialog opens (Figure 16-14).
Figure 16-14 Signing info dialog client receive
In the dialog:
Leave the default algorithm methods.
Select Use certificate path reference. Enter SampleClientTrustAnchor as the
Trust anchor reference and SampleCollectionCertStore as the Certificates
store reference.
Note: The SampleClientTrustAnchor and SampleCollectionCertStore are
defined as part of the default Web services security bindings.
Save the changes. The modifications in the ibm-webservicesclient-bnd.xmi file
are shown here:
<securityResponseReceiverBindingConfig>
<signingInfos>
<signatureMethod
algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<certPathSettings>
<trustAnchorRef ref="SampleClientTrustAnchor"/>
<certStoreRef ref="SampleCollectionCertStore"/>
</certPathSettings>
<canonicalizationMethod
algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<digestMethod algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
</signingInfos>
</securityResponseReceiverBindingConfig>
Chapter 16. Web services security with Application Developer
321
Defining server integrity
Once the client is configured, we have to configure the server to match both
configurations. Open the webservices.xml file and select the Security Extensions
page:
Select the WeatherForecastEJB port.
– Under Request Receiver Service Configuration Details, expand Required
Integrity and add the body and security tokens.
– Under Response Sender Service Configuration Details, expand Integrity
and add body (follow the same process used for client configuration).
Save the changes. The modifications in the ibm-webservices-ext.xmi file are
shown here:
<securityRequestReceiverServiceConfig>
<requiredIntegrity>
<references part="body"/>
<references part="securitytoken"/>
</requiredIntegrity>
....
</securityRequestReceiverServiceConfig>
<securityResponseSenderServiceConfig>
<integrity>
<references part="body"/>
</integrity>
</securityResponseSenderServiceConfig>
To configure the binding information for the server we follow similar steps to
those used when we configured the client.
On the Binding Configurations page select the WeatherForecastEJB port. Expand
Request Receiver Binding Configuration Details and Signing Information and
click Add. The signing info dialog opens (Figure 16-14 on page 321).
In the dialog:
Leave the default algorithm methods.
Select Use certificate path reference.
Enter SampleServerTrustAnchor as the Trust anchor reference and
SampleCollectionCertStore as the Certificates store reference.
Save the changes. The modifications in the ibm-webservices-bnd.xmi file are
shown here:
<securityRequestReceiverBindingConfig>
<signingInfos>
<signatureMethod
322
WebSphere Version 5.1 Web Services Handbook
algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<certPathSettings>
<trustAnchorRef ref="SampleServerTrustAnchor"/>
<certStoreRef ref="SampleCollectionCertStore"/>
</certPathSettings>
<canonicalizationMethod
algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<digestMethod algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
</signingInfos>
....
</securityRequestReceiverBindingConfig>
We define the digitally signed bindings for the server response message. Expand
Response Sender Binding Configuration Details and Key Locators and click Add.
The key locator dialog opens (Figure 16-12 on page 318).
In the dialog:
Enter SampleServerSignerKey as the Key locator name.
Select com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator as t he Key
locator class.
Select Use key store.
Enter server as the Key store storepass.
Enter ${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-receiver.ks
for the Key store path.
Enter JKS as the Key store type.
Click Add under Key. Enter soapprovider as the Alias, server as the Key pass
and serversignerkey as the Key name.
Click OK.
You can find the valid aliases using the keytool on the dsig-receiver.ks file
(see “Exploring a key store file using the keytool” on page 319). There is a key
entry called soapprovider with a certificate authority called soapca, the same
certificate authority for the soaprequester.
Finally, we have to specify the algorithm that we use to digitally sign the
information. Expand Response Sender Binding Configuration Details and
Signing Information and click Enable. The Signing info dialog opens
(Figure 16-13 on page 320).
In the dialog:
Leave the default algorithm methods.
Enter serversignerkey as the Signing key name.
Select SampleServerSignerKey as the Signing key locator.
Chapter 16. Web services security with Application Developer
323
Click OK.
Save the changes. The modifications in the ibm-webservices-bnd.xmi file are
shown here:
<securityResponseSenderBindingConfig>
<signingInfo>
<signatureMethod
algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<signingKey name="serversignerkey"
locatorRef="SampleServerSignerKey"/>
<canonicalizationMethod
algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<digestMethod algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
</signingInfo>
<keyLocators name="SampleServerSignerKey"
classname="com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator">
<keyStore storepass="{xor}LDotKTot"
path="${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-receiver.ks"
type="JKS"/>
<keys alias="soapprovider" keypass="{xor}LDotKTot"
name="serversignerkey"/>
</keyLocators>
</securityResponseSenderBindingConfig>
Testing integrity and authentication
To test integrity plus authentication we follow the same steps defined in “Testing
authentication” on page 314:
Restart the WeatherServer (this is necessary when Web service deployment
descriptors are modified).
Select the TestClient.jsp (in ItsoWebService6EJBClient) and Run on
Server. Select the getDayForecast method, enter a date, and click Invoke.
In the TCP/IP Monitor we can see the SOAP messages, and how the defined
security constraints are included in the header of the SOAP message.
Example 16-4 and Example 16-5 show the SOAP messages sent by client and
server respectively.
Example 16-4 Message sent by the client with integrity and authentication
<soapenv:Envelope ...>
<soapenv:Header>
<wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2003/06/secext"
soapenv:mustUnderstand="1">
<wsse:BinarySecurityToken
xmlns:wsu="http://schemas.xmlsoap.org/ws/2003/06/utility"
EncodingType="wsse:Base64Binary"
324
WebSphere Version 5.1 Web Services Handbook
ValueType="wsse:X509v3"
wsu:Id="wssecurity_binary_security_token_id_8136177880451455025">
MIIDQTCCAqqgAwIBAgICAQQwDQYJKoZIhvcNAQEFBQAwTjELMAkGA1UEBhMCSlAxETAP
</wsse:BinarySecurityToken>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<CanonicalizationMethod
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
</CanonicalizationMethod>
<SignatureMethod
Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1">
</SignatureMethod>
<Reference URI="#wssecurity_body_id_5492786874616061430">
<Transforms>
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
<ec:InclusiveNamespaces
xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"
PrefixList="xsd #default soapenc soapenv xsi wsu ">
</ec:InclusiveNamespaces>
</Transform>
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">
</DigestMethod>
<DigestValue>7AJOediqUBpXb1HNlrzSrbxHJLQ=</DigestValue>
</Reference>
<Reference URI="#usernametoken_8399303084298552593">
<Transforms>
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
</Transform>
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">
</DigestMethod>
<DigestValue>jhqLJWM2bik/9yLv5ttQwdkqJus=</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>
uR0DAKo7rxWAKFUby8JFT4VioBKSv2FSq3LChtoJZlZtj5NTUH0A3wp8EeRt
Rg1J2RDgJj0tgD7i9BgbXusiKLlyih6IAftF2maOpj2RGK2GCSI2H+df8RVJ
AeZhlvCSiTLKUl6CjQW/mnJxchJMHNjfflSJ9aaWWzQgLBkfeAs=
</SignatureValue>
<KeyInfo>
<wsse:SecurityTokenReference>
<wsse:Reference
URI="#wssecurity_binary_security_token_id_8136177880451455025">
</wsse:Reference>
</wsse:SecurityTokenReference>
</KeyInfo>
</Signature>
<wsse:UsernameToken ....
Chapter 16. Web services security with Application Developer
325
....
</soapenv:Header>
<soapenv:Body...
....
</soapenv:Body>
</soapenv:Envelope>
Example 16-5 Message response delivered by the server with integrity
<soapenv:Envelope ...>
<soapenv:Header>\
<wsse:Security ...>
<wsse:BinarySecurityToken ....>
MIIDQDCCAqmgAwIBAgICAQUwDQYJKoZIhvcNAQEFBQAwTjELMA......
</wsse:BinarySecurityToken>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>......</SignedInfo>
<SignatureValue>
IebfSDgXsZROJyKXREo+Za9u1zs13cm9WbnPDGD3ZO5xZg3fUTCHs90m2J+r
t4Xmy6NykbUtglQVJJsCc11mPXJN0LSp6WSgaiY7B+xEhUZ6BTeiwDPO8lkR
/zg0GQye0RWglR6af54nKPnVnWRBuVZrWQUThN6FSvWW1HTzQ8Q=
</SignatureValue>
<KeyInfo>......</KeyInfo>
</Signature>
</wsse:Security>
</soapenv:Header>
......
Confidentiality
Confidentiality is the process by which data is protected such that only
authorized actors can interpret the data, reducing the risk that someone not
authorized can understand the content. The data is encrypted based on the XML
Encryption specifications.
Confidentiality applies encryption to some parts of the SOAP message:
Body content
User ID and password
Note: Currently, Application Developer 5.1 does not provide granularity to
encrypt only referenced parts of the body; the body content is encrypted as a
whole. That possibility is expected for future releases.
326
WebSphere Version 5.1 Web Services Handbook
Defining client confidentiality
As we did when we applied authentication and integrity to the SOAP message,
we use the Web Service Deployment editor. Open the webservicesclient.xml
file (in ItsoWebService6EJBClient) and select the Security Extensions page.
Select the WeatherForecastEJB port to apply security to that port. Under Request
Sender Configuration, expand Confidentiality. The available reference parts are:
bodycontent
usernametoken
We select both available possibilities for our example. Click Add, select
bodycontent, and click OK. Click Add again, select usernametoken, and click OK
(Figure 16-15, left).
We also want to receive the body content response from the server encrypted.
Under Response Receiver Configuration, expand Required Confidentiality and
add bodycontent (Figure 16-15, right).
sender
receiver
Figure 16-15 Confidentially parts to encrypt
Save the changes. The modifications in the ibm-webservicesclient-ext.xmi file
are shown here:
<securityRequestSenderServiceConfig >
....
<confidentiality>
<confidentialParts part="bodycontent"/>
<confidentialParts part="usernametoken"/>
</confidentiality>
....
</securityRequestSenderServiceConfig>
<securityResponseReceiverServiceConfig>
....
<requiredConfidentiality>
<confidentialParts part="bodycontent"/>
</requiredConfidentiality>
</securityResponseReceiverServiceConfig>
Chapter 16. Web services security with Application Developer
327
We have to provide how these parts are encrypted. We create a key locator
where the key to encrypt is loaded. On the Port Binding page select the
WeatherForecastEJB port. Expand Security Request Sender Binding
Configuration and Key Locators and click Add. The key locator dialog opens
(Figure 16-12 on page 318).
In the dialog:
Enter SampleSenderEncryptionKeyLocator as the Key locator name.
Select com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator as the Key
locator class.
Select Use key store.
Enter storepass as the Key store storepass.
Enter ${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-sender.jceks
as the Key store path.
Enter JCEKS as the Key store type.
Click Add under Key. Enter Group1 as the Alias, keypass as the Key pass, and
CN=Group1 as the Key name.
Click OK.
You can find the valid aliases using the keytool on the enc-sender.jceks file
(see “Exploring a key store file using the keytool” on page 319, use the password
storepass):
\wsad-home>\runtimes\base_v51\java\jre\bin\keytool
-list -keytype JCEKS -keystore dsig-sender.ks -v
There are key entries called alice, group1, and bob (Example 16-6).
Example 16-6 enc-sender.jceks keys information
Keystore type: JCEKS
Keystore provider: IBMJCE
Your keystore contains 3 entries:
Alias name: alice
Creation date: Wed Apr 23 21:01:20 PDT 2003
Entry type: keyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Alice, O=IBM, C=US
....
*******************************************
*******************************************
Alias name: group1
328
WebSphere Version 5.1 Web Services Handbook
Creation date: Wed Oct 09 00:57:47 PDT 2002
Entry type: keyEntry
*******************************************
*******************************************
Alias name: bob
Creation date: Wed Apr 23 21:02:39 PDT 2003
Entry type: trustedCertEntry
Owner: CN=Bob, O=IBM, C=US
Issuer: CN=Bob, O=IBM, C=US
....
We also have to specify the algorithm that we use to encrypt the information. We
provide the public key bob to encrypt. Expand Security Request Sender Binding
Configuration and Encryption Information and click Enable. The Encryption info
dialog opens (Figure 16-16).
Figure 16-16 Encryption info dialog
In the dialog:
Enter EncryptionInfo_1 as the Encryption name.
Leave the default algorithm methods.
Enter CN=Bob, O=IBM, C=US as the Encryption key name.
Select SampleSenderEncryptionKeyLocator as the Encryption key locator
Click OK.
Save the changes. The modifications in the ibm-webservicesclient-bnd.xmi file
are shown here:
<securityRequestSenderBindingConfig>
....
<encryptionInfo name="EncryptionInfo_1">
<encryptionKey name="CN=Bob, O=IBM, C=US"
locatorRef="SampleSenderEncryptionKeyLocator"/>
<encryptionMethod
Chapter 16. Web services security with Application Developer
329
algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
<keyEncryptionMethod
algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
</encryptionInfo>
<keyLocators name="SampleSenderEncryptionKeyLocator"
classname="com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator">
<keyStore storepass="{xor}LCswLTovPiws"
path="${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-sender.jceks"
type="JCEKS"/>
<keys alias="Group1" keypass="{xor}NDomLz4sLA==" name="CN=Group1"/>
</keyLocators>
....
</securityRequestSenderBindingConfig>
We have to configure how to decrypt the response message received from the
server. We have to use the private key alice in enc-sender.jceks. Expand
Security Response Receiver Binding Configuration and Encryption Information
and click Add. The Encryption info dialog opens (Figure 16-16 on page 329)
In the dialog:
Enter EncryptionInfo_2 as the Encryption name.
Leave the default algorithm methods.
Enter alice as the Encryption key name
Enter SampleSenderEncryptionKeyLocator as the Encryption key locator.
Click OK.
Note: The definitions for SampleSenderEncryptionKeyLocator are part of
the default Web services security bindings, but only the public key is
defined.
Save the changes. The modifications in the ibm-webservicesclient-bnd.xmi file
are shown here:
<securityResponseReceiverBindingConfig >
....
<encryptionInfos name="EncryptionInfo_2">
<encryptionKey name="alice"
locatorRef="SampleSenderEncryptionKeyLocator"/>
<encryptionMethod
algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
<keyEncryptionMethod
algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
</encryptionInfos>
</securityResponseReceiverBindingConfig>
330
WebSphere Version 5.1 Web Services Handbook
Defining server confidentiality
We have to configure the server to match both configurations. Open the
webservices.xml file and select the Security Extensions page.
Select the WeatherForecastEJB port. Under Request Receiver Service
Configuration Details, expand Required Confidentiality and add bodycontent and
usernametoken. Under Response Sender Service Configuration Details, expand
Confidentiality and add bodycontent (the same as for the client configuration).
Save the changes. The modifications in the ibm-webservices-ext.xmi file are
shown here:
<securityRequestReceiverServiceConfig>
....
<requiredConfidentiality>
<confidentialParts part="bodycontent"/>
<confidentialParts part="usernametoken"/>
</requiredConfidentiality>
....
</securityRequestReceiverServiceConfig>
<securityResponseSenderServiceConfig>
....
<confidentiality>
<confidentialParts part="bodycontent"/>
</confidentiality>
</securityResponseSenderServiceConfig>
To configure the binding information for the server we follow similar steps to
those used when we configured the client. On the Binding Configurations page
select the WeatherForecastEJB port.
Expand Request Receiver Binding Configuration Details and Encryption
Information and click Add. The encryption info dialog opens (Figure 16-16 on
page 329).
In the dialog:
Enter EncryptionInfo_1 as the Encryption name
Leave the default algorithm methods.
Enter bob as the Encryption key name.
Enter SampleReceiverEncryptionKeyLocator as the Encryption key locator.
Click OK.
Save the changes. The modifications in the ibm-webservices-bnd.xmi file are
shown here:
<securityRequestReceiverBindingConfig>
....
<encryptionInfos name="EncryptionInfo_1">
Chapter 16. Web services security with Application Developer
331
<encryptionKey name="bob"
locatorRef="SampleReceiverEncryptionKeyLocator"/>
<encryptionMethod
algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
<keyEncryptionMethod
algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
</encryptionInfos>
</securityRequestReceiverBindingConfig>
We define the encryption bindings for the server response message. Expand
Response Sender Binding Configuration Details and Key Locators and click Add.
The key locator dialog opens (Figure 16-12 on page 318).
In the dialog:
Enter SampleReceiverEncryptionKeyLocator as the Key locator name.
Select com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator as the Key
locator class.
Select Use key store.
Enter storepass as the Key store storepass.
Enter ${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-receiver.jceks
as the Key store path.
Enter JCEKS as Key store type.
Click Add under Key. Enter Group1 as the Alias, keypass as the Key pass, and
CN=Group1 as the Key name.
Click OK.
You can find the valid aliases using the keytool on the enc-receiver.jceks file
(see “Exploring a key store file using the keytool” on page 319, use the password
storepass, use -storetype JCEKS). There are key entries called alice, group1,
and bob. Note that alice is the trusted key for the server.
Finally, we have to specify the algorithm that we use to encrypt the information.
Expand Response Sender Binding Configuration Details and Encrypt Information
and click Enable. The encryption info dialog opens (Figure 16-16 on page 329).
In the dialog:
332
Enter EncryptionInfo_2 as the Encryption name.
Leave the default algorithm methods.
Enter CN=Alice, O=IBM, C=US as the Encryption key name.
Select SampleReceiverEncryptionKeyLocator as the Encryption key locator.
Click OK.
WebSphere Version 5.1 Web Services Handbook
Save the changes. The modifications in the ibm-webservices-bnd.xmi file are
shown here:
<securityResponseSenderBindingConfig>
....
<encryptionInfo name="EncryptionInfo_2">
<encryptionKey name="CN=Alice, O=IBM, C=US"
locatorRef="SampleReceiverEncryptionKeyLocator"/>
<encryptionMethod
algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
<keyEncryptionMethod
algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
</encryptionInfo>
....
<keyLocators name="SampleReceiverEncryptionKeyLocator"
classname="com.ibm.wsspi.wssecurity.config.KeyStoreKeyLocator">
<keyStore storepass="{xor}LCswLTovPiws"
path="${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-receiver.jceks"
type="JCEKS"/>
<keys alias="Group1" keypass="{xor}NDomLz4sLA==" name="CN=Group1"/>
</keyLocators>
</securityResponseSenderBindingConfig>
Configuring the server for confidentiality
Before we can test confidentiality we have to configure the WeatherServer. This
configuration cannot be done using the standard configuration editor; we have to
use the Administrative Console.
We have to include the private key we use to encrypt the SOAP messages in the
SampleSenderEncryptionKeyLocator:
Open the WeatherServer configuration and on the Configuration page select
Enable administration console, then save and close.
Restart the WeatherServer.
Select the server and Run administrative console (context). A Web browser
opens with http://localhost:9090/admin.
Accept the certificate when prompted and enter a valid user ID and password
(use the values entered on the Security page).
Select Servers -> Application Servers -> server1 (wait until server1 appears).
Under Additional Properties select Web services: Default bindings for Web
Services Security.
Select Key Locators -> SampleSenderEncryptionKeyLocator. Under
Additional Properties select Keys and click New (Figure 16-17).
Chapter 16. Web services security with Application Developer
333
Figure 16-17 Private key configuration for sender
Enter CN=Alice, O=IBM, C=US as the Key Name, alice as the Key Alias,
keypass as the Key Password, and click OK. Apply the new configuration in
the master configuration; select Save in the Message(s) frame and click Save.
As we have done for the private key in the client, we define the private key to
decrypt the messages in the SampleReceiverEncryptionKeyLocator:
Select Web services: Default bindings for Web Services Security -> Key
Locators -> SampleReceiverEncryptionKeyLocator. Under Additional
Properties select Keys and click New.
Enter CN=Bob, O=IBM, C=US as the Key Name, bob as the Key Alias, keypass
as the Key Password, and click OK.
Save the configuration by selecting Save in the top menu. Click Save.
Testing confidentiality, integrity, and authentication
Restart the WeatherServer to activate the changes, then run the TestClient.jsp
(in ItsoWebService6EJBClient). Select the getDayForecast method, enter a date,
and click Invoke.
In the TCP/IP Monitor we can see the SOAP messages, and now how the
information is encrypted in the SOAP message. Example 16-7 and
Example 16-8 show the SOAP messages sent by the client and server,
respectively.
Example 16-7 Message sent by the client with confidentiality, integrity and authentication
....
<EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#">
<EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5">
334
WebSphere Version 5.1 Web Services Handbook
</EncryptionMethod>
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<wsse:SecurityTokenReference>
<wsse:KeyIdentifier>
/62wXObED7z6c1yX7QkvN1thQdY=
</wsse:KeyIdentifier>
</wsse:SecurityTokenReference>
</KeyInfo>
<CipherData>
<CipherValue>
UcPSKrpohBb3oOblReTIeZHWepMZnTGO....TWJu/VHlyF6wtGZDBERh2O2NU=
</CipherValue>
</CipherData>
<ReferenceList>
<DataReference URI="#wssecurity_encryption_id_4611467978057449038">
</DataReference>
<DataReference URI="#wssecurity_encryption_id_2815601963193745488">
</DataReference>
</ReferenceList>
</EncryptedKey>
....
<EncryptedData ....>
<EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc">
</EncryptionMethod>
<CipherData>
<CipherValue>
c6GbasJU/OZ8hbdr....TXHUmig==
</CipherValue>
</CipherData>
</EncryptedData>
</wsse:Security>
</soapenv:Header>
<soapenv:Body ....>
<EncryptedData ....>
<EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc">
</EncryptionMethod>
<CipherData>
<CipherValue>
cc1V//9/+mT2GerGLrCb2q7O....3YfHO8v/A==
</CipherValue>
</CipherData>
</EncryptedData>
</soapenv:Body>
</soapenv:Envelope>
Chapter 16. Web services security with Application Developer
335
Example 16-8 Message response delivered by the server with confidentiality and integrity
....
<EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#">
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5">
</EncryptionMethod>
....
<CipherValue>
UcPSKrpo....HlyF6wtGZDBERh2O2NU=
</CipherValue>
....
<CipherValue>
c6GbasJU/OZ8hbd....CEfTXHUmig==
</CipherValue>
....
</soapenv:Header>
<soapenv:Body ....>
....
<CipherValue>
cc1V//9/+mT2....ULAtArgNw4I4I3YfHO8v/A==
</CipherValue>
....
</soapenv:Body>
</soapenv:Envelope>
Note that the SOAP body is now encrypted and completely unreadable.
However, the test client displays the result. Stop the server when finished.
Resetting the server configuration and client proxy
Open the WeatherServer configuration:
Deselect Enable administration console on the Configuration page.
Switch off security on the Security page if you want to run the other enterprise
applications.
Remove the trace setting on the Trace page by changing the Trace string to
*=all=disabled.
Also reset the destination address in the WeatherForecastEJBServiceLocator
proxy in the ItsoWebService6EJBClient project (from port 9081 to 9080).
Trace output
You can find the server trace output in this directory:
<workspace>\.metadata\.plugins\com.ibm.etools.server.core\tmp0\logs\server1
336
WebSphere Version 5.1 Web Services Handbook
J2EE security and WS-Security relationship
J2EE security can be applied to secure Web services. We have to understand
that J2EE security is not message-level security, like the security we applied in
this chapter. By contrast, J2EE security is based on SSL transport security and
J2EE role-based security. J2EE security is the security applied in Web services
for the J2EE specification; see Chapter 5, “Implementing Enterprise Web
Services (JSR 109)” on page 77.
The Web service endpoint is secured using J2EE role-based security. The client
can provide HTTP basic authentication in the HTTP header and also use SSL to
secure the transport level. Once the message arrives to the Web service
endpoint, the Web container authenticates the user using the value provided by
the HTTP header and sets the security context for the call. That security context
is propagated through the different required modules to complete the client
request.
WS-Security can be used for any scenario. If we have a Web service using JMS,
only WS-Security can provide a way to propagate security tokens. WS-Security
does not contrapose to J2EE security. In contrary, WS-Security complements
and leverages J2EE role-based security. We can use SSL to transport a
message over HTTP that includes SOAP message security. We also can use the
EJB authorization process because WS-Security sets the security context for the
call—once the user is authenticated—and propagates that context to the EJB.
Using a process like that for a Web service, we can differentiate among clients.
Depending on the client profile, we verify the authorized methods for that client at
run time.
Summary
In this chapter we presented the basic functionality that can be used to apply
message-level security to Web services using Application Developer 5.1, the
primary tool to specify security. This security is applied to JSR 101 and JSR 109
Web services, built in Application Developer 5.1.1 to run in WebSphere
Application Server 5.1.
WS-Security brings flexible options to specify different levels of security. We have
reviewed the options to apply authentication, integrity, and confidentiality to
existing Web services. First, we introduced the authentication mechanisms,
followed by integrity, and finally implemented confidentiality.
Chapter 16. Web services security with Application Developer
337
We have also reviewed how we can trace SOAP messages with a TCP/IP
Monitor and what security information is included in the headers of those
messages. We have seen how a client can be modified to be a container
management client, the only client type supported for security.
Finally, we have discussed how WS-Security integrates with J2EE authentication
and role-based authorization security and how both of them can work together.
The tables that follow show the different security configurations we can apply to
secure a Web service with message level security:
Table 16-1—Shows client server security extensions’ possibilities for the
request message
Table 16-2—Shows client server security bindings’ possibilities for the request
message
Table 16-3—Shows server client security extensions’ possibilities for the
response message
Table 16-4—Shows server client security bindings’ possibilities for the
response message
Table 16-1 Client and server service extension configuration for request
338
securityRequestSenderServiceConfig
securityRequestReceiverServiceConfig
loginConfig
AuthMethod
loginConfig
AuthMethod
Integrity
Body
SecurityToken
TimeStamp
Integrity
Body
SecurityToken
TimeStamp
Confidentiality
BodyContent
UserNameToken
Confidentiality
BodyContent
UserNameToken
IDAssertion
IDType
valid username, DN or X509Cer
TrustMode
BasicAuth or Signature
IDAssertion
IDType
valid username, DN or X509Cer
TrustMode
BasicAuth or Signature
AddCreatedTimeStamp
true or false
expires
AddReceivedTimeStamp
true or false
WebSphere Version 5.1 Web Services Handbook
Table 16-2 Client and server service extension configuration for response
securityResponseReceiverServiceConfig
securityResponseSenderServiceConfig
Integrity
Body
TimeStamp
Integrity
Body
TimeStamp
Confidentiality
BodyContent
Confidentiality
BodyContent
AddReceivedTimeStamp
true or false
AddCreatedTimeStamp
true or false
expires
Table 16-3 Client and server binding configuration for request
securityRequestSenderBindingConfig
securityRequestReceiverBindingConfig
SigningInfo
SignatureMethod
CanonicalizationMethod
DigestMethod
SigningKey or CertPathSettings
SigningInfos
SignatureMethod
CanonicalizationMethod
DigestMethod
SigningKey or CertPathSettings
EncryptionInfo
DataEncryptionMethod
KeyEncryptionMethod
EncryptionKey
EncryptionInfos
DataEncryptionMethod
KeyEncryptionMethod
EncryptionKey
KeyLocators (0 or more)
KeyStore, Key, Property
KeyLocators (0 or more)
KeyStore, Key, Property
LoginBinding
AuthMethod
TokenValueType
CallBackHandler
LoginMapping
AuthMethod
TokenValueType
CallBackHandler
TrustedIDEvaluator or
TrustedIDEvaluatorRef
TrustAnchors
KeyStore
CertStoreList
LDAPCertStore or CollectionCertStore
Chapter 16. Web services security with Application Developer
339
Table 16-4 Client and server binding configuration for response
securityResponseReceiverBinding
Config
securityResponseSenderBindingConfig
SigningInfo
SignatureMethod
CanonicalizationMethod
DigestMethod
SigningKey or CertPathSettings
SigningInfos
SignatureMethod
CanonicalizationMethod
DigestMethod
SigningKey or CertPathSettings
EncryptionInfo
DataEncryptionMethod
KeyEncryptionMethod
EncryptionKey
EncryptionInfos
DataEncryptionMethod
KeyEncryptionMethod
EncryptionKey
KeyLocators (0 or more)
KeyStore, Key, Property
KeyLocators (0 or more)
KeyStore, Key, Property
TrustAnchors
KeyStore
CertStoreList
LDAPCertStore or
CollectionCertStore
More information
The best source for more and updated information is the WebSphere Application
Server Information Center:
http://www.ibm.com/software/webservers/appserv/infocenter.html
Expand Securing -> Applications -> Web services.
340
WebSphere Version 5.1 Web Services Handbook
17
Chapter 17.
Application Developer
Integration Edition
WebSphere Studio Application Developer, introduced in the previous chapters,
provides the support for developing, testing, and publishing Web services, and
writing clients that use the Web services. Application Developer Integration
Edition adds more sophisticated support, by providing a development
environment for enterprise services and business processes. The main purpose
of the Integration Edition is to provide development features used for applications
running on WebSphere Application Server Enterprise Edition.
Because the Integration Edition extends the function of Application Developer,
this chapter only presents the additional features:
Enterprise services
Resource adapters
Business Integration perspective
Business processes
Development and testing of a sample business process
Important: Application Developer Integration Edition was still at Version 5.0
when this book was updated. Therefore we did not change this chapter.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
341
Enterprise services
The service-oriented architecture takes existing software components residing
on the network and allows them to be published, discovered, and invoked by
each other. The service-oriented architecture allows a software programmer to
model programming solutions in terms of services offered by components to
anyone, anywhere over the network. Therefore, existing software components
are wrapped as services, and these services can communicate with other
applications through a common interface.
Like Web services, enterprise services offer access over the Internet to
applications in a platform-neutral and language-neutral fashion. In addition, they
offer access to enterprise information systems (EIS) and message queues, and
can be used in a client/server configuration without the Internet. Enterprise
services can access applications and data on a variety of EIS systems and in a
variety of formats. And these services can be combined to form a new service.
Software components wrapped as an enterprise service can be bound to use a
range of protocols, including SOAP, IIOP, JMS, JCA, EJB, and Java native
bindings. They are primarily used for wrapping connections to enterprise
information systems. The concept of enterprise services extends the Web
service model by using new open standard technologies, such as the Web
services invocation framework (WSIF), to communicate to an endpoint.
Enterprise services can be described in WSDL files using non-SOAP binding
information. Some sources also use the term enterprise Web services in contrast
to Internet Web services.
Enterprise services can be developed in WebSphere Studio Application
Developer Integration Edition.
Creating an enterprise service: Bottom-up
When using the bottom-up approach to develop an enterprise service, you are
primarily importing artifacts to generate the enterprise services for them. Besides
generating services for artifacts supported by Application Developer, such as
Java classes and EJBs, the Integration Edition can also generate enterprise
services that support the following resource adapters:
342
CICS ECI
CICS EPI
Host On-Demand 3270
IMS™
Imported customized EIS JCA resource adapters
WebSphere Version 5.1 Web Services Handbook
The main steps to create and install an enterprise service are:
Create a service project.
Develop or import the implementation into the service project.
Generate the enterprise service by using the service wizard.
Generate the deployed code (wrapper classes).
Deploy the enterprise service as an EAR file to an application server.
Creating an enterprise service: Top-down
You can develop enterprise services using a top-down approach by first creating
the service definition and then adding the implementation for the service.
Assuming that you have a WSDL file that contains the service interface
definitions (port types, operations, and messages), you can follow these steps to
add bindings and port definitions for the service and generate either a Java or
EJB skeleton for the implementation of the service:
Create a service project.
Import the interface files (WSDL).
Create an EJB project if an EJB skeleton is to be generated (this step is not
necessary when creating a simple Java skeleton).
Generate the service skeleton using the New Service Skeleton wizard, found
by clicking New- > Other -> Business Integration -> Build from service.
Implement the business logic in the skeleton.
Deploy the service as an EAR file to an application server.
Resource adapters
The J2EE Connector Architecture (JCA) is a standard way for a Java component
to connect to any enterprise system. It is part of the J2EE standard, introduced in
the J2EE 1.3 specification. WebSphere Application Server 5 is J2EE 1.3
compliant and therefore supports the connector architecture. The JCA states that
the way an application server communicates with an enterprise system (such as
CICS) is through a resource adapter.
A resource adapter is written specifically for the enterprise system it supports,
but the same resource adapter can be plugged into any application server.
Resource adapters represent a middle tier that allow Java clients to
communicate with enterprise information systems (EIS) such as CICS and IMS.
A Java client that interacts with an EIS uses a resource adapter specific for that
EIS. For example, a client connecting to IMS requires an IMS resource adapter.
Chapter 17. Application Developer Integration Edition
343
The Java client uses the common client interface (CCI) API to communicate with
the resource adapter. The resource adapter in turn interprets the CCI request,
and interacts with the EIS using a protocol native to the EIS. If a Java client calls
a program running in CICS, the Java client uses the CCI API to send a request to
the CICS ECI resource adapter, specifying the CICS program and server to call.
Figure 17-1 illustrates how resource adapters are used by services to access
legacy systems.
Client
Application
Server
EIS
Application
Front
end
Enterprise
Service
CCI
Resource
adapter
native
Legacy
application
and data
Figure 17-1 Using resource adapters to access legacy applications or data
Resource adapters run in a J2EE application server, such as WebSphere
Application Server. The application server can manage the connection between
resource adapter and EIS, allowing it to perform connection pooling, security
propagation, and transactions.
IBM provides JCA adapters for CICS, IMS, and Host On-Demand (HOD). Other
companies provides JCA adapters for a range of products, such as SAP,
PeopleSoft, Siebel, and Oracle ERP. A list of JCA adapters is provided at:
http://java.sun.com/j2ee/connector/products.html
Using Application Developer Integration Edition
In this section we discuss the enterprise services development environment
provided by Application Developer Integration Edition.
344
WebSphere Version 5.1 Web Services Handbook
Business Integration perspective
The Business Integration perspective configures the layout of the Workbench to
facilitate the development of enterprise services. The perspective contains views
of Workbench resources that you would typically use when you develop
enterprise services. Figure 17-2 shows the Business Integration perspective with
two important parts that support Web services:
Services view
WSDL editor
Figure 17-2 Business Integration perspective
The Business Integration perspective introduces the service project. A service
project holds the implementation of a service as well as meta information about
the service and deployed code. The deployed code is a wrapper around the
implementation to make it callable through specific bindings. Depending on the
type of binding, the deployed code can be either an EJB (for IIOP clients), a
SOAP wrapper (Web service), or a JMS wrapper (for asynchronous access).
Chapter 17. Application Developer Integration Edition
345
This Business Integration perspective offers several wizards that can be used to
create enterprise services, and all artifacts that they require, such as service
projects, business processes, wrapping and exposing of existing
implementations.
Services view
The Services view displays the service resources. The view presents two folders:
Service Projects—Contain service definitions, as well as other supporting
resources, such as Java, COBOL, and C source files
Deployable Services—Contain the resources that can be deployed, which are
the generated EJBs or Web services that wrap the actual implementation
There are several ways to launch the tool components from the perspective. The
quickest path is to launch them through the tool bar that the perspective offers.
Another way is through pop-up menu choices and a resource creation window.
Enhanced WSDL editor
In Integration Edition you can edit an enterprise service WSDL file using the
enhanced WSDL editor. This editor visualizes the complex information of a
WSDL file in a much better way than a normal XML editor. Figure 17-3 shows a
page of the WSDL editor viewing the weather forecast sample.
Figure 17-3 WSDL editor in Integration Edition
346
WebSphere Version 5.1 Web Services Handbook
Note that the Outline view is connected to the editor and allows a quick
navigation within the file. As per default, this editor is used when opening a
WSDL file. You can explicitly start the editor by selecting a WSDL file and Open
With -> WSDL Editor.
The name of the WSDL file that is open is shown on the tab at the top of the
WSDL editor view. You can have more than one WSDL file opened in the editor.
Each file shows up as a separate tab at the top of the Editor pane. Often you split
a WSDL document into two or three files to separate service, binding, and
interface information. The linkage between these corresponding WSDLs is
maintained by the editor, and whenever you access some information that is
provided in another file, that file is opened automatically.
Business process
There are a number of artifacts and components that can be exposed as
services. Web services, JavaBeans, and enterprise beans can all be used to
implement certain pieces of your business. The combination of more than one of
such services is called a business process. A business process is the outcome of
choreographing and combining services together.
A business process is also often a single activity from a client point of view. The
client is not aware of all the internal actions (services) that are required to
perform the function.
Integration Edition allows you to model such business processes in an easy way.
These business processes themselves can then be deployed and exposed as
new enterprise services for clients.
For example, if you have an existing application composed of enterprise beans,
and you want to integrate it with another application composed of enterprise
beans, you can easily create a business process to define the integration in a
flexible way. If you have an existing application and you want to add functionality
available as a Web service, you can use a business process to integrate the
enterprise bean application and the Web service. In either case you can add the
activity that best represents your existing implementation and the business
process will work in the same way regardless of the underlying implementation.
Process editor
The process editor is a graphical modeling environment used to design
processes that execute individual activities in a predetermined sequence to fulfill
an overall business goal. The process execution begins at an input activity and
Chapter 17. Application Developer Integration Edition
347
progresses through other activities to the output activity. The activities in between
describe either service or non-service specific operations:
Service-specific operations are described using Web services definition
language (WSDL). There are three parameters to each service: The service
name, the port type, and the operation.
Non service-oriented objects include JavaBean, EJB, event, or staff (people)
activities.
Elements of the process
Here is a list of process elements:
Input activity—The input activity is the source and starting point of the
process, and can have any number of outgoing controls. The input activity is
created automatically by the editor, and only one can be used per process.
Output activity—The output activity is the end of the process. For a
synchronous process the output activity returns a variable to the caller. An
output activity may also call a service passing a variable as parameter.
Control links—Control links dictate the sequence in which the flow's activities
are executed. They are represented graphically by solid blue arrows.
Java snippet activity—Use this activity to write custom Java code to
manipulate and prepare variables, for example, to transform output data of
one activity into input data of another activity.
Invoke service activity—This is an activity that invokes an external Web
service (any artifact with a service interface) as part of the business process.
Invoke Java activity—Use the Java activity to make a call to a Java class
within your business process.
Invoke process—An activity that represents a separate business process that
is being invoked within a larger one. Unlike the block activity, the process
activity is a complete process, and can exist on its own outside of the primary
process, and be used by other processes.
Invoke EJB—Use the EJB activity to make a call to an enterprise bean, and
use its activity as a part of the process.
Empty activity—An empty activity has no defined implementation and can be
used as a place holder in the design stage, and fleshed out later, or when a
fault needs to be caught and suppressed.
Fault activity—The fault activity is used when a business process fails. It can
throw an exception to the caller (synchronous), or it can call a separate
service passing a variable as the message.
Block activity—Use the block activity to simplify the diagram by decomposing
the process into individual distinct portions, each representing an entire
348
WebSphere Version 5.1 Web Services Handbook
nested business process that runs within a larger one. To open the process
that the block activity represents, you can double-click it or you can select
Open in New Page from the context menu.
Loop activity—This activity is a specialized form of a block that can be iterated
so that the operation executes more than once during the flow. The execution
of the loop is controlled by a conditional expression, and continues to execute
as long as this conditional expression evaluates to true.
Staff activity—This is an activity that requires human input to decide how to
proceed.
Receive event activity—The event activity represents an activity in the
business process that waits for one or more external events to happen before
continuing.
Text object—This is an activity that displays a message of your choice on the
editor for documentation purposes.
Dynamic process properties
Process dynamics refers to the manner in which a process runs from start to
finish. Your process can include any of the following:
Looping—Repeats a specific operation and does not proceed until certain
conditions are met
Asynchronous vs. synchronous processes—Determines whether the process
returns a response
Throwing faults—Uses faults to deal with exceptions that you expect the
process may encounter
Compensation service—Uses a compensation service to determine what to
do with committed activities in the event of a rollback later in the process
Interruptible vs. non-interruptible processes—A process is interruptible if it
stops for an external activity
Event activity—Uses an event to halt the process and wait for a predefined
external event to occur
Correlation methods—Uses correlation methods with an event activity to
instruct the runtime how to differentiate individual business processes in a
multi-executed business process environment
Staff activities—Uses a staff activity to direct the process to a person and wait
for human input before continuing
Compare the list of elements with the description in “Business process execution
language for Web services” on page 165.
Chapter 17. Application Developer Integration Edition
349
Sample business process
This section covers how to model a business process using the Business
Integration perspective.
The example takes a week number as input and returns the temperature in
degrees Fahrenheit of the first day in that week. The example uses the weather
forecast service described in earlier chapters.
Unfortunately the original service shows the temperature in degrees Celsius.
Therefore we have to integrate another service, TemperatureCalculator, into the
flow. This service translates between Celsius and Fahrenheit by taking a
temperature value and converting it.
Therefore, the steps in the sample process are:
Convert the week number into a concrete date.
Call the original weather forecast Web service to retrieve a Weather object.
Extract the temperature in degrees Celsius.
Invoke another Web service to convert from Celsius to Fahrenheit.
Return the temperature in Fahrenheit.
Prepare existing services
Because we are building a business process from a number of existing services,
we have to either create them first or at least make sure that they are accessible:
If the services are EJBs or Web services running in the same enterprise
application, you might want to check the corresponding projects.
If your are going to use external services, you just have to make sure that you
have the WSDL files specifying their interfaces.
In our example, the external services for weather forecast and temperature
calculation are placed in a separate Web module within the same enterprise
application project to make testing and starting of servers simpler.
Create a service project
First of all, you have to create a service project using File-> New -> Other ->
Service Project. This project will hold all the artifacts and metadata that you use
to model the process. Figure 17-4 shows the creation wizard. You typically create
a project with a suffix such as Service to distinguish it from the Web and EJB
projects that are created in a later step.
350
WebSphere Version 5.1 Web Services Handbook
Figure 17-4 Create a service project
Import existing Web services
Before we can work with existing—and maybe external—services, we have to
import their WSDL files into the service project, so that we can use them while
modeling the process flow. Either these WSDL files can be imported from
another project or file system, because you are using your own services, or they
have to be obtained by the service provider directly or through a UDDI registry.
In our case, we have an enterprise application (ItsoWebServBaseEAR) with two
Web projects (ItsoWebServWFWEB and ItsoWebServTCWEB) either already in the
workspace, or we import them from EAR/WAR files:
Select File -> Import -> EAR File, then click Browse and locate the file:
sg246891-01\sampcode\wsadie\ItsoWebServBaseEAR.ear
Enter ItsoWebServBaseEAR as the project name.
Select Preserve project names, classpath, and meta-data included in the
EAR and click Finish.
If you import the EAR without the Preserve project names option, you get errors
after import. In this case, select each Web project and Properties, and on the
Libraries page click Add Variable and add the SOAPJAR variable. This action
should remove the error messages from the Tasks view.
Before continuing, it is a good idea to test that the services are up and running,
either with the universal test client or a sample client. The Web modules also
include the WSDL files, which are located inside the Web projects. To test, you
would have to define a server, but you can wait to test until you define a server for
the testing of the sample process.
Chapter 17. Application Developer Integration Edition
351
Existing Web services
The ItsoWebServWFWEB project contains the weather forecast service, the same
service we developed in Chapter 15, “WebSphere Studio Application Developer”
on page 247. The only difference is the project name and therefore the access
point in the service WSDL file:
http://localhost:9080/ItsoWebServWFWEB/servlet/rpcrouter
The ItsoWebServFTCWEB project contains the temperature calculator service,
which converts between degrees Celsius and Fahrenheit. We will use the
convertCelsiusToFahrenheit method in our example.
Set up WSDL files of existing services
Next we create folders within the service project and import or copy the WSDL
files and associated XSD files. In the Business Integration perspective we can
find them in the Services view, as shown in Figure 17-5.
Copied from
ItsoWebServWFWeb
Copied from
ItsoWebServTCWeb
Figure 17-5 Services view with the WSDL files that will be used in the process
Create the business process
The next step is to create a new business process. We use the wizard, which can
be started using File -> New -> Business Process. Then we have to specify a
project, package, and file name for the process, as shown in Figure 17-6.
352
WebSphere Version 5.1 Web Services Handbook
Figure 17-6 Create a new business process
Every business process must have an input and an output operation. The input
operation is called to start the process. If the service is synchronous, the input
operation can return the result. If the service is asynchronous, the result of the
business process can be sent to another operation that can act upon the result.
If you had defined operations for the business process, you could specify them at
this time in a top-down design. Because we do not have defined operations that
our process must implement, we accept the default on the next wizard page and
select Define business process interface later. Click Finish.
The graphical business processor editor opens and displays an Input and Output
node, as shown in Figure 17-7.
Figure 17-7 Initial state of new business process
Chapter 17. Application Developer Integration Edition
353
On the left side of the editor is a palette of items you can use for modeling the
process. Note that there are a number of warnings both in the graphical design
as well as in the Tasks view. They indicate that the process is not finished yet and
disappear when we complete the process flow.
The editor has a number of tabs:
The Process tab shows the graphical representation.
The Interface tab defines the input and output operations of the process. We
did not define them yet in the wizard, so it shows an error. In that tab you can
also define operations corresponding to faults that you may handle within the
business process. Finally events can be defined that require requests to be
processed between the beginning and end of a business process.
On the Server tab, there are a number of settings specified for running the
business process in production. These settings can be modified when the
business process is deployed to WebSphere Application Server 5 Enterprise
Edition.
On the Variables tab, you can specify variables to maintain state as your
process is completed. Variables are a very important part of a business
process because they are used for holding information between calls to the
different services and artifacts that make up the process. Initially an input
and an output variable are defined.
On the Staff tab, you can define roles with certain levels of permission for
different people.
On the Client tab, JSP attributes can be defined for testing the process using
a Web client.
Adding services to the process
An easy way to add services to a process is by dragging and dropping the
appropriate WSDL files to the process space. We already imported the WSDL
files to the service project, so we find them in the Services view.
Note that there are three WSDL files for each service. The most interesting is the
file that typically contains the word Service in it, because it is the root document
and imports the others.
When we drop a service WSDL file on the white area, a window pops up (as
shown in Figure 17-8), where you can define which of the services, port types,
and operations you want to use at this point.
We add two services: The WeatherForecast and the TemperatureCalculator.
354
WebSphere Version 5.1 Web Services Handbook
Figure 17-8 Select service, port type, and operation to add a service
Adding flow to the process
To add flow into the process, we can use the graphical process editor. In the
palette you select Control Link, then click first the output terminal (the arrow on
the right of the icon) of one service, and then click the input terminal (the arrow
on the left of the icon) of another service.
In general we want to pass the weather information from the weather forecast
service to the temperature calculator service, and the calculator result to the
output.
After connecting all the services and the input and output nodes, the first draft of
our process is shown in Figure 17-9.
input terminal
output terminal
Figure 17-9 Flow between the activities
Chapter 17. Application Developer Integration Edition
355
Besides sequential flows between services, you can also model loops and
conditions that decide which part of the flow should be executed. For simplicity
reasons they are not covered in this chapter.
However, the process is not finished yet. We just connected the two services by a
control link, but we totally ignored the fact that these two services require their
input parameters in a specific data type:
Our business process has an integer (week number) as input, but the
WeatherForecast requires a date.
Also, the WeatherForecast returns a Weather object as a result, and the
TemperatureCalculator requires an integer (the temperature value inside the
Weather object).
There are two things to do to solve the problem:
Define variables for the input and output messages of the activities.
Insert a converter between the services to handle the data types.
Messages and variables
When a service is called within a business process, a message is returned. The
message is stored within a variable that you can specify. From this variable you
can extract parts and map it to parts in other messages, which are sent to other
services within the process. Often you have to place a mapping between two
messages. This can be done either by a transformation service or by simple Java
code. We will do the latter one for our process.
In the Properties window of a service that can be reached using the context
menu, there is a section called Implementation that specifies the messages and
variables associated with the in- and outbound terminals of that service. The
concrete message that is used is defined in the WSDL document of the service
and cannot be changed.
In the case where one operation has defined the same output message as the
next service input message, you would not have to specify anything. Of course
this is not the case in general and we have to implement converters:
We define a variable for the output message of the first activity.
We define a variable for the input message of the second activity.
We write a converter that fills the second variable with data of the first
variable.
356
WebSphere Version 5.1 Web Services Handbook
WSDL
WSDL
Service A
Operation 1
Response
Message 1
Service:
WeatherForecast
Operation:
getDayForecast
getDayForecast
Response
(Weather object)
Java Variable
in Process
Java Code or
Transformer
Java Variable
in Process
Variable1
Converter
Variable2
Weather object
int tempC =
weather.
getTemperature()
int
WSDL
Request
Message 2
convertCelsiusTo
FahrenheitRequest
(int)
WSDL
Service B
Operation 2
Service:
TemperatureCalculator
Operation:
convertCelsius..
ToFahrenheit
Figure 17-10 Using variables for conversion between messages
Figure 17-10 illustrates the chain of objects.
The middle row shows the elements in the process.
The upper row describes where and how these elements are specified.
The bottom row shows the names in our example.
The services (activities) have been added to the process and the messages are
defined in the WSDL file of each service. We now have to specify the variables
for the input and output messages and implement a converter.
In the Properties window of the getDayForecast, we find the variable bindings in
the section called Implementation:
We select the correct types for each message. Because we know that the
getDayForecast method returns a Weather object, we can select the Weather
XML schema for the getDayForecastResponse, indicated with (1) in
Figure 17-11.
There is also another—more general—way. You do not select the concrete
Weather.xsd file, because you might not even have the XML schema file. The
schema information is also included in the WSDL file. So the general
approach is to select the WSDL file that defines the messages—in our case
WeatherForecast.wsdl—and select the getDayForecastResponseMessage
(which in fact contains one part, namely a Weather object) as indicated with
(2) in Figure 17-11.
Using the second approach you define variables for input and output terminals
for both Web service calls:
getDayForecastRequest—Input of weather forecast
getDayForecastResponse—Output of weather forecast
convertCelsiusToFahrenheitRequest—Input of calculator
convertCelsiusToFahrenheitResponse—Output of calculator
Chapter 17. Application Developer Integration Edition
357
(1)
(2)
Figure 17-11 Defining variables for in- and outbound messages of operations
358
WebSphere Version 5.1 Web Services Handbook
Figure 17-12 shows the variables defined for the getDayForecast service.
Figure 17-12 Variables for input and output
The input parameter for the business process is the week number. We use the
predefined variable input for this, and its default type of Int is what we require
for the process. Figure 17-13 shows the complete set of variables in the
Variables tab.
Figure 17-13 Process variables
Chapter 17. Application Developer Integration Edition
359
Note the input and output variables. They define the data types of the input
parameter and the result of the operation. The default of Int for both variables is
exactly what we want for this process.
Save the diagram. A number of Java classes are generated:
itso.wsie.temperature—The Java code for the process itself
wsdl.itso.wsoj.WeatherForecast_msg—A package with two message
classes for the input and output messages (GetDayForecastRequestMessage
and GetDayForecastResponseMessage)
wsdl.itso.wstc.TemperatureCalculator_msg—A package with two message
classes (ConvertCelsiusToFahrenheitRequestMessage and
ConvertCelsiusToFahrenheitResponseMessage)
Extract of generated code
The temperature class provides the Java code to get and set the variables used
in the business process. Some of the generated methods are:
getInput—Retrieves the input variable. This method returns an IntMessage
from which the int value can be extracted:
public org.xmlsoap.schemas.wsdl.wsadie.messages.IntMessage getInput()
throws com.ibm.bpe.api.ProcessException {
return new org.xmlsoap.schemas.wsdl.wsadie.messages.IntMessage(
(WSIFMessage) readBPEVariable("input"));
}
setGetDayForecastRequest—Sets the input variable for the getDayForecast
activity by passing a message variable:
public void setGetDayForecastRequest(
wsdl.itso.wsoj.WeatherForecast_msg.GetDayForecastRequestMessage message)
throws com.ibm.bpe.api.ProcessException {
updateBPEVariable("getDayForecastRequest", message.message());
}
getGetDayForecastResponse—Retrieves the output variable of the
getDayForecast activity:
public wsdl.itso.wsoj.WeatherForecast_msg.GetDayForecastResponseMessage
getGetDayForecastResponse()
throws com.ibm.bpe.api.ProcessException {
return new
wsdl.itso.wsoj.WeatherForecast_msg.GetDayForecastResponseMessage(
(WSIFMessage) readBPEVariable("getDayForecastResponse"));
}
360
WebSphere Version 5.1 Web Services Handbook
The two messages associated with the getDayForecast activity are generated
into the wsdl.itso.wsoj.WeatherForecast_msg package.
The GetDayForecastRequestMessage class contains the input data of the Web
service, a Date object, with getter/setter methods:
public class GetDayForecastRequestMessage
extends com.ibm.wsif.jca.util.WSIFMessageImpl {
public GetDayForecastRequestMessage(WSIFMessage message)
{ super(message); }
public GetDayForecastRequestMessage() { super(); }
public java.util.Date getTheDate() {
try {
return (java.util.Date) super.getObjectPart("theDate");
} catch (WSIFException exc) {
throw new java.lang.IllegalArgumentException(exc.toString());
}
}
public void setTheDate(java.util.Date newValue) {
try {
super.setObjectPart("theDate", newValue);
} catch (WSIFException exc) {
throw new java.lang.IllegalArgumentException(exc.toString());
}
}
}
The GetDayForecastResponseMessage class contains the output data of the Web
service, a Weather object, with getter/setter methods:
public class GetDayForecastResponseMessage
extends com.ibm.wsif.jca.util.WSIFMessageImpl {
..... // constructors
public itso.wsoj.Weather getResult() {
try {
return (itso.wsoj.Weather) super.getObjectPart("result");
} catch (WSIFException exc) {
throw new java.lang.IllegalArgumentException(exc.toString());
}
public void setResult(itso.wsoj.Weather newValue) {
try {
super.setObjectPart("result", newValue);
} catch (WSIFException exc) {
throw new java.lang.IllegalArgumentException(exc.toString());
}
}
}
Chapter 17. Application Developer Integration Edition
361
Process files
The process flow information is stored in two files in the itso.wsie package.
Process file: temperature.process
The temperature.process file is an XML file that stores the graphical information
about the definition of the process, including the variables and conditions on the
control links.
FDML file: temperature.fdml
The temperature.fdml file uses the flow definition markup language (FDML) to
store information about the activities, links, and messages.
We examine the file in “Flow definition markup language” on page 368.
Adding Java snippets
After we have defined variables for all necessary input and output messages, we
have to implement the converters that translate the output of one node into the
input of the next node. The easiest way to achieve this is by writing Java
snippets, which in fact become methods in the process class. These snippets
have access to all the variables defined in the process:
At the beginning of the flow there is a snippet that creates a Date object from
the input week number.
One snippet translates the Weather object from the getDayForecast method of
the WeatherForecast service into an int for the convertCelsiusToFahrenheit
method of the TemperatureCalculator service.
We also added a final snippet at the end of the process to trace some output
messages.
To add a snippet between two operations:
Add a Java Snippet object from the palette.
Select Rename (context) to change the default name to a nice name.
Delete the old control link.
Connect the output terminal of the previous node to the input of the snippet.
Connect the output of the snippet to the input of the next node.
Note: You can also grab the endpoint of a link and move it to another terminal.
To edit the Java code, select the Java snippet icon and Show Java (context) or
click Show Java in the selection bar. In the source code pane underneath the
process flow, you can update the code that is executed in that process step.
362
WebSphere Version 5.1 Web Services Handbook
Figure 17-14 shows the new process with the Java snippets connected with new
control links. In the source pane you see the source code of the selected snippet,
prepareDate, which shows how to access variables.
Figure 17-14 Adding Java snippets for conversion between messages
There are three snippets to implement:
prepareDate—Take the week number of the process input and calculate a
date for the getDayForecast method:
// retrieve week number from process input
int weekNr = getInput().getValue();
// calculate date of monday in that week
Calendar cal = Calendar.getInstance();
cal.setFirstDayOfWeek(java.util.Calendar.MONDAY);
cal.set(java.util.Calendar.WEEK_OF_YEAR, weekNr);
// create message for service and pass that date to getDayForecast
GetDayForecastRequestMessage gdfr = new GetDayForecastRequestMessage();
gdfr.setTheDate(cal.getTime());
setGetDayForecastRequest(gdfr);
Chapter 17. Application Developer Integration Edition
363
extractDegrees—Extract the temperature out of the Weather object and pass
it to the convertCelsiusToFahrenheit method:
// get the weather response of getDayForecast
Weather w = getGetDayForecastResponse().getResult();
// extract the temperature
int degreeCelsius = w.getTemperatureCelsius();
// create new message and pass temperature to convert
ConvertCelsiusToFahrenheitRequestMessage request = new
ConvertCelsiusToFahrenheitRequestMessage();
request.setCelsius(degreeCelsius);
setConvertCelsiusToFahrenheitRequest(request);
traceResults—Trace the results and set the output value of the process:
Weather w = getGetDayForecastResponse().getResult();
System.out.println("traceResult: result of forecast weather="
+w.getDate()+"/"+w.getTemperatureCelsius()+"/"+w.getCondition());
int degreesCelsius =
getGetDayForecastResponse().getResult().getTemperatureCelsius();
int degreesFahrenheit =
getConvertCelsiusToFahrenheitResponse().getResult();
System.out.println("traceResult: result of Fahrenheit Calculator="
+degreesCelsius+"-->"+degreesFahrenheit);
// set output value
org.xmlsoap.schemas.wsdl.wsadie.messages.IntMessage outmsg =
new org.xmlsoap.schemas.wsdl.wsadie.messages.IntMessage();
outmsg.setValue(degreesFahrenheit);
setOutput(outmsg);
In the snippets we use short names for the Java classes. To remove error
messages, we have to add import statements to the class:
Select the empty canvas to see the Java import statements.
Add these statements:
import
import
import
import
import
wsdl.itso.wsoj.WeatherForecast_msg.*;
wsdl.itso.wstc.TemperatureCalculator_msg.*;
java.util.Calendar;
java.util.Date;
itso.wsoj.Weather;
Save the process. Only one warning remains in the Tasks view, indicating that
the input node requires an operation.
Important: Whenever you add custom code into a Java snippet or another
method in the process class, be sure to add your code only within the
comments user code begin and user code end. Code in other places is
removed without any notice whenever the process class is regenerated.
364
WebSphere Version 5.1 Web Services Handbook
Defining the process interface
The process is almost complete. The remaining step is to define the interface for
the overall business process, which is again done using a WSDL file. Integration
Edition generates the remaining information required to build the WSDL file.
The context menu of the Input node provides the Generate WSDL interface
selection:
This window offers options for the interface definition, for example, whether it
is a synchronous or asynchronous service:
– For synchronous service, the process is called and right after execution it
returns a result message to the caller.
– For asynchronous service, the call returns nothing, and the client is
responsible for querying the result later on. The asynchronous model
offers a large amount of flexibility but also requires a more complex
programming model on the client side.
On the second wizard page you can choose the interface definitions, such as
port type and operation, which should be used for this process.
In our example all the defaults are fine. You will have to regenerate this interface
whenever the interface of the process has changed, but not if the internals of the
process have changed.
A temperatureInterface.wsdl file is generated into the itso.wsie package
(Figure 17-15) and more Java code is added to the process class.
<?xml version="1.0" encoding="UTF-8"?>
<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 17-15 WSDL interface file of the business process
Chapter 17. Application Developer Integration Edition
365
Generate deploy code
The process is now completely defined, but there is a final step to do prior to
deploying the process to an application server. When you deploy a business
process, you generate the code necessary to make the process available as a
service on the application server.
Figure 17-16 Generate deployed code for a process
The Deployment Code wizard is started by selecting Enterprise Services ->
Generate Deploy Code in the context menu of the process file (Figure 17-16).
Within the wizard you can first choose to create a new port or use an existing
port. The choice depends on whether this is a brand new service (our case),
or if you have already deployed the service beforehand.
Another option is to choose the binding for this service. Remember that
Application Developer (not Integration Edition) only supports Web services
using SOAP/HTTP binding. Integration Edition also supports EJB and JMS
366
WebSphere Version 5.1 Web Services Handbook
bindings and therefore calls the services enterprise services. In our sample
we create a SOAP binding, so any client can call the business process using
the SOAP/HTTP protocol.
You can go through all the pages of the wizard to see what WSDL files are
generated and what options you can choose. Click Finish to generate.
The wizard creates an EJB as implementation for the business process and
defines the binding as chosen. Therefore new projects are created, such as an
EJB (ItsoWebServBPServiceEJB) and a Web (ItsoWebServBPServiceWeb) project.
The Services view in the Business Integration perspective now displays a second
section called Deployed Services, where you can find these generated projects
with the appropriate EJB that implements the process behavior (Figure 17-17).
Process
WSDL
interface
binding
service
Figure 17-17 Deployable services
Explore the ItsoWebServBPServiceEJB and ItsoWebServBPServiceWeb projects
and study the generated code.
Chapter 17. Application Developer Integration Edition
367
Flow definition markup language
Flow definition markup language (FDML) is used to describe the flow of a
business process. FDML was introduced in “Flow definition markup language” on
page 163.
For our sample business process, the FDML file is named temperature.fdml. In
this section we look at extracts of the FDML file.
Start
The file starts with:
<?xml version="1.0" encoding="UTF-8"?>
<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>
368
WebSphere Version 5.1 Web Services Handbook
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:output messageType="MessageType_6" name="out"/>
<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:output messageType="MessageType_3" name="out"/>
<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>
Chapter 17. Application Developer Integration Edition
369
Testing a business process in the test environment
To test the process, you have to create a server of type WebSphere Enterprise
Edition; only the Enterprise Edition can run business processes.
Create a server project named Servers. Then create a server and configuration
named ProcessServer and select WebSphere version 5.0 -> EE Test
Environment. This process adds two enterprise applications to the workspace:
BPEContainer, with three modules (one is a Web client Web project)
BPERemoteDeploy, with two modules (one is a SOAP client Web project)
Add the two EAR files of our process and Web services to the server:
ItsoWebServBaseEAR—Which runs the weather forecast and temperature
conversion services (ItsoWebServWFWEB and ItsoWebServTCWEB)
ItsoWebServBPEAR—Which holds the business process
Every time the process is changed, you have to redeploy it. In the Servers view,
select Deploy Process in the context menu of the EE Server (Figure 17-18).
Figure 17-18 Deploy process and run test client
Start the server. You should not get any exceptions and stack traces in the
console.
Web service client
To test the process you can create a client using the new WSDL files that were
generated for the process. This is exactly the same as generating a proxy and a
test or real client application as for any other Web service.
However, there is an easier way.
370
WebSphere Version 5.1 Web Services Handbook
Business process Web client
An easier way to test a process is to use the business process Web client, which
is similar to the universal test client (UTC) for EJBs. Using this tool, you do not
have to write a client or even a proxy object.
Select Run Process Web client in the context menu of the server (Figure 17-18),
or by just calling the URL http://localhost:8080/bpe/webclient.
A welcome page appears where you can select Open the work item manager or,
if you wait, the work item manager opens automatically (Figure 17-19).
Figure 17-19 Web client welcome page
The list of work items is displayed, but it is empty in our case.
If you have deployed the temperature process, it appears in the Templates
drop-down list. Select one of the templates (there is only one now) and click
Start, and the process description and input field is displayed (Figure 17-20).
Enter a value for the week number and click Start Process. A result page should
present the result object or an exception if something went wrong.
Note: Although the business process Web client can be used to start business
process instances, its primary function is for viewing and interacting with work
items created for a staff activity. Asynchronous business processes started in
the Web client will not invoke their one-way operations specified for the output
and fault activities. Interaction with events is also something that is not
possible from within the Web client. Support for these two items is available
through a proxy test client.
Chapter 17. Application Developer Integration Edition
371
13
Figure 17-20 Using the business process Web client to test processes
Server configuration
When defining a WebSphere Version 5.0 EE Test Environment server, the
configuration automatically includes two EAR projects: BPEContainer and
BPERemoteDeploy.
If you open the server configuration on the Data source page, you find that a
Cloudscape™ JDBC provider (BPEJdbcDriverCloudscape) and a data source
(BPEDataSourceCloudScape) have been defined. This data source is used by the
372
WebSphere Version 5.1 Web Services Handbook
business process container to maintain its state. Cloudscape is a complete Java
SQL database (shipped with WebSphere) with a small overhead and low amount
of administration, making it ideal for a testing environment.
On the JMS page, you find a set of queues registered and that the JMS server is
started. These queues are also used by the process container.
Do not forget to invoke Deploy Process (Figure 17-18 on page 370) before
testing business processes.
Configuring a remote WebSphere Application Server
Note that you must have WebSphere Application Server 5 Enterprise Edition to
run business processes.
First you have to start the server and install all the necessary EAR projects of
your application. If you want to use the server for debugging, you have to
configure the debug mode for the application server:
Start the Administrative Console and navigate to Servers -> Application
Servers.
On the Configuration tab select Debugging Service and make sure that
Startup is selected.
For the JVM debug port enter 7777, and for the JVM debug arguments make
sure that the address entry shows 7777 (Figure 17-21).
Figure 17-21 Configure debugging options in WebSphere Enterprise Edition
Because you normally step quite slowly through the code, it is necessary to
turn off the transaction time-outs. Therefore, select Additional Properties ->
Transaction Services and change the Total transaction lifetime time-out to 0.
Save the configuration and restart the server to make the changes effective.
In the debugger you can then attach to the server process as described
below.
Chapter 17. Application Developer Integration Edition
373
Debugging business processes
A business process is executed on a higher level than Java code. To examine the
execution flow of a business process, the process debugger can be used to
step through the different activities that make up a business process. The
debugger can also be used to step into the Java code, if available.
The architecture for the process debugger is the same as for debugging or
profiling a Java application. You can easily debug applications that run within the
Integration Edition.
Furthermore, you can use the IBM Agent Controller to debug applications that
run on a remote WebSphere Application Server Enterprise.
Setting breakpoints
To stop somewhere in the process, you have to set breakpoints. You can set
breakpoints anywhere in your Java code, and you can also set them in your
process:
Select Add Breakpoint in the context menu of a control link.
Select Add Breakpoint Before/After Activity in the context menu of an activity.
Start debugger
Start the server in debug mode and the Debug perspective opens.
After the server is started in debug mode, it is started in the step-by-step mode,
which means that the execution is paused as different objects or components
within the server are called. Whenever a new step is started, a window prompts
you for further execution. You can decide to step into or skip a certain step. There
is also the possibility to select Disable step-by-step mode and stop at breakpoints
only.
Start the process Web client and start the process. Execution stops at
breakpoints. Figure 17-22 shows the Debug perspective with execution stopped.
Note: The regular Debug perspective does not honor breakpoints set in the
process; only breakpoints set in the Java code of the process are honored. To
debug at the process level, you have to use the Process Debug perspective.
374
WebSphere Version 5.1 Web Services Handbook
Breakpoint
Figure 17-22 Debug perspective
Process debugging
There is a new Process Debug perspective that can be used for high-level
debugging of the business processes.
Open the Debug Process perspective (after the server has been started in debug
mode). Then click the Attach to Process Engine icon ( ) and a window opens.
Select the host to which to connect; for debugging in your own machine select
localhost. Select the server process and click Finish.
You can start a business process by starting an appropriate action in the Web
client. You can also start a business process from the Process Debug view.
There you find Create Process Instance in the context menu of all processes.
Since your process in general requires input parameters, you will be prompted in
the Web browser.
Chapter 17. Application Developer Integration Edition
375
Figure 17-23 shows the Process Debug perspective with execution stopped at a
process breakpoint. Notice the process breakpoint in the graphical view and in
the Process Breakpoints view. The Process Variables view is hidden behind the
Process Breakpoints view.
Step over activity
Step into Java
Stopped here
Figure 17-23 Process Debug perspective
Using the debugger
Similar to the Java Debugger, there are controls to step over activities. Note that
you work at an activity level in stepping mode, and every step is one complete
activity.
If you want to do more detailed debugging, you can step into the Java code and
debug at that level. You can then switch between the Process Debug perspective
and the Debug perspective (Java code).
You can also watch any variables that are defined in the process. Figure 17-24
shows the Variables view at two breakpoints, just after beginning the process and
before ending.
376
WebSphere Version 5.1 Web Services Handbook
Figure 17-24 Process variables in debug mode
In the Process Debug view, you can detach the process using the context menu.
Afterwards you can stop the server.
Deployment to an application server
You can deploy the business process as a Web service to an application server.
You package the EAR file as you would do with any other enterprise application.
In that EAR file, you will find the implementation EJB and WAR modules, as well
as an additional utility JAR that holds all the business process-relevant data.
Note that you can only deploy and run business processes on WebSphere
Application Server Enterprise Edition.
Deployment to WebSphere Application Server is covered in Chapter 20, “Web
services runtime and deployment in WebSphere” on page 479. However, we did
not install the Enterprise Edition for deployment of the process application.
Chapter 17. Application Developer Integration Edition
377
Importing the process solution
We provide the files of our solution in the directory:
sg246891-01\sampcode\wsadie\zSolution
Importing the projects
We provide the ItsoWebServBPServiceEAR project and the contained projects in
an EAR file that you can import:
Select File -> Import -> EAR File, and click Browse to locate the file:
sg246891-01\sampcode\wsadie\zSolution\ItsoWebServBPServiceEAR.ear
Enter ItsoWebServBPServiceEAR as the project name.
Select Create a new Java project defined as a utility JAR or web library and
Expanded: extract project contents for development.
Click Finish.
You will see many errors in the Tasks view because the Java build path is not
imported correctly and the service project is not recognized.
To fix the errors in the projects, a number of steps are required.
Web project
For the Web project:
Select the ItsoWebServBPServiceWeb project and Import -> File system.
Locate the directory:
sg246891-01\sampcode\wsadie\zSolution\Web
Import the .classpath file (select Overwrite existing resources without
warning).
Delete the itso folder under Java Source.
Select the project and Rebuild Project.
EJB project
For the EJB project:
Select the ItsoWebServBPServiceEJB project and Import -> File system.
Locate the directory:
sg246891-01\sampcode\wsadie\zSolution\EJB
Import the .classpath file (select Overwrite existing resources without
warning).
378
WebSphere Version 5.1 Web Services Handbook
Service project
For the Service project:
Delete the ItsoWebServBPService project completely (it was not recognized
as a service project).
Create a service project with the name ItsoWebServBPService.
Select File -> Import -> Zip file. Locate the file:
sg246891-01\sampcode\wsadie\zSolution\ItsoWebServBPService.jar
Select Overwrite existing resources without warning and click Finish.
EAR project
For the EAR project:
Open the deployment descriptor (application.xml) of the
ItsoWebServBPServiceEAR project.
Make sure that the ItsoWebServBPService.jar file is listed under Project
Utility JARs on the Module page.
Defining the server
Create a server project (Servers) and an EE test server (ProcessServer) as
described in “Testing a business process in the test environment” on page 370.
Add the two EAR files (ItsoWebServBPServerEAR and ItsoWebServBaseEAR) to the
server configuration.
Test the process sample
Select the ProcessServer in the Servers view and Deploy Process (context).
Start the server, then select Run Process Web client (context) and run the
application.
Chapter 17. Application Developer Integration Edition
379
Summary
WebSphere Studio Application Developer Integration Edition adds significant
features to the base Application Developer product, especially in the area of Web
services.
The concept of enterprise services allows services to be not only available
through SOAP over HTTP, but uses the Web services invocation framework to
offer several invocation scenarios for a service, including EJB, JMS, and native
invocations. The implementation of such enterprise services is hidden from a
client and the invocation is therefore completely transparent to a client.
The Business Integration perspective with all its views and editors enables a
graphical modeling of complex workflows that combine other services and/or
Java code into a business process. The business processes can be exposed
again as enterprise services that are used by clients or other business processes
as a single activity.
The enhanced WSDL editor provides for easy manipulation of WSDL documents
that are stored in multiple files.
More information
Refer to the online help in WebSphere Studio Application Developer Integration
Edition for further information about those topics. There are many concepts
described and well-documented examples show you how to implement and test
enterprise services and workflows.
380
WebSphere Version 5.1 Web Services Handbook
18
Chapter 18.
WebSphere SDK for Web
Services
In this chapter we introduce the IBM WebSphere SDK for Web Services (WSDK),
Version 5.1, which enables early adopters to create and test Java-based Web
services applications. This entry-level developer kit contains everything in a
single, convenient package.
The WSDK is based on open specifications for Web services, such as SOAP,
WSDL, and UDDI; conforms to the WS-I organization's Basic Profile 1.0; and
runs on Windows and Linux operating systems.
In this chapter, first, we explain the differences between the different packages
for developing Web services for WebSphere Application Server. Second, we
describe the IBM WebSphere SDK for Web Services (WSDK) and how to use it
to build our sample weather forecast Web services.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
381
The difference between the packages
There is some confusion about the different packages for developing Web
services for WebSphere Application Server:
For WebSphere Application Server Version 5.0, there were three packages:
– WebSphere SDK for Web Services
– Technology Preview
– Web Services Toolkit (WSTK)
For WebSphere Application Server Version 5.1, there are two packages:
– WebSphere SDK for Web Services
– Emerging Technologies Toolkit (ETTK), replacing WSTK
WebSphere SDK for Web Services (WSDK) provides developer tools and a
runtime environment for designing and executing Web service applications that
are consistent with the industry-standard platform for Web services and the
emerging standard for interoperability defined by the Web Services
Interoperability Organization (WS-I). Such applications can discover and
collaborate in business transactions without programming requirements or
human intervention. WSDK uses the WebSphere SOAP engine and is based on
JAX-RPC (JSR 101—see Chapter 4, “JAX-RPC (JSR 101)” on page 67) and on
Web services for J2EE (JSR 109—see Chapter 5, “Implementing Enterprise
Web Services (JSR 109)” on page 77).
The Emerging Technologies Toolkit (ETTK)—formerly known as the Web
Services Toolkit (WSTK)—delivers to developers early implementations of new
technologies using Web services, and acts as a consolidator of Web services
technologies from various IBM development and research labs. Unlike WSDK,
the ETTK does not have an embedded application server or a private UDDI
registry. The WSDK is therefore ideal for testing services applications developed
with ETTK. ETTK is based on the Axis programming model.
We can use WSDK without ETTK to develop industry-standard Web services
applications, or we can use it with ETTK if we want to explore the latest emerging
technologies, such as grid computing, that (can) use Web services.
ETTK Version 1.2 contains service data objects (SDO), policy-based IT
management demo, semantic Web services, autonomic computing toolset,
WS-Manageability demo, WS-Trust, WS-Addressing, Web services failure
recovery, and service domain technology.
For more information on ETTK, go to:
http://alphaworks.ibm.com/tech/ettk
382
WebSphere Version 5.1 Web Services Handbook
WebSphere SDK for Web Services Version 5.1
The IBM WebSphere SDK for Web Services (WSDK) provides developer tools
and a runtime environment for designing and executing Web service applications
that are consistent with the industry-standard platform for Web services and the
emerging standard for interoperability defined by the Web Services
Interoperability Organization (WS-I). We can use the WSDK to demonstrate the
interoperability of Web services between the IBM WebSphere J2EE-based
platform and platforms provided by other suppliers, for example, Microsoft .NET.
The functionality of the WSDK is based on open specifications such as SOAP,
WSDL, and UDDI, and the current release runs on both Linux and Windows
operating systems.
The WSDK is not a product. It is a free-of-charge IBM technology offering that
enables development and testing of Java-based Web services as an entry-level
developer kit. It is important to note that WSDK is not licensed for running
production applications or redistribution.
The WSDK contains:
An embedded version of IBM WebSphere Application Server Express,
Version 5.0.2 with additional support for ORBs and EJBs.
– Support for SOAP 1.1, WSDL 1.1, UDDI 2.0, JAX-RPC 1.0 (JSR 101),
EJB 2.0, Enterprise Web Services (JSR 109) 1.0, WSDL4J, UDDI4J, and
WS-Security.
– A private UDDI Version 2 registry.
– An entry-level database providing a JDBC implementation.
– IBM SDK for Java Technology, Version 1.3.1.
– Support for the Java Messaging Service (JMS) API and Message Driven
Beans (MDB). These functions are not intended for general use and they
have only been tested in the context of the WS-I Supply Chain
Management (SCM) sample.
Plug-ins for Eclipse Version 2.1.1. Installing the plug-ins into the plugins
directory of an Eclipse installation is an option when WSDK 5.1 is installed.
See “Installation of WebSphere SDK for Web Services 5.1” on page 523.
Tools to enable JavaBeans and stateless session EJBs as Web services, to
create Web services from WSDL definitions, and to publish and unpublish
Web services to a UDDI registry.
Comprehensive documentation including Web services concepts, developer
tasks, and reference materials.
Chapter 18. WebSphere SDK for Web Services
383
Samples showing how to enable JavaBeans and stateless session EJBs as
Web services, create Web services from WSDL definitions, publish,
unpublish, and look up Web services using UDDI, and create secure Web
services using the WS-Security specification.
Application server
The application server includes a private UDDI registry, used for publishing and
discovery of Web services using the UDDI protocols. The UDDI registry itself
runs as an enterprise application (EAR) within the application server.
The application server provided with WSDK 5.1 is based on WebSphere
Application Server Version 5.0.2. It is a J2EE-based server that provides the
functions of an HTTP Web server, a servlet engine, and an EJB container.
It also provides Web services capabilities based on the standards defined for
J2EE, namely JAX-RPC as defined by JSR 101, and the integration of Web
services with the J2EE server as defined by JSR 109. The application server
also includes IBM Java SDK Version 1.3.1, which is used to run the server itself,
and is also used to build and run client-side Java applications.
Tools
The WSDK provides utility tools (in <WSDK-home>/bin) that allow us to enable,
deploy, and publish J2EE applications:
Bean2WebService—Creates a fully deployable Web service from a Java
class and optionally deploys it to the application server
EJB2WebService—Creates a fully deployable Web service from a stateless
session EJB contained in an EJB module (contained in an EAR file) and
optionally deploys it to the application server
WSDL2WebService—Creates a fully deployable Web service from one or
more WSDL documents and optionally deploys it to the application server
WSDL2Client—Generates fully-deployable Web service clients from one or
more WSDL documents and optionally deploys them to the application server
UDDIPublish—Publishes a business entity or a business service to a public
or a private UDDI registry
UDDIUnpublish—Removes a business entity or a business service from a
public or a private UDDI registry
384
WebSphere Version 5.1 Web Services Handbook
In addition to the Web services development tools, WSDK provides tools to
monitor Web services and to administer the included application server:
tcpmon—Monitors and displays Web service messages (SOAP messages)
that are exchanged between a Web service client and a Web service server
appserver—Provides basic and Web services related administration
functions of the application server, such as starting and stopping the server,
installing and uninstalling Web services, and listing all installed Web services
setProxy—Configures HTTP proxy information for the WSDK tools and
runtime server
Note: WSDK 5.1 provides an Eclipse plug-in to create Web services with
graphical wizards in an Eclipse environment. See “Using the WSDK plug-in for
Eclipse” on page 416.
Documentation
WSDK documentation is divided into five main sections under IBM WebSphere
SDK for Web Services:
Getting started with WSDK—This section provides tailored learning paths
with different learning objectives, from Web services basics to an architectural
view.
Concepts—This section talks about the Web services technologies, such as
XML, SOAP, WSDL and UDDI. It also explains WS-Security, the Web services
architecture, and the J2EE specifications for Web services.
Tasks—This section explains how to Web service-enable J2EE applications,
or implement an existing Web service from its WSDL document. It also tells
how to secure Web services applications and develop several types of Web
services clients.
Reference—This section contains the reference materials for the tools
shipped with the WSDK, the API documentation, and a troubleshooting guide.
Samples—This section describes the nine Web services samples shipped
with the WSDK, tells how to run them, and what their expected behavior is. It
also includes a step-by-step guide to rebuilding the samples.
To access the documentation for WSDK, use the wsdkHelp command, located in
the <WSDK-home>/bin directory, or click the WSDK Help icon.
Chapter 18. WebSphere SDK for Web Services
385
Sample applications
There are nine sample applications located in <WSDK-home>/apps. These sample
applications cover a range of scenarios for Web services, include code for both
provider (server side) and requestors (client side), and also have examples of
publishing and finding Web services using UDDI. They are:
Sample 1—A request-response Web service created from a JavaBean and a
Web service requestor using the JAX-RPC service locator. Sample 1 also
demonstrates split WSDL.
Sample 2—A request-response Web service created from a session
enterprise bean and three Web service requestors for it:
– A J2EE client running in the WebSphere client container and using JNDI.
– A J2EE EJB client running in the EJB container and using JNDI.
– A J2SE client running as a stand-alone application and using the
JAX-RPC ServiceFactory.
Sample 3—Publishes and then unpublishes sample 1's Web service using
the UDDI registry publish API.
Sample 4—Demonstrates dynamic discovery and invocation of Web services
using the UDDI registry inquiry API.
Sample 5—Demonstrates the use of complex types in Web services.
Sample 6—A one-way Web service implemented as a JavaBean from a
WSDL document.
Sample 7—Demonstrates how headers and faults are handled by SOAP and
WSDL.
Sample 8—Demonstrates WS-Security digital signature, encryption,
authentication, and ID assertion.
Sample 9—Demonstrates a third-party client, a Visual Basic .NET client, that
invokes a WSDK-developed Web service.
The sample applications are already built and deployed to the application server
so that we can run them as soon as we have installed WSDK.
Note: Even though the WSDK comes with nine comprehensive samples, we
provide an additional, very simple and small sample to see the individual
WSDK tools at work. This sample is a String service that returns an input
argument string in all uppercase.
386
WebSphere Version 5.1 Web Services Handbook
WS-Security in WSDK
The WSDK implements the WS-Security elements shown in Table 18-1.
Table 18-1 WS-Security elements implemented in WSDK
Element
Notes®
<UsernameToken>
Both user name/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 18-1 shows the overall architecture of the WS-Security implementation in
the WSDK.
Figure 18-1 WS-Security implementation in WSDK
Chapter 18. WebSphere SDK for Web Services
387
Using the tools
In this section we describe the development tools provided with the WSDK. For
the installation see “Installation of WebSphere SDK for Web Services 5.1” on
page 523. For the WSDK installation root directory, we suggest d:\WSDK51.
For the command line examples we use the directory c:\wsdk51sample.
Bean2WebService
The Bean2WebService tool generates a fully deployable Web service from a Java
class, and optionally deploys it on the application server.
Generation steps explained
The automatic process followed by the command tool to generate the Web
services is shown in Figure 18-2.
J2EE EAR
WebSphere
5.0.2
J2EE WAR file
Deploy the EAR
J2EE EAR
JavaBean
8
WS DD
J2EE WAR file
WSDL
JavaBbean
WS DD
SEI class
WSDL
SEI class
Package WAR in
EAR
7
Javabean added
as part of web.xml
6
J2EE WAR file
J2EE WAR file
Add SEI, WSDL,
WS-DD to WAR
JavaBean
JavaBean
Copy in WEB-INF/ dir
WS DD
CONFIGURED
WSDL
WebServices DD
IBM binding
SEI class
1
Copy in WEB-INF/ dir
2
JavaBean
Javabean in
WAR package
Manually create
Service
endpoint
interface
class
(SEI)
Java2WSDL
5
4
3
WSDL
WSDL2Java
WebServices DD
IBM binding
Options "-META-INF-Only
-server-side Bean"
Figure 18-2 Process to create a Web service from a JavaBean (bottom-up)
388
WebSphere Version 5.1 Web Services Handbook
In brief, the steps are:
Step 1—Take the Java bean that will be available as a Web service.
Step 2—Create the SEI Java code from the Java bean with the methods that
will be exposed in the Web service.
Step 3—Generate the WSDL from the SEI with the Java2WSDL command.
Step 4—Generate the Web service deployment descriptor templates from the
WSDL with the WSDL2Java command.
Step 5—Configure the Web service deployment descriptor. Modify the
<servlet-link> tag in webservices.xml with the value of the <servlet-name>
tag in the web.xml file.
Step 6—Assemble all the files previously generated in a WAR file:
– Add the SEI file to the WAR file.
– Add the WSDL to the WAR file in the WEB-INF directory.
– Add the Web services and IBM binding deployment descriptors to the
WEB-INF directory.
Step 7—Assemble the WAR file in an enterprise application (EAR) file.
Step 8—Deploy the application on WebSphere Application Server Version
5.0.2.
Sample setup
To see the tool at work we use the simple StringService example:
Create a beanSrc directory in the c:\wsdk51sample directory.
Copy the StringService.java file (Example 18-1):
from: sg246891-01\sampcode\wsdk51\sample\beanSrc
to:
c:\wsdk51sample\beanSrc
Example 18-1 StringService example
public class StringService {
public StringService() {}
private String lowercase(String str) { return str.toLowerCase(); }
public String uppercase(String str) { return str.toUpperCase(); }
public static void main(String[] args) {
StringService stringService = new StringService();
System.out.println(stringService.lowercase(args[0]));
System.out.println(stringService.uppercase(args[0]));
}
}
Note that one method is private, and one is public. The private method returns
the argument string in all lowercase, and the public in all uppercase.
Chapter 18. WebSphere SDK for Web Services
389
To verify and prepare the service example class, open a command window, set
up the environment, compile the class, and run the program using the following
command sequence:
c:
cd \wsdk51sample\beanSrc
d:\<WSDK-home>\bin\setupEnv
javac StringService.java
java StringService Abc
d:\wsdk51\bin\setupEnv
The output should look like:
abc
ABC
Bean2WebService at work
To experiment with the Bean2WebService tool we run the tool on the simple
StringService bean:
cd \wsdk51sample
d:\<WSDK-home>\bin\setupEnv
Bean2WebService [options] -cp <ClassPath> -project <ProjectName> <BeanName>
Bean2WebService -verbose -cp .\beanSrc
-project beanProj
StringService
Note: Use Bean2WebService -help to see a short explanation of all the
options. The WSDK Help facility has more detailed information.
-cp is a list of absolute or relative path and file names.
-project must be a valid directory name.
The command window output is shown in Example 18-2, where ~ stands for
c:\wsdk51sample.
Example 18-2 Bean2WebService command output
Creating new project: beanProj ...
Removed all existing classes from directories under ~\beanProj\WEB-INF\classes\
Generating the service endpoint interface...
Generating WSDL:
WSWS3010I: Info: Generating
portType {http://DefaultNamespace}StringService
message {http://DefaultNamespace}uppercaseRequest
message {http://DefaultNamespace}uppercaseResponse
binding {http://DefaultNamespace}StringServiceSoapBinding
service {http://DefaultNamespace}StringServiceService
port StringService
Generating server side files:
WSWS3185I: Info: Parsing XML file: ~\beanProj\WEB-INF\wsdl\StringService.wsdl
WSWS3282I: Info: Generating
~\beanProj\DefaultNamespace\StringService.java.
~\beanProj\DefaultNamespace\StringServiceSoapBindingImpl.java.
390
WebSphere Version 5.1 Web Services Handbook
~\beanProj\WEB-INF\webservices.xml.
~\beanProj\WEB-INF\ibm-webservices-bnd.xmi.
~\beanProj\WEB-INF\ibm-webservices-ext.xmi.
~\beanProj\WEB-INF\StringService_mapping.xml.
Configuring webservices.xml...
~\beanProj\WEB-INF\wsdl\StringService.wsdl
Added web module with context root: beanProj
Web Service archive "file:~/beanProj/beanProj.ear" has been successfully generated.
Generating client side files:
WSWS3185I: Info: Parsing XML file: ~\beanProj\WEB-INF\wsdl\StringService.wsdl
WSWS3282I: Info: Generating
~\beanProj\client-side\DefaultNamespace\StringServiceService.java.
~\beanProj\client-side\DefaultNamespace\StringServiceServiceLocator.java.
~\beanProj\client-side\DefaultNamespace\StringService.java.
~\beanProj\client-side\DefaultNamespace\StringServiceSoapBindingStub.java.
~\beanProj\client-side\META-INF\webservicesclient.xml.
~\beanProj\client-side\META-INF\ibm-webservicesclient-bnd.xmi.
~\beanProj\client-side\META-INF\ibm-webservicesclient-ext.xmi.
~\beanProj\client-side\META-INF\StringService_mapping.xml.
Creating client-side build script...
All done.
The main output of the Bean2WebService tool is the <ProjectName>.ear file in the
root of the generated directory structure named <ProjectName>. The project
structure is shown in Figure 18-3:
The EAR file contains a fully deployable Web service.
The WEB-INF directory holds the server-side Web project information:
– Deployment descriptor
– Java classes
– WSDL file
Because we did not specify the -server-side-only option, a client-side
directory is generated with:
– Proxy classes (in DefaultNamespace)
– Deployment descriptor
– WSDL file
Look into the generated files, especially the StringService.wsdl and
StringService_SEI.java (service endpoint interface) files. Notice that by default
they include the public (and non-static) methods of the StringServices.java
class.
Chapter 18. WebSphere SDK for Web Services
391
c:\wsdk51sample
beanSrc
StringService.java
StringService.class
beanProj
beanProj.ear
WEB-INF
<=== server-side
webservices.xml
ibm-webwebservices-bnd.xml
ibm-webwebservices-ext.xml
StringService_mapping.xml
client-side
buildclient.bat
classes
StringService.class
StringService_SEI.java
StringService_SEI.class
lib
wsdl
StringService.wsdl
DefaultNamespace
StringService.java
StringServiceService.java
StringServiceServiceLocator.java
StringServiceSoapBindingStub.java
META-INF
webservicesclient.xml
ibm-webwebservicesclient-bnd.xml
ibm-webwebservicesclient-ext.xml
StringService_mapping.xml
wsdl
StringService.wsdl
Figure 18-3 Bean2WebService project structure
Command line help and options
The Bean2WebService command has many useful options:
-methods <method1 method2... methodN>— Allows to define the subset of the
public methods that should be exposed as Web services.
-deploy—Deploy the generated EAR file into the application server.
-server-side-only—Do not generate client-side files.
-genMain <mainclass> and -clientType <Application|EJB|J2SE|Servlet>—
Generate a main client class and implementation template.
-style <RPC|DOC|WRAPPED>—WSDL style, RPC or DOCUMENT, WRAPPED (default)
is a special document style.
-use <LITERAL|ENCODED>—Encoding (LITERAL by default).
-splitWsdl—Generate separate interface and binding files.
-wsSecDir <directory>—Directory for deployment descriptors configured for
security.
392
WebSphere Version 5.1 Web Services Handbook
EJB2WebService
The EJB2WebService tool generates a fully deployable Web service from a
stateless session EJB contained in an EAR file, and optionally deploys it to the
application server. Note that only Version 2.0 of the EJB architecture is
supported.
To use EJB2WebService, open a command window and enter:
cd <WSDK-home>\bin
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, and optionally a client-side directory is
generated with the extra files for client development.
The automatic process followed by the command tool to generate the Web
service is shown in Figure 18-4:
Step 1—Take the stateless session bean that will be available as a Web
service.
Step 2—Create the SEI Java code from the EJB with the methods that will be
be exposed in the Web service.
Step 3—Generate the WSDL from the SEI with the Java2WSDL command.
Step 4—Generate the Web service deployment descriptor templates from the
WSDL with the WSDL2Java command.
Step 5—Configure the Web service deployment descriptor. Modify the
<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
Step 7—Assemble the EJB JAR in an enterprise application (EAR).
Step 8—Create the Web service endpoint Web module WAR. Use the
command endptEnabler and answer the prompts.
Step 9—Deploy the application into WebSphere Application Server Version
5.0.2.
Chapter 18. WebSphere SDK for Web Services
393
J2EE EAR
J2EE EAR
8
EJB Jar
EJB Jar
endptEnabler
EJB
J2EE WAR
Enable
WsRouterServlet
EJB
WebSphere
5.0.2
9
WS DD
WS DD
Install
EAR
WSDL
WSDL
SEI class
SEI class
J2EE EAR
EJB Jar
EJB
J2EE WAR
Enable
WsRouterServlet
WS DD
7
WSDL
Package EJB Jar
in EAR
SEI class
6
EJB Jar
EJB Jar
Add SEI, WSDL,
WS-DD to EJB Jar
EJB
EJB
Copy in META-INF/ dir
WS DD
CONFIGURED
WSDL
WebServices DD
IBM binding
SEI class
1
Copy in META-INF/ dir
2
EJB
Stateless
Session Bean
Manually create
Service
endpoint
interface
class
(SEI)
3
Java2WSDL
5
4
WSDL
WSDL2Java
WebServices DD
IBM binding
Options "-META-INF-Only
-server-side EJB"
Figure 18-4 Process to create a Web service from an EJB (bottom-up)
WSDL2WebService
The WSDL2WebService tool generates, in three stages, fully deployable Web
services from one or more WSDL documents and optionally deploys them on the
application server.
Generation stages explained
The automatic process followed by the command tool to generate the Web
service is shown in Figure 18-5.
394
WebSphere Version 5.1 Web Services Handbook
J2EE EAR
WebSphere
5.0.2
EJB WAR
Jar
J2EE
EJB
JavaBean
WS
DD
WS DD
J2EE EAR
6
WSDL
WSDL
J2EE WAR
JavaBean
SEI class
class
SEI
WS DD
WSDL
SEI class
5
4
Stage3
J2EE WAR
JavaBean
WS DD
WSDL
CONFIGURED
SEI class
WebServices DD
IBM binding
3
Stage1
Stage2
1
WSDL
WSDL2Java
Options "-server-side Bean"
*SEI
*Web service implementation
Java Bean template
*WS DD + Binding
Implement Web
service from template
JavaBean
2
Figure 18-5 Process to create a JavaBean Web service from a WSDL (top-down)
In brief, the stages and steps are:
Stage 1—Step 1—Generate the Web service deployment descriptor
templates and the implementation files from the WSDL using the WSDL2Java
command.
Stage 2—Step 2—Complete the implementation of the bean.
Stage 3:
– Step 3—Configure the Web service deployment descriptor. Modify the
<servlet-link> tag in webservices.xml with the value of the
<servlet-name> tag in the web.xml.
– Step 4—Assemble all the generated files in a WAR:
•
•
•
•
Java bean as a servlet in the web.xml
SEI class
WSDL in the WEB-INF directory
Web services IBM binding deployment descriptor into META-INF
– Step 5—Assemble the WAR into an enterprise application (EAR).
Chapter 18. WebSphere SDK for Web Services
395
– Step 6—Deploy the application into WebSphere Application Server
Version 5.
Sample setup
To see the tool at work, we use the WSDL file generated for the StringService
sample:
Create a wsdlSrc directory in the wsdk51sample directory.
Copy the StringService.wsdl file into the directory. Take the file from the
previous example, or copy from:
sg246891-01\sampcode\wsdk51\sample\wsdlSrc
WSDL2WebService at work
The three stages reviewed:
Stage 1—Run the tool with the -createService argument to create skeleton
Java implementation templates for a Web service described by a particular
WSDL document.
Stage 2—Write the implementation code in the templates and compile it using
the compile script generated in stage 1.
Stage 3—Run the tool again with the -createEar argument to build a Web
service-enabled archive from this implementation, and deploy it to the
application server.
Note that we can perform stage 1 several times to create related Web services in
the same project directory. In stage 3 we can then create a separate module for
each of these Web services and add them to the same EAR file.
Stage 1—Creating a Web service implementation skeleton
To create a skeleton Web service implementation, open a command window and
enter:
cd wsdk51sample
d:\<WSDK-home>\bin\setupEnv
WSDL2WebService [<optional arguments>] -createService <ServiceName>
-type <Bean|EJB> -project <ProjectDir> <InputFile.wsdl>
WSDL2WebService -verbose -createService StringService -type Bean
-project .\wsdlProj .\wsdlSrc\StringService.wsdl
The command window output is shown in Example 18-3, where ~ stands for
c:\wsdk51sample.
Example 18-3 WSDL2WebService command output (createService)
Creating new Web-Service: StringService ...
Generating server side files:
396
WebSphere Version 5.1 Web Services Handbook
WSWS3185I: Info: Parsing XML file:
~\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl
WSWS3282I: Info: Generating
~\wsdlProj\StringService\DefaultNamespace\StringService.java.
~\wsdlProj\StringService\DefaultNamespace\StringServiceSoapBindingImpl.java.
~\wsdlProj\StringService\WEB-INF\webservices.xml.
~\wsdlProj\StringService\WEB-INF\ibm-webservices-bnd.xmi.
~\wsdlProj\StringService\WEB-INF\ibm-webservices-ext.xmi.
~\wsdlProj\StringService\WEB-INF\StringService_mapping.xml.
Generating client side files:
WSWS3185I: Info: Parsing XML file:
~\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl
WSWS3282I: Info: Generating...
~\wsdlProj\StringService\client-side\DefaultNamespace\StringServiceService.java.
~\wsdlProj\StringService\client-side\DefaultNamespace\StringServiceServiceLocator.java.
~\wsdlProj\StringService\client-side\DefaultNamespace\StringService.java.
~\wsdlProj\StringService\client-side\DefaultNamespace\StringServiceSoapBindingStub.java.
~\wsdlProj\StringService\client-side\META-INF\webservicesclient.xml.
~\wsdlProj\StringService\client-side\META-INF\ibm-webservicesclient-bnd.xmi.
~\wsdlProj\StringService\client-side\META-INF\ibm-webservicesclient-ext.xmi.
~\wsdlProj\StringService\client-side\META-INF\StringService_mapping.xml.
Creating client-side build script...
Creating server-side build script...
Configuring webservices.xml...
A new Web-Service "StringService" has been created successfully in the project directory
C:\wsdk51sample\wsdlProj.
To complete the Web-Service, you can now fill in your implementation code in the
following classes:
StringServiceSoapBindingImpl.java
Then compile the code using the provided script ~\wsdlProj\StringService\compile.bat and
run the tool again with the -createEar option.
After running the tool with the -createService <ServiceName> argument, a
directory named <ServiceName> containing several subdirectories is created
under the specified project directory. These subdirectories contain all the
necessary Java templates and deployment descriptors that are required to build
the Web service implementation(s). A build script called compile.bat (Windows)
or compile.sh (Linux) is also generated to compile the server-side code. The
directory and file structure is similar to Figure 18-3 on page 392:
WEB-INF—Server-side files with deployment descriptor files and WSDL
DefaultNamespace—Interface (StringService.java) and implementation
skeleton file (StringServiceSoapBindingImpl.java)
client-side—Identical to Bean2WebService command output
Chapter 18. WebSphere SDK for Web Services
397
Stage 2—Providing and Compiling the implementation code
Provide the implementation code by editing the file:
<ProjectDir>\<ServiceName>\<DefaultNamespace>\<ServiceName>SoapBindingImpl.java
c:\wsdk51sample\wsdlProj\StringService\DefaultNamespace\StringServiceSoapBindingImpl.
java
Replace the return statement as shown here and save the file:
/**
* StringServiceSoapBindingImpl.java
*
* This file was auto-generated ......
*/
package DefaultNamespace;
public class StringServiceSoapBindingImpl
implements DefaultNamespace.StringService{
public java.lang.String uppercase(java.lang.String arg_0_0)
throws java.rmi.RemoteException {
return arg_0_0.toUpperCase(); // was: return null;
}
}
If the implementation code has dependencies such as .jar files or directories
containing .class files, edit the compile.bat script, and add the full path names
of these dependencies to the USER_CLASSPATH variable.
To compile the code enter:
cd wsdk51sample\wsdlProj\StringService
compile
Note: Only the server code is compiled. If everything is OK, no command
window output is displayed.
Stage 3—Creating a Web services-enabled archive
To create a Web services-enabled archive:
cd wsdk51sample
d:\<WSDK-home>\bin\setupEnv
WSDL2WebService [<optional arguments>] -createEar <File.ear>
-project <ProjectDir>
WSDL2WebService -verbose -createEar StringService.ear -project .\wsdlProj
The command window output is shown in Example 18-4, where ~ stands for
c:\wsdk51sample.
398
WebSphere Version 5.1 Web Services Handbook
Example 18-4 WSDL2WebService command output (createEAR)
localhost:6080/StringService/services/StringService
Preparing to create the archive...
Organising the project directory: ~\wsdlProj\StringService
~\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl
Added web module with context root: StringService
Web Service archive "file://~/wsdlProj/StringService.ear" has been successfully
generated.
The archive ~\wsdlProj\StringService.ear has been successfully updated and is
now ready to deploy.
After we have written the implementation code, compiled it, and run the tool
again with the -createEar <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.
By specifying -type Bean in the stage 1 command we generated a JavaBean
implementation template. By using -type EJB we would generate an EJB
implementation template.
Other command line options are similar to the Bean2WebService command.
WSDL2Client
The WSDL2Client tool generates, in four stages, fully deployable Web service
clients from one or more WSDL documents and optionally deploys them on the
application server.
Sample setup
To see the tool at work, we use the generated WSDL file:
c:\wsdk51sample\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl
WSDL2Client at work
The four stages reviewed:
Stage 1—Run the tool with the -project argument to create a client skeleton
implementation for a Web service that is described by a particular WSDL
document.
Stage 2—Write the implementation code in the templates and compile it using
the build script that was generated in stage 1.
Chapter 18. WebSphere SDK for Web Services
399
Stage 3—If -clientType J2SE and -genMain options were specified in stage
1, run the client by using the run script generated in stage 1.
Stage 4—If -clientType Application, EJB or Servlet is specified in stage 1,
run the tool again with the -createEar argument to build a Web
service-enabled client archive (J2EE client) from this implementation.
Stage 1—Creating a skeleton client implementation
To create a client implementation skeleton, open a command window and enter:
cd wsdk51sample
d:\<WSDK-home>\bin\setupEnv
WSDL2Client [<optional arguments>] -project <ProjectDir> <WSDL URI>
WSDL2Client -verbose -clientType J2SE -genMain StringServiceClient
-project .\wsdlClient
.\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl
The output directory (wsdlClient\client-side\DefaultNamespace) contains all
the necessary Java templates, including serializer and deserializer classes for
complex types, and deployment descriptors that are required to build the Web
service client implementations.
A build script called buildclient.bat is also generated to help us compile all this
code. If we have run the tool with the -clientType J2SE argument, a run script
called runclient.bat is also generated.
Rerun the WSDL2Client command, but this time we generate a J2EE client
application into another output folder (wsdlJ2EE):
WSDL2Client -verbose -clientType Application
-genMain StringServiceJ2EEClient -project .\wsdlJ2EE
.\wsdlProj\StringService\WEB-INF\wsdl\StringService.wsdl
Stage 2—Writing and compiling the implementation code
The generated client program skeleton, StringServiceClient, must be edited to
add the Web service call (Example 18-5, modifications in bold).
Example 18-5 Web service client (copied from sampcode\wsdk51\sample\wsdlClient)
package DefaultNamespace;
public class StringServiceClient {
public static void main(String[] args) {
try {
StringServiceServiceLocator loc = new StringServiceServiceLocator();
// Call to the service locator's get<PortName>() method returns an interface of
// type <PortName>PortType
//StringService port = null; // loc.get<PortName>();
StringService port = loc.getStringService();
400
WebSphere Version 5.1 Web Services Handbook
/*
* Make calls to methods of the <PortName>PortType to access the Web Service
*/
String result = port.uppercase("Hello StringServiceClient");
System.out.println(result);
} catch (java.lang.Exception e){ e.printStackTrace(); }
}
}
If our implementation code has dependencies such as a .jar file or a directory
containing .class files, edit the buildclient.bat script, and add the full path
names of these dependencies to the USER_CLASSPATH variable.
To compile the code:
cd wsdk51sample\wsdlClient\client-side
buildclient
Stage 3—Running the client application
To run the client we have to install the enterprise application that contains the
Web service. We will do that in a moment.
Stage 4—Creating a J2EE client application
Edit the StringServiceJ2EEClient program (in wsdlJ2EE\client-side\...).
Notice that the J2EE client code using JNDI is generated (Example 18-6).
Example 18-6 Web service J2EE client (extract, modifications in bold)
public class StringServiceJ2EEClient {
public static void main(String[] args) {
try {
// Use JNDI to locate the Web Service
Context ctx = new InitialContext();
String webService = "java:comp/env/service/StringServiceService";
StringServiceService service = (StringServiceService) ctx.lookup(webService);
// Call to the service's get<PortName>() method returns an interface ...
//StringService port = null; // (StringService) service.get<PortName>();
StringService port = service.getStringService();
/*
* Make calls to methods of the Service Endpoint Interface (SEI) ...
*/
String result = port.uppercase("Hello StringServiceJ2EEClient");
System.out.println(result);
} catch (java.lang.Exception e){
e.printStackTrace();
}
}
}
Chapter 18. WebSphere SDK for Web Services
401
To compile the code:
cd wsdk51sample\wsdlJ2EE\client-side
buildclient
To create the Web service-enabled client archive:
cd wsdk51sample
d:\<WSDK-home>\bin\setupEnv
WSDL2Client [<optional arguments>] -createEar <name of target ear file>
-clientType <Application | Servlet | EJB> <ProjectDir>
WSDL2Client -createEar StringServiceClient.ear -clientType Application
-main DefaultNamespace.StringServiceJ2EEClient
.\wsdlJ2EE
The output will be either a new or updated EAR file. The -main parameter is
required for -clientType Application or Servlet. Notice that the client-side
classes are moved to the META-INF\classes directory. With -clientType Servlet
the classes would be moved to WEB-INF\classes.
Working with the application server
WSDK provides an appserver.bat command to work with the server. This
command file enables you to:
Start, stop, and restart the server.
Install and uninstall enterprise applications.
Start and stop enterprise applications.
List the installed applications.
Enable and disable security.
Enable and disable the samples.
Installing the StringService enterprise application
We created the StringService.ear file in the wsdlProj directory. To install this
enterprise application we run these commands:
cd <wsdk-home>\bin
appserver install c:/wsdk51sample/wsdlProj/StringService.ear
Note that we could have installed the application by using the -deploy options in
the WSDL2WebService -createEar command.
Starting the server and listing the applications
To start the server and list the enterprise applications use these commands:
cd <wsdk-home>\bin
appserver start
appserver appstatus
402
WebSphere Version 5.1 Web Services Handbook
<=== list running applications
Running a J2SE Web-service client
To run the J2SE client, we use the runclient.bat file that was generated into the
client-side folder:
cd wsdk51sample\wsdlClient\client-side
runclient
The client connects to the enterprise application running in the server and
displays this output:
HELLO STRINGSERVICECLIENT
If the implementation code has dependencies such as a .jar file or a directory
containing .class files, edit the runclient.bat script, and add the full path
names of these dependencies to the USER_CLASSPATH variable.
Running the J2EE client
In “Stage 4—Creating a J2EE client application” on page 401 we created the
StringServiceClient.ear file, a Web service-enabled J2EE client application.
We can run the J2EE client using the WebSphere launchClient command:
cd <WSDK-home>\appserver\bin
launchClient c:\wsdk51sample\wsdlJ2EE\client-side\StringServiceClient.ear
The output is similar to the J2SE client:
D:\<WSDK-home>\appserver\bin>launchClient
c:\wsdk51sample\wsdlJ2EE\client-side\StringServiceClient.ear
IBM WebSphere Application Server, Release 5.0
J2EE Application Client Tool
Copyright IBM Corp., 1997-2002
WSCL0012I: Processing command line arguments.
WSCL0013I: Initializing the J2EE Application Client Environment.
WSCL0035I: Initialization of the J2EE Application Client Environment ...
WSCL0014I: Invoking the Application Client class
DefaultNamespace.StringServiceJ2EEClient
HELLO STRINGSERVICEJ2EECLIENT
UDDIPublish
The UDDIPublish tool publishes either a business entity or a business service to
a public or private UDDI registry. When publishing a service, the tool creates the
necessary binding template and tModel elements in the UDDI hierarchy and
associates the service with an existing business. By default, the tool publishes to
the private WSDK registry.
Chapter 18. WebSphere SDK for Web Services
403
Publishing a business entity
To publish a business entity:
cd <WSDK-home>/bin
UDDIPublish -business -businessName <name> [<optional arguments>]
UDDIPublish -business -businessname ItsoBusiness
A message is returned informing us that the publish operation completed
successfully. The unique key for the new business (as generated in the registry)
is also displayed.
Publishing a business service
To publish a business service:
cd <WSDK-home>/bin
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>]
UDDIPublish -service -serviceName StringService
-businessname ItsoBusiness
-wsdlLocation .\wsdlproj\StringService\WEB-INF\wsdl\StringService.wsdl
-accessPoint http://localhost:6080/StringService/services/StringService
A message is returned informing us that the publish operation completed
successfully. The unique keys for the new business service, binding template,
and tModel instance are also displayed.
Security for publishing
Because the application server is running with security on, default credentials
(user ID: admin, password: adminpwd) are passed by the tool to the UDDI registry
when the publish operation is attempted. These credentials can be overridden by
the -username and -password arguments, which can be entered when publishing
or unpublishing either a service or a business.
Additional properties
With the -uddiprops argument of UDDIPublish, we can specify the location of a
Java properties file that contains additional input information. Businesses and
services can have this additional classification information associated with them
in the registry to assist in the discovery process. This information can be added
in the form of a keyed reference to the published item's category bag structure. A
category bag can contain numerous keyed references, each one containing the
name and the value of a category to which the published item belongs.
404
WebSphere Version 5.1 Web Services Handbook
We can use the provided speedstart.properties file with UDDIPublish to create
and categorize businesses and services in the public IBM UDDI V2 Business
Test Registry as being part of the IBM Speed Start program (Figure 18-6):
<WSDK-home>\appserver\properties\speedstart.properties
# Properties specific to IBM Speed Start
# URLs pointing to IBM test registry
wsdk.uddi.publish.url=https://uddi.ibm.com/testregistry/publishapi
wsdk.uddi.inquiry.url=https://uddi.ibm.com/testregistry/inquiryapi
# Added to category bags belonging to published services
wsdk.uddi.publish.bs.keyref.name.1=Web service information for the developerWorks Web
services community
wsdk.uddi.publish.bs.keyref.value.1=General
wsdk.uddi.publish.bs.keyref.tmodelkey.1=UUID:8F497C50-EB05-11D6-B618-000629DC0A53
wsdk.uddi.publish.bs.keyref.name.2=Web service information for the developerWorks
Speed Start community
wsdk.uddi.publish.bs.keyref.value.2=Speed Start
wsdk.uddi.publish.bs.keyref.tmodelkey.2=UUID:8F497C50-EB05-11D6-B618-000629DC0A53
# Added to category bags belonging to published business
wsdk.uddi.publish.be.keyref.name.1=Web service information for the developerWorks Web
services community
wsdk.uddi.publish.be.keyref.value.1=General
wsdk.uddi.publish.be.keyref.tmodelkey.1=UUID:8F497C50-EB05-11D6-B618-000629DC0A53
wsdk.uddi.publish.be.keyref.name.2=Web service information for the developerWorks
Speed Start community
wsdk.uddi.publish.be.keyref.value.2=Speed Start
wsdk.uddi.publish.be.keyref.tmodelkey.2=UUID:8F497C50-EB05-11D6-B618-000629DC0A53
Figure 18-6 Properties file for publishing
We can use the provided testregistry.properties file with UDDIPublish to
publish businesses and services to the IBM UDDI V2 Business Test Registry (but
without the special categories for the IBM Speed Start program).
Similarly, we can use the businessregistry.properties file to enable us to work
with the IBM UDDI V2 Business Registry.
UDDIUnpublish
The UDDIUnpublish tool removes (that is, unpublishes) either a business entity or
a business service from a public or private UDDI registry. By default, the tool
unpublishes from the private WSDK registry.
Chapter 18. WebSphere SDK for Web Services
405
Unpublishing a business entity or service
To unpublish a business entity or business service:
cd <WSDK-home>/bin
UDDIUnpublish -business -businessName <name> [<optional arguments>]
UDDIUnpublish -service -serviceName <name> -businessName <name>
-removeTModels [<optional arguments>]
A message is returned informing us that the unpublish operation completed
successfully. The unique key for the deleted business entity or business service
is also displayed.
Security for unpublishing
Security is handled in the same way as for publishing (see “Security for
publishing” on page 404).
Additional properties
With the -uddiprops argument of UDDIUnpublish, we can specify the location of a
Java properties file that contains additional input information.
The following properties are used by UDDIUnpublish:
wsdk.uddi.publish.url—Overrides the URL to the publish API of the remote
UDDI registry. Unless this property is set, the tool will publish to the WSDK
private registry.
wsdk.uddi.inquiry.url—Overrides the URL to the inquiry API of the remote
UDDI registry. Unless this property is set, the tool will send inquiries to the
WSDK private registry.
We can use the three provided properties files with UDDIUnpublish to remove
businesses and services from the public IBM UDDI V2 Business Test Registry
and IBM UDDI V2 Business Registry:
speedstart.properties (with categories for the IBM Speed Start program)
testregistry.properties
businessregistry.properties
Sample 1—JavaBean request/response Web service
Here we describe sample 1 to give us an idea of what WSDK samples are.
Sample 1 is a simple request-response Web service.
406
WebSphere Version 5.1 Web Services Handbook
Figure 18-7 Sample 1 scenario
The request message contains a string provided by the service requestor (that is,
the user), usually his name. The response message from the Web service is
“Hello <name>!”, where <name> is the argument passed in the request message.
The scenario is described in Figure 18-7.
The Web service is a JavaBean application, Sample1WebService.ear, that has
been Web services-enabled using the Bean2WebService tool. The only method
in this Java bean is getGreeting, which takes a string, <name>, and returns
another string, “Hello <name>!”
Sample 1 uses the -splitWsdl option to generate two WSDL files, the
interface and the implementation. The WSDL document, containing service
interface and implementation definitions, is accessed in the server at:
http://localhost:6080/Sample1WebService/services/Sample1?wsdl
The WSDL2WebService tool is used to create the client-side bindings from the
WSDL document describing the Web service.
When invoked, the client code obtains a static stub from the service locator
and uses it to make a call to the Web service's getGreeting operation. Refer
to the Accessing a Web service from a service locator client section of the
WSDK 5.1 documentation for a description of the service locator client.
The Java client code is located in:
<WSDK-home>\apps\Sample1\src\requester\com\ibm\wsdk\Sample1
Sample 1 uses the document/literal communication/encoding style,
described in the WSDL bindings section of the WSDK 5.1 documentation.
Using sample 1
First, start the application server by invoking this command:
<WSDK-home>\bin\appserver start
To run the sample client:
cd <WSDK-home>/apps/Sample1/bin
runclient.bat <name>
Chapter 18. WebSphere SDK for Web Services
407
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 we want to rebuild the samples, WSDK provides detailed step-by-step
instructions on how to do so. This section describes how to rebuild sample 1.
Compile the service provider source code (in this case a very simple Java
bean called Hello):
cd <WSDK-home>\apps\Sample1\src\provider
<WSDK-home>\appserver\java\bin\javac
-d <WSDK-home>\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-home>\apps\Sample1
<WSDK-home>\bin\Bean2WebService.bat -project Sample1WebService
-methods "getGreeting" -servicePortName Sample1
-style WRAPPED -splitWsdl
-sei .\src\provider\com\ibm\wsdk\Sample1\Sample1Interface.java
-deploy -cp .\classes\provider com.ibm.wsdk.Sample1.Hello
This first removes any old versions of the classes, and then creates a new
Sample1WebService project, rebuilds the archive, and finally deploys it to the
application server. Note that during this last stage we are prompted for
confirmation before overwriting the existing Sample1WebService application
that is already installed on the application server, and the original EAR file is
backed up to Sample1WebService.ear.backup.
The -splitWsdl option causes separate implementation and interface WSDL
documents.
Compile the service requestor source code. This consists of several helper
classes automatically generated as source into the
Sample1\Sample1WebService\client-side directory by the Bean2WebService
tool, and also the J2SE client itself, located in the Sample1\src\requester
directory. Copy the generated Java source files into this directory and compile
everything using the supplied build script, by entering:
<WSDK-home>\apps\Sample1\bin\buildclient.bat
408
WebSphere Version 5.1 Web Services Handbook
We have now successfully created the sample 1 Web service.
To check that it has worked, make sure the application server is running, and
then start the application by entering the command:
<WSDK-home>\bin\appserver.bat startapp Sample1WebService
Open up a browser and point to:
http://localhost:6080/Sample1WebService/services/Sample1
We should see the confirmation message that the Web service has been
deployed and is running successfully:
And now...Some Services
Implementing the weather forecast Web service
In this section we use the EJB2WebService tool to implement the weather forecast
Web service. We start with an enterprise application (ItsoWebService7) that
contains an EJB module (ItsoWebService7EJB) with a session bean
(WeatherForecastEJB) that provides the weather forecast application:
sg246891-01\sampcode\wsdk51\weather\ItsoWebService7.ear
Setting up the environment
Note: Please refer to “Set up the WEATHER database” on page 528 if the
WEATHER database has not yet been created.
Copy the sample data for the weather forecast application to the wsdk51sample
folder:
from: sg246891-01\sampcode\wsdk51\weather
to:
c:\wsdk51sample\weather
First, we set the required environment to run the weather forecast application.
We create a JAAS authentication alias, a JDBC Driver, and a data source.
Use the WeatherDataSource.jacl script provided in:
wsdk51sample\weather\setDataSource
Note: You have to tailor the WeatherDataSource.jacl file before executing (for
DB2 Version 7.2 use the WeatherDataSource7.jacl file):
set driverClassPath: With correct DB2 directory
set defaultUser/set defaultPassword: With valid user ID and password
Chapter 18. WebSphere SDK for Web Services
409
Run the wsadmin tool using these commands:
cd wsdk51sample\weather\setDataSource
set PATH=d:\<WSDK-home>\appserver\bin;%PATH%;
call wsadmin -f WeatherDataSource.jacl -conntype SOAP -host localhost
-username admin -password adminpwd
The tool displays this output:
WASX7209I: Connected to process "server1" on node DefaultNode using SOAP
connector; The type of process is: UnManagedProcess
Add an alias aliasW
create JAASAuthData object for aliasW
Installing DB2 datasource for WEATHER
Finding the server server1
Found server
server1(cells/DefaultNode/nodes/DefaultNode/servers/server1:server.xml#Serv
er_1)
Finding the Resource Adapter
Creating the provider for com.ibm.db2.jcc.DB2ConnectionPoolDataSource
Creating the datasource weather
Running the EJB2WebService tool
After we configured the data source, we can create and deploy the weather
forecast Web service. Run the EJB2WebService tool using the commands
provided in RunEJB2WS.bat (edit the file before running):
cd wsdk51sample\weather
set PATH=d:\<WSDK-home>\bin;%PATH%;
call EJB2WebService -methods getDayForecast getForecast getTemperatures
-verbose -deploy -style wrapped -use literal
-clientType J2SE -genMain WeatherClient
-project ItsoWebServiceWSDK
-ri itso.session.WeatherForecastEJB ItsoWebService7.ear
Note: Installation of the enterprise application is automated using the -deploy
option of the EJB2WebService command.
The tool displays this output with the -verbose option (abbreviated):
Creating new project: ItsoWebServiceWSDK ...
Generating the service endpoint interface...
Generating WSDL:
WSWS3010I: Info:Generating portType {http://session.itso}WeatherForecastEJB
....
WSWS3010I: Info: Generating port WeatherForecastEJBBean
410
WebSphere Version 5.1 Web Services Handbook
Generating server side files:
WSWS3185I: Info: Parsing XML file:
c:\wsdk51sample\weather\ItsoWebServiceWSDK\META-INF\wsdl\WeatherForecastEJB.wsdl
WSWS3282I: Info: Generating c:\wsdk51sample\weather\ItsoWebServiceWSDK\
wsdl2java_output\itso/mapping/Weather.java
....
Configuring webservices.xml
...
Saved archive: C:\wsdk51sample\weather\ItsoWebServiceWSDK\ItsoWebServiceWSDK.ear
Checking server for existing application...
Deploying Web Service client...
Deploy command:
"d:\<WSDK-home>\appserver\..\bin\appserver.bat"
install \"C:/wsdk51sample/weather/ItsoWebServiceWSDK/ItsoWebServiceWSDK.ear\"
{-usedefaultbindings -deployejb -appname \"ItsoWebServiceWSDK\"}
....
ADMA5016I: Installation of ItsoWebServiceWSDK started.
ADMA5018I: Starting EJBDeploy on ear .....\Temp\app56613.ear..
[EJBDeploy] Starting workbench.Starting workbench.
....
[EJBDeploy] EJBDeploy complete.EJBDeploy complete.
[EJBDeploy] 0 Errors, 0 Warnings, 0 Informational Messages
0 Errors, 0 Warnings, 0 Informational Messages
....
ADMA5013I: Application ItsoWebServiceWSDK installed successfully.
Generating client side files:
WSWS3185I: Info: Parsing XML file:
C:\wsdk51sample\weather\ItsoWebServiceWSDK\META-INF\wsdl\WeatherForecastEJB.wsdl
....
Creating client-side build script...
Creating main class...
All done.
Manual installation of the enterprise application would use this command:
appserver install \"C:/wsdk51sample/weather/
/ItsoWebServiceWSDK/ItsoWebServiceWSDK.ear\"
{-usedefaultbindings -deployejb -appname \"ItsoWebServiceWSDK\"}
Generated output
A subdirectory with the project name (ItsoWebServiceWSDK) is created. It
contains:
ItsoWebServiceWSDK.ear—Installable enterprise application
META-INF folder with:
– webservices.xml and ibm-webservices-XXX.xmi—Deployment descriptor
and IBM bindings for the Web service
– WeatherForecastEJB_mapping.xml—JAX-RPC mapping file
Chapter 18. WebSphere SDK for Web Services
411
– ejb-jar.xml and ibm-ejb-jar-bnd.xmi—Deployment descriptor and IBM
binding for the EJB
– wsdl folder with WeatherForecastEJB.wsdl
The implementation code of the Web service:
– itso\mapping folder with Weather, Weather_Ser, Weather_Deser,
Weather_Helper and WeatherPredictor
– itso\session folder with WeatherForecastEJB_SEI and original classes
(WeatherForecastEJB, WeatherForecastEJBHome, WeatherForecastEJBBean)
client-side folder with:
– buildclient.bat and runclient.bat—To build and run the J2SE client we
requested
– itso\mapping folder with Weather, Weather_Ser, Weather_Deser,
Weather_Helper
– itso\session folder with WeatherForecastEJBBeanSoapBindingStub,
WeatherForecastEJB (the interface), WeatherForecastEJBService,
WeatherForecastEJBServiceLocator, and WeatherClient
– META-INF folder with WeatherForecastEJB_mapping.xml,
webservicesclient.xml, ibm-webservicesclient-XXX.xmi
– META-INF\wsdl folder with the WSDL file
The installed enterprise application can be found in:
d:\<WSDK-home>\appserver\installedApps\DefaultNode\
Starting the Web service in the application server
Start the server using the appserver start command and wait for a ready
message. If the server is already running, we must start the newly installed
enterprise application using the command:
appserver startapp ItsoWebServiceWSDK
Enabling application ItsoWebServiceWSDK
WASX7357I: By request, this scripting client is not connected .....
enabling ItsoWebServiceWSDK
Enable process complete for application ItsoWebServiceWSDK
WASX7209I: Connected to process "server1" on node DefaultNode using SOAP
connector; The type of process is: UnManagedProcess
starting ItsoWebServiceWSDK
Start process complete for application ItsoWebServiceWSDK
412
WebSphere Version 5.1 Web Services Handbook
Creating and running a stand-alone client
A small stand-alone client uses the service locator to access the Web service
(Example 18-7). We modify the default skeleton generated by the tool with the
code of our client (see wsdk51sample\weather\client).
Example 18-7 Stand-alone client for weather forecast using service locator
/* Generated by WSDK on Wed Dec 03 05:41:49 PST 2003
*/
package itso.session;
import itso.mapping.*;
import java.util.Calendar;
import java.text.SimpleDateFormat;
public class WeatherClient {
public static void main(String[] args) {
try {
WeatherForecastEJBServiceLocator loc = new WeatherForecastEJBServiceLocator();
// Call to the service locator's get<PortName>() method .....e
itso.session.WeatherForecastEJB port = loc.getWeatherForecastEJBBean();
/* Make calls to methods of the <PortName>PortType to access the Web Service */
//gets today weather forecast
Weather today = port.getDayForecast(Calendar.getInstance());
System.out.println("Today weather forecast...");
System.out.println(printWeather(today));
//gets weekly temperatures
int[] temp = port.getTemperatures(Calendar.getInstance(),6);
System.out.println("Weekly temperatures forecast for next week...");
for (int j = 0; j < 7; j++)
System.out.println("Day " + (j+1) + ": "+ temp[j] + " Celsius");
//gets the weekly weather forecast
Weather[] week = port.getForecast(Calendar.getInstance(),6);
System.out.println("Weekly weather forecast for next week...");
for (int j = 0; j < 7; j++)
System.out.println(printWeather(week[j]));
} catch (java.lang.Exception e){
e.printStackTrace();
}
}
/**
* printWeather creates a string with the weather information
Chapter 18. WebSphere SDK for Web Services
413
* @param w The weather object
* @return A string with the weather information
*/
private static String printWeather(Weather w) {
SimpleDateFormat sdf = new SimpleDateFormat("EEE. MMM d, yyyy");
return "Weather: " + sdf.format(w.getDate().getTime())
+ " '" + w.getCondition() + "' wind: " + w.getWindDirection() + " "
+ w.getWindSpeed() + "km/h " + w.getTemperatureCelsius() + " Celsius";
}
}
Client logic
The main logic is very simple: A service locator is created, the port of the service
is retrieved, and the service methods are invoked:
WeatherForecastEJBServiceLocator loc =
new WeatherForecastEJBServiceLocator();
itso.session.WeatherForecastEJB port = loc.getWeatherForecastEJBBean();
Weather today = port.getDayForecast(Calendar.getInstance());
Service locator or service factory
Using the service locator (ServiceLocator class) may not work on all JAX-RPC
implementations. For portable client code with WSDL document in a single file,
the ServiceFactory should be used instead, as shown in WSDK's sample 5.
We provide a second client (ServiceFactoryClient.java) that uses the service
factory. An extract of the code is shown in Example 18-8.
Note: This client can be used only if we generate the Web service without the
-splitWsdl option.
Example 18-8 Stand-alone client for weather forecast using service factory
......
import javax.xml.namespace.QName;
import javax.xml.rpc.Service;
import javax.xml.rpc.ServiceFactory;
public class ServiceFactoryClient {
public static void main(String[] args) {
String wsdlURL
=
"http://localhost:6080/ItsoWebServiceWSDK/services/WeatherForecastEJBBean?wsdl";
String namespace
= "http://session.itso";
String serviceName = "WeatherForecastEJBService";
String portName
= "WeatherForecastEJBBean";
try {
ServiceFactory factory = ServiceFactory.newInstance();
414
WebSphere Version 5.1 Web Services Handbook
Service myService = factory.createService( new java.net.URL(wsdlURL),
new QName(namespace, serviceName) );
WeatherForecastEJB port = (WeatherForecastEJB)myService.getPort(
new QName(namespace, portName), WeatherForecastEJB.class);
/* Make calls to methods of the <PortName>PortType to access the Web Service */
......
// rest identical to WeatherClient.java
Compile and run the client
Copy the WeatherClient.java and ServiceFactoryClient.java files into the
generated client-side directory:
from: wsdk51sample\weather\client
to:
wsdk51sample\weather\ItsoWebServiceWSDK\
client-side\itso\session
Compile the client and all the generated code using the buildclient.bat file (in
wsdk51sample\weather\ItsoWebServiceWSDK\client-side).
Run the client using the runclient.bat file. To run the ServiceFactoryClient
modify the runclient.bat file.
Sample client output
Here is a sample output:
Today weather forecast...
Weather: Wed. Dec 3, 2003 'rainy' wind: E 31km/h -4 Celsius
Weekly temperatures forecast for next week...
Day 1: -4 Celsius
Day 2: -8 Celsius
......
Weekly weather forecast for next week...
Weather: Wed. Dec 3, 2003 'rainy' wind: E 31km/h -4 Celsius
Weather: Thu. Dec 4, 2003 'partly cloudy' wind: SW 40km/h -8 Celsius
......
Cleanup
In the rest of the chapter we are going to use the WSDK plug-in for Eclipse. To
make the server start faster, we suggest that you remove the applications we
installed:
appserver uninstall StringService
appserver uninstall ItsoWebServiceWSDK
Chapter 18. WebSphere SDK for Web Services
415
Using the WSDK plug-in for Eclipse
If you have Eclipse 2.1.1 installed on your workstation, then you can select to
install the WSDK plug-in for Eclipse when you install WSDK (see “Installation of
WebSphere SDK for Web Services 5.1” on page 523).
Note: What we call here the WSDK plug-in is really a set of plug-ins that
together provide the functionality of WSDK in the base Eclipse environment.
Starting Eclipse with the WSDK plug-in
WSDK provides a Launch Eclipse icon in the WSDK program group. Start
Eclipse and a workspace is initialized, by default in <eclipse-home>/workspace.
Figure 18-8 shows the Eclipse workbench after the applications discussed here
have been created. Open the Java, Resource, and Server perspectives.
Projects
Perpectives
Editor
Server
Figure 18-8 Eclipse workbench
416
WebSphere Version 5.1 Web Services Handbook
Preparing a server
We will use the WSDK server for the testing of WSDK-generated Web services
applications:
Open the Server perspective and select File -> New -> Server and Server
Configuration.
Expand WebSphere Version 5.0 and select WSDK 5.1 Server. Enter
WSDKServer as the name for the server. Click Finish.
Note: You cannot configure this server; therefore, data sources must be
defined outside of Eclipse (see “Setting up the environment” on page 409).
Creating a Web service from a JavaBean
In this section we use Eclipse and the WSDK plug-in to create a Web service
from a JavaBean.
Create a Web project
First we create a Web project:
Select File -> New -> Project -> Web -> Dynamic Web Project.
Enter ItsowebServiceEclipseWeb as the name, select Configure advanced
options, and click Next.
Enter ItsoWebServiceEclipse as the enterprise application name. Click
Finish.
In the Server perspective select the WSDKServer and Add and remove
projects. Select the ItsoWebServiceEclipse project and add it to the server.
Import the weather forecast application
In the ItsowebServiceEclipseWeb project create two packages under
JavaSource: itso.bean and itso.mapping.
Import the code from sg246891-01\sampcode\wsdk51\eclipse\import:
Select the itso.bean package and Import. Select File system, navigate to
...\eclipse\import, and import the WeatherForecast bean.
Select the itso.mapping package and Import. Import the WeatherPredictor
and Weather beans.
Select the META-INF folder in the ItsoWebServiceEclipse enterprise
application and import the was.policy file. This is required for the data source
because Java 2 Security is enabled in the server.
Chapter 18. WebSphere SDK for Web Services
417
Note: Alternatively Java 2 Security can be disabled in the server by editing:
<WSDK-home>/appserver/config/cells/DefaultNode/security.xml
And changing the value:
<security:Security ...... enforceJava2Security="false" ......>
Run the Web Service wizard
The WSDK plug-in provides a Web Service wizard that has a subset of the
functions of the same wizard in Application Developer.
We use the wizard to generate a Web service from the WeatherForecast bean:
Select the WeatherForecast bean in the ItsowebServiceEclipseWeb project
and New -> Other -> Web Service -> Web Service.
Select Start Web service in Web project, Generate a proxy, and Test the
generated proxy (Figure 18-9).
Figure 18-9 Web Service wizard: Start
On the next page verify that ItsoWebServiceEclipseWeb is the service project
and ItsowebServiceEclipseWebClient is the client project (this project will be
created).
On the next page the WeatherForecast JavaBean is preselected.
On the next page select the three get methods, but deselect the setWeather
method. Select Document/Literal and No Security (Figure 18-10).
418
WebSphere Version 5.1 Web Services Handbook
Figure 18-10 Web Service wizard: Methods and style
On the next page select Generate proxy. Note that the proxy will go into the
ItsowebServiceEclipseWebClient project (Figure 18-11).
Figure 18-11 Web Service wizard: Proxy
On the next page select Test the generated proxy and Run test on server.
Note that the test client will go into the sample/WeatherForecast folder in the
client project (Figure 18-12).
Chapter 18. WebSphere SDK for Web Services
419
Figure 18-12 Web Service wizard: Test client
On the final page click Finish (we do not publish into UDDI).
The Web service is installed, the client proxy and test client are generated, and
the WSDKServer is started...be patient.
Generated code
In the ItsowebServiceEclipseWeb project you will find:
SEI (service endpoint interface) WeatherForecast_SEI
Helper classes: Weather_Deser, Weather_Helper, Weather_Ser
WSDL file: WeatherForecast.wsdl
Deployment descriptor: webservices.xml
Mapping file: WeatherForecast_mapping.xml
Servlet configured in web.xml: itso_bean_WeatherForecast
In the ItsowebServiceEclipseWebClient project you will find:
420
Proxy classes in itso.bean
Helper classes in itso.mapping
Test client in sample\WeatherForecast
Deployment descriptor in WEB-INF: webservicesclient.xml
Mapping file: WeatherForecast_mapping.xml
WSDL file
WebSphere Version 5.1 Web Services Handbook
Testing the Web service
The test client should be started automatically, or you select the TestClient.jsp
(in the ItsoWebServiceEclipseWebClient project) and Run on Server. When
prompted for a server, always select the WSDKServer and Set server as project
default.
Note: Sometimes it is necessary to publish the application manually. Select
the WSDKServer and Publish.
Select one of the methods, enter the parameter(s), and click Invoke
(Figure 18-13).
Figure 18-13 Web service test client
Using the Web Services Explorer
Select the WeatherForecast.wsdl file (in the ItsowebServiceEclipseWeb project)
and Web Services -> Test with Web Services Explorer. The Web Services
Explorer opens (be patient...):
Select one of the methods and enter the parameter(s). Click Browse to select
a date from the calendar.
Click Go to invoke the service and the result is displayed (Figure 18-14).
Chapter 18. WebSphere SDK for Web Services
421
Figure 18-14 Web Services Explorer
Click Source to see the SOAP XML messages. Expand the window to see the
text (Figure 18-15). The complete output message is:
<?xml version="1.0" encoding="UTF-8" ?>
- <soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <soapenv:Body>
- <getDayForecastResponse xmlns="http://bean.itso">
- <getDayForecastReturn>
<condition xmlns="http://mapping.itso">sunny</condition>
<date xmlns="http://mapping.itso">2003-12-25T18:27:22.549Z</date>
<windDirection xmlns="http://mapping.itso">SE</windDirection>
<windSpeed xmlns="http://mapping.itso">11</windSpeed>
<temperatureCelsius xmlns="http://mapping.itso">36</temperatureCelsius>
<dbflag xmlns="http://mapping.itso">0</dbflag>
</getDayForecastReturn>
</getDayForecastResponse>
</soapenv:Body>
</soapenv:Envelope>
422
WebSphere Version 5.1 Web Services Handbook
<
Figure 18-15 Web Services Explorer: SOAP XML
Creating and running a client
Now let us create a real client application:
In the ItsowebServiceEclipseWebClient project create an itso.client
package.
Import the two files BeanClient.java and ServletClient.java from
sg246891-01\sampcode\wsdk51\eclipse\client into the new package.
Study the BeanClient. This is a stand-alone application that uses the proxy
classes to run the three methods of the Web service. The output is displayed
to the Console.
In the Java perspective, select the BeanClient and Run -> Run As -> Java
Application. The output is displayed in the Console and is similar to “Sample
client output” on page 415.
Study the ServletClient. This is an HTTP servlet that uses the proxy classes
to run the three methods of the Web service. The output is displayed as
HTML.
Chapter 18. WebSphere SDK for Web Services
423
In the Server perspective, select the ServletClient and Run on Server. The
enterprise application is republished to the server (you can also select the
WSDKServer and Publish). The servlet is started in a Web browser and the
formatted output is displayed (Figure 18-16).
Figure 18-16 Web service servlet client
After testing the servlet, select the ItsoWebServiceEclipse application under the
WSDKServer and Remove.
Creating a Web service from a session EJB
In this section we use Eclipse and the WSDK plug-in to create a Web service
from a session EJB.
Import an EJB JAR file
You cannot create EJBs in the Eclipse plug-in, but you can run EJBs. We start by
importing an EJB JAR file:
Select File -> Import. In the dialog select EJB JAR file and click Next.
Click Browse and navigate to the file:
sg246891-01\sampcode\wsdk51\eclipse\ejb\ItsoWebService2EJB.jar
The EJB project name is set to ItsoWebService2EJB. Overtype
ItsoWebService2 as the EAR project name and click Finish.
424
WebSphere Version 5.1 Web Services Handbook
Note: You get many warnings in the Tasks view about import statements not
being used. This does occur in the generated code of EJBs.
Create a Web project
Invoking an EJB Web service requires a Web router project:
Select File -> New -> Project -> Web -> Dynamic Web Project.
Enter ItsowebService2Router as the name, select Configure advanced
options, and click Next.
Select ItsoWebService2 as the enterprise application name. Click Finish.
In the Server perspective select the WSDKServer and Add and remove
projects. Select the ItsoWebService2 project and add it to the server.
Note: We suggest that you remove the ItsoWebServiceEclipse project
from the server for better performance.
Run the Web Service wizard
We use the Web Service wizard to generate a Web service from the
WeatherForecastEJB session bean:
Select File -> New -> Other -> Web Service -> Web Service.
Select EJB Web service as Web service type. Select Start Web service in
Web project, Generate a proxy, and Test the generated proxy.
On the next page verify that ItsoWebService2Router is the router project,
ItsoWebService2EJB is the EJB project, and ItsowebService2EJBClient is the
client project (this project will be created).
On the next page click Browse EJB beans. Select the WeatherForecastEJB
and click OK. The rest of the fields are now filled in.
On the next page select the three get methods, but deselect the setWeather
method. Select Document/Literal and No Security.
On the next page select Generate proxy. Note that the proxy will go into the
ItsowebService2EJBClient project.
On the next page select Test the generated proxy and Run test on server.
Note that the test client will go into the sample/WeatherForecastEJB folder in
the client project.
On the last page click Finish.
The Web service is installed; the router project, client proxy, and test client are
generated; and the WSDKServer is started...be patient.
Chapter 18. WebSphere SDK for Web Services
425
Generated code
In the ItsowebService2EJB project you will find:
SEI (service endpoint interface) WeatherForecastEJB_SEI (itso.session)
Helper classes: Weather_Deser, Weather_Helper, Weather_Ser
WSDL file: WeatherForecastEJB.wsdl
Deployment descriptor: webservices.xml
Mapping file: WeatherForecastEJB_mapping.xml
In the ItsowebService2Router project you will find:
Servlet configured in web.xml: WeatherForecastEJB, pointing to
com.ibm.ws.webservices.engine.transport.http.WebServicesServlet
In the ItsowebService2EJBClient project you will find:
Proxy classes in itso.session
Helper classes in itso.mapping
Test client in sample\WeatherForecastEJB
Deployment descriptor: webservicesclient.xml
Mapping file: WeatherForecastEJB_mapping.xml
WSDL file
Testing the EJB Web service
The test client should be started automatically, or you select the TestClient.jsp
and Run on Server. The test client runs identical to the JavaBean Web service
test client.
You can also use the Web Services Explorer (see “Using the Web Services
Explorer” on page 421).
Note: You may have to republish the enterprise application to make it work.
Select the WSDKServer and Publish.
Creating a stand-alone client application
With the server running and the EJB application (ItsoWebService2) installed, we
can use a stand-alone client to access the EJB Web service.
The code of the stand-alone client (EJBClient) is provided in:
sg246891-01\sampcode\wsdk51\eclipse\EJBclient\itso\client\EJBClient.java
An extract of the code shows how the proxy is used:
WeatherForecastEJBServiceLocator loc =
new WeatherForecastEJBServiceLocator();
426
WebSphere Version 5.1 Web Services Handbook
WeatherForecastEJB port = loc.getWeatherForecastEJB();
Weather today = port.getDayForecast(Calendar.getInstance());
......
To run the client we require the proxy classes (itso.session package), the
mapping classes (itso.mapping package), and the Web service runtime JAR
files.
Exporting the proxy and mapping classes
We export the required classes from the Eclipse workbench:
Expand the ItsoWebService2EJBClient project and select the itso folder
(under JavaSource) and Export.
Select File system and click Next.
For the target directory click Browse and locate:
sg246891-01\sampcode\wsdk51\eclipse\ejbclient
Select Overwrite existing files without warning and click Finish.
The session and mapping folders are created under the itso folder.
Compile and run the client
We provide the runEJBclient.bat file in the EJBclient folder to compile the client
and run it. You have to tailor the directory names before executing the code:
set LIB=d:\<WSDK-home>\appserver\lib
set SYSTEM_CLASSPATH=%LIB%\webservices.jar;%LIB%\commons-logging-api.jar;
%LIB%\j2ee.jar;%LIB%\qname.jar
"d:\<WSDK-home>\appserver\java\bin\javac" -extdirs %LIB% -classpath .
itso\client\*.java itso\mapping\*.java itso\session\*.java
set CLASSPATH=.;%SYSTEM_CLASSPATH%
"d:\<WSDK-home>\appserver\java\bin\java" itso.client.EJBClient
You have to run the command file from the EJBclient folder. The client produces
sample output similar to “Sample client output” on page 415.
Chapter 18. WebSphere SDK for Web Services
427
Summary
In this chapter we provided a short overview of the WebSphere SDK for Web
Services Version 5.1 and described the differences between this package and
the Emerging Technologies Toolkit.
We also implemented our weather forecast example with the WSDK by
generating the Web service using the EJB2WebService tool, installing it into the
application server, and using a simple client to invoke the Web service.
Finally we used the WSDK plug-in for Eclipse to work with JavaBean and EJB
Web services.
Note: The WSDK plug-in functionality is a subset of the Web services
functions in WebSphere Studio Application Developer (see Chapter 15,
“WebSphere Studio Application Developer” on page 247).
More information
The WSDK Web site contains additional information: A FAQ list, a forum, and
downloads. Check it out at:
http://www.ibm.com/developerworks/webservices/wsdk/
The speed-start program for Web services is located at:
http://www.ibm.com/developerworks/offers/ws-speed-start/
After installing the product we can find more information about the WSDK in the
InfoCenter. Use the wsdkHelp command, located in the <WSDK-home>/bin
directory, or click the WSDK Help icon from the program group. The WSDK Help
is also available in the Eclipse environment using Help -> Help Contents.
428
WebSphere Version 5.1 Web Services Handbook
19
Chapter 19.
Web services scenario:
Architecture and
implementation
This chapter describes a scenario that integrates most technologies and
concepts presented earlier in this book. It gives an introduction to implementing
the service-oriented architecture to meet the requirements of everyday business.
We also show how the previously described concepts and technologies are
incorporated into the solution.
This chapter is structured as follows:
The scenario situation including requirements
A detailed description of the solution, including the following issues:
– The project phases to build up the application, such as system build,
deployment, and run
– The processes within the application
– General concepts of the implementation
– Details of different client implementations
© Copyright IBM Corp. 2003, 2004. All rights reserved.
429
Overview
In this chapter we present a detailed scenario that combines selected concepts
and technologies presented in Part 1, “Web services concepts”. Due to the
limitations of the scope of this book, we do not present a full-blown e-business
application; instead we focus on selected aspects that we consider to be the
most relevant issues in Web services technology in everyday projects.
The scenario extends the weather forecast example presented in Chapter 14,
“Weather forecast application” on page 233. The original example contains a
Web service created from an EJB and from a JavaBean. Now we extend this by
introducing several providers for that service using different implementations, a
requestor that integrates the services into a local application, and a requestor
that updates the information. Furthermore, security features are applied.
We decided to focus on a single tool, WebSphere Studio Application Developer
5.1.1. It is the tool to use for tasks in many projects, because:
Application Developer Integration Edition will offer the same functionality plus
extra features, such as work flow (see Figure 12-1 on page 204 for details).
These additional tools, however, are not commonly used.
The other tools presented in the book (WebSphere SDK for Web Services
and Emerging Technologies Toolkit) provide different possibilities to create
Web services. Neither tool offers the basic range programming functionality
provided by Application Developer.
Scenario situation
In this chapter we extend the weather forecast scenario. In previous chapters we
discussed different paths to build Web services. We have shown how to build the
service bottom-up and top-down, and how to create a static client. For this
scenario we take the existing Web services and discuss the challenges in
creating a client. (We do not cover the creation of the services and the
implementation of security for the services.)
We assume the following situation:
There are several companies that provide weather forecasts. We introduce
two companies:1
– SiliconWeather (www.siliconweather.com)
– FlashAndThunder (www.flashandthunder.com)
1
430
These names are invented and do not relate to existing companies or persons.
At the time of writing this book, neither was an existing Web site.
WebSphere Version 5.1 Web Services Handbook
Furthermore, there is an umbrella corporation for the weather business, the
International Weather Association (IWA), that operates as a standards
body. IWA specifies the format in which its members must provide their
services and a requestor to updated weather information to its members.
Both service providers are members of IWA:
IWA (www.internationalweatherassociation.com)
Finally, our scenario contains an integrator, UnitedSuns
(www.unitedsuns.com), which wants to generate business by integrating
multiple weather forecasts and packaging them into a product or service.
All participants agree on a joint project that will offer a joint weather forecast to
users. This forecast is generated by putting together individual information
from the weather forecast producers. The providers give access to daily and
weekly forecasts updated by IWA. Here we use the functionality used in the
previous chapters and described for J2EE environments in Chapter 4,
“JAX-RPC (JSR 101)” on page 67, and in Chapter 5, “Implementing
Enterprise Web Services (JSR 109)” on page 77. As a special feature,
FlashAndThunder offers its service in two flavors: A regular service called
thunder, and an extremely accurate premium service called flash.
The participants agree to use Web services technology. According to Web
services terminology, SiliconWeather and FlashAndThunder are service
providers, while UnitedSuns and IWA act as service requestors. Furthermore,
a UDDI registry is used to publish and retrieve Web services by UnitedSuns.
Providers generate Web services, WSIL documents, and WSDL documents
according to a Web service interface WSDL provided by the IWA. The
providers publish their services in the UDDI registry.
Requirements
In a real project environment, the customer defines the requirements, possibly
together with a technical consultant. Because this is only a sample application,
we have invented our requirements.
Functional requirements
To run the envisaged business, UnitedSuns and the providers must be able to
perform a number of processes. Not all of them are run totally automated. The
providers must be able to retrieve IWA’s service interfaces and publish their own
Chapter 19. Web services scenario: Architecture and implementation
431
services to the registry. UnitedSuns must be able to perform the following
functionality:
Access the UDDI registry to find suitable providers and retrieve their service
description (manual and automated).
Access providers and read their WSIL to decide on their suitability and to find
their service (manual and automated).
Invoke the services of the providers and process the result into a Web page.
Figure 19-1 provides an abstract overview of the interaction between the actors.
For the sake of readability, we have drawn arrows only from the SiliconWeather
provider. Of course, FlashAndThunder is treated in the same way.
JMS
topic queue
IWA
update database
information
provide updated
weather
publish
references
to defined
standard
Silicon
Weather
retrieve
references
FlashAnd
Thunder
publish
services
UDDI
invoke service
find services
United
Suns
Figure 19-1 Actors in the scenario and their responsibilities
Non-functional requirements
In a typical e-business application, non-functional requirements are often very
important. They include such issues as availability, security, performance,
maintainability, and portability. In our proof-of-concept scenario, most of these
issues will not be addressed.
432
WebSphere Version 5.1 Web Services Handbook
We focus only on security, where we identify the following requirements:
Authentication for accessing a service
Integrity of the information transmitted
Secure transmission of requests and responses
Furthermore, both providers would like to be able to change their access points
rather frequently, which requires a flexible invocation.
Solution
We now present our solution to address these requirements.
Incorporating Web services concepts and technologies
To fulfill the requirements, we incorporate the following Web services concepts
and technologies covered in this book:
The standard technologies WSDL, SOAP, and UDDI.
WSIL for retrieving Web service descriptions directly from the provider’s
server.
UDDI4J, WSDL4J, and WSIL4J APIs for URL dynamic service invocation.
WS-Security and WebSphere security.
Process to create the application
There are many steps to be performed to build the application. However, not all of
them are processed automatically. For this chapter, we focus on the development
of the client (that is, the requestor) code and on deployment and administration
issues. The generation of the server-side code of the providers has already been
described in depth in the previous chapters. Thus, we shorten this description
and integrate the entire development of the server-side Web service (build,
deployment, and run phases) into one setup phase. So we have to distinguish
between four phases:
1. Setup phase—During this phase, preparation steps are taken, many of them
manually. The providers generate and deploy Web services, WSIL
documents, and WSDL documents according to a given Web service
interface provided by the IWA. The providers publish the WSDL documents in
the UDDI registry.
2. Build phase of the client application—In this phase the requestor’s
application is constructed, including proxies or stubs and the business logic
that uses them.
Chapter 19. Web services scenario: Architecture and implementation
433
3. Deployment phase of the client application—Next the developed
application is deployed into an environment, including the security
requirements.
4. Run phase of the client application—Finally the application is run. During
runtime, the application performs a dynamic invocation of the provided
services. The IWA also updates the weather information of the providers with
the accurate values.
These phases refer to the four-phase model described in Chapter 13, “Web
services development overview” on page 221. For our example, we do not focus
on the management phase presented in that chapter.
Types of service invocation
For our scenario, we provide two ways to actually find the service (in the
implementation we refer to them as sample 1 and sample 2) and one way to
update the weather forecast:
Look up with UDDI—The requestor accesses the UDDI registry and retrieves
references of implementations of the services requested.
Look up with WSIL— The requestor directly enters the Web server of a
provider and gets the WSIL document. This document includes a reference to
possibly several local WSDL documents or a UDDI registry, where the
provider is registered. In that case the requestor has to access the registry to
find a reference to the WSDL. We describe both variants as concepts;
however, we provide code samples only for the first choice.
Weather update with JMS—IWA uses a JMS connection topic to provide the
most updated and accurate information available. The providers retrieve that
information and use it to update their databases providing the last information
to their customer, UnitedSuns.
Note: To simplify, we only provide code to update the SiliconWeather
database using a connection queue. All providers also share the same
database.
In our scenario, the application retrieves the WSIL and WSDL documents at
runtime, although these documents have already been retrieved at build time.
This makes sense in situations in which the Web service access point changes
quite often or when there is more than one provider that implements the service.
Otherwise, a static invocation only during build time is acceptable.
434
WebSphere Version 5.1 Web Services Handbook
For a lookup in the UDDI registry, the requestor has to provide a description of
the requested service. As a result, the requestor gets m businesses that provide
n services (m and n do not necessarily have to be equal).
For a lookup using WSIL, the requestor must have the URL of a given service
provider. As a result, the requestor gets k services from this single business. The
lookup with WSIL is a less dynamic approach, because the provider can be
defined already during build time. This approach makes sense in cases where
the provider is fixed and offers several implementations of the same service, or
the binding access of the service changes frequently.
Next, we describe in detail the four phases. In particular, we describe which steps
are manual and which are performed automatically.
Setup phase
For the restricted scope of this chapter, in this phase actions are performed that
can be seen as preparation steps.
IWA
Service
Providers
UDDI
define and store
interface WSDL
publish business entity, tModel
retrieve tModelKey
retrieve interface WSDL
generate Web service;
store service WSDL
deploy
Web service
publish business entity,
publish service
generate and store
WSIL locally
Figure 19-2 Setup phase
Chapter 19. Web services scenario: Architecture and implementation
435
In particular, the actions shown in Figure 19-2 are performed.
The IWA decides on a standard interface for weather forecast services and
describes it as an interface WSDL. This WSDL document cannot contain a
service part, because that part refers to a concrete implementation of the
service (which does not exist yet).
If Application Developer is used to generate this WSDL document, the
generated WeatherForecast.wsdl file has to be provided once the service
information has been removed from the WSDL document. (The service
information describes the concrete implementation, which is not available
yet.)
The IWA publishes a business entity describing the IWA as an entry point for
searches in the UDDI registry. The IWA also publishes a tModel. This tModel
contains a tModelKey, which is a logical link to the actual WSDL document
that describes the interface. Only the tModel is published to the UDDI. The
WSDL document resides on IWA’s server and is not published to the UDDI.
These publishing processes are done manually.
For both SiliconWeather and FlashAndThunder providers, a clerk enters the
UDDI registry with a regular Web browser and retrieves the tModelKey.
The clerk can follow the link and also retrieve the WSDL file from the IWA
server. Should this operation fail, the clerk contacts the IWA (for instance,
using e-mail) and asks for the interface WSDL that matches the tModelKey,
and IWA sends the WSDL document to the clerk.
The providers’ implementers generate the three Web services (one for
SiliconWeather and the two flash and thunder services of FlashAndThunder).
This is done in a top-down fashion using the Application Developer’s wizard to
create a JavaBean skeleton. This skeleton is augmented with code to access
the existing forecast systems. Chapter 15, “WebSphere Studio Application
Developer” on page 247, describes these steps in much detail. The process
also generates an implementation WSDL document (WeatherForecast.wsdl),
which includes the service element that contains the actual bindings.
Each provider implements WS-Security for their Web services (see
Chapter 16, “Web services security with Application Developer” on page 303).
Each provider deploys the Web service(s) to a WebSphere Application
Server. See Chapter 20, “Web services runtime and deployment in
WebSphere” on page 479, for instructions.
Both providers register themselves as business entities in the UDDI registry.
They also publish the new generated services to the registry. (See
Chapter 15, “WebSphere Studio Application Developer” on page 247, for
details.) The service document, together with a binding template, describes
the implemented service. The binding template contains the access point of
the service. Again, no WSDL is published to the registry.
436
WebSphere Version 5.1 Web Services Handbook
Each provider generates a WSIL file and stores it on its own Web server. For
our scenario the WSIL files include references to the locally stored WSDL
documents and to the UDDI registry for demonstration purposes. We do not
use the reference to the registry any further. FlashAndThunder’s WSIL file
refers to both Web services of that company.
Figure 19-3 shows the entities and relationships created during the setup phase.
UDDI Registry
IWA
IWA
Business
Entity
Interface
WSDL
tModel
SW
Business
Entity
F&T
Business
Entity
SW
SW
Business
Business
Service
Service
F&T
Business
Service
Binding
Template
Binding
Template
Silicon
Weather
Service
WSDL
WSIL
FlashAnd
Thunder
flash
Service
WSDL
link
WSDL URL
access point
thunder
Service
WSDL
WSIL
Figure 19-3 Relationship of entities provided by IWA and the two providers
Note: The process followed by both providers to implement the automatic
weather information update is slightly different. IWA has the only valid client to
push the update process. Once a company turns into a member of the IWA,
the company receives a package that includes a full WSDL document,
including service, to locally implement the weather update Web service.
Therefore, this last Web service is kept in secret among the IWA associates.
Chapter 19. Web services scenario: Architecture and implementation
437
Build phase of the client application
In this phase we act as the implementer of the Web service client. We build the
integration application. As stated above, we distinguish between two
approaches. We present the steps to be performed, augmented with code
snippets that demonstrate key aspects.
UnitedSuns
Clerk
UDDI
IWA
Service
Providers
find IWA business entry
Sample 1:
Lookup
over UDDI
retrieve IWA tModel
retrieve interface WSDL
retrieve WSIL
Sample 2:
Lookup
over WSIL
retrieve WSDL
Figure 19-4 Retrieving the WSDL implementation file in the build phase
We perform the steps shown in Figure 19-4.
For the lookup with UDDI option, we do not contact any provider. We
manually access the UDDI to find the business entry of IWA for contact
information. Also we find the tModel (for service lookups during runtime).
There might be a link to the corresponding WSDL document specified in a
field called Overview URL. If there is no WSDL referenced, we have to
manually find the WSDL document. In our case the IWA provides the WSDL
on their Web site.
For the lookup with WSIL option, we directly access the providers’ Web server
and inspect the WSIL files, which are by definition located at:
http://www.siliconweather.com/inspection.wsil
http://www.flashandthunder.com/inspection.wsil
438
WebSphere Version 5.1 Web Services Handbook
The WSIL files specify the locations of the WSDL files, which in our case are
located on the Web servers of the providers. We manually browse to the
WSDL documents and retrieve them.
As described in Chapter 15, “WebSphere Studio Application Developer” on
page 247, we generate the client, and as described in Chapter 16, “Web
services security with Application Developer” on page 303, we apply the
security features.
– Authentication—Basic authentication
– Integrity—Body and security token for request and body for response
– Confidentiality—Body content and user name token for request and body
content for response
We then generate the main code of the application. Here we have to
distinguish between the two different invocation approaches. See “Run phase
of the client application” on page 439 for a description of the different steps of
the application.
We test the code.
Deployment phase of the client application
The developed application is deployed, possibly to different test stages and
eventually to the production stage. Details on deployment can be found in
Chapter 20, “Web services runtime and deployment in WebSphere” on
page 479.
Run phase of the client application
Once UnitedSuns’ application has gone live, the automated steps are performed
as shown in Figure 19-5.
We distinguish between the two approaches during initialization of the
application.2
Lookup with UDDI—In sample 1, the client accesses the UDDI with UDDI4J.
Using the tModelKey, which has been obtained in an earlier lookup step
during the build phase, the client searches for binding templates that
reference this tModel. These binding templates are then used for invocation,
because they contain the access points of the services.
2
It is good practice to run the lookup step only during the initialization of the application. In our
proof-of-concept implementation, however, it is performed for each request.
Chapter 19. Web services scenario: Architecture and implementation
439
Lookup with WSIL—In sample 2, for each provider the client accesses the
Web server and retrieves the current WSIL document:
– The client uses the WSIL4J API and the URL of the WSIL document that
has been retrieved during the build phase.
– From the WSIL document the client retrieves the location of the most
current WSDL document for each provider on their Web server.
– The client accesses these WSDL documents using WSDL4J and extracts
the service endpoints from the service tag in the service WSDL file and
stores them locally.
UnitedSuns
Application
UDDI
Service
Providers
retrieve service binding
Sample 1:
Lookup
over UDDI
extract service
access point
invoke service
retrieve WSIL
Sample 2:
Lookup
over WSIL
parse WSIL
retrieve WSDL
parse WSDL
invoke service
Figure 19-5 Run phase
After an Internet user has entered UnitedSuns (www.unitedsuns.com) and
initiated the integrated weather forecast, the client performs the following steps:
Using the gained endpoint information, the client applies the service’s
getWeatherForecast(URL) method for each of the WSDL documents.
440
WebSphere Version 5.1 Web Services Handbook
The client uses the stub’s getDayForecast, getForecast, and
getTemperatures methods to build its own content.
The markup is returned to the browser.
In the next two sections we provide more details on the implementation of
sample 1 and sample 2.
General concepts of the UnitedSuns client application
The application of the fictitious company UnitedSuns is a Web application using
servlets and JSPs.
Application flow
The general flow in the application is that a JSP displays an HTML form asking
for some parameter. When this form is submitted, a servlet is called to process
the request and forward to a response JSP that presents the reply (Figure 19-6).
Home page
Menu JSP
present menu
choose sample
or preferences
index.html
menu.jsp
Start JSP
enter information
preferences.jsp
lookup.jsp
client1.jsp
client2.jsp
Included page
Response JSP
reusable results
display results
weatherObjects.jsp
UDDIremark.html
preferences.jsp
lookupResponse.jsp
client1Response.jsp
client2Response.jsp
Servlet
process
information
access UDDI
and Web
services
SavePreferencesServlet
LookupServlet
StartClient1Servlet
StartClient2Servlet
Figure 19-6 Scenario client application flow
Frames
When starting the application, a frame set displays options in the frame called
menu (at the top) and a welcome page in the frame called main, which is the
content area. Using the menu, the user can choose between the different
samples and the preferences window (Figure 19-7).
Chapter 19. Web services scenario: Architecture and implementation
441
Figure 19-7 Entry to the UnitedSuns Web application: IBM Almaden Lab
Abstract servlet
The itso.wsdc.AbstractServlet is the base class for all servlets and provides
features that are required in all subclasses.
It provides helper methods such as trace, which writes a message to the
console, or getPreferences, which returns the current preferences object from
the HTTP session. Another method is forward, which is called after a servlet has
finished processing. It takes the name of a JSP and forwards to that JSP to
display the response.
The AbstractServlet also cares for the UDDIProxy instance that is stored in the
session. The servlet assures that the proxy is initialized with the desired inquiry
URL, which was specified in the preferences.
442
WebSphere Version 5.1 Web Services Handbook
Other important features are the invocation invokeService and invokeAll
methods, which call the getDayForecast method of a remote service and return
the resulting Weather object, or a vector of objects.
The invokeService method (Example 19-1) creates a context to look up the
weather service, retrieves a stub of the service, and invokes the getDayForecast
method. The resulting Weather object is returned, or an exception is thrown if a
problem occurs.
Example 19-1 AbstractServlet: invokeService method
protected Weather invokeService(String accessUrl)
throws MalformedURLException, Exception {
Weather w = null;
InitialContext ic = new InitialContext();
WeatherForecastService wfsl = (WeatherForecastService)
ic.lookup("java:comp/env/service/WeatherForecastService");
WeatherForecast wf = (WeatherForecast)
wfsl.getWeatherForecast(new URL(accessUrl));
w = wf.getDayForecast(Calendar.getInstance());
trace("StartClient1Servlet.invokeService: proxy returned weather: " + w);
return w;
}
The invokeAll method (Example 19-2) retrieves a vector with many access
URLs that have to be invoked. For each access URL it calls the invokeService
method. The resulting Weather object is added to a vector. Exceptions are caught
and added to the vector instead of the Weather object.
Example 19-2 AbstractServlet: invokeAll method
protected void invokeAll(Vector accessUrls, HttpServletRequest request) {
String invokeMessage = "";
Vector invocations = new Vector();
if (accessUrls == null || accessUrls.size() == 0) {
invokeMessage = "There were no accessUrls found...”;
return;
}
Enumeration enum = accessUrls.elements();
while (enum.hasMoreElements()) {
String aMessage = "";
String accessUrl = (String) enum.nextElement();
invocations.add(accessUrl);
try {
Weather w = invokeService(accessUrl);
Chapter 19. Web services scenario: Architecture and implementation
443
invocations.add(w);
} catch (Exception e) {
trace(aMessage= "<FONT color=\"red\">"+e.toString()+"</FONT>");
invokeMessage = "There were exceptions.";
invocations.add(aMessage);
}
}
request.setAttribute("invocations", invocations);
request.setAttribute("invokeMessage", invokeMessage);
}
Invocation result JSP
After the services are invoked using the invoke methods of the AbstractServlet,
the application presents the results of the invoked services.
This is done in a simple table with two columns, where the first column is the
access URL that was used, and the second column shows a string
representation of the resulting Weather object, as illustrated in Figure 19-8.
Figure 19-8 Displaying result weather objects returned by invoked services
The JSP code to display the results is shown in Example 19-3.
In our sample application this code is not in a specific response JSP, but in a
separate JSP fragment called weatherObjects.jsp, which is included by the
response JSPs of sample 1 and 2. The objects in the result vector can either be
Weather objects after a successful invocation, or strings with an exception
message text that was caught when trying to invoke the service.
444
WebSphere Version 5.1 Web Services Handbook
Example 19-3 JSP code for displaying results of invoked services
<jsp:useBean id="invokeMessage" class="java.lang.String" scope="request" />
<jsp:useBean id="invocations" class="java.util.Vector" scope="request" />
......
<%
Enumeration enum = invocations.elements();
while (enum.hasMoreElements()) {
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.mapping.Weather w = (itso.mapping.Weather) o;
%>
<%= w.getDate().getTime() %><BR>
<%= w.getCondition() %> <%= w.getTemperatureCelsius() %>&deg;<BR>
Wind: <%= w.getWindDirection() %> <%= w.getWindSpeed() %>km/h
<% } %>
</TD>
</TR>
<% } %>
Preferences
The preferences hold the setting that is used during runtime. The setting can be
changed by the user in an online window. This setting is:
UDDI registry—Specifying which registry to be used for all UDDI interactions.
You can choose one from the list, and you can also specify the inquire URL of
another registry if it is not listed. Note that for the sample in this publication, all
UDDI interactions were done with the IBM test registry.
Preferences class
The preferences are stored in a class called itso.wsdc.Preferences and can be
retrieved in any servlet by getPreferences().get<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.
Chapter 19. Web services scenario: Architecture and implementation
445
The Preferences instances are stored in the HTTP session. Whenever a servlet
is called, it checks if there is a preferences object in the HTTP session. If not, a
preferences object is created with default values. Whenever a user changes
some preferences, they are stored again in the HTTP session, but not persisted
permanently.
Preferences JSP
There is a JSP called preferences.jsp. This page displays the current options
and also allows you to change them. It takes the preferences out of the HTTP
session for display. It holds an HTML form that submits all fields to the
SavePreferencesServlet. Figure 19-9 shows the JSP.
Figure 19-9 Preferences window
Preferences servlet
The servlet called itso.wsdc.SavePreferencesServlet is called when the form in
the preferences.jsp is submitted. It takes the parameter of the form using the
getParameter method of the HTTPRequest object (registry), and stores it in the
current preferences object in the HTTP session. It then forwards the request to
the preferences.jsp again to redisplay the changed value.
UDDI lookup sample
This part of the sample application uses the UDDI4J API to look up entries in a
UDDI registry. We did not call the UDDI lookup a separate sample, because it is
a human user and not a client application that wants to browse the registry.
However, the tool shows the usage of UDDI4J in a dynamic client. The UDDI
registry location can be specified in the preferences page (as described above).
446
WebSphere Version 5.1 Web Services Handbook
There are four possible searches that can be done:
Business entities by name
Business services by name
tModels by name
Binding templates by the keys of a service and a tModel
UDDI lookup JSP
This JSP is the starting point for the lookup, where you define the names of
entities you want to look up, and the keys for the lookup of bindings. You can use
the % sign as a wild card.
Figure 19-10 shows the lookup window.
Figure 19-10 Starting the UDDI lookup: lookup.jsp
UDDI lookup servlet
The servlet itso.wsdc.LookupServlet is used to take the parameters specified in
the lookup.jsp and performs the actual inquiry. It uses the UDDIProxy object that
has been prepared by the base AbstractServlet class.
Chapter 19. Web services scenario: Architecture and implementation
447
After retrieving the URL parameters and getting the UDDI proxy, the servlet calls
several finder methods to perform the search. Each finder method takes some
search criteria and returns a list of result objects. These methods are described
in Chapter 6, “Introduction to UDDI” on page 99.
Look up businesses
To look up a business entity, the find_business method of the UDDI4J API is
used. Example 19-4 shows the code of the lookUpBusiness method in the
LookupServlet, which shows how to:
Extract the parameters.
Access the UDDI proxy object.
Call the find_business method.
Retrieve the vector with business information (getBusinessInfoVector).
Pass the vector together with the message to the JSP by placing the two
objects into the request block (setAttribute).
Example 19-4 Finding a business by name
protected boolean lookUpBusiness(HttpServletRequest request) {
// get the search string from the form
String business = (String) request.getParameter("searchStringBusiness");
String message = "";
boolean success = false;
try {
// initialize a vector with the desired name. ...
Vector names = new Vector();
names.addElement(new Name(business));
// invoke the finder on the uddi proxy
BusinessList businessList = getUddiProxy(request).
find_business(names, null, null, null, null, null, 0);
// extract the vector with business infos out of the result
Vector businesses =
businessList.getBusinessInfos().getBusinessInfoVector();
// set a message for the response page
int numberFound = businesses.size();
message = "Found " + numberFound + " business entries.";
// add the resulting vector to the request for the JSP to display
request.setAttribute("resultBusiness", businesses);
success = true;
} catch (Exception e) {
// trace any exception to the console
trace(message = "<FONT color=\"red\">" + e.toString() + "</FONT>");
}
// add the message to the request for the JSP to display
request.setAttribute("messageBusiness", message);
return success;
}
448
WebSphere Version 5.1 Web Services Handbook
Note that there are many null parameters in the find_business call. This is
because we only have the name as search criteria for the lookup. In the other
parameters we could provide further search criteria such as categorizations,
referenced tModels, and so forth. We could also specify special find qualifiers
specifying if the search string must fit exactly, or if the case within the name
should be ignored.
Lookup services
When searching for a service entity, the find_service method is used.
Figure 19-5 shows an excerpt of the code of the lookUpService method in the
LookupServlet, which shows how to:
Extract the parameters.
Access the UDDI proxy object.
Call the find_service method.
Retrieve the vector with service information (getServiceInfoVector).
Pass the vector together with the message to the JSP.
Example 19-5 Finding a service by name
protected boolean lookUpServices(HttpServletRequest request) {
String searchString = (String) request.getParameter("searchStringService");
String message = "";
ServiceList allServices = null;
boolean success = false;
try {
Vector names = new Vector();
names.addElement(new Name(searchString));
allServices = getUddiProxy(request).
find_service("", names, null, null, null, 0);
Vector resultServices =
allServices.getServiceInfos().getServiceInfoVector();
message = "Found " + resultServices.size() + " service entries.";
request.setAttribute("resultService", resultServices);
success = true;
} catch (Exception e) {
trace(message = "<FONT color=\"red\">" + e.toString() + "</FONT>");
}
request.setAttribute("messageService", message);
return success;
}
Look up tModels
When searching for a tModel entity, the find_tmodel method is used.
Example 19-6 shows an extract of the code of the lookUpTModel method in the
LookupServlet, which shows how to:
Extract the parameters.
Chapter 19. Web services scenario: Architecture and implementation
449
Access the UDDI proxy object.
Call the find_tmodel method.
Retrieve the vector with tModel information (gettModelInfoVector).
Pass the vector together with the message to the JSP.
Example 19-6 Finding a tModel by name
protected boolean lookUpTModel(HttpServletRequest request) {
String searchString = (String) request.getParameter("searchStringTModel");
String message = "";
boolean success = false;
try {
TModelList tModelList = getUddiProxy(request).
find_tModel(searchString, null, null, null, 0);
Vector tModels = tModelList.getTModelInfos().getTModelInfoVector();
message = "Found " + tModels.size() + " tModel entries.";
request.setAttribute("resultTModel", tModels);
success = true;
} catch (Exception e) {
trace(message = "<FONT color=\"red\">" + e.toString() + "</FONT>");
}
request.setAttribute("messageTModel", message);
return success;
}
Lookup bindings
A binding can only exist for the combination of a service and one or more
tModels. The most interesting attribute that a binding provides is the access point
information. This is the URL where a service can be invoked.
When searching for a binding, the find_binding method is used. Example 19-7
shows an extract of the code of the lookUpBinding method in the LookupServlet,
which shows how to:
Extract the parameters.
Access the UDDI proxy object.
Call the find_binding method.
Retrieve the vector with binding information (getBindingTemplateVector).
Pass the vector together with the message to the JSP.
Example 19-7 Finding a binding for a given tModel and service
protected boolean lookUpBinding(HttpServletRequest request) {
String message = "";
boolean success = false;
try {
// check in input parameters
450
WebSphere Version 5.1 Web Services Handbook
String serviceKey = (String)request.getParameter("bindingServiceKey");
String tModelKey = (String) request.getParameter("bindingTModelKey");
if (serviceKey.trim().length() == 0 || tModelKey.trim().length() == 0) {
message = "Need to specify search strings. Lookup skipped.";
request.setAttribute("messageBinding", message);
return true;
}
// ensure that tModel starts with 'UUID:'
if (!tModelKey.toLowerCase().startsWith("uuid:"))
tModelKey = "uuid:" + tModelKey;
// create the search criteria
TModelBag tModelBag = new TModelBag();
tModelBag.add(new TModelKey(tModelKey));
// call the finder
BindingDetail bd = getUddiProxy(request).find_binding(null, serviceKey,
tModelBag, 0);
// extract the bindings vector
Vector bindingTemplates = bd.getBindingTemplateVector();
// provide vector for JSP
request.setAttribute("resultBinding", bindingTemplates);
success = true;
} catch (Exception e) {
trace(message = "<FONT color=\"red\">" + e.toString() + "</FONT>");
}
// provide message to JSP
request.setAttribute("messageBinding", message);
return success;
}
Response JSP
After the servlet has made all lookups, it presents the results using the
lookupResponse.jsp. This result page is used in several cases; either it has
found some entries, or nothing was found, or it even encountered an exception
because the UDDI was not accessible.
The JSP is called and it retrieves the two objects that were added by the servlet.
For each lookup, there is a vector and a message.
The JSP uses color encoding to make it easier to distinguish between business
entities (blue), services (green), tModels (orange), and bindings (purple).
Presenting businesses and services
The list of businesses and services is shown in Figure 19-11.
Chapter 19. Web services scenario: Architecture and implementation
451
Figure 19-11 Businesses and their services
The JSP iterates through the vector returned by the servlet and shows
businesses and services. Both are shown with names and keys (UUIDs).
Example 19-8 shows a code snippet of the JSP.
Example 19-8 JSP code to display businesses and their services
<%
for (int i=0; i<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--&gt;</TD>
<TD><%= si.getNameString() %></TD>
<TD nowrap><%= si.getServiceKey() %></TD>
<% } %>
</TR>
<% } %>
Presenting services and tModels
Displaying the services and tModels is simpler than presenting the businesses,
because there are no hierarchical dependencies. (For the business, the
associated services were displayed as well.) The output is shown in
Figure 19-12.
452
WebSphere Version 5.1 Web Services Handbook
Figure 19-12 Services and associated tModels
The JSP code that is used to display the services and tModels is shown in
Example 19-9.
Example 19-9 JSP code that extracts and displays services and tModels
<%
for (int j = 0; j < resultService.size(); j++) {
ServiceInfo serviceInfo = (ServiceInfo) resultService.elementAt(j);
%>
<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>
<% } %>
Presenting the bindings
The bindings have more interesting attributes than the other entries. Most
important is the URL of the access point, but also its type (protocol). The sample
JSP displays the binding, as shown in Figure 19-13.
Chapter 19. Web services scenario: Architecture and implementation
453
Figure 19-13 Displaying the bindings for a given service and tModel
The JSP code that iterates through the binding vector to display the result is
shown in Example 19-10.
Example 19-10 JSP code that presents the binding
<%
for (int i=0; i<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>
<% } %>
Testing the UDDI lookup sample
The fields in the start page (Figure 19-10 on page 447) are already filled with
ITSO WS%. We published all entries in our sample with this prefix, because there
are other weather-related services already published. Of course you can use any
other search strings for lookups.
The last two fields on the start page require a valid service and tModelKey. You
can retrieve valid keys by first looking up services and tModels by name and
using the keys you found for further requests.
Sample 1: Dynamic invocation using UDDI lookup
This sample shows how to use UDDI4J to search for services that use a given
tModelKey and invokes them. We have to specify a tModelKey as input, for
example, a key found using the UDDI lookup function.
454
WebSphere Version 5.1 Web Services Handbook
This client application already knows the interface WSDL and has a proxy or
stub, which was created in the build phase. At runtime the client looks up the
access point such a service is invoked.
This sample has two parts:
UDDI lookup of businesses, services, and access points (bindings) that
implement a given tModel—This part looks up and displays all business
entities, their services, and binding templates, using the tModelkey as input.
The output of the businesses and services is not necessary for calling the
service, but it is interesting for our sample to see who implements services
with the desired tModel.
Invoke the services—Use the bindings that were retrieved to invoke all the
services that were found and show the results.
Start JSP
The client1.jsp is the entry point for this sample (Figure 19-14). It asks for the
key (UUID) of a tModel. There is already a default for the key. This is the key of
the ITSO Weather Forecast tModel, which was published in the IBM test registry
for this sample.
Figure 19-14 Client sample 1 for dynamic invocation using UDDI
The JSP simply contains some information text and an HTML form with one text
field and a Submit button. When clicked, the StartClient1Servlet list called.
Chapter 19. Web services scenario: Architecture and implementation
455
Servlet
The servlet (StartClient1Servlet) retrieves the tModelKey from the form and
ensures that it starts with a UUID: prefix. It then does the lookup for bindings, and
calls each of them.
Lookup businesses and services
This lookup is similar to the lookup of the businesses and services described
above, but it does not restrict to a certain name. The only input parameter is the
tModelKey. The central method is the performTask method, which does the
following:
Prepare tModelKey—Check if the prefix is OK, and store it in a TModelBag.
Call lookup—Find the businesses and services that have bindings.
Extract access URLs—Get the access points out of the binding objects to call
the invokeAll method.
Call invokeAll—Retrieve the results of all services.
Call a JSP for output.
The listing for performTask is shown in Example 19-11.
Example 19-11 Sample client 1 performTask method
protected void performTask(HttpServletRequest request, HttpServletResponse
response) throws ServletException, IOException {
String tModelKeyString = (String) request.getParameter("tModelKey");
if (!tModelKeyString.toLowerCase().startsWith("uuid:"))
tModelKeyString = "uuid:" + tModelKeyString;
TModelKey tModelKey = new TModelKey(tModelKeyString);
TModelBag tModelBag = new TModelBag();
tModelBag.add(tModelKey);
Vector bindingTemplates = lookUp(tModelBag, request);
Vector accessUrls = extractAccessUrls(bindingTemplates);
invokeAll(accessUrls, request);
forward("client1Response", request, response);
}
The lookUp method is called by the performTask method and is shown in
Example 19-12.
Example 19-12 Look up businesses, services, and bindings
protected
String
Vector
Vector
456
Vector lookUp(TModelBag tModelBag, HttpServletRequest request) {
message = "";
bindings = new Vector();
businesses = null;
WebSphere Version 5.1 Web Services Handbook
Vector bindingTemplates = null;
int numberOfBusinesses = 0;
int numberOfServices = 0;
int numberOfBindings = 0;
try {
// first look up busines and their services matching the tModel
BusinessList businessList = getUddiProxy(request).
find_business(null, null, null, null, tModelBag, null, 0);
businesses = businessList.getBusinessInfos().getBusinessInfoVector();
numberOfBusinesses = businesses.size();
// iterate through businesses
for (int i = 0; i < numberOfBusinesses; i++) {
BusinessInfo bi = (BusinessInfo) businesses.elementAt(i);
Vector serviceInfos = bi.getServiceInfos().getServiceInfoVector();
numberOfServices += serviceInfos.size();
// iterate through services
for (int j = 0; j < serviceInfos.size(); j++) {
ServiceInfo si = (ServiceInfo) serviceInfos.elementAt(j);
// find template for concrete service
bindingTemplates = lookUpBinding(tModelBag, si.getServiceKey(),
request);
if (bindingTemplates != null) {
bindings.addAll(bindingTemplates);
numberOfBindings += bindingTemplates.size();
}
}
}
} catch (Exception e) {
trace(message = "<FONT color=\"red\">" + e.toString() + "</FONT>");
}
message =
"Found "
+ numberOfBusinesses
+ " business entries, "
+ numberOfServices
+ " services and "
+ numberOfBindings
+ " binding templates.";
request.setAttribute("businesses", businesses);
request.setAttribute("bindings", bindings);
request.setAttribute("message", message);
return bindings;
}
Chapter 19. Web services scenario: Architecture and implementation
457
The lookUp method searches for all businesses and services that reference the
tModel. With the service keys, a call to lookUpBindings is made in order to find
the access points where the services can be called. And finally the performTask
method calls the helper method extractAccessUrls, which prepares the resulting
bindings for invocation. The lookUpBindings and extractAccessUrls methods
are shown in Example 19-13.
Example 19-13 Search for bindings and extract URLs from the result
protected Vector lookUpBinding(TModelBag tModelBag, String serviceKey,
HttpServletRequest request) {
String message = "";
Vector bindingTemplates = null;
try {
BindingDetail bd = getUddiProxy(request).
find_binding(null, serviceKey.toString(), tModelBag, 0);
bindingTemplates = bd.getBindingTemplateVector();
} catch (Exception e) {
trace(message = "<FONT color=\"red\">" + e.toString() + "</FONT>");
}
request.setAttribute("messageBinding", message);
return bindingTemplates;
}
protected Vector extractAccessUrls(Vector bindingTemplates) {
Vector accessUrls = new Vector();
if (bindingTemplates == null || bindingTemplates.size() == 0)
return accessUrls;
Enumeration enum = bindingTemplates.elements();
while (enum.hasMoreElements()) {
BindingTemplate bt = (BindingTemplate) enum.nextElement();
String accessUrl = bt.getAccessPoint().getText();
accessUrls.addElement(accessUrl);
}
return accessUrls;
}
Invoke services
The last action within the performTask method before forwarding to the response
JSP is to invoke the service. This is done using the invokeAll method of the
base class. This method was shown in Example 19-2 on page 443.
Response JSP
The client1response.jsp presents the results, which are in two parts:
A list of businesses and services where bindings were found
The results of the invocation
458
WebSphere Version 5.1 Web Services Handbook
Displaying the bindings
The first part shows all bindings that could be found using the tModel.
Figure 19-15 shows how they are displayed.
The bottom part shows the invocation of the services, which is identical to
Figure 19-8 on page 444.
Figure 19-15 Presenting the businesses, services, and bindings for the tModelKey
The JSP code to display this information is shown in Example 19-14.
Example 19-14 JSP code for displaying the businesses, services, and bindings
<%
for (int i=0; i<businesses.size(); i++) {
BusinessInfo bi = (BusinessInfo) businesses.elementAt(i);
%>
<TR class="business">
<TD colspan="4"><%= bi.getNameString() %></TD>
Chapter 19. Web services scenario: Architecture and implementation
459
<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">----&gt;</TD>
<TD colspan="3"><%= si.getNameString() %></TD>
<TD nowrap><%= si.getServiceKey() %></TD>
<%
Vector bindingTemplates =
Util.extractBindingTemplatesWithServiceKey(bindings,
si.getServiceKey());
Enumeration enum = bindingTemplates.elements();
while (enum.hasMoreElements()) {
BindingTemplate bt = (BindingTemplate) enum.nextElement();
%>
</TR><TR class="binding">
<TD></TD>
<TD align="right">----&gt;</TD>
<TD><%= bt.getDefaultDescriptionString() %>
<TD><%= bt.getAccessPoint().getText() %>
<TD><%= bt.getBindingKey() %>
<% } %>
<% } %>
</TR>
<% } %>
The businesses and services are stored in a vector with BusinessInfo objects.
These objects contain a collection of the services. The bindings, however, are not
contained in these UDDI4J objects. They are stored in a separate vector after
lookup. A helper method, Util.extractBindingTemplateWithServiceKey, fetches
all bindings with a certain service key and puts them in a separate vector. This is
useful to easily display the bindings right after their corresponding service.
public static Vector extractBindingTemplatesWithServiceKey
(Vector allBindingTemplates, String serviceKey) {
Vector result = new Vector();
if (allBindingTemplates == null || allBindingTemplates.size() == 0)
return result;
Enumeration enum = allBindingTemplates.elements();
while (enum.hasMoreElements()) {
BindingTemplate bt = (BindingTemplate) enum.nextElement();
if (bt.getServiceKey().equalsIgnoreCase(serviceKey))
result.add(bt);
}
return result;
460
WebSphere Version 5.1 Web Services Handbook
}
The second part of the response JSP shows the results of the actual invocation.
This is not part of this JSP, but is implemented in a separate JSP fragment that is
included by the response JSP. This part was described in “Invocation result JSP”
on page 444.
Test the sample
You can test the sample by providing a tModelKey in the start JSP. There is also
a default value specifying the key of the tModel that is published in the IBM test
registry. Using this you should find three implementations:
http://www.flashandthunder.com/ItsoFlashWeb/services/WeatherForecast
http://www.flashandthunder.com/ItsoThunderWeb/services/WeatherForecast
http://www.siliconweather.com/ItsoSiliconWeatherWeb/services/WeatherForecast
Sample 2: Dynamic invocation using WSIL lookup
The implementation details of the lookup with WSIL are contained in sample 2.
This sample shows some of the possibilities available in two APIs, WSIL4J and
WSDL4J.
In this client, we provide an example of how we can use these APIs to retrieve
the WSDL locations presented in a WSIL document and use those locations to
also retrieve the different service endpoints presented in each of them.
Start JSP
The client2.jsp is the entry point for this sample. It asks for the URL location of
an inspection language document and also for a service name to look up in the
WSIL document provided. The URL location is required and the service name is
optional. There is already a default value for the URL location. This is the value of
the WSIL document of the FlashAndThunder server. Note that this address does
not follow the WSIL specification (see Chapter 8, “Web services inspection
language” on page 141), but it sets to that because we only have one server with
two WSIL documents, one for SiliconWeather and one for FlashandThunder.
The start JSP is shown in Figure 19-16. The JSP simply contains some
information text and an HTML form with one text field and a Submit button. When
this button is clicked, the StartClient2Servlet is called.
Chapter 19. Web services scenario: Architecture and implementation
461
Figure 19-16 Starting client 2 for dynamic invocation using WSIL
Servlet
The class responsible for these operations is the StartClient2Servlet. The
central method is the performTask method:
Call the WSDL lookup—Get the URL locations of the WSDL document
presented in the WSIL document.
Call the service endpoint lookup—Using the URL locations of the WSDL
document, get the access points.
Call invokeAll—Using the access points, retrieve the results of all services.
The listing for performTask is shown in Example 19-15.
Example 19-15 Sample client 2 performTask method
protected void performTask(HttpServletRequest request, HttpServletResponse
response) throws ServletException, IOException {
Vector accessURLs = new Vector();
Hashtable access = getWSDLPort(lookUpWSDLlocations(request), request);
for (Enumeration e = access.keys() ; e.hasMoreElements() ;) {
Vector temp = (Vector) access.get((String)e.nextElement());
for (int i=0; i < temp.size(); i++)
accessURLs.add((String)temp.get(i));
}
invokeAll(accessURLs, request);
forward("client2Response", request, response);
}
462
WebSphere Version 5.1 Web Services Handbook
The two relevant methods in this servlet are:
LookUpWSDLlocations—Where we analyze a WSIL document and obtain all
the URLs for the WSDL documents referenced by the inspection document. In
this method, we have the possibility to restrict the lookup to only one specific
service name (Example 19-16).
Example 19-16 Method to look up WSDL locations
protected Hashtable lookUpWSDLlocations(HttpServletRequest request) {
Hashtable WSDLlocations = new Hashtable();
String wsilURL = (String) request.getParameter("wsilURL");
String serviceName = (String) request.getParameter("serviceName");
String message = "";
try {
// Create a new instance of a WS-Inspection document proxy
WSILProxy proxy = new WSILProxy(wsilURL);
// Get the WSIL document
WSILDocument iWsilDocument = proxy.getWSILDocument();
// Process the WSIL document to get the locations
org.apache.wsil.Service[] iServices =
iWsilDocument.getInspection().getServices();
for (int serviceCount = 0; serviceCount < iServices.length;
serviceCount++) {
ServiceName[] iServiceNames =
iServices[serviceCount].getServiceNames();
for (int serviceNameCount = 0; serviceNameCount <
iServiceNames.length; serviceNameCount++) {
if (serviceName.equals("") || iServiceNames[serviceNameCount].
getText().equalsIgnoreCase(serviceName)) {
Description[] iDescription =
iServices[serviceCount].getDescriptions();
for (int descriptionCount = 0; descriptionCount <
iDescription.length; descriptionCount++) {
String location =
iDescription[descriptionCount].getLocation();
//if the location is null is a UDDI service descriptor
if (location != null) {
WSDLlocations.put(iServiceNames[serviceNameCount].
getText(),location);
}
}
}
}
}
request.setAttribute("resultWSDLlocations", WSDLlocations);
} catch (Exception e) {
trace(message = e.toString());
}
Chapter 19. Web services scenario: Architecture and implementation
463
request.setAttribute("message", message);
return WSDLlocations;
}
GetWSDLPort—Where we retrieve all the service endpoints presented in the
locations received for the WSDL documents. This method is very similar to
the method shown in Figure 3-10 on page 63, but with the difference that in
this case we are not interested in only one service. We retrieve every service
and look into each for service endpoints (Example 19-17).
Example 19-17 Method to get the WSDL port
private Hashtable getWSDLPort(Hashtable WSDLFileLocations, HttpServletRequest
request) {
int endPointCounter = 0;
Service service;
Port port = null;
Hashtable serviceEndpoints = new Hashtable();
String message = "";
try {
// Read WSDL document and get definitions element
WSDLFactory wsdlFactory = WSDLFactory.newInstance();
WSDLReader wsdlReader = wsdlFactory.newWSDLReader();
for (Enumeration e = WSDLFileLocations.keys() ; e.hasMoreElements() ;) {
Vector endpoints = new Vector();
String serviceName = (String)e.nextElement();
Definition definition = wsdlReader.readWSDL(null, (String)
WSDLFileLocations.get(serviceName));
//Get the services
Map services = definition.getServices();
Collection serviceValues = services.values();
for (Iterator serviceIterator = serviceValues.iterator();
serviceIterator.hasNext();) {
service = (Service) serviceIterator.next();
//Get the ports
Map ports = service.getPorts();
Collection portsValues = ports.values();
for (Iterator portIterator = portsValues.iterator();
portIterator.hasNext();) {
port = (Port) portIterator.next();
//Get the extensible elements
List list = port.getExtensibilityElements();
for (Iterator iter = list.iterator(); iter.hasNext();) {
// The SOAP binding is an extensibility element of the Port
ExtensibilityElement element = (ExtensibilityElement)
iter.next();
if (element instanceof SOAPAddress) {
SOAPAddress soapAddress = (SOAPAddress) element;
endpoints.add(soapAddress.getLocationURI());
464
WebSphere Version 5.1 Web Services Handbook
}
}
}
serviceEndpoints.put(serviceName,endpoints);
}
request.setAttribute("resultServiceEndPoints", serviceEndpoints);
}
} catch (WSDLException e) {
trace(message = e.toString());
}
request.setAttribute("message", message);
return serviceEndpoints;
}
Finally, using the service endpoints, the performTask method configures the
addresses and calls the invokeAll method to invoke the services to obtain the
weather forecast results.
Response JSP
The client2Response.jsp presents the results, which are in fact two parts:
A list of WSIL service names with the URL location of their WSDL documents
and the access points presented in each WSDL document
The results of the invocation
An example of the information shown in the first part can be seen in
Figure 19-17.
Figure 19-17 Presenting the service names, WSDL locations, and access points
The second part of the response JSP shows the results of the actual invocation.
This is not part of this JSP, but is implemented in a separate JSP fragment that is
Chapter 19. Web services scenario: Architecture and implementation
465
included in this response JSP. This part was described in “Invocation result JSP”
on page 444.
Testing the sample
To test the functionality of this client you can try this in the start JSP, shown in
Figure 19-16 on page 462:
Provide the FlashAndThunder inspection document without filling in the
service name and invoke Start lookup & invocation. In our example this
address is:
http://www.flashandthunder.com/ItsoFlashWeb/inspection.wsil
The answer has two services, one each for the flash and thunder services
(Figure 19-18).
Repeat the operation but this time fill in the service name as:
ITSO WS Flash Weather Service
The answer only presents the result for the flash service (Figure 19-19).
Figure 19-18 Weather result without the service name
466
WebSphere Version 5.1 Web Services Handbook
Figure 19-19 Weather result with the service name
General concepts of the IWA application
The application of the fictitious association IWA is a simple Web application using
a servlet and a JSP to update the weather information for all its members.
Application flow
The general flow in the application is very similar to the UnitedSuns application,
but with only one servlet (UpdateWeather) and JSP (updateResponse) to display a
confirmation result.
Note: The client does not have any possibility to know what happens once the
weather information is set to the queue connection. Thus, although a
successful message can be shown by the application, it refers only to the
client side. The final process in the server may fail.
Figure 19-20 shows this simple flow.
Chapter 19. Web services scenario: Architecture and implementation
467
Update
enter information
update.html
Servlet
process
information
set the
information
in the queue
Home page
index.html
Response JSP
UpdateWeather
display results
updateResponse.jsp
Figure 19-20 IWA application flow
Home page with update HTML
The update.html is the entry point to provide the weather information for all the
providers associated to IWA. This HTML page (Figure 19-21) collects weather
information for one day and passes the values to the UpdateWeather servlet.
Figure 19-21 HTML page to update weather information
468
WebSphere Version 5.1 Web Services Handbook
Example 19-18 shows the code for the update.html file.
Example 19-18 HTML code to load weather information
<HTML>
....
<FORM action="UpdateWeather" target="main" method="get">
<TABLE border="0" cellspacing="0" cellpadding="4" background="images/IWA.jpg">
<TBODY>
<TR bgcolor="#a0c0b9">
<TD ... class="ClientTitle">Provide Accurate Weather Forecast</TD>
</TR>
<TR>
<TD>
<TD><B>Date:</B>
<TD colspan="2"><INPUT type="text" name="date" size="20
"maxlength="100" value="Dec 31, 2003">
</TR>
......
<TR>
<TD>
<TD><B>Wind Speed:</B>
<TD colspan="2"><INPUT type="text" name="windspeed" size="20
"maxlength="100" value="7">
</TR>
<TR>
<TD colspan="4" bgcolor="#a0c0b9"><INPUT type="submit" name="submit"
value="Update Weather">
... update weather information for providers</td>
</TR>
</TBODY>
</TABLE>
....
</HTML>
Update weather servlet
The itso.jms.UpdateWeather servlet is responsible for:
Parsing the information received from the update.html into a Weather object
Creating a weather service interface to obtain the client stub to finally call the
setWeather method in order to update the providers’ weather information
Forwarding the process comes out to the updateResponse.jsp
Example 19-19 shows the performTask method of this servlet.
Chapter 19. Web services scenario: Architecture and implementation
469
Example 19-19 UpdateWeather servlet doGet method
public void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
try {
Weather w = new Weather();
//date
String dateString = (String)req.getParameter("date");
DateFormat dateFormat = DateFormat.getDateInstance(DateFormat.MEDIUM,
Locale.US);
Date tempDate = dateFormat.parse(dateString);
Calendar date = Calendar.getInstance();
date.setTime(tempDate);
w.setDate(date);
......
//wind speed
String windspeedString = (String)req.getParameter("windspeed");
int windspeed = Integer.parseInt(windspeedString);
w.setWindSpeed(windspeed);
//create a mangement client
InitialContext ic = new InitialContext();
WeatherForecastJMSService wfsl = (WeatherForecastJMSService)
ic.lookup("java:comp/env/service/WeatherForecastJMSService");
WeatherForecastJMS wf = (WeatherForecastJMS) wfsl.getWeather();
Weather[] weatherArray = new Weather[1];
weatherArray[0] = w;
trace("UpdateWeather Servlet invoke Web Service set weather: " + w);
wf.setWeather(weatherArray);
req.setAttribute("weather", w);
req.setAttribute("exception", null);
trace("UpdateWeather Servlet invoke Web Service done.");
}
catch (Exception e) {
req.setAttribute("exception", e.toString());
}
RequestDispatcher rd =
getServletContext().getRequestDispatcher("updateResponse.jsp");
rd.forward(req, resp);
}
Response JSP
The response JSP provides the success or not of the update process. We have
to consider that the response that we received is based only on the success of
the message set in the queue and not on a successful update of the weather
information in the providers. Figure 19-22 shows a successful response.
470
WebSphere Version 5.1 Web Services Handbook
Figure 19-22 Successful response from the updateResponse JSP
Static client
To show the simplicity of a static client against the complicated nature of a
dynamic client, we also provide a static client application that invokes the three
Web services of SiliconWeather and FlashAndThunder.
The static client is a simple servlet, itso.servlet.WeatherClient, in the
ItsoUnitedSunsClient project. Example 19-20 shows the abbreviated code.
Example 19-20 Static client servlet
package itso.servlet;
import itso.bean.WeatherForecast;
import itso.bean.WeatherForecastProxy;
import itso.mapping.Weather;
......
public class WeatherClient extends HttpServlet implements Servlet {
public void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
SimpleDateFormat sdf = new SimpleDateFormat("EEE. MMM d, yyyy");
try {
PrintWriter out = resp.getWriter();
out.println("<html><body>");
// Instantiate the WeatherForecast proxy
WeatherForecastProxy proxy = new WeatherForecastProxy();
Chapter 19. Web services scenario: Architecture and implementation
471
proxy.setEndpoint("http://localhost:9080/ItsoSiliconWeatherWeb
/services/WeatherForecast");
Weather[] ws = proxy.getForecast(Calendar.getInstance(), 2);
proxy.setEndpoint("http://localhost:9080/ItsoFlashWeb
/services/WeatherForecast");
Weather[] wf = proxy.getForecast(Calendar.getInstance(), 2);
proxy.setEndpoint("http://localhost:9080/ItsoThunderWeb
/services/WeatherForecast");
Weather[] wt = proxy.getForecast(Calendar.getInstance(), 2);
for (int i=0; i<ws.length; i++) {
out.println("<h4>Weather Forecast for "+sdf.format(
ws[i].getDate().getTime() )+"</h4>");
out.println("<table border=1 cellpadding=5>");
out.println("<tr><th>Provider</th><th>Condition</th>
<th>Temperature</th><th>Wind</th></tr>");
out.println("<tr><td>Silicon"
+"</td><td>"+ws[i].getCondition()
+"</td><td>"+ws[i].getTemperatureCelsius()
+"</td><td>"+ws[i].getWindDirection()+" "+ws[i].getWindSpeed()
+"</td></tr>");
out.println("<tr><td>Flash"
+"</td><td>"+wf[i].getCondition()
+"</td><td>"+wf[i].getTemperatureCelsius()
+"</td><td>"+wf[i].getWindDirection()+" "+wf[i].getWindSpeed()
+"</td></tr>");
out.println("<tr><td>Thunder"
+"</td><td>"+wt[i].getCondition()
+"</td><td>"+wt[i].getTemperatureCelsius()
+"</td><td>"+wt[i].getWindDirection()+" "+wt[i].getWindSpeed()
+"</td></tr>");
out.println("</table>");
}
out.println("</body></html>");
} catch (Exception e) {
e.printStackTrace();
}
}
}
Invoke the static client from the link of the home page or with the URL:
http://localhost:9080/ItsoUnitedSunsClient/WeatherClient
A sample run of the static client is shown in Figure 19-23.
472
WebSphere Version 5.1 Web Services Handbook
Figure 19-23 Static client output
Installing the scenario in Application Developer
To run the dynamic application scenario in Application Developer, the system
must be set up properly by following the instructions in this section.
Enterprise applications
To run the scenario, we require two enterprise applications to simulate the client
and the server:
Client—ItsoUnitedSuns with an ItsoUnitedSunsClient Web application
represents the client (UnitedSuns).
Server—ItsoIWA with ItsoSiliconWeatherWeb, ItsoSiliconWeatherEJB,
ItsoSiliconWeatherEJBRouter, ItsoFlashWeb, ItsoThunderWeb, and
ItsoIWAUpdateWeatherClient applications. These applications represent the
SiliconWeather and FlashAndThunder servers and the IWA update client.
Chapter 19. Web services scenario: Architecture and implementation
473
All applications are copies of applications as developed in Chapter 15,
“WebSphere Studio Application Developer” on page 247, and completed with
security as in Chapter 16, “Web services security with Application Developer” on
page 303:
ItsoUnitedSunsClient—Same as ItsoWebService1WebClient, configured
with security as in ItsoWebService6EJBClient, and static and dynamic client
added
ItsoSiliconWeatherWeb, ItsoFlashWeb, ItsoThunderWeb—Same as
ItsoWebService1Web, configured with security as in ItsoWebService6EJB, and
a WSIL file (inspection.wsil) added:
http://www.siliconweather.com/ItsoSiliconWeatherWeb/inspection.wsil
http://www.flashandthunder.com/ItsoFlashWeb/inspection.wsil
Note that the WeatherForecast beans in ItsoFlashWeb and ItsoThunderWeb
have been slightly modified to return weather values that are different from
the ItsoSiliconWeatherWeb application.
ItsoSiliconWeatherEJB, ItsoSiliconWeatherEJBRouter—Same as
ItsoWebService3EJB, configured with security
ItsoIWAUpdateWeatherClient—Same as ItsoWebService3EJBClient,
configured with security as in ItsoWebService6EJBClient, and UpdateWeather
client added
All WSDL files are updated with the proper soap address, for example:
<wsdlsoap:address location="http://www.flashandthunder.com/
ItsoFlashWeb/services/WeatherForecast"/>
Importing the enterprise applications
The enterprise applications are provided in:
sg246891-01\sampcode\scenario
To import the ItsoUnitedSuns enterprise application, follow these steps:
Select File -> Import -> EAR file.
Click Browse and locate the EAR file:
sg246891-01\sampcode\scenario\ItsoUnitedSuns.ear
Click Finish.
After the import, select the ItsoUnitedSunsClient project and Properties. On
the Java Build Path -> Libraries page, add this JAR file (use Add Variable):
WAS_50_PLUGINDIR/lib/uddi4jv2.jar
474
WebSphere Version 5.1 Web Services Handbook
Open the webservices.xml, select Port binding -> Security Request Sender
Binding Configuration -> Login Binding, and click Edit. Modify the user and
password values with valid values for the current environment (Local OS).
Repeat the process for the ItsoIWA enterprise application:
Select File -> Import -> EAR file.
Click Browse and locate the EAR file:
sg246891-01\sampcode\scenario\ItsoIWA.ear
Click Finish.
Select the ItsoSiliconWeatherEJBRouter project and Properties. On the Java
Build Path -> Libraries page, add this JAR file (use Add Variable):
WAS_50_PLUGINDIR/lib/webservices.jar
Server project
To configure a server for testing, we require a server project. Define a server
project named Servers:
Select File -> New -> Project -> Server -> Server Project. Click Next.
Enter Servers as the name and click Finish.
Configurating a server for testing
A zip file to create the server in the Application Developer workspace directory is
provided in:
sg246891-01\sampcode\scenario\ScenarioServer.zip
To import that zip file into the workspace:
Select File -> Import -> Zip file and click Next.
Click Browse for From Zip file and locate the ServerScenario.zip. Select it
and click Open.
Click Browse for Into folder and select Servers, click OK, and then Finish.
To configure the server:
Open the Server perspective.
In the Server Configuration view, select the ScenarioServer and Switch
Configuration -> ScenarioServer.
Open the ScenarioServer.
Chapter 19. Web services scenario: Architecture and implementation
475
Select the Variables tab. At the bottom of the Node Settings variables, select
DB2UNIVERSAL_JDBC_DRIVER_PATH. Check that the value is according
to the current environment. If it is not, modify it.
Select the Environment tab. Expand Class Path and verify the location of the
urlprotocols.jar file in:
<wsad-home>\runtimes\base_v51\lib
Select the Ports tab. Notice that we configured port 80 in the Server Settings.
The UDDI entries point to port 80, and by default the internal HTTP server
listens to port 9080 only.
Another way to route the Web services calls from port 80 to 9080 is to define
a TCP/IP Monitor server.
Select the Data sources tab. The active data source is for DB2 8.1. A second
data source (jdbc/weather2) is defined for DB2 7.2. If you run DB2 7.2,
change the data source names so that jdbc/weather is the data source
matching your DB2 system.
Select the Security tab. Select DB2User in JAAS Authentication Entries and
click Edit.
Modify User ID and Password with the user information previously used to
generate the WEATHER database. Click OK. This user ID must be authorized for
DB2 access.
Modify the Current active authentication settings with a valid user ID and
password for the operating system.
Note: You can enable or disable security to run the application. With
security enabled you must provide a valid user ID and password.
Save and close the ScenarioServer configuration window.
Configure the HOSTS file
The application uses HTTP addresses such as www.flashandthunder.com. These
addresses must point to the local machine. Edit the HOSTS file in:
c:\WINNT\system32\drivers\etc\hosts
Configure one line as:
127.0.0.1
localhost www.siliconweather.com www.flashandthunder.com
www.unitedsuns.com
Test in a command window:
ping www.unitedsuns.com
476
WebSphere Version 5.1 Web Services Handbook
Run the samples
Everything is configured and we can run the samples:
Start the ScenarioServer and wait for the ready message (Server server1
open for e-business).
Select the ItsoUnitedSunsClient project and Run on Server.
Static client
Select Static Client (at the bottom) and wait for the response.
Sample 1
Select Start Sample 1, then select Start lookup & invocation. Be patient. UDDI
lookup can be slow, but you should see the result of the three Web services.
Sample 2
Select Start Sample 2, then enter a URL location:
http://www.flashandthunder.com/ItsoFlashWeb/inspection.wsil
http://www.siliconweather.com/ItsoSiliconWeatherWeb/inspection.wsil
Select Start lookup & invocation and you should see the results of the Web
services.
General UDDI lookup
Select General UDDI lookup then select Start lookup. You should see three
businesses, three services, and one tModel.
You can also search for any other entries. For example, if you enter Weather, you
will get over 20 business entries.
Weather update
Select the ITSOIWAUpdateWeatherClient project and Run on Server. Provide the
updated weather for today and Click Update Weather.
Use the UnitedSuns application to see how the prediction turns into reality.
Chapter 19. Web services scenario: Architecture and implementation
477
Summary
In this chapter we provided a Web services scenario and an implementation
using Application Developer and Application Server. Also we incorporated the
general concepts introduced in Part 1, “Web services concepts”. Although this
scenario is simplistic in some ways, it is well suited to demonstrating how to build
a Web services-based application.
In this chapter we showed the development process for this application. In
particular, we described which activities of the implementation have to be
performed manually and which can be run automatically. We also showed the
interaction of the various actors in the application.
Next we described in detail the implementation issues of the solution when
dynamically accessing a UDDI registry. We provided two types of dynamic
clients. One client uses the UDDI registry to find a suitable implementation of the
Web service in request, while the other accesses a WSIL file on the provider’s
server. We presented relevant implementation issues regarding these two
clients, including the security aspects.
In addition, we described a static client to show the difference between dynamic
and static client coding.
478
WebSphere Version 5.1 Web Services Handbook
20
Chapter 20.
Web services runtime and
deployment in WebSphere
This chapter describes Web services deployment in the IBM WebSphere
Application Server environment. We cover the product installation and
administration basics necessary to understand the deployment process. We
describe Web service Java implementation packaging and SOAP enablement,
as well as Web service administration. The WebSphere Version 5.0.2 and 5.1
enhancements in the area of Web services security, SOAP/JMS, and monitoring
using Tivoli Performance Viewer (TPF) are also discussed. We also discuss
some useful troubleshooting techniques.
It is not the intention of this chapter to cover the application server details beyond
the scope necessary to understand Web service deployment. However, we
provide links to additional resources. In addition, the product overview is provided
in Chapter 12, “IBM WebSphere product family” on page 203, and the product
installation is covered in Appendix A, “Installation and setup” on page 515.
© Copyright IBM Corp. 2003, 2004. All rights reserved.
479
Overview
In this section we cover IBM WebSphere Application Server as a Web service
deployment platform of choice. We do not discuss all the product details. We only
deal with the aspects necessary to understand Web services deployment,
administration, and security.
WebSphere Application Server general concepts
WebSphere Application Server—WebSphere for short—represents one of the
basic building blocks of the enterprise e-business environment. It is a part of the
IBM WebSphere product family, which we describe in Chapter 12, “IBM
WebSphere product family” on page 203.
Administration basics
In WebSphere 3.5 and WebSphere 4.0 Advanced Edition, the configuration was
saved in a relational database. The administration server had to be installed and
started on all the nodes in the domain to start and stop an application. The
administrative console was a thick Java client. In addition, command-line tools
such as XMLConfig and WSCP were available to automate the administration
tasks.
However, a Web-based administrative console was available for the WebSphere
4.0 Advanced Edition Single Server (AEs) and all the configuration information
was saved in an XML file. WebSphere Version 5 adopts this concept and does
not use a relational database for the administrative repository for configuration
data, but stores the data in XML files instead.
The administrative console Web application enables you to edit the configuration.
The WSADMIN scripting facility can be used in interactive or batch mode to
perform administrative console operations. The XMLConfig tool and the WSCP
scripting tool are not available in Version 5.
WebSphere topology building blocks
Before we discuss the details of Web application deployment, let us first cover
some fundamental administrative concepts:
Managed process or server—Denotes any instance of a JVM that can be
managed in a WebSphere environment. Application servers, JMS servers (a
special type of server that supports JMS communication), node agents, and
480
WebSphere Version 5.1 Web Services Handbook
deployment managers are all examples of managed processes. We discuss
node agents and deployment managers in the subsections that follow.
Node agent—Is responsible for controlling all the servers running on a
certain machine. These servers could be application servers and/or a JMS
server. In most cases we find a single node agent on one physical system,
although it is also possible that on some very high-end systems, multiple node
agents may be concurrently active.
Cell—A network of related node agents makes a cell. The concept of a cell is
very similar to the concept of domain, which we know from the previous
versions of WebSphere. In each cell, there is a single deployment manager.
However, despite its similarity, this process is not equivalent to the
administrative server of previous releases; its main purpose is to allow an
administrator to manage the resources in the entire cell.
Figure 20-1 shows an example of a WebSphere Version 5 topology.
Application
Server
XML
config
Managed
Process
Node
Agent
Cell
Application
Server
XML
config
Deployment
Manager
Managed
Process
Application
Server
XML
config
Node
Agent
Application
Server
XML
config
Figure 20-1 WebSphere Version 5 example topology
Chapter 20. Web services runtime and deployment in WebSphere
481
Each physical machine holds a separate installation of the product that is not
aware of installations on other machines. The configuration files are in XML. In
the base application server, the node agent code is there although it performs no
role until the node is added into a cell.
WebSphere Application Server Network Deployment represents a single
point of administration of multiple nodes. It is possible to install Network
Deployment on any machine in the network to create a network deployment
manager cell. A WebSphere Application Server installation on the same machine
is not a prerequisite. Once we install and start the network deployment instance,
we can use the addNode tool to add a WebSphere Application Server instance
(node) to the network deployment cell. The network deployment manager
assumes responsibility for the configuration of any application server nodes that
belong to the cell.
Each process keeps all the data necessary to start itself. The configuration data
is in XML files, and the application data in enterprise application EAR files. In the
Network Deployment environment, you can attach an administrative client to any
managed process to make changes to the configuration. The deployment
manager contains the master repository of XML files. Individual nodes and
servers synchronize the files with the master configuration data and all the
changes applied to them directly are lost after synchronization. It is best to
change configuration data only through the deployment manager.
In the following sections we cover the main functions of the Web administrative
console.
Administrative console
The WebSphere administrative console is a graphical, Web-based tool designed
to manage the WebSphere Application Server administrative server. The
administrative console builds upon the Admin Web application architecture and
functions that were introduced in WebSphere Version 4.0 AEs.
The administrative console Web application is installed by default during
WebSphere installation. After we start the server (in the case of the base
application server, the command is startserver server1), we can access the
console using a Web browser:
http://<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.
482
WebSphere Version 5.1 Web Services Handbook
taskbar
workspace
celltree
status/messages
Figure 20-2 WebSphere Administrative Console
The console window contains the following main areas: A taskbar, a cell tree
view, a workspace, and a status messages area. We can resize these areas to fit
our needs. They can be seen in Figure 20-2.
Taskbar—The taskbar helps a user to return to the console home page,
access product information, save changes made to administrative
configurations, and log out of the console.
Cell tree view—The tree view on the left side of the console is used to select
and manage components in a WebSphere administrative cell.
Workspace—The console workspace is the main area to make changes to
the configuration, such as creating application servers, installing an
enterprise application, and configuring data sources. The console also
provides a search function for locating and viewing resource objects.
Status messages area—The messages area at the bottom of the console
lists messages returned by the administrative server as well as messages
about events, such as successful completion and errors.
Chapter 20. Web services runtime and deployment in WebSphere
483
Enterprise application deployment
Enterprise applications (or J2EE applications) are applications that conform to
the Java 2 Platform Enterprise Edition specification. They consist of EJB
modules (EJB JAR files), Web modules (WAR files), connector modules (RAR
files), and application client modules (JAR files). None of these modules is
mandatory and any combination of modules is allowed. Optionally, additional
JAR files containing dependent classes or other components required by the
application can be added to the application. An enterprise application is
packaged in an enterprise archive (EAR) file.
WebSphere Application Server provides the Assembly Toolkit, which replaces
the Application Assembly Tool (AAT) of earlier Application Server versions:
The Assembly Toolkit consists of the J2EE Perspective of the WebSphere
Studio Application Developer product. With the Assembly Toolkit, you can
create and modify J2EE applications and modules, edit deployment
descriptors, and map databases.
The Assembly Toolkit is one of the tools provided by the Application Server
Toolkit (ASTK). Follow instructions available with the ASTK to install the
Assembly Toolkit.
Installing an enterprise application
Here we describe the steps needed to use the administrative console to install an
application.
We begin by selecting Applications -> Install New Application in the console
navigation tree. The first of the Preparing for application install pages is shown.
Preparing for application install (first page)
We have to specify the full path name of the enterprise application file (EAR file).
We can also specify a stand-alone WAR or JAR file for installation. If we are
installing a stand-alone WAR file, we have to specify the context root. Click Next
to move to the second page.
Preparing for application install (second page)
Select whether to generate default bindings. Using the default bindings causes
any incomplete bindings in the application to be filled in with default values.
Existing bindings are not altered. Click Next.
484
WebSphere Version 5.1 Web Services Handbook
Install new application pages
The install new application pages are now shown, starting with the Provide
options to perform the installation page. If we decide to generate default
bindings, we can proceed to the Summary step.
Provide options to perform the installation page
In this step, we provide values for the following settings specific to WebSphere
Application Server. Default values are used if a value is not specified.
Pre-compile JSP—We specify whether to precompile JSP files as a part of
installation. The default is not to precompile JSP files.
Directory to Install Application—We specify the directory in which the
application EAR file will be installed. The default is the installedApps
directory.
Distribute Application—We specify whether WebSphere Application Server
expands or deletes application binaries in the installation destination.
Use Binary Configuration—We specify whether the application server uses
the binding, extensions, and deployment descriptors located with the
application deployment document, the deployment.xml file (default), or those
located in the EAR file.
Deploy EJBs—We decide whether the EJBDeploy tool, which generates code
required to run EJB files, runs during application installation. If the deployed
code has been generated in Application Developer then this step can be
skipped.
Application Name—We decide how to name the application. Application
names must be unique within a cell and cannot contain characters that are
not allowed in object names.
Create MBeans for Resources—We specify whether to create MBeans for
various resources (such as servlets or JSP files) within an application when
the application is started.
Enable class reloading—We specify whether to enable class reloading when
application files are updated.
Reload Interval—We specify the number of seconds to scan the application's
file system for updated files. The default is the value of the reload interval
attribute in the IBM extension (META-INF/ibm-application-ext.xmi) file of the
EAR file. This setting takes effect only if class reloading is enabled.
The reload interval specified here overrides the value specified in the IBM
extensions for each Web module in the EAR file (which in turn overrides the
reload interval specified in the IBM extensions for the application in the EAR
file).
Chapter 20. Web services runtime and deployment in WebSphere
485
Optional panels
Several panes only appear under specific circumstances. We only briefly
describe those here:
Provide JNDI Names for Beans—This panel appears when the application
uses EJB modules. Here we can provide JNDI names for each enterprise
bean in every EJB module.
Map resource references to resources—This panel appears if the application
defines resource references.
Map virtual hosts for Web modules—This panel appears when the application
uses Web modules. This is normally true for the applications containing Web
services. Here we select a virtual host from the list that should map to a Web
module defined in the application. The port number specified in the virtual
host definition is used in the URL that is used to access artifacts such as
servlets and JSP files in the Web module. Each Web module must have a
virtual host to which it maps.
Map modules to application servers—This panel always appears. Here we
select a target server or a cluster from the clusters and servers list for every
module.
Map security roles to users/groups, specify users and groups that are
mapped to each of the security roles—This panel appears when the
application has security roles defined in its deployment descriptor.
Map RunAs roles to user—This panel appears when the application has
RunAs roles defined in its deployment descriptor. Here we can specify the
RunAs user name and password for every RunAs role.
Summary panel
On the Summary panel we verify the cell, node, and server where the application
modules will be installed. Then we start the deployment by clicking Finish.
Starting and stopping enterprise applications
Once an enterprise application has been installed, it can be started and stopped
from the administrative console.
Regenerate the HTTP server plug-in
After installing enterprise applications, it is necessary to regenerate the plug-in.
Select Environment -> Update Web Server Plugin and click OK. The HTTP
server must be restarted to make the plug-in effective.
486
WebSphere Version 5.1 Web Services Handbook
Web services deployment in WebSphere environment
Web services are contained in Web modules or EJB modules. When using
Application Developer, the Web services are fully deployed in the modules and
the containing EAR file.
These Web services are defined in the deployment descriptors of the EJB and
WEB modules, for example, created as described in “WebSphere Studio
Application Developer” on page 247. While deploying these Web services into
the WebSphere runtime, no special activities are required and the EAR file can
be installed like any other (non Web service) EAR file.
An exception to this is SOAP/JMS Web services, where you have to create and
configure the JMS queue and queue connection factory prior to installing the
Web server. We will discuss SOAP/JMS configuration in “Creating JMS
resources for use with the SOAP/JMS Web service” on page 489.
Web services enabling with the SoapEarEnabler tool
In the WebSphere/AppServer/bin directory you can find a command-line tool,
SoapEarEnabler.bat, for enabling a set of SOAP services within an EAR file. We
did not have to run this tool with our deployed EAR files, because they already
contained the necessary SOAP servlets.
For example, you have to use this tool when you create a Web service with tools
that do not create a Web module with the SOAP router servlets. The
SoapEarEnabler tool can add a Web router module to an existing EAR file.
Configuring a server for the ITSO Web services
To illustrate deployment of the ITSO sample Web services we configure the
default server, server1, with a data source, JMS resources, and security. These
activities are similar to configuring the test environment in Application Developer,
but the user interface is quite different.
Start the server and the administrative console
Start the WebSphere Application Server from the Program group or from the
First Steps application.
When the server is ready, start the administrative console. This opens a browser
at:
http://<hostname>:9090/admin/
Chapter 20. Web services runtime and deployment in WebSphere
487
Log in with your user ID. To make start/stop of the server faster, you may stop
and uninstall all the sample applications by selecting Applications -> Enterprise
Applications and stopping and uninstalling all samples except for the
adminconsole application.
Define the data source for the weather forecast database
We require a data source for the WEATHER database:
In the Navigation bar, select Resources -> JDBC Providers, then click Add.
(Note that we define at the Node level.)
Select DB2 Universal JDBC Driver Provider (XA) and click Apply.
The panel expands, click Apply again, and an Additional Properties section is
appended (Figure 20-3).
Figure 20-3 JDBC Provider
488
WebSphere Version 5.1 Web Services Handbook
Under Additional Properties select Data Sources, then click New. Enter
WEATHER as the Name and jdbc/sjweather as the JNDI Name, and click
Apply.
Under Related Items select J2C Authentication Data Entries, then click New.
Enter DB2User as the Alias, and a valid user ID and password with access to
DB2.
In the selection line at the top, select Data Sources to get back to the data
source definition:
JDBC Providers > DB2 Universal JDBC Driver Provider (XA) > Data Sources > WEATHER >
Select the WEATHER data source, then select the new DB2User alias for the
Component-managed and Container-managed Authentication Alias. Click
Apply.
Under Additional Properties select Custom Properties. Select the
databaseName property, set the value to WEATHER, and click OK.
Notice in Figure 20-3 the variables used to point to the DB2 JAR runtime JAR
files. We have to define one of these variables. In the Navigation bar, select
Environment -> Manage WebSphere Variables.
Select the DB2UNIVERSAL_JDBC_DRIVER_PATH variable and enter the
location of the JAR files, for example, C:\SQLLIB\java, and click OK.
Select the DB2_JDBC_DRIVER_PATH variable and set the same value.
Save the configuration (select Save in the top menu).
Note: For DB2 7.2 use the DB2 Legacy CLI-base Type 2 JDBC Driver.
Creating JMS resources for use with the SOAP/JMS Web service
In WebSphere 5.0.2 and 5.1, we have the option of using the SOAP/JMS as the
underlying transport medium for the SOAP clients to communicate with a SOAP
server. The WebSphere runtime configuration has to be modified to work for
SOAP over JMS. The steps are:
Create a queue connection factory and queue destination.
Create a listener port.
Activate the queue.
We can define the JMS engine to be a WebSphere JMS Provider, a WebSphere
MQ JMS Provider, or a Generic JMS Provider. Since the WebSphere JMS
Provider is shipped along with WebSphere Application Server, we will use it for
our sample application.
Chapter 20. Web services runtime and deployment in WebSphere
489
Create a queue connection factory and queue destination
To define the JMS resources follow these steps:
In the Navigation bar, select Resources -> WebSphere JMS Provider. We
define at the Node level.
Select WebSphere Queue Connection Factories, then click New. Enter
WeatherQCF as the name and jms/WeatherQCF as the JNDI Name. For the
Component-managed and Container-managed Authentication Alias select
the DB2User entry. Click Ok.
Now go back to the WebSphere JMS Provider page and this time select
WebSphere Queue Destinations and click New. Enter WeatherQueue for the
Name and jms/WeatherQueue for the JNDI Name. Click Ok.
Create a listener port
The SOAP/JMS communication is made possible by implementing a message
driven bean within the Web services application. The MBD listens on a listener
port that is associated with a queue and a queue connection factory. Here are the
steps:
In the Navigation bar, select Servers -> Application Servers -> server1. Under
Additional Properties select Message Listener Service. Select Listener Ports.
Click New.
Enter WeatherPort as the Name, jms/WeatherQCF as the connection factory
JNDI name and jms/WeatherQueue as the Destination JNDI name. Accept
defaults for the remaining fields. Click OK (Figure 20-4).
Figure 20-4 JMS listener port for MDB (abbreviated)
490
WebSphere Version 5.1 Web Services Handbook
Activate the queue
Now that we have created the queue connection factory, queue, and the listener
port, we need to activate the queue for this JMS server. Here are the steps:
In the Navigation bar, select Servers -> Application Servers -> server1.
Under Additional Properties, select Server Components -> JMS Servers.
In the Configuration for Queue names, add a line with the WeatherQueue to the
list. Verify that the initial state is Started. Click OK (Figure 20-5).
Figure 20-5 JMS Server configuration
Save the configuration.
Activating Web service security
Our weather application is equipped with three types of security safeguards
defined in the WS-Security specification. These safeguards are configured in the
deployment descriptor files of the application and the WebSphere runtime
configuration. The deployment descriptor configuration details have already been
discussed in “Web services security with Application Developer” on page 303.
Here we discuss the configuration changes to the WebSphere runtime.
Prior to installing the weather application EAR files in the WebSphere runtime,
we have to configure the security. These steps are similar to those performed in
WSAD in “Web services security with Application Developer” on page 303.
Enable global security in WebSphere runtime
To enable global security follow these steps:
In the Navigation bar, select Security -> User Registries -> Local OS.
Chapter 20. Web services runtime and deployment in WebSphere
491
Under General Properties, enter the Server user ID and Server password,
which is a valid user and password on the that system. Other user registries
such as remote LDAP servers or custom registries can also be used. Click
Apply (Figure 20-6).
Figure 20-6 Global Security user ID
Select Global Security on the navigation bar. Select Enabled. Deselect
Enforce Java 2 Security (which is selected automatically) because we do not
use Java 2 security in our application. Lower on the page, ensure that Active
User Registry is LocalOS. Click OK (Figure 20-7).
Figure 20-7 Enabling global security using the Administrative console
492
WebSphere Version 5.1 Web Services Handbook
Save the configuration.
Configure the server to decrypt the request
As we have done for the private key in the client, we define the private key to
decrypt the messages in the SampleReceiverEncryptionKeyLocator:
In the Navigation bar, select Servers -> Application Server -> server1.
Under Additional Properties select Web services: Default bindings for Web
Services Security -> Key Locators -> SampleReceiverEncryptionKeyLocator.
Under Additional Properties select Keys and click New.
Enter CN=Bob, O=IBM, C=US as the Key Name, bob as the Key Alias, keypass
as the Key Password, and click OK (Figure 20-8).
Figure 20-8 Private key configuration for receiver
Configure the server to encrypt the response
We have to include the private key we use to decrypt the messages in the
SampleSenderEncryptionKeyLocator:
Go back to Key Locators. Select SampleSenderEncryptionKeyLocator. Under
Additional Properties select Keys and click New.
Enter CN=Alice, O=IBM, C=US as the Key Name, alice as the Key Alias,
keypass as the Key Password, and click OK.
Save the configuration.
Configuring for the scenario application
The scenario application described in Chapter 19, “Web services scenario:
Architecture and implementation” on page 429, requires the configuration of host
names.
Chapter 20. Web services runtime and deployment in WebSphere
493
Configure the HOSTS file
The application uses HTTP addresses such as www.flashandthunder.com. These
addresses must point to the local machine. Edit the HOSTS file in:
c:\WINNT\system32\drivers\etc\hosts
Configure one line as:
127.0.0.1
localhost www.siliconweather.com www.flashandthunder.com
www.unitedsuns.com
Configure the server with virtual host names
The configuration of the virtual host is only required if you want to use HTTPS:
In the Navigation bar, select Environment -> Virtual Hosts, then select
default_host and Host Aliases.
Click New, enter www.siliconweather.com as the host name, 443 as the port,
and click OK.
Save the configuration.
Restart the application server with security
Log out from the administrative console and close the browser window. Stop the
server and restart it.
Open the administrative console. Accept the certificate and you are prompted for
a user ID and password. With security active you have to log in using a
password. Use the user ID and password that were set up for the server.
Important: When the server is started with security, you have to provide user
ID and password to stop the server:
stopserver server1 -user userID -password password
Install the enterprise applications
We developed a number of enterprise applications using Application Developer.
A number of them can be installed in the Application Server as configured above.
Install the scenario enterprise application
To work with the scenario application, install the two enterprise applications,
ItsoIWA and ItsoUnitedSuns, by following the instructions in “Installing an
494
WebSphere Version 5.1 Web Services Handbook
enterprise application” on page 484. Take all the defaults in the installation
panels.
The EAR files are provided in:
sg246891-01\sampcode\scenario
Save the configuration, then start the two enterprise applications.
Regenerate the HTTP Server plug-in
The WebSphere configuration of enterprise applications and virtual hosts must
be known to the HTTP server so that requests can be forwarded:
In the Navigation bar, select Environment -> Update Web Server Plugin, then
click OK.
Restart the IBM HTTP Server from the Windows Services list. The HTTP
server will pick up the SSL configuration and the WebSphere plug-in.
Run the application
After restarting the servers, you can test the application using the URLs:
http://www.unitedsuns.com/ItsoUnitedSunsClient/
http://www.unitedsuns.com/ItsoIWAUpdateWeatherClient/
Experiment with the static and dynamic client applications.
Install the enterprise applications of Application Developer
You can install these applications, exported as EAR files from Application
Developer:
ItsoWebService1
ItsoWebService2
ItsoWebService4
ItsoWebService5
ItsoWebService6
The ItsoWebService3 application has conflicts with the scenario application
because the same JMS resources are used.
Chapter 20. Web services runtime and deployment in WebSphere
495
Update the DADX group configuration
To run in WebSphere we configure the group properties with a data source:
Edit the group.properties file (in ItsoWebService5Web\JavaSource) and
change the lines in bold:
#Tue Dec 16 16:34:01 PST 2003
namespaceTable=namespacetable.nst
groupNamespaceUri=
reloadIntervalSeconds=5
dbDriver=COM.ibm.db2.jdbc.app.DB2Driver
dbURL=jdbc\:db2\:WEATHER
enableXmlClob=true
useDocumentStyle=false
password=
datasourceJNDI=jdbc/sjweather2
initialContextFactory=com.ibm.websphere.naming.WsnInitialContextFactory
userID=
autoReload=true
Define a JDBC driver and data source
In the WebSphere administrative console define a JDBC provider and a data
source. Follow the same steps as in “Define a JDBC driver and data source” on
page 496:
For the JDBC Provider select the DB2 Legacy CLI-base Type 2 JDBC Driver.
For the data source enter WEATHER2 and jdbc/sjweather2.
Save the configuration.
Installing the WORF runtime
The ItsoWebService5 application requires the WORF runtime. For testing in
Application Developer the runtime was added automatically. For WebSphere
Application Server we have to install it manually:
Copy the worf.jar file from Application Developer to the WebSphere
Application Server:
from: <wsad-home>\wstools\eclipse\plugins\com.ibm.etools.webservice_5.1.1\runtime
to:
<was-home>\lib
Stop and restart the application server. Remember that you need a user ID
and password to stop the server.
Installing the enterprise applications
We provide the EAR files in sg246891-01\sampcode\zEARfiles, or you can export
the applications yourself from Application Developer. Install the applications you
want to test, save the configuration, and start the applications.
496
WebSphere Version 5.1 Web Services Handbook
Running the sample enterprise applications
Here are a few URLs that you can use to run the sample applications:
http://localhost:9080/ItsoWebService1WebClient/sample/
WeatherForecastProxy/TestClient.jsp
http://localhost:9080/ItsoWebService1WebClient/WeatherClient
http://localhost:9080/ItsoWebService2EJBClient/sample/
WeatherForecastEJBProxy/TestClient.jsp
http://localhost:9080/ItsoWebService2EJBClient/WeatherClientEJB
http://localhost:9080/ItsoWebService4WebClient/WeatherClient
http://localhost:9080/ItsoWebService5Web/admin/index.html
http://localhost:9080/ItsoWebService5Web/WeatherForecastServlet
http://localhost:9080/ItsoWebService5WebClient/sample/
GoodWeather/TestClient.jsp
http://localhost:9080/ItsoWebService5Web/WeatherGroup/GoodWeather.dadx/TEST
http://localhost:9080/ItsoWebService5WebClient/sample/
WeatherForecastServlet/TestClient.jsp
http://localhost:9080/ItsoWebService6EJBClient/sample/
WeatherForecastEJBProxy/TestClient.jsp
Installing an application with transport channel security
In Chapter 19, “Web services scenario: Architecture and implementation” on
page 429, we secured an application using message-level security.
Message-level security is defined by the WS-Security specification. It is possible
to also secure Web services applications using transport channel security. In this
section, we provide information on how to secure Web services using
transport-channel security. Essentially, transport-level security is achieved by
configuring the client (Web browser) to use HTTPS when communicating with
the Web server.
Note: We do not provide a client application that uses SSL.
For a test environment, we run the Web service client and servers on one
machine, although logically we have three servers:
www.siliconweather.com and www.flashandthunder.com, where the Web
services run
www.unitedsuns.com, where the dynamic client runs
Chapter 20. Web services runtime and deployment in WebSphere
497
Configuring for HTTPS
The HTTP server must be configured for HTTPS. This process requires a
certificate and SSL configuration between the client and the HTTP server. This
configuration is optional if you do not want to use HTTPS.
Create a self-signed certificate
To create a self-signed certificate on the HTTP server where SiliconWeather is
running:
Create a subdirectory keys under <IBMHttpServer_home>\conf. This is where
we store the key database.
Launch the ikeyman tool by selecting Programs -> IBM HTTP Server 1.3.26 ->
Start Key Management Utility.
Note: The tool requires an environment variable, JAVA_HOME. You can
define this variable to point to <WAS_HOME>\java.
Select Key Database File -> New. Select CMS from the type drop-down, enter
webservKeyring.kdb as the file name, enter
<IBMHttpServer_home>\conf\keys for the location, and click OK.
Enter a password, for example, itsowebserv. Select Stash the password to a
file and click OK.
Select Create -> New Self-Signed Certificate. Enter SiliconWeather (no
spaces) as the label, accept X509 V3 as the version, and 1024 as the key size.
For the names, enter the server name as the common name, and IBM, ITSO,
San Jose, CA, US into the other fields. Enter 365 for the period, and click OK.
Close the key database (Key Database File -> Close) and exit the program.
Extract the certificate for installation into WebSphere
We have to extract the certificate so that we can install it in WebSphere:
Click Extract Certificate (bottom right).
Select Base64-encoded ASCII data as the type, enter ItsoWebServ.arm as
the file name, set the conf\keys directory as the location, and click OK.
Install the certificate in WebSphere
To install the extracted certificate in WebSphere (the server where the
UnitedSuns client is running):
Copy the extracted ItsoWebServ.arm file into <WAS_HOME>\etc.
Start the ikeyman command-line tool (<WAS_HOME>\bin\ikeyman.bat).
498
WebSphere Version 5.1 Web Services Handbook
Select Key Database File -> Open and select the DummyClientTrustFile.jks
file in the etc directory.
At the password prompt, enter the password for the key file then click OK. The
default password is usually WebAS.
Select Signer Certificates in the drop-down list and click Add. Select
Base64-encoded ASCII data for the type, enter ItsoWebServ.arm as the file
name, and <WAS_HOME>\etc as the location, and click OK.
You are prompted for a label name by which the trusted signer public
certificate will be known. Enter SiliconWeather as the label.
Close the key database (Key Database File -> Close) and exit the program.
Configure the HTTP server for SSL
Follow the instructions in the HTTP server documentation to enable SSL for the
www.siliconweather.com virtual host. You can find the instructions by selecting
IBM HTTP Server -> How to -> Get started -> With secure connections. Also
configure the other virtual hosts, www.unitedsuns.com and
www.flashandthunder.com, but without SSL.
After configuring SSL and the virtual hosts, the httpd.conf file should have a
number of lines attached:
LoadModule ibm_ssl_module modules/IBMModuleSSL128.dll
Listen 443
FileETag none
<VirtualHost www.siliconweather.com:443>
ServerName <yourhostname>
ServerPath c:/ibmhttpserver/htdocs/en_us
SSLEnable
SSLClientAuth none
</VirtualHost>
<VirtualHost www.flashandthunder.com>
ServerName <yourhostname>
ServerPath c:/ibmhttpserver/htdocs/en_us
FileETag none
</VirtualHost>
<VirtualHost www.unitedsuns.com>
ServerName <yourhostname>
ServerPath c:/ibmhttpserver/htdocs/en_us
FileETag none
</VirtualHost>
SSLDisable
Keyfile c:/ibmhttpserver/conf/keys/webservKeyring.kdb
SSLV2Timeout 100
SSLV3Timeout 1000
Chapter 20. Web services runtime and deployment in WebSphere
499
Accessing a Web service from a stand-alone Java client
For illustration purposes we provide a stand-alone client application that
accesses the Web service developed in Chapter 15, “WebSphere Studio
Application Developer” on page 247.
This is the stand-alone client developed in “Stand-alone Java client” on
page 264. The client code has been exported to the sample code:
sg24-6891\sampcode\was\StandaloneClient
A command file named RunAloneClient.bat is provided as well. You may have to
tailor the command file with the WebSphere installation directory.
You can run this client against the test environment or against the real
WebSphere Application Server. A sample output is shown here:
** RUNNING THE STANDALONE JAVA CLIENT OF WEATHERFORECAST WEB SERVICE **
1. Testing getDayForecast() method ...
Mon Dec 22 00:00:00 PST 2003
Temperature = -6
getWindSpeed = 35
Condition = rainy
getDayForecast() test successful
2. Testing getForecast() method ...
Mon Dec 22 00:00:00 PST 2003
Temperature = -6
getWindSpeed = 35
Condition = rainy
Tue Dec 23 00:00:00 PST 2003
Temperature = 32
getWindSpeed = 14
Condition = rainy
Wed Dec 24 00:00:00 PST 2003
Temperature = 16
getWindSpeed = 17
Condition = cloudy
getForecast() test successful
WindDirection = W
WindDirection = W
WindDirection = N
WindDirection = E
3. Testing getTemperatures() method ...
Temperature = -6, Temperature = 32, Temperature = 16,
getTemperatures() test successful
Using Tivoli Performance Viewer (TPF)
Introduced with WebSphere 5.0.2 is new monitoring support for Web services.
This monitoring is performed by Tivoli Performance Viewer, which is shipped as a
part of WebSphere Application Server. Web services data such as the number of
requests received, number of requests processed, and average response time is
displayed in real time, both in graphical and non-graphical formats.
500
WebSphere Version 5.1 Web Services Handbook
In the default WebSphere configuration this service is disabled. We have to make
the following configuration changes to enable it:
Enable the performance monitor interface (PMI) service in the server.
Restart the Application Server.
Start Tivoli Performance Viewer.
Enable PMI service in the application server
To enable PMI in the Application Server:
In the Administrative console select Servers -> Application Servers ->
server1.
Under Additional Properties, select Performance Monitoring Service.
On the Performance Monitoring Infrastructure page under General
Properties, select Startup.
Under Initial specification level, select the custom radio button. In the text box
below that change webServicesModule=N to webServicesModule=H.
By doing this you are enabling Web services-related performance data to be
visible to the Tivoli Performance Viewer (TPV). If you want to collect
performance data for other modules as well, select the Standard radio button.
This will convert all levels to H, including the one for Web services.
Click OK, then save the configuration.
Restart the server
Restart the application server that houses the Web services application.
Start Tivoli Performance Viewer (TPV)
TPV is a tool that connects to the Application Server and extracts performance
information from it. It then displays that performance information in text and
graphical formats.
Start TPV by running the batch file <WAS_HOME>\bin\tperfviewer.bat, or by
selecting the program from the WebSphere program group:
In TPV’s navigation bar, expand Viewer and navigate to the Web services
whose data you want to view.
Select the data you want charted in the bottom list.
The data is updated on the fly, and you can set a refresh interval.
A sample output is shown in Figure 20-9.
Chapter 20. Web services runtime and deployment in WebSphere
501
Figure 20-9 Tivoli Performance Viewer used to monitor Web services
Note: Disable security in the server when using TPV. If you want to run TPV
with security enabled, you have to update the soap.client.props file in
<WAS_HOME>\properties with the server user ID and password:
com.ibm.SOAP.securityEnabled=true
com.ibm.SOAP.loginUserid=userid
com.ibm.SOAP.loginPassword=password
502
WebSphere Version 5.1 Web Services Handbook
Implementing a private UDDI registry
You must have WebSphere Application Server Network Deployment, which
provides the private UDDI registry, which is a single-node registry. You also need
at least one application server in which to deploy the registry.
Install the UDDI registry on an application server
Follow the instructions in the InfoCenter under Installing -> Applications -> Web
services servers -> Installing and setting up a UDDI Registry. You can select
Cloudscape (testing) or DB2 (production) as the database:
Install the Network Deployment product to get access to the UDDI
component.
Install UDDI into a stand-alone application server (for example, server1).
For a production environment, you must configure WebSphere security.
Using the UDDI registry
The UDDI registry can be accessed programmatically through the SOAP
interface—for example, by using UDDI4J—or through the EJB client interface
that is also provided. Details of these interfaces are provided in the InfoCenter.
Refer to “UDDI4J overview” on page 114 for examples of the UDDI4J API.
In addition, a UDDI GUI—also referred to as the UDDI User Console—is
provided to allow users to familiarize themselves with the key concepts of UDDI.
This UDDI GUI can be used both to publish and to inquire about UDDI entities.
The GUI does not provide all the functions of the UDDI API; for some of the more
complex operations, the programmatic interfaces should be used instead.
Using the UDDI GUI
The following sections show how to perform some simple operations using the
UDDI GUI.
Start the UDDI GUI
Open a browser with the UDDI URL and the private UDDI home page opens
(Figure 20-10).
http://<yournode>:9080/uddigui
Chapter 20. Web services runtime and deployment in WebSphere
503
Figure 20-10 Private UDDI home page
Publishing information
To add a business use the Publish tab (left side), enter a business name in the
Quick Publish field, and click Publish now (Figure 20-11).
Note that the business radio button is selected. This operation will publish a
business with the specified name using the Quick Publish option. With this
option, no other information about the entity is provided.
If you want to provide further details, such as a description and some
categorization, you should use the Advanced Publish option.
504
WebSphere Version 5.1 Web Services Handbook
Without WebSphere security
enabled all entries are owned by
the user ID: UNAUTHENTICATED
Figure 20-11 Publishing a business
To locate and edit the entries you own, click Show owned entities (Figure 20-12).
Figure 20-12 Owned entities
You can edit the business and add a description, locators (classifications), and
contacts.
Chapter 20. Web services runtime and deployment in WebSphere
505
You can add a service to the business by clicking Add service and completing the
form (Figure 20-13). You have to click Add individually for each piece of
information that you enter, and click Publish Service (bottom) when done.
Figure 20-13 Adding a service to a business
The access point is:
http://www.flashandthunder.com/ItsoFlashWeb/services/WeatherForecast
Add a technical model using Quick Publish (Figure 20-14).
Figure 20-14 Publishing a technical model
506
WebSphere Version 5.1 Web Services Handbook
Edit the technical model from the owned entities panel (Figure 20-15):
Notice the Overview URL field that can point to a WSDL file on a provider
server.
Click Update Technical Model when done.
You could alternatively provide the extra information about the technical
model at the same time as you create it by using the Advanced Publish
option.
Figure 20-15 Updating a technical model
The Overview URL for our sample service is:
http://www.flashandthunder.com/ItsoFlashWeb/wsdl/itso/bean/WeatherForecast.wsdl
Chapter 20. Web services runtime and deployment in WebSphere
507
Finally you update the service to point to the technical model:
Select Show owned entities.
Click Show Services for the business entity.
Click Edit for the WeatherForecast service.
Click Add for Technical model name (Figure 20-16).
Figure 20-16 Assigning a technical model to a service (1)
Find the technical model by searching for ITSO. Click Find Technical Models.
Select the technical model from the list of results and click Update
(Figure 20-17).
Figure 20-17 Assigning a technical model to a service (2)
Figure 20-18 shows the owned entities panel with the business, service, and
technical model.
508
WebSphere Version 5.1 Web Services Handbook
Show services
Figure 20-18 Owned entities with services and technical models
Using the UDDI Explorer with the private UDDI registry
When you are developing applications using Application Developer Version 5,
you can perform these operations using the UDDI Explorer.
Start the UDDI Explorer by clicking Run -> Launch the Web Services Explorer.
In the home panel, click UDDI Main, assign a name to the private registry, and
define the inquiry API (Figure 20-19):
http://<yournode>:9080/uddisoap/inquiryapi
Click Go to connect to the registry.
Chapter 20. Web services runtime and deployment in WebSphere
509
Figure 20-19 UDDI Explorer: Set up private UDDI registry
Publishing
Click the Publish icon ( ) and fill in the form. You must provide the publishing
API URL and a user ID and password (Figure 20-20).
The user ID becomes
the owner of the entry.
Without WebSphere
security enabled you
can type any user ID
and leave the
password empty.
Figure 20-20 Publishing a business
510
WebSphere Version 5.1 Web Services Handbook
Finding information
Use the Find icon (
) to execute queries against the registry (Figure 20-21).
Figure 20-21 Exploring the UDDI registry
For more information on the UDDI Explorer, refer to “Publishing and exploring a
UDDI registry” on page 295.
Chapter 20. Web services runtime and deployment in WebSphere
511
Summary
In this chapter we covered IBM WebSphere Application Server as the basis for
deployment of enterprise applications and Web services.
We looked at the general concepts, the administration facilities, and then
specifically at how to deploy our example applications and Web services into an
application server.
Finally we showed how to implement a private UDDI registry and access the
registry using a browser interface and the Web Services Explorer of Application
Developer.
More information
For general information on the IBM WebSphere family of products, refer to:
http://www.software.ibm.com/websphere/
For information on IBM WebSphere Application Server, refer to:
http://www.ibm.com/webservers/appserv/
The WebSphere InfoCenter is one of the most valuable and up-to-date online
resources:
http://www.ibm.com/software/webservers/appserv/infocenter.html
The WebSphere Application Server product is also covered in detail in the
publication IBM WebSphere Application Server Version 5.0 Handbook,
SG24-6195. The security details are discussed in the publication IBM
WebSphere V5.0 Security: WebSphere Handbook Series, SG24-6573.
512
WebSphere Version 5.1 Web Services Handbook
Part 3
Part
3
Appendixes
© Copyright IBM Corp. 2003, 2004. All rights reserved.
513
514
WebSphere Version 5.1 Web Services Handbook
A
Appendix A.
Installation and setup
This appendix provides brief instructions for installing the products as used in this
publication, which are:
IBM WebSphere Application Server Version 5.1
IBM WebSphere Studio Application Developer Version 5.1.1
IBM WebSphere SDK for Web Services Version 5.1
IBM alphaWorks Emerging Technologies Toolkit Version 1.2
IBM Universal Database DB2 Version 8.1, Fixpack 2 (or 7.2, with Fixpack 7)
© Copyright IBM Corp. 2003, 2004. All rights reserved.
515
Installation planning
This section provides installation planning information for the products as used in
this book.
WebSphere Application Server Version 5.1 requirements
IBM WebSphere Application Server Base and Network Deployment have the
following hardware and software requirements. For updated information on the
requirements, please refer to WebSphere InfoCenter and documentation:
http://www-3.ibm.com/software/webservers/appserv/infocenter.html
http://www-3.ibm.com/software/webservers/appserv/doc/latest/prereq.html
Hardware
Hardware requirements for Windows servers include:
Intel Pentium processor at 500 MHz, or faster
Minimum 600 MB free disk space for installation of Version 5.1
Minimum 256 MB memory; 512 MB or more recommended
CD-ROM drive
Support for a communications adapter
Software
The installation requires the following software to be installed:
Windows NT Server V4.0, SP 6a or later, Windows 2000 Server or Advanced
Server SP 3, Windows Server 2003, Windows XP Pro SP 1
Netscape Communicator 4.79 or Microsoft Internet Explorer 5.5 SP 2 and 6.0
Web browser that supports HTML 4 and CSS
For detailed hardware and software requirements, go to:
http://www.ibm.com/software/webservers/appserv/doc/v50/prereqs/was_v51.htm
Database support
For the WebSphere installation, the database does not have to be configured.
Cloudscape can be used in test environment, but other databases are required
for the production environment.
Note: This publication includes sample code that uses a database and a data
source server configuration that is for DB2 UDB V8.1, but also provides
instructions how to reconfigure for a DB2 V7.2 Fixpack 7 data source.
516
WebSphere Version 5.1 Web Services Handbook
Installing WebSphere Application Server 5.1
The InstallShield Multi Platform (ISMP) is a new installer that is used to install
WebSphere Application Server on Intel, AIX, Linux, Linux/390, and Solaris. It
checks the installation prerequisites. It also generates the uninstall program after
the product has been completely installed.
The administrative database of WebSphere Version 4 does not exist any longer.
All of the configuration information for the WebSphere Application Server Version
5 is now contained in XML files in the ${WAS_ROOT}\config directory. There are
many files that contain all the configuration information.
Installation process for Version 5.1 base product
First we start the LaunchPad (launchpad.bat) to access the product overview,
the ReadMe file, and installation guides.
Select Install the product to launch the installation wizard (Figure A-1).
After confirming that we agree with the license agreement, we have to choose
between two installation choices: Full and Custom. Full installs the entire
product, whereas Custom installation options allows you to deselect
components you do not want to install. We chose Full installation.
The installation directories for the selected components are entered in the
next window. We chose:
c:\WebSphere\AppServer
c:\WebSphere\IBMHttpServer
c:\WebSphere\WebSphere MQ
In the following panel we enter a node name and host name or IP address. In
addition, we can select to install both WebSphere Application Server and IBM
HTTP Server as a service on Windows NT, 2000, and XP.
Appendix A. Installation and setup
517
Figure A-1 WebSphere Application Server LaunchPad
After the Summary window, the installation starts.
The FirstSteps window is started automatically at the end of the installation.
Verifying the installation
Installation verification can be started from the menu. In Windows 2000, select
Start -> IBM WebSphere -> Application Server v5.1 -> First Steps. Then select
Verify Installation. We can also start with the command ivc localhost.
If the install was successful, you should see messages similar to the following:
IVTL0095I: defaulting to host <node> and port 9080
IVTL0010I: Connecting to the WebSphere Application Server <node> on port: 9080
IVTL0020I: Could not connect to Application Server, waiting for server to start
IVTL0025I: Attempting to start the Application Server
IVTL0030I: Running cmd.exe /c "C:\WebSphere\AppServer\bin\startServer" server1
>ADMU0116I: Tool information is being logged in file
>
C:\WebSphere\AppServer\logs\server1\startServer.log
>ADMU3100I: Reading configuration for server: server1
>ADMU3200I: Server launched. Waiting for initialization status.
>ADMU3000I: Server server1 open for e-business; process id is 3056
518
WebSphere Version 5.1 Web Services Handbook
IVTL0050I: Servlet Engine Verification Status - Passed
IVTL0055I: JSP Verification Status - Passed
IVTL0060I: EJB Verification Status - Passed
IVTL0070I: IVT Verification Succeeded
IVTL0080I: Installation Verification is complete
Fixpack
You should always check if Fixpacks are available to upgrade the code.
Installing WebSphere Application Server Network Deployment 5.1
To follow the examples in this publication Network Deployment is not required,
unless you want to install the private UDDI registry, as described in
“Implementing a private UDDI registry” on page 503.
The InstallShield and update wizard are used for the Network Deployment
product as well, which provides a similar look and feel across the product line.
The Web services components (UDDI registry and Web Services Gateway) are
bundled and shipped with the Network Deployment version. The EAR files for
these components are placed into the installableApps subdirectory. The scripts
and additional details on how to install these components are located in the
UDDIReg and WSGW subdirectories, respectively.
Application Server Toolkit
The Application Server Toolkit (ASTK) is a separate installable component that
can be used, for example, for configuring enterprise applications with the
Assembly Toolkit.
We did not install and use the ASTK for this publication. We used Application
Developer to configure all enterprise applications.
Appendix A. Installation and setup
519
Installation of Application Developer 5.1.1
The installation of the Application Developer is a very straightforward process.
Perform the following steps:
Double-click setup.exe and the Installation Launcher window appears
(Figure A-2).
Figure A-2 Application Developer Installation window
Select Install IBM WebSphere Studio Application Developer.
In the Welcome window, click Next.
In the License Agreement window, accept the agreement and click Next.
In the Destination Folder window, browse to a folder of your choice and then
click Next. We used c:\WSAD511 as the installation folder.
In the Custom Setup window, accept the defaults and click Next.
In the next window, click Install.
After a rather long time period the next window tells you of the success of the
installation. Click Finish.
The last window allows you to specify the location of your workspace. We use
c:\WSAD511sg246819 for the workspace location.
520
WebSphere Version 5.1 Web Services Handbook
Installing optional components
The optional components are not required to follow the samples in this
publication.
You can install these components:
IBM Agent Controller—If you want to test or debug applications running in a
real WebSphere Application Server on the same or another machine.
Embedded messaging client and server—If you want to develop
applications using WebSphere MQ. (The message-driven bean we use for
Web services can be tested using the built-in MQ Simulator.)
Rational ClearCase LT—For team development as an alternative to
Common Versions Systems (CVS).
Starting Application Developer with a dedicated workspace
You can create icons to start Application Developer with multiple workspaces. In
the Properties window of the icon, enter the target with the -data flag to indicate
the workspace location, for example:
C:\<WSAD-HOME>\wsappdev.exe -data C:\WSAD511sg246891
Appendix A. Installation and setup
521
Installation of Application Developer Integration Edition
Important: You cannot install Integration Edition on the same machine as
base Application Developer. You must remove Application Developer first. All
the functions of Application Developer are included in Integration Edition.
Installation of Application Developer Integration Edition is similar to Application
Developer. An installation window very similar to Figure A-2 is presented, where
you select to install the Integration Edition:
Follow the prompts as for Application Developer.
For features, be sure to select the WebSphere Version 5 Enterprise Edition
test environment if you want to test business processes.
When you start the product, you are prompted for a workspace. For example,
enter d:\WSAD5sg246891-IE as the workspace location (Figure A-3):
Deselect the option Use this workspace as the default and do not show this
window box again.
You are then prompted for the workspace location every time you start the
product, which enables you to use multiple workspaces.
Figure A-3 Workspace location for Integration Edition
Optionally install the embedded messaging client and server and ClearCase LT.
CICS Transaction Gateway
When you install Application Developer Integration Edition, the IBM CICS
Transaction Gateway is automatically installed as well.
Agent Controller
The IBM Agent Controller is also installed automatically for you.
522
WebSphere Version 5.1 Web Services Handbook
Installation of WebSphere SDK for Web Services 5.1
Download the zip file of WSDK (for the Windows platform) from developerWorks:
http://www-106.ibm.com/developerworks/webservices/wsdk/
Eclipse plug-in
If you want to use the Eclipse plug-in of WSDK, you have to download Eclipse
2.1.1 and install it before installing WSDK. The download site for Eclipse is at:
http://www.eclipse.org
http://www.eclipse.org/downloads/index.php
WSDK installation
Unpack the WSDK ZIP file and start the executable installer (wsdksetup.exe).
Figure A-4 shows the English version welcome screen of the installer.
Follow the prompts in the various panels. Exclude the Eclipse plug-in
installation if you do not have Eclipse 2.1.1 installed on your machine.
Figure A-4 Installer for IBM WebSphere SDK for Web Services
Specify the installation target location, for example, d:\WSDK51.
The installation creates a program folder with three icons: Start Server, Stop
Server, and WSDK Help. Start the help facility and familiarize yourself with the
concepts and tools.
Appendix A. Installation and setup
523
Installation of the Emerging Technologies Toolkit (ETTK)
The Emerging Technologies Toolkit (ETTK) evolved from the Web Services
Toolkit (WSTK). The ETTK scope has been expanded to include emerging
autonomic and grid-related technologies and Web services, and—at the same
time—the ETTK has been split up into two tracks:
ETTK Autonomic Computing
ETTK Web Services Track
The installations of the Emerging Technologies Toolkit is straightforward:
Download the executable install files from alphaWorks for either track and
platforms—Windows or Linux—from:
http://www.alphaworks.ibm.com/tech/ettk
Run the executables and follow the instructions and prompts of the
InstallShield wizard. The wizard looks for the default JDK, but allows the user
to browse for the appropriate JDK.
Note: You require an application server to run the ETTK. This can be the
WebSphere SDK for Web Services (WSDK) 5.1, WebSphere Application
Server 5.0.2 or later, or Apache Tomkat 4.1.27 or later.
Installing the sample code
The sample code is available from the ITSO Redbooks Web site:
http://www.redbooks.ibm.com
Follow the link Additional Materials and look for the SG246891 directory matching
this book. Download the sample code, sg246891-01code.zip, and extract the files
to your hard drive, creating a directory c:\SG246891-01.
The content of the sample code is described in “Web material content” on
page 526.
Setting up the WEATHER database
To work through the weather forecast samples you have to set up the WEATHER
database as described in “Set up the WEATHER database” on page 528.
524
WebSphere Version 5.1 Web Services Handbook
B
Appendix B.
Additional material
This redbook refers to additional material that can be downloaded from the
Internet as described below.
Locating the Web material
The Web material associated with this redbook is available in softcopy on the
Internet from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/SG246891
Alternatively, you can go to the IBM Redbooks Web site at:
ibm.com/redbooks
Select the Additional materials and open the directory that corresponds with
the redbook form number, SG24-6891-01 (SG246891).
© Copyright IBM Corp. 2003, 2004. All rights reserved.
525
Using the Web material
The additional Web material that accompanies this redbook includes the
following files:
File name
Description
sg246891-01code.zip Sample code for following the samples in the book
corrections-01.txt
Corrections to the book after publishing
System requirements for downloading the Web material
The following system configuration is recommended:
Hard disk space
Operating System
Processor
Memory
3 GB
Windows 2000 or Windows NT
700 MHz or better
512 MB, recommended 784 MB
Web material content
Unzip the contents of the Web material sg246891-01code.zip file onto your hard
drive. This creates a folder structure c:\SG246891-01\sampcode\xxxx, where
xxxxx refers to a chapter or activity in the book:
_setup
Database setup and initial EAR files
weatherforecast
Basic code of the weather forecast example
wsad51
Sample code for Web services development using
WebSphere Studio Application Developer
wsad51security
Sample code for Web services with WS-Security 1.0
wsad-ie
Sample code for Application Developer Integration Edition
(this code has not been updated for Version 5.1)
wsdk51
Sample code for WebSphere SDK for Web Services
scenario
Sample code for Web services scenario
was
Deployment into Application Server
z_EARfiles
Final EAR files from Application Developer
z_workspace
Application Developer workspace projects
ItsoXxxxxxx
526
- Projects for import into workspace
WebSphere Version 5.1 Web Services Handbook
Workspace projects
Table B-1 lists the sample projects for Web service development with Application
Developer. Projects prefixed with a dash (-) belong to the enterprise application
listed above the project.
Table B-1 Application Developer projects (part 1)
Name
Description
ItsoWebService1
Web service from JavaBean
- ItsoWebService1Web
Web project with Web service
- ItsoWebService1WebClient
Client project to test Web service
- ItsoWebService1JavaClient
Stand-alone client application
ItsoWebService2
Web service from session EJB (HTTP-based)
- ItsoWebService2EJB
EJB project with session EJB
- ItsoWebService2EJBClient
Client project to test Web service
- ItsoWebService2RouterWeb
Router project to invoke EJB Web service
ItsoWebService3
Web service from session EJB (JMS-based)
- ItsoWebService3EJB
EJB project with session EJB
- ItsoWebService3EJBClient
Client project to test Web service
- ItsoWebService3RouterEJB
Router project with message-driven bean
ItsoWebService4
Web service top-down from WSDL
- ItsoWebService4Web
Web project with Web service
- ItsoWebService4WebClient
Client project to test Web service
ItsoWebService5
Web service from URL and DADX
- ItsoWebService5Web
Web project with Web service
- ItsoWebService5WebClient
Client project to test Web service
ItsoWebService6
WS-Security with EJB Web service
- ItsoWebService6EJB
EJB project with session EJB
- ItsoWebService6EJBClient
Client project to test Web service
- ItsoWebService6RouterWeb
Router project to invoke EJB Web service
Appendix B. Additional material
527
Table B-2 lists the sample projects of the scenario sample application for Web
Application Developer. Projects prefixed with a dash (-) belong to the enterprise
application listed above the project.
Table B-2 Application Developer projects (part 2)
Name
Description
ItsoIWA
International Weather Association EAR project
- ItsoFlashWeb
Web project for Flash Web service
- ItsoThunderWeb
Web project for Thunder Web service
- ItsoSiliconWeatherWeb
Web project for SiliconWeather Web service
- ItsoSiliconWeatherEJB
EJB project for SiliconWeather EJB Web service
- ItsoSiliconWeatherEJBRouter
EJB router project with message-driven bean
- ItsoIWAUpdateWeatherClient
Client Web project to update weather information
ItsoUnitedSuns
UnitedSuns EAR project
- ItsoUnitedSunsClient
Client Web project to invoke Web services
- ItsoWebService2EJBClient
Client project to test Web service
Installing the weather forecast application
Here are short instructions for how to install the starting sample code in
Application Developer 5.1.1.
Create a workspace for the samples, for example, c:\WSAD511sg246891.
Set up the WEATHER database
A DB2 command stream to define the WEATHER database is provided in
sg246891-01\sampcode\_setup\Database\Itsoweather.ddl.
There are two subdirectories with command files to execute the command
stream, DB2V7 and DB2V8. Use the subdirectory that matches your DB2
installation:
Execute the createWeather.bat file to define the database and table.
Execute the loadWeather.bat file to delete the existing data and add two
records.
Execute the listWeather.bat file to list the content of the database.
528
WebSphere Version 5.1 Web Services Handbook
Set up the WebSphere test server (WeatherServer)
The best way to set up a server is to define a server and configure it.
Server project
Definitions of servers are stored in a server project. To define such a project:
Select File -> New -> Project (or use the New icon (
toolbar).
) from the main
Select Server -> Server Project and click Next.
Enter Servers as the project name, and accept the default location.
Click Finish. The Confirm Perspective Switch window opens.
Click Yes and the Server perspective opens.
WebSphere Version 5.1 server
Now we define a WebSphere server for testing the EJBs. Because we implement
EJB 2.0 beans we must use the Version 5 server for testing.
Select File -> New -> Server and Server Configuration (or use the New icon
( ) from the main toolbar).
Select Server in the left pane and Server and Server Configuration in the right
pane, and click Next.
Enter WeatherServer as the name. The Servers project is preselected.
Expand WebSphere version 5.1 and select Test Environment.
Click Next. Check that the port is set to 9080 and click Finish.
Note: Application Developer Version 5.1.1 includes a WebSphere Application
Server Version 5.1.
Configuring the server
We use the WeatherServer to access the WEATHER database using EJBs. We have
to configure a data source for this access:
Open the WeatherServer in the Server Configuration view.
Look through the different pages of configuration information.
Define an authentication alias
Go to the Security page to define a user ID and password for the data source.
Click Add for JAAS Authentication Entries.
Appendix B. Additional material
529
Complete the window with a valid user ID and password (for example, the user ID
that was used to install DB2) and click OK (Figure B-1).
A JAAS alias is
required if the
container does the
authentication of
the user ID.
Figure B-1 Defining a user ID for authentication
The entry appears in the list on the Security page (Figure B-2).
Figure B-2 Server configuration: Security
Define a data source
Next, go to the Data source page. Note that there are Node Settings and Server
Settings. In the test environment we only run one server on one node. Therefore,
it does not matter where we define the data source for the WEATHER database.
Depending on the version of DB2, we define a data source for Version 8.1 or for
Version 7.2.
530
WebSphere Version 5.1 Web Services Handbook
DB2 Version 8.1
To define a data source follow these steps:
Scroll down to Server Settings. Click Add for JDBC Providers.
In the dialog, select IBM DB2 and DB2 Universal JDBC Driver Provider (XA).
Enter DB2 Universal JDBC Provider as the Name. Note that the classpath
uses the variable ${DB2UNIVERSAL_JDBC_DRIVER_PATH}.
Click Finish.
Select the JDBC Provider and click Add for Data source.
Click Add next to the Data source list.
In the Create a Data Source window, select DB2 Universal JDBC Driver
Provider for the type of JDBC provider and Version 5.0 data source for the
type of data source. Click Next.
The Modify Data Source window opens (Figure B-3).
Figure B-3 Define the data source for the WEATHER database
Appendix B. Additional material
531
Complete the Modify Data Source window:
– Enter WEATHER1 as the name to be displayed in the list of data sources.
– Enter jdbc/sjweather as the JNDI name (this is what we specify in the
EJB deployment descriptor to access the database).
– Verify the Data store helper class name (DB2DataStoreHelper).
– Select the DB2User for component- and container-managed authentication
alias.
– Deselect Use this data source in container-managed persistence (CMP).
We are not using container-managed persistence.
– Optionally enter a description. We do not specify the database name yet.
Click Next. In the Create Resource Properties window, select the
databaseName property and change the value to WEATHER (Figure B-4).
Click Finish.
Figure B-4 Setting the database name
The data source is added to the list and displayed in the server configuration
(Figure B-5).
532
WebSphere Version 5.1 Web Services Handbook
Figure B-5 Server configuration with data source
DB2 Version 7.2
Follow the instructions given for DB2 Version 8.1, but select the Default DB2
JDBC Provider (you do not have to define a provider):
Define the data source for the default provider.
Select DB2 JDBC Provider, otherwise the instructions are the same.
Verify the server variables
We have to set up the server variables that point to the DB2 JDBC providers:
On the variables page check the two variables DB2_JDBC_DRIVER_PATH and
DB2UNIVERSAL_JDBC_DRIVER_PATH. Both have to point to your DB2 installation
java directory, for example:
c:\SQLLIB\java
c:\Program Files\SQLLIB\java
Save the server configuration and close the editor.
Appendix B. Additional material
533
Configure the JMS server
We configure a JMS server inside the WeatherServer. We have to perform four
modifications in the server configuration:
Define a QueueConnectionFactory object.
Define a Queue object.
Add the Queue to the list of queues of the JMS provider.
Select the type of JMS server.
Define the listener port.
Here are the steps to configure the server with JMS:
Open the configuration of the WeatherServer.
Go to the JMS page.
Scroll down to the JMS Connection Factories section. For JMS Connection
Factories, click Add next to the WasQueueConnectionFactory entries. Supply
the Name and JNDI Name as shown in Figure B-6. Accept the default values
of the remaining fields.
Figure B-6 Add a QueueConnectionFactory to the server configuration
For JMS Destinations, click Add next to WASQueue. Supply the Name and JNDI
Name values as shown in Figure B-7. Accept defaults for the remaining fields.
Figure B-7 Add a Queue to the server configuration
For JMS Server Properties, click Add next to Queue names. Enter
WeatherQueue and click OK.
Select MQ Simulator for Java Developers under JMS Provider.
For the sake of simplicity we use the built-in messaging simulator instead of
WebSphere MQ.
After these additions, the JMS page should look like Figure B-8.
534
WebSphere Version 5.1 Web Services Handbook
Figure B-8 JMS server configuration
Go to the EJB page.
On the EJB page we add the listener port. Click Add and specify the values as
shown in Figure B-9.
Appendix B. Additional material
535
Figure B-9 Add a Listener Port
Runtime classpath
For JMS-based Web services, one JAR file is required in the server classpath:
On the Environment page, expand Class Path.
Click Add External JARs.
Navigate to c:\<wsad-home>\runtimes\base_v51\lib\urlprotocols.jar and
click Open (Figure B-10).
c:\WSAD511\runtimes\base_v51\lib\urlprotocols.jar
Figure B-10 Update the classpath
Important: Ensure that the urlprotocols.jar file is added to the Class Path
field of the Environment tab. During our testing we observed that this or any
other JMS samples do not run in WSAD 5.1 until this step is performed.
536
WebSphere Version 5.1 Web Services Handbook
At this point start the WeatherServer and watch the Console messages. The JMS
Provider is started and the queue is bound:
[...] ... JMSMQJDProvid A MSGS0656I: Starting the MQJD JMS Provider
[...] ... JMSMQJDProvid A MSGS0650I: MQJD JMS Provider open for business
[...] ... ResourceMgrIm I WSVR0049I: Binding WeatherQCF as jms/WeatherQCF
Stop the server when you have verified that the JMS server starts.
Set up the initial applications for Web services development
Enterprise application EAR files to create the starting applications in the
Application Developer workspace directory are provided in the
sg246891-01\sampcode\_setup\EAR directory of the sample code (see “Web
material content” on page 526).
To import the EAR files into the workspace:
Start WebSphere Studio Application Developer if it is not already started.
Select File -> Import -> EAR file and click Next.
Click Browse for the EAR file and locate the ItsoWebService1.ear file (in
sg246891-01\sampcode\_setup\EAR). Select the file and click Open, make
sure the project name is ItsoWebService1, then click Finish.
Repeat this for the ItsoWebService2.ear and ItsoWebService3.ear files.
Make sure the project names are ItsoWebService2 and ItsoWebService3.
Test the starting application
To test the starting enterprise application:
Select the WeatherServer (in the Server Configuration or Servers view) and
Add and remove projects. In the dialog select the three ItsoWebServiceX
projects and click Add>, then click Finish.
Start the WeatherServer.
Expand the ItsoWebService1Web project, select the WeatherTester servlet
and Run on Server:
– Select the WeatherServer when prompted, then click Next. Deselect
Deploy EJB beans (the code is already generated) and click Finish.
– The servlet runs the methods of the WeatherForecast JavaBean and
displays the weather results.
Appendix B. Additional material
537
Test the ItsoWebService2 application using the universal test client (UTC):
– Expand EJB Modules -> ItsoWebService2EJB -> Session Beans (in the
J2EE Hierarchy view).
– Select the WeatherForecastEJB bean and Run on Server.
– In the universal test client window, expand WeatherForecastEJB ->
WeatherForecastEJBHome, select the create method, click Invoke. and
afterwards click Work with Object.
– Expand WeatherForecastEJB1 and select the getForecast(Calendar, int)
method. Type 9 for the int value and click Invoke.
– The result is an array with 10 Weather elements. Click Work with Object.
– Expand Weather[10] and select Inspect Fields. There should be 10
weather predictions.
– Optionally test the other methods (getDayForecast, getTemperatures).
Run the listWeather.bat command file (sampcode\_setup\Database\DB2Vx)
and you should see the rows that were added with the current date and the
next 9 days.
Installing the scenario sample application
The scenario sample application is provided in two EAR files, ItsoIWA.ear and
ItsoUnitedSuns.ear, and a server configuration (ScenarioServer).
The instructions for installing and configuring the scenario sample application are
provided in “Installing the scenario in Application Developer” on page 473.
Installing the sample applications into WebSphere
The instructions for configuring a WebSphere Application Server for the scenario
and sample applications are provided in “Configuring a server for the ITSO Web
services” on page 487.
The instructions for installing and configuring the scenario and sample
applications into a WebSphere Application Server are provided in “Install the
enterprise applications” on page 494.
538
WebSphere Version 5.1 Web Services Handbook
Importing solutions into Application Developer
The z_workspace directory contains all the finished projects that can be imported
into an Application Developer workspace. Import the projects in the sequence
listed in Table B-1 on page 527 and Table B-2 on page 528.
Importing a sample project into Application Developer
To import a sample project ItsoWebServiceXXX from the sample code into the
Application Developer workspace, execute these steps:
Copy the desired project(s) from the sample code installation directory into
the Application Developer workspace directory:
From: sg246891-01\sampcode\z_workspace
To:
c:\WSAD511sg246891
Sample code
Application Developer workspace
In Application Developer, select File -> Import.
In the Import wizard (Figure B-11) select Existing Project into Workspace and
click Next.
Figure B-11 Application Developer Import Wizard
Appendix B. Additional material
539
In the Import Project window (Figure B-12) click Browse to select the project
contents directory.
c:\WSAD511sg246891\ItsoWebServiceXX
Figure B-12 Import project
In the Browse For Folder window (Figure B-13) browse to the location of the
desired project folder and click OK.
c:\WSAD511sg246891\ItsoWebServiceXxx
Figure B-13 Browse for folder: Import a project
540
WebSphere Version 5.1 Web Services Handbook
Back in the import wizard, click Finish. The selected project is added into the
Workspace.
Tip: After importing several projects that have dependencies on each other, it
may be necessary to rebuild all or selected projects:
Select a project and Project -> Rebuild Project (for one project).
Select Project -> Rebuild All (for all projects).
Importing a single source file into Application Developer
To import a sample source code file execute these steps:
Select the target folder in the workspace and Import (context).
In the Import wizard select File System and click Next.
Click Browse and locate the folder that contains the desired file in the
sg246891-01\sampcode\workspace\ItsoWebServiceXxxxx project directory
(Figure B-14). Click OK.
Project folder
Source folder
Figure B-14 Import from directory: Import files
Appendix B. Additional material
541
In the Import wizard, select the desired file(s) in the right pane. Do not select
the folder in the left pane (otherwise a subfolder is created in the workspace).
Verify the destination folder (Figure B-15).
Figure B-15 Import file selection window
Click Finish.
Universal test client problem
In Application Developer Version 5.1 you may get marshalling errors when
running the universal test client after generating the Web services. A solution is
to open the WeatherServer server configuration and on the Configuration page
set the Application class loader policy to SINGLE. You have to restart the server.
542
WebSphere Version 5.1 Web Services Handbook
Abbreviations and acronyms
AAT
Application Assembly Tool
EDI
Electronic data interchange
API
Application programming
interface
EIS
Enterprise information system
EJB
Enterprise JavaBeans
ASTK
Application Server Toolkit
EJS
Enterprise Java Server
AXIS
Apache eXtensible Interaction
System
EPI
External presentation
interface
B2B
Business-to-business
ERP
Enterprise resource planning
B2C
Business-to-consumer
ETTK
B2E
Business-to-employee
Emerging Technologies
Toolkit
BPEL
Business process execution
language
FDML
Flow definition markup
language
CCF
Common Connector
Framework
FTP
File Transfer Protocol
GUI
Graphical user interface
CCI
Common client interface
HTML
Hypertext Markup Language
CICS
Customer Information Control
System
HTTP
Hypertext Transfer Protocol
CORBA
Common Object Request
Broker Architecture
IBM
International Business
Machines Corporation
CRM
Customer relationship
management
IDE
Integrated development
environment
CTG
CICS Transaction Gateway
IIOP
Internet Inter-ORB Protocol
CVS
Common Versions System
IMS
Information Management
System
DAD
Document access definition
ITSO
DADX
Document access definition
extended
International Technical
Support Organization
IWA
DBMS
Database management
system
International Weather
Association (fictitious0
JCA
J2EE connector architecture
DCOM
Distributed common object
model
J2C
J2EE connector architecture
DII
Dynamic invocation interface
J2EE
Java 2 Enterprise Edition
DOM
Document object model
J2SE
Java 2 Standard Edition
DTD
Document type definition
JAR
Java archive
EAR
Enterprise application archive
JAX-RPC
Java APIs for XML based
RPC
ECI
External call interface
JDBC
Java Database Connectivity
© Copyright IBM Corp. 2003, 2004. All rights reserved.
543
JDK
Java Developer’s Kit
SPO
Service provider offering
JMS
Java Messaging Service
SQL
Structured query language
JMX
Java Management eXtension
SSL
Secure Sockets Layer
JNDI
Java Naming and Directory
Interface
TCP/IP
Transmission Control
Protocol/Internet Protocol
JSP
JavaServer Page
TPV
Tivoli Performance Viewer
JSR
Java specification request
UDDI
LDAP
Lightweight Directory Access
Protocol
Universal description,
discovery, and integration
UNSPSC
MVC
Model-view-controller
Universal Standard Products
and Services Classification
NAICS
North American Industry
Classification System
URL
Uniform resource locator
URN
Uniform resource name
OMG
Object Management Group
UTC
Universal test client
PMI
Performance monitor
interface
UUID
Universal unique identifier
WAR
Web application archive
PKI
Public key interface
WORF
QOS
Quality of service
Web service object runtime
facility
RAD
Rapid application
development
WSCA
Web services conceptual
architecture
RAR
Resource adapter archive
WSDL
RDBMS
Relational database
management system
Web service description
language
WSDK
WebSphere SDK for Web
Services
RMI
Remote Method Invocation
RPC
Remote procedure call
WSFL
Web services flow language
SAAJ
SOAP with Attachments API
for Java
WSGW
Web Services Gateway
WS-I
Web services interoperability
SAML
Security assertion markup
language
WSIF
Web services invocation
framework
SAX
Simple API for XML
WSIL
SCM
Supply chain management
Web services inspection
language
SDK
Software Development Kit
WSTK
Web Services Toolkit
SEI
Service endpoint interface
WWW
World Wide Web
SMTP
Simple Mail Transfer Protocol
XMI
XML metadata interchange
SOA
Service oriented architecture
XML
eXtensible Markup Language
SOAP
Simple Object Access
Protocol (also known as
Service Oriented Architecture
Protocol)
XSD
XML schema definition
544
WebSphere Version 5.1 Web Services Handbook
Related publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.
IBM Redbooks
For information on ordering these publications, see “How to get IBM Redbooks”
on page 548.
WebSphere Version 5 Application Development Handbook, SG24-6993
WebSphere Studio Application Developer Version 5 Programming Guide,
SG24-6957
EJB 2.0 Development with WebSphere Studio Application Developer,
SG24-6819
IBM WebSphere Application Server Version 5.0 Handbook, SG24-6195
IBM WebSphere V5.0 Security: WebSphere Handbook Series, SG24-6573
Legacy Modernization with WebSphere Studio Enterprise Developer,
SG24-6806
WebSphere Studio Application Developer Programming Guide, SG24-6585
Web Services Wizardry with WebSphere Studio Application Developer,
SG24-6292
Self-Study Guide: WebSphere Studio Application Developer and Web
Services, SG24-6407
WebSphere Version 4 Application Development Handbook, SG24-6134
Programming J2EE APIs with WebSphere Advanced, SG24-6124
CICS Transaction Gateway V5 The WebSphere Connector for CICS,
SG24-6133
Enterprise JavaBeans for z/OS and OS/390 CICS Transaction Server V2.1,
SG24-6284
Design and Implement Servlets, JSPs, and EJBs for IBM WebSphere
Application Server, SG24-5754
Integrating your Information, Getting stated with DB2 UDB, WebSphere MQ,
XML and Web Services, SG24-6892
© Copyright IBM Corp. 2003, 2004. All rights reserved.
545
Other resources
These publications are also relevant as further information sources:
WebSphere Bible, Kataoka et al, ISBN 0764548964, Wiley, John & Sons,
2002
Web Services: Building Blocks for Distributed Systems, Glass, ISBN
0130662569, Prentice Hall, 2001
SOAP Programming with Java, Brogden, ISBN 0782129285, Sybex, 2002
XML and Web Services Unleashed, Schmelzer et al, ISBN 0672323419,
SAMS, 2002
Referenced Web sites
These Web sites are also relevant as further information sources:
IBM Internet Web site
http://www.ibm.com/webservices/
Web services on developerWorks
http://www.ibm.com/developerworks/
http://www.ibm.com/developerworks/webservices
Web services on alphaWorks
http://www.alphaworks.ibm.com/
http://www.alphaworks.ibm.com/webservices
Web services interoperability
http://www.ws-i.org
IBM Software
http://www.ibm.com/software/websphere
http://www.ibm.com/software/webservers/
http://www.ibm.com/software/solutions/webservices
http://www.ibm.com/software/integration/busconn/gateway.htm
http://www.ibm.com/software/ad
http://www.ibm.com/software/ts
http://www.ibm.com/software/pervasive
IBM Tivoli
http://www.tivoli.com/
Eclipse
http://www.eclipse.org
546
WebSphere Version 5.1 Web Services Handbook
UDDI Web sites and registries
http://www.uddi.org
http://www.uddi4j.org
http://www.ibm.com/services/uddi
http://uddi.ibm.com
http://uddi.microsoft.com
http://uddi.sap.com
http://www.ntt.com/uddi
Apache open-source Web site
http://www.apache.org/
http://cvs.apache.org/
OASIS
http://www.oasis-open.org
World Wide Web Consortium W3C
http://www.w3.org/
XML schema
http://schemas.xmlsoap.org/
Sun Java Web site
http://java.sun.com/
Java Community Process
http://www.jcp.org/en/jsr/
Microsoft SOAP
http://msdn.microsoft.com/
XMethods
http://www.xmethods.net/inspection.wsil
Related publications
547
How to get IBM Redbooks
You can order hardcopy Redbooks, as well as view, download, or search for
Redbooks at the following Web site:
ibm.com/redbooks
You can also download additional materials (code samples or diskette/CD-ROM
images) from that site.
IBM Redbooks collections
Redbooks are also available on CD-ROMs. Click the CD-ROMs button on the
Redbooks Web site for information about all the CD-ROMs offered, as well as
updates and formats.
548
WebSphere Version 5.1 Web Services Handbook
Index
A
abbreviations 543
AbstractServlet 442
access point 105
acronyms 543
activity 160, 164, 166, 348
administrative console 480, 482
Agent Controller 522
alphaWorks 137, 167, 181, 524, 546
Apache
Axis 20
Web site 44
SOAP 19
implementation 35
server 35
Apache eXtensible Interaction System
see Axis 19
Application Assembly Tool 484
Application Developer
import 539
Application Server Toolkit 484
Assembly Toolkit 484
ASTK 484
asynchroneous Web service 236
auditing 196, 198
authentication 94, 178–179, 191, 196, 198, 309
alias 529, 532
Application Developer 310
client 310
server 312
testing 314
authorization 94, 178, 196, 198, 337
availability 198
Axis 19–20, 40
client architecture 41
server architecture 41
subsystems 42
B
B2B 100, 213
B2C 213
B2C Web application 13
B2E 213
© Copyright IBM Corp. 2003, 2004. All rights reserved.
basic authentication 190, 309
Bean2WebService 384, 388
binding
HTTP 61
MIME 62
SOAP 60
stub 72
template 101, 104
UDDI 152
WSDL 57
WSIL 150
WS-Inspection 150
block activity 348
body 21, 26
SOAP 26
bottom-up
Application Developer 248
development 223
Integration Edition 342
WSDK 394
BPEL 10, 159
Web site 168
BPEL4WS 165
concepts 165
BPWS4J
Web site 168
breakpoint 374
broker 6
business 10
entity 101
publishing 296
information 12
integration 12
models 11
process 7, 10, 159–160, 166, 347
execution language 165
see BPEL
externalization 12
Web client, 371
wizard 352
registry 107
relationships 102, 105
rule 7
service 101
549
Business Integration
perspective 345
business-to-business 100, 213
business-to-consumer 12, 213
business-to-employee 213
C
cell 481
certificate 195, 319, 498
certification agency 195
chain 41
channel 171, 173, 175
CICS 344
CICS Transaction Gateway 522
ClearCase LT 210
client
application 441
programming model 79
Web service 264
Common Business Objects 219
Common Versions System 210
communication
protocol 4
style 22, 28
compensation service 164
composable 11
compound type 30
confidentiality 94, 193, 196, 198, 326
client 327
server 331
configuration 333
testing 334
container 165
container-managed persistence 532
control link 161, 348, 369
CORBA 24
CrossWorlds 219
customer relationship management 213
CVS 210
data source
configuration 488, 529, 531
DB2
Everyplace 215
Legacy CLI-base Type 2 JDBC Driver 496
Universal JDBC Driver Provider 488
XML Extender 249
DB2_JDBC_DRIVER_PATH 489
DB2DataStoreHelper 532
DB2UNIVERSAL_JDBC_DRIVER_PATH 489
DB2User 530, 532
DCOM 24
debugger 374
deployment 301
descriptor 82, 305
SOAP 32
enterprise application 484
manager 481
SOAP 36
description language 5
deserialization 31
deserializer 33, 35, 38
developerWorks 140, 546
Web site 44
digital signature 126
DII 73, 81
document
access definition extension
see DADX
style
SOAP 28
type definition 26
WSDL 47
DTD 26
dynamic
binding 229
client 229
invocation interface 73, 81
proxy 73, 81
Web service 229
Web services 100, 131, 454
D
DADX 248
file 292
group 290, 496
data
link 162
model
SOAP 28
550
E
EAR
export 301
e-business 11
Eclipse 208
WSDK plug-in 383, 416
WebSphere Version 5.1 Web Services Handbook
WSDK server 417
EJB
authorization 337
client JAR 211
container
programming model 88
EJB2WebService 384, 393, 410
electronic data interchange 4
e-marketplace UDDI 121
Emerging Technologies Toolkit 167, 382
encoding 22, 32
SOAP 32
encryption 186, 193
enterprise
application
deployment 301, 484
installation 473, 494
start/stop 486
information systems 342
security 197
services 342
Web services 77
entity promotion 125
envelope 21
SOAP 24
error handling 27
ETTK 382
installation 524
explorer 296
eXtensible Markup Language
see XML
extranet UDDI 122
F
fault
activity 348
code 27
element 26
handler 166
message 27
FDML 10, 159, 163
elements 164
example 368
filter 171, 173, 176
find_binding 118
find_business 116
find_service 117
find_tModel 118
FlashAndThunder 430
flow 355
definition markup language 163
model 161
flow definition markup language
see FDML
G
garbage collection 20
gateway 169–170
security 177
global security 191, 491
H
handler 41, 93
header 25
SOAP 22
Host On Demand 344
HOSTS file 476, 494
hot method replace 210
HTTP 195
binding 61
extension framework 20
header 23
plug-in 495
server plug-in 486
HTTPS 195, 497
configuration 498
I
ibm-webservices-bnd.xmi 305
ibm-webservicesclient-bnd.xmi 305
ibm-webservicesclient-ext.xmi 305
ibm-webservices-ext.xmi 305
ID assertion 309
identification 196, 198
IDL 47
IIOP 131, 206
ikeyman 498
import 539
WSDL 51
information
center 208
set 64
installation
ETTK 524
WebSphere Application Server 516
Index
551
WebSphere Studio Application Developer 520
WebSphere Studio Integration Edition 522
WSDK 523
InstallShield Multi Platform (ISMP) 517
integration 4
Integration Edition
see WebSphere Studio Application Developer
Integration Edition 341
Integrator Broker 218
integrity 94, 187, 191, 196, 198, 316
client 316
server 322
testing 324
interface definition language 47
International Weather Association 431
internationalization 107
interoperability 4, 15, 30, 282
interoperable 10
intranet 10
ItsoWebService1 251, 253
ItsoWebService1JavaClient 264
ItsoWebService1WebClient 253
ItsoWebService2 251, 271
ItsoWebService2RouterWeb 271
ItsoWebService3 251, 274
ItsoWebService3EJBRouter 274
ItsoWebService4 279
ItsoWebService5 285, 290
ItsoWebService6 308
ItsoWebService7 409
IWA 431
application 467
K
key locator 318
keytool 319
J
J2C 211
J2EE
client 403
Connector Architecture
see JCA
role 85
security 94, 337
Web services 77
J2SE client 403
JAAS 310, 529
Java
API for XML based Remote Procedure Call 67
APIs for WSDL 63
build path 267
552
Management Extensions 207
Messaging Service 47
SDK 1.4.1 208
security 492
snippet 164, 348, 369
snippets 362
JavaServer Faces 211
JAX-RPC 67, 382
client 69
deployment descriptor 82
mapping deployment descriptor 83
WSIF 135
JCA 131
adapters 344
Web services 131
JDBC
provider 531
jdbc/sjweather 532
JDK 1.4.1 210
JMS 95, 132, 206, 212
provider 489
resources 489
JMX 207
JNDI 80
JSF 211
JSR 101 67, 210, 382–383
JSR 109 77, 210, 258, 382–383
security 94
JSR 110 63
Jython 208
L
language-independent 10
LDAP 213
legacy systems 8, 13, 137, 215, 344
link 161, 348
Linux 205, 381, 383, 397
listener port 490
literal
encoding 32
XML 32
loop activity 349
LTPA 309
WebSphere Version 5.1 Web Services Handbook
M
managed
client 74
process 480
mapping
JAX-RPC 75
SOAP 33
marshalling 31
MDB 274
message
oriented style 28
SOAP 21
WSDL 54
message-driven bean 274
message-oriented style 22
Microsoft SOAP Toolkit 20, 42
SOAP
Microsoft 19
MIME
binding 62
motivation 4
MQSeries
see WebSphere MQ
Workflow 219
mustUnderstand 25
N
NAICS 102, 106
namespaces 24
SOAP 24
WSDL 52
WS-Inspection 145
Network Deployment 105, 123
node agent 481
non-repudiation 196, 198
O
OASIS 100, 167, 188
operation 46
Oracle ERP 344
P
palette 354
partner 166
PeopleSoft 344
plug-in 495
port 46
port type
WSDL 55
private UDDI registry 120, 503
process
breakpoint 376
business 160
debugger 374
editor 347
files 362
flow 355
interface 365
programming
language 4, 15
model 78
EJB 88
Web 89
style 70
project
server 529
protocol 196, 199
provider 132, 161
proxy 260
authentication 179
class 71
classes 263
secure 444
UDDI 115, 450
WSIF 135
public broker
broker
public 6
publisher
assertions 102
publishing 104
Python 208
Q
quality of service 130
queue
connection factory 490
destination 490
R
Redbooks Web site 548
Contact us xxviii
registry
UDDI 100
relationships 105
Index
553
remote procedure call 22
replication 107
request security handler 304
requirements 4
scenario 431
resource adapter 343
response security handler 305
RMI 20
role 85
RPC 22, 28, 35
style 60
rule engine 7
S
SAAJ 138, 207
SAML
Web site 200
save_business 120
SAX 40
scenario 429
build 438
client 441
deployment 439
enterprise applications 474
installation 473, 494
preferences 445
requirements 431
run 439, 477
sample 1 454
sample 2 461
server 475
setup 435
static client 471
scope 37
secure proxy 444
security 5, 185
enterprise 197
exposures 186
framework 199
gateway 177
global 191
role references 87
token 191, 309
generation architecture 309
tokens 304
transport channel 194
SEI 72, 80, 259
self-contained 10
554
self-describing 10
self-signed certificate 498
serialization 31
serializer 33, 35, 38
server
configuration 333, 529, 532
decrypt 493
deployment descriptor 90
encrypt 493
programming model 86
project 529
security 494
service
broker 5–6
compensation 164
endpoint interface 72, 79
implementation bean 87
interface 72, 79
locator 72
project 350
projection 105
provider 5–6
registry 6
requestor 5–6, 54, 64, 100, 103–104, 128, 170,
227, 386, 408, 431
WSDL 58
WSIL 148
WS-Inspection 148
service-oriented architecture 3, 19
concepts 5
session EJB 88
sg246891code.zip 526
Siebel 344
SiliconWeather 430
simple API for XML 40
Simple Object Access Protocol
see SOAP
SMTP 195
SOAP 8
1.1 specification 44
architecture 19
binding 60
body 21, 26
Call object 38
client API 38
communication style 28
data model 28, 30
deployment 36
deployment descriptor 32, 36
WebSphere Version 5.1 Web Services Handbook
encoding 22, 32
engine
WebSphere 42
envelope 21
error handling 27
fault 26–27
fault response 306
header 22, 25
implementation 34
input message 270
intermediary 25
mapping 33
message 21, 24
authentication 189, 315
confidentiality 193, 334
encryption 193
integrity 192, 324
security 304
tracing 269
validation 283
Microsoft 20, 42
over HTTP 95
over JMS 95, 208, 236, 274
overview 20
response message 271
specification
Web site 44
Toolkit 19–20
with Attachments API for Java 138
SOAP4J 35, 40
soapearenabler 487
SQL statement 290
SQLJ 210
SSL 178, 185, 195, 497, 499
staff activity 349
stand-alone client 264, 500
stateless session EJB 88
static
stub 71, 80
Web service 100, 228
StringService 390
Struts 210
stub 136
stub-less 135
style 32
subscription API 127
supply chain management 213
SyncML standard 215
T
taxonomy 5, 101
TCP/IP
Monitor 269
view 270
monitoring 40
Monitoring Server 269
test registry 107–109, 295, 300, 405, 445, 455, 461
TestClient.jsp 262
Tivoli Access Manager 208
for Business Integration, 200
Tivoli Performance Viewer 479, 500
tModel 101
top-down
Application Developer 249
development 223
Integration Edition 343
WSDK 388
topology 125
TPF 479, 500
transaction 186
transport
channel security 187, 194, 497
listener 41
type
mapping 83
U
UBR 100
UDDI 8
API 114
binding 152
binding example 155
Business Registry 100, 107
client 115
cloud 120
data model 103
Explorer 295, 509
extranet 122
find 109
find binding 450
find business 448
find service 449
find tModel 450
find_binding 118
find_business 116
find_service 117
find_tModel 118
Index
555
GUI 503
IBM Web site 128
inquiry API 127
internationalization 107
introduction 99
library 115
lookup 454
lookup sample 446
policies 126
policy 126
pollution 121
private registry 120
proxy 115, 448, 450
publish 112
publishing 104
Application Developer 295
registry 147
installation 503
structure 101
replication 107
scenario 434
security 126
taxonomy 101
Test Registry 296
topology 125
Version 2 105
Version 3 124
Web front-end 109
Web site 128
UDDI4J 114, 230, 433, 439, 446, 448, 503
UDDIPublish 384, 403
UDDIUnpublish 384, 405
UML Visual Editor 210
unified resource name
see URN
UnitedSuns 431
universal description, discovery, and integration
see UDDI
universal resource identifier
see URI
universal test client 273
unmarshalling 31
unpublish 405
UNSPSC 102, 106
URI 24
URN 24, 38
UUID 110, 120
556
V
view
mapping 210
virtual host 494
Visual Editor 210
VisualAge for Java 208
VisualAge Generator 211
W
W3C 20
WDO 211
Weather class 237
WEATHER database 235
weather forecast 233
WSDK 409
WeatherDataSource.jacl 409
WeatherForecast class 234, 238
WeatherForecast_mapping.xml 260
WeatherForecastEJB 234
WeatherForecastProxy 264
WeatherPredictor class 235, 244
Web
container
programming model 89
Web service
from JavaBean 253
Web services
authentication 309
build 222
client 227
client deployment descriptor 82
confidentiality 326
deployment 223, 479, 487
deployment descriptor 90, 305
development 221–222
EJB 271
enabling 487
enterprise 77
example 12
Explorer 256, 260, 295–296
WSDK 421
flow language 160
from DADX 290
from JavaBean
WSDK 417
from session EJB
WSDK 424
from SQL 290
WebSphere Version 5.1 Web Services Handbook
from URL 285
from WSDL 279
gateway 169–170
generate client 277
generated files 259
integrity 316
J2EE 78
JMS 274
management 223
object runtime facility 290
protocol stack 199
runtime 223, 479
scenario 429
scope 37
security 185, 303
bindings 321
language 188
model 196
security model 196
Toolkit 382
Web client 268
wizard 248, 253
WSDK 418
Web services description language
see WSDL
Web services flow language
see WSFL
Web Services Gateway
see WSGW
Web services inspection language
see WSIL
Web services invocation framework
see WSIF
webservices.xml 90, 259
webservicesclient.xml 82, 260
Website Builder 210
WebSphere
administration 480
administrative console 482
Application Server 35, 205
Enterprise Edition 176, 206, 377
Express 206
installation 516
Network Deployment 105, 123, 206, 482
Business Connection 181
Web Services Gateway 183
Business Integration 218
certificates 319
Commerce 216
Business Edition 217
Professional
Edition 217
Entry 217
Data Objects 211
Everyplace 214
Access 215
Embedded Edition 215
Server 215
Information Center 208
JMS Provider 489
MQ 212
Integrator Broker 218
JMS Provider 489
Portal
Experience 214
Express 214
Extend 213
Portal Enable 213
Portal for Multiplatforms 213
product family 204
SOAP Engine 20, 42, 188
Studio 208
Application Developer 210, 247, 303
Integration Edition 211, 341, 522
Enterprise Developer 211
Site Developer 209
topology 480
Version 5.0.2 server 529
Voice Server 216
Workflow 139
WebSphere SDK for Web Services
see WSDK
WORF 290
runtime 496
test client 294
workflow 7, 159
workspace
projects 527
WS-Authentication 197
WSDK 381
binding 57
build 408
client 403
documentation 385
generated files 391
installation 523
plug-in 416
samples 386
Index
557
server 384, 402
Eclipse 417
tools 384, 388
weather forecast 409
Web Service wizard 418
Web site 428
WS-Security 387
WSDL 8
API 62
binding 150
binding example 154
document 46–47
editor 346
files 51
introductory 45
message 54
operation 46, 55
port 46
port type 55
service 58
specification
Web site 65
WS-I validation 283
WSDL to Java 389, 393
WSDL2Client 384, 399
WSDL2Java 389, 393
WSDL2WebService 384, 394
WSDL4J 62, 433
WS-Federation 196
WSFL 10, 159–160
concepts 160
example 162
specification
Web site 168
WSGW 10, 139, 169
enhancements 182
security 177
WS-I 15, 250, 282, 382
Basic Profile 16
compliance
preference 282
warning 256
SOAP message validation 283
validation tools 282
WSIF 9, 129, 171
API 132, 135
architecture 132
components 134
concepts 131
558
interaction 134
JAX-RPC 135
provider 132
proxy 135
SAAJ 138
stub 136
Web site 140
WSIFMessage 134
WSIFOperation 132
WSIFPort 133
WSIFProvider 132
WSIFService 132
WSIL 9, 141, 230, 435
binding 150
example 154
link
link 149
lookup sample 461
scenario 434
see also WS-Inspection
service 148
WSIL4J 156, 433
WS-Inspection 141
API 156
binding 150
definition 147
document 143
Java API 156
link 149
namespaces 145
overview 143
service 148
specification
Web site 157
WS-Policy 197
WS-Privacy 197
WS-SecureConversation 196
WS-Security 94
authentication 189
confidentiality 193
extensions 195
integrity 191
see also Web services security
specification 188
Web site 200
WSDK 387
ws-security.xml 306
WSTK 382
WS-Trust 197
WebSphere Version 5.1 Web Services Handbook
X
X.509 309
XLANG 165, 168
XMethod 157
XMI 32
XML 8
digital signature 304
editor 346
encryption 304
Web site 200
Information Set 64
metadata interchange
see XMI
namespaces 24
Protocol Working Group 20
schema descriptor 22
signature
Web site 200
XSD
type 30
Index
559
560
WebSphere Version 5.1 Web Services Handbook
WebSphere Version 5.1 Application
Developer 5.1.1 Web Services Handbook
Back cover
®
WebSphere Version 5.1
Application Developer 5.1.1
Web Services Handbook
Web services
overview and
concepts
Web services tools
and development
Web services
runtime environment
This IBM Redbook describes the new concept of Web services from
various perspectives. It presents the major building blocks Web
services rely on. Here, well-defined standards and new concepts are
presented and discussed.
Whereas these concepts are described vendor-independent, this
book also presents IBM’s view and illustrates with suitable
demonstration applications how Web services can be implemented
using IBM’s product portfolio, especially WebSphere Application
Server Version 5.1 and WebSphere Studio Application Developer
Version 5.1.1.
This book is a major update to the IBM Redbook Web Services
Wizardry with WebSphere Studio Application Developer, SG24-6292,
and to WebSphere Version 5 Web Services Handbook,
SG24-6891-00.
This book is structured in two parts:
Part 1 presents the underlying concepts for the use of Web
services: It presents the basic programming model, well-known
concepts in an updated way, and new concepts that go beyond
the scope of the earlier books.
Part 2 shows how Web services can be implemented using the
latest IBM tools. Here we introduce a sample application that is
demonstrated in various different ways.
SG24-6891-01
ISBN 0738498718
INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION
BUILDING TECHNICAL
INFORMATION BASED ON
PRACTICAL EXPERIENCE
IBM Redbooks are developed by
the IBM International Technical
Support Organization. Experts
from IBM, Customers and
Partners from around the world
create timely technical
information based on realistic
scenarios. Specific
recommendations are provided
to help you implement IT
solutions more effectively in
your environment.
For more information:
ibm.com/redbooks
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement