UDDI Peter Komisar ©   Conestoga College      v.1.0  /  2005
reference: 'UDDI Version 2.04 API Specification'
http://uddi.org/pubs/ProgrammersAPI-V2.04-Published-20020719.htm
UDDI 2 Schema, http://www.uddi.org/schema/uddi_v2.xsd
'Developing Java Web Services', R. Nagappan et.al., Wiley Press.
http://www.uddi.org/taxonomies/Core_Taxonomy_OverviewDoc.htm
'Java Web Services', Tyler Jewell & David Chapell, O'Reilly Press
http://www.oreilly.com/catalog/javawebserv/chapter/ch06.html

Overview

"Universal Description, Discovery and Integration, or UDDI, is the name of
a group of web-based registries that expose information about a business or
other entity and its technical interfaces (or API’s).  These registries are run
by multiple Operator Sites, and can be used by anyone who wants to make
information available about one or more businesses or entities, as well as
anyone that wants to find that information. 

There is no charge for using the basic services of these operator sites."
                                                      - UDDI Version 2.04 API Specification


UDDI Status

OASIS, the governing body that maintains UDDI, has recently announced
that UDDI version 3.02 has been ratified as an 'OASIS Standard' which is
this body's highest level of ratification. Following are a couple quotes from
the OASIS web site that indicate what sorts of improvements are included
in version 3.

"One of the most significant enhancements of UDDI v3.0.2 is that it allows
well-known identifiers for service descriptions to be created, facilitating reuse
of service descriptions among registries," added Tony Rogers of Computer
Associates, co-chair of the OASIS UDDI Specification Technical Committee.
"This makes it much easier for developers and architects to communicate."

"Other v3.0.2 features include support for digital signatures, allowing UDDI to
deliver a higher degree of data integrity and authenticity. Extended discovery
features can combine previous, multi-step queries into a single-step, complex
query. UDDI now also provides the ability to nest sub-queries within a single
query, letting clients narrow their searches much more efficiently."

While UDDI 3.0 add enhancements and refinements to the standard, UDDI
Version 2 is widely accepted and implemented at this time so we will focus
on describing Version 2. in this note.


OASIS

UDDI is maintained by OASIS. OASIS describes itself as "a not-for-profit
global consortium that drives the development, convergence and adoption
of e-business standards. We can look at the copyright notice associated
with UDDI and get a good idea of who's involved with OASIS.

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

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

The Consortium's Official Web site


The UDDI Official Web Site


UDDI is itself a great example of an XML application. It is also a excellent
example of an XML Web service.  UDDI supplies a glimpse of the ways
Web services will provide beneficial services and is just an early example
of many useful applications that will evolve over top of the Web services
model.

Who, What, Where & How?

 The sorts of information that can be registered with a UDDI directory supply
answers to Who, What Where and How?
Registry Uses

Many comparisons have been made between UDDI and the page types
from the telephone directory. These pages serve to describe the extent
to which the UDDI directory is used by a business. The authors of
'Developing Java Web Services' make the point that the following
categories are not explicitly defined in UDDI registrations and merely
implicit categories of registry use.


White Pages - used to register basic info, company name, address, contact info etc.
Yellow Pages - adding classification and taxonomy info makes businesses 'discoverable'
Green Pages - providing technical service info provides enhanced web service interactions


Interacting With a Registry

Because UDDI is a SOAP based web application a user may interact
with the registry in different ways.

'Developing Java Web Services' lists the following sites where Web
based GUIs are available to query sample UDDI directories.


Web based GUIs For Major Vendor UDDI Registries

Access points for inquiry and publishing APIs are available at different URLs.
To publish information to a public UDDI directory access points are provided
that are subject to authentication. Following is the list supplied in 'Developing
Java Web Services' that show both inquiry and publisher access points for
vendor public UDDI registries.


Inquiry and Publisher Access Points For Major Vendor UDDI Registries


The UDDI Specification

The following is a condensed version of UDDI Version 2.04 Specification.
Giving credit where it's due, this specification is especially well written and
easy to follow. Creating an abridged version was really not a lot of work.
If you have time you should read through the original.


UDDI Version 2.04 Specification

UDDI Terminology

Operator Site - (a.k.a. an UDDI Registry node ) An Operator Site is a server
that supplies as a web service a UDDI registry. UDDI Registries can be operated
as public or private registries. 

Public UDDI registry - A public UDDI registry is available to everyone to both
publish and query business and service information over the Internet.

Private UDDI registry  - A private UDDI registry is operated by a single organization
or collaboratively between a number of organizations who share information. A
private UDDI registry facilitates adding additional security constraints on the use
of the UDDI system.

A UDDI Business Registry - ( a.k.a. UBR ) a global grouping of UDDI Registry
nodes is called a 'UDDI Business Registry'.


Classification & Identification

UDDI Registries allow a company to list one or more classification or category
codes for a business. (The Oasis UDDI specification provides examples such
as NAICS, UN/SPC, SIC Codes etc.) These identifiers and classifications
facilitate service searches.  Registering geography, product and industry
codes along with business identifiers allow search services to supply 'added-
value indexing' in addition to a base UDDI registration. The following table
shows categorization schemes that UDDI support including 'open-ended'
categorization schemes that are not pre-defined.

Checked & Unchecked Taxonomies

UDDI version 2 adds 'checked' and 'unchecked' taxonomies. Unchecked
classifications are registered but not validated by a third party. Checked
taxonomies are used by entities for which it is important that the registered
information has been validated as being accurate and true.

