|
|
UDDI Spec TC |
UDDI Version 3.0.2
UDDI Spec Technical Committee Draft, Dated 20041019
uddi_v3
Current version:
http://uddi.org/pubs/uddi-v3.0.2-20041019.htm
Latest version:
http://uddi.org/pubs/uddi_v3.htm
Previous version:
http://uddi.org/pubs/uddi-v3.0.1-20031014.htm
Editors:
Andrew Hately, IBM
Claus von Riegen, SAP AG
Tony Rogers, Computer Associates
Contributors:
Tom Bellwood, IBM
Steve Capell
Luc Clement, Systinet
John Colgrave, IBM
Matthew J. Dovey
Daniel Feygin, UnitSpace
Andrew Hately, IBM
Rob Kochman, Microsoft
Paul Macias, LMI
Mirek Novotny, Systinet
Massimo Paolucci
Claus von Riegen, SAP AG
Tony Rogers, Computer Associates
Katia Sycara
Pete Wenzel, SeeBeyond Technology
Zhe Wu, Oracle
Abstract:
The UDDI Version 3.0.2 Specification describes the Web services, data structures and behaviors of all instances of a UDDI registry.
Status:
This specification has attained the status of Committee Draft. This document is updated periodically on no particular schedule.
Committee members should send comments on this Committee Specification to the uddi-spec@lists.oasis-open.org list. Others should subscribe to and send comments to the uddi-spec-comment@lists.oasis-open.org list. To subscribe, send an email message to uddi-spec-comment-request@lists.oasis-open.org with the word "subscribe" as the body of the message.
For information on whether any intellectual property claims have been disclosed that may be essential to implementing this Committee Specification, and any offers of licensing terms, please refer to the Intellectual Property Rights section of the UDDI Spec TC web page (http://www.oasis-open.org/committees/uddi-spec/ipr.php).
Copyrights:
Copyright © 2001-2002 by Accenture, Ariba, Inc., Commerce One, Inc., Fujitsu Limited, Hewlett-Packard Company, i2 Technologies, Inc., Intel Corporation, International Business Machines Corporation, Microsoft Corporation, Oracle Corporation, SAP AG, Sun Microsystems, Inc., and VeriSign, Inc. All Rights Reserved.
Copyright © OASIS Open 2002-2004. All Rights Reserved.
1.3 Diagrams Used in this document
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.2 XML and Unicode Character Set
1.8.3 Standardized Postal Address
1.8.4 Use of Multi-languages and Multi-scripts
1.8.5 Adding Language-specific Sort Orders
1.8.6 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
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 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
5.4.8 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
6.2 Considerations When Instantiating a Node
6.2.1 Canonical tModel Bootstrapping
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
6.5 HTTP GET Services for UDDI Data Structures
7.1 Inter-Node Policy Assertions
7.3.5 changeRecordPublisherAssertion
7.3.6 changeRecordDeleteAssertion
7.3.7 changeRecordAcknowledgment
7.3.9 changeRecordNewDataConditional
7.3.10 changeRecordConditionFailed
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
7.6 Error Detection and Processing
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
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.9 Node Collation Sequence Policy
9.5.11 Node Approved Certificate Authorities
9.5.12 Node Subscription API Assertion
9.5.15 Node discoveryURL Generation
9.5.16 Node XML Encoding Policy
9.6 UDDI Recommended Registry Policies
9.6.3 Domain key generator tModels
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 Version 2 API Considerations
10.2.1 Multiple xml:lang attributes of the same language
10.2.3 Return of a dispositionReport
10.2.4 Mapping Between URLType and useType attribute on accessPoint
10.2.5 Supporting External Value Set Providers Across Versions
10.2.6 Version 3 Schema Assessment
10.3 Version 2 Inquiry API Considerations
10.3.2 keyedReferenceGroup data
10.3.3 Multiple overviewDoc data
10.3.4 Multiple personName data
10.3.6 Sorting and Matching Behavior
10.4 Version 2 Publish API Considerations
10.4.1 Data update semantics consistent with request namespace
10.5 Data Migration and Multi-version Runtime Considerations
10.5.1 Empty Containers – Enforcement of Schema Strictness
10.5.2 Length Validation During v2/v3 Migration and During Runtime in a v2/v3 Multi-version Registry
10.6 Value sets with entity keys as valid values.
11 Utility tModels and Conventions
11.1 Canonical Category Systems, Identifier Systems and Relationship Systems
11.1.1 UDDI Types Category System
11.1.2 General Keyword Category System
11.1.3 UDDI Nodes Category System
11.1.4 UDDI Relationships System
11.1.5 UDDI "Owning Business" Category System
11.1.6 UDDI "Is Replaced By" Identifier System
11.1.7 UDDI "Validated By" Category System
11.1.8 UDDI "Derived From" Category System
11.1.9 UDDI "Entity Key Values" 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
11.2.7 UDDI Value Set Caching API
11.2.8 UDDI Value Set Validation API
11.2.10 UDDI Subscription Listener API
11.3 Transport and Protocol tModels
11.3.1 Secure Sockets Layer Version 3 with Server Authentication
11.3.2 Secure Sockets Layer Version 3 with Mutual Authentication
11.3.7 UDDI Telephone Transport
11.4.1 UDDI SQL99 Approximate Match Find Qualifier
11.4.2 UDDI Exact Match Find Qualifier
11.4.3 UDDI Case Insensitive Match Find Qualifier
11.4.4 UDDI Case Sensitive Match Find Qualifier
11.4.5 UDDI Diacritics Insensitive Match Find Qualifier
11.4.6 UDDI Diacritics Sensitive Match Find Qualifier
11.4.7 UDDI Binary Sort Order Qualifier
11.4.8 UDDI Unicode Technical Standard #10 Sort Order Qualifier
11.4.9 UDDI Case Insensitive Sort Find Qualifier
11.4.10 UDDI Case Sensitive Sort Find Qualifier
11.4.11 UDDI Sort By Name Ascending Find Qualifier
11.4.12 UDDI Sort By Name Descending Find Qualifier
11.4.13 UDDI Sort By Date Ascending Find Qualifier
11.4.14 UDDI Sort By Date Descending Find Qualifier
11.4.15 UDDI And All Keys Find Qualifier
11.4.16 UDDI Or All Keys Find Qualifier
11.4.17 UDDI Or Like Keys Find Qualifier
11.4.18 UDDI Combine Category Bags Find Qualifier
11.4.19 UDDI Service Subset Find Qualifier
11.4.20 UDDI Binding Subset Find Qualifier
11.4.21 UDDI Suppress Projected Services Find Qualifier
11.4.22 UDDI Signature Present Find Qualifier
11.5.1 Domain Key Generator for the UDDI Domain
11.5.2 Key Generator for UDDI Categorization tModels
11.5.3 Key Generator for UDDI Sort Order tModels.
11.5.4 Key Generator for UDDI Transport tModels
11.5.5 Key Generator for UDDI Protocol tModels
11.5.6 UDDI Hosting Redirector Specification
11.5.7 UDDI Policy Description Specification
13 Related Standards and Specifications
13.1 UDDI Specifications and documents
13.2 Standards and other Specifications
A Appendix A: Relationships and Publisher Assertions
A.2 Managing relationship visibility
B 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
B.3.1 Using the "businessEntity" value
B.3.2 Using the "homepage" value
B.8 Designating a new useType value
C Appendix C: Supporting Subscribers
C.2.1 Steps for Creating a Subscription
D 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 Sort Order Qualifier
E Appendix E: Using Identifiers
F 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
H.8.8 Registry operation: entity promotion
I Appendix I: Support For XML Digital Signatures.
J 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
K Appendix K – Modeling UDDI within UDDI – A Sample
K.4 The Publish Service – Supporting 3 Versions
K.5 The Inquiry Service – Supporting 3 Versions
L Appendix L: Glossary of Terms
M Appendix M: Acknowledgements
Web services are meaningful only if potential users may find information sufficient to permit their execution. The focus of Universal Description Discovery & Integration (UDDI) is the definition of a set of services supporting the description and discovery of (1) businesses, organizations, and other Web services providers, (2) the Web services they make available, and (3) the technical interfaces which may be used to access those services. Based on a common set of industry standards, including HTTP, XML, XML Schema, and SOAP, UDDI provides an interoperable, foundational infrastructure for a Web services-based software environment for both publicly available services and services only exposed internally within an organization.
1.1 About this specification
This document describes the Web services and behaviors of all instances of a UDDI registry. Normative material is provided in the numbered chapters of the document and in the XML schemas which accompany this document. Supplementary non-normative commentary, explanations, and guidance may be found in the lettered appendices. In particular, first-time readers of this specification may find Appendix L Glossary of Terms useful.
This specification contains examples of XML data and URIs used in interacting with UDDI. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
The primary audiences for this document are:
· Programmers who want to write software that will directly interact with a UDDI registry.
· Programmers who want to implement a UDDI node
· Programmers who want to implement any of the Web services UDDI Nodes invoke
All implementations of the UDDI specification must provide support for the required Web services described here as well as the behaviors defined.
1.2 Language & Terms
RFC 2119: The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they appear in this document, are to be interpreted as described in RFC 2119 found at http://www.faqs.org/rfcs/rfc2119.html.
MANDATORY, RECOMMENDED, and OPTIONAL: Beginning with this third version, the UDDI specification renders explicit which components of the UDDI specification are MANDATORY and MUST be implemented, which are RECOMMENDED and SHOULD be implemented, and which are OPTIONAL and MAY be implemented. It is important to note that OPTIONAL and RECOMMENDED elements of the specification, if they are implemented, MUST be implemented in the manner documented in this specification.
Separation of operational issues: In this third version of the UDDI Specification the trend begun in Version 2 to separate normative behavior from UDDI registry and node policy is completed. For instance, authorization has been called out as a policy decision. A similar separation of normative behavior and registry content has also been carried out. For example, the requirement to support specific category systems has been removed from this version of the specification.
1.3 Diagrams Used in this document
1.3.1 Attributes and elements
UDDI uses the XML Schema Language (See http://www.w3.org/TR/xmlschema-0/, http://www.w3.org/TR/xmlschema-1/ and http://www.w3.org/TR/xmlschema-2/) and its terminology, such as "sequence" and "choice" to formally describe its data structures. The diagrams[1] used in this specification show the structure and cardinality of the elements used in these structures. Attributes are not shown in the diagrams, but explained in the corresponding documentation.
1.3.2 Element structure
1.3.2.1 Sequence
The octagonal symbol with the horizontal "dotted" line indicates "sequence of." This diagram says the element registeredInfo consists of elements businessInfos and tModelInfos. All three elements are defined in the namespace whose prefix is "uddi".
The fact that businessInfos and tModelInfos have a box with a "+" in it at their right-hand end indicates that there is more structure to them than is shown in the diagram.
1.3.2.2 Choice
The switch-like symbol indicates a choice. In this case, a choice between the elements businessKey, fromKey, and toKey.
None of these has more structure than is given in the diagram (there are no boxes with a "+" in them at their right-hand ends). That they are adorned with a small series of horizontal lines in their upper left corners indicates that each is a non-empty element.
1.3.3 Cardinality
1.3.3.1 Optional, one
The dashed line indicates that the element listDescription is optional. The fact that it is not adorned with some other cardinality indicator (see below) says there can be at most one of them.
1.3.3.2 Mandatory, one
There must be exactly one of the element businessKey.
1.3.3.3 Optional, repeating
The element assertionStatusItem is optional and may appear an indeterminate number of times. The number of times it may appear is given by the adornment "0..Ą", a cardinality indicator meaning "zero to infinity". Other numbers may appear to indicate different cardinalities.
1.3.3.4 Mandatory, repeating
The element addressLine must appear at least once and may appear an indeterminate number of times.
1.4 Related Documents
1.4.1 Translations of the UDDI Specification
Translations of the UDDI Specifications may be produced, by the UDDI specification technical committee of OASIS, or by others. In all instances the English version of the document is the official version; in case of discrepancy the English version shall be the definitive source.
1.4.2 Best Practices and Technical Notes
To provide guidance on the use of UDDI registries, the UDDI specification technical committee of OASIS from time to time publishes "Best Practices" and "Technical Notes". The contents of these documents are not a part of this specification. See http://www.oasis-open.org/committees/uddi-spec/doc/bps.htm for further information on Best Practices and http://www.oasis-open.org/committees/uddi-spec/doc/tns.htm for information on Technical Notes.
1.5 Base UDDI Architecture
1.5.1 UDDI Data
This specification presents an information model composed of instances of persistent data structures called entities. Entities are expressed in XML and are persistently stored by UDDI nodes. Each entity has the type of its outer-most XML element. A UDDI information model is composed of instances of the following entity types:
· businessEntity: Describes a business or other organization that typically provides Web services.
· businessService: Describes a collection of related Web services offered by an organization described by a businessEntity.
· bindingTemplate: Describes the technical information necessary to use a particular Web service.
· tModel: Describes a "technical model" representing a reusable concept, such as a Web service type, a protocol used by Web services, or a category system.
· publisherAssertion: Describes, in the view of one businessEntity, the relationship that the businessEntity has with another businessEntity.[2]
· subscription: Describes a standing request to keep track of changes to the entities described by the subscription.
1.5.2 UDDI Services and API Sets
This specification presents APIs that standardize behavior and communication with and between implementations of UDDI for the purposes of manipulating UDDI data stored within those implementations. The API’s are grouped into the following API sets.
1.5.2.1 Node API Sets
· UDDI Inquiry
· UDDI Publication
· UDDI Security
· UDDI Custody Transfer
· UDDI Subscription
· UDDI Replication
1.5.2.2 Client API Sets
· UDDI Subscription Listener
· UDDI Value Set
1.5.3 UDDI Nodes
A set of Web services supporting at least one of the Node API sets is referred to as a UDDI node. A UDDI node has these defining characteristics:
1. A UDDI node supports interaction with UDDI data through one or more UDDI API sets
2. A UDDI node is a member of exactly one UDDI registry.
3. A UDDI node conceptually has access to and manipulates a complete logical copy of the UDDI data managed by the registry of which it is a part. Moreover, it is this data which is manipulated by any query and publish APIs supported by the node. Typically, UDDI replication occurs between UDDI nodes which reside on different systems in order to manifest this logical copy in the node.
The physical realization of a UDDI node is not mandated by this specification.
1.5.4 UDDI Registries
One or more UDDI nodes may be combined to form a UDDI Registry. The nodes in a UDDI registry collectively manage a particular set of UDDI data. This data is distinguished by the visible behavior associated with the entities contained in it.
A UDDI Registry has these defining characteristics.
1. A registry is comprised of one or more UDDI nodes.
2. The nodes of a registry collectively manage a well-defined set of UDDI data. Typically, this is supported by the use of UDDI replication between the nodes in the registry which reside on different systems.
3. A registry MUST make a policy decision for each policy decision point. It MAY choose to delegate policy decisions to nodes. See Chapter 9 Policy for details.
The physical realization of a UDDI Registry is not mandated by this specification.
1.5.5 Affiliations of Registries
1. The registries share a common namespace for entity keys.
2. The registries have compatible policies for assigning keys to entities.
3. The policies of the registries permit publishers to assign keys
1.5.6 Person, Publisher and Owner
When publishing information in a UDDI registry the information becomes part of the published content of the registry. During publication of an item of UDDI information, a relationship is established between the publisher, the item published and the node at which the publish operation takes place. The glossary contains definitions of the terms person, publisher and owner.
This specification defines a relationship between these three terms and leaves the binding of these abstract relationships to be determined by the policies of the registry and its nodes at implementation. It is important to review Chapter 9 on policy to understand how different implementations can define different policies but remain consistent with the UDDI specification.
1.5.7 Transfer of ownership
As the owner of datum, a person can initiate the transfer of ownership of the datum to another publisher within the registry. Section 5.4 Custody and Ownership Transfer API describes the transfer of ownership within UDDI.
1.5.8 Data Custody
Generally speaking, data is replicated between nodes of a UDDI registry using a replication protocol. Registries that choose to use the replication protocol defined in Section 7.4 Replication API Set MUST enforce the following data custody policy. (Registries which choose otherwise incur no such requirement.)
Each node has custody of a portion of the aggregate data managed by the registry of which it is a part. Each datum is by definition in the custody of exactly one such node. A datum in this context can be a businessEntity, a businessService, a bindingTemplate, a tModel, or a publisherAssertion. Changes to a datum in the registry MUST originate at the node which is the custodian of the datum. The registry defines the policy for data custody and, if allowed, the custodian node for a given datum can be changed; such custody transfer processes are discussed in Section 5.4 Custody and Ownership Transfer API.
1.6 Representing Information within UDDI
For Web services to be meaningful there is a need to provide information about them beyond the technical specifications of the service itself. Central to UDDI’s purpose is the representation of data and metadata about Web services. A UDDI registry, either for use in the public domain or behind the firewall, offers a standard mechanism to classify, catalog and manage Web services, so that they can be discovered and consumed. Whether for the purpose of electronic commerce or alternate purposes, businesses and providers can use UDDI to represent information about Web services in a standard way such that queries can then be issued to a UDDI Registry – at design-time or run-time – that address the following scenarios:
· Find Web services implementations that are based on a common abstract interface definition.
· Find Web services providers that are classified according to a known classification scheme or identifier system.
· Determine the security and transport protocols supported by a given Web service.
· Issue a search for services based on a general keyword.
· Cache the technical information about a Web service and then update that information at run-time.
These scenarios and many more are enabled by the combination of the UDDI information model and the UDDI API set. Because the information model is extremely normalized, it can accommodate many different types of models, scenarios and technologies. The specification has been written to be flexible so that it can absorb a diverse set of services and not be tied to any one particular technology. While a UDDI Node exposes its information as an XML Web service, it does not restrict the technologies of the services about which it stores information or the ways in which that information is decorated with metadata.
1.6.1 Representing Businesses and Providers with "businessEntity"
One top-level data structure within UDDI is the businessEntity structure, used to represent businesses and providers within UDDI. It contains descriptive information about the business or provider and about the services it offers. This would include information such as names and descriptions in multiple languages, contact information and classification information. Service descriptions and technical information are expressed within a businessEntity by contained businessService and bindingTemplate structures.
While the name of XML entity itself has the word business embedded in it, the structure can be used to model more than simply a "business" in its common usage. As the top-level entity, businessEntity can be used to model any "parent" service provider, such as a department, an application or even a server. Depending on the context of the data in the entire registry, the appropriate modeling decisions to represent different service providers can vary.
1.6.2 Representing Services with "businessService"
Each businessService structure represents a logical grouping of Web services. At the service level, there is still no technical information provided about those services; rather, this structure allows the ability to assemble a set of services under a common rubric. Each businessService is the logical child of a single businessEntity. Each businessService contains descriptive information – again, names, descriptions and classification information -- outlining the purpose of the individual Web services found within it. For example, a businessService structure could contain a set of Purchase Order Web services (submission, confirmation and notification) that are provided by a business.
Similar to the businessEntity structure, the term business is embedded within the name businessService. However, a suite of services need not be tied to a business per se, but can rather be associated with a provider of services, given a modeling scenario that is not based on a business use case.
1.6.3 Representing Web services with "bindingTemplate"
Each bindingTemplate structure represents an individual Web service. In contrast with the businessService and businessEntity structures, which are oriented toward auxiliary information about providers and services, a bindingTemplate provides the technical information needed by applications to bind and interact with the Web service being described. It must contain either the access point for a given service or an indirection mechanism that will lead one to the access point.
Each binding Template is the child of a single businessService. The containing parents, a bindingTemplate can be decorated with metadata that enable the discovery of that bindingTemplate, given a set of parameters and criteria.
1.6.4 Technical Models (tModels)
Technical Models, or tModels for short, are used in UDDI to represent unique concepts or constructs. They provide a structure that allows re-use and, thus, standardization within a software framework. The UDDI information model is based on this notion of shared specifications and uses tModels to engender this behavior. For this reason, tModels exist outside the parent-child containment relationships between the businessEntity, businessService and bindingTemplate structures.
Each distinct specification, transport, protocol or namespace is represented by a tModel. Examples of tModels that enable the interoperability of Web services include those based on Web Service Description Language (WSDL), XML Schema Definition (XSD), and other documents that outline and specify the contract and behavior – i.e., the interface – that a Web Service may choose to comply with. To describe a Web service that conforms to a particular set of specifications, transports, and protocols, references to the tModels that represent these concepts are placed in the bindingTemplate. In such a way, tModels can be re-used by multiple bindingTemplates. The bindingTemplates that refer to precisely the same set of tModels are said to have the same "technical fingerprint" and are of the same type. In this way, tModels can be used to promote the interoperability between software systems.
It is important to note that such technical documents and the supporting documentation necessary to a developer using Web services are not stored within the UDDI registry itself. A UDDI tModel simply contains the addresses where those documents can be found. A tModel, however, contains more than just URLs; it also stores metadata about the technical documents and an entity key that identifies that tModel.
Because tModels can represent any unique concept or construct, they have usage beyond the software interoperability scenario described above. They can also be used to represent other concepts within the UDDI information model, such that metadata concepts are reused throughout the model. For example, tModels are used for the following other purposes within UDDI:
· Transport and protocol definitions such as HTTP and SMTP. (See below and also Section 11.1.1 uddi-org:types for a description.)
· Value sets including identifier systems, categorization systems and namespaces. (See Section 3.3 businessEntity Structure and Appendix F Using Categorization for a description of how value sets are used in UDDI.)
· Structured categorizations using multiple value sets called "categorization groups."
· Postal address formats. (See Section 3.3.2.7 address and Appendix B Internationalization for a description.)
· Find qualifiers used to modify the behavior of the UDDI find_xx APIs. (See Section 5.1.4 findQualifiers for a description.)
· Use type attributes that specify the kind of resource being referred to by a URI reference. (See, for example, Section 3.5.2.1 accessPoint.)
The use of tModels is essential to how UDDI represents data and metadata. The UDDI specification defines a set of common tModels that can be used canonically to model information within UDDI. If a concept that is required to model a particular scenario does not exist in a registry, a user should introduce that concept by saving a tModel containing the URL of the relevant overview documents.
1.6.5 Taxonomic Classification of the UDDI entities
Data is worthless if it is lost within a mass of other data and cannot be distinguished or discovered. If a client of UDDI cannot effectively find information within a registry, the purpose of UDDI is considerably compromised. Providing the structure and modeling tools to address this problem is at the heart of UDDI’s design. The reification of data within UDDI is core to its mission of description, discovery and integration. It achieves this by several means.
First, it allows users to define multiple taxonomies that can be used in UDDI. In such a way, multiple classification schemes can be overlaid on a single UDDI entity. This capability allows organizations to extend the set of such systems UDDI registries support. One is not tied to a single system, but can rather employ several different classification systems simultaneously.
Second, UDDI allows such classification systems to be used on every entity within the information model. It defines a consistent way for a publisher to add any number of classifications to their registrations. It is important that taxonomies are used when publishing data into a UDDI registry. Whether standard codes are used (such as the United Nations Standard Products and Services Code System (UNSPSC)) or a new taxonomy is created and distributed, it is imperative that UDDI data -- businessEntity, businessService, bindingTemplate and tModel elements alike – are attributed with metadata.
Third, the UDDI Inquiry API set provides the ability to issue precise searches based on the different classification schemes. A range of queries that perform different joins across the UDDI entities can be generated, such that data can be discovered and accessed. Also, registering information such as industry codes, product codes, geography codes and business identification codes allows other search services to use this classification information as a starting point to provide added-value indexing and classification.
Classification and identification systems, taken together, are called "value sets" in UDDI. Value sets may be "checked" or "unchecked". Both checked and unchecked value sets are used for categorization and identification. The difference between them is that whenever a checked value set is used, the use is inspected to see that it conforms to the requirements of the value set. Unchecked value sets do not have their uses checked.
1.7 Introduction to Security
The security model for a UDDI registry can be characterized by the collection of registry and node policies and the implementation of these policies by a UDDI node. This specification details a list of policies that MUST be defined by registries and nodes in Chapter 9 Policy. This specification also describes how policies SHOULD be modeled.
Several optional and extensible mechanisms for implementing nodes, registries and clients with a particular security model are described in this specification. The principal areas of security policies and mechanisms in the UDDI specification are related to data management, user identification, user authentication, user authorization, confidentiality of messages and integrity of data.
In order to authorize or restrict access to data in a UDDI registry, an implementation of a UDDI node MAY be integrated with one or more identification systems. An implementation specific policy MUST identify the identification system(s) used. Integration of UDDI APIs and data with an identification system MAY be implemented through the authentication and authorization APIs to provide access control as described in Section 5.3 Security Policy API Set. Other authentication and authorization mechanisms and policies are represented in UDDI through use of tModels to describe the Web services of a UDDI node.
UDDI also supports XML Digital Signatures on UDDI data to enable inquirers to verify the integrity of the data with respect to the publisher.
The security model for a registry and node can be extended beyond the mechanisms described in this specification and represented by modeling the UDDI Web services and through node and registry policy documentation.
1.8 Introduction to Internationalization
As part of its aim of providing a registry for universal description, discovery and integration, the UDDI specification includes support for internationalization features. These features fall into two broad groups:
· Support for multi-regional businesses, organization, and other Web service providers to:
o Describe their operations across international or inter-region units
o Specify the timezone of each operation’s contacts
· Support for internationalization of UDDI data and services such as:
o XML and the Unicode Character Set
o Postal address
o Use of multiple languages or multiple scripts of the same language
o Mechanisms to specify additional language-specific sorting order
o Consistent search results independent of language of information being searched
1.8.1 Multi-regional businesses
The UDDI specification provides features that enable Web service providers to describe the location of different aspects of the business, e.g. where it offers its products and services, where it is located, or even where it has stores, warehouses, or other branches.
1.8.2 XML and Unicode Character Set
The UDDI specification uses XML and the Unicode Character Set (up to and including version 3.0 of the Unicode Standard). By basing the programming interface on XML, multilingual handling capability is automatically achieved as XML uses the Universal Character Set (UCS) defined by both the Unicode Consortium and ISO 10646. The UCS is a character set that encompasses most of the language scripts used in computing.
1.8.3 Standardized Postal Address
In UDDI, an <address> element consists of a list of <addressLine> elements. While this is useful for publishing addresses in a UDDI registry or simply printing them on paper, the address’ logical structure and meaning is not explicit.
Moreover, different geographical regions specify their postal addresses differently
· By having different subelements (e.g. subdivisions, suburbs, lots, building identifications, floor numbers)
· By grouping/sequencing the subelements.
To overcome the first concern, the UDDI specification exposes an address’ structure and meaning by the use of attributes within each <addressLine> element to specify that line’s structure and meaning.
To overcome the second concern, the UDDI Business Registry has specified a canonical postal address structure with common address subelements (e.g. states, cities). This canonical address structure describes address data via name/code pairs, enabling each common address subelement to be identified by name or code[3].
1.8.4 Use of Multi-languages and Multi-scripts
Multinational businesses or businesses involved in international trading at times require the use of possibly several languages or multiple scripts of the same language for describing their business. The UDDI specification supports this requirement through two means, first by specifying the use of XML with its underlying Unicode representation, and second by permitting the use of the xml:lang attribute for various items such as names, addresses, and document descriptions to designate the language in which they are expressed. Further information on this may be found in Section 3.3.2.3 name.
1.8.5 Adding Language-specific Sort Orders
The Universal Character Set supported through XML consists of characters of most of the language scripts of the world. Each character has a distinct collation weight within the language for use in the collation sequencing process. Handling the sort orders of different language scripts, i.e. the assignment of collation weight values, can be very different, with the complexity of handling dependent on whether the script is alphabetic, syllabic, or ideographic. Some examples of sort order handling issues are:
· Where multiple languages share the same alphabetic script, it is possible for a common character to have different collation weights when used in the different languages.
· Ideographic languages have large character repertoires with multiple collation sequencing possibilities depending on whether phonetic or stroke-order sequencing is chosen.
· Where languages are bicameral (having upper and lower cases), collation sequencing could depend on whether case-sensitive or insensitive sorting is required. Conversely, specifying case-sensitive sort for non-bicameral languages is meaningless.
· Where the language inherently has an obvious collation sequence, fastest sorting is achieved by using binary sort.
The UDDI specification allows the collation sequence of results returned by the APIs to be specified via qualifiers. The specification also supports a mechanism to specify additional language-specific collation sequences for collating returned results.
1.8.6 Consistent Internationalized Search
The existence within the Universal Character Set of combining characters and of multiple representations for what users perceive as the same character results in different (by content and sometimes by length as well) XML strings that are the same when rendered visually. These different XML strings, though different in their encoded binary form, should produce positive match results during any search operation. This requirement makes it necessary to define a canonical XML string representation. The canonical representation chosen is that of the Unicode Normalization Form C[4]. For further details, see Section 4.6.1.1 Normalization and Canonicalization.
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 |
http://uddi.org/schema/uddi_v3subscription.xsd |
|
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 |
http://uddi.org/schema/uddi_v3subscriptionListener.xsd |
|
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 |
http://uddi.org/schema/uddi_v3replication.xsd |
|
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 |
http://uddi.org/schema/uddi_v3policy.xsd |
|
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 |
http://uddi.org/schema/uddi_v3policy_instanceParms.xsd |
|
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 |
|
xml:lang |
string |
26 |
2.3.2 Subscription API
|
Element/attribute Name |
Data Type |
Length |
|
brief |
boolean |
|
|
endPoint |
dateTime |
|
|
notificationInterval |
duration |
|
|
expiresAfter |
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:uddi.org:ubr:categorization:iso3166"
keyName=""
keyValue="US-CA" />
<keyedReference
tModelKey="uddi:uddi.org:ubr:categorization:iso3166"
keyValue="US-CA" />
Semantically speaking from the perspective of UDDI, omitted attributes are identical to empty attributes. However, with respect to signing, specifically, canonicalization, omitted attributes are different from empty attributes. Therefore, the digital signatures of the above two keyedReferences are different, even though clients would consider the two keyedReferences be identical.
The difference, from a perspective of canonicalization, puts additional burden on clients in publishing entities. As a result, when applicable, the data structure elements of UDDI API Schema define default values for optional attributes, so that omitted attributes are treated as attributes with default value with respect to signing.
The exceptions are xml:lang and keyValue in addressLine. Both prohibit empty string. Hence, the ambiguity discussed above is not applicable. In the case of xml:lang, empty string is not a valid language code. In the case of keyValue in addressLine, the definition of keyValue requires the string to have a minimal length of one.
3.3 businessEntity Structure
Each businessEntity entity contains descriptive information about a business or organization and, through its contained businessService entities, information about the services that it offers. From an XML standpoint, the businessEntity is the top-level data structure that holds descriptive information about the business or organization it describes. Each contained businessService describes a logical service offered by the business or organization. Similarly, each bindingTemplate contained within a given businessService provides the technical description of a Web service that belongs to the logical service that is described by the businessService.
3.3.1 Structure diagram
|
Name |
Use |
|
businessKey |
optional |
3.3.2 Documentation
A given instance of the businessEntity structure is uniquely identified by its businessKey. When a businessEntity is published within a UDDI registry, the businessKey MUST be omitted if the publisher wants the registry to generate a key. When a businessEntity is retrieved from a UDDI registry, the businessKey MUST be present.
discoveryURLs is a list of Uniform Resource Locators (URL) that point to alternate, file based service discovery mechanisms.
Simple textual information about the businessEntity, potentially in multiple languages, is given by its name, short business description and contacts. The required, non-empty name and the optional description can occur multiple times. contacts is a simple list of single contact information.
businessServices is a list of business services provided by the businessEntity.
In addition to the businessKey, that uniquely identifies the businessEntity within the registry, the identifierBag contains a list of other identifiers, each valid in its own identifier system. Examples of identifiers are a tax identifier or D-U-N-S® number.
The categoryBag contains a list of business categories that each describes a specific business aspect of the businessEntity. Examples of categories are industry, product category or geographic region.
A businessEntity entity MAY be digitally signed using XML digital signatures. When a businessEntity is signed, each digital signature MUST be provided by its own dsig:Signature element. Appendix I Support for XML Digital Signatures covers the use of this element in accordance with the XML-Signature specification.
3.3.2.1 discoveryURLs
The discoveryURLs structure is a simple container of one or more discoveryURL elements.
3.3.2.2 discoveryURL
A discoveryURL is a URL that points to Web addressable (via HTTP GET) discovery documents. The expected return document is not defined. Rather, a framework for establishing conventions is provided, and a particular convention is defined within this specification.
Attributes
|
Name |
Use |
|
useType |
optional |
Each individual discoveryURL MAY be adorned with a useType attribute that designates the name of the convention that the referenced document follows. A reserved convention value is "businessEntity". It is RECOMMENDED that discoveryURLs qualified with this value point to XML documents of the type businessEntity, as defined in the UDDI API Schema.
An example of a discoveryURL, generated by a UDDI node that is accessible at www.example.com and rendered by the publisher of the businessEntity that is identified by the businessKey "uddi:example.com:registry:sales:53", is:
<discoveryURL useType="businessEntity">
http://www.example.com?businessKey=uddi:example.com:registry:sales:53
</discoveryURL>
Another reserved value for discoveryURL is "homepage". Adorning a discoveryURL with this value signifies that a business’s homepage can be discovered at that URL.
3.3.2.3 name
A businessEntity MAY contain more than one name. Multiple names are useful, for example, in order to specify both the legal name and a known abbreviation of a businessEntity, or in order to support romanization (see Appendix D Internationalization).
Attributes
|
Name |
Use |
|
xml:lang |
optional |
When a name is expressed in a specific language (such as the language into which a name has been romanized), it SHOULD carry the xml:lang attribute to signify this. When a name does not have an associated language (such as a neologism not associated with a particular language), the xml:lang attribute SHOULD be omitted.
As is defined in the XML specification, an occurrence of the xml:lang attribute indicates that the content to which it applies (namely the element on which it is found and to all its children, unless subsequently overridden) is to be interpreted as being in a certain natural language. Legal values for such attributes conform to RFC 3066[5] with one exception: UDDI imposes a maximum length of 26 characters.
As is the case for RFC 3066, all tags are to be treated as case insensitive; there exist conventions for capitalization of some of them, but these should not be taken to carry meaning. For instance, [ISO 3166] recommends that country codes are capitalized (MN Mongolia), while [ISO 639] recommends that language codes are written in lower case (mn Mongolian).
Examples include: "EN-us", "FR-ca".
3.3.2.4 description
A businessEntity can contain several descriptions, for example, in different languages.
Attributes
|
Name |
Use |
|
xml:lang |
optional |
In order to signify the language in which the descriptions are expressed, they MAY carry xml:lang values. There is no restriction on the number of descriptions or on what xml:lang value that they may have.
3.3.2.5 contacts
The contacts structure itself is a simple collection of one or more contact structures.
3.3.2.6 contact
The contact structure records contact information for a person or a job role within the businessEntity so that someone who finds the information can make human contact for any purpose. This information consists of one or more optional elements, along with a person’s name. Contact information exists by containment relationship alone; the contact structure does not provide keys for tracking individual contact instances.
Attributes
|
Name |
Use |
|
useType |
optional |
The useType attribute is used to describe the type of contact in unstructured text. Suggested examples include "technical questions", "technical contact", "establish account", "sales contact", etc.
description is used to describe how the contact information should be used. Publishing several descriptions, e.g. in different languages, is supported. To signify the language in which the descriptions are expressed, they MAY carry xml:lang values.
personName is the name of the person or name of the job role supporting the contact. Publishing several names, e.g. for romanization purposes, is supported.
Attributes
|
Name |
Use |
|
xml:lang |
optional |
In order to signify the contextual language (if any) in which a given name is expressed in (such as the language into which a name has been romanized), it SHOULD carry the xml:lang attribute See Section 3.3.2.3 name for details on using xml:lang values in name elements. There is no restriction on the number of personNames or what xml:lang value each may have. An example for a role might be:
<contact useType="Technical support">
<personName>Administrator</personName>
…
</contact>
phone is used to hold telephone numbers for the contact. This element MAY be adorned with an optional useType attribute for descriptive purposes.
email is the email address for the contact. This element MAY be adorned with an optional useType attribute for descriptive purposes.
address is the postal address for the contact.
3.3.2.7 address
address represents the contact’s postal address, in a form suitable for addressing an envelope. The address structure is a simple list of address lines.
Attributes
|
Name |
Use |
|
xml:lang |
optional |
|
useType |
optional |
|
sortCode |
optional |
|
tModelKey |
optional |
Address structures have four optional attributes.
The xml:lang value describes the language the address is expressed in. There is no restriction on the number of addresses or what xml:lang value they may have. Publication of addresses in several languages, e.g. for use in multilingual countries, is supported. See Appendix D Internationalization for an example.
The useType describes the address’ type in unstructured text. Suggested examples include "headquarters", "sales office", "billing department", etc.
The sortCode attribute is deprecated because of the guarantee of preserving the document order (see Section 4.5.3 Preservation of Document Order). In order to achieve this behavior, the data has just to be published in the desired order.
The tModelKey is a tModel reference that specifies that keyName keyValue pairs given by subsequent addressLine elements, if addressLine elements are present at all, are to be interpreted by the address structure associated with the tModel that is referenced. For a description of how to use tModels in order to give the addressLine list structure and meaning, see Appendix D Internationalization.
3.3.2.8 addressLine
addressLine contains a part of the actual address in text form.
Attributes
|
Name |
Use |
|
keyName |
optional |
|
keyValue |
optional |
Each addressLine element MAY be adorned with two optional descriptive attributes, keyName and keyValue. Both attributes MUST be present in each address line if a tModelKey is specified in the address structure. When no tModelKey is provided for the address structure, the keyName and keyValue attributes have no defined meaning.
3.3.2.9 businessServices
The businessServices structure is used to describe families of Web services. This simple container holds one or more businessService entities (see Section 3.4 businessService structure).
3.3.2.10 identifierBag
The optional identifierBag element allows businessEntity structures to be identified according to published identifier systems, for example, Dun & Bradstreet D-U-N-Sâ numbers or tax identifiers.
An identifierBag is a list of one or more keyedReference structures, each representing a single identification.
For a full description on how to establish an identity, see Appendix E Using Identifiers.
3.3.2.11 keyedReference (in identifierBags)
A keyedReference, when included in an identifierBag, represents an identifier of a specific identifier system.
Attributes
|
Name |
Use |
|
tModelKey |
required |
|
keyName |
optional |
|
keyValue |
required |
The keyedReference consists of the three attributes tModelKey, keyName and keyValue. The required tModelKey refers to the tModel that represents the identifier system, and the required keyValue contains the actual identifier within this system. The optional keyName MAY be used to provide a descriptive name for the identifier. Omitted keyNames are treated as empty keyNames.
For example, identifying SAP AG by its Dun & Bradstreet D-U-N-S® Number, using the corresponding tModelKey within the UDDI Business Registry, is done as follows:
<identifierBag>
<keyedReference
tModelKey="uddi:uddi.org:ubr:identifier:dnb.com:d-u-n-s"
keyName="SAP AG"
keyValue="31-626-8655" />
</identifierBag>
3.3.2.12 categoryBag
The optional categoryBag element allows businessEntity structures to be categorized according to published categorization systems. For example, a businessEntity might contain UNSPSC product and service categorizations that describe its product and service offering and ISO 3166 geographical regions that describe the geographical area where these products and services are offered.
Similar to the identifierBag, a categoryBag contains a simple list of keyedReference structures, each containing a single categorization. The categoryBag MAY also contain a simple list of keyedReferenceGroup structures. At least one keyedReference or one keyedReferenceGroup MUST be provided within the categoryBag.
For a full description of how to establish a categorization, see Appendix F Using Categorization.
3.3.2.13 keyedReference (in categoryBags)
As within an identifierBag (see Section 3.3.2.13 keyedReference (in identifierBags)), a keyedReference contains the three attributes tModelKey, keyName and keyValue. The required tModelKey refers to the tModel that represents the categorization system, and the required keyValue contains the actual categorization within this system. The optional keyName can be used to provide a descriptive name of the categorization. Omitted keyNames are treated as empty keyNames. A keyName MUST be provided in a keyedReference if its tModelKey refers to the general_keywords category system (see also Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups).
For example, in order to categorize a businessEntity as offering goods and services in California, USA, using the corresponding ISO 3166 tModelKey within the UDDI Business Registry, one would add the following keyedReference to the businessEntity’s categoryBag:
<keyedReference
tModelKey="uddi:uddi.org:ubr:categorization:iso3166"
keyName="California, USA"
keyValue="US-CA" />
3.3.2.14 keyedReferenceGroup
A keyedReferenceGroup, by itself, is a simple list of keyedReference structures that logically belong together.
Attributes
|
Name |
Use |
|
tModelKey |
required |
The keyedReferenceGroup MUST contain a tModelKey attribute that specifies the structure and meaning of the keyedReferences contained in the keyedReferenceGroup. A keyedReferenceGroup MUST also contain at least one keyedReference when published.
For example, to categorize a businessEntity as being located at the geodetic point that is specified by the latitude/longitude pair 49.6827/8.2952 using the corresponding World Geodetic System 1984 (WGS 84) tModelKey within the UDDI Business Registry, one would add the following keyedReferenceGroup to the businessEntity’s categoryBag:
<keyedReferenceGroup tModelKey="uddi:uddi.org:ubr:categorizationGroup:wgs84"
>
<keyedReference
tModelKey="uddi:uddi.org:ubr:categorization:wgs84:latitude"
keyName="WGS 84 Latitude"
keyValue="+49.682700" />
<keyedReference
tModelKey="uddi:uddi.org:ubr:categorization:wgs84:longitude"
keyName="WGS 84 Longitude"
keyValue="+008.295200" />
</keyedReferenceGroup>
3.4 businessService Structure
The businessService structure represents a logical service and contains descriptive information in business terms. A businessService is the logical child of a single businessEntity, the provider of this businessService. Technical information about the businessService is found in the contained bindingTemplate entities.
In some cases, businesses would like to share or reuse services, e.g. when a large enterprise publishes separate businessEntity structures. This can be done by using the businessService structure as a projection to a published businessService, as explained below.
3.4.1 Structure Diagram
|
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 a mandatory repeating element, used to house references to remote descriptive information or instructions related to the use of a particular tModel and its instanceParms. Multiple overviewDoc elements are useful, for example, to handle alternative representations of the documentation.
The instanceParms is an optional element of type string, used to locally contain settings or parameters related to the proper use of a tModelInstanceInfo. The suggested format is a namespace-qualified XML document so that the settings or parameters can be found in the XML documents elements and attributes.
At least one overviewDoc or instanceParms MUST be provided within the instanceDetails.
3.5.2.5 overviewDoc
This structure describes overview information about a particular tModel use within a bindingTemplate.
The description is a mandatory repeating element. Each description, optionally qualified by an xml:lang attribute, holds a short descriptive overview of how a particular tModel is to be used.
The optional overviewURL is to be used to hold a URL that refers to a long form of an overview document that covers the way a particular tModel is used as a component of an overall Web service description.
At least one description or an overviewURL MUST be provided within the overviewDoc.
3.5.2.6 overviewURL
The RECOMMENDED format for the overviewURL is a URI that is suitable for retrieving the actual overview document with an HTTP GET operation, for example, via a Web browser.
Attributes
|
Name |
Use |
|
useType |
optional |
The optional useType attribute is used to provide information about the type of document at that URL. One common value used in the useType attribute is "text". Using this value denotes that the overviewURL contains additional textual information. The content of the useType attribute may contain other values. See Appendix B Using and Extending the useType Attribute for more information.
3.6 tModel Structure
Making it easy to describe Web services in ways that are meaningful enough to be useful during searches is an important goal of UDDI. Another goal is to provide a facility to make these descriptions complete enough that people and programs can discover how to interact with Web services they do not know much about. To do this, there needs to be a way to mark a description with information that designates how it behaves, what conventions it follows, and what specifications or standards the service complies with.
Providing the ability to describe compliance with specifications, concepts, or even shared design is one of the roles that the tModel structure fills.
Each tModel instance is a keyed entity in UDDI. In a general sense, the purpose of tModel entities is to provide a reference system based on abstraction. There are two primary uses for tModel entities: as sources for determining compatibility of Web services and as keyed namespace references.
3.6.1 Common tModel uses
There are several places within a businessEntity that can refer to tModels. References to the same tModel instance can be found in many businessEntity structures. tModel references also occur in various API calls.
Section 3.6 tModel Structure gives an overview of the different types of tModels.
3.6.1.1 Defining the technical fingerprint
One common use for tModel entities is to represent technical specifications or concepts. For example, a tModel can be used to represent a specification that defines wire protocols, interchange formats and interchange sequencing rules. Examples can be seen in the RosettaNet Partner Interface Processes[6] specification, the Open Applications Group Integration Specification[7] and various Electronic Document Interchange (EDI) efforts.
Software that communicates with other software invariably adheres to some pre-agreed specifications. In situations where this is true, the designers of the specifications can establish a unique technical identity within a UDDI registry by publishing information about the specification in a tModel. While the main reason of registering a tModel with a specific UDDI registry is to define its identity, the actual specification or set of documents that describes the concept of a tModel is not a part of the registry and is remotely referenced using the overviewDoc structure. Publishers SHOULD choose well-known formats and description languages for the documents that describe the concept each tModel represents.
Once a tModel is published, other parties can express the availability of Web services that are compliant with a specification the tModel represents by simply including a reference to the tModel – i.e., its tModelKey – in their technical service descriptions bindingTemplate data.
This approach facilitates searching for registered Web services that are compatible with a particular specification. Once the proper tModelKey value is known, it is easy to discover that a particular businessEntity has registered a Web service that references the tModel. In this way, the tModelKey becomes a technical fingerprint that is unique to a given specification.
3.6.1.2 Defining value sets
The second general use for tModel entities is within the identifierBag, categoryBag, address and publisherAssertion structures that are used to specify organizational identity and various categories. Used in this context, a tModel represents the system of values used to identify or categorize UDDI entities.
For example, to represent the fact that a business described by a businessEntity has a particular US Tax identifier, a keyedReference is placed into the identifierBag of the businessEntity. The keyedReference has a keyValue that is the tax ID and refers to the tModel that means "the system of US Tax code identifiers". Together, the keyValue and the tModel reference specify a particular value in a particular system of values.
3.6.1.3 Defining a find qualifier
The third general use for tModel entities is to represent find qualifiers. Find qualifiers are values that modify how the find_xx APIs work. For example, to cause find_business to sort its results in the order in which they were published, the uddi:uddi.org:findqualifier:sortbydateasc may be specified. See Section 5.1.4 Find Qualifiers for details.
3.6.2 Structure diagram
Attributes
|
Name |
Use |
|
tModelKey |
optional |
|
deleted |
optional |
3.6.3 Documentation
A given tModel entity is uniquely identified by its tModelKey. When a tModel is published within a UDDI registry, the tModelKey MUST be omitted if the publisher wants the registry to generate a key. When a tModel is retrieved from a UDDI registry, the tModelKey MUST be present.
In retrieved tModel data, the deleted attribute, an information-only field, indicates whether the tModel is logically deleted. The two allowed values for this attribute are "true" and "false".
Simple textual information about the tModel, potentially in multiple languages, is given by its name and short description. While the tModel has exactly one non-empty name, it can have zero or more descriptions. The name SHOULD be formatted as a URI and, as a consequence, the xml:lang attribute of the name element SHOULD NOT be used. More information about the structure of the name and description elements can be found in Section 3.3 businessEntity structure.
The overviewDoc is an optional repeating element, used to house references to remote descriptive information or instructions related to the tModel. For more information about the structure of the overviewDoc v, see Section 3.5 bindingTemplate Structure.
The optional useType attribute contained in the overviewURL of the overviewDoc is used to provide information about the type of document at that URL. One common value used in the useType attribute is "text". Using this value denotes that the overviewURL contains additional textual information. Another common value is "wsdlInterface", which is used to designate that the overviewURL contains a WSDL interface document that can be re-used by many implementations. The content of the useType attribute may contain other values. See Appendix B Using and Extending the useType Attribute for more information.
In addition to the tModelKey that uniquely identifies the tModel within the registry, the identifierBag contains a list of logical identifiers, each valid in its own identifier system. For more information about identifierBags, see Section 3.3 businessEntity Structure.
The categoryBag contains a list of categories that describe specific aspects of the tModel (e.g. its technical type). Each category is valid in its own category system. For more information about categoryBags, see Section 3.3 businessEntity structure.
A tModel entity MAY be digitally signed using XML digital signatures. When a tModel is signed, each digital signature MUST be provided by its own dsig:Signature element. Appendix I Support for XML Digital Signatures covers the use of this element in accordance with the XML-Signature specification.
3.7 publisherAssertion Structure
Many businesses and organizations are not effectively represented by a single businessEntity, because their description and discovery are likely to be diverse. Examples include corporations with a variety of subsidiaries, private exchanges with sets of suppliers and their customers and industry consortiums with their members. An obvious solution is to publish several businessEntity structures. Such a set of businessEntity structures represents a more or less coupled community whose members often would like to make some of their relationships visible in their UDDI registrations. This may be accomplished by using the publisherAssertion structure. To eliminate the possibility that one publisher claims a relationship to another that is not reciprocated, both publishers must publish identical assertions for the relationship to become visible. More detailed information about relationships and publisher assertions is given in Appendix A Relationships and Publisher Assertions.
3.7.1 Structure Diagram
3.7.2 Documentation
The two businessEntity instances between which an assertion is made are uniquely identified by the required fromKey and toKey elements. The keyedReference describes the relationship between the businessEntity elements identified by fromKey and toKey. Similar to the general behavior of a keyedReference in a categoryBag (see full description in Section 3.3 businessEntity Structure), the included tModelKey uniquely identifies the relationship type system and the keyName keyValue pair designate a specific relationship type within this value set. Omitted keyNames are treated as empty keyNames.
A publisherAssertion entity MAY be digitally signed using XML digital signatures. When a publisherAssertion is signed, each digital signature MUST be provided by its own dsig:Signature element. Appendix I Support For XML Digital Signatures covers the use of this element in accordance with the XML-Signature specification.
3.8 operationalInfo Structure
Information about a publishing operation is captured whenever a UDDI core data structure is published. This data includes the date and time that the data structure was created and modified, the identifier of the UDDI node at which the publish operation took place, and the identity of the publisher. Operational information for a UDDI data structure is made accessible using the get_operationalInfo inquiry API. See Section 5.1.16 get_operationalInfo.
The operationalInfo structure is used to convey the operational information for the UDDI core data structures, that is, the businessEntity, businessService, bindingTemplate and tModel structures.
3.8.1 Structure diagram
Attributes
|
Name |
Use |
|
entityKey |
required |
3.8.2 Documentation
The UDDI entity with which the operationalInfo is associated is uniquely identified by the required entityKey attribute.
The created element indicates the instant in time at which the entity with which the operationalInfo is associated first appeared in a registry.
The modified element indicates the instant in time at which the entity with which the operationalInfo is associated was last changed by a save operation that may have updated its content. This will initially be equivalent to the value of the created element, but will diverge as changes are made over time.
Some UDDI core data structures are containers of other UDDI core data structures. For instance, businessService elements are contained by businessEntity elements and bindingTemplate elements are contained by businessService elements. Independent changes made to contained entities of such entities (for example, changes to an existing businessService within a businessEntity by means of a save_service API call) do not affect the value of the modified element associated with the containing entity. Instead, the modifiedIncludingChildren element in the containing entity contains the maximum of its own modified element and the modifiedIncludingChildren elements of each of the entities it contains (if any). If a contained entity is deleted or moved elsewhere, the modifiedIncludingChildren element is also updated, since such operations would otherwise not be documented elsewhere. Changes in a service that is being projected do not affect the modifiedIncludingChildren element of the businessEntity in which it is projected. The modifiedIncludingChildren element should not be returned for operationalInfo elements corresponding to bindingTemplate or tModel elements since there are no contained elements that can be modified independently.
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).
In a registry with multiple nodes, the operationalInfo MUST include the information required so that inquiry results are consistent across all nodes. The nodeID, authorizedName, modified and created elements are mandatory in multiple node registries both in responses to get_operationalInfo calls and in replication changeRecords containing operationalInfo elements. The modifiedIncludingChildren element MUST also be present in multiple node registries for operationalInfo elements corresponding to businessEntity and businessService elements.
UDDI specifies a number of API sets that are described in Chapter 5 UDDI Programmer APIs and Section 7.4 Replication API Set. If a node claims to support a UDDI API it MUST implement the API in conformance with this specification. Node and registry policy determine the transport and security mechanisms used for each API set. See Chapter 9 Policy for more information.
A UDDI registry MUST have at least one node that offers a Web service compliant Inquiry API set. A UDDI registry SHOULD have at least one node that offers a Web service compliant with the Publication, Security, and Custody and Ownership Transfer API sets. If a UDDI registry has multiple nodes, all nodes SHOULD offer Web services that are compliant with the Replication API set. The Subscription and Value Set API sets are OPTIONAL for all nodes and all registries.
The API descriptions that follow in Chapter 5 UDDI Programmers APIs designate input elements as optional or required. Required input elements MUST be provided within the guidelines described by the UDDI schema and in the API descriptions. Optional input elements MAY be provided, and when they are, they too must follow the guidelines described by the UDDI schema and in the API description.
4.1 SOAP Usage
This section describes the SOAP specific conventions and requirements applicable to UDDI.
Any use of SOAP by a UDDI implementation that differs from or extends the behavior described below should be modeled by publishing a tModel to represent this different use of SOAP. Any Web services that make use of the different SOAP behavior should reference the tModel in the tModelInstanceDetails of the Web service’s bindingTemplate. See Section 9.4.4 UDDI Data and Information Model for more information.
4.1.1 Support for SOAPAction
SOAP 1.1 requires the presence of the Hyper Text Transport Protocol (HTTP) header field named SOAPAction when an HTTP binding is specified. UDDI requires the presence of this HTTP Header field to be SOAP 1.1 compliant. Different SOAP toolkits treat this HTTP header field differently. For maximum tool compatibility, the SOAPAction may contain any value, including an empty string.
Both of the following message styles (among others) are permitted in UDDI.
POST /someVerbHere HTTP/1.1
Host: www.somenode.org
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: ""
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<get_bindingDetail xmlns="urn:uddi-org:api_v3">
…
and
POST /someVerbHere HTTP/1.1
Host: www.somenode.org
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "get_bindingDetail"
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<get_bindingDetail xmlns="urn:uddi-org:api_v3">
…
4.1.2 Support for SOAP Actor
The SOAP Actor feature is not supported by UDDI. UDDI nodes MUST reject any request that arrives with a SOAP Actor attribute in the SOAP Header element by returning a generic SOAP fault with no detail element and a "Client" faultcode. The faultstring will clearly indicate the problem.
4.1.3 Support for SOAP encoding
The SOAP encoding feature (i.e., SOAP 1.1. section 5) is not supported by UDDI. In messages sent to a UDDI node there must be no claims made about the encoding style of any element within the "urn:uddi-org:*" namespace. If such claims are made, the node must respond with a generic SOAP fault with no detail element and a "Client" faultcode. The faultstring will clearly indicate the problem
4.1.4 Support for SOAP Headers
UDDI registries MAY ignore the contents of SOAP header. SOAP headers that have the must_understand attribute set to true MUST be rejected with a SOAP fault - MustUnderstand. UDDI registries MAY ignore other extension headers received.
4.1.5 Support for SOAP Fault
UDDI registries signal a generic SOAP Fault[8] when unknown API references are invoked, validation failures occur, etc. UDDI specific errors MUST be handled via a SOAP Fault element containing a UDDI dispositionReport element. The following SOAP fault codes are used:
· VersionMismatch: An invalid namespace reference for the SOAP envelope element was passed. The valid namespace value is "http://www.xmlsoap.org/soap/envelope/".
· MustUnderstand: A SOAP header element, permitted to be ignored by a UDDI node, was received with the Must_Understand attribute set to true. In response, a UDDI node MUST return this response. See Section 4.8 Success and Error Reporting and Chapter 12 Error Codes.
· Client: A message was incorrectly formed or did not contain enough information to perform more exhaustive error reporting.
· Server: The Server class of errors indicate that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to the processing of the message. For example, processing could include communicating with an upstream processor which did not respond. The message may succeed at a later point in time.
4.1.6 XML prefix conventions – default namespace support
UDDI nodes are REQUIRED to support the use of the default namespaces (i.e. no XML prefix) in SOAP request and response documents as shown in the following HTTP example:
POST /someVerbHere HTTP/1.1
Host: www.example.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: ""
<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<get_bindingDetail xmlns="urn:uddi-org:api_v3">
…
4.2 XML Encoding Requirements
All messages sent to and received from UDDI nodes MUST be encoded in either UTF-8 or UTF-16, and MUST specify the Hyper Text Transport Protocol (HTTP) Content-Type header with a charset parameter of "utf-8" or "utf-16" respectively and a content type of text/xml. Other encoding name variants, such as UTF8, UTF_8, etc. MAY NOT be used.
All parts of the Content-type header are case insensitive and quotations are optional[9]. UDDI nodes MUST reject messages that do not conform to this requirement. For simplification purposes, all examples in this document use UTF-8.
An example of a valid HTTP Content-Type header specifying UTF-8 encoding of the message is:
Content-type: text/xml; charset="utf-8"
An example of a valid HTTP Content-Type header specifying UTF-16 encoding of the message is:
Content-type: text/xml; charset="utf-16"
4.3 Support for Unicode: Byte Order Mark
Unicode UTF-8 allows data to be transmitted with an OPTIONAL three-byte signature, also known as Byte Order Mark (BOM), preceding the XML data. This signature does not contain information that is useful for decoding the contents; but, in the case of UTF-8, tells the receiving program that the rest of the text is in UTF-8. Its presence makes no difference to the endianness of the byte stream as UTF-8 always has the same byte order. The BOM is not part of the textual content therefore UDDI nodes MAY remove the BOM prior to processing messages received.
UDDI nodes MUST be prepared to accept messages that contain Byte Order Marks, but the Byte Order Mark is not required to process SOAP messages successfully.
UDDI nodes MUST NOT return a Byte Order Mark with any of the response messages defined in this specification.
All UDDI nodes MUST support all of the Unicode characters, including all compatibility characters. See Section 4.6.1.1 XML Normalization and Canonicalization for further information on required behavior with respect to character set normalization and canonicalization.
4.4 About uddiKeys
UDDI registries MUST use keys that conform to the following grammar. All UDDI keys are URIs that conform to RFC 2396 but not all URIs are valid UDDI keys. The URIs that are valid as UDDI keys correspond to a subset of the opaque part alternative of the absoluteURI rule in RFC 2396. Further, registries MUST use keys from the scheme "uddi" following the syntactic and semantic rules for that scheme as given in this section, in Section 5.2.2 Publishing Entities with Publisher Assigned Keys, in Section 8.2 Data Management Policies and Procedures Across Registries, and Section 9.4.3 Policy Abstractions for the UDDI keying scheme. The primary motivations for the scheme for uddiKeys is to allow publishers to specify keys for entities they publish in UDDI registries using "sensible looking" keys and to promote interoperation among UDDI registries. See Chapter 10 Multi-Version Support for issues regarding backwards compatibility.
Keys in UDDI are declared as language independent case insensitive and must be case-folded by nodes as part of processing any API. With the inclusion of the attribute caseMapKind="fold" from Schema Centric Canonicalization in the schema declaration for uddiKey type, the normalized form of a uddiKey element is produced using Unicode Case Folding as defined in the Unicode Technical Report on Case Mappings (see http://www.unicode.org/unicode/reports/tr21/).
A derivedKey has the form uddiKey ":" KSS, where the key specific string (KSS) is composed of upper and lowercase characters, numbers, and other symbols permitted in a URI. See Section 5.2.2.1 Key generator keys and their partitions for a description of derivedKey.
4.4.1 Key Syntax[10]
uddiScheme = %d117.100.100.105 ; "uddi" in lower case
uddiKey = nonKeyGeneratorKey / keyGeneratorKey
nonKeyGeneratorKey = uuidKey / domainKey / derivedKey
uuidKey = uddiScheme ":" uuid_part
uuid_part = 8HEXDIG "-"
4HEXDIG "-"
4HEXDIG "-"
4HEXDIG "-"
12HEXDIG
domainKey = uddiScheme ":" hostname
hostname = *(domainlabel ".") toplabel ["."]
domainlabel = alphanum / alphanum *(alphanum / "-") alphanum
toplabel = ALPHA / ALPHA *(alphanum / "-") alphanum
alphanum = ALPHA / DIGIT
derivedKey = nonKeyGeneratorKey ":" KSS (Key Specific String)
keyGeneratorKey = nonKeyGeneratorKey ":" "keygenerator"
KSS = 1*uric ; KSS MUST NOT be "keygenerator"
uric = reserved / unreserved / escaped
reserved = ";" / "/" / "?" / "@" / "&" / "=" / "+" / "$" / ","
unreserved = alphanum / mark
mark = "-" / "_" / "." / "!" / "~" / "*" / "’" / "(" / ")"
escaped = "%" HEXDIG HEXDIG
There are some extra restrictions on domain names that are not captured in the ABNF syntax above:
1. The maximum length of a string representation of a hostname is 253 characters/octets.
2. The maximum length of an individual domainlabel is 63 characters/octets.
There is an additional restriction on the Key Specific Sting (KSS) that is not captured in the ABNF syntax above:
1. KSS MUST NOT be "keygenerator".
The keyword "keygenerator" is case-insensitive.
4.4.2 Examples of keys
The following are examples of legal domainKeys.
uddi:tempuri.com
Here, "tempuri.com" is the domain of this key.
uddi:us.tempuri.com
Here, "us.tempuri.com" is the domain.
The following is an example of a legal uuidKey.
uddi:4CD7E4BC-648B-426D-9936-443EAAC8AE23
"4CD7E4BC-648B-426D-9936-443EAAC8AE23" is the uuid of this key.
The following are examples of legal derivedkeys
uddi:AC104DCC-D623-452F-88A7-F8ACD94D9B2B:xyzzy
This is a derived Key based on the <uuidKey> "uddi:AC104DCC-D623-452F-88A7-F8ACD94D9B2B". The string "xyzzy" is key’s KSS.
uddi:tempuri.com:fish:buyingservice
This key is based on the derivedKey "uddi:tempuri.com:fish". The string "buyingService" is the key’s KSS.
The following is an example of a legal key generator key
uddi:tempuri.com:keygenerator
This key is based on the domainKey "uddi:tempuri.com"
4.5 Data insertion and document order
4.5.1 Inserting Data in Entities During save_xx Operations
When saving a businessEntity, businessService, bindingTemplate or tModel, the UDDI node is required to add or replace certain elements and attributes if they are not present or are incorrectly specified in the entity passed to the save_xx API. These are: For businessEntity, businessService, bindingTemplate and tModel structures, the businessKey, serviceKey, bindingKey, and tModelKey of the structure being saved.
4.5.2 Inserting Elements in Existing Entities
When a new child element is inserted by a publication API, the UDDI node MUST add the new child as the last of its siblings. For example, the save_service call can be used to add a businessService to a businessEntity. The added businessService appears as the last one in the (possibly single item) list of such businessService structures. When inserting a businessService using save_service or a bindingTemplate using save_binding, any digital signatures on the containing UDDI data structure may become invalid with the addition of a new child.
4.5.3 Preservation of Document Order
The UDDI data model requires UDDI nodes to preserve the order of all descendent elements in the UDDI core data structures. When a UDDI node responds to an inquiry API call, the descendent elements of the core data structures in the response must have the order specified by their publishers or by the order of insertion.
Preservation of document order in UDDI implies that all elements in a sequence MUST be preserved. It is a requirement not to de-duplicate elements of a sequence, other than for keyed entities as described in sections 5.2.16.4 save_business return section and 5.2.17.4 save_service return section.
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).[11]
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[12] 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
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 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 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.1.9 UDDI Registry API tModels.
5.1 Inquiry API Set
The inquiry API set allows one to locate and obtain detail on entries in a UDDI registry. The Inquiry API provides three forms of query that follow broadly used conventions which match the needs of software traditionally used with registries. Three distinct patterns of inquiry are supported.
5.1.1 The browse pattern
Software that allows people to explore and examine large quantities of data requires browse capabilities. The browse pattern characteristically involves starting with some broad information, performing a search, finding general result sets and then selecting more specific information for drill-down.
This specification supports the browse pattern by way of the API calls involving "find" operations (hereafter referred to as the "find_xx" APIs). These calls form the search capabilities provided by the API and are matched with summary return structures that return overview information about the registered information associated with the inquiry API and the search criteria specified in the inquiry.
A typical browse sequence might involve finding whether a particular business with a particular name has any information registered. This sequence starts with a call to find_business, passing the business name (which could involve the use of just a portion of the name together with a wildcard character by using the approximateMatch findQualifier described below). This returns a businessList result - overview information (keys, names and descriptions) derived from the registered businessEntity information, matching on the name. Information in the list may be used to select among the businesses and then to drill down into the corresponding businessService information, looking for one which matches a particular technical fingerprint (i.e., tModel such as for purchasing, shipping, etc) using the find_service API call. UDDI provides many similar sequences of API calls that let callers start with a broad notion of the kind of information they wish to retrieve from a registry, retrieve summary information, and then drill down to get details.
5.1.2 The drill-down pattern
Each instance of the core data structures – businessEntity, businessService, bindingTemplate and tModel – has a key which is one of the items in the summary information retrieved by find_xx APIs. Given such a key, it is easy to retrieve the full registered details for the corresponding instance by passing the key to the relevant get_xx API.
Continuing the example from the previous section on browsing, the businessKey associated with the business being sought is one of the items in the businessList returned by find_business. This key can be passed as an argument to get_businessDetail. Upon success, this API returns a businessDetail containing the full registered information, including the businessEntity structure for the entity whose key value was passed.
5.1.3 The invocation pattern
To have an application take advantage of a Web service that is registered within a UDDI registry, that application must be prepared to use the information found in the registry for the specific Web service being invoked. This type of inter-business service call has traditionally been a task that is undertaken entirely at development time. The degree to which this changes with Web services is an application design choice, but the existence of UDDI registry entries makes it significantly easier to do dynamic binding using the following pattern.
Obtain the bindingTemplate data for the Web service of interest from a UDDI registry, such as the UDDI Business Registry. Typically this is done using one of the browse-and-drill-down patterns discussed above. The bindingTemplate contains the specific details about an instance of a given interface type, including the location at which a program starts interacting with the Web service. The calling application caches this information and uses it to contact the Web service at the registered address whenever it needs to communicate with the Web service instance.
If a call fails using cached information previously obtained from a UDDI registry, the application SHOULD query the UDDI registry for fresh bindingTemplate information. The proper call is get_bindingDetail passing the original bindingKey value. If the data returned is different from the cached information, the application SHOULD retry the invocation using the fresh information. If the result of this retry is successful, the new information SHOULD replace the cached information.
By using this pattern with Web services, applications can interact with partners without undue communication and coordination costs. For example, if a business has activated a disaster recovery site, most of the calls from partners will fail when they try to invoke Web services at the failed site. By updating the UDDI information with the new address for the Web service, partners who use the invocation pattern will automatically locate the new Web service information and recover without further administrative action. Cached binding information could alternatively be kept up to date by means of notification or polling.
5.1.4 Find Qualifiers
Each of the find_xx APIs accepts an optional findQualifiers argument, which may contain multiple findQualifier values. Find qualifiers may be either tModelKeys or may be referenced by a string containing a "short name". Each of the pre-defined findQualifiers in UDDI can be referenced using either the appropriate tModelKey, or by its short name. Registries MUST support both forms, and MUST accept the find qualifiers case-insensitively. The use of tModelKeys for findQualifiers allows extension to create additional new qualifiers, but registries are not obligated to support them. Find qualifiers not recognized by a node will return the error E_unsupported.
Matching behavior for the find_xx APIs when multiple criteria are specified is logical "AND" by default. Find qualifiers allow the default search behaviors to be overridden. Not all find_xx APIs support all findQualifier element values. The following table identifies which findQualifiers apply to each API:
Table 1: Find Qualifiers by API
|
Find Qualifier Short Name and tModel Name |
find_business |
find _service |
find_binding |
find_tModel |
find_related Businesses |
|
"andAllKeys" (uddi-org:andAllKeys)
|
YES default for categoryBag, tModelBag, applicable to identifierBag |
YES default for tModelBag & categoryBag |
YES default for categoryBag, tModelBag |
YES default for categoryBag, applicable to identifierBag |
NO |
|
"approximateMatch" (uddi-org:approximateMatch:SQL99) |
YES |
YES |
YES |
YES |
YES |
|
"binarySort" (uddi-org:binarySort) |
YES |
YES |
NO |
YES |
YES |
|
"bindingSubset" (uddi-org:bindingSubset) |
YES applicable to categoryBag on bindingTemplate |
YES applicable to categoryBag on bindingTemplate |
NO |
NO |
NO |
|
"caseInsensitiveSort" (uddi-org:caseInsensitiveSort) |
YES |
YES |
NO |
YES |
YES |
|
"caseInsensitiveMatch" (uddi-org:caseInsensitiveMatch) |
YES |
YES |
YES |
YES |
YES |
|
"caseSensitiveSort" [13] (uddi-org:caseSensitiveSort) |
YES |
YES |
NO |
YES |
YES |
|
"caseSensitiveMatch" [14] (uddi-org:caseSensitiveMatch) |
YES |
YES |
YES |
YES |
YES |
|
"combineCategoryBags" (uddi-org:combineCategoryBags) |
YES |
YES |
NO |
NO |
NO |
|
"diacriticInsensitiveMatch" [15] (uddi-org:diacriticInsensitiveMatch) |
YES |
YES |
YES |
YES |
YES |
|
"diacriticSensitiveMatch" [16] (uddi-org:diacriticSensitiveMatch) |
YES |
YES |
YES |
YES |
YES |
|
"exactMatch" [17] (uddi-org:exactMatch) |
YES |
YES |
YES |
YES |
YES |
|
"signaturePresent" (uddi-org:signaturePresent) |
YES |
YES |
YES |
YES |
YES |
|
"orAllKeys" (uddi-org:orAllKeys) |
YES default for identifierBag, applicable to tModelBag or categoryBag |
YES applicable to categoryBag, tModelBag |
YES applicable to categoryBag, tModelBag |
YES applicable to categoryBag, default for identifierBag |
NO |
|
"orLikeKeys" (uddi-org:orLikeKeys) |
YES applicable to identifierBag, categoryBag |
YES applicable to categoryBag |
YES applicable to categoryBag |
YES applicable to categoryBag, identifierBag |
NO |
|
"serviceSubset" (uddi-org:serviceSubset) |
YES |
NO |
NO |
NO |
NO |
|
"sortByNameAsc" [18] (uddi-org:sortByNameAsc) |
YES |
YES |
NO |
YES |
YES |
|
"sortByNameDesc" (uddi-org:sortByNameDesc) |
YES |
YES |
NO |
YES |
YES |
|
"sortByDateAsc" (uddi-org:sortByDateAsc) |
YES |
YES |
YES default behavior |
YES |
YES |
|
"sortByDateDesc" (uddi-org:sortByDateDesc) |
YES |
YES |
YES |
YES |
YES |
|
"suppressProjectedServices" (uddi-org:suppressProjectedServices) |
YES |
YES |
NO |
NO |
NO |
|
"UTS-10" [19] (uddi-org:UTS-10) |
YES |
YES |
NO |
YES |
YES |
5.1.4.1 Invalid Find Qualifier Combinations
Using a findQualifier with one of the find_xx APIs to which it does not apply, will generally result in that qualifier being ignored, but there are a few situations for which certain findQualifiers elements are mutually exclusive and supplying them together will result in an E_invalidCombination error. The invalid combinations are:
· andAllKeys, orAllKeys, and orLikeKeys are mutually exclusive
· sortByNameAsc and sortByNameDesc are mutually exclusive
· sortByDateAsc and sortByDateDesc are mutually exclusive
· combineCategoryBags, serviceSubset and bindingSubset are mutually exclusive
· exactMatch and approximateMatch are mutually exclusive
· exactMatch and caseInsensitiveMatch are mutually exclusive
· binarySort and UTS-10 are mutually exclusive, as are all collation algorithm tModels with each other
· diacriticSensitiveMatch and diacriticInsensitiveMatch are mutually exclusive
· exactMatch and diacriticInsensitiveMatch are mutually exclusive
· caseSensitiveSort and caseInsensitiveSort are mutually exclusive
· caseSensitiveMatch and caseInsensitiveMatch are mutually exclusive
See Chapter 11, Utility tModels and Conventions for further information on find qualifier tModels.
5.1.4.2 General Form of Find Qualifiers
Find qualifiers are expressed by using a findQualifiers argument. The general form of the findQualifiers element is:
where a findQualifier can be either a string (with a maximum length of 255), or a tModelKey.
5.1.4.3 Find Qualifier Descriptions
The value passed in each findQualifier element indicates the behavior change desired. This list defines the set of UDDI defined valid qualifiers. Nodes MUST implement all of these except as noted.
· andAllKeys: this changes the behavior for identifierBag to AND keys rather than OR them. This is already the default for categoryBag and tModelBag.
· approximateMatch: signifies that wildcard search behavior is desired. This behavior is defined by the uddi-org:approximatematch:SQL99 tModel and means "approximate matching as defined for the character like predicate in ISO/IEC9075-2:1999(E) Section 8.5 like predicate, where the percent sign (%) indicates any number of characters and an underscore (_) indicates any single character. The backslash character (\) is used as an escape character for the percent sign, underscore and backslash characters. This find qualifier adjusts the matching behavior for name, keyValue and keyName (where applicable).
· binarySort: this qualifier allows for greater speed in sorting. It causes a binary sort by name, as represented in Unicode codepoints.
· bindingSubset: this is used in the find_business API or the find_service API and is used only in conjunction with a categoryBag argument. It causes the component of the search that involves categorization to use only the categoryBag elements from contained bindingTemplate elements within the registered data and ignores any entries found in the categoryBag which are not direct descendent elements of registered businessEntity elements or businessService elements. The resulting businessList or serviceList return those businesses or services that matched based on this modified behavior, in conjunction with any other search arguments provided. Additionally, in the case of the returned businessList from a find_business, the contained serviceInfos elements will only reflect summary data (in a serviceInfo element) for those services (contained or referenced) that contained a binding that matched on one of the supplied categoryBag arguments.
· caseInsensitiveMatch: signifies that the matching behavior for name, keyValue and keyName (where applicable) should be performed without regard to case.
· caseInsensitiveSort: signifies that the result set should be sorted without regard to case. This overrides the default case sensitive sorting behavior.
· caseSensitiveMatch: signifies that the matching behavior for name, keyValue and keyName (where applicable) should be performed with regard to case. This is the default behavior.
· caseSensitiveSort: signifies that the result set should be sorted with regard to case. This is the default behavior.
· combineCategoryBags: this may only be used in the find_business and find_service calls. In the case of find_business, this qualifier makes the categoryBag entries for the full businessEntity element behave as though all categoryBag elements found at the businessEntity level and in all contained or referenced businessService elements and bindingTemplate elements were combined. Searching for a category will yield a positive match on a registered business if any of the categoryBag elements contained within the full businessEntity element (including the categoryBag elements within contained or referenced businessService elements or bindingTemplate elements) contains the filter criteria. In the case of find_service, this qualifier makes the categoryBag entries for the full businessService element behave as though all categoryBag elements found at the businessService level and in all contained or referenced elements in the bindingTemplate elements were combined. Searching for a category will yield a positive match on a registered service if any of the categoryBag elements contained within the full businessService element (including the categoryBag elements within contained or referenced bindingTemplate elements) contains the filter criteria. This find qualifier does not cause the keyedReferences in categoryBags to be combined with the keyedReferences in keyedReferenceGroups in categoryBags when performing the comparison. The keyedReferences are combined with each other, and the keyedReferenceGroups are combined with each other.
· diacriticInsensitiveMatch: signifies that matching behavior for name, keyValue and keyName (where applicable) should be performed without regard to diacritics. Support for this findQualifier by nodes is OPTIONAL.
· diacriticSensitiveMatch: signifies that the matching behavior for name, keyValue and keyName (where applicable) should be performed with regard to diacritics. This is the default behavior.
· exactMatch: signifies that only entries with names, keyValues and keyNames (where applicable) that exactly match the name argument passed in, after normalization, will be returned. This qualifier is sensitive to case and diacritics where applicable. This qualifier represents the default behavior.
· orAllKeys: this changes the behavior for tModelBag and categoryBag to OR the keys within a bag, rather than to AND them. Using this findQualifier with both a categoryBag and a tModelBag, will cause all of the keys in BOTH the categoryBag and the tModelBag to be OR’d together rather than AND’d. It is not possible to OR the categories and retain the default AND behavior of the tModels. The behavior of keyedReferenceGroups in a categoryBag is analogous to that of individual keyedReferences, that is, the complete categoryBag is changed to OR the keys.
· orLikeKeys: when a bag container (i.e. categoryBag or identifierBag) contains multiple keyedReference elements, any keyedReference filters that come from the same namespace (e.g. have the same tModelKey value) are OR’d together rather than AND’d. For example "find any of these four values from this namespace, and any of these two values from this namespace". The behavior of keyedReferenceGroups is analogous to that of keyedReferences, that is, keyedReferenceGroups that have the same tModelKey value are OR’d together rather than AND’d.
· serviceSubset: this is used only with the find_business API and is used only in conjunction with a categoryBag argument. It causes the component of the search that involves categorization to use only the categoryBag elements from contained or referenced businessService elements within the registered data and ignores any entries found in the categoryBag which are not direct descendent elements of registered businessEntity elements. The resulting businessList structure contains those businesses that matched based on this modified behavior, in conjunction with any other search arguments provided. Additionally, the contained serviceInfos elements will only reflect summary data (in a serviceInfo element) for those services (contained or referenced) that matched on one of the supplied categoryBag arguments.
· signaturePresent: this is used with any find_xx API to restrict the result set to entities which either contain an XML Digital Signature element, or are contained in an entity which contains one. The Signature element is retrieved using a get_xx API call and SHOULD be verified by the client. A UDDI node may or may not verify the signature and therefore use of this find qualifier, or the presence of a Signature element SHOULD only be for the refinement of the result set from the find_xx API and SHOULD not be used as a verification mechanism by UDDI clients.
· sortByNameAsc: causes the result set returned by a find_xx or get_xx inquiry APIs to be sorted on the name field in ascending order. This sort is applied prior to any truncation of result sets. It is only applicable to queries that return a name element in the top-most detail level of the result set and if no conflicting sort qualifier is specified, this is the default sorting direction. This findQualifier takes precedence over sortByDateAsc and sortByDateDesc qualifiers, but if a sortByDateXxx findQualifier is used without a sortByNameXxx qualifier, sorting is performed based on date with or without regard to name.
· sortByNameDesc: causes the result set returned by a find_xx or get_xx inquiry call to be sorted on the name field in descending order. This sort is applied prior to any truncation of result sets. It is only applicable to queries that return a name element in the top-most detail level of the result set. This is the reverse of the default sorting direction. This findQualifier takes precedence over sortByDateAsc and sortByDateDesc qualifiers but if a sortByDateXxx findQualifier is used without a sortByNameXxx qualifier, sorting is performed based on date with or without regard to name.
· sortByDateAsc: causes the result set returned by a find_xx or get_xx inquiry call to be sorted based on the most recent date when each entity, or any entities they contain, were last updated, in ascending chronological order (oldest are returned first). When names are included in the result set returned, this find qualifier may also be used in conjunction with either the sortByNameAsc or sortByNameDesc findQualifiers. When so combined, the date-based sort is secondary to the name-based sort (results are sorted within name by date, oldest to newest).
· sortByDateDesc: causes the result set returned by a find_xx or get_xx inquiry call to be sorted based on the most recent date when each entity, or any entities they contain, were last updated, in descending chronological order (most recently changed are returned first. When names are included in the result set returned, this find qualifier may also be used in conjunction with either the sortByNameAsc or sortByNameDesc find qualifiers. When so combined, the date-based sort is secondary to the name-based sort (results are sorted within name by date, newest to oldest).
· suppressProjectedServices: signifies that service projections MUST NOT be returned by the find_service or find_business APIs with which this findQualifier is associated. This findQualifier is automatically enabled by default whenever find_service is used without a businessKey.
· UTS-10: this is used to cause sorting of results based on the Unicode Collation Algorithm on elements normalized according to Unicode Normalization Form C. When this qualifier is referenced, a sort is performed according to the Unicode Collation Element Table in conjunction with the Unicode Collation Algorithm on the name field, normalized using Unicode Normalization Form C. Support of this findQualifier by nodes is OPTIONAL.
At this time, these are the only UDDI find qualifiers defined. UDDI registries and individual nodes may define more find qualifier values than these – but all nodes and fully compatible software MUST support the above qualifiers, except where indicated otherwise.
5.1.4.4 Sorting Details
Sorting behavior of results returned as part of a UDDI inquiry is controlled by the following sort order find qualifiers: sortByDateAsc, sortByDateDesc, sortByNameAsc, sortByNameDesc, caseInsensitiveSort, binarySort and UTS-10. These find qualifiers specify four aspects of sorting behavior as shown in Table 2: Find Qualifier Sorting Behaviors below. For information on which find qualifiers are mutually exclusive, see Section 5.1.4.1 Invalid Find Qualifier Combinations. Not all aspects of sorting are controlled through use of a single sort order find qualifier. In order to control any combination of aspects of sorting behavior, multiple sort order find qualifiers can be specified. For example, specifying sortByNameDesc and UTS-10 causes sorting of the result set on the name element according to the Unicode Technical Standard (UTS) #10 Collation Sequence, but in descending order.
Table 2: Find Qualifier Sorting Behaviors
|
Find Qualifier |
Field being sorted |
Direction of sort |
Indicates Collation sequence |
Controls Case Sensitivity |
|
sortByNameAsc |
Name |
Asc |
|
|
|
sortByNameDesc |
Name |
Desc |
|
|
|
caseInsensitiveSort |
|
|
|
√ |
|
caseSensitiveSort |
|
|
|
√ |
|
binarySort |
|
|
√ |
|
|
UTS-10 |
|
|
√ |
|
|
sortByDateAsc |
Date |
Asc |
|
|
|
sortByDateDesc |
Date |
Desc |
|
|
The default sort order aspects are to perform a case sensitive sort on the primary name element (where present), or the last change date (when a name is not present), in ascending order, using the collation sequence as determined by node policy. Nodes MAY choose to perform a secondary date or name-based sort of duplicate entries in each of these cases. If a name-based findQualifier is specified without a date-based sort, then nodes MAY perform a secondary date-based sort of duplicate entries. Similarly, when a date-based sort findQualifier is specified without a name-based sort, nodes MAY perform a secondary name-based sort of duplicate entries (where applicable).
Comparison and sorting is performed based on a canonicalized representation. Specifying an unsupported sort order will result in the error E_unsupported. For more on canonicalization, refer to Section 0 XML Normalization and Canonicalization.
Different sorting behavior can be obtained through the use of different sort orders, which are represented by their corresponding tModels. The use of alternative collation sequences is achieved by referencing the corresponding tModelKey as the findQualifier argument supplied in the search. Support for sorting based tModels describing any collation sequences other than binary by a node is OPTIONAL.
When a result set is being sorted by name only, then by
default the first name stored for the businessEntity is the one against which
sorting is performed. Nodes that offer language-specific sort collation
sequences MAY sort based the name element associated with the collation
language.
5.1.5 Use of listDescription
Several of the inquiry APIs cause a list of results to be returned. In such cases, an element called listDescription MAY also be returned:
Where:
· includeCount: is the number of list items returned for the particular response
· actualCount: is the number of all available matches at the time this particular query was made
· listHead: is an index (with origin of 1) which indicates the index position within all available matches of the first element of the returned result set after any sorting has been applied.
When a listDescription is returned as part of the result set, it includes a listHead value that indicates the index position of the first result in the set relative to the beginning of the list of all matches for the query. The query can specify that the result set returned should start with a particular element in the list of all matches for the query by including a listHead attribute on the query (find_xx API). The maximum number of results included in response to a query may be determined by the maxRows attribute of the query (find_xx API) or by the node’s policy. The listDescription on the response is useful when the node determines that the size of the resultant list is too large to be returned or when the maxRows and listHead values specified by the client do not allow all of the results to be returned in response to a single query.
For example, a query with a maxRows attribute set to 10 could be issued to a node where 18 results match the query. The response to this query should contain items 1 through 10 and the listDescription would have an actualCount value of 18, a listHead value of 1 and an includeCount value of 10. If the data matching the query does not change and the query is sent again to the node with a listHead attribute value of 11, the result set should contain items 11-18 and the listDescription would have an actualCount value of 18, a listHead value of 11 and an includeCount value of 8. If the listHead value is less than 1, a value of 1 will be used to produce the result. If the listHead value exceeds the total number of results provided, an empty result set will be returned.
listDescription is not a true "cursoring" feature. Since both the registry content and the associated result set can change between queries, supplying a particular value for listHead on subsequent queries may result in either duplicate reporting of an element which was returned as part of the original query, or a failure to report on an element.
The results of using a find_xx API will include a listDescription only if the resultant list is greater than what a node implementation can return in a single group. For example, if the result set contains 20 items and all 20 are returned at once, then the listDescription element is allowable, but not required. If the result set is 1000 and only 500 items can be returned at once, then a listDescription is required (if the truncated attribute is not used).
5.1.6 About wildcards
The default behavior of UDDI with respect to matching is "exact match". No wildcard behavior is assumed. Many UDDI inquiry APIs take the arguments "name," "keyName," and "keyValue" whose values are of type string. All such arguments may be specified using a wildcard character to obtain an "approximate match". In order to obtain wildcard searching behavior, the findQualifier tModel uddi-org:approximateMatch:SQL99 (whose tModelKey is uddi:uddi.org:findqualifier:approximatematch), or its short name "approximateMatch" MUST be specified.
Wildcards, when they are allowed, may occur at any position in the string of characters that constitutes the argument value and may occur more than once. Wildcards are denoted with a percent sign (%) to indicate any value for any number of characters and an underscore (_) to indicate any value for a single character. The backslash character (\) is used as an escape character for the percent sign, underscore and backslash characters. Use of the "exactMatch" findQualifier will cause wildcard characters to be interpreted literally, and as such should not also be combined with the escape character. Detailed rules for interpretation are defined by the above tModel for approximate matching. Examples of the use of wildcards may be found in Appendix G Wildcards.
5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups
When determining matching behavior in searches involving keyedReferences in categoryBags and identifierBags, a match occurs if and only if:
1. The tModelKeys refer to the same tModel. This key MUST be specified and MUST NOT be empty.
2. The keyValues match (an exact match is the default, but the matching behavior is modified appropriately if the caseInsensitiveMatch, diacriticInsensitiveMatch or approximateMatch findQualifiers are used); and
3. If the tModelKey involved is "uddi:uddi-org:general_keywords", the keyName must match (wildcard matching rules apply if the approximateMatch findQualifier is used). Omitted keyNames are treated as empty keyNames. Otherwise, keyNames are not significant unless so indicated in the individual API sections below.
A given keyedReferenceGroup "X" (e.g., within a given categoryBag) matches a keyedReferenceGroup "Y" in the registry if and only if the tModelKey assigned to the keyedReferenceGroup X matches the tModelKey assigned to the keyedReferenceGroup Y and the set of keyedReferences in "X" are a subset of the set of keyedReferences in "Y." The order of individual keyedReferences within a keyedReferenceGroup is not important. Matching rules for the individual contained keyedReference elements are the same as above.
For additional information and examples, refer to Appendix E Using Identifiers and Appendix F Using Categorization.
5.1.8 Inquiry API functions
The APIs in this section represent inquiries that can be used to retrieve data from a UDDI registry. These calls all behave synchronously and are suitable for being exposed via HTTP-POST. The calls constituting the UDDI inquiry API are:
· find_binding: Used to locate bindings within or across one or more registered businessServices. Returns a bindingDetail structure. See Section 5.1.9 find_binding.
· find_business: Used to locate information about one or more businesses. Returns a businessList structure. See Section 5.1.10 find_business.
· find_relatedBusinesses: Used to locate information about businessEntity registrations that are related to a specific business entity whose key is passed in the inquiry. See Section 5.1.11 find_relatedBusinesses.
· find_service: Used to locate specific services within registered business entities. Returns a serviceList structure. See Section 5.1.12 find_service.
· find_tModel: Used to locate one or more tModel information structures. Returns a tModelList structure. See Section 5.1.13 find_tModel.
· get_bindingDetail: Used to get bindingTemplate information suitable for making service requests. Returns a bindingDetail structure. See Section 5.1.14 get_bindingDetail.
· get_businessDetail: Used to get the businessEntity information for one or more businesses or organizations. Returns a businessDetail structure. See Section 5.1.15 get_businessDetail.
· get_operationalInfo: Used to retrieve operational information pertaining to one or more entities in the registry. Returns an operationalInfos structure. See Section 5.1.16 get_operationalInfo.
· get_serviceDetail: Used to get full details for a given set of registered businessService data. Returns a serviceDetail structure. See Section 5.1.16 get_serviceDetail.
· get_tModelDetail: Used to get full details for a given set of registered tModel data. Returns a tModelDetail structure. See Section 5.1.18 get_tModelDetail.
Several of the find_xx APIs (find_binding, find_business and find_service) support nested queries, where one or more of the arguments to these APIs can itself be another (inner) query, the results of which are used to filter the overall results of the primary (outer) query along with the other criterions supplied. Any findQualifier arguments used only apply directly to the part of the query (outer or inner) for which they are supplied. They do not propagate inward or outward.
5.1.9 find_binding
The find_binding API is used to find UDDI bindingTemplate elements. The find_binding API call returns a bindingDetail that contains zero or more bindingTemplate structures matching the criteria specified in the argument list.
5.1.9.1 Syntax:
Attributes
|
Name |
Use |
|
maxRows |
optional |
|
serviceKey |
optional |
|
listHead |
optional |
5.1.9.2 Arguments:
· authInfo: This optional argument is an element that contains an authentication token. Registries that wish to restrict who can perform an inquiry typically require authInfo for this call.
· categoryBag: This optional argument is a list of category references in the form of keyedReference elements and keyedReferenceGroup structures. When used, the returned bindingDetail for this API will contain elements matching all of the categories passed (logical AND by default). Specifying the appropriate findQualifiers can override this behavior. Matching rules for each can be found in Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups.
· findQualifiers: This optional collection of findQualifier elements can be used to alter the default behavior of search functionality. See Section 5.1.4 Find Qualifiers, for more information.
· find_tModel: This argument provides an alternative or additional way of specifying tModelKeys that are to be used to find the bindingTemplate elements. When specified, the find_tModel argument is treated as an embedded inquiry that is performed prior to searching for bindingTemplate elements. The tModelKeys found are those whose tModels match the criteria contained within the find_tModel element. The tModelKeys found are added to the (possibly empty) collection specified by the tModelBag prior to finding qualified bindingTemplates. Note that the authInfo argument to this embedded find_tModel argument is always ignored. Large result set behavior involving the return of a listDescription does not apply within an embedded argument. If the intermediate result set produced is too large, then the overall query will return E_resultSetTooLarge with an indication that the embedded query returned too many results. If an E_unsupported error occurs as part of processing this embedded argument, it is propagated up to the containing (calling) API.
· listHead: This optional integer value is used to indicate which item SHOULD be returned as the head of the list. The client may request a subset of the matching data by indicating which item in the resultant set constitutes the beginning of the returned data. The use of the listDescription element is mutually exclusive to the use of the truncated attribute that simply indicates a truncated result list in the Inquiry APIs. See Section 5.1.5 Use of listDescription, for a detailed description of the listHead argument.
· maxRows: This optional integer value allows the requesting program to limit the number of results returned. This argument can be used in conjunction with the listHead argument.
· serviceKey: This optional uddi_key is used to specify a particular instance of a businessService element in the registered data. Only bindings in the specific businessService data identified by the serviceKey passed are searched. When it is either omitted or specified as empty (i.e., serviceKey=""), this indicates that all businessServices are to be searched for bindings that meet the other criteria supplied without regard to the service that provides them, and "projected" services are suppressed.
· tModelBag: This collection of tModelKey elements represent in part or in whole the technical fingerprint of the bindingTemplate structures for which the search is being performed. At least one of either a tModelBag or a find_tModel argument SHOULD be supplied, unless a categoryBag based search is being used.
If a find_tModel argument is specified (see above), it is treated as an embedded inquiry. The tModelKeys returned as a result of this embedded find_tModel argument are used as if they had been supplied in a tModelBag argument. Changing the order of the keys in the collection or specifying the same tModelKey more than once does not change the behavior of the find.
By default, only bindingTemplates that have a technical fingerprint containing all of the supplied tModelKeys match (logical AND). Specifying appropriate findQualifiers can override this behavior so that bindingTemplates with a technical fingerprint containing any of the specified tModelKeys are returned (logical OR).
5.1.9.3 Returns:
This API call returns a bindingDetail upon success:
Attributes
|
Name |
Use |
|
truncated |
optional |
In the event that no matches were located for the specified criteria, the bindingDetail structure returned is empty (i.e., it contains no bindingTemplate data). This signifies a zero match result. If no arguments are passed, a zero-match result set will be returned.
If the number of matches exceeds the value of the maxRows attribute, the result set MAY be truncated. If this occurs, the response contains the attribute "truncated " with the value "true".
As an alternative to the truncated attribute, a registry MAY return a listDescription element. See Section 5.1.5 Use of listDescription, for additional information.
5.1.9.4 Caveats:
If an error occurs in processing this API, a dispositionReport element is returned to the caller within a SOAP Fault. In addition to the errors common to all APIs, the following error information is relevant here:
· E_invalidCombination: signifies that conflicting findQualifiers have been specified. The error text clearly identifies the findQualifiers that caused the problem.
· E_invalidKeyPassed: signifies that the uddi_key value passed did not match with any known serviceKey or tModelKey values. The error structure signifies the condition that occurred and the error text clearly calls out the offending key.
· E_resultSetTooLarge: signifies that the particular node queried has deemed that the entire result set is too large to manage. Therefore, the result set is not available. Search criteria must be adjusted to obtain a result.
· E_unsupported: signifies that one of the findQualifier values passed was invalid. The invalid qualifier will be indicated clearly in text.
5.1.10 find_business
The find_business API is used to find UDDI businessEntity elements. The find_business API call returns a businessList that matches the criteria specified in the arguments.
5.1.10.1 Syntax:
Attributes
|
Name |
Use |
|
maxRows |
optional |
|
listHead |
optional |
5.1.10.2 Arguments:
· authInfo: This optional argument is an element that contains an authentication token. Registries that wish to restrict who can perform an inquiry in them typically require authInfo for this call.
· categoryBag: This is a list of category references in the form of keyedReference elements and keyedReferenceGroup structures. The returned businessList contains businessInfo elements matching all of the categories passed (logical AND by default). Specifying the appropriate findQualifiers can override this behavior. Matching rules for each can be found in Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups.
· discoveryURLs: This is a list of discoveryURL structures to be matched against the discoveryURL data associated with registered businessEntity information. To search for URL without regard to useType attribute values, omit the useType attribute or pass it as an empty attribute. If useType values are included, the match occurs only on registered information that matches both the useType and URL value. The returned businessList contains businessInfo structures matching any of the URL's passed (logical OR).
· identifierBag: This is a list of business identifier references in the form of keyedReference elements. The returned businessList contains businessInfo structures matching any of the identifiers passed (logical OR by default). Specifying the appropriate findQualifiers can override this behavior. Matching rules can be found in Section 5.1.7 Matching Rules for keyedReferences and keyedReferenceGroups.
· findQualifiers: This collection of findQualifier elements can be used to alter the default behavior of search functionality. See the Section 5.1.4 Find Qualifiers, for more information.
· find_relatedBusinesses: This argument is an embedded inquiry and limits the search results to those businesses that are related to a specified business in a specified way. The result is comprised of an intersection of the businesses located with this embedded inquiry and the businesses discovered using the remaining inquiry criteria. The standard syntax and arguments for find_relatedBusinesses apply here. Note that the authInfo argument to this embedded find_relatedBusinesses argument is always ignored. Large result set behavior involving the return of a listDescription does not apply within an embedded argument. If the intermediate result set produced is too large, then the overall query will return E_resultSetTooLarge with an indication that the embedded query returned too many results. If an E_unsupported error occurs as part of processing this embedded argument, it is propagated up to the containing (calling) API. See Section 5.1.11 find_relatedBusinesses, for further information.
· find_tModel: This argument provides an alternative or additional way of specifying tModelKeys that are used to find businesses which have service bindings with specific technical fingerprints as described above for the tModelBag element. When specified, the find_tModel argument is treated as an embedded inquiry that is performed prior to searching for businesses. The tModelKeys found are those whose tModels match the criteria contained within the find_tModel element. The tModelKeys found are added to the (possibly empty) collection specified by the tModelBag prior to finding qualified businesses. Note that the authInfo argument to this embedded find_tModel argument is always ignored. Large result set behavior involving the return of a listDescription does not apply within an embedded argument. If the intermediate result set produced is too large, then the overall query will return E_resultSetTooLarge with an indication that the embedded query returned