UDDI Spec TC

 

UDDI Version 3.0.1

UDDI Spec Technical Committee Specification, Dated 20031014

 

Document identifier:

uddi_v3

Current version:

http://uddi.org/pubs/uddi-v3.0.1-20031014.htm

Latest version:

http://uddi.org/pubs/uddi_v3.htm

Previous version:

http://uddi.org/pubs/uddi-v3.00-published-20020719.htm

Editors:

Tom Bellwood, IBM

Luc Clément, Microsoft

Claus von Riegen, SAP

Contributors:

Bob Atkinson, Microsoft

Tom Bellwood, IBM

Maud Cahuzac, France Telecom

Luc Clément, Microsoft

John Colgrave, IBM

Ugo Corda, SeeBeyond Technology

Alexandru Czimbor, OSS Nokalva

Matthew J. Dovey, Individual Member

Daniel Feygin, UnitSpace

Shishir Garg, France Telecom

Rajul Gupta, OSS Nokalva

Andrew Hately, IBM

Brad Henry, Individual Member

Aikichi Kawai, NTT USA

Paul Macias, LMI

Anne Thomas Manes, Individual Member

Claus von Riegen, SAP

Tony Rogers, Computer Associates

Alok Srivastava, Oracle

Paul Thorpe, OSS Nokalva

Alessandro Triglia, OSS Nokalva

Max Voskob, Individual Member

George Zagelow, IBM

 

Abstract:

The UDDI Version 3.0.1 Specification describes the Web services, data structures and behaviors of all instances of a UDDI registry. 

Status:

This specification has attained the status of Committee Specification. This document is updated periodically on no particular schedule.

 

Committee members should send comments on this Committee Specification to the uddi-spec@lists.oasis-open.org list. Others should subscribe to and send comments to the uddi-spec-comment@lists.oasis-open.org list. To subscribe, send an email message to uddi-spec-comment-request@lists.oasis-open.org with the word "subscribe" as the body of the message.

 

For information on whether any intellectual property claims have been disclosed that may be essential to implementing this Committee Specification, and any offers of licensing terms, please refer to the Intellectual Property Rights section of the UDDI Spec TC web page (http://www.oasis-open.org/committees/uddi-spec/ipr.php).

 

Copyrights:

Copyright © 2001-2002 by Accenture, Ariba, Inc., Commerce One, Inc., Fujitsu Limited, Hewlett-Packard Company, i2 Technologies, Inc., Intel Corporation, International Business Machines Corporation, Microsoft Corporation, Oracle Corporation, SAP AG, Sun Microsystems, Inc., and VeriSign, Inc.  All Rights Reserved.

 

Copyright © OASIS Open 2002-2003. All Rights Reserved.

 


 

Content

1       Introduction. 14

1.1 About this specification. 14

1.2 Language & Terms. 14

1.3 Diagrams Used in this document 15

1.3.1 Attributes and elements. 15

1.3.2 Element structure. 15

1.3.3 Cardinality. 15

1.4 Related Documents. 16

1.4.1 Translations of the UDDI Specification. 16

1.4.2 Best Practices and Technical Notes. 16

1.5 Base UDDI Architecture. 16

1.5.1 UDDI Data. 16

1.5.2 UDDI Services and API Sets. 17

1.5.3 UDDI Nodes. 17

1.5.4 UDDI Registries. 18

1.5.5 Affiliations of Registries. 18

1.5.6 Person, Publisher and Owner 18

1.5.7 Transfer of ownership. 18

1.5.8 Data Custody. 18

1.6 Representing Information within UDDI 19

1.6.1 Representing Businesses and Providers with “businessEntity” 19

1.6.2 Representing Services with “businessService” 20

1.6.3 Representing Web services with “bindingTemplate” 20

1.6.4 Technical Models (tModels) 20

1.6.5 Taxonomic Classification of the UDDI entities. 21

1.7 Introduction to Security. 22

1.8 Introduction to Internationalization. 22

1.8.1 Multi-regional businesses. 22

1.8.2 XML and Unicode Character Set 23

1.8.3 Standardized Postal Address. 23

1.8.4 Use of Multi-languages and Multi-scripts. 23

1.8.5 Adding Language-specific Sort Orders. 23

1.8.6 Consistent Internationalized Search. 24

2       UDDI Schemas. 25

2.1 Schema versioning. 27

2.2 Schema Extensibility. 28

2.3 Element and attribute types and lengths. 28

2.3.1 Data structure, publication API, inquiry API and security API 28

2.3.2 Subscription API 29

2.3.3 Replication API 29

3       UDDI Registry Data Structures. 30

3.1 Data structure overview.. 30

3.2 Design Principles. 30

3.2.1 Keys as unique identifiers. 31

3.2.2 Containment and references. 31

3.2.3 Collections. 31

3.2.4 Optional attributes. 31

3.3 businessEntity Structure. 32

3.3.1 Structure diagram.. 32

3.3.2 Documentation. 32

3.4 businessService Structure. 39

3.4.1 Structure Diagram.. 40

3.4.2 Documentation. 40

3.5 bindingTemplate Structure. 41

3.5.1 Structure Diagram.. 42

3.5.2 Documentation. 42

3.6 tModel Structure. 46

3.6.1 Common tModel uses. 46

3.6.2 Structure diagram.. 48

3.6.3 Documentation. 48

3.7 publisherAssertion Structure. 49

3.7.1 Structure Diagram.. 49

3.7.2 Documentation. 49

3.8 operationalInfo Structure. 50

3.8.1 Structure diagram.. 50

3.8.2 Documentation. 50

4       Using UDDI APIs. 52

4.1 SOAP Usage. 52

4.1.1 Support for SOAPAction. 52

4.1.2 Support for SOAP Actor 53

4.1.3 Support for SOAP encoding. 53

4.1.4 Support for SOAP Headers. 53

4.1.5 Support for SOAP Fault 53

4.1.6 XML prefix conventions – default namespace support 54

4.2 XML Encoding Requirements. 54

4.3 Support for Unicode: Byte Order Mark. 54

4.4 About uddiKeys. 55

4.4.1 Key Syntax. 55

4.4.2 Examples of keys. 56

4.5 Data insertion and document order 57

4.5.1 Inserting Data in Entities During save_xx Operations. 57

4.5.2 Inserting Elements in Existing Entities. 57

4.5.3 Preservation of Document Order 57

4.6 XML Normalization and Canonicalization. 57

4.6.1 Behavior of UDDI nodes. 57

4.6.2 Client Behavior 58

4.7 About Access Control and the authInfo Element 58

4.8 Success and Error Reporting. 60

4.8.1 dispositionReport element 60

4.8.2 Success reporting using the dispositionReport element 61

4.8.3 Error reporting using the dispositionReport element 62

5       UDDI Programmers APIs. 63

5.1 Inquiry API Set 63

5.1.1 The browse pattern. 63

5.1.2 The drill-down pattern. 63

5.1.3 The invocation pattern. 64

5.1.4 Find Qualifiers. 64

5.1.5 Use of listDescription. 72

5.1.6 About wildcards. 73

5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups. 73

5.1.8 Inquiry API functions. 73

5.1.9 find_binding. 74

5.1.10 find_business. 77

5.1.11 find_relatedBusinesses. 81

5.1.12 find_service. 86

5.1.13 find_tModel 89

5.1.14 get_bindingDetail 92

5.1.15 get_businessDetail 93

5.1.16 get_operationalInfo. 94

5.1.17 get_serviceDetail 95

5.1.18 get_tModelDetail 96

5.2 Publication API Set 98

5.2.1 Publishing entities with node assigned keys. 98

5.2.2 Publishing entities with publisher-assigned keys. 98

5.2.3 Special considerations for validated value sets. 102

5.2.4 Special considerations for the xml:lang attribute. 103

5.2.5 Publisher API summary. 103

5.2.6 add_publisherAssertions. 104

5.2.7 delete_binding. 106

5.2.8 delete_business. 107

5.2.9 delete_publisherAssertions. 109

5.2.10 delete_service. 110

5.2.11 delete_tModel 111

5.2.12 get_assertionStatusReport 113

5.2.13 get_publisherAssertions. 116

5.2.14 get_registeredInfo. 117

5.2.15 save_binding. 118

5.2.16 save_business. 121

5.2.17 save_service. 125

5.2.18 save_tModel 128

5.2.19 set_publisherAssertions. 132

5.3 Security Policy API Set 134

5.3.1 discard_authToken. 134

5.3.2 get_authToken. 135

5.4 Custody and Ownership Transfer API Set 137

5.4.1 Overview.. 137

5.4.2 Custody Transfer Considerations. 138

5.4.3 Transfer Execution. 139

5.4.4 discard_transferToken. 141

5.4.5 get_transferToken. 142

5.4.6 transfer_entities. 144

5.4.7 transfer_custody. 146

5.4.8 Security Configuration for transfer_custody. 147

5.5 Subscription API Set 148

5.5.1 About UDDI Subscription API functions. 148

5.5.2 Specifying Durations. 149

5.5.3 Specifying Points in Time. 149

5.5.4 Subscription Coverage Period. 150

5.5.5 Chunking of Returned Subscription Data. 150

5.5.6 Use of keyBag in Subscription. 150

5.5.7 Subscription API functions. 151

5.5.8 save_subscription. 152

5.5.9 delete_subscription. 155

5.5.10 get_subscriptions. 156

5.5.11 get_subscriptionResults. 157

5.5.12 notify_subscriptionListener 160

5.6 Value Set API Set 162

5.6.1 Value Set Programming Interfaces. 162

5.6.2 validate_values. 163

5.6.3 get_allValidValues. 165

6       Node Operation. 168

6.1 Managing Node Contents. 168

6.1.1 XML Requirements. 168

6.1.2 Key Generation and Maintenance. 169

6.1.3 Updates and Deletions. 169

6.2 Considerations When Instantiating a Node. 169

6.2.1 Canonical tModel Bootstrapping. 169

6.2.2 Self-Registration of Node Business Entity. 169

6.3 User Credential Requirements. 170

6.3.1 Establishing User Credentials. 170

6.3.2 Changing Entity Ownership. 170

6.4 Checked Value Set Validation. 171

6.4.1 Normative behavior during saves. 171

6.5 HTTP GET Services for UDDI Data Structures. 171

7       Inter-Node Operation. 173

7.1 Inter-Node Policy Assertions. 173

7.1.1 Data Custody. 173

7.2 Concepts and Definitions. 174

7.2.1 Update Sequence Number 174

7.2.2 Change Records. 175

7.2.3 Change Record Journal 176

7.2.4 High Water Mark Vector 176

7.2.5 Replication Messages. 176

7.2.6 Replication Processing. 177

7.3 Change Record Structures. 178

7.3.1 changeRecordNull 180

7.3.2 changeRecordNewData. 180

7.3.3 changeRecordHide. 181

7.3.4 changeRecordDelete. 181

7.3.5 changeRecordPublisherAssertion. 182

7.3.6 changeRecordDeleteAssertion. 183

7.3.7 changeRecordAcknowledgment 184

7.3.8 changeRecordCorrection. 184

7.3.9 changeRecordNewDataConditional 184

7.4 Replication API Set 187

7.4.1 get_changeRecords Message. 187

7.4.2 notify_changeRecordsAvailable Message. 189

7.4.3 do_ping Message. 190

7.4.4 get_highWaterMarks Message. 191

7.5 Replication Configuration. 192

7.5.1 Replication Configuration Structure. 192

7.5.2 Configuration of a UDDI Node – operator element 193

7.5.3 Replication Communication Graph. 194

7.5.4 SOAP Configuration. 195

7.5.5 Security Configuration. 195

7.6 Error Detection and Processing. 195

7.6.1 UDDI Registry Investigation and Correction. 196

7.7 Validation of Replicated Data. 200

7.8 Adding a Node to a Registry Using Replication. 200

7.9 Removing a Node from a Registry Using Replication. 201

8       Publishing Across Multiple Registries. 202

8.1 Relationships between Registries. 203

8.1.1 Root Registries and Affiliate Registries. 203

8.1.2 A Closer Look at Inter-Registry Communication Models. 203

8.2 Data Management Policies and Procedures Across Registries. 205

8.2.1 Establishing a Relationship with a Root Registry. 205

8.2.2 Data Sharing. 206

9       Policy. 208

9.1 Definitions. 208

9.2 Policy  208

9.3 Representation of Policy. 208

9.3.1 Policy Schema. 210

9.3.2 Policy Documents. 210

9.3.3 Policy Service within UDDI 211

9.3.4 Policy Modeling. 211

9.4 UDDI Registry Policy Abstractions. 211

9.4.1 Registry Policy Delegation. 212

9.4.2 Registry General Keying Policy. 212

9.4.3 UDDI keying scheme. 212

9.4.4 UDDI Information Access Control Policy. 213

9.4.5 Adding nodes to a registry. 213

9.4.6 Person, Publisher and Owner 213

9.4.7 Transfer of Ownership. 214

9.4.8 Registry Authorization Policy. 214

9.4.9 Modeling Authorization. 214

9.4.10 Registry Data Integrity. 215

9.4.11 Registry Approved Certificate Authorities. 215

9.4.12 Registry Data Confidentiality. 215

9.4.13 Registry Audit Policy. 215

9.4.14 Registry Privacy Policy. 216

9.4.15 Registry Clock Synchronization Policy. 216

9.4.16 Registry Replication Policy. 216

9.4.17 Support for Custody Transfer 216

9.4.18 Registry Subscription Policy. 216

9.4.19 Registry Value Set Policies. 217

9.5 UDDI Node Policy Abstractions. 218

9.5.1 Node Key Generation. 218

9.5.2 Node Publisher Generated Key Assertion. 218

9.5.3 Node Information Policy. 218

9.5.4 Node Authorization Policy. 218

9.5.5 Node Registration and Authentication. 218

9.5.6 Node Publication Limits. 219

9.5.7 Node Policy for Contesting Entries. 219

9.5.8 Node Audit Policy. 219

9.5.9 Node Sort Order Policy. 219

9.5.10 Find Qualifier Policy. 219

9.5.11 Node Approved Certificate Authorities. 220

9.5.12 Node Subscription API Assertion. 220

9.5.13 Node Element Limits. 220

9.5.14 Node HTTP GET Services. 220

9.5.15 Node discoveryURL Generation. 220

9.5.16 Node XML Encoding Policy. 220

9.6 UDDI Recommended Registry Policies. 221

9.6.1 Key Generator tModels. 221

9.6.2 Information Model 221

9.6.3 Domain key generator tModels. 222

9.6.4 Replication Policies. 222

9.6.5 Value sets. 223

9.7 UDDI Policy Summary. 224

9.7.1 UDDI Registry Policy Abstractions. 224

9.7.2 UDDI Node Policy Abstractions. 228

10      Multi-Version Support 231

10.1 Entity Key Compatibility with Earlier Versions of UDDI 231

10.1.1 Generating Keys From a Version 3 API Call 231

10.1.2 Generating Keys from a Version 2 API Call 232

10.1.3 Migrating Version 2 keys to a Version 3 Registry. 233

10.1.4 Mapping v1/v2 Canonical tModel Keys to v3 Evolved Keys. 233

10.2 Other Considerations of Version 2 Inquiry API Calls. 235

10.2.1 keyedReferenceGroup data. 235

10.2.2 keyedReference data. 235

10.2.3 Multiple overviewDoc data. 235

10.2.4 Multiple personName data. 235

10.2.5 Multiple xml:lang attributes of the same language. 235

10.2.6 New error codes. 235

10.2.7 Service Projections. 235

10.2.8 Length Discrepancies. 235

10.2.9 Schema Assessment 235

10.2.10 White Space Handling. 236

10.2.11 Mapping Between URLType and useType attribute on accessPoint 236

10.2.12 Supporting External Value Set Providers Across Versions. 236

10.2.13 Sorting and Matching Behavior 236

10.2.14 XML Encoding. 236

10.3 Data Migration Considerations. 236

10.3.1 Version 3 Schema Strictness. 236

10.4 Considerations of Version 2 Publish API Calls. 238

10.4.1 Data update semantics consistent with request namespace. 238

10.4.2 keyedReference data. 239

10.5 Value sets with entity keys as valid values. 239

11      Utility tModels and Conventions. 240

11.1 Canonical Category Systems, Identifier Systems and Relationship Systems. 240

11.1.1 UDDI Types Category System.. 241

11.1.2 General Keyword Category System.. 245

11.1.3 UDDI Nodes Category System.. 248

11.1.4 UDDI Relationships System.. 250

11.1.5 UDDI “Owning Business” Category System.. 252

11.1.6 UDDI “Is Replaced By” Identifier System.. 253

11.1.7 UDDI “Validated By” Category System.. 256

11.1.8 UDDI “Derived From” Category System.. 258

11.1.9 UDDI “Entity Key Values” Category System.. 262

11.2 UDDI Registry API tModels. 263

11.2.1 UDDI Inquiry API 263

11.2.2 UDDI Publication API 265

11.2.3 UDDI Security API 269

11.2.4 UDDI Replication API 270

11.2.5 UDDI Custody and Ownership Transfer API 272

11.2.6 UDDI Node Custody Transfer API 274

11.2.7 UDDI Value Set Caching API 275

11.2.8 UDDI Value Set Validation API 277

11.2.9 UDDI Subscription API 278

11.2.10 UDDI Subscription Listener API 280

11.3 Transport and Protocol tModels. 282

11.3.1 Secure Sockets Layer Version 3 with Server Authentication. 282

11.3.2 Secure Sockets Layer Version 3 with Mutual Authentication. 283

11.3.3 UDDI HTTP Transport 285

11.3.4 UDDI SMTP Transport 287

11.3.5 UDDI FTP Transport 288

11.3.6 UDDI Fax Transport 289

11.3.7 UDDI Telephone Transport 290

11.4 Find Qualifier tModels. 292

11.4.1 UDDI SQL99 Approximate Match Find Qualifier 292

11.4.2 UDDI Exact Match Find Qualifier 294

11.4.3 UDDI Case Insensitive Match Find Qualifier 295

11.4.4 UDDI Case Sensitive Match Find Qualifier 297

11.4.5 UDDI Diacritics Insensitive Match Find Qualifier 299

11.4.6 UDDI Diacritics Sensitive Match Find Qualifier 300

11.4.7 UDDI Binary Sort Order Qualifier 302

11.4.8 UDDI Unicode Technical Standard #10 Sort Order Qualifier 303

11.4.9 UDDI Case Insensitive Sort Find Qualifier 305

11.4.10 UDDI Case Sensitive Sort Find Qualifier 307

11.4.11 UDDI Sort By Name Ascending Find Qualifier 309

11.4.12 UDDI Sort By Name Descending Find Qualifier 312

11.4.13 UDDI Sort By Date Ascending Find Qualifier 314

11.4.14 UDDI Sort By Date Descending Find Qualifier 316

11.4.15 UDDI And All Keys Find Qualifier 317

11.4.16 UDDI Or All Keys Find Qualifier 319

11.4.17 UDDI Or Like Keys Find Qualifier 321

11.4.18 UDDI Combine Category Bags Find Qualifier 323

11.4.19 UDDI Service Subset Find Qualifier 324

11.4.20 UDDI Binding Subset Find Qualifier 326

11.4.21 UDDI Suppress Projected Services Find Qualifier 328

11.4.22 UDDI Signature Present Find Qualifier 330

11.5 Other Canonical tModels. 332

11.5.1 Domain Key Generator for the UDDI Domain. 332

11.5.2 UDDI Hosting Redirector Specification. 334

11.5.3 UDDI Policy Description Specification. 336

12      Error Codes. 338

12.1 Common Error Conditions. 340

13      Related Standards and Specifications. 341

13.1 UDDI Specifications and documents. 341

13.2 Standards and other Specifications. 341

A       Appendix A: Relationships and Publisher Assertions. 343

A.1        Example. 343

A.2        Managing relationship visibility. 344

B       Appendix B:  Using and Extending the useType Attribute. 345

B.1        accessPoint 345

B.1.1       Using the “endPoint” value. 345

B.1.2       Using the “wsdlDeployment” value. 346

B.1.3       Using the “bindingTemplate” value. 346

B.1.4       Using the “hostingRedirector” value. 347

B.2        overviewURL. 348

B.2.1       Using the “text” value. 349

B.2.2       Using the “wsdlInterface” value. 349

B.3        discoveryURL. 350

B.3.1       Using the “businessEntity” value. 350

B.3.2       Using the “homepage” value. 350

B.4        Contact 350

B.5        Address. 350

B.6        Phone. 350

B.7        Email 350

B.8        Designating a new useType value. 350

C       Appendix C:  Supporting Subscribers. 352

C.1        Subscription Scenarios. 352

C.2        Using Subscription. 353

C.2.1       Steps for Creating a Subscription. 353

C.2.2       Subscription Examples. 353

D       Appendix D: Internationalization. 358

D.1        Multilingual descriptions, names and addresses. 358

D.2        Multiple names in the same language. 359

D.3        Internationalized address format 359

D.4        Language–dependent collation. 361

D.4.1       UDDI JIS X 4061 Japanese Sort Order Qualifier 361

E       Appendix E: Using Identifiers. 363

E.1        Using identifiers. 363

F       Appendix F: Using Categorization. 365

F.1        Using simple categories. 365

F.2        Grouping categories. 367

F.3        Deriving categories. 369

G       Appendix G: Wildcards. 371

G.1       Find using “starts with” searching. 371

G.2       Find using “starts and ends with” searching. 371

G.3       Find using escaped literals. 371

G.4       Find using wildcards with Taxonomies. 372

H       Appendix H: Extensibility. 373

H.1        Using the basic UDDI infrastructure. 373

H.2        Establishing an extension. 373

H.2.1       Extension designer 373

H.2.2       Registries that support the extension. 374

H.3        Programmers API and UDDI Clients. 374

H.3.1       UDDI Clients not prepared to handle the extension. 374

H.3.2       UDDI Clients prepared to handle the extension. 375

H.4        Error Codes. 375

H.5        Digital signatures. 375

H.6        Entity promotion. 375

H.7        Replication. 375

H.8        Example. 375

H.8.1       Description. 376

H.8.2       Data structure (XML schema) 376

H.8.3       tModel of the extension. 376

H.8.4       Additional service end points. 379

H.8.5       Programmers API Description of the extension. 379

H.8.6       Digital signature. 380

H.8.7       Registry operation: replication. 380

H.8.8       Registry operation:  entity promotion. 380

H.8.9       Non-normative example. 381

I        Appendix I: Support For XML Digital Signatures. 383

I.1         Generation of a Signature. 383

I.2         Validation of a Signature. 384

J       Appendix J: UDDI Replication Examples. 385

J.1        Communication Graph. 385

J.2        Replication Configuration Structure Example. 385

J.3        notify_changeRecordsAvailable Example. 387

J.4        get_ChangeRecords Example. 388

J.5        Miscellaneous Replication Example. 389

J.6        Non-normative – Cycle of Cycles Topology. 391

K       Appendix K – Modeling UDDI within UDDI – A Sample. 392

K.1        The Node’s businessEntity. 392

K.1.1       XML Fragment 392

K.1.2       Explanation. 392

K.2        The Policy Service. 392

K.2.1       XML Fragment 393

K.2.2       Explanation. 393

K.3        The Security Service. 396

K.3.1       XML Fragment 396

K.3.2       Explanation. 396

K.4        The Publish Service – Supporting 3 Versions. 397

K.4.1       XML Fragment 397

K.4.2       Explanation. 398

K.5        The Inquiry Service – Supporting 3 Versions. 399

K.5.1       XML Fragment 399

K.5.2       Explanation. 401

L       Appendix L: Glossary of Terms. 402

M       Appendix M: Acknowledgements. 410

N       Appendix N: Notices. 411

 


 

1      Introduction

Web services are meaningful only if potential users may find information sufficient to permit their execution.  The focus of Universal Description Discovery & Integration (UDDI) is the definition of a set of services supporting the description and discovery of (1) businesses, organizations, and other Web services providers, (2) the Web services they make available, and (3) the technical interfaces which may be used to access those services.  Based on a common set of industry standards, including HTTP, XML, XML Schema, and SOAP, UDDI provides an interoperable, foundational infrastructure for a Web services-based software environment for both publicly available services and services only exposed internally within an organization.

1.1 About this specification

This document describes the Web services and behaviors of all instances of a UDDI registry.  Normative material is provided in the numbered chapters of the document and in the XML schemas which accompany this document. Supplementary non-normative commentary, explanations, and guidance may be found in the lettered appendices. In particular, first-time readers of this specification may find Appendix L Glossary of Terms useful.

This specification contains examples of XML data and URIs used in interacting with UDDI. 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.

The primary audiences for this document are:

·         Programmers who want to write software that will directly interact with a UDDI registry.

·         Programmers who want to implement a UDDI node

·         Programmers who want to implement any of the Web services UDDI Nodes invoke

All implementations of the UDDI specification must provide support for the required Web services described here as well as the behaviors defined.

1.2 Language & Terms

RFC 2119: The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they appear in this document, are to be interpreted as described in RFC 2119 found at http://www.faqs.org/rfcs/rfc2119.html.

MANDATORY, RECOMMENDED, and OPTIONAL: Beginning with this third version, the UDDI specification renders explicit which components of the UDDI specification are MANDATORY and MUST be implemented, which are RECOMMENDED and SHOULD be implemented, and which are OPTIONAL and MAY be implemented. It is important to note that OPTIONAL and RECOMMENDED elements of the specification, if they are implemented, MUST be implemented in the manner documented in this specification.

Separation of operational issues: In this third version of the UDDI Specification the trend begun in Version 2 to separate normative behavior from UDDI registry and node policy is completed. For instance, authorization has been called out as a policy decision. A similar separation of normative behavior and registry content has also been carried out. For example, the requirement to support specific category systems has been removed from this version of the specification.

1.3 Diagrams Used in this document

1.3.1 Attributes and elements

UDDI uses the XML Schema Language (See http://www.w3.org/TR/xmlschema-0/, http://www.w3.org/TR/xmlschema-1/ and http://www.w3.org/TR/xmlschema-2/) and its terminology, such as “sequence” and “choice” to formally describe its data structures. The diagrams[1] used in this specification show the structure and cardinality of the elements used in these structures. Attributes are not shown in the diagrams, but explained in the corresponding documentation.

1.3.2 Element structure

1.3.2.1 Sequence

The hexagonal symbol with the horizontal “dotted” line indicates “sequence of.” This diagram says the element registeredInfo consists of elements businessInfos and tModelInfos. All three elements are defined in the namespace whose prefix is “uddi”. Note that although the word “sequence” is used, there is no requirement for a specific order to these elements.

The fact that businessInfos and tModelInfos have a box with a “+” in it at their right-hand end indicates that there is more structure to them than is shown in the diagram.

1.3.2.2 Choice

The switch-like symbol indicates a choice. In this case, a choice between the elements businessKey, fromKey, and toKey.

None of these has more structure than is given in the diagram (there are no boxes with a “+” in them at their right-hand ends). That they are adorned with a small series of horizontal lines in their upper left corners indicates that each is a non-empty element.

1.3.3 Cardinality

1.3.3.1 Optional, one

The dashed line indicates that the element listDescription is optional. The fact that it is not adorned with some other cardinality indicator (see below) says there can be at most one of them.

1.3.3.2 Mandatory, one

There must be exactly one of the element businessKey.

1.3.3.3 Optional, repeating

The element assertionStatusItem is optional and may appear an indeterminate number of times. The number of times it may appear is given by the adornment “0..¥”, a cardinality indicator meaning “zero to infinity”. Other numbers may appear to indicate different cardinalities.

1.3.3.4 Mandatory, repeating

The element addressLine must appear at least once and may appear an indeterminate number of times.

1.4 Related Documents

1.4.1 Translations of the UDDI Specification

Translations of the UDDI Specifications may be produced, by the UDDI specification technical committee of OASIS, or by others. In all instances the English version of the document is the official version; in case of discrepancy the English version shall be the definitive source.

1.4.2 Best Practices and Technical Notes

To provide guidance on the use of UDDI registries, the UDDI specification technical committee of OASIS from time to time publishes “Best Practices” and “Technical Notes”. The contents of these documents are not a part of this specification.  See http://www.oasis-open.org/committees/uddi-spec/doc/bps.htm for further information on Best Practices and http://www.oasis-open.org/committees/uddi-spec/doc/tns.htm for information on Technical Notes.

1.5 Base UDDI Architecture

1.5.1 UDDI Data

This specification presents an information model composed of instances of persistent data structures called entities. Entities are expressed in XML and are persistently stored by UDDI nodes. Each entity has the type of its outer-most XML element. A UDDI information model is composed of instances of the following entity types:

·         businessEntity: Describes a business or other organization that typically provides Web services.

·         businessService: Describes a collection of related Web services offered by an organization described by a businessEntity.

·         bindingTemplate: Describes the technical information necessary to use a particular Web service.

·         tModel: Describes a “technical model” representing a reusable concept, such as a Web service type, a protocol used by Web services, or a category system.

·         publisherAssertion: Describes, in the view of one businessEntity, the relationship that the businessEntity has with another  businessEntity.[2]

·         subscription: Describes a standing request to keep track of changes to the entities described by the subscription.

1.5.2 UDDI Services and API Sets

This specification presents APIs that standardize behavior and communication with and between implementations of UDDI for the purposes of manipulating UDDI data stored within those implementations. The API’s are grouped into the following API sets.

1.5.2.1 Node API Sets

·         UDDI Inquiry

·         UDDI Publication

·         UDDI Security

·         UDDI Custody Transfer

·         UDDI Subscription

·         UDDI Replication

1.5.2.2 Client API Sets

·         UDDI Subscription Listener

·         UDDI Value Set

1.5.3 UDDI Nodes

A set of Web services supporting at least one of the Node API sets is referred to as a UDDI node. A UDDI node has these defining characteristics:

1.       A UDDI node supports interaction with UDDI data through one or more UDDI API sets

2.       A UDDI node is a member of exactly one UDDI registry.

3.       A UDDI node conceptually has access to and manipulates a complete logical copy of the UDDI data managed by the registry of which it is a part. Moreover, it is this data which is manipulated by any query and publish APIs supported by the node. Typically, UDDI replication occurs between UDDI nodes which reside on different systems in order to manifest this logical copy in the node.

The physical realization of a UDDI node is not mandated by this specification.

1.5.4 UDDI Registries

One or more UDDI nodes may be combined to form a UDDI Registry. The nodes in a UDDI registry collectively manage a particular set of UDDI data. This data is distinguished by the visible behavior associated with the entities contained in it.

A UDDI Registry has these defining characteristics.

1.       A registry is comprised of one or more UDDI nodes.

2.       The nodes of a registry collectively manage a well-defined set of UDDI data. Typically, this is supported by the use of UDDI replication between the nodes in the registry which reside on different systems.

3.       A registry MUST make a policy decision for each policy decision point. It MAY choose to delegate policy decisions to nodes. See Chapter 9 Policy for details.

The physical realization of a UDDI Registry is not mandated by this specification.

1.5.5 Affiliations of Registries

The entities businessEntity, businessService, bindingTemplate, tModel form the core data structures of UDDI. Within a registry, each instance of the core data structures is uniquely identified by a UDDI key. By choosing appropriate policies, multiple registries may form a group, known as an “affiliation”, whose purpose is to permit controlled copying of core data structures among them. A UDDI registry affiliation has these defining characteristics.

1.       The registries share a common namespace for entity keys.

2.       The registries have compatible policies for assigning keys to entities.

3.       The policies of the registries permit publishers to assign keys

1.5.6 Person, Publisher and Owner

When publishing information in a UDDI registry the information becomes part of the published content of the registry. During publication of an item of UDDI information, a relationship is established between the publisher, the item published and the node at which the publish operation takes place. The glossary contains definitions of the terms person, publisher and owner.

This specification defines a relationship between these three terms and leaves the binding of these abstract relationships to be determined by the policies of the registry and its nodes at implementation. It is important to review Chapter 9 on policy to understand how different implementations can define different policies but remain consistent with the UDDI specification.

1.5.7 Transfer of ownership

As the owner of datum, a person can initiate the transfer of ownership of the datum to another publisher within the registry. Section 5.4 Custody and Ownership Transfer API describes the transfer of ownership within UDDI.

1.5.8 Data Custody

Generally speaking, data is replicated between nodes of a UDDI registry using a replication protocol. Registries that choose to use the replication protocol defined in Section 7.4 Replication API Set MUST enforce the following data custody policy. (Registries which choose otherwise incur no such requirement.)

Each node has custody of a portion of the aggregate data managed by the registry of which it is a part. Each datum is by definition in the custody of exactly one such node. A datum in this context can be a businessEntity, a businessService, a bindingTemplate, a tModel, or a publisherAssertion. Changes to a datum in the registry MUST originate at the node which is the custodian of the datum. The registry defines the policy for data custody and, if allowed, the custodian node for a given datum can be changed; such custody transfer processes are discussed in Section 5.4 Custody and Ownership Transfer API.

1.6 Representing Information within UDDI

For Web services to be meaningful there is a need to provide information about them beyond the technical specifications of the service itself.  Central to UDDI’s purpose is the representation of data and metadata about Web services.  A UDDI registry, either for use in the public domain or behind the firewall, offers a standard mechanism to classify, catalog and manage Web services, so that they can be discovered and consumed.  Whether for the purpose of electronic  commerce or alternate purposes, businesses and providers can use UDDI to represent information about Web services in a standard way such that queries can then be issued to a UDDI Registry – at design-time or run-time – that address the following scenarios:

·         Find Web services implementations that are based on a common abstract interface definition.

·         Find Web services providers that are classified according to a known classification scheme or identifier system.

·         Determine the security and transport protocols supported by a given Web service.

·         Issue a search for services based on a general keyword.

·         Cache the technical information about a Web service and then update that information at run-time.

These scenarios and many more are enabled by the combination of the UDDI information model and the UDDI API set.  Because the information model is extremely normalized, it can accommodate many different types of models, scenarios and technologies.  The specification has been written to be flexible so that it can absorb a diverse set of services and not be tied to any one particular technology. While a UDDI Node exposes its information as an XML Web service, it does not restrict the technologies of the services about which it stores information or the ways in which that information is decorated with metadata. 

1.6.1 Representing Businesses and Providers with “businessEntity”

One top-level data structure within UDDI is the businessEntity structure, used to represent businesses and providers within UDDI.  It contains descriptive information about the business or provider and about the services it offers.  This would include information such as names and descriptions in multiple languages, contact information and classification information.  Service descriptions and technical information are expressed within a businessEntity by contained businessService and bindingTemplate structures. 

While the name of XML entity itself has the word business embedded in it, the structure can be used to model more than simply a “business” in its common usage.  As the top-level entity, businessEntity can be used to model any “parent” service provider, such as a department, an application or even a server.  Depending on the context of the data in the entire registry, the appropriate modeling decisions to represent different service providers can vary.

1.6.2 Representing Services with “businessService”

Each businessService structure represents a logical grouping of Web services.  At the service level, there is still no technical information provided about those services; rather, this structure allows the ability to assemble a set of services under a common rubric.  Each businessService is the logical child of a single businessEntity.   Each businessService contains descriptive information – again, names, descriptions and classification information -- outlining the purpose of the individual Web services found within it.  For example, a businessService structure could contain a set of Purchase Order Web services (submission, confirmation and notification) that are provided by a business.

Similar to the businessEntity structure, the term business is embedded within the name businessService.  However, a suite of services need not be tied to a business per se, but can rather be associated with a provider of services, given a modeling scenario that is not based on a business use case.

1.6.3 Representing Web services with “bindingTemplate”

Each bindingTemplate structure represents an individual Web service. In contrast with the businessService and businessEntity structures, which are oriented toward auxiliary information about providers and services, a bindingTemplate provides the technical information needed by applications to bind and interact with the Web service being described.  It must contain either the access point for a given service or an indirection mechanism that will lead one to the access point.  

Each binding Template is the child of a single businessService.  The containing parents, a bindingTemplate can be decorated with metadata that enable the discovery of that bindingTemplate, given a set of parameters and criteria. 

1.6.4 Technical Models (tModels)

Technical Models, or tModels for short, are used in UDDI to represent unique concepts or constructs.  They provide a structure that allows re-use and, thus, standardization within a software framework. The UDDI information model is based on this notion of shared specifications and uses tModels to engender this behavior.  For this reason, tModels exist outside the parent-child containment relationships between the businessEntity, businessService and bindingTemplate structures.  

Each distinct specification, transport, protocol or namespace is represented by a tModel.  Examples of tModels that enable the interoperability of Web services include those based on Web Service Description Language (WSDL), XML Schema Definition (XSD), and other documents that outline and specify the contract and behavior – i.e., the interface – that a Web Service may choose to comply with.  To describe a Web service that conforms to a particular set of specifications, transports, and protocols, references to the tModels that represent these concepts are placed in the bindingTemplate.  In such a way, tModels can be re-used by multiple bindingTemplates.  The bindingTemplates that refer to precisely the same set of tModels are said to have the same “technical fingerprint” and are of the same type.  In this way, tModels can be used to promote the interoperability between software systems.

It is important to note that such technical documents and the supporting documentation necessary to a developer using Web services are not stored within the UDDI registry itself. A UDDI tModel simply contains the addresses where those documents can be found.  A tModel, however, contains more than just URLs; it also stores metadata about the technical documents and an entity key that identifies that tModel.

Because tModels can represent any unique concept or construct, they have usage beyond the software interoperability scenario described above.  They can also be used to represent other concepts within the UDDI information model, such that metadata concepts are reused throughout the model.  For example, tModels are used for the following other purposes within UDDI:

·         Transport and protocol definitions such as HTTP and SMTP. (See below and also Section 11.1.1 uddi-org:types for a description.)

·         Value sets including identifier systems, categorization systems and namespaces. (See Section 3.3 businessEntity Structure  and Appendix F Using Categorization for a description of how value sets are used in UDDI.)

·         Structured categorizations using multiple value sets called “categorization groups.”

·         Postal address formats. (See Section 3.3.2.7 address  and Appendix B Internationalization for a description.)

·         Find qualifiers used to modify the behavior of the UDDI find_xx APIs. (See Section 5.1.4 findQualifiers for a description.)

·         Use type attributes that specify the kind of resource being referred to by a URI reference. (See, for example, Section 3.5.2.1 accessPoint.)

The use of tModels is essential to how UDDI represents data and metadata.  The UDDI specification defines a set of common tModels that can be used canonically to model information within UDDI.  If a concept that is required to model a particular scenario does not exist in a registry, a user should introduce that concept by saving a tModel containing the URL of the relevant overview documents.

1.6.5 Taxonomic Classification of the UDDI entities

Data is worthless if it is lost within a mass of other data and cannot be distinguished or discovered.  If a client of UDDI cannot effectively find information within a registry, the purpose of UDDI is considerably compromised.  Providing the structure and modeling tools to address this problem is at the heart of UDDI’s design.  The reification of data within UDDI is core to its mission of description, discovery and integration.  It achieves this by several means. 

First, it allows users to define multiple taxonomies that can be used in UDDI.  In such a way, multiple classification schemes can be overlaid on a single UDDI entity.  This capability allows organizations to extend the set of such systems UDDI registries support. One is not tied to a single system, but can rather employ several different classification systems simultaneously.

Second, UDDI allows such classification systems to be used on every entity within the information model.  It defines a consistent way for a publisher to add any number of classifications to their registrations.  It is important that taxonomies are used when publishing data into a UDDI registry.  Whether standard codes are used (such as the United Nations Standard Products and Services Code System (UNSPSC)) or a new taxonomy is created and distributed, it is imperative that UDDI data -- businessEntity, businessService, bindingTemplate and tModel elements alike – are attributed with metadata. 

Third, the UDDI Inquiry API set provides the ability to issue precise searches based on the different classification schemes.  A range of queries that perform different joins across the UDDI entities can be generated, such that data can be discovered and accessed.  Also, registering information such as industry codes, product codes, geography codes and business identification codes allows other search services to use this classification information as a starting point to provide added-value indexing and classification.

Classification and identification systems, taken together, are called “value sets” in UDDI. Value sets may be “checked” or “unchecked”. Both checked and unchecked value sets are used for categorization and identification. The difference between them is that whenever a checked value set is used, the use is inspected to see that it conforms to the requirements of the value set. Unchecked value sets do not have their uses checked.

1.7 Introduction to Security

The security model for a UDDI registry can be characterized by the collection of registry and node policies and the implementation of these policies by a UDDI node. This specification details a list of policies that MUST be defined by registries and nodes in Chapter 9 Policy. This specification also describes how policies SHOULD be modeled. 

Several optional and extensible mechanisms for implementing nodes, registries and clients with a particular security model are described in this specification. The principal areas of security policies and mechanisms in the UDDI specification are related to data management, user identification, user authentication, user authorization, confidentiality of messages and integrity of data.

In order to authorize or restrict access to data in a UDDI registry, an implementation of a UDDI node MAY be integrated with one or more identification systems. An implementation specific policy MUST identify the identification system(s) used.  Integration of UDDI APIs and data with an identification system MAY be implemented through the authentication and authorization APIs to provide access control as described in Section 5.3 Security Policy API Set.  Other authentication and authorization mechanisms and policies are represented in UDDI through use of tModels to describe the Web services of a UDDI node.

UDDI also supports XML Digital Signatures on UDDI data to enable inquirers to verify the integrity of the data with respect to the publisher.

The security model for a registry and node can be extended beyond the mechanisms described in this specification and represented by modeling the UDDI Web services and through node and registry policy documentation.

1.8 Introduction to Internationalization

As part of its aim of providing a registry for universal description, discovery and integration, the UDDI specification includes support for internationalization features.  These features fall into two broad groups:

·         Support for multi-regional businesses, organization, and other Web service providers to:

o        Describe their operations across international or inter-region units

o        Specify the timezone of each operation’s contacts

·         Support for internationalization of UDDI data and services such as:

o        XML and the Unicode Character Set

o        Postal address

o        Use of multiple languages or multiple scripts of the same language

o        Mechanisms to specify additional language-specific sorting order

o        Consistent search results independent of language of information being searched

1.8.1 Multi-regional businesses

The UDDI specification provides features that enable Web service providers to describe the location of different aspects of the business, e.g. where it offers its products and services, where it is located, or even where it has stores, warehouses, or other branches. 

1.8.2 XML and Unicode Character Set

The UDDI specification uses XML and the Unicode Character Set (up to and including version 3.0 of the Unicode Standard).  By basing the programming interface on XML, multilingual handling capability is automatically achieved as XML uses the Universal Character Set (UCS) defined by both the Unicode Consortium and ISO 10646.  The UCS is a character set that encompasses most of the language scripts used in computing.

1.8.3 Standardized Postal Address

In UDDI, an <address> element consists of a list of <addressLine> elements. While this is useful for publishing addresses in a UDDI registry or simply printing them on paper, the address’ logical structure and meaning is not explicit.

Moreover, different geographical regions specify their postal addresses differently

·         By having different subelements (e.g. subdivisions, suburbs, lots, building identifications, floor numbers)

·         By grouping/sequencing the subelements.

To overcome the first concern, the UDDI specification exposes an address’ structure and meaning by the use of attributes within each <addressLine> element to specify that line’s structure and meaning.

To overcome the second concern, the UDDI Business Registry has specified a canonical postal address structure with common address subelements (e.g. states, cities).  This canonical address structure describes address data via name/code pairs, enabling each common address subelement to be identified by name or code[3].

1.8.4 Use of Multi-languages and Multi-scripts

Multinational businesses or businesses involved in international trading at times require the use of possibly several languages or multiple scripts of the same language for describing their business. The UDDI specification supports this requirement through two means, first by specifying the use of XML with its underlying Unicode representation, and second by permitting the use of the xml:lang attribute for various items such as names, addresses, and document descriptions to designate the language in which they are expressed. Further information on this may be found in Section 3.3.2.3 name.

1.8.5 Adding Language-specific Sort Orders

The Universal Character Set supported through XML consists of characters of most of the language scripts of the world.  Each character has a distinct collation weight within the language for use in the collation sequencing process.  Handling the sort orders of different language scripts, i.e. the assignment of collation weight values, can be very different, with the complexity of handling dependent on whether the script is alphabetic, syllabic, or ideographic.  Some examples of sort order handling issues are:

·         Where multiple languages share the same alphabetic script, it is possible for a common character to have different collation weights when used in the different languages.

·         Ideographic languages have large character repertoires with multiple collation sequencing possibilities depending on whether phonetic or stroke-order sequencing is chosen.

·         Where languages are bicameral (having upper and lower cases), collation sequencing could depend on whether case-sensitive or insensitive sorting is required.  Conversely, specifying case-sensitive sort for non-bicameral languages is meaningless.

·         Where the language inherently has an obvious collation sequence, fastest sorting is achieved by using binary sort.

The UDDI specification allows the collation sequence of results returned by the APIs to be specified via qualifiers.  The specification also supports a mechanism to specify additional language-specific collation sequences for collating returned results.

1.8.6 Consistent Internationalized Search

The existence within the Universal Character Set of combining characters and of multiple representations for what users perceive as the same character results in different (by content and sometimes by length as well) XML strings that are the same when rendered visually.  These different XML strings, though different in their encoded binary form, should produce positive match results during any search operation.  This requirement makes it necessary to define a canonical XML string representation.  The canonical representation chosen is that of the Unicode Normalization Form C[4].  For further details, see Section 4.6.1.1 Normalization and Canonicalization.

 

 


 

2      UDDI Schemas

UDDI uses the XML Schema Language (See http://www.w3.org/TR/xmlschema-0/, http://www.w3.org/TR/xmlschema-1/ and http://www.w3.org/TR/xmlschema-2/) to formally describe its data structures. A UDDI node MUST use an XML processor that meets the definition of a minimally conforming schema aware processor as defined in XML Schema Part 1: Structures. The XML processor must further understand the references to schema components (see Section 4.2.3 of XML Schema Part 1: Structures) across namespaces which result from the import statements in the UDDI schemas. The complete definition comprises 9 schema files, as described below.

 

UDDI API Schema

Schema file

http://uddi.org/schema/uddi_v3.xsd

Target namespace

urn:uddi-org:api_v3

Referenced/imported namespaces

http://www.w3.org/2001/XMLSchema
http://www.w3.org/2000/09/xmldsig#
http://www.w3.org/XML/1998/namespace

Description

This is the main UDDI Schema file. It defines all of the common UDDI data types and elements as well as those used in the Inquiry, Publishing, and Security API sets.

 

UDDI Custody Schema

Schema file

http://uddi.org/schema/uddi_v3custody.xsd

Target namespace

urn:uddi-org:custody_v3

Referenced/imported namespaces

urn:uddi-org:api_v3
urn:uddi-org:repl_v3
http://www.w3.org/2001/XMLSchema

Description

This is the schema for the UDDI Custody and Ownership Transfer API set.

 

UDDI Subscription Schema

Schema file

http://uddi.org/schema/uddi_v3subscription.xsd

Target namespace

urn:uddi-org:sub_v3

Referenced/imported namespaces

urn:uddi-org:api_v3
http://www.w3.org/2001/XMLSchema

Description

This is the schema for the UDDI Subscription API set.

 


 

UDDI Subscription Listener Schema

Schema file

http://uddi.org/schema/uddi_v3subscriptionListener.xsd

Target namespace

urn:uddi-org:subr_v3

Referenced/imported namespaces

urn:uddi-org:api_v3
urn:uddi-org:sub_v3
http://www.w3.org/2001/XMLSchema

Description

This is the schema for the UDDI Subscription Listener API set.

 

UDDI Replication Schema

Schema file

http://uddi.org/schema/uddi_v3replication.xsd

Target namespace

urn:uddi-org:repl_v3

Referenced/imported namespaces

urn:uddi-org:api_v3
http://www.w3.org/2000/09/xmldsig# http://www.w3.org/2001/XMLSchema

Description

This is the schema for the UDDI Replication API set.

 

UDDI Value Set Validation Schema

Schema file

http://uddi.org/schema/uddi_v3valueset.xsd

Target namespace

urn:uddi-org:vs_v3

Referenced/imported namespaces

urn:uddi-org:api_v3
http://www.w3.org/2001/XMLSchema

Description

This is the schema for the UDDI Value Set Validation API set.

 

UDDI Value Set Caching

Schema file

http://uddi.org/schema/uddi_v3valuesetcaching.xsd

Target namespace

urn:uddi-org:vscache_v3

Referenced/imported namespaces

urn:uddi-org:api_v3
http://www.w3.org/2001/XMLSchema

Description

This is the schema for the UDDI Value Set Data API set.


 

UDDI Policy

Schema file

http://uddi.org/schema/uddi_v3policy.xsd

Target namespace

urn:uddi-org:policy_v3

Referenced/imported namespaces

http://www.w3.org/2001/XMLSchema
http://www.w3.org/2000/09/xmldsig#
http://www.w3.org/XML/1998/namespace

Description

This is the schema for the UDDI Policy Document for the Policy Service.

 

UDDI Policy Instance Parameters

Schema file

http://uddi.org/schema/uddi_v3policy_instanceParms.xsd

Target namespace

urn:uddi-org:policy_instanceParms_v3

Referenced/imported namespaces

http://www.w3.org/2001/XMLSchema

Description

This is the schema for the instance parameters that are used in modeling UDDI policies.

 

2.1 Schema versioning

UDDI follows the commonly encountered convention of changing the target namespace whenever a specification revision changes the schema in a way that changes the set of documents that is valid under the schema. In addition, UDDI changes the target namespace whenever a specification revision changes in a way that changes the behavior a compliant registry is permitted to display with respect to the schema, even if the set of documents that are valid under the schema remains unchanged. UDDI does not change the target namespace for other kinds of changes. For example, the target namespace is not changed for purely editorial or formatting errata, either to the Specification or to a schema.

The form of the target namespace is (using ABNF notation):

namespace = "urn:uddi-org:" schemaName  "_v" versionNumber [":" revisionNumber]
versionNumber = decimalInteger
revisionNumber = decimalInteger
schemaName = "api" / "custody" / "sub" / “subr” / "repl" / "vs" / “vscache” / “policy” / “policy_instanceParms”
decimalInteger = Unsigned integer with no leading zeroes.

Where versionNumber is the same as the version number of UDDI of which the schema is a part. E.g., for UDDI v3, versionNumber is 3. The value of revisionsNumber is the number of the revision to the specification in which the schema is used.

When the specification is first released revisionsNumber is 0. It is incremented by 1 with each released revision.

So, for example, namespace for the UDDI API Schema corresponding to UDDI v3 in its first release is "urn:uddi-org:api_v3:0".

In addition, the UDDI schemas use the version attribute of the schema element to mark changes to the text of the schema in the following manner. The value of the version attribute is an unsigned decimal integer. When a schema is first created for a given version of UDDI its version is 0. The value of version is incremented by at least 1 each time the schema is made publicly available.

2.2 Schema Extensibility

As defined in the UDDI schemas, all UDDI data structures are designed to permit UDDI node implementers to extend them using the XML Schema derivation-by-extension feature. While extending the UDDI schemas in this way can be a relatively straightforward process, designing an extension that includes behavioral modification is likely to be a complex undertaking that should be done with considerable care. See Appendix H Extensibility for more information on extending UDDI.

2.3 Element and attribute types and lengths

To ease the replication of data between nodes of a registry and to facilitate sharing data among the registries of an affiliation, UDDI imposes length restrictions on the types in its information model. The following tables summarize all the stored elements and attributes in the UDDI schemas that correspond to XML schema simpleTypes. They provide data types and, for those whose length is not specified by XML, their allowed lengths. The lengths are the storage length limits for information that is saved in a UDDI registry, given in Unicode characters. Since these limits are imposed in the schemas, structures containing data that exceeds the constraints depicted below are not valid.  The lengths specified in the UDDI schemas are the definitive source for type and length information.

2.3.1 Data structure, publication API, inquiry API and security API

Element/attribute Name

Data Type

Length

accessPoint

string

4096

addressLine

string

80

authInfo

string

4096

bindingKey

anyURI

255

businessKey

anyURI

255

deleted

boolean

 

description

string

255

discoveryURL

anyURI

4096

email

string

255

fromKey

anyURI

255

instanceParms

string

8192

keyName

string

255

keyValue

string

255

name

string

255

operator

string

255

overviewURL

anyURI

4096

personName

string

255

phone

string

50

serviceKey

anyURI

255

sortCode

string

10

tModelKey

anyURI

255

toKey

anyURI

255

useType

string

255

completionStatus

NMTOKEN

32

xml:lang

string

26

 

2.3.2 Subscription API

Element/attribute Name

Data Type

Length

brief

boolean

 

endPoint

dateTime

 

notificationInterval

duration

 

iexipresAfter

dateTime

 

startPoint

dateTime

 

maxEntities

integer

 

subscriptionKey

anyURI

255

 

2.3.3 Replication API

Element/attribute Name

Data Type

Length

acknowledgementRequested

boolean

 

nodeId

anyURI

255

notifyingNode

anyURI

255

originatingUSN

integer

 

operatorNodeID

anyURI

255

requestingNode

anyURI

255

responseLimitCount

integer

 

 

 


 

 

3      UDDI Registry Data Structures

3.1 Data structure overview

This chapter describes the semantics of the data structures that are specified by the UDDI API Schema. Refinements that are specific to individual APIs are described in Chapter 5 UDDI Programmers API’s.

As described in Section 1.6 Representing Information within UDDI, the information that makes up a UDDI registry consists of instances of four core data structure types, the businessEntity, the businessService, the bindingTemplate and the tModel, together with instances of additional data structure types defined in the UDDI API Schema.

The four core types and their relationships are shown in a simplified diagram in Figure 1 and are explained in detail in this chapter.

 

 

Figure 1 - UDDI core data structures

The schema also defines a number of request and response structures, each of which contain the core structures, references to the core structures, or summary versions of them; see Chapter 5 UDDI Programmers API’s for details.

3.2 Design Principles

Each of the core data structure types is used to express specific types of data, arranged in the relationship shown in Figure 1. A particular instance of an individual fact or set of related facts is expressed using XML according to the definition of these core types. For instance, two separate businesses may publish information in a UDDI registry about Web services they offer. Information describing each business and its Web services all exists as separate instances of the core data structures stored within the UDDI registry.

3.2.1 Keys as unique identifiers

Instances of many data structures in UDDI, including all of the core data structures are kept separately, and are accessed individually by way of unique identifiers called keys. An instance in the registry gets its keys at the time it is first published. Publishers may assign keys; if they don’t, the UDDI node MUST assign them. See Section 4.4 About uddiKeys.

3.2.2 Containment and references

The core data structures are sensitive to the containment relationships found in the UDDI API schema and shown in Figure 1. The businessEntity structure contains one or more distinct businessService structures. Similarly, individual businessService structures contain specific instances of bindingTemplate structures.

It is important to note that no single instance of an entity is ever “contained” by more than one containing entity. This means, for example, that only one specific businessEntity structure (identified by its unique key value) will ever contain a specific instance of a businessService structure (also identified by its own unique key).

References, on the other hand, operate differently. We can see an example of this in Figure 1 where the bindingTemplate entities refer to instances of tModel entities. References to a given entity can occur multiple times, as needed.

Determining what is a reference and what is the key for a specific entity is straightforward. Each kind of keyed entity has an attribute whose type is a corresponding type of key. For example, businessEntity has a businessKey attribute and a businessService has a serviceKey attribute. The value of this attribute is the entity’s key. All other keys are references or containment relationships. Taking the bindingTemplate as an example, the tModelKey that occurs in its inner structure is a reference and the serviceKey that occurs in the bindingTemplate is a containment relationship.

3.2.3 Collections

Many elements in the UDDI API Schema may occur multiple times. Those elements that do not have a complex inner structure, for example, name and description, are provided in a list. Elements that do have a more complex inner structure are usually grouped in their own container element. For example, the contacts structure is a container where one or more contact structures reside.

3.2.4 Optional attributes

In the data structure elements of the UDDI API Schema, there are many optional attributes, for example, keyName and useType. Most optional attributes have defaults of empty string (“”). During schema assessment, this produces a single representation for an omitted or empty string in an optional attribute. Consider the following two keyedReferences:

<keyedReference
    tModelKey=”uddi:uddi.org:ubr:categorization:iso3166”
    keyName=””

    keyValue=”US-CA” />

<keyedReference
    tModelKey=”uddi:uddi.org:ubr:categorization:iso3166”

    keyValue=”US-CA” />

 

Semantically speaking from the perspective of UDDI, omitted attributes are identical to empty attributes. However, with respect to signing, specifically, canonicalization, omitted attributes are different from empty attributes. Therefore, the digital signatures of the above two keyedReferences are different, even though clients would consider the two keyedReferences be identical.

The difference, from a perspective of canonicalization, puts additional burden on clients in publishing entities. As a result, when applicable, the data structure elements of UDDI API Schema define default values for optional attributes, so that omitted attributes are treated as attributes with default value with respect to signing.

The exceptions are xml:lang and keyValue in addressLine. Both prohibit empty string. Hence, the ambiguity discussed above is not applicable. In the case of xml:lang, empty string is not a valid language code. In the case of keyValue in addressLine, the definition of keyValue requires the string to have a minimal length of one.

3.3 businessEntity Structure

Each businessEntity entity contains descriptive information about a business or organization and, through its contained businessService entities, information about the services that it offers. From an XML standpoint, the businessEntity is the top-level data structure that holds descriptive information about the business or organization it describes. Each contained businessService describes a logical service offered by the business or organization. Similarly, each bindingTemplate contained within a given businessService provides the technical description of a Web service that belongs to the logical service that is described by the businessService.

3.3.1 Structure diagram

Attributes

Name 

Use 

businessKey 

optional 

 

3.3.2 Documentation

A given instance of the businessEntity structure is uniquely identified by its businessKey. When a businessEntity is published within a UDDI registry, the businessKey MUST be omitted if the publisher wants the registry to generate a key. When a businessEntity is retrieved from a UDDI registry, the businessKey MUST be present.

discoveryURLs is a list of Uniform Resource Locators (URL) that point to alternate, file based service discovery mechanisms.

Simple textual information about the businessEntity, potentially in multiple languages, is given by its name, short business description and contacts. The required, non-empty name and the optional description can occur multiple times. contacts is a simple list of single contact information.

businessServices is a list of business services provided by the businessEntity.

In addition to the businessKey, that uniquely identifies the businessEntity within the registry, the identifierBag contains a list of other identifiers, each valid in its own identifier system. Examples of identifiers are a tax identifier or D-U-N-S® number.

The categoryBag contains a list of business categories that each describes a specific business aspect of the businessEntity. Examples of categories are industry, product category or geographic region.

A businessEntity entity MAY be digitally signed using XML digital signatures. When a businessEntity is signed, each digital signature MUST be provided by its own dsig:Signature element. Appendix I Support for XML Digital Signatures covers the use of this element in accordance with the XML-Signature specification.

3.3.2.1 discoveryURLs

The discoveryURLs structure is a simple container of one or more discoveryURL elements.

3.3.2.2 discoveryURL

A discoveryURL is a URL that points to Web addressable (via HTTP GET) discovery documents. The expected return document is not defined. Rather, a framework for establishing conventions is provided, and a particular convention is defined within this specification.

Attributes

Name 

Use 

useType 

optional 

 

Each individual discoveryURL MAY be adorned with a useType attribute that designates the name of the convention that the referenced document follows. A reserved convention value is “businessEntity”. It is RECOMMENDED that discoveryURLs qualified with this value point to XML documents of the type businessEntity, as defined in the UDDI API Schema.

An example of a discoveryURL, generated by a UDDI node that is accessible at www.example.com and rendered by the publisher of the businessEntity that is identified by the businessKey “uddi:example.com:registry:sales:53”, is:

<discoveryURL useType=”businessEntity”>
    http://www.example.com?businessKey=uddi:example.com:registry:sales:53
</discoveryURL>

 

Another reserved value for discoveryURL is “homepage”.  Adorning a discoveryURL with this value signifies that a business’s homepage can be discovered at that URL.

 

3.3.2.3 name

A businessEntity MAY contain more than one name. Multiple names are useful, for example, in order to specify both the legal name and a known abbreviation of a businessEntity, or in order to support romanization (see Appendix D Internationalization).

Attributes

Name 

Use 

xml:lang 

optional 

 

When a name is expressed in a specific language (such as the language into which a name has been romanized), it SHOULD carry the xml:lang attribute to signify this. When a name does not have an associated language (such as a neologism not associated with a particular language), the xml:lang attribute SHOULD be omitted.

As is defined in the XML specification, an occurrence of the xml:lang attribute indicates that the content to which it applies (namely the element on which it is found and to all its children, unless subsequently overridden) is to be interpreted as being in a certain natural language. Legal values for such attributes conform to RFC 3066[5] with one exception: UDDI imposes a maximum length of 26 characters. 

As is the case for RFC 3066, all tags are to be treated as case insensitive; there exist conventions for capitalization of some of them, but these should not be taken to carry meaning.  For instance, [ISO 3166] recommends that country codes are capitalized (MN Mongolia), while [ISO 639] recommends that language codes are written in lower case (mn Mongolian).

Examples include: "EN-us", "FR-ca".

3.3.2.4 description

A businessEntity can contain several descriptions, for example, in different languages.

Attributes

Name 

Use 

xml:lang 

optional 

 

In order to signify the language in which the descriptions are expressed, they MAY carry xml:lang values. There is no restriction on the number of descriptions or on what xml:lang value that they may have.

3.3.2.5 contacts

The contacts structure itself is a simple collection of one or more contact structures.

3.3.2.6 contact

The contact structure records contact information for a person or a job role within the businessEntity so that someone who finds the information can make human contact for any purpose. This information consists of one or more optional elements, along with a person’s name. Contact information exists by containment relationship alone; the contact structure does not provide keys for tracking individual contact instances.

Attributes

Name 

Use 

useType 

optional 

 

The useType attribute is used to describe the type of contact in unstructured text. Suggested examples include “technical questions”, “technical contact”, “establish account”, “sales contact”, etc.

description is used to describe how the contact information should be used. Publishing several descriptions, e.g. in different languages, is supported. To signify the language in which the descriptions are expressed, they MAY carry xml:lang values.

personName is the name of the person or name of the job role supporting the contact. Publishing several names, e.g. for romanization purposes, is supported.

 

 

Attributes

Name 

Use 

xml:lang 

optional 

 

In order to signify the contextual language (if any) in which a given name is expressed in (such as the language into which a name has been romanized), it SHOULD carry the xml:lang attribute See Section 3.3.2.3 name for details on using xml:lang values in name elements. There is no restriction on the number of personNames or what xml:lang value each may have. An example for a role might be:

<contact useType=”Technical support”>

    <personName>Administrator</personName>

    …

</contact>

 

phone is used to hold telephone numbers for the contact. This element MAY be adorned with an optional useType attribute for descriptive purposes.

email is the email address for the contact. This element MAY be adorned with an optional useType attribute for descriptive purposes.

address is the postal address for the contact.

3.3.2.7 address

address represents the contact’s postal address, in a form suitable for addressing an envelope. The address structure is a simple list of address lines.

Attributes

Name 

Use 

xml:lang 

optional 

useType

optional

sortCode

optional

tModelKey

optional

 

Address structures have four optional attributes.

The xml:lang value describes the language the address is expressed in. There is no restriction on the number of addresses or what xml:lang value they may have. Publication of addresses in several languages, e.g. for use in multilingual countries, is supported. See Appendix D Internationalization for an example.

The useType describes the address’ type in unstructured text. Suggested examples include “headquarters”, “sales office”, “billing department”, etc.

The sortCode attribute is deprecated because of the guarantee of preserving the document order (see Section 4.5.3 Preservation of Document Order). In order to achieve this behavior, the data has just to be published in the desired order.

The tModelKey is a tModel reference that specifies that keyName keyValue pairs given by subsequent addressLine elements, if addressLine elements are present at all, are to be interpreted by the address structure associated with the tModel that is referenced. For a description of how to use tModels in order to give the addressLine list structure and meaning, see Appendix D Internationalization.

3.3.2.8 addressLine

addressLine contains a part of the actual address in text form.

Attributes

Name 

Use 

keyName 

optional 

keyValue

optional

 

Each addressLine element MAY be adorned with two optional descriptive attributes, keyName and keyValue. Both attributes MUST be present in each address line if a tModelKey is specified in the address structure. When no tModelKey is provided for the address structure, the keyName and keyValue attributes have no defined meaning.

3.3.2.9 businessServices

The businessServices structure is used to describe families of Web services. This simple container holds one or more businessService entities (see Section 3.4 businessService structure).

3.3.2.10 identifierBag

The optional identifierBag element allows businessEntity structures to be identified according to published identifier systems, for example, Dun & Bradstreet D-U-N-Sâ numbers or tax identifiers.

An identifierBag is a list of one or more keyedReference structures, each representing a single identification.

For a full description on how to establish an identity, see Appendix E Using Identifiers.

3.3.2.11 keyedReference (in identifierBags)

A keyedReference, when included in an identifierBag, represents an identifier of a specific identifier system.

 

 

 

Attributes

Name 

Use 

tModelKey 

required

keyName

optional

keyValue

required

 

The keyedReference consists of the three attributes tModelKey, keyName and keyValue. The required tModelKey refers to the tModel that represents the identifier system, and the required keyValue contains the actual identifier within this system. The optional keyName MAY be used to provide a descriptive name for the identifier. Omitted keyNames are treated as empty keyNames.

For example, identifying SAP AG by its Dun & Bradstreet D-U-N-S® Number, using the corresponding tModelKey within the UDDI Business Registry, is done as follows:

<identifierBag>
    <keyedReference
        tModelKey=”uddi:uddi.org:ubr:identifier:dnb.com:d-u-n-s”
        keyName=”SAP AG”

        keyValue=”31-626-8655” />

</identifierBag>

 

3.3.2.12 categoryBag

The optional categoryBag element allows businessEntity structures to be categorized according to published categorization systems. For example, a businessEntity might contain UNSPSC product and service categorizations that describe its product and service offering and ISO 3166 geographical regions that describe the geographical area where these products and services are offered.

Similar to the identifierBag, a categoryBag contains a simple list of keyedReference structures, each containing a single categorization. The categoryBag MAY also contain a simple list of keyedReferenceGroup structures. At least one keyedReference or one keyedReferenceGroup MUST be provided within the categoryBag.

For a full description of how to establish a categorization, see Appendix F Using Categorization.

3.3.2.13 keyedReference (in categoryBags)

As within an identifierBag (see Section 3.3.2.13 keyedReference (in identifierBags)), a keyedReference contains the three attributes tModelKey, keyName and keyValue. The required tModelKey refers to the tModel that represents the categorization system, and the required keyValue contains the actual categorization within this system. The optional keyName can be used to provide a descriptive name of the categorization. Omitted keyNames are treated as empty keyNames. A keyName MUST be provided in a keyedReference if its tModelKey refers to the general_keywords category system (see also Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups).

For example, in order to categorize a businessEntity as offering goods and services in California, USA, using the corresponding ISO 3166 tModelKey within the UDDI Business Registry, one would add the following keyedReference to the businessEntity’s categoryBag:

<keyedReference
    tModelKey=”uddi:uddi.org:ubr:categorization:iso3166”
    keyName=”California, USA”

    keyValue=”US-CA” />

 

3.3.2.14 keyedReferenceGroup

A keyedReferenceGroup, by itself, is a simple list of keyedReference structures that logically belong together.

Attributes

Name 

Use 

tModelKey 

required

 

The keyedReferenceGroup MUST contain a tModelKey attribute that specifies the structure and meaning of the keyedReferences contained in the keyedReferenceGroup.  A keyedReferenceGroup MUST also contain at least one keyedReference when published.

For example, to categorize a businessEntity as being located at the geodetic point that is specified by the latitude/longitude pair 49.6827/8.2952 using the corresponding World Geodetic System 1984 (WGS 84) tModelKey within the UDDI Business Registry, one would add the following keyedReferenceGroup to the businessEntity’s categoryBag:

<keyedReferenceGroup tModelKey=”uddi:uddi.org:ubr:categorizationGroup:wgs84” >
    <keyedReference
        tModelKey=”uddi:uddi.org:ubr:categorization:wgs84:latitude”
        keyName=”WGS 84 Latitude”

        keyValue=”+49.682700” />

     <keyedReference
         tModelKey=”uddi:uddi.org:ubr:categorization:wgs84:longitude”
         keyName=”WGS 84 Longitude”

         keyValue=”+008.295200” />

</keyedReferenceGroup>

3.4 businessService Structure

The businessService structure represents a logical service and contains descriptive information in business terms. A businessService is the logical child of a single businessEntity, the provider of this businessService. Technical information about the businessService is found in the contained bindingTemplate entities.

In some cases, businesses would like to share or reuse services, e.g. when a large enterprise publishes separate businessEntity structures. This can be done by using the businessService structure as a projection to a published businessService, as explained below.

3.4.1 Structure Diagram

Attributes

Name 

Use 

serviceKey 

optional 

businessKey 

optional 

 

3.4.2 Documentation

A given businessService entity is uniquely identified by its serviceKey. When a businessService is published within a UDDI registry, the serviceKey MUST be omitted if the publisher wants the registry to generate a key. When a businessService is retrieved from a UDDI registry, the serviceKey MUST be present.

The businessKey attribute uniquely identifies the businessEntity which is the provider of the businessService. Every businessService is “contained” in exactly one businessEntity.

When a businessService is published within a UDDI registry, the businessKey MAY be omitted if the businessService is a part of a fully expressed businessEntity element. When a businessService is retrieved from a UDDI registry, the businessKey MUST be present. This behavior provides the ability to browse through the containment relationships given any of the core elements as a starting point.

The businessKey may differ from the publishing businessEntity’s businessKey. This indicates a service projection. A service projection allows a business or organization to include in its businessEntity a businessService offered by some other business or organization. A projected businessService is made a part of a businessEntity by reference as opposed to by containment. Projections to the same service can be made in any number of business entities.

Simple textual information about the businessService, potentially in multiple languages, is given by its name and short service description. The non-empty name, required except when indicating a service projection, and the optional description can occur multiple times. More information about the structure of the name and description elements can be found in Section 3.3 businessEntity Structure.

bindingTemplates is a list of technical descriptions for the Web services provided.

The categoryBag contains a list of business categories that each describes a specific business aspect of the businessService (e.g. industry, product category or geographic region) and is valid in its own category system. More information about the categoryBag element can be found in Section 3.3 businessEntity Structure.

A businessService entity MAY be digitally signed using XML digital signatures. When a businessService is signed, each digital signature MUST be provided by its own dsig:Signature element. Appendix I Support for XML Digital Signature covers the use of this element in accordance with the XML-Signature specification.

3.4.2.1 bindingTemplates

The bindingTemplates structure holds, for a given businessService, the bindingTemplate entities that provide the technical descriptions of the Web services that constitute the businessService.

See Section 3.5 bindingTemplate structure for details on bindingTemplates.

3.5 bindingTemplate Structure

Technical descriptions of Web services are provided by bindingTemplate entities. Each bindingTemplate describes an instance of a Web service offered at a particular network address, typically given in the form of a URL. The bindingTemplate also describes the type of Web service being offered using references to tModels, application-specific parameters, and settings.

Each bindingTemplate is contained in a businessService.


 

3.5.1 Structure Diagram

 

Attributes

Name 

Use 

bindingKey 

optional

serviceKey 

optional 

 

3.5.2 Documentation

A given bindingTemplate entity is uniquely identified by its bindingKey. When a bindingTemplate is published within a UDDI registry, the bindingKey MUST be omitted if the publisher wants the registry to generate a key. When a bindingTemplate is retrieved from a UDDI registry, the bindingKey MUST be present.

The serviceKey attribute uniquely identifies the businessService that contains the bindingTemplate. When a bindingTemplate is published within a UDDI registry, the serviceKey MAY be omitted if the bindingTemplate is a part of a fully expressed businessService element. When a bindingTemplate is retrieved from a UDDI registry, the serviceKey MUST be present.

Simple textual information about the bindingTemplate, potentially in multiple languages, is given by its short binding description. It is optional and can occur multiple times. More information about the structure of the description element can be found in Section 3.3 businessEntity structure.

The accessPoint is a string used to convey the network address suitable for invoking the Web service being described. This is typically a URL but may be an electronic mail address, or even a telephone number. No assumptions about the type of data in this field can be made without first understanding the technical requirements associated with the Web service.

The hostingRedirector is a deprecated element, since its functionality is now covered by the accessPoint. For backward-compatibility, it can still be used, but it is not recommended. See the set of UDDI Version 2 Specifications for a description on hostingRedirector.

Either an accessPoint or a hostingRedirector must be provided within a bindingTemplate.

The tModelInstanceDetails structure is a list of one or more tModelInstanceInfo elements. The collection of tModelKey attributes found in the tModelInstanceInfo elements together form the "technical fingerprint" of a Web service that can be used to identify compatible services.

The categoryBag contains a list of categorizations that each describes a specific aspect of the bindingTemplate and is valid in its own category system. A categoryBag in a bindingTemplate can be used, for example, to indicate that the Web service described by the bindingTemplate has the status “test” or “production”. More information about the structure of the categoryBag element can be found in Section 3.3 businessEntity Structure.

A bindingTemplate entity MAY be digitally signed using XML digital signatures. When a bindingTemplate is signed, each digital signature MUST be provided by its own dsig:Signature element. Appendix I Support for XML Digital Signature covers the use of this element in accordance with the XML-Signature specification.

3.5.2.1 accessPoint

The accessPoint element is an attribute-qualified URI, typically a URL, representing the network address of the Web service being described. The notion of Web service seen here is fairly abstract and many types of network addresses are accommodated.

Attributes

Name 

Use 

useType 

optional

 

The purpose of the optional attribute useType is to facilitate the description of several types of accessPoints.

The following useType attributes values are pre-defined by UDDI:

·         endPoint: designates that the accessPoint points to the actual service endpoint, i.e. the network address at which the Web service can be invoked,

·         bindingTemplate: designates that the accessPoint contains a bindingKey that points to a different bindingTemplate entry. The value in providing this facility is seen when a business or entity wants to expose a service description (e.g. advertise that they have a service available that suits a specific purpose) that is actually a service that is described in a separate bindingTemplate record. This might occur when many service descriptions could benefit from a single service description,

·         hostingRedirector: designates that the accessPoint can only be determined by querying another UDDI registry.  This might occur when a service is remotely hosted.

·         wsdlDeployment: designates that the accessPoint points to a remotely hosted WSDL document that already contains the necessary binding information, including the actual service endpoint.

The useType attribute may contain other values than the four listed above.  See Appendix B Using and Extending the useType Attribute for more information.


 

3.5.2.2 tModelInstanceDetails

This structure is a container for one or more tModelInstanceInfo structures.

When a bindingTemplate is published it SHOULD contain, a tModelInstanceDetails element that in turn contains in its tModelInstanceInfo structures one or more tModel references. This arbitrarily ordered collection of references is called the “technical fingerprint” of the Web service. It indicates that the Web service being described complies with the specific and identifiable specifications implied by the tModelKey values provided. During an inquiry, interested parties can use this information to look for bindingTemplate entities that contain a specific fingerprint or partial fingerprint.

3.5.2.3 tModelInstanceInfo

Each tModelInstanceInfo structure represents bindingTemplate entity-specific details for each  tModel referenced.

Attributes

Name 

Use 

tModelKey 

required

 

The required tModelKey attribute references a tModel that represents a specification with which the Web service represented by the containing bindingTemplate complies.

The description is an optional repeating element. Each description, optionally qualified by an xml:lang attribute, describes what role the tModel plays in the overall service description.

The optional instanceDetails element can be used when tModel-specific settings or other descriptive information are required either to describe a tModel specific component of a service description or to support services that require additional technical data support (e.g. via settings or other handshake operations).


 

3.5.2.4 instanceDetails

This structure holds service instance-specific information that is required to either understand the service implementation details relative to a specific tModel, or to provide further parameter and settings support.

The description is an optional repeating element. Each description, optionally qualified by an xml:lang attribute, describes the purpose and/or use of the particular instanceDetails entry.

The overviewDoc is a mandatory repeating element, used to house references to remote descriptive information or instructions related to the use of a particular tModel and its instanceParms. Multiple overviewDoc elements are useful, for example, to handle alternative representations of the documentation.

The instanceParms is an optional element of type string, used to locally contain settings or parameters related to the proper use of a tModelInstanceInfo. The suggested format is a namespace-qualified XML document so that the settings or parameters can be found in the XML documents elements and attributes.

At least one overviewDoc or instanceParms MUST be provided within the instanceDetails.

3.5.2.5 overviewDoc

This structure describes overview information about a particular tModel use within a bindingTemplate.

The description is a mandatory repeating element. Each description, optionally qualified by an xml:lang attribute, holds a short descriptive overview of how a particular tModel is to be used.

The optional overviewURL is to be used to hold a URL that refers to a long form of an overview document that covers the way a particular tModel is used as a component of an overall Web service description.

At least one description or an overviewURL MUST be provided within the overviewDoc.

3.5.2.6 overviewURL

The RECOMMENDED format for the overviewURL is a URI that is suitable for retrieving the actual overview document with an HTTP GET operation, for example, via a Web browser.

Attributes

Name 

Use 

useType 

optional

 

The optional useType attribute is used to provide information about the type of document at that URL.  One common value used in the useType attribute is “text”.  Using this value denotes that the overviewURL contains additional textual information. The content of the useType attribute may contain other values.  See Appendix B Using and Extending the useType Attribute for more information.

3.6 tModel Structure

Making it easy to describe Web services in ways that are meaningful enough to be useful during searches is an important goal of UDDI. Another goal is to provide a facility to make these descriptions complete enough that people and programs can discover how to interact with Web services they do not know much about. To do this, there needs to be a way to mark a description with information that designates how it behaves, what conventions it follows, and what specifications or standards the service complies with.

Providing the ability to describe compliance with specifications, concepts, or even shared design is one of the roles that the tModel structure fills.

Each tModel instance is a keyed entity in UDDI. In a general sense, the purpose of tModel entities is to provide a reference system based on abstraction. There are two primary uses for tModel entities: as sources for determining compatibility of Web services and as keyed namespace references.

3.6.1 Common tModel uses

There are several places within a businessEntity that can refer to tModels. References to the same tModel instance can be found in many businessEntity structures. tModel references also occur in various API calls.

Section 3.6 tModel Structure gives an overview of the different types of tModels.

3.6.1.1 Defining the technical fingerprint

One common use for tModel entities is to represent technical specifications or concepts. For example, a tModel can be used to represent a specification that defines wire protocols, interchange formats and interchange sequencing rules. Examples can be seen in the RosettaNet Partner Interface Processes[6] specification, the Open Applications Group Integration Specification[7] and various Electronic Document Interchange (EDI) efforts.

Software that communicates with other software invariably adheres to some pre-agreed specifications. In situations where this is true, the designers of the specifications can establish a unique technical identity within a UDDI registry by publishing information about the specification in a tModel. While the main reason of registering a tModel with a specific UDDI registry is to define its identity, the actual specification or set of documents that describes the concept of a tModel is not a part of the registry and is remotely referenced using the overviewDoc structure. Publishers SHOULD choose well-known formats and description languages for the documents that describe the concept each tModel represents.

Once a tModel is published, other parties can express the availability of Web services that are compliant with a specification the tModel represents by simply including a reference to the tModel – i.e., its tModelKey – in their technical service descriptions bindingTemplate data.

This approach facilitates searching for registered Web services that are compatible with a particular specification. Once the proper tModelKey value is known, it is easy to discover that a particular businessEntity has registered a Web service that references the tModel. In this way, the tModelKey becomes a technical fingerprint that is unique to a given specification.

3.6.1.2 Defining value sets

The second general use for tModel entities is within the identifierBag, categoryBag, address and publisherAssertion structures that are used to specify organizational identity and various categories. Used in this context, a tModel represents the system of values used to identify or categorize UDDI entities.

For example, to represent the fact that a business described by a businessEntity has a particular US Tax identifier, a keyedReference is placed into the identifierBag of the businessEntity. The keyedReference has a keyValue that is the tax ID and refers to the tModel that means “the system of US Tax code identifiers”. Together, the keyValue and the tModel reference specify a particular value in a particular system of values.

3.6.1.3 Defining a find qualifier

The third general use for tModel entities is to represent find qualifiers. Find qualifiers are values that modify how the find_xx APIs work. For example, to cause find_business to sort its results in the order in which they were published, the uddi:uddi.org:findqualifier:sortbydateasc may be specified. See Section 5.1.4 Find Qualifiers for details.


 

3.6.2 Structure diagram

 

Attributes

Name 

Use 

tModelKey 

optional

deleted

optional 

 

3.6.3 Documentation

A given tModel entity is uniquely identified by its tModelKey. When a tModel is published within a UDDI registry, the tModelKey MUST be omitted if the publisher wants the registry to generate a key. When a tModel is retrieved from a UDDI registry, the tModelKey MUST be present.

In retrieved tModel data, the deleted attribute, an information-only field, indicates whether the tModel is logically deleted. The two allowed values for this attribute are “true” and “false”.

Simple textual information about the tModel, potentially in multiple languages, is given by its name and short description. While the tModel has exactly one non-empty name, it can have zero or more descriptions. The name SHOULD be formatted as a URI and, as a consequence, the xml:lang attribute of the name element SHOULD NOT be used. More information about the structure of the name and description elements can be found in Section 3.3 businessEntity structure.

The overviewDoc is an optional repeating element, used to house references to remote descriptive information or instructions related to the tModel. For more information about the structure of the overviewDoc v, see Section 3.5 bindingTemplate Structure.

The optional useType attribute contained in the overviewURL of the overviewDoc is used to provide information about the type of document at that URL.  One common value used in the useType attribute is “text”.  Using this value denotes that the overviewURL contains additional textual information. Another common value is “wsdlInterface”, which is used to designate that the overviewURL contains a WSDL interface document that can be re-used by many implementations. The content of the useType attribute may contain other values.  See Appendix B Using and Extending the useType Attribute for more information.

In addition to the tModelKey that uniquely identifies the tModel within the registry, the identifierBag contains a list of logical identifiers, each valid in its own identifier system. For more information about identifierBags, see Section 3.3 businessEntity Structure.

The categoryBag contains a list of categories that describe specific aspects of the tModel (e.g. its technical type). Each category is valid in its own category system. For more information about categoryBags, see Section 3.3 businessEntity structure.

A tModel entity MAY be digitally signed using XML digital signatures. When a tModel is signed, each digital signature MUST be provided by its own dsig:Signature element. Appendix I Support for XML Digital Signatures covers the use of this element in accordance with the XML-Signature specification.

3.7 publisherAssertion Structure

Many businesses and organizations are not effectively represented by a single businessEntity, because their description and discovery are likely to be diverse. Examples include corporations with a variety of subsidiaries, private exchanges with sets of suppliers and their customers and industry consortiums with their members. An obvious solution is to publish several businessEntity structures. Such a set of businessEntity structures represents a more or less coupled community whose members often would like to make some of their relationships visible in their UDDI registrations. This may be accomplished by using the publisherAssertion structure. To eliminate the possibility that one publisher claims a relationship to another that is not reciprocated, both publishers must publish identical assertions for the relationship to become visible. More detailed information about relationships and publisher assertions is given in Appendix A Relationships and Publisher Assertions.

3.7.1 Structure Diagram

3.7.2 Documentation

The two businessEntity instances between which an assertion is made are uniquely identified by the required fromKey and toKey elements. The keyedReference describes the relationship between the businessEntity elements identified by fromKey and toKey. Similar to the general behavior of a keyedReference in a categoryBag (see full description in Section 3.3 businessEntity Structure), the included tModelKey uniquely identifies the relationship type system and the keyName keyValue pair designate a specific relationship type within this value set. Omitted keyNames are treated as empty keyNames.

A publisherAssertion entity MAY be digitally signed using XML digital signatures. When a publisherAssertion is signed, each digital signature MUST be provided by its own dsig:Signature element. Appendix I Support For XML Digital Signatures covers the use of this element in accordance with the XML-Signature specification.

3.8 operationalInfo Structure

Information about a publishing operation is captured whenever a UDDI core data structure is published. This data includes the date and time that the data structure was created and modified, the identifier of the UDDI node at which the publish operation took place, and the identity of the publisher. Operational information for a UDDI data structure is made accessible using the get_operationalInfo inquiry API. See Section 5.1.16 get_operationalInfo.

The operationalInfo structure is used to convey the operational information for the UDDI core data structures, that is, the businessEntity, businessService, bindingTemplate and tModel structures.

3.8.1 Structure diagram

Attributes

Name 

Use 

entityKey 

required

 

3.8.2 Documentation

The UDDI entity with which the operationalInfo is associated is uniquely identified by the required entityKey attribute.

The created element indicates the instant in time at which the entity with which the operationalInfo is associated first appeared in a registry.

The modified element indicates the instant in time at which the entity with which the operationalInfo is associated was last changed by a save operation that may have updated its content. This will initially be equivalent to the value of the created element, but will diverge as changes are made over time.

Some UDDI core data structures are containers of other UDDI core data structures. For instance, businessService elements are contained by businessEntity elements and bindingTemplate elements are contained by businessService elements. Independent changes made to contained entities of such entities (for example, changes to an existing businessService within a businessEntity by means of a save_service API call) do not affect the value of the modified element associated with the containing entity. Instead, the modifiedIncludingChildren element in the containing entity contains the maximum of its own modified element and the modifiedIncludingChildren elements of each of the entities it contains (if any). If a contained entity is deleted or moved elsewhere, the modifiedIncludingChildren element is also updated, since such operations would otherwise not be documented elsewhere. Changes in a service that is being projected do not affect the modifiedIncludingChildren element of the businessEntity in which it is projected.

The degree to which the clocks of each UDDI node used to generate the created, modified, and modifiedIncludingChildren elements are synchronized is not architecturally specified, but rather is a matter of registry policy. Likewise, the frequency with which each clock is incremented (e.g.: 60Hz, 100Hz, etc.) is also a matter of registry policy.

The UDDI node (if any) that has custody of the entity to which an operationalInfo element is attached is identified by the nodeID element. The nodeID contains a unique key that is used to identify this node within a UDDI registry. As described in Section 7.5.2 Configuration of a UDDI Node – operator element for nodes that implement UDDI Replication, this element MUST match the value specified in the Replication Configuration element associated with the node.

A node may provide an indication of the owner of the data corresponding to the entityKey in the authorizedName element.  The exact contents of this element and how the authorizedName element should be interpreted depends on the authentication, identification and privacy policies of the registry and node (see Chapter 9, Policy).


 

4      Using UDDI APIs

UDDI specifies a number of API sets that are described in Chapter 5 UDDI Programmer APIs and Section 7.4 Replication API Set. If a node claims to support a UDDI API it MUST implement the API in conformance with this specification. Node and registry policy determine the transport and security mechanisms used for each API set.  See Chapter 9 Policy for more information.

A UDDI registry MUST have at least one node that offers a Web service compliant Inquiry API set.  A UDDI registry SHOULD have at least one node that offers a Web service compliant with the Publication, Security, and Custody and Ownership Transfer API sets.  If a UDDI registry has multiple nodes, all nodes SHOULD offer Web services that are compliant with the Replication API set.  The Subscription and Value Set API sets are OPTIONAL for all nodes and all registries.

The API descriptions that follow in Chapter 5 UDDI Programmers APIs designate input elements as optional or required. Required input elements MUST be provided within the guidelines described by the UDDI schema and in the API descriptions.  Optional input elements MAY be provided, and when they are, they too must follow the guidelines described by the UDDI schema and in the API description.

4.1 SOAP Usage

This section describes the SOAP specific conventions and requirements applicable to UDDI.

Any use of SOAP by a UDDI implementation that differs from or extends the behavior described below should be modeled by publishing a tModel to represent this different use of SOAP.  Any Web services that make use of the different SOAP behavior should reference the tModel in the tModelInstanceDetails of the Web service’s bindingTemplate. See Section 9.4.4 UDDI Data and Information Model for more information.

4.1.1 Support for SOAPAction

SOAP 1.1 requires the presence of the Hyper Text Transport Protocol (HTTP) header field named SOAPAction when an HTTP binding is specified.  UDDI requires the presence of this HTTP Header field to be SOAP 1.1 compliant.  Different SOAP toolkits treat this HTTP header field differently. For maximum tool compatibility, the SOAPAction may contain any value, including an empty string.

Both of the following message styles (among others) are permitted in UDDI.

POST /someVerbHere HTTP/1.1

Host: www.somenode.org

Content-Type: text/xml; charset="utf-8"

Content-Length: nnnn

SOAPAction: ""

 

<?xml version="1.0" encoding="UTF-8" ?>

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">

<Body>

   <get_bindingDetail xmlns="urn:uddi-org:api_v3">


and

POST /someVerbHere HTTP/1.1

Host: www.somenode.org

Content-Type: text/xml; charset="utf-8"

Content-Length: nnnn

SOAPAction: "get_bindingDetail"

 

<?xml version="1.0" encoding="UTF-8" ?>

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">

<Body>

   <get_bindingDetail xmlns="urn:uddi-org:api_v3">

 

4.1.2 Support for SOAP Actor

The SOAP Actor feature is not supported by UDDI.  UDDI nodes MUST reject any request that arrives with a SOAP Actor attribute in the SOAP Header element by returning a generic SOAP fault with no detail element and a “Client” faultcode. The faultstring will clearly indicate the problem.

4.1.3 Support for SOAP encoding

The SOAP encoding feature (i.e., SOAP 1.1. section 5) is not supported by UDDI. In messages sent to a UDDI node there must be no claims made about the encoding style of any element within the “urn:uddi-org:*” namespace.  If such claims are made, the node must respond with a generic SOAP fault with no detail element and a “Client” faultcode.  The faultstring will clearly indicate the problem

4.1.4 Support for SOAP Headers

UDDI registries MAY ignore the contents of SOAP header.  SOAP headers that have the must_understand attribute set to true MUST be rejected with a SOAP fault - MustUnderstand. UDDI registries MAY ignore other extension headers received.

4.1.5 Support for SOAP Fault

UDDI registries signal a generic SOAP Fault[8] when unknown API references are invoked, validation failures occur, etc.  UDDI specific errors MUST be handled via a SOAP Fault element containing a UDDI dispositionReport element.  The following SOAP fault codes are used:

·         VersionMismatch: An invalid namespace reference for the SOAP envelope element was passed.  The valid namespace value is “http://www.xmlsoap.org/soap/envelope/".

·         MustUnderstand: A SOAP header element, permitted to be ignored by a UDDI node, was received with the Must_Understand attribute set to true.  In response, a UDDI node MUST return this response.  See Section 4.8 Success and Error Reporting and Chapter 12 Error Codes.

·         Client: A message was incorrectly formed or did not contain enough information to perform more exhaustive error reporting.

·         Server: The Server class of errors indicate that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to the processing of the message. For example, processing could include communicating with an upstream processor which did not respond. The message may succeed at a later point in time.

4.1.6 XML prefix conventions – default namespace support

UDDI nodes are REQUIRED to support the use of the default namespaces (i.e. no XML prefix) in SOAP request and response documents as shown in the following HTTP example:

POST /someVerbHere HTTP/1.1

Host: www.example.com

Content-Type: text/xml; charset="utf-8"

Content-Length: nnnn

SOAPAction: ""

 

<?xml version="1.0" encoding="UTF-8" ?>

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">

   <Body>

       <get_bindingDetail xmlns="urn:uddi-org:api_v3">

4.2 XML Encoding Requirements

All messages sent to and received from UDDI nodes MUST be encoded in either UTF-8 or UTF-16, and MUST specify the Hyper Text Transport Protocol (HTTP) Content-Type header with a charset parameter of "utf-8" or “utf-16” respectively and a content type of text/xml. All such messages MUST also have the corresponding 'encoding="UTF-8"' or 'encoding="UTF-16"' markup in the XML-DECL that appears on the initial line.  Other encoding name variants, such as UTF8, UTF_8, etc. MAY NOT be used.

Therefore, to be explicit, when using UTF-8, the initial line MUST be:

<?xml version="1.0" encoding="UTF-8" ?>

 

and the Content-Type header MUST be:

Content-type: text/xml; charset="utf-8"

 

When using UTF-16, the initial line MUST be:

<?xml version="1.0" encoding="UTF-16" ?>

 

and the Content-Type header MUST be:

Content-type: text/xml; charset="utf-16"

 

All parts of the Content-type header are case insensitive and quotations are optional.

UDDI nodes MUST reject messages that do not conform to this requirement.

For simplification purposes, all examples in this document use UTF-8.

4.3 Support for Unicode: Byte Order Mark

Unicode UTF-8 allows data to be transmitted with an OPTIONAL three-byte signature, also known as Byte Order Mark (BOM), preceding the XML data.  This signature does not contain information that is useful for decoding the contents; but, in the case of UTF-8, tells the receiving program that the rest of the text is in UTF-8.  Its presence makes no difference to the endianness of the byte stream as UTF-8 always has the same byte order.  The BOM is not part of the textual content therefore UDDI nodes MAY remove the BOM prior to processing messages received.

UDDI nodes MUST be prepared to accept messages that contain Byte Order Marks, but the Byte Order Mark is not required to process SOAP messages successfully.

UDDI nodes MUST NOT return a Byte Order Mark with any of the response messages defined in this specification.

All UDDI nodes MUST support all of the Unicode characters, including all compatibility characters. See Section 4.6.1.1 XML Normalization and Canonicalization for further information on required behavior with respect to character set normalization and canonicalization.

4.4 About uddiKeys

UDDI registries MUST use keys that conform to the following grammar.  All UDDI keys are URIs that conform to RFC 2396 but not all URIs are valid UDDI keys.  The URIs that are valid as UDDI keys correspond to a subset of the opaque part alternative of the absoluteURI rule in RFC 2396. Further, registries MUST use keys from the scheme “uddi” following the syntactic and semantic rules for that scheme as given in this section, in Section 5.2.2 Publishing Entities with Publisher Assigned Keys, in Section 8.2 Data Management Policies and Procedures Across Registries, and Section 9.4.3 Policy Abstractions for the UDDI keying scheme. The primary motivations for the scheme for uddiKeys is to allow publishers to specify keys for entities they publish in UDDI registries using “sensible looking” keys and to promote interoperation among UDDI registries.  See Chapter 10 Multi-Version Support for issues regarding backwards compatibility.

Keys in UDDI are declared as language independent case insensitive and must be case-folded by nodes as part of processing any API.  With the inclusion of the attribute caseMapKind=”fold” from Schema Centric Canonicalization in the schema declaration for uddiKey type, the normalized form of a uddiKey element is produced using Unicode Case Folding as defined in the Unicode Technical Report on Case Mappings (see http://www.unicode.org/unicode/reports/tr21/).

4.4.1 Key Syntax[9]

uddiScheme            =   %d117.100.100.105  ; “uddi” in lower case

 

uddiKey               =   nonKeyGeneratorKey / keyGeneratorKey

 

nonKeyGeneratorKey   =   uuidKey / domainKey / derivedKey

 

uuidKey               =   uddiScheme “:” uuid_part

 

uuid_part         =   8HEXDIG “-“

                      4HEXDIG “-“

                      4HEXDIG “-“

                      4HEXDIG “-“

                      12HEXDIG

 

domainKey         =   uddiScheme “:” hostname

 

hostname          =   *(domainlabel “.”) toplabel [“.”]

 

domainlabel           =   alphanum / alphanum *(alphanum / “-“) alphanum

 

toplabel          =   ALPHA / ALPHA *(alphanum / “-“) alphanum

 

alphanum          =   ALPHA / DIGIT

 

derivedKey            =   nonKeyGeneratorKey “:” KSS

 

keyGeneratorKey       =   nonKeyGeneratorKey “:” “keygenerator”

 

KSS                  =   1*uric ; KSS MUST NOT be “keygenerator”

 

uric              =   reserved / unreserved / escaped

 

reserved          =   “;” / “/” / “?” / “:” / “@” / “&” / “=” / “+” / “$” / “,”

 

unreserved            =   alphanum / mark

 

mark              =   “-” / “_” / “.” / “!” / “~” / “*” / “’” / “(“ / “)”

 

escaped               =   “%”  HEXDIG HEXDIG

 

There are some extra restrictions on domain names that are not captured in the ABNF syntax above:

1.       The maximum length of a string representation of a hostname is 253 characters/octets.

2.       The maximum length of an individual domainlabel is 63 characters/octets.

There is an additional restriction on KSS that is not captured in the ABNF syntax above:

1.       KSS MUST NOT be “keygenerator”.

 

The keyword “keygenerator” is case-insensitive.

4.4.2 Examples of keys

The following are examples of legal domainKeys.

uddi:tempuri.com

Here, “tempuri.com” is the domain of this key.

uddi:us.tempuri.com

Here, “us.tempuri.com” is the domain.

The following is an example of a legal uuidKey.

uddi:4CD7E4BC-648B-426D-9936-443EAAC8AE23

“4CD7E4BC-648B-426D-9936-443EAAC8AE23” is the uuid of this key.

The following are examples of legal derivedkeys

uddi:AC104DCC-D623-452F-88A7-F8ACD94D9B2B:xyzzy

This is a derived Key based on the <uuidKey> “uddi:AC104DCC-D623-452F-88A7-F8ACD94D9B2B”. The string “xyzzy” is key’s KSS.

uddi:tempuri.com:fish:buyingservice

This key is based on the derivedKey “uddi:tempuri.com:fish”. The string “buyingService” is the key’s KSS.

The following is an example of a legal key generator key

uddi:tempuri.com:keygenerator

This key is based on the domainKey “uddi:tempuri.com”

4.5 Data insertion and document order

4.5.1 Inserting Data in Entities During save_xx Operations

When saving a businessEntity, businessService, bindingTemplate or tModel, the UDDI node is required to add or replace certain elements and attributes if they are not present or are incorrectly specified in the entity passed to the save_xx API. These are: For businessEntity, businessService, bindingTemplate and tModel structures, the businessKey, serviceKey, bindingKey, and tModelKey of the structure being saved.

4.5.2 Inserting Elements in Existing Entities

When a new child element is inserted by a publication API, the UDDI node MUST add the new child as the last of its siblings. For example, the save_service call can be used to add a businessService to a businessEntity. The added businessService appears as the last one in the (possibly single item) list of such businessService structures.  When inserting a businessService using save_service or a bindingTemplate using save_binding, any digital signatures on the containing UDDI data structure may become invalid with the addition of a new child.

4.5.3 Preservation of Document Order

The UDDI data model requires UDDI nodes to preserve the order of all descendent elements in the UDDI core data structures.  When a UDDI node responds to an inquiry API call, the descendent elements of the core data structures in the response must have the order specified by their publishers or by the order of insertion.

4.6 XML Normalization and Canonicalization

UDDI registries provide publishers with the ability to digitally sign and save entities they publish, and inquirers with the ability to retrieve and validate the digital signatures on published material. In order for this to be possible, publishers and registries MUST handle “normalization” and “canonicalization” as described in this section.

Normalization is the process of standardizing the representation of the characters that make up a document. In Unicode data there is often more than one way to represent a given glyph. For example, the character “Å” may be represented as one single character “LATIN CAPITAL LETTER A WITH RING ABOVE” (hexadecimal 00C5), as another single character “ANGSTROM SIGN” (hexadecimal 212B) or as a composition of “LATIN CAPITAL LETTER A” (hexadecimal 0041) and “COMBINING RING ABOVE” (hexadecimal 030A). Normalization chooses one standard representation in every such case.

Canonicalization is the process of generating a standard representation of XML. It deals with issues such as the representation of tags; attribute ordering; namespace declaration, expansion and ordering; and whitespace handling.

4.6.1 Behavior of UDDI nodes

4.6.1.1 Normalization and Canonicalization

UDDI registries MUST exhibit certain behavior with respect to the saved vs. retrieved representations of the entities they handle. Aspects of this behavior REQUIRE attention to the Schema Centric XML Canonicalization (see http://uddi.org/pubs/SchemaCentricCanonicalization.htm) for this function. More specifically, registries MUST exhibit the following behavior with respect to the data they store and retrieve. Let:

·         C(d, S) be the Schema Centric XML Canonicalization transform of document d with respect to the set of schemas S,

·         U be the set of UDDI v3 schemas,

·         x and y be UDDI entities,

·         R be a UDDI registry.

For all x saved in R, if y is x as retrieved from R, it MUST be the case that C(x, U) = C(y, U) in a literal bit-by-bit sense.

Stated informally, if you save an entity in a UDDI registry and later retrieve it, the canonicalization of what you saved will be the same as the canonicalization of what you got back. However, this is only guaranteed to be true with respect to the Schema Centric Canonicalization algorithm; in particular such guarantees are not provided with respect to the Canonical XML algorithm or its Exclusive Canonical XML variation (see http://www.w3.org/TR/xml-exc-c14n).[10]

4.6.2 Client Behavior

The behavior of UDDI registries with respect to normalization and canonicalization means that if an entity, x, is published and later retrieved from a registry as y, y will not, in general, be precisely the same bits as x; only a canonicalized form of x and y are guaranteed to be bitwise identical. This behavior means that for digital signatures to work, publishers and inquirers SHOULD take certain actions.

4.6.2.1 Publishers

Publishers SHOULD prepare entities they wish to sign by including in their XML DSIG SignedInfo a Transform which canonicalizes them using Schema Centric XML Canonicalization (see Section 4.6.1.1 Normalization and Canonicalization) before calculating the signatures. Publishers SHOULD avoid inserting elements into published signed entities as doing so likely invalidates the signature.

4.6.2.2 Inquirers

To validate signed entities, inquirers SHOULD adhere to the strictures and processes of the XML DSIG specification. If, as will almost always be the case in UDDI, the Schema Centric Canonicalization[11] algorithm was indicated by the signer, then execution of the algorithm will be necessary as part of the process of validating the signature.

4.7 About Access Control and the authInfo Element

The Authorization Policy for a Registry defines how/if access control is implemented. See Chapter 9 for a discussion of Policy issues.

The authInfo element is an OPTIONAL element on every API call of the Publication, Inquiry and Subscription API sets.  Using an optional element allows different UDDI registries and nodes within the registries to implement access control on whichever sets of operations such control is desired.

AuthInfo is an opaque element whose content is meaningful only to the node that created it. It is intended to enable a variety of authentication mechanisms. For example, it may be used with:

·         Id/password based systems in which the authInfo is an authorization token generated by the authentication operation (i.e. Kerberos Tickets)

·         Authorization assertions (i.e., SAML, X509 Attribute Certificates)

When a node uses authInfo elements it MAY offer the get_authToken and discard_authToken APIs as a means of obtaining and disposing of them. Alternatively, or in addition, it MAY offer other means for doing this.

The use of authInfo elements is not the only means a node may use for access control. For example, if a node chooses to implement authentication at the transport level, it may well rely on the authorization information supplied by the transport. 


 

4.8 Success and Error Reporting

The first line of error reporting is governed by the SOAP specification.  SOAP fault reporting and fault codes will be returned for most invalid requests or any request where the intent of the caller cannot be determined.

If any application level error occurs in processing a request message, a dispositionReport element will be returned to the caller within a SOAP fault report.  Faults that contain disposition reports contain error information that includes descriptions and the type of key associated with an entity that can be used to determine the cause of the error.  API-specific interpretations of error codes are provided with each API description.

In a manner consistent with the SOAP processing rules (Section 6.2 of the SOAP 1.1 specification) UDDI follows the semantics of the Hyper Text Transport Protocol (HTTP) Status codes for communicating status information in HTTP. As is the case for SOAP, success reporting will use a 200 status code to indicate that the client's request including the SOAP component was successfully processed.

UDDI application-level errors SHOULD be conveyed using standard HTTP status code where a 500-level code indicates a server-induced error. In such cases, the UDDI node MUST issue an HTTP 500 "Internal Server Error" response and return a dispositionReport inside a SOAP fault report. 

Many of the API constructs defined in this specification allow one or more of a given type of information to be passed.  These API calls each conceptually represent a request on the part of the caller. The general error handling treatment recommended for UDDI nodes is to detect errors in a request prior to processing the request.  Any errors in the request detected will invalidate the entire request, and cause a dispositionReport to be generated within a SOAP Fault as described below.

In the case of an API call that involves passing multiples of a given structure, the dispositionReport will call out only the first detected error, and is not responsible for reporting multiple errors or reflecting intermediate “good” data.  In situations where a specific reference within a request causes an error to be generated, the corresponding disposition/fault report will contain a clear indication of the key value that caused the rejection of the rejected request.

In general, UDDI nodes may return any UDDI error code needed to describe an error. The error codes specified within each API call description are characteristic of the API call, but other UDDI error codes may be returned in unusual circumstances or when doing so adds additional descriptive information.  See Chapter 12 Error Codes for a summary of UDDI error codes.

4.8.1 dispositionReport element

A dispositionReport is returned by many of the APIs whether the call completes successfully or not.  Error information is always returned in the dispositionReport. A dispositionReport has the form:


 

Attributes

Name  

Use  

truncated  

optional  

 

The dispositionReport is a non-empty list of success or error conditions, each described in a result element. The truncated attribute indicates whether error conditions occurred that are not listed in the dispositionReport.

Attributes

Name  

Use  

keyType  

optional  

errno

required

 

The result element contains an optional keyType and a required errno attribute. The errno attribute is set to the value described in Chapter 12 Error Codes. The keyType attribute is used to indicate the type of the uddiKey that is being reported on, e.g. in an E_invalidKeyPassed error condition. Valid values for keyType are “businessKey”, “serviceKey”, “bindingKey”, “tModelKey” and “subscriptionKey”. Detailed information about the error condition can be found in the optional errInfo element.

The errInfo element, if necessary, describes the error condition in more detail. It contains a string that is adorned with an errCode attribute, set to the string described in Chapter 12 Error Codes.

Like other UDDI data structures, the disposition report includes a namespace that identifies the UDDI version for which it applies.  When a UDDI node receives a message with a namespace that cannot be used to determine the version, a disposition report is return for the most current UDDI version that the node supports.

4.8.2 Success reporting using the dispositionReport element

The general form of a success report is:

<?xml version="1.0" encoding="UTF-8" ?>

<Envelope xmlns="http://schemas.xmlsoaporg.org/soap/envelope/">

   <Body>

       <dispositionReport xmlns="urn:uddi-org:api_v3" >

          <result errno="0" >

              <errInfo errCode=“E_success" />

          </result>

       </dispositionReport>

   </Body>

</Envelope>

 

In the case of success structures, the dispositionReport element is used as a normal SOAP message with the dispositionReport returned directly within the SOAP Body element.

4.8.3 Error reporting using the dispositionReport element

All application errors are communicated via the use of the SOAP FAULT element.  The general form of an error report is:

<?xml version="1.0" encoding="UTF-8" ?>

<Envelope xmlns="http://schemas.xmlsoaporg.org/soap/envelope/">

   <Body>

     <Fault>
       <faultcode>Client</faultcode>

       <faultstring>Client Error</faultstring>

       <detail>

         <dispositionReport xmlns="urn:uddi-org:api_v3">

            <result errno="10500">

               <errInfo errCode=“E_fatalError">The findQualifier

                  value passed is unrecognized: XYZ</errInfo>

            </result>

         </dispositionReport>

       </detail>
     </Fault>

   </Body>

</Envelope>

 

Multiple result elements may be present within the dispositionReport element, and can be used to provide very detailed error reports for multiple error conditions.  The number of result elements returned within a disposition report is implementation specific.  In general it is permissible to return an error response as soon as the first error in a request is detected.  References within the API reference sections that describe error text content rules pertain to the content of the errInfo element.

 


 

5      UDDI Programmers APIs

 

This API reference is divided into a number of logical sections, each addressing a particular programming focus.  These sections cover the inquiry API, the publishing API and the OPTIONAL security, custody transfer, subscription and value set APIs.

In all cases, the XML structures, attributes and element names shown in the API examples are derived from the UDDI API schemas described in Chapter 2 UDDI Schemas.  For a full understanding of structure contents, refer to this chapter, the UDDI schemas, and Chapter 3 UDDI Registry Data Structures.

Each API set has one or more corresponding tModels that are referenced in bindingTemplate structures to indicate that a compliant Web service is offered for the API set.  See Section 11.1.9 UDDI Registry API tModels.

5.1 Inquiry API Set

The inquiry API set allows one to locate and obtain detail on entries in a UDDI registry. The Inquiry API provides three forms of query that follow broadly used conventions which match the needs of software traditionally used with registries.  Three distinct patterns of inquiry are supported.

5.1.1 The browse pattern

Software that allows people to explore and examine large quantities of data requires browse capabilities.  The browse pattern characteristically involves starting with some broad information, performing a search, finding general result sets and then selecting more specific information for drill-down.

This specification supports the browse pattern by way of the API calls involving “find” operations (hereafter referred to as the “find_xx” APIs).  These calls form the search capabilities provided by the API and are matched with summary return structures that return overview information about the registered information associated with the inquiry API and the search criteria specified in the inquiry.

A typical browse sequence might involve finding whether a particular business with a particular name has any information registered.  This sequence starts with a call to find_business, passing the business name (which could involve the use of just a portion of the name together with a wildcard character by using the approximateMatch findQualifier described below).  This returns a businessList result - overview information (keys, names and descriptions) derived from the registered businessEntity information, matching on the name.  Information in the list may be used to select among the businesses and then to drill down into the corresponding businessService information, looking for one which matches a particular technical fingerprint (i.e., tModel such as for purchasing, shipping, etc) using the find_service API call.  UDDI provides many similar sequences of API calls that let callers start with a broad notion of the kind of information they wish to retrieve from a registry, retrieve summary information, and then drill down to get details.

5.1.2 The drill-down pattern

Each instance of the core data structures – businessEntity, businessService, bindingTemplate and tModel – has a key which is one of the items in the summary information retrieved by find_xx APIs. Given such a key, it is easy to retrieve the full registered details for the corresponding instance by passing the key to the relevant get_xx API.

Continuing the example from the previous section on browsing, the businessKey associated with the business being sought is one of the items in the businessList returned by find_business.  This key can be passed as an argument to get_businessDetail.  Upon success, this API returns a businessDetail containing the full registered information, including the businessEntity structure for the entity whose key value was passed.

5.1.3 The invocation pattern

To have an application take advantage of a Web service that is registered within a UDDI registry, that application must be prepared to use the information found in the registry for the specific Web service being invoked.  This type of inter-business service call has traditionally been a task that is undertaken entirely at development time.  The degree to which this changes with Web services is an application design choice, but the existence of UDDI registry entries makes it significantly easier to do dynamic binding using the following pattern.

Obtain the bindingTemplate data for the Web service of interest from a UDDI registry, such as the UDDI Business Registry. Typically this is done using one of the browse-and-drill-down patterns discussed above. The bindingTemplate contains the specific details about an instance of a given interface type, including the location at which a program starts interacting with the Web service.  The calling application caches this information and uses it to contact the Web service at the registered address whenever it needs to communicate with the Web service instance.

If a call fails using cached information previously obtained from a UDDI registry, the application SHOULD query the UDDI registry for fresh bindingTemplate information.  The proper call is get_bindingDetail passing the original bindingKey value.  If the data returned is different from the cached information, the application SHOULD retry the invocation using the fresh information.  If the result of this retry is successful, the new information SHOULD replace the cached information.

By using this pattern with Web services, applications can interact with partners without undue communication and coordination costs.  For example, if a business has activated a disaster recovery site, most of the calls from partners will fail when they try to invoke Web services at the failed site.  By updating the UDDI information with the new address for the Web service, partners who use the invocation pattern will automatically locate the new Web service information and recover without further administrative action.  Cached binding information could alternatively be kept up to date by means of notification or polling.

5.1.4 Find Qualifiers

Each of the find_xx APIs accepts an optional findQualifiers argument, which may contain multiple findQualifier values.  Find qualifiers may be either tModelKeys or may be referenced by a string containing a “short name”.  Each of the pre-defined findQualifiers in UDDI can be referenced using either the appropriate tModelKey, or by its short name.  Registries MUST support both forms, and MUST accept the find qualifiers case-insensitively.  The use of tModelKeys for findQualifiers allows extension to create additional new qualifiers, but registries are not obligated to support them.  Find qualifiers not recognized by a node will return the error E_unsupported. 

Matching behavior for the find_xx APIs when multiple criteria are specified is logical “AND” by default.  Find qualifiers allow the default search behaviors to be overridden.  Not all find_xx APIs support all findQualifier element values.  The following table identifies which findQualifiers apply to each API:

Table 1: Find Qualifiers by API

Find Qualifier Short Name and tModel Name

find_business

find _service

find_binding

find_tModel

find_related

Businesses

andAllKeys

(uddi-org:andAllKeys)

 

YES

default for   categoryBag, tModelBag, applicable to identifierBag

YES

default for tModelBag &  categoryBag

YES

default for categoryBag,  tModelBag

YES

default for categoryBag, applicable to identifierBag

NO

approximateMatch

(uddi-org:approximateMatch:SQL99)

YES

YES

YES

YES

YES

binarySort

(uddi-org:binarySort)

YES

YES

NO

YES

NO

bindingSubset

(uddi-org:bindingSubset)

YES

applicable to categoryBag on bindingTemplate

YES

applicable to categoryBag on bindingTemplate

NO

NO

NO

caseInsensitiveSort

(uddi-org:caseInsensitiveSort)

YES

YES

NO

YES

YES

caseInsensitiveMatch

(uddi-org:caseInsensitiveMatch)

YES

YES

YES

YES

YES

caseSensitiveSort”  [12]

(uddi-org:caseSensitiveSort)

YES

YES

NO

YES

YES

caseSensitiveMatch”  [13]

(uddi-org:caseSensitiveMatch)

YES

YES

YES

YES

YES

combineCategoryBags

(uddi-org:combineCategoryBags)

YES

YES

NO

NO

NO

diacriticInsensitiveMatch”  [14]

(uddi-org:diacriticInsensitiveMatch)

YES

YES

YES

YES

YES

diacriticSensitiveMatch”  [15]

(uddi-org:diacriticSensitiveMatch)

YES

YES

YES

YES

YES

exactMatch[16]

(uddi-org:exactMatch)

YES

YES

YES

YES

YES

signaturePresent

(uddi-org:signaturePresent)

YES

YES

YES

YES

YES

orAllKeys

(uddi-org:orAllKeys)

YES

default for identifierBag, applicable to tModelBag or categoryBag

YES

applicable to categoryBag, tModelBag

YES

applicable to categoryBag, tModelBag

YES

applicable to categoryBag, default for identifierBag

NO

orLikeKeys

(uddi-org:orLikeKeys)

YES

applicable to identifierBag, categoryBag

YES

applicable to categoryBag

YES

applicable to categoryBag

YES

applicable to categoryBag, identifierBag

NO

serviceSubset

(uddi-org:serviceSubset)

YES

NO

NO

NO

NO

sortByNameAsc[17]

(uddi-org:sortByNameAsc)

YES

YES

NO

YES

YES

sortByNameDesc

(uddi-org:sortByNameDesc)

YES

YES

NO

YES

YES

sortByDateAsc” 

(uddi-org:sortByDateAsc)

YES

YES

YES

default behavior

YES

YES

sortByDateDesc

(uddi-org:sortByDateDesc)

YES

YES

YES

YES

YES

suppressProjectedServices

(uddi-org:suppressProjectedServices)

YES

YES

NO

NO

NO

UTS-10[18]

(uddi-org:UTS-10)

YES

YES

NO

YES

YES

 

5.1.4.1 Invalid Find Qualifier Combinations

Using a findQualifier with one of the find_xx APIs to which it does not apply, will generally result in that qualifier being ignored, but there are a few situations for which certain findQualifiers elements are mutually exclusive and supplying them together will result in an E_invalidCombination error.  The invalid combinations are:

·         andAllKeys, orAllKeys, and orLikeKeys are mutually exclusive

·         sortByNameAsc and sortByNameDesc are mutually exclusive

·         sortByDateAsc and sortByDateDesc are mutually exclusive

·         combineCategoryBags, serviceSubset and bindingSubset are mutually exclusive

·         exactMatch and approximateMatch are mutually exclusive

·         exactMatch and caseInsensitiveMatch are mutually exclusive

·         binarySort and UTS-10 are mutually exclusive, as are all collation algorithm tModels with each other

·         diacriticSensitiveMatch and diacriticInsensitiveMatch are mutually exclusive

·         exactMatch and diacriticInsensitiveMatch are mutually exclusive

·         caseSensitiveSort and caseInsensitiveSort are mutually exclusive

·         caseSensitiveMatch and caseInsensitiveMatch are mutually exclusive

See Chapter 11, Utility tModels and Conventions for further information on find qualifier tModels.

5.1.4.2 General Form of Find Qualifiers

Find qualifiers are expressed by using a findQualifiers argument. The general form of the findQualifiers element is:

 

where a findQualifier can be either a string (with a maximum length of 255), or a tModelKey.

5.1.4.3 Find Qualifier Descriptions

The value passed in each findQualifier element indicates the behavior change desired.  This list defines the set of UDDI defined valid qualifiers.  Nodes MUST implement all of these except as noted.

·         andAllKeys: this changes the behavior for identifierBag to AND keys rather than OR them.  This is already the default for categoryBag and tModelBag.

·         approximateMatch: signifies that wildcard search behavior is desired.  This behavior is defined by the uddi-org:approximatematch:SQL99 tModel and means "approximate matching as defined for the character like predicate in ISO/IEC9075-2:1999(E) Section 8.5 like predicate, where the percent sign (%)  indicates any number of characters and an underscore (_) indicates any single character. The backslash character (\) is used as an escape character for the percent sign, underscore and backslash characters. This find qualifier adjusts the matching behavior for name, keyValue and keyName (where applicable).

·         binarySort:  this qualifier allows for greater speed in sorting.  It causes a binary sort by name, as represented in Unicode codepoints.

·         bindingSubset:  this is used in the find_business API or the find_service API and is used only in conjunction with a categoryBag argument.  It causes the component of the search that involves categorization to use only the categoryBag elements from contained bindingTemplate elements within the registered data and ignores any entries found in the categoryBag which are not direct descendent elements of registered businessEntity elements or businessService elements.  The resulting businessList or serviceList return those businesses or services that matched based on this modified behavior, in conjunction with any other search arguments provided.  Additionally, in the case of the returned businessList from a find_business, the contained serviceInfos elements will only reflect summary data (in a serviceInfo element) for those services (contained or referenced) that contained a binding that matched on one of the supplied categoryBag arguments.

·         caseInsensitiveMatch: signifies that the matching behavior for name, keyValue and keyName (where applicable) should be performed without regard to case.

·         caseInsensitiveSort: signifies that the result set should be sorted without regard to case. This overrides the default case sensitive sorting behavior. 

·         caseSensitiveMatch: signifies that the matching behavior for name, keyValue and keyName (where applicable) should be performed with regard to case.  This is the default behavior.

·         caseSensitiveSort:   signifies that the result set should be sorted with regard to case.  This is the default behavior.

·         combineCategoryBags:  this may only be used in the find_business and find_service calls.  In the case of find_business, this qualifier makes the categoryBag entries for the full businessEntity element behave as though all categoryBag elements found at the businessEntity level and in all contained or referenced businessService elements and bindingTemplate elements were combined.  Searching for a category will yield a positive match on a registered business if any of the categoryBag elements contained within the full businessEntity element (including the categoryBag elements within contained or referenced businessService elements or bindingTemplate elements) contains the filter criteria.  In the case of find_service, this qualifier makes the categoryBag entries for the full businessService element behave as though all categoryBag elements found at the businessService level and in all contained or referenced elements in the bindingTemplate elements were combined.  Searching for a category will yield a positive match on a registered service if any of the categoryBag elements contained within the full businessService element (including the categoryBag elements within contained or referenced bindingTemplate elements) contains the filter criteria.

·         diacriticInsensitiveMatch: signifies that matching behavior for name, keyValue and keyName (where applicable) should be performed without regard to diacritics.  Support for this findQualifier by nodes is OPTIONAL.

·         diacriticSensitiveMatch: signifies that the matching behavior for name, keyValue and keyName (where applicable) should be performed with regard to diacritics.  This is the default behavior.

·         exactMatch:  signifies that only entries with names, keyValues and keyNames (where applicable) that exactly match the name argument passed in, after normalization, will be returned.  This qualifier is sensitive to case and diacritics where applicable.  This qualifier represents the default behavior.

·         orAllKeys: this changes the behavior for tModelBag and categoryBag to OR the keys within a bag, rather than to AND them. Using this findQualifier with both a categoryBag and a tModelBag, will cause all of the keys in BOTH the categoryBag and the tModelBag to be OR’d together rather than AND’d. It is not possible to OR the categories and retain the default AND behavior of the tModels. The behavior of keyedReferenceGroups in a categoryBag is analogous to that of individual keyedReferences, that is, the complete categoryBag is changed to OR the keys.

·         orLikeKeys: when a bag container (i.e. categoryBag or identifierBag) contains multiple keyedReference elements, any keyedReference filters that come from the same namespace (e.g. have the same tModelKey value) are OR’d together rather than AND’d.  For example “find any of these four values from this namespace, and any of these two values from this namespace”. The behavior of keyedReferenceGroups is analogous to that of keyedReferences, that is, keyedReferenceGroups that have the same tModelKey value are OR’d together rather than AND’d.

·         serviceSubset: this is used only with the find_business API and is used only in conjunction with a categoryBag argument.  It causes the component of the search that involves categorization to use only the categoryBag elements from contained or referenced businessService elements within the registered data and ignores any entries found in the categoryBag which are not direct descendent elements of registered businessEntity elements.  The resulting businessList structure contains those businesses that matched based on this modified behavior, in conjunction with any other search arguments provided.  Additionally, the contained serviceInfos elements will only reflect summary data (in a serviceInfo element) for those services (contained or referenced) that matched on one of the supplied categoryBag arguments.

·         signaturePresent: this is used with any find_xx API to restrict the result set to entities which either contain an XML Digital Signature element, or are contained in an entity which contains one.  The Signature element is retrieved using a get_xx API call and SHOULD be verified by the client.  A UDDI node may or may not verify the signature and therefore use of this find qualifier, or the presence of a Signature element SHOULD only be for the refinement of the result set from the find_xx API and SHOULD not be used as a verification mechanism by UDDI clients.

·         sortByNameAsc: causes the result set returned by a find_xx or get_xx inquiry APIs to be sorted on the name field in ascending order. This sort is applied prior to any truncation of result sets.  It is only applicable to queries that return a name element in the top-most detail level of the result set and if no conflicting sort qualifier is specified, this is the default sorting direction.  This findQualifier takes precedence over sortByDateAsc and sortByDateDesc qualifiers, but if a sortByDateXxx findQualifier is used without a sortByNameXxx qualifier, sorting is performed based on date with or without regard to name.

·         sortByNameDesc: causes the result set returned by a find_xx or get_xx inquiry call to be sorted on the name field in descending order.  This sort is applied prior to any truncation of result sets.  It is only applicable to queries that return a name element in the top-most detail level of the result set.  This is the reverse of the default sorting direction.  This findQualifier takes precedence over sortByDateAsc and sortByDateDesc qualifiers but if a sortByDateXxx findQualifier is used without a sortByNameXxx qualifier, sorting is performed based on date with or without regard to name.

·         sortByDateAsc: causes the result set returned by a find_xx or get_xx inquiry call to be sorted based on the most recent date when each entity, or any entities they contain, were last updated, in ascending chronological order (oldest are returned first).  When names are included in the result set returned, this find qualifier may also be used in conjunction with either the sortByNameAsc or sortByNameDesc findQualifiers.  When so combined, the date-based sort is secondary to the name-based sort (results are sorted within name by date, oldest to newest).

·         sortByDateDesc: causes the result set returned by a find_xx or get_xx inquiry call to be sorted based on the most recent date when each entity, or any entities they contain, were last updated, in descending chronological order (most recently changed are returned first. When names are included in the result set returned, this find qualifier may also be used in conjunction with either the sortByNameAsc or sortByNameDesc find qualifiers.  When so combined, the date-based sort is secondary to the name-based sort (results are sorted within name by date, newest to oldest).

·         suppressProjectedServices: signifies that service projections MUST NOT be returned by the find_service or find_business APIs with which this findQualifier is associated.  This findQualifier is automatically enabled by default whenever find_service is used without a businessKey.

·         UTS-10:  this is used to cause sorting of results based on the Unicode Collation Algorithm on elements normalized according to Unicode Normalization Form C.  When this qualifier is referenced, a sort is performed according to the Unicode Collation Element Table in conjunction with the Unicode Collation Algorithm on the name field, normalized using Unicode Normalization Form C.  Support of this findQualifier by nodes is OPTIONAL.

At this time, these are the only UDDI find qualifiers defined.  UDDI registries and individual nodes may define more find qualifier values than these – but all nodes and fully compatible software MUST support the above qualifiers, except where indicated otherwise.

5.1.4.4 Sorting Details

Sorting behavior of results returned as part of a UDDI inquiry is controlled by the following sort order find qualifiers: sortByDateAsc, sortByDateDesc, sortByNameAsc, sortByNameDesc, caseInsensitiveSort, binarySort and UTS-10.  These find qualifiers specify four aspects of sorting behavior as shown in Table 2: Find Qualifier Sorting Behaviors below.  For information on which find qualifiers are mutually exclusive, see Section 5.1.4.1 Invalid Find Qualifier Combinations.  Not all aspects of sorting are controlled through use of a single sort order find qualifier.  In order to control any combination of aspects of sorting behavior, multiple sort order find qualifiers can be specified.  For example, specifying sortByNameDesc and UTS-10 causes sorting of the result set on the name element according to the Unicode Technical Standard (UTS) #10 Collation Sequence, but in descending order.


 

Table 2: Find Qualifier Sorting Behaviors

Find Qualifier

Field being sorted

Direction of sort

Indicates Collation sequence

Controls Case Sensitivity

sortByNameAsc

Name

Asc

 

 

sortByNameDesc

Name

Desc

 

 

caseInsensitiveSort

 

 

 

caseSensitiveSort

 

 

 

binarySort

 

 

 

UTS-10

 

 

 

sortByDateAsc

Date

Asc

 

 

sortByDateDesc

Date

Desc

 

 

 

The default sort order aspects are to perform a case sensitive sort on the primary name element (where present), or the last change date (when a name is not present), in ascending order, using the collation sequence as determined by node policy.  Nodes MAY choose to perform a secondary date or name-based sort of duplicate entries in each of these cases.  If a name-based findQualifier is specified without a date-based sort, then nodes MAY perform a secondary date-based sort of duplicate entries. Similarly, when a date-based sort findQualifier is specified without a name-based sort, nodes MAY perform a secondary name-based sort of duplicate entries (where applicable).

Comparison and sorting is performed based on a canonicalized representation.  Specifying an unsupported sort order will result in the error E_unsupported.   For more on canonicalization, refer to Section 4.6 XML Normalization and Canonicalization.

Different sorting behavior can be obtained through the use of different sort orders, which are represented by their corresponding tModels.  The use of alternative collation sequences is achieved by referencing the corresponding tModelKey as the findQualifier argument supplied in the search.  Support for sorting based tModels describing any collation sequences other than binary by a node is OPTIONAL.

When a result set is being sorted by name only, then by default the first name stored for the businessEntity is the one against which sorting is performed.  Nodes that offer language-specific sort collation sequences MAY sort based the name element associated with the collation language.

5.1.5 Use of listDescription

Several of the inquiry APIs cause a list of results to be returned.   In such cases, an element called listDescription MAY also be returned:

Where:

·         includeCount: is the number of list items returned for the particular response

·         actualCount: is the number of all available matches at the time this particular query was made

·         listHead: is an index (with origin of 1) which indicates the index position within all available matches of the first element of the returned result set after any sorting has been applied.

When a listDescription is returned as part of the result set, it includes a listHead value that indicates the index position of the first result in the set relative to the beginning of the list of all matches for the query.  The query can specify that the result set returned should start with a particular element in the list of all matches for the query by including a listHead attribute on the query (find_xx API). The maximum number of results included in response to a query may be determined by the maxRows attribute of the query (find_xx API) or by the node’s policy. The listDescription on the response is useful when the node determines that the size of the resultant list is too large to be returned or when the maxRows and listHead values specified by the client do not allow all of the results to be returned in response to a single query.

For example, a query with a maxRows attribute set to 10 could be issued to a node where 18 results match the query.  The response to this query should contain items 1 through 10 and the listDescription would have an actualCount value of 18, a listHead value of 1 and an includeCount value of 10. If the data matching the query does not change and the query is sent again to the node with a listHead attribute value of 11, the result set should contain items 11-18 and the listDescription would have an actualCount value of 18, a listHead value of 11 and an includeCount value of 8.  If the listHead value is less than 1, a value of 1 will be used to produce the result.  If the listHead value exceeds the total number of results provided, an empty result set will be returned.

listDescription is not a true “cursoring” feature.  Since both the registry content and the associated result set can change between queries, supplying a particular value for listHead on subsequent queries may result in either duplicate reporting of an element which was returned as part of the original query, or a failure to report on an element.

The results of using a find_xx API will include a listDescription only if the resultant list is greater than what a node implementation can return in a single group.  For example, if the result set contains 20 items and all 20 are returned at once, then the listDescription element is allowable, but not required.  If the result set is 1000 and only 500 items can be returned at once, then a listDescription is required (if the truncated attribute is not used).

5.1.6 About wildcards

The default behavior of UDDI with respect to matching is “exact match”. No wildcard behavior is assumed.  Many UDDI inquiry APIs take the arguments “name,” “keyName,” and “keyValue” whose values are of type string.  All such arguments may be specified using a wildcard character to obtain an “approximate match”.   In order to obtain wildcard searching behavior, the findQualifier tModel uddi-org:approximateMatch:SQL99 (whose tModelKey is uddi:uddi.org:findqualifier:approximatematch), or its short name “approximateMatch” MUST be specified.

Wildcards, when they are allowed, may occur at any position in the string of characters that constitutes the argument value and may occur more than once.  Wildcards are denoted with a percent sign (%) to indicate any value for any number of characters and an underscore (_) to indicate any value for a single character. The backslash character (\) is used as an escape character for the percent sign, underscore and backslash characters.  Use of the “exactMatch” findQualifier will cause wildcard characters to be interpreted literally, and as such should not also be combined with the escape character.  Detailed rules for interpretation are defined by the above tModel for approximate matching.  Examples of the use of wildcards may be found in Appendix G Wildcards.

5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups

When determining matching behavior in searches involving keyedReferences in categoryBags and identifierBags, a match occurs if and only if:

1.       The tModelKeys refer to the same tModel.  This key MUST be specified and MUST NOT be empty.

2.       The keyValues match (an exact match is the default, but the matching behavior is modified appropriately if  the caseInsensitiveMatch, diacriticInsensitiveMatch or approximateMatch findQualifiers are used); and

3.       If the tModelKey involved is “uddi:uddi-org:general_keywords”, the keyName must match (wildcard matching rules apply if the approximateMatch findQualifier is used).  Omitted keyNames are treated as empty keyNames. Otherwise, keyNames are not significant unless so indicated in the individual API sections below.  

A given keyedReferenceGroup “X” (e.g., within a given categoryBag) matches a keyedReferenceGroup “Y” in the registry if and only if the tModelKey assigned to the keyedReferenceGroup X matches the tModelKey assigned to the keyedReferenceGroup Y and the set of keyedReferences in “X” are a subset of the set of keyedReferences in “Y.”  The order of individual keyedReferences within a keyedReferenceGroup is not important. Matching rules for the individual contained keyedReference elements are the same as above.

For additional information and examples, refer to Appendix E Using Identifiers and Appendix F Using Categorization.

5.1.8 Inquiry API functions

The APIs in this section represent inquiries that can be used to retrieve data from a UDDI registry.  These calls all behave synchronously and are suitable for being exposed via HTTP-POST.  The calls constituting the UDDI inquiry API are:

·         find_binding: Used to locate bindings within or across one or more registered businessServices.  Returns a bindingDetail structure.  See Section 5.1.9 find_binding.

·         find_business: Used to locate information about one or more businesses.  Returns a businessList structure. See Section 5.1.10 find_business.

·         find_relatedBusinesses: Used to locate information about businessEntity registrations that are related to a specific business entity whose key is passed in the inquiry.  See Section 5.1.11 find_relatedBusinesses.

·         find_service: Used to locate specific services within registered business entities.  Returns a serviceList structure.  See Section 5.1.12 find_service.

·         find_tModel: Used to locate one or more tModel information structures.  Returns a tModelList structure.  See Section 5.1.13 find_tModel.

·         get_bindingDetail: Used to get bindingTemplate information suitable for making service requests.  Returns a bindingDetail structure.  See Section 5.1.14 get_bindingDetail.

·         get_businessDetail: Used to get the businessEntity information for one or more businesses or organizations.  Returns a businessDetail structure.  See Section 5.1.15 get_businessDetail.

·         get_operationalInfo:  Used to retrieve operational information pertaining to one or more entities in the registry.  Returns an operationalInfos structure.  See Section 5.1.16 get_operationalInfo.

·         get_serviceDetail: Used to get full details for a given set of registered businessService data.  Returns a serviceDetail structure.  See Section 5.1.16 get_serviceDetail.

·         get_tModelDetail: Used to get full details for a given set of registered tModel data.  Returns a tModelDetail structure.  See Section 5.1.18 get_tModelDetail.

Several of the find_xx APIs (find_binding, find_business and find_service) support nested queries, where one or more of the arguments to these APIs can itself be another (inner) query, the results of which are used to filter the overall results of the primary (outer) query along with the other criterions supplied.  Any findQualifier arguments used only apply directly to the part of the query (outer or inner) for which they are supplied.  They do not propagate inward or outward.

5.1.9 find_binding

The find_binding API is used to find UDDI bindingTemplate elements. The find_binding API call returns a bindingDetail that contains zero or more bindingTemplate structures matching the criteria specified in the argument list.

5.1.9.1 Syntax:

 


 

Attributes

Name  

Use  

maxRows  

optional  

serviceKey  

optional  

listHead  

optional  

 

5.1.9.2 Arguments:

·         authInfo:  This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can perform an inquiry typically require authInfo for this call.

·         categoryBag:  This optional argument is a list of category references in the form of keyedReference elements and keyedReferenceGroup structures.  When used, the returned bindingDetail for this API will contain elements matching all of the categories passed (logical AND by default).   Specifying the appropriate findQualifiers can override this behavior.  Matching rules for each can be found in Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups.

·         findQualifiers: This optional collection of findQualifier elements  can be used to alter the default behavior of search functionality.  See Section 5.1.4 Find Qualifiers, for more information.

·         find_tModel: This argument provides an alternative or additional way of specifying tModelKeys that are to be used to find the bindingTemplate elements.  When specified, the find_tModel argument is treated as an embedded inquiry that is performed prior to searching for bindingTemplate elements.  The tModelKeys found are those whose tModels match the criteria contained within the find_tModel element. The tModelKeys found are added to the (possibly empty) collection specified by the tModelBag prior to finding qualified bindingTemplates.  Note that the authInfo argument to this embedded find_tModel argument is always ignored.  Large result set behavior involving the return of a listDescription does not apply within an embedded argument.  If the intermediate result set produced is too large, then the overall query will return E_resultSetTooLarge with an indication that the embedded query returned too many results.  If an E_unsupported error occurs as part of processing this embedded argument, it is propagated up to the containing (calling) API.

·         listHead:  This optional integer value is used to indicate which item SHOULD be returned as the head of the list.   The client may request a subset of the matching data by indicating which item in the resultant set constitutes the beginning of the returned data.  The use of the listDescription element is mutually exclusive to the use of the truncated attribute that simply indicates a truncated result list in the Inquiry APIs. See Section 5.1.5 Use of listDescription, for a detailed description of the listHead argument.

·         maxRows: This optional integer value allows the requesting program to limit the number of results returned. This argument can be used in conjunction with the listHead argument.

·         serviceKey: This optional uddi_key is used to specify a particular instance of a businessService element in the registered data.  Only bindings in the specific businessService data identified by the serviceKey passed are searched.  When it is either omitted or specified as empty (i.e., serviceKey=””), this indicates that all businessServices are to be searched for bindings that meet the other criteria supplied without regard to the service that provides them, and “projected” services are suppressed.

·         tModelBag: This collection of tModelKey elements represent in part or in whole the technical fingerprint of the bindingTemplate structures for which the search is being performed. At least one of either a tModelBag or a find_tModel argument SHOULD be supplied, unless a categoryBag based search is being used.

If a find_tModel argument is specified (see above), it is treated as an embedded inquiry.  The tModelKeys returned as a result of this embedded find_tModel argument are used as if they had been supplied in a tModelBag argument. Changing the order of the keys in the collection or specifying the same tModelKey more than once does not change the behavior of the find. 

By default, only bindingTemplates that have a technical fingerprint containing all of the supplied tModelKeys match (logical AND). Specifying appropriate findQualifiers can override this behavior so that bindingTemplates with a technical fingerprint containing any of the specified tModelKeys are returned (logical OR).

5.1.9.3 Returns:

This API call returns a bindingDetail upon success:

Attributes

Name  

Use  

truncated  

optional  

 

In the event that no matches were located for the specified criteria, the bindingDetail structure returned is empty (i.e., it contains no bindingTemplate data).  This signifies a zero match result. If no arguments are passed, a zero-match result set will be returned.

If the number of matches exceeds the value of the maxRows attribute, the result set MAY be truncated.  If this occurs, the response contains the attribute “truncated “ with the value “true.

As an alternative to the truncated attribute, a registry MAY return a listDescription element.   See Section 5.1.5 Use of listDescription, for additional information.

5.1.9.4 Caveats:

If an error occurs in processing this API, a dispositionReport element is returned to the caller within a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidCombination: signifies that conflicting findQualifiers have been specified.  The error text clearly identifies the findQualifiers that caused the problem.

·         E_invalidKeyPassed: signifies that the uddi_key value passed did not match with any known serviceKey or tModelKey values.  The error structure signifies the condition that occurred and the error text clearly calls out the offending key.

·         E_resultSetTooLarge: signifies that the particular node queried has deemed that the entire result set is too large to manage.  Therefore, the result set is not available.  Search criteria must be adjusted to obtain a result.

·         E_unsupported: signifies that one of the findQualifier values passed was invalid.  The invalid qualifier will be indicated clearly in text.

5.1.10 find_business

The find_business API is used to find UDDI businessEntity elements. The find_business API call returns a businessList that matches the criteria specified in the arguments.

5.1.10.1 Syntax:

Attributes

Name  

Use  

maxRows  

optional  

listHead  

optional  

 

5.1.10.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.   Registries that wish to restrict who can perform an inquiry in them typically require authInfo for this call.

·         categoryBag: This is a list of category references in the form of keyedReference elements and keyedReferenceGroup structures.  The returned businessList contains businessInfo elements matching all of the categories passed (logical AND by default).   Specifying the appropriate findQualifiers can override this behavior.  Matching rules for each can be found in Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups.

·         discoveryURLs: This is a list of discoveryURL structures to be matched against the discoveryURL data associated with registered businessEntity information.  To search for URL without regard to useType attribute values, omit the useType attribute or pass it as an empty attribute.  If useType values are included, the match occurs only on registered information that matches both the useType and URL value.  The returned businessList contains businessInfo structures matching any of the URL's passed (logical OR).

·         identifierBag: This is a list of business identifier references in the form of keyedReference elements.  The returned businessList contains businessInfo structures matching any of the identifiers passed (logical OR by default). Specifying the appropriate findQualifiers can override this behavior.  Matching rules can be found in Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups.

·         findQualifiers: This collection of findQualifier elements  can be used to alter the default behavior of search functionality.  See the Section 5.1.4 Find Qualifiers, for more information.

·         find_relatedBusinesses:  This argument is an embedded inquiry and limits the search results to those businesses that are related to a specified business in a specified way.  The result is comprised of an intersection of the businesses located with this embedded inquiry and the businesses discovered using the remaining inquiry criteria.  The standard syntax and arguments for find_relatedBusinesses apply here.  Note that the authInfo argument to this embedded find_relatedBusinesses argument is always ignored. Large result set behavior involving the return of a listDescription does not apply within an embedded argument.  If the intermediate result set produced is too large, then the overall query will return E_resultSetTooLarge with an indication that the embedded query returned too many results.  If an E_unsupported error occurs as part of processing this embedded argument, it is propagated up to the containing (calling) API.  See Section 5.1.11 find_relatedBusinesses, for further information.

·         find_tModel: This argument provides an alternative or additional way of specifying tModelKeys that are used to find businesses which have service bindings with specific technical fingerprints as described above for the tModelBag element.  When specified, the find_tModel argument is treated as an embedded inquiry that is performed prior to searching for businesses.  The tModelKeys found are those whose tModels match the criteria contained within the find_tModel element. The tModelKeys found are added to the (possibly empty) collection specified by the tModelBag prior to finding qualified businesses.  Note that the authInfo argument to this embedded find_tModel argument is always ignored.  Large result set behavior involving the return of a listDescription does not apply within an embedded argument.  If the intermediate result set produced is too large, then the overall query will return E_resultSetTooLarge with an indication that the embedded query returned too many results.  If an E_unsupported error occurs as part of processing this embedded argument, it is propagated up to the containing (calling) API.

·         listHead:  This optional integer value is used to indicate which item SHOULD be returned as the head of the list.   The client may request a subset of the matching data by indicating which item in the resultant set constitutes the beginning of the returned data.  The use of the listDescription element is mutually exclusive to the use of the truncated attribute that simply indicates a truncated result list in the Inquiry APIs. See Section 5.1.5 Use of listDescription, for a detailed description of the listHead argument.

·         maxRows: This optional integer value allows the requesting program to limit the number of results returned. This argument can be used in conjunction with the listHead argument.

·         name: This optional collection of string values represents one or more names potentially qualified with xml:lang attributes. Since “exactMatch” is the default behavior, the value supplied for the name argument must be an exact match.  If the “approximateMatch” findQualifier is used together with an appropriate wildcard character in the name, then any businessEntity matching this name with wildcards and the other criteria will be referenced in the results.  For more on wildcard matching, see Section 5.1.6 About Wildcards.   The businessList returned contains businessInfo structures for businesses whose name matches the value(s) passed (lexical-order match – i.e., leftmost in left-to-right languages).  If multiple name values are passed, the match occurs on a logical OR basis. Each name MAY be marked with an xml:lang adornment.  If a language markup is specified, the search results report a match only on those entries that match both the name value and language criteria. The match on language is a leftmost case-insensitive comparison of the characters supplied. This allows one to find all businesses whose name begins with an "A" and are expressed in any dialect of French, for example.  Values which can be passed in the language criteria adornment MUST obey the rules governing the xml:lang data type as defined in Section 3.3.2.3 name.

·         tModelBag:  Every Web service instance exposed by a registered businessEntity is represented in UDDI by a bindingTemplate contained within the businessEntity. Each bindingTemplate contains a collection of tModel references called its “technical fingerprint” that specifies its type.  The tModelBag argument is a collection of tModelKey elements specifying that the search results are to be limited to businesses that expose Web services with technical fingerprints that match.

If a find_tModel argument is specified (see above), it is treated as an embedded inquiry.  The tModelKeys returned as a result of this embedded find_tModel argument are used as if they had been supplied in a tModelBag argument. Changing the order of the keys in the collection or specifying the same tModelKey more than once does not change the behavior of the find. 

By default, only bindingTemplates that contain all of the tModelKeys in the technical fingerprint match (logical AND). Specifying appropriate findQualifiers can override this behavior so that bindingTemplates containing any of the specified tModelKeys match (logical OR).

5.1.10.3 Returns:

This API call returns a businessList on success.  This structure contains information about each matching business, including summaries of its businessServices: 

 

Attributes

Name  

Use  

truncated  

optional  

 

The businessList’s businessInfos structure and its businessInfo structures contain:

 

Attributes

Name  

Use  

businessKey  

required  

 

If a tModelBag or find_tModel was used in the search, the resulting serviceInfos structure reflects data only for the businessServices that actually contained a matching bindingTemplate.  For more information on serviceInfos, see Section 5.1.12.3 [find_service] Returns

Projected services are treated exactly the same as services that are naturally a part of businessEntities unless the suppressProjectedServices findQualifier is specified, in which case they are omitted from the serviceInfos structure returned and are not considered when determining which businesses match the inquiry criteria.  In the event that no matches are found for the specified criteria, a businessList structure containing no businessInfos structure is returned.

In the event that no matches were located for the specified criteria, the businessList structure returned is empty (i.e., it contains no businessInfos data).  This signifies a zero match result. If no arguments are passed, a zero-match result set will be returned.

In the event of a large number of matches, (as determined by the UDDI node), or if the number of matches exceeds the value of the maxRows attribute, the UDDI node MAY truncate the result set.  If this occurs, the businessList will contain the attribute “truncated with the value “true.

Second level elements (serviceInfos) within the returned businessList will be sorted in the order in which they were saved.

As an alternative to the truncated attribute, a registry MAY return a listDescription element.   See Section 5.1.5 Use of listDescription, for additional information.

5.1.10.4 Caveats:

If any error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidCombination: signifies that conflicting findQualifiers have been specified.  The error text clearly identifies the findQualifiers that caused the problem.

·         E_unsupported: signifies that one of the findQualifier values passed was invalid.  The findQualifier value that was not recognized will be clearly indicated in the error text.

·         E_invalidKeyPassed: signifies that a uddi_key or tModelKey value passed did not match with any known businessKey key or tModelKey values. The error structure signifies the condition that occurred and the error text clearly calls out the offending key.

·         E_resultSetTooLarge: signifies that the node deems that a result set from an inquiry is too large and does not honor requests to obtain the results for this inquiry, even using subsets.  The inquiry that triggered this error SHOULD be refined and re-issued.

5.1.11 find_relatedBusinesses

The find_relatedBusinesses API is used to find businessEntity elements, which have a completed relationship with the specified businessEntity that matches the criteria supplied.  The find_relatedBusinesses API call returns a relatedBusinessesList structure containing results that match the criteria specified in the arguments.  For additional information on the use of find_relatedBusinesses, refer to Appendix A: Relationships and Publisher Assertions, for more information on business relationships.

5.1.11.1 Syntax:

Attributes

Name  

Use  

maxRows  

optional  

listHead  

optional  

 

5.1.11.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can perform an inquiry in them typically require authInfo for this call.

·         businessKey:  This uddi_key is used to specify a particular businessEntity instance to use as the focal point of the search.  It MUST NOT be used in conjunction with the fromKey or toKey arguments.  It MUST refer to the businessKey of an existing businessEntity in the registry.  The result set reports businesses that are related in some way to the businessEntity whose key is specified.

·         findQualifiers: This collection of findQualifier elements  can be used to alter the default behavior of search functionality.  See Section 5.1.4 Find Qualifiers, for more information.

·         fromKey:  This uddi_key is used to specify a particular businessEntity instance which corresponds to the fromKey of a completed businessRelationship, for use as the focal point of the search. It MUST NOT be used in conjunction with the businessKey or toKey arguments. The result set reports businesses for which a relationship whose fromKey matches the key specified exists.

·         keyedReference: This is a single, optional keyedReference element that is used to specify a relationship type, such that only businesses that are related to the focal point in a specific way are included in the results. Specifying a keyedReference only affects whether a business is selected for inclusion in the results. If a business is selected, the results include the full set of completed relationships between it and the focal point. See Appendix A: Relationships and Publisher Assertions, for more information on specifying relationships. Matching rules for the use of keyedReferences are described in Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups, with the exception that keyNames MUST also match if they are non-empty in the search criteria for this API. Omitted keyNames are treated as empty keyNames.

·         listHead:  This optional integer value is used to indicate which item SHOULD be returned as the head of the list.   The client may request a subset of the matching data by indicating which item in the resultant set constitutes the beginning of the returned data.  The use of the listDescription element is mutually exclusive to the use of the truncated attribute that simply indicates a truncated result list in the Inquiry APIs. See Section 5.1.5 Use of listDescription, for a detailed description of the listHead argument.

·         maxRows: This optional integer value allows the requesting program to limit the number of results returned. This argument can be used in conjunction with the listHead argument.

·         toKey:  This uddi_key is used to specify a particular businessEntity instance which corresponds to the toKey of an existing businessRelationship, for use as the focal point of the search.  It MUST NOT be used in conjunction with the businessKey or fromKey arguments. The result set reports businesses for which a relationship whose toKey matches the key specified exists.

5.1.11.3 Returns:

This API call returns a relatedBusinessesList on success: 

Attributes

Name  

Use  

truncated  

optional  

 

Here, the businessKey returned with relatedBusinessesList is the same one provided with the find_relatedBusinesses API call.  The relatedBusinessInfos structure and the relatedBusinessInfo structures it contains each have this syntax:

 

The businessKey returned in each relatedBusinessInfo structure pertains to a business, which matched the search criteria supplied in the find_relatedBusinesses API call. The sharedRelationships structures then have this syntax:

Attributes

Name  

Use  

direction  

required  

 

The direction attribute identifies the relationship from the perspective of the business whose uddi_key was used to specify a particular businessEntity instance to use as a focal point for the find_relatedBusinesses call. This attribute is either expressed as “fromKey” or “toKey” depending on the relationship of the business to those returned by the call.

The example below depicts that Matt's Garage is related to the focal business (i.e. whose business key is uddi:ws-o-rama-cars.com:be47 and which appeared in the find_relatedBusinesses) by exactly one relationship -- the "subsidiary" parent-child relationship -- and that Matt's Garage is a subsidiary of the focal business. In such cases, the direction attribute is set to “toKey”.

<relatedBusinessesList operator=”uddi.someoperator” truncated=”false” xmlns=”urn:uddi-org:api_v3”>

<businessKey>uddi:ws-o-rama-cars.com:be47</businessKey>

   <relatedBusinessInfos>

       <relatedBusinessInfo>

          <businessKey>uddi:ws-o-rama-cars.com:mattsgarage:be3</businessKey>

          <name>Matt’s Garage</name>

          <description>Car services in …</description>

          <sharedRelationships direction=”toKey”>

              <keyedReference tModelKey=“uddi:uddi.org:relationships”

              keyName=”Subsidiary”

              keyValue=”parent-child”>

          …]

       […]

 

A publisherAssertion structure is only returned if it contains a signature and it has the following syntax:

In the event that no matches were located for the specified criteria, the relatedBusinessesList structure returned does not contain a relatedBusinessInfos element.  This signifies zero matches.

In the event of a large number of matches (as determined by the node), or if the number of matches exceeds the value of the maxRows attribute, the node MAY truncate the result set.  When this occurs, the relatedBusinessesList contains the attribute “truncated with the value of this attribute set to “true.

As an alternative to use of the truncated attribute, a registry MAY return a listDescription element.  See Section 5.1.5 Use of listDescription, for additional information.

5.1.11.4 Caveats:

If any error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidCombination: signifies that conflicting findQualifiers have been specified.  The error text clearly identifies the findQualifiers that caused the problem.

·         E_invalidKeyPassed: signifies that an uddi_key or tModelKey value passed did not match with any known businessKey key or tModelKey values.  The error structure signifies that the condition occurred and the error text clearly calls out the offending key.

·         E_unsupported: signifies that one of the findQualifier values passed was invalid.  The findQualifier value that was not recognized will be clearly indicated in the error text.

·         E_resultSetTooLarge: signifies that the node deems that a result set from an inquiry is too large and does not honor requests to obtain the results for this inquiry, even using subsets.  The inquiry that triggered this error SHOULD be refined and re-issued.


5.1.12 find_service

The find_service API is used to find UDDI businessService elements. The find_service API call returns a serviceList structure that matches the conditions specified in the arguments.

5.1.12.1 Syntax:

 

Attributes

Name  

Use  

maxRows  

optional  

businessKey  

optional  

listHead  

optional  

 

5.1.12.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can perform an inquiry in them typically require authInfo for this call.

·         businessKey:  This optional uddi_key is used to specify a particular businessEntity instance to search.  When supplied, this argument is used to specify an existing businessEntity within which services should be found.  Projected services are included unless the “suppressProjectedServices” findQualifier is used.  If businessKey it is either omitted or specified as empty (i.e., businessKey=””), this indicates that all businessEntities are to be searched for services that meet the other criteria supplied without regard to the business that provides them and service projections does not apply.

·         categoryBag: This is a list of category references.  The returned serviceList contains serviceInfo structures matching all of the categories passed (logical AND by default).   Specifying the appropriate findQualifiers can override this behavior.  Matching rules for the use of keyedReferences and keyedReferenceGroups are described in Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups.

·         findQualifiers: This optional collection of findQualifier elements  can be used to alter the default behavior of search functionality.  See Section 5.1.4 Find Qualifiers, for more information.

·         find_tModel: This argument provides an alternative or additional way of specifying tModelKeys that are used to find services which have service bindings with specific technical fingerprints, as described above for the tModelBag element.  When specified, the find_tModel argument is treated as an embedded inquiry that is performed prior to searching for services. The tModelKeys found are those whose tModels match the criteria contained within the find_tModel element. The tModelKeys found are added to the (possibly empty) collection specified by the tModelBag prior to finding qualified services.  Note that the authInfo argument to this embedded find_tModel argument is always ignored.  Large result set behavior involving the return of a listDescription does not apply within an embedded argument.  If an E_unsupported error occurs as part of processing this embedded argument, it is propagated up to the containing (calling) API.

·         listHead:  This optional integer value is used to indicate which item SHOULD be returned as the head of the list.   The client may request a subset of the matching data by indicating which item in the resultant set constitutes the beginning of the returned data.  The use of the listDescription element is mutually exclusive to the use of the truncated attribute that simply indicates a truncated result list in the Inquiry APIs. See Section 5.1.5 Use of listDescription, for a detailed description of the listHead argument.

·         maxRows: This optional integer value allows the requesting program to limit the number of results returned. This argument can be used in conjunction with the listHead argument.

·         nameThis optional collection of string values represents one or more names potentially qualified with xml:lang attributes.  Since “exactMatch” is the default behavior, the value supplied for the name argument must be an exact match.  If the “approximateMatch” findQualifier is used together with an appropriate wildcard character in the name, then any businessService data contained in the specified businessEntity (or across all businesses if the businessKey is omitted or specified as empty) with matching name value will be returned. Matching occurs using wildcard matching rules. See Section 5.1.6 About Wildcards If multiple name values are passed, the match occurs on a logical OR basis within any names supplied.  Each name MAY be marked with an xml:lang adornment.  If a language markup is specified, the search results report a match only on those entries that match both the name value and language criteria. The match on language is a leftmost case-insensitive comparison of the characters supplied. This allows one to find all services whose name begins with an "A" and are expressed in any dialect of French, for example.  Values which can be passed in the language criteria adornment MUST obey the rules governing the xml:lang data type as defined in Section 3.3.2.3 name.

·         tModelBag: Every Web service instance is represented in UDDI by a bindingTemplate contained within some businessService. A bindingTemplate contains a collection of  tModel references called its “technical fingerprint” that specifies its type. The tModelBag argument is a collection of tModelKey values specifying that the search results are to be limited to businessServices containing bindingTemplates with technical fingerprints that match.

If a find_tModel argument is specified (see below), it is treated as an embedded inquiry.  The tModelKeys returned as a result of this embedded find_tModel argument are used as if they had been supplied in a tModelBag argument. Changing the order of the keys in the collection or specifying the same tModelKey more than once does not change the behavior of the find. 

By default, only bindingTemplates that contain all of the tModelKeys in the technical fingerprint match (logical AND). Specifying appropriate findQualifiers can override this behavior so that bindingTemplates containing any of the specified tModelKeys match (logical OR).

5.1.12.3 Returns:

This API call returns a serviceList on success: 

Attributes

Name  

Use  

truncated  

optional  

 

The serviceInfos and contained serviceInfo structures have the syntax:

Attributes

Name  

Use  

serviceKey  

required  

businessKey  

required  

 

In the event that no matches were located for the specified criteria, the serviceList structure returned does not contain a serviceInfos element.  This signifies zero matches.  If no search arguments (including businessKey) are passed, a zero-match result set is returned. If only the businessKey search argument is passed, the entire set of services for the business is returned. The named arguments are all optional, and with the exception of name, may appear at most once. When more than one distinct named argument is passed, matching services are those which match on all of the criteria.

When a businessKey is supplied, the resulting serviceList contains only services that are associated with the designated business.  Service projections are included in this list unless explicitly excluded using the suppressProjectedServices find Qualifier.  When the businessKey is omitted or specified as empty (i.e., businessKey=””), all services that meet the other criteria are returned in the serviceList, without regard to the business which own them.  Service projections are not returned when a businessKey is omitted or left empty because they are exact duplicates of the services being projected upon.

Since a serviceInfo structure can represent a projection to a deleted businessService, the name element within the serviceInfo structure is optional (see Section 5.2.16 save_business on deleting projected services).

In the event of a large number of matches (as determined by the node), or if the number of matches exceeds the value of the maxRows attribute, the result set MAY be truncated.  When this occurs, the serviceList contains the attribute “truncated” with the value of this attribute set to “true”.

As an alternative to the truncated attribute, a registry MAY return a listDescription element. See Section 5.1.5 Use of listDescription for additional information.

5.1.12.4 Caveats:

If any error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault. In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidCombination: signifies that conflicting findQualifiers have been specified.  The error text clearly identifies the findQualifiers that caused the problem.

·         E_invalidKeyPassed: signifies that the uddi_key value passed did not match with any known businessKey key or tModelKey values.  The error structure signifies the condition that occurred and the error text clearly calls out the offending key.

·         E_unsupported: signifies that one of the findQualifier values passed was invalid.  The findQualifier value that was not recognized will be clearly indicated in the error text.

·         E_resultSetTooLarge: signifies that the node deems that a result set from an inquiry is too large and does not honor requests to obtain the results for this inquiry, even using subsets.  The inquiry that triggered this error SHOULD be refined and re-issued.

5.1.13 find_tModel

The find_tModel API is used to find UDDI tModel elements. The find_tModel API call returns a list of tModel entries that match a set of specific criteria. The response consists of summary information about registered tModel data returned in a tModelList structure.

5.1.13.1 Syntax:

Attributes

Name  

Use  

maxRows  

optional  

listHead  

optional  

 

5.1.13.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can perform an inquiry in them typically require authInfo for this call.

·         categoryBag: This is a list of category references.  The returned tModelList contains tModelInfo elements whose associated tModels match all of the categories passed (logical AND by default).   Specifying the appropriate findQualifiers can override this behavior.  Matching rules for the use of keyedReferences and keyedReferenceGroups are described in Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups.

·         findQualifiers: This collection of findQualifier elements is used to alter the default behavior of search functionality.  See Section 5.1.4 Find Qualifiers for more information.

·         identifierBag This is a list of identifier references in the form of keyedReference elements. The returned tModelList contains tModelInfo elements whose associated tModels match any of the identifiers passed (logical OR by default). Specifying the appropriate findQualifiers can override this behavior.  Matching rules are described in Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups.

·         listHead:  This optional integer value is used to indicate which item SHOULD be returned as the head of the list.   The client may request a subset of the matching data by indicating which item in the resultant set constitutes the beginning of the returned data.  The use of the listDescription element is mutually exclusive to the use of the truncated attribute that simply indicates a truncated result list in the Inquiry APIs. See Section 5.1.5 Use of listDescription, for a detailed description of the listHead argument.

·         maxRows: This optional integer value allows the requesting program to limit the number of results returned. This argument can be used in conjunction with the listHead argument.

·         nameThis string value  represents the name of the tModel elements to be found.  Since tModel data only has a single name, only a single name may be passed.  The argument must match exactly since “exactMatch” is the default behavior, but if the “approximateMatch” findQualifier is used together with the appropriate wildcard character, then matching is done according to wildcard rules. See Section 5.1.6 About Wildcards for additional information.  The name MAY be marked with an xml:lang adornment.  If a language markup is specified, the search results report a match only on those entries that match both the name value and language criteria. The match on language is a leftmost case-insensitive comparison of the characters supplied. This allows one to find all tModels whose name begins with an "A" and are expressed in any dialect of French, for example.  Values which can be passed in the language criteria adornment MUST obey the rules governing the xml:lang data type as defined in Section 3.3.2.3 name.

5.1.13.3 Returns:

This API call returns a tModelList structure on success:

Attributes

Name  

Use  

truncated  

optional  

 

The tModelInfos and contained tModelInfo structures have the syntax:

Attributes

Name  

Use  

tModelKey  

required  

 

In the event that no matches were located for the specified criteria, the tModelList returned will not contain a  tModelInfos element.  This signifies zero matches.  If no arguments are passed, a zero-match result is returned.

In the event of a large number of matches (as determined by the node), or if the number of matches exceeds the value of the maxRows attribute, the result set MAY be truncated.  When this occurs, the tModelList contains the attribute “truncated” with the value “true”.

As an alternative to the truncated attribute, a registry MAY return a listDescription element. See Section 5.1.5 Use of listDescription for additional information.

5.1.13.4 Caveats:

If any error occurs in processing this API call, a dispositionReport element is returned to the caller within a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidCombination: signifies that conflicting findQualifiers have been specified.  The error text clearly identifies the findQualifiers that caused the problem.

·         E_invalidKeyPassed: signifies that the uddi_key value passed did not match with any known  tModelKey values.  The error structure signifies the condition that occurred and the error text clearly calls out the offending key.

·         E_unsupported: signifies that one of the findQualifier values passed was invalid.  The invalid qualifier is clearly indicated in the error text.

·         E_resultSetTooLarge: signifies that the node deems that a result set from an inquiry is too large and does not honor requests to obtain the results for this inquiry, even using subsets.  The inquiry that triggered this error SHOULD be refined and re-issued.

5.1.14 get_bindingDetail

The get_bindingDetail API call returns the bindingTemplate structure corresponding to each of the bindingKey values specified.

5.1.14.1 Syntax:

 

5.1.14.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can perform an inquiry in them typically require authInfo for this call.

·         bindingKey: One or more uddi_key values that represent the UDDI assigned keys for specific instances of registered bindingTemplate data.

5.1.14.3 Returns:

This API call returns a bindingDetail on successful match of the specified bindingKey values.  See Section 5.1.9.3 [find_binding] Returns for information on this structure.  If multiple bindingKey values were passed, the results are returned in the same order as the keys passed.

If a large number of keys are passed, the node MAY truncate the result set.  When this occurs, the bindingDetail result contains the attribute “truncated with the value “true.

A node MUST NOT return a listDescription element as part of the bindingDetail in response to this API call.

5.1.14.4 Caveats:

If any error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: signifies that one of the uddi_key values passed did not match with any known bindingKey key values.  No partial results are returned – if any bindingKey values passed are not valid bindingKey values, this error is returned.  The error text clearly calls out the offending key.

5.1.15 get_businessDetail

The get_businessDetail API call returns the businessEntity structure corresponding to each of the businessKey values specified.

5.1.15.1 Syntax:

 

5.1.15.2 Arguments:

·         authInfo:  This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can perform an inquiry in them typically require authInfo for this call.

·         businessKey: One or more uddi_key values that represent specific instances of known businessEntity data.

5.1.15.3 Returns:

This API call returns a businessDetail on successful match of the specified businessKey values: 

Attributes

Name  

Use  

truncated  

optional  

 

If multiple businessKey values were passed, the results MUST be returned in the same order as the keys passed.

If a large number of keys are passed, a node MAY truncate the result set.  When this occurs, the businessDetail response contains the attribute “truncated “ with the value “true”.

businessEntity elements retrieved with get_businessDetail can contain service projections. Such projected services appear in full in the businessEntity in which they occur. Projected services can be distinguished from the services that are naturally contained in the businessEntity in which they appear by their businessKey. Services naturally contained in the businessEntity have the businessKey of the businessEntity in which they appear. Projected services have the businessKey of the businessEntity of which they are a natural part.

5.1.15.4 Caveats:

If any error occurs in processing this API call, a dispositionReport element is returned to the caller within a SOAP Fault.   In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: signifies that one of the uddi_key values passed did not match with any known businessKey values.  No partial results are returned – if any businessKey values passed are not valid, this error is returned.  The error text clearly calls out the offending key.

5.1.16 get_operationalInfo

The get_operationalnfo API call is used to retrieve entity level operational information (such as the date and time that the data structure was created and last modified, the identifier of the UDDI node at which the entity was published and the identity of the publisher) pertaining to one or more entities. The get_operationalInfo API call returns an operationalInfos structure corresponding to each of the entityKey values specified.

5.1.16.1 Syntax:

5.1.16.2 Arguments:

·         authInfo:  This optional argument is an element that contains an authentication token.   Registries that wish to restrict who can perform an inquiry in them typically require authInfo for this call.

·         entityKey: One or more uddi_key values that represent businessEntity, businessService, bindingTemplate or tModelKeys.

5.1.16.3 Returns:

This API returns an operationalInfos structure that contains an operationalInfo element for each entity requested by the inquirer.

The operationalInfos structure has the form:

Attributes

Name  

Use  

truncated  

optional  

 

For information on the operationalInfo structure, see Section 3.8, operationalInfo Structure.

5.1.16.4 Caveats:

If any error occurs in processing this API call, a dispositionReport element is returned to the caller within a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: signifies that one of the uddi_key values passed did not match with any known entityKey values.  No partial results are returned – if any entityKey values passed are not valid, this error is returned.  The error text clearly calls out the offending key(s).

5.1.17 get_serviceDetail

The get_serviceDetail API call returns the businessService structure corresponding to each of the serviceKey values specified.

5.1.17.1 Syntax:

5.1.17.2 Arguments:

·         authInfo:  This optional argument is an element that contains an authentication token.   Registries that wish to restrict who can perform an inquiry in them typically require authInfo for this call.

·         serviceKey: One or more uddi_key values that represent UDDI assigned serviceKey values of specific instances of known businessService data.

5.1.17.3 Returns:

This API call returns a serviceDetail on successful match of the specified serviceKey values.

Attributes

Name  

Use  

truncated  

optional  

 

If multiple serviceKey values were passed, the results will be returned in the same order as the keys passed.

If a large number of keys are passed, a node MAY truncate the result set.  When this occurs, the response contains the attribute “truncated” with the value “true”.

5.1.17.4 Caveats:

If any error occurs in processing this API call, a dispositionReport element is returned to the caller within a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: signifies that one of the uddi_key values passed did not match with any known serviceKey values.  No partial results are returned – if any serviceKey values passed are not valid, this error is returned.  The error text clearly calls out the offending key.

5.1.18 get_tModelDetail

The get_tModelDetail API call returns the tModel structure, corresponding to each of the tModelKey values specified.

5.1.18.1 Syntax:

5.1.18.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can perform an inquiry in them typically require authInfo for this call.

·         tModelKey: One or more uddi_key values that represent UDDI assigned tModelKey values of specific instances of known tModel data.

5.1.18.3 Returns:

This API call returns a tModelDetail on successful match of the specified tModelKey values.

Attributes

Name  

Use  

truncated  

optional  

 

If multiple tModelKey values were passed, the results are returned in the same order as the keys passed.

If a large number of keys are passed, a node MAY truncate the result set.  When this occurs, the response contains the attribute “truncated” with the value of “true”.


 

5.1.18.4 Caveats:

If any error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: signifies that one of the uddi_key values passed did not match with any known tModelKey values.  No partial results are returned – if any tModelKey values passed are not valid, this error is returned.  The error text clearly calls out the offending key.


 

5.2 Publication API Set

The API calls in this section are used to publish and update information contained in a UDDI registry.  According to the policy of the UDDI registry, a publisher selects a UDDI node where it will publish the information. 

API calls in this section MUST all be implemented as synchronous and “atomic” from the point of view of the caller. That is, each call MUST either succeed completely or fail completely. Partial results MUST NOT be returned.

5.2.1 Publishing entities with node assigned keys

When a publisher does not provide keys for new entities, the UDDI node will assign keys in accordance with registry policy. Node-assigned keys MUST use keys that conform to the grammar in Section 4.4 About uddiKeys.

5.2.2 Publishing entities with publisher-assigned keys

The registry keying policy MAY allow an entity’s key to be proposed by the publisher. If the publisher does not propose a key for an entity, the registry MUST assign one.

Since entity keys MUST be unique in a registry without regard to the type of entity and since registries MUST define to impose policies concerning which publishers may publish which keys, publisher-assigned keys are subject to rules that UDDI registries enforce. Behavior that ensures uniqueness across entity types (businessEntity, businessService, bindingTemplate, tModel and subscription) is REQUIRED for all registries. In this section we discuss the behavior of registries that use the recommended “uddi:” key structure. This behavior provides uniqueness and promotes interoperability among registries, while allowing various registry-specific policies to be built. Practical guidance for the use of this facility may be found in Section 9.4.2 General Keying Policy and Section 9.4.3 Policy Abstractions for the UDDI keying scheme.

5.2.2.1 Key generator keys and their partitions

To ensure that publisher-generated keys do not conflict with one another, registries assign the authority to generate keys to publishers in the following manner:

1.       The conceptual space of uddiKeys is divided into non-overlapping, hierarchically arranged partitions, each of which can be associated with a publisher.

2.       Only the publisher associated with a particular partition is given the authority to assign keys within the partition.

3.       The publisher with authority for a given partition may designate any publisher it chooses for any partition directly below the partition it manages, provided it has not already designated a publisher to that partition.

4.       The publisher with authority for a partition may transfer its authority to another publisher.

5.       Initially, the registry itself has authority for the root partition of the hierarchy.

The specific mechanisms that enforce these rules are explained below.

Each node of a registry is a generator of keys.  This is required to enable the node to generate keys not provided by publishers. In addition, the policies of a registry MAY allow individual publishers to obtain the authority to be generators of keys for specific partitions within the space of uddiKeys. Publishers obtain this authority by owning a particular tModel called a key generator tModel.  The key generator tModel contains a key generator key, and it specifies the partition for which the publisher may assign keys. 

The subset of derivedKeys called key generator keys consists of all the keys of the form:

keyGeneratorKey           =          uddiKey ":keygenerator"

As described in Section 4.4.1, a derivedKey is one that is formed from another key by appending a non-empty, colon-prefixed string to another uddiKey.  A derivedKey is said to be "based on" this uddiKey. With this in mind, the complete partition of a given keyGeneratorKey is the set of keys consisting of:

 

1.       The set of derivedKeys based on the same uddiKey that the keyGeneratorKey is based upon.

2.       The set of keyGeneratorKeys based on a key that is in the partition.

3.       The domainKey, if the keyGeneratorKey is based upon that domainKey.

 

Note that the partition's keyGeneratorKey itself is exluded from the partition.

A rootKeyGeneratorKey is a keyGeneratorKey that is not based on a derivedKey. That is:

rootKeyGeneratorKey    =          (uuidKey / domainKey) ":keygenerator"

 

5.2.2.1.1 Examples

Based on the rules above, it is possible to construct the keyGeneratorKey for any key by manipulating the string representation of the key. To illustrate, suppose the key is x, then the following pseudo-code will determine the keyGeneratoryKey:

If x is a keyGeneratorKey, and y is that key minus the “:keygenerator” suffix,

then if y is a domainKey

   then x is a top-level keyGenerator, and has no keyGeneratorKey (1.a)

   else y is a derivedKey, based on z,

       and x’s keyGeneratorKey is z:keyGenerator (1.b)

else

If x is a domainKey

then x’s keyGeneratorkey is x:keyGenerator (2)
else x is based on a key y, and x’s keyGenerator is y:keyGenerator (3)

 

Using this pseudo-code illustration, the following table provides examples of legal URI’s and their associated key generators for each of the four cases noted:

Key

keyGeneratorKey

Case in pseudo-code

uddi:tempuri.com

uddi:tempuri.com:keygenerator

2

uddi:tempuri.com:keygenerator

<none>

1.a

uddi:tempuri.com:xxx:keygenerator

uddi:tempuri.com:keygenerator

1.b

uddi:tempuri.com:xxx

uddi:tempuri.com:keygenerator

3

uddi:tempuri.com:xxx:yyy

uddi:tempuri.com:xxx:keygenerator

3

 

The following keys do NOT belong to the partition of the key generator key “uddi:tempuri.com:keygenerator”.

 “uddi:tempuri.com:keygenerator”

The keyGeneratorKey does not belong to the partition it designates.

 

“uddi:tempuri.com:xxx:yyy”

This key belongs to the partition of the keyGeneratorKey “uddi:tempuri.com:xxx:keygenerator”, not this one.

“uddi:tempuri.com:keygenerator:zzz”

This key does not belong in any partition – it is an invalid key.

 

5.2.2.2 Behavior of publishers

To successfully publish a new entity with a proposed key, the publisher needs to own the key generator tModel for the partition in which the key lies. Typically, a publisher gets ownership by publishing the tModel in question, but publishers can also get ownership in other ways, for example by having another publisher transfer ownership.

Once a publisher owns a key generator tModel that publisher MAY publish new entities[19] and assign them keys within the key generator tModel’s partition. Publishers are responsible for managing the uniqueness of the keys in the partition they own. If a publisher fails to do so, and generates an already used key, a publish operation could inadvertently replace an entity previously published by that publisher.

If a publisher owns key generator tModels with the same key in multiple registries – for example one in the publisher’s private test registry and one in the UDDI Business Registry – that publisher MAY publish the entities with identical keys in those registries. This enables many interesting capabilities. For example, publishers may choose to develop their UDDI entities by publishing them into test registries and then, at appropriate times, “promote” them to the UDDI Business Registry.

5.2.2.3 Behavior of UDDI nodes

To ensure that publisher-assigned keys work correctly all UDDI implementations behave as follows.

5.2.2.3.1 “New” and “existing” entities defined

During a publish operation, the entity or entities being published are either “new” or “existing”. An existing entity is one that has a key that matches the key of an entity already in the registry. A new entity is one that does not. If a new entity has a key, this key is the key proposed for that entity by its publisher.

5.2.2.3.2 Behavior with respect to entities for which no key is proposed.

A UDDI node MUST generate and assign a key to each entity for which the publisher proposes no key. It may generate uuidKeys for use as the keys of new entities for which no key is proposed or it may generate keys in the partition of a key generator tModel it owns.

A registry whose nodes assign uddiKeys to new entities is called a root registry. The UDDI Business Registry is a root registry. A registry whose nodes gain ownership of their key generator tModels by publishing them in the UDDI Business Registry are affiliates of the UDDI Business Registry. See Section 1.5.5 Affiliations of Registries.

5.2.2.3.3 Behavior with respect to uuidKeys

A UDDI node SHOULD accept a uuidKey as the key for a new entity during a publish operation if the publisher is a trusted publisher of such keys, according to the policies of the registry. UDDI nodes MUST NOT allow other publishers to generate uuidKeys.

5.2.2.3.4 Behavior with respect to key generator keys

A UDDI node MUST NOT publish any non-tModel entity whose proposed key is a key generator key.  A tModel whose proposed key is a key generator key MUST include a category bag with a keyed reference with the tModelKey set to “uddi:uddi.org:categorization:types” and the keyValue set to “keyGenerator”.

5.2.2.3.5 Behavior with respect to root key generator keys

During a publish operation a UDDI node SHOULD accept a root key generator key as the key for a new tModel if it is proposed by a publisher authorized to publish the key, according to the policies of the registry. The policy MUST prevent more than one publisher from publishing tModels with the same root key generator key.

An appropriate policy for root and for affiliated registries is given in Chapter 9 Policy.

5.2.2.3.6 Behavior with respect to other proposed keys

A UDDI node SHOULD accept keys proposed for new entities during publishing operations if they meet both of the following criteria.

·         The proposed key lies in the partition of the key of an existing key generator tModel.

·         The same publisher who is proposing the new key owns the key generator tModel referred to in the previous bullet. [20]

5.2.2.4 Affiliations of registries

A set of registries may cooperate in managing a single multi-registry key space by designating one of the registries in the group to be the “root registry” and assigning it to be the authority for the root partition. Other registries in the set are said to be affiliate registries.  See Section 1.5.5  Affiliations of Registries for more information

The UDDI Business Registry is a root registry. Its policies and procedures are designed to make it simple for any UDDI registry to be affiliated with it.

Designating new authorities is done by publishing key generator tModels in the root registry, in one or more of the registries affiliated with the root registry or both. The owner of a key generator tModel is the naming authority for the partition the tModel represents.

5.2.3 Special considerations for validated value sets

Several of the APIs defined in this section allow publishers to save category and identifier information in support of searches that use category and identifier system references.  The save_business, save_service, save_binding and save_tModel APIs allow designation of these value set references.  Categorization is specified using the element named categoryBag, which contains namespace-qualified references to categories and descriptions.  categoryBags can also contain groups of these references to categories and descriptions.  Identifiers are specified using the identifierBag element, which contains namespace-qualified references to identifiers and descriptions.

Similarly, the add_publisherAssertions and set_publisherAssertions APIs allow publisherAssertion elements to be saved.  These publisherAssertion elements contain a characterization of the relationship being established using a keyedReference element that refers to a relationship type system.

Identifier, category and relationship type systems taken together are referred to as “value sets.”  UDDI allows value sets to be checked or unchecked.  References to checked value sets that are registered in UDDI can be checked internally by the UDDI nodes where publishing takes place, or externally by a provider of a validation Web service.  The UDDI node can also choose to not support some or all checked value sets.

When a UDDI node encounters a reference to a checked value set in a keyedReference it will either ensure the reference is validated or fail the save.  Such references to supported checked value sets are verified for validity according to the validation algorithm defined for the value set and described by its tModel.  When all checks succeed, the save is permitted.  An E_unvalidatable error indicates the checked value set is supported but its validation algorithm is not available.  An E_unsupported indicates the checked value set is not supported by the node.  E_invalidValue or E_valueNotAllowed indicate one or more references failed validation.  When the checked value set is not supported, the value set’s validation algorithm is unavailable, or any of the references fail validation, the save operation MUST fail.

When the UDDI node supports a checked value set it may check the references itself, or consult a validation Web service.  For cached checked value sets, the UDDI node verifies that referenced keyValues are in the set of valid values for the value set.  The selection of an algorithm for verifying a checked value set is a matter of registry policy as detailed in Chapter 9 Policy.

A category group system is portrayed by a keyedRefererenceGroup element.  Each keyedReferenceGroup has a tModelKey that references the category group system, and a set of contained keyedReference elements that make up the actual group of categories.  Similar to references to checked value sets, validation is carried out for a keyedReferenceGroup if the referenced category group system is checked.  Such validation entails verification that the keyedReferenceGroup is valid according to the validation algorithm described by the tModel for the category group system.  Validation for a keyedReferenceGroup that references a cached checked category group system involves verification that the tModels referenced by the contained keyedReference elements are valid for the category group system.  The set of valid values for such a cacheable checked category group system is defined by the tModelKeys for the set of tModels that can participate in the group.

No validation is performed on references to unchecked value sets

5.2.4 Special considerations for the xml:lang attribute

During save_xx API calls, the name, description, address, and personName UDDI elements MAY be adorned with the xml:lang attribute to indicate the language in which their content is expressed. (See Chapter 3 UDDI Registry Data Structures.)  When an optional xml:lang attribute is omitted from an element, no xml:lang attribute will be saved for that element.

Name elements in UDDI core data structures are frequently the main targets for sorts during UDDI inquiries.  When a UDDI data structure has multiple names, sorting occurs on the first name.  Care should be taken to list the primary name first when the entity is saved to ensure the proper placement of the entity in a sorted result set.

Values which can be passed in the language supplied in a save_xx API call MUST obey the recommended rules and syntax governing the xml:lang data type as defined in Section 3.3.2.3 name.

5.2.5 Publisher API summary

The publishing API calls are:

·         add_publisherAssertions: Used to add relationship assertions to the existing set of assertions.  See Appendix A Relationships and Publisher Assertions.

·         delete_binding: Used to remove an existing bindingTemplate from the registry.

·         delete_business: Used to delete existing businessEntity information from the registry.

·         delete_publisherAssertions: Used to delete specific publisher assertions from the assertion collection controlled by a particular publisher.  Deleting assertions from the assertion collection affects the visibility of business relationships.  Deleting an assertion causes any relationships based on that assertion to become incomplete.

·         delete_service: Used to delete an existing businessService from the registry.

·         delete_tModel: Used to hide existing information about a tModel.  Any tModel hidden in this way is still usable for reference purposes and accessible via the get_tModelDetail API, but is hidden from find_tModel result sets.  There is no specified way to delete a tModel.

·         get_assertionStatusReport: Used to get a status report containing publisher assertions and status information.  This report is useful to help an administrator manage publisher assertions. Returns an assertionStatusReport that includes the status of all assertions made involving any businessEntity controlled by the requesting publisher.

·         get_publisherAssertions: Used to get a list of publisher assertions that are controlled by an individual publisher.  Returns a publisherAssertions structure containing all publisher assertions associated with a specific publisher.

·         get_registeredInfo: Used to request an abbreviated list of businesses and tModels currently managed by a given publisher.

·         save_binding: Used to register new bindingTemplate information or to update existing bindingTemplate information.  Use this to control information about technical capabilities exposed by a registered business.

·         save_business: Used to register new businessEntity information or update existing businessEntity information.  Use this to control the full set of information about the entire business, including its businessService and bindingTemplate structures.  This API has the broadest effect of all of the save_xx APIs.

·         save_service:  Used to register or update complete information about a businessService.

·         save_tModel:  Used to register or update information about a tModel.

·         set_publisherAssertions: Used to save the complete set of publisher assertions for an individual publisher.  Replaces any existing assertions, and causes any old assertions that are not reasserted to be removed from the registry.

 

 

5.2.6 add_publisherAssertions

The add_publisherAssertions API call causes one or more publisherAssertions to be added to an individual publisher’s assertion collection.  See Appendix A Relationships and Publisher Assertions describing relationships and the API get_publisherAssertions for more information on this collection.

5.2.6.1 Syntax:


 

5.2.6.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other method external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         publisherAssertion: This required repeating element holds the relationship assertions that are being added.  Relationship assertions consist of a reference to two businessEntity key values as designated by the fromKey and toKey elements, as well as a REQUIRED expression of directional relationship within the contained keyedReference element.  See Appendix A Relationships and PublisherAssertions on managing relationships. The fromKey, the toKey, and all three parts of the keyedReference – the tModelKey, the keyName, and the keyValue MUST be specified or the call will fail with the error E_fatalError. Empty (zero length) keyNames and keyValues are permitted.

5.2.6.3 Behavior:

The publisher must own the businessEntity referenced in the fromKey, the toKey, or both.  If both of the businessKey values passed within an assertion are owned by the publisher, then the assertion is automatically complete and the relationship described in the assertion is visible via the find_relatedBusinesses API.  To form a relationship when the publisher only owns one of the two keys passed, the assertion MUST be matched exactly by an assertion made by the publisher who owns the other business referenced. Assertions exactly match if and only if they:

1.       refer to the same businessEntity in their fromKeys;

2.       refer to the same businessEntity in their toKeys;

3.       refer to the same tModel in their tModelKeys;

4.       have identical keyNames; and

5.       have identical keyValues.

When a publisherAssertion being added references a checked relationship system using the tModelKey in the contained keyedReference, the reference MUST be checked for validity prior to completion of the add, or the node must return E_unsupported, indicating it does not support the referenced checked relationship system.  Validation of a relationship system reference entails verification that the reference is valid according to the validation algorithm defined for the relationship system and described by its tModel.  For cached checked relationship systems, the validation algorithm verifies that referenced keyValues are in the set of valid values for the relationship system.

5.2.6.4 Returns:

Upon successful completion, a dispositionReport structure is returned with a single success indicator.

5.2.6.5 Caveats:

If an error occurs in processing this API call, a dispositionReport structure MUST be returned to the caller in a SOAP Fault. See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: signifies that one of the uddiKey values passed did not match with any known businessKey or tModelKey values.  The key and element or attribute that caused the problem SHOULD be clearly indicated in the error text.

·         E_userMismatch: signifies that neither of the businessKey values passed in the embedded fromKey and toKey elements is owned by the publisher associated with the authentication token.  The error text SHOULD clearly indicate which assertion caused the error.


 

5.2.7 delete_binding

The delete_binding API call causes one or more instances of bindingTemplate data to be deleted from the UDDI registry.

5.2.7.1 Syntax:

 

5.2.7.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other method external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         bindingKey: One or more required uddiKey values that represent specific instances of known bindingTemplate data.

5.2.7.3 Returns:

Upon successful completion, a dispositionReport is returned with a single success indicator. Section 4.8 Success and Error Reporting.

5.2.7.4 Caveats:

If an error occurs in processing this API call, a dispositionReport structure MUST be returned to the caller in a SOAP Fault.  See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: Signifies that one of the uddiKey values passed did not match with any known bindingKey values or multiple instances of the same bindingKey values were passed.  No partial results are returned – if any bindingKey values passed are not valid, this error is returned.  The key that caused the problem SHOULD clearly be indicated in the error text.

·         E_userMismatch: Signifies that one or more of the bindingKey values passed refers to a bindingTemplate that is not owned by the individual publisher associated with the authentication token.


5.2.8 delete_business

The delete_business API call is used to remove one or more business registrations and all elements that correspond to the natural content of the corresponding businessEntity elements from a UDDI registry.

5.2.8.1 Syntax:

 

5.2.8.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         businessKey: One or more required uddiKey values that represent specific instances of known businessEntity data.

5.2.8.3 Behavior:

The UDDI registry MUST permanently remove all of the natural contents[21] of the passed businessEntity elements, including any currently nested businessService and bindingTemplate data, from the UDDI registry.

If there are service projections[22] that reference businessService elements deleted in this way, they are left untouched. Such “broken” service projections appear in their businessEntity as businessService elements containing the businessKey and serviceKey attributes as their only content. For this reason, it is a best practice to coordinate references to businessService data published under another businessEntity with the party who manages that data. 

All publisher assertions that reference the businessKey of the businessEntity being deleted in either the fromKey or toKey of the publisherAssertion MUST be automatically deleted.  A deleted business MUST not be returned in the find_relatedBusinesses API.

 

5.2.8.4 Returns:

Upon successful completion, a dispositionReport structure is returned with a single success indicator. See Section 4.8 Success and Error Reporting.

5.2.8.5 Caveats:

If an error occurs in processing this API call, a dispositionReport element MUST be returned to the caller within a SOAP Fault.  See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: Signifies that one of the uddiKey values passed did not match with any known businessKey values or multiple instances of the same businessKey values were passed. The key that caused the error SHOULD be clearly indicated in the error text.

·         E_userMismatch: Signifies that one or more of the businessKey values passed refers to data that is not owned by the individual publisher who is represented by the authentication token.

 


5.2.9 delete_publisherAssertions

The delete_publisherAssertions API call causes one or more publisherAssertion elements to be removed from a publisher’s assertion collection.  See Appendix A Relationships and Publisher Assertions and the API get_publisherAssertions for more information on this collection.

5.2.9.1 Syntax:

5.2.9.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         publisherAssertion: One or more required publisher assertion structures exactly matching an existing assertion in the publisher’s assertion collection. 

5.2.9.3 Behavior:

The UDDI registry scans the assertion collection associated with the publisher, and removes any assertions that exactly match all parts of each publisherAssertion passed.  Any assertions described that cannot be located result in an error.  The removal of assertions in this API causes the corresponding relationships to no longer be visible via the find_relatedBusinesses API.

5.2.9.4 Returns:

Upon successful completion, a dispositionReport structure is returned with a single success indicator. See Section 4.8 Success and Error Reporting.

5.2.9.5 Caveats:

If an error occurs in processing this API call, a dispositionReport structure MUST be returned to the caller in a SOAP Fault.  See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_assertionNotFound: Signifies that one of the assertion structures passed does not have any corresponding match in the publisher’s assertion collection or multiple instances of the same publisherAssertions elements were passed.  The assertion that caused the problem SHOULD be clearly indicated in the error text.


5.2.10 delete_service

The delete_service API call is used to remove one or more businessService elements from the UDDI registry and from its containing businessEntity parent.

5.2.10.1 Syntax:

5.2.10.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         serviceKey: One or more required uddiKey values that represent specific instances of known businessService data.

5.2.10.3 Returns:

Upon successful completion, a dispositionReport is returned with a single success indicator. See Section 4.8 Success and Error Reporting.

All contained bindingTemplate data MUST also be removed from the registry as a result of this call.

If a business service being deleted is the target of a business service projection associated with another businessEntity, the referencing businessService elements are left untouched.  Such “broken” service projections appear in their businessEntity and businessService elements containing the businessKey and serviceKey attributes as their only content.  For this reason, it is recommended that references to businessService data published under another businessEntity be coordinated with the party that manages that data. 

5.2.10.4 Caveats:

If an error occurs in processing this API call, a dispositionReport structure MUST be returned to the caller in a SOAP Fault.  See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: Signifies that one of the uddiKey values passed did not match with any known serviceKey values or multiple instances of the same serviceKey values were passed. The key causing the error SHOULD be clearly indicated in the error text.

·         E_userMismatch: Signifies that one or more of the serviceKey values passed refers to data that is not owned by the individual publisher who is represented by the authentication token.


 

5.2.11 delete_tModel

The delete_tModel API call is used to logically delete one or more tModel structures. Logical deletion hides the deleted tModels from find_tModel result sets but does not physically delete them. New references to deleted (hidden) tModels can be established by publishers that know their keys.  Deleting an already deleted tModel has no effect.

5.2.11.1 Syntax:

 


5.2.11.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         tModelKey: One or more required uddiKey values that represent specific instances of known tModel data.

5.2.11.3 Returns:

Upon successful completion, a dispositionReport structure is returned with a single success indicator. See Section 4.8 Success and Error Reporting.

If a tModel is hidden in this way it MUST not be physically deleted as a result of this call. Any tModels hidden in this way are still accessible, via the get_registeredInfo and get_tModelDetail APIs, but are omitted from any results returned by calls to find_tModel.  All other inquiry APIs may include references to tModelKeys of deleted tModelKeys, and UDDI data structures that reference these tModels are found and retrieved.

The purpose of the delete_tModel behavior is to ensure that the details associated with a hidden tModel are still available to anyone currently using the tModel.  A hidden tModel can be restored and made visible to search results by invoking the save_tModel API at a later time, passing the original data and the tModelKey value of the hidden tModel.

5.2.11.4 Caveats:

If an error occurs in processing this API call, a dispositionReport element MUST be returned to the caller within a SOAP Fault.  See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: Signifies that one of the uddiKey values passed did not match with any known tModelKey values or multiple instances of the same tModelKey values were passed. The invalid key references SHOULD be clearly indicated in the error text.

·         E_userMismatch: Signifies that one or more of the tModelKey values passed refers to data that is not owned by the individual publisher who is represented by the authentication token.

 


5.2.12 get_assertionStatusReport

The get_assertionStatusReport API call provides administrative support for determining the status of current and outstanding publisher assertions that involve any of the business registrations managed by the individual publisher.  Using this API, a publisher can see the status of assertions that they have made, as well as see assertions that others have made that involve businessEntity structures controlled by the requesting publisher.   See Appendix A Relationships and Publisher Assertions for more information.

5.2.12.1 Syntax:


5.2.12.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         completionStatus: This optional argument lets the publisher restrict the result set to only those relationships that have the specified status value.  Assertion status is a calculated result based on the sum total of assertions made by the individuals that control specific business registrations.  When no completionStatus element is provided, all assertions involving the businesses that the publisher owns are retrieved, without regard to the completeness of the relationship.  completionStatus MUST contain one of the following values

o        status:complete: Passing this value causes only the publisher assertions that are complete to be returned.  Each businessEntity listed in assertions that are complete has a visible relationship that directly reflects the data in a complete assertion (as described in the find_relatedBusinesses API).

o        status:toKey_incomplete: Passing this value causes only those publisher assertions where the party who controls the businessEntity referenced by the toKey value in an assertion, has not made a matching assertion, to be listed.

o        status:fromKey_incomplete: Passing this value causes only those publisher assertions where the party who controls the businessEntity referenced by the fromKey value in an assertion, has not made a matching assertion, to be listed.


 

5.2.12.3 Returns:

Upon successful completion, an assertionStatusReport structure is returned containing zero or more assertionStatusItem structures.

The assertionStatusReport has the form:

The assertionStatusReport reports all complete and incomplete assertions and serves an administrative use for determining if there are any outstanding, incomplete assertions pertaining to relationships involving businesses with which the publisher is associated.

Since the publisher who was authenticated by the get_assertionStatusReport API may own several businesses, the assertionStatusReport structure shows the assertions made for all businesses owned by the publisher.

The assertion status report is composed of a set of assertionStatusItem elements that describe the assertions in which the publisher’s businesses participate.  The assertionStatusItem element has the form:

 

The assertionStatusItem structure has the following attribute:

Name 

Use 

completionStatus 

required

 

While the elements fromKey, toKey and keyedReference together identify the assertion on whose status a report is being provided, the keysOwned element designates those businessKeys the publisher manages.  The keysOwned element has the form:

An assertion is part of a reciprocal relationship only if the completionStatus attribute has a value “status:complete”. If completionStatus has a value “status:toKey_incomplete” or “status:fromKey_incomplete”, the party who controls the businessEntity referenced by the toKey or the fromKey has not yet made a matching assertion.

5.2.12.4 Caveats:

If an error occurs in processing this API call, a dispositionReport element MUST be returned to the caller within a SOAP Fault.  See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidCompletionStatus: Signifies that the completionStatus value passed is unrecognized.  The completion status that caused the problem SHOULD be clearly indicated in the error text.


 

5.2.13 get_publisherAssertions

The get_publisherAssertions API call is used to obtain the full set of publisher assertions that is associated with an individual publisher. It complements the get_registeredInfo API which returns information about businesses, services, bindings, and tModels managed by a publisher.

5.2.13.1 Syntax:


5.2.13.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

5.2.13.3 Returns:

This API call returns a publisherAssertions structure that contains a publisherAssertion element for each publisher assertion registered by the publisher.  When the registry distinguishes between publishers, this information is associated with the authentication information.  Only assertions made by the publisher are returned.  See get_assertionStatusReport and Appendix A Relationships and Publisher Assertions for more details.

The publisherAssertions structure has the form:

 

 

5.2.13.4 Caveats:

None, other than those common to all UDDI APIs. See Section 12.1 Common Error Codes.

 

 


 

5.2.14 get_registeredInfo

The get_registeredInfo API call is used to get an abbreviated list of all businessEntity and tModel data that are controlled by a publisher.  When the registry distinguishes between publishers, this is the individual associated with the credentials passed in the authInfo element. This returned information is intended, for example, for driving tools that display lists of registered information and then provide drill-down features. This is the recommended API to use after a network problem results in an unknown status of saved information.

 

5.2.14.1 Syntax:

 

Attributes

Name 

Use 

infoSelection

required

 

5.2.14.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         infoSelection: This required argument represents an enumerated choice that determines which tModels are returned.  “all” indicates all visible and hidden tModels owned by the publisher are to be returned (this is the default).  “visible” indicates only visible tModels owned by the publisher are to be returned.  “hidden” indicates only hidden (logically deleted) tModels owned by the publisher are to be returned.

5.2.14.3 Returns:

Upon successful completion, a registeredInfo structure MUST be returned, listing abbreviated business information in one or more businessInfo elements, and tModel information in one or more tModelInfo elements.  This API is useful for determining the full extent of registered business and tModel information owned by a single publisher in a single call.  This structure complements the get_publisherAssertions API call, which returns information about assertions owned by an individual publisher.

The registeredInfo structure has the form:

5.2.14.4 Caveats:

None, other than those common to all UDDI APIs. See Section 12.1 Common Error Codes.

 

5.2.15 save_binding

The save_binding API call is used to save or update a complete bindingTemplate element.  It can be used to add or update one or more bindingTemplate elements as well as the container/contained relationship that each bindingTemplate has with one or more existing businessService elements. Each bindingTemplate MAY be signed and MAY have publisher-assigned keys.

5.2.15.1 Syntax:


5.2.15.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         bindingTemplate: Required repeating element containing one or more complete bindingTemplate structures. To save a new bindingTemplate, a bindingTemplate element is passed with either an empty bindingKey attribute value, or with a publisher-assigned bindingKey. See Section 5.2.2.2 Behavior of Publishers.

5.2.15.3  Behavior

Each new bindingTemplate passed MUST contain a serviceKey value that corresponds to a registered businessService controlled by the same publisher. An existing binding template MAY contain a serviceKey value that corresponds to a registered businessService controlled by the same publisher.  The net effect of this call is to determine the containing parent businessService for each bindingTemplate affected by this call. If the same bindingTemplate (determined by matching bindingKey value) is listed more than once, any relationship to the containing businessService is determined by processing order, which is determined by the position of the bindingTemplate data in first to last order.

If the bindingKey within a bindingTemplate element is missing or is passed with an empty value, this is a signal that the bindingTemplate is being inserted for the first time.  When this occurs, the node MUST automatically generate a new key for the bindingTemplate that is without an associated key. New bindingTemplate structures can also be added with publisher-assigned keys. See Section 5.2.2.2 Behavior of Publishers.

Using this API call it is possible to move an existing bindingTemplate from one businessService to another by simply specifying a different parent businessService relationship along with the complete bindingTemplate.  Changing a parent relationship in this way causes two businessService structures to be affected.  The net result of such a move is that the bindingTemplate still resides within one, and only one businessService based on the value of the serviceKey passed. An attempt to move a bindingTemplate in this manner by a party who is not the publisher of the businessService that is specified by the serviceKey MUST be rejected with an error E_userMismatch.

When a bindingTemplate is saved with a categoryBag content that is associated with a checked value set or category group system tModel, the references MUST be checked for validity prior to completion of the save, or the node must return E_unsupported, indicating it does not support the referenced checked value set or category group system.  See Section 5.2.3 Special considerations for validated value sets and Appendix F Using Categorization for additional details.

5.2.15.4 Returns:

This API returns a bindingDetail structure containing the results of the call that reflects the newly registered information for the effected bindingTemplate elements.  If more than one bindingTemplate is saved in a single save_binding call, the resulting bindingDetail MUST return results in the same order that they appeared in the save_binding call.  If the same bindingTemplate (determined by matching bindingKey) is listed more than once in the save_binding call, it MAY be listed once in the result for each appearance in the save_binding call. If the same bindingTemplate appears more than once in the response, the last occurrence of the bindingTemplate in the results represents the state stored in the registry. Any bindingKeys that were assigned as a result of processing the save_binding call are included in the bindingTemplate data.

The bindingDetail structure has the form:

5.2.15.5 Caveats:

If an error occurs in processing this API call, a dispositionReport element MUST be returned to the caller in a SOAP Fault.  See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_accountLimitExceeded: Signifies that user account limits have been exceeded.

·         E_invalidKeyPassed: Signifies that the request cannot be satisfied because one or more uddiKey values specified are not valid key values for the entities being published. tModelKey, serviceKey, or bindingKey values that either do not exist, or exist with a different entity type, or are not authorized to be proposed by the publisher are considered to be invalid values. The key causing the error SHOULD be clearly indicated in the error text. This error code will also be returned in the event that the serviceKey is not provided and the bindingKey is either absent or has a value not registered in the registry. In this case, the error text SHOULD clearly indicate the use of an incomplete bindingTemplate.

·         E_invalidValue: A value that was passed in a keyValue attribute did not pass validation.  This applies to checked value sets that are referenced using keyedReferences. The error text SHOULD clearly indicate the key and value combination that failed validation.

·         E_keyUnavailable: Indicates that the proposed key has already been assigned to some other publisher or is not within the partition defined by a key generator tModel that the publisher owns.

·         E_requestTimeout: Signifies that the request could not be carried out because a needed validate_values service did not respond in a reasonable amount of time. Details identifying the failing Web service SHOULD be included in the dispositionReport element.

·         E_userMismatch: Signifies that one or more of the uddiKey values passed refers to data that is not owned by the individual publisher who is represented by the authentication token.

·         E_valueNotAllowed: Restrictions have been placed by the value set provider on the types of information that should be included at that location within a specific value set. A validate_values Web service chosen by the UDDI node has rejected this businessEntity for at least one specified keyedReference.  The error text SHOULD clearly indicate the keyedReference that was not successfully validated.


 

5.2.16 save_business

The save_business API call is used to save or update information about a complete businessEntity structure.  This API has the broadest scope of all of the save_xx API calls, and can be used to make sweeping changes to the published information for one or more businessEntity elements controlled by an individual.

This API call can be used to establish a reference relationship to businessService structures that are managed as the contents of another businessEntity.  In this way, a businessService that is a natural part of one businessEntity can appear as a projected service of another businessEntity.  The content of a businessService projected in this way (by way of a reference established by this API) are not managed as a part of the referencing entity.

businessEntity structures MAY be signed and MAY have publisher-assigned keys.

5.2.16.1 Syntax:

5.2.16.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         businessEntity:  Required repeating element containing one or more businessEntity structures.  These can be obtained in advance by using the get_businessDetail API call or by any other means.

5.2.16.3 Behavior:

If any of the uddiKey values within a businessEntity element (e.g. any data with a key value regulated by a businessKey, serviceKey or bindingKey) is missing or is passed with an empty value, this is a signal that the data that is so keyed is being inserted for the first time.[23]  When this occurs, the node MUST automatically generate a new key for the data passed that is without an associated key. New entities can also be added with publisher-assigned keys. See Section 5.2.2.2 Behavior of Publishers.

To make this API call perform an update to existing registered data, the keyed entities (businessEntity, businessService or bindingTemplate) MUST have uddiKey values that correspond to the registered data to be updated.

Data can be deleted with this API call when registered information is different from the new information provided. Any businessService and bindingTemplate structures found in the custodial UDDI node, but missing from the businessEntity information provided in this call, are deleted from the registry by this call.

Data contained within businessEntity structures can be rearranged with this API call. This can be done by redefining parent container relationships for other registered information.  For instance, if a new businessEntity is saved with information about a businessService that is registered already as part of a different businessEntity, this results in the businessService being moved from its current container to the new businessEntity.   This condition occurs when the businessKey of the businessService being saved matches the businessKey of the businessEntity being saved. An attempt to delete or move a businessService in this manner by a party who is not the publisher of the businessService MUST be rejected with an error E_userMismatch.

If the businessEntity being saved contains a businessService that has a businessKey referring to some businessEntity other than the businessEntity being saved, the UDDI registry notes a reference, called a “service projection”, to the existing businessService. Subsequent calls to the get_businessDetail API, passing either the businessKey of the businessEntity that contains the referenced businessService or the businessKey of the businessEntity that contains the service projection will result in an identical businessService element being included as part of the result set.

A businessEntity must not contain a businessService and a service projection to this businessService. As a result, a businessService cannot be moved to a businessEntity that already has a service projection to that businessService. Regardless of the order of operation, a businessService and a service projection can never appear under the same businessEntity. Implementations are required to reject and return an E_fatalError during such a save_business operation.

No changes to the referenced businessService are effected by the act of establishing a service projection.   Existing service projections associated with the businessEntity being saved that are not contained in the call to save_business are deleted automatically.  This reference deletion does not cause any changes to the referenced businessService. If the referenced businessService is deleted by any means, all references to it associated with other businessEntity structures are left untouched. Such “broken” service projections appear in their businessEntity as businessService elements containing the businessKey and serviceKey attributes as their only content. If the businessService is moved to another business, all projections will be updated to reflect the new businessKey[24]. For this reason, it is good practice to coordinate references to businessService data published under another businessEntity with the party who manages that data

When saving a businessEntity containing a service projection, all of the content of the businessService provided in the save_business, with the exception of the serviceKey and businessKey, is ignored.  The businessKey and serviceKey of the businessService being referenced are used to determine if the businessService is for a service projection or not.  If the businessService identified by the serviceKey is not part of the businessEntity identified by the businessKey, the error E_invalidProjection will be returned.

When a businessEntity is saved with identifierBag or categoryBag contents that is associated with a checked value set or category group system tModel, the references MUST be checked for validity prior to completion of the save or the node must return E_unsupported, indicating it does not support the referenced checked value set or category group system.  See Section 5.2.3 Special considerations for validated value sets, Appendix E Using Identifiers and Appendix F Using Categorization for additional details.

5.2.16.4 Returns:

This API returns a businessDetail structure containing the final results of the call that reflects the new registered information for the businessEntity information provided. Any businessKey, serviceKey, or bindingKey attributes that were assigned as a result of processing the save_business are included in the returned data. These results include any businessService elements that are contained by reference. If the same entity (businessEntity, businessService, or bindingTemplate), determined by matching key, is listed more than once in the save_business call, it MAY be listed once in the result for each appearance in the call. If the same entity appears more than once in the response, the last appearance occurrence of the entity in the results represents the final saved state stored in the registry.

The businessDetail has the form:

5.2.16.5 Caveats

If an error occurs in processing this API call, a dispositionReport element MUST be returned to the caller in a SOAP Fault.  See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_accountLimitExceeded: Signifies that user account limits have been exceeded.

·         E_invalidKeyPassed: Signifies that the request cannot be satisfied because one or more uddiKey values specified are not valid key values for the entities being published. tModelKey, businessKey, serviceKey, or bindingKey values that either do not exist, or exist with a different entity type, or are not authorized to be proposed by the publisher are considered to be invalid values. The key causing the error SHOULD be clearly indicated in the error text.

·         E_invalidProjection: Signifies that an attempt was made to save a businessEntity containing a service projection where the businessService being projected is not a part of the businessEntity that is identified by the businessKey in the businessService. The serviceKey of at least one such businessService SHOULD be included in the dispositionReport.

·         E_userMismatch: Signifies that one or more of the uddiKey values passed refers to data that is not owned by the individual publisher who is represented by the authentication token.  The key causing the error SHOULD be clearly indicated in the error text.

·         E_invalidValue: A value that was passed in a keyValue attribute did not pass validation.  This applies to checked value sets that are referenced using keyedReferences. The error text SHOULD clearly indicate the key and value combination that failed validation.

·         E_keyUnavailable: Indicates that the proposed key has already been assigned to some other publisher or is not within the partition defined by a key generator tModel that the publisher owns.

·         E_requestTimeout: Signifies that the request could not be carried out because a needed validate_values service did not respond in a reasonable amount of time. Details identifying the failing Web service SHOULD be included in the dispositionReport element.

·         E_unsupported: A keyedReference in a categoryBag or an identifierBag that references a checked value set cannot be validated by the UDDI node because the node does not support the referenced checked value set.  The error text should clearly indicate the keyedReference that cannot be validated.

·         E_unvalidatable: A keyedReference in a categoryBag or an identifierBag that references a checked value set cannot be validated by the UDDI node because the referenced tModel has been marked unvalidatable.  The error text should clearly indicate the keyedReference that cannot be validated.

·         E_valueNotAllowed: Restrictions have been placed by the value set provider on the types of information that should be included at that location within a specific value set. A validate_values Web service chosen by the UDDI node has rejected this businessEntity for at least one specified keyedReference.  The error text SHOULD clearly indicate the keyedReference that was not successfully validated.


 

5.2.17  save_service

The save_service API call adds or updates one or more businessService elements. Each businessService MAY be signed and MAY have publisher-assigned keys.

5.2.17.1 Syntax:


5.2.17.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         businessService:  Required repeating element containing one or more complete businessService elements.  For the purpose of performing round trip updates, this data can be obtained in advance by using the get_serviceDetail API call or by any other means.

5.2.17.3 Behavior:

Each new businessService passed MUST contain a businessKey value that corresponds to a registered businessEntity controlled by the same publisher. An existing business service MAY contain a businessKey value that corresponds to a registered businessEntity controlled by the same publisher.

If any of the uddiKey values within a businessService element (i.e., any data with a key value regulated by a serviceKey or bindingKey) is passed with an empty value, this is a signal that the data that is so keyed is being inserted for the first time. [25] In this case, a new key value MUST be automatically generated for the data which was passed without an associated key value. New entities can also be added with publisher-assigned keys. See Section 5.2.2.2 Behavior of Publishers.

If the same businessService is contained in more than one businessService argument, the final relationship to the containing businessEntity is determined by processing order – which is determined by first to last order of the information passed in the request. Analogously, if the same bindingTemplate is specified in the call as being in more than one businessService, the businessService that is its container at the conclusion of the call is last one listed.

Using this API call it is possible to move an existing bindingTemplate element from one businessService element to another, or move an existing businessService element from one businessEntity to another by simply specifying a different parent businessEntity relationship.  Changing a parent relationship in this way causes two businessEntity or two businessService structures to be changed. An attempt to move a bindingTemplate or a businessService in this manner by a party who is not the publisher of the businessService that is specified by the serviceKey or the businessEntity that is specified by the businessKey MUST be rejected with an error E_userMismatch.

When a businessService is saved with categoryBag contents that is associated with a checked value set or category group system tModel, the references MUST be checked for validity prior to completion of the save or the node MUST return E_unsupported, indicating it does not support the referenced checked value set or category group system.  See Section 5.2.3 Special considerations for validated value sets and Appendix F Using Categorization for additional details.

5.2.17.4 Returns:

This API call returns a serviceDetail containing the final results of the call that reflects the newly registered information for the affected businessService elements.  In cases where multiple businessService elements are passed in the request, the result contains the final results for each businessService passed and these appear in the same order as found in the request. Any serviceKey and bindingKey values that were assigned as a result of processing the save_service API are included in the businessService data.

If the same entity (businessService, or bindingTemplate), determined by matching key, is listed more than once in the save_service API, it MAY be listed once in the result for each appearance in the save_service API. If the same entity appears more than once in the response, the last occurrence of the entity in the results represents the state stored in the registry.

The serviceDetail has the form:

 


5.2.17.5 Caveats:

If an error occurs in processing this API call, a dispositionReport element MUST be returned to the caller within a SOAP Fault.  See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_accountLimitExceeded: Signifies that user account limits have been exceeded.

·         E_invalidKeyPassed: Signifies that the request cannot be satisfied because one or more uddiKey values specified are not valid key values for the entities being published. tModelKey, businessKey, serviceKey, or bindingKey values that either do not exist, or exist with a different entity type, or are not authorized to be proposed by the publisher are considered to be invalid values. The key causing the error SHOULD be clearly indicated in the error text. This error code will also be returned in the event that the businessKey is not provided and the serviceKey is either absent or has a value not registered in the registry.  In this case, the error text SHOULD clearly indicate the use of an incomplete businessService.

·         E_invalidValue: A value that was passed in a keyValue attribute did not pass validation.  This applies to checked value sets referenced using keyedReferences. The error text SHOULD clearly indicate the key and value combination that failed validation.

·         E_keyUnavailable: Indicates that the proposed key has already been assigned to some other publisher or is not within the partition defined by a key generator tModel that the publisher owns.

·         E_requestTimeout: Signifies that the request could not be carried out because a needed validate_values service did not respond in a reasonable amount of time. Details identifying the failing Web service SHOULD be included in the dispositionReport element.

·         E_userMismatch: Signifies that one or more of the uddiKey values passed refers to data that is not owned by the individual publisher who is represented by the authentication token.

·         E_unsupported: A keyedReference in a categoryBag that references a checked value set cannot be validated by the UDDI node because the node does not support the referenced checked value set.  The error text SHOULD clearly indicate the keyedReference that cannot be validated.

·         E_unvalidatable: A keyedReference in a categoryBag that references a checked value set cannot be validated by the UDDI node because the referenced tModel has been marked unvalidatable.  The error text SHOULD clearly indicate the keyedReference that cannot be validated.

·         E_valueNotAllowed: The value set validation routine chosen by the UDDI node has rejected the businessService data provided.  The error text SHOULD clearly indicate the keyedReference that was not successfully validated.


 

5.2.18 save_tModel

The save_tModel API call adds or updates one or more registered tModel elements. tModels MAY be signed and tModels MAY be saved with publisher-assigned keys, including those tModels that establish the domain partition of publisher-assigned keys, known as domain key generator tModels. 

5.2.18.1 Syntax:

 

5.2.18.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         tModel:  Required repeating element containing one or more required repeating complete tModel elements.  For the purpose of performing round-trip updates, this data can be obtained in advance by using the get_tModel API call or by other means.

5.2.18.3 Behavior:

If the uddiKey value within a tModel (i.e., tModelKey) is missing or is passed with an empty value, this is a signal that a new tModel is being inserted and that the UDDI registry MUST assign a new tModelKey identifier to this data.  If the new tModel is categorized with the keyGenerator value from the uddi:uddi.org:categorization:types category system, any publisher assigned key MUST end with the string “:keygenerator” , making the tModel a key generator tModel.  If the new tModel is categorized with the keyGenerator value from the uddi:uddi.org:categorization:types category, an empty uddiKey signifies that the tModelKey generated by the node will end with the string “:keygenerator”, making the tModel a key generator tModel.  New tModels can also be added with publisher-assigned keys. See Section 5.2.2.2 Behavior of Publishers and Section 5.2.18.3.1 Domain Key Generator tModels

This API call performs an update to existing registered data when the tModelKey values have uddiKey values that correspond to already registered data.

If a tModelKey value is passed that corresponds to a tModel that was previously hidden via the delete_tModel API call, the save_tModel service restores the tModel to full visibility, making it available for return in find_tModel results.

The value of the deleted attribute in the tModel is set to false in all saves. Saving a tModel that has specified a value of true for the deleted attribute MUST result in an error.

Multiple representations of the overview document MAY be registered for a tModel allowing, for example, both technical and human readable representations of the technical overview to be provided.

When a tModel is saved with keyedReferences, all tModelKeys used in keyedReferences must refer to tModels that existed prior to processing the tModel containing the references. A save_tModel API call may contain a sequence of tModels, in which case a keyedReference in a tModel may refer to tModelKeys created earlier but not later in the sequence. A tModel being created must not refer to itself. Self-referencing tModels can be created by using two subsequent save_tModel API calls, the first one without the reference, and the second one with the reference (to the already saved tModel). If these conditions are not met, the node MUST return E_invalidKeyPassed.

When a tModel is saved with identifierBag or categoryBag contents that is associated with a checked value set or category group system tModel, the references MUST be checked for validity prior to completion of the save, or the node MUST return E_unsupported, indicating it does not support the referenced checked value set or category group system.  See Section 5.2.3 Special considerations for validated value sets, Appendix E Using Identifiers and Appendix F Using Categorization for additional details.

5.2.18.3.1 Domain key generator tModels

For registries that use the recommended key syntax, a domain key generator tModel establishes a key partition from which uddiKeys can be derived and used in other entities controlled by the publisher, as described in Section 4.4.1 Key Syntax.  Additional considerations are involved when publishing a domain key generator tModel for the first time. 

1.       The tModelKey MUST be in the form of a domain_key and MUST end with the term: keyGenerator.

2.       The tModelKey MUST be categorized with the keyGenerator value from the uddi:uddi.org:categorization:types category system.

3.       Registry policy for establishing key domains MAY require the tModel to be signed.

Also, publishers of key generator tModels MAY use the overviewDoc to describe how the key space is defined.

The save_tModel API call does a first pass check of the tModel to check its suitability and, if it is acceptable according to the policy of the registry for saving domain key generator tModels, returns the tModelDetail for the registry. If it is not acceptable the reason is clearly indicated in the returned dispositionReport and no further processing takes place.

If the registry has multiple nodes, returning the tModelDetail is not an indication that the domain key generator tModel has been published successfully. A registry that allows publisher assigned keys MUST have a policy to ensure domainKey collisions do not occur.  The custodial node MUST ensure that the domain key generator tModel is not in the process of being published simultaneously on some other node. If, after the conclusion of a full replication cycle, no UDDI node has already assigned or attempted to assign the partition (e.g., no change record has been received from other nodes), the custodial node completes the publish operation of the domain key generator tModel, assigning it to the publisher. If some other node has already been assigned the partition, the tModel is not published.  See Section 7.3.9 changeRecordNewDataConditional for more information on the replication structure, and Section 9.4.2 General Keying Policy and Section 9.4.3 Policy Abstractions for the UDDI keying scheme for the recommended policy that addresses acceptance of a domain key generator.

When the publishing of a domain key generator tModel has completed, the custodial node MAY notify the publisher that the tModel is ready for use. Whether a node does this and the means by which it does so is a node policy. A typical node policy is to notify the publisher by e-mail using an e-mail address gathered at the time the publisher account was set up.

Before the publish operation is complete, the domain key generator tModel will be ignored by find_xx and get_xx API calls, and will return an E_keyUnavailable error to further save_tModel calls.

If after the replication cycle the publisher is in doubt about the outcome, get_tModelDetail may be issued specifying the key of the domain key generator tModel being published. If a tModel is retrieved and the publisher is the owner, the operation succeeded. If a tModel is retrieved and some other publisher is the owner, the operation failed because another publisher published a domain key generator with the chosen domain_key first. If no tModel is retrieved, then either the registry experienced a failure, or two publishers tried to publish tModels with the same key "simultaneously", and neither succeeded. In either of these cases, the save_tModel operation may be retried.

5.2.18.4 Returns:

In most cases this API returns a tModelDetail containing the final results of the call that reflects the new or pending registered information for the affected tModel structures. Any tModelKey attributes that were assigned as a result of processing the save_tModel API are included in the tModel data.  When a domain key generator is saved for the first time, the tModel that is returned in the tModelDetail represents an interim state, until all nodes in the registry have ascertained that the requested key domain does in fact belong to the publisher[26].  See Section 7.3.9 changeRecordNewDataConditional for more information.  If multiple tModel elements are passed in the save_tModel request, the order of the response MUST exactly match the order that the elements appeared in the save. If the same tModel, determined by matching key, is listed more than once in the save_tModel API, it MAY be listed only once in the result for each appearance in the save_tModel API. If the same tModel appears more than once in the response, the last occurrence of the tModel in the results represents the state stored in the registry.

The tModelDetail has the form:

 

5.2.18.5 Caveats:

If an error occurs in processing this API call, a dispositionReport element MUST be returned to the caller in a SOAP Fault.  See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_accountLimitExceeded: Signifies that user account limits have been exceeded.

·         E_invalidKeyPassed: Signifies that the request cannot be satisfied because one or more uddiKey values specified are not valid key values for the entities being published. tModelKey values that either do not exist, or exist with a different entity type, or are not authorized to be proposed by the publisher are considered to be invalid values. The key causing the error SHOULD be clearly indicated in the error text.

·         E_invalidValue: A value that was passed in a keyValue attribute did not pass validation.  This applies to checked value sets referenced using keyedReferences. The error text SHOULD clearly indicate the key and value combination that failed validation.

·         E_keyUnavailable: Indicates that the proposed key has already been assigned to some other publisher, is not within the partition defined by a key generator tModel that the publisher owns, or, in the case of a domain key generator tModel being saved for the first time, is assigned to some other publisher or is still pending its first save.

·         E_requestTimeout: Signifies that the request could not be carried out because a needed validate_values Web service did not respond in a reasonable amount of time. Details identifying the failing Web service SHOULD be included in the dispositionReport element.

·         E_unacceptableSignature: Indicates that the digital signature in the tModel is missing or does not meet the requirements of the registry. The errInfo element provides additional details.

·         E_userMismatch: Signifies that one or more of the uddiKey values passed refers to data that is not owned by the individual publisher who is represented by the authentication token.

·         E_unsupported: A keyedReference in a categoryBag or an identifierBag that references a checked value set cannot be validated by the UDDI node because the node does not support the referenced checked value set.  The error text SHOULD clearly indicate the keyedReference that cannot be validated.

·         E_unvalidatable: A keyedReference in a categoryBag or an identifierBag that references a checked value set cannot be validated by the UDDI node because the referenced tModel has been marked unvalidatable.  The error text SHOULD clearly indicate the keyedReference that cannot be validated.

·         E_valueNotAllowed: Restrictions have been placed by the value set provider on the types of information that should be included at that location within a specific value set.  The validation routine chosen by the UDDI node has rejected this tModel for at least one specified keyedReference.  The error text SHOULD clearly indicate the keyedReference that was not successfully validated.


 

5.2.19 set_publisherAssertions

The set_publisherAssertions API call is used to manage all of the tracked relationship assertions associated with an individual publisher.   See Appendix A Relationships and Publisher Assertions for more information.

5.2.19.1 Syntax:

 


5.2.19.2 Arguments:

·         authInfo: This optional argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification. Registries that serve multiple publishers and registries that restrict who can publish in them typically require authInfo for this call.

·         publisherAssertion: Optional repeating element asserting a relationship.  Relationship assertions consist of a reference to two businessEntity key values as designated by the fromKey and toKey elements, as well as a REQUIRED expression of the directional relationship within the contained keyedReference element.  See Appendix A Relationships and Publisher Assertions. The fromKey, the toKey, and all three parts of the keyedReference – the tModelKey, the keyName, and the keyValue – MUST be specified. E_fatalError is returned if any of these elements are missing in any of the publisherAssertion elements.  Empty (zero length) keyNames and keyValues are permitted.

5.2.19.3 Behavior:

The full set of assertions associated with a publisher is effectively replaced whenever this API is used.  When this API call is processed, the publisher assertions that exist prior to this API call for a given publisher are examined by the UDDI registry.  Any new assertions not present prior to the call are added to the assertions attributed to the publisher. Any existing assertions not present in the call are deleted.   As a result, new relationships may be completed (e.g. determined to have a completed status), and existing relationships may be dissolved.  Invoking this API with no publisherAssertion elements deletes all assertions associated with the publisher.

Any relationships attributed to assertions previously present but not present in the data provided in this call are deactivated and are no longer visible via the find_relatedBusinesses API.  For the sake of determining uniqueness within an assertion set, the fromKey, toKey, and the entire keyedReference within the publisherAssertion element are significant.  Any differences in any of the individual publisherAssertion element contents constitute a new unique assertion for purposes of detecting new assertions.  The direction of the relationship, as indicated by the two businessKey values in the fromKey and toKey elements, is also relevant in determining assertion uniqueness.

The publisher must own the businessEntity referenced in the fromKey, the toKey, or both.  If both of the businessKey values passed within an assertion are owned by the publisher, then the assertion is automatically complete and the relationship described in the assertion is visible via the find_relatedBusinesses API.  To form a relationship when the publisher only owns one of the two keys passed, the assertion MUST be matched exactly by an assertion made by the publisher who owns the other business referenced. Assertions exactly match if and only if they:

1.       refer to the same businessEntity in their fromKeys;

2.       refer to the same businessEntity in their toKeys;

3.       refer to the same tModel in their tModelKeys;

4.       have identical keyNames; and

5.       have identical keyValues.

When a publisherAssertion that is being saved references a checked relationship system using the tModelKey in the contained keyedReference, the reference MUST be checked for validity prior to completion of the save, or the node must return E_unsupported, indicating it does not support the referenced checked relationship system.  Validation of a relationship system reference entails verification that the reference is valid according to the validation algorithm defined for the relationship system and described by its tModel.  For cached checked relationship system, the validation algorithm verifies that referenced keyedReferences are valid for the relationship system.

5.2.19.4 Returns:

Upon successful completion, a publisherAssertions structure is returned containing all of the relationship assertions currently attributed to the publisher.  When registries distinguish between publishers, the structure contains assertion data that is associated with the authInfo passed.

See Section 5.2.13.3 get_publisherAssertions for more information on the publisherAssertions structure and contents.

This API returns all assertions made by the publisher who was authenticated in the set_publisherAssertions API.

5.2.19.5 Caveats:

If an error occurs in processing this API call, a dispositionReport element MUST be returned to the caller in a SOAP Fault.  See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: Signifies that one of the uddiKey values passed did not match with any known businessKey or tModelKey values.  The assertion element and the key that caused the problem SHOULD be clearly indicated in the error text.

·         E_userMismatch: Signifies that neither of the businessKey values passed in the embedded fromKey and toKey elements is controlled by the publisher associated with the authentication token.  The error text SHOULD clearly indicate which assertion caused the error.


 

 

5.3 Security Policy API Set

The security API includes the following API calls:

·         discard_authToken: Used to inform a node that a previously obtained authentication token is no longer required and should be considered invalid if used after this message is received.

·         get_authToken: Used to request an authentication token in the form of an authInfo element from a UDDI node.  An authInfo element MAY be required when using the API calls defined in Section 5.1 Inquiry API Set, Section 5.2 Publication API Set, Section 5.4 Custody and Ownership Transfer API Set, and Section 5.5 Subscription API Set.

Whether authInfo elements are required on API calls is determined by node policy as described in Section 4.8 About Access Control and the authInfo Element. In the event that an authInfo element is not discarded, a node MAY choose to expire the authentication token so it is no longer valid for authentication in API calls after a period of time.  If an expired token is passed to an API call other than discard_authToken, the error E_authTokenExpired will be returned as described in Chapter 12, Error Codes.

A UDDI node typically does not support the Security API set if it does not support using an authInfo element in any API set. If the node does support using an authInfo element in any of the API set provided by the node, it SHOULD support the Security API set.  A node MAY provide an alternative mechanism for obtaining authInfo elements. 

5.3.1 discard_authToken

The discard_authToken API call is used to inform a node that the passed authentication token is to be discarded, effectively ending the session.

5.3.1.1 Syntax:

 

5.3.1.2 Arguments:

·         authInfo: This required argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call.

5.3.1.3 Returns:

Upon successful completion, a dispositionReport is returned with a single success indicator.  Discarding an expired authToken is processed and reported as a success condition.

5.3.1.4 Caveats:

If an error occurs in processing this API call, a dispositionReport structure will be returned to the caller in a SOAP Fault. 


 

5.3.2 get_authToken

The get_authToken API call is used to obtain an authentication token.  An authToken element MAY be required when using the API calls defined in Section 5.1 Inquiry API Set, Section 5.2 Publication API Set, Section 5.4 Custody and Ownership Transfer API Set, and Section 5.5 Subscription API Set.

5.3.2.1 Syntax:

 

Attributes

Name 

Use 

userID

Required

cred

Required

 

5.3.2.2 Arguments:

·         userID: This required attribute argument is the user identifier that an individual authorized user was assigned by a UDDI node.  Nodes SHOULD provide a means for individuals to obtain a userID and password credentials that will be valid at the given node.

·         cred: This required attribute argument is the password or credential that is associated with the user.

5.3.2.3 Returns:

Upon successful completion this API call returns an authToken structure that contains a valid authInfo element that can be used in subsequent calls to API calls that require an authInfo value.

The authToken message has the form:

The authToken structure contains a single authInfo element that represents a token that is to be passed back in API calls that require one. This structure is always returned as a synchronous response to the get_authToken message.


 

5.3.2.4 Caveats:

If an error occurs in processing this API call, a dispositionReport element will be returned to the caller within a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_unknownUser: Signifies that the UDDI node that received the request does not accept the userID and/or cred argument values passed as valid credentials.

 


 

5.4 Custody and Ownership Transfer API Set

This section defines the UDDI Custody and Ownership Transfer API Set[27]. Data custody is introduced in Section 1.5.6 Data Custody. Ownership transfer is introduced in Section 1.5.7 Transfer of Ownership. By virtue of having created an entity, a publisher has ownership of the entity and is said to be the owner of the entity. A custodial node MUST maintain a relationship of ownership between an entity and its publisher by means of authorization mechanisms. Every node of a multi-node registry MUST guarantee the integrity of an entity's custody. As such, a node MUST not permit changes to an entity unless it has custody of it.

The Custody and Ownership Transfer API Set enables any nodes of a registry to cooperatively transfer custody of one or more businessEntity or tModel structures from one node to another, as well as allowing the transfer of ownership of these structures from one publisher to another. Associated entities of a businessEntity such as its businessService, bindingTemplate, and publisherAssertion structures are transferred as part of the custody transfer of the business entity. 

From a custody transfer point of view, the publishers are always distinct, though it may be the case that the publishers are the same person. Also, the two nodes may or may not be distinct; intra-node transfer between two publishers is simply a degenerate case in which node custody does not change. Thus, in the case of an inter-node transfer, ownership transfer is implied. In the case of an intra-node transfer the behavior results in the transfer of ownership between two publishers.

For example, one UDDI registry, UDDI-1, MAY allow each node in UDDI-1 (composed of nodes 1A, 1B and 1C) to define its own policies for registration, authentication and authorization.  In this case, a “person”, (P1) would need to review the policies of all 3 nodes and decide upon the node with which it chooses to register with. P1 may choose to register with more than one node.  P1 registers with node1A . Node1A also specifies how P1 is authenticated.  If P1 successfully authenticates and publishes a business entity (BE1) then P1 becomes the “owner” of BE1. Node1A is said to be the “custodian” of BE1. P1 can also register at node1B. If P1 successfully authenticates and publishes a business entity (BE2) then P1 becomes the “owner” of BE2. Node1B is said to be the “custodian” of BE2. There is no assumption that the registry UDDI-1 or its nodes (node1A and node1B) are aware that P1 is the same “person”.  P1 is responsible for maintaining the appropriate identity and authenticating correctly to each node within a registry.

Another UDDI registry, UDDI-2, MAY require each of its nodes (node2-1, node2-2 and node2-3) to use the same registration, authentication and authorization mechanisms.  In this case, the policies are the same across all nodes. The relationship of registration, publication and ownership remains the same.  If P1 wants to register with different nodes in UDDI-2, then it needs to differentiate its registration with the different nodes, since an attempt to register at node2-2 after registering at node2-1, would fail as “already registered” (since by policy the nodes all share the same registration, authentication and authorization).

5.4.1 Overview

There are a number of scenarios where a publisher may choose to transfer custodianship or ownership of one or more entities. These are described in this section.

5.4.1.1 Intra-Node Ownership Transfer

Intra-node ownership transfer involves transferring entity ownership from one publisher to another within the same UDDI node.  Usage scenarios for this type of transfer include the following:

·         Businesses or organizational merges:  Multiple organizations need to be consolidated under the control of a single publisher.

·         Domain key generators: One use of ownership transfer is the transfer of ownership of a derived key generator from one publisher to another to enable her or him to publish entities using keys in that domain.

The save_xx APIs can also be used to move entities between parent entities that are owned by the same publisher.  The save_service API, for example, can be used to move services (and binding templates) between one business entity and another as described in Section 5.2.17.3 Behavior of the save_service API. Changing the parent relationship in this way causes two businessEntity structures to be changed. Doing so enables the following scenarios:

·         Divestitures: An organization needs to reassign the control of a set of services to two or more publishers.

·         Consolidation of registry entities:  There are multiple entities for a given business that are to be consolidated under a single publisher.

5.4.1.2 Inter-Node Custody Transfer

Inter-node custody transfer involves the custody transfer of a set of entities across nodes of a UDDI registry. A transfer of ownership ensues as a consequence of this custody transfer.  In addition to the intra-node scenarios described above, inter-node custody transfer may be used to address the following use cases:

·         Unsatisfactory service level: The functionality or service level provided by a given node operator is insufficient, and the publisher wishes to move their UDDI data to another node.

·         Change in availability for a UDDI node: A node is no longer providing UDDI services, and all publishers need to be migrated to one or more nodes of the registry.

·         Organizational Mergers, Divestitures or Consolidations:  Changes in organizational structure may result in the need to make changes to the set of publishers used to manage the entities at various nodes of a registry.

For any of these intra and inter-node scenarios, a mechanism is specified to facilitate the transfer the custody of businessEntity and tModel entities between nodes whether the entity is being transferred within a single node or whether a custody transfer occurs between nodes of a registry.

5.4.2 Custody Transfer Considerations

When a businessEntity is transferred, all related businessService and bindingTemplate elements are transferred as well.  In addition, any publisherAssertion elements that reference the businessEntity element’s businessKey that are owned by the publisher are also transferred.

Note that the relinquishing publisher is not required to transfer all of its UDDI entities (i.e. businessEntity and/or tModel entities) in a single custody transfer request, nor is it required to transfer all of its entities to the same target publisher or target node.  Any combination or subset of UDDI registry entities may be transferred to any number of target publishers or nodes.

5.4.3 Transfer Execution

The Custody and Ownership Transfer API Set enables two publishers P1 and P2 and two nodes, N1 and N2, in a registry to cooperatively transfer custody of one or more existing businessEntity or tModel structures, E1…En, from N1 to N2 and, and by extension to transfer ownership of the entities from P1 to P2.  Related businessService, bindingTemplate, and publisherAssertion structures are transferred with their related businessEntities.  From the registry’s point of view, the publishers are always distinct, though it may be the case that P1 and P2 are the same party. The two nodes may or may not be distinct; intra-node transfer of ownership from P1 to P2 is simply a degenerate case in which node custody does not change.

The Custody and Ownership Transfer API Set is divided into two parts, a set of two client APIs and a single inter-node API. These client APIs are get_transferToken and transfer_entities; in short, this constitutes the Ownership Transfer API portion of this API set. The inter-node-API is transfer_ custody which when combined with replication makes up the Custody Transfer API portion of this API set. 

The overall flow of custody and ownership transfer is as follows:

Publisher P1 invokes get_transferToken on N1, specifying the keys K1…Kn of the entities E1…En that are to be transferred. If P1 is authorized to do this (i.e., if P1 has ownership of E1…En), N1 returns a structure T, called a transfer token, that represents authority to transfer the entities, including all of the naturally contained children and publisher assertions related to business entities involved in the transfer that are owned by P1.  The transferToken is a structure that consists of an opaque string that is meaningful only to the node that issued it, an expiration time, and a node identifier.

P1 then gives T to P2 (typically by some secure means since T is valuable). The publisher obtaining the custody information needs to have previously obtained a publishers account on the node accepting custody of the entity before he/she can complete the custody transfer. P2 then invokes transfer_entities on N2, passing K1…Kn and T. If transfer_entities completes successfully, the entities E1…En and their related structures (businessService, bindingTemplate, and publisherAssertion) are in the custody of N2 and are owned by P2. If the operation fails, nothing happens to the entities. The actual transfer proceeds as follows, in the processing of transfer_entities.

If N1 and N2 are not distinct nodes, the ownership transfer from P1 to P2 is an operation that is purely internal to the node – how it happens is up to the implementation. If N1 and N2 are distinct, the following protocol occurs while processing the transfer_entities request on N2.

Upon receipt of a transfer_entities request, N2 checks that K1…Kn are valid keys. There is the possibility that P1 might transfer more data than P2 can accept due to policy-based restrictions on the limit of entities allowed to be owned by P2 at N2. As is described below, replication is used to complete the custody transfer process. A question that arises is at the time of accepting the datum related to the transfer, could N2 throw a replication error because the data being transferred exceeds the limits of user P2? Such limits can not be enforced during replication because they are node-local policy decisions from the perspective of enforcement. Thus, it is therefore possible that as a result of a custody transfer a publisher may be caused to hold more data that he/she would have been able to publish. Should this situation occur, P2 MUST not be allowed to publish any additional data unless P2 first reduces the number of entries it owns to an allowable limit.

If all is well, N2 invokes the inter-node API transfer_custody on N1, presenting the keys of top-level entities to be transferred, K1…Kn, P2’s identity (using the publisher’s authorizedName), N2’s node identifier (as known in the Replication Configuration structure, see Section 7.5.2 Configuration of a UDDI Node – operator element), and T. The transferToken, T, implies permission to transfer the entire content of the entities it identifies, including all of the contained entities and related publisherAssertions, if any.  N1 checks to see whether T is a valid transferToken that it issued and that T represents the authority to transfer E1…En. If the validation is successful, N1 prevents further changes to entities E1…En. N1 then updates the authorizedName and nodeID of the operationalInfo of E1…En and related entities so that they are shown to be in the custody of N2 and owned by P2. Finally, N1 responds to N2 with a dispositionReport which triggers N2 to respond to the transfer_entities caller with a corresponding dispositionReport. This completes the processing for the transfer_entities request.

In the case that the datum being transferred is a key generator tModel, N1 will disallow further generation of keys associated with this key partition at its node.

Following the issue of the dispositionReport by N1 to the transfer_custody call, N1 will submit into the replication stream a changeRecordNewData providing in the operationalInfo, N2’s nodeID identifying it as the node where the datum is being transferred to, and the authorizedName of P2. The acknowledgmentRequested attribute of this change record MUST be set to “true”.

The last modified date timestamp in the operationalInfo must change to reflect the custody transfer. Figure 2 depicts the flow of a custody transfer between P1 and P2.

 

 

Figure 2 - Custody Transfer

 

Once N2 receives the changes via the replication stream it assumes custody of E1…En and assigns ownership of the entities and related entities owned by P1 to P2.

5.4.3.1 Content of a transferToken

The transferToken is a structure that consists of an opaque string that is meaningful only to the node that issued it, an expiration time, and a node identifier. It represents the one-time authority to transfer ownership of a specific set of entities to any publisher and to transfer custody of them to any node in the registry. Issuing it does not cause any such transfer to occur; it is simply an authorization for such a transfer to take place. The authority represented by a transferToken expires after some period of time, per node policy.

The expiration time represents the time, according to the node that issued the transferToken, after which the token is no longer valid. The expiration time is only a convenience; changing it does not change the time at which the authority expires. The node identification identifies, in a registry dependent way, the node that issued the transferToken. It is used by the node that receives the transferToken to determine which node in the registry to direct the transfer_custody request to.

The opaque token SHOULD reflect the entities that the custodial publisher has sought permission to be transferred.  It is often used in the latter stages of the custody transfer process by the custodial node to verify that the entities that the target publisher is requesting to own have been authorized by the target node under the auspices of the transferToken.

5.4.4 discard_transferToken

The discard_transferToken API is a client API used to discard a transferToken obtained through the get_transferToken API at the same node. This API accepts either a transferToken or a keyBag as parameters to remove the permission to transfer data associated with a particular transferToken.  If a keyBag is provided, all tokens corresponding to the keys in the keyBag will be discarded and will no longer be valid for custody or ownership transfer after the discard_transferToken is processed.  In the event that the keyBag represents a subset of the keyBag for one or more transferToken elements, the transferToken is discarded and will no longer be valid for transferring any entity.

5.4.4.1 Syntax

5.4.4.2 Arguments

·         authInfo: This OPTIONAL argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification, and represent the identity of the publisher at a UDDI node.

·         transferToken: This is a known transferToken obtained by a publisher at the node where the get_transferToken API was invoked.

·         keyBag: One or more uddiKeys associated either with businessEntity or tModel entities owned by the publisher that were to be transferred to some other publisher and/or node in the registry as the result of invocation of get_transferToken.  At least one businessKey or tModelKey must be provided in a keyBag.

5.4.4.3 Returns

Upon successful completion, a dispositionReport structure is returned with a single success indicator. See Section 4.8 Success and Error Reporting.

No error will be reported if the transferToken provided in the call does not match an existing token.  No error will be reported if a token is not found for a particular key in the keyBag.

5.4.4.4 Caveats

If an error occurs in processing this API call, a dispositionReport structure MUST be returned to the caller in a SOAP Fault. See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: signifies that one of the uddiKey values passed for entities to be transferred did not match with any known businessKey or tModelKey values.  The key and element or attribute that caused the problem SHOULD be clearly indicated in the error text.

·         E_userMismatch: signifies that one or more of the businessKey or tModelKey elements that identify entities to be transferred are not owned by the publisher identified by the authInfo element.  The error text SHOULD clearly indicate which entity keys caused the error.

5.4.5 get_transferToken

The get_transferToken API is a client API used to initiate the transfer of custody of one or more businessEntity or tModel entities from one node to another. As previously stated, the two nodes may or may not be distinct; intra-node transfer between two publishers is simply a degenerate case in which node custody does not change. No actual transfer takes place with the invocation of this API.  Instead, this API obtains permission from the custodial node, in the form of a transferToken, to perform the transfer. The publisher who will be recipient of the transferToken returned by this API must invoke the transfer_entities API on the target custodial node to actually transfer the entities.

5.4.5.1 Syntax

 

 

5.4.5.2 Arguments

·         authInfo: This OPTIONAL argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification and represent the identity of the publisher at a UDDI node.

·         keyBag: One or more key (of type uddi:uddiKey) associated either with businessEntity or tModel entities owned by the publisher that are to be transferred to some other publisher and/or node in the registry.  At least one businessKey or tModelKey must be provided.

5.4.5.3 Returns

If the publisher identified by the authInfo element owns the businessEntity elements identified by the businessKey elements provided and the tModel elements identified by the tModelKey elements provided, a transferToken is returned that represents the one-time permission to transfer custody of the identified entities.

 

 

The transfer token consists of a nodeID, an expirationTime and an opaqueToken.  The nodeID is used during the transfer_entities API by the recipient node to confirm with the relinquishing custodial node that the custody transfer is authorized and still valid. The nodeID of the transferToken is the value of the nodeID element of the Replication Configuration Structure. Refer to Section 7.5.2 Configuration of a UDDI Node – operator Element.

The expirationTime, defined as xsd:dateTime, represents the time at which the transfer token is no longer valid.

The opaqueToken is only meaningful to the node that issues it. The opaqueToken is defined as xsd:base64Binary to allow for a RECOMMENDED encryption of the token under the relinquishing custody node’s own encryption key.

5.4.5.4 Caveats

If an error occurs in processing this API call, a dispositionReport structure MUST be returned to the caller in a SOAP Fault. See section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: signifies that one of the uddiKey values passed for entities to be transferred did not match with any known businessKey or tModelKey values.  The key and element or attribute that caused the problem SHOULD be clearly indicated in the error text.

·         E_tokenAlreadyExists: signifies that one or more of the businessKey or tModelKey elements that identify entities to be transferred are associated with a transferToken that is still valid and has not been discarded, used or expired.  The error text SHOULD clearly indicate which entity keys caused the error.

·         E_userMismatch: signifies that one or more of the businessKey or tModelKey elements that identify entities to be transferred are not owned by the publisher identified by the authInfo element.  The error text SHOULD clearly indicate which entity keys caused the error.

 

5.4.6 transfer_entities

The transfer_entities API is used by publishers to whom custody is being transferred to actually perform the transfer.  The recipient publisher must have an unexpired transferToken that was issued by the custodial node for the entities being transferred.

5.4.6.1 Syntax

5.4.6.2 Arguments

·         authInfo: This OPTIONAL argument is an element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification, and represent the identity of the publisher at a UDDI node, in this case, the new owner of the entities being transferred.

·         transferToken: Required argument obtained from the custodial node via a call to get_transferToken by the publisher requesting a transfer of custody. The transferToken contains an opaque token, an expiration date, and the identity of the custodial node.  The transferToken represents permission to transfer the entities that have been identified via a prior call to the get_transferToken API.

·         keyBag: One or more uddiKeys  associated with businessEntity or tModel entities that are to be transferred to this publisher at the target node in the registry. The set of keys must be the same as the set of keys in the keyBag of the get_transferToken API call from which the given transferToken was once obtained.

5.4.6.3 Returns

The target node responds to this API by performing the transfer operation.  This operation is comprised of four steps:

·         Verification that the entity keys are valid.

·         Verification that ownership of the entities by the recipient publisher is allowed and would not violate any policies at the target node related to publisher limits.

·         Verification with the custodial node that the transfer of the designated entities is allowed.  This is accomplished by invoking transfer_custody on the custodial node that is identified by the nodeID element in the transferToken.  Any errors returned by the custodial node cause this API to fail and are propagated to the caller.

·         Changing custody and ownership of the designated entities and entering these changes into the replication stream.

Upon successful completion, a dispositionReport is returned indicating the success of the transfer operation. In the case of an inter-node custody transfer, while the transfer is in process, the entities being transferred are not available for modification. To determine the state of the data, UDDI clients can use the get_operationalInfo API to determine when custody and ownership transfer has taken place. A change in the nodeID of the operationalInfo provides such an indication.

5.4.6.4 Caveats

If an error occurs in processing this API call, a dispositionReport structure MUST be returned to the caller in a SOAP Fault. See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_accountLimitExceeded: signifies that the target node has determined that the transfer of custody of the identified entities would result in the target publisher exceeding policy limits for the number of owned entities.  The error text SHOULD clearly indicate which entities cause the publishers limits to be exceeded. It is possible for a publisher to come into possession of more data than the target node’s policy allows. The condition and node behavior under these circumstances are described in Section 5.4.3Transfer Execution.

·         E_invalidKeyPassed: signifies that one of the uddiKey values passed for entities to be transferred did not match with any known businessKey or tModelKey values.  The key and element or attribute that caused the problem SHOULD be clearly indicated in the error text.

·         E_transferNotAllowed: signifies that the transfer of one or more entities has been rejected by the target node or the custodial node.  Reasons for rejection include expiration of the transferToken and attempts to transfer a set of entities that does not match the one represented by the transferToken. The reason for rejecting the custody transfer SHOULD be clearly indicated in the error text.


 

5.4.7 transfer_custody

Invoked by the target node in a custody transfer operation in response to transfer_entities, this API is used by the custodial node to ensure that permission has been granted to transfer custody of the entities that the target publisher has requested.

5.4.7.1 Syntax

5.4.7.2 Arguments

·         transferToken: Required argument obtained from the custodial node via a call to get_transferToken by the publisher requesting a transfer of custody. The transferToken contains an opaque token, an expiration date, and the identity of the custodial node.  The transferToken represents permission to transfer the entities that have been identified via a prior call to the get_transferToken API. The custodial node MUST verify that the transferToken has not expired and that the businessKey and tModelKey elements that the target publisher has provided in transfer_entities are allowed to be transferred as captured in the transfer token’s opaqueToken.

·         keyBag: One or more uddiKeys associated with businessEntity or tModel entities that the target publisher is requesting ownership of at the target node in the registry. The set of keys must be the same as the set of keys in the keyBag of the get_transferToken API call from which the given transferToken was once obtained.

·         transferOperationalInfo: Required argument. The accepting publisher’s authorizedName and the accepting node’s nodeID are provided on input to the relinquishing custodial node to allow it to update the operationalInfo associated with the entities whose custody is being transferred. The authorizedName and nodeID elements are both required. The accepting node’s nodeID is obtained via the Replication Configuration structure as described in Section 7.5.2 Configuration of a UDDI Node – operator element. The authorizedName is obtained from the call to transfer_entities by the requesting publisher.

5.4.7.3 Returns

The custodial node must verify that it has granted permission to transfer the entities identified and that this permission is still valid.  This operation is comprised of two steps:

1.       Verification that the transferToken was issued by it, that it has not expired, that it represents the authority to transfer no more and no less than those entities identified by the businessKey and tModelKey elements and that all these entities are still valid and not yet transferred. The transferToken is invalidated if any of these conditions are not met.

2.       If the conditions above are met, the custodial node will prevent any further changes to the entities identified by the businessKey and tModelKey elements identified. The entity will remain in this state until the replication stream indicates it has been successfully processed via the replication stream. 

Upon successful verification of the custody transfer request by the custodial node, a dispositionReport is returned by it indicating the success of the request and acknowledging the custody transfer. 

Following the issue of the dispositionReport, the custodial node will submit into the replication stream a changeRecordNewData providing in the operationalInfo, the nodeID accepting custody of the datum and the authorizedName of the publisher accepting ownership. The acknowledgmentRequested attribute of this change record MUST be set to “true”.

Finally, the custodial node invalidates the transferToken in order to prevent additional calls of the transfer_entities API.

5.4.7.4 Caveats

If an error occurs in processing this API call, a dispositionReport structure MUST be returned to the caller in a SOAP Fault. See Section 4.8 Success and Error Reporting.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_transferNotAllowed: signifies that the transfer of one or more entities has been rejected by the custodial node.  Reasons for rejection include expiration of the transferToken and attempts to transfer a set of entities that does not match the one represented by the transferToken. The reason for rejecting the custody transfer SHOULD be clearly indicated in the error text.

·         E_invalidKeyPassed: signifies that one of the uddiKey values passed for entities to be transferred did not match with any known businessKey or tModelKey values. The key and element or attribute that caused the problem SHOULD be clearly indicated in the error text.

5.4.8 Security Configuration for transfer_custody

The use of mutual authentication of UDDI nodes in conjunction with the transfer_custody API is RECOMMENDED. This MAY be achieved using mutual X.509v3 certificate-based authentication as described in the Secure Sockets Layer (SSL) 3.0 protocol.  SSL 3.0 with mutual authentication is represented by the tModel uddi-org:mutualAuthenticatedSSL3 as described within Section 11.3.2 Secure Sockets Layer Version 3 with Mutual Authentication.


 

5.5 Subscription API Set

Subscription provides clients, known as subscribers, with the ability to register their interest in receiving information concerning changes made in a UDDI registry.  These changes can be scoped based on preferences provided with the request.  The APIs described below support this capability.  Usage scenarios and examples are provided in Appendix C Supporting Subscribers.  Each of the subscription APIs described here are OPTIONAL for UDDI implementations and MAY be implemented entirely at the discretion of a Node.

5.5.1 About UDDI Subscription API functions

The subscription API set satisfies a variety of requirements.  The flexibility of the subscription API allows monitoring of activity in a registry by registering to track new, changed and deleted entries for each of these entities:

·         businessEntity

·         businessService

·         bindingTemplate

·         tModel

·         related businessEntity

·         publisherAssertion (limited to those publisherAssertions for which the subscriber owns at least one of the businesses referenced)

With the exception of single publisher registries subscription typically is limited to authorized clients as a matter of node policy.  Therefore, subscribers MUST typically authenticate with the node before saving subscription requests.  Individual nodes, including those in the UDDI Business Registry, MAY establish policies concerning the use of the subscription APIs they choose to offer. Such policies might include restricting the use of subscription, defining which APIs are supported, establishing whether subscriptions require authentication, defining special rules affecting different classes of subscriptions, or even imposing fees for the use of these services.  The use of the authInfo argument is OPTIONAL throughout the subscription APIs, although registries which support multiple users or which require authentication for publishing operations typically require it. 

Subscription allows subscribers to “monitor” a particular subset of data within a registry.  Two patterns are defined.  Nodes MAY support either or both:

·         Asynchronous notification – subscribers choose to be asynchronously notified by the node when registry data of interest changes via calls to the notify_subscriptionListener API, which they implement as a “subscription listener” service.

·         Synchronous change tracking – subscribers issue a synchronous request using the get_subscriptionResults API to obtain information on activity in the registry which matches their subscription preferences.

A subscription request establishes criteria for the subscription and specifies how and if the subscriber is to be notified of changes matching the specified criteria.  Any of the existing standard inquiry APIs (find_xx and get_xx) may be used within a subscription request to define the criteria, although nodes are free to restrict which inquiry APIs are supported in subscription as a matter of policy.  The duration, or life of a subscription is also a matter of node policy, but subscribers can renew existing subscriptions periodically instead of having to create new ones.  Subscribers may also create multiple subscriptions.  Each subscription request is treated independently.  The level of detail provided for the data returned is controlled by the subscription request.

When asynchronous notifications are requested, subscriptions provide information on new, changed or deleted entities within a registry that occur after the point in time that the subscription is registered.  A node notifies subscribers based upon its identification of data matching the requested subscription criteria.  Subscribers can choose to have these notifications provided via email or an HTTP/SOAP-based Web service, which the subscriber MAY implement. Such services are called “subscription listeners.”  Notifications are made periodically rather than in response to the continuous stream of changes that normally occur within the registry.  This means that subscription results provided via notifications pertain only to the current state of the entities at the time they are reported – intermediate state changes are not provided.  While subscribers can specify a frequency for these notifications, nodes MAY choose to restrict this as a matter of policy.

When synchronous requests are made for subscription results, the current state of the registry data, which matches the subscription criteria, is returned for entries that were last created, changed or deleted within a specified date range.  Prior states of the registry data are not available and are not returned.

Subscriptions are owned by the subscriber who creates them.  A subscriptionKey, which distinguishes each individual subscription, is not visible to anyone except the subscriber.  While node policy MAY permit others besides the subscription’s owner to receive or retrieve subscription results, such interested parties require knowledge of the relevant subscriptionKey from the subscription owner in order to do so.

5.5.1.1 Definition of Changed Entities

As stated above, the subscription API allows monitoring of new, changed and deleted entities. This section provides the definition of changed entities.  The following are the criteria for considering an entity to have been “changed”:

·         For businessEntity, businessService, bindingTemplate, and tModel:
The entity is considered to be changed if the modifiedIncludingChildren element of the operationalInfo element of the entity has been changed.

·         For publisherAssertion:
A publisherAssertion is considered to be changed if the publisher has updated the publisherAssertion via the set_publisherAssertions,  or add_publisherAssertions APIs.

·         For related businessEntity:
A related businessEntity (related to the business specified in the businessKey argument of find_relatedBusinesses API) is considered to be changed if either:

1.       the related businessEntity is changed, or

2.       at least one of the two reciprocal publisherAssertions that represents the relationship is changed.

5.5.2 Specifying Durations

Time durations used in the subscription APIs are of type xsd:duration defined in XML Schema from [ISO 8601].  Any form supported by this data type is permitted.  For example, the lexical representation extended format can be used, which is of the form PnYnMnDTnHnMnS, where nY represents the number of years, nM the number of months, nD the number of days, 'T' is the date/time separator, nH the number of hours, nM the number of minutes and nS the number of seconds. The “P” identifies the field as duration.  The number of seconds can include decimal digits to arbitrary precision.

5.5.3 Specifying Points in Time

Points in time used in the subscription APIs are all of the XML Schema type, xsd:dateTime.  Two points in time are used to specify a period of time.

5.5.4 Subscription Coverage Period

The APIs, which support each of the patterns previously described for obtaining subscription results, accept a coveragePeriod argument, which is composed of two points in time.  Each of these corresponds to the last point in time which any given entity in the registry was modified (i.e., created, deleted or changed).  The syntax of this element is:

Where:

·         startPoint: Signifies the point in time after which subscription results are to be collected and/or returned. The startPoint is optional. If it is not specified, this indicates that all available results are to be returned from the beginning of the registry.

·         endPoint:  Signifies the point in time corresponding to the last activity date for entities matching subscription results.  No activity among matching entities, which occurred after this point in time, is returned. The endPoint is optional. If not provided, it signifies that the latest changes available, which match the subscription criterions that are to be returned.

With respect to notifications, the startPoint of a given notification SHOULD align with the endPoint of the previous notification.  If this is not the case, the subscriber SHOULD assume a notification was missed, or lost.  The subscriber can then take corrective action by using the get_subscriptionResults API. Note that it is permissible for nodes to send the same data more than once, depending on overlaps in these times.

5.5.5 Chunking of Returned Subscription Data

If a subscriber specifies a maximum number of entries to be returned with a subscription and the amount of data to be returned exceeds this limit, or if the node determines based on its policy that there are too many entries to be returned in a single group, then the node SHOULD provide a chunkToken with results.  The chunkToken is a string based token which is used by the node to maintain the state of the subscription results for a particular caller, when these results are chunked across multiple responses.  The format and content of the chunkToken is a matter of implementation choice by individual nodes. The chunkToken returned with a particular subscription result set SHOULD be used to retrieve subsequent results when subscription results are requested in a synchronous manor.  If no more results are pending, the value of the chunkToken MUST be “0”.

A chunkToken is intended as a short-term aid in obtaining contiguous results across multiple API calls and is therefore likely to remain valid for only a short time.  Nodes MAY establish policies on how long a chunkToken remains valid.

5.5.6 Use of keyBag in Subscription

The subscription results returned by the subscription APIs allow for the use of a structure called a keyBag.  A keyBag contains a list of entity keys, which correspond to any of the core data structures (businessEntity, businessService, bindingTemplate or tModel).  The keyBag has two uses. 

·         Returning results when a “brief” format is selected, which minimizes returned information. 

·         Indicating entities which have been deleted, or which no longer match the subscription criteria provided with the subscription.  This later situation is referred to as a “virtual delete”, in that the entity in question may not actually have be deleted from the registry, but it no longer matches the criterion which the subscriber defined in the subscription for tracking registry changes.  It should be noted that nodes MUST maintain information pertaining to registry changes for both forms of deletion, to be reported with subscription results for applicable subscriptions, although they MAY establish policies on how long such information is retained. Further details on the use of this structure are discussed in the relevant API sections that follow.  When the keyBag is used for deleted entities, the deleted element is set to “true,” and all entities listed in such a keyBag are assumed to represent deletions.

A UDDI node MUST never inform the subscriber of an entity that temporarily matched the subscription criteria but was removed or modified to no longer match the subscription criteria before the subscriber was informed of the match.

A UDDI node MAY inform a subscriber about the real or virtual deletion of an entity multiple times.

The syntax of a keyBag is shown here:

5.5.7 Subscription API functions

The APIs in this section describe how to interact with a UDDI node implementation to create and manage requests for the tracking of new and changed registry content.  These APIs are synchronous and are exposed via SOAP, although the notifications they may generate are not. 

The subscription APIs are:

·         delete_subscription:  Cancels one or more specified subscriptions.

·         get_subscriptionResults:  Synchronously returns registry data pertaining to a particular subscription within a specified time period.

·         get_subscriptions:  Returns a list of existing subscriptions previously saved by the subscriber.

·         save_subscription:  Establishes a new subscription or changes an existing one.  Also used to renew existing subscriptions.

The OPTIONAL client API is:

·         notify_subscriptionListener: A node invoked API which the client implements as a subscription listener service to accept notifications containing the data that changed since notify_subscriptionListener was last invoked for a particular subscription.

5.5.8 save_subscription

The save_subscription API registers a request to monitor specific registry content and to have the node periodically notify the subscriber when changes are available.  Notifications are not returned synchronously with results for this API.  Only data that matches the requested subscription criteria and which changes after the point in time that the subscription request is accepted is returned to the subscriber via a notification.

This API returns a duration for which this particular subscription is valid.  Depending upon the policy of the Node, subscriptions need to be renewed before the expiration date in order to insure that they remain active.  Subscriptions can also be redefined or renewed using this API.  The subscriptionKey pertaining to the subscription to be renewed must be supplied in the save_subscription invocation in order to accomplish this. This allows both renewal and changes to the subscription.  Invoking save_subscription automatically resets the expiration period for the subscription in question to a value based upon the node’s policy.

5.5.8.1 Syntax:

The syntax of the subscription structure is:

Attributes

Name  

Use  

brief  

optional  

 


 

The syntax of the subscriptionFilter structure is:

5.5.8.2 Arguments:

·         authInfo:  This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can save a subscription typically require authInfo for this call, though this is a matter of node policy.

·         bindingKey:  This optional argument of type anyURI specifies the bindingTemplate which the node is to use to deliver notifications to subscription listeners.  It is only required when asynchronous notifications are used.  This bindingTemplate MUST define either a Web service that implements notify_subscriptionListener (see below), or an email address to receive the notifications. If a notify_subscriptionListener Web service is identified, the node invokes it to deliver notifications.  If an email address is identified, the node delivers notifications via email to the address supplied. When notifications are delivered via email, the body of the email contains the body of the SOAP message, which would have been sent to the notify_subscriptionListener service if that option had been chosen.. The publisher making the subscription request MUST own the bindingTemplate.  If this argument is not supplied, no notifications are sent, although subscribers may still use the get_subscriptionResults API to obtain subscription results.  See Section 5.5.11 get_subscriptionResults for details.  If email delivery to the specified address fails, nodes MAY attempt re-delivery, but are not obligated to do so.  Depending upon node policy, excessive delivery failures MAY result in cancellation of the corresponding subscription.

·         brief:  This optional argument controls the level of detail returned to a subscription listener.  The default is “false” when omitted. When set to “true,” it indicates that the subscription results are to be returned to the subscriber in the form of a keyBag, listing all of the entities that matched the subscriptionFilter.  Refer to Section 5.5.6 Use of keyBag in Subscription, for additional information.  This option has no effect on the assertionStatusReport structure, which is returned as part of a notification when the subscriptionFilter specifies the get_assertionStatusReport filter criteria.  See the explanation of subscriptionFilter below.

·         expiresAfter:  This optional argument allows subscribers to specify the period of time for which they would like the subscription to exist.  It is of the XML Schema type xsd:dateTime.  Specifying a value for this argument is no guarantee that the node will accept it without change.  Information on the format of expiresAfter can be found in Section 5.5.1.1 Specifying Durations.

·         maxEntities:  This optional integer specifies the maximum number of entities in a notification returned to a subscription listener. If not specified, the number of entities sent is not limited, unless by node policy.

·         subscriptionFilter:  This argument specifies the filtering criteria which limits the scope of a subscription to a subset of registry records. It is required except when renewing an existing subscription. The get_xx and find_xx APIs are all valid choices for use as a subscriptionFilter.  Only one of these can be chosen for each subscription.  Notifications, based on the subscriptionFilter, are sent to the subscriber if and only if there are changes at the node, which match this criterion during a notification period.  A subscriptionFilter MUST contain exactly one of the allowed inquiry elements. The authInfo argument of the specified get_xx or find_xx API call is not required here and is ignored if specified.  All of the other arguments supported with each of these inquiry APIs are valid for use here.

Specifying find_relatedBusinesses is useful for tracking when reciprocal relationships are formed or dissolved.  Specifying get_assertionStatusReport can be used in tracking when reciprocal relationships (which pertain to a business owned by the subscriber) are formed, dissolved, or requested by the owners of some other business.

·         subscriptionKey:  This optional argument of type anyURI identifies the subscription.  To renew or change an existing subscription, a valid subscriptionKey MUST be provided. When establishing a new subscription, the subscriptionKey MAY also be either omitted or specified as an empty string in which case the node MUST assign a unique key. If subscriptionKey is specified for a new subscription, the key MUST conform to the registry’s policy on publisher-assigned keys.

·         notificationInterval:  This optional argument is only required when asynchronous notifications are used.  It is of type xsd:duration and specifies how often change notifications are to be provided to a subscriber.  If the notificationInterval specified is not acceptable due to node policy, then the node adjusts the value to match the next longer time period that is supported.  The adjusted value is provided with the returns from this API.  Also see Section 5.5.1.1 Specifying Durations.

5.5.8.3 Returns:

Upon successful completion this API returns a subscriptions structure.  Included in the subscription structure(s) it MUST contain is a subscriptionKey (of type anyURI) that is used by the subscriber to manage the subscription.   This key is required in order to delete (unsubscribe), modify or renew the subscription.   If a subscriber has multiple subscriptions, the subscriptionKey can be used to distinguish between different subscriptions.  The subscriptionKey is also part of the data contained in the notifications returned to subscription listeners. 

 

The subscription structure(s) returned from this API, MUST each contain an expiresAfter value, which has been assigned by the node.  Nodes SHOULD attempt to honor the value(s) provided with the save_subscription request, but MAY modify them based on node policy.    Depending upon the node’s policy, the node MAY delete a subscription after it has expired.

The value of the notificationInterval included in the subscription structure(s) returned MAY be adjusted by the node to the value closest to that requested which is supported by its policies. Depending upon the Registry’s workload a node MAY skip a notification cycle.  If a cycle is skipped, the next notification sent SHOULD include information based on registry activity, which has occurred since the last notification was issued.

5.5.8.4 Caveats:

If any error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: signifies that an entity key value passed did not match with any known key values.  The error structure signifies that the condition occurred and the error text clearly calls out the offending key.

·         E_unsupported: signifies that one of the argument values was not supported by this implementation. The offending argument is clearly indicated in the error text.

·         E_resultSetTooLarge: signifies that the node refuses to accept the subscription because it deems that result sets associated with the subscription are too large.  The subscription criteria that triggered this error should be refined and re-issued.

·         E_accountLimitExceeded: signifies that the request exceeded the quantity limits for subscription requests, based on node policy.

·         E_userMismatch: signifies that an attempt has been made to use the subscription API to change a subscription that is controlled by another party. Or that the bindingTemplate specified does not belong to the publisher.

·         E_requestDenied: signifies that the subscription cannot be renewed. The request has been denied due to either node or registry policy.

5.5.9 delete_subscription

Cancels an existing subscription.

5.5.9.1 Syntax:

 

5.5.9.2 Arguments:

·         authInfo:  This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can delete a subscription typically require authInfo for this call, though this is a matter of node policy.

·         subscriptionKey:  This required argument specifies, using anyURIs, the subscription or subscriptions to be deleted.

5.5.9.3 Returns:

If no errors occur, then E_success and a successful dispositionReport are returned.

 

5.5.9.4 Caveats:

If an error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_userMismatch: signifies that an attempt has been made to use the subscription API to delete a subscription that is controlled by another party.

·         E_invalidKeyPassed: signifies that the subscriptionKey is invalid or that the subscription has expired.

5.5.10 get_subscriptions

Returns the complete list of existing subscriptions owned by the subscriber.

5.5.10.1 Syntax:

5.5.10.2 Arguments:

·         authInfo:  This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can obtain information on subscriptions typically require authInfo for this call, though this is a matter of node policy.

5.5.10.3 Returns:

This API call returns information on all of the subscriptions owned by the subscriber, together with the expiration date for each.  The subscriptions structure returned contains one or more subscription structures, each pertaining to a subscription.  Only subscriptions created by the invoking subscriber are returned. See Section 5.5.8.1, [save_subscription] Syntax, for details on these structures.

5.5.10.4 Caveats:

If any error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.  There is no specific error information, other than the errors common to all APIs.


 

5.5.11 get_subscriptionResults

This API allows a subscriber to request that the information pertaining to an existing subscription be returned.  This is useful, for example, to obtain historical data when a subscription is first set up or when a subscriber misses the notification normally provided by the registry.  The results are returned synchronously as the response to this call.  The get_subscriptionResults API can also be used as an alternative to notifications for obtaining subscription data. If this is the preference, then the subscriber SHOULD not provide a bindingKey when saving the associated subscription. See Section 5.5.8 save_subscription.  This API is not affected by the value of the notificationInterval in the subscription.

5.5.11.1 Syntax:

5.5.11.2 Arguments:

·         authInfo:  This optional argument is an element that contains an authentication token.  Registries that wish to restrict who can retrieve subscription data typically require authInfo for this call, though this is a matter of node policy.

·         chunkToken:  This optional argument is used to retrieve subsequent groups of data when the first call to this API indicates more data is available.  This occurs when a chunkToken is returned whose value is not “0” in the subscriptionResultsList structure described in the next section. To retrieve the next chunk of data, the value returned should be used as an argument to the next invocation of this API.

·         coveragePeriod: This structure defines the time period over which the most recent changes in node data are compared with the subscription criteria in order to produce the result set. It provides start and end date/time information according to the format described in Section 5.5.4 Subscription Coverage Period.  The “current” state of registry entries pertaining to the subscription referenced by the subscriptionKey provided are returned if they were last created, changed or deleted during the specified time period.

·         subscriptionKey:  This required argument of type anyURI identifies the subscription for which non-recurring synchronous results are being sought.

5.5.11.3 Returns:

A subscriptionResultsList is returned whose content is determined by the coveragePeriod and the criteria in the subscription:

Attributes

Name  

Use  

someResultsUnavailable  

optional  

 

Subscription results MAY be chunked.  See Section 5.5.5 Chunking of Returned Subscription Data, for more information on chunking of results.  If results are chunked, then subsequent “chunks” can be retrieved using the chunkToken returned as an argument in a subsequent invocation of this API.

Note that the results returned in the subscriptionResultsList represent a snapshot of the current state of relevant entries in the registry.  They are non-transactional in nature and prior states cannot be returned.  Deleted entities and virtual deletes of entities, which have been changed in such a way that they no longer match the subscription criterion saved with the subscription, are returned only in the form of a keyBag structure, for which the deleted element is set to “true”. A UDDI node MAY inform a subscriber about the real or virtual deletion of an entity multiple times.

The someResultsUnavailable attribute is set to “true” whenever the node has found it necessary to flush subscription results information pertaining to entity deletions (either actual or virtual) which pertain to this subscription, which have not yet been reported through prior calls to this API, or through use of the notify_subscriptionListener API described below.  The period of time which a node retains information on deletions for a given subscription is a matter of node policy.

 

5.5.11.4 Caveats:

If an error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_invalidKeyPassed: signifies that the subscriptionKey is invalid or that the subscription has expired.

·         E_invalidValue:  signifies that the chunkToken value supplied is either invalid or has expired.

·         E_unsupported: signifies that one of the argument values was not supported by this implementation. The offending argument is clearly indicated in the error text.

·         E_userMismatch: signifies that, in a violation of node policy, an attempt has been made to use the subscription API to change a subscription that is controlled by another party.

·         E_invalidTime:  signifies that one or both of the values provided in the coveragePeriod range is invalid or does not define a range.  The error structure signifies the condition that occurred and the error text clearly calls out the cause of the problem.


 

5.5.12 notify_subscriptionListener

This API, when implemented by a subscriber and specified in a subscription, enables the node to deliver notifications to subscription listeners by invoking a Web service.  New, modified, and deleted data that matches the subscription is passed to notify_subscriptionListener. If the brief attribute of the subscription is “true”, then only the relevant keys will be sent; full details of the changed data can be accomplished via the standard get_xx API’s if required.  If a particular item that matches the subscription criteria is deleted during the notificationInterval, or is changed in such a way that it no longer matches the criterion defined for the subscription, then these entities are included in a keyBag containing a deleted element with a value of “true”.

To allow subscribers to determine whether a notification has been lost, the coverage period of the notification is included.  A date/time indicating the date/time values corresponding to the start and end points of this is provided.  The start date/time used in this call SHOULD align with the end date/time of the previous call and so fourth. 

If the maxEntities option was specified in the save_subscription call, the response supplied via this call is limited to that number of entities.   If the node cannot send all of the results in a single notify_subscriptionListener call, then the node repeatedly invokes the notify_subscriptionListener service until all information has been transmitted.   In no case will the data sent to notify_subscriptionListener exceed the maximum message size per the policy of the node.

5.5.12.1 Syntax:

 

5.5.12.2 Arguments:

·         authInfo:  This optional argument is an element that contains an authentication token.  Subscription listener services that wish to restrict who can transmit subscription data MAY require authInfo for this call, though this is a matter of client policy.

·         subscriptionResultsList:  This list contains the results for this notification, which consist of the result structures which are normally returned for standard find_xx or get_xx APIs, based upon the criteria saved in the subscriptionFilter for the subscription which is generating this notification. Note that the chunkToken is not returned with this structure for this API.  The subscriptionResultsList also contains a coveragePeriod structure which defines the time period over which the node data is compared with the subscription criterion in order to produce the result set. It provides the start and end date/time information according to the format described in Section 5.5.4 Subscription Coverage Period.  The “current” state of registry entries pertaining to the subscription referenced by the subscriptionKey provided are returned if they were last changed during the specified time period. See Section 5.5.11.3 Returns for more information on the subscriptionResultsList’s content.

5.5.12.3 Returns:

Upon successful completion, notify_subscriptionListener returns a dispositionReport indicating E_success.   Note that this is being returned by the client supported API.

5.5.12.4 Caveats:

If an error occurs in processing this API call, a dispositionReport structure is returned to the caller in a SOAP Fault.  In addition to the errors common to all APIs, the following error information is relevant here:

·         E_fatalError:  signifies the client’s failure to receive notification data.   The node is not obligated to retry.


5.6 Value Set API Set

Whenever a keyedReference is involved in a save operation it may be checked to see that it is valid.  Similarly, a keyedReferenceGroup element that is involved in a save operation may also be checked to ensure that it is valid.  Checking is performed for tModels that are deemed to be "checked", as determined by the policy of the UDDI registry.

UDDI provides the ability for third parties to register value sets, and then control the validation process used by UDDI to perform such checks. UDDI registries MAY support caching of these external value sets.  UDDI registries MAY also support external validation.  Node and registry policies determine the manner in which validation of references to external value sets is performed.  The APIs in this section can be used by UDDI registries and nodes in their validation policies.

Third parties that want to provide an external checking capability may be required by the UDDI registry to implement a Web service in the same manner that UDDI does (e.g. using SOAP for message passing using literal encoding) that exposes a single method named validate_values.  The interface for validate_values is described here.

In some cases a node may desire to eliminate or minimize the number of calls to external validation Web services.  It can do so by caching valid values for those external value sets that allow caching of their values.  A node has two normative options for obtaining the set of valid values.  One is to periodically obtain the set of valid values from those value set providers that implement a Web service that handles the get_allValidValues API.  This API is described below.  The other method of obtaining a cache of valid values is to accumulate the valid values from successful calls to validate_values.

5.6.1 Value Set Programming Interfaces

The Application Programming Interfaces in this section represent capabilities that a UDDI registry MAY use to enable validation of references to value sets.  Registry policy determines which external value sets are supported and how.  See Section 9.4.19 Value Set Policies and Section 9.6.5Value Sets for more information on registry support of external value sets.  These SOAP messages all behave synchronously.

The publicly accessible APIs that are used to support external value set validation are:

·         validate_values: Used by nodes to allow external providers of value set validation Web services to assess whether keyedReferences or keyedReferenceGroups are valid.  Returns a dispositionReport structure.

·         get_allValidValues: Used by nodes that support caching of valid values from cacheable checked value sets to obtain the set of valid values.  Returns a validValuesList structure.

Registry policy may require value set providers that offer one of these Web services to publish the bindingTemplate for the service and the tModel for the value set in a particular way so that the proper Web service can be discovered.  See Section 9.6.5 Value sets for more information.  When a value set provider offers one of these Web services, a tModel for the checked value set SHOULD be published in any registry the provider wishes to offer it, and a bindingTemplate SHOULD be published for the Web service(s) the value set provider offers for the checked value set.  The tModel SHOULD have categorizations from the uddi-org:types category system to indicate the type of value set (categorization, identifier, relationship, categorizationGroup), that it is checked (checked), and, if the value set provider allows validation to occur against node caches of valid values, the cacheable categorization should also be provided.  The tModel should also have a categorization reference to the bindingTemplate of the get_allValidValues or validate_values Web service that the value set provider designates, using the uddi-org:validatedBy category system.  See Section 11.1.1 UDDI Types Category System and Section 11.1.7 Validated By Category System for more information.

The bindingTemplate for the get_allValidValues or the validate_values Web service SHOULD reference in its tModelInstanceDetails the appropriate value set API tModel (Section 11.2.7 Value Set Caching API tModel or Section 11.2.8 Value Set Validation API tModel) as well tModels for all of the value sets the service applies to. 

5.6.2 validate_values

A UDDI node that supports external validation sends the validate_values API to the appropriate external Web service, of which there is exactly one, whenever a publisher saves data that uses a keyedReference or keyedReferenceGroup whose use is regulated by the external party who controls that Web service. For purposes of discussion, the identifier, category, and relationship type systems that the keyedReference elements refer to are called checked value sets. The category group systems that the keyedReferenceGroup elements refer to are similarly called checked category group systems. 

The normal use for checked value sets is to verify that specific values (checking the keyValue attribute of values supplied) exist within the value set.  For certain value sets the value set provider may further restrict the use of a value based on a contextual evaluation of the passed data.  The provider may do enable this contextual checking by offering a validation Web service.

Validation algorithms for checked category group systems similarly verify that the contents of the keyedReferenceGroup elements form a valid set according to the validation algorithm for the checked category group system.  Frequently such validation ensures that the value sets identified in contained keyedReferences are allowed to participate in the category group system.

5.6.2.1 Syntax:

 

5.6.2.2 Arguments:

The UDDI node that is calling validate_values MUST pass one or more businessEntity elements, one or more businessService elements, one or more bindingTemplate elements, one or more tModel elements, or one or more publisherAssertion elements as the sole argument to this Web service.  The one or more elements passed represents the outermost UDDI data structure(s) being passed within a save_business, save_service, save_binding, save_tModel, add_publisherAssertion, or set_publisherAssertions API call.  Multiple elements of the same type may be passed together if multiples are included in the same save invocation.

The optional authInfo argument is an element that contains an authentication token.  An authentication token is obtained using the get_authToken API call or through some other means external to this specification.  Providers of validate_values Web services that serve multiple registries and providers that restrict who can use their service may require authInfo for this API.

5.6.2.3 Behavior

The called Web service for a checked value set performs validation on all of the keyedReferences or keyedReferenceGroups that are associated with the value sets the Web service is authorized to check.  This can involve merely checking that the keyValue values supplied are good for the given value set (as signified by the embedded keyedReference tModelKey values). Other types of validation as desired may be performed, including context sensitive checks that utilize the information passed in the entity being saved.

The entity being saved may contain multiple references to values from the value set(s) that the validation Web service is authorized to validate.  When the entity being saved is a businessEntity, contained businessService and bindingTemplate entities may themselves reference values from the authorized value sets as well.  All references to values that are associated with the value set(s) that the validation Web service is authorized to check MUST be validated without regard to their placement in the entity being saved.

If the external value set and the node both support caching of valid values, the node may not invoke validate_values if it already knows that the referenced values are valid, through checking its cache.

A checked category group system is treated in the same manner as a checked value set.  The tModelKey associated with the keyedReferenceGroup identifies the checked category group system. A node may be able to validate a reference to a cacheable checked category group system without calling validate_values if it can determine using its cache that the tModelKey attributes from the keyedReference elements contained in the keyedReferenceGroup are allowed for the category group system.

5.6.2.4 Returns:

If all values referenced in the entity being saved are valid from the value set(s) or category group system(s) that the validation Web service is authorized to validate, the proper response is a dispositionReport structure as specified in Section 4.8 Success and Error Reporting.  The error code value returned MUST be E_success and the errno value in the result MUST be "0". 

5.6.2.5 Caveats:

If any error is found, or the called Web service needs to signal that the information being saved is not valid based on the validation algorithm chosen by the external Web service provider, then the Web service MUST raise a SOAP Fault as specified in Section 4.8 Success and Error Reporting.

When an error is signaled in this fashion, the UDDI node MUST reject the pending change and return to the original caller the same SOAP fault data returned by the validation Web service.  The error codes indicate one of the following reasons, and the error text clearly indicates the keyedReference or keyedReferenceGroup data that is being rejected and the reason it is being rejected.

·         E_invalidValue: One or more of the keyValues in the keyedReference or keyedReferences in the keyedReferenceGroup supplied failed validation.  Only the first error encountered need be reported.

·         E_valueNotAllowed: The values may be valid, but are not allowed contextually.

5.6.3 get_allValidValues

A UDDI node that supports external value sets MAY invoke a get_allValidValues Web service offered by a value set provider that has granted permission to that registry to cache the valid values for that value set.  The external value set provider MAY offer the get_allValidValues Web service and the UDDI node MAY use it.  The normal use is to return a full set of valid values for the identified value set.  If the value set provider determines there are too many values to return in one chunk, the set of valid values may be returned in chunks.

Registry policy may require the value set provider that offers a get_allValidValues Web service to republish its value set tModel when the cache should be re-acquired by participating nodes.  See Section 9.6.5 Value Sets for more information.

get_allValidValues can similarly be used to obtain the set of tModelKeys for value sets that can participate in a cached category group system.

5.6.3.1 Syntax:

5.6.3.2 Arguments:

·         tModelKey:  A required uddiKey value that identifies the specific instance of the tModel which describes the value set or category group system for which a Web service to get all valid values has been provided.  It uniquely identifies the category, identifier, or category group system for which valid values are being requested.

·         chunkToken:  Optional element used to retrieve subsequent groups of data when the first invocation of this API indicates more data is available.  This occurs when a chunkToken is returned whose value is not “0” in the validValuesList structure described in the next section.  To retrieve the next chunk of data, the chunkToken returned should be used as an argument to the next invocation of this API.

·         authInfo: An optional element that contains an authentication token.  Authentication tokens are obtained using the get_authToken API call or through some other means external to this specification.  Providers of get_allValidValues Web services that serve multiple registries and providers that restrict who can use their service may require authInfo for this API.

 

5.6.3.3 Returns

A validValuesList structure is returned containing the set of valid values for the external category or identifier system.  The list MUST contain a chunkToken if the Web service provider wishes to provide the data in packets.  The validValuesList has the form:

And its contained validValue element has the form:

5.6.3.4 Behavior

The called Web service returns the set of valid values in a validValuesList on success.  This structure lists every valid value associated with the value set or category group system that is described by the tModelKey provided.  In the event too many values exist to be returned in a single response (i.e., the message size exceeds the maximum number of bytes allowed by the UDDI registry), or the value set provider wants to supply the values in multiple packets, then the validValueList includes the chunkToken element and the API can be re-issued to get the remaining valid values.

5.6.3.4.1 Chunking of valid values

If the value set provider determines that there are too many values to be returned in a single group, then the provider SHOULD provide a chunkToken with the results.  The chunkToken is a string based token which is used by the value set provider to maintain the state of the set of values for a particular caller, when these results are chunked across multiple responses.  Providers should establish their own policies for determining the content and format of the chunkToken. The chunkToken returned with a particular value set result set SHOULD be used to retrieve subsequent results.  If no more results are pending, the value of the chunkToken will be “0” or the chunkToken will be absent. 

A chunkToken is intended as a short-term aid in obtaining contiguous results across multiple API calls and is therefore likely to remain valid for only a short time.  Value set providers may establish policies on how long a chunkToken remains valid.

5.6.3.5 Caveats:

If any error occurs in processing this API, a dispositionReport structure MUST be returned to the caller in a SOAP Fault.  See Section 4.8 Success and Error Reporting.  The following error information is relevant:

·         E_invalidKeyPassed: Signifies that the tModelKey passed did not match with the uddiKey of any known tModels.  The details on the invalid key SHOULD be included in the dispositionReport element.

·         E_noValuesAvailable: Signifies that no values could be returned.

·         E_unsupported: Signifies that the Web service does not support this API.

·         E_invalidValue: Signifies that the chunkToken value supplied is either invalid or has expired.

 

 


 

6      Node Operation

This chapter defines the normative behavior required of an operator hosting a UDDI node.  It outlines the operational parameters and requirements that a node MUST follow.  It also provides guidance when first bringing a node online. The intended audience for this chapter is someone intending to implement and host a UDDI node.

Note that this chapter alone is not sufficient to understand how to implement and host a node.  Refer to each of the preceding chapters, in order to understand the full scope of the UDDI specification. They provide the normative behavior in terms of how the APIs work.  Considerations regarding intra-registry operation (such as replication between nodes) and inter-registry operation (such as publishing data across multiple registries) are dealt with in Chapter 7 Inter-Node Operation and Chapter 8 Publishing Across Multiple Registries respectively.  Also, node implementers must be cognizant of the policy decisions that they must make; the list of policy-related decisions can be found in Chapter 9 Policy.

This chapter addresses only the operational specifics that must be followed when hosting a node, regardless of whether that node exists as the sole node in a registry or takes part in a multi-node environment.

6.1 Managing Node Contents

This section provides procedures and requirements for managing and maintaining the information within the UDDI registry.

6.1.1 XML Requirements

Given the use of XML, XML Schema, SOAP, and XML-Dsig within UDDI, a node must take care to adhere to these standards when processing data.  Specific additional requirements layered upon these standards are included in the UDDI specification.  Each node is responsible for implementing these additional requirements as well as those defined by the published standards. 

6.1.1.1 Processing by XML Schema Assessment

UDDI nodes MUST assess the validity of the XML elements that comprise the API requests they receive. This SHOULD be carried out by means of appealing to the 2nd or 3rd approaches enumerated in Section 5.2 Assessing Schema-Validity of XML Schema Structures (http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/#validation_outcome). API request elements which, having been so assessed are not found to have a [validity] property (http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/#sic-e-outcome) of valid, MUST not be further processed by the node.  An indication of this fact MUST be reported to the client by returning an error.

Note that a side effect of processing by XML Schema Assessment is that whitespace in elements and attributes is normalized (http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/section-White-Space-Normalization-during-Validation) in a well-defined manner.

6.1.1.2 Normalization and Canonicalization

UDDI registries provide publishers with the ability to digitally sign entities they publish, and inquirers with the ability to validate the digital signatures on published material. In order for this to be possible, publishers and registries MUST handle “normalization” and “canonicalization” as described in Section 4.6.1.1 Normalization and Canonicalization.

6.1.2 Key Generation and Maintenance

At the core of the UDDI specification is the ability to uniquely identify entities in a UDDI registry. 

6.1.2.1 Key Uniqueness

Each key stored by a node must be verified to be unique.  The node must not allow the generation or storage of a key that is already present somewhere in the registry.  This applies to both the node where the entry was originally saved, and, in the event the node is a part of a multi-node registry, any other node in the registry.  See Section 4.4 About uddiKeys for an extensive discussion around considerations in key generation and Chapter 9 Policy for more on policy decisions a node must make around key generation.

6.1.2.2 Node Generated Keys

When a node generates a uuidKey for an entity, it must make certain that the process of creating these is a correct one. Nodes SHOULD use the time-based or random number based UUID generation algorithm as defined at http://uddi.org/pubs/draft-leach-uuids-guids-01.txt.

6.1.3 Updates and Deletions

When an entity that contains other entities is updated, the entire content of the updated entity, including contained entities, is replaced.  When making updates to the registered information, the integrity of the overall registry must be maintained.

In particular, when deleting information from the UDDI registry, the following atomicity must be maintained:

·         When the deletion of an entity occurs and that entity contains other entities (i.e., a businessService within a businessEntity), all contained entities MUST also be deleted. 

·         Any referenced entities (i.e., a tModel reference) MUST NOT be deleted. 

·         tModel deletion (more accurately described as deprecation or "hiding") behavior is different from that of the other UDDI entities.  The result of a tModel deletion request is that it is stored in a deprecated state. 

6.2 Considerations When Instantiating a Node

When first bringing a node online, several steps should be followed.

6.2.1 Canonical tModel Bootstrapping

A node MUST provide the canonical UDDI tModels (outlined in Chapter 11 Utility tModels and Conventions) for entities to reference.  The node MAY acquire these canonical tModels either through performing an import of these tModels, through participating in a replication topology or through other means. 

6.2.2 Self-Registration of Node Business Entity

6.2.2.1 Normative Modeling of Node Business Entity

A node MUST register itself in the UDDI registry of which it is a part, so that it can be uniquely distinguished within a registry.  This UDDI entry is known as the “Node Business Entity”. The node MUST categorize its Node Business Entity with the uddi:uddi.org:categorization:nodes tModel using the keyValue, “node”:

   <categoryBag>

       <keyedReference

          tModelKey="uddi:uddi.org:categorization:nodes”

          keyName=””

          keyValue="node"/>

   </categoryBag>

 

This checked category system is only permitted to be used by the node itself.  If another publisher attempts to save a categoryBag that has a reference to the “uddi:uddi.org:categorization:nodes” category system, the node MUST return an error.  This checking guarantees the ability to query a single node and determine all the nodes that participate in a given registry. 

6.2.2.2 Recommended Modeling of Node Business Entity

A node is composed of Web services that implement one or more UDDI API sets.  A node SHOULD model those Web services within its Node Business Entity.  The modeling of the Node Business Entity SHOULD include the following characteristics:

·         Each bindingTemplate that describes an implementation of a UDDI API set SHOULD use tModelInstanceInfos that reference the API tModels of the API sets the implementation supports (e.g., uddi-org:inquiry_v3).  See Chapter 9 Policy and Section 11.1.9 UDDI Registry API tModels.

·         Each bindingTemplate provided SHOULD model the transport protocols and security protocols supported by the implementation it describes.

·         Each bindingTemplate provided SHOULD model the policies of the given node.  One option is to provide those policies in a document that can be found via the overviewURL of the tModelInstanceInfo of a given bindingTemplate.  Another option is to model those policies using instanceParms, categorization schemes or other UDDI constructs.

Because the UDDI data model offers great flexibility in how the modeling of services is achieved and because the context in which a node might exist varies greatly, normative mandates on the modeling of a Node Business Entity are inappropriate.  However, it may be the policy of a given registry that each node participating in that registry must model its Node Business Entity according to a given template or pattern.

6.3 User Credential Requirements

6.3.1 Establishing User Credentials

A UDDI node MAY require users to establish an account with the node, before they are allowed to utilize some or all of the services at the node.  The process for registration is determined by policy and may be node-specific.

For registries or nodes that enforce a policy relating particular publishers as owners of particular datum, it is essential that there is a mechanism to identify the publisher of each entity published at the node.  Although this data is not reflected in the schema provided by UDDI, it should be stored and obtainable by a node for entities for which it has custody of. See Section 1.5.8 Data Custody and Section 1.5.6 Person, Publisher and Owner.

6.3.2 Changing Entity Ownership

A UDDI node SHOULD provide an interface to permit a user to transfer ownership of data it currently owns to another user within that node. An API for this procedure is given in Section 5.4 Custody and Ownership Transfer API.

6.4 Checked Value Set Validation

This section describes the normative node behavior with respect to value set references.  Much of the node behavior in this area is not normative, but  instead is driven by registry and node policy. 

For more on external validation checking, see Section 5.6 Value Set API and Chapter 9 Policy.

6.4.1 Normative behavior during saves

Every time a publisher saves an entity that has a keyedReference associated with a checked value set, the node MUST perform validation in a manner that is acceptable to the value set provider, or MUST reject the reference with an E_unsupported error code.  How a UDDI node determines that the referenced value set is checked, where that value set is hosted, locates and invokes the validation algorithm, determines that a validation algorithm is acceptable, and deals with unavailability of the validation algorithm is all driven by registry, and in some cases, node policy.

When a UDDI node encounters a reference to a checked value set that it validates it MUST:

·         Perform validation for each top-level entity being saved.

·         Inspect tModel references in categoryBag, identifierBag or publisherAssertion keyedReferences, and keyedReferenceGroups to determine if references are to be checked.

·         Fail the save when any keyedReference fails validation.

·         Pass along error information for E_ invalidValue and E_valueNotAllowed errors from the validation algorithm to the caller of the save operation.

·         Return E_unvalidatable if the validation algorithm is unavailable.

A UDDI node that encounters a keyedReference for a checked value set that it validates MUST do so using one of the following methods:

·         Invoke the validation algorithm once for each individual reference, or once for the for the collective set of references to all value sets that share the same validation algorithm

·         Perform validation itself on cached values for checked value sets that the value set provider has allowed to be cached.

·         Grandfather previously validated value references when the validation algorithm is not available such that existing keyedReferences are considered still valid and are not re-checked while the validation algorithm is unavailable.  Nodes MAY allow previously validated keyedReferences associated with that unavailable value set to be (re)published without failing the save (e.g. the references are grandfathered and remain valid even though they can't be checked).  This gives nodes the opportunity to not penalize those publishers that attempt to reference a value set marked unvalidatable.  However, new value references an unavailable value sets MUST be rejected.

6.5 HTTP GET Services for UDDI Data Structures

A node may offer an HTTP GET service for access to the XML representations of UDDI data structures. If a node offers this service, the URLs should be in a format that is predictable and uses the entity key as a URL parameter.

The RECOMMENDED syntax for the URLs for such a service is as follows:

If a UDDI node’s base URI is http://uddi.example.org/mybase, then the URI http://uddi.example.org/mybase?<entity>Key=uddiKey would retrieve the XML for the data structure whose type is <entity> and whose key is uddiKey.  For example, the XML representation of a tModel whose key is "uddi:tempuri.com:fish:interface" can be retrieved by using the URL http://uddi.example.org/mybase?tModelKey=uddi:tempuri.com:fish:interface.

In the case of businessEntities, the node MAY add these URIs to the businessEntity’s discoveryURLs structure, though this is NOT RECOMMENDED behavior as it complicates the use of digital signatures.


 

7      Inter-Node Operation

This chapter defines the normative behavior of UDDI nodes interacting as a single UDDI registry.  It outlines the operational parameters and requirements that UDDI nodes and UDDI registries must follow.  These parameters and requirements are policies that a registry must establish and that the nodes must enforce. This chapter also describes the OPTIONAL replication protocol for propagation of UDDI data among nodes of a registry. The intended audiences for this chapter are registry administrators and node operators intending to implement and host a multi-node UDDI registry.

Considerations regarding inter-registry operation, such as data import and export between affiliated registries, are detailed in Section 8.2 Data Management Policies and Procedures Across Registries.

7.1 Inter-Node Policy Assertions

Any set of nodes composing a single UDDI registry MUST enforce a set of policies for keying, data management and value sets as defined in Chapter 9

This chapter focuses on the replication protocol that is appropriate to a multi-node registry that uses a single-master data model and assumes the data custody policy in the following section.

7.1.1 Data Custody

Registries that use the replication protocol defined in Section 7.4 Replication API Set MUST enforce the data custody policy specified in Section 1.5.6 Data Custody.

Portions of the Custody Transfer process discussed in Section 5.4 Custody and Ownership Transfer API are designed to utilize UDDI Replication.

7.2 Concepts and Definitions

Where two or more nodes are integrated into a registry, the use of the replication API described in this chapter allows the registry to be viewed as a single logical entity.  A registry designed in this way supports uniform access to a complete set of registry data from any node within the registry. The goal of replication is to facilitate the establishment and maintenance of a single consistent shared set of registry data. Replication latency notwithstanding, all nodes in a registry should at all times contain common content. 

This chapter describes the data replication process and programmatic interface required to achieve complete data replication in UDDI registries composed of more than one node.  The replication process makes use of Extensible Markup Language (XML) and Simple Object Access Protocol (SOAP) specification for using XML in simple message-based exchanges as described in Section 7.4 Replication API Set.

In general terms this section describes the replication API’s and behavior required of any node that intends to support UDDI replication. This function may be thought of as satisfying the following base requirements:

·         Support the addition of a node, by supplying to it an image of the current registry contents.

·         Support periodic replication between the nodes that compose a registry.

·         Support recovery from errors encountered during replication processing.

Note: Please refer to Chapter 2 UDDI Schemas for the reference to the UDDI XML Schema  and to the UDDI Replication XML Schema files.

7.2.1 Update Sequence Number

Each node SHALL maintain a strictly increasing register known as its Originating Update Sequence Number (USN).  An originating USN is assigned to a change record at its creation by a node. The originating USN SHALL NEVER decrease in value, even in the face of system crashes and restarts. UDDI nodes MUST NOT rely on an originating USN sequence increasing monotonically by a value of “1”.  Gaps in a node's originating USN sequence MUST be allowed for as they are likely to occur in the face of system crashes and restarts.

While processing changes to the Registry as a result of performing UDDI Replication, all replicated data MUST be assigned an additional unique and locally generated USN register value – a local USN

The originating and local USN registers MUST be sufficiently large such that register rollover is not a concern. For this purpose, UDDI nodes MUST implement a USN of exactly 63 bits in size.

Note that it is semantically meaningless to compare USNs that have been generated on different nodes; only USNs generated on the same node may be meaningfully compared to each other.

NO change record MAY have a USN equal to 0 (zero). 

7.2.2 Change Records

When a publisher changes a specific datum at a node, the node will create a change record that describes the details of the change.   

Each change record contains the following information:

·         The unique key of the originating node at which the change record was initially created.

·         An originating USN with which the change record is assigned at its creation by its originating node.

·         A payload of data that conveys the semantics of the change in question. These are elaborated and specified later in this chapter.

The UDDI replication process defines how change records are transmitted between nodes of a registry.  Each step of replication involves the transmission of such records from one node to another, say from Node A to Node B. As Node B receives change records from Node A, Node B assigns each incoming record with a fourth piece of (Node-B-generated) information, a local USN.

It is RECOMMENDED that within an implementation, a node should first process a new or updated record and then increment its originating and local USN registers.  This process assures that the USN values remain unique.

Should an implementer choose to record change records generated by an implementation within a Change Record Journal, the local USN and the originating USN values it assigns to a given change record MAY be set to an identical USN value. Thus, all change records ever processed by a node can be sequenced in order of the time of arrival via the replication stream by sorting on the local USNs values of change records it holds.

A node that is ready to initiate replication of change records held at another node within the registry uses the get_changeRecords message.  Part of the message is a high water mark vector that contains for each node of the registry the originating USN of the most recent change record that has been successfully processed by the invocating node. The effect of receiving a get_changeRecords message causes a node to return to the calling node change records it has generated locally and processed from other nodes constrained by the directives of the high water mark vector specified. As such, by invoking get_changeRecords a node obtains from its adjacent node all change records (constrained by the high water mark vector) the adjacent node has generated locally or successfully processed from other nodes participating in the replication topology. What constitutes an adjacent node is governed by the replication communication graph. Replication topology is controlled via a Replication Configuration Structure. Amongst other parameters, the Replication Configuration Structure identifies one unique URL to represent the replication point, soapReplicationURL, of each of the nodes of the registry. 

Upon receiving a get_changeRecords message, a node MUST return change records strictly in increasing order of its local USN values. This property, together with the rules by which local USNs are assigned, provides the following guarantee: Suppose a publisher, whose data is held at node B (that is, Node B is the custodian of that data) changes its data.  Node B originates a change record cr. Then it is guaranteed that any other node that receives change record cr will have previously received all changes which on Node B had a local USN less than the local (and originating) USN of cr.  This, however, is true only of changes cr that Node B originates. 

This important cause and effect relationship is relied upon in several places in the UDDI Replication design, notably the algorithm by which information is ultimately deleted from the UDDI registry.

 

7.2.3 Change Record Journal

Accurate replication of data within a UDDI registry relies on accurate and faithful creation, transmission, and retransmission of change records between all nodes of the UDDI registry. A change record originated by a node is the authoritative reference for change information propagation.  It is critical that change records are not inadvertently altered as they are conveyed from the originating node through intermediate nodes to reach other nodes in the UDDI registry.

To that end, each node SHOULD create and maintain as part of their internal implementation a change record journal that explicitly records verbatim the XML text of change records as they are received from other nodes.  This journaling may be performed before or after standard XML parsing of the change record. 

Implementers may find it convenient to also place their own change records in their change record journal as described above.

7.2.4 High Water Mark Vector

Each node maintains state information in the form of a high water mark vector that contains the originating USN of the most recent change record that has been successfully processed by each node of the registry.  This vector has one entry for each node that can now or has ever introduced change records into the replication stream. Each entry contains the following information:

·         nodeID, that provides the unique key of a node in the replication communication graph, and

·         originatingUSN, that provides the originating USN of the most recent change associated with the node identified by operatorNodeID that has been successfully consumed. Since changes originating from a given node are always originated and thus consumed in order, this will necessarily normally be the largest originating USN that the calling node has successfully consumed from the node identified.

A consuming node MAY reset the originating USN to another value that had been previously been requested for a given node. This may occur due to the need to obtain change records from other nodes as part of a recovery operation following a system failure.

7.2.5 Replication Messages

Replication processing consists of the notification of changes that are available and then the subsequent “pulling” of changes from one of the nodes within the registry.  A node within the registry MAY advertise that changes are available at that node.  The advertisement of changes available includes sufficient information so that another node within the registry can determine if and when it should pull the changes from the offering node to itself for replication processing.

UDDI Replication defines four messages. The first two presented here are used to perform replication and issue notifications. These are:

·         get_changeRecords - This message is used to initiate the replication of change records from one node to another. The invoking node, wishing to receive new change records, provides as part of the message a high water mark vector. This is used by the replication source node to determine what change records satisfy the caller’s request.

·         notify_changeRecordsAvailable - Nodes can inform others that they have new change records available for consumption by replication by using this message. The notify_changeRecordsAvailable message is the predecessor to the get_changeRecords message.

Figure 3 depicts the use of the get_changeRecords and notify_changeRecordsAvailable messages to carry out the process of replicating changes between UDDI nodes.

Figure 3 - Replication Processing

 

Two ancillary messages are also defined to support UDDI Replication. These are:

·         do_ping - This UDDI API message provides the means by which the current existence and replication readiness of a node may be obtained.

·         get_highWaterMarks - This UDDI API message provides a means to obtain a list of highWaterMark elements containing the highest known USN for all nodes in the replication communication graph.

7.2.6 Replication Processing

Replication SHOULD be configured so that in the absence of failures, changes propagate throughout the UDDI registry within a set amount of time.  This requirement means that get_changeRecords requests MAY have to be sent in some scheduled manner.

For example, assume that the communications graph is a cycle of 4 nodes (A, B, C, and D) such that D places get_changeRecords request to C (D>C), C>B, B>A, and then finally A>D. 

In this example, A starts the Replication process.  Periodically, A generates a timer event and notifies B of its high water vector; if necessary, B issues a get_changeRecords request to A, and then sends C its high water vector.  This continues around the cycle (B>A, C>B, D>C, A>D), but doesn't stop there.  B has not received any changes from C or D for the current period, and C has not received any changes from D.

So A continues this algorithm around the cycle again (B>A, C>B, D>C).  At this point, all changes that existed when A handled its timer event have been circulated to all nodes.  (Subsequent changes may have also been propagated.)

Nodes within the registry MAY do local optimizations of changes prior to replicating the changes throughout the UDDI registry.  Any local optimizations performed must be invisible to other nodes within the registry. 

This UDDI API provides a means to obtain a list of highWaterMark elements containing the highest known USN for all nodes in the replication communication graph.

Validation of replicated data is discussed in Section 7.7 Validation of Replicated Data. Error detection and processing is discussed in Section 7.6 Error Detection and Processing.

7.3 Change Record Structures

This section provides the definition of the various changeRecord elements defined for use for UDDI Replication. The overall changeRecord element is defined as follows.

 

Each change record contains a changeID that identifies the node on which the change originated and the originating USN of the change within that node. It then contains one of several allowed forms of change indication; these are elaborated below. With the exception of a changeRecordAcknowledgement type record, a changeRecord may contain an acknowledgementRequested attribute. 

If present with the acknowledgementRequested value set to “true,” then when each node receives a change record and successfully processes it into internal data store, that node MUST in turn originate a new change­Record with a changeRecordPayload_type of changeRecordAcknowledgement. This is done to acknowledge the message processing success and allow that knowledge to be disseminated through the rest of the UDDI registry.

As each changeRecord element first arrives at a node, it must be assigned a local USN value from the receiving node’s USN register. This local USN allows the node to maintain over time the relative order of changes it has received from others and changes it has originated locally. As was mentioned previously, when changes are replicated to others in response to a get_changeRecords request, the change records are provided in ascending order according to this local USN. However, the local USN itself never actually appears in any node-to-node data transmission.

In the event that any changeRecordPayload_type listed below is deprecated in a future version of this specification, transmissions of the change records of the deprecated changeRecordPayload_type MUST be treated as replication errors.  The corresponding handling of those replication transmission errors is specified within Section 7.6 Error Detection and Processing.


 

7.3.1 changeRecordNull

The changeRecordNull element is defined as follows:

Change records of this form do not in fact indicate any sort of semantic change. Rather, their utility largely lies in providing a convenient and safe means to exercise and test certain aspects of the UDDI replication infrastructure. In addition, a changeRecordNull to which an acknowledgement request is attached expands this testing capability of the UDDI registry.

A changeRecordNull is considered “successfully processed” once a node has received it and durably stored it in its Change Record Journal.

7.3.2 changeRecordNewData

The changeRecordNewData element is defined as follows:

 

A changeRecordNewData MUST not be empty; it must contain a valid semantic piece of new data. Change records of this type provide new or updated business or modeling information that is to be incorporated. Partial updates to a datum are not provided for; rather, the entire new contents of the datum are to be provided, and these replace any existing definition of the datum with the recipient of the change record.

The operationalInfo element MUST contain the operational information associated with the indicated new data.

A changeRecordNewData is considered “successfully processed” once a node has received it, assigned a local USN to it, validated it, durably stored it in its change record journal, and then successfully incorporated it into the node’s data store.


7.3.3 changeRecordHide

The changeRecordHide element is defined as follows:

A changeRecordHide element corresponds to the behavior of hiding a tModel described in the delete_tModel in the Publish API section of this Specification.  A tModel listed in a changeRecordHide should be marked as hidden, so that it is not returned in response to a find_tModel API call.

7.3.4 changeRecordDelete

The changeRecordDelete element is defined as follows:

A changeRecordDelete element indicates that an item defined in the UDDI registry is to no longer be used and expunged from the data stores in each of the nodes. The item to be deleted is indicated in the change record by the key of an appropriate entity type; this must contain the unique key of some businessEntity, businessService, bindingTemplate, or tModel that is presently defined.  The changeRecordDelete element for deleting tModels corresponds to the administrative deletion of a tModel described in Section 6.1.3 Updates and Deletions of this specification.  The changeRecordDelete for a tModel does not correspond to any API described in this specification and should only appear in the replication stream as the result of an administrative function to permanently remove a tModel.

Permanent deletions of tModel information within the node may be made administratively. In this event, a UDDI Node may insert a delete operation into the replication stream.  The publisher identifier for this operation is the account associated with the UDDI Node.  Note that a permanent deletion of tModel information from the registry must have the prior approval of the other nodes participating within the registry.


 

7.3.5 changeRecordPublisherAssertion

The changeRecordPublisherAssertion element describes the information that UDDI replication MUST convey in order to support the business-to-business relationship definition supported by UDDI. 

An implementation MUST be able to determine the Registry changes from the information transmitted within the replication stream.  The fromBusinessCheck and toBusinessCheck elements are Boolean values that represent which side of the business relationship is being asserted.  A changeRecordPublisherAssertion message may include one or both sides of the relationship.  For example, if the fromBusinessCheck is present and set to “true” then the assertion represents the parent-side of a parent-child relationship. 

A changeRecordPublisherAssertion element indicates that one or both sides of the business relationship are to be inserted.

a.       changeRecordPublisherAssertion with:

<fromBusinessCheck>true</fromBusinessCheck> and <toBusinessCheck>true</toBusinessCheck> is used to indicate that both sides of the publisherAssertion (i.e., business relationship) are to be inserted. The two businessEntity elements that are referred to within the publisherAssertion MUST be in the custody of the node that originates the changeRecord.

b.      changeRecordPublisherAssertion with:

<fromBusinessCheck>true</fromBusinessCheck> and <toBusinessCheck>false</toBusinessCheck> is used to indicate that the fromBusinessCheck side of the publisherAssertion (i.e., business relationship) is to be inserted. The businessEntity that is referred to in the fromBusinessCheck MUST be in the custody of the node that originates the changeRecord.

c.       changeRecordPublisherAssertion with:

<fromBusinessCheck>false</fromBusinessCheck> and <toBusinessCheck>true</toBusinessCheck> is used to indicate that the toBusinessCheck side of the publisherAssertion (i.e., business relationship) is to be inserted. The businessEntity that is referred to in the toBusinessCheck MUST be in the custody of the node that originates the changeRecord.

d.      changeRecordPublisherAssertion with:

<fromBusinessCheck>false</fromBusinessCheck> and <toBusinessCheck>false</toBusinessCheck> if this is received in the replication stream, such a changeRecord will not generate any change to the registry. The node SHOULD log any events such as this.

 

7.3.6 changeRecordDeleteAssertion

The changeRecordDeleteAssertion element is defined as follows:

 

A changeRecordDeleteAssertion element indicates that one or both sides of the business relationship are to be deleted.

a.       changeRecordDeleteAssertion with:

<fromBusinessCheck>true</fromBusinessCheck> and <toBusinessCheck>true</toBusinessCheck> is used to indicate that both sides of the publisherAssertion (i.e., business relationship) are to be deleted. The two businessEntity elements that are referred to within the publisherAssertion MUST be in the custody of the node that originates the changeRecord.

b.      changeRecordDeleteAssertion with:

<fromBusinessCheck>true</fromBusinessCheck> and <toBusinessCheck>false</toBusinessCheck> is used to indicate that the fromBusinessCheck side of the publisherAssertion (i.e., business relationship) is to be deleted. The businessEntity that is referred to in the fromBusinessCheck MUST be in the custody of the node that originates the changeRecord.

c.       changeRecordDeleteAssertion with:

<fromBusinessCheck>false</fromBusinessCheck> and <toBusinessCheck>true</toBusinessCheck> is used to indicate that the toBusinessCheck side of the publisherAssertion (i.e., business relationship) is to be deleted. The businessEntity that is referred to in the toBusinessCheck MUST be in the custody of the node that originates the changeRecord.

d.      changeRecordDeleteAssertion with:

<fromBusinessCheck>false</fromBusinessCheck> and <toBusinessCheck>false</toBusinessCheck> if this is received in the replication stream, such a changeRecord will not generate any change to the registry. The node SHOULD log any events such as this.

In the event that a businessEntity deleted with a delete_business API message references publisherAssertions, the node SHOULD NOT create corresponding changeRecords for the referenced publisherAssertions.  Please refer to Section 7.2.6 Replication Processing for more discussion related to this.


 

7.3.7 changeRecordAcknowledgment

The changeRecordAcknowledgement element is defined as follows:

 

A node MUST originate a changeRecordAcknowledgement message when it receives and successfully processes a changeRecord that contains an acknow­ledgementRequested attribute set to true.  The changeRecordAcknowledgement message contains the identification of the change that it is acknowledging.

It is specifically required that all nodes receiving a changeRecord with an acknowledgement request MUST originate an acknowledgement for it, even the node that originated the changeRecord in the first place.

7.3.8 changeRecordCorrection

A changeRecordCorrection contains information that is the corrected version of a change record that was previously originated in error. The correction simply contains the whole changeRecord that should have been transmitted in the first place; the originating node and originating USN information therein can be used to locate the offending record in change record journals.

When a node receives a changeRecordCorrection, it processes it only by making annotations in its change record journal; the data store of the node is not otherwise updated with the corrected change[28]. Specifically, and simply put, if the original offending change is still present in the node’s change record journal, its entry SHOULD be merely annotated in such a way that if the change needs to be propagated to a replication partner that the correct contents of the change are transmitted instead of the original. The changeRecordCorrection may be considered successfully processed once this has been durably accomplished and the changeRecordCorrection itself durably recorded in the change record journal.

7.3.9 changeRecordNewDataConditional

From time to time, registries may find it useful to permit certain new data with certain particular keys to be introduced at possibly any of their nodes. For example, registries face the issue that the tModel representing the definition of a new domainKey partition in the keying scheme may be published at any node, and thus possibly at more than one node simultaneously. Some means is therefore necessary to prevent the introduction at multiple nodes of different (and thus conflicting) data under the key in question.

The changeRecordNewDataConditional element provides a means by which this can be accomplished. Such elements necessarily contain wholly new data, that is, data residing under a key that does not yet exist in the registry. The replication and processing of these records ensure that either (a) the new data contained therein is introduced throughout the registry without conflict with other such introductions, or (b) that a conflict is detected by all nodes in the registry and as a consequence all nodes deem the data not to be introduced. That is, race conditions are detected and resolved.

It is a matter of registry policy which forms of data, if any, may be replicated within a given registry using the changeRecordNewDataConditional element.

Change records of type changeRecordNewDataConditional MUST be replicated in change records with an acknowledgementRequested attribute set to “true”. For this type of change record nodes that originate such change records MAY emit their own acknowledgment to their own request at any time after having originated it.

If a Node A originates a change record a with payload of type changeRecordNewDataConditional, then, at the instant of origination (that is, at the instant at which the change record a is assigned its local USN by Node A), it MUST be the case at Node A that the following three rules all are adhered to:

1.       The new data is valid at Node A. That is, Node A would at this instant be willing to have the data published into the registry’s data set. Thus, the data in question must conform to all the specifications and policies applicable to it. In particular, for example, if the registry in question supports publisher assigned keys and the data is a tModel representing the introduction of a new domainKey, then the tModel MUST be categorized with the value “keyGenerator” from the uddi-org:types category system, must be trusted as legitimate according to the policy of the registry, and so on.

2.       The key k is not an existing key at Node A. That is, at Node A there does not exist a change record x with local USN less than that of the USN of the change record a where x contains a changeRecordNewData or changeRecordNewDataConditional payload using the key k in its datum, and there does not exist subsequent to x a change record z with payload changeRecordDelete or changeRecordNewDataConditional also containing the key k.

3.       No other node is known by Node A to have requested the key k first. That is, at Node A there does not exist a change record x with local USN less than that of the USN of the change record a where x contains a payload of type changeRecordNewDataConditional whose contained data also has key k and for which it has not been determined that x was involved in a race in the manner set forth below.

7.3.9.1 Detection of collisions in conditional new data publication

The description within this section uses domain key generator tModels as an example. The behavior described MUST be applied to any type of new data that is found to collide with data from other nodes within the registry. 

When two nodes have saved a domainKey key generator tModel with the same domainKey, a collision has occurred.  Only one publisher can establish a domainKey domain at only one node.  When multiple publishers attempt to establish ownership over a single key domain only one can be allowed to succeed to guarantee uniqueness of publisher assigned keys.

Suppose an arbitrary Node A originates a changeRecordNewDataConditional change record a. Let Node B be an arbitrary other node which also originates a changeRecordNewDataConditional change record (call it b) which contains a datum with same key as that of the datum in a. Let Node C be any arbitrary other node in the registry. Let the notation (x,Y) represent the acknowledgement by Node Y (in a changeRecordAcknowledgement originated by Node Y) of changeRecordNewDataConditional change record x, and let the notation x < y denote the fact that, at a certain node, the local USN of x is less than the local USN of y.

Then, recalling the ordering principle of replication of change records mentioned in Section 7.2.2 Change Records, all of the following facts must be true:

 

At Node A

At Node B

At Node C

Fact

Reason

Fact

Reason

Fact

Reason

A1: a < b

Rule(3)

B1: b < a

Rule(3)

C1: a < (a,B)

B2 + ordering principle

A2: b < (b,A)

One can acknowledge only what one has seen

B2: a < (a,B)

One can acknowledge only what one has seen

C2: a < (b,A)

A3 + ordering principle

A3: a < (b,A)

A1 + A2

B3: b < (a,B)

B1 + B2

C3: b < (a,B)

B3 + ordering principle

A4: a < (a,B)

B2 + ordering principle

B4: b < (b,A)

A2 + ordering principle

C4: b < (b,A)

A2 + ordering principle

A5: b < (a,B)

B3 + ordering principle

B5: a < (b,A)

A3 + ordering principle

 

 

 

Thus, at all nodes in the registry, both requests a and b come before both acknowledgements (a,B) and (b,A); that is, at all nodes, { a, b } < { (b,A), (a,B) }.

Therefore, we can in a well-formed manner specify the following decision procedure:

·         If at any Node X (including at Node A), an acknowledgement (a,Y) is seen for all nodes Y other than Node A before any such b is seen, then Node X SHOULD conclude no such b in fact exists, that Node A now safely has published the key in question, and that the data contained in the changeRecordNewData inside of record a is successfully incorporated into the node’s data store.

·         Conversely, if record b is seen before all the acknowledgements from nodes other than Node A, then Node X SHOULD conclude that a race has occurred, that therefore neither Node A nor any node that it was racing with has published the key, and that the introduction of neither records a nor b into the replication stream had any enduring effect on the data of the registry (they were no-ops).

Moreover, the relative orderings established above ensure that all nodes in the registry (including Node A) will reach the same conclusions in these matters.

In typical uses of the changeRecordNewDataConditional functionality, these sorts of races only arise due to the end-user error of attempting to simultaneously establish new data (such as domainKey key generators) at more than one node. The outcome of such errors is that the new data is not introduced at all, and thus the user must try again.


 

7.4 Replication API Set

UDDI Replication defines four APIs. The first two presented here are used to perform replication and issue notifications. The latter ancillary APIs provide support for other aspects of UDDI Replication.

·         get_changeRecords

·         notify_changeRecordsAvailable

·         do_ping

·         get_highWaterMarks

7.4.1 get_changeRecords Message

The get_changeRecords message is used to initiate the replication of change records from one node to another. The caller, who wishes to receive new change records, provides as part of the message a high water mark vector. This is used by the replication source node to determine what change records satisfy the caller’s request.

7.4.1.1 Syntax

 


 

7.4.1.2 Arguments

·         requestingNode: The requestingNode element provides the identity of the calling node.  This is the unique key for the calling node and SHOULD be specified within the Replication Configuration Structure.

·         changesAlreadySeen: The changesAlreadySeen element, if present, indicates changes from each node that the requestor has successfully processed, and thus which should not be resent, if possible.

·         responseLimitCount or responseLimitVector: A caller MAY place an upper bound on the number of change records he wishes to receive in response to this message by either providing a integer responseLimitCount, or, using responseLimitVector, indicating for each node in the graph the first change originating there that he does not wish to be returned.

More specifically, the recipient determines the particular change records that are returned by comparing the originating USNs in the caller’s high water mark vector with the originating USNs of each of the changes the recipient has seen from others or generated by itself.  The recipient SHOULD only return change records that have originating USNs that are greater than those listed in the changesAlreadySeen highWaterMarkVector and less than the limit required by either the responseLimitCount or the responseLimitVector.

In nodes that support pre-bundled replication responses, the recipient of the get_changeRecords message MAY return more change records than requested by the caller.  In this scenario, the caller MUST also be prepared to deal with such redundant changes where a USN is less than the USN specified in the changesAlreadySeen highWaterMarkVector.

The response to a get_changeRecords message is a changeRecords element. Under all circumstances, all change records returned therein by the message recipient MUST be returned sorted in increasing order according to the recipient’s local USN.

7.4.1.3 Returns:

A node will respond with the corresponding changeRecords.

7.4.1.4 Caveats:

Processing an inbound replication message may fail due to a server internal error. The common behavior for all error cases is to return an E_fatalError error code. Error reporting SHALL be that specified by Section 4.8Success and Error Reporting of this specification.


 

7.4.2 notify_changeRecordsAvailable Message

Nodes can inform other nodes that they have new change records available for consumption by replication by using this message. This provides a proactive means through which replication can be initiated, potentially reducing the latency of the dissemination of changes throughout the set of UDDI nodes.  The notify_changeRecordsAvailable message is the predecessor to the get_changeRecords message.

Each node MUST respond with the message defined within the Section 7.4.2.3 Returns when a valid notify_changeRecordsAvailable message is received. 

At an interval set by policy after the origination of new change records within its node, a node SHOULD send this message to each of the other nodes with which it is configured to communicate this message according to the currently configured communication graph. It SHOULD ignore any response (errors or otherwise) returned by such invocations.

7.4.2.1 Syntax

 

7.4.2.2 Arguments

·         notifyingNode: The parameter to this message indicates that the notifyingNode has available the indicated set of changes for request via get_changeRecords.

·         changesAvailable: When sending the notify_changeRecordsAvailable message, a node shall provide a high water mark vector identifying what changes it knows to exist both locally and on other nodes with which it might have had communications. Typically, no communication graph restrictions are present for the notify_changeRecordsAvailable message.  In the event that the sending node does not know the USN for a specific node within the CommunicationGraph, the changesAvailable element MAY contain a highWaterMark for that node with an unspecified nodeID element.


 

7.4.2.3 Returns

A node MUST respond with a disposition report with the E_success error code when a valid notify_changeRecordsAvailable message is received. Success reporting SHALL be that specified by Section 4.8Success and Error Reporting of this specification.

7.4.2.4 Caveats:

Processing an inbound replication message may fail due to a server internal error. The common behavior for all error cases is to return an E_fatalError error code. Error reporting SHALL be that specified by Section 4.8Success and Error Reporting of this specification.

7.4.3 do_ping Message

This UDDI API message provides the means by which the current existence and replication readiness of a node may be obtained.

7.4.3.1 Syntax

 

7.4.3.2 Arguments

None

7.4.3.3 Returns

The response to this message must contain the operatorNodeID element of the pinged node.

7.4.3.4 Caveats:

Processing an inbound replication message may fail due to a server internal error. The common behavior for all error cases is to return an E_fatalError error code. Error reporting SHALL be that specified by Section 4.8Success and Error Reporting of this specification.


 

7.4.4 get_highWaterMarks Message

This UDDI API message provides a means to obtain a list of highWaterMark element containing the highest known USN for all nodes in the replication graph.

7.4.4.1 Syntax

           

7.4.4.2 Arguments

None

7.4.4.3 Returns

A highWaterMarks element is returned that contains a list of highWaterMark elements listing the highest known USN for all nodes in the replication communication graph. See Section 7.2.4 High Water Mark Vector for details.

If the highest originatingUSN for a specific node within the registry is not known, then the responding node MUST return a highWaterMark for that node with an originatingUSN of 0 (zero).

<highWaterMark>

   <nodeID>…</nodeID>

   <originatingUSN>0</originatingUSN>

</highWaterMark>

 

7.4.4.4  Caveats:

Processing an inbound replication message may fail due to a server internal error. The common behavior for all error cases is to return an E_fatalError error code. Error reporting SHALL be that specified by Section 4.8Success and Error Reporting of this specification.

 


 

7.5 Replication Configuration

7.5.1 Replication Configuration Structure

The replication of UDDI data within a registry SHOULD be governed by information maintained within a Replication Configuration Structure. This structure MAY be contained within a Replication Configuration File.  The structure includes sufficient information to uniquely identify each node within the UDDI registry.  If used, each node within the registry MUST specify at least one contact as described below.

If used, UDDI nodes MUST manage any and all changes to the contents of the Replication Configuration Structure.

The XML schema definition describing the replicationConfiguration element is shown below.  The root element of an instance document of this XML schema must be a replicationConfiguration element as defined in the UDDI v3 replication schema[29]:

 

 

The Replication Configuration Structure contains a serial number which is increased by at least one each time the published configuration is updated or changed.  For the convenience of users, the element timeOfConfigurationUpdate identifies the time of the last update. The formatting of the timeOfConfigurationUpdate element is described later in this specification.  The registryContact identifies a party who maintains and updates the Replication Configuration Structure.

The element, maximumTimeToGetChanges, allows for the specification of the maximum amount of time (in hours) that an individual node may wait to request changes. Nodes MUST perform a get_changeRecords replication message within the time frame defined by the value of the maximumTimeToGetChanges element defined within the Replication Configuration Structure.  Thus, change data can always be propagated throughout the UDDI registry within a finite amount of time, while at the same time changes will often propagate quickly. Use of this element is determined by registry policy as detailed in Section 9.6.4 Replication Policies

The operator elements in a Replication Configuration Structure are a list of the nodes and established paths of communication between the nodes within a registry.  The communication paths and general replication topology considerations are discussed later in this specification.

The element, maximumTimeToSyncRegistry, allows for the specification of when (in hours) a change made at any single node in the Registry is expected to be visible at all nodes within the registry.  The element, maximumTimeToGetChanges, allows for the specification of the maximum amount of time (in hours) that an individual node may wait to request changes.  Use of this element is determined by registry policy as detailed in Section 9.6.4 Replication Policies.

The dsig:Signature elements in a Replication Configuration Structure allow for signing of the document for assurance of its integrity using XML Digital Signature.

7.5.2 Configuration of a UDDI Node – operator element

Each current UDDI node within the Registry is identified with an operator element in the replicationConfiguration:

 

The operatorNodeID contains a unique key that is used to uniquely identify this node throughout the UDDI registry. The value used MUST match the businessKey of the Node Business Entity as referenced in Section 6.2.2 Self-Registration of Node Business Entity. The contact or contacts listed provide information about humans who should be contacted in the face of administrative and technical situations of various sorts. . The dsig:KeyInfo elements are intended to contain the certificate details if the soapReplicationURL makes use of Secure Sockets Layer 3.0 with mutual authentication as described in Section 7.5.5 Security Configuration.


 

7.5.3 Replication Communication Graph

The Replication Configuration Structure provides a means by which the UDDI replication traffic can be controlled and administered. This is achieved with the use of a communicationGraph element:   

 

The communicationGraph element begins by explicitly listing a unique ID for each node within the registry.  This second listing of the unique IDs within the Replication Configuration Structure enables the separate control of communication with a node from the management of other aspects of the node’s configuration.

Following the listing of nodes is the controlledMessage element that lists the set of messages over which this communication graph is intended to administer control of. If a message element local name is listed in the controlledMessage element, then such messages SHALL only be sent between nodes that are listed in the subsequent edges of the graph. In contrast, communication restrictions are not imposed on replication messages not identified in the controlledMessage element.

The next element of the communication graph, the edge element, identifies the graph edges imposed for those nodes that are listed. All node ID’s listed in an edge MUST have been previously identified in the node element of the communication graph.

Each edge in the graph is a directed edge. The message elements contain the local name of the Replication API message elements. They indicate that only messages of the type explicitly identified for a particular edge MAY be sent from the specified messageSender to the specified messageReceiver. Restricted two-way communication between nodes MUST, if desired, be identified as a pair of edges with opposing directionality. A given directed edge MAY be listed at most once: for each edge, the pairing (messageSender, messageReceiver) MUST be unique over the entire set of edges of the graph.

For each directed edge, an ordered sequence of zero or more alternate, backup edges MAY be listed using the messageReceiverAlternate element. Should a communications failure prevent message communication over the indicated primary edge, the backup edges MAY be tried in order until communication succeeds.

In the absence of a communicationGraph element from the Replication Configuration Structure, all nodes listed in the node element MAY send any and all messages to any other node of the registry.

A non-normative example of the use of the CommunicationGraph can be found within Appendix J UDDI Replication Examples.

7.5.4 SOAP Configuration

In UDDI, node-to-node replication communication MUST be carried out by means of SOAP messages and responses. The soapReplicationURL element of the operator element indicates where such messages should be sent to communicate with a given node. Specifically, in order to carry out a message invocation of type X with a given node in the registry, a message is sent using HTTP POST, as described in Chapter 4, to the URL identified within the Replication Configuration Structure.      

7.5.5 Security Configuration

Mutual authentication of UDDI nodes is RECOMMENDED. This MAY be achieved using mutual X.509v3 certificate-based authentication as described in the Secure Sockets Layer (SSL) 3.0 protocol.  SSL 3.0 with mutual authentication is represented by the tModel uddi-org:mutualAuthenticatedSSL3 as described within Section 11.3.2 Secure Sockets Layer Version 3 with Mutual Authentication. The certificate credentials that SHOULD be used for the mutual authentication SHOULD be included in the dsig:KeyInfo element(s) for each node Replication Configuration Structure.

7.6 Error Detection and Processing

While replication errors are expected to happen rarely, mechanisms must be in place to detect, deal with, and help manage the correction of such problems.

Throughout this section we will consider a UDDI registry consisting of 4 nodes (A, B, C, and D) configured in a cyclic replication pattern such that D places get_changeRecords requests to C (D>C), C>B, B>A, A>D. In addition to each node’s primary replication edge a set of alternate edges have been defined for each node which, in case of difficulty, permits it to bypass each upstream node in turn (i.e. B has two secondary edges: B>D and B>C).  For clarity, only one is depicted below in Figure 4.

Figure 4 - Alternate Edge Example

 

Asserting an invalid change record, it follows that:

In all of the cases below we assume that the following steps are executed, in the order listed:

1.       A Publisher of data held in custody at Node D saves changes to that data

2.       Node D originates a change record x.

3.       Node A issues a get_changeRecords request to Node D and successfully processes the change record set containing x which D issued in response.

4.       Node B issues a get_changeRecords request to Node A and processes the change record set that Node A issued in response. During processing of the change record set Node B encounters x and is unable to validate it.

When Node B is unable to validate x it is required to signal that it has encountered a change record that it considers invalid (see Section 7.7 Validation of Replicated Data for a precise definition of what it means for a change record to be ‘invalid’). It does this by communicating to all of the UDDI nodes.  The communication must include the following:

·         The originating Node’s USN Value

·         The reporting Operator Node ID

·         The Originating Node ID

·         The Replication operation type being processed (i.e., changeRecordPayload_type)

·         The unique key of the datum being processed

·         The type of datum being processed (i.e., businessEntity, businessService, tModel, etc.)

In addition Node B must refuse to accept x from Node A (i.e. it MUST NOT add x to its journal, MUST NOT process x into its registry, and MUST NOT update its high water mark vector to reflect processing of x) and MUST NOT consider x to be successfully processed.  Recall that Node A is required to deliver records ordered by local USN and Node B is required to consume records in the order they are provided.  As a consequence, Node B will for the moment be unable to accept any other new records from Node A.  Note that Node B may have successfully processed other change records from the change record set it received from Node A.  If those change records preceded x, then they are unaffected by the issues associated with x.

This design avoids polluting Node B with data that it knows to be invalid, while preserving the important ordering guarantee of change propagation upon which other replication semantics rely.

7.6.1 UDDI Registry Investigation and Correction

Once Node B has asserted the existence of an invalid change record the UDDI nodes MUST take remedial action. The investigation of Node B's assertion regarding x MAY have a number of outcomes. Those are documented in the cases below.

The following change records are used in these cases:

·         x: a changeRecordNewData message created by Node D that Node B asserts is invalid.

·         y: a changeRecordCorrection  message created by Node D containing x’, a corrected payload for x.

·         z: a changeRecordNewData message created by Node D containing current payload for x.

7.6.1.1 Case 1: Invalid record validation

The UDDI nodes MAY determine that Node B’s assertion that x is invalid MAY be a result of overly aggressive checking and validation in Node B’s UDDI implementation. In this case:

·         Node B WILL BE REQUIRED to change its code,

·         Node B WILL continue to participate in replication cycles, retrying propagation of x from A to B in each cycle until the code changes are deployed and x is processed successfully.

7.6.1.2 Case 2: Invalid interim representation

The assertion by Node B that x is incorrect MAY reflect incorrect handling of x by interim Node A (recall that x is replicated first from node D to Node A, then from Node A to Node B). Note that the originating Node D contains a valid x. In these cases:

·         Node A WILL BE REQUIRED to change its code.

·         Node D WILL BE REQUIRED to generate y and z.

·         Node A WILL continue to participate in replication, processing y (annotating x in its journal to refer to x’ in y) and z in one or more change record sets from Node D,

·         Node B WILL continue to participate in replication in subsequent cycles. In each it WILL attempt to propagate x from Node A, then begin to exercise its alternate edges, descending one additional edge each cycle (i.e. in cycle (n+1) it WILL attempt to replicate using B>A and B>D). At some point node B MAY process a valid x from an alternate node, in these instances, Node B WILL later process y (annotating x to point to x’ in y) and z from Node A. If Node B has not processed a valid x from an alternate node prior to issuing a get_changeRecords to Node A which has processed y, then Node B WILL process x’, y (annotating x to point to x’ in y), and z from Node A.

·         Node C WILL continue replication and will receive x, y, and z from Node B.

Expanded Description:

Handling of the assertion that change record x delivered by Node A is invalid begins in replication cycle (n+0) with Node B communicating the details of the issue to all nodes within the UDDI registry, discarding x and all subsequent change records received from Node A, and halting its replication.

During its next replication cycle (n+1) Node B WILL attempt to process a change record set from Node A. Assuming that Node A has not yet processed y produced by Node D, Node B WILL encounter an invalid x as the first record in the change record. In this case Node B WILL NOT issue a redundant message including the details of the issue to all nodes within the UDDI registry, however it WILL again discard x and all subsequent change records within the set issued by Node A. Node B WILL then use its first alternate replication edge (B>D) to circumvent Node A and will process a change record set containing x returned by Node D.

In its next replication cycle (n+2) Node B WILL successfully process a change record returned by Node A. Since Node B’s high water mark vector entry for Node D has been updated to reflect its successful processing of x, Node A WILL NOT be asked to deliver x, and should it do so Node B WILL NOT attempt to process it (recall that a node responding to a get_changeRecords request MUST reply with at least the data requested, but MAY respond with more data than was requested by the caller).

During an arbitrary replication cycle following Node B’s receipt of an invalid x from Node A, Node D WILL produce a changeRecordCorrection y containing a valid version x’ of x. Node A WILL process y annotating x within its journal to indicate that the payload in x is replaced by x’ in y. Note that although Node A’s journal now contains a valid x, Node A’s registry does not.

Node B’s next get_changeRecords request to Node A WILL result in a change record set containing either x’ and y or only y. Change record x’ is delivered in instances where Node A processed y before Node B issued its (n+1) get_changeRecords request to A.

Following production of y, Node D WILL produce z (which contains the now-current contents of the information manipulated by x). Change record z WILL be propagated normally through replication.

7.6.1.3 Case 3: Invalid generation

The assertion that x is invalid MAY be due to Node D having improperly generated x. In this case:

·         Node D WILL BE REQUIRED to change its code so that in future it generates correct change records, and to generate y and z.

·         Node A WILL BE REQUIRED to change its code so that in future it detects invalid change records such as x.

·         Node A WILL continue participating in replication, processing y (annotating x to point to x’ in y) and z.

·         Node B WILL continue participating in cycles, continuing to attempt propagation of x from Node A to Node B until it processes x’, y (annotating x to point to x’ in y), and z.

·         Node C WILL continue replication cycles, receiving x’, y (annotating x to point to x’ in y), and z.

 

Expanded Description:

In this case handling of the assertion that record x delivered by Node A is invalid begins in replication cycle (n+0) with Node B communicating the details of the issue to all nodes within the UDDI registry, discarding x and all subsequent change records received from Node A, and halting its replication.

During its next replication cycle (n+1) Node B WILL again process a change record set from Node A. It should encounter x as the first record in the change record set returned by Node A. If processing of x again yields an error, Node B WILL NOT issue a redundant message including the details of the issue to all nodes within the UDDI registry, it WILL discard x and all subsequent change records from Node A. Node B WILL then use its first alternate replication edge (B>D) to circumvent Node A and request change records from another node (D). In processing the change record set returned by Node D it WILL encounter an invalid x. It WILL then communicate the details of the issue to all nodes within the UDDI registry (pointing to Node D as the originating and the sending node), discard x and all subsequent change records received from Node D, and halt its replication.

In its next replication cycle (n+2) Node B WILL again process a change record set from Node A. Should it again encounter an invalid x as the first record in the set it WILL discard x and all subsequent change records from Node A and proceed to its first alternate replication (B>D). Should processing a change record set from Node D again uncover an invalid x as the first record in the set from Node D, Node B WILL discard x and all subsequent change records from Node D and proceed to its second alternate replication edge (B>C) to circumvent nodes A and D. Since Node C has not received x the change record set is produces should be valid.   

During an arbitrary replication cycle following production of x, Node D WILL produce a changeRecordCorrection y containing the corrected version x’ of x. This new change record y propagates using the normal replication mechanism. Node A WILL process y, annotating x in its journal to now refer to x’ in y. At this point Node A’s journal is correct, however its registry still contains an invalid version of x.

In a subsequent replication cycle, Nodes B and C WILL process x’ and y. Following production of y, Node D WILL produce z. In a subsequent replication cycle Nodes A, B, and C WILL process z.  At this point all three nodes contain a valid representation of the data addressed by x.


 

7.7 Validation of Replicated Data

UDDI nodes MUST enforce the validity of all the data entering their data store, both data they originate themselves, and data that they receive from other nodes through replication.  A registry policy should define the level of validation that nodes enforce above and beyond validating that the data conforms to the UDDI schemas and does not cause corruption of the node data store.

Specifically, it is required that a node fail to accept any publication API request which would, were it accepted, at that instant put its data store into an invalid state. Nodes must also support analogous enforcement through any user interfaces or other means by which the data in their data store may be added to or updated.

Moreover, as a node receives replicated changeRecords from another node in response to a get_changeRecords request, it must consider the potential effect of the incorporation of the change into its data store. If the incorporation by the receiving node of such a change record (together, of course, with any preceding changes) would put its data store into an invalid state, then an error in one or more of the UDDI node implementations within the registry has been detected. In response, the receiving node must carry out the error detection processing sequence described in Section 7.6 Error Detection and Processing.

Upon the receipt of changeRecords related to publisherAssertions that refer to businesses that have been previously deleted, or access point information that refers to invalid bindingKeys, or a tModelKey of a keyedReference that refers to a tModel that no longer exist, or any attempts to project a service that no longer exist at the node, or a reference in a isReplacedBy keyedReference to an invalid or missing businessEntity or tModel key, nodes MUST NOT raise replication errors.  Nodes MUST include the respective changeRecords in a response to relevant get_changeRecord messages.

Note as a point of implementation that it might often be useful to batch together several incoming change records under one validity check; this is a valid optimization since later change records cannot adversely affect the validity of earlier changes. However, should such an optimized validity check fail, an implementation must be prepared to back out of and fail to accept the entire set of candidate change records involved and then reconsider each individually in turn.

As a checked value set reference may be validated or checked at an originating node within the registry, it need not be checked again at a node in the midst of processing a replication stream.  If a checked value set reference is checked again during replication it SHOULD not generate a replication stream error.

7.8 Adding a Node to a Registry Using Replication

The following steps MAY be used to add a node to a registry that uses UDDI v3 replication.  A registry policy may be defined for the addition of a node and the policy MAY define a different or more detailed process than the following process:

1.       Add the new node to the Replication Configuration Structure with the operatorStatus value set to “new”.  If a communicationGraph is used in the registry’s replication Configuration Structure, one or more edges MUST be added so the new node may call the get_changeRecords API.

2.       Administrators of the existing nodes are notified of the update. They each retrieve and process the new information in the configuration file in order to add the new node as one of the parties with which their implementations are willing to authenticate and communicate. To verify the ability to communicate, each node pair within the current UDDI registry SHALL successfully exchange the do_ping message.

3.       Once all existing nodes within the registry have verified the ability to successfully communicate with the new node, the configuration file is changed a second time to add appropriate edges to the communicationGraph in order to introduce the new node into the active replication graph.  The messages allowed between the new node and its primary may be restricted to allow for startup processing.  Replication then proceeds to provide change records to the new node which establish in it a current image of the registry.

4.       The new node MUST issue a get_changeRecords API call to an existing node and SHOULD process all available changeRecord elements.  As nodes MAY limit the number of changeRecord elements in a response, processing all available changeRecord elements MAY require several get_changeRecords API calls.

5.       When the new node has completed processing of the change history and is ready to engage in all UDDI registry activities, the operatorStatus value, within the Replication Configuration Structure, WILL be updated from “new” to “normal” and any message restriction that may have been imposed earlier may be removed. The updated replicationConfiguration will be distributed to the nodes defined within the communicationGraph via replication.

7.9 Removing a Node from a Registry Using Replication

The following steps MAY be used to remove a node to a registry that uses UDDI v3 replication. A registry policy may be defined for the removal of a node and the policy MAY define a different or more detailed process than the following process

1.       At least one node in the registry MUST obtain all changeRecord elements representing the final state of the node that will be removed.

2.       The value of the operatorStatus element in the operator element in the Replication Configuration Structure of the node that is being removed MUST be changed from “normal” to “resigned.”  In addition any edge elements that include the node that is being removed MUST be removed from the communicationGraph element.  The operator element for the removed node remains in the Replication Configuration Structure so other nodes in the registry accept the changeRecord elements from the removed node.

3.       Depending on registry policy, the custody of the UDDI data from the removed node MAY subsequently be changed to one or more nodes in the registry.


 

8      Publishing Across Multiple Registries

In prior versions of the UDDI Specification, the behavior in which a publisher wished to copy the entirety of a UDDI registry entity from one registry to another while preserving the identical key was explicitly not allowed.  The Version 1 and 2 specifications mandated that only the UDDI node could generate keys.  A publisher could not pre-assign the key of a UDDI entity.  With this stipulation in place, a publisher could not import or export data between registries.  The rationale behind this mandate was to insure that no duplicate keys would ever be generated in a given registry because only nodes within that registry had the authority to generate keys.  Consequently data sharing between registries in Version 1 and 2 of UDDI was functionally not allowed.

Version 3 of UDDI approaches the issue of key generation in a significantly different fashion and, as such, the possibility of publishing an entity to another UDDI registry while preserving the key is allowed.  This behavior is known as entity promotion. With this version of UDDI, a publisher is permitted to propose a new key for an entity, and, given the policies of a registry, that key and the entity associated with that key may be inserted into the registry.  Thus, the possibility of sharing data among UDDI registries is a reality and, with this new functionality, UDDI’s scope in terms of a more broadly distributed environment is made manifest.

At its core, registry-to-registry data sharing, or the publishing of data across multiple registries, involves the sharing of data between two UDDI registries.  With such a notion, individual UDDI registries can be connected in complex ways.  In fact, for a given registry, a publisher may have the authority to add many entities to a registry and, as such, a publisher could potentially publish the entirety of a registry’s contents into another registry, effectively mirroring the data.  Or, the publisher might be interested in only a subset of data from another registry and only copy a portion of that data.  When considering the implications of entity promotion, it is important to conceive of a publisher in a broader context, which makes possible a number of interesting scenarios.

The most important aspect to consider in terms of data that has been published across multiple registries is that no a priori assumptions can be made about the nature of a relationship between the data in two registries and, by implication, no assumption can be made about the relationship between an entity that happens to exist in two (or more) registries.  The data associated with a given key is by default scoped to a single registry and not to multiple registries.  Consequently, inter-registry publication is quite different than inter-node behavior, i.e., the behavior of replication of nodes within a single registry.  In replication, there is a normative model for the nodes that participate in a replication topology and the for data management of those nodes.  However, a normative model for inter-registry publication does not exist and therefore cannot be assumed.  The nature of interaction between two given registries is not mandated by the UDDI specification.  The trust models and data management procedures between two registries are a matter of policy established by the two registries and are defined as non-normative behavior in terms of the UDDI v3 specification.  In this way, inter-registry interaction differs significantly from inter-node replication.

While normative inter-registry behavior is outside the scope of the specification, an explanation of exactly how the specification enables the ability to share data between registries is in order. The focus of this chapter is to outline further the rationale for inter-registry communication, to introduce the different kinds of inter-registry communication, and to provide guidance when considering engaging in inter-registry publication.

8.1 Relationships between Registries

8.1.1 Root Registries and Affiliate Registries

For this new capability to be useful, care must be taken to avoid key collision between registries.  The recommended way to prevent such collision is to establish a root registry, a registry that acts as the authority for key spaces.  A root registry serves to delegate key partitions such that other registries can rely upon the root registry for verification and validation of a given key partition.  All other registries that interact with the root registry are called affiliate registries.  Affiliate registries rely on the root registry to delegate key partitions and insure that uniqueness across key partitions is maintained.  By relying on a common root registry as an arbitrator of key spaces, affiliate registries can share data with both the root registry and among one another with the knowledge that a given partition is unique.  Note that it is still the responsibility of each registry, both a root registry and its affiliates, to insure the data integrity and uniqueness of the keys within its custody.

An important example of a root registry is the UDDI Business Registry, which has a set of policies in place to generate unique uuidKeys as well as to validate domainKeys through signatures that correlate with DNS records.  These policies insure the uniqueness of both domainKeys and uuidKeys within the UDDI Business Registry, and thus the UBR serves as a reasonable root registry for many purposes.  In fact, establishing alternate root registries is not recommended, as this would ultimately defeat the goal of publishers being able to share data between multiple registries with an assurance of avoiding a key collision.  By acknowledging the UDDI Business Registry as a root, an affiliate registry can establish inter-registry communication policies and procedures with both the UDDI Business Registry and any other registry which is an affiliate of the UDDI Business Registry.

8.1.2 A Closer Look at Inter-Registry Communication Models

Before looking at the operational details of sharing data between registries, a look at some of the permutations of inter-registry communication is in order.  Using a Venn diagram to represent the cross publication models between three registries sheds some light on permutations of data sharing.  Note that the diagram below does not represent the directional flow with regard to how exactly how the data might move between registries.  However, the diagram does provide a conceptual framework to begin thinking about how the data in multiple registries might be related.

In the Venn diagram below, the circle (1) represents the UDDI Business Registry, a root registry, while the two other circles represent registry A and registry B, two affiliate registries

 

 

 

Consider Scenario (1), in which the three registries contain data that exist independent of the other registries.  There are certainly scenarios that exist in which data would not be of value or interest to another registry, and thus would exist in one and only one registry.  In this case, it may appear that there are not concerns about possible key collision with another registry. 

However, it is critical to realize that, registry policy aside, nothing prevents a user of a registry from promoting entities from one registry to another registry.  Put another way, no registry is an island. A user with read authority in one registry and publish authority in some other registry can retrieve entities from the first and publish them in the second.  And, once that data has been promoted, nothing prevents the publisher from altering the data in the original registry. This concern is mitigated with the advent of digital signature support. A signed UDDI entity can be copied across multiple registries and the publisher can verify that the original content has not been modified.

It is important for both nodes and clients to remember that a registry typically does not control the data outside of itself.  A client of a given registry must be aware that different registries might contain identical keys with different data.  In some scenarios, this is the desired behavior, but there are also cases where such behavior could be construed as malicious.  As such, clients need to be cognizant of the policies and procedures of registries they interact with.

In Scenario (2), Affiliate A and Affiliate B each have data that exists in both an affiliate registry and the UDDI Business Registry.  This could have occurred in several different ways.  A publisher in Affiliate A may have subscribed to a certain set of entities in the root registry, publishing them in itself on an ongoing basis as changes are received.  Or, a publisher in Affiliate A may have generated a set of entities in its local registry and then published them to the UBR.  Such data exchange is potentially a two-way process: the data may originate in the root and end up in Affiliate A, or it may originate in Affiliate A and end up in the root. 

In Scenario (3), the two affiliates share data.  Again, this sharing has several permutations.  Publishers in Affiliate A and B may have an explicit agreement to subscribe to one another’s d