// third party validation service like a certificate authentication service


UDDI supported Categorization Schemes // adapted from Table 5.4 in "Developing Java Web Services"

 Categorization System
 Abbreviation
 Description
North American Industry Classification
System
NAICS
(pronounced Nakes)
  Adopted in 1997 to replace the old Standard Industrial Classification (SIC) system, used by the statistical agencies
of the United States.  It is the first economic classification system to be constructed based on a single economic concept. http://www.census.gov/epcd/www/naics.html
 United Nations Standard Products and Services Code UNSPSC
  UNSPSC
 UNSPSC describe themselves as a 5-level hierarchical convention that is used to classify all products and services.
1) Segment 2) Family 3) Class 4) Commodity 5) Business Function          http://www.unspsc.org
 ISO 3166
Geographic Taxonomy
  ISO 3166
 Categorization system based on geography
Other Taxonomy ( operator
  specific )
Open ended not predefined. Corresponds to  uddi-org:general_keywords tModel noted below


Technical Models ( tModels ) // encapsulation of a technical inteface or specification

UDDIs registry information model is based on the notion of shared specifications.
To make shared specifications 'discoverable', UDDI packages information 'about'
such shared specifications in a metadata construct called the 'tModel'.

Assume a 'tModel' describes a well known e-commerce communication interface.
It will be assigned at registration a unique identifier called a 'tModelKey' which acts
as a 'fingerprint' indentifying that 'tModel'. Many services might be registered as
being compatible with such a 'tModel'.  Such models supply a common reference
point where a service registered as supporting that interface will easily be identified.
<>
The following table shows UDDI Defined Technical Models that are supported for
well known classification systems and include those described in the above table.
.

UDDI v2.04 Defined Technical Models // for reference
.

ntis-gov:naics:1997 // tModel that defines the NAICS industry taxonomy.

tModel Description:      Business Taxonomy: NAICS (1997 Release)
tModel UUID:                uuid:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2
Categorization:             categorization
Checked:                      Yes

unspsc-org:unspsc:3-1 // tModel defines the UNSPSC product taxonomy, deprecated.

tModel Description:      Product Taxonomy: UNSPSC (Version 3.1)
tModel UUID:                uuid:DB77450D-9FA8-45D4-A7BC-04411D14E384
Categorization:             categorization
Checked:                      No

unspsc-org:unspsc  // defines the UNSPSC product and services taxonomy for Version 7 and beyond.

tModel Description:      Product  and Services Taxonomy: UNSPSC (Version 7)
tModel UUID:                uuid: CD153257-086A-4237-B336-6BDCBDCC6634
Categorization:             categorization
Checked:                      Yes

uddi-org:iso-ch:3166:1999 // defines the ISO 3166 geographic classification taxonomy namespace.

tModel Description:      UDDI Geographic Taxonomy
tModel UUID:                uuid:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88
Categorization:             categorization
Checked:                      Yes

uddi-org:general_keywords

tModel Description:      Other Taxonomy
tModel UUID:                uuid:A035A07C-F362-44dd-8F95-E2B134BF43B4
Categorization:             categorization
Checked:                      Yes
.

For more information on tModels, including DUNS Numbers see:
http://www.uddi.org/taxonomies/Core_Taxonomy_OverviewDoc.htm

What is a D&B DUNS Number? // https://eupdate.dnb.com/requestoptions.html?cmid=EOE100537

The D&B D-U-N-S Number is a unique nine-digit identification sequence, which provides unique identifiers of single business entities, while linking corporate family structures together. D&B links the D&B D-U-N-S Numbers of parents, subsidiaries, headquarters and branches on more than 64 million corporate family members around the world. Used by the world's most influential standards-setting organizations, it is recognized, recommended and/or required by more than 50 global, industry and trade associations, including the United Nations, the U.S. Federal Government, the Australian Government and the European Commission. In today's global economy, the D&B D-U-N-S Number has become the standard for keeping track of the world's businesses.
.


UDDI Design & Architecture

The UDDI authors have sought to keep the UDDI Programmers API as simple
as possible basing all actions on a simple request/response model making it
well suited to execution over HTTP. 

The programming APIs can be divided into two categories.
We might add here a set of UDDI Datastructures that the APIs work on

UDDI Publishers API

The Publisher's API is used to register new services in a UDDI directory. It
also supplies methods to modify existing service registrations. It is obvious,
that unauthorized changes would not be desirable, so an Operator Site must
supply authenticated access for use with the Publishers API. Each Operator
Site needs to adopt an authentication protocol. Each Operator Site must also
supply a 'new user' sign-up mechanism. In order to use the Publisher's API,
a user needs to sign up with one or more Operator Sites and credentials need
to be established. The Publisher's API is accessed with privacy assured,
using secure HTTP (HTTPS) , based on SSL 3.0 (Secure Socket Layer)
connections.


UDDI Inquiry API

The UDDI Inquiry API is used by anyone in the designated domain, (whether
public or private.) and are not authenticated. Inquiry APIs may be supplied
over HTTP or HTTPS, if privacy is a concern.


Publisher's API

New User --> Authentication Protocol  __
                                                          |
                                     UDDI Publisher's API --> HTTPS ( SSL3.0 ) --> Operator Site


Inquiry API

Any User  <--- Inquiry API <--- HTTP ( HTTPS optional ) ---< Operator Site

// Any User in either public or private domains
                                                                                

The UDDI Namespace & Versioning

