|
|
UDDI Version 3.0 Published Specification, 19 July 2002
|
This version:
http://uddi.org/pubs/uddi-v3.00-published-20020719.htm
Latest version:
http://uddi.org/pubs/uddi_v3.htm
Authors (alphabetically):
Luc Clément, Microsoft
David Ehnebuske, IBM
Andrew Hately, IBM
Maryann Hondo, IBM
Yin Leng Husband, HP
Karsten Januszewski, Microsoft
Sam Lee, Oracle
Barbara McKee, IBM
Joel Munter, Intel
Claus von Riegen, SAP
Working Group Contributors (alphabetically):
Selim Aissi, Intel
Bob Atkinson, Microsoft
John Colgrave, IBM
Tom Gaskins, HP
Tom Glover, IBM
Dan Guinan, VeriSign
Christian Hansen, SAP
Thomas Hardjono, VeriSign
Richard Harrah, HP
Keisuke Kibakura, Fujitsu
Seán MacRoibeáird, Sun
Ed Mooney, Sun
Andrew Nielsen, HP
Shigeru Shimada, IBM
Christian R. Thomas, Intel
Johannes Viegener, SAP
Advisor Group Contributors (alphabetically):
Sharon Boeyen, Entrust
Fennivel Chai, DealEasy
Paul Denning, MITRE
Matthew J. Dovey, Oxford University
Daniel Feygin, UnitSpace
Jeffrey Kenyon, Qwest
Anne Thomas Manes, Systinet
Takayuki Nakao, NTT Communications
Scott Wood, Cambian
Brian Young, Boeing
Copyright © 2000 - 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.
These UDDI Specifications (the "Documents") are provided by the companies named above ("Licensors") under the following license. By using and/or copying this Document, or the Document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to copy, prepare derivative works based on, and distribute the contents of this Document, or the Document from which this statement is linked, and derivative works thereof, in any medium for any purpose and without fee or royalty under copyrights is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:
1. A link to the original document posted on uddi.org.
2. An attribution statement : "Copyright © 2000 - 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."
If the Licensors own any patents or patent applications that may be required for implementing and using the specifications contained in the Document in products that comply with the specifications, upon written request, a non-exclusive license under such patents shall be granted on reasonable and non-discriminatory terms.
EXCEPT TO THE EXTENT PROHIBITED BY LOCAL LAW, THIS DOCUMENT (OR THE DOCUMENT TO WHICH THIS STATEMENT IS LINKED) IS PROVIDED "AS IS," AND LICENSORS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, ACCURACY OF THE INFORMATIONAL CONTENT, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY OR (WITH THE EXCEPTION OF THE RELEVANT PATENT LICENSE RIGHTS ACTUALLY GRANTED UNDER THE PRIOR PARAGRAPH) LICENSOR PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. Some jurisdictions do not allow exclusions of implied warranties or conditions, so the above exclusion may not apply to you to the extent prohibited by local laws. You may have other rights that vary from country to country, state to state, or province to province.
EXCEPT TO THE EXTENT PROHIBITED BY LOCAL LAW, LICENSORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL DAMAGES, OR OTHER DAMAGES (INCLUDING LOST PROFIT, LOST DATA, OR DOWNTIME COSTS), ARISING OUT OF ANY USE, INABILITY TO USE, OR THE RESULTS OF USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF, WHETHER BASED IN WARRANTY, CONTRACT, TORT, OR OTHER LEGAL THEORY, AND WHETHER OR NOT ANY LICENSOR WAS ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Some jurisdictions do not allow the exclusion or limitation of liability for incidental or consequential damages, so the above limitation may not apply to you to the extent prohibited by local laws.
1.3 Diagrams Used in this document 15
1.4.1 Translations of the UDDI Specification
1.4.2 Best Practices and Technical Notes
1.5.2 UDDI Services and API Sets
1.5.5 Affiliations of Registries
1.5.6 Person, Publisher and Owner
1.6 Representing Information within UDDI
1.6.1 Representing Businesses and Providers with “businessEntity”
1.6.2 Representing Services with “businessService”
1.6.3 Representing Web services with “bindingTemplate”
1.6.4 Technical Models (tModels)
1.6.5 Taxonomic Classification of the UDDI entities
1.8 Introduction to Internationalization
1.8.1 Multi-regional businesses
1.8.3 XML and Unicode Character Set
1.8.4 Standardized Postal Address
1.8.5 Use of Multi-languages and Multi-scripts
1.8.6 Adding Language-specific Sort Orders
1.8.7 Consistent Internationalized Search
2.3 Element and attribute types and lengths
2.3.1 Data structure, publication API, inquiry API and security API
3 UDDI Registry Data Structures
3.2.1 Keys as unique identifiers
3.2.2 Containment and references
3.7 publisherAssertion Structure
4.1.3 Support for SOAP encoding
4.1.4 Support for SOAP Headers
4.1.6 XML prefix conventions – default namespace support
4.3 Support for Unicode: Byte Order Mark
4.5 Data insertion and document order
4.5.1 Inserting Data in Entities During save_xx Operations
4.5.2 Inserting Elements in Existing Entities
4.5.3 Preservation of Document Order 56
4.6 XML Normalization and Canonicalization
4.7 About Access Control and the authInfo Element
4.8 Success and Error Reporting
4.8.1 dispositionReport element
4.8.2 Success reporting using the dispositionReport element
4.8.3 Error reporting using the dispositionReport element
5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups
5.2.1 Publishing entities with node assigned keys
5.2.2 Publishing entities with publisher-assigned keys
5.2.3 Special considerations for validated value sets
5.2.4 Special considerations for the xml:lang attribute
5.2.9 delete_publisherAssertions
5.2.12 get_assertionStatusReport
5.2.13 get_publisherAssertions
5.2.19 set_publisherAssertions
5.4 Custody and Ownership Transfer API Set
5.4.2 Custody Transfer Considerations. 139
5.4.7 Security Configuration for transfer_custody
5.5.1 About UDDI Subscription API functions
5.5.3 Specifying Points in Time
5.5.4 Subscription Coverage Period
5.5.5 Chunking of Returned Subscription Data
5.5.6 Use of keyBag in Subscription
5.5.7 Subscription API functions
5.5.11 get_subscriptionResults
5.5.12 notify_subscriptionListener
5.6.1 Value Set Programming Interfaces
6.1.2 Key Generation and Maintenance. 170
6.2 Considerations When Instantiating a Node
6.2.1 Canonical tModel Bootstrapping. 170
6.2.2 Self-Registration of Node Business Entity
6.3 User Credential Requirements
6.3.1 Establishing User Credentials
6.3.2 Changing Entity Ownership
6.4 Checked Value Set Validation
6.4.1 Normative behavior during saves. 172
6.5 HTTP GET Services for UDDI Data Structures
7.1 Inter-Node Policy Assertions
7.3.5 changeRecordPublisherAssertion. 183
7.3.6 changeRecordDeleteAssertion
7.3.7 changeRecordAcknowledgment
7.3.9 changeRecordNewDataConditional 185
7.4.1 get_changeRecords Message
7.4.2 notify_changeRecordsAvailable Message
7.4.4 get_highWaterMarks Message
7.5.1 Replication Configuration Structure
7.5.2 Configuration of a UDDI Node – operator element
7.5.3 Replication Communication Graph. 195
7.6 Error Detection and Processing. 196
7.6.1 UDDI Registry Investigation and Correction
7.7 Validation of Replicated Data
7.8 Adding a Node to a Registry Using Replication
7.9 Removing a Node from a Registry Using Replication
8 Publishing Across Multiple Registries
8.1 Relationships between Registries
8.1.1 Root Registries and Affiliate Registries
8.1.2 A Closer Look at Inter-Registry Communication Models
8.2 Data Management Policies and Procedures Across Registries
8.2.1 Establishing a Relationship with a Root Registry
9.3.3 Policy Service within UDDI
9.4 UDDI Registry Policy Abstractions
9.4.1 Registry Policy Delegation
9.4.2 Registry General Keying Policy. 213
9.4.3 UDDI recommended keying scheme. 214
9.4.4 UDDI Information Access Control Policy
9.4.5 Adding nodes to a registry
9.4.6 Person, Publisher and Owner
9.4.8 Registry Authorization Policy
9.4.10 Registry Data Integrity
9.4.11 Registry Approved Certificate Authorities
9.4.12 Registry Data Confidentiality
9.4.14 Registry Privacy Policy
9.4.15 Registry Clock Synchronization Policy
9.4.16 Registry Replication Policy
9.4.17 Support for Custody Transfer
9.4.18 Registry Subscription Policy
9.4.19 Registry Value Set Policies
9.5 UDDI Node Policy Abstractions
9.5.2 Node Publisher Generated Key Assertion
9.5.4 Node Authorization Policy
9.5.5 Node Registration and Authentication
9.5.7 Node Policy for Contesting Entries
9.5.11 Node Approved Certificate Authorities
9.5.12 Node Subscription API Assertion. 221
9.5.15 Node discoveryURL Generation
9.6 UDDI Recommended Registry Policies
9.7.1 UDDI Registry Policy Abstractions
9.7.2 UDDI Node Policy Abstractions
10.1 Entity Key Compatibility with Earlier Versions of UDDI
10.1.1 Generating Keys From a Version 3 API Call
10.1.2 Generating Keys From a Version 2 API Call
10.1.3 Migrating Version 2 keys to a Version 3 Registry
10.1.4 Mapping v1/v2 Canonical tModel Keys to v3 Evolved Keys
10.2 Other Considerations of Version 2 Inquiry API Calls
10.2.1 keyedReferenceGroup data
10.2.3 Multiple overviewDoc data
10.2.4 Multiple personName data
10.2.5 Multiple xml:lang attributes of the same language
10.2.10 Mapping Between URLType and useType attribute on accessPoint
10.2.11 Supporting External Value Set Providers Across Versions
10.2.12 Sorting and Matching Behavior
10.3 Data Migration Considerations
10.3.1 Version 3 Schema Strictness
10.4 Considerations of Version 2 Publish API Calls
10.4.1 Data update semantics consistent with request namespace
11 Utility tModels and Conventions. 243
11.1 Canonical Category Systems, Identifier Systems and Relationship Systems
11.1.1 UDDI Types Category System
11.1.2 General Keyword Category System.. 248
11.1.3 UDDI Nodes Category System
11.1.4 UDDI Relationships System
11.1.5 UDDI owningBusiness Category System
11.1.6 UDDI isReplacedBy Identifier System
11.1.7 UDDI validatedBy Category System
11.1.8 UDDI Derived From Category System
11.2 UDDI Registry API tModels
11.2.5 UDDI Custody and Ownership Transfer API
11.2.6 UDDI Node Custody Transfer API 274
11.2.7 UDDI Value Set Caching API
11.2.8 UDDI Value Set Validation API
11.2.10 UDDI Subscription Listener API 283
11.3 Transport and Protocol tModels. 286
11.3.1 Secure Sockets Layer Version 3 with Server Authentication
11.3.2 Secure Sockets Layer Version 3 with Mutual Authentication
11.3.3 UDDI HTTP GET Transport
11.3.7 UDDI Telephone Transport
11.4.1 UDDI SQL99 Approximate Match findQualifier
11.4.2 UDDI Exact Match findQualifier 298
11.4.3 UDDI Case Insensitive Match findQualifier
11.4.4 UDDI Case Sensitive Match findQualifier
11.4.5 UDDI Diacritics Insensitive Match findQualifier
11.4.6 UDDI Diacritics Sensitive Match findQualifier
11.4.7 UDDI Binary Sort sortOrder qualifier
11.4.8 UDDI Unicode Technical Standard #10 sortOrder qualifier
11.4.9 UDDI Case Insensitive Sort findQualifier
11.4.10 UDDI Case Sensitive Sort findQualifier
11.4.11 UDDI Sort By Name Ascending findQualifier
11.4.12 UDDI Sort By Name Descending findQualifier
11.4.13 UDDI Sort By Date Ascending findQualifier
11.4.14 UDDI Sort By Date Descending findQualifier
11.4.15 UDDI And All Keys findQualifier 321
11.4.16 UDDI Or All Keys findQualifier 323
11.4.17 UDDI Or Like Keys findQualifier 325
11.4.18 UDDI Combine Category Bags findQualifier
11.4.19 UDDI Service Subset findQualifier
11.4.20 UDDI Binding Subset findQualifier
11.4.21 UDDI Suppress Projected Services findQualifier
11.4.22 UDDI Signature Present findQualifier
11.5.1 Domain Key Generator for the UDDI Domain
11.5.2 UDDI Hosting Redirector Specification
11.5.3 UDDI Policy Description Specification
13 Related Standards and Specifications
13.1 UDDI Specifications and documents
13.2 Standards and other Specifications
Appendix A: Relationships and Publisher Assertions. 345
A.2 Managing relationship visibility
Appendix B: Using and Extending the useType Attribute
B.1.1 Using the “endPoint” value
B.1.2 Using the “wsdlDeployment” value
B.1.3 Using the “bindingTemplate” value
B.1.4 Using the “hostingRedirector” value
B.2.2 Using the “wsdlInterface” value. 351
B.3.1 Using the “businessEntity” value
B.3.2 Using the “homepage” value
B.8 Designating a new useType value. 353
Appendix C: Supporting Subscribers
C.2.1 Steps for Creating a Subscription
Appendix D: Internationalization
D.1 Multilingual descriptions, names and addresses
D.2 Multiple names in the same language
D.3 Internationalized address format
D.4 Language–dependent collation
D.4.1 UDDI JIS X 4061 Japanese sortOrder qualifier
Appendix F: Using Categorization
G.1 Find using “starts with” searching
G.2 Find using “starts and ends with” searching
G.3 Find using escaped literals
G.4 Find using wildcards with Taxonomies
H.1 Using the basic UDDI infrastructure
H.2.2 Registries that support the extension
H.3 Programmers API and UDDI Clients
H.3.1 UDDI Clients not prepared to handle the extension
H.3.2 UDDI Clients prepared to handle the extension
H.8.2 Data structure (XML schema)
H.8.4 Additional service end points
H.8.5 Programmers API Description of the extension
H.8.7 Registry operation: replication. 383
H.8.8 Registry operation: entity promotion
Appendix I: Support For XML Digital Signatures
Appendix J: UDDI Replication Examples
J.2 Replication Configuration Structure Example
J.3 notify_changeRecordsAvailable Example
J.5 Miscellaneous Replication Example
J.6 Non-normative – Cycle of Cycles Topology
Appendix K – Modeling UDDI within UDDI – A Sample
K.4 The Publish Service – Supporting 3 Versions
K.5 The Inquiry Service – Supporting 3 Versions
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 the sequence of elements businessInfos followed by tModelInfos. All three elements are defined in the namespace whose prefix is “uddi”.
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 UDDI.org 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, UDDI.org from time to time publishes “Best Practices” and “Technical Notes”. The contents of these documents are not a part of this specification. See http://uddi.org/bestpractices.html for further information on Best Practices and http://uddi.org/technotes.html 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
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 principle 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 Contact’s Timezone
In order to support human communication, the UDDI specification includes contact information such as phone numbers. The provision of time zone information helps in deriving the contact’s effective contactable hours. Businesses may indicate the timezone within which each contact operates by specifying it in the contact’s address.
1.8.3 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.4 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.5 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.6 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.7 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.
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 |
|
|
Target namespace |
urn:uddi-org:api_v3 |
|
Referenced/imported namespaces |
http://www.w3.org/2001/XMLSchema |
|
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 |
|
|
Target namespace |
urn:uddi-org:custody_v3 |
|
Referenced/imported namespaces |
urn:uddi-org:api_v3 |
|
Description |
This is the schema for the UDDI Custody and Ownership Transfer API set. |
|
UDDI Subscription Schema |
|
|
Schema file |
|
|
Target namespace |
urn:uddi-org:sub_v3 |
|
Referenced/imported namespaces |
urn:uddi-org:api_v3 |
|
Description |
This is the schema for the UDDI Subscription API set. |
|
UDDI Subscription Listener Schema |
|
|
Schema file |
|
|
Target namespace |
urn:uddi-org:subr_v3 |
|
Referenced/imported namespaces |
urn:uddi-org:api_v3 |
|
Description |
This is the schema for the UDDI Subscription Listener API set. |
|
UDDI Replication Schema |
|
|
Schema file |
|
|
Target namespace |
urn:uddi-org:repl_v3 |
|
Referenced/imported namespaces |
urn:uddi-org:api_v3 |
|
Description |
This is the schema for the UDDI Replication API set. |
|
UDDI Value Set Validation Schema |
|
|
Schema file |
|
|
Target namespace |
urn:uddi-org:vs_v3 |
|
Referenced/imported namespaces |
urn:uddi-org:api_v3 |
|
Description |
This is the schema for the UDDI Value Set Validation API set. |
|
UDDI Value Set Caching |
|
|
Schema file |
|
|
Target namespace |
urn:uddi-org:vscache_v3 |
|
Referenced/imported namespaces |
urn:uddi-org:api_v3 |
|
Description |
This is the schema for the UDDI Value Set Data API set. |
|
UDDI Policy |
|
|
Schema file |
|
|
Target namespace |
urn:uddi-org:policy_v3 |
|
Referenced/imported namespaces |
http://www.w3.org/2001/XMLSchema |
|
Description |
This is the schema for the UDDI Policy Document for the Policy Service. |
|
UDDI Policy Instance Parameters |
|
|
Schema file |
|
|
Target namespace |
urn:uddi-org:policy_instanceParms_v3 |
|
Referenced/imported namespaces |
|
|
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 |
|
|
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 |
2.3.2 Subscription API
|
Element/attribute Name |
Data Type |
Length |
|
brief |
boolean |
|
|
endPoint |
dateTime |
|
|
notificationInterval |
duration |
|
|
exipresAfter |
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.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:ubr.uddi.org:categorization:geo3166-2”
keyName=””
keyValue=”US-CA” />
<keyedReference
tModelKey=”uddi:ubr.uddi.org:categorization:geo3166-2”
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
|
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 are specified in the IETF standard RFC 1766 and its successors (including, as of the time of the present writing, RFC 3066). As is indicated therein, language values begin with a primary language tag, and are optionally followed by a series of hyphen-delimited sub-tags for country or dialect identification; the tags are not case-sensitive. 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 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:ubr.uddi.org: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:ubr.uddi.org:categorization:geo3166-2”
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.
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:ubr.uddi.org:categorizationGroup:wgs84” >
<keyedReference
tModelKey=”uddi:ubr.uddi.org:categorization:wgs84:latitude”
keyName=”WGS 84 Latitude”
keyValue=”+49.682700” />
<keyedReference
tModelKey=”uddi:ubr.uddi.org: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
|
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
|
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 an optional 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 has to 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 an optional 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[5] specification, the Open Applications Group Integration Specification[6] 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
|
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). Changes in a service that is being projected do not affect the modifiedIncludingChildren element of the businessEntity in which it is projected. The information provided by the modifiedIncludingChildren element is logically redundant, since it can be computed by inquirers. It is, however, commonly desired and is therefore provided directly in pre-computed form.
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).
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[7] 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 as UTF-8, and MUST specify the Hyper Text Transport Protocol (HTTP) Content-Type header with a charset parameter of "utf-8" and a content type of text/xml. All such messages MUST also have the 'encoding="UTF-8"' 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, 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"
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.
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 such responses MUST be encoded in UTF-8.
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 URIs conforming to RFC 2396 for keys. Further, it is RECOMMENDED that registries 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 recommended keying scheme. The primary motivations for the recommendation to use 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 the recommended scheme are case insensitive. The canonicalization algorithm does not normalize the case of URIs, which implies it does not normalize the case of keys. Even so, UDDI is required to preserve the case on uddiKeys to keep from invalidating digital signatures on signed entities that have publisher assigned keys.
4.4.1 Recommended Syntax[8]
uddiKey = uuidKey / domainKey / derivedKey
uuidKey = "uddi:" uuid
domainKey = "uddi:" domain
derivedKey = uddiKey ":" KSS
KSS = 1*KSSChars
KSSChars = upper / lower / number / other
uuid = 8hexNumber “-“ 4hexNumber “-“ 4hexNumber “-“
4hexNumber “-“ 12hexNumber
upper = "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" / "I" / "J" / "K" / "L" /
"M" / "N" / "O" / "P" / "Q" / "R" / "S" / "T" / "U" / "V" / "W" /
"X" / "Y" / "Z"
lower = "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" / "i" / "j" / "k" / "l" /
"m" / "n" / "o" / "p" / "q" / "r" / "s" / "t" / "u" / "v" / "w" /
"x" / "y" / "z"
number = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"
hexNumber = number / “A” / “B” / “C” / “D” / “F” / “a” / “b” / “c” / “d” / “f”
other = "(" / ")" / "+" / "," / "-" / "." / "=" / "@" / ";" / "$" / "_" / "!" / "'"
Where <domain> is a dNSname as defined in RFC 2459 section 4.2.1.7. A <uuid> is often referred to as a “formatted Universally Unique Identifier” or “formatted UUID”. A <KSS> is sometimes referred to as a “key specific string”.
4.4.2 Examples of keys
The following are examples of legal <domainKey>s.
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 <derivedkey>s
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:keyGenerator
This key is based on the <domainKey> “uddi:tempuri.com”. Its <KSS> is “keyGenerator”.
uddi:tempuri.com:fish:buyingService
This key is based on the <derivedKey> “uddi:tempuri.com:fish”. The string “buyingService” is the key’s <KSS>.
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).[9]
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[10] 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.
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.2 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. 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 criterions 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)
|