Front cover

WebSphere Service Registry and Repository Handbook
Best practices Sample integration scenarios

SOA governance

Chris Dudley Laurent Rieu Martin Smithson Tapan Verma Byron Braswell

ibm.com/redbooks

International Technical Support Organization WebSphere Service Registry and Repository Handbook March 2007

SG24-7386-00

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

First Edition (March 2007) This edition applies to Version 6, Release 0, Modification 0.1 of IBM WebSphere Service Registry and Repository (product number 5724-N72).
© Copyright International Business Machines Corporation 2007. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Part 1. SOA overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapter 1. Introduction to SOA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Service-oriented architecture - a business view . . . . . . . . . . . . . . . . . . . . . 4 1.1.1 What is a “service” in service-oriented architecture? . . . . . . . . . . . . . 5 1.1.2 The SOA Foundation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1.3 SOA lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.4 SOA reference architecture model . . . . . . . . . . . . . . . . . . . . . . . . . . 11 1.1.5 Supporting elements of the SOA reference architecture. . . . . . . . . . 14 1.2 Service-oriented architecture - an IT view . . . . . . . . . . . . . . . . . . . . . . . . . 18 1.2.1 Definition of a service-oriented architecture . . . . . . . . . . . . . . . . . . . 18 1.2.2 SOA terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.2.3 Drivers for SOA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 1.2.4 What is a service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 1.2.5 Web services and SOA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 1.2.6 Core technologies of Web services. . . . . . . . . . . . . . . . . . . . . . . . . . 26 1.2.7 Enterprise Service Bus and SOA . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 1.2.8 Definition of an Enterprise Service Bus. . . . . . . . . . . . . . . . . . . . . . . 30 1.2.9 Enterprise requirements for an ESB . . . . . . . . . . . . . . . . . . . . . . . . . 32 1.2.10 Service registry and repository in an SOA . . . . . . . . . . . . . . . . . . . 34 1.3 SOA governance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 1.3.1 What is SOA governance? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 1.3.2 SOA governance in practice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 1.3.3 Aspects of SOA governance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 1.4 SOA summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Part 2. WSRR concepts and architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Chapter 2. Concepts and architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 2.1 Overview of WebSphere Service Registry and Repository . . . . . . . . . . . . 54 2.1.1 What is WebSphere Service Registry and Repository? . . . . . . . . . . 55

© Copyright IBM Corp. 2007. All rights reserved.

iii

2.1.2 The limits of WebSphere Service Registry and Repository . . . . . . . 59 2.2 Architecture of WebSphere Service Registry and Repository . . . . . . . . . . 66 2.2.1 Overview of main components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 2.2.2 Information model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 2.2.3 Interfaces and APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 2.2.4 Governance enablers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Chapter 3. Information model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 3.2 Service description entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 3.2.1 Physical documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 3.2.2 Logical derivations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 3.2.3 GenericObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 3.3 Service description metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 3.3.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 3.3.2 Relationships. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 3.3.3 Classifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 3.3.4 Classifications in WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 3.4 Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 3.5 Document types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 3.5.1 XML Schema Definition (XSD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 3.5.2 Web Services Description Language service definitions . . . . . . . . . 94 3.5.3 Service Component Architecture (SCA) modules . . . . . . . . . . . . . . . 96 3.5.4 XML metadata files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 3.5.5 Service Policy (WS-Policy) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 3.6 XPath. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 3.7 Service Data Objects (SDO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 3.7.1 Data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 3.7.2 Data graphs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 3.8 BaseObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 3.9 Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 3.9.1 Types of query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 3.9.2 Searching and querying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 3.9.3 More query examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 3.9.4 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Chapter 4. Interfaces and APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 4.1 Java API (EJB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 4.1.1 Creating a Java client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 4.1.2 Creating content in WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 4.1.3 Retrieving content from WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 4.1.4 Updating content in WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 4.1.5 Deleting content from WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

iv

WebSphere Service Registry and Repository Handbook

4.1.6 Querying content in WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 4.2 Web services API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 4.2.1 Creating a Web services client . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 4.2.2 Ontology Web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 4.2.3 SOAP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 4.3 Web user interface (Web UI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 4.3.1 Web user interface layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 4.3.2 Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 4.3.3 View queries and navigation trees . . . . . . . . . . . . . . . . . . . . . . . . . 150 4.3.4 Collection views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 4.3.5 Detail views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 4.4 Command Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 4.5 Admin (JMX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Chapter 5. SOA governance enablers . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 5.2 Lifecycles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 5.2.1 State machine terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 5.2.2 Lifecycle definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 5.2.3 WSRR default lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 5.2.4 GovernanceRecords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 5.3 WSRR security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 5.3.1 J2EE security roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 5.3.2 User defined roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 5.3.3 Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 5.3.4 Extensible Access Control Markup Language (XACML). . . . . . . . . 196 5.4 WSRR plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 5.4.1 Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 5.4.2 Notifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 5.4.3 Packaging plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 5.4.4 Configuring plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 5.5 Impact analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 5.5.1 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 5.5.2 Specifying modelled dependency relationships . . . . . . . . . . . . . . . 218 5.5.3 Specifying user defined dependency relationships . . . . . . . . . . . . . 243 Part 3. Planning and installing WSRR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Chapter 6. Possible topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 6.1 WSRR requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 6.1.1 Supported platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 6.1.2 Supported databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 6.1.3 Prerequisite software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 6.1.4 Topology selection criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Contents

v

6.2 Database topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 6.2.1 Local database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 6.2.2 Remote database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 6.3 WebSphere Application Server topologies . . . . . . . . . . . . . . . . . . . . . . . 251 6.3.1 Standalone server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 6.3.2 Distributed server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Chapter 7. Installing and deploying. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 7.1 Install WebSphere Application Server V6.0 . . . . . . . . . . . . . . . . . . . . . . 254 7.2 Install WebSphere Application Server V6.0 refresh pack 2 (V6.0.2) . . . . 254 7.3 Install WebSphere Application Server V6.0.2 fix pack 11 (V6.0.2.11) . . 255 7.4 Install DB2 Universal Database Enterprise Server Edition . . . . . . . . . . . 256 7.5 Install WebSphere Service Registry and Repository. . . . . . . . . . . . . . . . 258 7.6 Deploy WebSphere Service Registry and Repository . . . . . . . . . . . . . . . 265 7.6.1 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 7.7 Installing WSRR with a remote database . . . . . . . . . . . . . . . . . . . . . . . . 275 7.8 Installing WSRR using the WebSphere Application Server Network Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 7.9 Upgrading WSRR to a new fixpack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 7.9.1 Upgrade from previous version . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 7.9.2 Direct Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 7.10 Installation troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Chapter 8. Administering WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 8.1 Administration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 8.1.1 Administrative scripting (wsadmin) . . . . . . . . . . . . . . . . . . . . . . . . . 282 8.1.2 Administrative (JMX) interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 8.1.3 Command line administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 8.1.4 Configuration data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 8.2 WSRR configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 8.2.1 Supported configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 8.3 Security considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 8.4 Administering WSRR using wsadmin . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 8.4.1 Setting up wsadmin for managing WSRR . . . . . . . . . . . . . . . . . . . . 285 8.4.2 Locating the WSRR MBean with wsadmin . . . . . . . . . . . . . . . . . . . 286 8.4.3 Discovering WSRR MBean operations using wsadmin . . . . . . . . . 286 8.4.4 Discovering WSRR MBean notifications using wsadmin . . . . . . . . 289 8.4.5 Invoking operations on WSRR MBean using wsadmin . . . . . . . . . . 289 8.4.6 Troubleshooting WSRR administration with wsadmin . . . . . . . . . . 291 8.5 Administering WSRR using JMX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 8.5.1 Using ServiceRegistryRepositoryProxy.java JMX client . . . . . . . . . 293 8.5.2 Invoking WSRR MBean operations with the Java JMX client . . . . . 295 8.5.3 Exception handling with the Java JMX client . . . . . . . . . . . . . . . . . 296

vi

WebSphere Service Registry and Repository Handbook

8.6 Administering WSRR using the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 8.6.1 Configuring scripting environment. . . . . . . . . . . . . . . . . . . . . . . . . . 299 8.6.2 Scripting elements and objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 8.6.3 Sample scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 8.7 Ontology administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 8.7.1 Creating an ontology system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 8.7.2 Removing an ontology system . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 8.8 Access control administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 8.8.1 Overview of access control within WSRR . . . . . . . . . . . . . . . . . . . . 309 8.8.2 Administering the WSRR access control policy . . . . . . . . . . . . . . . 310 8.9 Import/Export. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 8.9.1 Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 8.9.2 Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 8.9.3 Import and export with the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 8.9.4 Processing import / export files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 8.10 Environment promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 8.10.1 Promotion mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 8.10.2 Sample script for promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 8.11 Administration scripts (wsadmin). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 8.11.1 Scripts for managing configuration . . . . . . . . . . . . . . . . . . . . . . . . 322 8.11.2 Scripts for managing ontologies . . . . . . . . . . . . . . . . . . . . . . . . . . 322 8.11.3 Scripts for import and export of WSRR entities. . . . . . . . . . . . . . . 322 8.11.4 Scripts for managing access control policy . . . . . . . . . . . . . . . . . . 322 8.11.5 Scripts for managing lifecycles . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 Part 4. Using WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 Chapter 9. Getting started with WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 9.2 Navigating the Web UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 9.2.1 Quick search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 9.2.2 Unified Service Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 9.2.3 Service Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 9.2.4 Service Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 9.2.5 Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 9.2.6 Classification systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 9.2.7 My Service Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 9.2.8 Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 9.3 Publishing documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 9.4 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 9.4.1 Adding a new custom property . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 9.4.2 Editing a property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 9.4.3 Deleting a custom property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

Contents

vii

9.5 Relationships. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 9.5.1 Creating a new relationship. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 9.5.2 Editing an existing relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 9.5.3 Deleting a relationship. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 9.6 Classifying objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 9.6.1 Loading an OWL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 9.6.2 Browsing classifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 9.6.3 Removing a classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 9.6.4 Classifying an entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 9.7 Searching the registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 9.8 Deleting artefacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 9.9 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 9.9.1 Defining a concept template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 9.9.2 Classifying a complex type as a template . . . . . . . . . . . . . . . . . . . . 371 9.9.3 Viewing templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 9.9.4 Creating a concept from a template . . . . . . . . . . . . . . . . . . . . . . . . 374 9.9.5 Viewing the details of a concept . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 9.9.6 Deleting a concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Chapter 10. Customizing the Web UI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 10.2 View query definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 10.2.1 Using alternative views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 10.2.2 Querying by property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 10.2.3 Querying by relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 10.2.4 Querying by classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 10.3 Navigation trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 10.4 Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 10.4.1 A skeleton perspective definition. . . . . . . . . . . . . . . . . . . . . . . . . . 395 10.4.2 Adding name, title and roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 10.4.3 The navigation tree and weight . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 10.4.4 Collection and detail view mappings . . . . . . . . . . . . . . . . . . . . . . . 398 10.4.5 Perspective resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 10.5 Collection views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 10.5.1 Collection view areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 10.5.2 A skeleton collection view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 10.5.3 Adding name, title and description . . . . . . . . . . . . . . . . . . . . . . . . 403 10.5.4 Collection view columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 10.5.5 Collection view buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 10.5.6 Collection view button action values . . . . . . . . . . . . . . . . . . . . . . . 410 10.5.7 Adding collection view resources . . . . . . . . . . . . . . . . . . . . . . . . . 410 10.6 Managing UI customization configurations . . . . . . . . . . . . . . . . . . . . . . 411 10.6.1 Manage configurations with MBean operations . . . . . . . . . . . . . . 412

viii

WebSphere Service Registry and Repository Handbook

Chapter 11. Using the WSRR Eclipse plug-in . . . . . . . . . . . . . . . . . . . . . . 415 11.1 WSRR Eclipse user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 11.2 Installing the Eclipse user interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 11.3 Configuring the Eclipse user interface. . . . . . . . . . . . . . . . . . . . . . . . . . 428 11.4 Searching for objects in WSRR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 11.5 Importing documents into your local workspace . . . . . . . . . . . . . . . . . . 435 11.6 Publishing documents to WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 11.7 Adding properties to objects in WSRR . . . . . . . . . . . . . . . . . . . . . . . . . 440 11.8 Defining relationships between objects in WSRR . . . . . . . . . . . . . . . . . 442 11.9 Creating concepts for objects in WSRR . . . . . . . . . . . . . . . . . . . . . . . . 445 11.10 Creating concepts using local documents. . . . . . . . . . . . . . . . . . . . . . 448 Chapter 12. Scenarios description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 12.1 Services description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 12.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 12.3 Solution overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 Chapter 13. Configuring governance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461 13.1 Configuring security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 13.1.1 Modifying the J2EE security role mappings . . . . . . . . . . . . . . . . . 463 13.1.2 Removing the AllAuthenticatedUsers principal from the WSRR Administrator role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 13.1.3 Adding roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 13.1.4 Adding permissions to roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 13.1.5 Mapping users to roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 13.2 Using lifecycles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 13.2.1 Making an object governable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 13.2.2 Transitioning the lifecycle state of a governed object . . . . . . . . . . 479 13.2.3 Removing governance from an object . . . . . . . . . . . . . . . . . . . . . 481 13.3 Developing custom plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482 13.3.1 Developing a custom validator . . . . . . . . . . . . . . . . . . . . . . . . . . . 483 13.3.2 Developing a customer notifier . . . . . . . . . . . . . . . . . . . . . . . . . . . 486 13.3.3 Deploying custom plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 13.3.4 Configuring custom plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494 13.4 Performing impact analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 13.4.1 Analyzing dependencies between physical document objects . . . 500 13.4.2 Analyzing dependencies between physical document objects and derived objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 13.4.3 Analyzing dependencies between derived objects . . . . . . . . . . . . 507 Chapter 14. Integrating WSRR with WebSphere ESB . . . . . . . . . . . . . . . 511 14.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 14.2 WebSphere ESB overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 14.2.1 Key terms in WebSphere Enterprise Service Bus. . . . . . . . . . . . . 514

Contents

ix

14.3 Structure of WebSphere Enterprise Service Bus . . . . . . . . . . . . . . . . . 515 14.3.1 Mediations, service consumers, and service providers. . . . . . . . . 515 14.3.2 Mediation modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 14.3.3 Mediation flow components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 14.3.4 Mediation flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 14.3.5 Mediation primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 14.4 Related technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 14.4.1 Service message objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 14.5 Endpoint Lookup mediation primitive . . . . . . . . . . . . . . . . . . . . . . . . . . 525 14.5.1 Match policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 14.5.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 14.5.3 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 14.5.4 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 14.5.5 SOAP/HTTP example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 14.5.6 SOAP/JMS example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 14.5.7 SCA default binding example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 14.5.8 Dynamic endpoint selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 14.6 Managing access from WESB to WSRR. . . . . . . . . . . . . . . . . . . . . . . . 536 14.6.1 Registry definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 14.6.2 General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 14.6.3 Connection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 14.6.4 Connecting to a secure WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 14.7 Integration scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 14.7.1 Interaction between WESB and WSRR . . . . . . . . . . . . . . . . . . . . 544 14.7.2 Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 14.7.3 Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 14.7.4 Installation of sample Web services . . . . . . . . . . . . . . . . . . . . . . . 546 14.7.5 Publish the ItemPrice service to WSRR . . . . . . . . . . . . . . . . . . . . 555 14.7.6 Configure WSRR definition in WESB . . . . . . . . . . . . . . . . . . . . . . 568 14.7.7 Scenario 1: Dynamically fetch the service endpoint . . . . . . . . . . . 574 14.7.8 Scenario 1 testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587 14.7.9 Publish ItemPriceDiscounted service metadata in WSRR . . . . . . 590 14.7.10 Scenario 2: Fetch endpoint based on custom property. . . . . . . . 597 14.7.11 Scenario 2 testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 14.7.12 Scenario 3: Use the Lookup primitive to get both endpoints . . . . 612 14.7.13 Scenario 3 testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 Chapter 15. Integrating WSRR with ITCAM for SOA . . . . . . . . . . . . . . . . 625 15.1 SOA management and WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626 15.1.1 Introduction to SOA management. . . . . . . . . . . . . . . . . . . . . . . . . 626 15.1.2 Managing the SOA Foundation architectural layers . . . . . . . . . . . 629 15.1.3 The role of a service registry and repository in SOA management631 15.2 IBM Tivoli IT Service Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631

x

WebSphere Service Registry and Repository Handbook

15.3 IBM Tivoli solutions for SOA management . . . . . . . . . . . . . . . . . . . . . . 633 15.3.1 IBM Tivoli Composite Application Manager . . . . . . . . . . . . . . . . . 634 15.3.2 IBM Tivoli Enterprise Monitoring framework . . . . . . . . . . . . . . . . . 636 15.4 IBM Tivoli Composite Application Manager for SOA. . . . . . . . . . . . . . . 640 15.4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 15.4.2 Product features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 15.4.3 Product components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 15.5 WSRR and ITCAM for SOA integration scenarios . . . . . . . . . . . . . . . . 654 15.6 Discovery and display of service information . . . . . . . . . . . . . . . . . . . . 654 15.6.1 Discovery of services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655 15.6.2 Displaying of service information . . . . . . . . . . . . . . . . . . . . . . . . . 663 15.7 Service status information forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . 677 15.7.1 Detection and processing of service related situations . . . . . . . . . 678 15.7.2 Propagation, capture and processing of situation events . . . . . . . 687 15.7.3 Use of service status information . . . . . . . . . . . . . . . . . . . . . . . . . 690 15.8 Discovery and display of service information: working example . . . . . . 692 15.8.1 Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692 15.8.2 Assumptions and prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . 692 15.8.3 Logical architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694 15.8.4 Operational architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697 15.8.5 Monitoring services using ITCAM for SOA . . . . . . . . . . . . . . . . . . 698 15.8.6 Understanding WSRR Discovery Library Adapter . . . . . . . . . . . . 702 15.8.7 Installing WSRR Discovery Library Adapter . . . . . . . . . . . . . . . . . 705 15.8.8 Configuring WSRR Discovery Library Adapter . . . . . . . . . . . . . . . 708 15.8.9 Using WSRR Discovery Library Adapter. . . . . . . . . . . . . . . . . . . . 714 15.8.10 Reconciling service information using ITCAM for SOA . . . . . . . . 719 15.9 Forwarding service status information - working example . . . . . . . . . . 727 15.9.1 Understanding ITCAM for SOA Event Handler . . . . . . . . . . . . . . . 728 15.9.2 Installing ITCAM for SOA Event Handler . . . . . . . . . . . . . . . . . . . 729 15.9.3 Configuring ITCAM for SOA Event Handler . . . . . . . . . . . . . . . . . 731 15.9.4 Configuring Tivoli Enterprise Monitoring Framework to send events to the Event Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746 15.9.5 Triggering situations and forwarding service status information . . 754 15.9.6 Using service status information in ESB infrastructure . . . . . . . . . 770 Chapter 16. Integrating WSRR with WMB . . . . . . . . . . . . . . . . . . . . . . . . . 771 16.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772 16.2 About WebSphere Message Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . 772 16.2.1 Application integration and WebSphere Message Broker. . . . . . . 772 16.2.2 WebSphere Message Broker overview . . . . . . . . . . . . . . . . . . . . . 773 16.2.3 Capabilities of WebSphere Message Broker . . . . . . . . . . . . . . . . 774 16.2.4 Components of WebSphere Message Broker. . . . . . . . . . . . . . . . 776 16.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779

Contents

xi

16.3.1 Download the SupportPac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779 16.3.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779 16.3.3 Install the SupportPac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780 16.4 WebSphere Message Broker Client for WSRR . . . . . . . . . . . . . . . . . . . 786 16.4.1 WSRR nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787 16.4.2 WMB Client cache for WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787 16.4.3 Client runtime access to WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . 788 16.4.4 WMB Client and WSRR deployment. . . . . . . . . . . . . . . . . . . . . . . 789 16.5 WSRR nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790 16.5.1 Introducing the nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790 16.5.2 SRGetVirtualService node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791 16.5.3 SRProcessVirtualService node . . . . . . . . . . . . . . . . . . . . . . . . . . . 793 16.5.4 SRDispatchVirtualService node . . . . . . . . . . . . . . . . . . . . . . . . . . 794 16.5.5 SRRetrieveITService node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795 16.5.6 SRRetrieveEntity node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797 16.6 WMB Client Cache for WSRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800 16.6.1 Cache logical topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800 16.6.2 Cache loading strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801 16.6.3 Setting cache load strategy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802 16.6.4 Cached items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802 16.6.5 Cache synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803 16.7 WMB Client support for SOA patterns. . . . . . . . . . . . . . . . . . . . . . . . . . 803 16.7.1 Transcoder pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803 16.7.2 Router pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806 16.8 Setting up your environment for the patterns . . . . . . . . . . . . . . . . . . . . 809 16.8.1 Configuring WMB for the patterns . . . . . . . . . . . . . . . . . . . . . . . . . 810 16.8.2 Configuring WSRR for the patterns. . . . . . . . . . . . . . . . . . . . . . . . 810 16.8.3 Configure the test client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813 16.8.4 Run the tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813 16.8.5 Test message flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818 16.8.6 Optional: Importing the test scenario into WMB toolkit . . . . . . . . . 823 Chapter 17. Integrating WSRR with CICS . . . . . . . . . . . . . . . . . . . . . . . . . 825 17.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826 17.2 What is CICS?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827 17.2.1 CICS product portfolio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827 17.2.2 CICS Transaction Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827 17.2.3 CICS tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828 17.2.4 CICS connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828 17.2.5 CICS TXSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829 17.2.6 Why interoperate CICS and WebSphere? . . . . . . . . . . . . . . . . . . 829 17.2.7 CICS and WebSphere in an SOA . . . . . . . . . . . . . . . . . . . . . . . . . 831 17.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831

xii

WebSphere Service Registry and Repository Handbook

17.3.1 Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831 17.3.2 Downloading and installing the CICS SupportPac . . . . . . . . . . . . 832 17.4 Publishing WSDL files from z/OS batch to WSRR . . . . . . . . . . . . . . . . 834 17.4.1 Running DFHWS2SR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835 17.4.2 Job control statements for DFHWS2SR . . . . . . . . . . . . . . . . . . . . 837 17.5 Publishing WSDL files from CICS to WSRR . . . . . . . . . . . . . . . . . . . . . 842 17.5.1 Running the CWSP transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 843 17.6 Retrieving WSDL files from WSRR using z/OS batch . . . . . . . . . . . . . . 847 17.6.1 Running DFHSR2WS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848 17.6.2 Job control statements for DFHSR2WS . . . . . . . . . . . . . . . . . . . . 850 17.7 Security considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854 17.7.1 Configuring SSL between the z/OS batch utilities and WSRR . . . 854 17.7.2 Configuring SSL between CICS and WSRR . . . . . . . . . . . . . . . . . 855 Part 5. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857 Appendix A. IBM product descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 859 IBM products used to model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860 IBM products used to assemble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862 IBM products used to deploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866 IBM products used to manage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869 IBM Tivoli Composite Application Manager family products . . . . . . . . . . . 872 Appendix B. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877 Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877 Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877 System requirements for downloading the Web material . . . . . . . . . . . . . 878 How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879 Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883 Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887 IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887 Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887 Online resources and product documentation . . . . . . . . . . . . . . . . . . . . . . . . 888 How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890 Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891

Contents

xiii

xiv

WebSphere Service Registry and Repository 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 illustrate 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.

© Copyright IBM Corp. 2007. All rights reserved.

xv

Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both: alphaWorks® developerWorks® i5/OS® z/OS® z/VSE™ zSeries® z9™ AIX® Candle® ClearCase® CICS® DataPower® Domino® DB2 Universal Database™ DB2® IBM® IMS™ MQSeries® NetView® OMEGAMON Monitoring Agent® OMEGAMON® OS/2® Passport Advantage® Rational® Redbooks™ Redbooks (logo) ™ RACF® REXX™ SupportPac™ System z™ Tivoli Enterprise™ Tivoli Enterprise Console® Tivoli® TXSeries® WebSphere®

The following terms are trademarks of other companies: Oracle, JD Edwards, PeopleSoft, Siebel, and TopLink are registered trademarks of Oracle Corporation and/or its affiliates. SAP NetWeaver, SAP, and SAP logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries. Oracle, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office. DataStage, are trademarks or registered trademarks of Ascential Software Corporation in the United States, other countries, or both. Enterprise JavaBeans, EJB, Java, Java Naming and Directory Interface, JavaBeans, JavaServer, JavaServer Pages, JDBC, JDK, JMX, JRE, JSP, JVM, J2EE, J2SE, Solaris, Sun, Sun Microsystems, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Active Directory, Expression, Microsoft, Visio, Windows Server, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Intel, Intel logo, Intel Inside logo, and Intel Centrino logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others.

xvi

WebSphere Service Registry and Repository Handbook

Preface
Service-oriented architecture offers the promise of business agility and resilience through reuse, loose coupling, flexibility, interoperability, integration and governance. These are realized by separating service descriptions from their implementations, and using this descriptive metadata across the service lifecycle. Standards-based service metadata artefacts, such as Web Service Description Language (WSDL), XML schema, policy or Service Component Architecture (SCA) documents, capture the technical details of what a service can do, how it can be invoked, or what it expects other services to do. Semantic annotations and other metadata can be associated with these artefacts to offer insight to potential users of the service about how and when it can be used, and what purposes it serves. A service registry and repository handles the management of service descriptions and serves as the system of record for this information throughout the complete lifecycle of a service. IBM® WebSphere Service Registry and Repository is the master metadata repository for service interaction endpoint descriptions. Because WebSphere Service Registry and Repository is the integration point of service metadata, it establishes a central point for finding and managing service metadata. Once service metadata is placed in WebSphere Service Registry and Repository, visibility is controlled, versions are managed, proposed changes are analyzed and communicated, and usage is monitored. This IBM Redbook discusses the architecture and functions of IBM WebSphere Service Registry and Repository along with sample integration scenarios that can be used as examples for implementing WebSphere Service Registry and Repository in a customer service-oriented architecture environment.

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.

© Copyright IBM Corp. 2007. All rights reserved.

xvii

The team

Chris, Martin, Laurent, Tapan, Byron

Byron Braswell is a is a Networking Professional at the ITSO, Raleigh Center. He received a Bachelor of Science degree in Physics and a Master of Computer Science degree in Computering Sciences from Texas A&M University. He writes extensively in the areas of networking, application integration middleware, and personal computer software. Before joining the ITSO, Byron worked in IBM Learning Services Development in networking education development. Chris Dudley is a Software Engineer working in the Application Integration Middleware area for IBM Software Group in the U.K. After he received his degree in Civil Engineering in 1999, he joined IBM Software Group and worked on several IBM products including IBM WebSphere® MQ and IBM WebSphere Message Broker. He worked in IBM Emerging Technology Services before joining the IBM WebSphere Service Registry and Repository development team at its inception in late 2005, where he has worked ever since. Laurent Rieu is an IT Architect working for the SOA Advanced Technology team (formerly known as Enterprise Integration Solutions) within IBM Software Group. As part of this worldwide team Laurent is acting as an EMEA Lead Solution Architect and is helping to drive and enhance IBM software strategy around service-oriented architecture through customer engagements, field-based development, asset harvesting, and thought leadership. He has eight years of experience in the IT industry and has been working at IBM for seven years in various industries, such as insurance, telecommunications, distribution, public sector, and utilities. Before joining IBM Software Group, Laurent worked for IBM Global Business Services. His areas of expertise are service-oriented architecture, business integration, Patterns, Web services, and J2EE™ platform.

xviii

WebSphere Service Registry and Repository Handbook

Before joining IBM, he worked for one year as Technical Support for Société Générale in New York City, USA. He graduated (MS) from Ecole Supérieure d’Electricité in 1998. Martin Smithson is a Senior IT Specialist working on the WebSphere Service Registry and Repository product at IBM laboratory in Hursley, England. He has 11 years of experience working in the IT industry, five of which he spent working as a technical consultant for the EMEA IBM Software Services for WebSphere team. His areas of expertise include the architecture, design, and development of J2EE applications; he is also an expert on IBM WebSphere Application Server. He has authored several developerWorks® articles and co-authored several Redbooks™: WebSphere Application Server V6 System Management and Configuration Handbook, SG24-6451, WebSphere Application Server V6.1: System Management and Configuration, SG24-7304, and CCF Connectors and Database Connections Using WebSphere Advanced Edition Connecting Enterprise Information Systems to the Web, SG24-5514. Martin also developed the IBM Client Application Tool for JMS that is available for download from IBM alphaWorks® Web site. Tapan Verma is an Advisory IT Specialist at IBM Software Services for WebSphere in India. He has more than 10 years of experience in the IT Industry, five of those years working with IBM Software Group in India on WebSphere consultancy, designing, integration, installation, configuration, and troubleshooting. His areas of expertise include WebSphere Application Server, WebSphere Process Server and WebSphere Enterprise Service Bus. He has product certifications on WebSphere Application Server, WebSphere Process Server, WebSphere Studio Application Developer and DB2®. He also conducts training and workshops about WebSphere and related topics. Thanks to the following people for their contributions to this project: Carla Sadtler Margaret Ticknor Linda Robinson Carolyn Sneed Tamikia Barrow ITSO, Raleigh Center Mark Allman IBM United Kingdom, Software Group, WebSphere ESB Development Janet S. Andersen, Rohit I. Badlaney IBM RTP, Software Group, ITCAM for SOA Development Tom Bailey, Tim Baldwin, Rob Breeds, Steven Gallacher, Ian Heritage, Chris Jenkins, Kevin Marsh, Jamie Orchard, Mike Ricketts, Phil Rowley, Andrew

Preface

xix

Rutherford, Dave Seager, Ian Shore, Philip Taunton, Gary Whittingham, Stephen Willoughby IBM United Kingdom, Software Group, WebSphere Service Registry and Repository Development Duncan Clark, John Colgrave, Barbara McKee IBM United Kingdom, Software Group, Service Registry Chief Architect Kim Clark IBM United Kingdom, Software Group, WebSphere SOA Foundation Product Specialist Mark Cocker, Daniel Millwood, Peter Seddon IBM United Kingdom, Software Group, IBM CICS® Development David Currie IBM United Kingdom, Software Group, Senior IT Specialist, Pan-IOT Software Lab Services Software Development Engineer Arnauld Desprets, Michael Ellis, Bobby Woolf IBM Software Services for WebSphere Lisbeth Dineen IBM Pittsburgh, Software Group, WebSphere Process Integration Technical Enablement and Support Planning Raymond Ellis, Subhash Kumar, Bob Patten IBM United States, Software Group, SOA Advanced Technology US Design Center Guy Hochstetler IBM USA, Software Group, Consulting I/T Specialist David D. H. Lin IBM Austin, Software Group, Tivoli Argus Lead Architect Sunil Murthy IBM San Jose, Software Group, Product Management, WSRR Simon Rachman IBM United Kingdom, Software Group, Service Registry Development Manager Rosalind Radcliffe IBM RTP, Software Group, SOA Management Architect

xx

WebSphere Service Registry and Repository Handbook

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 have the opportunity to team with IBM technical professionals, Business Partners, and Clients. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you will develop a network of contacts in IBM development labs, and increase your productivity and marketability. Find out more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.html

Comments welcome
Your comments are important to us! We want our Redbooks to be as helpful as possible. Send us your comments about this or other Redbooks in one of the following ways: Use the online Contact us review redbook form found at: ibm.com/redbooks Send your comments in an email to: redbooks@us.ibm.com Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HYTD Mail Station P099 2455 South Road Poughkeepsie, NY 12601-5400

Preface

xxi

xxii

WebSphere Service Registry and Repository Handbook

Part 1

Part

1

SOA overview

© Copyright IBM Corp. 2007. All rights reserved.

1

2

WebSphere Service Registry and Repository Handbook

1

Chapter 1.

Introduction to SOA
Service-oriented architecture (SOA) is an approach to defining integration architectures that are based on the concept of a service. Applications collaborate by invoking each other’s services, and services can be composed into larger sequences to implement business processes. This chapter introduces service-oriented architecture from a business perspective and from an IT perspective in the following sections: 1.1, “Service-oriented architecture - a business view” on page 4 1.2, “Service-oriented architecture - an IT view” on page 18 1.3, “SOA governance” on page 40

© Copyright IBM Corp. 2007. All rights reserved.

3

1.1 Service-oriented architecture - a business view
The primary goal of service-oriented architecture (SOA) is to align the business world with the world of information technology (IT) in a way that makes both more effective. SOA is about the business results that can be achieved from having better alignment between the business and IT. SOA starts from the premise that all businesses have a business design. A business design describes how that business works – the processes that it performs; the organizational structure of the people and finances within that business; the business’ near-term and long-term goals and objectives; the economic and market influences that affect how that business achieves its goals; the rules and policies that condition how the business operates. Most businesses have a written form of their high level business plan – the high level definition that states the business’ purpose. Few businesses, however, have a written form of their business design. Many of those who have documented their business design have trouble keeping their design up to date with what they actually practice. Business processes evolve as businesses respond to shifts in the marketplace, regulations, or product innovations; this evolution usually happens without reflecting those changes in the formal design of the business. However, even if the business design has not been documented, or even if what is documented is now obsolete, there is nonetheless a business design in effect. A fundamental premise of SOA is that if the business design can be transcribed and maintained there is a potential for leveraging that captured design information. Even if the business design is not used to communicate between the business and IT organizations, it can nonetheless be a valuable tool to help businesses understand what they are doing and how. Beyond that, however, the business design becomes an essential tool in communicating requirements between the business and the IT organization. The business can identify those elements of the design that should be automated and what within that design should be performed by people, creating a blueprint of the information systems that are created to support that automation. By deriving the information system design from the business design you can more easily drive changes into the information system at the rate and pace of change in the business design. Furthermore, the information system can be used as a catalyst for change in the business design. It is from this correspondence that SOA delivers on the promise of more flexible businesses through more flexible IT.

4

WebSphere Service Registry and Repository Handbook

This correspondence is represented as the SOA Lifecycle, in which the business process is modeled, assembled, deployed and monitored in an iterative manner. This transforms the information system from being one of merely a “cost of doing business” to a fundamental tool for enabling a business to be more competitive, profitable and responsive to changes in the marketplace. To achieve this synergism between the business and IT domains we need to employ a number of capabilities: A formalism and language for capturing the business design A methodology for translating the business design into a set of information system artefacts to implement that design An infrastructure for hosting those implementation artefacts that is as flexible to changes in its marketplace as the business itself needs to be A place for retaining the correlation between the business design and the information system that can be used to identify and fix failures in executing on the goals and constraints of the business design A means by which we can manage the system to ensure those goals are met. These capabilities improve the flow of the business process through SOA Lifecycle iterations.

1.1.1 What is a “service” in service-oriented architecture?
We refer to the practice of deriving an information system design from a business design as service-oriented architecture. The business process and the tasks from which it is composed can be collectively thought of roughly as services. Thus, the business design is essentially a composition of services and the policies and conditions that must be applied to their use which form the information system design. However, there remains the question of “what is a service?” Is it a function within an application? Are all application functions services? Does SOA include system services? Coming up with a single, mathematically precise definition that applies universally to all situations can be hugely complicated. In practice, such precision is not necessary to achieving value and success from SOA. An underlying premise in the application of SOA to information technology is the principle of loose coupling – that is, avoiding or at least encapsulating temporal, technological and organizational constraints in the information system design. This same principle applies also to the definition of service – the rules used to define services in one context may not be applicable in another. What is important is that whatever definition we arrive at, it should originate from the primary concerns and constraints of that context. As a generalization, a service is

Chapter 1. Introduction to SOA

5

a repeatable task within a business process. So, if you can identify your business processes, and within that, the set of tasks that you perform within the process, then you can claim that the tasks are services and the business process is a composition of services. However, note that certain tasks can be decomposed into business processes in their own right. The order-entry process includes, amongst other things, a task to confirm availability of the items being ordered. The confirm-availability task is itself a business process that includes, for example, the tasks of checking the on-hand inventory, verifying the supply pipeline, and possibly creating a background request and determining its availability. Thus, business processes are themselves services; there is a principle of recursive decomposition implied in the term service. If taken far enough we could easily claim that everything is a service. This, obviously, is not useful – at some point treating everything as a service would yield an incredibly inefficient over-generalization of the problem space. You should exercise this principle of recursive decomposition only to the extent that you legitimately need flexibility within your business design. From this definition of service, service-orientation is a way of integrating your business as a set of linked services. If you can define the services in each of your vertical and horizontal lines-of-business, you can begin to link those LOBs by composing their services into larger business processes. Likewise, you can decompose the main services of your LOBs into a set of more basic services that can then be easily recomposed either to change LOB processes, or to interlink your LOBs at a lower level of their capabilities. Similarly, you can use the same principles of composition to create links with your business partners to both automate those relationships and to gain more efficiency from them. One consequence of service orientation is flexibility: you gain the ability to iteratively optimize your business design, unhampered by inflexible IT structures. A service-oriented architecture, then, is an architectural style for creating an Enterprise IT Architecture that exploits the principles of service-orientation to achieve a tighter relationship between the business and the information systems that support the business.

1.1.2 The SOA Foundation
What should be clear is that SOA is not just about technology. IBM views SOA as a holistic relationship between the business and the IT organization. SOA encompasses the tools and methodologies for capturing business design, and using that design information to help improve the business. It also encompasses the tools, programming model and techniques for implementing the business design in information systems. It encompasses the middleware infrastructure for hosting that implementation. SOA encompasses the management of that implementation to ensure availability to the business, and to ensure efficient use

6

WebSphere Service Registry and Repository Handbook

of resources in the execution of that implementation. It encompasses the establishment of who has authority and the processes that are used to control changes in the business design and its implementation in the information system. And ultimately, SOA accelerates the time-to-value for these benefits. The SOA Foundation is a comprehensive architecture and set of offerings, technologies, and practices that address all of these things about SOA. To avoid the connotation that SOA is only about technology we deliberately choose not to use the term SOA “Platform”.

1.1.3 SOA lifecycle
The SOA lifecycle (see Figure 1-1) begins with modeling your business (capturing your business design) including the key performance indicators of your business goals and objectives, translating that model into an information system design, deploying that information system, managing that deployment, and using the results coming out of that environment to identify ways to refine the business design. It is a premise of the lifecycle that feedback is cycled to and from phases in iterative steps of refinement and that the model may actually be built using reverse-engineering techniques or other means to facilitate the needs of the business.

Figure 1-1 SOA lifecycle

Chapter 1. Introduction to SOA

7

The lifecycle is then layered on a backdrop of a set of governance processes that ensure that compliance and operational polices are enforced, and that change occurs in a controlled fashion and with appropriate authority as envisioned by the business design.

Model
Modeling is the process of capturing your business design from an understanding of business requirements and objectives and translating that into a specification of business processes, goals and assumptions – creating an encoded model of your business. Capturing your business design using a rigorous approach offers the potential to gain better insight into your business, by, for example using tools to reason about the design and its supporting rationale. In particular, we can use the model to simulate how your business processes will actually run. A sophisticated modeling approach lets you perform “what-if” scenarios that reflect your understanding of the actual number of process instances, contacts, quantities, incoming traffic, and so on, that you may experience in your business. The process can then be simulated using those parameters to predict the effect that process will have on your business and on your IT systems. If you do not achieve the intended results then you can change your process definition to try to improve your results. You can go on to refine your processes as you have modeled them to optimize your business performance even before ever investing in an implementation of those processes. Your model will also capture key performance indicators – business metrics that are important measurements of your business. This could include, for example, a measure of the new accounts that you have opened in a given month. These key performance indicators are input to the assembly of your application and later, when the application is in production, collected and reported back to you. You will be able to use that information to determine how well your business is performing. You can use the correlation between your business design in your actual implementation in the information system to determine whether bottlenecks in your performance are due to limitations in your business design or limitations in the information system that automates your design. For more information, go to the following Web site: http://www.ibm.com/developerworks/webservices/library/ws-soa-design1

Assemble
You can use your business design to communicate with the IT organization – to assemble the information system artefacts that will implement the business design. The enterprise architect working with the business analyst can begin to convert the business design into a set of business process definitions and

8

WebSphere Service Registry and Repository Handbook

activities deriving the required services from the activity definitions. They can work with the software architect to flesh out the design of the services. During the process of resolving a design and implementation of your modeled business processes and services, you should search your existing asset inventories – your existing programs – to find application components that already meet your needs. Some application components will fit perfectly; some will have to be re-factored; and some will have to be augmented to meet the requirements of the design. These existing assets should be rendered as services for assembly into composite applications. It is also possible that some of your existing applications are so heavily bound into a tight relationship with presentation and data logic and other business functions that you simply cannot extract any re-usable componentry from those programs. In these cases you will have to decide whether and how to rewrite these functions as new services, and how to migrate the processes that depend on those old programs. Any new services required by the business design will have to be created. Software developers should use the SOA programming model to create these new services. Final assembly includes applying the set of policies and conditions to control how your applications operate in your production environment. This might include, for example, business and government regulations, but can also include critical operational characteristics such as packaging, localization constraints, resource dependency, integrity control, and access protection. For more information, go to the following Web sites: http://www.ibm.com/developerworks/websphere/library/techarticles/051 1_flurry/0511_flurry.html http://www.ibm.com/developerworks/webservices/library/ws-soa-enter4/ index.html

Deploy
The deploy phase of the lifecycle includes a combination of creating the hosting environment for your applications and the actual deployment of those applications. This includes resolving the application’s resource dependencies, operational conditions, capacity requirements, and integrity and access constraints. A number of concerns are relevant to construction of the hosting environment – including the presence of the already existing hosting infrastructure supporting existing applications and pre-existing services. Beyond that, you need to

Chapter 1. Introduction to SOA

9

consider appropriate platform offerings for hosting your user interaction logic, business process flows, business-services, access services, and information logic. You need to consider the techniques you will employ for ensuring availability, reliability, integrity, efficiency, and service ability. For more information, go to the following Web sites: http://www.ibm.com/developerworks/webservices/library/ws-soa-enter1/ http://www.ibm.com/developerworks/webservices/library/ws-enter5/inde x.html http://www.ibm.com/developerworks/library/ws-soa-enter6/index.html

Manage
Turning now to the manage phase of the lifecycle, you need to consider how to maintain the operational environment and the policies expressed in the assembly of the SOA applications deployed to that environment. This includes monitoring performance of service requests and timeliness of service responses; maintaining problem logs to detect failures in various system components; detecting and localizing those failures; routing work around them; recovering work affected by those failures; correcting problems; and restoring the operational state of the system. The manage phase also includes managing the business model – tuning the operational environment to meet the business objectives expressed in the business design, and measuring success or failure to meet those objectives. SOA is distinguished from other styles of enterprise architecture by its correlation between the business design and the software that implements that design, and its use of policy to express the operational requirements of the business services and processes that codify the business design. The manage phase of the lifecycle is directly responsible for ensuring those policies are being enforced, and for relating issues with that enforcement back to the business design. Managing the system also involves performing routine maintenance, administering and securing applications, resources and users, and predicting future capacity growth to ensure that resources are available when the demands of the business call for it. For more information, go to the following Web sites: http://www.ibm.com/developerworks/webservices/library/ws-sla4/

10

WebSphere Service Registry and Repository Handbook

http://www.ibm.com/software/tivoli/products/composite-application-mg r-soa/ http://www.ibm.com/software/tivoli/solutions/application-management/ http://www.ibm.com/software/tivoli/products/prov-mgr/ http://www.ibm.com/software/tivoli/products/identity-mgr/

Lifecycle flow
Progression through the lifecycle is not entirely linear. In fact, changes to key performance information in the Model phase often need to be fed directly in to the Management phase to update the operational environment. Constraints in the Deploy phase, such as limiting assumptions about where resources are located in the system, may condition some of the Assembly phase decisions. And, occasionally, information technology constraints established in the Assembly phase will limit the business design created during the Model phase – for example, the cost of wide-area wireless communication with remote hand held devices may be prohibitive to deploying a field force to rural locations and therefore needs to be reflected back into the business design.

1.1.4 SOA reference architecture model
The SOA reference architecture model attempts to decompose the functional underpinnings of your application design. Notice white space between architecture elements in Figure 1-2 on page 12. This is intended to imply our emphasis on maintaining a clean separation of concerns. The separation enables us to focus attention on the special skills that are required for each section of the overall architecture – enabling you to optimize your resources to the skills required for a given topic. This specialization avoids the situation that everyone on the team needs to understand everything about the entire system to be effective at anything they do in part of it. This should lower the cost of training, enable more efficient implementations, and enable the construction of tools optimized for specific skill sets. The reference architecture model attempts to be comprehensive – spanning all of the requirements of the SOA Foundation. The parts in light-green in Figure 1-2 on page 12 are the parts in which you will deploy application software to capture the domain logic specific to your business design. These are the boxes labeled Interaction Services, Process Services, Information Services, Partner Services, Business Application Services and Access Services. The other parts of the architecture exist to assist the rest of the SOA lifecycle. You use these other parts in the modeling of your business design, construction

Chapter 1. Introduction to SOA

11

and assembly of your software, deployment of your applications, and management of your operational system and the business design you have implemented. You may even customize these other parts with metadata or software you write to control or optimize those environments, but generally not with logic that is specific to your business design.

Business Innovation & Optimization Services
Provide for better decision-making With real-time business information

Development Services

Interaction Services
Enable collaboration between people, processes & information

Process Services
Orchestrate and automate business processes

Information Services
Manages diverse data and content in a unified manner

Integrated environment for design and creation of solution assets

ESB
Partner Services
Connect with trading partners

Enables interconnectivity between services

Security Policy

Business App Services
Build on a robust, scaleable, and secure services environment

Access Services
Facilitate interactions with existing information and application assets

IT Monitoring

Infrastructure Services
Optimizes throughput, availability and performance

Figure 1-2 SOA reference architecture model

Interaction Services
Interaction services are about the presentation logic of the business design – components that support the interaction between applications and end-users. Also we recognize that interactions with the external world are not limited to just interactions with humans. In some cases, interaction logic orchestrates the interface to industrial robots, vehicles, sensors, RFID devices, environmental control systems, process control equipment, and so on.

Process Services
Process services include various forms of compositional logic – the most notable of which are business process flows and business state machines (finite-state machines for business composition). We consider both kinds of composition mechanisms, plus other forms such as business rules and decision tree processing, as well as more ad-hoc forms of composition, to be equally valid approaches to choreographing service composition.

12

WebSphere Service Registry and Repository Handbook

IT Service Management

For more information about this topic, see the following Web sites: http://www.ibm.com/developerworks/webservices/library/ws-choreograph y/index.html http://www.ibm.com/developerworks/library/ws-soa-progmodel3/

Business Application Services
Business application services implement your core business logic. These are service components created specifically as services within a business model and that represent the basic building blocks of your business design – services that are not decomposable within the business model, but that can be composed to form higher level services.

Information Services
Information services contain the data logic of your business design. This logic exists at two levels. On the surface, information services provide access to the persistent data of your business. This can include query statements for retrieving the information you care about or referential integrity checks on the information manipulated by these services. These data services are available to the business application as services – often constructed with specific domain model semantics so that they appear for all intents and purposes as business application services. For more information, go to the following Web site: http://www.ibm.com/developerworks/webservices/library/ws-soa-ims2/in dex.html

Access Services
Access services are dedicated to integrating existing applications and functions into the service-oriented architecture. This includes simple wrapping of those functions and rendering them as services (in the case where the existing function is a good match with the semantic requirements of the business model in which it will be used), or in more complex cases augmenting the logic of the existing function to better meet the needs of the business design. In the latter case, the access service may in fact invoke multiple current functions to achieve the semantic requirements of the service. In other architectures we have often referred to these access services as adapters. For more information, go to the following Web site: http://www.ibm.com/developerworks/webservices/library/ws-buildebay/

Chapter 1. Introduction to SOA

13

Partner Services
Partner services capture the semantics of partner interoperability that have a direct representation in the business design. This can, for example, include the policies and constraints that other businesses must conform to work with your business – including business vertical requirements such as the need to conform to specific industry message and interchange standards like EDIFACT, SWIFT, RosettaNet, and so on. It can involve the business logic of managing how partners are selected, and which ones are used as a preference over others in particular circumstances.

1.1.5 Supporting elements of the SOA reference architecture
The remaining portions of the reference architecture are directly relevant to the SOA Foundation, and in fact may even be aspects that you can contribute code to or customize to meet your needs, but generally will not contain functional aspects of the business design and the application logic that goes directly to implementing that business design. In general, these areas of the functional architecture have more to do with the exploitation of information technology as a means for implementing the business design. They in effect represent information technology concerns within the overall architecture. See Figure 1-3.

Business Innovation & Optimization Services
Provide for better decision-making With real-time business information

Development Services

Interaction Services
Enable collaboration between people, processes & information

Process Services
Orchestrate and automate business processes

Information Services
Manages diverse data and content in a unified manner

Integrated environment for design and creation of solution assets

Enables interconnectivity between services

ESB

Registry/Repository

Security Policy

Partner Services
Connect with trading partners

Business App Services
Build on a robust, scaleable, and secure services environment

Access Services
Facilitate interactions with existing information and application assets

IT Monitoring

Infrastructure Services
Optimizes throughput, availability and performance

Figure 1-3 SOA reference architecture model with registry and repository

14

WebSphere Service Registry and Repository Handbook

IT Service Management

Enterprise Service Bus
The Enterprise Service Bus (ESB) is a silent partner in the SOA reference architecture. Its presence in the architecture is transparent to the services of your SOA application. However, the presence of an ESB is fundamental to simplifying the task of invoking services – making the use of services wherever they are needed, independent of the details of locating those services and transporting service requests across the network to invoke those services wherever they reside within your enterprise. Access services (see “Access Services” on page 13) that wrap existing applications may exist wherever that application has been deployed – on different servers, in different departments, in different data centers. The enterprise service bus simplifies the task of incorporating these disparate systems so that you can exploit them in your business design. See 1.2.7, “Enterprise Service Bus and SOA” on page 28 for additional information. For more information, go to the following Web sites: http://www.ibm.com/developerworks/websphere/library/techarticles/050 9_flurry1/0509_flurry1.html http://www.ibm.com/developerworks/websphere/techjournal/0509_reinitz /0509_reinitz.html http://www.ibm.com/developerworks/webservices/library/ws-esbia/index .html http://www.ibm.com/developerworks/library/ws-soa-progmodel4/

Registry/Repository
Like the Enterprise Service Bus, service registry and repository is a silent partner in the SOA reference architecture. Note the highlighted Registry/Repository function in Figure 1-3 on page 14. Even though Figure 1-3 on page 14 makes it appear that the service registry and repository function is part of the Enterprise Service Bus, it is not. The service registry and repository function is a separate entity from the Enterprise Service Bus. A service registry and repository handles the management of service descriptions and serves as the system of record for this information throughout the complete lifecycle of a service. The service registry and repository is used to find, publish, manage and subscribe to services with the assurance that the underlying policies associated with correct usages of these services are enforced and governed. It supports the following functions:

Chapter 1. Introduction to SOA

15

Find Publish Subscribe Manage

Search/browse for services with varying degrees of criteria driven by any metadata associated with the service Add new services through an approval process to be available and managed in an enterprise-wide scale Register to listen to any changes to the metadata associated with the services Provide customizable processes to manage the lifecycle of services in the registry enabling access control, promote/retire and analyze changes to services through impact analyses

In the Model phase (refer to “Model” on page 8) and Assemble phase (refer to “Assemble” on page 8), the service registry and repository serves two main functions. First the service registry and repository can store or capture the interfaces and messages used by a new service when it is modeled, or a composite service or process when it is assembled. Second, the service registry and repository makes the service information searchable to encourage reuse of common services. A common example of service information gathered or searched in these phases would be documents conforming to the Web Services Description Language (WSDL) or XML Schema Definition (XSD) standards. Architects and developers can also annotate this technical information in the registry and repository with extra information using formal classification techniques, such as using the Web Ontology Language (OWL) standard, or by adding other content defined following XSD standards. Such classification of services allows for meaningful groupings of the services based on business objectives. The service Deployment phase (refer to “Deploy” on page 9) adds additional information to the service registry and repository including the connectivity, security and reliability characteristics of the deployed service. This extra information builds on the information from the Model and Assembly phases and differentiates each deployed service instance in the service-oriented architecture. The deployment information may be expressed in terms of new WSDL content or through the use of policy statements defined using the WS-Policy specifications. In Deploy and Manage phases of the lifecycle, the service registry and repository serves as a point of integration for the SOA environment by reflecting a system of record for each deployed service. The relationships, dependencies and interaction of the services can be documented and exploited in these phases. See 1.2.10, “Service registry and repository in an SOA” on page 34 for additional information.

16

WebSphere Service Registry and Repository Handbook

For more information, go to the following Web site: http://www.ibm.com/developerworks/webservices/library/specification/ ws-servregrep/ The purpose of this redbook is to focus on the IBM service registry and repository product, WebSphere Service Registry and Repository. For more detailed information about WebSphere Service Registry and Repository (WSRR), see Part 2, “WSRR concepts and architecture” on page 51.

Business Innovation and Optimization Services
These services primarily represent the tools and the metadata structures for encoding your business design, including your business policies and objectives. Business innovation and optimization is achieved by capturing your business design and then introspecting on that design to improve it through a combination of iterative refinement and analysis of real-time business metrics. Business innovation and optimization services exist in the architecture to help you capture, encode, analyze and iteratively refine your business design. The services also include tools to help you simulate your business design and to use those results to predict the effect that design, or changes to that design, will have on your business. In addition, these services include tools to help you define your key performance indicators – that is, those business objectives and general metrics that you want to monitor. For more information, go to the following Web sites: http://www.ibm.com/developerworks/webservices/library/ws-odbp7/index .html http://www.ibm.com/developerworks/webservices/library/ws-odbp8/index .html http://www.ibm.com/developerworks/webservices/library/ws-cei/index.h tml

IT Service Management
Once your application has been deployed to the information system, it needs to be managed along with the IT infrastructure on which it is hosted. IT service management represents the set of management tools used to monitor your service flows, the health of the underlying system, the utilization of resources, the identification of outages and bottlenecks, the attainment of service goals, the enforcement of administrative policies, and recovery from failures.

Chapter 1. Introduction to SOA

17

For more information, go to the following Web sites: http://www.ibm.com/software/tivoli/features/it-serv-mgmt/ http://www.ibm.com/developerworks/autonomic/library/ac-prism1/

Infrastructure Services
Infrastructure services form the core of the information technology environment for hosting SOA applications. It is through these services that we are able to build a reliable system to provide efficient utilization of resources, ensure the integrity of the operational environment, balance workload to meet service level objectives, isolate work to avoid interference, perform maintenance, secure access to confidential business processes and data, and simplify overall administration of the system.

1.2 Service-oriented architecture - an IT view
In the previous section, we described service-oriented architecture from a business point of view. In this section, we describe SOA from an IT point of view.

1.2.1 Definition of a service-oriented architecture
Following are a few definitions of SOA. Note the common terms used in the definitions.

Component model
Service-oriented architecture is a component model that interrelates an application’s different functional units, called services, through well-defined interfaces and contracts between these services. The interface is defined in a neutral manner that should be independent of the hardware platform, the operating system, and the programming language in which the service is implemented. This allows services, built on a variety of such systems, to interact with each other in a uniform and universal manner. This feature of having a neutral interface definition that is not strongly tied to a particular implementation is known as loose coupling between services. The benefit of a loosely-coupled system is its agility and ability to survive evolutionary changes in the structure and implementation of the internals of each service that makes up the whole application.

18

WebSphere Service Registry and Repository Handbook

Application architecture
Service-oriented architecture is an application architecture in which all functions, or services, are defined using a description language and have invocable interfaces that are called to perform business processes. Each interaction is independent of each and every other interaction and the interconnect protocols of the communicating devices (that is, the infrastructure components that determine the communication system do not affect the interfaces). Because interfaces are platform-independent, a client from any device using any operating system in any language can use the service. Though built on similar principles, SOA is not the same as Web services, which indicates a collection of technologies, such as SOAP and XML. SOA is more than a set of technologies and runs independent of any specific technologies.

Integration architecture
Service-oriented architecture is an integration architecture approach based on the concept of a service. The business and infrastructure functions that are required to build distributed systems are provided as services that collectively, or individually, deliver application functionality to either end-user applications or other services. SOA specifies that within any given architecture, there should be a consistent mechanism for services to communicate. That mechanism should be coupled loosely and should support the use of explicit interfaces.

1.2.2 SOA terms
Figure 1-4 highlights the key terms used to describe a service-oriented architecture.

Chapter 1. Introduction to SOA

19

… a service?

… service orientation? A way of integrating your business as linked services and the outcomes that they bring

A repeatable business task – e.g., check customer credit; open new account

… service oriented architecture (SOA)?

… a composite application?

An IT architectural style that supports service orientation

A set of related & integrated services that support a business process built on an SOA

Figure 1-4 Definition of key terms for a service-oriented architecture

A service is representative of a repeatable business task. Services are used to encapsulate the functional units of an application by providing an interface that is well defined and implementation independent. Services can be invoked (consumed) by other services or client applications.

Service orientation defines a method of integrating business applications and processes as linked services.

Service-oriented architecture (SOA) can be different things to different people depending on the persons role and context (business, architecture, implementation, operational). From a business perspective, SOA defines a set of business services composed to capture the business design that the enterprise wants to expose internally, as well as its customers and partners. From an architecture perspective, SOA is an architectural style that supports service orientation. At an implementation level, SOA is fulfilled using a standards based infrastructure, programming model and technologies such as Web services. From an operational perspective, SOA includes a set of agreements between service consumers and providers that specify the quality of service, as well as reporting on the key business and IT metrics.
A composite application is a set of related and integrated services that support a business process built on an SOA.

20

WebSphere Service Registry and Repository Handbook

Basic components of an SOA
At the most basic level, an SOA consists of the following three components: Service provider Service consumer Service registry Each component can also act as one of the two other components. For instance, if a service provider needs additional information that it can only acquire from another service, it acts as a service consumer. Figure 1-5 on page 21 shows the operations each component can perform.

Service Registry

-

Flight Reservation Car Hire Hotel Booking Mortgage Lending Office Supplies 1 Publish

2

Discover

Service Consumer

3

Invoke

Request/Response

Service Provider

Application-A - Travel Agent - Retail Bank - Publishing House

Application-B - Airline/Car Rental/Hotel Chain - Mortgage Specialist/Investment Banks - Office Supplies Company

Figure 1-5 SOA components and operations

The service provider creates a service and in some cases publishes its interface and access information to a service registry. Each provider must decide which services to expose, evaluate trade-offs between security and easy availability, determine how to price the services or determine how to exploit the value of the services if they are free. The provider also has to decide in which category the service should be listed, and what sort of trading partner agreements are required to use the service.

Chapter 1. Introduction to SOA

21

The service registry is responsible for making the service interface and implementation access information available to service consumers. This is a searchable registry of service descriptions where service providers publish their service descriptions. Service requestors find services and obtain binding information (in the service descriptions) for services during development for static binding, or during execution for dynamic binding. For statically bound service requestors, the service registry is an optional role in the architecture, because a service provider can send the description directly to service requestors. Likewise, service requestors can obtain a service description from other sources besides a service registry, such as a local file, FTP site, Web site, and so on. The implementers of a service registry must consider the scope with which the registry will be implemented. For example, there are public service registries available over the Internet to an unrestricted audience, as well as private service registries that are only accessible to users within a company-wide intranet. See “Registry/Repository” on page 15 and 1.2.10, “Service registry and repository in an SOA” on page 34 for additional information. The purpose of this redbook is to focus on the IBM service registry product, WebSphere Service Registry and Repository. For more detailed information about WSRR, see Part 2, “WSRR concepts and architecture” on page 51. The service consumer locates (discovers) entries in the service registry and then binds to the service provider in order to invoke the defined service.

1.2.3 Drivers for SOA
The main driver for SOA is to define an architectural approach that assists in the flexible integration of IT systems. Organizations spend a considerable amount of time and money trying to achieve rapid, flexible integration of IT systems across all elements of the business cycle. The drivers behind this objective include: Increasing the speed at which businesses can implement new products and processes, can change existing ones, or can recombine them in new ways Reducing implementation and ownership costs of IT systems and the integration between them Enabling flexible pricing models by outsourcing more fine-grained elements of the business than were previously possible or by moving from fixed to variable pricing, based on transaction volumes Simplifying the integration work that is required by mergers and acquisitions Achieving better IT utilization and return on investment

22

WebSphere Service Registry and Repository Handbook

Achieving implementation of business processes at a level that is independent from the applications and platforms that are used to support the processes SOA prescribes a set of design principles and an architectural approach to achieve this rapid flexible integration.

1.2.4 What is a service?
Having outlined SOA as being an architectural approach to defining integration architectures based on services, it is important to define what is meant by a service in this context in order to fully describe SOA and to understand what can be achieved by using it. A service can be defined as any discrete function that can be offered to an external consumer. This function can be an individual business function or a collection of functions that together form a process. There are many additional aspects to a service that we must also consider in the definition of a service within an SOA. The most commonly agreed-on aspects are that services: Encapsulate reusable business functions Are defined by explicit, implementation-independent interfaces Are invoked through communication protocols that stress location transparency and interoperability

Reusable business functions
A service can be any business function. In an SOA, however, it is preferable that the function is genuinely reusable. The goal of a service in an SOA is that it can be used and reused by one or more systems that participate in the architecture. For example, while the reuse of a Java™ logging API can be described as design time (when a decision is made to reuse an available package and bind it into application code), the intention of SOA is to achieve the reuse of services at: Runtime Each service is deployed in one place and one place only and is invoked remotely by anything that must use it. The advantage of this approach is that changes to the service (for example, to the calculation algorithm or the reference data on which it depends) need only be applied in a single place. Deployment time Each service is built once but redeployed locally to each system or to the set of systems that must use it. The advantage of this approach is increased flexibility to achieve performance targets or to customize the service (perhaps according to geography).

Chapter 1. Introduction to SOA

23

Explicit implementation independent interfaces
The use of explicit interfaces to define and to encapsulate service function is of particular importance to making services genuinely reusable. The interface should encapsulate only those aspects of process and behavior that are used in the interaction between the service consumer and the service provider. An explicit interface definition, or contract, is used to bind a service consumer and a service provider. It should specify only the mutual behavior that is required for the interaction and should specify nothing about the implementation of the consumer or the provider. By explicitly defining the interaction in this way, those aspects of either system (for example the platform on which they are based) that are not part of the interaction are free to change without affecting the other system. This implementation-independent interface allows either system to change implementation or identity freely. Figure 1-6 illustrates the use of explicit interfaces to define and encapsulate services functions.

SYSTEM 1

Internal code and process

Service definition of reusable business function

INTERFACE

Code definition of reusable business function

Internal code and process

SYSTEM 2

Figure 1-6 Service implementation in SOA

24

WebSphere Service Registry and Repository Handbook

Communication protocols that stress location transparency
SOA does not specify that any specific protocol be used to provide access to a service. A key principle in SOA is that a service is not defined by the communication protocol that it uses but instead, should be defined in a protocol-independent way that allows different protocols to be used to access the same service. Ideally, a service should only be defined once, through a service interface, and should have many implementations with different access protocols. This type of definition helps to increase the reusability of any service definition.

1.2.5 Web services and SOA
SOA represents a conceptual architecture of how to integrate applications. Web services are a specific set of standards and specifications that are one method of enabling SOA. Web services technology is a collection of standards (or emerging standards) that can be used to implement a service-oriented architecture. That is not to say that Web services and SOA are intrinsically linked, because they can be implemented separately. In fact, many significant SOAs are proprietary or customized implementations that are based on reliable messaging and Enterprise Application Integration middleware (for example, IBM WebSphere MQ and IBM WebSphere Message Broker) do not use Web services technologies. Also, most existing Web services implementations consist of point-to-point integrations that address a limited set of business functions between a defined set of cooperating partners. The logical links between Web services and SOA are: Web services provide an open-standard model for creating explicit, implementation-independent descriptions of service interfaces. Web services provide communication mechanisms that are location-transparent and interoperable. Web services are evolving, through Business Process Execution Language for Web Services (WS-BPEL), document-style SOAP, Web Services Description Language (WSDL), to support the implementation of well-designed services that encapsulate and model reusable function in a flexible manner.

Chapter 1. Introduction to SOA

25

1.2.6 Core technologies of Web services
Web services are self-contained, modular applications that can be described, published, located, and invoked over networks. Web services encapsulate business functions, ranging from a simple request-reply to full business process interactions. The services can be new or can wrap around existing applications. Figure 1-7 shows the relationship between the core elements of Web services in an SOA.

Figure 1-7 Web services core elements in SOA

Core elements
The following are the core technologies used for Web services. Extensible Markup Language (XML) XML 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 the content in a structured way, separated from its presentation to a specific device.

26

WebSphere Service Registry and Repository Handbook

Simple Object Access Protocol (SOAP) SOAP is a specification for the exchange of structured XML-based messages between the service provider, service consumer, and service registry, consisting of three parts: – The format of 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. – Encoding rules are used for expressing instances of application-defined data types. SOAP defines a programming language independent data type schema based on an XML Schema Descriptor (XSD), plus encoding rules for all data types defined to this model. – RPC representation is the convention for representing remote procedure calls (RPC) and responses. SOAP, in principle, is a protocol-independent transport. Consequently, it can potentially be used in combination with a variety of protocols such as HTTP, JMS, SMTP, or FTP. Currently, the most common way of exchanging SOAP messages is through HTTP, which is also the only protocol supported by WS-I Basic Profile 1.0. XML Schema Definition (XSD) XSD is a language for describing XML files that contain XML schema. It defines an XML document with respect to constraints on what elements and attributes may appear, in addition to their relationship to each other, what types of data may be in them, and so on. The description can then be used to verify that each content item in a document agrees to the description of the element where the content is to be placed. Web Services Description Language (WSDL) WSDL is an XML-based interface and implementation description language. The service provider uses a WSDL document in order to specify the operations that a Web service provides and the parameters and data types of these operations. A WSDL document also contains the service access information. A WSDL document contains the following main elements: – Types is the container for data type definitions using a type system such as an XML Schema. – An abstract, typed definition of the data being communicated, a message can have one or more typed parts.

Chapter 1. Introduction to SOA

27

– An operation is an abstract description of an action supported by the service that defines the input and output message and optional fault message. – The binding is 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. – The service is a collection of related ports. – The port is a single endpoint, an aggregation of a binding and a network address. – A port type is an abstract set of one or more operations supported by one or more ports. Universal Description, Discovery, and Integration (UDDI) UDDI 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. It will become clear in the next chapter that IBM WebSphere Service Registry and Repository is intended to replace UDDI in an SOA environment. Web Services Inspection Language (WSIL) WSIL is an XML-based specification that locates Web services without using UDDI. However, WSIL can also be used with UDDI, that is, it is orthogonal to UDDI and does not replace it. As stated previously in the UDDI definition, IBM WebSphere Service Registry and Repository is intended to replace WSIL in an SOA environment.

1.2.7 Enterprise Service Bus and SOA
Successfully implementing an SOA requires applications and an infrastructure that can support the service-oriented architecture principles. Applications can be enabled by creating service interfaces to existing or new functions that are hosted by the applications. The service interfaces should be accessed using an infrastructure that can route and transport service requests to the correct service provider. As organizations expose more and more functions as services, it is vitally important that this infrastructure should support the management of SOA on an enterprise scale. The Enterprise Service Bus (ESB) is a middleware infrastructure component that supports the implementation of SOA within an enterprise. Figure 1-8 on page 29 shows where the Enterprise Service Bus fits in the SOA reference architecture.

28

WebSphere Service Registry and Repository Handbook

Business Innovation & Optimization Services
Provide for better decision-making with real-time business information

Development Services

Interaction Services
Enables collaboration between people, processes & information

Process Services
Orchestrate and automate business processes

Information Services
Manages diverse data and content in a unified manner

Connect with trading partners

Build on a robust, scaleable, and secure services environment

Facilitate interactions with existing information and application assets

Infrastructure Services
Optimizes throughput, availability and performance

Figure 1-8 ESB in the SOA reference architecture

The need for an ESB can be seen by considering how it supports the concepts of SOA implementation by: Decoupling the consumer’s view of a service from the actual implementation of the service Decoupling technical aspects of service interactions Integrating and managing services in the enterprise Decoupling the consumer’s view of a service from the actual implementation greatly increases the flexibility of the architecture. It allows the substitution of one service provider for another (for example, because another provider offers the same services for lower cost or with higher standards) without the consumer being aware of the change or without the need to alter the architecture to support the substitution. This decoupling is better achieved by having the consumers and providers interact via an intermediary. Intermediaries publish services to consumers. The consumer binds to the intermediary to access the service, with no direct coupling to the actual provider of the service. The intermediary maps the request to the location of the real service implementation. In an SOA, services are described as being loosely coupled. However, at implementation time, there is no way to loosely couple a service or any other

Apps & Info Assets

Integrated environment for design and creation of solution assets

ESB
Partner Services

Enable inter-connectivity between services

Business App Services

Access Services

Manage and secure services, applications & resources

IT Service Management

Chapter 1. Introduction to SOA

29

interaction between systems. The systems must have some common understanding to conduct an interaction. Instead, to achieve the benefits of loose coupling, consideration should be given to how to couple or decouple various aspects of service interactions, such as the platform and language in which services are implemented, the communication protocols used to invoke services, the data formats used to exchange input and output data between service consumers and providers. Further decoupling can be achieved by handling some of the technical aspects of transactions outside of applications. This could apply to aspects of interactions such as: How service interactions are secured How the integrity of business transactions and data is maintained (for example, through reliable messaging, the use of transaction monitors, or compensation techniques) How the invocation of alternative service providers is handled in the event that the default provider is unavailable These aspects imply a need for middleware to support an SOA implementation. Some of the functions that might be provided by the middleware are: Map service requests from one protocol and address to another Transform data formats Support a variety of security and transactional models between service consumers and service providers and recognize that consumers and providers might support or require different models Aggregate or disaggregate service requests and responses Support communication protocols between multiple platforms with appropriate qualities of service Provide messaging capabilities such as message correlation and publish/subscribe, to support different messaging models such as events and asynchronous request/response This middleware support is the role of an ESB.

1.2.8 Definition of an Enterprise Service Bus
An ESB provides an infrastructure that removes any direct connection between service consumers and providers. Consumers connect to the bus and not the provider that actually implements the service. This type of connection further decouples the consumer from the provider. A bus also implements further value add capabilities. For example, security and delivery assurance can be

30

WebSphere Service Registry and Repository Handbook

implemented centrally within the bus instead of having this buried within the applications. Integrating and managing services in the enterprise outside of the actual implementation of the services in this way helps to increase the flexibility and manageability of SOA. The primary driver for an ESB, however, is that it increases decoupling between service consumers and providers. Protocols such as Web services define a standard way of describing the interface to a service provider that allow some level of decoupling (as the actual implementation details are hidden). However, the protocols imply a direct connection between the consumer and provider. Although it is relatively straight forward to build a direct link between a consumer and provider, these links can lead to an interaction pattern that consists of building multiple point-to-point links that perform specific interactions. With a large number of interfaces this quickly leads to the build up of a complex spaghetti of links with multiple security and transaction models. Routing control is distributed throughout the infrastructure, and probably no consistent approach to logging, monitoring, or systems management is implemented. This environment is difficult to manage or maintain and inhibits change. A common approach to reducing this complexity is to introduce a centralized point through which interactions are routed, as shown in Figure 1-9.
Direct Connection
Service Consumer Service Provider

Hub and Spoke
Service Consumer Service Provider

Service Consumer

Service Provider

Service Consumer

Hub: ESB

Service Provider

Service Consumer

Service Provider

Service Consumer

Service Provider

Figure 1-9 Direct connection and central hub integration styles

A hub and spoke architecture is a common approach that is used in application integration architectures. In a hub, the distribution rules are separated from applications. The applications connect to the hub and not directly to any other application. This type of connection allows a single interaction from an application to be distributed to multiple target applications without the consumer being aware that multiple providers are involved in servicing the request. This connection can reduce the proliferation of point-to-point connections.

Chapter 1. Introduction to SOA

31

Note that the benefit of reducing the number of connections only truly emerges if the application interfaces and connections are genuinely reusable. For example, consider the case where one application needs to send data to three other applications. If this is implemented in a hub, the sending application must define a link to the hub, and the hub must have links that are defined to the three receiving applications, giving a total of four interfaces that need to be defined. If the same scenario was implemented using multiple point-to-point links, the sending application would need to define links to each of the three receiving applications, giving a total of just three links. A hub only offers the benefit of reduced links if another application also needs to send data to the receiving applications and can make use of the same links as those that are already defined for the first application. In this scenario, the new application only needs to define a connection between itself and the hub, which can then send the data correctly formatted to the receiving applications. Hubs can be federated together to form what is logically a single entity that provides a single point of control but is actually a collection of physically distributed components. This is commonly termed a bus. A bus provides a consistent management and administration approach to a distributed integration infrastructure.

1.2.9 Enterprise requirements for an ESB
Using a bus to implement an SOA has a number of advantages. In an SOA services should, by definition, be reusable by a number of different consumers, so that the benefits of reduced connections are achieved. In addition, the ESB: Supports high volumes of individual interactions. Supports more established integration styles, such as message-oriented and event-driven integration, to extend the reach of the SOA. The ESB should allow applications to be SOA enabled either directly or through the use of adapters. Support centralization of enterprise-level qualities of service and manageability requirements into the hub.

32

WebSphere Service Registry and Repository Handbook

Figure 1-10 show a high-level view of the ESB.

Figure 1-10 The Enterprise Service Bus

SOA applications are built from services. Typically, a business service relies on many other services in its implementation. The ESB is the component that provides access to the services and so enables the building of SOA applications.

Mediation support
The ESB is more than just a transport layer. It must provide mediation support to facilitate service interactions (for example, to find services that provide capabilities for which a consumer is asking or to take care of interface mismatches between consumers and providers that are compatible in terms of their capabilities). It must support a variety of ways to get on and off the bus, such as adapter support for existing applications or business connections, that enable external partners in business-to-business interaction scenarios. To support these different ways to get on and off the bus, it must support service interaction with a wide variety of service endpoints. It is likely that each endpoint will have its own integration techniques, protocols, security models and so on. This level of complexity should be hidden from service consumers. They need to be offered a simpler model. In order to hide the complexity from the consumers, the ESB is required to mediate between the multiple interaction models that are understood by service providers and the simplified view that is provided to consumers.

Chapter 1. Introduction to SOA

33

Protocol independence
As shown in Figure 1-10 on page 33, services can be offered by a variety of sources. Without an ESB infrastructure, any service consumer that needs to invoke a service needs to connect directly to a service provider using the protocol, transport, and interaction pattern that is used by the provider. With an ESB, the infrastructure shields the consumer from the details of how to connect to the provider. In an ESB, there is no direct connection between the consumer and provider. Consumers access the ESB to invoke services, and the ESB acts as an intermediary by passing the request to the provider using the appropriate protocol, transport, and interaction pattern for the provider. This intermediary connection enables the ESB to shield the consumer from the infrastructure details of how to connect to the provider. The ESB should support several integration mechanisms, all of which can be described as invoking services through specific addresses and protocols, even if in some cases the address is the name of a CICS transaction and the protocol is a J2EE resource adapter integrating with the CICS Transaction Gateway. By using the ESB, the consumers are unaware of how the service is invoked on the provider. Because the ESB removes the direct connection between service consumer and providers, an ESB enables the substitution of one service implementation by another with no effect to the consumers of that service. Thus, an ESB allows the reach of an SOA to extend to non-SOA enabled service providers. It can also be used to support migration of the non-SOA providers to using an SOA approach without impacting the consumers of the service.

1.2.10 Service registry and repository in an SOA
Service-oriented architecture promotes business agility and resilience through reuse, loose coupling, flexibility, interoperability, integration and governance. These are realized by separating service descriptions from their implementations, and using this descriptive information across the service life-cycle. Standards-based service information artefacts capture the technical details of what a service can do, how it can be invoked or what it expects other services to do. Information, annotations and classifications from the service providers can be associated with these artefacts to offer insight to potential users of the service on how and when it can be used, and what purposes it serves. A service registry and repository handles the management of service descriptions and serves as the system of record for this information. A populated and maintained service registry and repository is the place in an organization that catalogs all of the services deployed or used by an organization.

34

WebSphere Service Registry and Repository Handbook

Another function of a service registry and repository is to support the governance of the service lifecycle (see 1.1.3, “SOA lifecycle” on page 7) including promotion of services through phases of that life-cycle, controlled access to service information, and impact analysis and socialization of changes to services with interested parties.

Service registry and repository integration within SOA
A service registry and repository provides a place to organize, manage, find and govern the service descriptions. In heterogeneous deployment environments that are typical in SOA, the service registry and repository provides a standard, interoperable means for access, query and manipulate the service descriptions. The service registry and repository plays a central role throughout the SOA lifecycle. Therefore, it is important to note that it be integrated with applications from the service development lifecycle, change and release management, service runtimes, service management (operational efficiency and resilience) and other service registries and repositories. These integration points are shown in Figure 1-11.

Service Development Lifecycle
Model Build

Service Endpoint Registries / Repositories

Discover Assemble

Service Registry and Repository

Change and Release Management
Test

ESB

Operational Efficiency and Resilience
Manage Mediate Bind

Deploy

Runtime Integration

Figure 1-11 Service registry and repository integration points in an SOA

Chapter 1. Introduction to SOA

35

The Service Development Lifecycle box in Figure 1-11 represents the development time uses for a service registry and repository. Newly developed services are published to the service registry and repository. At the same time, the service registry and repository can be used to discover and reuse services that can serve as building blocks for new composite applications. The Change and Release Management box in Figure 1-11 on page 35 represents the lifecycle management of services and their service descriptions. This is the point at which service metadata is usually placed into the service registry and repository, assessed, administered, and made available to a broader constituency. The service registry and repository can be used to govern deployed services to ensure changes are authorized and service integrity is maintained. In addition, it can notify clients of changes to services. The Runtime Integration box in Figure 1-11 on page 35 represents the execution environment where the service registry and repository is accessed at runtime to dynamically select a service provider, or to dynamically enforce an invocation policy. It manages information that enables dynamic binding of service requestors to service providers (see Figure 1-5 on page 21) and allows the infrastructure to enforce registered policies. The Service Endpoint Registries/Repositories box in Figure 1-11 on page 35 represents the interactions between this service registry and repository and other distributed repositories to acquire service metadata for applications that may have services distributed over multiple registries and repositories. The Operational Efficiency and Resilience box in Figure 1-11 on page 35 represents the access to the service registry and repository to obtain additional information about services that are encountered during monitoring, to find out about new services that are candidates for monitoring, and for policies for monitoring and assessing the performance of services. Mediations in this area take advantage of the knowledge gained through monitoring and operational management.

Service registry and repository in SOA management
A service registry and repository stands as the source of service information and metadata in an organization. As such it plays a double role in the overall domain space of SOA management. It provides the SOA management infrastructure with detailed information about the registered services It supports the enrichment of service information with operational data observed and processed by the SOA management infrastructure

36

WebSphere Service Registry and Repository Handbook

Figure 1-12 provides a high-level overview of a service registry and repository in the SOA management space.

Service Consumer

Consume Services

Service Provider

Information on Provided Services

Register Provided Services

Observe & Manage Services

Service Registry & Repository

Information on Registered Services Information on Operational Services

Monitoring & Management

Figure 1-12 Service registry and repository and SOA management components

Chapter 1. Introduction to SOA

37

Figure 1-13 abstracts away the notion of Service Consumer and rather focusses on the other relevant roles.

Service Provider

Provided services are registered in SRR

Services are observed by the Monitoring and Management infrastructure Information on registered services is made available

Service Registry & Repository Operational data on observed services is fed back

Monitoring & Management

Operational data enriches the service information and metadata

Information on registered services is reconciled with that collected from observed services and is used to augment the understanding of the management domain

Figure 1-13 The role of service registry and repository in SOA management

Registered services are managed in the service registry and repository. This information is accessed by multiple actors, including the Service Provider (registering services) and the Service Consumer (looking for services to consume). The Monitoring and Management infrastructure uses this information about registered services to enhance its understanding of the topology and characteristics of the services in the monitored SOA. Such information can include immediate details on service endpoints. It can also consist of some meaningful description of service interfaces and behavior, or it can provide a

38

WebSphere Service Registry and Repository Handbook

formal description of relationships across services and other SOA citizens such as business processes, consumers and providers. Based on this information the Monitoring and Management infrastructure can enhance its view of the managed resources and their topologies. The Monitoring and Management infrastructure then feeds back some operational data it collects about the observed services to the service registry and repository. This data has been captured and collected at runtime by the observation points from the running services that are part of the managed resources. Various elements of the runtime behavior of the services can be collected, such as the average response time, the fault rate, the size and frequency of the messages, and so on. These operational elements are used to further enrich the service information model managed by the service registry and repository, therefore allowing other actors in the SOA to use this information. For example, ESB infrastructures could use indications on the observed quality of interaction a service supports (average response time, fault rate, availability...) to perform smart routing decisions to the best available service. The same reasoning could be applied to any service consumers which would base their consumption decisions on the observed operational behavior of the service. Another example could be when planning for the migration of services based on their utilization. This collaboration between the service registry and repository and the SOA management infrastructure expands the management domain so that it can embrace the overall service lifecycle and reflect the operational dimension of the services as first class citizen in an SOA environment. Note: Figure 1-13 on page 38 does not include any integration fabric middleware such as the ESB. However, it is arguable that, at a conceptual level, such a component can be considered as both a service consumer (it consumes the actual services provided by dedicated service components or systems) and a service provider (it exposes these virtualized services). In the former case, it can decide which service to consume based on the operational behavior of those services (routing scenario). In the latter case, the services it exposes (or virtualizes) can themselves be considered as managed resources and, consequently, subject to runtime observation by the management infrastructure. See “Registry/Repository” on page 15 for additional information about a service registry and repository.

Chapter 1. Introduction to SOA

39

The purpose of this redbook is to focus on the IBM service registry and repository product, WebSphere Service Registry and Repository. For more detailed information about WSRR, see Part 2, “WSRR concepts and architecture” on page 51.

1.3 SOA governance
SOA is a compelling technique for developing software applications that best align with business models. However, SOA increases the level of cooperation and coordination required between business and information technology (IT), as well as among IT departments and teams. This cooperation and coordination is provided by SOA governance, which covers the tasks and processes for specifying and managing how services and SOA applications are supported.

1.3.1 What is SOA governance?
In general, governance means establishing and enforcing how a group agrees to work together. Specifically, there are two aspects to governance: Establishing chains of responsibility, authority, and communication to empower people, determining who has the rights to make what decisions. Establishing measurement, policy, and control mechanisms to enable people to carry out their roles and responsibilities. Governance is distinct from management in the following ways: Governance determines who has the authority and responsibility for making the decisions. Management is the process of making and implementing the decisions. To put it another way, governance says what should be done, while management makes sure it gets done. A more specific form of governance is IT governance, which does the following: Establishes decision-making rights associated with IT. Establishes mechanisms and policies used to measure and control the way IT decisions are made and carried out. That is, IT governance is about who's responsible for what in an IT department and how the department knows those responsibilities are being performed. SOA adds the following unique aspects to governance:

40

WebSphere Service Registry and Repository Handbook

Acts as an extension of IT governance that focuses on the lifecycle of services to ensure the business value of SOA. Determines who should monitor, define, and authorize changes to existing services within an enterprise. Governance becomes more important in SOA than in general IT. In SOA, service consumers and service providers run in different processes, are developed and managed by different departments, and require a lot of coordination to work together successfully. For SOA to succeed, multiple applications need to share common services, which means they need to coordinate on making those services common and reusable. These are governance issues, and they're much more complex than in the days of monolithic applications or even in the days of reusable code and components. As companies use SOA to better align IT with the business, companies can ideally use SOA governance to improve overall IT governance. Employing SOA governance is key if companies are to realize the benefits of SOA. For SOA to be successful, SOA business and technical governance is not optional, it is required.

1.3.2 SOA governance in practice
In practice, SOA governance guides the development of reusable services, establishing how services will be designed and developed and how those services will change over time. It establishes agreements between the providers of services and the consumers of those services, telling the consumers what they can expect and the providers what they're obligated to provide. SOA governance does not design the services, but guides how the services will be designed. It helps answer many thorny questions related to SOA: What services are available? Who can use them? How reliable are they? How long will they be supported? Can you depend on them to not change? What if you want them to change, for example, to fix a bug? Or to add a new feature? What if two consumers want the same service to work differently? Just because you decide to expose a service, does that mean you're obligated to support it forever? If you decide to consume a service, can you be confident that it will not be shut down tomorrow? SOA governance builds on existing IT governance techniques and practices. A key aspect of IT governance when using object-oriented technologies like Java 2 Platform, Enterprise Edition (J2EE) is code reuse. Code reuse also illustrates the difficulties of IT governance. Everyone thinks reusable assets are good, but they're difficult to make work in practice: Who's going to pay to develop them? Will development teams actually strive to reuse them? Can everyone really agree on a single set of behavior for a reusable asset, or will everyone have their own

Chapter 1. Introduction to SOA

41

customized version which isn't really being reused after all? SOA and services make these governance issues even more important and thus, their consequences even more significant. Governance is more of a political problem than a technological or business one. Technology focuses on matching interfaces and invocation protocols. Business focuses on functionality for serving customers. Technology and business are focused on requirements. While governance gets involved in those aspects, it focuses more on ensuring that everyone is working together and that separate efforts are not contradicting each other. Governance does not determine what the results of decisions are, but what decisions must be made and who will make them. The two parties, the consumers and the providers, have to agree on how they're going to work together. Much of this understanding can be captured in a service-level agreement (SLA), measurable goals that a service provider agrees to meet and that a service consumer agrees to live with. This agreement is like a contract between the parties, and can, in fact, be a legal contract. At the very least, the SLA articulates what the provider must do and what the consumer can expect. SOA governance is enacted by a center of excellence (COE), a board of knowledgeable SOA practitioners who establish and supervise policies to help ensure an enterprise's success with SOA. The COE establishes policies for identification and development of services, establishment of SLAs, management of registries, and other efforts that provide effective governance. COE members then put those policies into practice, mentoring and assisting teams with developing services and composite applications. Once the governance COE works out the policies, technology can be used to manage those policies. Technology doesn't define an SLA, but it can be used to enforce and measure compliance. For example, technology can limit which consumers can invoke a service and when they can do so. It can warn a consumer that the service has been deprecated. It can measure the service's availability and response time. A good place for the technology to enforce governance policies is through a combination of an enterprise service bus (ESB) and a service registry. A service can be exposed so that only certain ESBs can invoke it. Then the ESB/registry combination can control the consumers' access, monitor and meter usage, measure SLA compliance, and so on. This way, the services focus on providing the business functionality, and the ESB/registry focuses on aspects of governance.

42

WebSphere Service Registry and Repository Handbook

1.3.3 Aspects of SOA governance
SOA governance is not just a single set of practices, but many sets of practices coordinated together. The sections that follow provide a brief overview of the various aspects of SOA governance.

Service definition
The most fundamental aspect of SOA governance is overseeing the creation of services. Services must be identified, their functionality described, their behavior scoped, and their interfaces designed. The governance COE may not perform these tasks, but it makes sure that the tasks are being performed. The COE coordinates the teams that are creating and requiring services, to make sure needs are being met and to avoid duplicate effort. Often, it is not obvious what should be a service. The function should match a set of repeatable business tasks. The service's boundaries should encapsulate a reusable, context-free capability. The interface should expose what the service does, but hide how the service is implemented and allow for the implementation to change or for alternative implementations. When services are designed from scratch, they can be designed to model the business; when they wrap existing function, it can be more difficult to create and implement a good business interface. An interesting example of the potential difficulties in defining service boundaries is where to set transactional boundaries. A service usually runs in its own transaction, making sure that its functionality either works completely or is rolled back entirely. However, a service coordinator may want to invoke multiple services in a single transaction (ideally through a specified interaction like WS-AtomicTransactions). This task requires the service interface to expose its transaction support so that it can participate in the caller's transaction. But such exposure requires trust in the caller and can be risky for the provider. For example, the provider may lock resources to perform the service, but if the caller never finishes the transaction (it fails to commit or roll back), the provider will have difficulty cleanly releasing the resource locks. As this scenario shows, the scope of a service and who has control is sometimes no easy decision.

Service deployment lifecycle
Services do not come into being instantaneously and then exist forever. Like any software, they need to be planned, designed, implemented, deployed, maintained, and ultimately, decommissioned. The application lifecycle can be public and affect many parts of an organization, but a service's lifecycle can have even greater impact because multiple applications can depend on a single service.

Chapter 1. Introduction to SOA

43

The lifecycle of services becomes most evident when you consider the use of a registry. When should a new service be added to the registry? Are all services in a registry necessarily available and ready for use? Should a decommissioned service be removed from the registry? While there is no one-size-fits-all lifecycle that is appropriate for all services and all organizations, a typical service development lifecycle has five main stages: 1. Plan A new service that is identified and is being designed, but has not yet been implemented or is still being implemented. 2. Test Once implemented, a service must be tested. Some testing may need to be performed in production systems, which use the service as though it were active. 3. Active This is the stage for a service available for use and what we typically think of as a service. It is a service, it is available, it really runs and really works, and it has not been decommissioned yet. 4. Deprecate This stage describes a service which is still active, but will not be for much longer. It is a warning for consumers to stop using the service. 5. Sunset This is the final stage of a service, one that is no longer being provided. Registries may want to keep a record of services that were once active, but are no longer available. This stage is inevitable, and yet frequently is not planned for by providers or consumers.

Sunsetting effectively turns the service version off, and the sunset date should be planned and announced ahead of time. A service should be deprecated within a suitable amount of time before it is sunsetted, to programmatically warn consumers so that they can plan accordingly. The schedule for deprecation and sunsetting should be specified in the SLA.
One stage which may appear to be missing from this list is “maintenance.” Maintenance occurs while a service is in the active state; it can move the service back into test to reconfirm proper functionality, although this can be a problem for existing users depending on an active service provider. Maintenance occurs in services much less than you might expect; maintenance of a service often involves not changing the existing service, but producing a new service version.

44

WebSphere Service Registry and Repository Handbook

Service versioning
No sooner than a service is made available, the users of those services start needing changes. Bugs need to be fixed, new functionality added, interfaces redesigned, and unneeded functionality removed. The service reflects the business, so as the business changes the service needs to change accordingly. With existing users of the service, however, changes need to be made judiciously so as not to disrupt their successful operation. At the same time, the needs of existing users for stability cannot be allowed to impede the needs of users desiring additional functionality. Service versioning meets these contradictory goals. It enables users satisfied with an existing service to continue using it unchanged, yet allows the service to evolve to meet the needs of users with new requirements. The current service interface and behavior is preserved as one version, while the newer service is introduced as another version. Version compatibility can enable a consumer expecting one version to invoke a different but compatible version. While versioning helps solve these problems, it also introduces new ones, such as the need to migrate.

Service migration
Even with service versioning, a consumer cannot depend on a service, or more specifically, a desired version of that service, to be available and supported forever. Eventually, the provider of a service is bound to stop providing it. Version compatibility can help delay this “day of reckoning” but will not eliminate it. Versioning does not obsolete the service development lifecycle, but it enables the lifecycle to play out over successive generations. When a consumer starts using a service, it is creating a dependency on that service, a dependency that has to be managed. A management technique is for planned, periodic migration to newer versions of the service. This approach also enables the consumer to take advantage of additional features added to the service. However, even in enterprises with the best governance, service providers cannot depend on consumer migration alone. For a variety of reasons, for example existing code, manpower, budget, priorities, some consumers may not migrate in a timely fashion. Does that mean the provider must support the service version forever? Can the provider simply disable the service version one day after everyone should have already migrated? Neither of those extremes is desirable. A good compromise is a planned deprecation and sunsetting schedule for every service version, as described in “Service deployment lifecycle” on page 43.

Chapter 1. Introduction to SOA

45

Service registries
How do service providers make their services available and known? How do service consumers locate the services they want to invoke? These are the responsibilities of a service registry. It acts as a listing of the services available and the addresses for invoking them. The service registry also helps coordinate versions of a service. Consumers and providers can specify which version they need or have, and the registry then makes sure to only enumerate the providers of the version desired by the consumer. The registry can manage version compatibility, tracking compatibility between versions, and enumerating the providers of a consumer's desired version or compatible versions. The registry can also support service states, like test and deprecated, and only make services with these states available to consumers that want them. When a consumer starts using a service, a dependency on that service is created. While each consumer clearly knows which services it depends on, globally throughout an enterprise these dependencies can be difficult to detect, much less manage. Not only can a registry list services and providers, but it can also track dependencies between consumers and services. This tracking can help answer the age-old question: Who's using this service? A registry aware of dependencies can then notify consumers of changes in providers, such as when a service becoming deprecated.

Service message model
In a service invocation, the consumer and provider must agree on the message formats. When separate development teams are designing the two parts, they can easily have difficultly finding agreement on common message formats. Multiply that by dozens of applications using a typical service and a typical application using dozens of services, and you can see how simply negotiating message formats can become a full-time task. A common approach for avoiding message format chaos is to use a canonical data model. A canonical data model is a common set of data formats that is independent of any one application and shared by all applications. In this way, applications do not have to agree on message formats, they can simply agree to use existing canonical data formats. A canonical data model addresses the format of the data in the message, so you still need agreement around the rest of the message format, for example header fields, what data the message payload contains, and how that data is arranged, but the canonical data model goes a long way toward reaching agreement. A central governance board can act as a neutral party to develop a canonical data model. As part of surveying the applications and designing the services, it can also design common data formats to be used in the service invocations.

46

WebSphere Service Registry and Repository Handbook

Service monitoring
If a service provider stops working, how will you know? Do you wait until the applications that use those services stop working and the people that use them start complaining? A composite application, one that combines multiple services, is only as reliable as the services it depends on. Since multiple composite applications can share a service, a single service failure can affect many applications. SLAs must be defined to describe the reliability and performance consumers can depend on. Service providers must be monitored to ensure that they're meeting their defined SLAs. A related issue is problem determination. When a composite application stops working, why is that? It may be that the application head, the UI that the users interface with, has stopped running. But it can also be that the head is running fine, but some of the services it uses, or some of the services that those services use, are not running properly. Thus it is important to monitor not just how each application is running, but also how each service (as a collection of providers) and individual providers are also running. Correlation of events between services in a single business transaction is critical. Such monitoring can help detect and prevent problems before they occur. It can detect load imbalances and outages, providing warning before they become critical, and can even attempt to correct problems automatically. It can measure usage over time to help predict services that are becoming more popular so that they can run with increased capacity.

Service ownership
When multiple composite applications use a service, who is responsible for that service? Is that person or organization responsible for all of them? One of them; if so, which one? Do others think they own the service? Welcome to the ambiguous world of service ownership. Any shared resource is difficult to acquire and care for, whether it is a neighborhood park, a reusable Java framework, or a service provider. Yet a needed pooled resource provides value beyond any participant's cost: Think of a public road system. Often an enterprise organizes its staff reporting structure and finances around business operations. To the extent that an SOA organizes the enterprise's IT around those same operations, the department responsible for certain operations can also be responsible for the development and run time of the IT for those operations. That department owns those services. Yet the services and composite applications in an SOA often do not follow an enterprise's strict

Chapter 1. Introduction to SOA

47

hierarchical reporting and financial structure, creating gaps and overlap in IT responsibilities. A related issue is user roles. Because a focus of SOA is to align IT and business, and another focus is enterprise reuse, many different people in an organization have a say in what the services will be, how they will work, and how they'll be used. These roles include business analyst, enterprise architect, software architect, software developer, and IT administrator. All of these roles have a stake in making sure the services serve the enterprise needs and work correctly. An SOA should reflect its business. Usually this means changing the SOA to fit the business, but in cases like this, it may be necessary to change the business to match the SOA. When this is not possible, increased levels of cooperation are needed between multiple departments to share the burden of developing common services. This cooperation can be achieved by a cross-organizational standing committee that, in effect, owns the services and manages them.

Service testing
The service deployment lifecycle includes the test stage, during which the team confirms that a service works properly before activating it. If a service provider is tested and shown to work correctly, does the consumer need to retest it as well? Are all providers of a service tested with the same rigor? If a service changes, does it need to be retested? SOA increases the opportunity to test functionality in isolation and increases the expectation that it works as intended. However, SOA also introduces the opportunity to retest the same functionality repeatedly by each new consumer who doesn't necessarily trust that the services it uses are consistently working properly. Meanwhile, because composite applications share services, a single buggy service can adversely affect a range of seemingly unrelated applications, magnifying the consequences of those programming mistakes. To leverage the reuse benefits of SOA, service consumers and providers need to agree on an adequate level of testing of the providers and need to ensure that the testing is performed as agreed. Then a service consumer need only test its own functionality and its connections to the service, and can assume that the service works as advertised.

Service security
Should anyone be allowed to invoke any service? Should a service with a range of users enable all users to access all data? Does the data exchanged between service consumers and providers need to be protected? Does a service need to be as secure as the needs of its most paranoid users or as those of its most lackadaisical users?

48

WebSphere Service Registry and Repository Handbook

Security is a difficult but necessary proposition for any application. Functionality needs to be limited to authorized users and data needs to be protected from interception. By providing more access points to functionality (that is, services), SOA has the potential to greatly increase vulnerability in composite applications. SOA creates services that are easily reusable, even by consumers who ought not to reuse them. Even among authorized users, not all users should have access to all data the service has access to. For example, a service for accessing bank accounts should only make a particular user's accounts available, even though the code also has access to other accounts for other users. Some consumers of a service have greater needs than other consumers of the same service for data confidentiality, integrity, and nonrepudiation. Service invocation technologies must be able to provide all of these security capabilities. Access to services has to be controlled and limited to authorized consumers. User identity must be propagated into services and used to authorize data access. Qualities of data protection have to be represented as policies within ranges. This enables consumers to express minimal levels of protection and maximum capabilities and to be matched with appropriate providers who may, in fact, include additional protections. For more information, go to the following Web sites: https://www.ibm.com/software/solutions/soa/gov/ http://www.ibm.com/developerworks/ibm/library/ar-servgov/ http://www.ibm.com/developerworks/rational/downloads/06/plugins/rmc_ soa_gov/overview.html http://www.ibm.com/developerworks/wikis/display/woolf/SOA+Governance ?showChildren=false&decorator=printable

1.4 SOA summary
Service-oriented architecture and Web services enable new opportunities for more flexible, rapid, and widespread integration in a model that is consistent with the exposure of business function as services. SOA and Web services offer the choreography of those services into processes that can be modeled, executed, and monitored with features such as: SOA defines concepts and general techniques for designing, encapsulating, and invoking reusable business functions through loosely bound service interactions. Most of the techniques have been proven individually in previous

Chapter 1. Introduction to SOA

49

technologies or design styles. SOA unites them in an approach that is intended to bring encapsulation and reuse to the enterprise level. Web services provide an emerging set of open-standard technologies that can be combined with proven existing technologies to implement the concepts and techniques of service-oriented architecture. Industry support for Web services standards, interoperability among different implementations of Web services, and the infrastructure technology that is required to support a service-oriented architecture give technology customers increasingly mature and sophisticated technologies that are suitable for service-oriented architecture implementation. These techniques and technologies give you the tools that are required to implement flexible service-oriented architectures and to evolve toward an on demand business model. However, SOA is an architectural approach, not a technology or a product. In order to implement an SOA, you must have the infrastructure to support the architecture, such as an Enterprise Service Bus and a service registry and repository. For more information, go to the following Web site: http://download.boulder.ibm.com/ibmdl/pub/software/dw/webservices/ws -soa-whitepaper.pdf

50

WebSphere Service Registry and Repository Handbook

Part 2

Part

2

WSRR concepts and architecture

© Copyright IBM Corp. 2007. All rights reserved.

51

52

WebSphere Service Registry and Repository Handbook

2

Chapter 2.

Concepts and architecture
This chapter provides an overview of WebSphere Service Registry and Repository concepts and architecture: 2.1, “Overview of WebSphere Service Registry and Repository” on page 54 2.2, “Architecture of WebSphere Service Registry and Repository” on page 66

© Copyright IBM Corp. 2007. All rights reserved.

53

2.1 Overview of WebSphere Service Registry and Repository
IBM WebSphere Service Registry and Repository (WSRR) is a tool that enables better management and governance of your services. Through its registry and repository capabilities and its integration with IBM SOA Foundation (see to 1.1.2, “The SOA Foundation” on page 6), WebSphere Service Registry and Repository is an essential foundational component of a service-oriented architecture (SOA) implementation. WSRR enables you to store, access, and manage information about services and service interaction endpoint descriptions (referred to as service metadata) in an SOA. This information is used to select, invoke, govern, and reuse services as part of a successful SOA. This service information includes traditional Web services that implement Web Services Description Language (WSDL) interfaces with SOAP/HTTP bindings as well as a broad range of SOA services that can be described using WSDL, XML Schema Definition (XSD) and policy decorations, but might use a range of protocols and be implemented according to a variety of programming models. Note: For more information about the IBM SOA programming model and how it relates to the notion of service, see the Introduction to the IBM SOA Programming Model at: http://www.ibm.com/developerworks/webservices/library/ws-soa-prog model/ You can use WebSphere Service Registry and Repository to store information about services in your systems, or in other organizations' systems, that you already use, that you plan to use, or that you want to be aware of. For example, an application can check with WSRR just before it invokes a service to locate the most appropriate service that satisfies its functional and performance needs. This capability helps make an SOA deployment more dynamic and more adaptable to changing business conditions. WebSphere Service Registry and Repository includes: A service registry that contains information about services, such as the service interfaces, its operations, and parameters A metadata repository that has the robust framework and extensibility to suit the diverse nature of service usage

54

WebSphere Service Registry and Repository Handbook

The following sections give more detail on what WSRR is and what its functions are in a service-oriented architecture, and just as importantly, what WSRR is not intended for.

2.1.1 What is WebSphere Service Registry and Repository?
As the integration point for service metadata, WebSphere Service Registry and Repository establishes a central point for finding and managing service metadata acquired from a number of sources, including service application deployments and other service metadata and endpoint registries and repositories, such as Universal Description, Discovery, and Integration (UDDI). It is where service metadata that is scattered across an enterprise is brought together to provide a single, comprehensive description of a service. Once this happens, visibility is controlled, versions are managed, proposed changes are analyzed and communicated, usage is monitored and other parts of the SOA foundation can access service metadata with the confidence that they have found the copy of record. WebSphere Service Registry and Repository does not manage all service metadata, and it does not manage service metadata across the whole SOA lifecycle. It focuses on a minimalist set of metadata that describes capabilities, requirements, and the semantics of deployed service endpoints. It interacts and federates with other metadata stores that play a role in managing the overall lifecycle of a service. In summary, WebSphere Service Registry and Repository: Provides awareness of service associations and relationships while encouraging reuse of services to avoid duplication and reduce costs. Enhances connectivity with dynamic service selection and binding at runtime. Enables governance of services throughout the service lifecycle. Ensures interoperability of services with a registry and repository built on open standards. Use other standard registries and repositories to ensure a unified view across a variety of service information sources. Helps institute best practices and enforce policies in SOA deployments.

Registry and repository
System of records for service information and metadata
Service metadata artefacts exist across an enterprise in a variety of heterogeneous development and runtime stores which often provide information about a service tailored towards use cases in a particular phase of the SOA life-cycle. Examples include Asset Management systems in the development

Chapter 2. Concepts and architecture

55

space or Configuration Management systems in the runtime space (see “Reusable business functions” on page 23). Service metadata plays a key role in an SOA as it can be used to describe and enrich SOA concepts such as services, providers, consumers or contracts. These elements provide contextual as well as operational information about the overall system and can influence the way it is behaving. An example of such information is the definition of service endpoints to be used in a service interaction, indication of service ownership, or elements of service performance such as the average response time or the error rate for a particular service. In this context, WSRR mostly focuses on handling the metadata management aspects of operational services and provides the system of record of these metadata artefacts – the place where anybody looking for a catalogue of all services deployed in or used by the enterprise would go first. To fully support this role of a system of record for service related information and metadata, WSRR exhibits both registry and repository capabilities: It provides registry functions supporting publication and retrieval of metadata about services, their capabilities, requirements and semantics of services that enable service consumers to find services or to analyze their relationships. And it provides repository functions to store, manage and version service information and metadata. In that respect, WSRR really owns part of the service information and metadata and is able to play a key role in the overall SOA governance by governing and controlling the entities it manages.

Metadata and policy driven SOA
Part of the metadata stored and managed by WSRR may constitute policies that constrain and drive different aspects of the SOA. For example, you might want to define security policies and relate them to the services that are defined in WSRR. Another example would be to describe Service Level Agreements (SLA) and bind them to service providers and consumers as part of the overall service information model managed by WSRR. Such policies would influence and drive the behavior or the overall SOA by constraining or relaxing some of the aspects of this system of services. For example, defining security policies to control access and usage of services and storing them in WSRR would help in the implementation of an overall security model applied to an ecosystem of services. Defining service providers’ capabilities and service consumers’ expectations in the form of Service Level Agreements and relating these definitions to service interactions would also contribute to the ability to control and manage the overall SOA. As a system of record for service information and metadata, WebSphere Service Registry and Repository is a natural fit for the definition, the promotion and

56

WebSphere Service Registry and Repository Handbook

possibly the application of service oriented policies (“service oriented” in the sense that these policies apply to services) across the different actors and components of the SOA. In that context WSRR might take care of different aspects: The definition of service-oriented metadata and policies by leveraging a rich and extensible information model The promotion of service-oriented policies and metadata across the multiple actors and components of an SOA by providing extended access capabilities to retrieve the pieces of information (see “Integration point with other SOA components” on page 57) The enforcement of some service-oriented policies in relation with the overall governance model of the SOA (see “Enabler for SOA governance” on page 57 for more information)

Integration point with other SOA components
WebSphere Service Registry and Repository provides extended capabilities to promote service information and metadata across all the components of the architecture. The type of information exchanged depends on the context of the integration and the stage in the SOA Foundation lifecycle where it takes place. The alignment between a service registry and repository and the other SOA components has already been described in the text following Figure 1-11 on page 35. More details on these possible integration scenarios are provided later in this book. To enable this integration and the promotion of service information and metadata among a broad community of components, environments and stages, WSRR provides the following capabilities: Various interfaces and APIs supporting different interaction contexts, protocols and technologies such as EJB™, Web Services, JMX™, GUI and command line Complete security model to control these integration cases and restrict access to the managed resources Auditing mechanism to trace the operations taking place as part of these integration cases

Enabler for SOA governance
For a service-oriented architecture to be successful, it requires an expanded scope of governance centered around the reconciliation of multiple points of view and interest, such as business versus IT and development versus operations, and across different lines of business with different priorities. Coming up with a consistent service process model to meet these reconciled objectives is also key.

Chapter 2. Concepts and architecture

57

SOA governance tasks serve the entire SOA lifecycle, insuring service cooperation, service technology compatibility, and proper service investment and reuse. WebSphere Service Registry and Repository plays a key role in the end-to-end SOA governance. While the scope of SOA governance is definitively broader than what WSRR provides support for, it is important to stress the fact that WSRR must be considered as an enabler for SOA governance. WSRR supports governance of service metadata throughout the lifecycle of a service from its initial publication in the development space to deployment to service management. The support for SOA governance that WSRR provides is the subject of Chapter 5, “SOA governance enablers” on page 157. The following is a brief summary of the main mechanisms WSRR provides to support SOA governance: WSRR is a registry/repository that allows customers to both store and register standards-based service metadata including WSDL, XSD and policy. This gives customers the ability to have a copy of record for all service metadata and thus ensure consistency throughout their enterprise. The publication of service metadata through tooling, UI or API allows customers to socialize their high value or standardized shared services encouraging interoperability and reuse. The ability to query and find service metadata is used at development time through tooling, for reuse of interfaces and schemas as well as static binding of service endpoints. At runtime WSRR service queries through the API allow infrastructures such as the ESB to make dynamic endpoint selection decisions based on metadata in the registry. The capture of service dependencies allows the impact of changes to be assessed. Consumers of services that are impacted by the change can be notified and thus take advantage of improvements and ensure that no degradation in quality of service occurs. WSRR provides a basic mechanism for associating policies to services which allows the infrastructure (for example, ESB, Tivoli®) or application code to interpret and enforce the policy. This gives agility since policy is configured in the registry which can be changed quickly (without redeployment) but is still subject to governance. WSRR allows client applications (and other middleware) to extend the metadata that can be represented beyond the out-of-the-box standards-based metadata. By providing user defined classifications, properties and relationships, WSRR can be extended to support any enterprise service metadata model.

58

WebSphere Service Registry and Repository Handbook

WSRR supports validation plugins that can be configured to run whenever actions are performed against the registry. This means service metadata updates can be validated ensuring metadata integrity and (JMS) events generated to allow external applications to respond to the changes. For more information about SOA governance, see 1.3, “SOA governance” on page 40.

2.1.2 The limits of WebSphere Service Registry and Repository
In the previous section, we give a broad overview of what WebSphere Service Registry and Repository is, and what functions it can perform in a service-oriented architecture environment. In this section, we continue to define what WSRR is, while at the same time pointing out specific functions or aspects of an SOA that WSRR does not address. Analyzing what a component is not designed to do helps to frame and emphasize the scope of its responsibilities and capabilities. In the light of the elements previously described, we can now briefly list features and function not included in the WSRR scope of responsibility: WSRR is not a broker component to mediate/route service interactions WSRR is not a generic policy decision/enforcement point WSRR is not a generic content management solution WSRR is not a source configuration/asset management solution WSRR is not an enterprise wide metadata repository WSRR is not the definitive SOA governance tool WSRR is not a UDDI registry WSRR is not a system management solution

Not a broker component
WebSphere Service Registry and Repository’s main responsibility is to stand as a system of records for service oriented information and metadata. It does not replace any service broker component such as the Enterprise Service Bus (ESB), but rather complements these with extensive capabilities to query service information and metadata which would then be leveraged by these middleware components to route service requests and enforce service oriented policies. WSRR does not route service requests on its own nor does it act as an intermediary in the service invocation chain.

Chapter 2. Concepts and architecture

59

For a further detail, see 1.1.5, “Supporting elements of the SOA reference architecture” on page 14 and 1.2.7, “Enterprise Service Bus and SOA” on page 28.

Not a generic policy decision/enforcement point
While WebSphere Service Registry and Repository can store and manage service oriented policies as described in “Metadata and policy driven SOA” on page 56, it should not be considered as a generic policy decision/enforcement point. The responsibilities of WSRR in regard to service oriented policies are the following: Description, management and promotion of service oriented metadata and policies across the different components of the SOA: one can leverage WSRR information model to capture and store service oriented metadata and policies. WSRR query capabilities and interfaces provide access to that information to the different components of the SOA (for example, ESB, Service Gateway, Security Components...) which would then use it to enforce service oriented policies. Decision and enforcement point for some service oriented policies: while WSRR is definitively not a generic policy decision and enforcement point, some policies might be best enforced in WSRR itself. Examples might include some policies related to the governance and service lifecycle model as described here: – Compliance policies (for example, compliance with WS-I profiles or compliance with organization specific rules) – Security policies (for example, constrained access to service information and metadata to represent structured service ownership and visibility model)

Not a generic content management solution
WebSphere Service Registry and Repository is SOA and service centric in nature. It has not been designed to act as a generic content management solution and does not provide extended capabilities around information capturing, indexing or archiving. WSRR is specifically targeted at service information and metadata and cannot replace existing enterprise content management solutions. However, relationships can be described to materialize potential links that might exist between service oriented content managed in WSRR and pieces of information residing in other sources of data.

60

WebSphere Service Registry and Repository Handbook

Not a source configuration/asset management solution
WebSphere Service Registry and Repository is not a source configuration/asset management solution in that it does not try to address the usual requirements for these solutions: It does not aim to store all the artefacts (including source code, deployment descriptors...) that make up a service, but rather only to manage service description and metadata. It does not try to capture services as packaged assets (including associated documentation, deployment scripts, test scripts...) but should rather focus on the minimalist amount of information necessary to describe, classify and access these services. However, as pointed out in the previous section (“Not a generic content management solution”), links can be described in WSRR to materialize possible relationships between the service registry and repository and other source of information such as source code or asset management solutions. These links will become obvious depending on the context WSRR is used in, and specifically on the positioning of WSRR in the service lifecycle. As illustrated in Figure 2-1 WSRR must clearly be considered to span the overall service lifecycle, including development and operational activities, and has to, in that respect, integrate with other sources of information targeted at specific parts of that lifecycle.

WebSphere Integration Developer

WebSphere Service Registry and Repository

WebSphere Business Modeler

Info Services Director

Rational Application Developer

Figure 2-1 WSRR and service oriented information and metadata exchange in the SOA lifecycle

Chapter 2. Concepts and architecture

61

Development and modeling tools such as WebSphere Integration Developer, WebSphere Business Modeler or Rational Application Developer all deal with service information and metadata in the context of their usual scope of application in the overall SOA lifecycle. To do so they have to exchange elements of information with WSRR in a bi-directional fashion: For example, service development requires use of and writing to a different kind of repository, such as an asset repository. However once a service exits development, often at deployment to a post-development environment, the service metadata will usually be copied to WSRR. On the other hand, consuming a service in a development environment also requires service description and information to be retrieved from WSRR. These interaction points are usually mandated at different stages within the service lifecycle or triggered as the result of specific events, in order to keep track and govern the notion of service and its different perspectives throughout the overall SOA lifecycle.

Not an enterprise wide metadata repository
While WebSphere Service Registry and Repository does provide information and metadata management capabilities, it does not aim to stand as the single source of service information in the enterprise. The service oriented information is spread across multiple sources as a result of multiple aspects of a SOA such as: Multiple delivery channels (twin consumer/provider tracks): information related to service consumers and providers is often physically separated and might not be easily reconciled into a single repository Extended scope of service lifecycle: as pointed out earlier, because of the rather large scope of the service lifecycle in an enterprise’s processes WSRR cannot accommodate all service related information and metadata but rather references external sources of data Organizational and governance constraints: SOA spans lines of business, this might imply that the information owned by these LoB and governed as part of separate governance domains is defined and managed in different repositories used and operated by different people. Operational and regulatory constraints: service information may span multiple environments within an organization, leading to the need to have physically separate repositories to accommodate various constraints between these environments (for example, security, connectivity...). This might also be the result of some regulations imposing a requirement that pieces of information and metadata be physically stored and managed in specific locations or geographies. Technical constraints: multiple products and technologies can be used to manage information and metadata, depending on both functional (for

62

WebSphere Service Registry and Repository Handbook

example, the availability of a predefined information model for a specific industry) and non-functional (for example, scalability, quality of information...) requirements. As a matter of fact, WSRR can be considered to mostly focus on the operational aspects of services in a SOA, while the rest of the information is owned and managed by other sources such as asset management, configuration management, identity management or generic information management solutions. The logical reconciliation of these islands of information usually follows a “master and satellite” topology where master copies of records are centrally managed and exchange information with satellites sources dedicated to specific aspects of the information lifecycle. Figure 2-2 on page 64 describes and extends these notions in the context of information services built using the IBM software portfolio. Two master copies of records, namely WebSphere Service Registry and Repository and WebSphere Metadata Server exchange information with their respective satellites. These two masters also exchange service information between them as part of the service lifecycle. Figure 2-2 on page 64 illustrates these interactions using the following use cases: Expose information services using WebSphere Information Server and publish it to WebSphere Service Registry and Repository Discover information services and associated metadata using WebSphere Integration Developer from the information managed by WebSphere Information Server

Chapter 2. Concepts and architecture

63

IBM Information Server Unified Deployment
Understand Info Svc 1: ValidateAddress Clense Transform Transform Info Svc 3: AccountInfo

WebSphere Service Registry and Repository Publish Information Service
Publish Find Enrich Manage Govern

Discover, model, and govern information structure and content

Standardize, merge, and correct information

Info Svc 2: OrderHistory

Combine and restructure information for new uses

Combine and restructure information for new uses

Unified Metadata Management Parallel Processing Rich Connectivity to Applications, Data and Content

WebSphere Integration Analyzer 3rd Party... WebSphere Metadata Server RDA WebSphere DataStage Info Services Director Info Services Director WebSphere QualityStage

WebSphere Integration Developer

Sharing of Service Metadata

WebSphere Service Registry and Repository

WebSphere Business Modeler

Rational Application Developer

IBM Information Server Unified Deployment
Understand Info Svc 1: ValidateAddress Clense Transform Transform Info Svc 3: AccountInfo

Discover, model, and govern information structure and content

Standardize, merge, and correct information

Info Svc 2: OrderHistory

Combine and restructure information for new uses

Combine and restructure information for new uses

Discovery of Services and metadata

Unified Metadata Management Parallel Processing Rich Connectivity to Applications, Data and Content

Figure 2-2 Sharing of service metadata across masters and satellites

Not the definitive SOA governance tool
While WebSphere Service Registry and Repository and SOA governance are closely related, it must be clearly understood that the aim of WSRR is not to provide support for the entire enterprise wide SOA governance framework, but rather to enable parts of it. In that respect, WSRR really focuses on the service lifecycle as a prime governed domain. By leveraging WSRR capabilities such as the following: defining permission rules on the information model customizing the service lifecycle model to drive and enforce the state of governed entities as they transit through this model, or implementing validation points to ensure compliance and correctness of parts of the information model,

64

WebSphere Service Registry and Repository Handbook

WSRR helps enable an overall SOA governance framework. See “Enabler for SOA governance” on page 57 for more information. See Chapter 5, “SOA governance enablers” on page 157 for additional detail on SOA governance.

Not a UDDI registry
Universal Description, Discovery and Integration (UDDI) provides a standardized API and model to describe, classify and access service information and metadata. It also provides corresponding methods to manipulate and query the UDDI model. The UDDI V3 specification was ratified as an OASIS Standard in February 2005. The UDDI specification defines a registry that evolved from an Internet service directory to a Web services registry specification. The SOA requirements described in Chapter 1, “Introduction to SOA” on page 3 go beyond the capabilities of UDDI, specifically in that SOA requires integration with repository and service lifecycle. Specifically, the UDDI specification falls short of what is required for a complete service registry and repository solution: UDDI is satisfactory for simple endpoint lookups. UDDI is not well suited for more advanced, general service metadata artefact retrieval. From the inception of UDDI, the focus was on finding services, usually Web services, and usually by humans at development time. Typical use cases for UDDI would not include runtime usage by demanding middleware. This is reflected in cumbersome and inefficient APIs for routine runtime use (creative artefact decomposition and mapping to the UDDI model often leads to inefficient search and retrieval paths, often requiring repeated use of different parts of the UDDI API). Emerging SOA use cases require that metadata and relationships be associated with pieces of service descriptions not originally foreseen by UDDI, such as associating policy with individual messages bound to operations. The UDDI information model does not allow fine grained description and manipulation of smaller pieces of service related elements such as operations, messages and policies. Because UDDI is not a repository with fine grained search of artefacts, searchable metadata must be extracted from referenced artefacts and mapped to the UDDI data model to be able to be queried. This would require proprietary decomposition and mapping conventions for emerging artefact types, relationships between artefacts, increasing artefact granularity, consumer SLA requirements and governance support. Also, the lack of repository capabilities prevents UDDI from actually storing and owning the artefacts, and thus from acting as a master copy of records of

Chapter 2. Concepts and architecture

65

the service artefacts. This severely limits its ability to control and govern their change. Note: For more information about UDDI, refer to: http://www.uddi.org/

Not a complete system management solution
WebSphere Service Registry and Repository stores and manages service information and metadata. This may include operational information about service behavior, status and compliance with predefined SLA. Such information would have been provided by external dedicated components in the SOA infrastructure such as management and monitoring solutions. However, WSRR is not in itself a complete system management solution as it does not exhibit the capabilities to actually monitor service execution at runtime. Integration between WebSphere Service Registry and Repository and IBM Tivoli Composite Application Manager for SOA is described in Chapter 15, “Integrating WSRR with ITCAM for SOA” on page 625 and provides a good example of this type of collaboration between a service registry and repository and some SOA management solution.

2.2 Architecture of WebSphere Service Registry and Repository
Figure 2-3 on page 67 provides a brief overview of how all the key building blocks fit together within the WebSphere Service Registry and Repository architecture.

66

WebSphere Service Registry and Repository Handbook

User User Interface Interface

Web

Eclipse Plug-in

External Systems

ESBs

Process Servers

Appliances

Monitors

3rd Party

Registries & Repositories

•••

Events Generated Programming Programming Interfaces Interfaces Java SOAP Extensions & Extensions & Integrations Integrations

Registry & Repository Registry & Repository Create Create Retrieve Retrieve Update Update Delete Delete Query Query Validation Notification

Admin Admin JMX Import // Export Import Export Configure Configure

Governance Governance Transition Transition Validate Validate Notify Notify Impact Analysis Impact Analysis Audit Audit Lifecycle Validators

Events Generated

Content models

RDB

Access Control Classifications

Figure 2-3 Overview of WebSphere Service Registry and Repository architecture

WebSphere Service Registry and Repository is essentially a Java 2 Platform Enterprise Edition (J2EE) application that runs on WebSphere Application Server. As such, it takes advantage of the role-based access control provided by the application server. When WSRR is deployed as an enterprise-wide application in your environment, it is recommended that security be turned on. This enables role-based views and access control, and this is tied to many of the WSRR governance capabilities. This J2EE application provides a core group of functions such as registry and repository, governance, and administration, all of them supported by shared access control and classification capabilities (see Figure 2-3). As mentioned previously, some of these features rely on the infrastructure services provided by the J2EE environment WSRR is running in. WebSphere Service Registry and Repository uses a relational database as a backend store for service information and metadata persistence. WSRR contains service information and metadata artefacts that are in the form of XML documents. You can put any XML document into WSRR, but there are some types that are special, such as WSDL and XSD. These special types are modeled, and when one of these special types of document is loaded into WSRR, it is parsed into a finer-grained information model.

Chapter 2. Concepts and architecture

67

You can also define non-XML pieces of information (referred to as GenericObjects) that represent service metadata entities that are not backed by a document in WSRR. To manipulate service information and metadata you can use the programming and user interfaces to perform basic Create, Retrieve, Update, and Delete (CRUD) operations on the content, and flexible queries based on XPATH expressions against the content. You can use J2EE Stateless Session Beans or Web services to interact with WSRR programmatically. You can also use a Web application or an Eclipse plug-in to interact with service metadata stored and managed by WSRR through dedicated user interfaces.

2.2.1 Overview of main components
The following sections introduce the key elements of the WebSphere Service Registry and Repository architecture. Refer to Figure 2-3 on page 67 to determine where each of the components fit in the WSRR architecture. Note: These architectural elements and the use cases they support are elaborated in more details in the remaining chapters of this book.

Registry and Repository
WebSphere Service Registry and Repository offers both registry and repository capabilities for service metadata. The repository allows users to store, manage and query service metadata artefacts holding service descriptions (WSDL, XSD, WS-Policy, SCDL or XML documents). It not only takes good care of the documents containing service metadata, but it also provides a fine-grained representation of the content of those documents (for example, ports and portTypes in WSDL documents). In addition, it provides registry functions for decorating registered service declarations and elements of the derived information models with user-defined properties, relationships, and classifiers. WSRR provides a rich query interface that makes use of those decorations when you want to find a service endpoint or service interface. Whenever a change to registry or repository content is detected by WSRR, it invokes all validation and notification plugins that are registered. Both kinds of plugins are considered extension mechanisms that you can use to customize how you want Registry and Repository to react to changes. You can write and register validation functions that WSRR will then execute when changes are made to the content. For example, you can write and register a validation function that checks for completeness of a service definition. You can also write and register notification functions to communicate changes in the content of the

68

WebSphere Service Registry and Repository Handbook

repository. WebSphere Service Registry and Repository comes with an out-of-the-box JMS notification plugin which posts notification messages to a JMS queue. By registering listeners to that queue it is possible to consume these messages and turn them into context or channel specific actions and notifications (for example, e-mail or SMS). WSRR also has a subscription capability that allows your users to register their interest in consuming notifications.

Governance functions
WebSphere Service Registry and Repository supports a rich set of extensible governance functions, including the ability to model your own service lifecycle model for governed entities, define valid transitions between service states, write and plugin validators to guard the transitions between states, and designate (notification) actions to be taken as result of the transition. It also provides interfaces to analyze the impact of changes to WSRR content, and provides auditing of such changes.

Classifications
Classifications play a major role in many interactions with WebSphere Service Registry and Repository. They allow you to annotate service descriptions and parts of service definitions with your corporate vocabulary and extend the service information model with additional information which are relevant to your particular context. For example, you can use classifications to segregate service endpoints that are deployed in different environments. Classifications are also used by WSRR to capture the governance state. WebSphere Service Registry and Repository classification systems are captured as ontologies in Web Ontology Language (OWL) documents that you load into WSRR using the administrative interface. You can then classify managed entities with values from these classification systems, which allows you to perform classification-based queries, and restrict access based on classification.

Chapter 2. Concepts and architecture

69

Note: In computer science, an ontology is a data model (a model that describes in an abstract way how data are represented in a business organization) that represents a domain (the relevant set of entities that are being dealt with by quantifiers) and is used to derive conclusions about the objects in that domain and the relations between them. An ontology is “a description of the concepts and relationships that can exist for an agent or a community of agents.” It is generally written “as a set of definitions of formal vocabulary”. OWL stands for Web Ontology Language. Where earlier languages have been used to develop tools and ontologies for specific user communities (particularly in the sciences and in company-specific e-commerce applications), they were not defined to be compatible with the architecture of the World Wide Web in general, and the Semantic Web in particular. OWL uses both URIs for naming and the description framework for the Web provided by RDF (Resource Description Framework) to add the following capabilities to ontologies: Ability to be distributed across many systems Scalability to Web needs Compatibility with Web standards for accessibility and internationalization Openness and extensibility OWL builds on RDF and RDF Schema and adds more vocabulary for describing properties and classes: among others, relations between classes (for example, disjointedness), cardinality (for example, “exactly one”), equality, richer typing of properties and characteristics of properties (for example, symmetry), and enumerated classes. For more information about OWL, visit the following URL provided by W3C as part of the Semantic Web Activity: http://www.w3.org/2004/OWL/

Access control model
In addition to the role-based access control provided by the underlying WebSphere Application Server, WebSphere Service Registry and Repository supports a fine-grained access control model that allows you to define which user roles can perform specific types of actions on corresponding artefacts. You can capture Access Control Rules in XACML and reference lifecycle states and semantic annotations such as classifications, and properties. This allows you to restrict visibility of services by business area or to restrict which user roles can transition services to certain lifecycle states.

70

WebSphere Service Registry and Repository Handbook

Administration interfaces
These interfaces support the import and export of WSRR content for exchange with other repositories and provide a JMX-based API for configuration and basic administration. These support interactions with the Access Control model and with the Classification Systems.

Programming interfaces
You can use Java and SOAP APIs to interact programmatically with WSRR. These APIs provide basic CRUD (create. retrieve, update, and delete) operations, governance operations, and a flexible query capability based on XPath. You can use the SOAP API to communicate content using XML data structures or the Java API to communicate content using SDO data graphs.

User interfaces
Two user interfaces are provided that enable you to interact with WebSphere Service Registry and Repository. A servlet-based Web User Interface (UI) is the main way for your users, representing different roles, to interact with WSRR. This UI supports look-up and publish scenarios, metadata management and analysis scenarios, and functions that support SOA governance. Your developer roles can also work with WSRR using an Eclipse plug-in that supports look-up, retrieval, and publishing of service metadata from your Eclipse-based development tools or management consoles.

Command line interface
A command line interface is provided to perform a mix of regular and administration operations using scripting capabilities.

2.2.2 Information model
This section provides a brief description of WebSphere Service Registry and Repository’s information model. A complete description of this model is provided in Chapter 3, “Information model” on page 79. Other documentation may to the WSRR information model as a “content model”. In this redbook, we use the term “information model”. The WebSphere Service Registry and Repository information model has elements representing service description entities (such as WSDL) and service description metadata (such as Classifications). All WSRR elements have a WSRR-assigned URI, a name and a description.

Chapter 2. Concepts and architecture

71

Service description entities are artefacts and documents created and managed in WSRR, both physical and logical, and describe the service. For example WSDL, PortType. Service description metadata is used to decorate service description entities with attributes like Properties and Relationships with other elements. Figure 3-1 on page 80 depicts an overview of WSRR’s content model. See Chapter 3, “Information model” on page 79 for more information.

2.2.3 Interfaces and APIs
You can use the programmatic and user interfaces that WebSphere Service Registry and Repository provides to interact with and manage its content. Using WSRR, you can create, retrieve, update and delete documents and GenericObjects managed by it. However, you cannot modify entities in the logical model. You can only change these by updating the document that contains the logical entity. GenericObjects can be created, retrieved and deleted. You can also change all semantic decorations on all entity types. Last but not least, you can govern services and related information elements as they go through their lifecycle.

Query interface
You can interact with the WebSphere Service Registry and Repository query interface in two ways: You can use one of the predefined queries that are configured via parameters (for example, all WSDL documents with classifier X). You can write your own XPath-based query. You can use XPath expressions in the Query API to perform searches for coarse and fine-grained queries. Queries can be performed using semantic annotations, properties, and all or parts of the physical service metadata artefacts. You can request that fragments of metadata be returned (such as endpoints), all metadata be returned, and both metadata and documents be returned. In addition to “free-form” XPath-based queries, a set of pre-canned queries are available for you to use to address common paths through the WSRR information model. When you use the XPath-based query interface, you create an XPath expression that identifies the type of managed entity to be returned and a filter that captures the managed elements related to the desired object. Extensions are provided for you to include classification annotations in a query. For example, if you are looking for all WSDL Services that have a port that refers to a binding referring to

72

WebSphere Service Registry and Repository Handbook

a portType named StockQuotePortType, the following query expression would be used: //WSDLService[port/binding/portType/@name='StockQuotePortType']; See 3.6, “XPath” on page 99 for additional information about XPath. See 3.9, “Query” on page 103 for additional information about the Query interface.

User interfaces
Two user interfaces (refer to Figure 2-3 on page 67) are provided to access WSRR: A Web user interface An Eclipse plug-in

Web user interface
The main interface is a Web application deployed with the WSRR runtime. This supports all of your user roles, offering lookup, browse, retrieve, publish, and annotate capabilities, as well as governance activities, such as import/export and impact analysis. The Web user interface supports customizable views of WSRR content represented to a user. A set of user interface definition files describes the content and layout of the various components that make up the Web user interface. The concept of user-role-specific perspectives is supported. WebSphere Service Registry and Repository comes with a set of predefined perspectives for the most common user roles, but you can customize the predefined ones or introduce new, role-specific perspectives. See 4.3, “Web user interface (Web UI)” on page 144 and Chapter 10, “Customizing the Web UI” on page 381 for additional information.

Eclipse plug-in
A subset of this user interface is offered as an Eclipse plug-in to meet the needs of your developer and analyst users that use Eclipse based-tooling. The Eclipse plug-in is used primarily for lookup, browse, retrieve and publish capabilities. See Chapter 11, “Using the WSRR Eclipse plug-in” on page 415 for additional information. The Eclipse plug-in is not shipped with the WebSphere Service Registry and Repository product distribution. It is available as a download from the following URL: http://www.ibm.com/support/docview.wss?rs=3163&context=SSWLGF&dc=D40 0&uid=swg24013925&loc=en_US&cs=UTF-8&lang=en

Chapter 2. Concepts and architecture

73

Command line interface
Interactive and scripted administration of WSRR is possible with the Jython-based command line interface The command line interface provides full support for all of the WSRR programmatic APIs, including all administrative operations. It may be used from a standalone Jython or Jacl interpreter, or it may be run inside wsadmin and used in conjunction with the facilities available there. The command line interface uses both the JMX API and the SOAP API to communicate with WSRR. See 4.4, “Command Line Interface” on page 154 for additional information.

Supported APIs
End-users can interact directly with WSRR using a Web-based console application or an Eclipse-based plug-in as mentioned previously. In addition, applications can fully interact with WSRR using one or more of its application programming interfaces (APIs) as shown in Figure 2-3 on page 67 and below: A J2EE-based Java API (EJB) A Web service SOAP-based API An administration JMX-based API

Usage APIs
Note: We refer to both the EJB API and the SOAP API as usage APIs to emphasize the fact that these APIs directly support WSRR regular use cases, as opposed to administration operations which are performed via the JMX API. WebSphere Service Registry and Repository provides three different usage APIs with dedicated scope and exposition as summarized in Table 2-1.
Table 2-1 WebSphere Service Registry and Repository usage APIs API Core Ontology Governance Scope Create, Retrieve, Update, Delete, Query Lookup of Ontology Classes and Systems (Read only) Make objects governable, transition them, find the transitions that can be made on the objects Exposed as EJB Yes Yes Yes Exposed as SOAP Web service Yes Yes No

74

WebSphere Service Registry and Repository Handbook

Both the EJB and SOAP APIs support publishing (creating and updating) service metadata artefacts and metadata associated with those artefacts, retrieving service metadata artefacts, deleting the artefacts and their metadata, and querying the content of WSRR through the Core API. Read-only manipulation of ontologies and classification systems is provided to EJB and SOAP clients through the Ontology API. Modification of ontology and classification systems must be performed using the Web interface. Governance operations are restricted to J2EE clients as the governance API is exposed only as an EJB at the time of writing. The EJB programming API uses Version 2 of Service Data Objects (SDO) to capture the data graphs inherent in the information model, allowing access to physical documents, logical parts of the physical documents, and GenericObjects. The SOAP API uses XML documents to similarly represent Service Data Objects to communicate content structures in both the physical and logical model. See 4.1, “Java API (EJB)” on page 120 and 4.2.3, “SOAP API” on page 139 for additional information. The governance API lets you analyze the impact of changes to specific artefacts. A set of predefined impact queries is available to help you navigate through the WSRR content according to popular patterns, such as which WSDL files import or use a specific XSD.

Administration API
WebSphere Service Registry and Repository also provides a JMX-based Administration API that supports basic configuration and loading and managing of metadata in support of repository content, such as classification and lifecycle management. The Administration API allows you to load definitions of state machines to be used to model the lifecycle of governed entities, and to load classification systems described in OWL. In addition, the Administration API supports registration of plugins for Validation functions or additional Notification providers. See 4.5, “Admin (JMX)” on page 155 for additional information.

Chapter 2. Concepts and architecture

75

2.2.4 Governance enablers
WSRR plays a key role in the end-to-end governance underpinnings of the SOA lifecycle. WSRR enables governance of service metadata by leveraging some built-in mechanisms: The definition and the enforcement of service lifecycle for governed objects The validation and notification of operations and events related to changes and evolution in the service lifecycle or service information model The definition, enforcement and accountability of security policies constraining the visibility of the service information model and the operations performed on it

Service lifecycle
WebSphere Service Registry and Repository provides support for the definition and the enforcement of a lifecycle which is applied to each governed entity. For each governed entity a state machine is defined that describes the lifecycle states the entity can take on, the transitions between those states, conditions for the transitions to be taken and actions to be taken should a transition be performed. While WSRR provides a set of out-of-the-box lifecycle models, you can define your own state machines to match with your requirements.

Validation
WSRR allows you to register validation functions that are run when basic CRUD operations are executed against its content, and also in the context of the governance model when lifecycle state transitions are operated on governed objects. Validation functions must not have side-effects and must return a Boolean result that can be used to veto the update. An example of validation scenarios could include WS-I compliance checking for services managed in WSRR.

Notification
WebSphere Service Registry and Repository provides basic event notification features to allow exploiters to register their interest in any changes to WSRR content. Initially notification will be based on JMS publication of events. These events identify the type of the change and contain a pointer to the object that was changed. WSRR ships a default notification handler that publishes change events on a JMS topic. The event specifies the type of event (create, update, delete or transform), the artefact impacted (identified via its URI) and a few more bits of information about the artefact. To avoid violating access control rules, the actual

76

WebSphere Service Registry and Repository Handbook

content of the artefact in question is not shipped with the event and must be retrieved separately. Examples of notification scenarios could include an e-mail notification feature that allows users to request an e-mail to be sent when an interesting event happens such as the publication or the revocation of services in the overall lifecycle.

Auditing
A simple Audit capability is provided that logs information about WSRR updates. See Chapter 5, “SOA governance enablers” on page 157 for additional information.

Chapter 2. Concepts and architecture

77

78

WebSphere Service Registry and Repository Handbook

3

Chapter 3.

Information model
This chapter describes the information (metadata) model used in WebSphere Service Registry and Repository (WSRR). It explains different types of service metadata stored in WSRR. Other documentation may refer to the WSRR information model as a “content model”. In this redbook, we use the term “information model”. The topics covered are: 3.2, “Service description entities” on page 80 3.3, “Service description metadata” on page 84 3.4, “Templates” on page 88 3.5, “Document types” on page 89 3.6, “XPath” on page 99 3.7, “Service Data Objects (SDO)” on page 99 3.8, “BaseObject” on page 101 3.9, “Query” on page 103

© Copyright IBM Corp. 2007. All rights reserved.

79

3.1 Introduction
The WebSphere Service Registry and Repository information model has elements representing service description entities (such as WSDL) and service description metadata (such as Classifications). All WSRR elements have a WSRR-assigned URI, a name and a description. Service description entities are artefacts and documents created and managed in WSRR, both physical and logical, and describe the service. For example WSDL, PortType. Service description metadata is used to decorate service description entities with attributes like Properties and Relationships with other elements. Figure 3-1 is an overview of the different types of metadata stored in WSRR.
Service Description Entities
Physical Documents
WSDL XSD SCDL WS-Policy XML – User-defined Documents …..

Service Description Metadata
Properties name namespace version description modifiedDate name namespace User-defined metrics Relationships imports includes predecessor User-defined Classifications
User-defined States Created Approved Published Operational User-defined Environments Development Test Approval Production User-defined GenericObjects Application Process Capability Standard Ontologies NAICS UNSPSC ISO3166

Logical derivations Interface Operation Message Type Service Binding Endpoint …..

Metadata applies to all entities

derivedFrom operations messages User-defined

GenericObjects User-defined by classification Business Application Business Process Governed Collection External reference User-defined owner externalURL User-defined dependantServices serviceInterface governedEntities policies …..

Figure 3-1 WebSphere Service Registry and Repository information model

3.2 Service description entities
There are three kinds of service description entities that are stored and managed in WSRR. 1. Physical documents

80

WebSphere Service Registry and Repository Handbook

Physical documents are XML documents that are known as service metadata artefacts. 2. Logical derivations Logical derivations are the finer-grained pieces of content that result when some types of physical documents are parsed as they are loaded into WSRR. 3. GenericObject GenericObjects are generic entities that are usually typed, and represent anything that is not represented by a document in WSRR. You can interact with all three types of service description entities, using them in queries, applying service annotations, and establishing relationships from and to them.

3.2.1 Physical documents
The most elemental building blocks for the WSRR information model are service metadata artefact documents (physical documents), such as XSD or WSDL files. These service metadata documents are stored and managed in WSRR. The coarse-grained model made up from registry objects that represent those documents is referred to as the physical model. Documents are versionable objects in WSRR information model, meaning that in addition to a URI, name and description they also have a version property. Any service metadata artefact type can be stored in WSRR and receive the benefits of broader visibility and reuse, management, and governance. WSRR offers advanced functions for a number of well-known SOA metadata types. The key WSRR metadata document types are: Web Services Description Language (WSDL) XML Schema Definition (XSD) WS-Policy Service Component Description Language (SCDL) For details on these document types, see 3.5, “Document types” on page 89. For these document types WSRR provides special services, including parsing of the documents upon receipt into Logical Derivations. See 3.2.2, “Logical derivations” on page 82. Other types of service metadata can be stored using a generic content type: XML Document; documents of type XMLDocument are not decomposed into the logical derivations.

Chapter 3. Information model

81

3.2.2 Logical derivations
WSRR offers advanced functions for a number of well-known SOA metadata types. These key metadata document types are: WSDL, XSD, WS-Policy, and SCDL. For these document types, WSRR provides special services, including parsing of the documents upon receipt into logical derivations or a set of logical objects. Logical objects are not versionable. Logical derivations or logical objects enable users to explore WSRR content beyond the boundaries of the files stored. Logical objects cannot be individually versioned since they are derived from a physical document (which can be versioned) and cannot therefore be individually manipulated. Logical objects may however have additional service description metadata allocated to them such as properties, relationships and classifications. For the key document types WSRR also defines a few predefined properties and makes an effort to detect relationships to other key documents, and where available, records those relationships in the information model. An XSDDocument, for example, has a targetNamespace property and the relationships importedXSDs, redefinedXSDs and includedXSDs. When an entry for a key-type document is created in WSRR, it is introspected for relationships to other key-type artefacts; if not already in represented in WSRR, these related artefacts are also added, and in either case the relationship between the artefacts is recorded. The set of logical derivations comprises the logical model of WSRR. The logical model has entities such as portType, port, and message related to WSDL files, and complexType or simpleType related to XSD documents. Elements of the logical model have properties and relationships reflecting a subset of their characteristics as defined in the underlying document. For example, a WSDLService element has a namespace property and a relationship to the ports it contains. It is important to note that all the individual results of document parsing are aggregated into one logical model that represents not only the content of individual documents, but also the relationships between the content in the different documents. WSRR stores other types of service metadata using the XMLDocument, a generic document type. Documents of type XMLDocument are not decomposed into the logical model. For more details, refer to section 3.5, “Document types” on page 89.

82

WebSphere Service Registry and Repository Handbook

3.2.3 GenericObject
There is one other kind of entity in WSRR, referred to as a GenericObject. This is a generic object that can be used to represent anything that does not have a physical document in WSRR. GenericObjects can be used to represent a reference to content in some other metadata repository such as a portlet in a portlet catalogue, an asset in an asset repository, service implementation artefacts kept in a source code library or information about SOA infrastructure topologies in a configuration management database. Note: GenericObject is the API name for the objects that appear in the Web UI as Concepts. Refer to 9.9, “Concepts” on page 370 for more information. A GenericObject can be used to group physical artefacts together for ease of retrieval. GenericObjects can be used to represent collections of documents or other GenericObjects. GenericObjects can also be used to represent a business-level view on the SOA metadata managed in WSRR; this could include GenericObjects such as Business Process, Business Service, Business Object and Business Policy. A GenericObject is simply a container for metadata, there are no constraints as to what it can be used to represent. This means that you must provide additional metadata such as classifications or templates to distinguish between different “types” of GenericObject and thus the properties and relationships that are appropriate. It is up to client applications to enforce the interpretation of these “types”. WSRR provides support through templates and validator plug-ins to allow you to extend WSRR to perform this. GenericObjects provide the following predefined properties: Name A mandatory name identifying the GenericObject. This must be unique across all objects in the repository when combined with the namespace and version properties. An optional namespace used to distinguish similarly named objects. An optional textual string that identifies different versions of the same name/namespace identified object. An optional textual description of the GenericObject.

Namespace Version Description

GenericObjects can be created, modified, used and deleted using the Web UI (see 9.9, “Concepts” on page 370) or the API (see Chapter 4, “Interfaces and APIs” on page 119).

Chapter 3. Information model

83

3.3 Service description metadata
In addition to content directly related to service description entities, WSRR supports a number of user-defined metadata types that are used to decorate the service description entities to explain their semantics; we refer to those metadata as Service description metadata. See Figure 3-1 on page 80. WSRR supports three types of service description metadata types: 1. Properties 2. Relationships 3. Classifications All three types can be used to decorate entities in the physical or logical model, and GenericObjects as well. For example, you would use service semantic metadata to: Associate a property businessValue with a physical model entity representing a WSDL file. Define a new relationship makesUseOf between an entity in the logical model representing a portType and an entity in the physical model representing an XML document. Create a classifier importantThings and associate it with a port entity in the logical model and with an entity in the physical model representing a Policy document. This enables semantic queries to target individual elements of the service metadata, and meaningful dependency analyzes to take place prior to making changes.

3.3.1 Properties
Properties are simple name/value pairs that are associated with any of the Service description entities. Some properties are assigned by the system, such as the unique id, the owner, and the last time the service entity was changed. These system-assigned properties cannot be changed. Others are derived through the parsing of a key-type service description document into its logical model. Properties of this type include name and namespace. Sometimes you are allowed to change these system-assigned values. You can also create your own properties. These are referred to as user-defined

84

WebSphere Service Registry and Repository Handbook

properties. You can use user-defined properties as a simple, unstructured and untyped extension mechanism. Note: User-defined properties are referred to as Custom Properties in the Web user interface. WSRR treats general properties and custom properties in the same way and all property values are treated as strings. Properties can be used in queries, and can be used to establish fine-grained access control. Properties can be created, modified, used and deleted using the Web UI (see 9.4, “Properties” on page 335) or the API (see Chapter 4, “Interfaces and APIs” on page 119).

3.3.2 Relationships
In a SOA environment, organizations expect to see reuse and loose flexible coupling between services. This means that it is essential to able to determine what services depend on what other services (or other service artefacts) at any time in the lifecycle of the business applications. Even at the IT level, services are described using standards-based documents such as WSDLs and XSDs which have dependencies between them. As business services progress through their lifecycles and evolve to meet market needs, the targets of these dependencies will change and it will be crucial to keep this information up to date. Any changes to services in the deployed environment may have an impact on other business applications. Changes in interface versions and compatibility will need to be tracked and the impact of any change evaluated. WebSphere Service Registry and Repository (WSRR) provides a means of defining these relationships and dependencies between objects as relationship metadata. WSRR defines and associates a number of built-in relationships that are defined against the classes of objects exposed in the WSRR information model. These are primarily associated with documents and imports and includes between them. These built-in relationships are often created automatically when a document is published and will therefore never be modifiable by a user. Relationships tie together one source service description entity to one or more target service description entities. Every relationship is given a name. A source is only allowed to have a single relationship with a given name. Some relationships are assigned by WSRR during the parsing of key types of documents. One example of a system-assigned relationship is the relationship

Chapter 3. Information model

85

established between XSD documents based on the importing of one into the other. WSRR also allows custom relationships. For example, you can: Relate a GenericObject that represents an external object to a service using a user defined relationship. Relate all of the service description documents that will be governed as a unit to a governable entity. Relate a monitoring policy to a service endpoint. These can be added or deleted from any object on an instance by instance basis. For custom relationships both the name and target objects can be defined by the user. WSRR treats built-in relationships and custom relationships in similar ways for the purposes of manipulation and query. Relationships can be created, modified, used and deleted using the Web UI (see 9.5, “Relationships” on page 347) or the API (see Chapter 4, “Interfaces and APIs” on page 119).

3.3.3 Classifications
WebSphere Service Registry and Repository (WSRR) provides a means of classifying service artefact descriptions represented in WSRR. This allows you to organize your services by allocating classifications from a set of predefined classification systems. Each classification system represents a different way of organizing services and is represented as a hierarchy of classifications similar to a library indexing system. WSRR supports any number of classification systems that can be predefined to organize your service artefacts in the best way. You can load classification systems into WSRR where they can then be used to apply semantic meaning to Service description entities. Classification systems are documents encoded using the Web Ontology Language (OWL). While any valid OWL document can be used as a Classifier system, at present WSRR exploits only a small subset of the expressiveness of OWL. WSRR represents OWL Classes as classifiers and interprets the subTypeOf relationship between those Classes as establishing a classifier hierarchy. Other OWL concepts such as data or relationships representing properties or other built-in OWL relationships are ignored.

86

WebSphere Service Registry and Repository Handbook

A classifier system is imported into WSRR as a whole and cannot be modified via WSRR functions; updates are done by importing a modified version of the ontology. Any Class in the underlying ontology can be used as a classifier; the same classifier can be used to classify multiple entities and an entity can be associated with multiple classifiers.

Ontologies
An ontology is a vocabulary used to describe some domain. This includes describing the entities in the domain, and their relationships. See the definition of an ontology following “Classifications” on page 69.

Web Ontology Language
The Web Ontology Language (OWL) is a W3C endorsed format that can be used to define an ontology. See the definition of an ontology following “Classifications” on page 69. It can define relatively rich semantics including relations between classes of entities (for example disjointedness), cardinality (for example “exactly one”), equality, properties, characteristics of properties (for example symmetry), and enumerated classes. WSRR does not provide any facilities for editing or composing a new OWL file. It is expected that external tools will be used to produce an OWL file, and the resulting file is then loaded into WSRR by an Administrator. For more details about OWL, visit: http://www.w3.org/2004/OWL/

Taxonomies
At a more simplistic level, OWL can also describe taxonomies. A taxonomy is a system of hierarchical types which can be used to describe entities. The types are expressed in a class and subclass system. So for example, a simple taxonomy could consist of a class called “Transport” which could have subclasses “Air Transport” and “Land Transport”. Then, “Land Transport” could in turn have subclasses “Bus” and “Car”. This hierarchy means that a “Car” is a type of “Land Transport”, and is also a type of “Transport”.

3.3.4 Classifications in WSRR
WSRR is able to load and understand OWL files, but currently does not exploit all the features of the OWL language. Instead, the taxonomy part of the OWL file is made available to “classify” artefacts in WSRR. Within the WSRR Web UI each taxonomy is referred to as a “classification system”, and the classes within the taxonomy are referred to as “classifications” or “classification classes”.

Chapter 3. Information model

87

Classification classes are used to organize and find artefacts in WSRR. Any artefact may be tagged or “classified” with multiple classification classes. For example an organizational classification system may be produced, with a class “Europe”, which has a subclass “UK”, which in turn has a subclass “London office” (and there could be many other classes for other regions, countries and groups). In addition simple lifecycle classification system could be produced with classes such as “Development”, “Production”, “Obsolete” and so on. An artefact in WSRR could then be classified with any number or combination of these classes. Although the English language meaning of some of these classes suggests that some of them are mutually exclusive, there is no enforcement of such semantics; all classes are equal and any can be applied to any artefact. One possibility is that a WSDL portType, say, is classified with the “London office” and “Production” classes. This artefact would then be returned in a search for all artefacts that had both these classifications applied, that is a search for all artefacts produced by the London office that were in the production state. It would also be returned for a search for all artefacts produced in the UK that were in production. Classifications can be used from the Web UI (see 9.6, “Classifying objects” on page 358) or the API (see Chapter 4, “Interfaces and APIs” on page 119).

3.4 Templates
As discussed previously, user-defined properties and relationships can be used to customize the set of predefined properties and relationships provided in the WSRR meta-model. Users can add properties to a WSDLDocument or they can configure a GenericObject with properties and relationships to represent its structure. To simplify the process of customizing WSRR entities, a simple template mechanism is provided. It allows you to create an XML schema that captures the definition of properties and relationships associated with a GenericObject entity of a particular type. You can then associate the template with the entity type. All interactions with entities of that type will then be “patterned” to match the template, designating the properties and relationships that are relevant when interacting with that kind of entity. Template allows user-defined properties and relationship names to be applied consistently to GenericObjects created within WSRR. These templates are

88

WebSphere Service Registry and Repository Handbook

defined as simple XSD complex types with attributes being used to represent the property and relationship names expected for entities created from the templates. Templates may therefore be used to represent metadata that describes objects in the business domain, such as business services. Templates can be used to model sets of metadata, which may then be applied to any GenericObjects that are created in WSRR, thus allowing many different metadata models to be represented. Note: WSRR provides no other metadata modelling tools, so the use of templates is the only way to achieve this. The template model does not include type-checking or any other modelling-based validation, so you should ensure that the templates are correct when you create them. For more details on configuration of Templates, see 9.9.1, “Defining a concept template” on page 371.

3.5 Document types
WSRR manages services by representing them in the registry and associating metadata with them that describes the role of the service in the SOA environment together with its relationship to other artefacts on which it depends. By managing this service metadata, WSRR can provide the single copy of record for service descriptions and thus allow organizations to manage their services. As described previously, WSRR offers advanced functions for a number of well-known SOA metadata types. These key WSRR metadata document types are: Web Services Description Language (WSDL) XML Schema Definition (XSD) WS-Policy Service Component Description Language (SCDL) The menu hierarchy for service documents can be seen in Figure 3-2 on page 90.

Chapter 3. Information model

89

Figure 3-2 Service Documents

See Figure 3-3 for document objects.

Figure 3-3 Document objects

For these document types, WSRR provides special services, including parsing of the documents upon receipt into logical derivations or a set of logical objects.

90

WebSphere Service Registry and Repository Handbook

Figure 3-4 Service metadata

3.5.1 XML Schema Definition (XSD)
WebSphere Service Registry and Repository provides a single copy of record for all service metadata. In a SOA environment the services exchange information in Extensible Markup Language (XML) formats. To achieve interoperability, different services have to agree on the schemas for this information exchange. The industry standard for defining the XML schema is XSD (XML Schema Definition). In an SOA environment there are many important artefacts that use XML schemas to define the service implementation. Some of these are described here. Business objects - Businesses often adopt standardized representations of information that is key to their business. Some of these are standardized across individual companies to support particular market sectors. Business messages - Message driven architectures rely primarily on XML schema definitions to define the formats that are used to exchange information. Business Events - As with messages, event structures are often defined in XML schemas to assist in reporting and systems management. Service operation signatures - Even when services are described using WSDL, the parameters of the service operations are often expressed using XML

Chapter 3. Information model

91

schemas expressed in XSD documents. This allows different services to share a common information model. WSRR provides the capability to register XSD documents and to identify the important XML Schema constructs within those documents that will affect the interoperability or common dependencies between services being managed. For each XSD document WSRR identifies: Global complex types - These identify the actual types used in interface and message definitions. WSRR only identifies the name and namespace of the complex type from the XSD, it does not maintain finer grain structure. Global simple types - These identify the actual types used in interface and message definitions. WSRR only identifies the name and namespace of the type from the XSD. Global elements - These identify elements that have global visibility and may thus be used in interface and message definitions. WSRR only identifies the name and namespace of the element from the XSD. Global attributes - These identify attributes that have global visibility and may thus be used in interface and message definitions. WSRR only identifies the name and namespace of the attribute from the XSD. Each of these constructs results in an object that is stored in the registry and related to the schema document that declared it. These “derived” or “logical” objects cannot be created or deleted by the user, they are managed entirely by the registering or de-registering of the XSD document that defines them. There is a special extension of global complex types that is used to support templates. WSRR interprets certain local attributes and these can be used when creating GenericObjects from templates as follows. Local attributes that are declared of type xsd:string are treated as WSRR properties in GenericObjects created from the template. Local attributes that are declared of type xsd:IDREF are treated as WSRR relationships in GenericObjects created from the template. The only information available for these local attributes is the name. The objective for all these “derived” objects is to allow the named construct to be annotated with metadata to indicate how it should be used across the SOA enterprise. This allows a particular construct declared within a document to be managed differently from other constructs declared within the same document. This has the implication that if any document is deleted or even updated (in terms

92

WebSphere Service Registry and Repository Handbook

of content), any derived objects will be deleted and the attached metadata will be lost. In addition to this parsing of XSD documents, WSRR automatically detects and maintains dependencies between documents. At the time of loading or creation, of the dependent document, the documents that it depends on must be: Already available within WSRR. Special handling of this is required since xsd:include, xsd:import, xsd:redefine statements do not include enough information to resolve between different versions of the same schema (same name, location and namespace). Provided with the dependent document as part of the load. In this case the document that is depended on will also be loaded and parsed. Available from the uri given in the import or include location hint. In this case the document that is depended on will also be loaded and parsed. For each of these dependencies encountered and resolved, WSRR will ensure that a built-in relationship is established between the dependent document and the depended on document. See Figure 3-5 for XSD logical objects.

Figure 3-5 XSD logical objects

XSD Documents can be managed in WSRR using Web UI (see Chapter 9, “Getting started with WSRR” on page 327), Eclipse plug-in (see Chapter 11, “Using the WSRR Eclipse plug-in” on page 415) and APIs (see Chapter 4, “Interfaces and APIs” on page 119).

Chapter 3. Information model

93

3.5.2 Web Services Description Language service definitions
WebSphere Service Registry and Repository aims to provide a single copy of record for all service definitions in a SOA environment. In SOA the loose coupling between services means that organizations have the flexibility to change which services depend on which other services. Before any change can occur there needs to be confidence that the consumer service is compatible with the provider. Thus all deployed or about to be deployed services need to have a clear service definition that can be published for consumers to discover. The industry standard for Web service definitions is Web Services Description Language (WSDL). Web service definitions are often provided at three levels, all of which use WSDL to describe them. Service interface definitions - Describe the interfaces in terms of operations and signatures provided by a service. These will often reference XML schemas to define common message formats or operation parameters. Service binding definitions - Describe how the interfaces are represented in the infrastructure and over the wire. This defines the transport protocols that are supported such as SOAP, JMS, and so on. This references the service Interface definition to indicate exactly which operations are actually supported over this transport protocol. Service endpoint definitions - Describe each individual deployed service and describe how a consumer would actually find and connect to a service. They define the endpoints and indicate which bindings and thus interfaces are supported on each endpoint. It is good practice to make sure that each of these three levels of service definition are defined in different WSDL documents. This is not enforced by WSRR but the split of definitions across multiple documents is supported. WSRR provides the capability to register WSDL documents and to identify the important WSDL constructs within those documents that will affect the interoperability or common dependencies between services being managed. For each WSDL document WSRR identifies: Port Types - These identify the service interfaces defined in the document including the operations and their signatures. These will often reference XML schema constructs to define operation parameters.

94

WebSphere Service Registry and Repository Handbook

Bindings - These identify the bindings defined in the document including the soap binding and the portType supported. Services - These identify the service, ports, soap address and the bindings to which they relate. Each of these constructs results in a related collection of objects that are stored in the registry and related to the WSDL document that defined them. These “derived” or “logical” objects cannot be created or deleted by the user, they are managed entirely by the loading or deleting of the WSDL document that defines them. This has the implication that if any document is deleted or updated (in terms of content), any derived objects will be deleted and the attached metadata will be lost. The objective for all these derived objects is to allow the named construct to be annotated with metadata to indicate how it should be used across the SOA enterprise. This allows a particular construct declared within a document to be managed differently from other constructs declared within the same document. For example, different policies might be attached to different operations of a service interface even though all the operations are defined in the same WSDL document. See Figure 3-6 for WSDL logical objects.

Figure 3-6 WSDL logical objects

Chapter 3. Information model

95

In addition to this parsing of WSDL documents, WSRR automatically detects and maintains dependencies between documents. At the time of loading or creation, of the dependent document, the documents that it depends on must be: Already available within WSRR. Special handling of this is required since an xsd:include, xsd:import, wsdl:import statements do not include enough information to resolve between different versions of the same document (same name, location and namespace). Provided with the dependent document as part of the create. In this case the document that is depended on will also be loaded and parsed. Available from the URI given in the import or include location hint. In this case the document that is depended on will also be loaded and parsed. For each of these dependencies encountered and resolved, WSRR will ensure that a built-in relationship is established between the dependent document and the depended on document. WSDL Documents can be managed in WSRR using Web UI (see Chapter 9, “Getting started with WSRR” on page 327), Eclipse plug-in (see Chapter 11, “Using the WSRR Eclipse plug-in” on page 415) and APIs (see Chapter 4, “Interfaces and APIs” on page 119).

3.5.3 Service Component Architecture (SCA) modules
WebSphere Service Registry and Repository provides support for conventional service and schema definitions through the use of WSDL and XSD documents. However, these document standards are not enough to describe the dependencies between services that are necessary to support service-oriented architectures (SOA). SOA offers the ability to assemble components from existing services either at development time or at runtime. The emerging standard that will allow these assemblies to be described is the Service Component Architecture (SCA). SCA modules are components that can be deployed into an SCA environment and represent processes or other compound services. Modules are assembled from development time components into a single deployable artefact but these modules can still be related to (depend on) other external deployed services. SCA provides a number of important constructs that are defined as part of an SCA module deployment description. SCA libraries - each library provides a number of XSD and WSDL documents that describe the services artefacts that are being reused or referenced within the module.

96

WebSphere Service Registry and Repository Handbook

SCA module file - this provides the definition of the module in terms of the internal components used within the module. WSRR does not interpret the internal content information but does identify any externalized dependencies as imports and exports. SCA imports - these provide the definitions of the external services that the module depends on. These import files define the interfaces, bindings and endpoints that the module will need to resolve when it is deployed. SCA exports - these provide the endpoint descriptions that the module exposes in terms of interfaces, bindings and endpoints. For more details on SCA import export bindings, see 14.3.2, “Mediation modules” on page 516. One of the advantages of SCA over WSDL is that it allows a wider range of bindings to be expressed. Thus, SCA modules can work with JMS and other message based paradigms as well as the Web services that WSDL supports. See Figure 3-7 for SCA logical objects.

Figure 3-7 SCA logical objects

SCA Documents can be managed in WSRR using Web UI (see Chapter 9, “Getting started with WSRR” on page 327) and APIs (see Chapter 4, “Interfaces and APIs” on page 119).

Chapter 3. Information model

97

3.5.4 XML metadata files
WebSphere Service Registry and Repository aims to provide a single copy of record for all service metadata. Many SOA artefacts can be described by well known standards such as XSD and WSDL. Many customers will however have their own service descriptions that are stored in some other XML format. Examples of this can be business rules, business policies, Business Process Execution Language (BPEL) files, and so on. WSRR provides a means of storing these XML documents and thus relating them to the other service artefacts in the registry. WSRR will not interpret the content of the XML document so there will be no derived objects created. XML metadata files can be managed in WSRR using Web UI (see Chapter 9, “Getting started with WSRR” on page 327), Eclipse plug-in (see Chapter 11, “Using the WSRR Eclipse plug-in” on page 415) and APIs (see Chapter 4, “Interfaces and APIs” on page 119).

3.5.5 Service Policy (WS-Policy)
One of the key goals of SOA is to provide policy driven interactions between services. This results in business agility and faster time to value since behavior can be changed simply by modifying the applicable policies. However the policies themselves then need to be managed as closely as the service implementations in order to maintain a compliant solution. WebSphere Service Registry and Repository (WSRR) aims to provide a copy of record for all policy documents. Using the metadata facilities within WSRR, these policies can be related to the service artefacts to which they apply. WSRR provides a very basic interpretation of the content of the WS-Policy documents so there will be no derived objects created to which metadata can be applied. It is therefore up to the client applications to interpret and enforce any policies that are deemed applicable by the metadata contained within WSRR. Policy documents can be managed in WSRR using Web UI (see Chapter 9, “Getting started with WSRR” on page 327) and APIs (see Chapter 4, “Interfaces and APIs” on page 119).

98

WebSphere Service Registry and Repository Handbook

3.6 XPath
The XML Path Language (XPath) is a set of syntax and semantics for referring to portions of XML documents. XPath models an XML document as a tree of nodes, and provides the ability to navigate around the tree, selecting nodes by a variety of criteria.There are different types of nodes, including element nodes, attribute nodes and text nodes. Some types of nodes also have names. XPath uses expressions to identify a set of nodes in an XML document. This set of nodes can contain zero or more nodes. XPath expressions can refer to attributes as well as elements in an XML document. When referring to an attribute, the @ character is used. For example, the following XPath expression identifies currentPrice elements whose currency attributes contain the value EUR: /list/item/currentPrice[@currency="EUR"] XPath includes built-in functions for string values, numeric values, date and time comparison, node and QName manipulation, sequence manipulation, Boolean values, and more. XPath is intended to be used by other specifications such as Extensible Stylesheet Language Transformations (XSLT) and the XML Pointer Language (XPointer). For more details on XPath, visit the following Web sites: http://www.w3.org/TR/xpath http://www.ibm.com/developerworks/edu/x-dw-xxpath-i.html

3.7 Service Data Objects (SDO)
In WSRR programming model, all elements (documents, logical models, user-defined metadata, generic objects queries) are represented as SDO. Service Data Objects (SDO) are designed to simplify and unify the way in which applications handle data. Using SDO, application programmers can uniformly access and manipulate data from heterogeneous data sources, including relational databases, XML data sources, Web services, and enterprise information systems.

Chapter 3. Information model

99

SDO is based on the concept of disconnected data graphs. A data graph is a collection of tree-structured or graph-structured data objects. Under the disconnected data graphs architecture, a client retrieves a data graph from a data source, mutates the data graph, and can then apply the data graph changes back to the data source. The task of connecting applications to data sources is performed by data mediator services. Client applications query a data mediator service and get a data graph in response. Client applications send an updated data graph to a data mediator service to have the updates applied to the original data source. This architecture allows applications to deal principally with data graphs and data objects. SDO enables both a static (or strongly typed) programming model and a dynamic (or loosely typed) programming model. This enables a simple programming model without sacrificing the dynamic model needed by tools and frameworks. SDO also provides a metadata API, which allows applications, tools, and frameworks to introspect the data model for a data graph. The SDO metadata API unifies data-source-specific metadata APIs to enable applications to handle data from heterogeneous data sources in a uniform way. SDO is intended to be language-neutral and to be available in a range of programming languages.

3.7.1 Data objects
Data objects are the fundamental components of SDO. In fact, they are the service data objects found in the name of the specification itself. Data objects are the SDO representation of structured data. Data objects are generic and provide a common view of structured data. Data objects are linked together and contained in data graphs.

3.7.2 Data graphs
Data graphs provide a container for a tree of data objects. SDO clients can traverse a data graph and read and modify its data objects. SDO is a disconnected architecture because SDO clients are disconnected from the data source; they only see the data graph. Furthermore, a data graph can include objects representing data from different data sources. A data graph contains a root data object, all of the root's associated data objects, and a change summary (See Figure 3-8 on page 101). When being transmitted between application components (for example, between a Web service requester and provider during service invocation), or saved to disk, data graphs are serialized to XML. The SDO specification provides the XML Schema of this serialization.

100

WebSphere Service Registry and Repository Handbook

Figure 3-8 Data graph

For an introduction to SDO, see: http://www.ibm.com/developerworks/java/library/j-sdo/ For more information about the goals and architecture of SDO, see the following Web site: http://www.ibm.com/developerworks/library/specification/ws-sdo/

3.8 BaseObject
BaseObject is the root WSRR type. All elements in WSRR are inherited from BaseObject. It defines common attributes and relationships.
Example 3-1 BaseObject

Chapter 3. Information model

101

 See Figure 3-9 on page 103 for the BaseObject model.

102

WebSphere Service Registry and Repository Handbook

Figure 3-9 BaseObject model

3.9 Query
Once registered, services must be available for reuse and management for them to be any use. WSRR implements a subset of XPath 2.0 with some extensions to provide a simple yet powerful search and query mechanism.

Chapter 3. Information model

103

WSRR allows querying against a virtual XML document rooted at /WSRR. This document contains every SDO object held in WSRR. The child elements of the /WSRR root are named after top-level SDO types, each element instance representing an object. A simple example of a query expression is: /[] Where, is the path to the required SDO along the containment hierarchy of the information model. For example to search for WSDLDocument SDOs the is /WSRR/WSDLDocument, for WSDLPort SDOs the is /WSRR/WSDLService/ports. Elements of types which are not top-level are named after the containing relation. For example, /WSRR/WSDLService/ports. SDO attributes are modelled as XML attributes on those elements. For clarity, the word 'association' is used to mean 'non-containment relationship'. A 'relationship' can be through association or containment. An element is said to be contained by another if it is accessed at a lower point in the XML hierarchy. An element is said to be associated to another if the former is related to the latter but the latter is not contained by the former. That is, association is used in a more specific sense than in UML, to mean non-containment relationships in particular.

bsrURI attribute
A bsrURI attribute of XSD type xs:ID is assigned to every SDO object which is unique to it within WSRR. These bsrURIs are used to implement associations internally and so can be safely used to reconstruct relationships between objects obtained by one or more queries. This is safer than using the original ids because bsrURIs are WSRR-unique, rather than document-unique. Do not use bsrURIs directly to navigate associations. For each association a function has been provided which takes the current context as its only argument. This function replaces the current context node with that of the associated element.

3.9.1 Types of query
There are two types of queries: PropertyQuery and GraphQuery.

104

WebSphere Service Registry and Repository Handbook

PropertyQuery
A PropertyQuery is used when only some attributes of objects that match the query expression are to be returned. In this case, the result of the query is a collection of QueryResult objects, each of which has the appropriate user-defined properties set to the values of the chosen attributes of a matching object.

GraphQuery
A GraphQuery is used when a complete datagraph is to be returned for each object that matches the query expression. The default is to return all the objects related to the matched object, but an attribute on the GraphQuery can control the depth of the returned graph. A depth parameter can be specified on the GraphQuery object that allows you to specify the depth of relationships that are resolved in the object graph that is returned. Specifying a depth parameter of -1 means that a complete object graph is returned. For example, if a query with depth parameter of -1 returns a single WSDLService element, you can then programmatically follow all the relationships (both predefined and user-defined) from the root WSDLService object that is returned from the query. Specifying a depth parameter of 0 implies that only the objects that have been queried for are returned and so you can access all the properties for a given object, but cannot access any related object programmatically without executing an additional query. For example, if a WSDLService is returned, the default behavior will be to return the WSDLService instance itself, all of the WSDLPort objects contained by the WSDLService, the WSDLBindings associated with each WSDLPort and so on. If the depth attribute were set to 2, then only the WSDLService, the WSDLPort objects and the WSDLBinding objects would be returned. The leaf objects have empty values for modelled relationships and do not have any user-defined relationships.

3.9.2 Searching and querying
The following sections provide examples of queries.

Simple queries
This section explains how to write basic XPath queries.

Chapter 3. Information model

105

Queries are built up from expressions separated by forward slashes '/'. Here is a graph query which returns all WSDLServices: /WSRR/WSDLService Note that the singular form is used. The Relationship map (See “Relationship map” on page 111) in the has the correct forms of all relations. Adding further expressions delves deeper, finding objects which are either contained by or associated with the preceding elements. For example, this graph query will return all WSDLPorts contained by any WSDLService. /WSRR/WSDLService/ports To traverse an association rather than a containment relationship, append '(.)'. All user-defined relationships are considered associations. /WSRR/WSDLBinding/portType(.) To retrieve an attribute (built-in or user-defined) from an element, use '@' in a property query: /WSRR/WSDLService/@name It will return the names of all the WSDLServices which exist, not the WSDLService objects themselves. If instead the intention was to find all WSDLServices called 'TickerService', the following graph query could be used: /WSRR/WSDLService[@name='TickerService'] Note: Graph queries end (ignoring predicates) in a relationship name, like WSDLService or binding(.). Property queries end in an attribute name, like @name. Use the appropriate API code for each.

Predicates
This section explains how to filter your results. The previous example showed the use of a simple predicate to filter the objects returned. Predicates can be used at any stage, and more than once in the query. /WSRR/WSDLService[@name='Catalogue']/ports[@name='search'] Predicates can be logically combined using 'and' and 'or'. The 'or' operator has a higher precedence in XPath than it does in SQL, so using parentheses to group complex expressions is recommended to avoid unexpected results. /WSRR/WSDLService[@name='TickerService' and @version!='1.2']/ports /WSRR/WSDLService[@name='Catalogue' or @name='Library']

106

WebSphere Service Registry and Repository Handbook

Predicates can be more complex than just an attribute accessor. They can be any valid XPath expression which evaluates to a Boolean. Query 1 below returns WSDLService objects, whereas query 2 returns WSDLPorts: 1. /WSRR/WSDLService[ports/@name='incoming'] 2. /WSRR/WSDLService/ports[@name='incoming'] By putting the two together, complex filters can be created like this: /WSRR/WSDLService[ports/@name='incoming' and ports/@name='outgoing'] The above query demonstrates that different objects may be used to fulfil each sub-expression of the predicate. It could be translated as “give me all the WSDLServices which have a port named 'incoming' and also have a port named 'outgoing'”. To express “give me all the WSDLServices which have a port named 'incoming' that is also described as 'open'”, use nested predicates. This forces a single port to match both conditions: /WSRR/WSDLService[ports[@name='incoming' and @description='open']] The matches() function allows you to use '.*' within your queries to mean 'any sequence of characters'. For example, these queries find WSDLServices whose names contain IBM at the beginning, end and in the middle respectively. No other elements of regular expressions syntax are allowed. /WSRR/WSDLService[matches(@name, 'IBM.*')] /WSRR/WSDLService[matches(@name, '.*IBM')] /WSRR/WSDLService[matches(@name, '.*IBM.*')] The existence of a user-defined property or relationship can be queried like so: /WSRR/WSDLService[@MyProperty] /WSRR/WSDLService[MyRelationship(.)] Note: Comparisons can be made, but all values are treated as strings. This means that '2' is considered to be greater than '10'. Avoid queries like this: # DO NOT DO THIS! /WSRR/WSDLService[@version > '10']

Shortcuts and wildcards
This section explains how to use the double-slash and star operators. The following graph query will return all WSRR objects named 'Ticker'. //*[@name='Ticker']

Chapter 3. Information model

107

A star can also be used to mean any attribute. This will include both built-in and user-defined attributes. /WSRR/WSDLService[@*='StockQuote'] These are the only supported uses of the double-slash and star operators. The WSRR-provided function, anyUserDefinedRelationship(.), acts like a star for user-defined relationships. This function can be used within a predicate as well, to find objects which have user-defined relationships: /WSRR/WSDLService/anyUserDefinedRelationship(.) /WSRR/WSDLService[anyUserDefinedRelationship(.)]

Classification functions
WSRR provides a number of additional XPath functions to assist querying using classifications. Some of the important functions are classifiedByAnyOf, which returns true if an object is classified with any of the URIs specified as arguments to the function. classifiedByAllOf, which returns true if an object is classified by all of the URIs specified as arguments to the function. Note that these functions all take a single dot '.' as their first argument. The examples use the following ontology (words are used instead of proper URIs for clarity): class color – class red – class green class shape – class round – class tall This ontology is used to classify the following WSDLServices: 1. name="Apple" classifications=["red", "round"] 2. name="Lime" classifications=["green", "round"] 3. name="Tree" classifications=["green", "tall"] The following function: classifiedByAnyOf(., 'owlURI1', 'owlURI2', ...)

108

WebSphere Service Registry and Repository Handbook

It returns all objects classified by at least one of the given owlURIs or their subtypes. So in our example, query: /WSRR/WSDLService/classifiedByAnyOf(., 'shape') It will return all three WSDLServices. The following query: /WSRR/WSDLService/classifiedByAnyOf(., 'red', 'round') It will return the Apple and Lime WSDLServices. The following query: /WSRR/WSDLService/classifiedByAnyOf(., 'green', 'tall') It will return the Lime and Tree WSDLServices. The following function: classifiedByAllOf(., 'owlURI1', 'owlURI2', ...) It returns all objects classified by all of the given owlURIs or their subtypes. So in our example, the following query: /WSRR/WSDLService/classifiedByAllOf(., 'shape') It will return all three WSDLServices. The following query: /WSRR/WSDLService/classifiedByAllOf(., 'red', 'round') It will return the Apple WSDLService. The following query: /WSRR/WSDLService/classifiedByAllOf(., 'green', 'tall') It will return the Tree WSDLService. Following function: exactlyClassifiedByAnyOf(., 'owlURI1', 'owlURI2', ...) It returns all objects classified by at least one of the given owlURIs. Subtypes are not considered. So in our example, the following query: /WSRR/WSDLService/exactlyClassifiedByAnyOf(., 'shape') It will return none of the WSDLServices. The following query: /WSRR/WSDLService/exactlyClassifiedByAnyOf(., 'red', 'round') It will return the Apple and Lime WSDLService. The following query: /WSRR/WSDLService/exactlyClassifiedByAnyOf(., 'green', 'shape') It will return the Lime and Tree WSDLServices.

Chapter 3. Information model

109

The following function: exactlyClassifiedByAllOf(., 'owlURI1', 'owlURI2', ...) It returns all objects classified by all of the given owlURIs. Subtypes are not considered. So in our example, the following query: /WSRR/WSDLService/exactlyClassifiedByAllOf(., 'shape') It will return none of the WSDLServices. The following query: /WSRR/WSDLService/exactlyClassifiedByAllOf(., 'red', 'round') It will return the Apple WSDLService. The following query: /WSRR/WSDLService/exactlyClassifiedByAllOf(., 'green', 'shape') It will return none of the WSDLServices.

Treat as
There are two points in the model where the query system needs some help to know what the type of the elements are. Consider this query: /WSRR/Module/exports You know that for the Module you are interested in, the exports are SCAWSDLPortTypes. As far as the query engine is concerned though, they are of the supertype LogicalObject. To access properties or relationships defined on the subtype, you must introduce a downcast, expressed in XPath with 'treat as': /WSRR/Module/exports/(interfaces treat as element(interfaces,SCAWSDLPortType))/WSDLPortType(.) /WSRR/Module/exports/(interfaces treat as element(interfaces,SCAWSDLPortType))[WSDLPortType(.)[@name='pt']] /WSRR/Module/exports/(exportBinding treat as element(exportBinding,SCAExportBinding))[@name='eb' and @namespace='ens'] Note: The parentheses around the treat as expression are required. The following types all descend from concrete supertypes and must be cast using 'treat as' to access the relations and properties they define: JMSImportBinding JMSExportBinding SCAImportBinding

110

WebSphere Service Registry and Repository Handbook

SCAExportBinding SLSBImportBinding WebServiceImportBinding WebServiceExportBinding SimpleTypeDefinition ComplexTypeDefinition SCAWSDLPortType

Relationship map
This relationship map describes the WSRR object hierarchy and can be used to assist in building XPath queries. The map employs the following conventions: Relations are given as their simple names. Attributes are prefixed with @. Containment is represented with indentation. X < Y means type X inherits from Y. X → Y means relation X leads to objects of type Y. X is a Y means object X is of type Y, which has subclasses. The map is in three parts: Concrete types - Concrete types are those WSRR types which are directly accessible from an XPath query. Use this map to begin building an XPath query. Supertypes - Supertypes cannot be accessed directly in an XPath query. However, concrete types either inherit from supertypes or have an object type of one of the supertypes. Therefore, supertype attributes and subtypes may appear in an XPath query. XSD files - XSD files containing the XML schema definitions for all the WSRR types.

Concrete types
Concrete types are those WSRR types which are directly accessible from an XPath query. Use this map to begin building an XPath query. To build an XPath query, begin at /WSRR and traverse through the object hierarchy, appending subtypes, separated by “/”, at each stage and incorporating attributes as required. Where a type A inherits from a type B (indicated by “ WSDLDocument /XSDDocuments(.) -> XSDDocument /exportDocuments(.) -> ExportDocument /importDocuments(.) -> ImportDocument /moduleDocument(.) -> ModuleDocument /SimpleTypeDefinition < XSDType /Subscription < BaseObject @emailAddress @locale @subscribedOperations @subscribedTransitions @targetBsrUri @targetClassifications @targetName @targetNamespace @targetVersion /WSDLBinding < LogicalObject /SOAPBinding < LogicalObject @style @transport /portType(.) -> WSDLPortType /WSDLDocument < Document /importedWSDLs(.) -> WSDLDocument /importedXSDs(.) -> XSDDocument /includedXSDs(.) -> XSDDocument /redefinedXSDs(.) -> XSDDocument /WSDLMessage < LogicalObject /messageParts is a WSDLPart /xsdElement(.) -> ElementDeclaration /xsdType(.) -> XSDType /WSDLPortType < LogicalObject /operations is a WSDLOperation

Chapter 3. Information model

113

/faults(.) -> WSDLMessage /inputMessage(.) -> WSDLMessage /outputMessage(.) -> WSDLMessage /WSDLService < LogicalObject /ports is a WSDLPort /SOAPAddress < LogicalObject @location /binding(.) -> WSDLBinding /XMLDocument < Document /XSDDocument < Document /importedXSDs(.) -> XSDDocument /includedXSDs(.) -> XSDDocument /redefinedXSDs(.) -> XSDDocument

Supertypes
Supertypes cannot be accessed directly in an XPath query. However, concrete types either inherit from supertypes or have an object type of one of the supertypes. Therefore, supertype attributes and subtypes may appear in an XPath query. Note: The UserDefinedRelationship and UserDefinedProperty associations on BaseObject are unavailable. Use the name of the relationship and the dot function (.) to traverse these. The supertypes map is as follows:
Example 3-3 Supertype map

/BaseObject @bsrURI @description @lastModified @name @namespace @owner @version /Export < LogicalObject /exportBinding is an ExportBinding /interfaces is an Interface @preferredInteraction /ExportBinding < LogicalObject /Import < LogicalObject /importBinding is an ImportBinding /interfaces is an Interface

114

WebSphere Service Registry and Repository Handbook

@preferredInteraction /ImportBinding < LogicalObject /Interface < LogicalObject @preferredInteraction /JMSExportBinding < ExportBinding @dataBindingType /JMSImportBinding < ImportBinding @dataBindingType /JMSExportBinding(.) -> JMSExportBinding /LocalAttribute < LogicalObject @attributeType /LogicalObject < BaseObject /document(.) -> Document /OriginalObject < BaseObject /predecessors(.) -> OriginalObject /template(.) -> ComplexTypeDefinition /QueryObject < OriginalObject @queryExpression /SCAExportBinding < ExportBinding /SCAImportBinding < ImportBinding /scaExportBinding(.) -> SCAExportBinding /SCAWSDLPortType < Interface /WSDLPortType(.) -> WSDLPortType /SLSBImportBinding < ImportBinding @jndiName /SOAPAddress < LogicalObject @location /SOAPBinding < LogicalObject @style @transport /WSDLOperation < LogicalObject /faults(.) -> WSDLMessage /inputMessage(.) -> WSDLMessage /outputMessage(.) -> WSDLMessage /WSDLPart < LogicalObject /xsdElement(.) -> ElementDeclaration /xsdType(.) -> XSDType /WSDLPort < LogicalObject /SOAPAddress < LogicalObject @location /binding(.) -> WSDLBinding /WebServiceExportBinding < ExportBinding /WSDLPort(.) -> WSDLPort /WebServiceImportBinding < ImportBinding /WSDLPort(.) -> WSDLPort

Chapter 3. Information model

115

/XSDType < LogicalObject

XSD files
The XSD files containing the XML schema definitions for all the WSRR types are provided with the product. Go to \admin\schemas folder and see WSRRGovernanceSDO.xsd WSRRSDO.xsd. They provide additional information not available from the map, attribute types for example. However, many of the types defined in the XSD files are not accessible in an XPath query; the concrete types map should, therefore, always be used as the starting point for constructing a query.

3.9.3 More query examples
Following examples will help you understand the use of XPath to query elements from WSRR.

Query all instances of a type
To query all instances of a type, first establish the path to the required type in the information model. For example, WSDL documents are top level SDOs so the XPATH is: /WSRR/WSDLDocument WSDL PortTypes are contained in WSDL services through the relationship named “ports” so the XPATH is: /WSRR/WSDLService/ports To find all interface SDOs that are used within SCA modules, you need to do two queries. An SCA module contains SCA imports and SCA exports through the relationships named “imports” and “exports” and each of those can contain interface SDOs, so there are two XPATH expressions that return interface SDOs. One of them is: /WSRR/Module/imports/interfaces And the other is: /WSRR/Module/exports/interfaces

Query Instances of a Type with a particular property value
To add a condition to the query based on type, use the standard XPath predicate syntax.

116

WebSphere Service Registry and Repository Handbook

For example, to search for all WSDLService instances named “StockQuoteService” use a query string of: /WSRR/WSDLService[@name='StockQuoteService']

Query based on a condition on a referrer
It is possible to have a relationship after the predicate(s) when the type of objects returned are related to another object against which a predicate is expressed. For example, to query for all portTypes referred to from bindings referred to from ports of all services named "StockQuoteService" use /WSRR/WSDLService[@name='StockQuoteService']/ports/binding(.)/portTy pe(.) Note that WSDL ports do not contain WSDL bindings but rather have a relationship with them. As a result the function binding(.) needs to be invoked. Because WSDL port types are contained in WSDL bindings, the next step is simply the name of this containment relationship, that is portType.

Query based on a condition on a referent
It is possible to have a condition on a property of an object reached through a relationship. For example, to return all WSDLServices that have a port that refers to a binding that refers to a portType named “StockQuotePortType” use /WSRR/WSDLService[ports/binding(.)/portType(.)/@name='StockQuotePort Type']

Testing property existence
To query for all objects that have a property named “foo” defined, regardless of value, use the following query expression: //*[@foo] The //* looks for all objects, regardless of where they are in the hierarchy of the information model.

Testing relationship existence
To query for all objects that have a relationship named “MyRelationship” defined, use the following query expression: //*[MyRelationship(.)]

Chapter 3. Information model

117

3.9.4 Limitations
Note that not every possible XPATH expression is supported. Listed here are some of the limitations of WSRR queries: Predicates filtering //* may only access attributes defined on BaseDocument. The effective type of the target of a user-defined relationship is BaseObject. This limits the attributes and relationships available to further terms in the query. You cannot query based on the inheritance hierarchy of the SDOs. Multi-valued attributes are not supported. In general, multi-valued attributes have been replaced by elements with children. It is not possible to return the targets of relationships defined on extension types in the SCA model. For example, query i below will not work. Instead, run query 2 and access the WSDLPortType programmatically: a. /WSRR/Module/(imports treat as element(imports,SCAWSDLPortType))/WSDLPortType(.) b. /WSRR/Module/(imports treat as element(imports,SCAWSDLPortType)) The flexibility of user-defined relationships and inheritance can easily cause the underlying complexity of a query to expand exponentially. Therefore in WSRR V6.0, no more than two of the following can be included in any query, to guarantee it finishes before the timeout expires: – Traversals of relations defined by supertypes – Traversals of user-defined relationships – Access to user-defined properties

118

WebSphere Service Registry and Repository Handbook

4

Chapter 4.

Interfaces and APIs
WSRR has several different interfaces that provide different ways of accessing the product’s functionality. This chapter describes the following: 4.1, “Java API (EJB)” on page 120 4.2, “Web services API” on page 136 4.3, “Web user interface (Web UI)” on page 144 4.4, “Command Line Interface” on page 154 4.5, “Admin (JMX)” on page 155

© Copyright IBM Corp. 2007. All rights reserved.

119

4.1 Java API (EJB)
WebSphere Service Registry and Repository has a Java application programming interface (API) so that you can develop Java applications that access WSRR at run time to find the most appropriate Web service to use. During development, you can perform tasks such as creating documents in WSRR using the Web-based user interface (UI). If you are developing applications in an Eclipse environment, you can also use an Eclipse plug-in UI to perform tasks such as searching for and uploading services to WSRR. For more information about the Eclipse plug-in UI, see Chapter 11, “Using the WSRR Eclipse plug-in” on page 415. The WSRR API enables you to develop applications that can access WSRR at run time to find the most appropriate Web service to use. There are three aspects of the Java programming model: The representation of the content of WSRR. The support for creating, retrieving, updating, and deleting content in WSRR. The support for querying WSRR. The API is based on Service Data Objects (SDO) Version 2. All artefacts that are stored in WSRR are represented by SDO. The WSRR types have both data value properties and data object properties, which are referred to as relationships in WSRR. All WSRR SDO types support open content properties, properties that are defined on an individual instance of a type. The WSRR API is made available as several Stateless Session Beans, with both local and remote interfaces.

4.1.1 Creating a Java client
There are two clients supplied with the product which are used to interact with WSRR. These is an EJB client and a Web services client. Both use the same interfaces apart from the EJB client has a few more methods for supplying lists of information for tasks such as update and delete. In order to use either of the clients you must add the required jar files to your runtime: sdo-int.jar (This must be as high up the class path as possible to override SDO 1 interfaces) ServiceRegistryClient.jar

120

WebSphere Service Registry and Repository Handbook

A suitable EJB/Web services runtime Both sdo-int.jar and ServiceRegistryClient.jar can be found in your WSRR installation directory (e.g. c:\Program Files\IBM\WebSphereServiceRegistry).

ServiceRegistryClient
ServiceRegistryClient.jar can be found in your WSRR installation directory. It contains the following functionality: WSRR SDO Objects Helper classes – (for creating objects and manipulating them) Core EJB Client Governance EJB Client Ontology EJB Client Web Services generated code WSRR Core Web services client (calls the generated code) SDO2 classes Renamed EMF (required by the SDO2 runtime) Figure 4-1 on page 122 illustrates how ServiceRegistryClient.jar can be used to communicate with the WSRR server. The Ontology Web service is shown separate to ServiceRegistryClient.jar as no special client code is needed to access that Web service. See 4.2.1, “Creating a Web services client” on page 136 for more information.

Chapter 4. Interfaces and APIs

121

ServiceRegistry.ear Core Web service ServiceRegistryClient.jar WSRR Obj. Helpers Core Core EJB Governance EJB Ontology EJB Ontology WS EJB Impl http/https Core WS EJB

Plugins

Governance

Ontology

Ontology Web service
Figure 4-1 ServiceRegistryClient.jar architecture

Creating the EJB client
In this example, an EJB reference has been set up in the client J2EE environment which points to the real JNDI name of ejb/com/ibm/serviceregistry/ServiceRegistrySessionHome. Example 4-1 shows example code for connecting to a WSRR server where security is turned off on the application server.
Example 4-1 Creating an EJB client

try { // look up the home ServiceRegistrySessionHome ejbHome = (ServiceRegistrySessionHome) PortableRemoteObject.narrow(context.lookup("ejb/ServiceRegistrySession"), ServiceRegistrySessionHome.class); // create the client

122

WebSphere Service Registry and Repository Handbook

ServiceRegistrySession serviceRegistry = ejbHome.create(); } catch (ClassCastException e) { // do something } catch (NamingException e) { // do something } catch (CreateException e) { // do something } The Web services client is covered in 4.2, “Web services API” on page 136. There are three helper classes: com.ibm.serviceregistry.SRXMLHelper Used to create Documents com.ibm.serviceregistry.sdo.helper.DataFactory Used to create GenericObjects and QueryObjects com.ibm.serviceregistry.sdo.helper.BSRSDOHelper Used to add relationships and properties to WSRR Objects

Registering the SDO objects
In order for any client to use the SDO objects, they must first be registered using the org.apache.tuscany.sdo.util.SDOUtil.registerStaticTypes() method; this needs only to be done once. There are three separate packages that can be registered: com.ibm.serviceregistry.sdo.SdoFactory com.ibm.serviceregistry.governance.sdo.SdoFactory com.ibm.serviceregistry.ontology.sdo.SdoFactory However, if you register com.ibm.serviceregistry.governance.sdo.SdoFactory then com.ibm.serviceregistry.sdo.SdoFactory will also be registered automatically, as it is an extension, so there is no need to register it separately. It is recommended that the following two lines of code are added to the client application: SDOUtil.registerStaticTypes(com.ibm.serviceregistry.governance.sdo.SdoF actory.class); SDOUtil.registerStaticTypes(com.ibm.serviceregistry.ontology.sdo.SdoFac tory.class);

Chapter 4. Interfaces and APIs

123

4.1.2 Creating content in WSRR
Several attributes can only be specified on a create operation. Once created, they are treated as read-only. These attributes are: namespace name version

Creating a GenericObject
The SDO DataFactory is used to create a GenericObject. The namespace used to create WSRR dataobjects is: http://www.ibm.com/xmlns/prod/serviceregistry/6/0/sdo This is defined in a TypeConstants helper class.
Example 4-2 Creating a GenericObject

try { GenericObject go = (GenericObject)DataFactory.INSTANCE.create(TypeConstants.SR_URI,TypeCon stants.TYPE_GENERICOBJECT); go.setName(“GenericObject1”); go.setLocation(“location1”); go.setVersion(“1”); String bsrURI = serviceRegistry.create(go); } catch (ServiceRegistryException e) { // handle exception; }

Creating a document instance
The SRXMLHelper interface is used to create a Document instance. The content of the document can be supplied locally by various means, or it can be retrieved from a URL. It is possible to add additional metadata to the Document instance, including properties, relationships and classifications before saving the Document. The interface is shown in Figure 4-2 on page 125.

124

WebSphere Service Registry and Repository Handbook

Figure 4-2 SRXMLHelper interface

In order to create a document, the appropriate load method is invoked to read in the content of the document and construct an instance of the appropriate subtype of Document. This instance can then be passed to the create method. For example, creating a WSDL using the Java API is shown in Example 4-3, however, the same technique can be used for any of the Document objects.
Example 4-3 Creating a WSDL using the Java API

try { WSDLDocument wsdlDoc = (WSDLDocument)SRXMLHelper.INSTANCE.load(new FileInputStream(“C:/my.wsdl”),TypeConstants.TYPE_WSDLDOCUMENT); wsdlDoc.setName(“myWsdl”); wsdlDoc.setLocation(“my.wsdl”); wsdlDoc.setVersion(“1”); String bsrURI = serviceRegistry.create(wsdlDoc); } catch (ServiceRegistryException e) { // handle exception; } catch (FileNotFoundException e) { // handle exception; } catch (IOException e) { // handle exception; }

Chapter 4. Interfaces and APIs

125

Resolving dependencies
In the case of WSDL and XML Schema files, WSRR will attempt to resolve references to other documents that have a full URL specified for the location of the dependency. WSDL has one mechanism for referring to another file: the wsdl:import element. XML Schema has three mechanisms: xsd:include xsd:import xsd:redefine Any imported documents are related to the original document by a modelled relationship. For example, WSDLDocument has a modelled relationship called importedWSDLs that contains the other WSDL documents that are imported by the root WSDL document. Dependencies can also be satisfied by documents already in WSRR. Matching is based on the appropriate combination of namespace and location (name). For example, if w1.wsdl is a WSDL document that contains and a document already exists in WSRR with a name/location of w2.wsdl and a targetNamespace of “someNamespace” then when w1.wsdl is saved the import will be resolved to w2.wsdl in WSRR, and the importedWSDLs relationship on w1.wsdl will be updated appropriately.

Generating the logical model
If the subtype of Document is one which has an associated logical model, then the content of the Document will be parsed and the appropriate logical model objects created. For example, if a WSDL document contains two portTypes, then two instances of WSDLPortType will be created and associated with the new instance of WSDLDocument.

Creating multiple items at once
A GenericObject can be used as a collection to create multiple items with a single create invocation. For example, to create a WSDL file GGG.wsdl and an XML Schema file FFF.xsd that it depends on, a GenericObject would be created and the two documents would be added to the GenericObject with a user-defined relationship. When the GenericObject is saved, each document in each of the relationships of the GenericObject is tested to see if it is already in WSRR. If it is not it is added. When dependencies such as WSDL imports are encountered, the documents in the collection are examined to see if they satisfy the dependencies. If they do, then those documents are used to satisfy the dependencies. If they do not, then

126

WebSphere Service Registry and Repository Handbook

the normal processing of dependencies will take place, with a dependency being satisfied from a document in WSRR if the appropriate document already exists in WSRR, or an attempt to download the dependency from the URL used to refer to the dependency. A GenericObject can contain a relationship to another GenericObject, either a new GenericObject or an existing one. If a GenericObject contains a relationship to another GenericObject, then both GenericObjects will be saved. All of the documents referenced from all of the GenericObjects referenced from the root GenericObject are considered when looking to satisfy a dependency, and it is an error if there is more than one document in the set of documents that can satisfy a single dependency. A GenericObject can have multiple relationships and all documents in all relationships are treated equally. It is possible to save a set of GenericObjects with circular dependencies but there is no advantage to having circular dependencies and they should generally be avoided.

Creating a document that depends on a specific version
Another use of GenericObject is to allow a document to be saved with a dependency on a specific version of a document that is already in WSRR. In this case, a GenericObject is created to contain the new document and the mixture of new and existing documents that are required by the new document. The existing documents are represented by an instance of the appropriate SDO type which has previously been retrieved from WSRR. The retrieval can be based on a specific version. For example, to create a new file GGG.wsdl with a dependency on Version 1.2 of HHH.xsd, do this: 1. Create a new GenericObject using the SDO DataFactory 2. Create a new WSDLDocument instance using the SRXMLHelper 3. Create a user-defined relationship and add it to the GenericObject with an initial value that is the WSDLDocument instance for foo.wsdl 4. Retrieve an XSDDocument instance from WSRR for Version 1.2 of HHH.xsd 5. Save the GenericObject in WSRR When the GenericObject is processed, a new WSDLDocument will be persisted for GGG.wsdl and when processing the import of HHH.xsd, the location and targetNamespace of the import in GGG.wsdl will be checked against the locations and namespaces of other documents in the collection. In this case, the version of

Chapter 4. Interfaces and APIs

127

HHH.xsd in the collection will match against the import in GGG.wsdl so the import will be satisfied by Version 1.2 of HHH.xsd and this will be reflected in the importedSchemas relationship of GGG.wsdl. A GenericObject can have a dependency on another GenericObject, and if the GenericObject has relationships to other documents, then the dependencies can be satisfied by any of the documents related to the second GenericObject. When a document is included in more than one collection, with different versions of its dependencies, then all of the dependencies are added to the appropriate relationships. For example, if W1.wsdl is a WSDL document at Version 1.0 and it imports X1.xsd at Version 1.0 then the importedSchemas relationship on the WSDLDocument representing W1.wsdl will include Version 1.0 of X1.xsd. If a collection is created that includes the same version of W1.wsdl but in this case Version 1.1 of X1.xsd is required, when the collection is saved, the importedSchemas relationship on the WSDLDocument representing W1.wsdl will have two XSDDocuments: one for the original Version 1.0 of X1.xsd and the second for Version 1.1 of X1.xsd.

Creating a QueryObject
The SDO DataFactory is used to create the different types of QueryObject. This is illustrated in Example 4-4.
Example 4-4 Creating a QueryObject using the Java API

GraphQuery query = (GraphQuery)DataFactory.INSTANCE.create(http://www.ibm.com/xmlns/prod/s erviceregistry/6/0/sdo”,”GraphQuery”); PropertyQuery query = (PropertyQuery)DataFactory.INSTANCE.create(http://www.ibm.com/xmlns/pro d/serviceregistry/6/0/sdo,”PropertyQuery”);

4.1.3 Retrieving content from WSRR
Any object can be retrieved by its bsrURI as shown in Example 4-5.
Example 4-5 Retrieving a document using the Java API

/* * Retrieve a document with a known bsrURI. If we know the bsrURI for a * document it can be retrieved using the retrieve() method. If we * didn't know the bsrURI we would need to find it using a query *

128

WebSphere Service Registry and Repository Handbook

* The "namespace" property will have been set from the original XML * content and the "location" property will have been set from the * original document location. */ System.out.println(" retrieving document"); WSDLDocument storedDoc = (WSDLDocument)serviceRegistry.retrieve(wsdlBsrURI); System.out.println(" document found:"); System.out.println(" name = " + storedDoc.getName()); System.out.println(" namespace = " + storedDoc.getNamespace()); System.out.println(" version = " + storedDoc.getVersion()); System.out.println(" location = " + storedDoc.getLocation()); If the bsrURI is not known then a query would need to be run to find it, as described in 4.1.6, “Querying content in WSRR” on page 130.

4.1.4 Updating content in WSRR
These properties are ignored when performing an update: namespace name version Example 4-6 shows example code retrieving a WSDLDocument, adding two user defined properties and then updating the registry with the new changes.
Example 4-6 Retrieve a WSDLDocument, add user defined properties and update

try { // set the bsrURI to the value of a stored WSDLDocument String wsdlBsrURI = “bsrURI”; WSDLDocument documentStored = (WSDLDocument) serviceRegistry .retrieve(wsdlBsrURI); // add user defined properties BSRSDOHelper.INSTANCE.addProperty(documentStored, "prop1", "value1"); BSRSDOHelper.INSTANCE.addProperty(documentStored, "prop2", "value2"); // update the document serviceRegistry.update(documentStored); } catch (ServiceRegistryException e) { // handle exception

Chapter 4. Interfaces and APIs

129

}

Updating a GenericObject collection
Calling update with a GenericObject will: Update the properties on the root GenericObject. Add any new Documents contained in any of the user-defined relationships of the root GenericObject. Remove the association with any documents no longer mentioned in any of the user-defined relationships of the GenericObject. For example, if a GenericObject is created with a relationship to documents A, B and C and is then updated with the relationship containing A, C and D, after the update the relationship will only contain A, C and D; B is removed. Note that existing dependencies are not affected by the removal of B from the GenericObject collection.

4.1.5 Deleting content from WSRR
Logical objects cannot be deleted explicitly, the document that defined them must be deleted, in which case all the logical objects that were contributed by the document are also deleted. Example 4-7 shows how to delete a document using the Java API.
Example 4-7 Deleting a document using the Java API

/* * Delete a document we no longer need. Documents must be deleted by * passing the bsrURI to the delete() method. */ serviceRegistry.delete(wsdlBsrURI);

4.1.6 Querying content in WSRR
The support for query is based on XPath. There are two types of query: GraphQuery PropertyQuery These types of query are described in the following pages.

130

WebSphere Service Registry and Repository Handbook

An example using the GraphQuery and PropertyQuery can be found in Example 4-8 and Example 4-9 respectively.
Example 4-8 Using GraphQueries with the Java API

try { GraphQuery query = (GraphQuery) DataFactory.INSTANCE.create( TypeConstants.SR_URI, TypeConstants.TYPE_GRAPHQUERY); // retrieve all the XMLDocuments in the registry query.setQueryExpression("/WSRR/XMLDocument"); List graphQueryResults = serviceRegistry.executeQuery(query); for (int i = 0; i < graphQueryResults.size(); i++) { XMLDocument doc = (XMLDocument) graphQueryResults.get(i); System.out.println(doc.getBsrURI()); System.out.println(doc.getName()); } } catch (ServiceRegistryException e) { // handle exception }
Example 4-9 Using PropertyQueries with the Java API

try { PropertyQuery query = (PropertyQuery)DataFactory.INSTANCE.create( TypeConstants.SR_URI, TypeConstants.TYPE_PROPERTYQUERY); // retrieve all the XMLDocuments in the registry query.setQueryExpression("/WSRR/XMLDocument"); BSRSDOHelper.INSTANCE.addProperty(query, "p1", "description"); BSRSDOHelper.INSTANCE.addProperty(query, "p2", "name"); List propertyQueryResults = serviceRegistry.executeQuery(query); // process each PropertyQueryResultObject found in the list for (int i = 0; i < propertyQueryResults.size(); i++) { PropertyQueryResult pqr = (PropertyQueryResult) propertyQueryResults.get(i); // get the name String name = BSRSDOHelper.INSTANCE.getPropertyQueryResultValue(propertyQueryResult," name"));

Chapter 4. Interfaces and APIs

131

// get the description String description = BSRSDOHelper.INSTANCE.getPropertyQueryResultValue(propertyQueryResult," description")); } } catch (ServiceRegistryException e) { // handle exception }

PropertyQuery
A PropertyQuery returns only a subset of the properties of the objects that match the query expression. The properties to be returned are specified as the values of user-defined properties on the PropertyQuery object. For example, to return the name and description properties, add two user-defined properties to the instance of PropertyQuery, one with the value “name” and the other with the value “description”. The properties to be returned must be specified in property values because query objects extend BaseObject and therefore have their own name, description, and so on.

GraphQuery
GraphQueries retrieve SDO object graphs that represent data held in WSRR. A depth parameter can be specified on the GraphQuery object that allows you to specify the depth of relationships that are resolved in the object graph that is returned. Specifying a depth parameter of -1 means that a complete object graph is returned. For example, if a query with depth parameter of -1 returns a single WSDLService element, you can then programmatically follow all the relationships (both predefined and user-defined) from the root WSDLService object that is returned from the query. Specifying a depth parameter of 0 implies that only the objects that have been queried for are returned and so you can access all the properties for a given object, but cannot access any related object programmatically without executing an additional query.

Predefined queries
WSRR has a number of predefined queries, all of which are GraphQueries with a depth of 0. Table 4-1 on page 133 lists the queries, giving the name of the query, a description of the query and a description of the parameters of the query, if any.

132

WebSphere Service Registry and Repository Handbook

When supplying the modelled attribute name and attribute value, pass in a String array: String[] params = new String[] { "attribute name", "attribute value"};
Table 4-1 WSRR predefined queries Name of Query getAllWSDLDocuments getAllXSDDocuments getAllPolicyDocuments getAllXMLDocuments getAllServices getAllPorts getAllBindings getAllPortTypes getAllOperations getAllMessages getAllParts getAllElementDeclarations getAllComplexTypeDefinitions getAllAttributeDeclarations getWSDLDocument Description Returns all instances of WSDLDocument Returns all instances of XSDDocument Returns all instances of PolicyDocument Returns all instances of XMLDocument Returns all instances of WSDLService Returns all instances of WSDLPort Returns all instances of WSDLBinding Returns all instances of WSDLPortType Returns all instances of WSDLOperation Returns all instances of WSDLMessage Returns all instances of WSDLPart Returns all instances of ElementDeclaration Returns all instances of ComplexTypeDefinition Returns all instances of AttributeDeclaration Returns all instances of WSDLDocument that have a specific value for the named attribute. Returns all instances of XSDDocument that have a specific value for the named attribute. Returns all instances of PolicyDocument that have a specific value for the named attribute. Returns all instances of XMLDocument that have a specific value for the named attribute. Parameters None None None None None None None None None None None None None None 1. Modelled attribute name 2. Attribute value 1. Modelled attribute name 2. Attribute value 1. Modelled attribute name 2. Attribute value 1. Modelled attribute name 2. Attribute value

getXSDDocument

getPolicyDocument

getXMLDocument

Chapter 4. Interfaces and APIs

133

Name of Query getWSDLDocServices

Description Return instances of WSDLService corresponding to the WSDL services defined in a specific WSDL document Return instances of SOAPPort associated with the WSDL ports defined in a specific WSDL document Return instances of WSDLBinding corresponding to the WSDL bindings defined in a specific WSDL document Return instances of SOAPBinding associated with the WSDL bindings defined in a specific WSDL document Return instances of WSDLPort corresponding to the WSDL ports defined in a specific WSDL document Return instances of WSDLPortType corresponding to the WSDL portTypes defined in a specific WSDL document Return instances of WSDLOperation corresponding to the WSDL operations defined in a specific WSDL document Return instances of WSDLMessage corresponding to the WSDL messages defined in a specific WSDL document Return instances of WSDLMessage corresponding to the WSDL messages defined in a specific WSDL document Return instances of ElementDeclaration corresponding to the global XML Schema elements declared in a specific schema document Return instances of SimpleTypeDefinition corresponding to the global XML Schema simple types defined in a specific schema document

Parameters bsrURI of the WSDL document bsrURI of the WSDL document bsrURI of the WSDL document bsrURI of the WSDL document bsrURI of the WSDL document bsrURI of the WSDL document bsrURI of the WSDL document bsrURI of the WSDL document bsrURI of the WSDL document bsrURI of the XML Schema document

getWSDLDocSOAPPorts

getWSDLDocBindings

getWSDLDocSOAPBindings

getWSDLDocPorts

getWSDLDocPortTypes

getWSDLDocOperations

getWSDLDocMessages

getWSDLDocParts

getXSDElements

getXSDSimpleTypeDefs

bsrURI of the XML Schema document

134

WebSphere Service Registry and Repository Handbook

Name of Query getXSDComplexTypeDefs

Description Return instances of ComplexTypeDefinition corresponding to the global XML Schema complex types defined in a specific schema document Return instances of AttributeDeclaration corresponding to the global XML Schema attributes declared in a specific schema document Return instances of WSDLService that have a specific value for a specific modelled attribute Return instances of WSDLPort that have a specific value for a specific modelled attribute Return instances of WSDLPortType that have a specific value for a specific modelled attribute Return all instances of GenericObject Returns a List of PropertyQueryResult objects that have the relationship names as a user defined property of the PropertyQueryResult (see Example 4-10) Returns the GovernanceRecord of a governed object

Parameters bsrURI of the XML Schema document

getXSDAttributeDeclarations

bsrURI of the XML Schema document

getWSDLServices

1. Modelled attribute name 2. Attribute value 1. Modelled attribute name 2. Attribute value 1. Modelled attribute name 2. Attribute value None None

getWSDLPorts

getWSDLPortTypes

getAllGenericObjects getUserDefinedRelationshipN ames

getGovernanceRecord

bsrURI of the object which has been governed

Example 4-10 illustrates how to use the WSRR predefined queries to retrieve the relationship names from the query results list.
Example 4-10 Using WSRR predefined queries to retrieve the relationship names

// "serviceRegistry" is an EJB or Web service client previously created List propertyQueryResults = serviceRegistry.executeNamedQuery("getUserDefinedRelationshipNames"); // In this case we want to know the value of the property "name" // and add it to a list ArrayList relationshipNames = new ArrayList(); for(int index = 0; index < propertyQueryResults.size(); index++) { PropertyQueryResult propertyQueryResult =

Chapter 4. Interfaces and APIs

135

(PropertyQueryResult)propertyQueryResults.get(index); relationshipNames.add(BSRSDOHelper.INSTANCE.getPropertyQueryResultValue(pr opertyQueryResult,"name")); }

4.2 Web services API
Many of the functions in WSRR can also be invoked via a Web services API. There is both a Java Web service API (4.2.1, “Creating a Web services client” on page 136) and a raw SOAP API (4.2.3, “SOAP API” on page 139). Not all functionality can be invoked via the Web services API. At the time of writing all core and ontology functions had a Web services interface but the governance functionality could only be invoked via the EJB API or the Web user interface.

4.2.1 Creating a Web services client
As mentioned previously in 4.1.1, “Creating a Java client” on page 120 there are two clients which are used to interact with WSRR, supplied with the product. These is an EJB client and a Web services client. Both use the same interfaces apart from the EJB has a few more methods for supplying list of information for tasks such as update and delete. In order to use either of the clients you must add the required jar files to your runtime: sdo-int.jar (This must be as high up the class path as possible to override SDO 1 interfaces) ServiceRegistryClient.jar A suitable EJB/Web services runtime Both sdo-int.jar and ServiceRegistryClient.jar can be found in your WSRR installation directory (e.g. c:\Program Files\IBM\WebSphereServiceRegistry). The Core Web service makes use of custom bindings to do conversion to/from Datagraphs. This is illustrated in Figure 4-3 on page 137.

136

WebSphere Service Registry and Repository Handbook

ServiceRegistryClient.jar

ServiceRegistry.ear

Generated Client

WSRRCoreSDOClient

Custom Binding

Custom Binding

Figure 4-3 Core Web service client architecture

The WSRRCodeSDOClient allows the user to work with SDO objects directly and call methods that take the same parameters as the EJB methods. It has two constructors, one of which takes a userid and password: com.ibm.serviceregistry.ws.WSRRCoreSDOClient(java.lang.String endpoint) com.ibm.serviceregistry.ws.WSRRCoreSDOClient(java.lang.String endpoint, java.lang.String username, java.lang.String password) The URL to access the Core Web service is: http(s)://localhost:port/WSRRCoreSDO/services/WSRRCoreSDOPort The URL to access the Ontology Web service is: http(s)://localhost:port/WSRROntologyWS/services/WSRR_Ontology_Port

Web Service

Chapter 4. Interfaces and APIs

137

The WSDLs can be exported from the WebSphere Application Server administration console: Go to Applications → ServiceRegisty → Publish WSDLs There is also a Web services client to allow access to ontologies. There is no special client code needed for the ontology Web service API since it does not use SDOs. Export the WSDLs from WebSphere as documented previously and then run the exported file through wsdl2java. The generated code can then be used to access the Ontology API through Web services. This is described in more detail in 4.2.2, “Ontology Web service” on page 138.

Create a Web services client
Example 4-11 shows the example code for connecting to WSRR where security is turned off on the application server.
Example 4-11 Creating a Web service client

try { String url = http://localhost/WSRRCoreSDO/services/WSRRCoreSDOPort; WSRRCoreSDOClient serviceRegistry = new WSRRCoreSDOClient(url); } catch (ServiceException e) { // do something } catch (MalformedURLException e) { // do something }

4.2.2 Ontology Web service
The ontology Web service allows you to perform a limited number of tasks for querying of Ontologies. Unlike the main Web service, no client is supplied, so it is necessary to create a client using external tooling. There are a number of ways of generating the client code. For example, you could use IBM Rational® Software Architect or WSDL2Java which comes with the WebSphere Application Client or WebSphere Application Server. The typical command for generating the basic client code using WSDL2Java is: WSDL2Java -a -r client WSRR_Ontology_API_service.WSDL It is advisable to generate the client using namespace to classname mapping if possible: http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ws/ontology/service = com.yourcompany.ontology.service

138

WebSphere Service Registry and Repository Handbook

http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ws/ontology/binding = com.yourcompany.ontology.service http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ws/ontology/portType = com.yourcompany.ontology.service http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ws/ontology/schema = com.yourcompany.ontology.service http://www.ibm.com/xmlns/prod/serviceregistry/6/0/ontology/sdo = com.yourcompany.ontology.types Example 4-12 shows an example of how to use the generated ontology Web service client.
Example 4-12 Using the generated Ontology Web service client

URL url = new URL("http://hostname:port/WSRROntologyWS/services/WSRR_Ontology_Port"); WSRR_Ontology_ServiceLocator locator = new WSRR_Ontology_ServiceLocator(); WSRR_Ontology_API_portType port = locator.getWSRR_Ontology_Port(url); If WebSphere security is turned on, the following two properties need to be added: ((javax.xml.rpc.Stub)port)._setProperty(Stub.USERNAME_PROPERTY,"usernam e"); ((javax.xml.rpc.Stub)port)._setProperty(Stub.PASSWORD_PROPERTY,"passwor d"); Trust Stores and Key Stores will also need to be set up.

4.2.3 SOAP API
This is the same SOAP API that is used by the SDO-based Web service client. This section focuses on the low-level details that are hidden from the user by the SDO runtime and the WSRR client. SOAP: A lightweight, XML-based protocol for exchanging information in a decentralized, distributed environment. SOAP can be used to query and return information and invoke services across the Internet. Note: IBM is working to define a standard API for a service registry such as WSRR. The current SOAP API will be deprecated when such a standard API is defined.

Chapter 4. Interfaces and APIs

139

DataGraphType
Many of the operations have one or more instances of DataGraphType as part of either an input message or an output message. This is a specialization of the standard SDO DataGraphType. The DataGraphType as used by WSRR contains either an instance of the WSRR type or an instance of the PropertyQueryResult type as the root object. The data graphs used by WSRR are defined by the XML Schema element shown in Example 4-13.
Example 4-13 SOAP API DataGraph XML schema

The data graph returned from a property query has an instance of PropertyQueryResult as the root object of the data graph. All other uses of DataGraphType have an instance of WSRR as the root object. With the single exception of updating document content, when a change summary element is used, none of the BaseDataGraphType elements are used.

WSRR
The artefacts element contains all the objects in the graph of objects that are not contained in any other object in the graph of objects. For example, if the graph consists of two WSDLDocument objects, both objects will be in the artefacts, whereas if the graph consists of a WSDLService and its WSDLPorts then only the WSDLService will be an artefact as the WSDLPorts are contained by the WSDLService. The WSRR type is defined by the XML Schema type shown in Example 4-14 on page 141.

140

WebSphere Service Registry and Repository Handbook

Example 4-14 SOAP API WSRR type XML schema

The root element contains the bsrURI value of the object that is the root of the graph of objects contained by the WSRR instance.

PropertyQueryResult
The PropertyQueryResult contains the set of properties specified in the query, for one object that matched the query. Each object matching the query is sent back as a separate instance of DataGraphType. The PropertyQueryResult is defined by the XML Schema type shown in Example 4-15.
Example 4-15 SOAP API PropertyQueryResult XML schema

Temporary bsrURI values
When creating new objects, a temporary bsrURI value can be assigned to an object, and one must be assigned to an object if it is necessary to refer to that object. If the root object of the data graph is a new object then it must have a temporary bsrURI value assigned and that value must be specified as the value of the root element of the WSRR instance.

Chapter 4. Interfaces and APIs

141

As the type of the bsrURI attribute is the XML Schema ID type, the values must be compatible with the NCName type, which means that a bsrURI must begin with a Letter or with the underscore '_' character. As normal bsrURI values begin with a Letter, a temporary bsrURI value must begin with a '_' character.

Document content
When working with documents, the content of the document is represented as the value of an attribute named content, and it is encoded using base64 encoding.

Error handling
All of the operations return a ServiceRegistryWebServiceException fault. The fault contains the message from the exception thrown by the WSRR server.

WSRR portType
The WSRR SOAP API is a document-literal SOAP/HTTP binding of a portType that provides the following operations: create delete executeNamedQuery executeNamedQueryWithParameters executeQuery retrieve retrieveWithDepth update All the operations are documented in more detail in the WebSphere Service Registry and Repository Information Center, we will cover “create” only here, as an example: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.do c/rwsr_soap_api_guide11.html

Create
The createRequest message is an instance of the create element, which consists of a single datagraph element. The definition of the create operation is as follows.

142

WebSphere Service Registry and Repository Handbook

Example 4-16 SOAP API create operation

The createResponse message is an instance of the createResponse element, which contains a single string which is the bsrURI value assigned by WSRR to the root object of the request datagraph. The following message (Example 4-17) is an example of a create request that represents creating a single document, in this case an XMLDocument. A single user-defined property is defined at the time of creation. Note the use of the temporary bsrURI value of "_1" to refer to the root object.
Example 4-17 Example create a document using the SOAP API

_1

Chapter 4. Interfaces and APIs

143

 The following message (Example 4-18) is an example of a successful response message.
Example 4-18 Example of a successful response to a create document using SOAP API

WSRR--c8e644f7.fa84a879.29e0adb9.10db8541a90.6ae36dd4.46 Other examples of using the SOAP API can be found in the WebSphere Service Registry and Repository Information Center: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.do c/rwsr_soap_api_guide11.html

4.3 Web user interface (Web UI)
WSRR provides extensive customization capabilities for its user interface, allowing you to modify the way in which information about your services is presented to the user. These customization capabilities range from simply modifying the properties that are displayed on an existing view of a service to deploying a whole new perspective that defines new views for the information stored in WebSphere Service Registry and Repository. This new perspective may be specific to a certain kind of user within your organization, using terminology that the user can understand and restricting the information displayed to the minimum that allows the user to perform their day-to-day job.

144

WebSphere Service Registry and Repository Handbook

This section describes the concepts and architecture of the Service Registry and Repository Web user interface. Chapter 10, “Customizing the Web UI” on page 381 goes into more detail on how to configure the WSRR user interface.

4.3.1 Web user interface layout
The WSRR Web user interface is structured in a fairly standard way familiar to most users. A frameset is used to divide the page into three areas, as shown in Figure 4-4.

Banner

Workarea Navigation

Figure 4-4 Web user interface frameset

The only portion of the Web user interface that cannot be customized is the banner. However, if you deploy a custom perspective to WSRR that the current user is permitted to view, the display name of the custom perspective will appear in the User perspective list within the banner frame. The user can then switch to the custom perspective by selecting its name from the list and clicking Go.

Chapter 4. Interfaces and APIs

145

The content that is displayed within the Navigation and Workarea frames is controlled by a number of XML definition files. A set of system definition files is loaded into WSRR as part of the installation process. These files define the Administrator and User perspectives that are available by default within WSRR. The XML definition files for these system perspectives can be modified to tailor them to your business needs. There are five different types of definition files used by the WSRR user interface, as follows: Perspective Navigation Tree Collection View Detail View View Query Certain definition files may reference objects that are defined in other definition files. For instance, a perspective definition must specify the navigation tree that will be displayed when a user is viewing that perspective as well as the collection views and detail views that should be used when viewing different types of object within the perspective. The dependencies that exist between the different types of definition file form a hierarchical structure for any given perspective, as shown in Figure 4-5 on page 147.

146

WebSphere Service Registry and Repository Handbook

Perspective

Navigation Tree

Detail View

Collection View

View Query

Figure 4-5 Definition file hierarchy

The sections that follow describe the key concepts of each of the definition file types used by the WSRR user interface.

4.3.2 Perspectives
A perspective defines the views that users will see when they are browsing the content of WSRR in the context of that perspective. More specifically, a perspective defines: The user roles whose members are permitted to view the perspective. The navigation tree that will be displayed in the Navigation frame. The collection views that will be used when displaying collections of objects in the Workarea frame.

Chapter 4. Interfaces and APIs

147

The detail views that will be used when displaying a specific object in the Workarea frame. A perspective is intended to provide the user with a consistent view of the data within WSRR. For instance, a Business Analyst perspective would display a navigation tree and a number of detail views and collection views that all use consistent terminology that is meaningful to a business analyst. A Service Developer perspective, on the other hand, would display a different navigation tree, detail views, and collection views that would be likely to use more technical terminology that is meaningful to a service developer. Note: Role-based views It is recommended that, when you are defining custom perspectives, you attempt to use consistent terminology and display similar sets of metadata across all of the views that are used by that perspective. Designing a perspective in this way should ensure that it provides a role based view onto the data stored within WSRR.

Roles
WSRR defines the Administrator and the User roles. You can use these roles when creating a perspective to define the users that are permitted to view that perspective. By default, any user that is able to log into the Web user interface is able to see all perspectives that are visible to the User role. However, it is possible to define additional roles to WSRR that match the roles performed by the users in your organization. Users or groups can then be mapped to these custom roles and the visibility of a perspective can then be restricted to just those users or groups that are mapped to the custom role.

Relationships to other view definitions
It is important to note that a perspective does not contain or own any of the objects that it refers to. It simply specifies the views that should be used to display data in the context of the perspective. This allows navigation trees, collection views and detail views to be shared across several perspectives at the same time. In fact, many of the system collection views and detail views are actually shared by the Administrator and User perspectives. This is shown in Figure 4-6 on page 149.

148

WebSphere Service Registry and Repository Handbook

Perspective

Perspective

Navigation Tree

Detail View

Collection View

Navigation Tree

View Query

View Query

Figure 4-6 Reusing view definitions

Due to the loose coupling that exists between the various definition files that make up a perspective, WSRR does not mandate the order in which the files must be loaded. As a result, the Web user interface delays attempting to resolve any of the references between the files until they are required at runtime. This late binding allows a perspective within the Web user interface to continue to operate even if some of the view definitions that are referenced by the perspective have not been loaded into WSRR. It is only when the user attempts to navigate to an area of the perspective with the missing view definitions that any problems will occur. At this point, a suitable error message will be displayed and a WSRR administrator will need to take suitable action to resolve the problem.

View definition selection precedence
We have explained that users browse the information within WSRR in the context of a perspective. The view definition mappings for the users current perspective

Chapter 4. Interfaces and APIs

149

are searched when attempting to resolve the collection or detail view definition that should be used to display a certain type of object. By default, the WSRR Web user interface will simply use the name of the underlying SDO object type in order to select a suitable view definition to use to display the data. For instance, if you are attempting to view the details of a WSDL document object, the Web user interface will attempt to find a view definition within your current perspective that is mapped to “WSDLDocument”. However, it is possible to control how a perspective selects the view definition to use when displaying an object. This is achieved using display types in the other types of definition files within the user interface. If a display type is specified, this display type is passed to the perspective and used when attempting to resolve the view definition mapping instead of the name of the underlying SDO type. In effect, when you use display types within view query, collection view or detail view definitions you are stating that you want the information displayed using a specific view definition. For additional details on perspectives, see 10.4, “Perspectives” on page 394.

4.3.3 View queries and navigation trees
The navigation tree is key to the definition of any perspective. It is the starting point for browsing the information stored within the WSRR. A well designed navigation tree can help to ensure that a user can find the information that they are looking for quickly and without the need to browse through several other panels of information. Within WSRR, the definition of the navigation tree is actually split into two different configuration file types: The visible portion of the navigation tree is defined within a navigation tree definition file. This defines the physical structure of the navigation tree and the text that is displayed for each node of the tree. It also defines whether a node will be rendered as a link and what action should be performed when the link is selected. The query that will be executed when a node in the navigation tree is selected is defined within a view query definition file. A view query definition file can define multiple view queries, each with an ID. It is possible to override the behavior of an existing system view query by defining a new view query with the same ID. However, since view queries are shared across all of the perspectives defined within WSRR, overriding a system view query may modify the behavior of another perspective. For this reason, overriding an existing view query should only be done with caution. View queries can vary in complexity, from simply returning all objects of a specific type to returning all of the objects that satisfy certain search criteria. A view query can also

150

WebSphere Service Registry and Repository Handbook

specify the collection view that should be used to display the results of the query. Figure 4-7 shows how the navigation tree definition file links the nodes within the navigation tree to the corresponding view queries that will be executed when the node is selected.

• •

Navigation Tree Definition

• •

• • WSDLDocument

View Query Definition

• •
Figure 4-7 Defining a navigation tree

Welcome page link and search box
Every navigation tree within WSRR will display a link to the welcome page and a search box above the actual navigation tree. These items are always displayed and cannot be configured using the navigation tree definition or view query definition files. For additional detail on queries, see 10.2, “View query definitions” on page 382. For additional detail on navigation, see 10.3, “Navigation trees” on page 390.

4.3.4 Collection views
As its name suggests, a collection view is used to display information about a collection of objects in WSRR. A collection view definition describes the properties of the underlying object that are to be displayed in columns within the view and also which action buttons should be displayed. A collection view definition file can only contain a single collection view definition. A collection view must also specify which columns within the view will be displayed as HTML links. Selecting one of these links will navigate the user to the

Chapter 4. Interfaces and APIs

151

detail view for the object on the corresponding row in the collection view. A collection view can control the detail view definition that is used to display the details of the selected object by specifying a display type. Recall that, if a display type is specified the Web user interface will attempt to resolve it to a detail view definition using the mappings defined within the current perspective. If a display type is not specified, the Web user interface uses the SDO type name of the object in the selected row to find the detail view definition to use. Figure 4-8 shows the areas of a collection view that are controlled by a collection view definition.
Title

Description

Button Definitions

Column Definition

Column Definition

Column Definition

Column Definition

Figure 4-8 Collection views

For additional detail on collection views, see 10.5, “Collection views” on page 401.

4.3.5 Detail views
As its name suggests, a detail view is used to display the details of a specific object in WSRR. A detail view definition describes the properties of the underlying object that are to be displayed in the detail view and where within the detail view they will be displayed. A detail view definition file can only contain a single detail view definition. However, detail views do support the concept of tabs. Tabs allow different views to be defined onto the same underlying data.

152

WebSphere Service Registry and Repository Handbook

However, currently the only type of tab that supports customization is the Details tab. The area of a detail view defined with a tab definition is shown in Figure 4-9.

Tab Definition

Figure 4-9 Detail view tabs

The way in which a property is displayed on the details tab within a detail view depends on the type of the property itself and where in the detail view it is displayed. The details tab is divided into a General Properties section and multiple Additional Properties sections, as shown in Figure 4-10 on page 154.

Chapter 4. Interfaces and APIs

153

Additional Properties

General Properties

Additional Properties

Additional Properties

Figure 4-10 General and additional properties

Properties that are displayed within the General Properties section of the details view must be of type string. The value of the property is displayed within a text entry field. Properties that are displayed in an Additional Properties section of the details view must represent a reference to another object or objects in WSRR. Properties displayed in the Additional Properties section of a details view are displayed as HTML links. Selecting one of these links navigates the user to a detail or collection view for the corresponding property on the object in question. A detail view can control the view definition that is used to display the resulting page by specifying a display type. Recall that, if a display type is specified the Web user interface will attempt to resolve it to a view definition using the mappings defined within the current perspective.

4.4 Command Line Interface
The Command Line Interface provides full support for all of the WSRR programmatic APIs, including all administrative operations. It may be used from a

154

WebSphere Service Registry and Repository Handbook

standalone Jython or Jacl interpreter, or it may be run inside wsadmin and used in conjunction with the facilities available there. Several example scripts show you how to perform governance tasks such as promoting entities from one WSRR to another, or transitioning entities through different lifecycle states. See 8.6, “Administering WSRR using the CLI” on page 299 for information about how to configure the CLI and how to use it for administrative functions. Several sample scripts are provided with the CLI that illustrate how to use it for both user and administrative tasks, more details on these scripts can be found in 8.6.3, “Sample scripts” on page 306.

4.5 Admin (JMX)
The WSRR administrative (JMX) interface provides a Java API that allows you to manage configuration settings to control registry runtime behavior. For example, loading and removing classification systems (ontologies), setting up access control policies, or customizing the user interface. In addition, you can register listeners for specific administration events. Sample client code is provided for you to build on in the \admin\javasrc directory. More information about the WSRR administrative JMX interface can be found in 8.5, “Administering WSRR using JMX” on page 292.

Chapter 4. Interfaces and APIs

155

156

WebSphere Service Registry and Repository Handbook

5

Chapter 5.

SOA governance enablers
This chapter describes the features of WebSphere Service Registry and Repository that enable you to implement the governance processes that exist within your SOA environment. This chapter contains the following: 5.2, “Lifecycles” on page 158 5.3, “WSRR security” on page 187 5.4, “WSRR plugins” on page 197 5.5, “Impact analysis” on page 213

© Copyright IBM Corp. 2007. All rights reserved.

157

5.1 Overview
As discussed in Chapter 1, “Introduction to SOA” on page 3, SOA dramatically increases the dynamism of your information system. More accurately, it provides a means for you to address the requirements for dynamism that most businesses are already facing. The basic tenet of SOA is to provide an information system that is responsive to the rate of change faced by your business in its markets. But that dynamism also brings additional risks, for example: The risk that someone will change a business process in a way that is detrimental to the business. That someone will change a business process or service that places unexpected and excessive demand on the capacity of the information system, either crashing the system or having an adverse affect on the other processes also being served by the information system. That someone will introduce rogue software that siphons critical business information. That someone will change the configuration of the system in way that disrupts the business. For these reasons, the SOA lifecycle is layered on a backdrop of a set of governance processes that ensure that compliance and operational policies are enforced, and that change occurs in a controlled fashion and with appropriate authority as envisioned by the business design. It must be stressed that the scope of governance within an SOA environment extends beyond any single product. However, WebSphere Service Registry and Repository is a powerful enabler for SOA governance and provides a number of mechanisms that allow you to implement the governance processes that have been specified within your business design. These mechanisms are discussed in the sections that follow.

5.2 Lifecycles
WebSphere Service Registry and Repository provides support for the definition and enforcement of lifecycles which can be applied to the objects that it stores. The process of applying a lifecycle to an object within WSRR is referred to as making the object governable. An object that currently has a lifecycle applied to it is referred to as a governed object or governed entity. If, at some point, you

158

WebSphere Service Registry and Repository Handbook

decide that you no longer want to apply a lifecycle to an object, you can remove governance from the object. Note: Referring to objects in WSRR that have a lifecycle applied to them as governed objects is a little misleading. It is possible to apply other aspects of SOA governance to objects within WSRR, such as security and validation, without applying a lifecycle to the objects. Indeed, applying a lifecycle to an object in WSRR is optional. However, within this book, when we refer to governed objects, we are referring to objects that have a lifecycle applied to them. During the installation process a simple default lifecycle is loaded into WSRR. This default lifecycle provides the minimum capability to govern an object, or collection of objects, in WSRR. This lifecycle is adequate for use in a proof of concept or for prototyping. However, you should consider defining and deploying a lifecycle that is more representative of the governance processes defined within your organization. For more information about replacing the lifecycle definition in WSRR, see the WebSphere Service Registry and Repository Information Center: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.do c/twsr_configrn_governance02.html

5.2.1 State machine terminology
The lifecycle state of an object in WSRR is maintained using a simple state machine. A state machine basically consists of states with transitions between them. Within WSRR, an object can transition between states due to a call to the transition method on the Governance API or due to a user clicking the relevant button in the Web user interface. The basic terms that define the building blocks of state machines are defined here: States Within WSRR, the state of a governed object simply defines the position of that object within the governance lifecycle that is being applied to the object. Composite states A composite state is an aggregate of one or more states. They can be used to decompose a complex state machine into a hierarchy of state machines. Events In the context of a generic state machine, an event is what triggers a transition from one state to another. Within WSRR, however, there is only one event that can trigger a transition for a governed entity. This event is a call to the

Chapter 5. SOA governance enablers

159

transition method on the governance API (the Web user interface uses this method when transitioning objects as the result of a user action). Transitions A transition is the movement that occurs when a governed object moves from a source state to a target state, as the result of a triggering event. The transitions that are available for a governed object can be determined by looking at the transitions whose source state match the current lifecycle state the object.

5.2.2 Lifecycle definitions
Governance lifecycles in WSRR are defined using a matched pair of files. Both of these files must be present in WSRR in order to be able to perform any lifecycle related operations, such as making an object governable or transitioning the state of an object within the lifecycle from one state to another.

State Adaptive Choreography Language (SACL) file
The actual governance lifecycle itself is defined using the State Adaptive Choreography Language (SACL). SACL is simply an XML representation of state machines that is used within WebSphere Process Server. SACL allows you to define the states that exist within your state machine and the transitions that can occur to move entities from one state to another. WSRR only allows one SACL file to be loaded at any given time. However, this SACL file is capable of defining multiple lifecycles. It is also possible to replace the default lifecycle within WSRR with a custom lifecycle that is more representative of the governance processes defined within your organization. If you decide that you want to define your own lifecycle, a graphical editor is available for creating and modifying SACL files within WebSphere Integration Developer. It is also possible manually generate a SACL file using other development tools. If you decide that you want to manually generate a SACL file, we recommend that you use an XML editor that performs validation. The SACL XML schema definition is provided as part of the WSRR fixpack 1 install and can be found in the \admin\schemas directory.

Lifecycle ontology file
Although all of the information required to apply a lifecycle to the objects in WSRR is contained in the SACL file, WSRR requires additional information in order to: Simplify the process of searching for governed objects.

160

WebSphere Service Registry and Repository Handbook

Simplify the process of defining access control permissions on governed objects. Display states and transitions in a user friendly manner. WSRR achieves this by using the SACL file to generate a corresponding OWL file. This OWL file defines a number of classes that represent the states and transitions that are defined in the SACL file. For each state or transition contained in the SACL file, there will exactly one OWL class defined in the corresponding OWL file. At runtime, WSRR uses these OWL classes to classify governed objects with a classification that corresponds to their state within the lifecycle. This enables you to construct simple XPath queries that will return all of the objects in WSRR that are in a given lifecycle state. Note: The relationship between the states and transitions defined in the SACL file, and the classes defined in the OWL file, is central to the operation of the lifecycle state machine. If any modification is made to the SACL file, a corresponding modification must be made to the OWL file. In other words, the information that is contained in this matching pair of files must be kept synchronized to ensure the correct operation of the lifecycle state machine.

Generating the lifecycle ontology file
The lifecycle ontology file does not need to be manually generated. WSRR provides an Extensible Stylesheet Language Transformations (XSLT) file that is able to generate the OWL file from the corresponding SACL file. This process is shown in Figure 5-1 on page 162. The OWL classes that are generated by the XSLT transform are of the form: # For example, the OWL class that is generated to represent the initial state of the default lifecycle (InitialState1) is as follows: http://www.ibm.com/xmlns/prod/serviceregistry/6/0/governance/Default Lifecycle#InitialState1 For more information about generating the lifecycle ontology file from the SACL file, see the WebSphere Service Registry and Repository Information Center: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.do c/twsr_configrn_governance20.html

Chapter 5. SOA governance enablers

161

SACL

XSLT

XSLT Processor

OWL

Figure 5-1 Generating the lifecycle ontology file

Modifying the lifecycle ontology file
By default, the labels that are generated for the OWL classes only contain the basic information that is available in the SACL file. For states, the label that is generated contains the value of the displayName attribute of the SACL state. For transitions, the label that is generated contains the value of the name attribute, of the operation element, of the SACL transition. However, the generated lifecycle ontology file can be edited before it is loaded into WSRR in order to provide additional information, for example: More descriptive state and transition labels can be specified. Translations of the state and transition labels can be specified in order to provide support for displaying states and transitions in browsers that specify the relevant locales.

162

WebSphere Service Registry and Repository Handbook

Descriptions of the state and transitions can be specified. It is also possible to provide translations of these descriptions. Example 5-1 shows an example of an OWL class that has been modified to include translations of both the label and description.
Example 5-1 Modified OWL class

Created Erstellt Creato ... This initial state represents the default state of a newly created governed collection. Dieser Anfangszustand gilt als Standardzustand einer neu erstellten regulierten Sammlung. Questo stato iniziale rappresenta lo stato predefinito di una collezione governata appena creata. ...

5.2.3 WSRR default lifecycle
As discussed previously, a simple default lifecycle is loaded in to WSRR at installation time. This lifecycle is based upon the IBM SOA Foundation lifecycle that was discussed in 1.1.3, “SOA lifecycle” on page 7. The states and transitions defined within the WSRR default lifecycle represent the states and transitions that apply to services as they move through the SOA lifecycle. The WSRR default lifecycle is shown in Figure 5-2 on page 164.

Chapter 5. SOA governance enablers

163

Initial State

Created Plan Model AuthorizeDevelopment

Assemble Certify Deploy Approve Revoke Retired
Final State

Repair

Manage Deprecate
Figure 5-2 WSRR default lifecycle

Created
The Created state represents the initial state of any object, or collection of objects, within WSRR that is made governable. The transitions that are available from this state are: Plan Performing the Plan transition moves the object, or collection of objects, from the Created state to the Model state.

Model
In the IBM SOA Foundation lifecycle, modelling is described as the process of capturing your business design from an understanding of business requirements and objectives and translating that into a specification of business processes, goals and assumptions – creating an encoded model of your business. In the context of WSRR, several tasks may be performed when a service is in the model state including, but not limited to, the following: Defining the business concepts that are required in order to fully describe your services within WSRR. Defining the metadata that must be added to the different types of artefacts that you will store within WSRR. Defining who should be allowed to access WSRR and what types of objects they should be allowed to access. Identifying existing service artefacts that your new services may depend on.

164

WebSphere Service Registry and Repository Handbook

The transitions that are available from this state are: AuthorizeDevelopment Performing the AuthorizeDevelopment transition moves the object, or collection of objects, from the Model state to the Assemble state. This transition should be performed once the modelling of the service is complete.

Assemble
Services that are in the Assemble state in WSRR are in the process of being developed and tested. This occurs when the service interface has been defined and published to WSRR in order to socialize the interface, but the implementation of the service is not yet complete. This approach allows clients of the new service to be developed before the service is actually deployed, or for the new service to be included in composite business process definitions. Several of the WSRR artefacts that were identified during the Model phase of the SOA lifecycle may also be created at this point. For instance, GenericObjects may be created within WSRR or the service artefacts within WSRR may be decorated with metadata. The transitions that are available from this state are: Certify Performing the Certify transition moves the object, or collection of objects, from the Assemble state to the Deploy state. This transition should be performed once the implementation of the service is complete.

Deploy
Services that are in the Deploy state in WSRR are in the process of being deployed to the target runtime environment and tested in that environment. The length of time that a service may spend in the Deploy state depends on the complexity of the service. For instance, a simple, self contained service that is to be hosted in an existing environment might be deployed in a matter of minutes. A business process, on the other hand, that requires several component services to be deployed across multiple new hosting environments may take days, or even weeks, to deploy. The deployment process might also involve creating or updating service artefacts within WSRR. For instance, additional artefacts that represent the endpoints of the deployed services may be created, or metadata regarding the environment on which the services are being hosted may be added to the service definition.

Chapter 5. SOA governance enablers

165

The transitions that are available from this state are: Approve Performing the Approve transition moves the object, or collection of objects, from the Deploy state to the Manage state. This transition should be performed once the deployment and testing of the process is complete and the testing indicates that the service is functioning correctly. Repair Performing the Repair transition moves the object, or collection of objects, from the Deploy state back to the Assemble state. This transition could be performed because the testing of the new service indicated that it was not functioning as required or providing the required levels of performance.

Manage
Services that are in the Manage state in WSRR are services that have been deployed to a target runtime environment. At this point in the service lifecycle, WSRR can be used to dynamically locate service endpoints at runtime. Monitoring software, such as IBM Tivoli Composite Application Manager for SOA, can also be used to monitor the performance of the services in the runtime environment and update the service artefacts in WSRR with performance related metadata. This metadata can, in turn, be used to affect the runtime routing decisions of runtimes that use WSRR to dynamically locate service endpoints at runtime. The transitions that are available from this state are: Deprecate Performing the Deprecate transition moves the object, or collection of objects, from the Manage state to the Retired state. This transition should be performed once the service is no longer required or used by other services within the SOA environment, maybe as a result of a newer version of the service being deployed. Impact analysis can be performed to determine the other services within the SOA that have a dependency on the service in question. Revoke Performing the Revoke transition moves the object, or collection of objects, from the Manage state back to the Deploy state. This transition could be performed in order to take the service offline and prevent it from being invoked by other services, maybe because certain quality of service issues need to be addressed in the runtime environment. Once again, impact analysis can be performed to determine the other services within the SOA that have a dependency on the service in question.

166

WebSphere Service Registry and Repository Handbook

Retired
Services that are in the Retired state in WSRR are services that have been withdrawn from service and should no longer be used.

5.2.4 GovernanceRecords
The lifecycle state of a governed object in WSRR is not stored on the object itself. Instead, GovernanceRecords are used to encapsulate all of the information regarding the state of an object in the governance lifecycle. When an object in WSRR is made governable, a corresponding instance of a GovernanceRecord is created in order to maintain the state of that object within the governance lifecycle. It is this GovernanceRecord that is used by the lifecycle state machine in order to determine the transitions that are available for the governed object. The lifecycle state machine also uses the GovernanceRecord when the governed object is transitioned from one state to another within the lifecycle. Table 5-1 describes the attributes of the GovernanceRecord.
Table 5-1 GovrnanceRecord attributes Attribute name entityBsrURI Description The entityBsrUri attribute contains the bsrUri of the object that was made governable. The object that this bsrUri refers to is known as the root object. A single GovernanceRecord is able to maintain the state in the governance lifecycle of a collection of OriginalObjects in WSRR. The governedObjects attribute is a list that contains references to all of the OriginalObjects for which this GovernanceRecord is maintaining lifecycle state. The collection of OriginalObjects that is referenced by the governedObjects attribute is referred to as a governed collection. The governed collection will always contain, at least, a reference to the root object. The state attribute defines the current lifecycle state of all of the OriginalObjects in the governed collection.

governedObjects

state

An OriginalObject is any object a user specifically creates such as a Document, a QueryObject, or a GenericObject. Refer to Figure 3-9 on page 103 to see where the OriginalObject type fits into the BaseObject model. Refer to Figure 3-1 on page 80 and 3.2.3, “GenericObject” on page 83 for additional information about WebSphere Service Registry and Repository objects.

Chapter 5. SOA governance enablers

167

Note: It is only possible to make the following types of objects governable in WSRR: – – – – – – GenericObject PolicyDocument SCAModule WSDLDocument XMLDocument XSDDocument

It is not possible to govern derived objects directly. However, derived objects are governed indirectly by governing the physical document from which they were parsed. All derived objects are classified with the same governance lifecycle state as the physical document from which they were parsed and are consequently returned when querying WSRR for objects classified in this manner.

Obtaining the GovernanceRecord
The GovernanceRecord for a particular object in WSRR can be obtained using the getGovernanceRecord method on the Governance API. The bsrURI of the object in question must be passed as an argument to this method. If the value returned from this method is null, this indicates that the object in question is not governed.

The root object
When an OriginalObject in WSRR is made governable, and a corresponding instance of a GovernanceRecord is created, a reference to the governed object is stored as the root object of the governed collection in the GovernanceRecord. The root object of a governance collection has special significance. When you want to transition the lifecycle state of a governed collection from one state to another, you must do so using the root object. Attempting to transition the lifecycle state of a governed collection using any object other than the root object will cause an error. Similarly, if you want to remove governance from a governed collection, you must do so using the root object. Attempting to remove governance from a governed collection using any object other than the root object will cause an error. It is possible to determine whether an object is the root object of a governed collection by comparing its bsrUri with the value of the entityBsrUri attribute on the GovernanceRecord. If the two bsrUris are the same, then the object in question is the root object of the governed collection. If the two bsrUris are

168

WebSphere Service Registry and Repository Handbook

different, then the value of the entityBsrUri of the GovernanceRecord can be used to retrieve the root object of the governed collection.

Governed collections
Consider a simple scenario where an OriginalObject exists in WSRR that has no predefined or user defined relationships to any other OriginalObjects. If this object is made governable, then the only reference that is added to the list of governed objects in the GovernanceRecord is the root object. This is shown in Figure 5-3.

Governed Ungoverned
Make Governable

Governance Record Root Object WSDL GovernedObjects State

WSDL

Figure 5-3 Governing an object with no relationships to other objects

Chapter 5. SOA governance enablers

169

However, a root object may have a number of predefined or user defined relationships to other OriginalObjects in WSRR, forming an object graph. In this scenario, when the GovernanceRecord is created, references to all of the OriginalObjects in this object graph, including the root object, are added to the list of governed objects in the GovernanceRecord. This is shown in Figure 5-4.

Ungoverned
XSD
Make Governable

Governed
XSD Governance Record Root Object WSDL GovernedObjects XSD State

WSDL

XSD

Generic Object

Generic Object

Figure 5-4 Governing an object with relationships to other objects

170

WebSphere Service Registry and Repository Handbook

For clarity in the discussions that follow, we will group all of the references from the list of governed objects in the GovernanceRecord and depict them as shown Figure 5-5.

Governance Record Root Object GovernedObjects State

XSD

WSDL

XSD

Generic Object Governed Collection
Figure 5-5 The governed collection

Adding an object to the governed collection
As previously discussed, the governed collection represents all of the OriginalObjects that are related in some way to the root object. It is not possible to explicitly add an OriginalObject in WSRR to a governed collection. Instead, an

Chapter 5. SOA governance enablers

171

OriginalObject is added to the governed collection implicitly. This occurs when a relationship is added from an OriginalObject that is in the governed collection, to an ungoverned OriginalObject object. This is shown in Figure 5-6.
Governance Record Root Object GovernedObjects State Governance Record Root Object GovernedObjects State

XSD

Add Relationship

XSD

WSDL

WSDL

XSD

XSD

Generic Object Governed Collection

XSD

Generic Object

XSD Governed Collection

Figure 5-6 Adding an ungoverned object to a governed collection

In this situation, there is an XSD that is ungoverned. When a relationship is added from the GenericObject in the governed collection to the XSD, the XSD becomes part of the governed collection.

172

WebSphere Service Registry and Repository Handbook

The direction of the relationship that is added is extremely important. Adding a relationship from an OriginalObject that is ungoverned, to one of the OriginalObjects in the governed collection, has no effect on the contents of the governed collection. This is shown in Figure 5-7.
Governance Record Root Object GovernedObjects State Governance Record Root Object GovernedObjects State

XSD

Add Relationship

XSD

WSDL

WSDL

XSD

XSD

Generic Object Governed Collection

XSD

Generic Object Governed Collection

XSD

Figure 5-7 The effect of the direction of a relationship on a governed collection

In this situation, there is an XSD that is ungoverned. When a relationship is added from the XSD to the GenericObject in the governed collection, the XSD does not become part of the governed collection.

Chapter 5. SOA governance enablers

173

It is also not possible for an OriginalObject in WSRR to be in more than one governed collection at any given time. If a relationship is added from an OriginalObject that is in one governed collection, to an OriginalObject that is in another governed collection, then the contents of both governed collections remain unchanged. This is shown in Figure 5-8.
Governance Record Root Object GovernedObjects State Governance Record Root Object GovernedObjects State

XSD

XSD

WSDL

WSDL

XSD

XSD

Generic Object Governed Collection
Figure 5-8 Creating a relationship between two governed objects

XSD Governed Collection

In this situation, a relationship has been defined from the GenericObject in one governed collection to the XSD the other governed collection. Because the target XSD was already in a governed collection, it has not been added to the governed collection containing the GenericObject.

Removing an object from the governed collection
In the same way that it is not possible to explicitly add an OriginalObject to a governed collection, it is also not possible to explicitly remove an OriginalObject from a governed collection. An OriginalObject is removed from the governed

174

WebSphere Service Registry and Repository Handbook

collection implicitly. This occurs when the relationship from an OriginalObject in the governed collection to the object in question is removed. This is shown in Figure 5-9.
Governance Record Root Object GovernedObjects State Governance Record Root Object GovernedObjects State

XSD

Remove Relationship

XSD

WSDL

WSDL

XSD

XSD

Generic Object

Generic Object Governed Collection

XSD

XSD Governed Collection

Figure 5-9 Removing a governed object from a governed collection

In this situation, the relationship from the GenericObject to the XSD is removed. As a result, the XSD is also removed from the governed collection containing the GenericObject.

Chapter 5. SOA governance enablers

175

However, this relationship must be the last such relationship from an OriginalObject in the governed collection to the object in question. If any other relationships exist from an OriginalObject to the object in question, then the object will remain within the governed collection. This is shown in Figure 5-10.

Governance Record Root Object GovernedObjects State

Governance Record Root Object GovernedObjects State

XSD

Remove Relationship

XSD

WSDL

Generic Object

WSDL

Generic Object

XSD

XSD

Governed Collection
Figure 5-10 Multiple relationships to an object in a governed collection

Governed Collection

In this situation, the GenericObject in the governed collection is the target of a relationship from both of the XSDs. Removing the relationship from one of the XSDs to the GenericObject does not remove the GenericObject from the governed collection due to the fact that it is still the target of a relationship from the other XSD. Care must also be taken when removing a relationship to ensure that an entire branch of the object graph is not inadvertently removed. This can occur when a relationship to a non-leaf node in the object graph is removed. If this relationship

176

WebSphere Service Registry and Repository Handbook

is the only relationship tieing the target object to the governed collection, then the entire branch of the object graph extending from the target object is removed from the governed collection. This is shown in Figure 5-11.
Governance Record Root Object GovernedObjects State Governance Record Root Object GovernedObjects State

XSD

Remove Relationship

XSD

WSDL

WSDL

XSD

XSD

Generic Object

Governed Collection

Generic Object

XSD Governed Collection

XSD

Figure 5-11 Removing multiple governed objects from a governed collection

In this situation, the relationship from the XSD to the GenericObject is removed. As a result, the branch of the object graph extending from the GenericObject is removed from the governed collection. In this case, the object graph only consists of the GenericObject and an XSD to which it is related. However, it is a conceivable that, in a real world scenario, the number of objects removed from the governed collection could be far more extensive. It is also important to note that, during the process of removing an OriginalObject from a governed collection, it will not be added to another governed collection. This is the case, even if the object in question is the target of a relationship from an OriginalObject in another governed collection. This is shown in Figure 5-12 on page 178.

Chapter 5. SOA governance enablers

177

Governance Record Root Object GovernedObjects State

Governance Record Root Object GovernedObjects State

WSDL

Generic Object

Generic Object

WSDL

Governed Collection 1
Remove Relationship

Governed Collection 2

Governance Record Root Object GovernedObjects State

Governance Record Root Object GovernedObjects State

WSDL Governed Collection 1

Generic Object

Generic Object

WSDL

Governed Collection 2

Figure 5-12 Removing a governed object from a governed collection

Notice that a relationship exists between the GenericObject in Governed Collection 1 and the GenericObject in Governed Collection 2. When the relationship from the WSDL document to the GenericObject in Governed Collection 1 is removed, the GenericObject becomes ungoverned, even though it is still the target of a relationship from the GenericObject in Governed Collection 2. The reason for this behavior is that an object in WSRR can be the target of multiple relationships from multiple different objects. If, when removing an

178

WebSphere Service Registry and Repository Handbook

OriginalObject from a governed collection, that object is the target of relationships originating from objects in several different governed collections, there would be no way to determine which governed collection to which the object should be added.

Governed collection best practices
Ensuring that the appropriate lifecycles are being applied to the appropriate set of objects is essential when enforcing governance in an SOA environment. WSRR provides you with the means to define the lifecycles that are relevant to the governance processes within your SOA and to apply these lifecycles to configurable governed collections. However, because the contents of a governed collection are determined by examining the relationships that exist within an object graph, care must be taken when making an object governable and adding relationships to, or removing relationships from, objects within a governed collection. The sections that follow describe a number of best practices that should be followed when dealing with governed collections in WSRR.

Determine the order in which you need to make objects governable
The act of making an OriginalObject governable could implicitly add a number of objects to the same governed collection. However, the lifecycle that will be applied to the governed collection might not be appropriate for all of the objects. Before making an object governable, you should use impact analysis in WSRR to examine the object graph that extends from that object to ensure that the lifecycle that will be applied is appropriate for all of the objects that will be added to the governed collection. If there are objects in the object graph for which the lifecycle is not appropriate, you will need to make these objects governable first. This will prevent them from being added to the governed collection of the object in question. Impact analysis is discussed in 5.5, “Impact analysis” on page 213. To illustrate this scenario, consider the default lifecycle that is provided with WSRR. This lifecycle defines operational states that might only be relevant to service artefacts that have some form of implementation. For instance, the deploy and manage states of the default lifecycle might only be relevant to WSDLs that have a corresponding implementation, such as WSDLs that define a Service element. A WSDL that only defines a PortType element, on the other hand, only specifies the service interface and consequently does not have a corresponding implementation. Similarly, the operational states of the default lifecycle might not be applicable to XSDs.

Chapter 5. SOA governance enablers

179

A more suitable lifecycle for these types of objects is shown in Figure 5-13. This lifecycle does not define any operational states and, therefore, could be applied to artefacts in WSRR for which there is no corresponding implementation.

Initial State

Specified Approve Approved Deprecate Deprecated
Final State
Figure 5-13 Sample lifecycle

180

WebSphere Service Registry and Repository Handbook

Now consider the simple object graph shown in Figure 5-14. If the objects in this object graph were loaded into WSRR, it would be logical to apply different lifecycles to certain objects. For instance, it would make sense to apply the lifecycle shown in Figure 5-13 on page 180 to the XSD and the PortType WSDL documents. It might also make sense to apply the default lifecycle to the two Service WSDL documents.

XSD

PortType WSDL

Service WSDL

Service WSDL

Figure 5-14 Sample object graph

However, to ensure that the appropriate lifecycle is applied to each of the objects in the object graph, it is essential to make the objects governable in the correct order.

Chapter 5. SOA governance enablers

181

If you were to make one of the Service WSDL documents governable, applying the default lifecycle, both the PortType WSDL document and the XSD document would also be added to the governed collection. This is shown in Figure 5-15.

Governed Collection

XSD

PortType WSDL Governance Record Root Object GovernedObjects State Service WSDL Service WSDL

Figure 5-15 Applying the same lifecycle

But, as we have already discussed, the default lifecycle that is applied to the Service WSDL document might not be appropriate for the PortType WSDL document and the XSD document.

182

WebSphere Service Registry and Repository Handbook

In order to ensure that the sample lifecycle can be applied to the PortType WSDL document and the XSD document, these documents need to be made governable before the Service WSDL document. Since the PortType WSDL document imports the XSD document, this can be achieved by making the PortType WSDL document governable and applying the sample lifecycle. This is shown in Figure 5-16.

Governed Collection

XSD

PortType WSDL Governance Record Root Object GovernedObjects State Service WSDL Service WSDL

Figure 5-16 Applying the sample lifecycle first

Chapter 5. SOA governance enablers

183

The first Service WSDL document can be then be made governable, applying the default lifecycle, without affecting the governed collection of the PortType WSDL document and the XSD document. This is shown in Figure 5-17.

Governed Collection
Governance Record Root Object GovernedObjects State PortType WSDL Governance Record Root Object GovernedObjects State Service WSDL Service WSDL

XSD

Governed Collection
Figure 5-17 Applying the default lifecycle to the Service WSDL document

Of course, in a real world situation, it is unlikely that all of these artefacts would have been loaded into WSRR at the same point in time. It is more realistic to suggest that the underlying data model defined by the XSD document would be designed first and then approved for use in the SOA environment. The service interface defined by the PortType WSDL document would then be designed and also approved for use in the SOA environment. Finally, the service implementations would be developed and deployed, but not necessarily at the same time.

184

WebSphere Service Registry and Repository Handbook

In this scenario, it is quite conceivable that each of the artefacts in our sample object graph would be loaded into WSRR at different points in time and, consequently, would be contained within different governed collections. This is shown in Figure 5-18.

Governance Record Root Object GovernedObjects State

Governed Collection

Governance Record Root Object

XSD

GovernedObjects State

Governed Collection
PortType WSDL

Governance Record Root Object GovernedObjects State Service WSDL Service WSDL

Governance Record Root Object GovernedObjects State

Governed Collection

Governed Collection

Figure 5-18 More realistic governed collection membership

Examine the source and target of a relationship before creation
The act of creating a relationship between two objects may implicitly add the target of the relationship to the governed collection of the source object. Before you create a relationship between two objects in WSRR, you should examine the source and target objects of the relationship to determine what, if any, side effects will occur. The questions that you should ask are as follows: Is the source object governed? An object will only be added to a governed collection if it is the target of a relationship from an OriginalObject that is already governed. If the source object is not governed, then adding the relationship will not add the target object to the governed collection.

Chapter 5. SOA governance enablers

185

What is the type of the source object in the relationship? An object will only be added to a governed collection if it is the target of a relationship from an OriginalObject that is already governed. If the source object is not an OriginalObject, then adding the relationship will not add the target object to the governed collection. Is the target object governed? The target object of a relationship will only be added to the governed collection of the source object if it is not already in a governed collection. If the target object is already governed, then adding the relationship will not add the target object to the governed collection of the source object. What is the type of the target object in the relationship? The target object of a relationship will only be added to the governed collection of the source object if it is an OriginalObject. If the target object is not an OriginalObject, then adding the relationship will not add the target object to the governed collection. Note: Derived objects can only ever be in the same governed collection as the physical document object from which they were parsed. Does the target object define relationships to other OriginalObjects? The target object of a relationship may itself define a number of relationships to other OriginalObjects in WSRR. Assuming that the target object is added to the governed collection of the source object as a result of creating the relationship, any of the OriginalObjects to which it is related may also be added to the governed collection of the source object. You must examine the object graph for the target object to ensure that any OriginalObjects that are added to the governed collection of the source object are of the appropriate type for the lifecycle that is being applied.

Examine the target of a relationship before deletion
The act of deleting a relationship between two objects may implicitly remove the target of the relationship from the governed collection of the source object. Before you delete a relationship between two objects in WSRR, you should examine the target object of the relationship to determine what, if any, side effects will occur. The questions that you should ask are as follows: Does the target object define relationships to other OriginalObjects? The target object of a relationship may itself define a number of relationships to other OriginalObjects in WSRR. Assuming that the target object is removed from the governed collection of the source object as a result of deleting the relationship, any of the OriginalObjects to which it is related may also be

186

WebSphere Service Registry and Repository Handbook

removed from the governed collection of the source object. You must examine the object graph for the target object to ensure that any OriginalObjects that are removed from the governed collection of the source object do not require the relevant lifecycle to be applied.

5.3 WSRR security
WebSphere Service Registry and Repository makes use of the security mechanisms provided by WebSphere Application Server to ensure that only authenticated users are able to access the various interfaces that it exposes. However, it also extends these capabilities to allow more fine grained access control to the information that it stores. These capabilities are discussed in the sections that follow.

5.3.1 J2EE security roles
As a J2EE application, WebSphere Service Registry and Repository defines a number of security roles within its’ deployment descriptors. When global security is enabled within WebSphere Application Server these J2EE security roles are used to restrict who can access WSRR at runtime. In other words, WebSphere Application Server uses these roles to enforce standard J2EE security within the relevant J2EE containers at runtime. The J2EE security roles defined by WSRR are: User Administrator In order to be able to access the WSRR Web user interface, or to invoke methods on the WSRR API, a user must at least be mapped to the J2EE User role. By default the special subject AllAuthenticatedUsers is mapped to both the User and Administrator roles during WSRR installation. Mapping the AllAuthenticatedUsers special subject to a role maps any user that has authenticated to WebSphere Application Server to that role. Therefore, in a default WSRR installation, all users who are able to authenticate to WSRR are able to perform any action against WSRR.

Chapter 5. SOA governance enablers

187

Note: It is recommended that you modify the relevant environment script prior to installation to ensure that only those users or groups who are permitted to access WSRR are mapped to the relevant roles. However, note that the Server user ID that is configured in your WebSphere Application Server environment must be mapped to the Administrator J2EE security role in WSRR. If this mapping is not defined, WSRR will fail to start when running in a WebSphere environment where security has been enabled.

5.3.2 User defined roles
The access control provided by the use of J2EE security roles within WSRR is very coarse grained. It is only able to control who can access the WSRR Web user interface or the WSRR API methods themselves. It is not able to control access to the objects on which the WSRR API methods operate. In order to provide more fine grained access control functionality, WSRR provides an authorization component that allows additional roles to be defined and for permissions to be added to these roles. User or Group principals must be explicitly mapped to these roles in order for the principal to have the entitlement (permissions) associated with the role. When a method is invoked on the API, WSRR uses the authorization component to determine whether the user is authorized to perform the requested action on the target object or objects. Therefore, in a secure environment each method invocation on the WSRR API results in the user being authorized twice, once for standard J2EE role based access control and once for the more fine grained access control provided by WSRR. This is shown in Figure 5-19.

Figure 5-19 Role based authorization within WSRR

188

WebSphere Service Registry and Repository Handbook

Note: Any roles that are defined to the authorization component in WSRR are completely separate from the J2EE security roles defined within the deployment descriptors for the WSRR application. At runtime WebSphere Application Server is only aware of the Administrator and User J2EE security roles. To simplify the installation and configuration of WSRR, the installation process creates roles within the WSRR authorization component that match the J2EE security roles. That is, the installation process creates an Administrator and a User role within the WSRR authorization component. It also maps the same users and groups to these roles that are mapped to the J2EE security roles.

5.3.3 Permissions
A permission within WSRR encapsulates an action and the target objects on which it can be performed. Adding a permission to a role grants the users who are mapped to that role the permission to perform the specified action on the specified target objects. This is shown in Figure 5-20.

Role
Name: Administrator

Permission Permission Permission Name: CreateWSDLPermission
Name: CreateWSDLPermission Action: srrCreate Name: CreateWSDLPermission Action: srrCreate Target: /WSRR/WSDLDocument Action: srrCreate Target:: /WSRR/WSDLDocument

Figure 5-20 Roles and permissions in WSRR

The sections that follow describe the properties that can be defined on a permission within WSRR.

Chapter 5. SOA governance enablers

189

Name
The name of the permission is used to identify the permission within WSRR. The name of a permission must be unique within the context of a specific role. It is possible, therefore, to create permissions with the same name on different roles. Note: It is recommended that you use unique permission names for all of the permissions that you define to the WSRR authorization component.

Action
The action property for a permission specifies the operation that the permission authorizes. Table 5-2 describes the actions that can be specified for permissions in WSRR.
Table 5-2 Valid actions for WSRR permissions Name Description

srrCreate srrRetrieve

Permissions that specify the srrCreate action authorize the target objects to be created in WSRR. Permissions that specify the srrRetrieve action authorize the target objects to be retrieved from WSRR. Permissions that specify this action can be used to control access to objects that are retrieved from WSRR using both the retrieve and query methods on the WSRR API. When a user is performing a query against WSRR, any objects that they are not authorized to see will not be included in the query results. Permissions that specify the srrUpdate action authorize the target objects to be updated within WSRR. This includes updates to both the metadata and the content of the target objects. Permissions that specify the srrDelete action authorize the target objects to be deleted from WSRR. Permissions that specify the srrTransition action authorize the target objects to be transitioned within WSRR. Permissions that specify the srrManageGov action authorize the target objects to be governed, or to have governance removed, in WSRR.

srrUpdate

srrDelete srrTransition srrManageGov

190

WebSphere Service Registry and Repository Handbook

Note: The permissions that are defined using these actions are completely independent of each other. For example, defining a permission to allow a specific type of artefact to be deleted does not imply that permission to update that type of artefact is automatically granted.

Target
The target property for a permission specifies the objects in WSRR to which the permission applies. The target is specified using the WSRR query language. As discussed in 3.6, “XPath” on page 99, the WSRR query language is based on a subset of XPath 2.0 with support for Service Data Objects (SDO) properties, relationships, and some additional functions to support querying by classification. A simple example of a query expression is shown here: /[] The element defines the type of object to which the permission applies and must match one of the types described in Chapter 3, “Information model” on page 79. The type specified can appear at any point in the WSRR information model type hierarchy. For instance, if you specified a of /WSRR/BaseObject for a permission then that permission would apply to all objects in WSRR, since all of the object types in the WSRR information model extend BaseObject. If, however, you specified a of /WSRR/WSDLDocument then that permission would only apply to objects of type WSDLDocument in WSRR, since this type has no sub-types. Note: The element must always be prefixed with /WSRR.

Note: When defining permissions that specify the srrCreate or srrDelete actions, the type specified must be one of the following: – – – – – – – – – – GenericObject OriginalObject PolicyDocument SCAModule WSDLDocument XMLDocument XSDDocument QueryObject GraphQuery PropertyQuery

Chapter 5. SOA governance enablers

191

The element defines additional constraints that can be used to further restrict the objects in WSRR to which the permission applies. Table 5-3 shows some example filter expressions that can be used when specifying the target of a permission. More complex filter expressions can be specified by combining multiple expressions using the AND or OR operators. Up to five expressions can be combined into a single, more complex, filter expression using this mechanism.
Table 5-3 Example filter expressions Expression @property Example @foo Description This filter expression filters the target objects to those that contain the specified property. The example shown filters the target objects to those that have a property named ‘foo’. This filter expression filters the target objects to those that contain the specified property with the specified value. The example shown filters the target objects to those that have a property named ‘foo’ with a value of ‘bar’. The following restrictions apply when specifying a filter expression of this form: Only single valued properties are supported Only the equality operator = is supported classifiedByAnyOf classifiedByAnyOf( 'classificationURI_1', 'classificationURI_2' ) classifiedByAllOf( 'classificationURI_1', 'classificationURI_2' ) This filter expression filters the target objects to those that are classified by any of the specified classification URIs. The example shown filters the target objects to those that are classified by ‘classificationURI_1’ or ‘classificationURI_2’. This filter expression filters the target objects to those that are classified by all of the specified classification URIs. The example shown filters the target objects to those that are classified by ‘classificationURI_1’ and ‘classificationURI_2’.

@property=’value’

@foo=’bar’

classifiedByAllOf

Default permissions
WSRR adopts a permissive approach to access control in the authorization component. This means that access to all of the artefacts in WSRR is unrestricted by default. This approach allows users to continue to access objects in WSRR when security is enabled, without the need to define permissions that explicitly grants them access to these objects.

192

WebSphere Service Registry and Repository Handbook

However, once a role is explicitly granted access to a set of target objects in WSRR, all other roles are implicitly denied access to that set of objects. In this situation, in order for other roles to access the same set of target objects, each role must also be explicitly granted access to the set of objects. For example, if you added a permission to the Administrator role that granted its members permission to create WSDLDocument objects in WSRR, all other roles that were defined to the authorization component would no longer be able to create WSDLDocument objects. In order to grant users in a Developer role the permission to create WSDLDocuments, you would need to add the same permission to this role.

Administrator permissions
WSRR defines a set of default permissions that are used to control access to governed objects. Table 5-4 describes the default permissions that are granted to the Administrator role.
Table 5-4 Administrator default permissions Permission Name: Action: Target: GovernedCreatePermission srrCreate /WSRR/BaseObject[ classifiedByAnyOf( 'a#State' )] Description This permission authorizes WSRR Administrators to create objects that are classified by one of the states defined by the WSRR default lifecycle. This is most likely to occur when using the createGovernable method on the WSRR Governance API. Granting this permission to the Administrator role implicitly denies other roles the permission to perform this action on the target objects. This permission authorizes WSRR Administrators to retrieve objects from WSRR that are classified by one of the states defined by the WSRR default lifecycle. Granting this permission to the Administrator role implicitly denies other roles the permission to perform this action on the target objects. However, limited capability to retrieve the target objects is granted to the User role by the GovernedUserRetrievePermissionA and GovernedUserRetrievePermissionB permissions. These permissions are described in Table 5-5 on page 195.

Name: Action: Target:

GovernedRetrievePermission srrRetrieve /WSRR/BaseObject[ classifiedByAnyOf( 'a#State' )]

Chapter 5. SOA governance enablers

193

Permission Name: Action: Target: GovernedUpdatePermission srrUpdate /WSRR/BaseObject[ classifiedByAnyOf( 'a#State' )]

Description This permission authorizes WSRR Administrators to update objects in WSRR that are classified by one of the states defined by the WSRR default lifecycle. Granting this permission to the Administrator role implicitly denies other roles the permission to perform this action on the target objects. However, limited capability to update the target objects is granted to the User role by the GovernedUserUpdatePermission permission. This permission is described in Table 5-5 on page 195. This permission authorizes WSRR Administrators to delete objects from WSRR that are classified by one of the states defined by the WSRR default lifecycle. Granting this permission to the Administrator role implicitly denies other roles the permission to perform this action on the target objects. Therefore, by default, once an object in WSRR is governed it can only be deleted by an Administrator. This permission authorizes WSRR Administrators to transition the lifecycle state of any type of object in WSRR from one state to another. Granting this permission to the Administrator role implicitly denies other roles the permission to perform this action on any type of object in WSRR. Therefore, by default, only an Administrator is able to transition the lifecycle state of an object in WSRR from one state to another. This permission authorizes WSRR Administrators to make any type of object, or collection of objects, governable and to remove governance from any type of object, or collection of objects, in WSRR. Granting this permission to the Administrator role implicitly denies other roles the permission to perform these actions on any type of object in WSRR. Therefore, by default, only an Administrator is able to make an object, or collection of objects, governable or remove governance from an object, or collection of objects, in WSRR.

Name: Action: Target:

GovernedDeletePermission srrDelete /WSRR/BaseObject[ classifiedByAnyOf( 'a#State' )]

Name: Action: Target:

GovernanceTransitionPermission srrTransition /WSRR/BaseObject

Name: Action: Target:

GovernanceManagePermission srrManageGov /WSRR/BaseObject

a. Where is http://www.ibm.com/xmlns/prod/serviceregistry/6/0/governance/DefaultLifecycle

194

WebSphere Service Registry and Repository Handbook

User Permissions
In isolation, the default permissions that are granted to the Administrator role would prevent normal WSRR users from accessing governed objects. In order to grant the User role a restricted level of access to governed objects, WSRR defines a set of default permissions for this role. Table 5-5 describes the default permissions that are granted to the User role.
Table 5-5 User default permissions Permission Name: Action: Target: GovernedUserUpdatePermission srrUpdate /WSRR/BaseObject[ classifiedByAnyOf( 'a#State1', 'a#State2', )] GovernedRetrievePermissionA srrRetrieve /WSRR/BaseObject[ classifiedByAnyOf( 'a#State1', 'a#State2', )] GovernedRetrievePermissionB srrRetrieve /WSRR/BaseObject[ classifiedByAnyOf( 'a#State3', 'a#State4', )] This permission authorizes WSRR Users to retrieve objects from WSRR that are classified by the lifecycle state Deploy (State3) or Manage (State4). This permission authorizes WSRR Users to retrieve objects from WSRR that are classified by the lifecycle state Model (State1) or Assemble (State2). Description This permission authorizes WSRR Users to update objects in WSRR that are classified by the lifecycle state Model (State1) or Assemble (State2).

Name: Action: Target:

Name: Action: Target:

a. Where is http://www.ibm.com/xmlns/prod/serviceregistry/6/0/governance/DefaultLifecycle

Note: The GovernedRetrievePermissionA and GovernedRetrievePermissionB permissions do not grant members of the User role the authority to retrieve objects from WSRR that are in the Created (InitialState1) or Retired (FinalState1) lifecycle states.

Chapter 5. SOA governance enablers

195

5.3.4 Extensible Access Control Markup Language (XACML)
The Extensible Access Control Markup Language is an XML based language that is designed to express security rules, policies and policy sets that define the access rights of users (subjects) to resources. The goal of XACML is to provide a common policy language that allows organizations to enforce all of the elements of their security policy across all of the components of their IT infrastructure. The XACML specifications were developed through a collaborative effort involving various companies including IBM, Sun™ Microsystems™, and Entrust. XACML was ratified by the Organization for the Advancement of Structured Information Standards (OASIS) in February 2003. The XACML specification can be found here: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xacml The WSRR authorization component uses XACML to represent the security policies that have been defined to it. It generates XACML policy files that are then stored in WSRR and are used during application startup to initialize the WSRR authorization component with the current security policies. The WSRR authorization component makes use of two policy files and these are discussed in more detail in the sections that follow.

Role mapping file
The WSRR authorization roles, and the User and Group principals that have been mapped to these roles, are defined in the role mapping XACML file. This file is read from WSRR during application startup and is used to initialize the role mappings within the WSRR authorization component. The role mapping file is stored in WSRR as configuration document called SrrAuthzRoleMappingXacml of type XACML.

Authorization policy file
The WSRR authorization policy is defined in the authorization policy XACML file. This file defines the mapping between permissions and the roles to which they have been added. This file is read from WSRR during application startup and is used to initialize the authorization policy within the WSRR authorization component. The authorization policy file is stored in WSRR as a configuration document called SrrAuthCheckedPolicyXacml of type XACML.

196

WebSphere Service Registry and Repository Handbook

Note: While it is possible to modify these XACML files directly and load them into WSRR, it is not recommended. The WSRR administration MBean provides all of the operations that are required in order manipulate the contents of these files, as follows: – – – – – – – – – – – – – addRole removeRole addPrincipalToRole removePrincipalFromRole getRolesWithPermissions removePermissionFromRole removeAllRolePermissions removeAllRoles addPermissionToRole addPermissionToRole2 getPermissionsForRole persistPolicy persistRoleMappings

See Chapter 8, “Administering WSRR” on page 281 for more information about using the administration MBean.

5.4 WSRR plugins
WebSphere Service Registry and Repository provides system programming interfaces that allow you to implement code that can invoked during the standard processing performed by WSRR. Classes written to these interfaces are referred to as WSRR plugins. Plugins enable you to implement code that enforces the governance processes that are defined by the business design within your SOA environment. There are currently two types of plugin defined within WebSphere Service Registry and Repository, as follows: Validators Notifiers Validators are invoked prior to persisting the changes for the relevant API method within WSRR. Notifiers are invoked at the end of the relevant API method call. The invocation sequence for a single validator and a single notifier is shown in Figure 5-21 on page 198. If multiple validators or notifiers have been configured within WSRR, separate calls to each validator or notifier in the chain may be made as a result of a single call to the WSRR API.

Chapter 5. SOA governance enablers

197

Figure 5-21 Validator and notifier invocation

Note: The implementation classes for both validation and notification plugins are able to make use of the WSRR API at runtime. However, they MUST avoid creating instances of the ServiceRegistrySession or ServiceRegistryGovernance EJB’s within their constructors. When an instance of one of these EJBs is created, it instantiates the set of plugin instances that it will use to perform validation and notification for each method invoked. If the constructors for any of the plugins create an instance of one these EJBs, an infinite loop will occur. For this reason, plugins should delay creating instances of these EJBs until the instance is actually required (lazy initialization).

Note: Both validation and notification plugins are invoked synchronously, on the same thread of execution as the WSRR EJB, as shown in Figure 5-21. You should avoid performing long running operations in your plugin implementation to ensure that the WSRR EJB method call completes in a reasonable amount of time and the EJB thread is returned to the ORB thread pool.

5.4.1 Validators
Validation plugins are invoked at the beginning of calls to certain WSRR API methods. They provide you with an opportunity to validate that the operation being performed on the objects within WSRR complies with the policies that are defined within your SOA environment. For instance, there may be a policy within

198

WebSphere Service Registry and Repository Handbook

your SOA environment that states that all Web services deployed to the SOA must be compliant with Version 1.0 of the WS-I Basic Profile. A validator is also able to modify the objects that are passed to WSRR. This provides you with an opportunity to define additional metadata on the objects before they are persisted to the database. This is the approach taken in the template validator that is provided with WSRR. This validator is used when creating instances of an OriginalObject from a template. The template validator modifies the OriginalObject during creation to add the properties and relationships that are defined on the relevant template.

Validator interfaces
The validator interfaces defined by the WSRR API are shown in Figure 5-22.

Figure 5-22 Validator interfaces

Notice that there are actually two validator interfaces defined by the API. The ServiceRegistryValidator interface defines the methods that you should implement if you require validation to occur as a result of invoking operations on the WSRR Core API. The ServiceRegistryGovernanceValidator interface extends the ServiceRegistryValidator interface and defines additional methods that you should implement if you require validation to occur as a result of invoking operations on the WSRR Governance API.

Chapter 5. SOA governance enablers

199

Note: The methods that are defined by the ServiceRegistryGovernanceValidator interface are only invoked for objects that are currently part of a governed lifecycle. That is, they will only be invoked on a governance validator as a result of invoking a WSRR Governance API method on a governed object.

Create method
The create method is invoked before an instance of an OriginalObject is created in WSRR. The create method is passed a reference to the OriginalObject that is about to be created in order to perform the required validation tasks. The validator is able to modify this object to ensure that it conforms with the relevant governance policies that are in place before it returns from the create method. The create method must return a ServiceRegistryStatus object to indicate whether the validation process succeeded or failed. If the create method returns a SUCCESS or WARNING return code in the ServiceRegistryStatus object, WSRR will persist the new object. If the create method returns an ERROR return code in the ServiceRegistryStatus object, WSRR will throw a ServiceRegistryValidationException from the invoked WSRR API method and the new object will not be created in WSRR.

Update method
The update method is invoked before an existing OriginalObject within WSRR is updated. The update method is passed references to the object in its current state (oldObject) and its new state (newObject) in order to perform the required validation tasks. The validator is able to modify the new state (newObject) of the object to ensure that it conforms with the relevant governance policies that are in place before it returns from the update method. The update method must return a ServiceRegistryStatus object to indicate whether the validation process succeeded or failed. If the update method returns a SUCCESS or WARNING return code in the ServiceRegistryStatus object, WSRR will persist the changes to the OriginalObject. If the update method returns an ERROR return code in the ServiceRegistryStatus object, WSRR will throw a ServiceRegistryValidationException from the invoked WSRR API method and the changes to the OriginalObject will not be persisted to WSRR.

200

WebSphere Service Registry and Repository Handbook

Delete method
The delete method is invoked before an existing OriginalObject within WSRR is deleted. The delete method is passed a reference to the object that is about to be deleted in order to perform the required validation tasks. For example, it may be necessary to ensure that the object to be deleted is not the target of any relationships that have been defined on other objects within WSRR. The delete method must return a ServiceRegistryStatus object to indicate whether the validation process succeeded or failed. If the delete method returns a SUCCESS or WARNING return code in the ServiceRegistryStatus object, WSRR will delete the OriginalObject. If the delete method returns an ERROR return code in the ServiceRegistryStatus object, WSRR will throw a ServiceRegistryValidationException from the invoked WSRR API method and the OriginalObject will not be deleted from WSRR.

Transition method
The transition method is invoked before a governed object, or governed object collection, is transitioned to a new governance lifecycle state. The transition method is passed a reference to the object whose governance lifecycle state is being changed and the transition that is being performed. The validator is able to modify the governed object, or governed object collection, to ensure that it conforms with the relevant governance policies that are in place before it returns from the transition method. Note: If the target of the transition is a governed object collection then the OriginalObject passed to the transition method is the root object of the governed object collection. The transition method must return a ServiceRegistryStatus object to indicate whether the validation process succeeded or failed. If the transition method returns a SUCCESS or WARNING return code in the ServiceRegistryStatus object, WSRR will modify the governance lifecycle state of the specified OriginalObject. If the transition method returns an ERROR return code in the ServiceRegistryStatus object, WSRR will throw a ServiceRegistryValidationException from the transition method that was invoked on the WSRR Governance API and the governance lifecycle state of the OriginalObject will not be modified within WSRR.

Chapter 5. SOA governance enablers

201

Note: If a transition completes successfully the governance lifecycle state of the governed object, or governed object collection, is updated. As a consequence of these updates, the update method of any other registered validators may be invoked.

Validate method
The validate method is invoked as the result of an explicit call to the validate method on the WSRR Governance API. The validate method is passed a reference to the governed object, or governed object collection, that is to be validated. The validate method must return a ServiceRegistryStatus object to indicate whether the validation process succeeded or failed. If the validate method returns a SUCCESS or WARNING return code in the ServiceRegistryStatus object, WSRR considers the validation to be a success and processing within the WSRR client application continues as normal. If the transition method returns an ERROR return code in the ServiceRegistryStatus object, WSRR considers the validation to have failed and will throw a ServiceRegistryValidationException from the validate method that was invoked on the WSRR Governance API. Note: Invoking the validate method on the WSRR Governance API will cause the validate method on all of the registered governance validators to be invoked for the governed object or governed object collection. However, the validate method on the WSRR Governance API is simply a convenience method that forces the validators to be invoked. Any modifications made by a validator to the governed object, or governed object collect, will not be persisted to WSRR.

The ServiceRegistryStatus object
As discussed previously, the ServiceRegistryStatus object is primarily used by a validator method to indicate the success or failure of that method. This is achieved by setting the return code on the ServiceRegistryStatus object to one of the constant values defined by the ServiceRegistryStatus class, as follows: SUCCESS WARNING ERROR The default value of the return code for new instances of ServiceRegistryStatus objects is SUCCESS. The return code for a ServiceRegistryStatus object will

202

WebSphere Service Registry and Repository Handbook

remain set to the highest value it is given. For example, if the return code for an instance of a ServiceRegistryStatus object is set to ERROR and then subsequently set to SUCCESS or WARNING, the return code for that object will remain at the ERROR level. If you need to reduce the level of the return code, you must create a new instance of a ServiceRegistryStatus object and set the required return code value.

ServiceRegistryStatus diagnostics
Validator methods should not throw exceptions to indicate that validation has failed. However, a validator method may need to provide more information about the failure of the validation process, particularly in situations where this process is complex. If a validator method needs to provide more information about the results of the validation process, it can add diagnostic objects or messages to the ServiceRegistryStatus object that is returned using the methods shown in Example 5-2.
Example 5-2 ServiceRegistryStatus diagnostic methods

public void addDiagnostic(int returnCode, Object message) public void addException(Exception ex) Both of these methods add the diagnostic information to an ordered list of diagnostics that is maintained within the ServiceRegistryStatus object instance. Note: Invoking the addException(Exception ex) method on a ServiceRegistryStatus instance will automatically set the return code for that instance to ERROR.

5.4.2 Notifiers
Notification plugins are invoked at the end of calls to certain WSRR API methods. They provide you with an opportunity to perform various post processing tasks based on the result of the operation that was requested. For instance, there may be a policy within your SOA environment that states that an audit trail must be maintained for all interactions with WSRR.

Notifier interfaces
The notifier interfaces defined by the WSRR API are shown in Figure 5-23 on page 204.

Chapter 5. SOA governance enablers

203

Figure 5-23 Notifier interfaces

Notice that there are actually two notifier interfaces defined by the API. The ServiceRegistryNotifier interface defines the methods that you should implement if you require notification to occur as a result of invoking operations on the WSRR Core API. The ServiceRegistryGovernanceNotifier interface extends the ServiceRegistryNotifier interface and defines additional methods that you should implement if you require notification to occur as a result of invoking operations on the WSRR Governance API. Note: The methods that are defined by the ServiceRegistryGovernanceNotifier interface are only invoked for objects that are currently part of a governed lifecycle. That is, they will only be invoked on a governance validator as a result of invoking a WSRR Governance API method on a governed object.

Note: There is no validate method defined on the ServiceRegistryGovernanceNotifier interface. This is due to the fact that the validate method on the WSRR Governance API is simply a convenience method that forces the validators to be invoked.

Create method
The create method is invoked after an instance of an OriginalObject has been created in WSRR, or after an attempt to create an instance of an OriginalObject has failed. The create method is passed the following parameters: A reference to the object that was created, or whose creation failed. A boolean success flag that indicates whether the create method succeeded or failed. True indicates that the object was created successfully. False indicates that the creation of the object failed.

204

WebSphere Service Registry and Repository Handbook

An exception parameter that indicates the cause of the failure if the creation of the object failed. The value of this parameter will be null if the creation of the object succeeded.

Update method
The update method is invoked after an object stored in WSRR has been updated, or after an attempt to update an object in WSRR has failed. The update method is passed the following parameters: A reference to the original state of the object that was updated, or whose update failed. A reference to the new state of the object that was updated, or whose update failed. A boolean success flag that indicates whether the update method succeeded or failed. True indicates that the object was updated successfully. False indicates that the update of the object failed. An exception parameter that indicates the cause of the failure if the update of the object failed. The value of this parameter will be null if the update of the object succeeded. Note: The type of the oldObject and newObject parameters that are passed to this method is BaseObject. This means that the update method on a notifier can be invoked when any type of object within WSRR is updated, not just OriginalObjects.

Delete method
The delete method is invoked after an instance of an OriginalObject has been deleted from WSRR, or after an attempt to delete an instance of an OriginalObject has failed. The delete method is passed the following parameters: A reference to the object that was deleted, or whose deletion failed. A boolean success flag that indicates whether the delete method succeeded or failed. True indicates that the object was deleted successfully. False indicates that the deletion of the object failed. An exception parameter that indicates the cause of the failure if the deletion of the object failed. The value of this parameter will be null if the deletion of the object succeeded.

Transition method
The transition method is invoked after a governed object, or governed object collection, has been transitioned to a new governance lifecycle state, or after an

Chapter 5. SOA governance enablers

205

attempt to transition to a new governance lifecycle state has failed. The transition method is passed the following parameters: The URI of the transition that was performed or failed. A reference to the original state of the governed object, or governed object collection, whose governance lifecycle state was being transitioned, or whose transition failed. A reference to the new state of the governed object, or governed object collection, whose governance lifecycle state was being transitioned, or whose transition failed. A boolean success flag that indicates whether the transition method succeeded or failed. True indicates that the governance lifecycle state of the governed object, or governed object collection, was modified successfully. False indicates that the transition failed. An exception parameter that indicates the cause of the failure if the transition of the governed object, or governed object collection, failed. The value of this parameter will be null if the transition of the governed object, or governed object collection, succeeded. Note: If the target of the transition is a governed object collection then the OriginalObject passed to the transition method is the root object of the governed object collection.

5.4.3 Packaging plugins
As discussed previously, a plugin is simply a Java class that implements one of the plugin interfaces defined within the WSRR API. Plugin implementations must be made available to WSRR on the classpath at runtime. The recommended way to achieve this is to package all of the classes required by a plugin into a JAR file and to add this JAR file to the classpath of a suitably configured shared library within the WebSphere Application Server instance on which WSRR is running. The deployment of WSRR plugins is discussed in more detail in 13.3.3, “Deploying custom plugins” on page 491. To simplify the plugin installation and configuration process, multiple plugins can be packaged into the same JAR file. However, it may also be desirable to package each plugin and its dependent classes into separate JAR files to allow more granularity at deployment time.

206

WebSphere Service Registry and Repository Handbook

5.4.4 Configuring plugins
Validation and notification plugins are configured in WSRR using configuration properties files. These configuration properties files are stored within WSRR itself. Initial versions of these configuration properties files are loaded into WSRR during the installation process in order to configure the default validation and notification plugins that are required by WSRR. In order for your custom validation and notification plugins to be invoked at runtime, you must modify the relevant configuration properties file within WSRR. Since these configuration properties files form part of the administration configuration of WSRR, the administration MBean must be used in order to retrieve and update the relevant files. Typically you will use the retrieveConfiguration operation on the administration MBean to retrieve a configuration properties file. You then need to modify the retrieved file to include the entries for the relevant plugins. You then use updateConfiguration operation on the administration MBean to load the modified configuration properties file back into WSRR. In order for the configuration changes to take effect, you will need to restart the application server on which WSRR is running. The administration MBean is described in more detail in 8.5, “Administering WSRR using JMX” on page 292. Table 5-6 shows the parameters that should be passed to the administration MBean when invoking the retrieveConfiguration or updateConfiguration operations to work with the configuration properties files for validation or notification plugins.
Table 5-6 MBean operation parameters Plugin type Validator Notifier Configuration Name ValidationProperties NotificationProperties Configuration type PLUGIN_PROPERTIES PLUGIN_PROPERTIES System configuration true true

Validator plugin properties
The configuration properties file for validation plugins uses the standard Java format for properties files. The properties within the file are specified as key/value pairs. The set of keys that can be used within the configuration properties file for validation plugins is shown in Table 5-7 on page 208.

Chapter 5. SOA governance enablers

207

Table 5-7 Valid property keys for defining validation plugins Configuration properties key validators Description Validation plugins listed against this key will be invoked as a result of the relevant WSRR API methods being invoked on any type of object. Validation plugins listed against this key will be invoked as a result of the relevant WSRR API methods being invoked on objects of the specified type. Currently, only OriginalObject sub-classes can be specified, as follows:

validators.

– – – – – validators.classification. WSDLDocument XSDDocument PolicyDocument XMLDocument GenericObject

Validation plugins listed against this key will be invoked as a result of the relevant WSRR API methods being invoked on objects that are classified by the specified classification URI. Validation plugins listed against this key will be invoked as a result of the relevant WSRR API being invoked on an object that is part of a governed lifecycle. Any validation plugins listed against this key must implement the ServiceRegistryGovernanceValidator interface.

governanceValidators

Note: Due to the limitations of the Java properties file, any classification URI specified as part of a key within the file must not contain any ‘:’ (colon) characters. These should simply be omitted from any classification URI specified. The values specified within the configuration properties file must be a comma separated list of fully qualified class names for the required validation plugins. As discussed in 5.4.3, “Packaging plugins” on page 206, the implementation classes

208

WebSphere Service Registry and Repository Handbook

for any validation plugins that are specified in the configuration properties file must be made available to WSRR on the classpath at runtime. The default configuration properties file for validation plugins that is loaded into WSRR during the installation process is shown in Example 5-3.
Example 5-3 Default configuration properties file for validation plugins

# These validators are called for all document types validators=com.ibm.sr.api.SRTemplateValidator # These validators are called for governed objects only governanceValidators=com.ibm.sr.governance.api.SRGovernanceValidator As you can see, this configuration properties file defines two default validation plugins, as follows: com.ibm.sr.api.SRTemplateValidator This validation plugin provides support for applying templates to instances of OriginalObjects during their creation. com.ibm.sr.governance.api.SRGovernanceValidator This validation plugin ensures that any updates to governed objects within WSRR do not modify governance related metadata. Note: The SRTemplateValidator and SRGovernanceValidator plugins are system plugins that are required by WSRR at runtime. These validators should not be removed when you are modifying the configuration properties file for validation plugins. Example 5-4 provides an example of how the configuration properties file for validation plugins can be updated to include two additional validators. Notice that the com.ibm.itso.plugins.ITSODefaultValidator plugin has been added to the list of the plugins for the validators key. Also, the com.ibm.itso.plugins.WSIComplianceValidator has been added against the validators.WSDLDocument key. This validator will only be invoked when WSRR API methods are invoked on objects of type WSDLDocument.
Example 5-4 Modified configuration properties file for validation plugins

# These validators are called for all document types validators=com.ibm.sr.api.SRTemplateValidator,com.ibm.itso.plugins.ITSO DefaultValidator # These validators are called for WSDLDocuments only validators.WSDLDocument=com.ibm.itso.plugins.WSIComplianceValidator

Chapter 5. SOA governance enablers

209

# These validators are called for governed objects only governanceValidators=com.ibm.sr.governance.api.SRGovernanceValidator

Validator chains
For any given call to the WSRR API, several validators may need to be invoked to enforce various aspects of the governance policies defined within your SOA environment. WSRR allows multiple validators to be configured for any given type of object. This enables you to implement each validator such that it enforces just a single aspect of your overall governance policy. Combinations of validators can then be deployed and configured to WSRR to build up the overall governance policy that is required in your SOA environment. When a call is made to one of the relevant WSRR API methods at runtime, WSRR determines which validators need to be invoked. Using the information contained within the configuration properties file for validation plugins, WSRR builds a list of the applicable validators and then invokes the relevant method on each validator in turn. The list of validators that need to be invoked for a specific API method call is known as a validator chain. The order in which the validators are added to the validator chain is as follows: 1. If the target of the WSRR API method call is a governed object, any governance validators are added to the validator chain. 2. General validators. 3. Classification specific validators. 4. Object type specific validators If multiple validators are listed against one of the relevant keys in the configuration properties file, these validators are added to the validator chain in the order in which they are listed. It is valid for the same validator to appear several times in the configuration properties file for validation plugins. In this situation, the same plugin may appear more than once in the validator chain. If this occurs, WSRR will only invoke the validator in question once, at the earliest opportunity. If any of the validators in the chain return a ServiceRegistryStatus object that indicates that the validation failed, WSRR will not invoke the remaining validators in the chain. More importantly, the WSRR API implementation module will not be invoked for the relevant method. In this situation, WSRR will invoke any registered notifiers that are relevant for the method, indicating to each notifier that the operation failed using the success flag. Once all of the relevant notifiers have been invoked a ServiceRegistryValidationException is returned to the

210

WebSphere Service Registry and Repository Handbook

client. The invocation sequence for a single validator that fails validation, and a single notifier is shown in Figure 5-24.

Figure 5-24 Failed validation invocation sequence

Note: Unlike validators, notifiers are not able to affect the execution of a WSRR API method. They are simply notified of the result of a WSRR API method call, giving them opportunity to perform any required post-processing tasks.

Notifier plugin properties
The configuration properties file for notification plugins uses the standard Java format for properties files. The properties within the file are specified as key/value pairs. The set of keys that can be used within the configuration properties file for validation plugins is shown in Table 5-8.
Table 5-8 Valid property keys for defining notification plugins Configuration properties key notifiers Description Notification plugins listed against this key will be invoked as a result of the relevant WSRR API methods being invoked on any type of object.

Chapter 5. SOA governance enablers

211

Configuration properties key notifiers.

Description Notification plugins listed against this key will be invoked as a result of the relevant WSRR API methods being invoked on objects of the specified type. Currently, only OriginalObject sub-classes can be specified, as follows:

WSDLDocument XSDDocument PolicyDocument XMLDocument GenericObject notifiers.classification. Notification plugins listed against this key will be invoked as a result of the relevant WSRR API methods being invoked on objects that are classified by the specified classification URI. Notification plugins listed against this key will be invoked as a result of the relevant WSRR API being invoked on an object that is part of a governed lifecycle. Any notification plugins listed against this key must implement the ServiceRegistryGovernanceNotifier interface.

governanceNotifiers

Note: Due to the limitations of the Java properties file, any classification URI specified as part of a key within the file must not contain any ‘:’ (colon) characters. These should simply be omitted from any classification URI specified. The values specified within the configuration properties file must be a comma separated list of fully qualified class names for the required notification plugins. As discussed in 5.4.3, “Packaging plugins” on page 206, the implementation classes for any notification plugins that are specified in the configuration properties file must be made available to WSRR on the classpath at runtime. The default configuration properties file for notification plugins that is loaded into WSRR during the installation process is shown in Example 5-5.
Example 5-5 Default configuration properties file for notification plugins

# These notifiers are called for all document types notifiers=com.ibm.sr.api.ServiceRegistryNotifierJMS # These notifiers are called for governed objects only governanceNotifiers=com.ibm.sr.api.ServiceRegistryNotifierJMS

212

WebSphere Service Registry and Repository Handbook

As you can see, this configuration properties file defines a single default notification plugin, as follows: com.ibm.sr.api.ServiceRegistryNotifierJMS This notification plugin provides support for publishing notification events to the relevant JMS topics used by WSRR. Note: The ServiceRegistryNotifierJMS plugin is a system plugin that is required by WSRR at runtime. This notifier should not be removed when you are modifying the configuration properties file for notification plugins. Example 5-6 provides an example of how the configuration properties file for notification plugins can be updated to include two additional notifiers. Notice that the com.ibm.itso.plugins.ITSOAuditNotifier plugin has been added to the list of the plugins for the notifiers key. Also, the com.ibm.itso.plugins.WSIComplianceNotifier has been added against the notifiers.WSDLDocument key. This notifier will only be invoked when WSRR API methods are invoked on objects of type WSDLDocument.
Example 5-6 Modified configuration properties file for notification plugins

# These notifiers are called for all document types notifiers=com.ibm.sr.api.ServiceRegistryNotifierJMS,com.ibm.itso.plugin s.ITSOAuditNotifier # These notifiers are called for WSDLDocuments only notifiers.WSDLDocument=com.ibm.itso.plugins.WSIComplianceNotifier # These notifiers are called for governed objects only governanceNotifiers=com.ibm.sr.api.ServiceRegistryNotifierJMS

5.5 Impact analysis
The huge majority of objects that are stored in WSRR do not exist in isolation. Each object may define a number of predefined relationships (also known as modelled relationships) or user defined relationships that connect them to other objects in WSRR, forming an object graph. These relationships indicate dependencies that exist between the objects in the object graph. They can be traversed in order to determine which objects may be affected by changes to other objects in the graph. However, for any non-trivial object graph, attempting to perform this task manually would be a time consuming process. The impact

Chapter 5. SOA governance enablers

213

analysis functionality within WSRR can automatically traverse the relationships in an object graph to determine the list of dependent objects. More specifically, the impact analysis component recursively navigates the relationships that originate from a specified object, building a list of all of the reachable objects in the object graph. It is this list that is returned as a result of running impact analysis. It represents the collection of objects in WSRR that may be affected by a change to the specified object.

5.5.1 Dependencies
When the impact analysis component in WSRR is traversing the relationships of an object graph, the direction of the relationships between the objects in the graph is extremely important. The impact analysis component categorizes these relationships by the type of dependency that they define between objects in WSRR. These are: Outbound dependencies Inbound dependencies When you initiate impact analysis using either the Web user interface or the governance API, you must specify which type of dependency you want to be analyzed. The sections that follow described the different types of dependency that can exist between objects in WSRR.

Outbound dependencies
An object, Object A, has an outbound dependency on another object, Object B, if a modelled or user defined relationship exists from Object A to Object B. To put it more simply, Object A has an outbound dependency on Object B if Object A depends on Object B. Using our simple object graph, shown in Figure 5-25 on page 215, the two Service WSDL documents each have an outbound dependency on the PortType WSDL document. The PortType WSDL document itself has an outbound dependency on the XSD document.

214

WebSphere Service Registry and Repository Handbook

XSD

PortType WSDL

Service WSDL

Service WSDL

Figure 5-25 Sample object graph

In order to determine the list of objects on which a specific object depends, you must invoke the getOutboundDependencies() method on the governance API, specifying the bsrUri of the object in question. If you are using the Web user interface, you must navigate to the Impact Analysis tab for the object in question and ensure that the Include entities this entity depends on check box is checked, as shown in Figure 5-26 on page 216.

Chapter 5. SOA governance enablers

215

Figure 5-26 Retrieving outbound dependencies using the Web user interface

Inbound dependencies
An object, Object A, has an inbound dependency from another object, Object B, if a modelled or user defined relationship exists from Object B to Object A. To put it more simply, Object A has an inbound dependency from Object B if Object B depends on Object A. Once again, using the simple object graph, shown in Figure 5-25 on page 215, the XSD document has an inbound dependency from the PortType WSDL document and the PortType WSDL document has two inbound dependencies, one from each of the Service WSDL documents. In order to determine the list of objects that depend on a specific object, you must invoke the getInboundDependencies() method on the governance API, specifying the bsrUri of the object in question. If you are using the Web user interface, you must navigate to the Impact Analysis tab for the object in question and ensure that the Include entities that depend on this entity check box is checked, as shown in Figure 5-27 on page 217.

216

WebSphere Service Registry and Repository Handbook

Figure 5-27 Retrieving inbound dependencies using the Web user interface

Dependency depth
It is possible to restrict the extent to which the impact analysis component traverses the object graph by specifying the depth of the analysis. In the context of the impact analysis, the depth refers to the number of relationships that need to be been traversed in order to navigate from the object on which impact analysis is being performed, to any other object in the object graph. When traversing the object graph, the impact analysis component stops analyzing a given branch once the specified depth has been reached for that branch. Specifying a suitable value for the depth is important when performing impact analysis, since each object that is found when traversing a relationship is itself analyzed for dependencies. Specifying a depth that is too small could lead to important objects further down the object graph not being returned in the dependency list. Specifying a depth that is too large could lead to a huge list of dependent objects being returned, making it difficult to identify the most important dependencies. A value for the depth can be specified on both the getOutboundDependencies() and getInboundDependencies() method on the governance API and also on the

Chapter 5. SOA governance enablers

217

Web user interface, using the Dependency depth field on the Impact Analysis tab, as shown in Figure 5-28.

Figure 5-28 Specifying impact analysis depth using the Web user interface

5.5.2 Specifying modelled dependency relationships
As discussed in 2.2, “Architecture of WebSphere Service Registry and Repository” on page 66, when loading documents into WSRR, the document content is stored as a physical document object. However, during the process of loading WSDL and XSD documents, WSRR parses the content of the document and creates derived objects that represent the important structural elements of the document. Relationships are added to these derived objects to associate them with the physical document object from which they were parsed. For example, consider a simple WSDL document that defines a single PortType element. This PortType element itself defines a single Operation element with both Input and Output message elements. When this WSDL document is loaded into WSRR, a WSDLDocument object is created to represent the document itself

218

WebSphere Service Registry and Repository Handbook

and several derived objects are created to represent the elements contained within the document. Each of the derived objects has a relationship named document that references the WSDLDocument object from which it was parsed. This is shown in Figure 5-29.

Derived Objects

WSDLPortType

Physical Document document WSDL

WSDLOperation

WSDLMessage

WSDLMessage

WSDLPart

WSDLPart

WSDLPart

Figure 5-29 Physical and derived objects

Understanding the distinction between physical document objects, derived objects, GenericObjects and how all of these objects are related to each other is essential when performing impact analysis, because you must specify the list of modelled and user defined relationships that you want the impact analysis component to traverse in the object graph when attempting to determine the dependencies.

Chapter 5. SOA governance enablers

219

Note: When performing impact analysis, the relationships that you specify do not need to exist on the root object. Each object that is discovered during impact analysis will itself be assessed to determine if it possesses any of the modelled or user defined relationships that have been specified. If it does, then these relationships are traversed and the objects that are discovered are assessed, and so on until the specified depth is reached. If the object does not contain any of the specified modelled or user defined relationships the impact analysis component is unable to traverse the relevant branch of the object graph any further and the object in question is considered to be a leaf node. The list of modelled relationships that should be traversed when performing impact analysis is specified using the modelledRelationships parameter of the the getOutboundDependencies() or getInboundDependencies() method on the governance API. This parameter must contain the list of modelled relationship names. If you are using the Web user interface, you can specify the modelled relationships to be traversed by selecting them in the Built-in relationships list box on the Impact Analysis tab, as shown Figure 5-30 on page 221.

220

WebSphere Service Registry and Repository Handbook

Figure 5-30 Specifying modelled relationships

The modelled relationships that can be specified when performing impact analysis on a number of the object types in the WSRR information model are described in the sections that follow. Each of these sections contain a table that describes whether each modelled relationship represents an inbound or outbound dependency. They also specify both the name of the relationship that must be used when performing impact analysis using the governance API (shown as SDO) and the name of the relationship that must be used when performing impact analysis using the Web user interface (shown as UI).

Common relationships
All of the types defined by the information model in WSRR are an extension of the BaseObject type. As a consequence, all of the object types in WSRR share some common relationships that can be specified when performing impact analysis. These are described in Table 5-9 on page 222.

Chapter 5. SOA governance enablers

221

Table 5-9 Common modelled relationships that can be traversed during impact analysis Relationship name SDO: UI: classificationURIs Entity Reference to classification Dependency type Outbound Description When an object in WSRR is classified, the URI of the classification is added to the classificationURIs list on the object. This creates a dependency from the object to the OntologySystem that defines the classification URI. If this relationship is specified when performing impact analysis, all of the OntologySystem objects on which the object depends will be included in the returned list. SDO: UI: governedObjects Relationship to object in the same governance group Inbound When an object in WSRR is added to a governed collection, the bsrUri of the object is added to the governedObjects list of the relevant GovernanceRecord object. This creates a dependency from the GovernanceRecord to the object. If this relationship is specified when performing impact analysis, the GovernanceRecord for the object will be included in the returned list.

These relationships are shown in Figure 5-31.

Governance Record

governedObjects BaseObject

classificationURIs

Ontology System

Figure 5-31 Common modelled relationships that can be traversed during impact analysis

Note: At the time of writing, specifying the classificationURIs relationship when using the governance API, or the Entity Reference to classification relationship when using the Web user interface, does not result in any OntologySystem objects being included in the returned dependency list, regardless of how the object in question is classified.

222

WebSphere Service Registry and Repository Handbook

Note: At the time of writing, specifying the Relationship to object in the same governance group relationship when using the Web user interface to perform impact analysis on a governed object, results in the GovernanceRecord being included in the returned dependency list. However, the display name of the GovernanceRecord object is (no value). Also, attempting to select this entry in the displayed dependency list will cause an error similar to the following to be displayed:
The item was of a type GovernanceRecord for which no detail view definition exists in perspective Administrator.

Note: The relationship name Relationship to object in the same governance group is somewhat misleading. This name suggests that all of the objects in the same governed collection will be included in the dependency list if this relationship is specified when performing impact analysis. However, as we have described, specifying this relationship simply returns the associated GovernanceRecord.

OriginalObject relationships
All of the physical document type objects defined by the information model in WSRR ultimately extend the OriginalObject type. The GenericObject type also extends OriginalObject. As a consequence, all of the physical document types and the GenericObject type share some common relationships that can be specified when performing impact analysis. These are described in Table 5-10.
Table 5-10 Modelled relationships that can be traversed for OriginalObjects during impact analysis Relationship name SDO: UI: predecessors Entity Relationship to predecessor Dependency type Outbound/Inbound Description An OriginalObject in WSRR can refer to previous versions of itself using the predecessor relationship. This creates a dependency from the object to the previous versions of the OriginalObject. If this relationship is specified when performing impact analysis of outbound dependencies, all of the OriginalObject instances referred to by the predecessors relationship will be included in the returned list. If this relationship is specified when performing impact analysis of inbound dependencies, the OriginalObject instance that is a later version of the object in question will be included in the returned list.

Chapter 5. SOA governance enablers

223

Relationship name SDO: UI: template Non-derived entity reference to its template

Dependency type Outbound

Description An OriginalObject in WSRR can be based on a template. The template is defines a number of properties and relationships that should be added to an instance of an OriginalObject when the template is applied to them. Applying a template to an OriginalObject creates a dependency from the object to the ComplexTypeDefinition that defines the template. If this relationship is specified when performing impact analysis, the ComplexTypeDefinition object that defines the template will be included in the returned list.

These relationships are shown in Figure 5-32.

Original Original Object Original Object Object

predecessors

Original Object

template

Complex Type Definition

Figure 5-32 Modelled relationships that can be traversed for OriginalObjects during impact analysis

Document relationships
All of the physical document types objects defined by the information model in WSRR extend the Document type. As a consequence, all of the physical document types share a common relationships that can be specified when performing impact analysis. These are described in Table 5-11.
Table 5-11 Modelled relationships that can be traversed for Document objects during impact analysis Relationship name SDO: UI: document Derived entity reference to its source document Dependency type Inbound Description See Table 5-14 on page 229 for a description of the relationship from LogicalObject objects to Document objects.

224

WebSphere Service Registry and Repository Handbook

These relationships are shown in Figure 5-33.

Logical Object

document

Document

Figure 5-33 Modelled relationships that can be traversed for Document objects during impact analysis

WSDLDocument relationships
The modelled relationships that can be specified when performing impact analysis on WSDLDocument objects are described in Table 5-12.
Table 5-12 Modelled relationships that can be traversed for WSDLDocuments during impact analysis Relationship name SDO: UI: importedWSDLs WSDL document to imported WSDL document Dependency type Outbound/Inbound Description A WSDL document, WSDL A, may import another WSDL document, WSDL B. When these documents are loaded into WSRR, a reference to WSDL B is added to the importedWSDLs list of WSDL A. This creates a dependency from the WSDLDocument object representing WSDL A to the WDSLDocument object representing WDSL B. If this relationship is specified when performing impact analysis of outbound dependencies, all of the WSDLDocument objects that are referenced by the importedWSDLs relationship will be included in the returned list. If this relationship is specified when performing impact analysis of inbound dependencies, all of the WSDLDocument objects that import the WSDLDocument in question will be included in the returned list.

Chapter 5. SOA governance enablers

225

Relationship name SDO: UI: importedXSDs WSDL or XSD document to imported XSD document

Dependency type Outbound

Description A WSDL document, WSDL A, may import an XSD document, XSD A. When these documents are loaded into WSRR, a reference to XSD A is added to the importedXSDs list of WSDL A. This creates a dependency from the WSDLDocument object representing WSDL A to the XSDDocument object representing XSD A. If this relationship is specified when performing impact analysis, all of the XSDDocument objects that are referenced by the importedXSDs relationship will be included in the returned list.

SDO: UI:

includedXSDs WSDL or XSD document to included XSD document

Outbound

A WSDL document, WSDL A, may include an XSD document, XSD A. When these documents are loaded into WSRR, a reference to XSD A is added to the includedXSDs list of WSDL A. This creates a dependency from the WSDLDocument object representing WSDL A to the XSDDocument object representing XSD A. If this relationship is specified when performing impact analysis, all of the XSDDocument objects that are referenced by the includedXSDs relationship will be included in the returned list.

SDO: UI:

redefinedXSDs WSDL or XSD document to redefined XSD document

Outbound

A WSDL document, WSDL A, may redefine elements defined in an XSD document, XSD A. When these documents are loaded into WSRR, a reference to XSD A is added to the redefinedXSDs list of WSDL A. This creates a dependency from the WSDLDocument object representing WSDL A to the XSDDocument object representing XSD A. If this relationship is specified when performing impact analysis, all of the XSDDocument objects that are referenced by the redefinedXSDs relationship will be included in the returned list.

These relationships are shown in Figure 5-34 on page 227.

226

WebSphere Service Registry and Repository Handbook

WSDL WSDL WSDL

importedWSDLs

WSDL

importedXSDs includedXSDs redefinedXSDs

XSD XSD XSD

Figure 5-34 Modelled relationships that can be traversed for WSDLDocuments during impact analysis

XSDDocument relationships
The modelled relationships that can be specified when performing impact analysis on XSDDocument objects are described in Table 5-13.
Table 5-13 Modelled relationships that can be traversed for XSDDocuments during impact analysis Relationship name SDO: UI: importedXSDs WSDL or XSD document to imported XSD document Dependency type Outbound/Inbound Description An XSD document, XSD A, may import another XSD document, XSD B. When these documents are loaded into WSRR, a reference to XSD B is added to the importedXSDs list of XSD A. This creates a dependency from the XSDDocument object representing XSD A to the XSDDocument object representing XSD B. If this relationship is specified when performing impact analysis of outbound dependencies, all of the XSDDocument objects that are referenced by the importedXSDs relationship will be included in the returned list. If this relationship is specified when performing impact analysis of inbound dependencies, all of the XSDDocument and WSDLDocument objects that import the XSDDocument in question will be included in the returned list.

Chapter 5. SOA governance enablers

227

Relationship name SDO: UI: includedXSDs WSDL or XSD document to included XSD document

Dependency type Outbound/Inbound

Description An XSD document, XSD A, may include an XSD document, XSD B. When these documents are loaded into WSRR, a reference to XSD B is added to the includedXSDs list of XSD A. This creates a dependency from the XSDDocument object representing XSD A to the XSDDocument object representing XSD B. If this relationship is specified when performing impact analysis of outbound dependencies, all of the XSDDocument objects that are referenced by the includedXSDs relationship will be included in the returned list. If this relationship is specified when performing impact analysis of inbound dependencies, all of the XSDDocument and WSDLDocument objects that include the XSDDocument in question will be included in the returned list.

SDO: UI:

redefinedXSDs WSDL or XSD document to redefined XSD document

Outbound/Inbound

An XSD document, XSD A, may redefine elements defined in an XSD document, XSD B. When these documents are loaded into WSRR, a reference to XSD B is added to the redefinedXSDs list of XSD A. This creates a dependency from the XSDDocument object representing XSD A to the XSDDocument object representing XSD B. If this relationship is specified when performing impact analysis of outbound dependencies, all of the XSDDocument objects that are referenced by the redefinedXSDs relationship will be included in the returned list. If this relationship is specified when performing impact analysis of inbound dependencies, all of the XSDDocument and WSDLDocument objects that redefine elements in the XSDDocument in question will be included in the returned list.

228

WebSphere Service Registry and Repository Handbook

These relationships are shown in Figure 5-35.

WSDL WSDL WSDL

importedXSDs includedXSDs redefinedXSDs

XSD

importedXSDs includedXSDs redefinedXSDs

XSD XSD XSD

Figure 5-35 Modelled relationships that can be traversed for XSDDocuments during impact analysis

LogicalObject relationships
All of the derived object types defined by the information model in WSRR ultimately extend the LogicalObject type. As a consequence, all of the derived object types share a common relationship that can be specified when performing impact analysis. This is described in Table 5-14.
Table 5-14 Modelled relationships that can be traversed for LogicalObjects during impact analysis Relationship name SDO: UI: document Derived entity reference to its source document Dependency type Outbound Description Recall that the document relationship on a derived object (LogicalObject) references the physical document instance from which it was parsed. This creates a dependency from the derived object to the physical document object. If this relationship is specified when performing impact analysis, the Document object that is referenced by the document relationship will be included in the returned list.

These relationships are shown in Figure 5-36.

Logical Object

document

Document

Figure 5-36 Modelled relationships that can be traversed for LogicalObjects during impact analysis

Chapter 5. SOA governance enablers

229

Note: It is important to remember that LogicalObjects are created as a result of parsing the contents of a physical document object. While the document relationship on each derived object refers to the physical document object from which they were parsed, the physical document object has no knowledge of any of the derived objects that were produced from it. As a result, it is not possible to perform impact analysis on a physical document and use modelled relationships alone to discover the derived objects that are associated with it.

WSDLPortType relationships
The modelled relationships that can be specified when performing impact analysis on WSDLPortType objects are described in Table 5-15.
Table 5-15 Modelled relationships that can be traversed for WSDLPortTypes during impact analysis Relationship name SDO: UI: operations WSDL Port Type to WSDL Operation Dependency type Outbound Description A portType element in a WSDL document can define a number of operations. If this is the case, when loaded into WSRR the operations relationship on the WSDLPortType object will contain references to the WSDLOperation objects that were created when the document was parsed. This creates a dependency from the WSDLPortType object to the relevant WSDLOperation objects. If this relationship is specified when performing impact analysis, all of the WSDLOperation objects that are referenced by the operations relationship will be included in the returned list. SDO: UI: portType WSDL Binding to WSDL Port Type Inbound See Table 5-19 on page 236 for a description of the relationship from WSDLBinding objects to WSDLPortType objects

230

WebSphere Service Registry and Repository Handbook

These relationships are shown in Figure 5-37.

WSDL Binding

portType

WSDL Port Type

operations

WSDL WSDL Operation WSDL Operation Operation

Figure 5-37 Modelled relationships that can be traversed for WSDLPortTypes during impact analysis

WSDLOperation relationships
The modelled relationships that can be specified when performing impact analysis on WSDLOperation objects are described in Table 5-16.
Table 5-16 Modelled relationships that can be traversed for WSDLOperations during impact analysis Relationship name SDO: UI: inputMessage WSDL Operation to WSDL Input Message Dependency type Outbound Description An operation element in a WSDL document can define an input message. If this the case, when loaded into WSRR the inputMessage relationship on the WSDLOperation object will contain a reference to the WSDLMessage object that was created when the document was parsed. This creates a dependency from the WSDLOperation object to the relevant WSDLMessage object. If this relationship is specified when performing impact analysis, the WSDLMessage object that is referenced by the inputMessage relationship will be included in the returned list.

Chapter 5. SOA governance enablers

231

Relationship name SDO: UI: outputMessage WSDL Operation to WSDL Output Message

Dependency type Outbound

Description An operation element in a WSDL document can define an output message. If this the case, when loaded into WSRR the outputMessage relationship on the WSDLOperation object will contain a reference to the WSDLMessage object that was created when the document was parsed. This creates a dependency from the WSDLOperation object to the relevant WSDLMessage object. If this relationship is specified when performing impact analysis, the WSDLMessage object that is referenced by the outputMessage relationship will be included in the returned list.

SDO: UI:

faults WSDL Operation to WSDL Fault Message

Outbound

An operation element in a WSDL document can define a number of fault messages. If this the case, when loaded into WSRR the faults relationship on the WSDLOperation object will contain references to the WSDLMessage objects that were created when the document was parsed. This creates a dependency from the WSDLOperation object to the relevant WSDLMessage objects. If this relationship is specified when performing impact analysis, all of the WSDLMessage objects that are referenced by the faults relationship will be included in the returned list.

SDO: UI:

operations WSDL Port Type to WSDL Operation

Inbound

See Table 5-15 on page 230 for a description of the relationships from WSDLPortTpye objects to WSDLOperation objects.

These relationships are shown in Figure 5-38.

WSDL Port Type

operations

WSDL Operation

inputMessage outputMessage faults

WSDL WSDL Message WSDL Message Message

Figure 5-38 Modelled relationships that can be traversed for WSDLOperations during impact analysis

232

WebSphere Service Registry and Repository Handbook

WSDLMessage relationships
The modelled relationships that can be specified when performing impact analysis on WSDLMessage objects are described in Table 5-17.
Table 5-17 Modelled relationships that can be traversed for WSDLMessages during impact analysis Relationship name SDO: UI: messageParts WSDL Message to WSDL Part Dependency type Outbound Description A message element in a WSDL document can define a number of parts. If this the case, when loaded into WSRR the messageParts relationship on the WSDLMessage object will contain references to the WSDLPart objects that were created when the document was parsed. This creates a dependency from the WSDLMessage object to the relevant WSDLPart objects. If this relationship is specified when performing impact analysis, all of the WSDLPart objects that are referenced by the messageParts relationship will be included in the returned list. SDO: UI: inputMessage WSDL Operation to WSDL Input Message outputMessage WSDL Operation to WSDL Output Message faults WSDL Operation to WSDL Fault Message Inbound Inbound Inbound See Table 5-16 on page 231 for a description of the relationships from WSDLOperation objects to WSDLMessage objects.

SDO: UI:

See Table 5-16 on page 231 for a description of the relationships from WSDLOperation objects to WSDLMessage objects.

SDO: UI:

See Table 5-16 on page 231 for a description of the relationships from WSDLOperation objects to WSDLMessage objects.

Chapter 5. SOA governance enablers

233

These relationships are shown in Figure 5-39.

WSDL Operation

inputMessage outputMessage faults

WSDL Message

messageParts

WSDL WSDL Part WSDL Part Part

Figure 5-39 Modelled relationships that can be traversed for WSDLMessages during impact analysis

WSDLPart relationships
The modelled relationships that can be specified when performing impact analysis on WSDLPart objects are described in Table 5-18.
Table 5-18 Modelled relationships that can be traversed for WSDLParts during impact analysis Relationship name SDO: UI: xsdType WSDL Part to XSD Type Dependency type Outbound Description A part element in a WSDL document can specify its XSD type. If this the case, when loaded into WSRR the xsdType relationship on the WSDLPart object will contain a reference to the XSDType object that was created when the document was parsed. This creates a dependency from the WSDLPart object to the relevant XSDType object. If this relationship is specified when performing impact analysis, the XSDType object that is referenced by the xsdType relationship will be included in the returned list. SDO: UI: xsdElement WSDL Part to XSD Element Declaration Outbound A part element in a WSDL document can specify the XSD element that defines its structure. If this the case, when loaded into WSRR the xsdElement relationship on the WSDLPart object will contain a reference to the ElementDeclaration object that was created when the document was parsed. This creates a dependency from the WSDLPart object to the relevant ElementDeclaration object. If this relationship is specified when performing impact analysis, the ElementDeclaration object that is referenced by the xsdElement relationship will be included in the returned list.

234

WebSphere Service Registry and Repository Handbook

Relationship name SDO: UI: messageParts WSDL Message to WSDL Part

Dependency type Inbound

Description See Table 5-17 on page 233 for a description of the relationship from WSDLMessage objects to WSDLPart objects.

These relationships are shown in Figure 5-40.

xsdType

XSD Type

WSDL Message

messageParts

WSDL Part

xsdElement

Element Declaration

Figure 5-40 Modelled relationships that can be traversed for WSDLParts during impact analysis

WSDLBinding relationships
The modelled relationships that can be specified when performing impact analysis on WSDLBinding objects are described in Table 5-19 on page 236.

Chapter 5. SOA governance enablers

235

Table 5-19 Modelled relationships that can be traversed for WSDLBindings during impact analysis Relationship name SDO: UI: portType WSDL Binding to WSDL Port Type Dependency type Outbound Description A binding element in a WSDL document must specify the portType that it binds using the type attribute. When the WSDL document is loaded into WSRR the portType relationship on the WSDLBinding object will contain a reference to the WSDLPortType object that was created when the document was parsed. This creates a dependency from the WSDLBinding object to the relevant WSDLPortType object. If this relationship is specified when performing impact analysis, the WSDLPortType object that is referenced by the portType relationship will be included in the returned list. SDO: UI: SOAPBinding WSDL Binding to SOAP Binding Outbound A binding element in a WSDL document can specify that it uses the SOAP binding by specifying a soap:binding element. If this is the case, when the WSDL document is loaded into WSRR the SOAPBinding relationship on the WSDLBinding object will contain a reference to the SOAPBinding object that was created when the document was parsed. This creates a dependency from the WSDLBinding object to the relevant SOAPBinding object. If this relationship is specified when performing impact analysis, the SOAPBinding object that is referenced by the SOAPBinding relationship will be included in the returned list. SDO: UI: binding WSDL Port to WSDL Binding Inbound See Table 5-22 on page 239 for a description of the relationship from WSDLPort objects to WSDLBinding objects.

236

WebSphere Service Registry and Repository Handbook

These relationships are shown in Figure 5-41.

SOAPBinding

SOAP Binding

WSDL Port Type

portType

WSDL Binding

binding

WSDL Port

Figure 5-41 Modelled relationships that can be traversed for WSDLBindings during impact analysis

SOAPBinding relationships
The modelled relationships that can be specified when performing impact analysis on SOAPBinding objects are described in Table 5-20.
Table 5-20 Modelled relationships that can be traversed for SOAPBindings during impact analysis Relationship name SDO: UI: SOAPBinding WSDL Binding to SOAP Binding Dependency type Inbound Description See Table 5-19 on page 236 for a description of the relationship from WSDLBinding objects to SOAPBinding objects.

Chapter 5. SOA governance enablers

237

These relationships are shown in Figure 5-42.

WSDL Binding

SOAPBinding

SOAP Binding

Figure 5-42 Modelled relationships that can be traversed for SOAPBindings during impact analysis

WSDLService relationships
The modelled relationships that can be specified when performing impact analysis on WSDLService objects are described in Table 5-21.
Table 5-21 Modelled relationships that can be traversed for WSDLServices during impact analysis Relationship name SDO: UI: ports WSDL Service to WSDL Port Dependency type Outbound Description A service element in a WSDL document can group a set of related ports together. If this is the case, when the WSDL document is loaded into WSRR the ports relationship on the WSDLService object will contain references to the WSDLPort object that was created when the document was parsed. This creates a dependency from the WSDLService object to the relevant WSDLPort objects. If this relationship is specified when performing impact analysis, the WSDLPort object that is referenced by the ports relationship will be included in the returned list.

238

WebSphere Service Registry and Repository Handbook

These relationships are shown in Figure 5-43.

WSDL Service

ports

WSDL WSDL Port WSDL Port Port

Figure 5-43 Modelled relationships that can be traversed for WSDLServices during impact analysis

WSDLPort relationships
The modelled relationships that can be specified when performing impact analysis on WSDLPort objects are described in Table 5-22.
Table 5-22 Modelled relationships that can be traversed for WSDLPorts during impact analysis Relationship name SDO: UI: SOAPAddress WSDL Port to SOAP Address Dependency type Outbound Description A port element in a WSDL document that is using the SOAP binding must specify exactly one address. When the WSDL document is loaded into WSRR the SOAPAddress relationship on the WSDLPort object will contain a reference to the SOAPAddress object that was created when the document was parsed. This creates a dependency from the WSDLPort object to the relevant SOAPAddress object. If this relationship is specified when performing impact analysis, the SOAPAddress object that is referenced by the SOAPAddress relationship will be included in the returned list.

Chapter 5. SOA governance enablers

239

Relationship name SDO: UI: binding WSDL Port to WSDL Binding

Dependency type Outbound

Description A port element in a WSDL document must specify the binding that it defines an endpoint for by using the binding attribute. When the WSDL document is loaded into WSRR the binding relationship on the WSDLPort object will contain a reference to the WSDLBinding object that was created when the document was parsed. This creates a dependency from the WSDLPort object to the relevant WSDLBinding object. If this relationship is specified when performing impact analysis, the WSDLBinding object that is referenced by the binding relationship will be included in the returned list.

SDO: UI:

ports WSDL Service to WSDL Port

Inbound

See Table 5-21 on page 238 for a description of the relationship from WSDLService objects to WSDLPort objects.

These relationships are shown in Figure 5-44.

SOAPAddress

SOAP Address

WSDL Service

ports

WSDL Port

binding

WSDL Binding

Figure 5-44 Modelled relationships that can be traversed for WSDLPorts during impact analysis

240

WebSphere Service Registry and Repository Handbook

SOAPAddress relationships
The modelled relationships that can be specified when performing impact analysis on SOAPAddress objects are described in Table 5-23.
Table 5-23 Modelled relationships that can be traversed for SOAPAddresses during impact analysis Relationship name SDO: UI: SOAPAddress WSDL Port to SOAP Address Dependency type Inbound Description See Table 5-22 on page 239 for a description of the relationship from WSDLPort objects to SOAPAddress objects.

These relationships are shown in Figure 5-45.

WSDL Port

SOAPAddress

SOAP Address

Figure 5-45 Modelled relationships that can be traversed for SOAPAddresses during impact analysis

ElementDeclaration relationships
The modelled relationships that can be specified when performing impact analysis on ElementDeclaration objects are described in Table 5-24.
Table 5-24 Modelled relationships that can be traversed for ElementDeclarations during impact analysis Relationship name SDO: UI: xsdElement WSDL Part to XSD Element Declaration Dependency type Inbound Description See Table 5-18 on page 234 for a description of the relationship from WSDLPart objects to ElementDeclaration objects.

Chapter 5. SOA governance enablers

241

These relationships are shown in Figure 5-46.

WSDL Part

xsdElement

Element Declaration

Figure 5-46 Modelled relationships that can be traversed for ElementDeclarations during impact analysis

ComplexTypeDefinition relationships
The modelled relationships that can be specified when performing impact analysis on ComplexTypeDefinition objects are described in Table 5-24 on page 241.
Table 5-25 Modelled relationships that can be traversed for ComplexTypeDefinitions during impact analysis Relationship name SDO: UI: localAttributes XSD complex type reference to a local attribute Dependency type Outbound Description An XSD complex type definition within an XSD document or a WSDL document can define a number of attribute elements. If this the case, when the relevant document is loaded into WSRR the localAttributes relationship on the ComplexTypeDefinition object will contain a reference to the LocalAttribute objects that were created when the document was parsed. This creates a dependency from the ComplexTypeDefinition object to the relevant LocalAttribute object. If this relationship is specified when performing impact analysis, the LocalAttribute objects that are referenced by the localAttributes relationship will be included in the returned list. SDO: UI: template Non-derived entity reference to its template Inbound See Table 5-10 on page 223 for a description of the relationship from OriginalObject objects to ComplexTypeDefinition objects.

These relationships are shown in Figure 5-47 on page 243.

242

WebSphere Service Registry and Repository Handbook

Original Object

template

Complex Type Definition

localAttributes

Local Attribute

Figure 5-47 Modelled relationships that can be traversed for ComplexTypeDefinitions during impact analysis

5.5.3 Specifying user defined dependency relationships
User defined relationships allow you to associate a source object to zero or more target objects. The source and target objects can be of any physical document object, derived object or GenericObject type. Any given source object is able to contain many user defined relationships and the name of each user defined relationship is defined when you create the relationship (with the restriction that they must be unique within the scope of a source object). This brief explanation of user defined relationships describes a simple, but extremely flexible, feature of WSRR. However, the flexibility that user defined relationships provide makes it difficult to use them when performing impact analysis. Since user defined relationships are able to transcend all physical document object, derived object and GenericObject types, the results that are produced when they are used to perform impact analysis are not as predictable as when using modelled relationships alone. This is exacerbated by the fact that, without extensive knowledge of the objects in your object graph, it is not possible to anticipate whether a user defined relationship constitutes an inbound or outbound dependency on an object. The list of user defined relationships that should be traversed when performing impact analysis is specified using the userDefinedRelationships parameter on the getOutboundDependencies() or getInboundDependencies() method on the governance API. This parameter must contain the list of user defined relationship names. If you are using the Web user interface, you can specify the user defined relationships to be traversed by selecting them in the Custom relationships list box on the Impact Analysis tab, as shown Figure 5-48 on page 244.

Chapter 5. SOA governance enablers

243

Figure 5-48 Specifying user defined relationships

Note: When the impact analysis component encounters a specified user defined relationship on an object in the object graph, it adds all of the target objects of the relationship to the list of dependencies.

244

WebSphere Service Registry and Repository Handbook

Part 3

Part

3

Planning and installing WSRR

© Copyright IBM Corp. 2007. All rights reserved.

245

246

WebSphere Service Registry and Repository Handbook

6

Chapter 6.

Possible topologies
This chapter describes some possible installation topologies, such as which version of IBM WebSphere Application Server to use and where to locate the databases. This chapter contains the following: 6.1, “WSRR requirements” on page 248 6.2, “Database topologies” on page 250 6.3, “WebSphere Application Server topologies” on page 251

© Copyright IBM Corp. 2007. All rights reserved.

247

6.1 WSRR requirements
WebSphere Service Registry and Repository (WSRR) comes with an installer that provides an out of the box solution for numerous platforms. WSRR can also be installed in several different configurations. Before installing WSRR, administrators should consider a number of factors that will affect how they install WSRR and what configuration tasks they need to undertake in order to make WSRR provide the desired capability in their Service Oriented Architecture (SOA).

6.1.1 Supported platforms
WSRR V6.0.0 is supported on the following platforms: AIX® V5.3 Solaris™ 2.9 or 2.10 on SPARC processors Linux® on x86 processors (RHAS 4.0 and SLES 9) HPUX 11.23 on PA-RISC Windows® Server 2003 z/OS V1.7 WSRR requires at least 2Gb of physical memory and at least 2Gb of spare disk space to install. More detailed requirements on the supported operating systems and hardware requirements can be found on the WSRR support Web site: http://www.ibm.com/software/integration/wsrr/sysreqs/index.html

6.1.2 Supported databases
DB2 Universal Database Enterprise Server Edition V8.2 and Fix Pack 5 (or later Fix Pack) is supported on all of the platforms listed in 6.1.1, “Supported platforms” on page 248. DB2 Universal Database Enterprise Server Edition V8.2 Fix Pack 5 is supplied with WSRR. In addition WSRR V6.0.0 supports Oracle® 10g Enterprise Edition Release 10.2.0.1.0 on Solaris on SPARC.

248

WebSphere Service Registry and Repository Handbook

6.1.3 Prerequisite software
WSRR requires both a database (supported ones are listed in 6.1.2, “Supported databases” on page 248) and a WebSphere Application Server. Therefore WSRR also requires WebSphere Application Server V6.0.2 and Fix Pack 11 (or later fix pack) to be installed. As of WSRR V6.0.0 Fix Pack 1 WSRR supports both WebSphere Application Server Base edition and WebSphere Application Server Network Deployment edition. Regardless of which edition is used the version must be V6.0.2 Fix Pack 11 (or later fix pack). WebSphere base edition V6.0.2 Fix Pack 11 is supplied with WSRR.

6.1.4 Topology selection criteria
While a variety of factors come into play when considering the appropriate topology for a WebSphere deployment, the primary factors to plan for typically include: Security Performance Throughput Scalability Availability Maintainability Session state For detailed information about topologies, their advantages and disadvantages, required software, as well as topology selection criteria, refer to the redbook WebSphere Application Server V6 Planning and Design WebSphere Handbook Series, SG24-6446. Note: For each of the Network Deployment topologies, a decision needs to be made regarding the placement of the Deployment Manager and master cell repository. The Deployment Manager can be located either on a dedicated machine, or on the same machine as one of its nodes. It is, however, considered a best practice to place the Deployment Manager on a separate machine. For more information about possible configurations, refer to 9.3, “Cell topologies” in the redbook WebSphere Application Server V6 Planning and Design WebSphere Handbook Series, SG24-6446.

Chapter 6. Possible topologies

249

6.2 Database topologies
Regardless of which database server you are using, DB2 or Oracle (Oracle is only supported on Solaris in WSRR V6.0.0) you can choose to have the database physically located on the same machine as the WebSphere Application Server or on a different machine. These two topologies are now explained.

6.2.1 Local database
This is when the database server and the WebSphere server are both located on the same physical machine. This is illustrated in Figure 6-1. Obviously the machine must be able to handle both the database server and WebSphere server running at the same time. This would normally require a more powerful machine than would be necessary were the database remote.

Physical Server
Database Server WSRR xmeta1 WebSphere Application Server

SOR

Figure 6-1 Local database topology

6.2.2 Remote database
It is also possible to install WSRR in a configuration with the database server and WebSphere server are on different physical machines. This configuration is illustrated in Figure 6-2 on page 251 and the installation process is described in 7.7, “Installing WSRR with a remote database” on page 275.

250

WebSphere Service Registry and Repository Handbook

This configuration requires multiple machines but each machine does not need to be as powerful as would be necessary were the database local. The network connection between the two machines should be as fast as possible and involve as few network switches, hubs, and so on as possible. An ideal setup would have both machines located in the same rack and on the same network subnet.

Physical Server 1
Database Server

Physical Server 2

WSRR xmeta1 WebSphere Application Server

SOR

Figure 6-2 Remote database topology

6.3 WebSphere Application Server topologies
This section introduces the different WebSphere configurations that are possible to use with WSRR. Refer to the Redpaper WebSphere Application Server V6 Technical Overview, REDP-3918, which is about the WebSphere Application Server architecture and components. For more information about WebSphere performance, refer to the redbook WebSphere Application Server V6 Scalability and Performance Handbook, SG24-6392.

6.3.1 Standalone server
Base, and Network Deployment both support a single stand-alone server environment. With a stand-alone configuration, each application server acts as a unique entity. An application server runs one or more J2EE applications and provides the services required to run those applications. Multiple stand-alone application servers can exist on a machine, either through independent installations of the WebSphere Application Server code or through multiple configuration profiles within one installation. However, WebSphere

Chapter 6. Possible topologies

251

Application Server does not provide for common management or administration for multiple application servers.

6.3.2 Distributed server
With Network Deployment, you can build a distributed server configuration, which enables central administration and workload management. In this environment, you integrate one or more application servers into a cell that is managed by a deployment manager. The application servers can reside on the same machine as the deployment manager or on multiple separate machines. Administration and management is handled centrally from the administration interfaces via the deployment manager. With this configuration, you can create multiple application servers to run unique sets of applications and then manage those applications from a central location. As of V6.0.0 Fix Pack 1 WSRR supports being installed into a federated server using WebSphere Application Server Network Deployment. However, WSRR V6.0.0 does not yet support any form of clustering, workload management or failover using Network Deployment. The main reason for using Network Deployment with WSRR instead of the supplied Base edition would be to harmonize versions of WebSphere with existing WebSphere servers or to provide the ability to use a separate deployment manager.

252

WebSphere Service Registry and Repository Handbook

7

Chapter 7.

Installing and deploying
This chapter describes how to install and deploy WebSphere Service Registry and Repository and its associated prerequisite software. In this chapter, the following topics are described: 7.1, “Install WebSphere Application Server V6.0” on page 254 7.2, “Install WebSphere Application Server V6.0 refresh pack 2 (V6.0.2)” on page 254 7.3, “Install WebSphere Application Server V6.0.2 fix pack 11 (V6.0.2.11)” on page 255 7.4, “Install DB2 Universal Database Enterprise Server Edition” on page 256 7.5, “Install WebSphere Service Registry and Repository” on page 258 7.6, “Deploy WebSphere Service Registry and Repository” on page 265 7.7, “Installing WSRR with a remote database” on page 275 7.8, “Installing WSRR using the WebSphere Application Server Network Deployment” on page 277 7.9, “Upgrading WSRR to a new fixpack” on page 279 7.10, “Installation troubleshooting” on page 280

© Copyright IBM Corp. 2007. All rights reserved.

253

7.1 Install WebSphere Application Server V6.0
As discussed in Chapter 6, “Possible topologies” on page 247 WSRR supports both WebSphere Application Server and WebSphere Application Server Network Deployment. Whichever edition is used it must be Version 6.0.2.x (where, x is 11 or greater). For the purposes of this book we will assume we are using WebSphere Application Server base edition. 1. Insert the WebSphere Application Server CD. 2. If the launchpad did not autorun then double-click launchpad.bat. 3. Select “WebSphere Application Server Installation” from the launchpad 4. Select “Launch the installation wizard for the WebSphere Application Server” 5. Click Next on the welcome window 6. Select the “I accept” option and then click Next on the license panel 7. Click Next on the system prerequisite check panel 8. Enter the directory to install the software to (for example, C:\Program Files\IBM\WebSphere\AppServer) and then click Next 9. Click Next on the feature selection panel 10.Click Next on the Installation summary panel 11.Deselect the “Launch the First steps console” check box and click Finish on the Installation Complete panel.

7.2 Install WebSphere Application Server V6.0 refresh pack 2 (V6.0.2)
We now need to upgrade the installed version of WebSphere to be V6.0.2. To do this, perform the following steps: 1. Insert the WebSphere Application Server fixpack CD 1 2. Open the 6.0-WS-WAS-WinX32-RP0000002 directory 3. Copy the “updateinstaller” directory to your WebSphere Application Server directory (for example, C:\Program Files\IBM\WebSphere\AppServer) 4. Double-click the update.exe program in your freshly copied directory (e.g. C:\Program Files\IBM\WebSphere\AppServer\updateinstaller\update.exe) 5. Click Next on the welcome panel

254

WebSphere Service Registry and Repository Handbook

6. Check the path to your WebSphere installation is correct and then click Next. 7. Ensure “Install maintenance package.” is selected and click Next. 8. Ensure the path to the package to install ends in “6.0-WS-WAS-WinX32-RP0000002.pak” and then click Next. 9. The refresh pack update needs to install a new Java runtime, however the update installer is running using the current one, so it needs to copy the new JDK™ to a temporary directory and then relaunch. After reading the explanation of these steps in the panel click Next. 10.Once the copy has completed, click Relaunch. 11.When the wizard restarts ensure “Install maintenance package” is selected and click Next. 12.The path to the package should not have changed and so click Next. 13.The wizard will now detail what it is about to do, namely to install “RP6020 WebSphere Application Server 6.0.2.0”. Check these details are correct and then click Next. 14.Once it is complete, click Finish.

7.3 Install WebSphere Application Server V6.0.2 fix pack 11 (V6.0.2.11)
We now need to upgrade the installed version of WebSphere to V6.0.2.11. To do this, perform the following steps: 1. Delete the \updateinstaller directory (e.g. C:\Program Files\IBM\WebSphere\AppServer\updateinstaller) 2. Insert the WebSphere Application Server fixpack CD 2 3. Open the 6.0.2-WS-WAS-WinX32-FP00000011 directory 4. Copy the “updateinstaller” directory to your WebSphere Application Server directory (e.g. C:\Program Files\IBM\WebSphere\AppServer) 5. Double-click the update.exe program in your freshly copied directory (e.g. C:\Program Files\IBM\WebSphere\AppServer\updateinstaller\update.exe) 6. Click Next on the welcome panel 7. Check the path to your WebSphere installation is correct and then click Next. 8. Ensure “Install maintenance package.” is selected and click Next. 9. Ensure the path to the package to install ends in “6.0.2-WS-WAS-WinX32-FP00000011.pak” and then click Next.

Chapter 7. Installing and deploying

255

10.The wizard will now detail what it is about to do, namely to install “FP60211 WebSphere Application Server 6.0.2.11”. Check these details are correct and then click Next. 11.Once it is complete click Finish. 12.Delete the \updateinstaller directory (e.g. C:\Program Files\IBM\WebSphere\AppServer\updateinstaller) 13.Open the 6.0.2-WS-WASJavaSDK-WinX32-FP00000011 directory on the CD 14.Copy the “updateinstaller” directory to your WebSphere Application Server directory (e.g. C:\Program Files\IBM\WebSphere\AppServer) 15.Double-click the update.exe program in your freshly copied directory (e.g. C:\Program Files\IBM\WebSphere\AppServer\updateinstaller\update.exe) 16.Click Next on the welcome panel 17.Check the path to your WebSphere installation is correct and then click Next. 18.Ensure “Install maintenance package.” is selected and click Next. 19.Ensure the path to the package to install ends in “6.0.2-WS-WASJavaSDK-WinX32-FP00000011.pak” and then click Next. 20.The fix pack update needs to install a new Java runtime, however the update installer is running using the current one, so it needs to copy the new JDK to a temporary directory and then relaunch. After reading the explanation of these steps in the panel click Next. 21.Once the copy has completed click Relaunch. 22.When the wizard restarts ensure “Install maintenance package” is selected and click Next. 23.The path to the package should not have changed and so click Next. 24.The wizard will now detail what it is about to do, namely to install “WASJAVASDKFP60211 - Software Developer Kit V6.0.2.11”. Check these details are correct and then click Next. 25.Once it is complete click Finish.

7.4 Install DB2 Universal Database Enterprise Server Edition
It is possible to install direct from a Windows DB2 fixpack without needing to install the original GA product first. This is not possible on other platforms, however for the purposes of this IBM Redbook we are only using Windows.

256

WebSphere Service Registry and Repository Handbook

Follow these steps to install DB2 Universal Database Enterprise Server Edition 8.2.5: 1. Insert the DB2 Universal Database Enterprise Server Edition 8.2 fixpack 5 CD. 2. Run setup.exe 3. Select “Install Product” from the launchpad 4. Click Next after confirming that you want to install DB2 Universal Database Enterprise Server Edition. 5. The DB2 install wizard will now start. Click Next on the welcome window. 6. Select the “I accept” option and then click Next on the license panel 7. Select Typical installation type and leave the additional function check boxes unselected, then click Next. 8. Ensure the “Install DB2 Enterprise Server Edition on this computer” box is checked and the “Save your settings in a response file” box is unchecked. Click Next. 9. Select the option “Single-partition database environment” and click Next 10.Select the directory to install DB2 in to, e.g. C:\Program Files\IBM\SQLLIB and then click Next. 11.Enter the following values for the DB2 Admin user details: – Domain: leave this blank if you do not have a domain – User name: Change this value if you want to use something other than db2admin – Password: Enter a password for the userid – Confirm password: Enter the password again Ensure the “Use the same user name and password for the remaining DB2 services” box is checked and then click Next. 12.Leave the Administration contact list as Local and leave “Enable notification” deselected and then click Next. 13.Click OK in the notification warning window that appears. 14.Click Next in the Configuring DB2 instances panel 15.Check the “Do not prepare the DB2 tools catalog” option and click Next. 16.When asked to specify a contact for health monitoring select “Defer the task until after installation is complete” and click Next. 17.Check the settings for this install are correct and then click Install. 18.Once the install has completed click Finish.

Chapter 7. Installing and deploying

257

19.Click Exit First Steps when the First Steps Launchpad appears.

7.5 Install WebSphere Service Registry and Repository
It is possible to install direct from WSRR fixpacks without needing to install the original GA image. Therefore these instructions are going to assume you are installing directly from the WSRR fixpack1 image. The instructions for later fixpacks should be similar. Note: There was a manufacturing refresh performed after fixpack 1 was completed, so if you obtained your WSRR install images after January 2007, they should already be at the fixpack1 level. Consult the readme.html file supplied with your WSRR installer to check which version you have. 1. From the directory Fixpack1 was downloaded to, run setup.exe 2. Select an installation language and click OK as in Figure 7-1.

Figure 7-1 WSRR Installation Language selection

258

WebSphere Service Registry and Repository Handbook

3. Click Next on the welcome panel as in Figure 7-2.

Figure 7-2 WSRR Installation Welcome panel

Chapter 7. Installing and deploying

259

4. Select the “I accept” option and then click Next on the license panel as in Figure 7-3

Figure 7-3 WSRR Installation License panel

260

WebSphere Service Registry and Repository Handbook

5. Select the directory to install to, e.g. C:\Program Files\IBM\WebSphereServiceRegistry and then click Next as in Figure 7-4.

Figure 7-4 WSRR Installation Destination panel

Chapter 7. Installing and deploying

261

6. Confirm the install settings are correct and then click Install as in Figure 7-5.

Figure 7-5 WSRR Installation Pre-install summary panel

262

WebSphere Service Registry and Repository Handbook

7. The installer will now install the files as in Figure 7-6. Once complete it will tell you that you need to run the deployment scripts to install the enterprise application into WebSphere and to create the databases (See Figure 7-7 on page 264. We will do that in the next section, 7.6, “Deploy WebSphere Service Registry and Repository” on page 265.). Click Next.

Figure 7-6 WSRR Installation progress panel

Chapter 7. Installing and deploying

263

Figure 7-7 WSRR Installation deployment warning panel

8. Click Finish as in Figure 7-8.

Figure 7-8 WSRR Installation completion panel

264

WebSphere Service Registry and Repository Handbook

7.6 Deploy WebSphere Service Registry and Repository
In order to use WSRR it must be deployed to WebSphere. This will also create the necessary databases. The deployment process will carry out the following operations: Create and populate the xmeta1 database Create and populate the SOR database Create JDBC™ Providers (XA and non-XA) in WebSphere Create an authentication alias for the database userID and password Create a JDBC datasource for the xmeta1 database Set up a WAS variable pointing at a WSRR subdirectory Create a shared library Add a namespace binding Create the xmeta SI Bus and JMS resources Create a JDBC datasource for the SOR database Create the WSRR SI bus and JMS resources Install the ServiceRegistry.ear application Change the default authorization provider Configure the startup bean to start on startup Preload the repository with configuration files Setup default roles for fine grained access control Note: The information in this section is appropriate for WebSphere Service Registry and Repository V6.0.0.1 (fixpack 1). Other fixpack versions may differ slightly. As noted previously there was a manufacturing refresh performed after fixpack 1 was completed, so if you obtained your WSRR install images after January 2007, they should already be at the fixpack1 level. Consult the readme.html file supplied with your WSRR installer to check which version you have. To do so, perform the following steps: 1. Navigate to the WSRR installation directory (e.g. C:\Program Files\IBM\WebSphereServiceRegistry) 2. Navigate to the “install” subdirectory 3. Open setenv.bat in notepad and edit the values in the file to match your current environment. Typically the following variables might need to be edited: – WebSphere Application Server install location – DB2 install location – WebSphere SOAP and Bootstrap port numbers

Chapter 7. Installing and deploying

265

– WebSphere server name – WebSphere profile name – Database user name But there are other variables in the file that you may need to edit too. All possible parameters are described in Table 7-1. Note that the values for these can be set by editing setenv.bat or by specifying them on the command line. As can be seen in the usage statement for installall.bat shown in Example 7-1.
Example 7-1 Installall.bat usage statement

Usage: installall.bat

-was-password was-password -db-password db-password [-was-user was-user] [-administrator-user administrator-user-name] [-administrator-group administrator-group] [-user-user user-role-user-name] [-user-group user-role-group] [-was-home C:\IBM\WebSphere\AppServer] [-was-profile default] [-was-server server1] [-soap-port 8880] [-bootstrap-port 2809] [-db-home C:\IBM\SQLLIB] [-db-type db2_8] [-db-user db-user] [-db-port 50000] [-db-hostname localhost] [-db-tsdir C:\DB2TS] [-skip-dbcreate true or false]

Table 7-1 WSRR Deployment parameters Parameter DB_TYPE Description The database type in use, one of the following two values: db2_8 or oracle10g (Note: oracle10g is only supported on Solaris) For DB2 this should be set to the user ID to use to access the databases. On Windows if this user does not exist it will be created automatically, however on UNIX® the user ID must already exist, for example, xmeta. On Oracle the db-user should be set to "system"

DB_USER

266

WebSphere Service Registry and Repository Handbook

Parameter DB_HOME DB_HOSTNAME DB_PORT

Description The path to the Database software install directory, for example, C:\IBM\SQLLIB or /opt/IBM/db2/8.1 The name of the server the database is running on, for example, localhost The database instance port number, for example, 50000. On UNIX, if in doubt check /etc/services and look for the db2c_ entry. The directory path for the DB2 tablespaces, for example, C:\DB2TS Set this option to true if you have already manually run the createdb_db2 or createdb_ora script to create the database table structures. The installer will then assume the databases exist and will perform the remainder of the install steps. This allows a database administrator to create the database manually, should they want to, as explained in 7.7, “Installing WSRR with a remote database” on page 275. The path to the WebSphere install directory, for example, C:\IBM\WebSphere\AppServer The name of the WebSphere profile, for example, default The name of the WebSphere server, for example, server1 The port number for the SOAP Connector, for example, 8880 The port number for the bootstrap port, for example, 2809 The WebSphere Administrator ID, or if WebSphere security is turned off then a local system Administrator The user you want added to the administrator role. This can also be set to NONE or ALL_AUTHENTICATED. The group you want added to the administrator role. The user you want added to the user role. This can also be set to NONE or ALL_AUTHENTICATED. The group you want added to the user role.

DB2TSDIR SKIPDBCREATE

WAS_HOME WAS_PROFILE WASSRVR WASPORT BOOTSTRAPPORT WAS_ADMIN_USER ADMINISTRATOR_USER ADMINISTRATOR_GROUP USER_USER USER_GROUP

Chapter 7. Installing and deploying

267

Parameter LOGDIR

Description The directory to put the install log files in. Normally set to be %SR_INSTALL% which will equate to be the \install directory.

Table 7-2 shows the extra parameters that can be found in setenv.sh when installing on UNIX but that are not used on Windows.
Table 7-2 UNIX only extra WSRR deployment parameters Parameter DB_INSTID DB2INST ORACLEPATH Description The user ID the database instance runs as, for example, db2admin (DB2 only) The DB2 instance name, for example, db2inst1 (DB2 only) The path to the Oracle software install directory. For example /home/oracle/product/10.2.0/Db_1 (Only used on Oracle on Solaris) The port in use by Oracle. (Only used on Oracle on Solaris) The oracle administration ID, for example oracle. (Only used on Oracle on Solaris)

ORAPORT ORAUSER

If any values in your environment file are incorrect then it is likely the deployment will fail. For more information about using the deployment scripts, consult the WSRR Information Center: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.do c/twsr_installn15.html Note: A common source of problems with the deployment stage is errors in the parameters specified in setenv. Ensure all parameters used are appropriate for your environment. Take extra care over the WASPORT and BOOTSTRAPPORT values as there is no validation for these values. Example 7-2 on page 269 shows the environment file used in our deployment.

268

WebSphere Service Registry and Repository Handbook

Note: Even if you are not using security in WebSphere Application Server you must still provide values for the WAS_ADMIN_USER variable in setenv.bat and the was-password parameter on the installall.bat command line. It is easiest to just provide the username and password for a local system administrator. If WebSphere security is off the install does seem to proceed correctly even if the username and password specified are not actually valid, values just have to be provided for them.

Example 7-2 WSRR deployment environment file

@rem begin_generated_IBM_copyright_prolog @rem @rem @rem @rem @rem @rem Licensed Materials - Property of IBM 5724-N72 (c) Copyright IBM Corp. 2006 All Rights Reserved US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

@rem end_generated_IBM_copyright_prolog @echo off set SR_INSTALL=%~dps0 set XMETA_HOME=%~dps0..\xmeta REM -------- DB Installation Information -------REM Database type REM possible values: db2_8 if "%DB_TYPE%" == "" set DB_TYPE=db2_8 REM Database username REM Please do not put quotes around the user ID if "" == "%DB_USER%" set DB_USER=xmeta REM The database password is not stored in this file for security reasons REM Database install directory REM Please do not put quotes around the directory path if "%DB_HOME%" == "" set DB_HOME=c:\Program Files\IBM\SQLLIB REM DB hostname REM if you set this to anything other than localhost you must create the database REM manually first and then specify "-skip-dbcreate true"

Chapter 7. Installing and deploying

269

if "%DB_HOSTNAME%" == "" set DB_HOSTNAME=localhost REM DB PORT if "%DB_PORT%" == "" set DB_PORT=50000 REM DB2 Tablespace Directory if "%DB2TSDIR%" == "" set DB2TSDIR=c:\DB2 REM Skip Database creation REM Set this to true if you have created the database manually already. REM This will then assume the databases exist and have all tables and REM tablespaces correctly configured. if "%SKIPDBCREATE%" == "" set SKIPDBCREATE=false REM -------- WAS Installation Information -------REM WAS Base Installation Directory REM Please do not put quotes around the directory path if "%WAS_HOME%" == "" set WAS_HOME=c:\Program Files\IBM\WebSphere\AppServer REM WAS Profile Name if "%WAS_PROFILE%" == "" set WAS_PROFILE=default REM WAS Server name if "%WASSRVR%" == "" set WASSRVR=server1 REM WAS SOAP CONNECTOR ADDRESS PORT if "%WASPORT%" == "" set WASPORT=8880 REM WAS BOOTSTRAP CONNECTOR ADDRESS PORT if "%BOOTSTRAPPORT%" == "" set BOOTSTRAPPORT=2809 REM WAS Administration User ID REM Please do not put quotes around the user ID if "" == "%WAS_ADMIN_USER%" set WAS_ADMIN_USER=Administrator REM The WAS admin password is not stored in this file for security reasons REM REM REM REM REM REM REM REM REM ------------------------------------------------------------------------ Users and groups that should be granted each of the roles -- defined by the service registry. -- Each xxx_USER variable can be set to one of: -- {NONE, EVERYONE, ALL_AUTHENTICATED, } -- if using LDAP, the user name must be the short version of the user name -- Each xxx_GROUP variable can be set to the name of a group or nothing. -- if using LDAP, the group name must be the fully qualified group name --

270

WebSphere Service Registry and Repository Handbook

REM -- (where xxx is either ADMINISTRATOR or USER) REM ----------------------------------------------------------------------REM Please do not put quotes around the values if "" == "%ADMINISTRATOR_USER%" set ADMINISTRATOR_USER=ALL_AUTHENTICATED if "" == "%USER_USER%" set USER_USER=ALL_AUTHENTICATED if "" == "%ADMINISTRATOR_GROUP%" set ADMINISTRATOR_GROUP=NONE if "" == "%USER_GROUP%" set USER_GROUP=NONE REM REM set set REM ------------------------------------------------------------------------ Setup the ANT PATHS so we can use ant from WAS for installation -SR_ANTHOME=%XMETA_HOME%\lib SR_ANTCP=%SR_ANTHOME%\ant.jar;%SR_ANTHOME%\ant-launcher.jar -----------------------------------------------------------------------

REM The directory the install logs will be saved to. set LOGDIR=%SR_INSTALL% REM REM REM REM REM ------------------------------------------------ Shouldn't need to edit below this ----- Section of the file, but check just in ----- case you do... ------------------------------------------------

if not exist "%WAS_HOME%\bin\wasprofile.bat" goto :nowas for /F "usebackq delims=" %%f in (`cmd /c "%WAS_HOME%\bin\wasprofile" -getPath -profileName %WAS_PROFILE%`) do set WASPROFILEDIR=%%f :nowas REM JAVA_HOME. You shouldn't need to edit this one. set JAVA_HOME=%WAS_HOME%\java REM Update the PATH. You shouldn't need to edit this one either. set PATH=%JAVA_HOME%\jre\bin;%JAVA_HOME%\bin;%PATH%;%WAS_HOME%\bin;%DB_HOME%\java\jdk\jre\bin goto ENDSCRIPT :ENDERROR exit /B 1 :ENDSCRIPT exit /B 0 Once you have finished editing setenv.bat save and close the file.

Chapter 7. Installing and deploying

271

4. Open a command prompt and cd to the install sub directory as shown in Figure 7-9.

Figure 7-9 WSRR Deployment - change directory

5. Run installall.bat as in Example 7-3.
Example 7-3 WSRR Deployment command

installall.bat -was-password passw0rd -db-password passw0rd This is illustrated in Figure 7-10. Replace “passw0rd” with the appropriate passwords for your environment.

Figure 7-10 WSRR Deployment - install command

272

WebSphere Service Registry and Repository Handbook

6. You should then get output similar to that shown in Figure 7-11.

Figure 7-11 WSRR Deployment - command output

If for any reason the deployment failed then you can look in the two log files mentioned in the output, for possible information about why it failed. Otherwise please contact your IBM Support representative. 7. WSRR should now be deployed and you should be able to verify the installation was successful by pointing a Web browser at the WSRR user interface: http://:9080/ServiceRegistry Or, if you have WebSphere security turned on, point to: https://:9443/ServiceRegistry You should see something similar to that shown in Figure 7-12 on page 274. Note: The port number in the above URLs might be different for your environment.

Chapter 7. Installing and deploying

273

Figure 7-12 WSRR User Interface

Installation of WebSphere Service Registry and Repository is now complete.

7.6.1 Security
In most installations it is desirable to limit access to WSRR. This is done by turning on WebSphere security. It is not within the scope of this book to cover how to do that, but it is documented in the WebSphere Information Center: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/topic/com.ibm. websphere.base.doc/info/aes/ae/tsec_csec.html For the purposes of this book we have turned on WebSphere Global Security and we are using local operating system authentication. Therefore we have created a local user on the WSRR installation machine called “wasadmin”. We did not turn on Java2 Security because it is not necessary for this book. See the

274

WebSphere Service Registry and Repository Handbook

following Web page in the WSRR Information Center for more information about using WSRR with Java2 Security: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.do c/cwsr_planning_install16.html

7.7 Installing WSRR with a remote database
Our example install above is now complete, but there are several possible install topologies as explained in Chapter 6, “Possible topologies” on page 247, and one of those makes use of a separate remote database server instead of using the same machine for both WebSphere and DB2 (or Oracle). This section will detail how to do that should you want to do so. 1. Install WebSphere and its associated fixpacks on the WebSphere server as explained in 7.1, “Install WebSphere Application Server V6.0” on page 254 to 7.3, “Install WebSphere Application Server V6.0.2 fix pack 11 (V6.0.2.11)” on page 255. 2. Install WSRR on the WebSphere server as outlined in 7.5, “Install WebSphere Service Registry and Repository” on page 258. 3. Install DB2 on the database server as outlined in 7.4, “Install DB2 Universal Database Enterprise Server Edition” on page 256. 4. Install WSRR on the database server as outlined in 7.5, “Install WebSphere Service Registry and Repository” on page 258. 5. On the database server navigate to the install subdirectory of your WSRR install root. Open setenv.bat in notepad. 6. Make sure the DB_USER, DB_HOME, DB_PORT and DB2TSDIR variables are all set correctly. DB_HOSTNAME can be set to localhost here, although it will need setting correctly when we come to run the WebSphere scripts on the WebSphere server. The other settings in the file for WebSphere are not important and will not be used by the create database script. Note: It is normally easier if you create a user on both the database and WebSphere servers with the same name and then use this user as the DB_USER. 7. Open a command prompt and cd to the install/xmeta sub-directory as shown in Example 7-4 on page 276.

Chapter 7. Installing and deploying

275

Example 7-4 WSRR change directory command

cd “C:\IBM\Program Files\WebSphereServiceRegistry\install\xmeta” 8. Run createdb_db2.bat as in Example 7-5.
Example 7-5 WSRR Create database command

createdb_db2.bat -db-password passw0rd Replace “passw0rd” with the appropriate password for your environment. This should then create the xmeta1 and SOR databases and populate them with the required tables, tablespaces and contents. Note: This command will output several thousand lines of output so you may want to redirect the output to a log file to be able to review it later and check for possible errors: createdb_db2.bat -db-password passw0rd > createdb.log 2>&1 9. On the WebSphere server navigate to the install sub-directory of your WSRR install root. Open setenv.bat in notepad. 10.Make sure the DB_USER, DB_PORT, DB_HOSTNAME, WAS_HOME, WAS_PROFILE, WASSRVR, WASPORT, BOOTSTRAPPORT, WAS_ADMIN_USER variables are set correctly. The ADMINISTRATOR_USER, ADMINISTRATOR_GROUP, USER_USER and USER_GROUP variables should also be set here if needed. It is not important to set the DB_HOME or DB2TSDIR variables since they are not needed on the WebSphere server. 11.Set the SKIPDBCREATE variable to be true. This tells the deployment scripts that we have already created the database separately and to not attempt those steps. 12.Open a command prompt and cd to the install sub-directory as shown in Example 7-6.
Example 7-6 WSRR change directory command

cd “C:\IBM\Program Files\WebSphereServiceRegistry\install” 13.Run installall.bat as in Example 7-7.
Example 7-7 WSRR installall command

installall.bat -was-password passw0rd -db-password passw0rd

276

WebSphere Service Registry and Repository Handbook

It is still necessary to specify the database user’s password. Replace “passw0rd” with the appropriate passwords for your environment. This should then create the WebSphere resources and configure WebSphere to connect to the remote database server and the databases we just created. 14.WSRR should now be deployed and you should be able to verify the installation was successful by pointing a Web browser at the WSRR user interface: http://:9080/ServiceRegistry Or if you have WebSphere security turned on: https://:9443/ServiceRegistry You should see something similar to that shown in Figure 7-12 on page 274. Note: The port number in the above URLs might be different for your environment.

7.8 Installing WSRR using the WebSphere Application Server Network Deployment
It is possible to install WSRR using WebSphere Application Server Network Deployment instead of WebSphere Application Server base edition. WebSphere should be installed in a similar way to that explained at the beginning of this chapter with the exception of using the Network Deployment version of the software and fixpacks. Note: Even if using WebSphere Application Server Network Deployment, WSRR V6.0.0.1 only supports Version 6.0.2.x where x is 11 or greater. The DB2 installation will be identical to that outlined in 7.4, “Install DB2 Universal Database Enterprise Server Edition” on page 256. The WSRR installation will also be identical to that for WebSphere base edition, see 7.5, “Install WebSphere Service Registry and Repository” on page 258. If you are installing to a standalone server profile in WebSphere Application Server Network Deployment then follow the instructions in 7.6, “Deploy WebSphere Service Registry and Repository” on page 265. However since there might be multiple profiles on the same machine take care that the WASPORT and BOOTSTRAPPORT variables are correctly set in setenv.bat. Refer to the

Chapter 7. Installing and deploying

277

WebSphere documentation for instructions on how to find what port numbers your server is using if you are not sure. If you want to install to a federated server then you will need to follow the steps here: 1. Create a Deployment Manager profile inside WebSphere Application Server Network Deployment if you do not already have one. 2. Start the deployment manager. 3. Create a custom profile. 4. Create an application server in the custom profile node you just created. 5. Deploy the WSRR application as outlined in 7.6, “Deploy WebSphere Service Registry and Repository” on page 265 with the following important changes when editing setenv.bat: – Set WAS_PROFILE to the name of the custom profile e.g. WSRRNode – Set WASSRVR to the name of the server created in that profile e.g. WSRRServer1 – Set WASPORT to the SOAP_CONNECTOR_ADDRESS value of the Deployment Manager e.g. 8879 – Set BOOTSTRAPPORT to the BOOTSTRAP_PORT value for the application server specified in WASSRVR running in the WAS_PROFILE specified. e.g. 2811 Note: It is important to take care here as the two port values are pointing at different servers, the SOAP port must point at the deployment manager in order to run the wsadmin commands to create the WebSphere resources. The BOOTSTRAPPORT value is that of the application server profile itself as some of the utilities need to connect to it directly rather than via the deployment manager. 6. WebSphere Service Registry and Repository should now be successfully installed to your federated server. You should be able to verify the installation was successful by pointing a Web browser at the WSRR user interface: http://:9080/ServiceRegistry or if you have WebSphere security turned on: https://:9443/ServiceRegistry

278

WebSphere Service Registry and Repository Handbook

The port numbers in these URLs will need to be substituted for those appropriate to your environment. You should see something similar to that shown in Figure 7-12 on page 274.

7.9 Upgrading WSRR to a new fixpack
It is possible to install direct from the fixpack install image without needing to have a previous version installed. However previous installations can also be upgraded to the new level.

7.9.1 Upgrade from previous version
To upgrade to the latest fix pack, download the fix pack from the WebSphere Service Registry and Repository support Web site: http://www.ibm.com/software/integration/wsrr/support/index.html 1. Make a backup of your existing files, especially your setenv.bat/sh file as the fixpack will overwrite it. 2. Run the InstallShield installer. Install the files over the top of the previous version. 3. Edit the new setenv file and make sure the variables are set to the values they were in the previous version. It is not possible to simply replace the new setenv file with the old one as the new version could contain new variables that will need setting. 4. Run the install/updatewsrr script as follows. For Windows: install/updatewsrr.bat –was-password password –db-password password For UNIX: install/updatewsrr.sh –was-password password –db-password password That script will update the ServiceRegistry application in WebSphere with the fixpack version.

7.9.2 Direct Installation
It is also possible to install direct from the fix pack without having a previous version installed. To do this just download the fix pack, and then run the InstallShield installer and deployment scripts as explained in 7.6, “Deploy WebSphere Service Registry and Repository” on page 265.

Chapter 7. Installing and deploying

279

7.10 Installation troubleshooting
Due to the deployment of WSRR involving several different products and performing multiple operations it is possible that it may fail to run through to completion. This is normally due to a variable being incorrectly set in setenv.bat/sh so all the values in that file should be thoroughly checked first. The next thing to check is the levels of the software being used, If you are using Windows then only Windows 2003 and Windows XP SP2 are supported. The deployment scripts will fail to run correctly on Windows 2000 or XP SP1. See 6.1, “WSRR requirements” on page 248 for more information about the supported levels of software. The deployment scripts produce two log files (installxmeta.log and installsr.log) normally found in the install subdirectory of your WSRR installation, for example: C:\Program Files\IBM\WebSphereServiceRegistry\install Check these files for any errors as they may give an indication of which part of the deployment failed. Some possible problems and their solutions have been documented in TechNotes on the WSRR support site: http://www.ibm.com/support/search.wss?tc=SSWLGF&rs=3163&dc=DB520&ran k=8 If you cannot find the cause of the problem then contact IBM Support, details of how to do so can be found on the WSRR Support Web site: http://www.ibm.com/software/integration/wsrr/support/index.html

280

WebSphere Service Registry and Repository Handbook

8

Chapter 8.

Administering WSRR
This chapter describes how to administer WebSphere Service Registry and Repository and the various interfaces that can be used. This chapter contains the following: 8.1, “Administration overview” on page 282 8.2, “WSRR configurations” on page 283 8.3, “Security considerations” on page 285 8.4, “Administering WSRR using wsadmin” on page 285 8.5, “Administering WSRR using JMX” on page 292 8.6, “Administering WSRR using the CLI” on page 299 8.7, “Ontology administration” on page 307 8.8, “Access control administration” on page 309 8.9, “Import/Export” on page 311 8.10, “Environment promotion” on page 319 8.11, “Administration scripts (wsadmin)” on page 321

© Copyright IBM Corp. 2007. All rights reserved.

281

8.1 Administration overview
Most of the administration of WebSphere Service Registry and Repository is performed through its JMX interface. Each WSRR application registers an MBean with an MBean identifier of ServiceRegistryRepository. This MBean may be used by client applications to inspect and manage the runtime configuration of a WSRR application. In order to manage the configuration of WSRR, the ServiceRegistry application must be in the started state. The WSRR MBean operations can be invoked using standard JMX clients, such as Java applications and wsadmin scripts. In addition, WSRR has a command line interface which allows invocation of administration operations. Some administration functions can also be performed through the WSRR Web user interface, by users in the Administrator role. These functions are import and export of entities and their metadata, and loading and removing ontology systems.

8.1.1 Administrative scripting (wsadmin)
The WebSphere administrative (wsadmin) scripting program is a powerful, non-graphical command interpreter environment enabling you to run administrative operations in a scripting language. The wsadmin tool is intended for production environments and unattended operations. In addition to application server related tasks, the wsadmin scripting program can be used to manage WSRR applications, by invoking the Service Registry and Repository MBean. All of the operations available on the JMX interface are available to the wsadmin scripting program. wsadmin scripts can be written in Jacl or Jython.

8.1.2 Administrative (JMX) interface
The WSRR administrative (JMX) interface provides a Java API that allows you to manage configuration settings to control registry runtime behavior. For example, loading and removing classification systems (ontologies), setting up access control policies, or customizing the user interface. In addition you can register listeners for specific administration events. Sample client code is provided for you to build on in the \admin\javasrc directory.

282

WebSphere Service Registry and Repository Handbook

8.1.3 Command line administration
Interactive and scripted administration of WSRR is possible with the Jython-based command line interface. The command line interface provides full support for all of the WSRR programmatic APIs, including all administrative operations. Several example scripts show you how to perform governance tasks such as promoting entities from one WSRR instance to another, or transitioning entities through different lifecycle states. These scripts can be found in the \CLI\scripts directory.

8.1.4 Configuration data
The behavior of many aspects of WSRR is determined by configuration data residing in configuration files, typically using XML. For example, user interface perspectives, lifecycle states, access control policies are all stored this way. These configuration files are managed using the administrative tools described in this chapter. Configuration items are stored with a configuration name, the content of the configuration file, the type of configuration and whether the specific configuration is a system configuration or a user-defined one.

8.2 WSRR configurations
WSRR components use configuration documents stored within the registry to determine their runtime behavior. The management interfaces allow administrators to retrieve, create, update, and remove configurations to meet their business requirements. A configuration in WSRR consists of: Name A logical name to uniquely identify the configuration for a particular configuration type. The name must be 1 to 255 characters in length. Configuration type An identifier for the type of configuration, used by components to read the content of the configuration in the appropriate context. See 8.2.1, “Supported configurations” on page 284 for allowed configuration type values. Content The raw configuration content, stored as bytes. The configuration administration operations provide different constructors to take the content parameter as a byte array, a server-local file, or a remote URL.

Chapter 8. Administering WSRR

283

System indicator A boolean flag which indicates if the configuration is a system configuration (true) or a user-defined one (false). WSRR components may use this flag to determine whether a configuration is required. When a configuration is created, it is given a unique URI (within WSRR). Some operations have signatures that take this URI as the configuration identifier, for example updateConfiguration, retrieveConfiguration and deleteConfiguration. In situations where you do not have this identifier available, operations often have a signature that takes a name and configuration type, for example updateConfiguration, retrieveConfiguration. To find out the identifier for a configuration there is an operation that accepts a name and a configuration type.

8.2.1 Supported configurations
The configuration type parameter value for each configuration must be one of the following:
Table 8-1 Supported configurations Configuration type UI_PERSPECTIVE UI_NAVIGATION_TREE UI_VIEW_QUERY_SYSTEM UI_VIEW_QUERY_USER_DEF UI_DETAIL_VIEW UI_COLLECTION_VIEW SACL XACML EMAIL_TEMPLATE PLUGIN_PROPERTIES Description UI perspective definition UI navigation tree definition UI view query definition (system) UI view query definition (user-defined) UI detail view definition UI collection view definition Lifecycle state definition Access control definition E-mail template for subscription notifications plugin properties

Note: If you are customizing the WSRR Web user interface, do not use the UI_VIEW_QUERY_SYSTEM configuration type - use the UI_VIEW_QUERY_USER_DEF configuration type with its systemConfiguration flag set to false.

284

WebSphere Service Registry and Repository Handbook

These values can be determined programmatically using the com.ibm.serviceregistry.admin.ConfigurationType java class found in the ServiceRegistryClient.jar. All of the allowed configuration types are declared as public static final fields (it's a type-safe enumeration). This class also has a utility method isConfigurationType(String type) which returns true if the type is valid.

8.3 Security considerations
When WebSphere global security is enabled, you can only invoke the operations of the ServiceRegistryRepository MBean if you are a user in an administrative role. The operations which make updates require the WebSphere Administrator or Operator role, while read operations can be performed by the WebSphere Administrator, Operator, Configurator and Monitor roles. With security enabled you will also need to provide additional security parameters when configuring the connection to the MBean.

8.4 Administering WSRR using wsadmin
WSRR administrative operations are performed by invoking the WSRR MBean using standard wsadmin commands. You need to know the type of the WSRR MBean, and the cell, node and server for the WSRR you want to configure.

8.4.1 Setting up wsadmin for managing WSRR
If the WSRR MBean encounters an error, either a validation problem with input parameters or a system problem, it will throw a WSRR specific exception of type com.ibm.serviceregistry.exception.admin.AdminException. This AdminException may also contain one or more cause exceptions which will be subtypes of ServiceRegistryException. These exception classes are available in the ServiceRegistryClient.jar file. For this reason, the wsadmin environment must be configured with the exception classes available on the class path. To configure wsadmin, in addition to any other parameters specific to your environment, you must specify the class path as follows: \bin\wsadmin -wsadmin_classpath \ServiceRegistryClient.jar

Chapter 8. Administering WSRR

285

Where is the path to the directory where WebSphere Application Server is installed and is the path to the directory where the ServiceRegistryClient.jar resides. Refer to the WebSphere Application Server scripting documentation for further information: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/topic/com.ibm. websphere.base.doc/info/aes/ae/txml_scriptingep.html

8.4.2 Locating the WSRR MBean with wsadmin
As for all MBeans present in a WebSphere application server environment, including cells, the only information required to start invoking MBean operations is to know the MBean type. In the case of WSRR, the MBean type is “ServiceRegistryRepository”. 1. To locate the WSRR MBean, first create a string representation of an ObjectName query: wsadmin>set objectNameString [$AdminControl queryNames type=ServiceRegistryRepository,*] This finds the ObjectNames for all WSRR MBeans running in the WebSphere server process. If the client is connected to a Deployment Manager, there may be multiple WSRR MBeans present in the cell. In this case you could reduce the scope of the query and specify the cell name, node name and server name. The typical response will be the string representation of the matching ObjectName: WebSphere:platform=dynamicproxy,cell=WSRRCell,version=6.0.2.11,name= ServiceRegistryRepository,mbeanIdentifier=ServiceRegistryRepository, type=ServiceRegistryRepository,node=WSRRNode,process=server1 2. The next step is to create a JMX ObjectName object version from the string: wsadmin>set objectName [$AdminControl makeObjectName $objectNameString] WebSphere:platform=dynamicproxy,cell=WSRRCell,version=6.0.2.11,name= ServiceRegistryRepository,mbeanIdentifier=ServiceRegistryRepository, type=ServiceRegistryRepository,node=WSRRNode,process=server1

8.4.3 Discovering WSRR MBean operations using wsadmin
You can interactively discover the interface of all WSRR MBean operations by using the standard help mechanism of wsadmin. You must pass the string

286

WebSphere Service Registry and Repository Handbook

version of the ObjectName (See 8.4.2, “Locating the WSRR MBean with wsadmin” on page 286): wsadmin>$Help operations $objectNameString This will then respond with a list of possible operations. All available operations have been described in Table 8-2. More information about the Admin MBean operations can be found in the MBean reference documentation: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.ja vadoc.doc/WSRR_MBean.html
Table 8-2 Admin MBean operations Method loadConfiguration loadConfiguration loadConfiguration updateConfiguration updateConfiguration retrieveConfiguration retrieveConfiguration retrieveAllConfigurationNames deleteConfiguration getConfigurationId getConfigurationIds createOntologySystem Description Loads configuration file contents from a byte array, returning ID of created object Loads configuration file contents from given location, returning ID of created object Loads configuration file contents from a File, returning ID of created object Updates configuration file contents of given name Updates configuration file contents of given ID Returns configuration file contents for given ID Returns configuration file contents for given name Returns names (as String) of all configurations for given type Deletes configuration file of given ID Returns ID of configuration document for given name and configuration type Returns IDs for all configuration documents of the given configuration type Creates ontology system Parameters name, type, content, systemConfiguration name, type, location, systemConfiguration name, type, file, systemConfiguration name, type, content, systemConfiguration id, content, systemConfiguration id name, type, systemConfiguration type id name, type type content

Chapter 8. Administering WSRR

287

Method createOntologySystem

Description Loads ontology system contents from given location, returning ID of created ontology system Removes ontology system Imports Service Registry and Repository metadata content returning the list of URIs for objects created Exports metadata XML (as byte array) for specified Service Registry and Repository objects Adds a new role to the Service Registry and Repository authorization component role mapping configuration Removes a role from the Service Registry and Repository authorization component role mapping configuration Adds a principal to a role in the Service Registry and Repository authorization component role mapping configuration Removes a principal from a role in the Service Registry and Repository authorization component role mapping configuration Gets all roles with permissions in the Service Registry and Repository authorization component policy configuration Removes a permission from a role in the Service Registry and Repository authorization component role mapping configuration Removes all permissions from roles in the Service Registry and Repository authorization component policy configuration Removes all roles from the Service Registry and Repository authorization component role mapping configuration

Parameters location

deleteOntologySystem importMetaData

uri xmlBytes

exportMetaData

uris

addRole

roleName

removeRole

roleName

addPrincipalToRole

principalSecurityName, roleName principalSecurityName, roleName

removePrincipalFromRole

getRolesWithPermissions

None

removePermissionFromRole

permissionName, roleName

removeAllRolePermissions

None

removeAllRoles

None

288

WebSphere Service Registry and Repository Handbook

Method addPermissionToRole

Description Adds a permission to a role in the Service Registry and Repository authorization component policy configuration Adds an existing permission to a role in the Service Registry and Repository authorization component policy configuration Returns all permissions (as String) for the given role in the Service Registry and Repository authorization component policy configuration Persist the Service Registry and Repository authorization component policy configuration Persist the Service Registry and Repository authorization component role mapping configuration

Parameters roleName, action, permissionName, permissionTarget roleName, permissionName roleName

addPermissionToRole2

getPermissionsForRole

persistPolicy persistRoleMappings

None None

8.4.4 Discovering WSRR MBean notifications using wsadmin
Using wsadmin help, again with the string version of the ObjectName of the WSRR MBean, you can list the notification events fired by WSRR when certain operations are invoked:
Example 8-1 Discover WSRR MBean notifications using wsadmin

wsadmin>$Help notifications $objectNameString Notifications ibm.serviceregistry.event ibm.serviceregistry.classificationsystem.loaded ibm.serviceregistry.classificationsystem.deleted ibm.serviceregistry.configuration.loaded ibm.serviceregistry.configuration.deleted ibm.serviceregistry.configuration.updated jmx.attribute.changed These events can be monitored programmatically using standard JMX techniques.

8.4.5 Invoking operations on WSRR MBean using wsadmin
To invoke MBean operations, the operation signature and parameters must be passed to the invoke operation of the MBean client. The operation signature

Chapter 8. Administering WSRR

289

specifies each of the parameter types as string values, and the parameters are the corresponding values, as Java objects. As an example, the loadConfiguration operation with the signature that takes a byte[] as the configuration content is used to illustrate how to invoke one of the WSRR MBean operations to load a custom navigation tree for the WSRR Web user interface, from an XML file called CustomNavTree.xml. The full signature of the operation is as follows: java.lang.String loadConfiguration(java.lang.String name, java.lang.String type, byte[] content, boolean systemConfiguration) The return type is the id of the configuration item in the registry. First, read the configuration file into a byte[] as in Example 8-2:
Example 8-2 wsadmin - read configuration file into a byte array

set filename "CustomNavTree.xml" set filepath "C:/configurations" set fis [java::new {java.io.FileInputStream} "$filepath/$filename"] set channel [$fis {getChannel}] set chansize [$channel {size}] Create the byte array object with the same size as the file as in Example 8-3:
Example 8-3 wsadmin - create the byte array object

set content [java::new {byte[]} $chansize] Populate the byte array with the file content as in Example 8-4:
Example 8-4 wsadmin - populate the byte array

$fis read $content Set up the required signature as in Example 8-5:
Example 8-5 wsadmin - set up the signature

set sigs $sigs $sigs $sigs $sigs

[java::new {java.lang.String[]} 4] set 0 java.lang.String set 1 java.lang.String set 2 \[B set 3 boolean

290

WebSphere Service Registry and Repository Handbook

Note: The byte array in the signature must be specified in the Java shorthand notation and the square bracket must be escaped with a backslash character. Also note that the operation requires a boolean primitive, set in the signature as 'boolean' but because the parameters must be specified as an Object[], a java.lang.Boolean is passed. Set the parameter values in the parameters array as in Example 8-6:
Example 8-6 wsadmin - set the parameter values

set name "CustomNavTree" set type "UI_NAVIGATION_TREE" set systemConfig [java::new {java.lang.Boolean} false] set params [java::new {java.lang.Object[]} 4] $params set 0 $name $params set 1 $type $params set 2 $content $params set 3 $systemConfig set id [$AdminControl invoke_jmx $objectName loadConfiguration $params $sigs] The system returns the unique ID of the new configuration.

8.4.6 Troubleshooting WSRR administration with wsadmin
WSRR MBean operation parameters are validated before invoking the operation. Should invalid data be passed to the operation, or the operation results in a system error, the operation will throw an AdminException and cause exception. The messages associated with the AdminException aim to help diagnose the problem. For example, if you tried to load a configuration file using the same configuration name and the same configuration type as a configuration already present in WSRR, the message in Example 8-7 would be returned in the wsadmin scripting client.
Example 8-7 wsadmin - example exception message

javax.management.MBeanException com.ibm.serviceregistry.exception.admin.AdminException: com.ibm.serviceregistry.exception.admin.AdminException: GSR0098E: A

Chapter 8. Administering WSRR

291

ConfigItem with the same name and configuration type already exists in the repository. A limitation of wsadmin is that when an MBeanException is thrown, the wsadmin environment throws a ScriptingException to the client with only the message of the underlying exception, but has no way of retrieving the cause exception. There are circumstances where you may get a com.ibm.serviceregistry.exception.admin.AdminException indicating an operation failed. For example, if you tried to load a configuration with an invalid configuration type of “UI_PERSECTIVE” you would get:
Example 8-8 wsadmin - example invalid configuration type exception

javax.management.MBeanException: null nested exception is com.ibm.serviceregistry.exception.admin.AdminException: GSR0125E: Unable to load configuration. There is a cause exception of type com.ibm.serviceregistry.exception.admin.ConstraintException with a message of “GSR0138E: The configuration type value “UI_PERSECTIVE” is unknown but this is not reported by wsadmin. However, java JMX clients and WSRR command line interface clients are able to catch and handle AdminExceptions and their cause exceptions directly. If you cannot diagnose problems similar in nature to this when invoking administration operations using wsadmin, you can establish the cause by turning on wsadmin trace. To turn on wsadmin tracing: In the directory WAS_HOME/properties, in the file wsadmin.properties, uncomment this line: com.ibm.ws.scripting.traceString=com.ibm.*=all=enabled When you invoke the wsadmin command again, the results are recorded in a file “wsadmin.traceout”, in the directory WAS_HOME\profiles\\logs. This provides a stack trace, including the cause exception and its message.

8.5 Administering WSRR using JMX
WSRR can be managed programmatically by any remote Java client. A client proxy class in ServiceRegistryClient.jar allows you to easily connect to the WSRR MBean and invoke operations by invoking corresponding methods on the proxy, without your classes needing to know about JMX classes or the WSRR MBean.

292

WebSphere Service Registry and Repository Handbook

The ServiceRegistryRepositoryProxy class can be configured and invoked as-is, or, with the provided source code, you can customize it to suit your needs. The source code for this class can be found in the WSRR installation directory, at: /admin/javasrc

8.5.1 Using ServiceRegistryRepositoryProxy.java JMX client
The ServiceRegistryRepositoryProxy class is built around standard code to set up the properties required to connect to the MBean on the target WSRR, establish the connection, locate the WSRR MBean, and then allow further requests to invoke specific operations. The proxy class takes care of casting parameters and return types to the types you expect to use according to the WSRR MBean interface. Exception handling is left as an exercise for the developer but you should look at 8.5.3, “Exception handling with the Java JMX client” on page 296 for information about how to extract the available diagnostic information when an exception is thrown by the WSRR administration component. To invoke operations on the WSRR MBean follow this simple approach: 1. From your own client code, use one of the constructors to get an instance of the ServiceRegistryRepositoryProxy class. This locates the WSRR MBean and stores a reference to it. 2. Prepare parameters according to the WSRR MBean API. 3. Invoke methods on the proxy class, passing the necessary parameters. 4. Handle exceptions. Each of these steps is described in the following sections.

ServiceRegistryRepositoryProxy.java constructors
There are three constructors available, depending on the way that the target server is configured, whether global security is enabled, and which connector type you want to use. Use this constructor when global security is off and you want to use SOAP: public ServiceRegistryRepositoryProxy(String server, String port, String wasHome) Use this constructor when WAS global security is enabled and you want to use SOAP: ServiceRegistryRepositoryProxy(String server, String port, String wasHome, String userName, String userPassword, String

Chapter 8. Administering WSRR

293

trustStorePath, String keyStorePath, String trustStorePassword, String keyStorePassword) Use this constructor if you want to configure the connection separately and choose from the available connector types (SOAP, RMI or JMS): public ServiceRegistryRepositoryProxy(Properties adminProperties) When the connection is established, the proxy (private) method setupMBean attempts to locate the WSRR MBean using this ObjectName query: ObjectName queryName = new ObjectName("WebSphere:type=ServiceRegistryRepository,*"); The queryNames method of AdminClient is invoked which uses the query to search the entire cell for all occurrences of the WSRR MBean. If more than one WSRR MBean ObjectName is found, only the first is used in this implementation, and set as a private object variable for use by other public methods. Note: If you want to run in an environment where there is more than one WSRR application installed in the same cell (for example in WebSphere Application Server Network Deployment), you will need to modify the setupMBean method to use a more specific query that restricts and specifies the server and node such that one MBean reference is obtained. If running the client code from a static main method, the arguments passed could correspond with the parameters required for one of the constructors. For example: String server = args[0]; String soapPort = args[1]; String wasHome = args[2]; ServiceRegistryRepositoryProxy wsrr = new ServiceRegistryRepositoryProxy(server, soapPort, wasHome);

Determining the WSRR MBean API programmatically
The ServiceRegistryRepositoryProxy class provides a utility method (outputMBeanInterface) to programmatically interrogate the ServiceRegistryRepository MBean and output all the available attributes, operations and notifications to System.out. For each operation, the return type, operation name and parameter types are output as well as the impact property which indicates how the operation changes the state of the ServiceRegistryRepository MBean (and the WSRR application). As for all MBeans, the value for the impact property can be one of the following:

294

WebSphere Service Registry and Repository Handbook

ACTION the state of the MBean will be changed INFO the state of the MBean remains unchanged and will return information ACTION_INFO the state of the MBean will change and return some information UNKNOWN the impact of invoking the operation is not known Invoke outputMBeanInterface method (verbose parameter is set to false). The available methods can be found described in Table 8-2 on page 287. The expected output of invoking outputMBeanInterface can be found in the WSRR Information Center: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.do c/twsr_adminstn_adiministration21.html

8.5.2 Invoking WSRR MBean operations with the Java JMX client
As an example, the following code illustrates how to gather a list of the names of all configurations in WSRR for a particular configuration type. The method to invoke is retrieveAllConfigurationNames, with this signature: public List retrieveAllConfigurationNames(String type) The type parameter can be any String but as far as the administration component is concerned, it must be one of the allowed configuration types. To ensure this, use the ConfigurationType class and choose one of the types, in this case UI_DETAIL_VIEW as shown in Example 8-9.
Example 8-9 JMX ConfigurationType example

List uiDetailViewNames = wsrr.retrieveAllConfigurationNames( ConfigurationType.UI_DETAIL_VIEW.toString()); System.out.println("UI detail view configurations:"); Iterator iterator = uiDetailViewNames.iterator(); while (iterator.hasNext()) { String configurationName = (String) iterator.next(); System.out.println(configurationName); }

Chapter 8. Administering WSRR

295

The configuration names are returned as a List to the invoking class. Inspecting the retrieveAllConfigurationNames method in the proxy class shows how the parameters are prepared for invoking the MBean operation: 1. Specify the type of each parameters: String[] signature = new String[] { String.class.getName() }; 2. Place the parameters in an object array: Object[] params = new Object[] { type }; 3. Invoke the method by name and cast the returned object to the required type: List names = (List) invoke("retrieveAllConfigurationNames", signature, params); 4. Return the result: return names; The invoke method in the proxy is used by all other public methods to invoke the actual MBean operation, using the AdminClient object, previously set up in the constructor: return adminClient.invoke(mBean, operation, params, signature); This pattern for invoking MBean operations is the same regardless of whether the client is using Java code, or scripts using wsadmin or the WSRR command line interface.

8.5.3 Exception handling with the Java JMX client
The public methods that correspond to WSRR MBean operations declare they throw the following exceptions: InstanceNotFoundException MBeanException ReflectionException ConnectorException For diagnosing problems caused by invalid parameters, or a problem occurring in WSRR, the important exception to examine is MBeanException. The MBeanServer will add any exceptions thrown by the MBean as the cause exception of an MBeanException. The WSRR MBean will only ever throw com.ibm.serviceregistry.exception.admin.AdminException exceptions, and the following example shows how MBeanException can be examined to get useful diagnostic information.

296

WebSphere Service Registry and Repository Handbook

Note: Do not confuse com.ibm.serviceregistry.exception.admin.AdminException (thrown by WSRR MBean) with the com.ibm.websphere.management.exception.AdminException. Using the previous example, retrieving configuration names for a particular configuration type, the first step is to place a try-catch block around the method call as illustrated in Example 8-10.
Example 8-10 JMX - retrieve configuration names example with try-catch block

try { List uiDetailViewNames = wsrr.retrieveAllConfigurationNames( ConfigurationType.UI_DETAIL_VIEW.toString()); System.out.println("UI detail view configurations:"); Iterator iterator = uiDetailViewNames.iterator(); while (iterator.hasNext()) { String configurationName = (String) iterator.next(); System.out.println(configurationName); } } catch (MBeanException e) { } catch (Exception e) { e.printStackTrace(); } To simplify the example, the InstanceNotFoundException, ReflectionException and ConnectorException are caught in the last catch block and ignored. To determine if the MBeanException contains an AdminException, extract the cause exception as shown in Example 8-11:
Example 8-11 JMX - retrieve configuration names example extract cause exception

} catch (MBeanException e) { if (e.getCause() != null && e.getCause() instanceof AdminException) { AdminException ae = (AdminException) e.getCause(); } } catch (Exception e) { e.printStackTrace(); }

Chapter 8. Administering WSRR

297

In addition to the standard getMessage and getLocalizedMessage from the Exception class, the AdminException (which inherits from ServiceRegistryException) provides several helper methods to pull out more specific information as shown in Example 8-12:
Example 8-12 JMX - retrieve configuration names example with added information

} catch (MBeanException e) { if (e.getCause() != null && e.getCause() instanceof AdminException) { AdminException ae = (AdminException) e.getCause(); System.out.println("Caught AdminException: "); System.out.println("message: " + ae.getMessage()); System.out.println("explanation: " + ae.getExplanationText()); System.out.println("response: " + ae.getResponseText()); if (ae.getCause() != null && ae.getCause() instanceof AdminException) { AdminException ce = (AdminException) ae.getCause(); System.out.println("AdminException cause: "); System.out.println("message: " + ce.getMessage()); System.out.println("explanation: " + ce.getExplanationText()); System.out.println("response: " + ce.getResponseText()); } } } catch (Exception e) { e.printStackTrace(); } The example code outputs the messages using default locale of the system. The methods getExplanationText, getResponseText are overloaded to take a Locale object if you want the message in a particular language. There are other methods available on the ServiceRegistryException class to retrieve the message number, message severity, and the message without the prefix. You can force an AdminException to be thrown by changing this line: List uiDetailViewNames = wsrr.retrieveAllConfigurationNames( ConfigurationType.UI_DETAIL_VIEW.toString()); to this, where the configuration type is invalid: List uiDetailViewNames = wsrr.retrieveAllConfigurationNames( "INVALID_DETAIL_VIEW"); This results in this output are shown in Example 8-13 on page 299.

298

WebSphere Service Registry and Repository Handbook

Example 8-13 Results of invalid configuration type

Caught AdminException: message: GSR0131E: Unable to retrieve all configuration names for configuration type "INVALID_DETAIL_VIEW". explanation: The configuration type may not be valid. The operation may have failed because of a validation error or a system error. If there is a cause exception, its message may offer more explanation. response: Check the type is valid. Correct any validation errors caused by invalid parameters, and check system configuration. AdminException cause: message: GSR0138E: The configuration type value "INVALID_DETAIL_VIEW" is unknown. explanation: The configuration type must be one of the values in the ConfigurationType class. response: Replace the value of the configuration type string with a valid value.

8.6 Administering WSRR using the CLI
Interactive and scripted administration of WSRR is possible with the Jython-based command line interface. The command line interface provides full support for all of the WSRR programmatic APIs, including all administrative operations. It may be used from a standalone Jython or Jacl interpreter, or it may be run inside wsadmin and used in conjunction with the facilities available there. Several example scripts show you how to perform governance tasks such as promoting entities from one WSRR to another, or transitioning entities through different lifecycle states.

8.6.1 Configuring scripting environment
The command line client is invoked through the high level operating system specific script called wsrrcli which sets up the command line environment for accessing Jython and WebSphere Application Server libraries. This script should be configured appropriately as a part of the installation. The following explains the installation and configuration steps.

Install WebSphere, Jython
The WSRR command line client requires that either WebSphere Application Server or WebSphere Application Client be installed. If you are using the application client you will need to install Jython as well.

Chapter 8. Administering WSRR

299

The default method is to copy jython.jar from an application server installation into the AppClient/optionalLibraries/jython directory.

Edit environment variables
The command line client is invoked from scripts installed in /CLI. On Unix-like platforms the script is wsrrcli.sh; on Windows platforms it is WSRRCLI.bat. There are several environment variables referenced in the script. Customize the environment variables to suit your installation: WSRR_HOME – the root of the WSRR installation, something like C:\IBM\WebSphereServiceRegistry or /opt/IBM/WebSphereServiceRegistry. It is used to locate the WSRR client java libraries, scripts, and configuration files. WAS_HOME – the root of the WebSphere installation, something like C:\IBM\WebSphere\AppServer or /opt/IBM/WebSphere/AppClient. It is used to locate WebSphere client java libraries, and so on. JYTHON_HOME – the root of the Jython install, which contains the jython.jar library. By default the command line client uses the Jython from the WebSphere installation. JAVA – the Java executable to be used to execute Jython. By default the command line client uses the JVM™ from the WebSphere installation. It must refer to an IBM JVM.

Edit network and security configuration
The command line client generally refers to a configuration file containing the network connection and security configuration of the service registry repository. A sample is contained in config\wsrrcli.conf, as well as samples of two associated files. Configuring a secure WebSphere environment can be complex, and users interested in the topic should consult the WebSphere Application Server documentation. There are two ways to access the service registry repository, EJB and MBean, and they require different parameters. Find the parameters. EJB connection configuration parameters include: – java.naming.provider.url – com.ibm.CORBA.ConfigURL – com.ibm.CORBA.loginUserid (optional, may be supplied at runtime) – com.ibm.CORBA.loginPassword (optional, may be supplied at runtime)

300

WebSphere Service Registry and Repository Handbook

– java.security.auth.login.config MBean connection configuration parameters include: – host – port – type (SOAP or RMI) – username (optional, may be supplied at runtime) – password (optional, may be supplied at runtime) – securityEnabled – javax.net.ssl.trustStore – javax.net.ssl.keyStore – javax.net.ssl.trustStorePassword – javax.net.ssl.keyStorePassword You may designate an alias by prefixing the parameter names with the alias, thus: AN_ALIAS.host = test21.location.ibm-itso.com This makes it possible to store configuration information for several machines in the same file. The following example (Example 8-14) shows a configuration for two machines, an unsecured machine “open” and a secure machine “secure”. (Note that line breaks have been inserted for readability – refer to file for actual format.)
Example 8-14 Example CLI configuration file

## sample unsecured site -- alias "open" # EJB connection configuration open.java.naming.provider.url = iiop://192.168.1.100:2809 # MBean connection configuration parameters open.host = 192.168.1.100 open.port = 8880 open.type = SOAP open.securityEnabled = false ## sample secure site -- alias "secure" # EJB connection configuration secure.java.naming.provider.url = iiop://192.168.1.101:2809 secure.com.ibm.CORBA.ConfigURL = file:///IBM/WebSphereServiceRegistry/CLI/config/sas.client.props secure.java.security.auth.login.config = file:///IBM/WebSphereServiceRegistry/CLI/config/wsjaas_client.conf # MBean connection configuration parameters

Chapter 8. Administering WSRR

301

secure.host = 192.168.1.101 secure.port = 8880 secure.type = SOAP secure.securityEnabled = true secure.javax.net.ssl.trustStore = C:/IBM/WebSphere/AppClient/etc/DummyClientTrustFile.jks secure.javax.net.ssl.keyStore = C:/IBM/WebSphere/AppClient/etc/DummyClientKeyFile.jks secure.javax.net.ssl.trustStorePassword = WebAS secure.javax.net.ssl.keyStorePassword = WebAS

Test connectivity
Once you have installed and configured the command line client it is a good idea to test that it can connect properly to the WSRR server. The connectTest.py script establishes and tests connections to each of the EJB beans and to the MBean server. To use it, run: wsrrcli connectTest.py -a \ -u -p For example: WSRRCLI.bat scripts\connectTest.py –a open –c config\wsrrcli.conf Or: wsrrcli.sh scripts/connectTest.py –a secure \ –c config/wsrrcli.conf -u username –p passw0rd

8.6.2 Scripting elements and objects
The command line interface provides a thin utility class called the WSRRConnectionFactory that helps in setting up the connections and sessions to the WSRR EJB and MBean objects. These objects can then be manipulated in the Jython scripts to invoke the desired operations on the WSRR API. See below for the API specification for WSRRConnectionFactory class.

Constructor detail
Example 8-15 and Example 8-16 on page 303 detail the two constructors.
Example 8-15 WSRRConnectionFactory constructor

public WSRRConnectionFactory(java.util.Properties newProperties, java.lang.String alias) throws CLIException

302

WebSphere Service Registry and Repository Handbook

Create a new WSRRConnectionFactory directly from a Properties object containing configuration information. An alias may be specified; if null is passed then no alias will be used and the keys in the properties object will be used unmodified. Parameters: newProperties - Properties object containing configuration information alias - alias value, null if no alias is to be used
Example 8-16 WSRRConnectionFactory constructor

public WSRRConnectionFactory(java.lang.String configFileName, java.lang.String alias) throws CLIException Create a new WSRRConnectionFactory from a properties file containing configuration information. If the file name is null an attempt will be made to find the file specified by com.ibm.serviceregistry.cli.ConfigURL. If com.ibm.serviceregistry.cli.ConfigURL is not defined, the file config/wsrrcli.conf will be used. An alias may be specified; if a null is passed then no alias will be used and the keys in the configuration file will be used unmodified. Parameters: configFileName - configuration file name alias - alias value, null if no alias is to be used

Method detail
Example 8-17, Example 8-18 on page 304, Example 8-19 on page 304, Example 8-20 on page 305 and Example 8-21 on page 305 show examples of the available methods.
Example 8-17 getSessionConnection method

public com.ibm.serviceregistry.ServiceRegistrySession getSessionConnection(java.lang.String user, java.lang.String password) throws java.rmi.RemoteException, javax.naming.NamingException, javax.ejb.CreateException, CLIException

Chapter 8. Administering WSRR

303

Returns a connection to the WSRR core session bean, using the session bean connection parameters in the configuration. Parameters: user - user name to use for authentication, or null password - password to use for authentication, or null Returns: ServiceRegistrySession instance
Example 8-18 getOntologyConnection method

public com.ibm.serviceregistry.ServiceRegistryOntology getOntologyConnection(java.lang.String user, java.lang.String password) throws java.rmi.RemoteException, javax.naming.NamingException, javax.ejb.CreateException, CLIException Returns connection to the WSRR Ontology manager, using the session bean connection parameters in the configuration. Parameters: user - user name to use for authentication, or null password - password to use for authentication, or null Returns: ServiceRegistryOntology instance
Example 8-19 getGovernanceConnection method

public com.ibm.serviceregistry.governance.ServiceRegistryGovernance getGovernanceConnection(java.lang.String user, java.lang.String password) throws java.rmi.RemoteException, javax.naming.NamingException, javax.ejb.CreateException, CLIException Returns connection to the WSRR Governance bean, using the session bean connection parameters in the configuration. Parameters: user - user name to use for authentication, or null

304

WebSphere Service Registry and Repository Handbook

password - password to use for authentication, or null Returns: ServiceRegistryGovernance instance
Example 8-20 getServiceRegistryRepositoryProxy method

public com.ibm.serviceregistry.admin.ServiceRegistryRepositoryProxy getServiceRegistryRepositoryProxy(String user, String password) throws ServiceRegistryException { Gets ServiceRegistryRepositoryProxy instance using mbean connection parameters from configuration. The proxy represents a ServiceRegistryRepository MBean and provices methods that correspond to the operations defined in the ServiceRegistryRepository MBean descriptor. Parameters: user - user name to use for authentication, or null password - password to use for authentication, null Returns: ServiceRegistryRepositoryProxy instance
Example 8-21 getProperties method

public java.util.Properties getProperties() Returns a copy of the properties used to configure this instance of the connection factory. Returns: copy of Properties object for this connection factory Refer to the following API specifications for more details on the API operations that are available to be invoked from the command line scripts: WSRR External programmatic API: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.do c/rwsr_api.html WSRR MBean API: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.ja vadoc.doc/WSRR_MBean.html

Chapter 8. Administering WSRR

305

8.6.3 Sample scripts
A number of scripts are provided with the WSRR command line client for illustrative purposes. Some of these scripts are utility scripts while others use the utility scripts and perform programmatic and administrative tasks such as creating content in WSRR, state transitions, export, import, find, and so on. Though all the provided scripts are written in Jython, users are free to create and use Jacl scripts instead of Jython using the API objects available. All the sample scripts can be found in the \CLI\scripts directory. The sample script cmdline.py provides methods that provides utility methods to parse and validate command line arguments supplied to the command line scripts. The fileUtils.py and utils.py scripts provide utility methods to read and write byte arrays from files, and to find objects by name, namespace, and version in the Service Registry. The createGenericObject.py is a sample script used to create generic objects with the specified name, namespace and version information. Usage: createGenericObject.py -a -c -u -p -n -ns -v The createXMLDocument.py script is used to create an XML document in the Service Registry from the supplied input file Usage: createXMLDocument.py -a -c -u -p -in -n -ns -v -loc The findBaseObject.py script queries the Service Registry for the requested object based on the name, namespace and version. Usage: findBaseObject.py -a -c -u -p -n -ns -v The deleteBaseObject.py script removes the object(s) from the Service Registry that findBasObject.py would return. Usage: deleteBaseObject.py -a -c -u -p -n -ns -v The export.py script exports the specified object into a file on the local file system. Usage: export.py -a -c -u -p -n -ns -v -out

306

WebSphere Service Registry and Repository Handbook

The import.py script imports an object into a WSRR instance from the supplied file Usage: import.py -a -c -u -p -in The promote.py script promotes an object from one WSRR instance to another Usage: promote.py -c -sp -tp -v -s -su -t -tu -n -ns

The transition.py script executes a transition on an object in the WSRR instance. Usage: transition.py -a -c -u -p -n -ns -v -t The loadConfig.py script loads configuration data to WSRR instance from the specified file. Usage: loadConfig.py -a -c -u -p -n -t -in The retrieveConfig.py script retrieves configuration object from WSRR instance and optionally stores it to specified file. Usage: retrieveConfig.py -a -c -u -p -n -t -out The deleteConfig.py script deletes a configuration object from WSRR. Usage: deleteConfig.py -a -c -u -p -n -t The updateConfig.py script updates the specified configuration object in the WSRR instance from the specified file. Usage: updateConfig.py -a -c -u -p -n -t -in

8.7 Ontology administration
Classification systems or taxonomies are represented in WSRR as ontologies, in the form of OWL (Web Ontology Language) files. The WSRR MBean operations available to manage ontologies are createOntologySystem and deleteOntologySystem as shown in Example 8-22.

Chapter 8. Administering WSRR

307

Example 8-22 Ontology Administration MBean operations

java.lang.String createOntologySystem(byte[] content) [ACTION] (Creates ontology system) java.lang.String createOntologySystem(java.lang.String location) [ACTION] (Loads ontology system contents from given location, returning ID of created ontology system) void deleteOntologySystem(java.lang.String uri) [ACTION] (Removes ontology system) Ontologies can also be loaded and removed from WSRR using the Web user interface by users in the Administrator role. Note: There is no updateOntologySystem method in the WSRR MBean. To update an ontology it must be deleted and then recreated.

8.7.1 Creating an ontology system
To create an ontology system in WSRR, your ontology must exist as an OWL document. OWL documents are best created using dedicated tooling although you could create an OWL document using a text or XML editor, according to the OWL schema definition. The WSRR MBean provides two operations to create ontology systems: Create an ontology system from byte array: java.lang.String createOntologySystem(byte[] content) Create an ontology system from an OWL document hosted at a URL: java.lang.String createOntologySystem(java.lang.String location) Both operations return the OWL URI of the ontology system. As soon as the ontology is system is created it is immediately available for use in the Web user interface. Use the Jacl script \admin\scripts\loadOntologySystem.jacl to create an ontology system from an OWL document on the file system.

8.7.2 Removing an ontology system
To remove an ontology system from WSRR, use the MBean operation: void deleteOntologySystem(java.lang.String uri)

308

WebSphere Service Registry and Repository Handbook

The uri parameter is the OWL URI of the ontology system. When an ontology system is deleted, it is no longer available for use in the Web user interface. A Jacl script is provided to perform this operation using wsadmin: \admin\scripts\deleteOntologySystem.jacl Note: Before removing an ontology system you should consider the impact to users who may have classified WSRR entities with the ontology. Deleting the ontology system will not remove classification URIs from entities, so queries relying on these classifications will still work. However, if users try to view an entity with a classification that no longer exists in an ontology system, the UI will not be able to retrieve the corresponding labels and will report an error. In addition, users will not be able to add further classifications from that ontology system.

8.8 Access control administration
Fine-grained access control to WSRR artefacts is applied if WebSphere global security is enabled. The WSRR authorization component will initially try to find a policy in the WSRR configuration files. If successful it will load and use that policy. If no policy is found a default policy is generated at runtime and stored within WSRR for use when the application next starts.

8.8.1 Overview of access control within WSRR
Fine-level control of access to artefacts in WSRR is role-based and is similar in concept to the standard, declarative scheme used to control access to the individual methods of an EJB. Within WSRR, the following types of access are defined: Create Permission to create an artefact in WSRR. Update Permission to update a particular artefact in WSRR Delete Permission to delete a given artefact from WSRR Retrieve Permission to retrieve information from a particular artefact in WSRR.

Chapter 8. Administering WSRR

309

Transition Permission to apply a transition as defined by an existing governance lifecycle to an artefact in WSRR. Each of these types of permission is independent of all the others, and there are no implicit relationships between them. For instance, permission to delete an artefact does not imply that permission to update the same artefact is automatically granted, although permission to update could be defined explicitly. Permissions are granted to roles. The number and names of the roles used to control access within WSRR is configurable by the user. Typically each role defined would map to a group of users defined within the user authentication scheme being used. Permissions are then granted to each of the defined roles as appropriate and all users belonging to a given role have the access permissions granted to that role. The artefacts to which a particular permission applies are defined using a subset of XPath. Using this subset it is possible to specify sets of artefacts by their type (WSDLDocument for example), by their modelled and user-defined properties, and by their classification. In this way sets of artefacts can be defined in a generic way. Once permission for a given type of access has been defined for a particular set of artefacts, for a given role, then every role which requires that access to that set of artefacts must be granted that permission explicitly. Expressing it a different way: access to all artefacts within the registry is unrestricted until a permission is granted protecting a particular set of artefacts. Once this happens explicit permission is then required for the defined access type to the defined set of artefacts. Note: The statements made in the preceding paragraph apply independently to each of the permission types defined previously. For example, granting update permission to a role for a set of artefacts will not protect those artefacts from deletion by any role. That protection must come from an explicit declaration of delete permission granted to the appropriate role, after which users in other roles will not be able to delete them without explicit permission.

8.8.2 Administering the WSRR access control policy
Although the access control policy used within WSRR is defined as two XACML configuration files, it is strongly recommended that these are not modified directly. JMX operations for administering the access control policy used by WSRR are accessible via the WSRR MBean. These operations provide the means to add and remove roles within the configuration, and also allow the

310

WebSphere Service Registry and Repository Handbook

addition and removal of permissions for those roles. Operations are also available to ensure changes made to the policy are made permanent such that the saved policy is available when WSRR is restarted. Jacl scripts to apply these operations are supplied in the \admin\scripts directory. Refer to the following documentation sources for further information. WebSphere Application Server scripting: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/topic/com.ibm. websphere.base.doc/info/aes/ae/txml_scriptingep.html WSRR MBean API specification: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.ja vadoc.doc/WSRR_MBean.html

8.9 Import/Export
WSRR provides a facility for exporting collections of entities, with their associated metadata, to a file, and importing that file back into another WSRR instance. The WSRR export function extracts entities from the source registry and writes a document describing selected entities and their properties, relationships and classifications. The WSRR import function reads the export document and publishes the entities with their metadata into a target registry. This enables a number of possible administrative tasks, for example: Selective backup and restore Promotion to another WSRR instance (see 8.10, “Environment promotion” on page 319) Bulk loading of registry metadata WSRR defines a schema for the format of this import/export file. This schema is proprietary and published but is expected to change in forthcoming releases as standards in this area emerge. It is recognized that users may want to manipulate the exported data for administrative tasks so the schema has been provided and is explained in a subsequent section.

8.9.1 Export
Only original documents should be exported, as all logical objects and metadata associated with the original document will be exported to support it; this is because the logical objects and metadata cannot exist without the original

Chapter 8. Administering WSRR

311

document, so any metadata exported must also have its original document exported. The export function is based on the document bsrURI, so some pre-selection of documents for export must be carried out. Document pre-selection and export can be performed within the Web user interface. An exported document will be accompanied by everything to which it is related; if it is related to some metadata from another document then that document will be contained within the export. The exported content is then a full WSRR representation of anything to which the requested document is related, taken to the full hierarchical depth. If a large portion of the documents in the registry are connected via relationships then simply exporting one could result in this large portion of the WSRR also being exported. Care should be taken to avoid large portions of the registry being connected in this manner and some examination of the document for export should be carried out. Export should not be used with a large list of documents. It should be noted that the bsrURI is exported as a normal property; however on import, the value of this will be overwritten by a bsrURI specific to the import registry. In addition, the exported file will contain only the classification URI, not the ontology to which this refers. To export artefacts from WSRR through the UI, use the Export button provided in the document collection views. Figure 8-1 shows the Policy documents collection, the export button is circled.

Figure 8-1 Exporting documents using the Web UI

312

WebSphere Service Registry and Repository Handbook

8.9.2 Import
Since files for import can be created outside WSRR, and those exported from WSRR can be manipulated, the import process follows the same process and validation as normal creation of the document. This ensures that badly formed import/export files will not cause problems for the registry. The difference with import is that the file for import will contain not only the original document but its full WSRR representation, with all supporting documents, relationships, user-defined properties and classifications. These will also get created in the same transaction. The document explicitly exported must not exist in the registry on import as this would have the same effect as trying to create an already existing document. Supporting documents can, however, already exist within the registry and the import will attempt to find these supporting documents and use any existing ones in place of those in the import file. As a result, the document imported will match that in the import/export file at the top level; however, as relationships are followed down the graph, documents may be encountered which already exist within the repository. Import will not alter these pre-existing supporting documents so importing a document can only result in the creation of new documents or relationships to existing ones; it will not result in the altering of an already existing document. If it is required that the import/export file exactly matches the registry after import, then either none of the supporting documents should exist within the repository, or each supporting document should have been previously imported. Any logical objects (also referred to as logical derivations) included within the import file are used to update logical objects created through the normal creation process. Therefore, for the purposes of import, if these logical objects are not present in the import file then the import will go through the normal creation process and they will be created anyway. If the logical objects are present in the import file then any user defined properties, relationships, and classifications can be added to the created logical objects during import. Modelled properties will not be overridden. The following examples illustrate the process: 1. A is related to B: – If A is exported then B will be exported as a supporting document – If the export file is then imported into a registry which already contains B, A is created and the relationship is set up to the existing B which remains unmodified. The supporting B in the import file is not used so any user

Chapter 8. Administering WSRR

313

defined metadata on B in the import file is not set on the existing B in the registry. 2. A is related to B, and B is related to C: – If A is exported then B and C will be exported as supporting documents. – If the export file is then imported into a registry which already contains B, A is created and the relationship is setup to the existing B which remains unmodified. The supporting B in the import file is not used so any user defined metadata on B in the import file is not set on the existing B in the registry. C is also created since it was originally related to A via B but the existing B is not updated since the relationship B to C may not be valid in this new registry. However, since C is created it is possible to manually create this relationship from B to C after the import has completed. 3. A logical object of A (logA) is related to a logical object of B (logB): – If A is exported then logA will also be exported. Since logA is related to logB, B will be exported together with logB as a supporting document. – If the export file is then imported into a registry which already contains B and, consequently, logB, then A is created, and the logA that is created as a result of creating A has a relationship set up to the already existing logB. B and logB remain unchanged. The supporting B and logB in the import file are not used so any user defined metadata on B in the import file is not set on the existing B in the registry. Documents can be imported using the Web UI, click Administration → Import. Figure 8-2 shows the import screen.

Figure 8-2 Importing a document using the Web UI

314

WebSphere Service Registry and Repository Handbook

8.9.3 Import and export with the CLI
The command line interface can also be used to manage import and export of WSRR entities. The export.py script (see Example 8-23) and the import.py script (see Example 8-24 on page 316) demonstrate this function. Both scripts can be found in the \CLI\scripts directory. Refer to 8.6, “Administering WSRR using the CLI” on page 299 for further details on the use of the CLI.
Example 8-23 WSRR CLI export.py script

## export object from WSRR instance to file # usage: jython export.py -a -c -u -p -n -ns -v -out import sys options = [ [ "-a", "alias" ], [ "-c", "configFile" ], [ "-u", "user" ], [ "-p", "password" ], [ "-n", "objectName" ], [ "-ns", "objectNamespace" ], [ "-v", "objectVersion" ], [ "-out", "outputFile" ] ] ## process command line arguments import cmdline cmdline.processArgs(sys.argv, options, globals()) ## export object from WSRR to file import utils metadata = utils.export(alias, configFile, user, password, objectName, objectNamespace, objectVersion) # store export in file if metadata != None : from java.io import FileOutputStream outStream = FileOutputStream(outputFile) outStream.write(metadata) outStream.close()

Chapter 8. Administering WSRR

315

Example 8-24 WSRR CLI import.py script

## import object to WSRR instance from file # usage: jython import.py -a -c -u -p -in import sys options = [ [ "-a", "alias" ], [ "-c", "configFile" ], [ "-u", "user" ], [ "-p", "password" ], [ "-in", "inputFile" ] ] ## process command line arguments import cmdline cmdline.processArgs(sys.argv, options, globals()) # read metadata from file import fileUtils metadata = fileUtils.readByteArray(inputFile) ## import metadata into WSRR instance from com.ibm.serviceregistry.cli import WSRRConnectionFactory connectionFactory = WSRRConnectionFactory(configFile, alias) mbeanProxy = connectionFactory.getServiceRegistryRepositoryProxy(user, password) uris = mbeanProxy.importMetaData(metadata) if uris == None : print "No uris imported" else : print "imported", uris

8.9.4 Processing import / export files
The schema for import/export files, WSRRImportExport.xsd, can be found in the \admin\schemas directory, where is the directory location in which the WSRR files were installed. A simple example of an export file for an XML document is shown in Example 8-25 on page 317.

316

WebSphere Service Registry and Repository Handbook

Example 8-25 Example export file for an XML document

testXMLtoSOAPElement: This is the description testXMLtoSOAPElement 1 testXMLtoSOAPElement

Chapter 8. Administering WSRR

317

 File://thisIsMyClassification/fred File://thisIsMyOtherClassification/wilma I am property value more property values The file contains a list of RequestedObject elements, each with an id. This id is used within the import/export file to apply properties, relationships, and so on, to the correct document. The RequestedObject is used to indicate which of the following MetadataSections must be created on import and cannot already exist. For each RequestedObject there is a MetaData element with a matching id which will contain the MetadataSection for this object along with MetadataSection elements for supporting documents, logical objects and further elements for properties, relationships and classifications.

Loading documents into WSRR through an import file
Since import follows the normal logic for creating a document, the contents of the import file can be incomplete with respect to what is actually stored within the repository. The minimum information required within the import file is the same minimum information required when adding something to the repository. With this information to hand, an import file could be written to load documents into the repository with the ability to specify user defined relationships between them.

318

WebSphere Service Registry and Repository Handbook

8.10 Environment promotion
Environment promotion is the process of moving a service from one WSRR environment to another. For instance, there may be multiple Service Registries corresponding to a development WSRR environment, a test WSRR environment, and a production WSRR environment; so, environment promotion is the movement of a service from development to test to production.

8.10.1 Promotion mechanism
Environment promotion is achieved through the command line interface. The promote mechanism is implemented as a script and can be configured for custom requirements. An example of this kind of configuration could be the state of an entity. WSRR entities can contain a variety of metadata. Some of this metadata, such as IT service endpoints, may need to change when an entity is promoted. The environment promotion script allows the user to configure the promotion for their environment. A typical environment promotion script would perform tasks in the order specified here: 1. A check is performed on the state of the specified entity. 2. An export of the entity is performed on the source WSRR instance, storing the exported contents into a file. 3. An import of the entity is performed on the target WSRR instance, obtaining the imported contents from the same file (see above). 4. The state of the imported entity is changed. A callout to a user script could be added between items #2 and #3, to perform the transformation. Or the transformation can be added inline by changing the default promotion script. Since promotion is a scripted form of export/import the promotion scheme - what will be promoted - is based on export/import. For instance, if an entity is promoted that has a specified classification, and if that classification does not exist in the target WSRR instance, the promotion will fail. Or, if an entity A is promoted and it has references to other entities, when it is imported into the target WSRR it and its dependencies will also be created.

8.10.2 Sample script for promotion
A sample promotion script (promote.py) is provided with the WSRR command line interface to illustrate how an import/export mechanism could be utilized to perform environment promotion.

Chapter 8. Administering WSRR

319

Example 8-26 WSRR Sample promotion script

## Promote an object from one WSRR instance to another # usage: jython promote.py -c -s -su -sp -t -tu -tp -n -ns -v import sys options = [ [ "-c", "configFile" ], [ "-s", "sourceAlias" ], [ "-su", "sourceUserName" ], [ "-sp", "sourcePassword" ], [ "-t", "targetAlias" ], [ "-tu", "targerUserName" ], [ "-tp", "targetPassword" ], [ "-n", "objectName" ], [ "-ns", "objectNamespace" ], [ "-v", "objectVersion" ] ] ## process command line arguments import cmdline cmdline.processArgs(sys.argv, options, globals()) ## export metadata from source WSRR instance import utils metadata = utils.export(sourceAlias, configFile, sourceUserName, sourcePassword, objectName, objectNamespace, objectVersion) ## metadata is a byte array at this point ## it can be transformed in any way desired, providing the result is legal WSRR import/export format ## for example, it may be turned into a string, subjected to pattern substitution, and then turned back into a byte array ## or it may be parsed into an XML document model and transformed with XSLT ## --> your transformation here -f The command is entered as one line. The script filename parameter is the path to the Jacl script file. The script parameters are specific to each script, as described below. Additional parameters are required if you are managing WSRR in a WebSphere Application Server that has global security enabled, or you want to use RMI instead of SOAP. These parameters are described by the wsadmin usage message and in the WebSphere Application Server documentation. The WebSphere Application Server must be in started state, as must the ServiceRegistry application.

Chapter 8. Administering WSRR

321

8.11.1 Scripts for managing configuration
These scripts help manage configuration items in WSRR, allowing you to load, update, delete, and view details about loaded configurations. loadConfiguration.jacl updateConfiguration.jacl deleteConfiguration.jacl reportAllConfigurations.jacl

8.11.2 Scripts for managing ontologies
Classification systems or taxonomies must be defined as Web Ontology Language (OWL) files. The following scripts allow you to load and delete ontologies. loadOntologySystem.jacl deleteOntologySystem.jacl Note: There is no MBean operation for updateOntologySystem.

8.11.3 Scripts for import and export of WSRR entities
The following scripts allow you to export entities from WSRR and import them into another WSRR. exportMetaData.jacl importMetaData.jacl

8.11.4 Scripts for managing access control policy
Fine grained control of access to entities in WSRR is achieved using the following administration scripts. Scripts (or directly invoked MBean operations) that change access control policies will immediately change the runtime behavior of WSRR with the new access control policies. However, these changes would be lost if the WSRR application is restarted. To persist the active access control policy configurations, invoke the two operations persistPolicy and persistRoleMappings. This can be achieved with the scripts persistPolicy.jacl and persistRoleMappings respectively. addPermissionToRole.jacl addPermissionToRole2.jacl

322

WebSphere Service Registry and Repository Handbook

addPrincipalToRole.jacl addRole.jacl getPermissionsForRole.jacl getPolicyConfiguration.jacl getRoleMappingConfiguration.jacl getRoles.jacl loadPolicyConfiguration.jacl loadRoleMappingConfiguration.jacl persistPolicy.jacl persistRoleMappings.jacl removeAllRolePermissions.jacl removeAllRoles.jacl removePermissionFromRole.jacl removePrincipalFromRole.jacl removeRole.jacl

8.11.5 Scripts for managing lifecycles
These scripts illustrate how to go about setting the lifecycles used by the governance component of WSRR, and the associated access control policies. setupDefaultLifecyclePermissions.jacl updateLifecycleDefinition.jacl

Chapter 8. Administering WSRR

323

324

WebSphere Service Registry and Repository Handbook

Part 4

Part

4

Using WSRR

© Copyright IBM Corp. 2007. All rights reserved.

325

326

WebSphere Service Registry and Repository Handbook

9

Chapter 9.

Getting started with WSRR
This chapter describes how to use the core functionality of WSRR from the Web user interface (Web UI). It will cover how to work with documents, properties, relationships, classifications and concepts. It contains the following: 9.1, “Introduction” on page 328 9.2, “Navigating the Web UI” on page 329 9.3, “Publishing documents” on page 331 9.4, “Properties” on page 335 9.5, “Relationships” on page 347 9.6, “Classifying objects” on page 358 9.7, “Searching the registry” on page 363 9.8, “Deleting artefacts” on page 369 9.9, “Concepts” on page 370

© Copyright IBM Corp. 2007. All rights reserved.

327

9.1 Introduction
Chapter 7, “Installing and deploying” on page 253 explains how to install WebSphere Service Registry and Repository. We now cover how to use the main interface to it, the Web UI. The Web UI enables you to use and manage all aspects of WSRR from a compatible Web browser. Figure 9-1 shows the WSRR Web UI welcome window.

Figure 9-1 WSRR Web UI

This chapter covers the basics of how to use the Web UI. It will then guide you through using it to perform some basic operations such as loading a document, adding relationships, classifications, and so on.

328

WebSphere Service Registry and Repository Handbook

9.2 Navigating the Web UI
We cover the structure of the Web UI in 4.3.1, “Web user interface layout” on page 145. When looking at the Web UI (as in Figure 9-1 on page 328), at the top of the screen there are some basic links that will always be present as the “banner” area of the frameset is not customizable. There is a drop down list to select a different perspective. (Creating new perspectives is covered in Chapter 10, “Customizing the Web UI” on page 381.) There are also links to Logout, there is a link to the WSRR Support site and a link to some basic Web UI Help on the current screen. To the left-hand side is the navigation pane. This is where you choose what operations to perform. Selecting a link here will normally load some content or the operation output in the workarea pane to the right. At the top of the navigation pane is a link to the welcome window (Figure 9-1 on page 328). Under this is the quick search box and then links to different areas of functionality in WSRR. Each of these is briefly described in the sections that follow.

9.2.1 Quick search
Use the quick search field at the top left of the navigation tree to find any type of object stored in the registry. The search is performed on the entire registry using an exact-case match on the text entered. It is matched against the name and description properties of any object. The text is used as a partial match; for example, a search for “Echo” would return both “Echo.wsdl” and “MyEcho”. You can specify an asterisk (*) in any part of the search text to denote that any number of other characters are permitted to occur at that position in the search results.

9.2.2 Unified Service Metadata
Use the Unified Service Metadata section of the navigation tree to work with views of business-oriented or abstract concepts. By default, the Unified Service Metadata section contains just two views, Concepts and Templates. Concepts are entities in the registry that cannot be represented using the standard WSRR document types such as WSDL and XSD. The Concepts link shows all concept entities that are stored in the registry. The Templates link shows all the available templates that can be used to create concepts.

Chapter 9. Getting started with WSRR

329

9.2.3 Service Documents
Use the Service Documents section of the navigation tree to work with all of the documents stored in the registry, and to load new documents into the registry.

9.2.4 Service Metadata
Use the Service Metadata section of the navigation tree to work with all of the derived logical objects stored in the registry. Every time a document is loaded into the registry, it is parsed and a rich logical view of the contained XML elements is generated and stored along with the original document. WSDL documents, XML schema documents, and SCA modules all have associated logical elements derived from them and stored on upload. Each document type that has logical elements has an expandable section in the navigation tree that contains links to collections of the more important types of derived logical objects for the document.

9.2.5 Queries
Use the query wizard to perform selected queries against objects stored in the registry. See 9.7, “Searching the registry” on page 363 for more information.

9.2.6 Classification systems
Use classifications in the registry to make objects easier to find, and also to add meaning to custom objects that are unique to a particular system. WSRR supports classification systems loaded from OWL files (Web Ontology Language). While the underlying OWL sub-system supports most forms of OWL files, the most useful types are ones that have simple hierarchical relationships; those for example, found in industry standard taxonomies such as NAICS (North American Industry Classification System). See 9.6, “Classifying objects” on page 358 for more information.

9.2.7 My Service Registry
Use the My Service Registry section of the navigation tree to work with information that is specific to you, as the current user: My subscriptions shows the list of all subscriptions in the registry that are owned by the currently logged-in user. This enables you to determine what objects are

330

WebSphere Service Registry and Repository Handbook

currently being monitored. Administrators have an additional link that shows the list of all subscriptions currently active in the registry for all users. My favorites shows the list of objects in the registry that the current user has selected as favorites. My preferences shows configuration settings that allow you to alter the appearance of elements in the Web UI. The only setting that can be changed currently is the time zone that you want to use when dates and times are displayed on screen.

9.2.8 Administration
The Administration section of the navigation tree allows an administrator to import objects into the registry. Only files generated by the export facility can be imported back into the registry. No other file formats are supported.

9.3 Publishing documents
In order to populate WSRR, documents such as WSDLs and XSDs must be loaded. The process of loading the document creates all the logical objects that are derived from the original source document. Once the document is loaded, both the original source document and the derived logical objects can then be annotated with metadata. Assuming you have a WSDL file locally that you want to load into WSRR, use the following steps.

Chapter 9. Getting started with WSRR

331

1. From the navigation pane expand the Service Documents section and then select Load Document as shown in Figure 9-2.

Figure 9-2 Load document menu option

Alternatively there is a Load Document button on the collection view for each of the supported Service Document types as shown in Figure 9-3.

Figure 9-3 Load document link on XSD collection view

2. The load document wizard should then open in the workarea tab.

332

WebSphere Service Registry and Repository Handbook

3. Select the document you want to load and optionally specify a description and version for it. If you loaded the wizard using the Load Document link from the navigation tree then you must also specify the document type. See Figure 9-4 for an example of the load document wizard.

Figure 9-4 Load document wizard

Chapter 9. Getting started with WSRR

333

4. The document should now be loaded and a screen similar to Figure 9-5 should display.

Figure 9-5 Load document results

Once the document has been loaded a detail page summarizes the properties of the object. There are also links to the logical objects that were derived from the source document.

334

WebSphere Service Registry and Repository Handbook

Any properties that are not read-only may be set from this page. The changes will be committed when either the “OK” or the “Apply” buttons are pressed. Clicking on the Content tab shows the contents of the source document (as in Figure 9-6).

Figure 9-6 Document content view

9.4 Properties
WSRR is not intended to be an editor for any of the artefacts it stores. For instance, when the WSDL for a service is published to WSRR, read-only logical elements are created to represent its contents. These elements are read-only because changing their properties would mean the logical model would no longer be in sync with the content of the original WSDL document.

Chapter 9. Getting started with WSRR

335

Properties, relationships and classifications allow a user to annotate the objects within WSRR with service metadata. This service metadata can then be used both internally, by WSRR, and externally by clients extracting information from WSRR. Properties within WSRR are modelled as String properties on the underlying SDOs and so consequently the properties are shown as simple name/value pairs. Within the SDO property names must be unique. Therefore, it is not possible to define a property or relationship on an object if a property or relationship of the same name already exists on that object.

9.4.1 Adding a new custom property
To add a new custom property to the StockQuote.wsdl we just loaded follow these steps. 1. Navigate to the document and then click Custom Properties as shown in Figure 9-7.

Figure 9-7 Document custom properties link

336

WebSphere Service Registry and Repository Handbook

2. The list of current properties on the document will then appear. Clicking on the name of any of the existing properties will allow you to edit the value of that property. Some of the properties are compulsory, and so the delete check box next to those properties is greyed out. At the top of this list is a New button as shown in Figure 9-8. Click New.

Figure 9-8 Document custom properties

Chapter 9. Getting started with WSRR

337

3. You will then be prompted for a Key and Value for the new custom property. Enter your desired values for these fields as demonstrated in Figure 9-9. Then click OK.

Figure 9-9 Entering values for the new custom property

338

WebSphere Service Registry and Repository Handbook

4. The new property has now been added and you should see it in the list of properties, as shown in Figure 9-10.

Figure 9-10 The newly added custom property

Chapter 9. Getting started with WSRR

339

It is also possible to add the same custom property to multiple documents at once from the collective view. Select the check box for all the desired documents in the collective view and then click the Add Property button as shown in Figure 9-11.

Figure 9-11 Adding custom properties to multiple documents

9.4.2 Editing a property
To edit a property, whether it is a predefined property or a custom property, follow these steps.

340

WebSphere Service Registry and Repository Handbook

1. From the document’s details page select Custom properties from the Additional properties links on the right, as highlighted in Figure 9-12.

Figure 9-12 Custom properties link

Chapter 9. Getting started with WSRR

341

2. Click the name of the property you want to edit. In Figure 9-13 we are going to edit the value of the “ServiceLevel” custom property.

Figure 9-13 Selecting a property to edit

342

WebSphere Service Registry and Repository Handbook

3. Change the value of the property to whatever you want it to be and then click OK (see Figure 9-14).

Figure 9-14 Edit property value

Chapter 9. Getting started with WSRR

343

4. You should then be able to see the new value for the property in the properties list as shown in Figure 9-15.

Figure 9-15 Edit property result

9.4.3 Deleting a custom property
Predefined properties cannot be deleted. However, to delete a custom property follow these steps.

344

WebSphere Service Registry and Repository Handbook

1. From the document’s details page select Custom properties from the Additional properties links on the right, as highlighted in Figure 9-16.

Figure 9-16 Custom properties link

Chapter 9. Getting started with WSRR

345

2. Select the check box for the custom property you want to delete and then click the Delete button as highlighted in Figure 9-17.

Figure 9-17 Delete custom property

3. You should now get a confirmation message that the property was deleted as in Figure 9-18 on page 347.

346

WebSphere Service Registry and Repository Handbook

Figure 9-18 Delete custom property result

9.5 Relationships
Relationships, similar to properties, allow users to annotate objects in WSRR with service metadata. They are modelled within WSRR as List properties on the underlying SDOs. They are 1:many (1 source object, many target objects) and are uni-directional. The object on which the relationship is defined is the source object of the relationship. The relationship property contains the list of WSRR objects that are the target of the relationship.

9.5.1 Creating a new relationship
To create a relationship follow these steps. 1. Select the document to create the relationship from. 2. From that document’s details view select the Custom relationships link from the Relationships links on the right. This is highlighted in Figure 9-19 on page 348.

Chapter 9. Getting started with WSRR

347

Figure 9-19 Custom relationships link

3. Click New in the custom relationships window as shown in Figure 9-20 on page 349.

348

WebSphere Service Registry and Repository Handbook

Figure 9-20 Create new custom relationship

It is also possible to add a new relationship to multiple documents at once using the Add relationship button on the document collective view as shown in Figure 9-21 on page 350.

Chapter 9. Getting started with WSRR

349

Figure 9-21 Add a relationship to multiple documents

4. The custom relationship wizard should now open. Enter a name for the relationship and click Next as shown in Figure 9-22 on page 351.

350

WebSphere Service Registry and Repository Handbook

Figure 9-22 New relationship - relationship name

5. You will now need to find the document(s) to create a relationship to. Select the type of document to query for and then click Next (see Figure 9-23).

Figure 9-23 New relationship - query document type

6. You now need to enter the search criteria to find the specific documents to create a relationship to. You can query by different criteria, in our case we knew the name of the document “Address.wsdl” and so typed that in the Name field, as shown in Figure 9-24 on page 352. Click Next once you have entered the desired search criteria.

Chapter 9. Getting started with WSRR

351

Figure 9-24 New relationship - query document details

7. It will now display the results of your search query. You can now select the precise documents you want to create a relationship to. Check the check box next to the desired target document and click Next. (See Figure 9-25 on page 353.)

352

WebSphere Service Registry and Repository Handbook

Figure 9-25 New relationship - select document

8. You will now see a summary of the proposed new relationship as shown in Figure 9-26. If all the details seem correct then click Finish.

Figure 9-26 New relationship - summary

Chapter 9. Getting started with WSRR

353

9. The relationship has now been created and you should see output similar to that in Figure 9-27.

Figure 9-27 New relationship - result

9.5.2 Editing an existing relationship
Once a relationship has been created, it is only possible to add or remove target objects from it. To do this, follow these steps: 1. From the source document’s detail view click Custom relationships as highlighted in Figure 9-28 on page 355.

354

WebSphere Service Registry and Repository Handbook

Figure 9-28 Custom relationships link

2. When the custom relationships list appears, click the name of the relationship you want to edit, as shown in Figure 9-29 on page 356.

Chapter 9. Getting started with WSRR

355

Figure 9-29 Edit relationship - select relationship

3. You will then be displayed with the list of current targets for that relationship similar to Figure 9-30. To add a new target click the Add button and you will then have to follow a similar process to that used to find the target of the relationship when creating a new relationship in 9.5.1, “Creating a new relationship” on page 347. The main differences are that you cannot specify the relationship name and you must specify a target object. To remove a target, check the check box next to that target and click the Remove button.

Figure 9-30 Edit relationship - targets

356

WebSphere Service Registry and Repository Handbook

9.5.3 Deleting a relationship
1. To delete an existing relationship navigate to the relationships collection view on the relevant object and then check the check box next to the relationship you want to delete and click Delete. This is shown in Figure 9-31.

Figure 9-31 Delete relationship

2. You should now see a confirmation message similar to that in Figure 9-32.

Figure 9-32 Delete relationship result

Chapter 9. Getting started with WSRR

357

9.6 Classifying objects
Classifications can be used to make finding objects easier and to add meaning to entities unique to a customer’s environment. They are defined as OWL files (Web Ontology Language). It is possible to import user-defined OWL files, however this operation can only be performed by a WSRR Administrator. Classifications currently support simple hierarchies or parents and children and are modelled as list properties on the classified entity.

9.6.1 Loading an OWL file
This task can only be performed by WSRR Administrators. 1. Select Load classification system from the navigator under “Classification Systems” (highlighted in Figure 9-33).

Figure 9-33 Load classification link

2. You will then be prompted for the path to the OWL file. Either type in the path to your OWL file or browse until you find it. Then click OK. (See Figure 9-34 on page 359.)

358

WebSphere Service Registry and Repository Handbook

Figure 9-34 Load classification

3. Once the classification has been loaded you should see a confirmation message similar to that displayed in Figure 9-35.

Figure 9-35 Load classification result

9.6.2 Browsing classifications
In order to see the available ontologies use the following steps.

Chapter 9. Getting started with WSRR

359

1. Select Browse classification systems from the “Classification systems” section of the navigation pane as highlighted in Figure 9-36.

Figure 9-36 Browse classifications link

2. You should then see a tree structure representing all of the loaded ontologies as shown in Figure 9-37.

Figure 9-37 Classifications tree structure

360

WebSphere Service Registry and Repository Handbook

9.6.3 Removing a classification
To remove a classification follow these steps: 1. Select Browse classification systems from the Classification systems section of the navigation pane as highlighted in Figure 9-36 on page 360. 2. Check the check box for the classification tree you want to delete and then click the Delete button, as shown in Figure 9-38.

Figure 9-38 Delete classifications

3. You should then get confirmation the classification was deleted.

9.6.4 Classifying an entity
To classify an object in WSRR follow these steps: 1. Browse to the detail view of the entity you want to classify 2. Select Classifications from the Relationships links on the right-hand side as highlighted in Figure 9-39 on page 362.

Chapter 9. Getting started with WSRR

361

Figure 9-39 Classifications link

3. Select the classification you want to classify this entity as, from the tree structure on the left and then click the Add button. This is shown in Figure 9-40 on page 363.

362

WebSphere Service Registry and Repository Handbook

Figure 9-40 Add classifications to an entity

4. You should now see your added classification in the “Classification List” box on the right. Click the OK button. Note: Multiple classifications can be added at the same time, just keep selecting classifications from the tree on the right and click the Add button. 5. Your classification has now been added and you should have been returned to the detail view for the entity.

9.7 Searching the registry
The query wizard allows queries based on the following criteria: Different specific types of entity All entity types Entity name

Chapter 9. Getting started with WSRR

363

Custom property name or value Classifications Some entity property (for example, namespace) AND or OR queries To use the query wizard follow the example. In this example we will search for the document that we added the classification to in 9.6.4, “Classifying an entity” on page 361. 1. Select Query wizard from the navigation pane under “Queries” as highlighted in Figure 9-41.

Figure 9-41 Query wizard link

2. Select the type of query from the drop down list shown in Figure 9-42 on page 365. For the purposes of this example we will query by classification, and so we selected Entities by Classification. Then click OK.

364

WebSphere Service Registry and Repository Handbook

Figure 9-42 Select the type of query

3. The query wizard window should appear as shown in Figure 9-43 on page 366. We will leave the query set to use AND and leave the Name field blank. Check the “Match children” check box and then click the Choose button.

Chapter 9. Getting started with WSRR

365

Figure 9-43 Query by classification

4. The classification wizard will then appear as shown in Figure 9-44 on page 367. In order to demonstrate the “match children” field working we will select the parent of the classification we used in 9.6.4, “Classifying an entity” on page 361. Then click the Add button and then the OK button.

366

WebSphere Service Registry and Repository Handbook

Figure 9-44 Select the classification to query for

5. You should now see the classification you selected in the list box on the query wizard screen, as shown in Figure 9-45 on page 368. Click Next.

Chapter 9. Getting started with WSRR

367

Figure 9-45 Query wizard after selecting classification

6. The query wizard will now display a summary of the query to be run (see Figure 9-46 on page 369). Click Finish.

368

WebSphere Service Registry and Repository Handbook

Figure 9-46 Query wizard summary

7. The query results should now be displayed. Figure 9-47 shows an example of the results screen.

Figure 9-47 Query wizard results

9.8 Deleting artefacts
To delete a document from WSRR use the following steps.

Chapter 9. Getting started with WSRR

369

1. First you must navigate to the collection view for the type of document you want to delete. 2. Then select the check boxes next to the document that you want to delete and click the Delete button as shown in Figure 9-48.

Figure 9-48 Delete a document

3. You should then receive a confirmation message to state the document was deleted from WSRR.

9.9 Concepts
WSRR models the content of the artefacts that it stores. However, it is possible you will want to work with business objects that do not exactly match those

370

WebSphere Service Registry and Repository Handbook

defined within WSRR. These could include MQ endpoints, capabilities, verbs, and so on. It is not possible for WSRR to model all possible business objects that might be required. Concepts provide a way of modelling the business objects that you might need to represent within an SOA environment. Note: Concept is the Web UI term for GenericObject.

9.9.1 Defining a concept template
WSRR used XML schema complex types to define the structure of the concepts. The complex type acts as a template when creating an instance of the concept. In the XML an attribute of type string defined on the complex type results in a custom property being added to the new concept. If an attribute of type IDREFS is defined on the complex type then a custom relationship will be added to the new concept. As an example, the Application complex type shown in Example 9-1 defines a businessOwner attribute of type string and referencedServices and referencedProcesses attributes of type IDREFS.
Example 9-1 Example concept complex type definition

Creating a new concept instance using the Application template would result in a new concept with the following metadata associated with it: A custom property called businessOwner A custom relationship called referencedServices A custom relationship called referencedProcesses

9.9.2 Classifying a complex type as a template
A complex type that can be used to create instances of concepts must first be classified as a template within WSRR.

Chapter 9. Getting started with WSRR

371

The Template classification is provided within WSRR as part of the “WSRR Core Ontology” as shown in Figure 9-49.

Figure 9-49 Template classification

To classify a complex type as a Template follow the instructions in 9.6.4, “Classifying an entity” on page 361 but use the Template classification.

9.9.3 Viewing templates
The templates that have been defined in WSRR can be viewed by selecting the Templates link from the navigation pane as highlighted in Figure 9-50.

Figure 9-50 List templates link

372

WebSphere Service Registry and Repository Handbook

This will then display a screen similar to that shown in Figure 9-51, displaying a list of the templates currently available in WSRR.

Figure 9-51 List of available templates

Clicking on an individual template will display the details for that specific template as shown in Figure 9-52 on page 374.

Chapter 9. Getting started with WSRR

373

Figure 9-52 Template details view

9.9.4 Creating a concept from a template
To create a new instance of a concept follow these steps: 1. Select Templates from the navigation pane as shown in Figure 9-53 on page 375.

374

WebSphere Service Registry and Repository Handbook

Figure 9-53 Templates link

2. Select the Template you want to use for the new concept instance. Click the Create new instance button as shown in Figure 9-54.

Figure 9-54 Create new instance from a template

Chapter 9. Getting started with WSRR

375

3. Fill in the fields as necessary for your template and then click OK. The example shown in Figure 9-55 is based on the JMSEndpoint template created by the WMB V6 Client for WebSphere Service Registry and Repository.

Figure 9-55 New instance of a template - details

4. Your new instance should now have been created. The next section will explain how to view the details on it. Custom properties that will be added by the template are shown in a separate section below the General Properties. Custom relationships defined by the template are not shown until after the new concept instance has been created.

376

WebSphere Service Registry and Repository Handbook

As a result, targets for the custom relationships cannot be defined during creation.

9.9.5 Viewing the details of a concept
1. To view details of a concept click the Concepts link on the navigation pane as shown in Figure 9-56.

Figure 9-56 Concepts link

2. The concepts collection view will then display 3. Then click the concept you want to see the details of. You should then see the details of that concept. For instance, Figure 9-57 on page 378 shows the details for the concept we created in 9.9.4, “Creating a concept from a template” on page 374.

Chapter 9. Getting started with WSRR

377

Figure 9-57 Details of a concept

9.9.6 Deleting a concept
1. To delete a concept click the Concepts link on the navigation pane, as shown in Figure 9-56 on page 377. 2. From the concepts collection view, select the concepts you want to delete and then click the Delete button, as highlighted in Figure 9-58 on page 379.

378

WebSphere Service Registry and Repository Handbook

Figure 9-58 Delete a concept

3. You should then receive confirmation the concept was deleted.

Chapter 9. Getting started with WSRR

379

380

WebSphere Service Registry and Repository Handbook

10

Chapter 10.

Customizing the Web UI
This chapter discusses how to customize the WSRR Web user interface (Web UI). It will use the sample scenario provided with the WMB V6 Client for WebSphere Service Registry and Repository SupportPac™ as a demonstration of some of the capabilities. This chapter describes the following: 10.1, “Introduction” on page 382 10.2, “View query definitions” on page 382 10.3, “Navigation trees” on page 390 10.4, “Perspectives” on page 394 10.5, “Collection views” on page 401 10.6, “Managing UI customization configurations” on page 411

© Copyright IBM Corp. 2007. All rights reserved.

381

10.1 Introduction
As covered in 4.3, “Web user interface (Web UI)” on page 144, WSRR provides extensive customization capabilities for its user interface. These customization capabilities range from simply modifying the properties that are displayed on an existing view of a service to deploying a whole new perspective that defines new views for the information stored in Service Registry and Repository. This new perspective may be specific to a certain kind of user within your organization, using terminology that the user can understand and restricting the information displayed to the minimum that allows the user to perform their day-to-day job. Section 4.3, “Web user interface (Web UI)” on page 144 describes the concepts and architecture of the WebSphere Service Registry and Repository Web user interface. This chapter goes into more detail on the underlying technology powering that flexibility and how you can customize it for your own needs. For demonstration purposes we will use the example scenario that comes with the WebSphere Message Broker V6 Client for WebSphere Service Registry and Repository SupportPac. The scenario is described in more detail in 16.7, “WMB Client support for SOA patterns” on page 803. We will describe how to perform the customizations necessary for that scenario, however the UI customization files necessary for it are actually provided with the SupportPac in the following directory: \Tests\WSRRTestEntities\GUIConfiguration Where is the directory the WMB V6 Client for WebSphere Service Registry and Repository is installed to.

10.2 View query definitions
The WSRR view query system is a highly customizable method of creating predefined queries against the contents of the registry. It uses a simple XML file that defines the parameters of each query, associating that query with a unique identifier. These queries then form the main method of providing links from the navigation tree to show relevant views in the user interface. Users can customize existing or new navigation trees in the UI by defining additional view queries in a new view query definition file and then referencing the new queries in the navigation tree. This chapter will describe how to understand and create view query definition files and will go on to describe how to apply those view queries to a custom navigation tree as part of a custom perspective view.

382

WebSphere Service Registry and Repository Handbook

View query definitions allow you to perform a rich set of queries against just about any type of object that WSRR can store. The possible parameters include object type, classifications, properties and relationships, all of which can be used in any combination. This covers all three categories of metadata that WSRR supports so should allow the maximum flexibility to find the required objects in the registry. Let us begin with a simple view query which we can build on to explain other features. In Example 10-1 the XML namespace attributes are listed for informational purposes, however they will be omitted from the later examples in this chapter for the sake of clarity.
Example 10-1 Basic view query

WSDLService Each view consists of a separate Query element that is contained within the QueryDefinitions element. There is no limit to the number of queries that can be defined except for physical storage since each one will be represented in memory at startup. Each query must have a unique ID represented as the “id” attribute within the Query element. It is recommended that the query ID start with a short prefix so as to minimize the chances of a name conflict with other view query definitions already defined in the system. Note that there is one exception to the unique ID rule; it is possible to override an existing system-defined view query with a user-defined one by creating the user view query with the same ID. This should only be used with caution since changing a system view query could affect the expected operation of the default perspective views. The query in Example 10-1 returns all WSDLService objects currently stored in the registry and introduces the ObjectType element. The object type is an optional element that filters the query to return only objects of the given type. The type can only be chosen from a fixed list of types that correspond to the Service Data Objects (SDO) types currently supported for querying in the registry. Table 10-1 on page 384 shows the list of valid object types that can be used.

Chapter 10. Customizing the Web UI

383

Table 10-1 Valid object types Object type WSDLDocument XMLDocument XSDDocument PolicyDocument GenericObject WSDLBinding WSDLMessage WSDLOperation WSDLPart WSDLPort WSDLPortType WSDLService SOAPAddress SOAPBinding XSDAttribute XSDComplexType XSDSimpleType XMLElement SCAModule ModuleDocument ImportDocument ExportDocument Module Import Export SCAImportBinding Description WSDL document XML document XML schema definition document Policy document Generic object (displayed as Concept in the UI) WSDL binding logical object WSDL message logical object WSDL operation logical object WSDL message part logical object WSDL port logical object WSDL port type logical object WSDL service logical object SOAP address logical object SOAP binding logical object XSD attribute logical object XSD complex type logical object XSD simple type logical object XML element logical object SCA module container (SCA) module document (SCA) import document (SCA) export document (SCA) module logical object (SCA) import logical object (SCA) export logical object SCA import binding logical object

384

WebSphere Service Registry and Repository Handbook

Object type SLSBImportBinding WebServiceImportBinding SCAWSDLPortType SCAExportBinding WebServiceExportBinding Subscription

Description (SCA) Stateless session bean import binding logical object (SCA) Web service import binding logical object SCA WSDL port type logical object SCA export binding logical object (SCA) Web service export binding logical object Subscription object

Note: GenericObject is the API name for the objects that appear in the Web UI as Concepts. The ObjectType element is not a required setting - omitting the value will cause the query to consider all searchable registry objects as part of the query (that is, all objects that derive from the BaseObject SDO parent class).

10.2.1 Using alternative views
The query in Example 10-1 on page 383 will use the default collection view definition for a WSDLService object, however we can choose to use a different view to display the results of the query. In our example WMB Patterns scenario, we have some extra properties being stored in our endpoints and it would be helpful to display those new values in the query results views. This is achieved using the DisplayType element as shown in Example 10-2 (an XML snippet taken from MBPatternViewQueryDefinition.xml as supplied in the WMB V6 Client for WebSphere Service Registry and Repository). Example 10-2 is querying by classification not ObjectType, this is explained in 10.2.4, “Querying by classification” on page 387, but does not affect how using alternative views works.
Example 10-2 Using alternative views

MBPatternEndpoint http://eis.ibm.com/ServiceRegistry/GenericObjectTypes#Endpoint

Chapter 10. Customizing the Web UI

385

 The DisplayType element instructs the Web UI to use a different view definition to display the results of the query. This view definition is referenced by its unique ID which is mapped to a collection view definition in the perspective definition file. More detailed information about how to create perspectives and view definitions can be found in 10.4, “Perspectives” on page 394.

10.2.2 Querying by property
The view query system has support for querying by property using the Property element. The Property element has two attributes that specify the name and value of the property being queried. Each one is an exact match test, that is, there are no wild cards permitted in the name and value. Example 10-3 shows an example which we could use in the WMB Pattern scenario.
Example 10-3 Querying by property

MBPatternEndpoint In this example the query is looking for all objects that contain a property called “endpointtype” that has an exact value of “JMS”. It's also possible to omit either one of name or value to widen the search. Omitting the value attribute will change the query such that it will now search for all objects of the given type that contain a property of the given name regardless of the value. Similarly, omitting the value attribute will change the meaning of the query such that it will now search for all objects of the given type that contain any property that has the given value as an exact match.

10.2.3 Querying by relationship
Querying by relationship allows you to find objects in the registry specifically by their relationship to another object. This uses the Relationship element and its associated Target child element. A typical usage of this is when using templated

386

WebSphere Service Registry and Repository Handbook

objects to ensure that the objects found in the search are of the correct templated type. Example 10-4 shows the syntax of just such a query:
Example 10-4 Querying by relationship

GenericObject This query reads as “find all the generic objects that have a relationship called 'template' where the target object of that relationship has a name of 'JMSEndpoint'”. This introduces several new elements to the query. Firstly, the Relationship element which declares that the query is looking for a relationship on the objects of the given type. This has one optional attribute that gives the specific name of the relationship to look for which can be either a modelled relationship or a user-defined relationship. This is an exact match test and wild cards are not expanded in the value. Omitting the name of the relationship means the query will look for target objects for any relationship on the initial list of objects filtered by the given type. The Relationship element can contain a Target child element that directs the query to consider the objects that are at the target of the relationship. The Target element must contain exactly one Property element declaring which name/value pair to look for on the target object. It is not possible to specify more than one property to look for when considering the target objects of a relationship. The rules for the Property element when used within a target object search are exactly the same as when they are used in the main body of the query. The Target element is optional - omitting it means that the query will be widened to search purely for objects that have the named relationship.

10.2.4 Querying by classification
The view query system has four different elements to cover all the ways that classifications can be used as part of a query. Each of these elements then contains any number of ClassificationURI elements that build up a list of classifications to search for. Classifications are specified as the fully qualified

Chapter 10. Customizing the Web UI

387

OWL URI from the classification system that was used to classify the object. Searches involving classifications that have child OWL URIs in the classification system (that is, there are additional classifications that are a subClassOf the given URI in OWL terms) can additionally be used such that the URI given and all of its inferred child URIs are also considered as part of the search. For example a classification search on “Fruit” with inference would also consider “Apple” and “Orange” as additional classifications as part of the search. Table 10-2 shows the four elements and their behavior.
Table 10-2 Classification elements Element QueryClassificationsAnyOf Meaning Find objects that are classified by any of the given URIs and additionally consider any inferred child URIs from each URI in the initial list. Find objects that are classified by all of the given URIs and additionally consider any inferred child URIs from each URI in the initial list. Find objects that are classified exactly by any of the given URIs without using inference. Find objects that are classified exactly by all of the given URIs without using inference.

QueryClassificationsAllOf

QueryExactClassificationsAnyOf QueryExactClassificationsAllOf

For our example WMB Patterns scenario we use a simple OWL file to classify services. It is used to mark services as a particular type and impose a hierarchy where JMSEndpoint, MQEndpoint and URLEndpoint are all children of Endpoint. Example 10-5 shows a snippet from the OWL file used. The complete file can be found here: \Tests\WSRRTestEntities\Classifications\GenericObjec tTypes.owl
Example 10-5 Sample OWL file

388

WebSphere Service Registry and Repository Handbook

MB Nodes Concept Types Endpoint JMSEndpoint URLEndpoint MQEndpoint In our WMB Patterns scenario we use a view query using classifications to show the MQEndpoints as shown in Example 10-6.
Example 10-6 Querying by classification

MBPatternMQEndpoint http://eis.ibm.com/ServiceRegistry/GenericObjectTypes#MQEndpoint

Chapter 10. Customizing the Web UI

389

 View queries are restricted to allowing just one classification-type element per query, chosen from the list of four available. Finding the fully qualified OWL URI for a classification value can sometimes be tricky even if you have access to the source of the OWL document. There is a simple procedure that can be used in the Web UI that will allow you to find the full URI of any classification value. In the Web UI, navigate to any object either in a collection view or detail view. From a collection view, select the object from the list and click Add classifications, or from a detail view, click the Classifications link in the relationships section. Note that you do not need to update the object with new classifications, this is purely to get a specific view in the Web UI. Once in the classifications view, the full OWL URI of any classification value can be obtained by selecting the classification in the classification list which then shows the full details of that value in the table at the bottom of the page. The URI can then be copied and pasted from the Web UI. If the classification value is not in the list, then it can be added to the list by browsing the tree, selecting the value and clicking the Add button. If you are not intending to update the classifications on the object, remember to click the Cancel button when complete.

10.3 Navigation trees
In the WSRR Web UI, the navigation tree is always available on the left side of the page and acts as the table of contents for the current perspective view. As part of customizing the UI, this is where you decide which views will be useful for the target audience of the perspective. A well designed navigation tree will allow you to find the information you need quickly and with only a few mouse clicks. This section will explain how to create a custom navigation tree and how the navigation tree definition file and the view query definition file combine to form the completed navigation tree. Figure 10-1 on page 391 shows the example navigation tree that forms part of the scenario for this chapter.

390

WebSphere Service Registry and Repository Handbook

Figure 10-1 Example navigation tree

The navigation tree for our WMB Patterns scenario introduces a completely new top-level grouping called “Message Broker Pattern Metadata” which collects together all the custom views that we need for monitoring the services in the registry. It also re-uses the query wizard, classification, and other sections from the default navigation trees supplied with WSRR.

Built-in standard features
The navigation tree has a link to the welcome page and a quick search box that are shown at the top of the navigation tree pane. These are always present and cannot be configured or customized through the navigation view definition or the view query definition files. Figure 10-2 on page 392 shows how the navigation tree definition combines with the view query definitions to form the final view.

Chapter 10. Customizing the Web UI

391

Navigation tree

Navigation tree definition

View query definition MBPatternRouter http://eis.ibm.com/ServiceRegistry/GenericObject Types#Router

Figure 10-2 Linking navigation tree and view query

The diagram shows that there are two parts to each node definition in the navigation tree. The display part is a resource key (and optional resource bundle) that defines the text to be displayed for the node in the tree, and the link part that defines what action will be performed when you click the link in the tree. In our example, the link runs the view query specified by the view query ID in the navigation tree node. Example 10-7 shows part of the navigation tree definition file used to display the tree for the sample scenario.
Example 10-7 Example navigation tree

... ... ... The enclosing NavigationTree element has just one attribute name that must be unique within the context of all navigation trees within WSRR. This name is used directly by the perspective definition file to declare which navigation tree to use. There is only one other element node used to construct the navigation tree. Node elements can be nested to any depth and will form the tree hierarchy in the navigation pane of the Web UI. The outer-most node with the ID of “navtree_root” must be present in the definition file - it doesn't get displayed but acts as the container for all the displayable nodes. The first level nodes under the root node form the main content sections of the tree and are highlighted as main headings in the navigation pane. Content sections cannot be set as links to views, they only serve to contain other nodes and are always displayed in the navigation pane. The node element has just two required attributes: id which must be unique within the navigation definition file and node-resource-key which defines the key to use in the resource file for the display text for the node. To go with the resource key there is the optional node-resource-bundle attribute that lets you specify a different resource file to load display text from. If this is omitted, then the resource bundle defaults to the built-in resources used by the Web UI. Any user-supplied resource properties file must be available on the WAS classpath - in the default profile the easiest directory to use would be /profiles/default/classes.

Chapter 10. Customizing the Web UI

393

There are two ways to specify the way the active link works when using the node element. The main way is to use the view-query-id attribute and specify its value as the ID of a view query stored in a view query definition file. View query links are typically used to display collections of objects stored in the registry, however not every possible view or action in WSRR can be represented by a view query so there is a second attribute forward that can be used to forward to the special view, wizard or action. Table 10-3 details exactly what forwards can be used and what action they perform.
Table 10-3 Special navigation forwards Forward LoadDocument QueryWizardPrepare LoadClassificationSystem BrowseClassificationSystem ListMySubscriptions ListMyFavourites ShowPreferences ImportDocuments Action performed Displays the load document page Displays the first page of the query wizard Displays the load classification system page administrator task only Displays the available classification systems in a browsable tree view Displays the subscriptions specifically for the current user Displays the list of favorites for the current user Displays the UI preferences for the current user Displays the first page of the import documents wizard for importing a WSRR export file - administrator task only

10.4 Perspectives
Perspectives are used in the WSRR Web User Interface to provide a user role the appropriate view of the data and the ability to perform their tasks. The Administrator perspective allows you to load classification systems and import data among other tasks. The User perspective lets you browse the classification system, load documents and browse the artefacts in the Service Registry and Repository. The perspective developed for the WMB Patterns scenario shows metadata relevant to their business. In order to show the WMB Patterns scenario metadata, we have created a custom MB Pattern User perspective which shows the navigation tree from Figure 10-1 on page 391 and their services' operational and static metadata in collection and detail views.

394

WebSphere Service Registry and Repository Handbook

A perspective definition describes the title of the perspective, the navigation tree, which user roles are permitted to use the perspective, and which collection and detail views are to be shown. Figure 10-3 shows the MB Pattern User perspective starting page.

Figure 10-3 The MB Pattern User perspective

10.4.1 A skeleton perspective definition
A skeleton perspective file is shown in Example 10-8. The perspective definition name is blank, there are placeholders for the title, roles and navigation tree, and no mappings.
Example 10-8 Skeleton perspective definition

Chapter 10. Customizing the Web UI

395

 role navigation-tree-name

10.4.2 Adding name, title and roles
Every perspective has a name, which is independent of the definition file name. This name is only used by the WSRR internally. For our MB Pattern User perspective we use the name MBPatternUser. Because definitions are stored by their file name, we recommend always using the definition name as the file name. In our case, the perspective is stored in a file called MBPatternUserPerspectiveDefinition.xml. The title message which appears in the perspective drop-down is defined using a resource bundle key name. By default this key is resolved using the WSRR Web UI resource bundle which is not customizable. The attribute resource-bundle-name is used to specify a different resource bundle which you provide. In this example, we use the resource bundle MBPatternResources for all messages.

Definition name uniqueness
The perspective definition name is a unique key which identifies the definition among other definitions of the same type. Every perspective definition must have a unique name among perspectives. We therefore advise using a prefix for all of your definitions.

Resource key uniqueness
A resource key must be unique within its resource bundle. By specifying a different resource bundle, your resource keys only need to be unique within that bundle. As discussed in 4.3.2, “Perspectives” on page 147, each perspective specifies a set of permissible user roles which can access the perspective. A user needs to be in one of these roles to use the perspective. Because we want all users to be able to view the MB Pattern User perspective, we specify only one entry of User. In the MB Pattern User perspective file MBPatternUserPerspectiveDefinition.xml the perspective definition has a definition name, title and role added, as shown in

396

WebSphere Service Registry and Repository Handbook

Example 10-9. The file MBPatternUserPerspectiveDefinition.xml can be found in the following folder: \Tests\WSRRTestEntities\GUIConfiguration
Example 10-9 Perspective name, title and a role

User ...

10.4.3 The navigation tree and weight
A perspective has a single navigation tree which is shown in the navigation pane when the perspective is active. The navigation-tree-name element specifies the name of the navigation tree to use, as defined in the navigation tree definition XML file. In 10.3, “Navigation trees” on page 390 we showed the navigation tree developed for the WMB Patterns scenario which groups services according to endpoint type, called MBPatternUserNavigationTree. We want this to be the navigation tree for our perspective. Each perspective has a weight which defines the weight of the perspective relative to others within the WSRR user interface. When a user logs into the WSRR Web UI, the perspective with the highest weight is used as the current perspective. The weight of the MB Pattern User perspective will be 40. Two perspectives are provided with the WSRR user interface. The Administrator perspective has a weight of 100 and the User perspective has a weight of 70. Therefore the Administrator perspective is the default. If you want your perspective to be the default one, give it a weight greater than 100.

Chapter 10. Customizing the Web UI

397

Example 10-10 shows the MB Pattern User perspective definition which specifies a weight of 40 and a navigation tree called MBPatternUserNavigationTree.
Example 10-10 Perspective weight and navigation tree

User MBPatternUserNavigationTree ...

10.4.4 Collection and detail view mappings
Required mappings
A perspective contains a set of mappings for collection and detail views. They map between a display type name and the definition name of a view. Whenever a view is needed, it is looked up in the current perspective using the mappings. This is significant in several ways. Firstly, whenever the WSRR user interface displays an entity, it is actually showing a Service Data Object (SDO) instance from the WSRR API. Each different type of entity within WSRR is represented by a different type of SDO, each SDO type has a distinct type name. By default, when the WSRR user interface displays an entity, it uses the SDO type name as the display type and looks up a detail view definition in the current perspective. Therefore, to show an entity such as a WSDL Document or WSDL Service, a mapping for the display type “WSDLDocument” or “WSDLService” must be in the current perspective. This applies to all SDO types in WSRR; they must all have a

398

WebSphere Service Registry and Repository Handbook

detail view mapping to be displayed. Consequently there is a list of detail view mappings which should be present in all perspective definitions, if you want to be able to display all entities. Secondly the WSRR detail views link to collection views of related entities, such as the WSDL ports of a WSDL document. The query wizard also uses a set of collection views to display results, the quick search box uses a specific collection view to display results, and the classification browser uses a specific collection view. Consequently there is a list of collection view mappings which should be present in all perspective definitions, for non-customizable parts of the user interface to use. Thirdly any of the views used by the WSRR user interface can potentially be overridden to specify your own detail and collection views. You can also use entirely unique names to identify your new views, then refer to these names within collection and detail view definitions. The complete MB Pattern User perspective definition in the \Tests\WSRRTestEntities\GUIConfiguration directory contains all the necessary mappings. These are the mappings present in the WSRR User perspective. To copy the mappings directly, you can extract the User perspective definition from WSRR using the administration interface. See Chapter 8, “Administering WSRR” on page 281 for more details.

Customized mappings
We have developed several collection views detail views for the WMB Pattern scenario. These views show the static and operational metadata of interest to the scenario. In order to use them from view queries and collection views, these views must be added to the mapping sections. To add mappings for our new collection views, the collection-view-mappings element has several view-mapping elements added. These map between the display type names used in the view queries in 10.2, “View query definitions” on page 382 and our collection views. The mappings are shown in Example 10-11.
Example 10-11 New collection view mappings

Chapter 10. Customizing the Web UI

399

 ... To add mappings for our new detail views the detail-view-mappings element has a new view-mapping element added, as shown in Example 10-12.
Example 10-12 New detail view mappings

...

10.4.5 Perspective resources
The title key used in the perspective definition has to be added to the resource file we specified in the definition. This was MBPatternResources. Example 10-13 shows the key used.
Example 10-13 Perspective messages

# resources for the MB Pattern User perspective mbpattern.perspective.display.name.user=MB Pattern User

400

WebSphere Service Registry and Repository Handbook

10.5 Collection views
Collection views are used extensively in the WSRR Web UI. Query results, lists of WSDL Documents, the operations in a port type; all of these are collection views and all are defined in the same way. Collection views show a set of entities from the WSRR. The collection views developed for the WMB Patterns scenario show their business metadata as columns for each entity in the collection. In order to show all deployed endpoints in the WMB Patterns scenario, we have created a set of collection views. Each collection view shows metadata of interest to the WMB Patterns scenario; the name, description and namespace for each endpoint or routing. In this section we show how to create such a collection view. A collection view definition describes the properties of the WSRR entities that are to be displayed in columns within the view and also which action buttons should be displayed. Figure 10-4 shows the collection view used to display all MQ Endpoints.

Figure 10-4 A WMB Patterns scenario collection view

10.5.1 Collection view areas
A collection view has several aspects which are specified in a collection view definition. These are the title, description, column headings, the properties which provide the values for rows in the view, and the buttons. The buttons are

Chapter 10. Customizing the Web UI

401

each specified in a button definition. A column heading and which property is used is specified in the column definition. Figure 10-5 shows these areas.
Title

Description

Button Definitions

Column Definition

Column Definition

Column Definition

Column Definition

Figure 10-5 Areas of the collection view

10.5.2 A skeleton collection view
A skeleton collection view file is shown in Example 10-14. The definition name is blank, there are placeholders for the title and description, and a single empty column definition. Collection view definitions are stored in the folder named collection underneath the folder named views in your project. We will extend this skeleton to make a collection view intended to display all MQ Endpoints.
Example 10-14 Skeleton collection view definition

402

WebSphere Service Registry and Repository Handbook

 property-name

10.5.3 Adding name, title and description
Every view definition has a name, which is independent of the definition file name. This name is used in the view mappings in the perspective. For this view we will use the name MBPatternMQEndpointCollection. The title and description messages which appear on the collection view are defined using two resource bundle key names. By default these keys are resolved using the WSRR Web UI resource bundle which is not customizable. The attribute resource-bundle-name is used to specify a different resource bundle which you provide. In this article, we use the resource bundle MBPatternResources for all messages. The title and description we use state that the view is showing all monitored services.

Definition name uniqueness
Every collection view definition must have a unique definition name among collection views. We therefore advise using a prefix for all of your definitions. In this scenario, we use “MBPattern” as our prefix.

Resource key uniqueness
A resource key must be unique within its resource bundle. By specifying a different resource bundle, your resource keys only need to be unique within that bundle. Update the skeleton as shown in Example 10-15 to add a definition name, title and description keys.
Example 10-15 Adding the messages

property-name The title appears in several places; at the top of the collection view and in the portlet title. It also appears as the entry in the bread crumb trail. Figure 10-6 shows where these new additions appear.

Figure 10-6 The title and description on the view

Reusing view definition content
In order to create a new collection view definition which differs from another by only the title and description, it is necessary to create an entirely new view definition, copying the column and button definitions into the new definition.

10.5.4 Collection view columns
A collection view definition can contain one or more column definitions. A column definition describes the heading message for the column, again using a message key and resource bundle. Recall that a collection view shows a set of entities

404

WebSphere Service Registry and Repository Handbook

from WSRR, each in a row. Each entity has a number of properties with a name and value. A column definition identifies the name of a property on the entity, the value of which is shown in the cell. This is done by the value of the property element. A cell value can be rendered as plain text, or as a HTML link which links to a detail view of the entity in the row. Typically the first column of a collection view is a set of HTML links allowing the user to see details of the entities shown. Adding an action element with the value of DetailView makes the cell a link to a detail view. You can specify which detail view is used to show the entity, using a customized view instead of the Web UI default. This is done by adding a display-type element, the value of which is mapped to a detail view name in the perspective. We will use the customized detail view developed for the WMB Pattern scenario to show the MQ endpoints, called MBPatternMQEndpoint. The first column in our view will show the name of the entity. All entities in WSRR have a property called name which contains their name. Modify the column-definition element to specify a message key for the column heading, our resource bundle, the property name of name, add an action element with a value of ViewDetail and a display-type element with a value of MBPatternMQEndpoint. The new column definition is shown in Example 10-16.
Example 10-16 Adding a name column

name ViewDetail MBPatternMQEndpoint Figure 10-7 on page 406 shows the column you added to the collection view.

Chapter 10. Customizing the Web UI

405

Figure 10-7 The name column in the view

The value of display-type means the detail view looks up the view mapped to the display type MBPatternMQEndpoint in the MB Pattern User perspective. This is the detail view we shall develop later in this chapter. For other columns, we want the cell values shown as plain text, so we will omit the action element. The entities shown in a collection view are Service Data Objects (SDOs), each of which has predefined properties, for example name or version. They can also have user defined properties, which can be added from the Web UI or the API. Both predefined and user defined property names can be specified in a collection view definition. If a user defined property has not been added to a particular entity, the cell will be empty. We need to add the metadata of interest to our scenario to the collection view, so we can see at a glance the available endpoints.

Showing the type of an entity
You can specify a special property name which results in the SDO type of the entity being shown in the cell. This special name is sdoType. The completed column definitions should appear as in Example 10-17.
Example 10-17 The completed column definitions

name

406

WebSphere Service Registry and Repository Handbook

ViewDetail MBPatternMQEndpoint description namespace

10.5.5 Collection view buttons
A collection view definition can specify a number of buttons which appear above the columns. There is a set of actions to choose from for each button. A button's action determines what happens when the button is clicked. If a collection view definition specifies any buttons, an extra column of select boxes will be rendered in the view. The select boxes allow the user to select entities for those actions which act upon entities. Some actions do not act upon entities, such as the New Concept action. For our scenario we will add buttons to allow us to create new endpoints, delete existing endpoints, add properties, relationships and classifications to the endpoints, export, subscribe to changes and add the endpoints to our favorites. All button definitions are enclosed in a single button-definitions element which must be after the column-definitions element. An individual button is defined in a button-definition element, with required elements to define the button message and the button action. The first button we will add to our view will allow us to add a user defined property to the selected entities in the view. Add a button-definitions element below the column-definitions element, as shown in Example 10-18 on page 408.

Chapter 10. Customizing the Web UI

407

Example 10-18 A button definition for “Add property”

... addProperty The button-message element specifies the message which appears on the button, here we use a message from the WSRR resource bundle. The button-action element specifies what happens when the button is clicked; its value is from a predefined list of button actions, discussed in 10.5.6, “Collection view button action values” on page 410. Figure 10-8 shows where the button you added appears in the view.

Figure 10-8 The Add Properties button in the view

To complete the button definitions, add button-definition elements with the values shown in Table 10-4.
Table 10-4 Button definitions Button message key collectionButton.new collectionButton.deleteItems Button action createGenericObject deleteItems

408

WebSphere Service Registry and Repository Handbook

Button message key collectionButton.addProperty collectionButton.addRelationship collectionButton.addClassifications collectionButton.export collectionButton.subscribe collectionButton.addFavourites

Button action addProperty addRelationship addClassifications exportDocuments subscribe addFavorites

The completed button-definitions element is shown in Example 10-19.
Example 10-19 The complete button definitions

createGenericObject MQEndpoint deleteItems addProperty addRelationship addClassifications exportDocuments subscribe

Chapter 10. Customizing the Web UI

409

 addFavorites

10.5.6 Collection view button action values
As mentioned, a button can perform one of a number of actions when clicked. The button-action element specifies this action. You can use one of the following button actions: Create a new GenericObject (Concept) by presenting you with the initial values to use. Load a new document into WSRR. Add a new user defined property to all selected entities, with values provided by you in the Web UI. Delete the selected entities, providing they can be deleted. Add a new custom relationship to all selected entities, with the name and targets provided by you in the Web UI. Export the selected entities, providing they can be exported. Add the selected entities to the your favorites list. Subscribe to changes of the selected entities, further filtering can be provided by you in the Web UI. Add classifications to all selected entities, as chosen by you in the Web UI. For further information and detail, see the WSRR Information Center, UI customization section: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.do c/twsr_configrn_webUI.html

10.5.7 Adding collection view resources
The keys used in the collection view definition need to be added to the resource file we specified in the view definition. This was MBPatternResources. Example 10-20 on page 411 shows the messages used by this collection view.

410

WebSphere Service Registry and Repository Handbook

Example 10-20 Collection view messages

mbpattern.collection.view.mqendpoints.title=MQ Endpoints mbpattern.collection.view.mqendpoints.description=This is the collection of the MQ Endpoints in the registry.

10.6 Managing UI customization configurations
The runtime behavior of WSRR components is determined by the content of configuration objects associated with those components. For example the access control component uses two configuration objects that set policy and role mapping behavior. The UI has five such configuration types which correspond to each of the types of UI definition files. A WSRR configuration comprises a logical name, a configuration type, content (as bytes), and an indication of whether it is a system configuration or a user-defined configuration, as shown in Table 10-5.
Table 10-5 Attributes of a configuration object Name Name Type Description The logical name for this configuration. The configuration type, which, for the purposes of customizing the UI must be one of:

UI_PERSPECTIVE UI_VIEW_QUERY_USER_DEF UI_NAVIGATION_TREE UI_COLLECTION_VIEW UI_DETAIL_VIEW
Content System indicator The contents of the configuration, stored as a byte array. This is typically populated by reading from an XML file. A value of true indicates the configuration is used internally by WSRR. A value of false indicates the configuration is user-defined.

For each of the UI view definition files you create, you need to load a corresponding configuration object of the appropriate type, as shown in Table 10-6. As these are typically new view definitions, the configuration object must be loaded with the system indicator value set to false.
Table 10-6 Configuration types and corresponding UI view definitions Configuration type UI_PERSPECTIVE Use this for the UI view definition of type: perspectives

Chapter 10. Customizing the Web UI

411

Configuration type UI_VIEW_QUERY_USER_DEF UI_NAVIGATION_TREE UI_COLLECTION_VIEW UI_DETAIL_VIEW

Use this for the UI view definition of type: view queries navigation trees collection views detail views

The combination of a configuration name and configuration type uniquely identify a configuration. For example, you could have two configurations called “new user”, one for the perspective configuration and one for the navigation tree.

10.6.1 Manage configurations with MBean operations
You load, update, remove and retrieve configurations using the JMX interface. The WSRR application provides an MBean of type ServiceRegistryRepository which allows administrators to perform a range of housekeeping operations. In addition to managing configurations this includes refining access control, managing ontology systems and performing import/export of WSRR entities. The specific operations you are interested in for managing configurations are: loadConfiguration updateConfiguration deleteConfiguration retrieveConfiguration getConfigurationId Previously, we defined view queries that return all endpoints that are classified with type of “MQ”, “JMS” or “URL” (see 10.2.4, “Querying by classification” on page 387). To support this classification of services, we would need to define an ontology system as an OWL file and load into WSRR. The MBean operations for loading and removing ontology systems are: createOntologySystem deleteOntologySystem The pattern for invoking any MBean operation is the same: locate an MBean, specify operation signature and parameters, invoke the named operation on the MBean and cast any result object to an appropriate type. For more information about how to use the WSRR Admin MBean, refer to 8.5, “Administering WSRR using JMX” on page 292. A sample script to load all the UI customizations that make up our scenario is provided with the WMB V6 Client for WebSphere Service Registry and

412

WebSphere Service Registry and Repository Handbook

Repository. It can be found in the \Tests\WSRRTestEntities\GUIConfiguration directory and is documented in 16.8.2, “Configuring WSRR for the patterns” on page 810 step 8 on page 812.

Chapter 10. Customizing the Web UI

413

414

WebSphere Service Registry and Repository Handbook

11

Chapter 11.

Using the WSRR Eclipse plug-in
This chapter describes the installation, configuration and usage of the WebSphere Service Registry and Repository (WSRR) Eclipse plug-in. During development, if you are working in an Eclipse-based development environment, you can use the Eclipse user interface (UI) that is supplied in the WSRR Eclipse plug-in to access and search for documents that are stored in WSRR. You can also use the Eclipse UI to publish documents that you are developing to WSRR.

© Copyright IBM Corp. 2007. All rights reserved.

415

11.1 WSRR Eclipse user interface
The WebSphere Service Registry and Repository Eclipse user interface (UI) is supplied as a WSRR Eclipse plug-in and provides a new view, the Service Registry view, in your Eclipse workbench (for example, Rational Software Architect). You can use the Service Registry view to access and search for objects in WSRR. You can also publish to WSRR new objects that you develop in the Eclipse workbench using the Service Registry view. The Service Registry view is supplied by the WSRR plug-in. The plug-in can be downloaded from the WSRR SupportPac page: http://www.ibm.com/support/docview.wss?rs=171&uid=swg27008751#1 Install it using Update Manager in your Eclipse workbench. When you have installed the WSRR plug-in, you can open the Service Registry view, which is initially displayed by default in the Resource perspective, as shown in Figure 11-1.

Figure 11-1 Resource perspective

416

WebSphere Service Registry and Repository Handbook

You can rearrange the views in the workbench if you prefer. For more information, see Moving and docking views in the Eclipse Workbench User Guide: http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.user/t asks/tasks-3e.htm The Eclipse UI connects the workbench to a local or remote instance of WSRR. You can then work in the Service Registry view to perform the following tasks: Search WSRR for objects. Import objects from WSRR to a project in your local workspace. Publish to WSRR objects that you create in your local workspace. Add property and relationship information to objects in WSRR. Every object in WSRR can be uniquely identified by using a combination of the document's name, version, and namespace. Every object can also have any number of custom name-value properties, any number of custom relationships, and belong to a hierarchy of classifications. From the Service Registry view, you can search WSRR using one or more of the following criteria: The object's uniqueness identifiers or any part of it. If you search on only one or two parts of the identifier, more than one object could be returned in the search results. The type, or types, of object that you want to retrieve; for example, you can search for XML and WSDL documents. One or more properties and property values of the object. The classification of the object in WSRR. If you specify a high level classification, all of the objects in all of the classifications below it are returned in the search results. The search results return zero or more objects depending on how specific the search criteria are.

11.2 Installing the Eclipse user interface
The Eclipse UI comes in the form of an Eclipse plug-in and is supplied separately as a WebSphere Service Registry and Repository SupportPac. The following instructions describe how to download, install, and configure the Eclipse UI in an Eclipse workbench; for example, in WebSphere Integration Developer or Rational Software Architect.

Chapter 11. Using the WSRR Eclipse plug-in

417

Before you can install and use the Eclipse UI, you must complete the following tasks: Install on your local computer an Eclipse workbench; for example, WebSphere Integration Developer or Rational Software Architect. The minimum level is Eclipse 3.0.2. Install on your local computer the WebSphere Application Server Application Client or WebSphere Application Server Application Server. For more information about installing the Application Client, see “Installing Application Client for WebSphere Application Server” in the WebSphere Application Server information center. Alternatively, have access to a WebSphere Application Server version 6.0.2 JRE™. Connect to the Internet. To download and install the WSRR plug-in: 1. On the WSRR SupportPacs page http://www.ibm.com/support/docview.wss?rs=3163&uid=swg27008751 click SA02. 2. Download the WSRR Eclipse plug-in zip file to a local folder in your machine, for example, C:\ITSO\WSRR\EclipsePlugin. 3. Start the Eclipse workbench. 4. In the workbench, from the Help menu, click Software Updates → Find and Install, as shown in Figure 11-2. The Install/Update wizard should now open.

Figure 11-2 Help Menu

418

WebSphere Service Registry and Repository Handbook

5. In the wizard, click Search for new features to install (see Figure 11-3 on page 419), then click Next.

Figure 11-3 New features to install

6. The wizard lists the locations that are searched when searching for new features. 7. Add a new location to search. a. Click New Archived Site (as shown in Figure 11-4). The Select Local Site Archive dialog opens.

Chapter 11. Using the WSRR Eclipse plug-in

419

Figure 11-4 New Archived Site

b. Choose the WSRR Eclipse plug-in zip file you have downloaded. c. Click OK. The new location is added to the list in the wizard as shown in Figure 11-5.

420

WebSphere Service Registry and Repository Handbook

Figure 11-5 New location added

8. Select the check box for the new location or archived site and then click Next as shown in Figure 11-6 on page 422. If the location is secured, enter your user name and password.

Chapter 11. Using the WSRR Eclipse plug-in

421

Figure 11-6 New location selected

9. Eclipse searches the selected location or locations for new features. When the search is complete, the available features that are relevant to your installation are displayed in the wizard. 10.Select the check box for com.ibm.serviceregistry.core.feature, which contains the WSRR plug-in, as shown in Figure 11-7 on page 423, and then click Next.

422

WebSphere Service Registry and Repository Handbook

Figure 11-7 Select Feature to install

11.Read the license agreements and click I accept the terms in the license agreements to accept the terms, then click Next (see Figure 11-8 on page 424).

Chapter 11. Using the WSRR Eclipse plug-in

423

Figure 11-8 License agreement

12.Select the location on your local computer where you want to install the WSRR plug-in (see Figure 11-9 on page 425). To add a new location, click Add Site, and then browse to the location where you want to install the WSRR plug-in.

424

WebSphere Service Registry and Repository Handbook

Figure 11-9 Select Install location

13.Click Finish. 14.In the Jar Verification dialog (Figure 11-10 on page 426), click Install.

Chapter 11. Using the WSRR Eclipse plug-in

425

Figure 11-10 Jar Verification

15.When prompted, click Yes to restart the Eclipse workbench, which completes the installation. The WSRR plug-in is now installed in your Eclipse workbench. 16.Open the Service Registry view: a. From the window menu, click Show View → Other. The Show View dialog opens as in Figure 11-11 on page 427. b. Expand the Service Registry folder. c. Click Service Registry, then click OK.

426

WebSphere Service Registry and Repository Handbook

Figure 11-11 The show view dialog

d. The Service Registry view opens in the bottom-right of the workbench as in Figure 11-12.

Figure 11-12 Service Registry view

You have now installed the WSRR Eclipse UI in your Eclipse workbench. The next section covers configuration of the Eclipse UI to connect to WSRR.

Chapter 11. Using the WSRR Eclipse plug-in

427

11.3 Configuring the Eclipse user interface
Before you can use the Eclipse UI to access the objects in WSRR, you must configure the UI with the connection details that it needs, including any security details for making a secure connection. To configure the Eclipse UI to connect to WSRR: 1. Start the Eclipse workbench and ensure that the Service Registry view is open. 2. From the window menu, click Preferences. The Preferences dialog opens. 3. In the Preferences dialog, expand Service Registry, then click WSRR Locations. The WSRR Locations page is displayed. 4. On the WSRR Locations page, shown in Figure 11-13, click Add.

Figure 11-13 WSRR Preferences

5. The Add/Edit Service Registry Preferences dialog opens (shown in Figure 11-14 on page 429). 6. In the dialog, enter your connection details: a. In the Alias field, type a meaningful name for the connection. For example, type the name of the remote computer to which you are connecting. b. In the Host field, type the fully-qualified name or IP address (IPv4 or IPv6) of the remote computer to which you are connecting. For example, eclipse.itso.ibm.com or 192.168.0.3

428

WebSphere Service Registry and Repository Handbook

c. In the Port field, type the port number of the WSRR WebSphere Application Server’s JNDI port. The default port number is 2809. d. In the Security field, select the type of security to use for the connection: • If the WebSphere Application Server instance to which you are connecting has security turned off, select None.

Figure 11-14 Add Service Registry preferences

•

If the WebSphere Application Server (WSRR) instance to which you are connecting has security turned on, select sas.client.props. The WebSphere client provides a sample sas.client.props file. For example: \profiles\default\properties\sa s.client.props. Open the sas.client.props file in a text editor. In the sas.client.props file, type the WebSphere Application Server user name and password on the lines shown here: com.ibm.CORBA.loginSource=properties com.ibm.CORBA.loginUserid= com.ibm.CORBA.loginPassword=

Chapter 11. Using the WSRR Eclipse plug-in

429

Edit the following lines of the file to ensure that the com.ibm.ssl.keyStore and com.ibm.ssl.trustStore have the correct values: com.ibm.ssl.keyStore=C:/IBM/AppServer/profiles/default/etc/Dum myClientKeyFile.jks com.ibm.ssl.trustStore=C:/IBM/AppServer/profiles/default/etc/D ummyClientTrustFile.jks If security is enabled on the WSRR instance, then the panel should look similar to Figure 11-15.

Figure 11-15 Edit Service Registry preferences

e. Click OK. The new connection is listed on the WSRR Locations page of the Preferences dialog.

430

WebSphere Service Registry and Repository Handbook

Note: If you are connecting to a secure WSRR and the Eclipse plug-in is installed in RSA (Rational Software Architect) V6 or WID (WebSphere Integration Developer) V6, you need to start RSA or WID with -vm argument to use JRE of WebSphere Client. For example For RSA: rationalsdp.exe -vm C:\RSA6.0\runtimes\base_v6\java\jre\bin\javaw.exe For WID: wid.exe -vm C:\RSA6.0\runtimes\base_v6\java\jre\bin\javaw.exe 7. Select the new location, checking the appropriate location, then click OK. 8. If you have previously connected to WSRR in this workbench session you will have to restart the workbench to apply the changes. The Eclipse JVM caches the security credentials of any previous WSRR connection, you must restart the workbench to clear the cache. You have now configured the WSRR Eclipse UI to connect to WSRR. The following sections cover using the Eclipse UI to access WSRR.

11.4 Searching for objects in WSRR
You can search for documents and other objects in WSRR using a combination of different types of criteria. To search for objects in WSRR: 1. In the Service Registry view, right-click somewhere in the view, then click Retrieve (this is shown in Figure 11-16 on page 432). The Search dialog opens.

Chapter 11. Using the WSRR Eclipse plug-in

431

Figure 11-16 Retrieving objects from WSRR

2. In the Search dialog, select the criteria on which you want to search. You must select, as a minimum, the type of object for which you are searching. For example, select the WSDL check box to search for WSDL files as shown in Figure 11-17 on page 433. The number of results that are returned depends on how specific the criteria are.

432

WebSphere Service Registry and Repository Handbook

Figure 11-17 Search window

3. Click Search. All objects in WSRR that match the search criteria that you specified are displayed in the Retrieved Items dialog (see Figure 11-18 on page 434) which opens when the search has completed.

Chapter 11. Using the WSRR Eclipse plug-in

433

Figure 11-18 Search result window

4. Click OK to close the Retrieved Items dialog. The retrieved items are added to the appropriate categories of the Service Registry view; for example, if you searched for some WSDL documents, the WSDL documents that were retrieved are listed under the WSDL Documents category in the Service Registry view. If a document imports another document, for example, if a.wsdl imported b.wsdl then this is displayed as an expandable tree node with a + symbol next to the a.wsdl document. See Figure 11-19 on page 435 for an example of this.

434

WebSphere Service Registry and Repository Handbook

Figure 11-19 WSDL Documents retrieved

If you want to retrieve all of the objects of a certain type from WSRR, you can quickly do this if you right-click in the Service Registry view, then click the object type that you want to retrieve; for example, to retrieve all the WSDL documents in WSRR, click Retrieve WSDLs. Now, you can import one or more of the retrieved documents into a project in your local workspace.

11.5 Importing documents into your local workspace
When you have retrieved documents from WSRR, they are displayed in the Service Registry view. You cannot work with the documents, though, until you have imported them into a project in your local workspace. To import documents from WSRR to your local workspace: 1. Switch to the Resource perspective. 2. In the Navigator view, create a new project. 3. In the Service Registry view, right-click the document that you want to import, then click Import document as shown in Figure 11-20 on page 436. The Import wizard opens.

Chapter 11. Using the WSRR Eclipse plug-in

435

Figure 11-20 Import Document

4. In the wizard (see Figure 11-21 on page 437), click the name of the project into which you want to import the document and ensure that the correct file name is shown in the File Name field.

436

WebSphere Service Registry and Repository Handbook

Figure 11-21 Import document wizard

5. Optional: To import any objects that depend on the selected document, select the Include all dependent artefacts check box. 6. Click Finish.

Chapter 11. Using the WSRR Eclipse plug-in

437

Figure 11-22 Document Imported

A copy of the document from WSRR is imported into the project in your local workspace as shown in Figure 11-22. You can now change or use the document as required.

11.6 Publishing documents to WSRR
When you have developed new documents, or new versions of documents that already exist in WSRR, you can publish them to WSRR using the Eclipse UI. To publish a document, or a new version of a document, to WSRR: 1. Switch to the Resource perspective. 2. In the Navigator view, right-click the document that you want to publish, then click Service Registry → Publish Document (as shown in Figure 11-23).

Figure 11-23 Publish Document menu option

3. The Publish A Document To WSRR wizard opens as shown in Figure 11-24 on page 439. 4. In the wizard, check that the correct name is shown in the Name field and the correct document type is shown in the File type field. 5. Optional: Type a description in the Description field.

438

WebSphere Service Registry and Repository Handbook

6. Optional: If a previous version of the document already exists in WSRR, type a new version number in the Version field so that you can distinguish this new version of the document.

Figure 11-24 Publish a Document to WSRR dialog

7. Click Finish. When the document has been published to WSRR, a confirmation message is shown. Click Ok. The document is now stored in WSRR. You can check this by retrieving it using the Service Registry view. You can now perform the following tasks on the document in WSRR: Adding properties to objects in WSRR Defining relationships between objects in WSRR Creating concepts for objects in WSRR These tasks are explained in the next sections.

Chapter 11. Using the WSRR Eclipse plug-in

439

11.7 Adding properties to objects in WSRR
You can use the Eclipse UI to add properties to the objects in WSRR to formally describe them and make it easier for other developers to find and reuse them. To add properties to an object in WSRR: 1. In the Service Registry view, retrieve the document or documents to which you want to add properties. The documents must be displayed in the Service Registry view. 2. In the Service Registry view, right-click one or more documents, then click Add Properties (as shown in Figure 11-25).

Figure 11-25 Add Properties menu option

3. The Add Properties wizard opens as in Figure 11-26 on page 441. In the wizard, click Add.

440

WebSphere Service Registry and Repository Handbook

Figure 11-26 Add Properties dialog

4. The Add Property dialog opens as in Figure 11-27. In the dialog, type a name for a new property and type the value for the property, then click OK.

Figure 11-27 Add property dialog

5. Optional: Add more or edit properties in the same way. 6. Click Next. This will display a summary of the documents that will have new properties added to and the list of properties that will be added to each. 7. Click Finish. The new properties will now be added to the documents. The properties of a particular document can be seen in the Properties view; if you open the Properties view and reselect the document in the Service Registry

Chapter 11. Using the WSRR Eclipse plug-in

441

view then you will see them in the User-defined category of the Properties view, as highlighted in Figure 11-28.

Figure 11-28 Properties view

The properties have now been added to the documents in WSRR.

11.8 Defining relationships between objects in WSRR
In WSRR, you can define relationships between documents so that, for example, one document has a named relationship to another document. You can define these relationships using the Eclipse UI. To define relationships between objects in WSRR: 1. In the Service Registry view, retrieve the document or documents to which you want to add relationships. The documents must be displayed in the Service Registry view. 2. In the Service Registry view, right-click one document, and then click Add Relationships (as shown in Figure 11-29 on page 443).

442

WebSphere Service Registry and Repository Handbook

Figure 11-29 Add Relationships menu option

3. The Add Relationships wizard opens as in Figure 11-30. In the wizard, type the name of the relationship that you want to define, then click Next.

Figure 11-30 Add Relationship dialog

4. The wizard displays the Search dialog (see Figure 11-31 on page 444) so that you can search for the document or documents you want to define the relationship to.

Chapter 11. Using the WSRR Eclipse plug-in

443

Figure 11-31 Search criteria

5. Click Next. This will display the results of the search (see Figure 11-32). If no results are found, either: – Click Back and re-specify your search criteria, – Or click Cancel. Check at least one document that you want to create a relationship to, from your originally selected document.

Figure 11-32 Search results

6. Click Finish.

444

WebSphere Service Registry and Repository Handbook

The new relationship is now defined between the documents in WSRR. This new relationship can be seen in the User relationships category of the Properties view as shown in Figure 11-33.

Figure 11-33 Properties view

11.9 Creating concepts for objects in WSRR
Concepts are collections of objects stored in WSRR. You can create concepts using the Eclipse UI. Note: Concepts are called GenericObjects in the WSRR API. To create a concept in WSRR: 1. In the Service Registry view, select the documents that you want to group together into a Concept. 2. Right-click the selection, then click Create Concept as in Figure 11-34 on page 446.

Chapter 11. Using the WSRR Eclipse plug-in

445

Figure 11-34 Create Concept menu option

3. The Publish as Concept wizard opens as in Figure 11-35. Enter a name, description, and version for the concept, then click Next.

Figure 11-35 New Concept details

446

WebSphere Service Registry and Repository Handbook

4. For each document click in the cell for the Relationship name (highlighted in Figure 11-36). A cursor is displayed in the cell so that you can type in it. Press Enter to apply each change.

Figure 11-36 Add Relationships to documents in new Concepts

5. Optional: Click Next, then add one or more properties to the concept. 6. Click Finish. A message confirms that the concept was successfully created. The concept has now been created in WSRR as seen in Figure 11-37 on page 448. You can check this by retrieving it using the Service Registry view.

Chapter 11. Using the WSRR Eclipse plug-in

447

Figure 11-37 New Concept created

11.10 Creating concepts using local documents
Concepts are collections of objects. New objects that are created within the Eclipse workspace can be grouped together into a collection and published as a new concept into WSRR. This has the same effect as individually publishing a document into WSRR then creating concepts for objects in WSRR. Before you can create concepts using local documents, you must have created a document in a project in your local workspace; the project must be displayed in the Navigator view of the Resource perspective. To publish a concept using local documents: 1. In the Navigator view, select and right-click one or more documents, then click Publish as Concept (as in Figure 11-38 on page 449). The Publish As Concept wizard opens.

448

WebSphere Service Registry and Repository Handbook

Figure 11-38 Publish as Concept menu option

2. In the wizard, type a name, description, and version for the concept (as shown in Figure 11-39), then click Next.

Figure 11-39 New Concept details

3. For each document click in the Relationship name cell as highlighted in Figure 11-40 on page 450. A cursor is displayed in the cell so that you can type in it. Press Enter to apply each change.

Chapter 11. Using the WSRR Eclipse plug-in

449

Figure 11-40 Add Relationships to documents in new Concepts

4. Optional: Click Next, then add one or more properties to the concept. 5. Click Finish. A message confirms that the concept was successfully created. The concept has now been created in WSRR as shown in Figure 11-41 on page 451. You can check this by retrieving it using the Service Registry view.

450

WebSphere Service Registry and Repository Handbook

Figure 11-41 New Concept created

Chapter 11. Using the WSRR Eclipse plug-in

451

452

WebSphere Service Registry and Repository Handbook

12

Chapter 12.

Scenarios description
This chapter describes the example scenarios used later in this book in Chapters 13, 14 and 15. The topics covered are: 12.1, “Services description” on page 454 12.2, “Requirements” on page 458 12.3, “Solution overview” on page 458

© Copyright IBM Corp. 2007. All rights reserved.

453

12.1 Services description
IBM-ITSO Ltd. decided to use Web services in their organization to query the price of items they deal in. They want to use Service Oriented Architecture to add dynamic and flexibility to their solution. They use WebSphere Service Registry and Repository as their service registry solution. They have a WSDL Port Type ItemPrice describing the Interface. Figure 12-1 shows the interface ItemPrice, which is the interface of the Web services. It accepts itemName of type xsd:string as input and returns xsd:int price as output.

Figure 12-1 ItemPrice Interface

IBM-ITSO has developed two Web services, ItemPriceService and ItemPriceDiscountedService to provide the price for a given item name. ItemPriceService returns the normal price (without any discounts) and it is comparatively slow. Valid item names are Item1, Item2 and Item3. Any other item name generates a RuntimeException. See Example 12-1. Note: A delay of 5 seconds has been added in ItemPriceService so that the response of the service is delayed. This is intentionally done to illustrate and observe different quality of interactions between the two services.
Example 12-1 ItemPriceSerivce implementation

/** * ItemPriceSoapBindingImpl.java */ package com.ibm.itso;

454

WebSphere Service Registry and Repository Handbook

public class ItemPriceSoapBindingImpl implements com.ibm.itso.ItemPrice { public int getPrice(java.lang.String itemName) throws java.rmi.RemoteException { int itemPrice = -100; // Sleep to add delay try { Thread.sleep(5000); } catch (InterruptedException e) { e.printStackTrace(); } if (itemName.equals("Item1")) itemPrice = 100; else if (itemName.equals("Item2")) itemPrice = 200; else if (itemName.equals("Item3")) itemPrice = 300; else throw new RuntimeException("ItemPriceService: Internal Error!!"); System.out.println("ItemPrice:: itemName: " + itemName + ", itemPrice: " + itemPrice); return itemPrice; } } ItemPriceDiscountedService returns the discounted price which is typically provided for privileged customers. There is no delay in this service implementation and the response is comparatively fast. Valid item names are Item1, Item2 and Item3. Any other item name generates a RuntimeException. See Example 12-2.
Example 12-2 ItemPriceDiscountedSerivce implementation

/** * ItemPriceDiscountedSoapBindingImpl.java */ package com.ibm.itso; public class ItemPriceDiscountedSoapBindingImpl implements

Chapter 12. Scenarios description

455

com.ibm.itso.ItemPrice { public int getPrice(java.lang.String itemName) throws java.rmi.RemoteException { int itemPrice = -90; if (itemName.equals("Item1")) itemPrice = 90; else if (itemName.equals("Item2")) itemPrice = 180; else if (itemName.equals("Item3")) itemPrice = 270; else throw new RuntimeException("ItemPriceDiscountedService: Internal Error!!"); System.out.println("ItemPriceDelayed:: itemName: " + itemName + ", itemPrice: " + itemPrice); return itemPrice; } } They have two categories of customers, Gold and General. Gold customers are privileged customers and get discounts on items. All price requests from Gold customers should be handled by the discounted service. See Figure 12-2.
General IBM-ITSO Ltd. ItemPriceService ItemPriceDiscountedService

Gold

Figure 12-2 System context

Both services use the ItemPrice PortType but have different endpoints. See Figure 12-3 on page 457.

456

WebSphere Service Registry and Repository Handbook

getPrice (Operation)

ItemPrice (PortType)

ItemPriceService SOAP Endpoint

ItemPrice (Port)

ItemPriceDiscounted (Port)

ItemPriceDiscountedService SOAP Endpoint

ItemPriceService (Service)

ItemPriceDiscountedService (Service)

Figure 12-3 ItemPrice and ItemPriceDiscounted services use the same PortType

Users provide name of item and type of customer (Gold or General) to query the price of item. We use another interface ItemPriceEnquiry to receive request from users. See Figure 12-4.

Figure 12-4 ItemPriceEnquiry Interface

Chapter 12. Scenarios description

457

12.2 Requirements
The solution requirements are divided into Governance and ESB Runtime categories.

Governance requirements
1. Access to the resources in the WSRR runtime environment must be restricted such that each user is only granted the minimum level of access that they require in order to perform their role. 2. The physical document objects that are stored in WSRR must have a suitable lifecycle applied to them. 3. When a physical document object is loaded into WSRR, a checksum must be calculated and added as property to the object.

ESB Runtime Requirements
1. To externalize the endpoint address and not hard code it in WebSphere Enterprise Service Bus (WESB) 2. Dynamically decide which service to invoke (ItemPrice or ItemPriceDiscounted) based on the customer type

12.3 Solution overview
ESB Runtime
Both ItemPriceService and ItemPriceDiscountedService will be deployed in WebSphere Application Server. Service metadata (like the endpoints) will be published to WebSphere Service Registry and Repository (WSRR). The solution uses WebSphere Enterprise Service Bus (WESB) to mediate the service consumer request and redirect to the appropriate service based on the customer type.

458

WebSphere Service Registry and Repository Handbook

WESB Service Consumer

WAS

1

Mediation Module

3

ItemPriceService ItemPriceDiscountedService

2

WSRR

Figure 12-5 Interaction between WESB and WSRR

Chapter 12. Scenarios description

459

460

WebSphere Service Registry and Repository Handbook

13

Chapter 13.

Configuring governance
This chapter describes how to enforce the various aspects of SOA governance that were discussed in Chapter 5, “SOA governance enablers” on page 157. This chapter contains the following: 13.1, “Configuring security” on page 462 13.2, “Using lifecycles” on page 476 13.3, “Developing custom plugins” on page 482 13.4, “Performing impact analysis” on page 499

© Copyright IBM Corp. 2007. All rights reserved.

461

13.1 Configuring security
The sections that follow describe how to configure security in WebSphere Service Registry and Repository in the context of the scenario described in Chapter 12, “Scenarios description” on page 453. IBM-ITSO Ltd. wants to harden the security configuration of WSRR in their SOA environment to ensure that the permissions that are granted to users only provide them with the minimum level of access that they need in order to perform their role. In this scenario, we assume that WSRR has been installed to a WebSphere Application Server environment that has global security enabled and is using the Local OS as the user registry. Also, as discussed in 7.6.1, “Security” on page 274, we assume that the “wasadmin” user has been defined on the machine on which WSRR is running. Finally, we assume that the default role mappings were used during the installation process. It is not within the scope of this book to describe how to enable global security in WebSphere Application Server. This is described in the WebSphere Information Center: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/topic/com.ibm. websphere.base.doc/info/aes/ae/tsec_csec.html It is also not within the scope of this book to describe how to create users and groups in the user registry that you have configured in your WebSphere Application Server environment. However, the sections that follow require that a number of users are created in the relevant user registry. You must perform the steps that are required by the configured user registry in order to create the users shown in Table 13-1.
Table 13-1 Users defined in the IBM-ITSO Ltd. user registry User name itcam4soa wesb assetmgr wsrruser Description This user is used by the IBM Tivoli Composite Application Manager for SOA product in order to connect to WSRR. This user is used by the WebSphere Enterprise Service Bus product in order to connect to WSRR. This user performs lifecycle related tasks on the artefacts in WSRR, such as making objects governable and transitioning their state. This user represents a normal user of WSRR in IBM-ITSO Ltd.

462

WebSphere Service Registry and Repository Handbook

Note: All of the example commands shown in this section specify -user and -password parameters when invoking wsadmin. These parameters are required because IBM-ITSO Ltd. has enabled security in their WebSphere environment. Also, in all of the example commands shown, is the root installation directory of WebSphere Application Server and is the root installation directory of WebSphere Service Registry and Repository. Finally, it is assumed that all of the example commands are executed from the \admin\scripts directory.

13.1.1 Modifying the J2EE security role mappings
As discussed previously, WSRR was installed into the IBM-ITSO Ltd. environment using the default role mappings that are specified in the WSRR installation scripts. This means that the special subject, AllAuthenticatedUsers, is currently mapped to both the Administrator and User J2EE security roles in WSRR. IBM-ITSO Ltd. wants to modify the security role mappings so that only the wasadmin user is mapped to the Administrator J2EE security role. As noted in 5.3.1, “J2EE security roles” on page 187, since the wasadmin user is defined as the Server user ID in the IBM-ITSO Ltd. WebSphere environment, it must be mapped to the Administrator J2EE security role in order to ensure the correct operation of WSRR in a secure environment. The steps that are required to do this are as follows: 1. Logon to the WebSphere Administrative Console as the wasadmin user. 2. In the navigation tree, expand Applications. 3. Click Enterprise Applications. 4. In the list of Enterprise Applications, click ServiceRegistry. 5. In the Additional Properties section, click Map security roles to users/groups. This is shown in Figure 13-1 on page 464.

Chapter 13. Configuring governance

463

Figure 13-1 Map security roles to users/groups

6. Check the check box in the Select column for the Administrator role and uncheck the check box in the All authenticated? column. 7. Click Look up users, as shown in Figure 13-2 on page 465.

464

WebSphere Service Registry and Repository Handbook

Figure 13-2 Removing the “all authenticated” mapping

8. Make sure that an asterisk (*) is entered in the Search String entryfield. 9. Click Search. 10.The Available list box displays the list of user names that match the specified search string. From this list of user names, select the wasadmin user. 11.Click >>, as shown in Figure 13-3 on page 466.

Chapter 13. Configuring governance

465

Figure 13-3 Adding the wasadmin mapping

12.The wasadmin user is now displayed in the Selected list box. Click OK. 13.The wasadmin user is now listed in the Mapped users column for the Administrator role, as shown in Figure 13-4 on page 467.

466

WebSphere Service Registry and Repository Handbook

Figure 13-4 The completed mapping

14.Click OK. 15.Save the changes and synchronize them with the nodes. 16.For the changes to become effective, you must restart the application server on which WSRR is running.

13.1.2 Removing the AllAuthenticatedUsers principal from the WSRR Administrator role
As discussed in 5.3.2, “User defined roles” on page 188, WebSphere Service Registry and Repository provides an authorization component that allows additional roles to be defined. Since the default role mappings were used when installing WSRR to the IBM-ITSO Ltd. environment, the AllAuthenticatedUsers special subject has also been mapped to the Administrator role in the WSRR authorization component. In order to restrict the users who have administrative access to WSRR, IBM-ITSO Ltd. wants to modify the role mappings defined in the WSRR authorization component to remove this role mapping. They would then like to map the wasadmin user to the Administrator role in the WSRR authorization component. In order to remove the AllAuthenticatedUsers special subject from the Administrator role in the WSRR Authorization component, execute the command shown in Example 13-1 on page 468.

Chapter 13. Configuring governance

467

Example 13-1 Command to remove the AllAuthenticatedUsers mapping from the Administators role

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f removePrincipalFromRole.jacl VirtualPrincipal.AllAuthenticatedUsers Administrator Note: VirtualPrincipal.AllAuthenticatedUsers must be specified as the principal in order to remove the AllAuthenticatedUsers special subject. Simply specifying AllAuthenticatedUsers will have no effect on the role mapping. In order to add the wasadmin user to the Administrator role in the WSRR Authorization component, execute the command shown in Example 13-2.
Example 13-2 Command to map the wasadmin user to the Administrators role

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPrincipalToRole.jacl wasadmin Administrator The modifications to the role mappings in the WSRR Authorization component must be persisted in order for them to become effective. In order to do this, execute the command shown in Example 13-3.
Example 13-3 Command to persist the WSRR role mappings

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f persistRoleMappings.jacl

13.1.3 Adding roles
IBM-ITSO Ltd. wants to harden the security configuration of WSRR to prevent users from performing any actions that are outside of their defined roles. In order to do this, they need to define additional roles to the authorization component in

468

WebSphere Service Registry and Repository Handbook

WSRR and map the relevant user to these roles. The roles that IBM-ITSO Ltd. need to define are shown in Table 13-2.
Table 13-2 New roles required by IBM-ITSO Ltd. Role name SOAInfrastructure Description This role will be used to control access to objects in WSRR by other runtime components in IBM-ITSO Ltd’s SOA environment, such as IBM Tivoli Composite Application Manager for SOA and WebSphere Enterprise Service Bus. This role will be used to control access to the lifecycle management actions provided by WSRR.

LifecycleManager

In order to add these roles to the WSRR Authorization component, execute the commands shown in Example 13-4.
Example 13-4 Commands to add the required roles

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addRole.jacl SOAInfrastructure \wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addRole.jacl LifecycleManager The modifications to the role mappings in the WSRR Authorization component must be persisted in order for them to become effective. In order to do this, execute the command shown in Example 13-3 on page 468.

13.1.4 Adding permissions to roles
As discussed in 5.3, “WSRR security” on page 187, WSRR adopts a permissive approach to access control in the WSRR authorization component, with access to all of the objects in WSRR unrestricted by default. However, once a role is explicitly granted access to a set of target objects in WSRR, all other roles are implicitly denied access to that set of objects. In this situation, in order for other

Chapter 13. Configuring governance

469

roles to access the same set of target objects, each role must also be explicitly granted access to the set of objects. IBM-ITSO Ltd. require that the permissions for all WSRR users provide them with the minimum level of access that they need in order to perform their role. Given the behavior described previously, in order to achieve this they will first need to grant the Administrator role the permission to perform any action on any object in WSRR. This will implicitly deny all other roles the permission to perform these actions. They can then selectively grant permissions to each role to allow the required level of access for that role. The permissions required by each of the roles in the IBM-ITSO Ltd. SOA environment are shown in Table 13-4 on page 475.
Table 13-3 IBM-ITSO Ltd. permissions WSRR action srrCreate srrRetrieve srrUpdate srrDelete srrTransition srrManageGov Administrator X X X X X X X X X X X X X LifecycleManager SOAInfrastructure User

The sections that follow describe the commands that need to be executed in order to add the required permissions to each of the roles.

Adding permissions to the Administrator role
In order to add the required permissions to the Administrator role, execute the commands shown in Example 13-5.
Example 13-5 Commands to add the required permissions to the Administrator role

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl Administrator srrCreate IBMITSOAdministratorCreatePermission /WSRR/BaseObject

470

WebSphere Service Registry and Repository Handbook

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl Administrator srrRetrieve IBMITSOAdministratorRetrievePermission /WSRR/BaseObject \wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl Administrator srrUpdate IBMITSOAdministratorUpdatePermission /WSRR/BaseObject \wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl Administrator srrDelete IBMITSOAdministratorDeletePermission /WSRR/BaseObject \wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl Administrator srrTransition IBMITSOAdministratorTransitionPermission /WSRR/BaseObject \wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar

Chapter 13. Configuring governance

471

-f addPermissionToRole.jacl Administrator srrManageGov IBMITSOAdministratorManageGovPermission /WSRR/BaseObject

The modifications to the permissions in the WSRR Authorization component must be persisted in order for them to become effective. In order to do this, execute the command shown in Example 13-6.
Example 13-6 Command to persist the WSRR permissions policy

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f persistPolicy.jacl

Adding permissions to the LifecycleManager role
In order to add the required permissions to the LifecycleManager role, execute the commands shown in Example 13-7.
Example 13-7 Commands to add the required permissions to the LifecycleManager role

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl LifecycleManager srrRetrieve IBMITSOLifecycleManagerRetrievePermission /WSRR/BaseObject \wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl LifecycleManager srrUpdate IBMITSOLifecycleManagerUpdatePermission /WSRR/BaseObject

472

WebSphere Service Registry and Repository Handbook

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl LifecycleManager srrTransition IBMITSOLifecycleManagerTransitionPermission /WSRR/BaseObject \wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl LifecycleManager srrManageGov IBMITSOLifecycleManagerManageGovPermission /WSRR/BaseObject

The modifications to the permissions in the WSRR Authorization component must be persisted in order for them to become effective. In order to do this, execute the command shown in Example 13-6 on page 472.

Adding permissions to the SOAInfrastructure role
In order to add the required permissions to the SOAInfrastructure role, execute the commands shown in Example 13-8.
Example 13-8 Commands to add the required permissions to the SOAInfrastructure role

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl SOAInfrastructure srrRetrieve IBMITSOSOAInfrastructureRetrievePermission /WSRR/BaseObject \wsadmin.bat -user wasadmin -password passw0rd

Chapter 13. Configuring governance

473

-wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl SOAInfrastructure srrUpdate IBMITSOSOAInfrastructureUpdatePermission /WSRR/BaseObject

The modifications to the permissions in the WSRR Authorization component must be persisted in order for them to become effective. In order to do this, execute the command shown in Example 13-6 on page 472.

Adding permissions to the User role
In order to add the required permissions to the User role, execute the commands shown in Example 13-9.
Example 13-9 Command to add the required permission to the User role

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPermissionToRole.jacl User srrRetrieve IBMITSOUserRetrievePermission /WSRR/BaseObject

The modifications to the permissions in the WSRR Authorization component must be persisted in order for them to become effective. In order to do this, execute the command shown in Example 13-6 on page 472.

Removing permissions from the User role
As discussed in “User Permissions” on page 195, the User role is granted some default permissions in the WSRR authorization component by the installation process. Two of these permissions grant the User role the permission to retrieve objects from WSRR that are in specific states in the default lifecycle. Since this action is also authorized for the User role by the permission defined in Example 13-9, these permissions do not concern us, although it would normally be best practice to remove them. However, the GovernedUserUpdatePermission authorizes the User role to update objects in WSRR that are in the Model or Assemble states defined by the default lifecycle. The requirements specified by IBM-ITSO Ltd. do not allow users

474

WebSphere Service Registry and Repository Handbook

in the User role to perform any updates of objects in WSRR and so this permission must be removed. In order to remove this permission from the User role, execute the command shown in Example 13-10.
Example 13-10 Command to remove the GovernedUserUpdatePermission permission from the User role

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f removePermissionFromRole.jacl GovernedUserUpdatePermission User

The modifications to the permissions in the WSRR Authorization component must be persisted in order for them to become effective. In order to do this, execute the command shown in Example 13-6 on page 472.

13.1.5 Mapping users to roles
Now that the roles required by IBM-ITSO Ltd. have been created and the required permissions have been added to them, the only thing that remains to be done is to add the relevant users to them. The required role mappings for IBM-ITSO Ltd. are shown in Table 13-4.
Table 13-4 IBM-ITSO Ltd. role mappings Role name Administrator User SOAInfrastructure LifecycleManager Mapped users wasadmin AllAuthenticatedUsers itcam4soa wesb assetmgr

Note that the Administrator and User roles are just shown for completeness. The wasadmin user was mapped to the Administrator in 13.1.2, “Removing the AllAuthenticatedUsers principal from the WSRR Administrator role” on page 467. The AllAuthenticatedUsers special subject was mapped to the User role during WSRR installation. In order to map the relevant users to the new roles in the WSRR Authorization component, execute the commands shown in Example 13-11 on page 476.

Chapter 13. Configuring governance

475

Example 13-11 Commands to map users to roles

\wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPrincipalToRole.jacl itcam4soa SOAInfrastructure \wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPrincipalToRole.jacl wesb SOAInfrastructure \wsadmin.bat -user wasadmin -password passw0rd -wsadmin_classpath \ServiceRegistryClient.jar -f addPrincipalToRole.jacl asssetmgr LifecycleManager

The modifications to the role mappings in the WSRR Authorization component must be persisted in order for them to become effective. In order to do this, execute the command shown in Example 13-3 on page 468. Note: If WebSphere Application Server has been configured to use an LDAP user registry and you are attempting to map an LDAP group principal to a role in WSRR, you must specify the fully qualified name of the LDAP group principal, for example: cn=wsrruser,ou=itdepartment,o=IBMITSO

13.2 Using lifecycles
As discussed in 5.2, “Lifecycles” on page 158, WebSphere Service Registry and Repository provides support for the definition and enforcement of a lifecycle. The sections that follow describe how a lifecycle can be applied to an object in

476

WebSphere Service Registry and Repository Handbook

WSRR, how the lifecycle state of an object can by transitioned from one state to another and how you can stop applying a lifecycle to an object. All of these tasks can be performed using both the WSRR Web UI or the Governance API. However, the sections that follow only describe how to perform these tasks using the Web UI. For more information about performing these tasks using the Governance API, refer to the Governance application programming section of the WebSphere Service Registry and Repository Information Center: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.doc/t wsr_mansrvce_programmingguide_1_502.html These tasks are not described within the context of a scenario. We simply describe the steps that need to be performed in order to achieve the tasks. The following chapters may refer to these instructions when asking you to perform the relevant actions in the context of the scenario for that chapter.

13.2.1 Making an object governable
Recall that the process of applying a lifecycle to an object in WSRR is referred to as making the object governable. The steps here describe how to make an object governable using the Web user interface. 1. Logon to the WebSphere Service Registry and Repository Console as a user in the Administrator role. 2. In the navigation tree, expand Service Documents. 3. Click WSDL Documents. 4. Click a WSDL document in the list. 5. On the details view of the WSDL document, click the Governance tab. 6. The Governance tab displays the current governance status for the object. when the object is not governed, the panel will as shown in Figure 13-5 on page 478.

Chapter 13. Configuring governance

477

Figure 13-5 Governance tab for an object that is not governed

7. Select a suitable transition from the Initial state transitions list. When using the WSRR default lifecycle, only the Default transition is available. 8. Click Make Governable. 9. The WSDL document is made governable. During this process a GovernanceRecord is created and the object is added to its list of governed objects. The object is also classified using the relevant initial state for the lifecycle in question. Figure 13-6 on page 479 shows the governance panel for the ItemPrice.wsdl WSDL document after making it governable. Notice that the Governance State for the object is Created. This is initial state for the WSRR default lifecycle.

478

WebSphere Service Registry and Repository Handbook

Figure 13-6 Governance tab for a governed object

13.2.2 Transitioning the lifecycle state of a governed object
Once an object in WSRR is governed, it is possible to transition the governed object from one lifecycle state to another. The steps here describe how to transition the governed object. 1. In the navigation tree, expand Service Documents. 2. Click WSDL Documents. 3. Click a WSDL document in the list. 4. On the details view of the WSDL document, click the Governance tab. 5. Select the required transition from the Available state transitions list. 6. Click Transition, as shown in Figure 13-7 on page 480.

Chapter 13. Configuring governance

479

Figure 13-7 Transitioning an object

7. The lifecycle state of the WSDL document is transitioned to the relevant state. In the example shown, the WSDL object is originally in the Created state. In the default lifecycle, the only transition from that is available from this state is the Plan transition. Performing this transition moves the WSDL document from the Created state to the Model state, as shown in Figure 13-8 on page 481.

480

WebSphere Service Registry and Repository Handbook

Figure 13-8 New lifecycle state

Note: When using the default lifecycle, it is not always possible to transition an object back to a previous state in the lifecycle. This is due to the fact that some states only have transitions defined that move objects forwards in the lifecycle. Refer to 5.2.3, “WSRR default lifecycle” on page 163 for more information about the transitions that are possible in the WSRR default lifecycle.

13.2.3 Removing governance from an object
If, at some point, you decide that you no longer want to apply a lifecycle to an object, you can remove governance from the object. The steps here describe how to remove governance from a governed object. 1. In the navigation tree, expand Service Documents. 2. Click WSDL Documents. 3. Click a WSDL document in the list. 4. On the details view of the WSDL document, click the Governance tab. 5. Click Remove Governance, as shown in Figure 13-9 on page 482.

Chapter 13. Configuring governance

481

Figure 13-9 Removing governance from an object.

6. Governance is removed from the WSDL document. That is, the WSDL document no longer has a lifecycle applied to it. During this process the GovernanceRecord associated with the WSDL document is deleted. The governance panel is updated to reflect the fact that the WSDL document is no longer governed, as shown in Figure 13-5 on page 478. Note: Governance can only be removed from the root object of a governance collection. Attempting to remove governance from any non-root object in the governance collection will result in an error. It is possible to navigate from an object in the governance collection to the root object of the governance collection. This can be done by selecting the Root governance record link on the Governance tab of the non-root object.

13.3 Developing custom plugins
As discussed in 5.4, “WSRR plugins” on page 197, WebSphere Service Registry and Repository provides the following system programming interfaces that allow you to implement WSRR plugins that can be invoked during the standard processing performed by WSRR:

482

WebSphere Service Registry and Repository Handbook

– – – –

ServiceRegistryValidator ServiceRegistryGovernanceValidator ServiceRegistryNotifier ServiceRegistryGovernanceNotifier

The sections that follow describe an example of developing, packaging, deploying and configuring a validation and a notification plugin. Note: This section assumes that you have already downloaded and unpacked the additional materials itso.zip file to the root of the your C drive. For more detailed information, refer to Appendix B, “Additional material” on page 877.

13.3.1 Developing a custom validator
In the context of our scenario, IBM-ITSO Ltd. wants to store in memory copies of the documents in WSRR on client machines in order to improve performance. To do this, they must be able to determine if the content of the document that is stored in WSRR is the same as the content of the document that is stored on the client. IBM-ITSO Ltd. has decided to make use of the java.security.MessageDigest class to calculate a fixed-length hash value for each document that is stored in WSRR. The java.security.MessageDigest class provides applications with the functionality of a message digest algorithm, such as MD5 or SHA. Message digests are secure one-way hash functions that take arbitrary-sized data and output a fixed-length hash value. In order to ensure that each document that is stored in WSRR has the correct hash value associated with it, IBM-ITSO Ltd. has implemented a validation plugin that will calculate the hash value when a document is created or updated in WSRR. The sections that follow describe the implementation of this validator. The full source code for this validator can be found in the \ITSO\WSRR\src directory, where is the directory where you extracted the additional materials for this redbook.

ITSOValidationPlugin class definition
IBM-ITSO Ltd. require that the hash value for a document be calculated regardless of whether or not the document in question is a governed object. Since their validator does make use of any of the methods defined on the ServiceRegistryGovernanceValidator interface, it simply implements the ServiceRegistryValidator interface, as shown in Example 13-12 on page 484.

Chapter 13. Configuring governance

483

Example 13-12 ITSOValidationPlugin class

public class ITSOValidationPlugin implements ServiceRegistryValidator { // Checksum property name constant private static final String CHECKSUM_PROPERTY = "checksum"; public ServiceRegistryStatus create(OriginalObject newObject) { // Make sure that the object has a CustomerType property ServiceRegistryStatus srStatus = addChecksum(newObject); return srStatus; } public ServiceRegistryStatus update(OriginalObject oldObject, OriginalObject newObject) { // Make sure that the object has a CustomerType property ServiceRegistryStatus srStatus = addChecksum(newObject); return srStatus; } public ServiceRegistryStatus delete(OriginalObject oldObject) { return new ServiceRegistryStatus(); } }

The addChecksum method
Both the create and the update methods of the validation plugin invoke the addChecksum method. The addChecksum method is shown in Example 13-13 on page 485. This method needs to ensure that the object in question is a Document object. Once it has determined that the object in question represents a document, it checks to see if the object has a checksum property. If no checksum property is present, the hash value for the document content is calculated. A checksum property is then added to the object using the calculated hash as the value. If the object already has checksum value, a check is made to ensure that the checksum is correct since it is possible that the content of the document has been updated. If the hash value that is calculated for the document content is different to the hash value stored in the checksum property, the value of the checksum property is updated with the new hash value.

484

WebSphere Service Registry and Repository Handbook

Example 13-13 addChecksum method

private ServiceRegistryStatus addChecksum(OriginalObject object) { // Create the variable to return ServiceRegistryStatus srStatus = new ServiceRegistryStatus(); // Make sure that the object represents a document if (object instanceof Document) { // Cast the object to a document Document document = (Document)object; // All document objects must have a checksum property. If it's // not already there add it, unless there is a relationship with // the same name, in which case we have an error. BSRSDOHelper sdoHelper = BSRSDOHelper.INSTANCE; if (!sdoHelper.isRelationshipSet(object, CHECKSUM_PROPERTY)) { try { if (!sdoHelper.isPropertySet(object, CHECKSUM_PROPERTY)) { // No CustomerType property or relationship... // ...add the property. String checksum = calculateMD5Checksum(document.getContent()); sdoHelper.addProperty(object, CHECKSUM_PROPERTY, checksum); } else { // Check to see if the content of the object has // changed by comparing checksums String currentChecksum = sdoHelper.getPropertyValue( object, CHECKSUM_PROPERTY); String newChecksum = calculateMD5Checksum( document.getContent()); if (!currentChecksum.equals(newChecksum)) { sdoHelper.addProperty(object, CHECKSUM_PROPERTY, newChecksum); } } } catch (Exception e) { // Add exception to the status object. // This automatically sets the return code to ERROR srStatus.addException(e); } } else { // A relationship called CustomerType already exists on the

Chapter 13. Configuring governance

485

// object... this is an error. srStatus.addDiagnostic(ServiceRegistryStatus.ERROR, "Relationship with name: " + CHECKSUM_PROPERTY + " already exists on the object"); } } return srStatus; }

The calculateMD5Checksum method
The calculateMD5Checksum method is the method that actually calculates the hash value of the document content. As its name suggests, it uses the MD5 message digest algorithm in order to calculate the hash value. It then converts this hash value to a hexadecimal string. The calculateMD5Checksum method is shown in Example 13-14.
Example 13-14 calculateMD5Checksum method

private String calculateMD5Checksum(byte[] content) throws NoSuchAlgorithmException { // Create the variable to return String md5hash = null; // Create the MD5 MessageDigest object MessageDigest msgDigest = MessageDigest.getInstance("MD5"); byte[] md5sum = msgDigest.digest(content); // Convert the byte array to hex BigInteger bigInt = new BigInteger(1, md5sum); md5hash = bigInt.toString(16); return md5hash; }

13.3.2 Developing a customer notifier
In the context of our scenario, IBM-ITSO Ltd. wants to use the WSRR mediation primitive in provided with WebSphere Enterprise Service Bus to dynamically route service requests to the target service based on the customer type. The WSRR mediation primitive queries WSDLPort objects from WSRR at runtime using the metadata defined on these objects. IBM-ITSO Ltd. wants to add a

486

WebSphere Service Registry and Repository Handbook

CustomerType property to all WSDLPort objects in WSRR to be used for this purpose. WSDLPort objects, however, do not represent physical documents in WSRR. A WSDLPort is a derived object that is created to represent the contents of a port element contained in a WSDL document. Therefore, a WSRR validation or notification plugin will not be invoked directly as the result of creating a WSDLPort object. In order to update WSDLPort objects in WSRR, IBM-ITSO Ltd. has implemented a notification plugin that adds a CustomerType property to all of the WSDLPorts that are created when a WSDLDocument object is created or updated. Note: The CustomerType property is added to WSDLPort objects using a notification plugin because the plugin must make use of the bsrURI of the WSDLDocument in order to query the relevant WSDLPort objects from WSRR. It is not possible to use a validator for this, since the bsrURI of objects that are being created does not get set until the object is persisted to WSRR. This happens after the create method on the validator is invoked.

Note: The value of the CustomerType property that is added to the WSDLPort objects is an empty string. IBM-ITSO Ltd. administrators still need to manually specify the correct value of this property in order to ensure that service requests are routed correctly. The sections that follow describe the implementation of this notifier. The full source code for this notifier can be found in the \ITSO\WSRR\src directory, where is the directory where you extracted the additional materials for this redbook.

ITSONotificationPlugin class definition
IBM-ITSO Ltd. require that the CustomerType property be added to WSDLPort objects regardless of whether or not the WSDLDocument being created or updated is a governed object. Since their notifier does make use of any of the methods defined on the ServiceRegistryGovernanceNotifier interface, it simply implements the ServiceRegistryNotifier interface, as shown in Example 13-15 on page 488. Notice that the notifier has a constructor that it uses to create an InitialContext instance. However, the constructor does not attempt to create an instance of the WSRR API session EJB. As discussed in 5.4, “WSRR plugins” on page 197, validators and notifiers should not attempt to create instances of the ServiceRegistrySession or ServiceRegistryGovernance EJB’s within their constructors.

Chapter 13. Configuring governance

487

Example 13-15 ITSONotificationPlugin class

public class ITSONotificationPlugin implements ServiceRegistryNotifier { // Business owner property name constant private static final String CUSTOMER_TYPE_PROPERTY = "CustomerType"; // Attribute required to acces WSRR API session EJB private InitialContext context = null; private ServiceRegistrySession wsrrClient = null; public ITSONotificationPlugin() { try { // Create the InitialContext object context = new InitialContext(); } catch (NamingException e) { e.printStackTrace(); } } public void create(OriginalObject newObject, boolean success, ServiceRegistryException ex) { // Check to see if the create succeeded if (success) { // Check to see if a WSDLDocument was created if (newObject instanceof WSDLDocument) { // Check the WSDLPorts for the CustomerType property checkWSDLPorts((WSDLDocument) newObject); } } } public void update(BaseObject oldObject, BaseObject newObject, boolean success, ServiceRegistryException ex) { // Check to see if the update succeeded if (success) { // Check to see if a WSDLDocument was updated if (newObject instanceof WSDLDocument) {

488

WebSphere Service Registry and Repository Handbook

// Check the WSDLPorts for the CustomerType property checkWSDLPorts((WSDLDocument) newObject); } } } public void delete(OriginalObject oldObject, boolean success, ServiceRegistryException ex) { } }

The init method
The ITSONotificationPlugin implements an init method in order to perform lazy initialization of the ServiceRegistrySession EJB reference. This is shown in Example 13-16.
Example 13-16 init method

private void init() { // Get the local home try { Object obj = context.lookup( "ejb/com/ibm/serviceregistry/ServiceRegistrySessionHome"); ServiceRegistrySessionHome home = (ServiceRegistrySessionHome)PortableRemoteObject.narrow(obj, ServiceRegistrySessionHome.class); wsrrClient = home.create(); } catch (Exception e) { e.printStackTrace(); } }

The checkWSDLPorts method
Both the create and the update methods of the notification plugin check to see if the object being created or updated is a WSDLDocument object. If it is, they invoke the checkWSDLPorts method. The checkWSDLPorts method is shown in Example 13-17 on page 490.

Chapter 13. Configuring governance

489

The first thing that the checkWSDLPorts method does is to ensure that the reference to the WSRR API session EJB is initialized. This lazy initialization of the EJB reference avoids the infinity loop issue discussed in 5.4, “WSRR plugins” on page 197. The checkWSDLPorts method then needs to execute a query to obtain all of the WSDLPorts that were created as a result of creating or updating the WSDLDocument. WSRR provides a set of predefined queries that can be used to run common queries. The getWSDLDocPorts query returns the list of WSDLPort objects for a given WSDLDocument. For the full list of predefined queries that are available in WSRR, see the WebSphere Service Registry and Repository Information Center: http://publib.boulder.ibm.com/infocenter/sr/v6r0/topic/com.ibm.sr.do c/programguide63.html The checkWSDLPorts method iterates over the list of WSDLPort objects that was returned by the query and checks each one for the existence of the CustomerType property.
Example 13-17 checkWSDLPorts method

private void checkWSDLPorts(WSDLDocument wsdlDocument) { // Make sure that remote EJB reference is initialized if (wsrrClient == null) { init(); } try { // Run the getWSDLDocPorts predefined query String[] params = new String[] { wsdlDocument.getBsrURI() }; List results = wsrrClient.executeNamedQuery("getWSDLDocPorts", params); // For each WSDLPort found, make sure that // it has CustomerType property for (Iterator i = results.iterator(); i.hasNext();) { WSDLPort wsdlPort = (WSDLPort) i.next(); checkForCustomerType(wsdlPort); } } catch (Exception e) { e.printStackTrace(); } }

490

WebSphere Service Registry and Repository Handbook

The checkForCustomerType method
The checkForCustomerType method simply checks the WDSLPort object to see if it has a CustomerType property. If no CustomerType property is present, it adds the property with an empty string as the value. The checkForCustomerType method is shown in Example 13-18.
Example 13-18 checkForCustomerType method

private void checkForCustomerType(WSDLPort wsdlPort) { // All objects need to have the CustomerType property. // If it's not already there add it, unless there is a relationship // with the same name, in which case we have an error. BSRSDOHelper sdoHelper = BSRSDOHelper.INSTANCE; if(!sdoHelper.isRelationshipSet(wsdlPort, CUSTOMER_TYPE_PROPERTY)) { if (!sdoHelper.isPropertySet(wsdlPort, CUSTOMER_TYPE_PROPERTY)) { try { // No CustomerType property or relationship... // ... add the property. sdoHelper.addProperty(wsdlPort, CUSTOMER_TYPE_PROPERTY, ""); wsrrClient.update(wsdlPort); } catch (Exception e) { e.printStackTrace(); } } } else { System.out.println( "Relationship with name: " + CUSTOMER_TYPE_PROPERTY + " already exists on the object"); } }

13.3.3 Deploying custom plugins
As discussed in 5.4.3, “Packaging plugins” on page 206, the recommended way of deploying custom plugins is to package them in a JAR file and add this JAR file to the classpath of the WSRR application. Two actions need to be performed in order to achieve this, as follows: 1. The JAR file containing the plugin implementation classes must be added to the classpath of a shared library within WebSphere Application Server instance on which WSRR is running.

Chapter 13. Configuring governance

491

2. A reference to this shared library must be added to the WSRR application. These actions are described in the sections that follow.

Creating the shared library
IBM-ITSO Ltd. have packaged the ITSOValidationPlugin and ITSONotificationPlugin into a JAR file called ITSO_WSRR_Plugins.jar. This JAR file is provided with the additional materials in the \ITSO\WSRR\plugins directory, where is the directory where you extracted the additional materials for this redbook. In order to create a shared library and add this JAR file to its classpath, follow the steps described here: 1. Copy the ITSO_WSRR_Plugins.jar to a directory on the target machine, for example, C:\ITSO\WSRR\plugins. 2. Logon to the WebSphere Application Server Administrative Console. 3. In the navigation tree, expand Environment → Shared Libraries. 4. Click New. 5. Enter ITSO_WSRR_Plugins in the Name field. 6. Enter the path to the ITSO_WSRR_Plugins.jar file in the Classpath field, as shown in Figure 13-10 on page 493.

492

WebSphere Service Registry and Repository Handbook

Figure 13-10 Creating the shared library

7. Click OK. 8. Save the changes and synchronize them with the nodes.

Adding a reference to the shared library to WSRR
The new shared library has now been created at the specified scope within the WebSphere Application Server cell. However, the plugin implementation classes contained in the shared library are still not available to WSRR. In order to make them available to WSRR, the shared library needs to be added to the classloader for the WSRR application. To do this, follow the steps described here: 1. In the navigation tree, expand Applications → Enterprise Applications. 2. In the list of enterprise applications, click ServiceRegistry. 3. In the Additional Properties section, click Libraries.

Chapter 13. Configuring governance

493

4. Click Add. 5. Select ITSO_WSRR_Plugins in the Library name drop down list, as shown in Figure 13-11.

Figure 13-11 Adding the shared library reference to WSRR

6. Click OK. 7. Save the changes and synchronize them with the nodes. 8. For the changes to become effective, you must restart the application server on which WSRR is running.

13.3.4 Configuring custom plugins
WSRR is now able to access the plugin implementation classes contained in the ITSO_WSRR_Plugins.jar file. However, WSRR needs to be configured so that it knows what actions and what object types the plugins need to be invoked for. As discussed in 5.4.4, “Configuring plugins” on page 207, this is achieved by modifying the relevant configuration properties file. The sections that follow describe how to configure the validation and notification plugins in WSRR.

Configuring the validation plugin
The sections that follow describe how to configure the validation plugin in WSRR.

494

WebSphere Service Registry and Repository Handbook

Retrieving the validation configuration properties file from WSRR
In order to make the necessary modifications to the validation configuration properties file, it must first be retrieved from WSRR. We have provided a script that will retrieve this configuration properties file from WSRR. In order to retrieve the file using this script, follow the steps described here: 1. Open a command prompt and change to the \ITSO\WSRR\scripts directory, where is the directory where you extracted the additional materials for this redbook. 2. Execute the command shown in Example 13-19, where is the path to the directory where WebSphere Application Server is installed and is the file path to the directory where the ServiceRegistryClient.jar resides.
Example 13-19 Running the retrieveConfiguration.jacl script

\bin\wsadmin -wsadmin_classpath \ServiceRegistryClient.jar -f retrieveConfiguration.jacl ValidationProperties PLUGIN_PROPERTIES true validation.properties Note: The command shown in Example 13-19 must be entered on a single line of the command window. 3. The validation configuration properties file will be retrieved from WSRR and written to the validation.properties file.

Modifying the validation configuration properties file
Once the configuration properties file has been retrieved, it must be modified to include an entry for the ITSOValidationPlugin. Recall that the ITSOValidationPlugin adds a checksum property to documents when they are created or updated in WSRR. The plugin itself checks that the type of document being created represents a physical document, so it is possible to add the ITSOValidationPlugin implementation class to the end of the list of validators specified on the validators key. To do this, follow the steps described here: 1. Open the validation.properties file in a text editor. 2. Modify the validators key to include the fully qualified ITSOValidationPlugin implementation class, as shown in Example 13-20 on page 496.

Chapter 13. Configuring governance

495

Example 13-20 Modifying the validation configuration properties file

# These validators are called for all document types validators=com.ibm.sr.api.SRTemplateValidator,com.ibm.itso.plugins.ITSO ValidationPlugin 3. Save and close the validation.properties file.

Updating the validation configuration properties file in WSRR
The modified validation configuration properties file must now be stored back in WSRR. WSRR provides a sample administration script that can be used to update configuration objects. In order to update the configuration properties file using this script, follow the steps described here: 1. Copy the modified validation.properties file to \admin\scripts, where is the directory where WSRR is installed. 2. Open a command prompt and change to the \admin\scripts directory. 3. Execute the command shown in Example 13-21, where is the path to the directory where WebSphere Application Server is installed.
Example 13-21 Running the updateConfiguration.jacl script

\bin\wsadmin -wsadmin_classpath \ServiceRegistryClient.jar -f updateConfiguration.jacl . validation.properties ValidationProperties PLUGIN_PROPERTIES true Note: The command shown in Example 13-21 must be entered on a single line of the command window.

496

WebSphere Service Registry and Repository Handbook

Note: The parameters required by the updateConfiguration.jacl script are:
Filepath Filename Configuration name Configuration type System configuration

The current directory “.” is specified as the filepath specified in Example 13-21. If you need to specify a fully qualified filepath for when running this script on the Windows platform, all path separators need to be specified using forward slashes “/”. 4. The validation configuration properties file has now been updated in WSRR. For the changes to become effective, you must restart the application server on which WSRR is running.

Configuring the notification plugin
The sections that follow describe how to configure the notification plugin in WSRR.

Retrieving the notification configuration properties file from WSRR
In order to make the necessary modifications to the notification configuration properties file, it must first be retrieved from WSRR. We have provided a script that will retrieve this configuration properties file from WSRR. In order to retrieve the file using this script, follow the steps described here: 1. Open a command prompt and change to the \ITSO\WSRR\scripts directory, where is the directory where you extracted the additional materials for this redbook. 2. Execute the command shown in Example 13-19 on page 495, where is the path to the directory where WebSphere Application Server is installed and is the file path to the directory where the ServiceRegistryClient.jar resides.
Example 13-22 Running the retrieveConfiguration.jacl script

\bin\wsadmin -wsadmin_classpath \ServiceRegistryClient.jar -f retrieveConfiguration.jacl NotificationProperties PLUGIN_PROPERTIES true notification.properties

Chapter 13. Configuring governance

497

Note: The command shown in Example 13-22 must be entered on a single line of the command window. 3. The notification configuration properties file will be retrieved from WSRR and written to the notification.properties file.

Modifying the notification configuration properties file
Once the configuration properties file has been retrieved, it must be modified to include an entry for the ITSONotificationPlugin. Recall that the ITSONotificationPlugin adds a CustomerType property to WSDLPort objects when the WSDLDocument object that contains them has been created or updated in WSRR. Since the plugin only needs to be invoked after a WSDLDocument object is created or updated, the ITSONotificationPlugin implementation class can be added to the end of the list of notifiers specified on a new key of notifiers.WSDLDocument. To do this, follow the steps described here: 1. Open the notification.properties file in a text editor. 2. Add a new notifiers.WSDLDocument key to the properties file, specifying the fully qualified ITSONotificationPlugin implementation class as the value, as shown in Example 13-23.
Example 13-23 Modifying the validation configuration properties file

# These validators are called for all WSDLDocuments notifiers.WSDLDocument=com.ibm.itso.plugins.ITSONotificationPlugin 3. Save and close the notification.properties file.

Updating the notification configuration properties file in WSRR
The modified notification configuration properties file must now be stored back in WSRR. WSRR provides a sample administration script that can be used to update configuration objects. In order to update the configuration properties file using this script, follow the steps described here: 1. Copy the modified notification.properties file to \admin\scripts, where is the directory where WSRR is installed. 2. Open a command prompt and change to the \admin\scripts directory. 3. Execute the command shown in Example 13-21 on page 496, where is the path to the directory where WebSphere Application Server is installed.

498

WebSphere Service Registry and Repository Handbook

Example 13-24 Running the updateConfiguration.jacl script

\bin\wsadmin -wsadmin_classpath \ServiceRegistryClient.jar -f updateConfiguration.jacl . notification.properties NotificationProperties PLUGIN_PROPERTIES true Note: The command shown in Example 13-24 must be entered on a single line of the command window.

Note: The parameters required by the updateConfiguration.jacl script are:
Filepath Filename Configuration name Configuration type System configuration

The current directory “.” is specified as the filepath specified in Example 13-21. If you need to specify a fully qualified filepath for when running this script on the Windows platform, all path separators need to be specified using forward slashes “/”. 4. The notification configuration properties file has now been updated in WSRR. For the changes to become effective, you must restart the application server on which WSRR is running.

13.4 Performing impact analysis
The sections that follow provide a number of examples of performing impact analysis in WSRR using the Web user interface in order to determine the dependencies that exist between various artefacts. The artefacts that are used within the example are those from the IBM-ITSO Ltd. scenario described in Chapter 12, “Scenarios description” on page 453. It is assumed at this point that all of the relevant artefacts for the scenario have been loaded into WSRR.

Chapter 13. Configuring governance

499

13.4.1 Analyzing dependencies between physical document objects
The documents for the services that IBM-ITSO Ltd. have developed have been loaded into WSRR in their SOA environment. The object graph for the physical document objects for these services is very simple, consisting of three WSDL documents, as follows: ItemPricePortType.wsdl ItemPrice.wsdl ItemPriceDiscounted.wsdl The ItemPricePortType.wsdl document simply defines the port type for the service. The ItemPrice.wsdl and ItemPriceDiscounted.wsdl documents both import the ItemPricePortType.wsdl document and define bindings and endpoints for the service. This is shown in Figure 13-12.

ItemPricePortType WSDL

import

import

ItemPrice WSDL

ItemPriceDiscounted WSDL

Figure 13-12 IBM-ITSO Ltd. physical document objects

WSDL documents that import other WSDL documents
The importedWSDLs relationship on a WSDLDocument object can be navigated in order to determine whether it imports other WSDL documents. To use impact analysis to determine the list of WSDL documents that are imported by the ItemPrice.wsdl document object, follow the steps described here: 1. Logon to the WebSphere Service Registry and Repository Console.

500

WebSphere Service Registry and Repository Handbook

2. In the navigation tree, expand Service Documents. 3. Click WSDL Documents. 4. Click ItemPrice.wsdl in the WSDL documents. 5. On the details view of the WSDL document, click the Impact Analysis tab. 6. To determine which WSDL documents are imported, we must determine the outbound dependencies for the ItemPrice.wsdl document. Therefore, check the Include entities this entity depends on check box. 7. The modelled relationships that can be specified when performing impact analysis on WSDLDocument objects are described in Table 5-12 on page 225. To determine which WSDL documents are imported, select the WSDL document to imported WSDL document from the Built-in relationships list box, as shown in Figure 13-13.

Figure 13-13 Analyzing outbound dependencies to other WSDL documents

8. Click OK. 9. The results are shown in Figure 13-14 on page 502.

Chapter 13. Configuring governance

501

Figure 13-14 WSDL documents imported by ItemPrice.wsdl

The results can be interpreted by reading the columns in the order: 1. Originating Object 2. Impact Relationship 3. Name 4. Relationship name For the results shown in Figure 13-14, this would interpreted as: ItemPrice.wsdl depends on ItemPricePortType.wsdl via the importedWsdls relationship.

WSDL documents that are imported by other WSDL documents
It is also possible to use impact analysis to traverse the importedWSDLs relationship on a WSDLDocument object in the other direction. That is, it is possible to use impact analysis to determine whether other WSDL documents import the WSDL document in question. To use impact analysis to determine the list of WSDL documents that import the ItemPricePortType.wsdl document object, follow the steps described here: 1. Logon to the WebSphere Service Registry and Repository Console. 2. In the navigation tree, expand Service Documents. 3. Click WSDL Documents. 4. Click ItemPricePortType.wsdl in the WSDL documents. 5. On the details view of the WSDL document, click the Impact Analysis tab. 6. To determine which WSDL documents import this document, we must determine the inbound dependencies for the ItemPricePortType.wsdl document. Therefore, check the Include entities that depend on this entity check box. 7. The modelled relationships that can be specified when performing impact analysis on WSDLDocument objects are described in Table 5-12 on page 225.

502

WebSphere Service Registry and Repository Handbook

To determine which WSDL documents that import this WSDL document, select the WSDL document to imported WSDL document from the Built-in relationships list box, as shown in Figure 13-15.

Figure 13-15 Analyzing inbound dependencies from other WSDL documents

8. Click OK. 9. The results are shown in Figure 13-16.

Figure 13-16 WSDL documents that import the ItemPricePortType.wsdl

The results can be interpreted by reading the columns in the order: 1. Originating Object 2. Impact Relationship 3. Name

Chapter 13. Configuring governance

503

4. Relationship name For the results shown in Figure 13-16 on page 503, this would interpreted as: “ItemPricePortType.wsdl is depended on by ItemPriceDiscounted.wsdl via the importedWsdls relationship.” “ItemPricePortType.wsdl is depended on by ItemPrice.wsdl via the importedWsdls relationship.”

13.4.2 Analyzing dependencies between physical document objects and derived objects
The derived objects that were created when the ItemPricePortType.wsdl document was loaded into WSRR are shown in Figure 13-17.

ItemPrice WSDLPortType

getPrice WSDLOperation

getPriceRequest WSDLMessage

getPriceResponse WSDLMessage

parameters WSDLPart

getPrice ElementDeclaration

getPriceResponse ElementDeclaration

Figure 13-17 Derived objects parsed from the ItemPricePortType.wsdl document

504

WebSphere Service Registry and Repository Handbook

As noted in “LogicalObject relationships” on page 229, the ItemPricePortType.wsdl WSDLDocument object has no knowledge of any of the derived objects that were produced from it. However, it is possible to use impact analysis to determine all of the derived objects that were parsed from a physical document object. This can be done by specifying the document relationship when performing impact analysis to determine inbound dependencies on a physical document object. To use impact analysis to determine the list of derived objects that were parsed from the ItemPricePortType.wsdl document object, follow the steps described here: 1. Logon to the WebSphere Service Registry and Repository Console. 2. In the navigation tree, expand Service Documents. 3. Click WSDL Documents. 4. Click ItemPricePortType.wsdl in the WSDL documents. 5. On the details view of the WSDL document, click the Impact Analysis tab. 6. To determine which derived objects were parsed from this WSDL document, we must determine the inbound dependencies for the ItemPricePortType.wsdl document. Therefore, check the Include entities that depend on this entity check box. 7. The modelled relationships that can be specified when performing impact analysis on Document objects are described in Table 5-11 on page 224. To determine which derived objects were parsed from this WSDL document select the Derived entity reference to its source document from the Built-in relationships list box, as shown in Figure 13-18 on page 506.

Chapter 13. Configuring governance

505

Figure 13-18 Analyzing inbound dependencies from derived objects

8. Click OK. 9. The results are shown in Figure 13-19.

Figure 13-19 Derived objects parsed from the ItemPricePortType.wsdl

506

WebSphere Service Registry and Repository Handbook

The results can be interpreted by reading the columns in the order: 1. Originating Object 2. Impact Relationship 3. Name 4. Object type 5. Relationship name For the first result in the list shown in Figure 13-19 on page 506, this would interpreted as: “ItemPricePortType.wsdl is depended on by getPriceResponse XML element via the document relationship.” Note: The impact analysis results shown in Figure 13-19 on page 506 actually contains eight results, but only seven derived objects were created when the ItemPricePortType.wsdl was loaded into WSRR. The parameters object appears twice in the impact analysis results due to the fact that this object can be reached via two different branches of the object graph.

13.4.3 Analyzing dependencies between derived objects
Due to the large number relationships that can be traversed when performing impact analysis on derived objects, it is not possible to provide examples for all of them. We simply provide a single example that demonstrates how impact analysis can be used to determine both inbound and outbound dependencies at the same time using the Web user interface. In this example, we demonstrate how to perform impact analysis on the getPrice WSDLOperation object to determine which port type it is defined in and also which input and output messages it defines. In order to do this, follow the steps described here: 1. Logon to the WebSphere Service Registry and Repository Console. 2. In the navigation tree, expand Service Documents → WSDL. 3. Click Operations. 4. In the list of operations, click the getPrice operation that has a Namespace value of http://itso.ibm.com. 5. On the details view of the operation, click the Impact Analysis tab. 6. To determine which input and output messages this operation defines, we must determine the outbound dependencies for the getPrice WSDLOperation. Therefore, check the Include entities this entity depends on check box.

Chapter 13. Configuring governance

507

7. To determine which port type this operation was defined in, we must determine the inbound dependencies for the getPrice WSDLOperation. Therefore, check the Include entities that depend on this entity check box. 8. The modelled relationships that can be specified when performing impact analysis on WSDLOperation objects are described in Table 5-16 on page 231. To determine which input messages the getPrice WSDLOperation defines, select WSDL operation to input WSDL message from the Built-in relationships list box. 9. To determine which output message the getPrice WSDLOperation defines, select WSDL operation to output WSDL message from the Built-in relationships list box. 10.To determine which port type the getPrice WSDLOperation was defined in, select WSDL port type to WSDL operation from the Built-in relationships list box, as shown in Figure 13-20.

Figure 13-20 Analyzing inbound and outbound dependencies for derived objects

11.Click OK. 12.The results are shown in Figure 13-21 on page 509.

508

WebSphere Service Registry and Repository Handbook

Figure 13-21 Dependent objects for the getPrice WSDLOperation

Chapter 13. Configuring governance

509

510

WebSphere Service Registry and Repository Handbook

14

Chapter 14.

Integrating WSRR with WebSphere ESB
This chapter describes how to integrate WSRR with WebSphere Enterprise Service Bus (WESB). The following topics are covered: 14.1, “Introduction” on page 512 14.2, “WebSphere ESB overview” on page 512 14.3, “Structure of WebSphere Enterprise Service Bus” on page 515 14.4, “Related technologies” on page 521 14.5, “Endpoint Lookup mediation primitive” on page 525 14.6, “Managing access from WESB to WSRR” on page 536 14.7, “Integration scenario” on page 543

© Copyright IBM Corp. 2007. All rights reserved.

511

14.1 Introduction
This chapter describes the use of WebSphere Service Registry and Repository in an Enterprise Service Bus (ESB) environment, using WebSphere Enterprise Service Bus (WESB) as the ESB implementation. Use of WSRR allows ESB mediations that interact with some set of endpoint services to be more tolerant of changes within the environment. This is enabled by the ESB using WSRR as a dynamic lookup mechanism, providing information about service endpoints (the service metadata). So, when changes occur in the service endpoint environment, the associated ESB mediations do not have to change. The interaction between WESB and WSRR is provided by a new primitive introduced in WESB V6.0.2 called the Endpoint Lookup primitive. This primitive can be used when building Mediation flows in WESB. It can call WSRR to fetch service metadata and has caching mechanism to improve the efficiency of the interaction. Section 14.5, “Endpoint Lookup mediation primitive” on page 525 includes more information about this new primitive and how it works.

14.2 WebSphere ESB overview
WebSphere Enterprise Service Bus delivers an Enterprise Service Bus (ESB) infrastructure to enable inter-application connections with standards based interfaces (typically a Web service interface described in a WSDL file). It provides mechanisms to process request and response messages from service consumers and service providers that connect to the ESB. WebSphere Enterprise Service Bus is the mediation layer that runs on top of the transport layer within WebSphere Application Server. As such, WebSphere Enterprise Service Bus provides prebuilt mediation functions and easy-to-use tools to enable rapid construction and implementation of an ESB as a value-add on top of WebSphere Application Server. Figure 14-1 on page 513 gives an overview of WebSphere Enterprise Service Bus, the components in the product, and the features and functions that are associated with the product.

512

WebSphere Service Registry and Repository Handbook

Messaging:
MQ Interoperability JMS 1.1

Clients:
C++ Client .Net Client Java and C/C++ Web Services Client

WebSphere Enterprise Service Bus
Custom Mediation

WebSphere Integration Developer

XSLT

Message Logger

Mediation Function

Message Router

DB Lookup

WebSphere Adapter Support

Web Services:
SOAP/ HTTP SOAP/ JMS

WebSphere Application Server
Tivoli Access Manager DB2 Universal Database Edge Components UDDI Web Services Gateway

SCA Programming Model:
SCA

WS-*

UDDI Registry 3.0

SMO

SDO

Figure 14-1 WebSphere Enterprise Service Bus at a glance

WebSphere Enterprise Service Bus leverages WebSphere Application Server Network Deployment qualities of service, with its clustering, failover, scalability, security, and a built-in messaging provider. Along with these qualities, WebSphere Enterprise Service Bus includes a number of key WebSphere Application Server related features, including UDDI as a service registry, the Web services gateway, Tivoli Access Manager, DB2 Universal Database™, and Edge components. WebSphere Enterprise Service Bus adds the following value to the application server: Provides built-in mediation functions, which can be used to create integration logic for connectivity. The Service Component Architecture (SCA) programming model supports rapid development of mediation flow components. WebSphere Integration Developer is an easy-to-use tool that supports WebSphere Enterprise Service Bus. Leveraging WebSphere Application Server, WebSphere Enterprise Service Bus offers JMS messaging and WebSphere MQ interoperability for messaging, as well as a comprehensive clients package for connectivity. Offers support for J2EE Connector Architecture based WebSphere Adapters.

Chapter 14. Integrating WSRR with WebSphere ESB

513

To implement an SOA properly, it is necessary to have a single invocation model and a single data model. Service Component Architecture (SCA) is this invocation model — every integration component is described through an interface. These services can then be assembled in a component assembly editor thus enabling a very flexible and encapsulated solution. WebSphere Enterprise Service Bus introduces a new component type to the SCA model — the mediation flow component. From the perspective of the SCA, a mediation flow component is not different to any other service component. Business Objects are the universal data description. They are used as data objects are passed between services and are based on the Service Data Objects (SDO) standard. In WebSphere Enterprise Service Bus a special type of SDO is introduced, the service message object (SMO).

14.2.1 Key terms in WebSphere Enterprise Service Bus
Table 14-1 summarizes the key terms that are introduced in this chapter in the context of WebSphere Enterprise Service Bus.
Table 14-1 Key terms relating to WebSphere Enterprise Service Bus Term Mediation Explanation A service request interception by an ESB that typically centralizes logic such as routing, transformation, and data handling. The basic building block in WebSphere Enterprise Service Bus for creating mediations. Exposes the interfaces of a mediation module and contains the bindings. The external publishing of an interface for SCA clients only (without a WSDL description). Represents the service providers that are invoked by a mediation module. The protocols and transports that are assigned to exports and imports. The container for mediation logic inside a mediation module that provides interfaces and that uses references. Defines access points and is defined using WSDL.

Mediation module Export Stand-alone reference Import Binding Mediation flow component

Interface

514

WebSphere Service Registry and Repository Handbook

Term Operation

Explanation Represent interactions that can be 1-way (only input parameters) and 2-way (input and output parameters) The declaration of the referenced interfaces of an mediation flow component. An association between components inside a mediation module and exports/imports/stand-alone references. The processing steps that are defined for each interface in the form of a request flow and usually a response flow. Units of message processing inside a mediation flow that provide different terminals. A data object that represents the context, the content, and the header information of an application message that is created during a mediation flow. Data type definitions (specified in an XML schema) that can be used for input/output parameters.

Partner reference Wire

Mediation flow

Mediation primitive Service message object (SMO)

Business object

14.3 Structure of WebSphere Enterprise Service Bus
This section explores the structure of WebSphere Enterprise Service Bus by working through the different layers of the product architecture in a top-down manner.

14.3.1 Mediations, service consumers, and service providers
A service interaction in SOA defines both service consumers and service providers. The role of WebSphere Enterprise Service Bus is to intercept the requests of service consumers and fulfill additional tasks in mediations in order to support loose coupling. When the mediation completes, the relevant service provider(s) should be invoked. The mediation tasks include: Centralizing the routing logic so that service providers can be exchanged transparently Performing tasks like protocol translation and transport mapping

Chapter 14. Integrating WSRR with WebSphere ESB

515

Acting as a facade in order to provide different interfaces between service consumers and providers Adding logic to provide tasks such as logging As shown in Figure 14-2, mediations customize the protocol and the details of a request and also modify the results of the reply.

Figure 14-2 Enterprise Service Bus and mediations

WebSphere Enterprise Service Bus can interconnect a variety of different service consumers and providers using standard protocols including: JMS SOAP over HTTP (for Web services) SOAP over JMS (for Web services) For back-end applications (such as SAP®) several IBM WebSphere Adapters (based on JCA) are available.

14.3.2 Mediation modules
The mediation module is a type of SCA component that can process or mediate service interactions. As illustrated in Figure 14-3 on page 517, the mediation module is externalized or made available through an export, which specifies the interfaces that are exposed. These interfaces are defined in a WSDL document. The mediation module typically invokes other service providers. These providers are declared with the creation of an import, which represents an external service to be invoked.

516

WebSphere Service Registry and Repository Handbook

Figure 14-3 Mediation modules

For each export and import, an interface needs to be specified. Each interface has multiple operations, which in turn can have multiple input and output parameters that are associated with either simple data types or business objects. Every export and import has to be associated with a binding. A binding identifies a specific type of invocation for a service consumer or provider. WebSphere Enterprise Service Bus supports several bindings: Web Service bindings – Web Service bindings allow you to access Web services. – The supported protocols are SOAP/HTTP and SOAP/JMS. SCA bindings – SCA bindings connect SCA modules to other SCA modules. – SCA bindings are also referred to as default bindings. Java Message Service (JMS) 1.1 bindings – JMS bindings allow interoperability with the WebSphere Application Server default messaging provider. – JMS can exploit various transport types, including TCP/IP and HTTP(S). – The JMS Message class and its five subtypes (Text, Bytes, Object, Stream, and Map) are automatically supported. WebSphere MQ JMS bindings – WebSphere MQ JMS bindings allow interoperability with WebSphere MQ based JMS providers.

Chapter 14. Integrating WSRR with WebSphere ESB

517

– You might have WebSphere MQ JMS bindings if you want to use WebSphere MQ as a JMS provider. – The JMS Message class and its five subtypes (Text, Bytes, Object, Stream, and Map) are automatically supported. WebSphere MQ bindings – WebSphere MQ bindings allow interoperability with WebSphere MQ. – You might have WebSphere MQ bindings if you want to communicate with native WebSphere MQ applications. – You can use WebSphere MQ bindings only with remote queue managers via a WebSphere MQ client connection; you cannot use them with local queue managers. WebSphere Adapter bindings – WebSphere Adapter bindings enable interaction with Enterprise Information Systems (EIS). Finally, data types (business objects) and interfaces can be defined at the module level, but they can also be defined and referenced in libraries in order to centralize them and to be able to reuse those artefacts.

14.3.3 Mediation flow components
Inside a mediation module there can be one mediation flow component. Mediation flow components offer one or more interfaces and use one or more partner references. Both get resolved, assigning them to exports or imports via wires, as shown in Figure 14-4 on page 519. In addition to the mediation flow component inside a mediation module, one or more Java components can be created using custom mediation implementations.

14.3.4 Mediation flows
Mediation flows (Figure 14-4 on page 519) contain the high-level mediation logic. In WebSphere Enterprise Service Bus, the processing of requests is separated from processing of responses. Therefore, we distinguish between a request flow and a response flow. In both directions, logic can be added or modifications can be applied.

518

WebSphere Service Registry and Repository Handbook

Figure 14-4 Mediation flows

Mediation flows consist of a sequence of processing steps that are executed when an input message is received. A request flow begins with a single input for the source operation and can have multiple callouts. If a message is to be returned to the source directly after processing, it can be wired to an input response in the request flow. If fault messages are defined in the source operation, an input fault is also created. A response flow begins with one or more callout responses and ends with a single input response (and optionally a callout fault). In terms of the actual data, WESB introduces the service message object (SMO). SMO is a special kind of a service data object that represents the content of an application message as it passes through a mediation flow component. As well as the payload in the body, it contains context and header information, which can be accessed and acted upon inside the mediation flows.

Chapter 14. Integrating WSRR with WebSphere ESB

519

14.3.5 Mediation primitives
Mediation primitives (Figure 14-5) are the smallest building blocks in WebSphere Enterprise Service Bus. They are wired and configured inside mediation flows. They let you change the format, content, or target of service requests; log messages; do database lookups; and so forth.

Figure 14-5 Mediation primitives (in the complete overview)

WebSphere Integration Developer and WebSphere Enterprise Service Bus V6.0.2 provide the following standard mediation primitives: The Message Logger primitive logs a copy of a message to a database for future retrieval or audit. The integration developer can customize the primitive by, for example, naming the database. The Database Lookup primitive retrieves values from a database to add them to a message. The Message Filter primitive compares the content of a message to expressions configured by the developer, and routes the message to the next mediation primitive based on the result. The XSL Transformations (XSLT) primitive transforms messages according to transformations defined by an XSL style sheet.

520

WebSphere Service Registry and Repository Handbook

The Fail primitive throws an exception and terminates the path through the mediation flow. The Stop primitive silently terminates the path through the mediation flow. The Custom Mediation primitive allows the user to implement their own mediate method using Java. The Custom mediation, like the other primitives, receives a Service Message Object and returns a Service Message Object. It can be used to perform tasks that cannot be performed by using the other mediation primitives. The Endpoint Lookup primitive dynamically routes the messages to appropriate service endpoints. The primitive searches for service information in WebSphere Service Registry and Repository. See section 14.5, “Endpoint Lookup mediation primitive” on page 525 for more details. The Event Emitter Mediation primitive emits business events from within a mediation flow, if an event occurs. The Message Element Setter primitive can be used to set the contents of messages. Mediation primitives have three types of terminal:

In terminal: All mediation primitives have an in terminal that can be wired to accept a message.

Out terminal: Most mediation primitives have one or more out terminals that can be wired to propagate a message (exceptions are the stop and the fail primitive). Fail terminal: If an exception occurs during the processing of an input message, then the fail terminal propagates the original message, together with any exception information.

14.4 Related technologies
This section explores some of the accompanying features of WebSphere Enterprise Service Bus in more detail.

14.4.1 Service message objects
Messages can come from a variety of sources, so the payload has to be able to carry a number of different types of messages. Mediation primitives need to be able to operate on these messages, and service message objects (SMOs) represents the common representation that is needed.

Chapter 14. Integrating WSRR with WebSphere ESB

521

The types of messages that are handled by WebSphere Enterprise Service Bus include: SDO data object SDO data graph SCA component invocation message (request, reply or exception) SOAP message JMS message The SMO model is extensible so it can support other message types in the future, such as COBOL structures. SMO extends SDO with additional information to support the needs of a messaging subsystem.

SMO structure
All SMOs have the same basic structure, defined by an XML schema. An SMO has three major sections: The body contains the application data (payload) of the message, particularly the input or output values of an operation. The headers contain the information relevant to the protocol used to send the message. The context covers the data specific to the logic of a flow or failure information. Figure 14-6 on page 523 shows a sample SMO when calling the ItemPrice service which is used later in this chapter.

522

WebSphere Service Registry and Repository Handbook

Figure 14-6 Sample SMO

Data section
The data that is carried in the SMO body is the operation that is defined by the interface specification and the inputs/outputs/faults that are specified in the message parts set in the business object definition (Figure 14-7 on page 524).

Chapter 14. Integrating WSRR with WebSphere ESB

523

Figure 14-7 Content of the SMO body

Context section
The context includes the correlation and transient context information. Correlation is used to maintain data across a request/response flow, while transient maintains data only in one direction. Both of these contexts are used to pass application data between mediation primitives. They are described as business objects, which contain XML schema that are described data objects and that are specified on the mediation flows input node properties. The context includes the failInfo, which is added to the SMO when a fault terminal flow is used. The information that is provided includes the failureString (nature of the failure), origin (mediation primitive in which the failure occurred), invocationPath (the flow taken through the mediation) and predecessor (previous failure). It also includes primitiveContext, which are used by primitives. EndpointLookup primitive uses primitiveContext to adds zero or more EndpointLookupContext to store service endpoints. See Figure 14-6 on page 523. In the future more primitives will use primitiveContext to store context information.

Header section
The header section of a SMO contains the following supplemental information: SMOHeader: information about the message (message identifier, SMO version) JMSHeader: used when there is a JMS import or export binding SOAPHeader: used when there is a Web services import or export binding SOAPFaultInfo: contains information about SOAP faults Properties[]: arbitrary list of name value pairs (for example JMS user properties)

524

WebSphere Service Registry and Repository Handbook

SMO manipulation
During the execution of mediation flows the active mediation primitives can access and manipulate the SMO. There are three different ways to access SMOs: XPath V1.0 expressions Many mediation primitives have a property called Root that contains an XPath 1.0 expression. The XPath expression represents the root of the current mediation. Typically, you can specify: /, /body, /headers, or your own XPath expression. / refers to the complete SMO, /body refers to the body section of the SMO, /headers refers to the headers of the SMO. If you specify your own XPath expression then the part of the SMO you specify is processed. XSL stylesheets Used by the XSLT mediation primitive and are the common way to modify the SMO type within a flow. It can also be used to modify the SMO without changing the type (using XSLT function and logical processing with XSL choose statements). Java code Using the Custom Mediation primitive, you can access the SMO either using the generic DataObject APIs (commonj.sdo.DataObject, which is loosely typed) or the SMO APIs (com.ibm.websphere.sibx.smobo, strongly typed).

14.5 Endpoint Lookup mediation primitive
The Endpoint Lookup mediation primitive is used to dynamically route messages to appropriate service endpoints. The Endpoint Lookup searches for service information in WebSphere Service Registry and Repository (WSRR). The Endpoint Lookup mediation primitive lets you retrieve service endpoint information from a WSRR registry that can be local or remote. The service endpoint information can relate directly to Web services or to Service Component Architecture (SCA) module exports. In order to use the Endpoint Lookup mediation primitive you might need to add service endpoint information to your WSRR registry. If you want to extract service endpoint information about Web services, then your WSRR registry must contain the appropriate WSDL documents or SCA modules that contain exports using Web service bindings. If you want to extract service endpoint information about exports that use the default SCA binding, then your WSRR registry must contain the appropriate SCA modules.

Chapter 14. Integrating WSRR with WebSphere ESB

525

The Endpoint Lookup mediation primitive lets you retrieve service endpoint information that relates to the following: Web services using SOAP/HTTP. Web services using SOAP/JMS. Mediation module exports with Web service bindings, using SOAP/HTTP. Mediation module exports with Web service bindings, using SOAP/JMS. Mediation module exports with the default SCA binding. When the Endpoint Lookup mediation primitive receives a message it sends a search query to the registry. The search query is constructed using the Endpoint Lookup properties that you specify and the query might return nothing, or might return one or more service endpoints. You can choose whether to be informed of all endpoints that match your query, or just one endpoint that matches your query. The Endpoint Lookup mediation primitive has one input terminal and three output terminals. The input terminal is wired to accept a message and the output terminals are wired to propagate a message. One of the output terminals is for failure output. If an exception occurs during the processing of the input message, then the fail terminal propagates the original message, together with any exception information. If service endpoints are retrieved from the registry then the out terminal propagates the original Service Message Object (SMO) modified by the service endpoint information. If no services are retrieved from the registry then the noMatch terminal propagates an unmodified message. The Endpoint Lookup primitive as represented in the Mediation Flow Editor in WebSphere Integration Developer is shown in Figure 14-8.

Figure 14-8 Endpoint Lookup primitive

Note: In order for the runtime to implement dynamic routing on a request, you must set the Use dynamic endpoint property in the callout node. Optionally, you can specify a default endpoint that the runtime uses if it cannot find a dynamic endpoint. You specify a default endpoint by wiring an import that has the default service selected.

526

WebSphere Service Registry and Repository Handbook

14.5.1 Match policy
Figure 14-9 shows how to change the Match Policy for the primitive.

Figure 14-9 Endpoint Lookup primitive properties

If you specify an endpoint Match Policy of Return one matching endpoint, and your registry query returns matches, then the dynamic callout address in the SMO header is updated with one service address and the SMO context is updated with registry information relating to that service. If you specify an endpoint Match Policy of Return all matching endpoints, and your registry query returns matches, then the SMO context is updated with registry information relating to all services returned by the registry. The dynamic callout address in the SMO header is not updated. Therefore, you need to post-process the SMO to select a service endpoint. The SMO context contains a primitiveContext element that is used for storing state information. The Endpoint Lookup mediation primitive uses an element within the primitiveContext, called EndpointLookupContext, to store the results of WSRR queries. A number of service endpoints can be stored within the SMO context. If you specify a Match Policy of Return one matching endpoint then the Endpoint Lookup mediation primitive updates the SMO header at /headers/SMOHeader/Target/address. If you specify a Match Policy of Return all matching endpoints then you must wire the Endpoint Lookup mediation primitive to another mediation primitive that decides which endpoint to use, and moves endpoint information from the SMO context to /headers/SMOHeader/Target/address.

Chapter 14. Integrating WSRR with WebSphere ESB

527

14.5.2 Usage
You can use the Endpoint Lookup mediation primitive to dynamically route messages based upon customer classification. For example, you might want messages for customers of type A routed to URL X, and messages for customers of type B routed to URL Y. If you set up your registry to key URLs against customer types, then you can dynamically route customer requests according to customer type. You can use the Endpoint Lookup mediation primitive, together with other mediation primitives, to add security to dynamic routing. For example, you could use the Endpoint Lookup, Message Filter and XSLT mediation primitives to check whether an endpoint was external or internal, and remove any internal information from public messages. To do this you might wire the matching output terminal of the Endpoint Lookup mediation primitive to the input terminal of the Message Filter mediation primitive. You could then use the Message Filter mediation primitive to check whether the URL was internal or external, and route external messages to the XSLT mediation primitive: wire one of the Message Filter output terminals to the XSLT mediation primitive. Lastly, you could use the XSLT mediation primitive to remove private information from messages.

14.5.3 Properties
The Endpoint Lookup primitive fetches service metadata from WSRR based on the properties specified in the primitive. There are advanced properties which let you specify Classification and User Properties. This enables you to search for objects that match a particular classification. Also, you can search the registry for services that are annotated with user defined properties. See Figure 14-10 on page 529.

528

WebSphere Service Registry and Repository Handbook

Figure 14-10 Endpoint Lookup primitive advanced properties

The properties of the Endpoint Lookup primitive are described in Table 14-2 and Table 14-3 on page 531. Refer to Figure 14-9 on page 527 and Figure 14-10 for screen captures of the Endpoint Lookup primitive property pages in WebSphere Integration Developer.
Table 14-2 Endpoint Lookup mediation primitive properties Property Registry Name Description This identifies the WSRR definition to be used by Endpoint Lookup mediation primitive. A WSRR definition is created using the server administrative console and provides connection information for a WSRR instance. At least one WSRR definition needs to exist on the server that your mediation module is installed to. If the Registry Name is absent then the default WSRR definition is used. For details on how to configure WSRR Definitions in WESB, see 14.6, “Managing access from WESB to WSRR” on page 536.

Chapter 14. Integrating WSRR with WebSphere ESB

529

Property Match Policy

Description If the registry has more than one service matching your query, then the Match Policy determines how many service endpoints should be added to the message. Specify Return one matching endpoint to add only one match, and specify Return all matching endpoints to add all matches. If you choose a Match Policy of Return one matching endpoint then the Endpoint Lookup mediation primitive selects the first service returned from the registry. If you choose a Match Policy of Return all matching endpoints then, typically, you would wire the match output terminal of the Endpoint Lookup to another mediation primitive. This is because if multiple endpoints are returned, the SMO context is updated but the dynamic callout address in the SMO header is not updated. Therefore, you need to post-process the SMO to select a service endpoint. Search the registry for services that implement a particular portType, the name of which is specified by PortType Name. Search the registry for services that implement a particular portType, the namespace of which is specified by PortType Namespace. The PortType Namespace can be specified in any valid namespace format. For example, URI or URN. Search the registry for services that implement a particular portType, the version of which is specified by PortType Version. Search the registry for services that are annotated with user defined properties. Name The name of the user defined property. Type The type of the user defined property. If the type is String then what you specify as the Value is used as a literal, in the search query. If the type is XPath then what you specify as the Value must be an XPath expression. The XPath expression must resolve to a unique leaf node in the inbound SMO. The value of the leaf node is used in the search query. Value The value of the user defined property. This can be either a literal value or an XPath expression, depending upon the Type property.

PortType Name PortType Namespace

PortType Version

User Properties

530

WebSphere Service Registry and Repository Handbook

Property Classification

Description Search for objects that match a particular classification. The WSRR classifies objects using the ontology classification system (OWL), in which each classifier is a class and has a URI. OWL implements a simple hierarchical system. For example, a bank account could start with the following details: Account o Identifier o Name - First name - Second name o Address - First line of Address - Second line of Address Specifying a classification of Address matches any object classified as Address, First line of address or Second line of address.

Table 14-3 describes valid and default values for the properties of the Endpoint Lookup primitive.
Table 14-3 Endpoint Lookup mediation primitive properties valid values and defaults Property Registry Name Match Policy Valid Values String String: Return one matching endpoint or Return all matching endpoint String String String String String or XPath Dependent on Type List of URIs Default The default registry One

PortType Name PortType Namespace PortType Version User Properties - Name User Properties - Type User Properties - Value Classification

Chapter 14. Integrating WSRR with WebSphere ESB

531

14.5.4 Considerations
Consider the following when using the Endpoint Lookup mediation primitive: If the Use dynamic endpoint property is not set in the callout node, then the runtime will not use the dynamic endpoint in /headers/SMOHeader/Target/address. In this case, the runtime uses the default endpoint if there is one, or throws an error. It is valid to specify no properties for an Endpoint Lookup mediation primitive, other than the Match Policy. In this case, the default registry will be queried for all applicable services. You can use WSDL Web services loaded into the WSRR registry as a WSDL file, or as a mediation module with an export using the Web service binding. In either case, the Endpoint Lookup mediation primitive will search the registry for WSDL Port objects that implement a PortType described by the PortType properties. Any Classification or User properties specified on the Endpoint Lookup need to be defined on the WSDL Port object within the registry. In the case of mediation modules that include an export using the default SCA binding, the Endpoint Lookup mediation primitive searches the registry for SCA Export objects that implement a PortType described by the PortType properties. Any Classification or User properties specified on the Endpoint Lookup need to be defined on the SCA Export object within the registry. All PortType, Classification or User properties specified for an Endpoint Lookup mediation primitive result in a query that combines all of these properties using a logical AND. If you want to use Classification URIs that include white space characters, the correct URL encoding should be used. For example, a single character space should be represented as %20. White space characters provided in any of the Endpoint Lookup mediation primitive properties will be treated as literal characters. They are not removed by the Endpoint Lookup mediation primitive when querying the registry. For example, if you specify a Classification property and the expected results are not returned from a query, ensure there is no white space before or after the Classification URI.

14.5.5 SOAP/HTTP example
The URI format in the case of an export with a Web service binding, is as follows: http://://sca/

532

WebSphere Service Registry and Repository Handbook

The URI format in the general Web service case, (when a Web service is not implemented by an export with a Web service binding), is as follows: http://:/ Consider the example WSDL in Example 14-1.
Example 14-1 SOAP/HTTP example WSDL

Chapter 14. Integrating WSRR with WebSphere ESB

533

The port declaration contains a soap:address location of http://testhost:9080/RegistryWeb/sca/SOAP_HTTPExport. This indicates that it is an export with a Web service binding. To enable dynamic routing, update the /headers/SMOHeader/Target/address field in the message with the location value in the soap:address element.

14.5.6 SOAP/JMS example
The URI format in the case of an export with a Web service binding, is as follows: jms:/queue?destination=jms/WSjmsExport&connectionFactory=jms/WSjmsExpor tQCF&targetService=WSjmsExport_ServiceBJmsPort The URI format in the general Web service case, (when a Web service is not implemented by an export with a Web service binding), is as follows: jms:/queue?destination=&connectionFactory=&targetser vice= Consider the example WSDL in Example 14-2.
Example 14-2 SOAP/JMS example WSDL

534

WebSphere Service Registry and Repository Handbook

14.5.7 SCA default binding example
The URI format in the case of an export with the default SCA binding, is as follows: sca:/// For services that use the SCA binding, the URI is never physically present in the resources that define the service. If using an Endpoint Lookup mediation primitive to retrieve endpoint information about services using the SCA binding from a service registry, the Endpoint Lookup will derive this URI from the information returned by the registry. Consider the example SCDL in Example 14-3.
Example 14-3 Example SCDL

cd C:\ITSO\WSRR\ITCAMforSOA-WSRR_DLA\bin C:\ITSO\WSRR\ITCAMforSOA-WSRR_DLA\bin>WSRR_DLA.bat -r -d The last command line: Forces the creation of a refresh book (-r option)

Chapter 15. Integrating WSRR with ITCAM for SOA

715

Does not perform post-discovery file transfer (-d option) Example 15-8 describes the output which is displayed in the console and is also captured in the WSRRDLALog.log log file located in [DLA_INSTALL_DIR]/logs.
Example 15-8 WSRR DLA execution log C:\ITSO\WSRR\ITCAMforSOA-WSRR_DLA\bin>WSRR_DLA.bat -r -d 2006-12-12 20:22:02.391-05:00 [main] KD4SR0017I The discovery library adapter is starting its discovery process. 2006-12-12 20:22:09.047-05:00 [P=922438:O=0:CT] KD4SR0010I The discovery library adapter book: WSRRv600.ITSO-WSRR.itso.ral.ibm.com.2006-12-13T01.22.06.219Z.refresh.xml was generated and stored into the following directory: ../staging\. 2006-12-12 20:22:09.078-05:00 [P=922438:O=0:CT] KD4SR0018I The discovery library adapter is exiting its discovery process.

The resulting WSRR DLA book should appear in the [DLA_INSTALL_DIR]/staging directory with a refresh.xml extension: WSRRv600.ITSO-WSRR.itso.ral.ibm.com.2006-12-13T01.22.06.219Z.refresh.xml Note: Depending on your configuration and your context the name of the WSRR DLA book is likely to be different. While the format of the resulting DLA book is rather verbose, it is still easy to verify that only the services that were in the Manage state were discovered, that is ItemPriceService and ItemPriceDiscountedService. You can perform a quick search on these two names to make sure you find the following occurrences in the xml file. There should be no mention of the ItemPriceEnquiryService which was in the Assemble state. This example stresses the importance of service classification to be able to handle a large number of services.

Transferring WSRR DLA book to Discovery Library File Store
Once created the WSRR DLA book needs to be transferred to the Discovery Library File Store.

716

WebSphere Service Registry and Repository Handbook

Transfer instructions
Transfer of DLA books can be automatically performed by the DLA scripts when configuration values have been specified in the configuration files. See “Editing DLA_FileTransfer.properties file” on page 711.

Working Example
In our example, we do not use the automatic book transfer feature but rather manually copy the WSRR DLA book to the appropriate directory. We use the following directory as the DLFS on the itso-itcam machine: C:\ITSO\WSRR\DLA\books

Loading WSRR DLA book into the TCORE database
The WSRR DLA book stored in the Discovery Library File Store needs to be loaded into the TCORE database to enrich the Common Object Repository with additional information describing the services registered in WSRR. This is done using the Bulk Load Program.

Bulk Load Program
The bulk load program loads Identity Markup Language (IDML) XML files called books from the Discovery Library File Store into the Tivoli Common Object Repository. It is useful for loading large numbers of managed elements and relationship data into the Tivoli Common Object Repository. You can use operating system utilities such as cron on Linux or AIX to periodically run the bulk load program to load new files as they appear in the shared directory, or you can run the bulk load program manually as new files become available.

Running the Bulk Load Program
All information about how to run the Bulk Load Program is included in the following document: Tivoli Composite Application Manager for SOA - Version 6.1.0 - Installation and User’s Guide, GC32-9492-01. In particular, refer to The Bulk Load Program section in Chapter 12. Using Discovery Library Adapters.

Working example
Run the Bulk Load Program as follows: cd C:\IBM\ITM\CNPS\Products\KD4\tcore\bin The location of the Bulk Load Program can vary depending on your installation. loadidml -f C:\ITSO\WSRR\DLA\books\

Chapter 15. Integrating WSRR with ITCAM for SOA

717

In our case is: WSRRv600.ITSO-WSRR.itso.ral.ibm.com.2006-12-13T01.22.06.219Z.refresh.xml Example 15-9 describes the execution and the result of the Bulk Load Program after loading the WSRR DLA book previously extracted.
Example 15-9 Bulk Load Program (working example)

C:\IBM\ITM\CNPS\Products\KD4\tcore\bin>loadidml -f C:\ITSO\WSRR\DLA\books\WSRRv6 00.ITSO-WSRR.itso.ral.ibm.com.2006-12-13T01.22.06.219Z.refresh.xml C:\IBM\ITM\CNPS\Products\KD4\tcore\bin>call setenv.bat Bulk Load Program starting. Bulk Load Program running. Bulk Load Program running. Bulk Load Program succeeded. Return code is: 0 0 Bulk Load Program ending. At this point the TCORE model should have been updated to reflect both the services as they are observed by ITCAM for SOA and the services registered in WSRR. The situation should be the one depicted in Figure 15-34 on page 719.

718

WebSphere Service Registry and Repository Handbook

Observed Services (ITCAM for SOA) ItemPriceService ItemPriceDiscountedService

Registered Services (WSRR) ItemPriceService ItemPriceDiscountedService ItemPriceEnquiryService

ITCAM for SOA DLA Book (Observed Services)

WSRR DLA Book (Registered Services in Deploy or Manage state )

ItemPriceService ItemPriceDiscountedService

ItemPriceService ItemPriceDiscountedService

TCORE / CCMDB ItemPriceService ItemPriceDiscountedService

Figure 15-34 Observed and registered services in TCORE: working example

15.8.10 Reconciling service information using ITCAM for SOA
To explore the managed resources and the topology of the management domain, and perform visual reconciliation between observed services and registered services, we use the Tivoli Enterprise Portal.

Accessing the Services Management workspace
We use the Services Management workspace which was described in “Services Management workspace” on page 663. As for any other workspace, we access this workspace using the Navigator View and selecting either the ITCAM for SOA option in the combo box or the ITCAM for SOA tab if the Services Management workspace has been opened previously. Figure 15-35 on page 720 illustrates this.

Chapter 15. Integrating WSRR with ITCAM for SOA

719

Figure 15-35 Accessing Services Management workspace using the Navigator View in TEP

Note: The Services Management workspace is not enabled by default on the ITCAM for SOA installation. To enable it, refer to the product documentation.

Exploring the Services Overview table view
The Services Overview table view is the main view of the Services Management workspace, and is displayed by default when opening that workspace as shown on Figure 15-36.

Figure 15-36 Services Overview table view in TEP

720

WebSphere Service Registry and Repository Handbook

The Services Overview table view allows us to reconcile service information extracted from the different sources (ITCAM for SOA and WSRR) by displaying the following information for the two discovered services, namely ItemPriceService and ItemPriceDiscountedService: The name of the Service Ports In that case the two services have different ports: ItemPrice (for ItemPriceService) and ItemPriceDiscounted (for ItemPriceDiscountedService) The name of the Operations Both services sharing the same PortType, they have the same single getPrice operation. The name of the Services Both services appear here: ItemPriceService and ItemPriceDiscountedService. The name of the Application Servers where the Service Ports are deployed Both services are deployed onto the same instance of WebSphere Application Server which is called server1. The IP address of the Computer System where these services are running As mentioned above, both services are running on the same machine. The observation status of the Service Ports Both services are currently monitored by ITCAM for SOA, as represented by the Observed checked box. The registration status of the Service Ports Both services are currently registered in WSRR, as represented by the Registered checked box. Note: As mentioned in “Reconciliation of observed and registered services” on page 664, there might be cases where the observation and registration status differ. Our working example does not illustrate one of these situations but rather focusses on one simple case, obviously without claiming to closely reflect a complete real-life SOA management scenario.

Exploring the Service Details view
We access the Service Details view by either double-clicking on of the row in the Services Overview table view or by selecting one row, right-clicking to display the contextual menu, and selecting View Service Details.

Chapter 15. Integrating WSRR with ITCAM for SOA

721

Figure 15-37 and Figure 15-38 on page 723 illustrate the Service Details views associated respectively with ItemPriceService and ItemPriceDiscountedService.

Figure 15-37 Service Details view: ItemPriceService

722

WebSphere Service Registry and Repository Handbook

Figure 15-38 Service Details view: ItemPriceDiscountedService

These visual representations of the service topology are built from the information stored in the Common Object Repository describing each of these services and related resources: Services: ItemPriceService and ItemPriceDiscountedService are represented as bells. Service Ports: ItemPrice and ItemPriceDiscounted are represented as bells linked to gearings. Operation: the single getPrice operation provided by both services is represented as a gearing. Server: both services are running on the same server called server1. While our example is pretty straightforward, more complex topologies would take advantage of this visual representation mode to provide an immediate understanding of the relationships among the different resources of the SOA. One can obtain more information either using the hover help or the table view. Hover help is triggered by hovering the mouse for some time over the selected element as illustrated in Figure 15-39 on page 724.

Chapter 15. Integrating WSRR with ITCAM for SOA

723

Figure 15-39 Hover help in Service Details view

Switching between topology view and table view in the Service Details view is done using either the dedicated buttons in the toolbar or the Topology → View as Table/View as Topology items in the contextual menu. Figure 15-40 illustrates the Service Details view of ItemPriceService displayed in a table view.

Figure 15-40 Table view of ItemPriceService Service Details

The table view provides more information about all resources linked to a given service than the corresponding topology view, for example: Name of the resource Type of the resource Namespace for Operation, Service and Service Port resources Associated PortType for Operation and Service Port resources IP address of the hosting Computer System for Server resources Relationships between the different resources Note: Additional attributes for each resource can be displayed or hidden using the filtering mechanism provided by the table view.

724

WebSphere Service Registry and Repository Handbook

Exploring the Metadata view
Provided the necessary information (that is, WSDL and XSD documents) has been discovered in WSRR and imported into the Common Object Model during the service discovery phase, a Metadata view is available on the following type or resources: Service Service Port Operation Accessing the Metadata view is done using the contextual menu on the desired resource as illustrated in Figure 15-41.

Figure 15-41 Accessing Metadata view in TEP

When accessing the Metadata view for the ItemPriceService, we are displayed a selection dialog to choose the metadata documents we want to view. This process is illustrated in Figure 15-42 on page 726.

Chapter 15. Integrating WSRR with ITCAM for SOA

725

Figure 15-42 Selecting metadata documents to display for ItemPriceService

This process provide support for multiple metadata documents related to a given resource to be displayed in TEP. In our example above, ItemPriceService has two related metadata documents: ItemPricePortType.wsdl: this is the interface WSDL, where PortType, Messages and Schemas are defined. ItemPrice.wsdl: this is the implementation WSDL for the ItemPriceService, which references the ItemPricePortType WSDL document. Figure 15-43 on page 727 illustrates the display of ItemPricePortType.wsdl metadata document for ItemPriceService.

726

WebSphere Service Registry and Repository Handbook

Figure 15-43 ItemPricePortType.wsdl metadata document for ItemPriceService

15.9 Forwarding service status information - working example
In the previous part of the scenario we have reconciled the services observed by ITCAM for SOA with the ones registered in WSRR. This part of the scenario describes a working example where we use the situation and event mechanisms provided by ITCAM for SOA to forward operational information to WSRR. Refer to 15.7, “Service status information

Chapter 15. Integrating WSRR with ITCAM for SOA

727

forwarding” on page 677 for more information of the key aspects of this integration.

15.9.1 Understanding ITCAM for SOA Event Handler
ITCAM for SOA Event Handler was introduced in “Capture and processing of situation events” on page 689. This section provides more information about this component. Figure 15-44 describes a high level break-down of ITCAM for SOA Event Handler.
ITCAMListener.ear Event Event Adapter
Properties

Integration Logic

WSRR

Configuration File

Editor for Configuration File

Metadata Repository

Web Browser

Figure 15-44 ITCAM for SOA Event Handler

Events sent by ITCAM for SOA using the Event Integration Facility or EIF (see “Propagation of situation events” on page 687) are captured by the Event Adapter which adapts the content of the event to the internal data model, including the properties of the event. The adapted event is passed to the Integration Logic which processes the event received and updates the content of the corresponding elements in WSRR using the Web Services API.

728

WebSphere Service Registry and Repository Handbook

The processing of the events, the update of corresponding properties in WSRR, the configuration of the Event Adapter and the connectivity to WSRR are governed by an internal XML configuration file. The manipulation of the configuration file is performed using a dedicated Editor provided by the Event Handler package. The Editor takes the form of a Web console which is packaged with the Event Handler and is deployed at the same time. The Event Handler is packaged as an EAR file and must be deployed on a WebSphere Application Server.

15.9.2 Installing ITCAM for SOA Event Handler
This section describes the installation procedure of ITCAM for SOA Event Handler for WSRR, also referred to as ITCAM for SOA Event Handler.

Installation prerequisites
The following are prerequisites for the ITCAM for SOA Event Handler: IBM WebSphere Application Server V6.0.2 and Fix Pack 11 or later. This can be the same application server to which the registry is installed. IBM WebSphere Service Registry and Repository 6.0.0.1 installed and configured. IBM Tivoli Monitoring V6.1 Fixpack 4 IBM Tivoli Composite Application Manager for SOA V6.1 Tivoli Enterprise Console V3.9 (optional) ITCAM for SOA Event Handler is packaged as part of the WSRR 6.0.0.1 ITCAM for SOA Event Handler SupportPac. This SupportPac is now available as a archive file for customer download at the following URL: http://www.ibm.com/support/docview.wss?rs=171&uid=swg24014240&loc=en _US&cs=utf-8&lang=en

Installation instructions
1. For Windows download sa04.zip to a temporary location. For Linux or Unix download sa04.tgz to a temporary location. 2. Extract ITCAMListener.ear from the downloaded file to a temporary location. 3. Using the WebSphere Application Server administration console or command line wsadmin tool, deploy the ear to the chosen installation of WebSphere Application Server.

Chapter 15. Integrating WSRR with ITCAM for SOA

729

For more information about the installation of an Enterprise Application, refer to the WebSphere Application Server InfoCenter. Important: If installing to an instance of WebSphere Application Server other than that with WebSphere Service Registry and Repository installed, two client jars are required: ServiceRegistryClient.jar (from the registry’s default installation directory) sdo-int.jar (from [WAS_HOME]/classes after having run the WSRR installall script) Both client libraries must be copied to the [WAS_HOME]/classes directory on the server where the Event Handler is intended to reside.

Working example
In our example we install the Event Handler on the same instance of WebSphere Application Server that already hosts WSRR. Hence we do not need to copy the extra client jars to that instance. Installing the ITCAMListener.ear file as a new Enterprise Application is performed using the administration console. Start the application. Figure 15-45 shows the result of the installation in WebSphere Application Server administration console after application has been started.

Figure 15-45 ITCAM for SOA Event Handler installed as an Enterprise Application in WebSphere Application Server administration console

730

WebSphere Service Registry and Repository Handbook

15.9.3 Configuring ITCAM for SOA Event Handler
This section describes the configuration procedure of ITCAM for SOA Event Handler for WSRR.

Configuration instructions
Configuration of the ITCAM for SOA Event Handler is performed via a Web configuration console. The URL for this is: http://:/ITCAMWeb/admin Figure 15-46 illustrates the Web configuration console provided by ITCAM for SOA Event Handler.

Figure 15-46 ITCAM for SOA Event Handler Web configuration console (Configuration page)

The default page is the Configuration page.

Chapter 15. Integrating WSRR with ITCAM for SOA

731

From this page the registry which is to be updated by the Event Handler is specified, along with any required security information and logging information. On the left-hand side is a navigation pane with links to the State page, where the Event Handler is stopped and started, and the EventMapping page where the incoming events that are to be mapped to custom properties in the registry are specified. The Configuration link points to the Configuration page. Pressing Submit saves the configuration and pressing Refresh reverts the configuration page back to the currently saved configuration. Figure 15-47 illustrates the State page of the ITCAM for SOA Event Handler configuration console.

Figure 15-47 ITCAM for SOA Event Handler Web configuration console (State page)

Figure 15-48 on page 733 illustrates the EventMapping page of the ITCAM for SOA Event Handler configuration console.

732

WebSphere Service Registry and Repository Handbook

Figure 15-48 ITCAM for SOA Event Handler Web configuration console (EventMapping page)

The following sections describe the various aspects of the Event Handler that require configuration. These configuration points are all accessed using the Web configuration editor and the navigation pane located of the left part of the screen.

ITCAMListener (Configuration page)
Port is the TCP/IP port that the Event Handler listens on for events. It should be left as 1111 unless there in a port clash with an existing service on the server on which the Event Handler is installed. IBM Tivoli Monitoring or the Tivoli Enterprise Console must also be configured to use this same port number. See the sections “Configuring IBM Tivoli Monitoring for Event Handler” on page 746 and “Configuring IBM Tivoli Enterprise Console for Event Handler” on page 752 for more details.

WSRRLocation (Configuration page)
Endpoint is the Web services endpoint of the WebSphere Service Registry and Repository which the Event Handler updates.

Chapter 15. Integrating WSRR with ITCAM for SOA

733

Assuming security is off for the server where WSRR instance is running, then the endpoint should be: http://:/WSRRCoreSDO/services/WSRRCoreSDOPort For example: http://myserver:9080/WSRRCoreSDO/services/WSRRCoreSDOPort If security is enabled for the server where WSRR instance is running, then the endpoint should be: https://:/WSRRCoreSDO/services/WSRRCoreSDOPort For example: https://myserver:9443/WSRRCoreSDO/services/WSRRCoreSDOPort UID and PWD refer to the username and password required to log in to WebSphere Service Registry and Repository. These are only needed when security is enabled, otherwise leave blank.

HTTPS (Configuration page)
If security is not enabled for the server where WSRR instance is running, leave this check box unchecked and continue to the next section. If security is enabled, check this box and specify the locations and passwords of the trust store and key store. Find more information in the WebSphere Application Server V6.0 Information Center.

EIFLogger (Configuration page)
Logging and tracing parameters for the Event Integration Facility (EIF) used by the Event Handler are specified in this section. The file where the logging is saved is specified as LogFileName, and the tracing file is specified as TraceFileName. They are in the usual format for the operating system. LogLevel and TraceLevel specify the level of logging (or tracing). Use the default values unless otherwise instructed by IBM support personnel. The Event Handler’s traces are specified in the WebSphere Application Server Admin Console. See the Information Center for more details. The Event Handler’s log messages are written to the application server’s SystemOut.log file.

734

WebSphere Service Registry and Repository Handbook

EventMap (EventMapping page)
The EventMap defines how the Event Handler processes the situation events received from ITCAM for SOA, and how these events are turned into modifications on the service properties managed by WSRR. The EventMap configuration is accessed by following the EventMapping link on the left-hand side of the page. Here events of interest are identified for mapping to property updates in the WebSphere Service Registry and Repository. Each row in the table represents one mapping for events with a given situation name, which is also called an EventID. Each event has a status of either Y, N or P, representing, respectively: the situation is open meaning the situation event is received (Y) the situation is closed meaning the situation has been cleared (N) the situation is no longer being monitored (P) When a status=Y event of interest is received by the Event Handler, it attempts to create or update a property as specified by the Received type and value in the EventMap table, explained below. When a status=N event is received by the Event Handler, it attempts to update the property using the Cleared type and value information. A status=P event received by the Event Handler causes all properties associated with that EventID to be removed from the repository. When the Event Handler is first installed there are several event mappings preconfigured. For each mapping there are the following settings.
Table 15-10 ITCAM for SOA Event Handler: default settings for event mapping Setting EventID Explanation The name of the ITCAM for SOA situation. You can use any of following names (predefined situations) or use custom names for custom situations: Fault_610 MessageSize_610 MaxMessageSize_610 ResponseTimeCritical_610 ResponseTimeWarning_610 MaxResponseTimeCritical_610 MaxResponseTimeWarning_610 The name of the property to be created, updated or removed in the WSRR

WSRRPropertyName

Chapter 15. Integrating WSRR with ITCAM for SOA

735

Setting Compound

Explanation Appends the name of the service operation that triggered the event to the front of the property name, for example methodname.propertyname. This differentiates properties associated with different operations that share a service endpoint. The Received Type section is used for events received with a status of Y. Possible values are Property Value or Static String: A value of Property Value indicates that the WSRR property will contain the value of the event property entered in the Received Value column. See the ITCAM for SOA Event Properties section for the list of event property names that can be specified. A value of Static String indicates that the WSRR property will contain the value specified in the Received Value column. Used for ReceivedTypes of Property Value and Static String, this value is used to specify which event property of the incoming event to put in the registry property value, or the static string to put in the registry property value. See “ITCAM for SOA event properties” on page 737 for the list of event property names that can be specified for this setting when the Received Type is set to Property Value. The Cleared Type selection is used for events received with a status of N. Possible values: Removal, Property Value or Static String: A value of Removal indicates the WSRR property associated with the received event will be removed. A value of Property Value indicates the value of the WSRR property associated with the received event will be updated with the value of the event property entered in the Cleared Value column. A value of Static String indicates the value of the WSRR property associated with the received event will be updated with the value of the string entered in the Cleared Value column. Used for Cleared Types of Property Value and Static String, this value is used to specify which event property of the incoming clearing event to place in the registry property value, or the static string to place in the registry property value. Disabled when Cleared Type is Removal. See “ITCAM for SOA event properties” on page 737 for the list of event property names that can be specified for this setting when the Cleared Type is set to Property Value.

Received Type (WSRRPropertyValue)

Received Value (WSRRPropertyValue)

Cleared Type (WSRRPropertyValue)

Cleared Value (WSRRPropertyValue)

New event mappings can be introduced by pressing the create button which creates an empty row in the table. When this page is revisited the EventIDs are ordered alphabetically, so a new event map may no longer be seen at the bottom of the table. Pressing Submit saves the configuration and pressing Refresh reverts the configuration page back to the last saved configuration.

736

WebSphere Service Registry and Repository Handbook

Any ITCAM for SOA situation can be configured to write corresponding properties in WSRR. Each situation should be assigned to a unique property name. Sharing properties among situations causes unpredictable results due to the random ordering of events that clear situations. ITCAM for SOA Message Arrival events are ignored by the Event Handler as they are pure events and do not originate from the Services Inventory_610 table. Note: In addition to the WSRR property defined in the event map, the Event Handler also writes or removes correlation properties in the registry. The name of the correlation property is a concatenation of values received in the event: ------ For example: ResponseTimeCritical_610---343e64e14341cc26267585b1f84a2e8d---D4--46 7c60d6--cs-gr2qh5jaqiz-serve Its value is the name of WSRR property that is written for the received event, for example, ResponseTime. The correlation property allows the Event Handler to identify the WSRR property that needs to be changed or removed when the situation clears.

Event Handler Runtime (State page)
Once the configuration of the Event Handler has been saved it does not take effect until the Event Handler application has been [re]started. Start the Event Handler by clicking on the State link on the left-hand side of the page, then click Submit so that the Event Handler state changes to active. To restart the Event Handler application, click Submit twice: once to stop the application and again to start it. When the application server is restarted, the Event Handler and its listener will automatically be started.

ITCAM for SOA event properties
Event properties describe the information contained in the situation event that the Event Handler can use and process to update the service metadata managed by WSRR. Table 15-11 on page 738 lists (in alphabetical order) the names of the event properties in the ITCAM for SOA events generated from the Services Inventory_610 table, also called an attribute group. See “Situations and situation events for WSRR” on page 683.

Chapter 15. Integrating WSRR with ITCAM for SOA

737

Note: If you define a custom situation for the Services Inventory_610 table that the Event Handler should process, you must select the Unique_Key_U event property as the value of the Display Item selection when configuring the advanced situation options.
Table 15-11 ITCAM for SOA event properties Event property name appl_label application_server_cellName_u application_servercluster_u application_servername_u application_server_nodename_u application_serverenv Description Application specific data related with the event, if any. Name of the application server cell where the port and operation are deployed. Name of the application server cluster where the port and operation are deployed. Name of the application server where the port and operation are deployed. Node name of the application server where the port and operation are deployed. Specifies the application server environment: 1=WebSphere Application Server 2=.NET 3=WebLogic Server 4=JBoss 5=CICS 6=SAP 7=WebSphere Community Edition 8=DataPower 9=Service Component Architecture Average elapsed round trip time in milliseconds during this monitoring interval. This does not include values which were set to -1 to indicate entry requests. The average message length, in bytes, observed during this monitoring interval (including headers when possible). TCP/IP host name of the Tivoli Enterprise Monitoring Server that forwards the event. Tivoli Enterprise Monitoring Server port on which the service is listening. Number of messages observed during this monitoring interval that contain an elapsed time value.

avg_elapsed_time

avg_msg_length cms_hostname cms_port elapsed_time_msg_count

738

WebSphere Service Registry and Repository Handbook

Event property name fault_count hostname integration_type

Description Number of faults observed during this monitoring interval. Base event class attribute that contains the TCP/IP hostname of the managed system where the event originates, if available. Indicator to help Tivoli Enterprise Console performance: N for a new event, the first time the event is raised U for update event, subsequent event status changes Inclusive beginning date and time of the monitoring interval. Exclusive ending date and time of the monitoring interval. Length of the monitoring interval in minutes. Specifies the status of this monitoring interval: 1=Incomplete 2=Complete Incomplete means the end of this monitoring interval has not yet been reached. Hostname of the machine where the port and operation are deployed IP address of the machine where the port and operation are deployed Master reset indicator set for master reset events: R for Tivoli Enterprise Monitoring Server recycle master_reset S for hotstandby master_reset NULL for all other events Largest elapsed time, in milliseconds, of any message observed during this monitoring interval. Length of the largest message, in bytes, observed during this monitoring interval. Smallest elapsed time, in milliseconds, of any message observed during this monitoring interval. Length of the smallest message, in bytes, observed during this monitoring interval. Base event class attribute that contains the situation name and formula. The number of messages observed during this monitoring interval. Web Services Description Language (WSDL) operation name Namespace used to fully qualify the operation name.

interval_begin_time interval_end_time interval_length interval_status

local_hostname_u local_ipaddress_u master_reset_flag

max_elapsed_time max_msg_length min_elapsed_time min_msg_length msg msg_count operation_name_u operation_namespace_u

Chapter 15. Integrating WSRR with ITCAM for SOA

739

Event property name port_namespace_u port_number severity service_name_u situation_displayitem situation_eventdata

Description Namespace used to fully qualify the service port name. The number of the port, 0 - 65535, on which the application container being monitored is listening. -1 if unknown. Base event class attribute that contains the resolved severity. Service port name also known as the Web Services Description Language (WSDL) port name Display item of associated situation, if available. Event data attributes in key-value pair format. The event data can be truncated because the Event Integration Facility (EIF) imposes a 2k size limit. Name of the associated situation. Same value as sub_source attribute. Current status of the situation event: Y indicates the event has been opened. N indicates the event has been closed P indicates the situation has been stopped There are additional status values but the Event Handler does not take an action on those values. Timestamp of the situation event. Base event class attribute that contains "ITM" The standard deviation of all elapsed round trip times, in milliseconds, observed during this monitoring interval. Standard deviation of all message lengths, in bytes, observed during this monitoring interval. Base event class attribute that contains the origin managed system name for the associated situation. The version of this table definition. A unique hash of the service port namespace, service port name, operation namespace, operation name, and service type in this event.

situation_name situation_origin situation_status

situation_time source std_dev_elapsed_time std_dev_msg_length sub_source table_version_u unique_key_u

740

WebSphere Service Registry and Repository Handbook

Working example
In our example the Event Handler is installed on the same instance of WebSphere Application Server than WSRR. Security is turned on in this instance. To configure the ITCAM for SOA Event Handler, we use the Web configuration console using the following URL: http://itso-wsrr:9080/ITCAMWeb/admin We begin with the base configuration of the Event Handler, accessed using the Configuration link in the navigation pane on the left side. Also, the Configuration page should be displayed by default when first accessing the Event Handler Web configuration URL.

Configuration
As summarized in Table 15-12, we start by setting the configuration attributes in the Configuration page.
Table 15-12 Configuration attributes for Event Handler (working example) Section ITCAMListener WSRRLocation Attribute Port Endpoint UID PWD Https Enabled TrustStore Value 1111 https://localhost:9443/WSRRCoreSDO/services/WS RRCoreSDOPort itcam4soa itso4you yes C:\Program Files\IBM\WebSphere\AppServer\profiles\default\ect \DummyClientTrustFile.jks WebAS C:\Program Files\IBM\WebSphere\AppServer\profiles\default\ect \DummyClientKeyFile.jks WebAS

TrustStore Password KeyStore

KeyStore Password

Chapter 15. Integrating WSRR with ITCAM for SOA

741

Section EIFLogger

Attribute LogFileName LogLevel TraceFileName TraceLevel

Value C:\itso\eif\eif01.log ALL C:\itso\eif\eif01.trc ALL

Note: for our example we are using the default TrustStore and KeyStore provided by WebSphere Application Server. In a real world deployment we recommend that you generate your own cryptographic stores. Also, we set both the Log and Trace levels to ALL in order to easily assess the correct behavior of the Event Handler. For performance reasons this is obviously not a recommended setting in any real case scenarios. We click the Submit link to validate and save our changes. A confirmation screen reading The configuration file has been saved successfully should be displayed on the screen. We can proceed with the definition of the event mappings. Note: To obtain more information about the events received and processed by the Event Handler, we also turned on the corresponding WSRR logs in WebSphere Application Server: com.ibm.wsrr.*=all

EventMapping
The definition of event mappings is performed using the EventMapping page. This page is accessed via the EventMapping link on the navigation pane located on the left side. In our scenario we use the Fault_610 situation to trigger the propagation of situation events from ITCAM for SOA to WSRR and ultimately update status information. While this most probably would not be sufficient in a real life deployment, our scenario provides us with an easy way to generate faults from the deployed services by using incorrect item name (see Chapter 17, “Integrating WSRR with CICS” on page 825 for a complete description of the scenario).

742

WebSphere Service Registry and Repository Handbook

Fault_610 situation: Use the Fault_610 situation while monitoring messages in the Web services flow to alert you when a Web services fault occurs during the most recently completed monitoring interval. The situation is described by the following formula: *IF *VALUE Services_Inventory_610.Fault_Count *GT 0 *AND *VALUE Services_Inventory_610.Interval_Status *EQ Complete If a fault occurs for a service operation an increment count is set to >0, which indicates at least one SOAP fault was received in response to the message. This fault might occur for one of the following reasons: There might be an application based fault. For example, the application might not be running in the application server runtime environment. Navigate to the Faults Summary workspace and examine the summary of faults that have been reported. In the Fault Details table view, locate the fault of interest and examine the contents of the Fault String column for more information. Then take the necessary action to correct any problems with your applications. The message was rejected according to filtering criteria defined in the monitoring agent. If the applications do not appear to be the source of the problem, select the Services Management Agent node in the Navigator Physical view and examine the filter criteria defined in the Data Collector Filter Control Configuration view. These filter criteria are defined to reject messages based on a specified combination of service port name, service port namespace, operation name, operation namespace, and remote IP address. If these criteria are not defined correctly, undesired faults might be received as a result. Use the AddFltrCntrl_610 or the DelFltrCntrl_610 Take Action commands to modify your filter criteria as needed.

Chapter 15. Integrating WSRR with ITCAM for SOA

743

Note: As discussed before, the fact that ITCAM for SOA uses situation events to forward service status information to WSRR implies that you pay particular attention when defining the event mappings in the Event Handler. Effectively, events mappings and the associated situations that trigger their emission will ultimately determine the frequency of that feedback loop from ITCAM for SOA to WSRR. Depending on your exact requirements, you may want to limit the number of event mappings and situation events, change the settings of these situations, use custom situations to control this feedback more precisely. To define the adequate event mappings for our scenario, we start by deleting all default event mappings using the Delete button. Then we create a new event mapping using the Create button. Define the event mapping as described in Table 15-13.
Table 15-13 Creating event mapping (working example) Setting EventID WSRRPropertyName Compound Received Type Received Value Cleared Type Cleared Value Value Fault_610 AvgResponseTime No Property Value avg_elapsed_time Static String cleared

This event mapping supports the following scenario: Whenever the situation Fault_610 evaluates to true, meaning that the number of Web services faults exceeds a given threshold, an Open situation event is sent to the Event Handler. On the reception of this Open situation event, a property named AvgResponseTime is created (if it does not exist) or updated (if it already exists) in WSRR for the target WSDLPort object (the Service Port the operation at the origin of the situation belongs to). The property is valued with the content of the event property called avg_response_time, representing the average response time of the target operation.

744

WebSphere Service Registry and Repository Handbook

Whenever the situation Fault_610 is cleared, meaning that the number of Web services faults observed during an observation interval does not exceed a given threshold anymore, a Closed situation event is sent to the Event Handler. On the reception of this Closed situation event, the AvgResponseTime property is valued with the content of the “cleared” static string. Whenever the situation Fault_610 is no longer being monitored, a Removed situation event is sent to the Event Handler. On the reception of this Removed situation event, the AvgResponseTime property is removed from WSRR. Note: As the services used in our example provide only a single operation, we do not use the Compound feature of the Event Handler which would append the name of the operation to the name of the property in order to distinguish between different operations of the same Service Port in WSRR. Figure 15-49 illustrates the corresponding EventMapping configuration page.

Figure 15-49 Defining the event mapping (working example)

We click the Submit link to validate and save our changes. A confirmation screen reading The configuration file has been saved successfully should be displayed on the screen. Once the configuration of the Event Handler has been saved we can proceed with restarting the Event Handler.

State
Once updated, the configuration of the Event Handler does not take effect until the Event Handler application has been restarted. The State page allows us to restart the Event Handler and is accessible using the State link on the left-hand side navigation pane. The Event Handler should be running as illustrated by a green arrow beside the Module State label. We stop the Event Handler by clicking on the Submit button. The arrow mentioned above should be replaced by a red cross.

Chapter 15. Integrating WSRR with ITCAM for SOA

745

We restart the Event Handler by clicking another time on the Submit button. The red cross should be replaced by the green arrow. Now that we are all set with ITCAM for SOA Event Handler, we can configure Tivoli Monitoring infrastructure to send event to the Event Handler.

15.9.4 Configuring Tivoli Enterprise Monitoring Framework to send events to the Event Handler
If IBM Tivoli Monitoring has not been configured to forward events to an event server, you should configure IBM Tivoli Monitoring to forward ITCAM for SOA events from the Hub Tivoli Enterprise Monitoring Server directly to the Event Handler. See “Configuring IBM Tivoli Monitoring for Event Handler” on page 746. On the other hand, If IBM Tivoli Monitoring has been configured to forward events to Tivoli Enterprise Console, you should configure Tivoli Enterprise Console to send ITCAM for SOA events to the Event Handler. See “Configuring IBM Tivoli Enterprise Console for Event Handler” on page 752.

Configuring IBM Tivoli Monitoring for Event Handler
This section discusses how to configure IBM Tivoli Monitoring to send situation events to the Event Handler and provides a working example.

Configuration instructions
Note: Currently you cannot forward events directly from a Tivoli Enterprise Monitoring Server running in z/OS to the Event Handler. If you want to forward events detected for z/OS monitoring to the Event Handler, there are a couple of options to achieve that: You can run the Tivoli Enterprise Monitoring Server in zLinux and from there forward the situations to the Event Handler. You can run the Tivoli Enterprise Monitoring Server in a distributed system and then forward the events to the Event Handler. To configure IBM Tivoli Monitoring to forward events, you need to start by enabling event forwarding for the Tivoli Enterprise Monitoring Server. For Windows monitoring servers only, do the following: – Open the Manage Tivoli Enterprise Monitoring Services application. – Right-click the Tivoli Enterprise Monitoring Server and click Reconfigure.

746

WebSphere Service Registry and Repository Handbook

– On the configuration options window, select TEC Event Integration Facility. – Click OK and OK. – Complete the following fields on the TEC Server: Location and Port Number window and click OK: • • TEC Server Location: Type the host name or IP address for the server where the Event Handler is installed. TEC Port Number: Type the port number that the Event Handler is listening on. By default, the Event Handler uses port number 1111. The port number must match the port number value specified when you configured the Event Handler.

For UNIX and Linux monitoring servers, do the following on the server where Tivoli Enterprise Monitoring Server is installed: – At the command line change to the /opt/IBM/ITM/bin directory (or the directory where you installed IBM Tivoli Monitoring). – Run the following command: ./itmcmd config -S -t tems_name where tems_name is the name of your monitoring server (for example, HUB_itmdev17). – You will be prompted for the monitoring server configuration values. Enter the same values that you provided when you installed the monitoring server until you are asked about the TEC Event Integration Facility. Answer YES for this question and press Enter. Complete the following additional steps: • • At the TEC Server prompt, type the hostname or IP address of the server where the Event Handler is installed. At the TEC Port prompt, type the port number that the Event Handler is listening on. By default, the Event Handler uses port number 1111. The port number must match the port number value specified when you configured the Event Handler.

Once event forwarding has been enabled for Tivoli Enterprise Monitoring Server, you need to specify where events are to be forwarded to. In this case, you need to have Tivoli enterprise Monitoring Server forward events to the Event Handler acting as an event server. To do that, edit the Event Integration Facility (EIF) configuration file, om_tec.config, which is located in the following directory on the server where Tivoli Enterprise Monitoring Services is installed: On a Windows system: C:\IBM\ITM\cms\TECLIB

Chapter 15. Integrating WSRR with ITCAM for SOA

747

On a UNIX or Linux system: /opt/IBM/ITM/tables/host name/TECLIB where /opt/IBM/ITM and C:\IBM\ITM are the default locations where the Tivoli Enterprise Monitoring Server is installed and host name is the value supplied during the Tivoli Enterprise Monitoring Server configuration. As summarized in Table 15-14the following parameters should be added or modified in the om_tec.config file.
Table 15-14 Configuration parameters in om_tec.config file Parameter name FilterMode Filter:Class Parameter Value IN ITM_Services_Inventory_610; Parameter Description Enables event filtering Event filter which forwards all ITCAM for SOA events for the Services_Inventory_610 table to the Event Handler. Filter that specifies which events to cache when IBM Tivoli Monitoring is unable to forward an event to the Event Handler.

FilterCache:Class

ITM_Services_Inventory_610;

Important: If the EIF configuration file already contains values for any of the parameters listed above, you should replace the current values with the values described in the table. The EIF configuration file also contains other parameters, including ServerLocation and ServerPort parameters which are set to the values you configured during the procedure described above. However, you must use this procedure described to specify the hostname and port number for the Event Handler rather than editing the EIF configuration file directly with these values.

Note: For more information about configuring IBM Tivoli Monitoring to forward events, see the IBM Tivoli Monitoring Version 6.1 Administrator’s Guide topics on configuring Tivoli Event Console integration. The next step is to ensure the kd4.map file is copied to the directory where the EIF configuration file is located. The kd4.map file is available on the ITCAM for SOA V6.1 installation media and also in the itcam4soa-tec-file.zip file that is

748

WebSphere Service Registry and Repository Handbook

included in the sa04.zip and sa04.tgz files that are downloaded from the Event Handler SupportPAC Web page. You then need to restart the Tivoli Enterprise Monitoring Server for these changes to take effect: For Windows monitoring servers only, use the Manage Tivoli Enterprise Monitoring Services application to start the monitoring server. For UNIX and Linux monitoring servers, do the following: – At the command line change to the /opt/IBM/ITM/bin directory (or the directory where you installed IBM Tivoli Monitoring). – Run the following commands: ./itmcmd server stop ./itmcmd server start tems_name tems_name

where tems_name is the name of your monitoring server (for example, HUB_itmdev17). Note: See the Commands Reference in the IBM Tivoli Monitoring Version 6.1 Installation and Setup Guide for more information about these commands.

Working example
In our working example, we start by reconfiguring TEMS using the Tivoli Enterprise Monitoring Services application (Windows system). We right-click the Tivoli Enterprise Monitoring Server and click Reconfigure as shown in Figure 15-50 on page 750.

Chapter 15. Integrating WSRR with ITCAM for SOA

749

Figure 15-50 Reconfiguring TEMS

We select TEC Event Integration Facility and click OK twice as illustrated in Figure 15-51 on page 751.

750

WebSphere Service Registry and Repository Handbook

Figure 15-51 TEMS Configuration

We specify the TEC event server location using the IP address and the port of the Event Handler as shown in Figure 15-52.

Figure 15-52 TEC event handler location and port

We click OK to validate our configuration changes. We then modify the Event Integration Facility configuration file located at C:\IBM\ITM\cms\TECLIB\om_tec.config as illustrated in Example 15-10.
Example 15-10 om_tec.config configuration file

ServerLocation=9.42.170.137 ServerPort=1111

Chapter 15. Integrating WSRR with ITCAM for SOA

751

RetryInterval=5 getport_total_timeout_usec=50500 NO_UTF8_CONVERSION=YES ConnectionMode=co BufferEvents=YES BufEvtMaxSize=4096 BufEvtPath=./TECLIB/om_tec.cache FilterMode=IN Filter:Class=ITM_Services_Inventory_610; FilterCache:Class=ITM_Services_Inventory_610; Note: We just need to add/update the FilterMode, Filter:Class and FilterCache:Class properties as the rest of the properties have been updated in the previous steps using the graphical interface. We copy the kfd4.map file in the C:\IBM\ITM\cms\TECLIB\ folder. Using the Tivoli Enterprise Monitoring Services application we then restart TEMS so that our changes take effect.

Configuring IBM Tivoli Enterprise Console for Event Handler
This section discusses how to configure IBM Tivoli Enterprise Console to re-send situation events to the Event Handler and provides a working example. This procedure configures Tivoli Enterprise Console to send ITCAM for SOA events to the Event Handler. 1. Create a temporary directory, for example C:\temp\itcamsoarules on a Windows system. 2. Download the .zip file provided with the Event Handler SupportPAC and extract the following files from the .zip file to the temporary directory that you created in step 1. – install_itcam_rb.sh – tec_itcam.rls – tec_itcam.conf – kd4.baroc – kd4.map If Tivoli Enterprise Console is installed on a UNIX or Linux system, ensure install_itcam_rb.sh is granted execute permission. 3. Edit the following parameters in the tec_itcam.conf file as shown in Table 15-15 on page 753.

752

WebSphere Service Registry and Repository Handbook

Table 15-15 Configuration parameters in tec_itcam.conf file Parameter name ServerLocation Parameter Value Event Handler server address Event Handler port number Parameter Description Hostname or IP address of the server where the Event Handler is installed Port number that the Event Handler is listening on. By default, the Event Handler uses port number 1111. The port number must match the port number value specified when you configured the Event Handler.

ServerPort

4. Edit the following variables in itcam_rb.sh.
Table 15-16 Configuration parameters in itcam_rb.sh file Variable name DIR Value description Set this variable to the temporary directory that contains the install_rb.sh file. For example: DIR=C:\temp\itcamsoarules Set this variable to the rule base that was specified when IBM Tivoli Enterprise Console event synchronization was installed on the event server. Set this variable to the rule base path that was specified when IBM Tivoli Enterprise Console event synchronization was installed on the event server.

RuleBase

RuleBasePath

5. Open a command line window 6. Set up the Tivoli Management Framework environment by running the following command: – On a Windows system, run the following command: C:\WINDOWS\system32\drivers\etc\Tivoli\setup_env.cmd – On a Linux or UNIX system, run the following command from a shell environment: ./etc/Tivoli/setup_env.sh Change to the directory created in step 1 Enter the following commands: bash

Chapter 15. Integrating WSRR with ITCAM for SOA

753

./install_itcam_rb.sh 7. Restart Tivoli Enterprise Console Important: Also ensure the kd4.map file is copied to the following directory on the system where Tivoli Enterprise Monitoring Server is installed: On a Windows system: C:\IBM\ITM\cms\TECLIB On a UNIX or Linux system: /opt/IBM/ITM/tables/host name/TECLIB where /opt/IBM/ITM and C:\IBM\ITM are the default locations where the Tivoli Enterprise Monitoring Server is installed and host name is the value supplied during the Tivoli Enterprise Monitoring Server configuration. The kd4.map file is available on the ITCAM for SOA V6.1 installation media and also in the .zip file that you downloaded in step 2 above. The steps above install a re-send rule that forwards all ITCAM for SOA events to the Event Handler. All events, except events with the severity set to Harmless, are sent to the Event Handler.

15.9.5 Triggering situations and forwarding service status information
The next step of our integration scenario is the triggering of situations in ITCAM for SOA and the observation of the updates in WSRR.

Observing the initial state of the registered services
Before triggering the situation, we can observe the initial definition of the two services (ItemPriceService and ItemPriceDiscountedService) as they are defined in WSRR. The elements of interest in our scenario are the two Ports as these are the Logical Objects that get updated with operational information flowing back from ITCAM for SOA when situations arise. Figure 15-53 on page 755 and Figure 15-54 on page 756 show the custom properties initially defined respectively for the ItemPrice port and the ItemPriceDiscounted port in WSRR.

754

WebSphere Service Registry and Repository Handbook

Figure 15-53 Initial custom properties for ItemPrice service port

Chapter 15. Integrating WSRR with ITCAM for SOA

755

Figure 15-54 Initial custom properties for ItemPriceDiscounted service port

Configuring predefined situations
For the purpose of our scenario, we are using the predefined Fault_610 situation which falls under the Services Management Agent Environment in the Situation Editor provided by TEP. This situation is preconfigured with a default threshold of 0 for the Fault Count, is cleared whenever the sampling interval is complete, and has a default sampling interval of 5 minutes. Figure 15-55 on page 757 shows the default configuration of the Fault_610 situation in the Situation Editor.

756

WebSphere Service Registry and Repository Handbook

Figure 15-55 Fault_610 predefined situation in TEP Situation Editor

You can modify the sampling interval to augment the frequency with which the situation is evaluated, or change the threshold of the Fault Count to adjust its sensitivity.

Triggering situations: Fault_610 open
To observe meaningful results in the average response time measurement, we start by generating some traffic involving the two observed services as shown in Figure 15-56 on page 758.

Chapter 15. Integrating WSRR with ITCAM for SOA

757

Service Provider Service Consumer getPrice(ItemName) Item price is returned ItemPriceService ItemPriceDiscountedService

Observe operational data (messages, response time…)

Service Registry & Repository

Monitoring & Management

Display service information (topology and operational data)

Figure 15-56 Observing ItemPriceService and ItemPriceDisountedService

The Monitoring and Management infrastructure observes, collects and displays the regular operational data for the observed services as illustrated in Figure 15-56. We then generate a Web services Fault by issuing a request for the price of an unknown item. The invoked service returns a simulated fault which is observed, collected and displayed by the Monitoring and Management infrastructure as shown in Figure 15-32 on page 702. This Fault triggers the Fault_610 predefined situation at the end of the sampling interval. The situation appears in the Navigator view as blue exclamation points as shown in Figure 15-57 on page 759.

758

WebSphere Service Registry and Repository Handbook

Figure 15-57 Situation Fault_610 displayed in TEP Navigator view

The situation is also displayed in the Situation Event Console view as shown in Figure 15-58.

Figure 15-58 Situation Fault_610 displayed in TEP Situation Event Console view

Figure 15-59 on page 760 illustrates a customized Workspace displaying an consolidated view of the Faults by Operation, along with the Fault Details and the Situation Events Console.

Chapter 15. Integrating WSRR with ITCAM for SOA

759

Figure 15-59 Fault and Fault_610 situation in customized TEP workspace

Observing service status information in WSRR
The Fault_610 situation triggers the corresponding situation event which is sent to the ITCAM for SOA Event Handler. As the result of the event being captured and processed by the Event Handler, a custom property named AvgResponseTime is created/updated on the Service Port Logical Object which has issued the Fault (in that case ItemPrice service port), as shown in Figure 15-60 on page 761.

760

WebSphere Service Registry and Repository Handbook

Figure 15-60 AvgResponseTime custom property added to ItemPrice service port in WSRR

Note: As explained in “EventMap (EventMapping page)” on page 735, ITCAM for SOA Event Handler also creates a correlation custom property to keep track of the WSRR property that needs to be changed or removed when the situation clears. The lastModified custom property is modified accordingly to reflect the modification on the Service Port object. Trace was turned on for both the Event Handler and the WebSphere Application Server. The trace files produced by the ITCAM for SOA Event Handler (Example 15-11) and WebSphere Application Server (Example 15-12 on page 762) provide some details on the capture and the processing of the situation event.
Example 15-11 eif01.trc (C:\ITSO\EIF)

2006.12.14 14:24:26.906 com.tivoli.tec.event_delivery.transport.socket.SocketTransport decodeEvent Decoding event using the encoding: UTF8

Chapter 15. Integrating WSRR with ITCAM for SOA

761

Example 15-12 trace.log ([WAS_INSTALL\profiles\default\logs\server1) [12/14/06 14:24:26:906 EST] 000000e7 adapter 1 ************************************************************************************** [12/14/06 14:24:26:906 EST] 000000e7 Fault_610 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 D4:18c837b2:9-server1 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 http://itso.ibm.com [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 b0c804fa56fa84ac827cd3adaddcb7b6 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 b0c804fa56fa84ac827cd3adaddcb7b6 [12/14/06 14:24:26:906 EST] 000000e7 ITSO-WMBNode01 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 b0c804fa56fa84ac827cd3adaddcb7b6 [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:906 EST] 000000e7 ITSO-WMBNode01Cell [12/14/06 14:24:26:906 EST] 000000e7 [12/14/06 14:24:26:922 EST] 000000e7 [12/14/06 14:24:26:922 EST] 000000e7 [12/14/06 14:24:26:922 EST] 000000e7 ITSO-ITCAM.itso.ral.ibm.com [12/14/06 14:24:26:922 EST] 000000e7 adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter adapter 1 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 ITCAMAdaptor receives a message with ID: [severity] = HARMLESS [interval_begin_time] = 1061214192500000 [situation_origin] = [adapter_host] = ITCAM4SOA:ITSO-WMB:D4 [operation_namespace_u] = [cms_port] = 3661 [sub_source] = D4:18c837b2:9-server1 [table_version_u] = 1 [interval_status] = 2 [std_dev_msg_length] = 103 [fault_count] = 1 [min_msg_length] = 240 [situation_name] = Fault_610 [application_servername_u] = server1 [master_reset_flag] = [avg_elapsed_time] = 5000 [situation_displayitem] = [application_serverenv] = 1 [max_elapsed_time] = 5000 [hostname] = ITSO-WMB [elapsed_time_msg_count] = 4 [local_ipaddress_u] = 9.42.170.143 [unique_key_u] = [application_server_nodename_u] = [source] = ITM:Truncated [interval_end_time] = 1061214193000000 [sub_origin] = [std_dev_elapsed_time] = 0 [application_server_cellname_u] = [msg_count] = 8 [origin_node] = D4:18c837b2:9-server1 [service_type] = 1 [cms_hostname] = [operation_name_u] = getPrice

762

WebSphere Service Registry and Repository Handbook

[12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [integration_type] = U [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [situation_time] = 12/14/2006 14:30:56.000 [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [appl_label] = [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [avg_msg_length] = 334 [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [local_hostname_u] = 9.42.170.143 [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [msg] = Fault_610[(Fault_Count>0 AND Interval_Status=Complete ) ON D4:18c837b2:9-server1 ON b0c804fa56fa84ac827cd3adaddcb7b6 (Fault_Count=1 Interval_Status=Complete )] [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [situation_status] = Y [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [situation_eventdata] = ~ [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [filler1] = 0 [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [service_name_u] = ItemPrice [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [origin] = 9.42.170.143 [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [port_number] = 2809 [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [interval_length] = 5 [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [min_elapsed_time] = 5000 [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [date] = 12/14/2006 [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [application_servercluster_u] = [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [port_namespace_u] = http://itso.ibm.com [12/14/06 14:24:26:922 EST] 000000e7 adapter 3 [max_msg_length] = 484 [12/14/06 14:24:26:922 EST] 000000e7 integrationmo 1 Event is being processed ... [12/14/06 14:24:26:922 EST] 000000e7 integrationmo 1 Event ID: Fault_610 [12/14/06 14:24:26:922 EST] 000000e7 integrationmo 1 Event Msg: ITM_Services_Inventory_610;cms_hostname='ITSO-ITCAM.itso.ral.ibm.com';cms_port='3661';integrati on_type='U';master_reset_flag='';appl_label='';situation_name='Fault_610';situation_origin='D4: 18c837b2:9-server1';situation_time='12/14/2006 14:30:56.000';situation_status='Y';hostname='ITSO-WMB';origin='9.42.170.143';adapter_host='ITCA M4SOA:ITSO-WMB:D4';severity='HARMLESS';date='12/14/2006';source='ITM:Truncated';sub_source='D4: 18c837b2:9-server1';msg='Fault_610[(Fault_Count>0 AND Interval_Status=Complete ) ON D4:18c837b2:9-server1 ON b0c804fa56fa84ac827cd3adaddcb7b6 (Fault_Count=1 Interval_Status=Complete )]';situation_displayitem='b0c804fa56fa84ac827cd3adaddcb7b6';sub_origin='b0c804fa56fa84ac827cd3 adaddcb7b6';origin_node='D4:18c837b2:9-server1';application_servercluster_u=' ';application_servername_u='server1';service_name_u='ItemPrice';operation_name_u='getPrice';int erval_length='5';port_namespace_u='http://itso.ibm.com';operation_namespace_u='http://itso.ibm. com';port_number='2809';unique_key_u='b0c804fa56fa84ac827cd3adaddcb7b6';service_type='1';applic ation_serverenv='1';avg_msg_length='334';msg_count='8';elapsed_time_msg_count='4';avg_elapsed_t ime='5000';fault_count='1';max_msg_length='484';max_elapsed_time='5000';min_msg_length='240';mi n_elapsed_time='5000';std_dev_msg_length='103';std_dev_elapsed_time='0';interval_status='2';fil ler1='0';interval_begin_time='1061214192500000';interval_end_time='1061214193000000';local_host name_u='9.42.170.143';local_ipaddress_u='9.42.170.143';application_server_nodename_u='ITSO-WMBN ode01';application_server_cellname_u='ITSO-WMBNode01Cell';table_version_u='1';situation_eventda ta='~';END [12/14/06 [12/14/06 [12/14/06 [12/14/06 14:24:26:922 14:24:26:922 14:24:26:922 14:24:26:922 EST] EST] EST] EST] 000000e7 000000e7 000000e7 000000e7 integrationmo integrationmo integrationmo integrationmo 1 1 1 1 Handle the Y-type event. OperationName = getPrice PortName = ItemPrice PortNamespace = http://itso.ibm.com

Chapter 15. Integrating WSRR with ITCAM for SOA

763

[12/14/06 14:24:26:922 EST] 000000e7 integrationmo 1 Query statement: /WSRR/WSDLService/ports[@name='ItemPrice' and @namespace='http://itso.ibm.com'] [12/14/06 14:24:27:547 EST] 000000e7 integrationmo 1 Handle the event as a WebService binding event. [12/14/06 14:24:27:547 EST] 000000e7 integrationmo 1 /WSRR/Module/exports[(exportBinding treat as element(exportBinding,WebServiceExportBinding))[WSDLPort(.)[@name='ItemPrice' and @namespace='http://itso.ibm.com']]] [12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 try to update properties in BaseObject[com.ibm.serviceregistry.sdo.impl.WSDLPortImpl@b052e3cd (classificationURIs: [http://www.ibm.com/xmlns/prod/serviceregistry/6/0/governance/DefaultLifecycle#State4], bsrURI: WSRR--7797c588.ec8a0705.98a064c.7c8dbd7c-34a1-41fb.8a54.65078e655417, description: null, lastModified: 1166114668375, name: ItemPrice, namespace: http://itso.ibm.com, owner: administrator, version: )] [12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 the value of property[AvgResponseTime] will be updated [12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 property has been updated [12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 correlation property[Fault_610---b0c804fa56fa84ac827cd3adaddcb7b6---D4--18c837b2--9-server1] has been added [12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 There are 1 WSDLPort(s) need to be updated [12/14/06 14:24:27:594 EST] 000000e7 integrationmo 1 Persisting 1 WSRR instance(s) to WSRR ...

Figure 15-61 on page 765 summarizes the overall use case.

764

WebSphere Service Registry and Repository Handbook

Service Provider Service Consumer getPrice(UnknownItemName) Fault is returned Fault ItemPriceDiscountedService ItemPriceService

Fault

Observe operational data (Messages, Response time, Faults…)

The situation event is Service captured and Registry processed by the & Repository Event Handler. A corresponding AvgResponseTime=5000 AvgResponseTime property is created and valued for the target Service Port object in WSRR.

Monitoring & Management Event Situation Open
Properties

Fault_610 Situation Open

Fault_610 situation is triggered after the end of the sampling interval and a situation event is fired

Figure 15-61 Observing Faults on ItemPriceService and ItemPriceDiscountedService, and forwarding events

Clearing situations: Fault_610 cleared
After some time (depending on the configuration of the sampling interval in the Situation Editor), the Fault_610 situation is cleared as shown in Figure 15-62 on page 766 displaying the customized workspace used previously.

Chapter 15. Integrating WSRR with ITCAM for SOA

765

Figure 15-62 Fault_610 situation cleared in TEP customized workspace

A corresponding situation event is fired and sent to the Event Handler which captures and processes it. As a result, the AvgResponseTime custom property on the ItemPrice service port object in WSRR is set to “cleared” as specified when configuring the Event Handler EventMapping (see “Working example” on page 749). Figure 15-63 on page 767 displays the updated custom properties on the ItemPrice service port object in WSRR.

766

WebSphere Service Registry and Repository Handbook

Figure 15-63 AvgResponseTime custom property set to “cleared” in WSRR

Note: The correlation custom property created previously is removed when the situation clears. The lastModified custom property is modified accordingly to reflect the modification on the Service Port object. Figure 15-64 on page 768 summarizes the overall use case.

Chapter 15. Integrating WSRR with ITCAM for SOA

767

Service Provider Service Consumer getPrice(ItemName) Item price is returned ItemPriceService ItemPriceDiscountedService

Observe operational data (Messages, Response time, Faults…)

The situation event is Service captured and Registry processed by the & Repository Event Handler. The corresponding AvgResponseTime=cleared AvgResponseTime property is set to “cleared” for the target Service Port object in WSRR.

Monitoring & Management Event Situation Cleared
Properties

Fault_610 Situation Cleared

Fault_610 situation is cleared after the end of the sampling interval and a situation event is fired

Figure 15-64 Cleared situation and forwarding of corresponding event

Removing situations: Fault_610 removed
Stopping the Fault_610 situation using the Situation Editor as shown in Figure 15-65 triggers a situation event which is sent to the Event Handler.

Figure 15-65 Stopping Fault_610 situation in TEP Situation Editor

Figure 15-66 on page 769 shows the corresponding event in the Situation Event Console view.

768

WebSphere Service Registry and Repository Handbook

Figure 15-66 Stopped situation event in TEP Situation Event Console view

As a result, the corresponding custom property AvgResponseTime is deleted from the ItemPrice service port object in WSRR. Figure 15-67 shows the resulting custom property set of the ItemPrice service port object in WSRR.

Figure 15-67 AvgResponseTime custom property removed in WSRR

Once more, the lastModified custom property is modified accordingly to reflect the modification on the Service Port object. Figure 15-68 on page 770 summarizes the overall use case.

Chapter 15. Integrating WSRR with ITCAM for SOA

769

Service Provider Service Consumer getPrice(ItemName) Item price is returned ItemPriceService ItemPriceDiscountedService

St o

p

Fa ul t_ 61 0

Si tu at

Observe operational data (Messages, Response time, Faults…) io n

The situation event is captured and processed by the Event Handler. The corresponding AvgResponseTime property is removed from the target Service Port object in WSRR.

Service Registry & Repository Event Situation Stopped
Properties

Monitoring & Management

Fault_610 Situation Stopped

Fault_610 situation is stopped and a situation event is fired

Figure 15-68 Stopped situation and forwarding of corresponding event

Note: The same behavior would have occurred if we had removed the Fault_610 situation instead of just stopping it.

15.9.6 Using service status information in ESB infrastructure
Elaborating from the scenario described in 14.7.12, “Scenario 3: Use the Lookup primitive to get both endpoints” on page 612 we could now use the operational data observed from the running ItemPriceService and ItemPriceDiscountedService services in the routing policy. This would be an implementation of the logical architecture depicted in 15.7.3, “Use of service status information” on page 690. Instead of basing the routing policy only on the CustomerType static custom property, we could enhance this policy with the use of the dynamic AvgResponseTime custom property so that this policy would now take into account the observed average response time of the services in the routing decision.

770

WebSphere Service Registry and Repository Handbook

16

Chapter 16.

Integrating WSRR with WMB
This chapter describes how to integrate WSRR with WebSphere Message Broker through the use of the additional SupportPac “WMB V6 Client for WebSphere Service Registry and Repository”. This chapter contains the following: 16.1, “Introduction” on page 772 16.2, “About WebSphere Message Broker” on page 772 16.3, “Installation” on page 779 16.4, “WebSphere Message Broker Client for WSRR” on page 786 16.5, “WSRR nodes” on page 790 16.6, “WMB Client Cache for WSRR” on page 800 16.7, “WMB Client support for SOA patterns” on page 803 16.8, “Setting up your environment for the patterns” on page 809

© Copyright IBM Corp. 2007. All rights reserved.

771

16.1 Introduction
This chapter describes the use of WebSphere Service Registry and Repository in an Enterprise Service Bus (ESB) environment, using WebSphere Message Broker (WMB) as the ESB implementation. Use of WSRR allows ESB mediations that interact with some set of endpoint services to be more tolerant of changes within the environment. This is enabled by the ESB using WSRR as a dynamic lookup mechanism, providing information about service endpoints (the service metadata). So, when changes occur in the service endpoint environment, the associated ESB mediations do not have to change. The interaction between WMB and WSRR is provided by an IBM product extension for WMB, the WebSphere Message Broker V6 Client for WebSphere Service Registry and Repository. This is provided as a Category 1 SupportPac, IA9L, available from the WMB SupportPac URL: http://www.ibm.com/support/docview.wss?uid=swg24013639 The support encompasses a set of WMB nodes that can be used when building WMB flows. These nodes encapsulate the API calls to WSRR and a caching mechanism to improve the efficiency of the interaction. Section 16.4, “WebSphere Message Broker Client for WSRR” on page 786 includes more information about the component parts of the client and how it works.

16.2 About WebSphere Message Broker
Application integration is a big challenge for enterprises, and IBM provides a number of software solutions and offerings to assist companies with integrating their applications. WebSphere Message Broker is an important part of the IBM offerings, and the way in which WebSphere Message Broker benefits application integration is described in the following sections.

16.2.1 Application integration and WebSphere Message Broker
Application integration, at a high level, refers to solutions that are implemented to integrate software applications within and between organizations. Historically, application integration has been concerned with the integration of existing software applications, such as between different departments and divisions within companies, or new acquisitions. Within an organization, these applications often vary considerably across departments, exist on different platforms, are written in different programming languages, and use different data formats.

772

WebSphere Service Registry and Repository Handbook

Integrating the applications is a more practical and cost effective solution than the alternative of re-writing the existing applications. WebSphere Message Broker is used in the implementation of an application integration architecture because it provides a mechanism for connecting, routing, and transforming business data from a variety of transports without any need to change the underlying applications generating the data. WebSphere Message Broker enhances the flow and distribution of information by enabling the transformation and intelligent routing of messages without the need to change either the applications that are generating the messages or the applications that are consuming them. In WebSphere Message Broker, connectivity is provided by applications that communicate by sending and receiving messages. WebSphere Message Broker also has the following key capabilities that make it a valuable solution for business integration: Distributes any type of information across and between multiple diverse systems and applications, providing delivery of the correct information in the correct format and at the correct time Reduces the number of point-to-point interconnections and simplifies application programming by removing integration logic from the applications Routes information in real time based on topic and content to any endpoint using a powerful publish/subscribe messaging engine Validates and transforms messages in-flight between any combination of different message formats, including Web Services, and other XML and non-XML formats Routes messages based on (evaluated) business rules to match information content and business processes Improves business agility by dynamically reconfiguring information distribution patterns without reprogramming end-point applications Access control to securely deliver personalized information to the right place at the right time

16.2.2 WebSphere Message Broker overview
WebSphere Message Broker is a powerful information broker that allows both business data and information, in the form of messages, to flow between disparate applications and across multiple hardware and software platforms. Business rules can be applied to the data that is flowing through the message broker in order to route, store, retrieve, and transform the information.

Chapter 16. Integrating WSRR with WMB

773

Editions of WebSphere Message Broker
There are three editions of the WebSphere Message Broker product as described in the sections below.

WebSphere Event Broker
WebSphere Event Broker is used for the distribution and routing of messages from disparate applications. It can distribute information and data, which is generated by business events in real time, to people, applications, and devices throughout an enterprise. WebSphere Event Broker has support for multiple transport protocols and extends the flow of information in an organization beyond point to point, utilizing flexible distribution mechanisms such as publish/subscribe and multicast.

WebSphere Message Broker
WebSphere Message Broker contains all the functionality of WebSphere Event Broker and extends it to include additional capabilities to enable storage, transformation, and enrichment of data flowing through the broker. Detailed capabilities of the product are described in the following sections and are based upon the functional capabilities of the WebSphere Message Broker specifically.

Rules and Formatter Extension
WebSphere Message Broker with Rules and Formatter Extension includes the Rules and Formatter Extension from New Era Of Networks which provides Rules and Formatter nodes and associated runtime elements. These support the functionality supplied with earlier releases of WebSphere MQ Integrator.

16.2.3 Capabilities of WebSphere Message Broker
The primary capabilities of WebSphere Message Broker are message routing, message transformation, message enrichment, and publish/subscribe. Together these capabilities make WebSphere Message Broker a powerful tool for business integration.

Message routing
WebSphere Message Broker provides connectivity for both standards based and non-standards based applications and services. The routing can be simple point-to-point routing or it can be based on matching the content of the message to business rules defined to the broker. WebSphere Message Broker contains a choice of transports that enable secure business to be conducted at any time and any place, providing powerful integration using mobile, telemetry, and Internet technologies. WebSphere

774

WebSphere Service Registry and Repository Handbook

Message Broker is built upon WebSphere MQ and therefore supports the same transports. However, it also extends the capabilities of WebSphere MQ by adding support for other protocols, including real-time Internet, intranet, and multicast endpoints. WebSphere Message Broker supports the following transports: WebSphere MQ Enterprise Transport WebSphere MQ Web Services Transport WebSphere MQ Real-time Transport WebSphere MQ Multicast Transport WebSphere MQ Mobile Transport WebSphere MQ Telemetry Transport WebSphere Broker JMS Transport In addition to the supplied transports, the facility exists for users to write their own input nodes to accept messages from other transports and formats as defined by the user.

Message transformation and enrichment
Transformation and enrichment of in-flight messages is an important capability of WebSphere Message Broker, and allows for business integration without the need for any additional logic in the applications themselves. Messages can be transformed between applications to use different formats, for example, transforming from a custom format in a existing system to XML messages that can be used with a Web service. This provides a powerful mechanism to unify organizations because business information can now be distributed to applications that handle completely different message formats without a need to reprogram or add to the applications themselves. Messages can also be transformed and enriched by integration with multiple sources of data such as databases, applications, and files. This allows for any type of data manipulation including logging, updating, and merging. For the messages that flow through the broker, business information can be stored in databases or can be extracted from databases and files and added to the message for processing in the target applications. Complex manipulation of message data can be performed using the facilities provided in the Message Brokers Toolkit, such as ESQL and Java. In WebSphere Message Broker, message transformation and enrichment is dependent upon a broker understanding the structure and content of the incoming message. Self-defining messages, such as XML messages, contain information about their own structure and format. However, before other messages, such as custom format messages, can be transformed or enhanced,

Chapter 16. Integrating WSRR with WMB

775

a message definition of their structure must exist. The Message Brokers Toolkit contains facilities for defining messages to the message broker. These facilities are discussed in more detail below.

Publish/subscribe
The simplest way of routing messages is to use point-to-point messaging to send messages directly from one application to another. Publish/subscribe provides an alternative style of messaging in which messages are sent to all applications that have subscribed to a particular topic. The broker handles the distribution of messages between publishing applications and subscribing applications. As well as applications publishing on or subscribing to many topics, more sophisticated filtering mechanisms can be applied. An improved flow of information around the business is achieved through the use of publish/subscribe and the related technology of multicast. These flexible distribution mechanisms move away from hard-coded point-to-point links.

16.2.4 Components of WebSphere Message Broker
WebSphere Message Broker is comprised of two principle parts, a development environment for the creation of message flows, message sets, and other message flow application resources; and a runtime environment, which contains the components for running those message flow applications that are created in the development environment.

Development environment
The development environment is where the message flow applications that provide the logic to the broker are developed. The broker uses the logic in the message flow applications to process messages from business applications at run time. In the Message Brokers Toolkit, you can develop both message flows and message sets for message flow applications.

Message flows
Message flows are programs that provide the logic that the broker uses to process messages from business applications. Message flows are created by connecting nodes together, with each node providing some basic logic. A selection of built-in nodes is provided with WebSphere Message Broker for performing particular tasks. These tasks can be combined to perform complex manipulations and transformations of messages. A choice of methods is available for defining the logic in the message flows to transform data. Depending on the different types of data or the skills of the message flow application developer, the following options are available:

776

WebSphere Service Registry and Repository Handbook

Extended Structured Query Language (ESQL) Java eXtensible Style sheet Language for Transformations (XSLT) Drag-and-drop mappings The nodes in the message flows define the source and the target transports of the message, any transformations and manipulations based on the business data, and any interactions with other systems such as databases and files.

Message sets
A message set is a definition of the structure of the messages that are processed by the message flows in the broker. As mentioned previously, in order for a message flow to be able to manipulate or transform a message, the broker must know the structure of the message. The definition of a message can be used to verify message structure, and to assist with the construction of message flows and mappings in the Message Brokers Toolkit. Message sets are compiled for deployment to a broker as a message dictionary, which provides a reference for the message flows to verify the structure of messages as they flow through the broker.

Broker Application Development perspective
The Broker Application Development perspective is the part of the Message Brokers Toolkit that is used to design and develop message flows and message sets. It contains editors that create message flows, create transformation code such as ESQL and define messages.

Runtime environment
The runtime environment is the set of components that are required to deploy and run message flow applications in the broker.

Broker
The broker is a set of application processes that host and run message flows. When a message arrives at the broker from a business application, the broker processes the message before passing it on to one or more other business applications. The broker routes, transforms, and manipulates messages according to the logic that is defined in their message flow applications. A broker uses WebSphere MQ as the transport mechanism both to communicate with the Configuration Manager, from which it receives configuration information, and to communicate with any other brokers to which it is associated. Each broker has a database in which it stores the information that it needs to process messages at run time.

Chapter 16. Integrating WSRR with WMB

777

Execution groups
Execution groups enable message flows within the broker to be grouped together. Each broker contains a default execution group. Additional execution groups can be created as long as they are given unique names within the broker. Each execution group is a separate operating system process and, therefore, the contents of an execution group remain separate from the contents of other execution groups within the same broker. This can be useful for isolating pieces of information for security because the message flows execute in separate address spaces or as unique processes. Message flow applications are deployed to a specific execution group. To enhance performance, the same message flows and message sets can be running in different execution groups.

Configuration Manager
The Configuration Manager is the interface between the Message Brokers Toolkit and the brokers in the broker domain. The Configuration Manager stores configuration details for the broker domain in an internal repository, providing a central store for resources in the broker domain. The Configuration Manager is responsible for deploying message flow applications to the brokers. The Configuration Manager also reports back on the progress of the deployment and on the status of the broker. When the Message Brokers Toolkit connects to the Configuration Manager, the status of the brokers in the domain is derived from the configuration information stored in the Configuration Manager’s internal repository.

Broker domain
Brokers are grouped together in broker domains. The brokers in a single broker domain share a common configuration that is defined in the Configuration Manager. A broker domain contains one or more brokers and a single Configuration Manager. It can also contain a User Name Server. The components in a broker domain can exist on multiple machines and operating systems, and are connected together with WebSphere MQ channels. A broker belongs to only one broker domain.

User Name Server
A User Name Server is an optional component that is required only when publish/subscribe message flow applications are running, and where extra security is required for applications to be able to publish or subscribe to topics.

778

WebSphere Service Registry and Repository Handbook

The User Name Server provides authentication for topic-level security for users and groups that are performing publish/subscribe operations.

Broker Administration perspective
The Broker Administration perspective is the part of the Message Brokers Toolkit that is used for the administration of any broker domains that are defined to the Message Brokers Toolkit. This perspective is also used for the deployment of message flows and message sets to brokers in the defined broker domains. The Broker Administration perspective also contains tools for creating message broker archive (bar) files. Bar files are used to deploy message flow application resources such as message flows and message sets. The Broker Administration perspective also contains tools to help test message flows. These tools include Enqueue and Dequeue for putting and getting messages from WebSphere MQ queues.

16.3 Installation
For the purposes of this book we will assume that you already have WebSphere Message Broker V6 installed and working. If not, refer to the WMB Information Center for documentation about how to install WebSphere Message Broker: http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/index.jsp

16.3.1 Download the SupportPac
To acquire the SupportPac you must contact your IBM representative or e-mail spacs@uk.ibm.com. You will then be sent a link from which you can download the SupportPac zip file. This information is also available on the SupportPac Web site: http://www.ibm.com/support/docview.wss?uid=swg24013639

16.3.2 Prerequisites
The SupportPac provides WSRR nodes and functionality to be used with WebSphere Message Broker V6.0.0.2 (and later) product. WebSphere Service Registry and Repository is also required. For normal use there are no other prerequisites. In order for the cache synchronization to function using a SIBus (the default for both WebSphere and WSRR), the JMS Client will need to be available. It can be obtained from:

Chapter 16. Integrating WSRR with WMB

779

http://www.ibm.com/support/docview.wss?uid=swg24012804 If global security is enabled for the WebSphere Application Server then a WMB fix to enable secure access to the SIBus is also needed. This fix is included in WMB FixPack 3 (V6.0.0.3). WMB FixPack 3 can be downloaded from: http://www.ibm.com/support/docview.wss?rs=849&uid=swg24013952 Note: The WMB V6 Client for WebSphere Service Registry and Repository uses JAR files from both WSRR and from either WebSphere Application Server or the WebSphere Application Client. These JAR files must be available for the WMB Client to operate, they are not provided with the SupportPac itself.

16.3.3 Install the SupportPac
The installation of the WMB V6 Client for WebSphere Service Registry and Repository is quite complicated and involves several manual steps. Take care when following the steps here.

Install WMB
For the purposes of this book we will assume that you have WMB installed. If you do not, then consult the WMB documentation about how to do so: http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/index.jsp

Install WMB FP3
If you have global security turned on in WebSphere then you will require WMB FixPack 3 (V6.0.0.3). Download it from this Web site and then follow the instructions there about how to install it: http://www.ibm.com/support/docview.wss?rs=849&uid=swg24013952

Install JMS Client
Install the JMS client on the WMB Broker runtime system. This is only needed if you want to use the cache synchronization functionality provided in the WSRR SupportPac. 1. Download from: http://www.ibm.com/support/docview.wss?uid=swg24012804 2. Copy the downloaded file to the directory you want to install the JMS Client to, for example, C:\Program Files\IBM\MQSI\JMSClient 3. Install the client by executing the following command from the directory to which you copied the JMSClient jar file.

780

WebSphere Service Registry and Repository Handbook

java -jar sibc_install-.jar -text jms_jndi_ibm Where is the specific version of your JMSClient jar file, at the time of writing the latest version was build o0647.15 Substitute jms_jndi_sun for jms_jndi_ibm if installing on Solaris.

Install WMB Client for WSRR
Download the SupportPac from: http://www.ibm.com/support/docview.wss?uid=swg24013639 Unzip the zip file to where you want the WMB Client installed, for example, C:\Program Files\IBM\MQSI\WMB-WSRRClient

Gather files on the runtime system
There are several files that you will need later on in the installation process. It is simpler to gather them all together now. Copy the following files to a single folder on the target WMB toolkit system, for example, C:\Program Files\IBM\MQSI\WMB-WSRRClient\clientfiles From the SupportPac: \ServerRuntime\MBClientAccessToWSRR Folder \ServerRuntime\MBRuntimeExtension\ServiceRegsitry MessageBrokerNodes.par \ServerRuntime\MBClientCacheSynchronization\WSRRU pdateCache_1.0.1.bar \SupportPac-Shared-classes\WMBc4WSRR_1.0.1.jar From the WSRR WebSphere Application Server Install: \classes\sdo-int.jar \runtimes\ibm-jaxrpc-client.jar From the WSRR Install: \ServiceRegistryClient.jar

Setup and Configure Broker Classpath
Edit the brokers profile script (typically mqsiprofile.cmd or mqsiprofile.sh in the \bin directory adding the following lines to the CLASSPATH section of the script: rem Adding to support WSRR set CLASSPATH=%CLASSPATH%;\ibm-jaxrpc-client.jar

Chapter 16. Integrating WSRR with WMB

781

set CLASSPATH=%CLASSPATH%;\lib\sibc.jms.jar;\lib\sibc.jndi.jar Where is the directory you gathered all the files to in the previous step. Where is the directory you installed the JMS client to in a previous step. Ensure you restart the command environment to pick up these changes.

Configuring and running wsrrsetparams
You now need to configure and run wsrrsetparms.bat or wsrrsetparms.sh depending on the type of system you are using. 1. Create a folder \MBClientAccessToWSRR\config\shared-classes Where is the directory you gathered all the files to in a previous step. 2. Move the provided wsrr.properties file from the config directory into the newly created shared-classes directory and ensure no other wsrr.properties files exist on the file system (saving confusion), for example, move \MBClientAccessToWSRR\config\wsrr.properties \MBClientAccessToWSRR\config\shared-classes Where is the directory you gathered all the files to in a previous step. 3. Copy the provided key file to an available location on the runtime environment. A suggestion would be the same folder as the ibm-jaxrpc-client.jar above, for example: move \MBClientAccessToWSRR\config\WSRRProxyConfig.key Where, is the directory you gathered all the files to in a previous step. 4. Edit wsrr.properties file in the shared-classes directory of MBClientAccessToWSRR: – For a standard configuration remove the predefinedQueries value – Change the keyStore and trustStore locations if necessary, you may need to copy these files from your WebSphere server to the local machine if WSRR is not installed on the same machine as WMB.

782

WebSphere Service Registry and Repository Handbook

– Update the endpointaddress to reflect the correct hostname and port for your WSRR installation. Note you need to specify whether to use HTTP or HTTPS too. – Change all references to the default alias to a value you prefer An example wsrr.properties file is shown in Example 16-1, note that the password values will all be set in step 7 by running wsrrsetparams.
Example 16-1 Example wsrr.properties file

DEFAULT_ALIAS = ITSO ITSO.endpointaddress = https://itso-wsrr:9443/WSRRCoreSDO/services/WSRRCoreSDOPort ITSO.keyStore = C:/Progra~1/ibm/MQSI/WMB-WSRRClient/clientfiles/DummyClientKeyFile.jks ITSO.keyStorePassword = (DES)+BjuKS5EWVY= ITSO.keyfile = file:/C:/progra~1/IBM/MQSI/WMB-WSRRClient/clientfiles/WSRRProxyConfig.key ITSO.needCache = true ITSO.password = (DES)KdB6OwaJfJXIWyDoLB9lCA== ITSO.predefinedQueries = ITSO.refreshQueriesAfterNotification = true ITSO.timeout = 10000000 ITSO.trustStore = C:/Progra~1/ibm/MQSI/WMB-WSRRClient/clientfiles/DummyClientTrustFile.jks ITSO.trustStorePassword = (DES)+BjuKS5EWVY= ITSO.userid = (DES)dqndmirQTCzIWyDoLB9lCA== 5. Confirm that the URL provided in the properties file correctly addresses WSRR: – Navigate using a Web browser to the value used in ITSO.endpointaddress this should produce a Web page indicating a test Web service has been called. 6. Edit the \MBClientAccessToWSRR\wsrrsetparms.bat (or.sh) file: – Provide a path to a java runtime, it is likely the one provided in the script doesn't exist. set JAVA_HOME=C:\IBM\WebSphere\AppServer\java – Provide the full path to the key file mentioned above set WSRR_PROXY_KEY=”file:/C:/Progra~1/IBM/MQSI/WMB-WSRRClient/clientf iles/WSRRProxyConfig.key”

Chapter 16. Integrating WSRR with WMB

783

– Configure the correct alias to use as defined in your current wsrr.properties file set WSRR_PROXY_CONFIG_ALIAS=”ITSO” 7. Execute wsrrsetparms – Provide values for the user name and passwords of all entries – The keystore and truststore default password is WebAS wsrrsetparams.bat -u wasadmin -p passw0rd -k WebAS -t WebAS Replace the values above with the correct values for your environment.

Configure the WMB runtime shared-classes
Copy the following files to the \shared-classes directory. To determine the directory query the MQSI_WORKPATH environment variable. By default this is C:\Documents and Settings\All Users\Application Data\IBM\MQSI\shared-classes. Note: This may be a hidden directory and so you may need to alter some Windows folder options to see the folder. sdo-int.jar ServiceRegistryClient.jar WMBc4WSRR_1.0.1.jar wsrr.properties (the file created in step 4 on page 782 above)

Configure the WMB toolkit
1. Unzip \ClientTooling\MBToolkitPlugin\ServiceRegistryMessag eBrokerNodesPlugin_1.0.1.zip Where is the directory you gathered all the files to in a previous step. 2. Copy the com.ibm.sr.mb.nodes_1.0.1 folder from the expanded zip file plugins directory to the toolkit machine placing in the directory \6.0\eclipse\plugins Where, is the WMB Toolkit install directory. 3. Copy the following files from the directory to the WMB toolkit machine into the \6.0\eclipse\plugins\com.ibm.sr.mb.nodes_1.0.1\sha red-classes directory

784

WebSphere Service Registry and Repository Handbook

– sdo-int.jar – ServiceRegistryClient.jar – wsrr.properties (the file created in step 4 on page 782 above) – ibm-jaxrpc-client.jar 4. Start the WMB Toolkit with the -clean option to refresh the toolkit with the new plugin \6.0\wmbt.exe -clean Where is the WMB Toolkit install directory.

Configure WSRR bus security
For WMB FP2 or earlier you must turn off security for the WSRR bus as defined in the SupportPac documentation. For WMB FP3 or later execute the following commands: mqsistop mqsisetdbparms -n jms::jms/SRConnectionFactory -u -p mqsistart Where uid and pwd are the userid and password for your WSRR installation. The broker must be stopped for the mqsisetdbparms command to run.

Configure the broker
On the WMB runtime machine configure the broker to load the plugin jar file. Ensure that you have reloaded the profile after the changes were made in “Setup and Configure Broker Classpath” on page 781 above. 1. Copy \ServiceRegsitryMessageBrokerNodes_1.0.1.par to a directory you prefer on the WMB runtime system if necessary. 2. Configure the broker to reference the above directory: mqsichangebroker -l Note: If you do not already have a broker, then create one before running mqsichangebroker. The mqsicreatebroker can be used for this purpose; consult the WMB documentation for more information. 3. Start the broker and check for any errors Possible places to see errors would be in the console output or in the Windows Event Viewer:

Chapter 16. Integrating WSRR with WMB

785

Control Panel → Administrative Tools → Event Viewer → Application/System For more information about troubleshooting WMB, check the WMB Information Center: http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/topic/com.ib m.etools.mft.doc/au03830_.htm

Optional: Deploy the UpdateCache bar file
This step is only necessary if you want to use the cache synchronization functionality by the SupportPac. 1. Copy the bar file to the Toolkit machine 2. Create a new Servers project in the WMB Toolkit. 3. Import the \WSRRUpdateCache_1.0.1.bar file 4. Click the configure tab for the BAR file 5. Change the JNDI settings to point to your WSRR installation, for example: iiop://itso-wsrr:2809/ 6. Deploy the BAR file, again checking for errors Installation of the WMB Client for WSRR is now complete. The following section will explain what the client provides before we then go on to set up an example scenario which will demonstrate the use of it.

16.4 WebSphere Message Broker Client for WSRR
The WMB V6 Client for WebSphere Service Registry and Repository provides the runtime access to WSRR from within WebSphere Message Broker.

786

WebSphere Service Registry and Repository Handbook

The contents of the client are shown in Figure 16-1.

WebSphere Message Broker Execution Group Flow Flow WSRR Node WSRR Proxy (cache) Execution Group Flow Flow WSRR Node WSRR Proxy (cache) WSRR Nodes

WMB Client for WSRR

Figure 16-1 WMB Client for WSRR contents

The two primary parts of the client are the WMB nodes and a WMB cache for WSRR entities.

16.4.1 WSRR nodes
The client’s nodes provide access to a service’s metadata contained in WSRR. These nodes operate similar to other WMB built-in nodes. At development time the WSRR entity is specified (or values for a query are specified). The nodes access WSRR, as requested by the developer of the flow, at runtime in order to populate the contents of the domain (with the service metadata). For more details, refer to 16.5, “WSRR nodes” on page 790.

16.4.2 WMB Client cache for WSRR
The client’s proxy provides a WMB localized cache for service metadata. The cache helps improve the performance of the flow (by accessing a local cached copy of service metadata instead of retrieving it on each invocation). For more details refer to 16.6, “WMB Client Cache for WSRR” on page 800.

Chapter 16. Integrating WSRR with WMB

787

16.4.3 Client runtime access to WSRR
At runtime a WMB flow uses the WMB client for WSRR to access an entity’s metadata as seen in Figure 16-2.

WebSphere Message Broker Execution Group Flow Flow WSRR Node

1

Execution Group WSRR Proxy (cache) Flow Flow WSRR Node WSRR Proxy (cache) WSRR Nodes

2
WebSphere Application Server

5

Application Application Application

WSRR UI

WSRR

3
Database

4

Figure 16-2 WMB Client Runtime access sequence

The runtime sequence of execution starts with the execution of the mediation: 1. When the mediation flow is executed, and the client node is invoked, the node uses the information specified at development time to access the entity’s metadata. It does this by accessing a WMB client for WSRR proxy, which looks for the entity in the cache before accessing WSRR. 2. When an entity is requested by the WSRR proxy, the proxy checks to see if that service is available from the cache. If the service (metadata) is available from the cache the proxy returns that information to the requesting node. If the service is not available from the cache the proxy retrieves the service directly from the WSRR and stores it in its cache for future use. See 16.6, “WMB Client Cache for WSRR” on page 800 for more information about cache strategy options. 3. When a service is requested from the WSRR, it communicates with the datastore to obtain the service metadata. It returns this metadata to the requestor. 4. If changes are made to a service, via the WSRR UI (Web-based or command line) the WSRR fires a notification event with details of the change. 5. When a service notification event is received by the WMB client for WSRR proxy its cache is updated to contain the new metadata. For details about how

788

WebSphere Service Registry and Repository Handbook

this notification event is obtained and processed by the proxy, refer to the cache details, 16.6, “WMB Client Cache for WSRR” on page 800.

16.4.4 WMB Client and WSRR deployment
Figure 16-3 shows the deployment of the WMB Client for WSRR components.

WebSphere Message Broker Execution Group Flow Flow WSRR Node WSRR Proxy (cache) Execution Group Flow Flow WSRR Node WSRR Proxy (cache) WSRR Nodes

Flows use WMB client for WSRR nodes

Cache shared within an Execution Group

Deployed for a broker instance

Figure 16-3 WMB Client for WSRR deployment

The WMB flows are deployed in WebSphere Message Broker, within a specified Execution Group. These flows represent the exposed service and control the actual service that is invoked, any message transformation that needs to occur, as well as other mediation specific details. Cache Scope: The WMB client proxy handles the request for service metadata, retrieving that metadata from either its cache or from WSRR. The default deployment for the cache is within a WMB execution group. This means that each execution group contains its own separate cache. Refer to 16.6, “WMB Client Cache for WSRR” on page 800 for details on the deployment options for the cache. Node Scope: The WMB client nodes are deployed across an entire WMB installation. This means that the nodes are available across all brokers and execution groups.

Chapter 16. Integrating WSRR with WMB

789

16.5 WSRR nodes
The following sections discuss the WebSphere Message Broker (WMB) nodes for accessing WSRR. They are used the same way as other WMB built-in nodes. The nodes utilize metadata stored in WSRR and node properties to determine the action to take, within a flow, at runtime. The node properties combined with the Service (entity) metadata can be used at runtime to determine how the flow operates. There are two types of nodes; nodes supporting the router and transcoder patterns and nodes for generic access to WSRR content. Note: All nodes throw a MbRecoverableException when a syntactical or semantic error occurs, unless otherwise stated.

16.5.1 Introducing the nodes
There are five nodes that may be used to access service metadata that resides in WSRR. These nodes are designed to be included in message processing flows that mediate between service consumers and service providers in an SOA installation. The first three nodes, SR****VirtualService, are available for a specific pattern of usage (see 16.7, “WMB Client support for SOA patterns” on page 803); while the other two, SRRetrieve****, are for generic WSRR access. The names of the five nodes provided are shown in Table 16-1.
Table 16-1 WSRR WMB nodes Node Name SRGetVirtualService Node Purpose Get Virtual service metadata from WSRR. This virtual service represents the router pattern. (This requires specific configuration of WSRR see 16.8, “Setting up your environment for the patterns” on page 809 for details.) Process message content for services obtained with the SRGetVirtualService node. (This requires specific configuration of WSRR, see 16.8, “Setting up your environment for the patterns” on page 809 for details.) Dispatches an IT service that will execute the request, for services obtained with the SRGetVirtualService node. This requires specific configuration of WSRR see 16.8, “Setting up your environment for the patterns” on page 809 for details.)

SRProcessVirtualService

SRDispatchVirtualService

790

WebSphere Service Registry and Repository Handbook

Node Name SRRetrieveITService SRRetrieveEntity

Node Purpose Get a WSRR service (currently only a Web Service defined via a WSDL is supported). Retrieve metadata about any entity defined in WSRR.

16.5.2 SRGetVirtualService node
This node is used within a message flow to obtain metadata associated with the virtual service that corresponds to the WMB flow. This virtual service represents the router pattern.

Node properties
The properties on the node are: namespace, name, version, relationship type name, and relationship type value. These are shown in Table 16-2.
Table 16-2 SRGetVirtualService node properties Property Name Name Namespace Version Relationship type Relationship type XPath Mandatory Yes Yes Yes Configurable Yes Yes Yes Yes Yes verb Default Values Property Values

The Namespace, Name, and Version are specified on the SRGetVirtualService node properties to uniquely identify the virtual service that represents the WMB flow implementing the router pattern. The Relationship Type and XPath can also be specified on the properties page. The Relationship Type defaults to “verb”. The XPath location of the relationship type corresponds to the incoming message (for example, the location of the relationship type within the incoming message). The Relationship Type XPath value can also be specified on the relationship and would override the value set here.

Node terminals
Table 16-3 on page 792 shows the terminals for this node.

Chapter 16. Integrating WSRR with WMB

791

Table 16-3 SRGetVirtualService node terminals Terminal Name In Out Failure Description Node input terminal Node output terminal Node failure terminal (where exceptions are thrown)

Runtime destination routing
Since the virtual service obtained with this node represents the router pattern, this node automatically sets the destination routing based on the relationship type, relationship value, and endpoint alias (also known as the network location). This means that flows can be built to handle all ‘known’ routes and the node will set the context so that the correct route will be taken. The SRGetVirtualService node will set a default destination label to the value “RouteToLabel” specified on the relationship between Services, if blank or not set the destination label will not be set.

792

WebSphere Service Registry and Repository Handbook

Use of this destination is primarily related to use by the WMB built-in node RouteToLabel, as seen in Figure 16-4, but can also be used in a non-WMB environment. The destination can be overridden using normal WMB toolkit functionality.

Figure 16-4 SRGetVirtualService node route mapping

16.5.3 SRProcessVirtualService node
This node is used to create the proper format for the target service invocation and override the target service’s operation (if necessary). This node is normally invoked after message translation (if needed).

Node properties
This node has no properties.

Node terminals
Table 16-4 shows the terminals for this node.
Table 16-4 SRProcessVirtualService node terminals Terminal Name In Description Node input terminal

Chapter 16. Integrating WSRR with WMB

793

Terminal Name Out Failure

Description Node output terminal Node failure terminal (where exceptions are thrown)

Runtime destination routing
This node will set the destination label to the value “Label{-}”. The protocol must be one of the supported types of protocols; such as MQ, URL, or JMS. If the protocol is not specified, the routing label will be “Label”. At the completion of this node the endpoint will be established such that the backend service can be invoked (usually through the use of a HTTPRequest or MQOutput node). Use of this destination is primarily related to use by the WMB built-in node RouteToLabel. The destination can be overridden using normal Message Broker toolkit functionality.

16.5.4 SRDispatchVirtualService node
This node is used to establish the endpoint of the target service. It will normally send its output to a HTTPResponse or MQOutput built-in node. Note: This node is dependent on the domain context set by the SRGetVirtualService node.

Node properties
This node has no properties.

Node terminals
Table 16-5 shows the terminals for this node.
Table 16-5 SRDispatchVirtualService node terminals Terminal Name In Out Failure Description Node input terminal Node output terminal Node failure terminal (where exceptions are thrown)

794

WebSphere Service Registry and Repository Handbook

16.5.5 SRRetrieveITService node
This node is a generic node in that it retrieves the service endpoint information related to a WSRR defined service (for example, WSDL). It does not perform additional filtering or selection; other than that specified by the property matching. If a single service (Web Service only) is requested (MatchPolicy is One), it will set the endpoints in the context so that this service information is correctly placed in the domain context in order that existing WMB built-in nodes will correctly invoke the service. Note: This node is independent of any other domain context. Support is currently limited to querying for Web Service endpoints.

Node properties
The properties on the node are: name tuple, user properties, classification and MatchPolicy. These are shown in Table 16-6.
Table 16-6 SRGetVirtualService node properties Property Name Name tuple (portType name, namespace and version) User properties Classification Mandatory No Configurable Yes Default Values Property Values Name tuple that uniquely defines a WSRR defined WSDL service portType.

No

No

Allows a query to specify user-defined properties for the port. This uses the OWL classification system. Each classifier is a ‘class’ in OWL, and has a URI. One Specify ‘One’ to return only 1 match; Specify ‘All’ to return all matches.

No

Yes

MatchPolicy

Yes

Yes

If all three values are specified for the Name tuple then all ports that implement the single service portType will be returned (if they exist). At least one of the three is required. If any of the three are left blank, then all ports that implement multiple service portTypes will be returned (if a match is found).

Chapter 16. Integrating WSRR with WMB

795

Note: While the Name tuple, user properties and Classification fields are not mandatory, a warning will be issued if none of the three properties are set. Figure 16-5 shows a sample properties dialog for the SRRetrieveITService node.

Figure 16-5 SRRetrieveITService node properties

Node terminals
Table 16-7 shows the terminals for this node.
Table 16-7 SRRetrieveITService node terminals Terminal Name In Out Description Node input terminal Node output terminal

796

WebSphere Service Registry and Repository Handbook

Terminal Name Failure Nomatch

Description Node failure terminal (where exceptions are thrown) If no entity is found, based on the specified values, the message is propagated to this terminal.

Operational sequence
The following is the sequence that this node follows: 1. Receives a message 2. Retrieves the IT service endpoint information from WSRR using the specified query string 3. If one or more matches can be found: a. If “MatchPolicy” is “One” and a single endpoint is matched, the proper endpoints will be set in the domain so that existing WMB built-in nodes can be used to invoke the service. b. If “MatchPolicy” is “All”, adds all matching endpoints information to the message instance, leaving all other message content unchanged. c. Propagates this to the ‘out’ terminal 4. If a match cannot be found: a. Propagates the input message to the ‘nomatch’ terminal 5. On failure a. Adds ‘FailInfo’ to the unchanged message content leaving all other message elements unchanged

16.5.6 SRRetrieveEntity node
This node is a generic node that retrieves the metadata related with a WSRR entity. It does not perform additional filtering or selection, other than that specified by the property matching. It also does not resolve endpoints, do content based routing, or set domain context for execution of the target service. It is up to the message flow developer to perform all those functions. Note: This node is independent of any other domain context.

Node properties
The properties on the node are: name tuple, template, user properties, classification and MatchPolicy. These are shown in Table 16-8.

Chapter 16. Integrating WSRR with WMB

797

Table 16-8 SRRetrieveEntity node properties Property Name Name tuple (portType name, namespace and version) Template Mandatory No Configurable Yes Default Values Property Values Name tuple that uniquely defines a WSRR defined WSDL service portType.

No

Yes

The template or type of the entity as defined in WSRR. Allows a query to specify user-defined properties for the port. This uses the OWL classification system. Each classifier is a ‘class’ in OWL, and has a URI. One Specify ‘One’ to return only 1 match; Specify ‘All’ to return all matches.

User properties Classification

No

No

No

Yes

MatchPolicy

Yes

Yes

If all three values are specified for the Name tuple then all ports that implement the single service portType will be returned (if they exist). At least one of the three is required. If any of the three are left blank, then all ports that implement multiple service portTypes will be returned (if a match is found). Note: While the Name tuple, template, user properties and Classification fields are not mandatory, a warning will be issued if none of the four properties are set. Figure 16-6 on page 799 shows a sample properties dialog for the SRRetrieveEntity node.

798

WebSphere Service Registry and Repository Handbook

Figure 16-6 SRRetrieveEntity node properties

Node terminals
Table 16-9 shows the terminals for this node.
Table 16-9 SRRetrieveEntity node terminals Terminal Name In Out Failure Description Node input terminal Node output terminal Node failure terminal (where exceptions are thrown)

Chapter 16. Integrating WSRR with WMB

799

Terminal Name Nomatch

Description If no entity is found, based on the specified values, the message is propagated to this terminal.

Operational sequence
The following is the sequence that this node follows: 1. Receives a message 2. Retrieves the entity metadata information from WSRR using the specified query string 3. If one or more matches can be found: a. If “MatchPolicy” is “One” adds a single piece of metadata information to the message instance, leaving all other message content unchanged. b. If “MatchPolicy” is “All”, adds all matching metadata information to the message instance, leaving all other message content unchanged. c. Entity metadata information will be available for additional processing (either by ESQL or a JavaComputeNode) d. Propagates this to the ‘out’ terminal 4. If a match cannot be found: a. Propagates the input message to the ‘nomatch’ terminal 5. On failure a. Adds ‘FailInfo’ to the unchanged message content leaving all other message elements unchanged

16.6 WMB Client Cache for WSRR
This section gives a brief overview of the cache provided in the WMB V6 Client for WebSphere Service Registry and Repository and explains the caching options available for it.

16.6.1 Cache logical topology
The WMB Client’s cache for WSRR entities is composed of both a cache and proxy component, which utilizes the WSRR Web Service API to retrieve and cache data in memory. See also this article on the Requestor side caching pattern for additional details: http://www.ibm.com/developerworks/webservices/library/ws-rscp1/

800

WebSphere Service Registry and Repository Handbook

The proxy provides a basic API and utilizes the cache content to provide efficient access to WSRR content at runtime. The cache itself stores both the query objects (containing a reference to all bsrURI objects that represent the result of the query as returned by WSRR) and the individual WSRR objects along with basic statistics on the objects such as updatedTimestamp, lastAccessedTimestamp and the number of times the object has been accessed from the cache. The logical topology of the WSRR cache can be seen in Figure 16-7.

Message Broker Specific WSRR Nodes

WSRR Cache

WSRR

WSRR Proxy API

Proxy (Cache) Configuration WSRR
WSRR Web Service API Notification Publish

WSRR Proxy & Cache Cache Synchronize

WSRR EJB Client

JMS Pub/Sub

Notification Subscribe

Figure 16-7 WSRR cache logical topology

16.6.2 Cache loading strategy
The cache loading strategy determines how and when content from WSRR is retrieved and populated in the cache. The proxy/cache configuration file supplies data on the loading method to be used by the proxy. This file is supplied to the proxy by the client environment through an API call. There are three options of loading available to be specified. No Load The first option is to specify no load wherein the cache instance is completely bypassed. The proxy serves as nothing more than a pass-through in accessing WSRR. None of the query results obtained from WSRR are cached and all queries are sent to WSRR for processing. Lazy Load The second option is to specify lazy load wherein the cache instance is populated with an object from WSRR when the object is queried for the first

Chapter 16. Integrating WSRR with WMB

801

time by a client. Thereafter the object is stored up in the cache and returned from the cache for subsequent queries for the same object. The object is retained in the cache until the object is invalidated due to synchronization or other means. Preload The third option is to specify preload wherein the cache instance is populated with objects from WSRR prior to the object being queried by a client. The cache configuration file controls the objects to be preloaded by specifying a classification or a set of classifications – objects belonging to which are queried and pre-loaded by the proxy into the cache. The object is retained in the cache until the object is invalidated due to synchronization or other means.

16.6.3 Setting cache load strategy
No Load Set the needCache option to false (needCache=false) in the wsrr.properties file. Preload Set the needCache option to true (needCache=true) in the wsrr.properties file. To specify the WSRR entities that will be preloaded, specify the predefinedQueries value required to load the entities needed. The preload option requires the cache update synchronization flow be installed. Lazy Load Set the needCache option to true (needCache=true) in the wsrr.properties file and set the predefinedQueries to blank. The lazy load option does not require that the cache update synchronization flow is installed (but it is recommended).

16.6.4 Cached items
Entities stored in the cache are indexed by query string and by name tuple (name, namespace, and version). Before issuing a query against WSRR, the proxy will check the cache to see if it contains entities for the exact same query string (name, classification, user property, and so on) or for a specific entity by its unique tuple (name, namespace, and version). If found by either index (query string or tuple), it will return the item, or if not found by either index it will perform a query against WSRR and store the results (indexed by query string and tuple). Entities are stored in the cache only once; however, they may be indexed in multiple ways. For instance, suppose a query returns a specific entity. If a new

802

WebSphere Service Registry and Repository Handbook

and different query is specified, the proxy would not find an existing index for this new query string, and will thus issue the query against WSRR. If the same entity is returned, the existing cached entity will be updated, and a new index created (for the new query string). If a different entity is returned, it is stored in the cache and two indexes are created (query string and tuple).

16.6.5 Cache synchronization
The cache synchronization process is available to keep the data consistent between the cache and WSRR. While the cache is read-only, objects in WSRR could be modified after the object has been cached in the WMB Client cache on the client side. WSRR generates notifications in the form of JMS topics whenever an object in the registry is created, updated or deleted.

16.7 WMB Client support for SOA patterns
The WMB Client nodes support two different styles of uses; one is a set of generic access nodes for WSRR metadata and the other set of nodes support the Router and Transcoder patterns. These patterns are explained below.

16.7.1 Transcoder pattern
From “Service Oriented Architecture (SOA) Compass” by IBM Press, ISBN 0-13-187002-5: “The transcoder pattern changes the format of the message payload without changing its logical content. For example, it may convert a SOAP message into a JMS/Text message with an XML payload that matches the body of the SOAP message (possibly by mapping SOAP header fields into JMSProperties). Mediations which conform to this pattern can often be created automatically when there is a clear definition of the two formats and of the relationship between them.” This pattern requires update access to the payload of the message.

Context
As seen in the SOA Characteristics section in the SOA Compass book, the characteristics of platform, location, protocols, and versioning all need to be understood, to one degree or another, by the requesters of a specific service. Enterprises may choose different ways to implement a service and the implementation may change over the life of the service.

Chapter 16. Integrating WSRR with WMB

803

Services come online, to provide new functionality or replace existing services (for example, that have become obsolete). These changes, depending on the implementation, can adversely affect clients. Use of the pattern allows the Enterprise to reduce the impact to clients and increase the flexibility of their (the Enterprise) choices for implementing services.

Forces
If the requester and provider are both under full control of the Enterprise, then establishment of a unified protocol (location, and so on) and the planning and scheduling of changes (that affect both parties) can be largely controlled. This can lead to a preferred communication between the requester and provider, which may result in a performance increase. However, if both the requester and provider are not under full control of the Enterprise, then isolating the requester from the implementation details can provide benefits to the provider (the Enterprise) and the requester. Multiple implementations of the same semantic service provide distinct benefit to the Enterprise. For instance, the same semantic service may be provided by both a SOAP/HTTP implementation and a XML/MQ implementation; without the requester knowing these details. New versions of a service may require new (or different) transformations. For instance, a service’s change in implementation from SOAP/HTTP to XML/MQ for performance reasons or a new version of a service coming online requiring a different signature can be performed with no impact to the client.

Solution
This is a WSRR virtual service in that it does not provide business functionality; however, it does represent the exposed business functionality and implements the pattern. For instance, suppose an enterprise provides a service that represents functionality for a customer or about a customer. The functional and non-functional specification (the functionality delivered and quality of availability) defines the service, at least at the business partnership level. Regardless of the implementation of the service, the business can specify the functionality that a service will provide and the quality of that service and/or the availability of that service. Suppose this service is implemented as a Web Service; however, in order to provide a specific quality of service it is re-implemented as a “MQ-based service”. In other words, the implementation of the service has at least changed the protocol, message format (probably), and location (service executable endpoint). This change will require changes to all requesters, internal and

804

WebSphere Service Registry and Repository Handbook

external. Coordination of the change(s) will impact the both requesters and providers in multiple ways. Within an Enterprise Service Bus the Transcoder mediation pattern provides (or represents) a common semantic for the business service. It is responsible for determining which operational service to invoke to execute the request, based on message context, message content, and/or other data. Depending on this information the mediation can transform the message (as required), change the destination (location), and choose which operational service to use to fulfill the request. New IT services can be brought online, old ones retired, and the complete service lifecycle followed without affecting the clients. In effect the mediation encapsulates the underlying operational service implementation(s) into a single semantic service that uses a single canonical interface. The mediation can determine if there is a preferred implementer, use a different operational service provider to provide a different QoS to meet specific SLAs, or route to a specific service for other business or technical reasons. Figure 16-8 shows an enterprise’s view of the virtual service (ESB mediation). In the figure all the IT service providers are assumed to provide the same semantics, but maybe using different syntax.

ESB mediations control which IT service provider is invoked

Client
Virtual Service (Mediation)

MQ based Service Provider

Both use single, wellknown location All content in XML

Web Service Based Service Provider

Internal Requester

Web Service Based Service Provider

Figure 16-8 ESB Mediation Pattern

Chapter 16. Integrating WSRR with WMB

805

Consequences
A direct consequence of the ESB Transcoder pattern is that there is a single canonical semantic representation of the exposed service, regardless of the actual implementation of the operational service. This semantic could be a Web Service that is exposed to requesters or some other interface type. This virtual service is responsible for all transformations required to invoke the operational service. Another consequence is that this virtual service needs to have each supported operational service “known to it”. This means that relationships between this service, that implements the transcoder pattern, and the operational service that actually provides the functionality must be established. This can be ‘hard-coded’ into this service, or can be externalized in WSRR.

Implementation
The most flexibility is obtained by externalizing the relationships between the virtual service (that implements the transcoder pattern) and the operational services. The virtual service that implements the transcoder pattern contains relationships to the operational services. The relationship’s metadata is used by this service in order to determine which relationship, and thus which targeted operational service, to select. In the logical model, the metadata that is used in the selection is called endpointAlias (see the Endpoint object). However, the actual metadata could be much more complex. The Routing Label relationship property is used by the transcoder service to branch or execute a specific piece of functionality. For instance, a message may need to be transformed before it can be passed to a specific operational service. Refer to 16.8, “Setting up your environment for the patterns” on page 809 on how to realize this pattern in WSRR and using the pattern-based nodes in WMB.

16.7.2 Router pattern
The router pattern changes the intended route of a message, selecting between the service providers associated with the mediation. Simple selection would include routing between two versions of a service, with the percentage routed to the new version being increased by the system administrator as confidence in its capabilities increases. Another example is routing to a local version of a service until it becomes overloaded, then routing to a more expensive remote service. This latter case could also take the importance of the message into consideration, as indicated by a “gold” user status or the size of a purchase, for

806

WebSphere Service Registry and Repository Handbook

example. This pattern requires update access to the context of the message and read access to the payload if it is needed for the routing-selection criteria. Another way for the Enterprise to achieve looser coupling is to use a router. The ‘router’ really is intended to do what classically has been called distribution/aggregation, that is, parsing the incoming request, sending individual requests to appropriate service, handling responses. Response aggregation can occur with synchronous protocols or can be avoided with asynchronous protocols. Internal requesters normally interface with the virtual service that performs the mediation. However, they could interface with the router virtual service. The router can handle multiple message formats (for example, XSD schemas) and perhaps even aggregated messages.

Context
As seen in the SOA Characteristics section in the SOA Compass book (“Service Oriented Architecture (SOA) Compass” by IBM Press, ISBN 0-13-187002-5), the characteristics of platform, location, protocols, and versioning all need to be understood, to one degree or another, by the requesters of a specific service. Enterprises may choose different ways to implement a service and the implementation may change over the life of the service. Services come online, to provide new functionality or replace existing services (for example, that have become obsolete). These changes, depending on the implementation, can adversely affect clients. Use of the pattern allows the Enterprise to reduce the impact to clients and increase the flexibility of their (the Enterprise) choices for implementing services.

Forces
If the enterprise wants to provide a single (or small set) of access points. The router provides dynamic context routing, commonly using the message content to aid that routing process. If the enterprise wants to perform specific routing decisions, for instance combining message content with service metadata to determine preferred machines, service locations, and so on. If the enterprise needs to route certain requesters to different services, perhaps to fulfil a SLA.

Solution
This is a virtual service in that it does not provide business functionality; however, it does represent the exposed business functionality. In this case it is usually a single gateway for all services or for a classification of services. For instance,

Chapter 16. Integrating WSRR with WMB

807

suppose an enterprise provides three levels of service; standard, gold, and platinum. Each of these QoS levels could be a separate router location. In affect the mediation, router service, encapsulates a set of services into a single location. Figure 16-9 shows an enterprise’s view of the virtual service (ESB router).

Virtual Service

Client

Distribution / Aggregation Virtual Service (Router)

Virtual Service

Logically shown as two different ESBs, but could be physically the same ESB

Internal Requester
Virtual Service

Figure 16-9 ESB Router Pattern

Consequences
A direct consequence of the ESB Router pattern is that there is a single (or small set) location for requesters to access. The enterprise can then determine how to process a specific request. For instance, when a new version of a service comes online, the enterprise may choose to route a specific list of requesters (perhaps the beta users) to the new version. Another consequence is that this virtual service needs to have a relationship to each service it is capable of routing to; whether the service is another virtual service or an operational service. If this routing needs to be dynamic, then the necessary metadata needs to be externalized.

Implementation
The most flexibility is obtained by externalizing the relationship metadata between the router virtual service and the service to which it can route.

808

WebSphere Service Registry and Repository Handbook

Refer to 16.8, “Setting up your environment for the patterns” on page 809 on how to realize this pattern in WSRR and using the pattern-based nodes in WMB.

16.8 Setting up your environment for the patterns
The configuration files necessary to set up the patterns in WSRR are provided with the WMB V6 Client for WebSphere Service Registry and Repository. They can be found in the following directory: \Tests Where is the WMB Client installation directory. In the following structure: \Tests\ClientForTestExecution - Tools to run this example scenario \Tests\SampleMessages - Example messages to use in the WMB Message Flow \Tests\WASTestWebServices - Example Web services to deploy to WebSphere \Tests\WMBTestFlows - WMB Message Flows corresponding to this scenario \Tests\WSRRTestEntities - WSRR configuration scripts \Tests\WSRRTestEntities\Classifications - an OWL file corresponding for this scenario \Tests\WSRRTestEntities\Deployment - deployment scripts to setup this scenario in WSRR \Tests\WSRRTestEntities\GUIConfiguration Configuration files to add the new perspective to the WSRR UI \Tests\WSRRTestEntities\SampleVirtualServices example services to add to WSRR For the benefit of documenting the configuration procedure we used two machines: itso-wsrr - WSRR and will also host the demo Web services

Chapter 16. Integrating WSRR with WMB

809

itso-wmb - WMB and WMQ You could host everything on a single machine if desired, although obviously the machine may need to be slightly more powerful in that scenario.

16.8.1 Configuring WMB for the patterns
The following steps will guide you through how to configure your WMB and WSRR environments to support the Mediation and Router SOA Patterns. 1. Edit \Tests\WSRRTestEntities\Deployment\setenv.bat and set all variables as necessary for your environment. You will almost definitely need to edit the SUPPORTPAC_HOME and PAR_FILE_DIR variables. 2. From a WMB Command Console prompt run the following: \Tests\WSRRTestEntities\Deployment\deploy_local.b at. That script will then perform the following steps: – Create MQ queues for the sample test flows – Deploy the WMB ServiceRegistryMessageBrokerNodes.par file – Copy required jars to the WMB working path shared-classed directory. (This step is not actually necessary, since we did this manually in “Configure the WMB runtime shared-classes” on page 784, however it will not do any harm for the copy to run again since the same file will be copied.) – Deploy the sample test flows BAR file to the broker – Deploy the cache update BAR file to the broker

16.8.2 Configuring WSRR for the patterns
We now need to configure WSRR, this will entail loading a new ontology system for the new classifications and some new UI customizations. Note: The UI customizations necessary for the WMB Patterns are used as the demonstration scenario in Chapter 10, “Customizing the Web UI” on page 381. These steps do not need to be performed on the WSRR machine, the WSRR CLI can connect to a remote WSRR server, however for reasons of practicality we will be running the CLI on the WSRR server itself.

810

WebSphere Service Registry and Repository Handbook

1. We need to configure the WSRR CLI before we use it to load the new ontology and UI configuration files into WSRR. Edit \CLI\config\wsrrcli.conf and ensure all settings are set correctly for your environment. If you have an unsecured WSRR installation then configure the “open” settings, since our WSRR server has WebSphere security turned on we will configure the “secure” settings. The relevant portion of wsrrcli.conf for our environment can be seen in Example 16-2.
Example 16-2 Sample wsrrcli.conf configuration file

## sample secure site -- alias "secure" # EJB connection configuration secure.java.naming.provider.url = iiop://localhost:2809 secure.com.ibm.CORBA.ConfigURL = file://c:/Progra~1/IBM/WebSphere/AppServer/profiles/default/properties/sas .client.props secure.java.security.auth.login.config = file://C:/progra~1/IBM/WebSphere/AppServer/profiles/default/properties/wsj aas_client.conf # MBean connection configuration parameters secure.host = localhost secure.port = 8880 secure.type = SOAP secure.securityEnabled = true secure.javax.net.ssl.trustStore = C:/progra~1/IBM/WebSphere/AppServer/profiles/default/etc/DummyClientTrustF ile.jks secure.javax.net.ssl.keyStore = C:/progra~1/IBM/WebSphere/AppServer/profiles/default/etc/DummyClientKeyFil e.jks secure.javax.net.ssl.trustStorePassword = WebAS secure.javax.net.ssl.keyStorePassword = WebAS 2. If you are running the WSRR CLI on a different machine to the one where the WSRR client is installed, then copy the \Tests directory to the WSRR CLI machine. In our case we copied the entire directory to the WSRR CLI machine and placed it here: C:\Program Files\IBM\WMB-WSRRClient 3. The MQ connection details are defined in \Tests\WSRRTestEntities\SampleVirtualServices\scr ipts\Constants.py. Check that the settings in that file are correct, but do NOT change the values for the classifications in Constants.py though.

Chapter 16. Integrating WSRR with WMB

811

4. Edit \Tests\WSRRTestEntities\SampleVirtualServices\cre ate_sample_services.bat (in our case on the WSRR CLI machine). Make sure the ALIAS is set to the correct alias from your wsrrcli.conf, in our case “secure”. If you have security turned on then make sure the USER_ID and PASSWORD are also set correctly to a user ID that can access WSRR. 5. Edit \Tests\WSRRTestEntities\SampleVirtualServices\Dem oCustomer.wsdl and \Tests\WSRRTestEntities\SampleVirtualServices\Dem oVehicle.wsdl (in our case on the WSRR CLI machine). Make sure the wsdlsoap:address location at the bottom of the files is set to the correct hostname and port for the machine you are deploying the DemoServiceEAR to. In our case that is the WSRR machine itself. You may also need to change it to https if you are using WebSphere security. 6. Run the following script and if prompted enter the correct userID and password for a user able to access WSRR: \Tests\WSRRTestEntities\SampleVirtualServices\cre ate_sample_services.bat 7. Edit \Tests\WASTestWebServices\deploy_DemoServiceEAR.b at (in our case on the WSRR CLI machine). Change WAS_BIN_HOME to be the correct path to your WebSphere bin directory. If you have security turned on then make sure the USER_ID and PASSWORD are also set correctly to a user ID that can access WSRR. 8. Change directory to \Tests\WSRRTestEntities\GUIConfiguration Run the following command: “\CLI\wsrrcli.bat” -a secure -c “\CLI\config\wsrrcli.conf” -u wasadmin -p passw0rd -w “/profiles/default” Where is your WSRR installation directory and is your WebSphere Application Server installation directory. Replace “secure” with the name of the alias you are using in wsrrcli.conf (normally open or secure). Also replace wasadmin and passw0rd with the correct credentials for your WSRR installation. It may prompt you for a username and password - if so enter the user ID and password for your WSRR WebSphere installation. Once complete it should have reported the installation of numerous configuration files.

812

WebSphere Service Registry and Repository Handbook

9. Restart WebSphere on the WSRR machine to pick up the new GUI configuration files. Once done you should see two new perspectives in the WSRR UI - “MB Pattern Admin” and “MB Pattern User”. 10.Run the following script: \Tests\WASTestWebServices\deploy_DemoServiceEAR.b at 11.Edit \Tests\WSRRTestEntities\Deployment\createJmsEnpoi ntResources.bat (in our case on the WSRR CLI machine). Change WAS_HOME to be the correct path to your WebSphere AppServer directory. If you have security turned on then make sure the WAS_USERNAME and WAS_PASSWORD are also set correctly to a user ID that can access WSRR. If you are not security then set both WAS_USERNAME and WAS_PASSWORD to be ““. Note: If your path contains a space character then you will also need to replace both references to “%~dp0” with “%~dps0” in createJmsEnpointResources.bat. Otherwise the script will not run correctly and will report errors, such as “Cannot find c:\Program”. 12.Run the following script: \Tests\WSRRTestEntities\Deployment\createJmsEnpoi ntResources.bat

16.8.3 Configure the test client
On the WMB machine edit \Tests\ClientForTestExecution\setEnv.bat and ensure JAVA_HOME is set correctly. Note: If your path contains a space character then you will also need to replace references to “%~dp0” with “%~dps0” in all the scripts in the ClientForTestExecution directory. Otherwise the scripts will not run correctly.

16.8.4 Run the tests
On the WMB machine you should now be able to run the supplied test scripts to verify that the flows do indeed work and that WMB can connect to WSRR and retrieve data.

Chapter 16. Integrating WSRR with WMB

813

There are five test scripts provided all in the \Tests\ClientForTestExecution directory. Run each of the scripts from a Windows command prompt.

run_addVehicle.bat
This script will invoke the TestFlow with the vehicle message. It outputs a trace file in C:\VirtualService.log if you need to debug any problems. Example 16-3 shows an example of the type of output you should get back from running the script.
Example 16-3 run_addVehicle.bat example output

*** invoke test flow with message_vehicle.xml Sending message to http://localhost:7080/DemoSR/services/TestFlow Getting response >>> A vehicle description Completed in 9094 ms. C:\Program Files\ibm\MQSI\WMB-WSRRClient\Tests\ClientForTestExecution>pause Press any key to continue . . . Figure 16-10 on page 819 shows the TestFlow message flow as used by run_addVehicle.bat. It is also described in more detail in “TestFlow” on page 818.

run_testCustomer.bat
This script will invoke the TestFlow with the customer message. It outputs a trace file in C:\VirtualService.log if you need to debug any problems. Example 16-4 shows an example of the type of output you should get back from running the script.
Example 16-4 run_testCustomer.bat example output

*** invoke test flow with message_customer.xml Sending message to http://localhost:7080/DemoSR/services/TestFlow Getting response >>>

814

WebSphere Service Registry and Repository Handbook

 DemoCusto mer.updateCustomer(A customer description) Completed in 12172 ms. Press any key to continue . . . Figure 16-10 on page 819 shows the TestFlow message flow as used by run_testCustomer.bat. It is also described in more detail in “TestFlow” on page 818.

run_testEntityFlow.bat
This script will invoke the EntityTestFlow. It outputs a trace file in C:\RetrieveEntity.log if you need to debug any problems. Example 16-5 shows an example of the type of output you should get back from running the script.
Example 16-5 run_testEntityFlow.bat example output

Sending message to http://localhost:7080/DemoSR/services/EntityTestFlow Getting response >>> Found 1 Entity(ies)!<wsp:Policy wsu:Id="RMAssertion" TargetNamespace="http://mb.sr.eis.ibm.com" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss -wssecurity-utility-1.0.xsd" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"& gt; <wsp:ExactlyOne> <wsp:All> <wsrm:RMAssertion><wsrm:InactivityTimeout Milliseconds="600000"/><wsrm:BaseRetransmissionInterval Milliseconds="3000"/><wsrm:ExponentialBackoff/><w

Chapter 16. Integrating WSRR with WMB

815

srm:AcknowledgementInterval Milliseconds="200"/></wsrm:RMAssertion> </wsp:All> </wsp:ExactlyOne> </wsp:Policy> Completed in 1766 ms. C:\Program Files\ibm\MQSI\WMB-WSRRClient\Tests\ClientForTestExecution>pause Press any key to continue . . . Figure 16-12 on page 822 shows the EntityTestFlow as used by run_testEntityFlow.bat, the message flow is also described in more detail in “EntityTestFlow” on page 822.

run_testITService.bat
This script will invoke the ITServiceTestFlow with the customer message. It outputs a trace file in C:\SRRetrieveITService.log if you need to debug any problems. Example 16-6 shows an example of the type of output you should get back from running the script.
Example 16-6 run_testITService.bat example output

*** invoke test flow with message_customer.xml Sending message to http://localhost:7080/DemoSR/services/ITServiceTestFlow Getting response >>> DemoCusto mer.updateCustomer(A customer description) Completed in 3797 ms. Press any key to continue .

816

WebSphere Service Registry and Repository Handbook

Figure 16-11 on page 821 shows the ITServiceTestFlow message flow as used by run_testITService.bat, the message flow is also described in more detail in “ITServiceTestFlow” on page 821.

run_testMQ.bat
This script will invoke the TestFlow with the MQ message. It outputs a trace file in C:\VirtualService.log if you need to debug any problems. Example 16-7 shows an example of the type of output you should get back from running the script.
Example 16-7 run_testMQ.bat example output

*** invoke test flow with message_mq.xml Sending message to http://localhost:7080/DemoSR/services/TestFlow Getting response >>> Message submitted to MQ service for processingWBRK6_DEFAULT_ QUEUE_MANAGERSERVICE.INPUT414d51205742524b365f44454641554ce4fd7345200014034 14d51205742524b365f44454641554ce4fd734520001404 user id password UpdateAll mq message data Completed in 187 ms. C:\Program Files\ibm\MQSI\WMB-WSRRClient\Tests\ClientForTestExecution>pause Press any key to continue . . . Figure 16-10 on page 819 shows the TestFlow message flow as used by run_testMQ.bat. It is also described in more detail in “TestFlow” on page 818.

Chapter 16. Integrating WSRR with WMB

817

16.8.5 Test message flows
The following sections describe each of the three message flows used in this scenario in more detail. More information about the WMB built-in nodes mentioned below can be found at this Web site: http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/topic/com.ib m.etools.mft.doc/ac04550_.htm

TestFlow
Figure 16-10 on page 819 shows the TestFlow message flow.

818

WebSphere Service Registry and Repository Handbook

Figure 16-10 TestFlow message flow

The message flows through the TestFlow Message Flow as follows: 1. The starting point for the message is the “HTTP Input” node which is listening for a message. 2. The message is then used to trigger the retrieval of a Web service from WSRR in the “SR Get Service” node, this checks WSRR for a service which has the same verb as the input message to this flow. 3. There is then a “TraceService” node which outputs some debug information to a file.

Chapter 16. Integrating WSRR with WMB

819

4. The “Route to mapping” node then routes the message based on the “SR-Route-To-Label” environment variable in the WMB LocalEnvironment. This value was set by the SRGetVirtualService node. If it contains “vehicle” then the message is routed to the “Label-Vehicle” node, if it contains “customer” then it is routed to the “Label-Customer” node. Otherwise if it contains “ALL” it is routed to the “Label-ALL” node. 5. If it was a customer message then it now proceeds through the “map customer” node, this generates a new message in a different format based on the input message. If it was a vehicle message then it now proceeds through the “map vehicle” node, this also generates a new message in a different format based on the input message. 6. All three types of message now flow to the “SR Process Service” node where the message is processed. This node is used to create the proper format for the target service invocation. 7. The message then passes through the “Route to Dispatcher” node which will route the message based on the content of the SR-Protocol-Label environment variable in the WMB LocalEnvironment. If it contains “URLEndpoint” the message is routed to the “Label-URLEndpoint” node, messages containing “MQEndpoint” go to the “Label-MQEndpoint” node, and those containing “JMSEndpoint” are routed to the “Label-JMSEndpoint” node. 8. The service in each message is then dispatched using the relevant SRDispatchVirtualService node for each type of message. The SRDispatchVirtualService nodes are used to establish the endpoint of the target service. a. URLEndpoint messages retrieve the HTTP service information from WSRR and then invoke it using the “HTTP Request” node. This then gives a HTTP Service Reply. b. MQEndpoint messages retrieve the MQ service information from WSRR and then put a MQ message on the appropriate MQ queue. The “Display MQ Submission” compute node is then called which sets the relevant parameters for the MQ Destination queue from variables in the LocalEnvironment. The final node in the flow for MQ messages gets the “MQ Service Reply”. c. JMSEndpoint messages retrieve the JMS service information from WSRR and then publish a JMS message using that information. The “Display JMS Submission” compute node is then called which sets some Result parameters based on variables in the LocalEnvironment. The final node in the flow for JMS messages gets the “JMS Service Reply”.

820

WebSphere Service Registry and Repository Handbook

ITServiceTestFlow
Figure 16-11 shows the ITServiceTestFlow message flow.

Figure 16-11 ITServiceTestFlow message flow

This message flow retrieves a PortType from WSRR in the following stages: 1. The starting point for the message is the “HTTP Input” node which is listening for a message. 2. The message is then used to trigger the retrieval of a service port type from WSRR in the “SRRetrieveITService” node, this checks WSRR for a port type called “DemoCustomer” with a given namespace and which has a user property “policy” set to “RM”, and “country” set to “China”. It also must have the specified classification (InitialState1). 3. If the node fails to retrieve the service then the “Failure” compute node is called which will set the appropriate result status. 4. If the “SRRetrieveITService” node did not match a service with the appropriate criteria then the “Post No Match” compute node is called which again sets the appropriate result status. 5. If the document was found then a “Customer Mapping” node is called which creates a new message based on the original one. 6. A “Trace” node is then called to output some appropriate debug information to a file. 7. The “HTTP Request” node then opens a connection to the specified URL. 8. Regardless of the path through the flow, it comes to an end with the “HTTP Reply” node which will output the reply message to the Web services client (or the console in the case of the test scripts).

Chapter 16. Integrating WSRR with WMB

821

EntityTestFlow
Figure 16-12 shows the EntityTestFlow message flow.

Figure 16-12 EntityTestFlow message flow

This message flow retrieves a Policy document from WSRR in the following stages: 1. The starting point for the message is the “HTTP Input” node which is listening for a message. 2. The message is then used to trigger the retrieval of a policy document from WSRR in the “SRRetrieveEntity” node, this checks WSRR for a document called “RMAssertionPolicy” with a given namespace and which has a user property “grade” set to “gold”. 3. If the node fails to retrieve the policy document then the “Display Failure” compute node is called which will set the appropriate result status. 4. If the “SRRetrieveEntity” node did not match a policy document with the appropriate criteria then the “Display No Match” compute node is called which again sets the appropriate result status. 5. If the document was found then a “Trace” node is called to output some appropriate debug information to a file. 6. Then the “Display Entity Content” node is called to output the Policy document content. 7. Regardless of the path through the flow, it comes to an end with the “HTTP Reply” node which will output the reply message to the Web services client (or the console in the case of the test scripts).

822

WebSphere Service Registry and Repository Handbook

16.8.6 Optional: Importing the test scenario into WMB toolkit
If you want to see how the provided message flows work, or customize them in any way then the provided files can be imported into your WMB Toolkit. 1. Create a Server project 2. Import into that project from the provided zip file: \Tests\WMBTestFlows\WSRRNodes_TestFlow_PIC.zip 3. Create a new Message Broker Archive selecting the projects you just imported 4. Deploy the new BAR file to your Broker execution group. Refer to the WMB Information Center if you need more help with any of these stages: http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/index.jsp

Chapter 16. Integrating WSRR with WMB

823

824

WebSphere Service Registry and Repository Handbook

17

Chapter 17.

Integrating WSRR with CICS
This chapter describes how to integrate WSRR with CICS and the possible ways this combination can be used. This chapter discusses the following: 17.1, “Introduction” on page 826 17.2, “What is CICS?” on page 827 17.3, “Installation” on page 831 17.4, “Publishing WSDL files from z/OS batch to WSRR” on page 834 17.5, “Publishing WSDL files from CICS to WSRR” on page 842 17.6, “Retrieving WSDL files from WSRR using z/OS batch” on page 847 17.7, “Security considerations” on page 854

© Copyright IBM Corp. 2007. All rights reserved.

825

17.1 Introduction
Customer Information Control System (CICS) can be integrated with WebSphere Service Registry and Repository through an additional CICS SupportPac (CA1N). This SupportPac provides the tools to streamline the job of registering, discovering and governing Web services resources generated from CICS applications. Together these tools provide additional support for organizations intending to move to a Service-Oriented Architecture (SOA). The new tools enable Web Services Description Language (WSDL) files derived from CICS application interfaces to be automatically published from the CICS z/OS environment to WSRR where they can be accessed by other Web applications. The tools also enable retrieval of Web Service Description Language files from WSRR, into the z/OS environment where they can be modified and ‘reverse engineered’ into new CICS High Level Language applications (HLLs). The SupportPac includes: CWSP - a CICS transaction to publish a WSDL document to WSRR for each of your CICS programs that are Web service providers DFHWS2SR - a z/OS batch utility to publish a WSDL document to WSRR DFHSR2WS - a z/OS batch utility to read a WSDL document from WSRR When enabling your CICS application to be a Web service provider, you can use the CICS Web services assistant (DFHLS2WS) provided with CICS TS V3.1 to generate the WSDL interface from your programs high level language structures. Use this SupportPac to automate the publication of this WSDL directly from z/OS to WSRR. When developing a CICS application that invokes a Web service, use this SupportPac to automate the retrieval of the WSDL document from WSRR directly to z/OS. You can then use the CICS Web services assistant (DFHWS2LS) to generate the high level language structures needed to pass data to CICS when invoking the Web service. Note: CICS SupportPac CA1N can be downloaded from: http://www.ibm.com/support/docview.wss?rs=1083&uid=swg24013629

826

WebSphere Service Registry and Repository Handbook

17.2 What is CICS?
This section provides a short overview of the products in the CICS portfolio. It also looks at why the ability to interoperate CICS with WebSphere is important in the context of using CICS transactional applications as Web services within an SOA (service oriented architecture). Finally the section explains why WSRR is central to both application development and the runtime in an SOA that implements CICS and WebSphere.

17.2.1 CICS product portfolio
CICS is IBM Customer Information Control System and is a major family of IBM application servers, connectors and tools for delivering high volume transaction processing, management and connectivity. Since being introduced over 30 years ago, CICS has been the power behind worldwide transaction processing systems that handle billions of transactions per day. CICS is used in financial, insurance, banking, e-commerce and other transactional environments where high throughput, security, scalability and reliability are critically important. CICS runs primarily on IBM mainframe systems under the z/OS or z/VSE™ operating systems but is also available as a distributed product for use on i5/OS®, OS/2®, and as TXSeries® on AIX, Windows, and Linux. The majority of users run CICS on z/OS. CICS transaction processing systems handle online and batch processing, supporting thousands of transactions per second on large mainframe systems such as System z™ and z9™. This capability makes CICS a central part of enterprise computing. Programmers and developers write CICS applications in COBOL, PL/I, C, C++, IBM Basic Assembly Language, REXX™, and Java.

17.2.2 CICS Transaction Server
CICS Transaction Server is the application server that handles CICS transactions. It provides a mainframe runtime environment for processing high volumes of CICS transactions reliably and securely, in a way that can be scaled to meet changing demands and workloads. CICS Transaction Server also supports the use of CICS applications as service providers or requesters within an SOA. CICS Transaction Server has an associated set of tools used for managing the CICS subsystem (for example CICS Configuration Manager), and for transforming applications (for example CICS Business Event Publisher for MQSeries®).

Chapter 17. Integrating WSRR with CICS

827

17.2.3 CICS tools
The CICS tools play an important role in managing the CICS Transaction Server runtime efficiently. They enable system managers and administrators to analyze and optimize CICS system functionality, performance and efficiency. The CICS tools are designed to increase productivity, reduce costs and ultimately, to improve the customer satisfaction perceived by end-users. The CICS tools enable best practice management, monitoring and control of the CICS subsystem. They also enable transformation of CICS applications so they can be accessed by other systems. The following tools support CICS subsystem management, monitoring and control: CICS Configuration Manager: for managing CICS resource definitions used in multiple CICS systems CICS Interdependency Analyzer: for analyzing the relationships between CICS resources to make management decisions. CICS VSAM Recovery: for recovering corrupted CICS or VSAM data. Session Manager: for managing multiple CICS sessions from a single terminal. CICS Batch Application Control: for managing batch processes that coexist with CICS systems. CICS Performance Analyzer: for offline reporting on CICS system performance. CICS VSAM Copy: for copying CICS data without interrupting users. CICS Online Transmission Time Optimization: for 3270 terminal data stream performance optimization. The following tools support CICS application transformation: CICS Business Event Publisher for MQSeries: for publishing CICS applications and data as events. CICS Interdependency Analyzer: for analyzing relationships between CICS resources to make decisions about transforming them. CICS VSAM Transparency: for migrating VSAM data to DB2 without rewriting it.

17.2.4 CICS connectors
The CICS connectors provide a way of extending existing CICS and TXSeries (the distributed version of CICS) into other operational areas in order to more

828

WebSphere Service Registry and Repository Handbook

fully exploit the resources they use. The connectors enable better performance, scalability, reliability, systems management and security. The CICS connectors are: CICS Transaction Gateway: for rapid deployment of CICS applications into an SOA whilst keeping existing business logic intact. CICS Universal Client: for delivering low-cost, single-user access to CICS across an enterprise. SOAP for CICS: for enabling CICS applications to interact securely and reliably with Web services, independently of platform, environment or application language. MQSeries Integrator Agent for CICS: for application integration with a run time component and a build time component.

17.2.5 CICS TXSeries
TXSeries is designed for running CICS transactions on distributed systems rather than in a mainframe environment. TXSeries has been powering CICS transaction processing on distributed platforms for 10 years. It runs on the AIX, Windows, HP-UX and Solaris operating systems, and features an intuitive Web-based administrative console which has the same look and feel as the WebSphere administrative console. TXSeries also enables services written in COBOL, C, C++, PL/1 and Java, to be integrated into an SOA.

17.2.6 Why interoperate CICS and WebSphere?
From a business viewpoint, interoperation greatly increases the range of commercial possibilities for customers who are using CICS and WebSphere by allowing the tools, applications and runtimes in each environment to make use of resources held in the other. From the CICS customer viewpoint, the transactional programs and applications that have been developed and maintained over the last 20 to 30 years represent a huge investment in time and money with many millions of lines of code usually being involved. By allowing WebSphere to access these valuable resources, they can be modernized, reused and better exploited in modern, flexible SOA architectures. There are two main scenarios where CICS and WebSphere can interoperate: Application development: using tools like WebSphere Developer for System z to develop new CICS applications and to modernize existing CICS

Chapter 17. Integrating WSRR with CICS

829

applications. In addition, using the CICS SupportPac tools to reverse-engineer CICS applications from files held in WSRR. Application runtime: enabling applications in CICS and WebSphere to invoke each other as service providers and service requesters within an SOA implementation.

Application Development
The WebSphere product portfolio contains an important tool for System z application development called WebSphere Developer for System z. WebSphere Developer for System z (formerly called WebSphere Developer for zSeries®) is an integrated application development workbench that runs in Eclipse. The product is specifically designed for developing System z applications (the applications that run on CICS mainframe systems). When a developer uses WebSphere Developer for System z to work with a CICS application, the tool must be able to locate the resources (programs) that make up that application. This is possible because an Eclipse plug-in provides an interface that allows WebSphere Developer for System z to access service metadata held the WSRR in the form of WSDL files. On the CICS side of the development fence, the WSRR SupportPac tools included with CICS Transaction Server enable developers to retrieve application service metadata files (WSDL files) from WSRR, bring them into the CICS z/OS environment, and 'reverse engineer' them into new CICS High Level Language (HLL) applications.

Application Runtime
In an SOA implementation that involves CICS and WebSphere, CICS applications must be able invoke WebSphere applications as service providers (for example applications running in WebSphere Application Server). WebSphere applications must be able to invoke CICS applications as service providers. WSRR plays a key role in an SOA runtime environment because it holds the service metadata information (WSDL files) that enable CICS and WebSphere applications to discover and invoke (call) each other. This is possible because WSDL files derived from CICS application HLL structures are published automatically from the CICS z/OS environment to WSRR. These files can then be accessed by other Web applications that want to invoke their associated applications.

830

WebSphere Service Registry and Repository Handbook

17.2.7 CICS and WebSphere in an SOA
Firstly, a short recap of what an SOA is. SOA is not a product or a runtime environment. It is a business-centric, architectural approach to IT that allows loose coupling of disparate applications as reusable business tasks, processes or services. SOA encourages the use of composite applications that call other functions from multiple sources within and beyond the enterprise, thus supporting horizontal business processes. In an SOA that implements CICS and WebSphere applications (or any other SOA for that matter), good governance is critically important. Good governance enables best practice management, control and exploitation of assets and resources. Put in practical terms, this means allowing developers to easily discover existing services or components so that they can be reused, extended and exploited within new solutions. It also means enabling disparate applications running in CICS and WebSphere (two very different environments) to discover and invoke each other as service requesters or service providers. An SOA that involves CICS and WebSphere therefore depends on having a WSRR which is well structured. The registry must also be supported by a good governance process, and by development staff who are encouraged to reuse existing assets and resources wherever possible.

17.3 Installation
This section describes the tasks you need to perform to download and install the CICS SupportPac, and the software required to run it. This section is aimed at experienced CICS system programmers who are responsible for installing and customizing CICS. Knowledge of downloading files from the internet, uploading files to z/FS, and UNIX commands is assumed. Options for the cp, pax, and chmod commands are detailed in the “z/OS UNIX System Services Command Reference” manual.

17.3.1 Software requirements
To use the SupportPac, the following software products required at the version stated, or later: IBM CICS Transaction Server for z/OS V3.1 The service APAR PK23547 for CICS TS is required to be applied to provide the mapping level 1.2 support.

Chapter 17. Integrating WSRR with CICS

831

IBM SDK for z/OS Java 2 Technology Edition V1.4 IBM WebSphere Service Registry and Repository V6

17.3.2 Downloading and installing the CICS SupportPac
The following steps guide you through downloading and installing the SupportPac. 1. From a workstation, download the ca1n.zip file from the IBM CICS SupportPacs Web site to your workstation: – Browse to the Web site or to the CICS TS V3.1 Information Center Welcome page. http://www.ibm.com/software/htp/cics/tserver/support/ – Click the link “SupportPacs” – Click the link “View all: By Category” – Click the link “CA1N” – Click the link “FTP” – Providing you agree to the terms and conditions shown, click the link “I agree” – Save the ca1n.zip file onto your workstation. 2. Extract the contents of ca1n.zip to a local directory. The directory should contain the following: \ca1n\ca1n.pdf – the SupportPac documentation \ca1n\ca1n.pax.Z – the SupportPac code in the z/OS pax archive format 3. Upload the file \ca1n\ca1n.pax.Z in binary to your z/OS system. For example, from a workstation command shell, enter the following. Substitute “install-directory” with the directory to be used for the SupportPac files on z/FS, such as “/usr/lpp/cicsts/ca1n”. ftp mvs.mysite.com (login with your hostname, userid and password) ftp> ftp> ftp> ftp> ftp> mkdir /install-directory cd /install-directory bin put ca1n\ca1n.pax.Z quit

832

WebSphere Service Registry and Repository Handbook

4. Expand the ca1n.pax.Z file. For example, from a z/OS UNIX shell enter the following: cd /install-directory pax -rvf ca1n.pax.Z 5. Ensure the appropriate permissions and attributes are set for the files in the “install-directory” and its sub-directories. In particular the files in “install-directory/bin” need to have their execution permission set. For example, from a z/OS UNIX shell enter the following: chmod 755 /install-directory/bin/* 6. Copy the CA1N.JCL.XMIT and CA1N.LOAD.XMIT files to datasets. For example, from a z/OS UNIX shell enter the following. Substitute “hlq” for the high-level qualifier to be used for the SupportPac datasets: cp -F bin -P "RECFM=FB,LRECL=80" /install-directory/datasets/CA1N.JCL.XMIT "//'hlq.CA1N.JCL.XMIT'" cp -F bin -P "RECFM=FB,LRECL=80" /install-directory/datasets/CA1N.LOAD.XMIT "//'hlq.CA1N.LOAD.XMIT'" 7. Expand the hlq.CA1N.JCL.XMIT and hlq.CA1N.LOAD.XMIT datasets to libraries. For example, from a z/OS TSO shell enter the following: RECEIVE INDATASET('hlq.CA1N.JCL.XMIT') When prompted with the message “Enter restore parameters...” respond with: DA('hlq.CA1N.JCL') RECEIVE INDATASET('hlq.CA1N.LOAD.XMIT') When prompted with the message “Enter restore parameters...” respond with: DA('hlq.CA1N.LOAD') 8. The hlq.CA1N.JCL.XMIT and hlq.CA1N.LOAD.XMIT datasets can now be safely removed. The following directories and dataset libraries should now exist: /install-directory/ - high level installation /install-directory/bin - z/OS UNIX shell scripts /install-directory/classes - Java class libraries /install-directory/datasets - z/OS datasets /install-directory/docs - documentation /install-directory/licenses - license information /install-directory/pipeline - CICS pipeline configuration

Chapter 17. Integrating WSRR with CICS

833

/install-directory/samples - sample configuration /install-directory/wsbind - CICS WSBIND hlq.CA1N.JCL() - JCL to launch the utilities and sample JCL library hlq.CA1N.LOAD() - program load modules library

17.4 Publishing WSDL files from z/OS batch to WSRR
This section describes how to use the z/OS cataloged procedure DFHWS2SR provided by the SupportPac to publish a Web Services Description Language document stored on z/FS to WSRR together with optional metadata. If you need to first create a WSDL document from your CICS application's high level language structures (copybooks), use the DFHLS2WS procedure provided with CICS TS V3.1. It is possible to call DFHLS2WS followed by DFHWS2SR within the same z/OS batch JCL to keep the WSBind, WSDL, and the WSDL stored in WSRR in step with the copybooks. Figure 17-1 illustrates the components involved in this scenario.

z/OS Batch JCL
Input Parameters: Language, container, end of URI, Provider Application Name, etc... Output Input Language Structures

Input Parameters: WSDL document location, meta data – description, name, version, encoding, user-defined name+value, WSRR server location + security credentials

. . DFHLS2WS Build WSDL and WSBind . file from Language Structure(s) . . . . DFHWS2SR . Publish to WSRR . . log WSBind

WSDL

Web service WSRR API

WSRR

Figure 17-1 Publishing WSDL files from z/OS batch to WSRR

834

WebSphere Service Registry and Repository Handbook

This section is aimed at experienced CICS system programmers who are responsible for installing and customizing CICS. Knowledge of basic UNIX commands and the Java configuration on your system is required. The userid under which the DFHWS2SR procedure is run will need authority to: read files from the SupportPac bin directory (WORKDIR symbolic parameter) read files from the Java product directories (JAVADIR symbolic parameter) read the WSDL file to be published (LOCATION parameter) optionally, read the trust store and key store files (TRUSTSTORE and KEYSTORE parameters) write access to the temporary directory (TMPDIR symbolic parameter) write access the log file (LOGFILE parameter) access to TCP/IP services to send Web services requests to the WSRR server (HOSTPORT parameter) If connectivity to WSRR is required to be via HTTPS, review 17.7, “Security considerations” on page 854.

17.4.1 Running DFHWS2SR
To run the DFHWS2SR procedure you need to write JCL that includes symbolic parameters and input parameters. 1. Customize the template JCL provided in hlq.CA1N.JCL(WSDLPUB) using information in 17.4.2, “Job control statements for DFHWS2SR” on page 837. 2. Submit the JCL. 3. If there are errors reported in the JCL output, check the z/FS log file specified by the LOGFILE parameter for detailed error messages. The following (Example 17-1) is a customized version of hlq.CA1N.JCL(WSDLPUB).
Example 17-1 A customized version of hlq.CA1N.JCL(WSDLPUB)

//WSDLPUB JOB (MYSYS,AUSER),MSGCLASS=H, // CLASS=A,NOTIFY=&SYSUID,REGION=0M //WSDLPUB JCLLIB ORDER=(CICS.CICSTS.CA1N.JCL) // EXEC DFHWS2SR, // JAVADIR='java/IBM/J1.4', // WORKDIR='/usr/lpp/cicsts/ca1n', // TMPDIR='/u/username/tmp', // TMPFILE='WS2SR' //INPUT.SYSUT1 DD *

Chapter 17. Integrating WSRR with CICS

835

LOGFILE=/u/username/tmp/WS2SR.log LOCATION=/usr/lpp/cicsts/cicsts31/samples/webservices/wsdl/placeOrder.wsdl NAME=placeOrder DESC=CICS TS V3.1 Catalog sample – place order service VERSION=3 ENCODING=UTF-8 HOSTPORT=http://wsrr.my-example.server:443 USERNAME=wasadmin PASSWORD=wasadm1n KEYSTORE=/u/username/DummyClientKeyFile.jks KEYPWD=wasadm1n TRUSTSTORE=/u/username/DummyClientTrustFile.jks TRUSTPWD=wasadm1n PROP1NAME=Host PROP1VALUE=IBM CICS Transaction Server PROP2NAME=Publisher PROP2VALUE=CICS SupportPac CA1N */ Example 17-2 is an extract from the log file created by DFHWS2S after submitting the example JACL above in Example 17-1 on page 835.
Example 17-2 DFHWS2S log extract

Value of 'NAME' is 'placeOrder'. Value of 'LOCATION' is '/usr/lpp/cicsts/cicsts31/samples/webservices/wsdl/placeOrder.wsdl'. Value of 'DESC' is 'CICS TS V3.1 Catalog sample – place order service'. Value of 'VERSION' is '3'. Value of 'ENCODING' is 'UTF-8'. Value of 'LOGFILE' is '/u/username/tmp/WS2SR.log'. Value of 'HOSTPORT' is 'http://wsrr.my-example.server:443'. Value of 'USERNAME' is 'wasadmin'. Value of 'PASSWORD' is '********'. Value of 'KEYSTORE' is '/u/username/DummyClientKeyFile.jks'. Value of 'KEYPWD' is '********'. Value of 'TRUSTSTORE' is '/u/username/DummyClientTrustFile.jks'. Value of 'TRUSTPWD' is '********'. Value of 'PROP1NAME' is 'Host'. Value of 'PROP1VALUE' is 'IBM CICS Transaction Server'. Value of 'PROP2NAME' is 'Publisher'. Value of 'PROP2VALUE' is 'CICS SupportPac CA1N'. Starting publish of WSDL document to WSRREndpoint [http://wsrr.my-example.server:443/WSRRCoreSDO/services/WSRRCoreSDOPort ]

836

WebSphere Service Registry and Repository Handbook

Create message [< soapenv:Body>< sdo:datagraph xmlns:sdo="commonj.sdo" xmlns:sdo_1="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/sdo">//@eRootObject/@artefacts.0] CreateResponse [< createReturn>WSRR--c8e644f7.f101e566.3a247853.10defa75aa9.26ec785d.63] Program 'DFHWS2SR' completed SUCCESSFULLY.

17.4.2 Job control statements for DFHWS2SR
JOB Initiates the job. EXEC Specifies the procedure name (DFHWS2SR). DFHWS2SR requires sufficient storage to run a Java virtual machine (JVM). You are advised to specify REGION=0M on the EXEC statement. INPUT.SYSUT1 DD Specifies the input. The input parameters are usually specified in the input stream.

Chapter 17. Integrating WSRR with CICS

837

However, they can be defined in a data set, or in a member of a partitioned dataset.

Symbolic parameters
The following symbolic parameters are defined in cataloged procedure DFHWS2SR: JAVADIR=path Specifies the name of the Java directory that is used by DFHWS2SR. The value of this parameter is appended to /usr/lpp/ giving a complete path name of /usr/lpp/path. TMPDIR=tmpdir Specifies the location of a directory in z/FS that DFHWS2SR uses as a temporary work space. The user ID under which the job runs must have read and write permission to this directory. The default value is /tmp TMPFILE=tmpprefix Specifies a prefix that DFHWS2SR uses to construct the names of the temporary workspace files. The default value is WS2SR WORKDIR=path Specifies the location of the directory in z/FS in which the SupportPac was installed. The user ID under which the job runs must have read permission to this directory.

The temporary work space
DFHWS2SR creates the following three temporary files during execution: tmpdir/tmpprefix.in tmpdir/tmpprefix.out tmpdir/tmpprefix.err Where: tmpdir is the value specified in the TMPDIR parameter tmpprefix is the value specified in the TMPFILE parameter. The default names for the files (when TMPDIR and TMPFILE are not specified), are: /tmp/WS2SR.in /tmp/WS2SR.out

838

WebSphere Service Registry and Repository Handbook

/tmp/WS2SR.err Important: DFHWS2SR does not lock access to the generated HFS file names. Therefore, if two or more instances of DFHWS2SR run concurrently, and use the same temporary workspace files, there is nothing to prevent one job overwriting the workspace files while another job is using them. This can lead to unpredictable failures. Therefore, you are advised to devise a naming convention, and operating procedures, that will avoid this situation. For example, you can use the system symbolic parameter SYSUID to generate workspace file names that are unique to an individual user. These temporary files are deleted before the end of the job.

Input Parameters for DFHWS2SR
These are shown in Example 17-3.
Example 17-3 Input parameters to DFHWS2SR

.-CCSID=Cp037-. >>-+-------------+--+------------+--+----------------+---------------> '-CCSID=value-' '-DESC=value-' '-ENCODING=value-' >----HOSTPORT=scheme://-+-domain name-+-:port number----------------> '-IP address--' >--+-------------------------------+--LOCATION=value--LOGFILE=value-> '-KEYSTORE=value-+--------------+ '-KEYPWD=value-' >--+------------+--+----------------------------------------+-------> '-NAME=value-' +-PROP1NAME=value----PROP1VALUE=value----+ +-PROP2NAME=value----PROP2VALUE=value----+ etc. +-PROP254NAME=value--PROP254VALUE=value--+ '-PROP255NAME=value--PROP255VALUE=value--' >--+-----------------------------------+----------------------------> '-TRUSTSTORE=value-+----------------+ '-TRUSTPWD=value-' .-VERSION=1-----. >--+---------------------------------+--+---------------+---------->< '-USERNAME=value-+----------------+ '-VERSION=value-' '-PASSWORD=value-'

Parameter use
You can specify the input parameters in any order.

Chapter 17. Integrating WSRR with CICS

839

Each parameter must start on a new line. A parameter (and its continuation character, if you use one) must not extend beyond column 72; columns 73 to 80 should contain blanks. If a parameter is too long to fit on a single line, use an asterisk (*) character at the end of the line to indicate that the parameter continues on the next line. Everything (including spaces) before the asterisk is considered part of the parameter. For example: LOCATION=/dir/* placeOrder.wsdl is equivalent to LOCATION=/dir/placeOrder.wsdl A parameter (and its continuation character, if you use one) must not extend beyond column 72; columns 73 to 80 should contain blanks. A # character in the first character position of the line is a comment character. The line is ignored. All keywords and values are case sensitive unless otherwise specified.

Parameter description
CCSID=Cp037|value The character encoding used to read the WSDL file from z/FS. A list of character encodings that can be specified is available in the “Supported Encodings” topic in the Java manuals. For Java 1.4, the character encodings are available from: http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html DESC=value The description of the WSDL used by WSRR to set the “Description” property. ENCODING=value The character set encoding of the WSDL document used by WSRR to set the “Encoding” property. If ENCODING is not specified, WSRR obtains this value from the typically found at the beginning of the WSDL document. HOSTPORT=scheme://{domain name|IP address}:port number The URI of the WSRR server. The scheme can be HTTP or HTTPS. The port number defaults to 80 for the scheme HTTP, and 443 for HTTPS. KEYSTORE=value The fully qualified filename of the Keystore file. KEYPWD=value

840

WebSphere Service Registry and Repository Handbook

The password to decrypt the keystore file. LOCATION=value The fully qualified filename of the WSDL to publish. LOGFILE=value The fully qualified filename into which DFHWS2SR writes its activity log and trace information. DFHWS2SR creates the file (but not the directory structure) if it does not already exist. Normally you will not need to use this file, but it may be helpful to diagnose problems. NAME=value The name of the WSDL used by WSRR to set the “Name” property. If NAME is not specified, WSRR uses the unqualified filename of the WSDL. PASSWORD=value The password to access WSRR. PROP1NAME=value WSRR allows for custom properties to be publish along with WSDL documents. Each custom property has a name and value pair. Up to 255 custom properties can be specified using the format PROPxNAME replacing “x” with a numeric between 1 to 255 in ascending order. Duplicate and blank custom property names should be avoided. PROP1VALUE=value The value of a custom property to set in WSRR. Required if PROP1NAME specified. Similarly, if PROP2NAME is specified, PROP2VALUE is required, and so on. TRUSTPWD=value The password to decrypt the truststore file. TRUSTSTORE=value The fully qualified filename of the truststore file. USERNAME=value The username to access WSRR, and is used by WSRR to set the “Owner” property. VERSION=1|value The version number of the WSDL used by WSRR to set the “Version” property.

Completion Codes
Table 17-1 on page 842 shows the possible completion codes for DFHWS2SR.

Chapter 17. Integrating WSRR with CICS

841

Table 17-1 Completion codes for DFHWS2SR Completion Code 0 4 Meaning OK. The job completed successfully and only Informational messages have been issued. Input Error. The job did not complete successfully. One or more error messages were issued to SYSOUT whilst validating the input parameters. Input Error. The job did not complete successfully. One or more error messages were issued to SYSOUT whilst validating the input parameters. Error. The job did not complete successfully. One or more error messages were issued to SYSOUT during execution.

8

12

17.5 Publishing WSDL files from CICS to WSRR
This section describes how to use the CWSP transaction provided by the CICS SupportPac to publish a WSDL document installed as part of a CICS Web service provider application to WSRR together with optional metadata. The following diagram (Figure 17-2) illustrates the components involved in this scenario.

CICS TS V3.1 WSDL WSDL WSDL

Input Parameters: WSRR server location + security credentials + description + version

CWSP Transaction
Publish WSDL to WSRR

Web service WSRR API

WSRR log

Figure 17-2 Publishing WSDL files from CICS to WSRR

This section is aimed at experienced CICS system programmers who are responsible for installing and customizing CICS. Knowledge of basic UNIX commands is required.

842

WebSphere Service Registry and Repository Handbook

Before performing the steps to run the CWSP transaction, the following needs to be in place: The CICS system initialization (SIT) parameter LOCALCCSID must be set to an EBCDIC code page. The default for LOCALCCSID is EBCDIC codepage 037. If a non-EBCDIC code page is specified, CWSP will ABEND AEXZ. The WSDL document for the CICS Web service provider application needs to be available to the CICS region, and specified in the applications associated WEBSERVICE resource in the WSDLFILE parameter. In addition the CICS default user ID running CWSP requires read permission on for the WSDL document. The CICS region needs access to TCP/IP services to send Web services requests to the WSRR server (HOSTPORT parameter) If connectivity to WSRR is required to be via HTTPS, review 17.7, “Security considerations” on page 854.

17.5.1 Running the CWSP transaction
Perform the following steps to setup and run CWSP: 1. Add the SupportPac load library to the CICS startup 2. Create and install the resource group DFHWSPB 3. Modify the CWSP configuration file 4. Run CWSP and check output messages

Add the SupportPac load library to the CICS startup
Add the dataset hlq.CA1N.LOAD to the CICS module load library (DFHRPL) concatenation for the CICS regions within which CWSP is going to run.

Create and install the resource group DFHWSPB
The following steps involve using the CICS TS V3.1 supplied DFHCSDUP utility to update the CICS System Definition (CSD). Alternative methods could be used – for example using the facilities provided by the CEDA transaction or CICSPlexSM. 1. Modify the JCL template file hlq.CA1N.JCL(DFHWSUP) to: Update the JOB accounting information. Update STEPLIB to point to the SDFHLOAD dataset for the CICS TS V3.1 installation. Update DFHCSD to point to the CSD dataset used by the CICS region in which CWSP is to be used.

Chapter 17. Integrating WSRR with CICS

843

Replace all instances of “install-directory” with the z/FS directory the SupportPac was installed in to. Optionally, modify the transient data queue named CWSP if messages produced by CWSP are to be directed somewhere other than the default CSSL. 2. Submit the modified JCL to create the CSD group DFHWSPB. 3. Install the CSD group DFHWSPB, for example by adding the group to your CICS startup LIST.

Modify the CWSP configuration file
Modify the template configuration file, /install-directory/samples/dfhwspb.config, to specify the location of the WSRR server, access credentials, and other information to be published with WSDL files. See “CWSP configuration file” on page 845 for details of the valid parameters.

Run CWSP and check output messages
User ID under which the CWSP transaction runs requires the authority to use the CICS SPI. The CWSP uses SPI commands to dynamically create a DOCTEMPLATE as a means of retrieving the WSDL document from z/FS. To publish all installed CICS Web service provider applications to WSRR, run CWSP with no parameters. To publish a single CICS Web service provider application to WSRR, run CWSP specifying the WEBSERVICE resource name as a parameter. This parameter is case sensitive. If you need to alter the upper casing options on your terminal, use the CEOT transaction provided by CICS. For example see Example 17-4:
Example 17-4 CWSP output messages

CWSP TEST Complete -

1 published

CWSP writes output messages to the CWSP transient data queue. By default is redirected to the CSSL which can typically be viewed by viewing the CICS JOB output in JES. Example 17-5 is an except from publishing CICS Web service provider to WSRR.
Example 17-5 CICS JOB output

27/09/06 11:12:20 DFHWSPB has started

844

WebSphere Service Registry and Repository Handbook

27/09/06 11:12:20 Server location is https://wsrr.my-example.server:9443 DFHCA5510 W 27/09/2006 11:12:19 IYCQST20 IYCQTC50 CWSP DOCTEMPLATE names beginning with DFH are reserved and may be redefined by CICS. DFHDH0105 27/09/2006 11:12:19 IYCQST20 Document template definition DFH00048 has been added as HFSFILE(/u/ca1n/wsdl/myservice1.wsdl) with template name DFH00048. TC50 CWSP CTSQ01D 27/09/06 11:12:19 CREATE DOCTEMPLATE(DFH00048) TEMPLATENAME(DFH00048) HFSFILE(/u/ca1n/wsdl/myservice1.wsdl) APPENDCRLF(YES) TYPE(BINARY) DFHDH0106 27/09/2006 11:12:19 IYCQST20 Document template definition DFH00048 has been deleted. 27/09/06 11:12:20 Starting to publish TEST 27/09/06 11:12:28 WSDL published for TEST 27/09/06 11:12:28 DFHWSPB has finished

CWSP configuration file
Parameter use: You can specify the input parameters in any order. A parameter cannot span more than one line. Parameter can be delimited by a comma “,” or carriage return or line feed. All keywords and values are case sensitive unless otherwise specified.

Configuration parameters for CWSP
Example 17-6 shows the possible configuration parameters for CWSP.
Example 17-6 CWSP configuration parameters

.-----------------. v | >>--+-------------+-+--+------------+--+----------------+-----------> '-aName=value-' '-DESC=value-' '-ENCODING= >----HOSTPORT=scheme://-+-domain name-+-:port number----------------> '-IP address--' .-VERSION= >--+-----------------------------------+--+---------------+-------->< '-USERNAME=value--+-----------------+ '-VERSION=

Chapter 17. Integrating WSRR with CICS

845

'-PASSWORD=value-'

Parameter description aName=value WSRR allows for custom properties to be published along with WSDL documents. Each custom property has a name and value pair. Up to 255 name and value pairs can be specified. Duplicate and blank custom property names should be avoided. An example aName=value is Publisher=CICS SupportPac CA1N DESC=value The description of the WSDL used by WSRR to set the “Description” property. ENCODING=value The character set encoding of the WSDL document used by WSRR to set the “Encoding” property. If ENCODING is not specified, WSRR obtains this value from the typically found at the beginning of the WSDL document. HOSTPORT=scheme://{domain name|IP address}:port number The URI of the WSRR server. The scheme can be HTTP or HTTPS. The port number defaults to 80 for the scheme HTTP, and 443 for HTTPS. PASSWORD=value The password to access WSRR. USERNAME=value The username to access WSRR, and is used by WSRR to set the “Owner” property. VERSION=1|value The version number of the WSDL used by WSRR to set the “Version” property. An example CWSP configuration file is shown in Example 17-7.
Example 17-7 Example CWSP configuration file

DESC=A description for all the webservices being published VERSION=1 HOSTPORT=https://wsrr.my-example.server:9443 USERNAME=wsrrusername PASSWORD=wsrrpassword ENCODING=UTF-8 Host=IBM CICS Transaction Server

846

WebSphere Service Registry and Repository Handbook

Publisher=CICS SupportPac CA1N

17.6 Retrieving WSDL files from WSRR using z/OS batch
This section describes how to use the z/OS cataloged procedure DFHSR2WS provided by the CICS SupportPac to read a WSDL document stored in WSRR and place a copy of it on z/FS. If you need to create high level language structures (copybooks) from the WSDL document, use the DFHWS2LS procedure provided with CICS TS V3.1. It is possible to call DFHSR2WS followed by DFHWS2LS within the same z/OS batch JCL to keep the copybooks, WSBind and WSDL on z/FS in step with the WSDL stored in WSRR. To keep the CICS application which makes use of the generated copybooks would take additional steps. Figure 17-3 illustrates the components involved in this scenario.

z/OS Batch JCL
Input Parameters: WSDL unique token, WSRR server location + security credentials

. . . . . . DFHWS2LS Build Language . Structure(s) & WSBIND file from WSDL . .
DFHSR2WS . Read from WSRR

Web service WSRR API

WSRR

WSDL

Input Parameters: Language, container, end of URI, Provider Application Name, etc...

WSBind
Output Input Language Structures

log

Figure 17-3 Reading WSDL files stored in WSRR from z/OS batch

This section is aimed at experienced CICS system programmers who are responsible for installing and customizing CICS. Knowledge of basic UNIX commands and the Java configuration on your system is required.

Chapter 17. Integrating WSRR with CICS

847

The userid under which the DFHWS2SR procedure is run will need authority to: read files from the SupportPac bin directory (WORKDIR symbolic parameter) read files from the Java product directories (JAVADIR symbolic parameter) optionally, read the trust store and key store files (TRUSTSTORE and KEYSTORE parameters) write the WSDL file to z/FS (LOCATION parameter) write access to the temporary directory (TMPDIR symbolic parameter) write access the log file (LOGFILE parameter) access to TCP/IP services to send Web services requests to the WSRR server (HOSTPORT parameter) If connectivity to WSRR is required to be via HTTPS, review 17.7, “Security considerations” on page 854.

17.6.1 Running DFHSR2WS
To run the DFHSR2WS procedure you need to write JCL that includes symbolic parameters and input parameters. 1. Customize the template JCL provided in hlq.CA1N.JCL(WSDLREAD) using information in the 17.6.2, “Job control statements for DFHSR2WS” on page 850. 2. Submit the JCL. 3. If there are errors reported in the JCL output, check the z/FS log file specified by the LOGFILE parameter for detailed error messages. Example 17-8 shows a customized version of hlq.CA1N.JCL(WSDLREAD).
Example 17-8 Customized version of hlq.CA1N.JCL(WSDLREAD)

//WSDLREAD JOB (MYSYS,AUSER),MSGCLASS=H, // CLASS=A,NOTIFY=&SYSUID,REGION=0M //WSDLREAD JCLLIB ORDER=(CICS.CICSTS.CA1N.JCL) // EXEC DFHSR2WS, // JAVADIR='java/IBM/J1.4', // WORKDIR='/usr/lpp/cicsts/ca1n', // TMPDIR='/u/username/tmp', // TMPFILE='SR2WS' //INPUT.SYSUT1 DD * LOGFILE=/u/username/tmp/SR2WS.log LOCATION=/u/username/tmp/placeOrder.wsdl HOSTPORT=https://wsrr.my-example.server:9443

848

WebSphere Service Registry and Repository Handbook

USERNAME=wasadmin PASSWORD=password KEYSTORE=/u/username/DummyClientKeyFile.jks KEYPWD=wasadm1n TRUSTSTORE=/u/username/DummyClientTrustFile.jks TRUSTPWD=wasadm1n WSDLID=WSRR--c8e644f7.f101e566.614371e8.10def3f4b13.e2af041.2a */ Example 17-9 is an extract from the log file created by the DFHSR2WS after submitting the example JCL above.
Example 17-9 Log extract after running customized version of hlq.CA1N.JCL(WSDLREAD)

Value of 'LOCATION' is '/u/username/tmp/placeOrder.wsdl'. Value of 'LOGFILE' is '/u/username/logread'. Value of 'HOSTPORT' is 'https://wsrr.my-example.server:9443'. Value of 'USERNAME' is 'wasadmin'. Value of 'PASSWORD' is '********'. Value of 'WSDLID' is 'WSRR--c8e644f7.f101e566.614371e8.10def3f4b13.e2af041.2a'. Value of 'KEYSTORE' is '/u/username/DummyClientKeyFile.jks'. Value of 'KEYPWD' is '********'. Value of 'TRUSTSTORE' is '/u/username/DummyClientTrustFile.jks'. Value of 'TRUSTPWD' is '********'. Starting read of WSDL document from WSRREndpoint [https://wsrr.my-example.server:9443/WSRRCoreSDO/services/WSRRCoreSDOPo rt] getRequest [< soapenv:Body>< p828:bsrURI>WSRR--c8e644f7.f101e566.614371e8.10def3f4b13.e2af041.2a0] getResponse [< soapenv:Body>< sdo:datagraph xmlns:sdo="commonj.sdo" xmlns:sdo_1="http://www.ibm.com/xmlns/prod/serviceregistry/6/0/sdo"> WSRR--c8e644f7.f101e566.614371e8.10def3f4b13.e2af041.2a http://www.WEBPROV.WEBPROVI.Request.com http://www.WEBPROV.WEBPROVI.Response.com ] Program 'DFHSR2WS' completed SUCCESSFULLY.

17.6.2 Job control statements for DFHSR2WS
JOB Initiates the job. EXEC Specifies the procedure name (DFHSR2WS). DFHSR2WS requires sufficient storage to run Java virtual machine (JVM). You are advised to specify REGION=0M on the EXEC statement. INPUT.SYSUT1 DD Specifies the input. The input parameters are usually specified in the input stream. However, they can be defined in a data set, or in a member of a partitioned data set.

850

WebSphere Service Registry and Repository Handbook

Symbolic parameters
The following symbolic parameters are defined in cataloged procedure DFHSR2WS: JAVADIR=path Specifies the name of the Java directory that is used by DFHSR2WS. The value of this parameter is appended to /usr/lpp/ giving a complete path name of /usr/lpp/path TMPDIR=tmpdir Specifies the location of a directory in z/FS that DFHSR2WS uses as a temporary work space. The user ID under which the job runs must have read and write permission to this directory. The default value is /tmp TMPFILE=tmpprefix Specifies a prefix that DFHSR2WS uses to construct the names of the temporary workspace files. The default value is SR2WS WORKDIR=path Specifies the location of the directory in z/FS in which the SupportPac was installed. The user ID under which the job runs must have read permission to this directory.

The temporary work space
DFHWS2SR creates the following three temporary files during execution: tmpdir/tmpprefix.in tmpdir/tmpprefix.out tmpdir/tmpprefix.err Where: tmpdir is the value specified in the TMPDIR parameter tmpprefix is the value specified in the TMPFILE parameter. The default names for the files (when TMPDIR and TMPFILE are not specified), are: /tmp/SR2WS.in /tmp/SR2WS.out /tmp/SR2WS.err

Chapter 17. Integrating WSRR with CICS

851

Important: DFHSR2WS does not lock access to the generated HFS file names. Therefore, if two or more instances of DFHSR2WS run concurrently, and use the same temporary workspace files, there is nothing to prevent one job overwriting the workspace files while another job is using them. This can lead to unpredictable failures. Therefore, you are advised to devise a naming convention, and operating procedures, to avoid this situation. For example, you can use the system symbolic parameter SYSUID to generate workspace file names that are unique to an individual user. These temporary files are deleted before the end of the job.

Input parameters for DFHSR2WS
These are shown in Example 17-10.
Example 17-10 Input parameters for DFHSR2WS

.-CCSID=Cp037-. >>-+-------------+--HOSTPORT=scheme://-+-domain name-+-:port number--> '-CCSID=value-' '-IP address--' >--+-------------------------------+--LOCATION=value--LOGFILE=value--> '-KEYSTORE=value-+--------------+ '-KEYPWD=value-' >--+-----------------------------------+-----------------------------> '-TRUSTSTORE=value-+----------------+ '-TRUSTPWD=value-' >--+---------------------------------+--WSDLID=value---------------->< '-USERNAME=value-+----------------+ '-PASSWORD=value-'

Parameter use
You can specify the input parameters in any order. Each parameter must start on a new line. A parameter (and its continuation character, if you use one) must not extend beyond column 72; columns 73 to 80 should contain blanks. If a parameter is too long to fit on a single line, use an asterisk (*) character at the end of the line to indicate that the parameter continues on the next line. Everything (including spaces) before the asterisk is considered part of the parameter. For example:

852

WebSphere Service Registry and Repository Handbook

LOCATION=/dir/* placeOrder.wsdl This is equivalent to: LOCATION=/dir/placeOrder.wsdl • A parameter (and its continuation character, if you use one) must not extend beyond column 72; columns 73 to 80 should contain blanks. • A # character in the first character position of the line is a comment character. The line is ignored. • All keywords and values are case sensitive unless otherwise specified.

Parameter description
CCSID=Cp037|value The character encoding used to write the WSDL file to z/FS. A list of character encodings that can be specified is available in the “Supported Encodings” topic in the Java manuals. For Java 1.4, the character encodings are available from: http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html HOSTPORT=scheme://{domain name|IP address}:port number URI of the WSRR server. The scheme should be HTTP or HTTPS. The port number defaults to 80. KEYSTORE=value Only required if the scheme specified in HOSTPORT is HTTPS. Fully qualified filename of the Keystore file. KEYPWD=value The password to decrypt the keystore file. LOCATION=value Fully qualified filename for the WSDL document read from WSRR. DFHSRWS creates the file (but not the directory structure) if it does not already exist. LOGFILE=value The fully qualified filename into which DFHSR2WS writes its activity log and trace information. DFHSR2WS creates the file (but not the directory structure) if it does not already exist. Normally you will not need to use this file, but it may be helpful to diagnose problems. PASSWORD=value

Chapter 17. Integrating WSRR with CICS

853

The password to access WSRR. TRUSTPWD=value The password to decrypt the truststore file. TRUSTSTORE=value The fully qualified filename of the truststore file. USERNAME=value The username to access WSRR. WSDLID=value The unique WSRR document ID (also known as the bsrURI). The bsrURI for a WSDL document is shown in WSRR Web interface by viewing its “Custom Properties”.

Completion code
Table 17-2 shows the possible completion codes for DFHSR2WS.
Table 17-2 Completion codes for DFHSR2WS Completion Code 0 4 Meaning OK. The job completed successfully and only Informational messages have been issued. Input Error. The job did not complete successfully. One or more error messages were issued to SYSOUT whilst validating the input parameters. Input Error. The job did not complete successfully. One or more error messages were issued to SYSOUT whilst validating the input parameters. Error. The job did not complete successfully. One or more error messages were issued to SYSOUT during execution.

8

12

17.7 Security considerations
When the HTTPS transport is used, SSL needs to be configured between either the z/OS batch utilities or CICS and WSRR.

17.7.1 Configuring SSL between the z/OS batch utilities and WSRR
The z/OS batch utilities require a key store and a trust store to be provided. These can be created using a key configuration program such as ikeyman.

854

WebSphere Service Registry and Repository Handbook

WebSphere Application Server which hosts WSRR provides some sample key stores called DummyClientKeyFile.jks, DummyServerKeyFile.jks, and trust stores called DummyClientTrustFile.jks and DummyServerTrustFile.jks. These can be used as-is for testing the z/OS batch utilities with WSRR by specifying the client key and trust files in the z/OS batch utilities and the server key and trust files in WebSphere. As the keys in these stores are shipped with WebSphere, they should be replaced. As an example of using self-signed certificates, you could change the keys by opening the client key file using ikeyman, delete the “websphere dummy client” certificate and create a new self-signed certificate. Then extract the certificate and add it into the server's trust file. Next, open the servers' key file, delete the “websphere dummy server” certificate and create a new self-signed certificate, then extract the certificate and add it into the client's trust file. The client and server will then be able to use SSL with the new certificates.

17.7.2 Configuring SSL between CICS and WSRR
If the WebSphere Application Server within which WSRR is running is configured to use global security, CICS needs to interact with WSRR via HTTPS. When the HTTPS transport is used, SSL needs to be configured between CICS and WSRR. The configuration for CICS is done through RACF®. As an example using self-signed certificates, a digital certificate and public/private key pair must be created in RACF for the user ID the CICS region runs under. This certificate must then be appended to a keyring in RACF as the default certificate. The keyring is specified to the CICS region through the KEYRING SIT parameter. The certificate should also be extracted and added to the WebSphere trust store. The relevant certificate from the WAS key file should be extracted and added to the keyring in RACF that is specified in the CICS SIT parameter. For more information, refer to the CICS TS V3.1 documentation - topic “Configuring CICS to use SSL”: http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/topic/com.ibm.c ics.ts31.doc/dfht5/topics/dfht560.htm Or, refer to the WebSphere Application Server documentation on “Secure Sockets Layer”: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/topic/com.ibm. websphere.base.doc/info/aes/ae/csec_ssl.html

Chapter 17. Integrating WSRR with CICS

855

856

WebSphere Service Registry and Repository Handbook

Part 5

Part

5

Appendixes

© Copyright IBM Corp. 2007. All rights reserved.

857

858

WebSphere Service Registry and Repository Handbook

A

Appendix A.

IBM product descriptions
This appendix provides a brief description of the IBM products used within each phase of the SOA lifecycle for the SOA scenarios. The appendix is organized into the following sections: “IBM products used to model” on page 860 “IBM products used to assemble” on page 862 “IBM products used to deploy” on page 866 “IBM products used to manage” on page 869

© Copyright IBM Corp. 2007. All rights reserved.

859

IBM products used to model
This section includes a brief product description as well as a reference to more detailed information for the following IBM products used to model within the SOA lifecycle: “WebSphere Business Modeler” on page 860 “Rational Software Architect” on page 860 “Rational Data Architect” on page 861

WebSphere Business Modeler
IBM WebSphere Business Modeler, known as Modeler, is targeted at Business Analysts to help you capture your business design. You can use Modeler for documentation and compliance purposes: providing a visual and textual representation of your processes, organization, resources, collaborations and business measurements. You can import any static diagrams that you have created previously in Microsoft Visio®. Modeler includes a simulation tool with which you can analyze your processes and test how well your processes will hold up under different operating assumptions. You can use this analysis to refine and optimize your business design. Modeler is built on the Eclipse tool framework making it easy for you to share information about your business design with other parts of your organization and tools. In particular, you can export your design into WebSphere Integration Developer and Rational Software Architect so that your application developers can use that as a blueprint for designing process flows for automating your business design. More information about IBM WebSphere Business Model can be found here: http://www.ibm.com/software/integration/wbimodeler/

Rational Software Architect
IBM Rational Software Architect is an Eclipse based UML and Java integrated design and development tool that leverages model-driven development for creating well-architected applications and for building services in a serviceoriented architecture (SOA). It also includes the J2EE development tooling found in IBM Rational Application Developer. With Rational Software Architect you can unify all aspects of software design and development. Develop applications and Web services more productively than ever Exploit the latest in modeling language technology Review and control the structure of Java and service-oriented applications Leverage an open and extensible modeling platform Simplify your design and development tool solution Integrate with other facets of the lifecycle

860

WebSphere Service Registry and Repository Handbook

Rational Software Architect supports UML 2.0 for analysis and design using Use Case, Class, Sequence, Activity, Composite Structure, State Machine, Communication Component and Deployment diagrams. It supports UML class diagram editing for Java, Enterprise Java Beans and Database objects. As well as supporting full features of UML, it provides many additional capabilities. Rational Software Architect is useful for turning the output of WebSphere Modeler into service specifications and component-detailed designs that you can then hand over to software developers for implementation. Rational Software Architect has support for plugging in design patterns that help automate development and promote re-use. It comes already populated with the classic patterns described in Design Patterns: Elements of Reusable ObjectOriented Software by Erich Gamma, et al [GAMMA]. You can obtain other predefined patterns or create your own to capture specific design practices that you use commonly throughout your software. More information about IBM Rational Software Architect can be found here: http://www.ibm.com/software/awdtools/architect/swarchitect/features/ index.html

Rational Data Architect
IBM Rational Data Architect helps data architects model, visualize, relate, and develop data assets to understand data assets and their relationships to each other, accelerate new or composite application development, reuse prior design and development investments, and assess and manage schema changes. Built with integration challenges in mind, it combines traditional data modeling capabilities with metadata discovery, mapping, and analysis, and creates integrated and abstracted views and deploys them directly onto WebSphere Information Integrator accelerating value delivery. It plugs into the Eclipse modeling framework, and provides full lifecycle design, development and debugging for database schema, SQL, and Java-based procedures, triggers, and functions. More information about IBM Rational Data Architect can be found on this Web site: http://www.ibm.com/software/data/integration/rda/

Appendix A. IBM product descriptions

861

IBM products used to assemble
This section includes a brief product description as well as a reference to more detailed information for the following IBM products used to assemble within the SOA lifecycle: “Rational Application Developer” on page 862 “CICS Web Services Assistant” on page 863 “WebSphere Developer for zSeries” on page 864 “Bowstreet Portlet Factory” on page 865 “WebSphere Integration Developer” on page 865

Rational Application Developer
IBM Rational Application Developer is an Eclipse based integrated development environment for constructing, testing, assembling, deploying and debugging applications that are built with Java/J2EE, Web Services and many other open standards. Rational Application Developer is optimized for IBM WebSphere software, but also supports non-IBM run-time environments, such BEA WebLogic and JBOSS. IBM Rational Application Developer for WebSphere Software is powered by the Eclipse open source platform so developers can adapt and extend their development environment to match their needs and increase their productivity. When used with the IBM Software Development Platform, developers can access a broad range of requirements and change-management functions directly from Rational Application Developer for WebSphere Software. Some key features and benefits are: Accelerate portal, SOA and J2EE using RAD tools and wizards. Leverage existing skills and shorten the Java learning curve with drag-and-drop UI components and point-and-click database connectivity. Improve code quality with automated tools for applying coding standard reviews, component and Web Service unit testing and multi-tier runtime analysis. Integrate your business applications with interoperable Web services and service-oriented architectures. Visualize and graphically edit code through the UML Visual Editor for Java and EJB. Collaborate and share assets across the team using built-in IBM Rational ClearCase® LT version control. Adapt and extend your development environment with Eclipse-based plug-ins to match your needs.

862

WebSphere Service Registry and Repository Handbook

Quickly build and deploy interactive reports using drag-and-drop UI components and Crystal Reports. More information about IBM Rational Application Developer can be found here: http://www.ibm.com/software/awdtools/developer/application/index.htm l

CICS Web Services Assistant
The CICS Web Services Assistant, included with IBM CICS Transaction Server V3.1, is a set of batch utilities used to create Web Services for CICS applications, as well as enable CICS applications to invoke Web Services. The CICS Web services assistant provides two utility programs: DFHLS2WS: This utility is used to generates a Web Service binding file from a language structure. It can also be used to generates a Web Service description. DFHWS2LS: This utility is used to generate a Web Service binding file from a Web service description. It can also generate a language structure that you can use in your application programs. The assistant supports rapid deployment of CICS applications for use by service providers and service requesters, with the minimum of programming effort. When using the CICS Web Services Assistant, you do not have to write your own code for parsing inbound messages and for constructing outbound messages; CICS maps data between the body of a SOAP message and the application program’s data structure. In most cases, CICS can generate and install the resource definitions automatically. You do have to define PIPELINE resources, but in many cases you can use one of the pipeline configuration files provided with CICS (basicsoap11provider.xml, basicsoap11requester.xml). The assistant can create a WSDL document from a simple language structure, or a language structure from an existing WSDL document, and supports COBOL, C/C++, and PL/I. However, the assistant cannot deal with every possibility, and there will be times when you will need to take a different approach. If you decide not to use the CICS Web Services Assistant, you will have to: Provide your own code or parsing inbound messages and constructing outbound messages (unless you use WebSphere Developer). Provide your own pipeline configuration file. Define and install your own URIMAP and PIPELINE resources.

Appendix A. IBM product descriptions

863

More information about IBM CICS Transaction Server V3.1, Web Services Assistant can be found at this Web site: http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/index.jsp

WebSphere Developer for zSeries
WebSphere Developer for zSeries V6.0.1, is built upon the Rational Software Developer Platform (Eclipse based), facilitates the development of both Java and z/OS-based applications. WebSphere Developer contains tools that support the development of Web services and the XML enablement of existing CICS COBOL applications. The XML Services for the Enterprise (XSE) capability of WebSphere Developer provides tools that let you adapt COBOL-based applications so that they can consume and produce XML messages. XSE supports the creation of driver programs that work with existing CICS (or IMS) applications. The Web Services Enablement wizard is the XSE tool that supports the bottom-up approach for creating Web services based on existing CICS COBOL programs. It takes as input the COMMAREA copybook. The XML structure and data types are then derived from the COBOL data declarations. Based on these, the Web Services Enablement wizard generates the set of artefacts. Tip: Building the ultimate CICS development and unit test environment The combination of WebSphere Developer for zSeries V6.0.1 and the bundled CICS Transaction Server for WebSphere Developer test environment, and the CICS Transaction Gateway V6.0.2, provides an incredible powerful environment to develop by direct exposure and indirect exposure Web Services for CICS. We recommend that you refer to the following article on IBM developerWorks for information about building this CICS development and test environment: http://www.ibm.com/developerworks/websphere/library/techarticles/0509_barosa /0509_barosa.html

IBM WebSphere Developer for zSeries V6.0.1 prerequisites are: IBM Rational Application Developer or Rational Software Architect V6.0.1.1 + EGL feature must be pre-installed WebSphere Developer for zSeries CD images (disks) 1-4 are required, and CD 5 includes the CICS Transaction Server for WebSphere Developer test environment The CICS Transaction Gateway V6.0.1 (or V6.0.2) is a separate CD image.

864

WebSphere Service Registry and Repository Handbook

More information about IBM WebSphere Developer for zSeries V6 can be found here: http://www.ibm.com/software/awdtools/devzseries/

Bowstreet Portlet Factory
Now acquired by IBM, Bowstreet Portlet Factory for WebSphere is a development technology that accelerates the development, customization, deployment and maintenance of portlets for WebSphere Portal. With Bowstreet Portlet Factory, Bowstreet for short, developers can quickly and easily repurpose a company's core assets, automatically assembling them into custom, high-value portlets. These portlets can then be deployed into WebSphere Portal. The Bowstreet solution is built on open standards and supports Java, J2EE, XML and JSR 168. Bowstreet speeds up portlet development through dynamic generation of code which can be quickly modified by business users. It can rapidly generate portlets for existing systems such as Domino®, Siebel®, SAP, PeopleSoft®, Hyperion and many others. The portlets created can automatically present themselves as standalone Web applications, Web services or portlets based on JSR 168 specification without requiring any coding of assets.

WebSphere Integration Developer
IBM WebSphere Integration Developer (WID) is also an Eclipse based tool designed to help create business process flows, state machines and business rules. WebSphere Integration Developer V6.0 simplifies integration with its Service Component Architecture (SCA). SCA uses Business Process Execution Language for assembling business process tasks into workflows, which can then be deployed to IBM WebSphere Process Server. WebSphere Integration Developer can directly import business models from the IBM Business Modeler. You can then use a wiring editor for assembling service components, for importing service interface definitions and for setting binding policies to build SOA enabled applications. More information about IBM WebSphere Integration Developer can be found here: http://www.ibm.com/software/integration/wid/

Appendix A. IBM product descriptions

865

IBM products used to deploy
This section includes a brief product description as well as a reference to more detailed information for the following IBM products used to deploy within the SOA lifecycle: “WebSphere Application Server Network Deployment” on page 866 “WebSphere Enterprise Service Bus” on page 867 “WebSphere Message Broker” on page 867 “WebSphere Portal” on page 868 “WebSphere Process Server” on page 868 “WebSphere Information Integration Server” on page 869

WebSphere Application Server Network Deployment
IBM WebSphere Application Server Network Deployment serves two roles within the SOA Foundation. It is the hosting environment for basic SOA business services – primarily those implemented with J2EE Enterprise JavaBeans™ (EJBs). These services can be exposed with WSDL and integrated through standard Web service protocols and encodings, or can be integrated in a more tightly coupled fashion through Remote Method Invocation/InterORB Protocol (RMI/IIOP) bindings. WebSphere Application Server also serves as the underlying execution platform for WebSphere Portal, WebSphere Process Server, WebSphere Enterprise Service Bus, and a variety of other offerings within the IBM portfolio. This foundational role enables these products to be tightly integrated (albeit hosting a set of loosely-coupled service artefacts) with a common approach to installation, clustering, scaling, administration, service and security. WebSphere Application Server is offered in a variety of flavors, including a very compact and simple platform for J2EE applications based on Apache Geronimo, the WebSphere Community Edition (CE); WebSphere Application Server Base Edition is a standalone, single server application server that provides full run-time support for J2EE V1.4 and Web services. A customized variant packaged with tooling and targeted specifically at the ISV community that serves the small and medium business marketplace, the WebSphere Application Server Express Edition and a scalable version that supports clustering, dynamic fail-over, and a centralized administration model, the WebSphere Application Server Network Deployment Edition (ND). WebSphere Extended Deployment (XD) builds on the capabilities of WebSphere ND and offers a dynamic goals-directed, high performance environment for running mixed application types and workload patterns in WebSphere.

866

WebSphere Service Registry and Repository Handbook

More detailed information about IBM WebSphere Application Server family can be found at this Web site: http://www.ibm.com/software/webservers/appserv/was/ More detailed information about IBM WebSphere Application Server Network Deployment Edition can be found at this Web site: http://www.ibm.com/software/webservers/appserv/was/network/

WebSphere Enterprise Service Bus
IBM WebSphere Enterprise Service Bus provides Web services connectivity, JMS messaging and service-oriented integration for SOA. It instantiates the enterprise service bus architectural pattern, providing for a basic fabric for transparent interconnection of services across an enterprise distributed network. The WebSphere Enterprise Service Bus includes support for service bus mediations for reconciling different types of connectivity, including support for transformation of service requests, content based routing and constructing side-logging for auditing or traceability purposes. WebSphere Enterprise Service Bus is optimized to operate on service requests that have been bound using SOAP encodings and context processing semantics. It supports a variety of binding transports, including HTTP, the default embedded JMS message provider in WebSphere Application Server, and WebSphere MQ. More information about IBM WebSphere Enterprise Service Bus can be found here: http://www.ibm.com/software/integration/wsesb/

WebSphere Message Broker
IBM WebSphere Message Broker delivers an advanced Enterprise Service Bus providing connectivity and universal data transformation for both standard and non-standards-based applications and services. WebSphere Message Broker enhances the WebSphere Enterprise Service Busby by providing support for message transformation support for non-XML message types such AL3, HL7, Swift, HIPAA and EDI. WebSphere Message Broker provides optional support for DataStage™ TX for complex message transformations. It also has built-in support to help you implement complex event processing without programming. WebSphere Message Broker has its roots in message-based integration, a form of business composition and hub-centered mediation that predated the latest standards for SOA. While it is reasonable to think of WebSphere Message Broker as extending the capabilities of WebSphere Enterprise Service Bus, most often it

Appendix A. IBM product descriptions

867

will be appropriate to use them together in a bridged interconnection, leveraging the abilities of WebSphere Message Broker to provide interconnection with non-XML based services, native interconnectivity with CICS and IMS, and for those cases where you need complex event processing and transformation, and then using WebSphere Enterprise Service Bus to optimize your interconnectivity between XML and standard SOA-based services. More information about IBM WebSphere Message Broker can be found here: http://www.ibm.com/software/integration/wbimessagebroker/

WebSphere Portal
IBM WebSphere Portal delivers a single point of personalized interactions with applications, content, processes and people. WebSphere Portal is a hosting environment for the user interaction logic of your SOA application. More than that, the Portal server provides a platform on which multiple service user interfaces can be aggregated on a single user page within a layout template defined by the business. This provides for a unique combination of structured layout and freedom for end users to customize the content they find most important to getting their job done. In addition, portlets rendered within the page layout can be configured with published properties that when managed through the WebSphere Portal’s built-in property broker can be used to create visual integration between the services rendered by each of those Portlets. In effect, WebSphere Portal offers the enterprise user the ability to form a customized visual composition of business services. WebSphere Portal is built on the J2EE and Web Services foundations provided by WebSphere Application Server. WebSphere Portal enables rapid assembly of application artefacts via the portlets. More information about IBM WebSphere Portal can be found here: http://www.ibm.com/software/genservers/portal/

WebSphere Process Server
IBM WebSphere Process Server is the primary hosting environment for business processing. Built on WebSphere Enterprise Service Bus, WebSphere Process Server includes support for both BPEL based process flows as well as business state machines. WebSphere Process Server also supports the integration of business rules in process and service selection. The Process Server is the first product within the IBM suite to offer direct support for the Service Component Architecture SOA programming model.

868

WebSphere Service Registry and Repository Handbook

WebSphere Process Server integrates with WebSphere Portal to deliver business process management through a portal – there is support for human tasks within a business process. Human tasks are defined as activities within the process definition that will be carried out by human end-users. This includes built-in support for task assignment, pick-lists, scheduling and escalation policies in case a task is not processed in a timely fashion. More information about IBM WebSphere Process Server can be found here: http://www.ibm.com/software/integration/wps/

WebSphere Information Integration Server
IBM WebSphere Information Integration server is design specifically to enable information integration services as defined by the SOA Foundation. It provides composition of data from a variety of underlying data sources, enabling you to compose views on data that match the information needs of our composed business services. WebSphere Information Integration server can be used to build views, set import and caching strategies, and virtualize the schema of multiple, heterogeneous data systems into a homogenized relational type system. For example, you can combine data from IMS DL/I, VSAM, DB2 and Oracle databases to build a view on that joined data that appears to your application as though it is all coming from a single relational database. More detailed information about WebSphere Information Server can be found at this Web site: http://www.ibm.com/software/data/integration/db2ii/

IBM products used to manage
This section includes a brief product description as well as a reference to more detailed information for the following IBM products used to manage within the SOA lifecycle: “WebSphere Business Monitor” on page 869 “Tivoli Composite Application Manager for SOA” on page 870 “Tivoli OMEGAMON XE for Messaging” on page 870 “Tivoli Access Manager” on page 871 “Tivoli Federated Identity Manager” on page 872

WebSphere Business Monitor
IBM WebSphere Business Monitor enables you to monitor business processes in real-time, providing a visual display of business process status.

Appendix A. IBM product descriptions

869

WebSphere Business Monitor the compliment to WebSphere Business Modeler. It helps you create dashboards for visualizing the performance of your business based on the key performance indicators that you identified in your business design. You can use this to track time, cost and resources used within your processes. WebSphere Business Monitor provides tools to let you set situational triggers and notifications to bring your attention to potential bottlenecks or workload imbalances in your business. Ultimately WebSphere Business Monitor helps you better understand how your business design achieves your business objectives, and provides guidance on how to refine and optimize that business design in the case your goals are not being met. More information about IBM WebSphere Business Monitor can be found here: http://www.ibm.com/software/integration/wbimonitor/

Tivoli Composite Application Manager for SOA
IBM Tivoli Composite Application Manager (ITCAM) offering is designed specifically to enable IT service management. It has been designed to understand the unique semantics and loosely coupled characteristics of serviceoriented architecture (SOA) based services. ITCAM has three editions that are relevant directly to the SOA Foundation: ITCAM for WebSphere, ITCAM for SOA, and ITCAM for Response Time Tracking. These cover the gamut from application server monitoring and resource consumption, deep-dive diagnostics and correlation as service invocations cascade across multiple systems, and service level response times and problem isolation. Tivoli Composite Application Manager for SOA utilizes the foundation services of Tivoli Enterprise Monitoring Services. More information about IBM Tivoli Composite Application Manager can be found at: http://www.ibm.com/software/tivoli/solutions/application-management/

Tivoli OMEGAMON XE for Messaging
IBM Tivoli OMGEGAMON XE for Messaging is part of the Tivoli monitoring products suite. Tivoli OMEGAMON product came as part of the Candle acquisition by IBM. It helps you to: Improve WebSphere MQ, Message Broker, MQ Integrator and InterChange Server Availability – Identify common problems and automate corrective actions.

870

WebSphere Service Registry and Repository Handbook

– Auto-discovery and immediate monitoring of complex environments – Drill-down to locate a problem, identify the root cause and resolve bottlenecks or outages Proactively Prevent Problems – Correctly configure and deploy your WebSphere MQ infrastructure – Detect and repair problems as they happen, or alert you to an imminent concern – Provides key MQ and Message Broker metrics for real-time and historical data analysis Simplify Management with a Single Tool – Manages WebSphere MQ, Message Broker, MQ Integrator and InterChange Server in distributed and mainframe environments – User-customized displays including business, platform and resource views More information about IBM Tivoli OMEGAMON XE can be found at this Web site: http://www.ibm.com/software/tivoli/products/omegamon-xe-websphere-bu s-int/

Tivoli Access Manager
Tivoli Access Manager for e-business is a versatile solution for authentication and authorization problems. Primarily focused on Web applications, Access Manager implementations vary from simple Single Sign-on (SSO) to more complex security infrastructure deployments. Tivoli Access Manager for e-business can help you manage growth and complexity, control escalating management costs, and address the difficulties of implementing security policies across a wide range of Web and application resources. It works by centrally managing security and audit policy for enforcement points that can be placed as a proxy in front of Web applications, or through authorization and authentication plugins direct into a Web server or application-server environment. You can use Tivoli Access Manager to control wired and wireless access to applications and data to help bar unauthorized users. For authorized users, Tivoli Access Manager integrates with Web applications and servers to deliver a secured and unified business experience. It helps you secure access to business-critical applications and data spread across the extended enterprise, allowing highly available, scalable transactions with partners, customers, suppliers, and employees.

Appendix A. IBM product descriptions

871

More information about IBM Tivoli Access Manager can be found at this Web site: http://www.ibm.com/software/tivoli/products/access-mgr-e-bus/

Tivoli Federated Identity Manager
IBM Tivoli Federated Identity Manager provides a simple, loosely-coupled model for managing identity and access to resources that span companies or security domains. Rather than replicate identity and security administration at both companies, IBM Tivoli Federated Identity Manager provides a simple model for managing identities and providing them with access to information and services in a trusted fashion. For companies deploying service-oriented architecture (SOA) and Web Services, Tivoli Federated Identity Manager provides policy-based integrated security management for federated Web services. The foundation of Federated Identity Management is trust, integrity, and privacy of data. Tivoli Federated Identity Manager implements a number of industry standard mechanisms, including SAML, the Liberty Alliance, and the Web Service Federation Language (WS-Federation) specification for federating user information and authentication schemes that may be used across different parts of your business or between you and your business partners. Tivoli Federated Identity Manager operates on the recognition that no one entity in the world will have sole authority over the authenticity of users in the internet, or even the relationships between multiple business partners. Instead, it enables you to recognize the authority that each partner has in establishing the authenticity of the users that exist at each partner, and then coordinating how that authenticity may be used to control access to your own services and resources. This can dramatically reduce operational expenses by eliminating duplicate registry entries for all your users at each location that hosts services you want to use. It simplifies your user’s job by enabling a single sign-on to all the systems your user needs. The single sign-on also increases the overall integrity of your system by reducing the number passwords that your users must remember. More information about Tivoli Federated Identify Manager can be found here: http://www.ibm.com/software/tivoli/products/federated-identity-mgr/

IBM Tivoli Composite Application Manager family products
This section includes complimentary product information for the ITCAM.

872

WebSphere Service Registry and Repository Handbook

More information about the IBM Tivoli Composite Application Manager family of products can be found with the following resources: IBM Tivoli Composite Application Manager products page: http://www.ibm.com/software/tivoli/sw-atoz/indexC.html IBM Redbook IBM Tivoli Composite Application Manager V6.0 Family: Installation, Configuration, and Basic Usage, SG24-7151

IBM Tivoli Composite Application Manager for Response Time Tracking V6.0
IBM Tivoli Composite Application Manager for Response Time Tracking V6.0 (ITCAM for RTT) can proactively recognize, isolate, and resolve transaction performance problems using robotic and real-time techniques. It is an end-to-end transaction management solution that monitors end-user response time and helps you visualize a transaction’s path through your application systems, including response time contributions of each step. You can drill down to each step that the transaction takes as it travels across multiple systems, and measure how each component of a transaction contributes to the overall response time. The entire transaction analysis process is transparent to customers and application developers.

IBM Tivoli Composite Application Manager for SOA V6.0
IBM Tivoli Composite Application Manager for SOA (ITCAM for SOA) can monitor, manage, and control the Web services layer of IT architectures while drilling down to the application or resource layer to identify the source of bottlenecks or failures, and pinpoint services that take the most time or use the most resources. ITCAM for SOA includes the Web Services Navigator, a plug-in to IBM Rational and other Eclipse-based tools, which provides deep understanding of service flows, patterns and relationships to developers and architects using operational data from Tivoli Data Warehouse.

IBM Tivoli Composite Application Manager for WebSphere V6.0
IBM Tivoli Composite Application Manager for WebSphere (ITCAM for WebSphere) can help you quickly pinpoint, in real time, the source of bottlenecks in application code or server resources. Real-time information includes throughput, response time, and details for a specific transaction. ITCAM for WebSphere also provides predefined reports that you can use to display historical data, so you can plan for future growth.

Appendix A. IBM product descriptions

873

IBM Tivoli Composite Application Manager for CICS Transactions V6.0
ITCAM for CICS Transactions is a data collector installed on CICS systems to provide data for ITCAM for Response Time Tracking or ITCAM for WebSphere. ITCAM for CICS Transactions does not provide in-depth application analysis or CICS system analysis; this requires Tivoli OMEGAMON XE for CICS on z/OS. ITCAM for CICS Transactions provides the following information: CICS call summary and response time CICS transaction response time CICS processor and memory usage ITCAM for CICS Transactions is not a standalone product. It needs either ITCAM for Response Time Tracking, ITCAM for WebSphere, or both.

IBM Tivoli Composite Application Manager for IMS Transactions V6.0
ITCAM for IMS Transactions is a data collector installed on IMS systems to provide data for ITCAM for Response Time Tracking or ITCAM for WebSphere. ITCAM for IMS Transactions does not provide in-depth application analysis or IMS system analysis; this requires IBM Tivoli OMEGAMON XE for IMS on z/OS. ITCAM for IMS Transactions provides the following information: IMS transaction response time IMS processor and memory usage ITCAM for IMS Transactions is not a standalone product. It needs ITCAM for Response Time Tracking, ITCAM for WebSphere, or both.

OMEGAMON XE for WebSphere Business Integration V1.1
IBM Tivoli OMEGAMON XE for WebSphere Business Integration helps improve the availability and performance of business-critical applications and business integration systems. It can identify common problems and automate corrective actions using predefined industry best-practice situations, while monitoring key WebSphere MQ and WebSphere Business Integration Message Broker metrics. It improves WebSphere MQ, Message Broker, MQ Integrator and InterChange Server Availability: – Identify common problems and automates corrective actions – Auto-discovery and immediate monitoring of complex environments – Drill-down to locate a problem, identify the root cause, and resolve bottlenecks or outages

874

WebSphere Service Registry and Repository Handbook

Proactively Prevent Problems – Correctly configure and deploy your WebSphere MQ infrastructure – Detect and repair problems as they happen, or alert you to an imminent concern – Provides key WebSphere MQ and Message Broker metrics for real-time and historical data analysis Simplify Management with a Single Tool – Manages WebSphere MQ, Message Broker, MQ Integrator and InterChange Server in distributed and mainframe environments – User-customized displays including business, platform and resource views When used collectively, the ITCAM products provide end-to-end transactional view of monitored systems with detail analysis of resource utilization in a heterogeneous environment.

IBM Tivoli Composite Application Manager product family and Candle terminology
IBM acquired the Candle company which was incorporated into the Tivoli brand of solutions. It is important to note that the ITCAM family of products is a result of integration of Candle OMEGAMON products and IBM Tivoli products. Table 17-3 provides a mapping of the new IBM Tivoli terminology and the old Candle terminology. Although the products have acquired the new IBM terminologies and names, you can see references to the old OMEGAMON names within the product and documentation. ITCAM for SOA is designed to operate within the IBM Tivoli Monitoring.
Table 17-3 Summary of ITCAM product family and Candle terminology IBM Tivoli terminology IBM Tivoli management services IBM Tivoli Monitoring Tivoli Enterprise Monitoring Server Tivoli Enterprise Monitoring Agent Tivoli Enterprise Portal Server Tivoli Enterprise Portal Situation Event Console Candle/OMEGAMON Terminology OMEGAMON Platform OMEGAMON for distributed products Candle Management Server (CMS) OMEGAMON Monitoring Agent CandleNET Portal Server CandleNET Portal Enterprise Event Console/Event Console

Appendix A. IBM product descriptions

875

IBM Tivoli terminology Tivoli Enterprise Portal Data Warehouse

Candle/OMEGAMON Terminology Candle Management Workstation Candle Data Warehouse

876

WebSphere Service Registry and Repository Handbook

B

Appendix B.

Additional material
This redbook refers to additional material that can be downloaded from the Internet as described here.

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/SG247386 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, SG247386.

Using the Web material
The additional Web material that accompanies this redbook includes the following file: File name SG247386.zip Description Zipped integration scenario samples

© Copyright IBM Corp. 2007. All rights reserved.

877

System requirements for downloading the Web material
The following system configuration is recommended: Hard disk space: Operating System: 200KB Windows

How to use the Web material
Unzip theSG247386.zip file to a suitable location. The following directory structure will be created: \ITSO\WSRR\xxx\ Where, xxx represents one of the following directories: \plugins\ used in Chapter 13, “Configuring governance” on page 461 \scripts\ used in Chapter 13, “Configuring governance” on page 461 \src\ used in Chapter 13, “Configuring governance” on page 461 \WESB\ used in Chapter 14, “Integrating WSRR with WebSphere ESB” on page 511 Each of these directories contains files and data used in the integration scenarios covered in this redbook. Refer to the specific integration chapters for additional details.

878

WebSphere Service Registry and Repository Handbook

Glossary
B
broker archive. A file that is the unit of deployment to the broker that can contain any number of compiled message flow and message set files and a single deployment descriptor. A separate broker archive file is required for each configuration that is deployed. Business Process Execution Language (BPEL). An XML-based language for the formal specification of business processes and business interaction protocols. BPEL extends the Web Services interaction model and enables it to support business transactions. Extensible Access Control Markup Language (XACML). XACML is an XML based language that is designed to express security rules, policies and policy sets that define the access rights of users to resources. Extensible Markup Language (XML). (1) A standard metalanguage for defining markup languages that is based on Standard Generalized Markup Language (SGML). XML simplifies the process of authoring and managing structured information and transmitting and sharing structured information across diverse computing systems. (2) A text-based tag language used for document processing and for publishing information on the Web. Extensible Stylesheet Language (XSL). A language for specifying style sheets for XML documents. XSL Transformation (XSLT) is used with XSL to describe how an XML document is transformed into another document. Extensible Stylesheet Language Transformation (XSLT). An XML processing language that is used to convert an XML document into another document in XML, PDF, HTML, or other format.

C
Common Object Request Broker Architecture (CORBA). An architecture and a specification for distributed object-oriented computing that separates client and server programs with a formal interface definition. See also Internet Inter-ORB Protocol.

E enterprise archive (EAR). A specialized type of JAR file, defined by the J2EE standard, used to deploy J2EE applications to J2EE application servers. An EAR file contains EJB components, a deployment descriptor, and Web archive (WAR) files for individual Web applications. See also Web archive, Java archive. Enterprise JavaBeans (EJB). A component architecture defined by Sun Microsystems for the development and deployment of object-oriented, distributed, enterprise-level applications.

I
Information Technology Infrastructure Library (ITIL). A framework of best practice approaches intended to facilitate the delivery and the management of high quality information technology (IT) services. Internet Inter-ORB Protocol (IIOP). A protocol used for communication between Common Object Request Broker Architecture (CORBA) object request brokers. See also Common Object Request Broker Architecture.

© Copyright IBM Corp. 2007. All rights reserved.

879

J
J2EE Connector architecture (JCA). A standard architecture for connecting the J2EE platform to heterogeneous enterprise information systems (EIS). Java 2 Platform Enterprise Edition (J2EE). An environment for developing and deploying enterprise applications, defined by Sun Microsystems Inc. The J2EE platform consists of a set of services, application programming interfaces (APIs), and protocols that provide the functionality for developing multitiered, Web-based applications. Java API for XML-based RPC (JAX-RPC). A specification that describes application programming interfaces (APIs) and conventions for building Web services and Web service clients that use remote procedure calls (RPC) and XML. JAX-RPC is also known as JSR 101. Java archive (JAR). A compressed file format for storing all the resources that are required to install and run a Java program in a single file. See also enterprise archive, Web archive. Java Authentication and Authorization Service (JAAS). In J2EE technology, a standard API for performing security-based operations. Through JAAS, services can authenticate and authorize users while enabling the applications to remain independent from underlying technologies. Java Management Extensions (JMX). A means of doing management of and through Java technology. JMX was developed through the Java Community ProcessSM program, by Sun Microsystems, Inc. and some leading companies in the management field. JMX is a universal, open extension of the Java programming language for management that can be deployed across all industries, wherever management is needed. Java Message Service (JMS). An application programming interface that provides Java language functions for handling messages.

Java Naming and Directory Interface™ (JNDI). An extension to the Java platform that provides a standard interface for heterogeneous naming and directory services. Java Native Interface (JNI). A programming interface that allows Java code to interoperate with functions that are written in other programming languages. JavaServer™ Pages™ (JSP™). A server-side scripting technology that enables Java code to be dynamically embedded within Web pages (HTML files) and executed when the page is served, in order to return dynamic content to a client.

R
Remote Method Invocation (RMI). A protocol that is used to communicate method invocations over a network. Java Remote Method Invocation is a distributed object model in which the methods of remote objects written in the Java programming language can be invoked from other Java virtual machines, possibly on different hosts. Remote Method Invocation over Internet InterORB Protocol (RMI/IIOP). Part of the Java 2 Platform, Standard Edition (J2SE™) model that developers can use to program in the Java language to work with RMI interfaces, but use IIOP as the underlying transport. remote procedure call (RPC). A protocol that allows a program on a client computer to run a program on a server.

S
Secure Sockets Layer (SSL). A security protocol that provides communication privacy. With SSL, client/server applications can communicate in a way that is designed to prevent eavesdropping, tampering, and message forgery.

880

WebSphere Service Registry and Repository Handbook

Service Data Objects (SDO). An open standard for enabling applications to handle data from heterogeneous data sources in a uniform way. SDO incorporates J2EE patterns but simplifies the J2EE data programming model. service-oriented architecture (SOA). A collection of services that communicate with each other. The communication might involve either simple data passing or two or more services coordinating some activity. Simple Object Access Protocol (SOAP). A lightweight, XML-based protocol for exchanging information in a decentralized, distributed environment. SOAP can be used to query and return information and invoke services across the Internet. State Adaptive Choreography Language (SACL). SACL is an XML representation of state machines. SACL allows you to define the states that exist within your state machine and the transitions that can occur to move entities from one state to another.

W
Web archive (WAR). A compressed file format, defined by the J2EE standard, for storing all the resources required to install and run a Web application in a single file. See also enterprise archive, Java archive. Web Ontology Language (OWL). The Web Ontology Language (OWL) is a W3C endorsed format that can be used to define an ontology. It can define relatively rich semantics including relations between classes of entities (for example disjointedness), cardinality (for example “exactly one”), equality, properties, characteristics of properties (for example symmetry), and enumerated classes. Web Services Description Language (WSDL). (1) A set of definitions that consist of service, port, message, bindings, and port type. WSDL provides a way for service providers to describe the basic format of Web service requests over different protocols or encodings. (2) An XML-based specification for describing networked services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. Web Services Invocation Framework (WSIF). A Java API that supports dynamic invoking of Web services, regardless of the format in which the service is implemented or the access mechanism. Web Services Invocation Language (WSIL). An XML document format that facilitates the discovery of existing Web services and provides a set of rules for how inspection-related information should be made available for consumption.

U
Uniform Resource Identifier (URI). (1) A compact string of characters for identifying an abstract or physical resource. (2) A unique address that is used to identify content on the Web, such as a page of text, a video or sound clip, a still or animated image, or a program. The most common form of URI is the Web page address, which is a particular form or subset of URI called a Uniform Resource Locator (URL). A URI typically describes how to access the resource, the computer that contains the resource, and the name of the resource (a file name) on the computer. Universal Description, Discovery, and Integration (UDDI). UDDI 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.

Glossary

881

X
XML Path Language (XPath). An XSL sublanguage designed to uniquely identify or address parts of a source XML document, for use with XSLT. XPath also provides basic facilities for manipulation of strings, numbers and Booleans. See Extensible Markup Language and Extensible Stylesheet Language Transformation. XML Schema Definition Language (XSD). A language for describing XML files that contain XML schema. XML schema. An international standard that defines a language for describing the structure of XML documents. An XML schema formally describes and constrains the content of XML documents by indicating which elements are allowed and in which combinations. (An XML Schema is an alternative to a document type definition (DTD), and can be used to extend functionality in the areas of data typing, inheritance, and presentation.) The XML Schema language is ideally suited to describing the messages that flow between business applications. XML Services for the Enterprise (XSE). A capability of WebSphere Developer which provides tools that let you adapt COBOL-based applications so that they can consume and produce XML messages. XML shredder. A function that parses an XML document, extracting rows of data from an XML table. Also referred to as parsing.

882

WebSphere Service Registry and Repository Handbook

Abbreviations and acronyms
AIX APAR API BAR BPEL CCMDB CICS CLI CMDB COBOL COE CORBA CRUD CSD DCA DLA DLFS DOS EAI EAR EBCDIC EDI EIF EIS EJB ESB ESQL FTP GUI HLL Advanced Interactive eXecutive authorized program analysis report application programming interface Broker Archive Business Process Execution Language Tivoli Change and Configuration Management Database Customer Information Control System command line interface Configuration Management Database Common Business Oriented Language Center of Excellence Common Object Request Broker Architecture create, retrieve, update, and delete CICS System Definition Data Collector Adapter Discovery Library Adapter Discovery Library File Store disk operating system Enterprise Application Integration enterprise archive Extended Binary Coded Decimal Interchange Code electronic data interchange Event Integration Facility Enterprise Information Systems Enterprise Java Bean Enterprise Service Bus Extended Structured Query Language File Transfer Protocol Graphical User Interface high-level language JAR JCA JCL JDBC JDK JES JMS JMX JNDI JRE JSP J2C J2EE JAAS ISV ITCAM IIOP IRA ISO HTML HTTP IBM HyperText Markup Language HyperText Transport Protocol International Business Machines Corporation Internet Inter-ORB Protocol Intelligent Remote Agent International Organization for Standardization independent software vendor IBM Tivoli Composite Application Manager

ITCCMDB IBM Tivoli Change and Configuration Management Database ITIL ITM ITSO Information Technology Infrastructure Library IBM Tivoli Monitoring International Technical Support Organization J2EE Connector Architecture Java 2 Platform, Enterprise Edition Java Authentication and Authorization Service Java archive J2EE Connector architecture job control language Java Database Connectivity Java Development Kit Job Entry Subsystem Java Message Service Java Management eXtensions Java Naming and Directory Interface Java Runtime Environment JavaServer Pages

JAX-RPC Java API for XML-based RPC

© Copyright IBM Corp. 2007. All rights reserved.

883

JSR JVM LDAP MQ MSS OASIS ODBC OTEA OWL RACF RAD RAM RDF RFID RHAS RMI

Java Specification Request Java virtual machine Lightweight Directory Access Protocol managers and queues Managed Software System Organization for the Advancement of Structured Information Standards Open Database Connectivity OMEGAMON TEC Event Adapter Web Ontology Language Resource Access Control Facility rapid application development Rational Asset Manager Resource Description Framework radio frequency ID Red Hat Advanced Server Remote Method Invocation

SPI SQL SSH SSL SSO TCORE TDW TEC TEMA TEMS TEP TEPS TSO UDB UDDI UI UML URI URL VSAM WAR WESB WID WMB WMQ WPS

Security Policy Index Structured Query Language Secure Shell Secure Sockets Layer Single Sign-on Tivoli Common Object Repository Tivoli Data Warehouse Tivoli Enterprise Console Tivoli Enterprise Monitoring Agent Tivoli Enterprise Monitoring Server Tivoli Enterprise Portal Tivoli Enterprise Portal Server Time Sharing Option Universal Database Universal Description, Discovery and Integration User Interface Universal Markup Language Uniform Resource Identifier Uniform Resource Locator Virtual Storage Access Method Web Archive WebSphere Enterprise Service Bus WebSphere Integration Developer WebSphere Message Broker WebSphere MQ WebSphere Process Server

RMI/IIOP Remote Method Invocation over Internet InterORB Protocol RPC RSA SACL SAML SCA SCDL SDK SDO SHA SLA SLES SMO SMTP SOA SOAP SOR remote procedure call Rational Software Architect State Adaptive Choreography Language Security Assertion Markup Language Service Component Architecture Service Component Definition Language software development kit Service Data Object Secure Hash Algorithm service level agreement SuSE Linux Enterprise Server service message objects Simple Mail Transport Protocol service-oriented architecture Simple Object Access Protocol statement of requirements

WS-BPEL Business Process Execution Language for Web services WSDL WSIF WSIL WSRR XACML XML Web Services Description Language Web Services Invocation Framework Web Services Inspection Language WebSphere Service Registry and Repository Extensible Access Control Markup Language Extensible Markup Language

884

WebSphere Service Registry and Repository Handbook

XPath XSD XSE XSL XSLT

XML Path language XML Schema Definition XML Services for the Enterprise Extensible Stylesheet Language Extensible Stylesheet Language Transformations

XPointer XML Pointer Language

Abbreviations and acronyms

885

886

WebSphere Service Registry and Repository 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 about ordering these publications, see “How to get IBM Redbooks” on page 890. Note that some of the documents referenced here may be available in softcopy only. Patterns: SOA Foundation Service Creation Scenario, SG24-7240 Patterns: SOA Foundation Service Connectivity Scenario, SG24-7228 Patterns: Integrating Enterprise Service Buses in a Service-Oriented Architecture, SG24-6773 Patterns: Implementing an SOA using an Enterprise Service Bus, SG24-6346 Getting Started with WebSphere Enterprise Service Bus V6, SG24-7212 Web Services Handbook for WebSphere Application Server 6.1, SG24-7257 Architecting Access to CICS within an SOA, SG24-5466 WebSphere Message Broker Basics, SG24-7137 IBM Tivoli Composite Application Manager V6.0 Family: Installation, Configuration, and Basic Usage, SG24-7151 Best Practices for SOA Management, REDP-4233 Understanding SOA Security Design and Implementation, SG24-7310

Other publications
These publications are also relevant as further information sources: Service-Oriented Architecture Compass: Business Value, Planning, and Enterprise Roadmap, by Norbert Bieberstein, et al. IBM Press, 2005, ISBN-10: 0131870025

© Copyright IBM Corp. 2007. All rights reserved.

887

Online resources and product documentation
The following Web sites and documents are also relevant as further information sources:

WebSphere Service Registry and Repository
Web service standards for Service Registry and Repository http://www.ibm.com/developerworks/webservices/library/specification/ ws-servregrep/ WebSphere Service Registry and Repository product page http://www.ibm.com/software/integration/wsrr/ WebSphere Service Registry and Repository Information Center http://publib.boulder.ibm.com/infocenter/sr/v6r0/index.jsp Introducing WebSphere Service Registry and Repository, Part 1 http://www.ibm.com/developerworks/websphere/library/techarticles/060 9_mckee/0609_mckee.html Introducing WebSphere Service Registry and Repository, Part 2 http://www.ibm.com/developerworks/websphere/library/techarticles/060 9_mckee2/0609_mckee2.html Introducing WebSphere Service Registry and Repository APIs http://www.ibm.com/developerworks/websphere/library/techarticles/061 1_baldwin/0611_baldwin.html Using collections in the WebSphere Service Registry and Repository to resolve versioned imports, Part 1: Using GenericObjects http://www.ibm.com/developerworks/websphere/library/techarticles/070 1_kufluk/0701_kufluk.html Customizing the WebSphere Service Registry and Repository user interface, Part 1 http://www.ibm.com/developerworks/websphere/library/techarticles/061 1_smithson/0611_smithson.html WebSphere Service Registry and Repository Support http://www.ibm.com/software/integration/wsrr/support/ WebSphere Service Registry and Repository SupportPacs http://www.ibm.com/support/docview.wss?rs=171&uid=swg27008751#1

888

WebSphere Service Registry and Repository Handbook

WebSphere Service Registry and Repository Eclipse plug-in http://www.ibm.com/support/docview.wss?rs=3163&context=SSWLGF&dc=D40 0&uid=swg24013925&loc=en_US&cs=UTF-8&lang=en

WebSphere
WebSphere MQ Information Center http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/index.jsp WebSphere Application Server V6.0 Information Center http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp

CICS
Publishing a Web service to WebSphere Service Registry and Repository from CICS Transaction Server V3.1 http://www.ibm.com/developerworks/websphere/library/techarticles/061 0_millwood/0610_millwood.html CICS TS SupportPac CA1N - Support for the WebSphere Service Registry and Repository http://www.ibm.com/support/docview.wss?rs=1083&uid=swg24013629 CICS TS V3.1 Information Center http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/index.jsp

Service-oriented architecture
IBM SOA Foundation - An Architectural Introduction and Overview http://download.boulder.ibm.com/ibmdl/pub/software/dw/webservices/ws -soa-whitepaper.pdf Introduction to SOA programming model http://www.ibm.com/developerworks/webservices/library/ws-soa-progmod el/ Introduction to SOA governance http://www.ibm.com/developerworks/library/ar-servgov/

Tivoli Composite Application Manager for SOA
Tivoli Composite Application Manager for SOA - Version 6.1.0 - Installation and User’s Guide, GC32-9492

Related publications

889

Tivoli Composite Application Manager for SOA Information Center http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp?toc =/com.ibm.itcamsoa.doc/toc.xml IBM Tivoli Composite Application Manager for SOA product information http://www.ibm.com/software/tivoli/products/composite-application-mg r-soa/

WebSphere Message Broker
WebSphere Message Broker V6.0 Information Center http://publib.boulder.ibm.com/infocenter/wmbhelp/v6r0m0/index.jsp Build flexible ESB mediations with WebSphere Message Broker and WebSphere Service Registry and Repository http://www.ibm.com/developerworks/websphere/library/techarticles/061 0_patten/0610_patten.html WMB V6 Client for WebSphere Service Registry and Repository http://www.ibm.com/support/docview.wss?uid=swg24013639

How to get IBM Redbooks
You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at this Web site: ibm.com/redbooks

Help from IBM
IBM Support and downloads ibm.com/support IBM Global Services ibm.com/services

890

WebSphere Service Registry and Repository Handbook

Index
A
access control administration 309–311 overview 309 scripts for managing policy 322 type create 309 delete 309 retrieve 309 transition 310 update 309 Access Services SOA reference architecture model 13 action property 190 add properties to objects 440–442 addChecksum 484–485 adding permissions to roles 469 addPermissionToRole 197, 289, 322 addPermissionToRole2 289, 322 addPrincipalToRole 197, 288, 323 addRole 197, 288, 323 Admin (JMX) interface overview 155 Admin MBean operations addPermissionToRole 289 addPermissionToRole2 289 addPrincipalToRole 288 addRole 288 createOntologySystem 287–288 deleteConfiguration 287 deleteOntologySystem 288 exportMetaData 288 getConfigurationId 287 getConfigurationIds 287 getPermissionsForRole 289 getRolesWithPermissions 288 importMetaData 288 loadConfiguration 287 persistPolicy 289 persistRoleMappings 289 removeAllRolePermissions 288 removeAllRoles 288 removePermissionFromRole 288 removePrincipalFromRole 288 removeRole 288 retrieveAllConfigurationNames 287 retrieveConfiguration 287 updateConfiguration 287 AdminException 285, 291–292, 297 Administration 331 administrator permission 193 AL3 867 AllAuthenticatedUsers 187 application architecture 19 AppServer 660 Assemble SOA lifecycle 8 attribute tables 681–682 AttributeDeclaration 133, 135 auditing 77 authorization policy file 196 AuthorizeDevelopment 165

B
BaseObject 101–103, 114 BindAddress 660 binding 22, 28, 55, 95, 514, 517 dynamic 22, 36 Java Message Service bindings 517 SCA binding 517, 535 static 22, 58 Web Service bindings 517 WebSphere Adapter bindings 518 WebSphere MQ bindings 518 WebSphere MQ JMS bindings 517 BM Tivoli Composite Application Manager for SOA overview 641 BOOTSTRAPPORT 267–268, 276–278 Bowstreet Portlet Factory overview 865 BrowseClassificationSystem 394 BSRSDOHelper 123 bsrURI 104, 128–129, 141–143, 168, 312, 801, 854 defined 104 temporary 141 Business Application Services

© Copyright IBM Corp. 2007. All rights reserved.

891

SOA reference architecture model 13 Business Innovation and Optimization Services SOA reference architecture model 17 Business Process Details 675 Business Process Execution Language 98 Business Process Execution Language for Web Services 25, 657 Business Processes for Service 674 Business Processes for Service Port 675 button-action 408, 410 button-definitions 407, 409 button-message 408

C
C 863 C++ 863 CA1N 826 calculateMD5Checksum 486 callout responses 519 Candle Data Warehouse 876 Candle Management Server 875 Candle Management Workstation 876 CandleNET Portal 875 CandleNET Portal Server 875 canonical data model 46 Change and Release Management 36 checkWSDLPorts 489–490 CICS overview 827–831 SOA 831 Transaction Server 863 overview 827 TXSeries 829 Web Services Assistant 863 CICS SupportPac downloading 832 installation 831–834 overview 826 Class 861 classification functions 108 Classification Systems 330 classifications 86–88 ontology 87 taxonomies 87 Web Ontology Language 87 within WSRR 87 ClassificationURI 387 classifiedByAllOf 192

classifiedByAnyOf 192 classifying objects 358–363 browsing classifications 359 classifying an entity 361 loading an OWL file 358 removing a classification 361 client-side interception 651 CMDB See Configuration Management Database CMS See Candle Management Server collection 401–410 definition file 151–152 name, title, description 403 skeleton collection view 402 view areas 401 view buttons 407 view columns 404 column-definitions 407 com.ibm.ssl.keyStore 430 com.ibm.ssl.trustStore 430 command line WebSphere Service Registry and Repository administration 283 command line interface 74 import/export 315 overview 154 sample scripts 306 createGenericObject 306 createXMLDocument 306 deleteBaseObject 306 deleteConfig 307 export 306 findBaseObject 306 import 307 loadConfig 307 promote 307 retrieveConfig 307 transition 307 updateConfig 307 WebSphere Service Registry and Repository administration 299–307 Common Data Model 657–658, 662 Common Object Repository 656, 659, 661, 664 common relationships 221 Communication Component 861 complex type 371 ComplexTypeDefinition 111, 133, 135 ComplexTypeDefinition relationships 242

892

WebSphere Service Registry and Repository Handbook

component model 18 composite application defined 20 composite state 159 Composite Structure 861 ComputerSystem 660 concepts 83, 370–379, 385, 445–451 classifying a complex type as a template 371 creating a concept from a template 374 creating concepts for objects 445–447 creating concepts using local documents 448–451 defining a concept template 371 deleting a concept 378 viewing templates 372 viewing the details of a concept 377 concrete types 111 configuration 283–285, 411–413 configuration document 283 configuration type 283 content 283, 411 managing 411–413 name 283, 411 supported configurations 284 system indicator 284, 411 type 284, 411 Configuration Management Database 632, 696 ConfigurationType 285 ConnectorException 296–297 content model See information model create method 204 createGenericObject script 306 createOntologySystem 287–288, 307, 412 createRequest 142 createResponse 143 createXMLDocument script 306 creating content in WSRR 124 Custom Mediation 521 Customer Information Control System See CICS CWSP 842, 844 configuration file 844–845 overview 826 running 843

D
Data Collector Adapter 648

Data Collectors 648, 651 data graphs 100 data objects 100 Data Warehouse 876 Database Lookup 520 DataFactory 123–124, 127–128 DataGraphType 140 DataStage TX 867 DB2 869 DB2 Universal Database Enterprise Server Edition installing 256–258 decoupling Enterprise Service Bus 29 default permission 192 define relationships between objects 442–445 delete method 205 deleteBaseObject script 306 deleteConfig script 307 deleteConfiguration 287, 322, 412 deleteOntologySystem 288, 307, 322, 412 deleting artefacts 369–370 deleting content from WSRR 130 delta books 656 dependency depth 217 Deploy SOA lifecycle 9 deploying WebSphere Service Registry and Repository 265–275 Deployment diagrams 861 deployment time 23 derived objects 93, 95, 98, 168, 186, 218–219, 230, 504–509 defined 218 dependencies 507 detail definition file 152 DetailView 405 DFHLS2WS 834, 863 DFHSR2WS 847 JCL 850 overview 826 running 848 DFHWS2LS 826, 863 DFHWS2SR 834 JCL 837 overview 826 running 835 DFHWSPB 843

Index

893

discovery 22 Discovery Library Adapter 648, 654, 659–662, 702–718 Business Process Execution Language for Web Services 657 configuring 708–713 delta books 656 Deployed 661 IBM Tivoli Composite Application Manager for SOA 657 installing 705–707 managed 661 overview 656–657, 703 refresh books 656 using 714–718 WebSphere Service Registry and Repository 657 DLA See Discovery Library Adapter document instance creating 124–128 document relationships 224 document types 89–98 Service Component Architecture 96–97 Service Component Description Language 89 Web Services Description Language 89, 94–96 WS-Policy 89, 98 XML metadata 98 XML Schema Definition 89, 91–93 downcast 110 dynamic binding 22, 36 dynamic programming model 100

E
Eclipse plug-in 73, 415–451 See also Eclipse UI installation 417–427 Eclipse UI See also Eclipse plug-in 416–451 add properties to objects 440–442 configuring 428–431 creating concepts for objects 445–447 creating concepts using local documents 448–451 define relationships between objects 442–445 import documents into local workspace 435–438

publishing documents 438–439 searching the registry 431–435 EDI 867 EIF See Event Integration Facility EIFLogger 734, 742 EJB client 136 ElementDeclaration 133–134 ElementDeclaration relationships 241 Endpoint Lookup 521, 525–536 usage 528 Enterprise Event Console/Event Console 875 Enterprise Java Beans 861 Enterprise Service Bus 28–34, 512 and service-oriented architecture 28 decoupling 29 defined 30 hub and spoke architecture 31 in a service-oriented archtecture 15 mediation support 33 protocol independence 34 substitution 34 entityBsrUri 167 Environment Promotion 319–321 defined 319 sample script 319 ESB See Enterprise Service Bus Event Emitter Mediation 521 Event Integration Facility 687, 728, 734, 740, 747, 751 EventMap 735 executeNamedQuery 142 executeNamedQueryWithParameters 142 executeQuery 142 Export 384, 514 export script 306 ExportDocument 384 exportMetaData 288, 322 Extensible Access Control Markup Language 196 extensible markup language defined 26 Extensible Stylesheet Language Transformations 161, 520, 525, 528, 777

F
Fail 521 Fail terminal 521

894

WebSphere Service Registry and Repository Handbook

Fault_610 680, 743, 757–758, 760, 765, 768 FilterExpression 192 findBaseObject script 306

G
GenericObject 83, 123, 126–128, 130, 135, 168, 191, 384–385 creating 124 defined 81 getAllAttributeDeclarations 133 getAllBindings 133 getAllComplexTypeDefinitions 133 getAllElementDeclarations 133 getAllGenericObjects 135 getAllMessages 133 getAllOperations 133 getAllParts 133 getAllPolicyDocuments 133 getAllPorts 133 getAllPortTypes 133 getAllServices 133 getAllWSDLDocuments 133 getAllXMLDocuments 133 getAllXSDDocuments 133 getConfigurationId 287, 412 getConfigurationIds 287 getGovernanceConnection 304 getGovernanceRecord 135, 168 getInboundDependencies 220 getOntologyConnection 304 getOutboundDependencies 220 getPermissionsForRole 197, 289, 323 getPolicyConfiguration 323 getPolicyDocument 133 getProperties 305 getRoleMappingConfiguration 323 getRoles 323 getRolesWithPermissions 197, 288 getServiceRegistryRepositoryProxy 305 getSessionConnection 303 getUserDefinedRelationshipNames 135 getWSDLDocBindings 134 getWSDLDocMessages 134 getWSDLDocOperations 134 getWSDLDocParts 134 getWSDLDocPorts 134, 490 getWSDLDocPortTypes 134 getWSDLDocServices 134

getWSDLDocSOAPBindings 134 getWSDLDocSOAPPorts 134 getWSDLDocument 133 getWSDLPorts 135 getWSDLPortTypes 135 getWSDLServices 135 getXMLDocument 133 getXSDAttributeDeclarations 135 getXSDComplexTypeDefs 135 getXSDDocument 133 getXSDElements 134 getXSDSimpleTypeDefs 134 governance 40–49, 55–57, 64–65, 76–77, 157–244, 461–509 See also SOA governance auditing 77 configuring 461–509 governed collections 169–179 adding an object 171 best practices 179–187 removing an object 174 notification 76 removing governance 481 root object 168 service lifecycle 76 validation 76 Governance API 477 GovernanceManagePermission 194 governanceNotifiers 212 GovernanceRecord 135, 167–187 attributes entityBsrUri 167 governedObjects 167 state 167 GovernanceTransitionPermission 194 governanceValidators 208 governed collections 169–179 adding an object 171 best practices 179–187 removing an object 174 governed entity 158 governed object 158 GenericObject 168 lifecycle 159 making an object governable 477 PolicyDocument 168 removing governance 481 SCAModule 168 transitioning the lifecycle state 479

Index

895

WSDLDocument 168 XMLDocument 168 XSDDocument 168 GovernedCreatePermission 193 GovernedDeletePermission 194 governedObjects 167 GovernedRetrievePermission 193 GovernedRetrievePermissionA 195 GovernedRetrievePermissionB 195 GovernedUpdatePermission 194 GovernedUserUpdatePermission 195 GraphQuery 105, 130–132, 191 defined 132

H
HIPAA 867 HL7 867 hub and spoke architecture 31

I
IBM Discovery Library Identity Markup Language 656 IBM IT Service Management 631 IBM Tivoli Access Manager overview 871 IBM Tivoli Composite Application Manager Candle product integration 875 overview 634 IBM Tivoli Composite Application Manager for CICS Transactions 635 overview 874 IBM Tivoli Composite Application Manager for IMS Transactions 635 overview 874 IBM Tivoli Composite Application Manager for Response Time Tracking 634, 638 overview 873 IBM Tivoli Composite Application Manager for SOA 166, 634, 638, 640–653 components 647 integration scenarios with WebSphere Service Registry and Repository 654 overview 870, 873 product features 644 situation 678–690 overview 679 predefined 680 IBM Tivoli Composite Application Manager for SOA

Event Handler 687–689, 698 configuring 731–746 event properties 737 installation 729–730 overview 689, 728–729 IBM Tivoli Composite Application Manager for WebSphere 635 overview 873 IBM Tivoli Data Warehouse 640 IBM Tivoli Enterprise Console 638, 687, 689, 729, 733, 739, 746, 752–754 IBM Tivoli Enterprise Monitoring Agent 875 overview 638 IBM Tivoli Enterprise Monitoring framework 636–640, 692, 746 IBM Tivoli Enterprise Monitoring Server 875 overview 636 IBM Tivoli Enterprise Portal 875–876 IBM Tivoli Enterprise Portal clients overview 637 IBM Tivoli Enterprise Portal Server 875 overview 637 IBM Tivoli Federated Identity Manager overview 872 IBM Tivoli Management Framework 753 IBM Tivoli management services 875 IBM Tivoli Monitoring 638, 875 IBM Tivoli OMEGAMON XE for Messaging overview 870 IDML See IBM Discovery Library Identity Markup Language impact analysis 213–244, 499–509 dependency depth 217 inbound dependencies 216 outbound dependencies 214 Import 384, 514 import documents into local workspace 435–438 import script 307 import/export 311–318 export 311 import 313 ImportDocument 384 ImportDocuments 394 importedWSDLs 500 importMetaData 288, 322 IMS DL/I 869 In terminal 521 inbound dependencies 216

896

WebSphere Service Registry and Repository Handbook

information model 71–72, 79–118 BaseObject 101–103 document types 89–98 parsing 67, 81–82, 84–85, 90, 93, 96, 168, 218–219, 230 query 103–118 See also query classification functions 108 examples 105–117 GraphQuery 105 limitations 118 predicates 106 PropertyQuery 105 relationship map 111 shortcuts and wildcards 107 treat as 110 Service Data Objects 99–101 data graphs 100 data objects 100 service description entities 80–83 defined 72, 80 GenericObject 83 defined 81 logical derivations 82 defined 81 physical documents 81 defined 80 service description metadata 84–88 classifications 86–88 ontology 87 taxonomies 87 Web Ontology Language 87 within WSRR 87 defined 72, 80 properties 84–85 relationships 85–86 templates 88–89 XPath 99 Information Services SOA reference architecture model 13 Information Technology Infrastructure Library 632, 696 Infrastructure Services SOA reference architecture model 18 installing DB2 Universal Database Enterprise Server Edition 256–258 WebSphere Application Server 254–256 WebSphere Application Server ND 277–279

WebSphere Service Registry and Repository 258–264 remote DB 275–277 InstanceNotFoundException 296–297 integration architecture 19 Intelligent Remote Agent 648 Interaction Services SOA reference architecture model 12 interfaces and APIs 72–75 Admin (JMX) interface overview 155 command line interface 74 overview 154 Eclipse plug-in 415–451 See also Eclipse plug-in Java API (EJB) 120–135 creating content in WSRR 124 deleting content from WSRR 130 GraphQuery 132 Java client 120 PropertyQuery 132 querying content in WSRR 130 retrieving content from WSRR 128 ServiceRegistryClient 121 updating content in WSRR 129 query interface 72 SOAP API 139–144 bsrURI 141 DataGraphType 140 portType 142 PropertyQueryResult 141 WSRR type 140 supported APIs 74 user interfaces 73 Eclipse plug-in 73 Web interface 73 Web services API 136–144 EJB client 136 ontology Web service 138 Web services client 136 Web UI 144–154 introspect 17, 82, 100 IPInterface 660 IPv4Address 660 IT Service Management SOA reference architecture model 17 ITCAMListener 733, 741 ITIL See Information Technology Infrastructure Li-

Index

897

brary

J
Java API (EJB) 120–135 creating content in WSRR 124 deleting content from WSRR 130 GraphQuery 132 Java client 120 PropertyQuery 132 querying content in WSRR 130 retrieving content from WSRR 128 ServiceRegistryClient 121 updating content in WSRR 129 Java client 120 Java Message Service bindings 517 JMSEndpoint 820 JMSExportBinding 110 JMSImportBinding 110 JMX WebSphere Service Registry and Repository administration 282, 292–298

ListMyFavourites 394 ListMySubscriptions 394 LoadClassificationSystem 394 loadConfig script 307 loadConfiguration 287, 322, 412 LoadDocument 394 loading an OWL file 358 loadOntologySystem 322 loadPolicyConfiguration 323 loadRoleMappingConfiguration 323 locating WSRR MBean 286 logical derivations 82 defined 81–82 parsing 81–82 logical objects 82 defined 82 LogicalObject relationships 229 logicalobjects from parsing 230

M making an object governable 158, 477 Manage SOA lifecycle 10 mapping users to roles 475 match policy 527, 530 MaxMessageSize_610 680 MaxResponseTimeCritical_610 681 MaxResponseTimeWarning_610 681 MBean 286 createOntologySystem 307 deleteOntologySystem 307 discovering WSRR MBean notifications 289 invoking MBean operations 289 ServiceRegistryRepository 282, 285–286, 294, 412 supported Admin operations 197, 287 MBeanException 292, 296–297 mediation 514–515 mediation flow 518–519 callout responses 519 request flow 518–519 response flow 518–519 mediation flow component 514, 518 mediation module 514, 516–518 mediation primitives 520–521 Custom Mediation 521 Database Lookup 520

K keyStore 430

L lazy initialization 198 lifecycle 7–11, 158–187 definitions 160 governed object 159 lifecycle flow 11 management with scripts 323 removing governance 481 SOA governance 158–187 state machine 159 transitioning the lifecycle state 479 using 476–482 WSRR default 163–167 assemble 165 created 164 deploy 165 manage 166 model 164 retired 167 lifecycle ontology file 160–163 generating 161 modifying 162

898

WebSphere Service Registry and Repository Handbook

Endpoint Lookup 521, 525–536 usage 528 Event Emitter Mediation 521 Extensible Stylesheet Language Transformations 520 Fail 521 Message Element Setter 521 Message Filter 520 Message Logger 520 Stop 521 mediation support 33 message 27 Message Element Setter 521 Message Filter 520 Message Logger 520 MessageArrivalClearing_610 681 MessageArrivalCritical_610 681 MessageSize_610 680 metadata API 100 Model SOA lifecycle 8 modelled relationships 213, 218–242 modelledRelationships parameter 220 Module 384 ModuleDocument 384 monitoring agent 648–649 MQEndpoint 820 mqsichangebroker 785 mqsicreatebroker 785 My Service Registry 330

O object types Export 384 ExportDocument 384 GenericObject 384 Import 384 ImportDocument 384 Module 384 ModuleDocument 384 PolicyDocument 384 SCAExportBinding 385 SCAImportBinding 384 SCAModule 384 SCAWSDLPortType 385 SLSBImportBinding 385 SOAPAddress 384 SOAPBinding 384 Subscription 385 WebServiceExportBinding 385 WebServiceImportBinding 385 WSDLBinding 384 WSDLDocument 384 WSDLMessage 384 WSDLOperaton 384 WSDLPart 384 WSDLPort 384 WSDLPortType 384 WSDLService 384 XMLDocument 384 XMLElement 384 XSDAttribute 384 XSDComplexType 384 XSDDocument 384 XSDSimpleType 384 ObjectType 383, 385 OMEGAMON Distributed 638 OMEGAMON for distributed products 875 OMEGAMON Monitoring Agent 875 OMEGAMON Platform 875 OMEGAMON TEC Event Adapter 688 OMEGAMON XE for WebSphere Business Integration 635 overview 874 OMEGAMON z/OS 638 ontology 87 administration 307–309 creating an ontology system 308 defined 70 delete 322

N name 190 navigation definition file 150 navigation tree 390–394, 397 NetView for z/OS 638 notification 76 NotificationProperties 207 notifiers 197, 203–206 developing custom notifiers 486–491 interfaces 203–206 create method 204 delete method 205 transition method 205 update method 205 properties 211

Index

899

load 322 removing an ontology system 308 ontology Web service 138 operation 28 Operational Efficiency and Resilience 36 Oracle 869 OriginalObject 168–171, 173–174, 176–177, 179, 185, 191, 199–201, 204–206 OriginalObject relationships 223 Out terminal 521 outbound dependencies 214 outputMBeanInterface 294–295 OWL See Web Ontology Language

P parsing 67, 81–82, 84–85, 90, 93, 96, 168, 218–219, 230 Partner Services SOA reference architecture model 14 patterns router pattern 806–809 transcoder pattern 803–806 permission 189–195 action property 190 srrDelete 190 srrManageGov 190 srrRetrieve 190 srrTransition 190 srrUpdate 190 ssrCreate 190 adding permissions to roles 469 administrator permission 193 default permission 192 GenericObject 191 GovernanceManagePermission 194 GovernanceTransitionPermission 194 GovernedCreatePermission 193 GovernedDeletePermission 194 GovernedRetrievePermission 193 GovernedRetrievePermissionA 195 GovernedRetrievePermissionB 195 GovernedUpdatePermission 194 GovernedUserUpdatePermission 195 GraphQuery 191 name 190 OriginalObject 191 PolicyDocument 191

PropertyQuery 191 QueryObject 191 SCAModule 191 target property 191 user permission 195 WSDLDocument 191 XMLDocument 191 XSDDocument 191 persistPolicy 197, 289, 323 persistRoleMappings 197, 289, 323 perspective 394–400 defined 394 definition file 147 mappings 398 name, title, role 396 navigation tree 397 skeleton perspective file 395 physical documents 81 defined 80 dependencies 500–507 Service Component Description Language 81 Web Services Description Language 81 WS-Policy 81 XML Schema Definition 81 PL/I 863 plugins 197–213 configuring 207–213, 494–499 deploying 491–494 developing custom plugins 482–499 notifiers 197, 203–206 custom 486–491 interfaces 203–206 create method 204 delete method 205 transition method 205 update method 205 properties 211 packaging 206 validators 197–203 chains 210 custom 483–486 interfaces 199–202 create method 200 delete method 201 transition method 201 update method 200 validate method 202 properties 207 PolicyDocument 133, 168, 191, 384

900

WebSphere Service Registry and Repository Handbook

port 28 port type 28, 94 portType 126, 142 predicates 106 Process Services SOA reference architecture model 12 programming model 9 promote script 307 properties 84–85, 335–346 add properties to objects 440–442 adding a new custom property 336 deleting a custom property 344 editing a property 340 PropertyQuery 105, 130–132, 191 defined 132 PropertyQueryResult 135, 140–141 defined 141 protocol independence 34 publishing documents 331–335, 438–439

quick search 329

R
RAD See Rational Application Developer Rational Application Developer 62 overview 862 Rational Data Architect overview 861 Rational Software Architect 416–417, 860 overview 860 Rational Software Developer Platform 864 Redbooks Web site 890 Contact us xxi ReflectionException 296–297 refresh books 656 relationship map 111 concrete types 111 supertypes 111, 114 XSD files 111, 116 relationships 85–86, 347–357 common 221 ComplexTypeDefinition 242 creating a new relationship 347 define relationships between objects 442–445 deleting a relationship 357 document 224 editing an existing relationship 354 ElementDeclaration 241 LogicalObject 229 modelled 213, 218–242 OriginalObject 223 SOAPAddress 241 SOAPBinding 237 user defined 213, 243–244 WSDLBinding 235 WSDLDcoument 225 WSDLMessage 233 WSDLOperation 231 WSDLPart 234 WSDLPort 239 WSDLPortType 230 WSDLService 238 XSDDocument 227 Remote Method Invocation/InterORB Protocol (RMI/IIOP) 866 remote procedure call 27 removeAllRolePermissions 197, 288, 323

Q query 103–118, 330, 382–390 See also searching the registry classification functions 108 definition file 150 examples 105–117 GraphQuery 105 limitations 118 predicates 106 PropertyQuery 105 querying by classification 387 querying by property 386 querying by relationship 386 relationship map 111 shortcuts and wildcards 107 treat as 110 using alternative views 385 view query 382–390 query interface 72 QueryClassificationsAllOf 388 QueryClassificationsAnyOf 388 QueryDefinitions 383 QueryExactClassificationsAllOf 388 QueryExactClassificationsAnyOf 388 querying content in WSRR 130 QueryObject 123, 128, 191 creating 128 QueryWizardPrepare 394

Index

901

removeAllRoles 197, 288, 323 removePermissionFromRole 197, 288, 323 removePrincipalFromRole 197, 288, 323 removeRole 197, 288, 323 removing governance 481 reportAllConfigurations 322 request flow 518–519 response flow 518–519 ResponseTimeCritical_610 681 ResponseTimeWarning_610 681 retrieveAllConfigurationNames 287 retrieveConfig script 307 retrieveConfiguration 207, 287, 412 retrieveWithDepth 142 retrieving content from WSRR 128 reusable business functions deployment time 23 runtime 23 role mapping 463–476 adding permissions to roles 469 adding roles 468 mapping users to roles 475 role mapping file 196 root object 168 router pattern 806–809 RPC See remote procedure call run_addVehicle.bat 814 run_testCustomer.bat 814 run_testEntityFlow.bat 815 run_testITService.bat 816 run_testMQ.bat 817 runtime 23 Runtime Integration 36

S
SACL See State Adaptive Choreography Language SAML 872 SCA See Service Component Architecture SCA bindings 517, 535 SCAExportBinding 111, 385 SCAImportBinding 110, 384 SCAModule 168, 191, 384 SCAWSDLPortType 111, 385 script import and export of WSRR entities

exportMetaData 322 importMetaDataa 322 managing access control policy addPermissionToRole 322 addPermissionToRole2 322 addPrincipalToRole 323 addRole 323 getPermissionsForRole 323 getPolicyConfiguration 323 getRoleMappingConfiguration 323 getRoles 323 loadPolicyConfiguration 323 loadRoleMappingConfiguration 323 persistPolicy 323 persistRoleMappings 323 removeAllRolePermissions 323 removeAllRoles 323 removePermissionFromRole 323 removePrincipalFromRole 323 removeRole 323 managing configuration deleteConfiguration 322 loadConfiguration 322 reportAllConfigurations 322 updateConfiguration 322 managing lifecycles setupDefaultLifecyclePermissions 323 updateLifecycleDefinition 323 managing ontologies deleteOntologySystem 322 loadOntologySystem 322 sample command line interface 306 createGenericObject 306 createXMLDocument 306 deleteBaseObject 306 deleteConfig 307 export 306 findBaseObject 306 import 307 loadConfig 307 promote 307 retrieveConfig 307 transition 307 updateConfig 307 SDO See Service Data Objects sdo-int 136 sdo-int.jar 730 sdoType 406

902

WebSphere Service Registry and Repository Handbook

searching the registry 363–369, 431–435 See also query security 139, 187–196, 274, 285, 462–476 CICS 854 configuring 462–476 permission 189–195 See also permission role mapping 463–476 roles 187, 463 user defined roles 188 z/OS 854 Sequence 861 server-side interception 651 service 28, 95 defined 5, 20, 23 service binding definitions 94 Service Component Architecture 96–97, 513, 661, 865 defined 514 Service Component Description Language 81, 89 service consumers 22, 515 logical node 695 Service Data Objects 75, 99–101, 120, 191, 383, 406, 514 data graphs 100 data objects 100 defined 99 valid object types 384 service definition 43 service deployment lifecycle 43 active 44 deprecate 44 plan 44 sunset 44 test 44 service description entities 80–83 defined 72, 80 GenericObject 83 defined 81 logical derivations 82 defined 81 physical documents 81 defined 80 Service Component Description Language 81 Web Services Description Language 81 WS-Policy 81 XML Schema Definition 81 service description metadata 84–88

classifications 86–88 ontology 87 taxonomies 87 Web Ontology Language 87 within WSRR 87 defined 72, 80 properties 84–85 relationships 85–86 Service Details 669–671 Service Development Lifecycle 36 Service Documents 330 service endpoint definitions 94 Service Endpoint Registries/Repositories 36 service interface definitions 94 service lifecycle 76 service message model 46 service message objects 514–515, 519, 521–525 manipulation 525 structure 522–524 context section 524 data section 523 header section 524 Service Metadata 330 service migration 45 service monitoring 47 service orientation defined 20 service ownership 47 Service Port Details 672–674 service providers 21, 515 logical node 695 service registry 22, 46 in SOA governance 46 service registry and repository See also WebSphere Service Registry and Repository Change and Release Management 36 defined 15–17 in a service-oriented architecture 15–17, 34–40 Operational Efficiency and Resilience 36 Runtime Integration 36 Service Development Lifecycle 36 Service Endpoint Registries/Repositories 36 Service Registry view 416–417, 426–427, 434–435, 440, 442, 445, 447, 450 service security 48 service testing 48 service versioning 45 service-oriented architecture

Index

903

a business view 4–18 an IT view 18–40 components service consumer 22 service provider 21 service registry 22 defined 20 by role 20 composite application 20 service 20, 23 service orientation 20 definitions application architecture 19 component model 18 integration architecture 19 drivers flexible pricing 22 increasing speed 22 reducing costs 22 return on investment 22 simplifying integration 22 service deployment time 23 implementation-independent 23 loosely bound 23 reusable 23 runtime 23 Web services 25 ServiceRegistryClient 121, 136 ServiceRegistryClient.jar 730, 784–785 ServiceRegistryException 285 ServiceRegistryGovernance 198, 487 ServiceRegistryGovernanceNotifier 204, 483, 487 ServiceRegistryGovernanceValidator 199–200, 483 ServiceRegistryNotifier 204, 483, 487 ServiceRegistryNotifierJMS 213 ServiceRegistryRepository 282, 285–286, 294, 412 ServiceRegistryRepositoryProxy 293–294 ServiceRegistrySession 198, 487 ServiceRegistryStatus 200–203, 210 return codes 202 ServiceRegistryValidationException 200–202, 210 ServiceRegistryValidator 199, 483 ServiceRegistryWebServiceException 142 Services Management workspace 663–664 overview 663 Services Overview 666–668 setenv.bat 265–266, 269, 271, 275–280, 810

setenv.sh 268, 279–280 setupDefaultLifecyclePermissions 323 shortcuts and wildcards 107 ShowPreferences 394 Simple Object Access Protocol body 27 defined 27 encoding rules 27 envelope 27 headers 27 message format 27 remote procedure call representation 27 transports 27 SimpleTypeDefinition 111, 134 situation 678–690 attribute tables 681–682 overview 679 predefined 680 Fault_610 680 MaxMessageSize_610 680 MaxResponseTimeCritical_610 681 MaxResponseTimeWarning_610 681 MessageArrivalClearing_610 681 MessageArrivalCritical_610 681 MessageSize_610 680 ResponseTimeCritical_610 681 ResponseTimeWarning_610 681 Situation Event Console 875 SLSBImportBinding 111, 385 SMO See service message objects SOA See service-oriented architecture SOA Foundation 6 SOA governance 40–49, 57, 64–65, 76–77, 157–244, 461–509 See also governance auditing 77 configuring 461–509 defined 40 GovernanceRecord 167–187 governed collections 169–179 adding an object 171 best practices 179–187 removing an object 174 governed object 159 lifecycle 158–187, 476–482 WSRR default 163–167 assemble 165

904

WebSphere Service Registry and Repository Handbook

created 164 deploy 165 manage 166 model 164 retired 167 making an object governable 158 notification 76 root object 168 service definition 43 service deployment lifecycle 43 active 44 deprecate 44 plan 44 sunset 44 test 44 service lifecycle 76 service message model 46 service migration 45 service monitoring 47 service ownership 47 service registry 46 service security 48 service testing 48 service versioning 45 validation 76 SOA lifecycle 5, 7–11, 158–187, 476–482 See also lifecycle Assemble 8 definitions 160 Deploy 9 lifecycle flow 11 Manage 10 Model 8 state machine 159 SOA management 36–39, 626–631 SOA reference architecture model 11–18 Access Services 13 Business Application Services 13 Business Innovation and Optimization Services 17 Information Services 13 Infrastructure Services 18 Interaction Services 12 IT Service Management 17 Partner Services 14 Process Services 12 SOAP See Simple Object Access Protocol SOAP API 139–144

bsrURI 141 DataGraphType 140 portType 142 PropertyQueryResult 141 WSRR type 140 SOAPAddress 384 SOAPAddress relationships 241 SOAPBinding 134, 384 SOAPBinding relationships 237 SOAPPort 134 SRDispatchVirtualService 790, 794, 820 SRGetVirtualService 790–791 SRGovernanceValidator 209 SRProcessVirtualService 790, 793 SrrAuthCheckedPolicyXacml 196 SrrAuthzRoleMappingXacml 196 srrCreate 190, 193 srrDelete 190, 194 SRRetrieveEntity 791, 797 SRRetrieveITService 791, 795 srrManageGov 190, 194 srrRetrieve 190, 193 srrTransition 190, 194 srrUpdate 190, 194 SRTemplateValidator 209 SRXMLHelper 123–124, 127 state 167 State Adaptive Choreography Language defined 160 state machine 159, 861 static binding 22, 58 static programming model 100 Stop 521 Subscription 385 supertypes 111, 114 supported APIs 74 Swift 867

T target property 191 taxonomies 87 TCORE See Tivoli Common Object Repository TDW See Tivoli Data Warehouse TEC See Tivoli Enterprise Console TEMA

Index

905

See Tivoli Enterprise Monitoring Agent templates 88–89 TEMS See Tivoli Enterprise Monitoring Server TEPS See Tivoli Enterprise Portal Server Tivoli Access Manager overview 871 Tivoli Common Object Repository 656 Tivoli Composite Application Manager Candle product integration 875 overview 634 Tivoli Composite Application Manager for CICS Transactions 635 overview 874 Tivoli Composite Application Manager for IMS Transactions overview 874 Tivoli Composite Application Manager for Response Time Tracking 634, 638 overview 873 Tivoli Composite Application Manager for SOA 166, 634, 638, 640–653 components 647 integration scenarios with WebSphere Service Registry and Repository 654 overview 641, 870, 873 product features 644 situation 678–690 overview 679 predefined 680 Tivoli Composite Application Manager for SOA Event Handler 687–689, 698 configuring 731–746 event properties 737 installation 729–730 overview 689, 728–729 Tivoli Composite Application Manager for WebSphere 635, 638 overview 873 Tivoli Data Warehouse 640 Tivoli Enterprise Console 638, 687, 689, 729, 733, 739, 746, 752–754 Tivoli Enterprise Monitoring Agent 875 overview 638 Tivoli Enterprise Monitoring framework 636–640, 692, 746 Tivoli Enterprise Monitoring Server 875 overview 636

Tivoli Enterprise Portal 875–876 Tivoli Enterprise Portal clients overview 637 Tivoli Enterprise Portal Server 875 overview 637 Tivoli Federated Identity Manager overview 872 Tivoli Management Framework 753 Tivoli management services 875 Tivoli Monitoring 638, 875 Tivoli OMEGAMON XE for Messaging overview 870 transcoder pattern 803–806 transition method 205 transition script 307 treat as 110 trustStore 430 types 27

U
UDDI See Universal Description, Discovery, and Integration UML 2.0 861 Unified Service Metadata 329 Universal Description, Discovery, and Integration defined 28, 65 update method 205 updateConfig script 307 updateConfiguration 207, 287, 322, 412 updateLifecycleDefinition 323 updating content in WSRR 129 upgrading WebSphere Service Registry and Repository 279 URLEndpoint 820 Use Case 861 user defined relationships 213, 243–244 user defined roles 188 user interfaces 73 Eclipse plug-in 73, 415–451 Web interface 73 user permission 195 UserDefinedProperty 114 UserDefinedRelationship 114

V validation 76

906

WebSphere Service Registry and Repository Handbook

ValidationProperties 207 validators 197–203 chains 210 developing custom validators 483–486 interfaces 199–202 create method 200 delete method 201 transition method 201 update method 200 validate method 202 properties 207 ViewDetail 405 VSAM 869

W
WASPORT 267–268, 276–278 Web interface 73 Web Ontology Language 16, 87, 307–308, 322, 661 defined 70 loading an OWL file 358 Web Service bindings 517 Web Service Federation Language (WS-Federation) 872 Web services and SOA 25 client 136 core elements extensible markup language 26 Simple Object Access Protocol 27 SOAP 27 Universal Description, Discovery, and Integration 28 Web Services Description Language 27 XML 26 XML Schema Definition 27 installation 546 Web Services Description Language 532 Web services API 136–144 EJB client 136 ontology Web service 138 Web services client 136 Web Services Description Language 16, 25, 58, 67–68, 80–81, 89, 91, 94–96, 126, 179, 329–331, 335, 516, 532, 657, 660 binding 28, 95 CICS 826 creating using Java API 125

defined 27, 54 import Web Services Description Language documents 500 message 27 operation 28 parsing 67, 82, 90, 96, 219, 230 port 28 port type 28, 94 publishing from CICS 842 publishing from z/OS 834 retrieve 435 retrieving from z/OS 847 searching for 417 service 28, 95 service binding definitions 94 service endpoint definitions 94 service interface definitions 94 types 27 versions 662 Web Services Inspection Language defined 28 Web UI 144–154, 327–379, 381–413 Administration 331 Classification Systems 330 classifying objects 358–363 collection 151–152, 401–410 concepts 370–379 See also concepts concepts and architecture 144–154 customizing 381–413 definition files 146–154 collection 151–152 detail 152 hierarchy 147 navigation 150 perspective 147 query 150 deleting artefacts 369–370 detail 152 layout 145–147 My Service Registry 330 navigation 150 navigation tree 390–394 perspective 147, 394–400 properties 335–346 publishing documents 331–335 query 103–118, 150, 330, 382–390 quick search 329 relationships 347–357

Index

907

searching the registry 363–369 Service Documents 330 Service Metadata 330 Unified Service Metadata 329 using 329–331 Web user interface See Web UI WebService 661 WebServiceExportBinding 111, 385 WebServiceImportBinding 111, 385 WebSphere 526 WebSphere Adapter bindings 518 WebSphere Application Server installing 254–256 WebSphere Application Server Base Edition overview 866 WebSphere Application Server Express Edition overview 866 WebSphere Application Server ND installing 277–279 WebSphere Application Server Network Deployment overview 866 WebSphere Broker JMS Transport 775 WebSphere Business Modeler 62 overview 860 WebSphere Business Monitor overview 869 WebSphere Community Edition (CE) overview 866 WebSphere Developer for zSeries V6.0.1 864 WebSphere Enterprise Service Bus key terms 514 overview 512–514, 867 structure 515–521 WSRR definition 536–543 WebSphere ESB See WebSphere Enterprise Service Bus WebSphere Extended Deployment (XD) overview 866 WebSphere Information Integration Server overview 869 WebSphere Information Server 63 WebSphere Integration Developer 62–63, 417–418, 431, 513, 520, 526, 860 overview 865 WebSphere Message Broker 771–823 components 776 overview 772–779, 867

supported transports WebSphere Broker JMS Transport 775 WebSphere MQ Enterprise Transport 775 WebSphere MQ Mobile Transport 775 WebSphere MQ Multicast Transport 775 WebSphere MQ Real-time Transport 775 WebSphere MQ Telemetry Transport 775 WebSphere MQ Web Services Transport 775 WebSphere Message Broker V6 Client for WebSphere Service Registry and Repository 382, 771–823 installation 780–786 overview 786–789 patterns 803–823 router pattern 806–809 setting up 809–823 transcoder pattern 803–806 prerequisites 779 WebSphere MQ bindings 518 WebSphere MQ Enterprise Transport 775 WebSphere MQ JMS bindings 517 WebSphere MQ Mobile Transport 775 WebSphere MQ Multicast Transport 775 WebSphere MQ Real-time Transport 775 WebSphere MQ Telemetry Transport 775 WebSphere MQ Web Services Transport 775 WebSphere Portal overview 868 WebSphere Process Server overview 868 WebSphere Service Registry and Repository See also service registry and repository administration command line 283 command line interface 299–307 JMX 282, 292–298 wsadmin 282, 285–292 wsadmin scripts 321–323 authorization policy file 196 Change and Release Management 36 classifying objects 358–363 concepts 370–379 See also concepts configuration 283–285 See also configuration supported configurations 284 content model See information model

908

WebSphere Service Registry and Repository Handbook

deleting artefacts 369–370 deploying 265–275 Eclipse UI 416–451 See also Eclipse UI Environment Promotion 319–321 defined 319 sample script 319 impact analysis 213–244, 499–509 dependency depth 217 inbound dependencies 216 outbound dependencies 214 import/export 311–318 export 311 import 313 information model 71–72, 79–118 See also information model BaseObject 101–103 document types 89–98 query 103–118, 382–390 Service Data Objects 99–101 service description entities 80–83 service description metadata 84–88 templates 88–89 XPath 99 installing 258–264 integration scenarios with Tivoli Composite Application Manager for SOA 654 limits 59–66 Operational Efficiency and Resilience 36 plugins 197–213, 482–499 See also plugins pre-requisite software 249 properties 335–346 publishing documents 331–335, 438–439 relationships 347–357 See also relationships remote DB installing 275–277 requirements 248–249 role mapping file 196 Runtime Integration 36 searching the registry 363–369, 431–435 security 187–196, 274, 285, 462–476 See also security permission 189–195 See also permission roles 187 user defined roles 188 Service Development Lifecycle 36

Service Endpoint Registries/Repositories 36 SOA governance 40–49, 57, 64–65, 76–77, 157–244 See also SOA governance auditing 77 notification 76 service lifecycle 76 validation 76 supported databases 248 supported platforms 248 topology selection criteria 249 upgrading 279 Web UI 144–154, 327–379, 381–413 See also Web UI WSRR definition 536–543 WebSphereCell 660 WebSphereCluster 660 WebSphereNode 660 WebSphereServer 660 WESB See WebSphere Enterprise Service Bus WID See WebSphere Integration Developer WMB See WebSphere Message Broker wsadmin discover WSRR MBean notifications 289 invoke operations on WSRR Mbean 289 script import and export of WSRR entities exportMetaData 322 importMetaData 322 managing access control policy addPermissionToRole 322 addPermissionToRole2 322 addPrincipalToRole 323 addRole 323 getPermissionsForRole 323 getPolicyConfiguration 323 getRoleMappingConfiguration 323 getRoles 323 loadPolicyConfiguration 323 loadRoleMappingConfiguration 323 persistPolicy 323 persistRoleMappings 323 removeAllRolePermissions 323 removeAllRoles 323 removePermissionFromRole 323 removePrincipalFromRole 323

Index

909

removeRole 323 managing configuration deleteConfiguration 322 loadConfiguration 322 reportAllConfigurations 322 updateConfiguration 322 managing lifecycles setupDefaultLifecyclePermissions 323 updateLifecycleDefinition 323 managing ontologies deleteOntologySystem 322 loadOntologySystem 322 setting up 285 troubleshooting WSRR administration 291 WebSphere Service Registry and Repository administration 282, 285–292 WebSphere Service Registry and Repository administration scripts 321–323 WS-BPEL See Business Process Execution Language for Web Services WSDL See Web Services Description Language WSDL2Java 138 WSDLBinding 105, 133–134, 384 WSDLBinding relationships 235 WSDLDocument 88, 104, 116, 126–127, 133, 140, 168, 191, 384, 398, 487 WSDLDocument relationships 225 WSDLMessage 133–134, 384 WSDLMessage relationships 233 WSDLOperation 133–134, 384, 507 WSDLOperation relationships 231 WSDLPart 133, 384 WSDLPart relationships 234 WSDLPort 105, 133–135, 140, 384, 486–487 WSDLPort relationships 239 WSDLPortType 118, 126, 133–135, 384 WSDLPortType relationships 230 WSDLService 105–110, 116, 133–135, 140, 383–385, 398 WSDLService relationships 238 WSEndpoint 660 WSIL See Web Services Inspection Language WSOperation 660–661 WS-Policy 81, 89, 98 WSPort 659, 661 WSPortType 661

WSRR definition 536–543 WSRR type SOAP 140 wsrr.properties 782–783 wsrrcli 299 wsrrcli.bat 300 wsrrcli.conf 300 wsrrcli.sh 300 wsrrcli.conf 811 WSRRCodeSDOClient 137 WSRRConnectionFactory 302 WSRRLocation 733, 741 WSRRPropertyName 735 WSRRPropertyValue 736 wsrrsetparms 782, 784

X
XACML See Extensible Access Control Markup Language XML See extensible markup language XML metadata 98 XML Path Language See XPath XML Pointer Language 99 XML Schema Definition 16, 81, 89, 91–93 defined 27, 54 import 126 include 126 parsing 67, 82, 85, 90, 93 redefine 126 XML Services for the Enterprise (XSE) 864 XMLDocument 133, 168, 191, 384 XMLElement 384 XPath 72, 99, 114 defined 99 XPointer See XML Pointer Language XSD See XML Schema Definition XSD files 111, 116 XSDAttribute 384 XSDComplexType 384 XSDDocument 133, 168, 191, 384 XSDDocument relationships 227 XSDSimpleType 384 XSLT

910

WebSphere Service Registry and Repository Handbook

See Extensible Stylesheet Language Transformations XSLT editor 607–608 XSLT mapping 606–607 XSLTransformationRequest 602, 606, 613 XSLTransformationResponse 607

Index

911

912

WebSphere Service Registry and Repository Handbook

WebSphere Service Registry and Repository Handbook

(1.5” spine) 1.5” 1.998” 789 1051 pages

Back cover

®

WebSphere Service Registry and Repository Handbook
Best practices Sample integration scenarios SOA governance
Service-oriented architecture offers the promise of business agility and resilience through reuse, loose coupling, flexibility, interoperability, integration and governance. These are realized by separating service descriptions from their implementations, and using this descriptive metadata across the service lifecycle. Standards-based service metadata artefacts, such as Web Service Description Language, XML schema, policy or Service Component Architecture documents, capture the technical details of what a service can do, how it can be invoked, or what it expects other services to do. Semantic annotations and other metadata can be associated with these artefacts to offer insight to potential users of the service about how and when it can be used, and what purposes it serves. IBM WebSphere Service Registry and Repository (WSRR) is the master metadata repository for service interaction endpoint descriptions. As the integration point of service metadata, WSRR establishes a central point for finding and managing service metadata. Once service metadata is placed in WSRR, visibility is controlled, versions are managed, proposed changes are analyzed and communicated, and usage is monitored. This IBM Redbook discusses the architecture and functions of IBM WebSphere Service Registry and Repository along with sample integration scenarios that can be used as examples for implementing WebSphere Service Registry and Repository in a customer service-oriented architecture environment.

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

SG24-7386-00

ISBN 0738489972