The UDDI specification supplies the 'generic' attribute to indicate which version
of UDDI is being used. Versions 1 and 2.0 of UDDI are identified with the values
'1.0' and '2.0' respectively. Mismatching a version value with an inapproprate
namespace will yield an error condition.

UDDI takes advantage of the xmlns keyword to define a default namespace for
it's element set. The namespace is given in the form of a URN, specific for each
UDDI version 1 or 2.0.


UDDI Version 1 and 2.0 Namespace URNs
The following hypothetical element shows the 'generic' attribute and the 'xmlns'
prefix assigned the correct corresponding UDDI namespace URN.


Example

<uddi_method  generic="2.0"  xmlns="urn:uddi-org:api_v2" >
             <!--   .   .   .       -->           
</uddi_method>


UDDI is an XML Application

The UDDI programming interface is written in XML. UDDI uses SOAP over HTTP
with POST commands to exchange information. Errors are wrapped in SOAP Fault
messages. It is suggested that Operator Sites, detect errors before processing
requests. Following is an example of a UDDI Query packaged inside a SOAP
message as part of a HTTP POST command.

UDDI v.12.04 Specificaiton Example

// a UDDI Query Message Packaged as SOAP message inside a HTTP POST Command
 <>
POST /someVerbHere HTTP/1.1
Host: www.someoperator.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 generic="2.0"

   xmlns="urn:uddi-org:api_v2">

…

<>// also acceptable -->  SOAPAction: "urn:uddi-org:api_v2#get_bindingDetail"

UDDI Error Handling

An error will invalidate the request and result in a 'dispostionReport' being
generated inside a SOAP Fault element. An appropriate error in wrapped inside a
'dispositionReport' inside a Fault element. In the event of multiple errors, only the
first error, that caused the request rejection is reported on in the SOAP Fault.

Each function description in the specification lists the types of errors that can
be raised for this method. UDDI errors follow a naming convention, where they
begin with an upper-case 'E' followed by underscore followed by the name of the
error. Following is an example.

Example  E_busy      // request cannot be processed at the current time

There are 31 Error types specified in Appendix A of the UDDI  2.04 specification.
They include a an name corresponding to the error code, a number which is the
error number and a description. The error number is issued to a 'errno' attribute
of a <result> element and the error code is assigned to an 'errCode' attribute
of an <errInfo> element which is nested inside the <result> element. The UDDI
specification supplies the following two examples of a 'dispostionReport'. The
first is not encloded in a <Fault> element is it indicates a successful, error
free query. Notice the <dispositionReport> element takes a default namespace
value corresponding to the URN for UDDI version 2.0.

OASIS UDDI 2.04 Success Report Example 

// Success reporting with the dispositionReport element:

<?xml version="1.0" encoding="UTF-8" ?>
<Envelope xmlns="http://schemas.xmlsoaporg.org/soap/envelope/">
<Body>
<dispositionReport generic="2.0" operator="OperatorURI"
xmlns="urn:uddi-org:api_v2" >
     <result errno="0" >
       <errInfo errCode=“E_success" />
     </result>
</dispositionReport>
</Body>
</Envelope>


The next example shows the general form of an error
'dispostionReport' nested inside a SOAP Fault message.


OASIS UDDI 2.04 Error Report Example 

<?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 generic="2.0" operator="OperatorURI"
        xmlns="urn:uddi-org:api_v2" >
            <result errno="10050" >
              <errInfo errCode=“E_fatalError">
                 The findQualifier value passed is unrecognized: XYZ
              </errInfo>
            </result>
</dispositionReport>
            </detail>
    </Fault>
</Body>
</Envelope>

Following is an abbreviated listing of Errors listed in Appendix A of the UDDI Version 2.04
Specification

Errors listed in Appendix A of the UDDI Version 2.04 Specification  // for reference

 Error Code
 Error#  Description
 E_assertionNotFound
 30000 -a particular publisher assertion cannot be identified
 E_authTokenExpired
 10110
-the authentication token information has timed out
E_authTokenRequired 10120 -an invalid authentication token was passed to an API call
E_accountLimitExceeded 10160 -a save request exceeded the quantity limits for a given data type
E_busy 10400 -the request cannot be processed at the current time.
E_invalidKeyPassed 10210 -the uuid_key value passed didn't match with any known key values
E_fatalError 10500 -a serious technical error has occurred during request processing
E_invalidCompletionStatus 30100 -one of the assertion status values passed is unrecognized.
E_invalidValue 20200 -a value passed in a keyValue attribute did not validate in
checked categorizations.
E_languageError 10060 -an error was detected while processing elements that were
 annotated with xml:lang qualifiers. (only the description and
 name elements support xml:lang qualifications.)
E_messageTooLarge 30110 -signifies that the message is too large.
E_publisherCancelled 30220 -the target publisher cancelled the custody transfer operation
E_requestDenied 30210 -a custody transfer request has been refused.
E_requestTimeout 20240 -request unanswered, needed component didn't respond in time.
E_secretUnknown 30230 -unable to match the shared secret, 5 attempt limit  exhausted.
E_success       0 - no failures, returned in a dispositionReport for requests
 with no natural response document.
E_tooManyOptions 10030 -too many or incompatible arguments were passed
E_transferAborted 30200 Signifies that a custody transfer request will not succeed.
E_unrecognizedVersion 10040 -the generic attribute value passed is unsupported by Operator
E_unknownUser 10150 -the user ID & password passed is unknown or not valid.
E_unsupported 10050 -the implementer does not support a feature or API.
E_userMismatch 10140 -an attempt was made to use the publishing API to
change data that is controlled by another party
E_valueNotAllowed 20210 -a value did not pass validation because of contextual issues.
E_unvalidatable 20220 -an attempt was made to reference a taxonomy or identifier system in a keyedReference whose tModel is categorized as unvalidatable
E_nameTooLong
RETIRED 		 10020  Signifies that the partial name value passed exceeds the maximum name length designated by the policy of an implementation or Operator Site.
// for UDDI Version 1.0 compatibility
E_invalidCategory
RETIRED
 20000 the given keyValue did not correspond to a category
within the taxonomy identified by the tModelKey.
 Replaced by E_invalidValue in 2.0+.Used for UDDI v1.0 compatibility
E_invalidProjection 20230 -an attempt was made to save a businessEntity containing a service projection that does not match the businessService being projected.
E_categorizationNotAllowed
RETIRED		 20100 -data provided doesn't conform to restrictions placed on category used.
 Replaced by E_valueNotAllowed in 2.0+.  Used for UDDI v1.0 compatibility

// Some errors are labelled DO NOT USE. They are E_keyRetired, (10310),   E_operatorMismatch: (10130),
// E_invalidURLPassed: (10220) Error codes listed here that are marked "DO NOT USE" are not to be used
// by UDDI operators.  Error codes listed here that are marked "RETIRED" are still used for version 1
// compatibility, but in version 2 and higher, these retired codes are superceded.
Special Values in UDDI Syntax

Following are list of special values. The list consists of elements, attributes and a namespace
qualifier that are are used in function calls of the Publisher's and Inquiry APIs. They are listed
with brief descriptions in the table below.

uuid_key

 -Access keys inside UDDI elements are universal unique identifiers, (a.k.a. a GUID),
formatted according to a algorithm, endorsed by the UDDI Operator Council with
the exception of tModelKey values which are prefixed with a URN qualifier in the
format "uuid:" followed by the UUID value. // universal unique identifiers
generic
 -a required metadata attribute for all messages, used to designate
the UDDI version used to format messages. ( i.e. '1.0' & '2.0')
xmlns -default namespace qualifier, assigned URNs, “urn:uddi-org:api" for
V1  & urn:uddi-org:api_v2 for V2 
findQualifiers -special element found in the inquiry API functions used in searches
to signal special behaviors.
maxRows
  Inquiry API qualifier that limits the number of results returned. If a result
is truncated because of this limit or if an operator-specific limit is passed
the 'truncated' is set to 'true'.
 truncated
-if set to true, indicates the result is not the entire result set. Intended to
support the average query. UDDI is not designed to support large data sets.
categoryBag
  -searches can cross categories. Operator sites support several categories,
supplying category dimensions, 'industry type', product or service type, and
geography. searches by default match ALL categories supplied ( A & B & C ).
identifierBag -searches  match any supplied identifiers for primary elements containing
identifierBag elements. Version 2 supports 'checked' identifiers, permitting
'copycat' information to be discerned from validated business registrations.
tModelBag
 -found in the inquiry messages named find_business, find_service, and find_binding.
" Searches that match a particular technical fingerprint use UUID values to search for bindingTemplates with matching tModelKey value sets. . . "the concept of tModel fingerprints allows for highly selective searches for specific combinations of keys"
( a search for a combination of tModel key values can be conducted that correspond
 to the full set of specifications. i.e. UDDI itself.)

"All tModelKey values are always expressed using a Uniform Resource Identifier (URI) format that starts with the characters "uuid:" followed by a formatted Universally Unique Identifier (UUID) consisting of Hexadecimal digits arranged in the common 8-4-4-4-12 format pattern."


UDDI Data Stuctures

UDDI data structures are typical XML constructs governed by XML Schema.
The UDDI data structures represent the information stored in a UDDI Registry.
The XML messages of the Programming APIs manipulate these data structures
when making queries on the UDDI database.



The key datastructures are represented by the following elements where
the first four are used to describe a business and the latter three are involved
in classification. The publisherAssertion element is used to define relationships
between businesses.

We can look at each of these more closely in conjunction with their schema
definitions.

<businessEntity>

The <businessEntity> element contains key information that describes and
categorizes a business. The following schema definition for this element shows
this description can include includes names, 'discoveryURLs', descriptions,
businessServices and the classification elements 'identifierBag' and
'categoryBag'. It also has a required 'businessKey' attribute.


Schema Definition of a businessEntity Element

<xsd:element name="businessEntity" type="uddi:businessEntity"/>
    <xsd:complexType name="businessEntity">
        <xsd:sequence>
            <xsd:element ref="uddi:discoveryURLs" minOccurs="0"/>
            <xsd:element ref="uddi:name" maxOccurs="unbounded"/>
            <xsd:element ref="uddi:description" minOccurs="0" maxOccurs="unbounded"/>
            <xsd:element ref="uddi:contacts" minOccurs="0"/>
            <xsd:element ref="uddi:businessServices" minOccurs="0"/>
            <xsd:element ref="uddi:identifierBag" minOccurs="0"/>
            <xsd:element ref="uddi:categoryBag" minOccurs="0"/>
        </xsd:sequence>
        <xsd:attribute name="businessKey" type="uddi:businessKey" use="required"/>
        <xsd:attribute name="operator" type="string" use="optional"/>
        <xsd:attribute name="authorizedName" type="string" use="optional"/>
    </xsd:complexType>


<businessService>

The businessService element is used to describe the services a business
offers. While we might expect these would be Web services, in fact the
descriptions can be of any sort of service, for instance a '1-800' style order
desk. The above schema shows that there is an optional <businessServices>
element. This examples a common pattern in the UDDI schema where plural
versions of elements are created. Following is the <businessServices> element's
schema definition. It shows that the element may contain zero or more
businessService elements. This pattern is repeated for several singular
elements defined in the UDDI schema.


Schema Definition of a businessServices Element

<xsd:element name="businessServices" type="uddi:businessServices"/>
    <xsd:complexType name="businessServices">
        <xsd:sequence>
            <xsd:element ref="uddi:businessService" minOccurs="0" maxOccurs="unbounded"/>
        </xsd:sequence>
    </xsd:complexType>


Following is the schema definition of the singular, businessService Element. It
holds any number of names and descriptions, a plural, 'bindingTemplates' element
and a 'categoryBag' element. It also has a mandatory 'serviceKey' attribute. 


Schema Definition of a businessService Element

<xsd:element name="businessService" type="uddi:businessService"/>
    <xsd:complexType name="businessService">
        <xsd:sequence>
            <xsd:element ref="uddi:name" minOccurs="0" maxOccurs="unbounded"/>
            <xsd:element ref="uddi:description" minOccurs="0" maxOccurs="unbounded"/>
            <xsd:element ref="uddi:bindingTemplates" minOccurs="0"/>
            <xsd:element ref="uddi:categoryBag" minOccurs="0"/>
        </xsd:sequence>
        <xsd:attribute name="serviceKey" type="uddi:serviceKey" use="required"/>
        <xsd:attribute name="businessKey" type="uddi:businessKey" use="optional"/>
    </xsd:complexType>



<bindingTemplate>

The bindingTemplate element holds technical descriptions and URLs for services.
It has a required 'bindingKey' attribute. The following schema definition shows this
element includes zero or more descriptions and a choice of an 'accessPoint' or a
'hostingRedirector'. An accessPoint holds a URL. A hostingRedirector element holds
a 'bindingKey' that references another 'bindingTemplate'. The 'bindingTemplate'
element also holds a 'tModelInstanceDetails' which hold a lot of nested information
regarding tModels.


Schema Definition of a bindingTemplate Element

<xsd:element name="bindingTemplate" type="uddi:bindingTemplate"/>
    <xsd:complexType name="bindingTemplate">
        <xsd:sequence>
            <xsd:element ref="uddi:description" minOccurs="0" maxOccurs="unbounded"/>
            <xsd:choice>
                <xsd:element ref="uddi:accessPoint"/>
                <xsd:element ref="uddi:hostingRedirector"/>
            </xsd:choice>
            <xsd:element ref="uddi:tModelInstanceDetails"/>
        </xsd:sequence>
        <xsd:attribute name="serviceKey" type="uddi:serviceKey" use="optional"/>
        <xsd:attribute name="bindingKey" type="uddi:bindingKey" use="required"/>
    </xsd:complexType>


Schema Definition of an accessPoint Element

<xsd:element name="accessPoint" type="uddi:accessPoint"/>
    <xsd:complexType name="accessPoint">
        <xsd:simpleContent>
            <xsd:extension base="string">
                <xsd:attribute name="URLType" type="uddi:URLType" use="required"/>
            </xsd:extension>
        </xsd:simpleContent>
    </xsd:complexType>


<tModel>

We saw built-in tModel descriptions earlier in the note. The <tModel> element
holds information on specifications that are managed at other locations. We
can bring forward the UDDI definition for the tModel described for UNSPSC
Version 7 of their specification as an example.


tModel Description in the UDDI Specification v.2.04

unspsc-org:unspsc 
// defines the UNSPSC product and services taxonomy for Version 7 and beyond.

tModel Description:      Product  and Services Taxonomy: UNSPSC (Version 7)
tModel UUID:                uuid: CD153257-086A-4237-B336-6BDCBDCC6634
Categorization:             categorization  // assigned to keyValue see below
Checked:                      Yes

Following is the schema definition for the <tModel> element which we can
compare to the description supplied. The tModel name is 'unspsc-org:unspsc'.
The description is "Product  and Services Taxonomy: UNSPSC (Version 7)". The
'tModelKey' attribute would store 'CD153257-086A-4237-B336-6BDCBDCC6634'

  Schema Definition of the <tModel> Element

<xsd:element name="tModel" type="uddi:tModel"/>
    <xsd:complexType name="tModel">
        <xsd:sequence>
            <xsd:element ref="uddi:name"/>
            <xsd:element ref="uddi:description" minOccurs="0" maxOccurs="unbounded"/>
            <xsd:element ref="uddi:overviewDoc" minOccurs="0"/>
            <xsd:element ref="uddi:identifierBag" minOccurs="0"/>
            <xsd:element ref="uddi:categoryBag" minOccurs="0"/>
        </xsd:sequence>
        <xsd:attribute name="tModelKey" type="uddi:tModelKey" use="required"/>
        <xsd:attribute name="operator" type="string" use="optional"/>
        <xsd:attribute name="authorizedName" type="string" use="optional"/>
    </xsd:complexType>

Following is an example from the UDDI site showing how pre-defined tModel
types would be referenced.

UDDI Site tModel Referencing Example

 
<tModel tModelKey=...
...
  <categoryBag>
    <!--Specify that this is a taxonomy tModel by classifying it as "categorization"
        under the uddi-org:types taxonomy -->
    <keyedReference keyName="uddi-org:types" keyValue="categorization"
    tModelKey="uuid:C1ACF26D-9672-4404-9D70-39B756E62AB4"/>
  </categoryBag>
...
</tModel>



Following is a UDDI sample found on the Microsoft site that shows the
"fingerprint", UUID value being referenced as the tModelKey. It also provides
a sample of how these elements are nested inside the businessEntity element.


Microsoft Example of a UDDI Example showing a tModel being Referenced
<businessEntity xmlns="urn:uddi-org:api"  
 businessKey="BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB"> 
 <name>Contoso Finance Services</name> 
 <description xml:lang="en">Corporate Finance</description> 
 <businessServices> 
  <businessService  
   businessKey="BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB"  
   serviceKey="CCCCCCCC-CCCC-CCCC-CCCC-CCCCCCCCCCCC"> 
  <name>Credit Check</name> 
   <bindingTemplates> 
    <bindingTemplate  
     serviceKey="CCCCCCCC-CCCC-CCCC-CCCC-CCCCCCCCCCCC"  
     bindingKey="DDDDDDDD-DDDD-DDDD-DDDD-DDDDDDDDDDDD"> 
    <accessPoint                  URLType="https">
     https://contoso.com/credit.aspx
    </accessPoint> 
     <tModelInstanceDetails> 
      <tModelInstanceInfo 
       tModelKey="UUID:AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA"/> 
     </tModelInstanceDetails> 
    </bindingTemplate> 
   </bindingTemplates> 
  </businessService> 
 </businessServices> 
 <categoryBag> 
  <keyedReference 
   tModelKey="UUID:CD153257-086A-4237-B336-6BDCBDCC6634"  
   keyName="Consumer credit gathering or reporting services"  
   keyValue="84.14.16.01.00"/>  
 </categoryBag> 
</businessEntity>

<publisherAssertion>

In the above example the <publisherAssertion> element is not present.
This element is used to represent relationships with other organizations.
Both parties in a relationship must make a similar publishers assertion
before a UDDI registry will make this relationship publically viewable.
The publisherAssertion has the following form where the 'fromKey' and
'toKey' reference the 'businessKey' values of two <businessEntity>
registrations.

Schema Definition of the <publisherAssertion> Element

<xsd:element name="publisherAssertion" type="uddi:publisherAssertion"/>
    <xsd:complexType name="publisherAssertion">
        <xsd:sequence>
            <xsd:element ref="uddi:fromKey"/>
            <xsd:element ref="uddi:toKey"/>
            <xsd:element ref="uddi:keyedReference"/>
        </xsd:sequence>
 

<identityBag & categoryBag>

These elements are used to store identity information or category information
respectively. They each store sequences of 'keyedReference' types.


Schema Definition of the <categoryBag> Element

    <xsd:element name="categoryBag" type="uddi:categoryBag"/>
    <xsd:complexType name="categoryBag">
        <xsd:sequence>
            <xsd:element ref="uddi:keyedReference" maxOccurs="unbounded"/>
        </xsd:sequence>
    </xsd:complexType>


Schema Definition of the <identifierBag> Element

<xsd:complexType name="identifierBag">
        <xsd:sequence>
            <xsd:element ref="uddi:keyedReference" maxOccurs="unbounded"/>
        </xsd:sequence>
    </xsd:complexType>

The 'keyedReference' type is shown below and may be used to describe
optionally a 'tModelKey' and or a 'keyName'. A keyValue is required.

Schema Definition of the <keyedReference> Element

<xsd:element name="keyedReference" type="uddi:keyedReference"/>
    <xsd:complexType name="keyedReference">
        <xsd:attribute name="tModelKey" type="uddi:tModelKey" use="optional"/>
        <xsd:attribute name="keyName" type="string" use="optional"/>
        <xsd:attribute name="keyValue" type="string" use="required"/>
    </xsd:complexType>

We borrow the keyedReference element from the Microsoft example
above.

Microsoft Example of a keyedReference Element
  <keyedReference 
   tModelKey="UUID:CD153257-086A-4237-B336-6BDCBDCC6634"  
   keyName="Consumer credit gathering or reporting services"  
   keyValue="84.14.16.01.00"/>

Keys

The schema defines the following all key types that are simple
schema string types. They are used to hold the required key
attribute for each of the main element types.

All are defined in schema elements similar to the following example.

UDDI Schema Example  for the simpleType "bindingKey"


<xsd:simpleType name="bindingKey">
        <xsd:restriction base="string"/>
    </xsd:simpleType>


 
The <dispostionReport> and <result> Elements

The 'dispositionReport' element, used to used to report errors or report
a successful operation where there is no return value, has the following
schema definition. It is a series of one or more <result> elements along
with required attributes 'generic', 'operator' and 'truncated'. We can refer
to our earlier example to see these element deployed.


Schema Definition of the <dispositionReport> Element

<xsd:element name="dispositionReport" type="uddi:dispositionReport"/>
    <xsd:complexType name="dispositionReport">
        <xsd:sequence>
            <xsd:element ref="uddi:result" maxOccurs="unbounded"/>
        </xsd:sequence>
        <xsd:attribute name="generic" type="string" use="required"/>
        <xsd:attribute name="operator" type="string" use="required"/>
        <xsd:attribute name="truncated" type="uddi:truncated" use="optional"/>
    </xsd:complexType>

Following is the schema definition for the <result> element that is used in
the <disposition> element.


Schema Definition of the <result> Element

<xsd:element name="result" type="uddi:result"/>
    <xsd:complexType name="result">
        <xsd:sequence>
            <xsd:element ref="uddi:errInfo" minOccurs="0"/>
        </xsd:sequence>
        <xsd:attribute name="keyType" type="uddi:keyType" use="optional"/>
        <xsd:attribute name="errno" type="int" use="required"/>
    </xsd:complexType>



UDDI Inquiry APIs

UDDI Query Patterns.

UDDI describes the following three query patterns.

The Browse Pattern

Exploring hierarchical data requires 'browse' capabilities, a search is done on broad
information and result sets are obtained. By 'drilling down' into the result set more
specific information can be obtained. The UDDI API supplies 'find_xx' method calls
to accomodate the browse pattern. Summary return messages carry an overview of
registered information associated with the the inquiry message type and the search
criteria used.


Example Summarizing the Browse Pattern // described in the UDDI Specification

Question: Does a business you know have information registered?

Call: Call 'find_business'  + arguments ( a few characters of a business name)
Returns: Returns a 'businessList' containing keys, names and descriptions.


Spotting the business you are looking for in the list will lead to 'drilling-down'
into the corresponding 'businessService' information, looking for particular
service types such as purchasing or shipping etc. using a 'find_service' call.

"If you know the technical fingerprint (tModel signature) of a particular software
interface and want to see if the business you’ve chosen provides a web service
that supports that interface, you can use the find_binding inquiry message".

- Oasis UDDI 2.04 specification

The Drill-down Pattern

"Once you have a key for one of the four main data types managed by a UDDI
you can use that key to access the full registered details for a specific data
instance. The current UDDI data types are businessEntity, businessService,
bindingTemplate and tModel.  You can access the full registered information for
any of these structures by passing a relevant key type to one of the get_xx API
calls."
- Oasis UDDI 2.04 specification

Example Summarizing the Drill-Down Pattern // continued from earlier example

Call: get_'businessDetail'  + argument 'businessKey'
Returns: Returns a 'businessDetail' message holds all registered info
for key(s) passed, (a full businessEntity structure.)

The invocation pattern

UDDI provides the invocation pattern that seeks to eliminate downtime and coordination
costs involved in relocating a service that has moved for reasons such as server upgrades,
disastor recovery, service acquisitions or business name changes etc.

The UDDI bindingTemplate structure stores data representing the details of a given
interface type, including the location at which a program starts interacting with the
service.  This information should be stored (cached) by the calling application for
future communications.

If the service is moved, then calls based on cached bindingTemplate information will
fail.

Example Summarizing the Invocation Pattern

// If a service is moved and calls based on cached bindingTemplate info fail
// the UDDI registry should be queried for fresh bindingTemplate information

Call: Call 'get_bindingDetail' passing as an argument the original bindingKey value. 

Behaviours Based on Return Values:  If the returned data is different from the
cached information, the original service invocation should automatically be retried
using the fresh binding information. (If the result of this retry is successful),  the
new information should replace the cached information.

The Inquiry API

Following are the methods listed for the UDDI Inquiry API. These methods are
available to anyone, akin to phone directory. The methods are executed as HTTP
POST commands and behave synchronously.  Method are notated as XML
elements as is shown in the following simplified example.

Example  <find_binding />

Following is a summary of the find and get methods defined in the Inquiry API.
Following are abbreviated definitions of what each method does. ( For fuller
explanations refer to the UDDI version 2.04 specification.)
 


Inquiry API methods 


* The Related Businesses feature is used to manage registration of business units,
relating them on the basis of organizational hierarchies or business partner relationships.



The Publishers API

As mentioned earlier, publisher's messages require authentication to access a UDDI
Operator Site. These messages are used to register new business information or alter
or delete an existing registration. Maintenance of registrations is the responsibility of
the user as UDDI provides no automated mechanisms to reconcile multiple or duplicate
registrations. Following are abbreviated definitions of what each method does. ( For
fuller explanations refer to the UDDI version 2.04 specification.)


The Publisher'sAPI
 * "Replaces any existing assertions, and causes any old assertions that are not reasserted to be removed
    from the registry. Publisher assertions are used to control publicly visible business relationships"

Details of Inquiry API

Programming API Elements

Each of the message types defined in the Publisher's and Inquiry API are all
defined inside the UDDI schema.  As an example following is the schema
definition for the <find_business> element.


Schema Definitions of the <find_business> Element

<xsd:element name="find_business" type="uddi:find_business"/>
    <xsd:complexType name="find_business">
        <xsd:sequence>
            <xsd:element ref="uddi:findQualifiers" minOccurs="0"/>
            <xsd:element ref="uddi:name" minOccurs="0" maxOccurs="unbounded"/>
            <xsd:element ref="uddi:identifierBag" minOccurs="0"/>
            <xsd:element ref="uddi:categoryBag" minOccurs="0"/>
            <xsd:element ref="uddi:tModelBag" minOccurs="0"/>
            <xsd:element ref="uddi:discoveryURLs" minOccurs="0"/>
        </xsd:sequence>
        <xsd:attribute name="generic" type="string" use="required"/>
        <xsd:attribute name="maxRows" type="int" use="optional"/>
    </xsd:complexType>


These elements are described in the UDDI 2.04 Specifciation in their instance
forms, the forms they would take as SOAP messages. Let us consider some
of the methods that would be used in the 'browse' pattern.

<find_business>

You can find description similar to the following for all the Inquiry and Publisher's
API Messages in the UDDI v.2.04 Specification. The find_business element
results in a businessList message between returned that matches the conditions
specified in it's arguments.

UDDI Syntax:

<find_business [maxRows="nn"] generic="2.0" xmlns="urn:uddi-org:api_v2" >

          [<findQualifiers/>]

          [<name/> [<name/>]…]

     [<discoveryURLs/>]

     [<identifierBag/>]

     [<categoryBag/>]

     [<tModelBag/>]

</find_business>

<>
Arguments

maxRows - optional integer value limiting number of returned results
findQualifiers - This set of findQualifier elements may be used alter the search behavior
name: supplies string values, wild carding is accomplished using the % character.
// The businessList returned contains businessInfo structures names matching value(s) passed.
// see UDDI spec. for details of search behaviour
identifierBag: supplies a list of business identifier references. The returned businessList
contains businessInfo structures matching any of the identifiers passed (logical OR by default).
categoryBag: This is a list of category references.  The returned businessList contains businessInfo
elements matching all of the categories passed (logical AND by default).
tModelBag: The registered businessEntity data contains a bindingTemplates element that in turn
contains bindingTemplate elements that contain specific tModel references. The tModelBag
argument lets you search for businesses that have bindings that expose a specific fingerprint
within the tModelInstanceDetails collection.
discoveryURLs: -supplies a list of URLs to be matched against the discoveryURL data
associated with any registered businessEntity information. 

Return Value

"This API call returns a businessList on success.  This structure contains information
about each matching business, and summaries of the businessServices . . . If a
tModelBag was used in the search, the resulting serviceInfos structure will only
reflect data businessServices that actually contained a matching bindingTemplate. 
In the event that no matches were located for the specified criteria, a businessList
structure with zero businessInfo structures is returned. If no arguments are passed,
a zero-match result set will be returned.

In the event of a large number of matches, (as determined by each Operator Site), or if the
number of matches exceeds the value of the maxRows attribute, the Operator site will truncate
the result set. If this occurs, the businessList will contain the truncated attribute with the value
“true”.  "

Caveats:  // the UDDI describes error scenario in terms of 'Caveats' 

<>If any error occurs in processing this API call, a dispositionReport structure will be returned
to the caller in a SOAP Fault.  The following error number information will be relevant:

E_invalidKeyPassed: - the uuid_key value passed did not match with any known tModelKey values.
E_unsupported: signifies that one of the findQualifier values passed was invalid.
E_tooManyOptions: signifies the defined limit on the number of name arguments was exceeded

Maybe having the schema definition for the name element will be handy.


Schema Definition for the 'name' Element

<xsd:element name="name" type="uddi:name"/>
    <xsd:complexType name="name">
        <xsd:simpleContent>
            <xsd:extension base="string">
                <xsd:attribute ref="xml:lang" use="optional"/>
            </xsd:extension>
        </xsd:simpleContent>
    </xsd:complexType>


Example of a find_Business message that might be sent by a SOAP client.

<find_business maxRows="20" generic="2.0" xmlns="urn:uddi-org:api_v2" >

<>                 <name> % <name/>
                         </find_business>


You send this 'method description' to a UDDI registry and a businessList element
is returned. Inside the business list is one or more businessInfo elements which
include ' businessKey' values. Key values can be used in a subsequent call to
on the <get_businessDetail> method.

<get_businessDetail>

The get_businessDetail call returns complete businessEntity information for one or
more specified businessEntity registrations matching on the businessKey values
specified.

Syntax:

<get_businessDetail generic="2.0" xmlns="urn:uddi-org:api_v2" >

          <businessKey/> [<businessKey/> …]

</get_businessDetail>

Arguments:

businessKey: one or more uuid_key values that represent specific instances of known businessEntity data.

Returns

"Returns a businessDetail message on successful match of one or more businessKey values.
If multiple businessKey values were passed, the results will be returned in the same order as
the keys passed.

Caveats:

If any error occurs in processing this API call, a dispositionReport element will be
returned to the caller within a SOAP Fault.

E_invalidKeyPassed: - one uuid_key values passed did not match with any known
businessKey values.


Following is the form a get_businessDetail might take inside a POST Command.


A get_businessDetail Message Example

<get_businessDetail generic="2.0" xmlns="urn:uddi-org:api_v2" >

<>          <businessKey>
           BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB<>
          <businessKey/>
</get_businessDetail>

Summary

All the Inquiry and Publisher API methods work in a similar fashion. They are
well described in the UDDI Specification. Between the UDDI Specification and
the UDDI Schema for each of these elements it is possible to use these methods
unambiguously. What is missing is a method to POST these messages and
capture the return values.

Where do we go from here?

Next week we look at the JAXM API that gives us a lot of programmatic control
that allows us to do SOAP messaging. We should be able to use a JAXM to
create a client that may be used to make UDDI Inquiries on one of the major
vendor UDDI registries.


Exercise

In the next exercise when we look at Java's JAXM API we might
investigate how a JAXM client could be used to exercise the
UDDI Inquiry API.

For this note, we will do a simple exercise. Read the sections
on the browse and drill down patterns. Then visit one of the sites
of major vendors that supply GUIs for making inquiries on the
UDDI registry. Correlate screen shots of the GUI queries
and results to the Call and Return values described in the
'Browse' & 'Drill Down' patterns described.

In other words, describe briefly how the UDI Inquiry API is being
exercised behind the scenes when using the GUI tool.