![]() ![]() |
UDDIIn early 2000, as the idea of Web services began gaining momentum within the community, it became clear that Web services registries were going to be essential for the concept to become practical. Furthermore, in view of the movement towards open standards in the community, anything but a standard interface and search mechanism for these registries would be unacceptable. Such a registry standard would have to be endorsed by several, if not all, of the large software providers, and adopted by the various industries. Thus, the UDDI initiative, the result of several months of collaboration between representatives from Ariba, IBM, and Microsoft starting in the spring of 2000, was born and formally announced on September 6, 2000. Support for UDDI has expanded beyond the original three companies. Currently, the UDDI project (http://www.uddi.org) involves a community of more than 310 companies. The purpose of UDDI is to facilitate service discovery both at design time and dynamically at runtime. Consequently, the UDDI project runs a public online business (and corresponding services) registry, which first went live on May 2, 2001. This registry is referred to as the UDDI Business Registry. The UDDI Business Registry actually consists of two replicated registries currently hosted by two companies (IBM and Microsoft) called the UDDI Operators Becoming a UDDI registry Operator involves some strict agreements about data replication, data privacy, and policies. From a registered business perspective and from a user perspective, the requirement is that different Operator registries should be theoretically indistinguishable. Businesses can register with any UDDI Operator, and their information will be replicated to the other Operators' registries. As a result, users can search any Operator site and find businesses regardless of which Operator these businesses used to register. There are, however, some subtle issues involved with the decision as to which Operator to use to register your business. For example, some Operators might ask for additional optional information that is not required by UDDI (such as surveys or marketing information). This information is not replicated to other Operators. Another fact to keep in mind is that once you register with an Operator, all updates to your information must be performed through that Operator. This is the case because different Operators implement different security and authentication policies, so authentication information cannot be easily replicated. UDDI is more than a business and services registry, however. It also defines a set of data structures and an API specification for programmatically registering and finding businesses, services, bindings, and service types. In typical Web services scenarios, Web service providers will want to publish their business and service descriptions to a registry, and service requestors, whether at design time or runtime, will want to query the registry for service descriptions. The UDDI API specification, therefore, provides a set of publication APIs In addition to providing a programmatic API, UDDI registry Operators each provide a Web-based user interface for registering, managing, and finding businesses and services in the registry. These Web sites provide a subset of the programmatic API and are relatively self-explanatory, once you have mastered the concepts introduced in this chapter. Their use will be covered in the section "Using the UDDI Web Browser Interface." As of this writing, IBM had its UDDI Web site at http://www.ibm.com/services/uddi and Microsoft at http://uddi.microsoft.com. Of course, all the operator nodes are accessible from http://www.uddi.org. The UDDI Usage ModelIn this section, we'll first examine some typical requirements for a registry of metadata, defining some typical data elements and operations. We will then provide an overview of the UDDI data structures and API, relating them to the original requirements. We will also explore some common UDDI operations that can be performed through the Web browser-based interface to UDDI, as provided by the main UDDI Operators. In doing so, we will introduce the main theme of the SkatesTown scenario that will be used throughout this chapter. The UDDI Registry Requirements: OverviewRegistries in general, whether for software components, services, or otherwise, have some basic requirements:
Common registry requirements for the metadata are:
Common registry requirements for the operations are:
The registry part of UDDI is no different: It has an information model that represents the data structure specifications and an API for the operation specifications. The UDDI information model was designed to be flexible and extensible to allow for any user defined service description models. Because the UDDI specification is an ongoing process of refinement and extension, the bulk of this chapter will describe UDDI Version 1.0 (V1), available at the UDDI Web site. Future versions will only extend the current version with more functionality, while taking care of issues such as replication, versioning, and security. The section "What's New in V2" will describe the UDDI extensions proposed in V2. The UDDI Data Structures: OverviewVersion 1.0 of the UDDI specification allows entities such as businesses and organizations to register public information about themselves and details of the services they offer. It also allows entities such as businesses, standards bodies, and industry groups to register information about the types of services they have defined, about standards and abstractions, and to refer to them by their assigned identifiers. In effect, it is as if UDDI is offering two different registries: a business registry and a reference type registry. Correspondingly, UDDI has at its core two fundamental root data structures: businessEntity and tModel The businessEntity Data StructureBusiness entity information is conceptually divided into what's commonly known as White, Yellow, and Green pages:
It is important to note that this is a conceptual model only, and that UDDI does not specify any particular storage model. Conceptually, however, an entity's White pages entry will contain classification information that points to its place in the various Yellow pages, and an entity's business service entries will contain implementation information that points to entries in the Green pages. This is reflected in the details of the businessEntity structure (see Figure 7.3). The businessEntity element, in addition to various contact, identifier, and taxonomy information, contains a businessServices element, which is a container for businessService elements. A businessService element in turn contains a bindingTemplates element, which is a container for bindingTemplate elements. Finally, bindingTemplate entries point to tModel entries. The details of these structures will be explored in the next sections. Figure 7.3. UDDI information model.The tModel Data StructureThe other important structure in the UDDI information model is the tModel element. Entries in the Green pages, where invocation details are described, are actually business-specific binding details for service types and other abstractions defined elsewhere. These reusable abstractions are referred to as technology models, and their corresponding UDDI data structure is the tModel element. This element allows industry groups, standards bodies, and individual businesses to specify reusable abstract definitions of service types that others can use and combine, creating, in effect, a signature for a service. In the UDDI identification scheme, each instance of the four types of entries is assigned a unique identifier by the UDDI node upon initial registration. In addition, according to the UDDI containment scheme, each instance of a contained structure (businessService and bindingTemplate) holds a key reference to its containing entity (in this case, businessEntity and businessService, respectively) in a strict parent-child relationship. These identifiers are Universal Unique Identifiers (UUIDs) that follow the OSF Distributed Computing Environment (DCE) conventions (http://www.osf.org/onlinepubs/9629399/apdxa.htm). They follow the familiar 8-4-4-4-12 pattern (such as F775A3A6-FF3E-4B85-B1DE-F0F99D0E2C6D). In addition, tModel references are given the uuid: URN qualifier. Finally, it was deemed important that private (that is, non-Operator but otherwise UDDI compatible) UDDI registries be able to extend the businessEntity structure to include data for their own purposes. To this end, the businessEntityExt structure was specified. UDDI registry Operators, however, will not provide extensions in their publicly online available business entity data. The UDDI API: OverviewIn addition to defining the data structures to be stored in the registry, the UDDI specification provides two main types of API operations: the Publication API and the Inquiry API. These APIs define a set of 20 SOAP messages over HTTP or HTTPS that must be understood by any UDDI-conformant registry. The SOAP body of the API messages and responses are XML structures defined in the UDDI specification. The Publication API is an authenticated set of operations that allows organizations to publish information, whether business, service, implementation, or service type specification, to the UDDI registry. Aside from requiring an authentication token The Inquiry API is a non-authenticated public set of operations that allows users to extract information out of the UDDI registry. Inquiries can follow two different patterns: a browsing pattern to find general information (the find operations), usually followed by a drill-down pattern to find specific detail information (the get_Detail operations). Corresponding to the four structure types (businessEntity, businessService, bindingTemplate, and tModel), UDDI provides four save operations (save_business, save_service, save_binding, and save_tModel), four delete operations (delete_business, delete_service, delete_binding, and delete_tModel), four find operations (find_business, find_service, find_binding, and find_tModel) and four get_Detail operations (get_businessDetail, get_serviceDetail, get_bindingDetail, and get_tModelDetail); see Table 7.1. You can use the save operations to create a new entry or to update an existing one. When creating a new entry, the entry identification key parameter is not supplied in the call, but instead is assigned by the Operator and returned in the Operator's response. To update an existing entry, this Operator-assigned key is supplied in the call. The delete operations take the Operator assigned keys as parameters and remove the corresponding entries from the registry. The delete_tModel operation is an exception that will be discussed in the section "The Delete Operations." The find operations are passed a set of search criteria and generally return a (possibly empty) list structure containing information about entries that match the search criteria. The get_detail operations are passed a list of identifiers and return detailed information about the entries referred to by the supplied keys. The API provides one additional get_detail operation, get_businessDetailExt, to allow the retrieval of extended business information from non-Operator nodes that implement these extensions. In addition, because the Publication API is a set of authenticated operations, where authentication is token-based, the API provides two authentication operations, get_authToken and discard_authToken. Finally, getRegisteredInfo is an authenticated operation that returns all the businessEntity and tModel keys registered by an accredited user. In the next sections, we will cover in detail the UDDI data structures and API and go through examples as SkatesTown registers its information so that potential clients can locate it, and so that it can locate potential suppliers. It is important to note that it is possible to perform most of the Publication and Inquiry API functions (such as some find and get_Details operations) through the individual Operators' Web sites. The next section will go through such an example while introducing one of the main scenarios that will be used throughout the chapter. In addition to being more complete and powerful than what's available through the browser interface, however, the API is intended to allow businesses to perform all the operations programmatically, in order to facilitate dynamic (runtime) service discovery. Keep that in mind as we go through the next examples. Using the UDDI Web Browser InterfaceBefore we examine the API in detail, it will be useful to briefly explore the browser interface to UDDI. UDDI Operators, as part of their responsibility to the UDDI consortium, have each provided a free public Web-based interface to their UDDI business registries. This interface allows organizations to register their businesses, along with contact information and services provided. Service type definitions can also be entered (these will be covered in more detail later in the section "The UDDI tModel Concept"). In this next example, SkatesTown will register its business and the contact information of Dean Carroll, the company's chief technology officer. It will also register its online catalog as an HTTP-based Web service, and classify it under the North American Industry Classification System (NAICS) taxonomy (we will discuss taxonomies in more detail in the section "More on Classification and Categorization"). Although this basic example will be explored in more detail and expanded significantly throughout our discussion of the UDDI API, it provides the main theme for the UDDI usage model. The first step in using the UDDI registries is to register an ID and obtain an authentication token. Both IBM (https://www-3.ibm.com/services/uddi/protect/registry.html) and Microsoft (http://uddi.microsoft.com/register.aspx) registries require a username and password as a method of authentication. In the following example Dean Carroll, SkatesTown CTO, will use the IBM Test registry. Figure 7.4 shows the registration page. Dean enters skatestown as the user ID and fills out the rest of the required information. Once registered, Dean can start the process of adding a new business entry. Having entered the business name, he then has the option of entering a business description, business contact information, and business locator information, which allows other users to find SkatesTown through a variety of keyword searches on the Add New Business Web page. Figure 7.4. The UDDI Registration Web page.A variety of contact information can be entered, including descriptions, phone numbers, e-mail addresses, and mailing addresses. Finally, the business is categorized by entering locator information. The UDDI Version 1.0 specification provides a set of pre-determined taxonomies to be used for this purpose (see the section "More on Classification and Categorization"). For this instance, Dean will use the NAICS taxonomy and drill down to the 33992 category, "Sporting and Athletic Goods Manufacturing" (see Figure 7.5). Figure 7.5. The NAICS Category 33992 Selection Web page.The next step is to enter a Web service registration. In this case, Dean will register the online Check Order Status Web service provided by SkatesTown. The service registration page allows for a variety of information to be entered about the service, including a description (what is this service?), access point information (how do I invoke it?) and locator information (what kind of service is it?). Figures 7.6 and 7.7 show a high-level view of all the SkatesTown business and service information that was entered, respectively. Figure 7.6. The UDDI Business Details Web page.Figure 7.7. The UDDI Service Details Web page.It is interesting to notice that in both cases, the UDDI registry has generated unique keys for the business entry and the service entry. In addition, it has generated a URL for the business description (under the title Discovery URL) that returns the following XML document, describing the SkatesTown UDDI business entry: <?xml version="1.0" encoding="utf-8" ?> <businessDetail generic="1.0" xmlns="urn:uddi-org:api" operator="www.ibm.com/services/uddi" truncated="false"> <businessEntity authorizedName="0100003BG0" operator="www.ibm.com/services/uddi" businessKey="ED88D790-AA0E-11D5-98D0-0004AC49CC1E"> <discoveryURLs> <discoveryURL useType="businessEntity"> http://www-3.ibm.com/services/uddi/testregistry/uddiget? businessKey=ED88D790-AA0E-11D5-98D0-0004AC49CC1E </discoveryURL> </discoveryURLs> <name>SkatesTown</name> <contacts> <contact useType="CTO"> <personName>Dean Carroll</personName> </contact> </contacts> <businessServices> <businessService serviceKey="C8013A60-AA10-11D5-98D0-0004AC49CC1E" businessKey="ED88D790-AA0E-11D5-98D0-0004AC49CC1E"> <name>Check Order Status</name> <description xml:lang="en">Check your order status online </description> <bindingTemplates> <bindingTemplate bindingKey="C8061C60-AA10-11D5-98D0-0004AC49CC1E" serviceKey="C8013A60-AA10-11D5-98D0-0004AC49CC1E"> <description xml:lang="en"> This is a web based (http) order status service </description> <accessPoint URLType="http"> http://www.skatestown.com/services/orderStatus</accessPoint> <tModelInstanceDetails> <tModelInstanceInfo tModelKey="UUID:68DE9E80-AD09-469D-8A37-088422BFBC36"> </tModelInstanceInfo> </tModelInstanceDetails> </bindingTemplate> </bindingTemplates> <categoryBag> <keyedReference tModelKey="UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2" keyName="Sporting and Athletic Goods Manufacturing" keyValue="33992"> </keyedReference> </categoryBag> </businessService> </businessServices> <categoryBag> <keyedReference tModelKey="UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2" keyName="Sporting and Athletic Goods Manufacturing" keyValue="33992"> </keyedReference> </categoryBag> </businessEntity> </businessDetail> We will be seeing more of this type of XML document as we expand on the example in the next sections, by exploring the UDDI data structure and API. The UDDI tModel ConceptBefore we begin publishing more services to UDDI, we need to explore the concept of a tModel in detail, because it is essential to how services are described. What Is a tModel?In order to invoke a service, you sometimes need to know a large amount of detail in terms of document formats, transport protocols, input and output parameters, URNs, business process, and so on. These details in general could be supplied in the description of the service implementation. In Chapter 6, Listing 6.1, you saw an example of a WSDL definition for the PriceCheck service for SkatesTown. That definition contained both abstract reusable information (the service interface definition) and concrete implementation information (the service implementation definition). If software engineering has taught us one thing in the last decade, it is the power of abstraction and re-use. Suppose that another company belonging to the same SEMC consortium were to implement an identical service. It would have to repeat the same bulk of information in its WSDL document, with the only difference being the endpoint address for the implementation of its SOAP service. Suppose, however, that the SEMC consortium were to abstract out the service interface definition of the WSDL document and publish it as a consortium standard. This would enable both companies (and any other company in the consortium) to reference that abstract definition and only have to supply their concrete implementation endpoint. That abstract service interface definition is, in essence, a perfect example of a tModel. In general, these types of service specifications could be applicable in several different places for different services, or for different bindings for the same service. They can also be specified by an industry consortium as we saw in the examples, a standards body, or a large corporation for the use by its suppliers. Thus conformance to a known and predefined set of specifications becomes very important. The tModel concept is the mechanism for such abstractions. It allows various entities (businesses, standards bodies, industry groups, and so on) to publish abstract specifications to be used by other entities in implementing services. In our previous examples, the SEMC would register its http://www.semc-consortium.org/BP/PriceCheck specification as a tModel, which would be assigned a unique identifier key and be referenced by all businesses in the consortium, such as SkatesTown. In addition, clients wanting to find businesses that conform to that SEMC specification can query the registry for businesses referencing that tModel. How to Use tModelsIt is important to stress that based on the UDDI specification, a tModel could define just about anything: It consists of a key, a name, a description, and a URL. This simplicity is a powerful concept, but it can also be a double-edged sword. On the one hand, because of the simplicity in defining a tModel, you can define anything you want, even if it's not useful to or reusable by anyone else. On the other hand, if used properly, you can use tModels to specify the standards and templates that will be used in the next generation of e-Business on the Web. Throughout the UDDI data structures, tModels are used as references. By convention, the UDDI specification suggests two main uses for them. The primary use is in defining what is called a technical fingerprint. This refers to any technical specifications or pre-arranged agreements on how to conduct business. For example, tModels can be created by industry groups such as RosettaNet (http://www.rosettanet.org), or by companies wishing to standardize the way they deal with suppliers. Our examples illustrate how SkatesTown and MyTurningWheels are using a specification defined by another entity, namely SEMC. The other main use for tModels is in defining namespaces to be used in the identifierBag and categoryBag structures. This will be covered in more detail in the section "More on Classification and Categorization." The tModel StructureAs we already discussed, the tModel structure is very simple. In general, an entity that acts as a reference needs a name, a description, some reference material that describes the details of its use, and a resolvable, unique identifier. This is true of a UDDI tModel. It has a key, a name, a description, an optional descriptive overview document, and some categorization and identification information (see Figure 7.8). Figure 7.8. The tModel structure.tModel attributes are as follows:
tModel elements are as follows:
More on Classification and CategorizationAs we previously stated, one of the main objectives of the UDDI registries is the discovery of services, whether statically (design time) or dynamically (runtime). This entails a form of search through a large space of entries. In a reasonably populated registry, depending on the search mechanism, this could return a very large set of hits. An early requirement for UDDI, therefore, was a way to perform intelligent searches. Until the semantic problem (see Chapter 9, "Future Concepts") is addressed in a satisfactory manner, the best current mechanism to facilitate such searches is through taxonomic categorization and classification. Categorization is the process of creating categories, whereas classification is the process of assigning objects to these predefined categories (or classes). There are several types of classification schemes (such as the Library of Congress Classification used in most libraries), but for a large space such as businesses and services, the most useful ones are hierarchical in nature. In general, hierarchies are very powerful for organizing data (consider XML!). One of the most powerful examples of the importance of hierarchical classification in the age of the Web is Yahoo! In addition to a search engine, Yahoo! offers an extensive classification scheme. For example, to find manufacturers of skateboards, you would naturally traverse the Yahoo! classification tree to get to Business_and_Economy/Shopping_and_Services/Sports/ Skateboarding/Deck_and_Truck_Manufacturers/. It can be argued that the first-generation Web (the information Web of HTML and CGI pages) did not attain its potential until the Yahoo! classification scheme became available. Similarly, a registry such as UDDI would be very difficult to use without some classification schemes. The first version of UDDI includes in its core specifications three predefined classification schemes: the North American Industry Classification System (NAICS) for classifying businesses by industry (http://www.ntis.gov/product/naics.htm), the Universal Standard Products and Services Classification (UNSPSC) for product and service classifications (http://eccma.org/unspsc), and the ISO 3166 standard for geographic location classifications (http://www.din.de/gremien/nas/nabd/iso3166ma). In order to take advantage of these schemes, businesses need to provide the relevant classification information as they register their entries. This is done through the categoryBag element. This element contains a set of keyedReference elements (see Figure 7.9), each of which has attributes forming a name/value pair and an optional tModelKey. The tModelKey is a simple but powerful extension mechanism that acts as a namespace qualifier for the values specified in the name/value pair. For example, if SkatesTown wanted to classify its business using the Yahoo! classification scheme, (assuming that Yahoo has registered the scheme as a tModel with an assigned key of 3D4EC875-E54F-4D8D-9CBF-346D48BCAD9C), the company could add the following keyedReference to its categoryBag, using the reference to the Yahoo! classification tModel as a namespace for its category: <keyedReference keyName="Yahoo Business Taxonomy" keyValue="Business_and_Economy/Shopping_and_Services/Sports/ Skateboarding/Deck_and_Truck_Manufacturers" tModelKey="UUID:3D4EC875-E54F-4D8D-9CBF-346D48BCAD9C"/> Figure 7.9. The keyedReference structure.Another important use for the keyedReference element is in the identifierBag structure. The identifierBag is very similar to the categoryBag construct in structure in that it is a container for a set of keyedReference elements. Instead of categorization information, however, the identifierBag (as its name implies) is used to provide identification information. This mechanism allows registered entities, whether businesses or tModels, to be associated with some declared identification scheme, such as a tax ID or an industry group ID, in a consistent manner. This, in turn, provides a richer context and an additional mechanism for searching across UDDI entries. As an example, consider that the D-U-N-S number is defined as a tModel in the UDDI Taxonomy namespace (see the section "UDDI Core tModel"). In a similar manner, e-Torus can define its own business registry under this model. Businesses in the e-Torus marketplace can identify themselves using that tModel as a namespace. The details of the e-Torus Registry Number tModel would look like this (it is of type identifier in the UDDI Type taxonomy): <tModel tModelKey="uuid:F2390501-A240-4470-8A5A-6088EE5B1A14"> <name>et:e-Torus-registry</name> <description xml:lang="en">e-Torus Registry Number</description> <categoryBag> <keyedReference keyName=" Unique identifiers for member companies" keyValue="identifier" tModelKey="uuid:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> This means that businesses that want to provide their e-Torus Registry Number as identification for search purposes can do so by adding keyed reference pointing to this tModel in their categoryBag. You will see such examples in the section "The Business Entity Structure." The save_tModel StructureOrganizations or businesses can define, create, and publish their own tModels using the save_tModel operation. A save_tModel message needs to be constructed with a save_tModel structure in the body element of the SOAP envelope, and the tModel structure contained within (see Figure 7.10). Figure 7.10. The save_tModel message structure.save_tModel has this message signature:
<save_tModel generic="1.0" xmlns="urn:uddi-org:api" >
<authInfo/>
<tModel/> [<tModel/>...] | <uploadRegister/> [<uploadRegister/>...]
</save_tModel>
save_tModel has a single attribute: generic, which is required. This attribute is present on all the UDDI API operations. As the UDDI specification grows and is modified, Operator sites will have to manage versions of the API, and will be required to support all current versions. The generic attribute specifies the version of the API to which a particular operation belongs. In UDDI V1 operations, this is the string "1.0". save_tModel has the following elements:
AuthenticationAs you have already seen, all Publication API operations need to be authenticated. Privacy, security, and authentication are crucial for the UDDI Operators to build a trusted relationship with UDDI users. However, because there is still no one clearly universal and widely accepted standard for authentication, various Operators have different authentication policies. As a result, the UDDI authentication mechanism involves getting an opaque authentication token by means specified by the UDDI Operator, using it in the authInfo attribute, and then, optionally, discarding it. In addition, all Publication API messages are SSL encrypted. UDDI Operator nodes can specify their own specific mechanism for getting a token. In case no Operator-specific mechanism is provided, Operators are required to implement the get_authToken API. Authentication in this case is performed by first getting an opaque authentication token from the UDDI registry through the get_authToken call (see Figure 7.11), supplying that token in the authInfo element in the subsequent calls, and finally discarding the token through the discard_authToken call (see Figure 7.12). This process is described in the next examples. Figure 7.11. The get_authToken message structure.Figure 7.12. The discard_authToken message structure.Before being allowed to publish information to an Operator node, a prospective user will need to establish some credentials through an initial pre-registration step, which is Operator dependent. As a result of this initial step, each registering entity is either issued an authentication token (such as a certificate) or a user ID and password. These values are passed in the authInfo element of the Publishing API calls, or the userID and cred elements of the get_authToken call, respectively. The following is an example of the get_authToken message where the sender has pre-registered with the UDDI Operator site and been assigned a user ID and password: <get_authToken generic="1.0" xmlns="urn:uddi-org:api" userID="{ userID assigned by Operator} " cred="{ password chosen at registration} "/> The result of the get_authToken operation is an authToken structure (see Figure 7.13) identifying the Operator and providing a token, usually in the form of a UUID. Figure 7.13. The authToken structure.The response to the previous message, assuming the correct password was supplied and the user is pre-registered, is shown: <authToken generic="1.0" xmlns="urn:uddi-org:api" operator="UDDIOperator"> <authInfo>5BA16322-B5ED-4300-8F2F-420DA3A212D2</authInfo> </authToken> The discard_authToken operation is used to inform the token issuer that the token is no longer valid and can be discarded. Subsequent Publishing API calls using the same token should be rejected. It passes as parameter the token received in the get_authToken operation: <discard_authToken generic="1.0" xmlns="urn:uddi-org:api"> <authInfo>5BA16322-B5ED-4300-8F2F-420DA3A212D2</authInfo> </discard_authToken> Publishing tModel Information in UDDISkatesTown belongs to an industry consortium, the Sports Equipment Manufacturing Consortium (SEMC), which has published a set of specifications for conducting business on the Internet, including specifications for order management, and in particular order status processing. When implemented by manufacturers, these specifications are intended to facilitate the process of customers' checking the status of their orders. The SEMC published its specifications under several tModels. The root specification that covers the overall SEMC set of specifications is registered in this section. As discussed in the previous section on authentication, it is assumed here that the SEMC has already registered with a UDDI Operator, and that the Operator uses a user ID and password authentication scheme. In order to use the Publication API, we need to get an authentication token: <get_authToken generic="1.0" xmlns="urn:uddi-org:api" userID="SEMC" cred="thisbetterbeareallygoodpassword:wemakestuff"/> The Operator UDDI node then would send a response: <authToken generic="1.0" xmlns="urn:uddi-org:api" operator="UDDIOperator"> <authInfo>50D1FEBF-4D47-4D8F-A9A5-56403DF080AB</authInfo> </authToken> The authInfo token is then used in the save_tModel call. The following shows what a new tModel registration document would look like: <save_tModel generic="1.0" xmlns="urn:uddi-org:api"> <authInfo>50D1FEBF-4D47-4D8F-A9A5-56403DF080AB</authInfo> <tModel tModelKey=""> <name>Sports Equipment Manufacturing Consortium e-business Specification V1.2</name> <description xml:lang="en">Root tModel for the SEMC set of specifications for e-business on the Internet</description> <overviewDoc> <description xml:lang="en">This document describes the structure, sections and requirements for the SEMC IeBS specification V1.2 </description> <overviewURL>http://www.semc-consortium.org/SEMC-IeBS.html </overviewURL> </overviewDoc> <identifierBag> <keyedReference keyName="DUNS" keyValue="00-222-2222" tModelKey="uuid:D9392AEE-9A13-4B6E-B528-5A0D08BD4BF9"/> </identifierBag> <categoryBag> <keyedReference keyName="types" keyValue="specification" tModelKey="uuid:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> </save_tModel> In this example, the SEMC is using the authentication token that it received in the previous get_authToken call. Registering the information is very straightforward. In addition to a name and brief description, an overviewURL is given, pointing to the SEMC Web pages that describe the set of specifications. identifierBag and categoryBag information is included. The identifierBag information lists the D-U-N-S number for the consortium, which will facilitate searching for the tModels registered by SEMC (the number shown is fictitious and only used for illustration). The categoryBag information uses the canonical UDDI tModel supertype for specification, indicating that this tModel is a specification type of tModel. Canonical UDDI tModels are described in the section "UDDI Core tModels." The UDDI registry would then assign a key to the tModel, register it, and send the following acknowledgement response. Notice that the Operator has assigned a unique tModelKey to the tModel, along with an authorizedName (SEMC.org) and an Operator (UDDIOperator). The following is a response to the SEMC save_tModel Message: <tModelDetail generic="1.0" operator="UDDIOperator" truncated="false" xmlns="urn:uddi-org:api"> <tModel authorizedName="SEMC.org" operator="UDDIOperator" tModelKey="uuid:61A08700-0684-4E05-BB7D-C624BED3B901"> <name>Sports Equipment Manufacturing Consortium eBusiness Specification V1.2</name> <description xml:lang="en">Root tModel for the SEMC set of specifications for eBusiness on the Internet</description> <overviewDoc> <description xml:lang="en">This document describes the structure, sections and requirements for the SEMC IeBS specification V1.2 </description> <overviewURL>http://www. semc.org/SEMC-IeBS.html</overviewURL> </overviewDoc> <identifierBag> <keyedReference keyName="DUNS" keyValue="00-222-2222" tModelKey="uuid:D9392AEE-9A13-4B6E-B528-5A0D08BD4BF9"/> </identifierBag> <categoryBag> <keyedReference keyName="types" keyValue="specification" tModelKey="uuid:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> </tModelDetail> Next, the SEMC registers an Order Management specification V1.5 using the following message. Notice that one of the keyed references in the categoryBag element points to the root SEMC IeBS specification V1.2, indicating that this tModel is part of that hierarchy, again facilitating searches. Here is what that tModel looks like: <save_tModel generic="1.0" xmlns="urn:uddi-org:api"> <authInfo>50D1FEBF-4D47-4D8F-A9A5-56403DF080AB</authInfo> <tModel tModelKey=""> <name>Sports Equipment Manifacturing Consortium Order Management V1.5</name> <description xml:lang="en">tModel for the SEMC Order Management set of specifications V1.5</description> <overviewDoc> <description xml:lang="en">This document describes the details and conformance requirements for the SEMC IeBS Order Management V1.5 specification </description> <overviewURL>http://www.semc-consortium.org/SEMC-IeBS/OrderMgmt.html </overviewURL> </overviewDoc> <identifierBag> <keyedReference keyName="DUNS" keyValue="00-222-2222" tModelKey="uuid:D9392AEE-9A13-4B6E-B528-5A0D08BD4BF9"/> </identifierBag> <categoryBag> <keyedReference keyName="types" keyValue="specification" tModelKey="uuid:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> <keyedReference keyName="types" keyValue="specification" tModelKey="uuid:61A08700-0684-4E05-BB7D-C624BED3B901"/> </categoryBag> </tModel> </save_tModel> The UDDI registry again registers the tModel and assigns it a tModel key (for future examples, let's assume this key has a value of 6E986185-3937-442F-8916-209DA01DF837). UDDI Core tModelsAs we saw in the previous example, SEMC declared its specifications to be of the specification type, using a types namespace provided by UDDI. The first release of the UDDI specification registered several tModels for use as a starting set. UDDI defines a root or supertype tModel for all types, used to establish a hierarchical taxonomy of types. Then, all other type tModels are defined in this tModel's namespace (including the UDDI Type itself, which is self-referential, as seen from its definition). The UDDI type taxonomy tModel has the following definition: <tModel tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"> <name>uddi-org:types</name> <description xml:lang="en">UDDI Type Taxonomy</description> <overviewDoc> <description xml:lang="en">Taxonomy used to categorize Service Descriptions</description> <overviewURL>http://www.uddi.org/specification.html</overviewURL> </overviewDoc> <categoryBag> <keyedReference keyName="types" keyValue="categorization" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> Figure 7.14 lists all the UDDI types belonging to this taxonomy. These types can be used to categorize other tModels. Figure 7.14. The core tModel taxonomy hierarchy.Let's look at how this works. For example, the Dun & Bradstreet D-U-N-S® number is defined as follows: <tModel tModelKey="UUID:8609C81E-EE1F-4D5A-B202-3EB13AD01823"> <name>dnb-com:D-U-N-S</name> <description xml:lang="en">Dun & Bradstreet D-U-N-S® Number</description> <overviewDoc> <description xml:lang="en">This tModel is used for the Dun & Bradstreet D-U-N-S(r) Number identifier.</description> <overviewURL>http://www.uddi.org/specification.html</overviewURL> </overviewDoc> <categoryBag> <keyedReference keyName="types" keyValue="identifier" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> In the keyedReference element in the categoryBag, the tModelKey value of C1ACF26D-9672-4404-9D70-39B756E62AB4 is the key for the UDDI Type Taxonomy tModel, which is the namespace for all UDDI Types. Of all the possible values in the taxonomy of this core namespace, this tModel is categorized as an identifier type (through the keyValue attribute). (The authorizedName and operator attributes of the tModel element will be omitted in all the examples in this section because they are irrelevant to the point being illustrated.) Next, UDDI defines some core tModels for the three main API services. These tModels are all classified in the UDDI Type tModel namespace as being of types specification, xmlSpec, and soapSpec: <tModel tModelKey="UUID:4CD7E4BC-648B-426D-9936-443EAAC8AE23"> <name>uddi-org:inquiry</name> <description xml:lang="en">UDDI Inquiry API - Core Specification </description> <overviewDoc> <description xml:lang="en">This tModel defines the inquiry API calls for interacting with the UDDI registry.</description> <overviewURL>http://www.uddi.org/specification.html</overviewURL> </overviewDoc> <categoryBag> <keyedReference keyName="types" keyValue="specification" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> <keyedReference keyName="types" keyValue="xmlSpec" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> <keyedReference keyName="types" keyValue="soapSpec" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> The UDDI Publication API core specification tModel has the following definition: <tModel tModelKey="UUID:64C756D1-3374-4E00-AE83-EE12E38FAE63"> <name>uddi-org:publication</name> <description xml:lang="en">UDDI Publication API - Core Specification </description> <overviewDoc> <description xml:lang="en">This tModel defines the publication API calls for interacting with the UDDI registry.</description> <overviewURL>http://www.uddi.org/specification.html</overviewURL> </overviewDoc> <categoryBag> <keyedReference keyName="types" keyValue="specification" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> <keyedReference keyName="types" keyValue="xmlSpec" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> <keyedReference keyName="types" keyValue="soapSpec" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> The UDDI Taxonomy API core specification tModel has the following definition: <tModel tModelKey="UUID:3FB66FB7-5FC3-462F-A351-C140D9BD8304"> <name>uddi-org:taxonomy</name> <description xml:lang="en">UDDI Taxonomy API</description> <overviewDoc> <description xml:lang="en">This tModel defines the taxonomy maintenance API calls for interacting with the UDDI registry </description> <overviewURL>http://www.uddi.org/specification.html</overviewURL> </overviewDoc> <categoryBag> <keyedReference keyName="types" keyValue="specification" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> <keyedReference keyName="types" keyValue="xmlSpec" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> <keyedReference keyName="types" keyValue="soapSpec" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> The different taxonomies are also defined in the spec. The NAICS taxonomy is as follows: <tModel tModelKey="UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2"> <name>ntis-gov:naics:1997</name> <description xml:lang="en">Business Taxonomy: NAICS (1997 Release) </description> <overviewDoc> <description xml:lang="en">This tModel defines the NAICS industry taxonomy.</description> <overviewURL>http://www.uddi.org/specification.html</overviewURL> </overviewDoc> <categoryBag> <keyedReference keyName="types" keyValue="categorization" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> The UNSPSC taxonomy is as follows: <tModel tModelKey="UUID:DB77450D-9FA8-45D4-A7BC-04411D14E384"> <name>unspsc-org:unspsc:3-1</name> <description xml:lang="en">Product Taxonomy: UNSPSC (Version 3.1) </description> <overviewDoc> <description xml:lang="en">This tModel defines the UNSPSC product taxonomy.</description> <overviewURL>http://www.uddi.org/specification.html</overviewURL> </overviewDoc> <categoryBag> <keyedReference keyName="types" keyValue="categorization" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> The ISO 3166-1:1997 and 3166-2:1998 geographic taxonomy is as follows: <tModel tModelKey="UUID:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88"> <name>iso-ch:3166:1999</name> <description xml:lang="en">ISO 3166-1:1997 and 3166-2:1998. Codes for names of countries and their subdivisions. Part 1: Country codes. Part 2:Country subdivision codes. Update newsletters include ISO 3166-1 V-1 (1998-02-05), V-2 (1999-10-01), ISO 3166-2 I-1 (1998)</description> <overviewDoc> <description xml:lang="en">Taxonomy used to categorize entries by geographic location.</description> <overviewURL>http://www.uddi.org/iso-ch-3166-1999.html</overviewURL> </overviewDoc> <categoryBag> <keyedReference keyName="types" keyValue="categorization" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> Finally, a miscellaneous taxonomy for entries that do not validate in the other taxonomies is as follows: <tModel tModelKey="UUID:A035A07C-F362-44DD-8F95-E2B134BF43B4"> <name>uddi-org:misc-taxonomy</name> <description xml:lang="en">Other Taxonomy</description> <overviewDoc> <description xml:lang="en">This tModel defines an unidentified taxonomy </description> <overviewURL>http://www.uddi.org/specification.html</overviewURL> </overviewDoc> <categoryBag> <keyedReference keyName="types" keyValue="categorization" tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4"/> </categoryBag> </tModel> The last tModel is the Dun and Bradstreet D-U-N-S number, which we've already seen. Publishing Business Information to a UDDI RegistryLet's now go through some detailed examples of businesses using the UDDI registry. SkatesTown has decided to start using UDDI to publish its information and find business partners. To publish its business information, SkatesTown needs to construct a businessEntity structure and send it in a SOAP message using the save_business call. Let's look in more detail at the businessEntity structure. The businessEntity StructureThe businessEntity element is the top-level element in the UDDI information data structure (see Figure 7.15). The structure is used to represent information about an entity or a business. It is also used as a container for the business services element and indirectly for the corresponding implementation and binding details of all the services that an entity provides. Its top structure is relatively similar to the other top structure in the UDDI information model, the tModel, in that it has for attributes a unique key, an Operator, and an authorized name. Again, just like a tModel structure, its elements include name, description, categoryBag, and identifierBag information. In addition, it has contact information, and it acts as the container for the business services. Figure 7.15. The businessEntity structure.businessEntity has the following attributes:
businessEntity has the following elements:
The save_business OperationIn order to publish the business information to the UDDI registry, you need to construct a save_business message with a save_business structure in the body element of the SOAP envelope, and the businessEntity structure contained within (see Figure 7.17). This structure is very similar to the save_tModel structure, the only difference being that it contains a businessEntity element, and that the uploadRegister information should point to valid businessEntity information: <save_business generic="1.0" xmlns="urn:uddi-org:api"> <authInfo/> <businessEntity/> [<businessEntity/>...] | <uploadRegister/> [<uploadRegister/>...] </save_business> Figure 7.17. The save_business message structure.The response to a save_business SOAP message is a businessDetail structure reflecting the final results of the save_business operation. Putting It Together: save_business ExampleFirst, as we saw, SkatesTown needs to get an authentication token. Although it is important to keep in mind that all Publication API calls are authenticated, this step will be omitted from now on for brevity. The authInfo token is then used in the save_business call. The following shows what a new business entity registration document would look like: <save_business generic="1.0" xmlns="urn:uddi-org:api"> <authInfo>65EC92F4-21C4-4EA6-B438-9994C4BD24CB</authInfo> <businessEntity <name>SkatesTown</name> <description xml:lang="en">Provides the best skate products in the world </description> <contacts> <contact useType="Technical Information"> <description xml:lang="en">CTO for technical information </description> <personName>Dean Carroll</personName> <phone useType="Main Office">1.212.555.0001</phone> <email useType="CTO">dean.carroll@SkatesTown.com</email> <email useType="General Information">info@SkatesTown.com</email> <address useType="Main Office" sortCode="10001"> <addressLine>2001 Skate Services Ln</addressLine> <addressLine>New York, NY 10001</addressLine> <addressLine>USA</addressLine> </address> </contact> </contacts> <categoryBag> <keyedReference keyName="Sporting and Athletic Goods Manufacturing" keyValue="33992" tModelKey="UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2"/> <keyedReference keyName="New York" keyValue="US-NY" tModelKey="UUID:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88"/> </categoryBag> <identifierBag> <keyedReference keyName="DUNS" keyValue="00-111-1111" tModelKey="UUID:8609C81E-EE1F-4D5A-B202-3EB13AD01823"/> </identifierBag> </businessEntity> </save_business> In this example, SkatesTown has used the authentication token that it received in the previous get_authToken call, and registered information about itself. In addition to its business name, description, and technical contact information (CTO), it has categorized itself under code 33992 (Sporting and Athletic Goods Manufacturing) of the NAICS classification and in the US-NY value of the geographic location classification and provided its Dun & Bradstreet D-U-N-S number as identifier. Note that the businessKey element is not supplied, because this is a new registration. In response, the Operator UDDI node would send this confirmation: <businessDetail generic="1.0" operator="UDDIOperator" truncated="false"> <businessEntity businessKey="uuid:D7B8D630-59E7-11D5-9675-95373BEF0080" operator="UDDIOperator" authorizedName="Dean Carroll"> <discoveryURLs> <discoveryURL useType="businessEntity"> http://www.UDDIOperator.com? businessKey=55BB30D8-565A-4EF9-BA2E-83118AED644D </discoveryURL> <discoveryURLs> <name>SkatesTown</name> <description xml:lang="en">Provides the best skate products in the world </description> <contacts> <contact useType="Technical Information"> <description xml:lang="en">CTO for technical information </description> <personName>Dean Carroll</personName> <phone useType="Main Office">1.212.555.0001</phone> <email useType="CTO"> dean.carroll@SkatesTown.com</email> <email useType="General Information"> info@SkatesTown.com</email> <address useType="Main Office" sortCode="10001"> <addressLine>2001 Skate Services Ln</addressLine> <addressLine>New York, NY 10001</addressLine> <addressLine>USA</addressLine> </address> </contact> </contacts> <categoryBag> <keyedReference keyName="Sporting and Athletic Goods Manufacturing" keyValue="33992" tModelKey="UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2"/> <keyedReference keyName="New York" keyValue="US-NY" tModelKey="UUID:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88"/> </categoryBag> <identifierBag> <keyedReference keyName="DUNS" keyValue="00-111-1111" tModelKey="UUID:8609C81E-EE1F-4D5A-B202-3EB13AD01823"/> </identifierBag> </businessEntity> </businessDetail> Notice that in its response, the UDDI Operator has assigned a unique identifier to the entity and filled out the businessKey, operator, and authorizedName attributes for the businessEntity element. It also assigned a discoveryURL address for the business in the Operator's domain space. This URL returns an XML document containing the businessEntity structure for SkatesTown. This example showed how a business would register its entry for the first time. Having been assigned a businessKey, it can now use the businessKey to update its information, such as adding a new contact for sales when a VP of Sales is hired, (assuming the company has obtained an authentication token). The example message is as follows: <save_business generic="1.0" xmlns="urn:uddi-org:api"> <authInfo>87CD1C7F-2D23-4324-A927-82B557134DF8</authInfo> <businessEntity businessKey="uuid:D7B8D630-59E7-11D5-9675-95373BEF0080"> <name>SkatesTown</name> <description xml:lang="en">Provides the best skate products in the world </description> <contacts> <contact useType="Technical Information"> <description xml:lang="en">CTO for technical information</description> <personName>Dean Carroll</personName> <phone useType="Main Office">1.212.555.0001</phone> <email useType="CTO"> dean.carroll@SkatesTown.com</email> <email useType="General Information"> info@SkatesTown.com</email> <address useType="Main Office" sortCode="10001"> <addressLine>2001 Skate Services Ln</addressLine> <addressLine>New York, NY 10001</addressLine> <addressLine>USA</addressLine> </address> </contact> <contact useType="Sales Information"> <description xml:lang="en">VP Sales</description> <personName>Sandy Smith</personName> <phone useType="Main Office">1.212.555.0001</phone> <phone useType="Mobile">1.212.555.8888</phone> <email useType="VP Sales"> sandy.smith@SkatesTown.com</email> <email useType="Sales Information"> sales@SkatesTown.com</email> <address useType="Main Office" sortCode="10001"> <addressLine>2001 Skate Services Ln</addressLine> <addressLine>New York, NY 10001</addressLine> <addressLine>USA</addressLine> </address> </contact> </contacts> <categoryBag> <keyedReference keyName="Sporting and Athletic Goods Manufacturing" keyValue="33992" tModelKey="UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2"/> <keyedReference keyName="New York" keyValue="US-NY" tModelKey="UUID:4E49A8D6-D5A2-4FC2-93A0-0411D8D19E88"/> </categoryBag> <identifierBag> <keyedReference keyName="DUNS" keyValue="00-111-1111" tModelKey="UUID:8609C81E-EE1F-4D5A-B202-3EB13AD01823"/> </identifierBag> </businessEntity> </save_business> Publishing Service Information to a UDDI RegistrySkatesTown next decides to publish its product catalog online as a service, and to publish another service that will enable its customers to check the status of their orders. This last service follows the SEMC specification V1.5 in the required documents and process. UDDI service information consists of two main typeslogical (abstract) reusable service description and specific (concrete) implementation detailsfor the different bindings for the same logical service. In the case of the order status service, for instance, the abstract service description for order status has already been specified by SEMC and will be used by SkatesTown through a reference to its tModel. Furthermore, SkatesTown decides to offer two interfaces for this service: one Web (browser) based and another SOAP based. Both Web-based and SOAP-based services are pre-defined logical service descriptions. However, they require two different concrete implementations, and their binding details are different (for example, specifying different URLs for sending the requests). The next sections will go through the details of defining and registering an online catalog service with one binding (Web-based), and an order status service with two bindings (Web and SOAP-based). To publish service information, SkatesTown first needs to construct a businessService structure. This structure can then be published in one of two ways: by including it in the initial businessEntity structure and publishing it through the initial save_business message, or by sending it independently in a save_service message. This is analogous to the mechanisms used to publish businessEntity information with the save_business message. Let's look in more detail at the businessService structure. The businessService StructureThe businessService structure is the root element for describing a logical business service, such as a stock quote service, or a securities buying service (see Figure 7.18). Different implementation details and bindings for the same logical service, if offered, are grouped under the same businessService element, through the bindingTemplates element. Obviously, one or more businessService elements can be contained in a businessServices element. Figure 7.18. The businessService structure.businessService has the following attributes:
businessService has the following elements:
Let's see how SkatesTown can register its Web-based service to offer its catalog to customers. We'll begin composing the businessService entry for this service: <businessService businessKey="uuid:55BB30D8-565A-4EF9-BA2E-83118AED644D" serviceKey=""> <name>Online Catalog</name> <description>This is the SkatesTown online retail catalog. You can use it to buy equipment from us</description> <bindingTemplates> ... </bindingTemplates> <categoryBag> <keyedReference keyName="Sporting and Athletic Goods Manufacturing" keyValue="33992" tModelKey="UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2"/> </categoryBag> </businessService> The next step involves specifying what the bindings will be for that service. Let's look more closely at the bindingTemplate structure. The bindingTemplate StructureIn a certain sense, the bindingTemplate structure is the end goal of UDDI. Other structures allow you to get information about businesses, their descriptions, contact information, categorization and taxonomy information, and what kind of services they offer. After a decision is made on using a particular service from a particular provider, however, the bindingTemplate subtree holds the necessary technical information for the service to actually be invoked. The same logical service can have more than one binding (such as a SOAP-based HTTP binding, an HTTP browser-based binding, and an e-mail SMTP binding). Each of these bindings is described in its own bindingTemplate structure. This is generally a combination of access point information and tModel references and their specific parameters (see Figure 7.19). Figure 7.19. The bindingTemplate structure.bindingTemplate has the following attributes:
bindingTemplate has the following elements:
Let us now continue with the previous example of defining the Web-based catalog service for SkatesTown. The only relevant information is the access point, which is a URL to be used in a Web browser. Its URLType is http: <bindingTemplates> <bindingTemplate bindingKey="" serviceKey="" <description xml:lang="en">This is a web based (http) online catalog </description> <accessPoint URLType="http"> http://www.skatestown.com/services/catalog</accessPoint> <tModelInstanceDetails> ... </tModelInstanceDetails> </bindingTemplate> </bindingTemplates> The only thing left to specify is the tModelInstanceDetail structure. Let's examine that in more detail. The tModelInstanceDetail StructureThe tModelInstanceDetail structure is a container for tModelInstanceInfo structures (see Figure 7.20) and is where the final invocation details of the service are defined. As we've already discussed, each registered business service can have one or more bindings, each of which usually refers to one or more tModels. For example, when SkatesTown registers a service that conforms to the SEMC IeBS 1.2 specification, it might decide to provide the service using two bindings, one SOAP/HTTP-based and another e-mail/SMTP-based. In this case, both bindings will have at least two tModelInstanceInfo structures, one of which will reference the SEMC tModel. The SOAP service will also reference the SOAP specification tModel in a separate tModelInstanceInfo structure, whereas the SMTP service will reference the SMTP specification tModel. This effectively provides several benefits: For example, the service will re-use existing abstractions for the specifications while allowing other businesses to locate it based on its technical fingerprint of using both SEMC and SOAP. Figure 7.20. The tModelInstanceInfo structure.The tModelInstanceInfo structure has one important required attribute, tModelKey. This is the UUID reference to the tModel associated with this structure. Its presence indicates that the binding for the containing business service implements, conforms to, or is somehow associated with this tModel. In our example, this would be a reference to the IeBS tModel or the SOAP or SMTP tModels. In addition, it has two optional elements: a repeating description element and the InstanceDetails element. The InstanceDetails element is a container that is used when parameters specific to the tModel being referenced need to be set. An example of this could be a specific port number that is left unspecified in the tModel but that needs to be set at invocation time. There are two mechanisms to set parameters through the instanceParms element. In the first mechanism, the parameter values could be specified inside the element. In this case, it is suggested that these be a namespace-qualified XML string (from outside the UDDI namespaces). In the other mechanism, a URL to the location of the parameters is supplied. In the simple case of the SkatesTown online catalog, all we need to supply is the tModel reference to the uddi-org:http tModel (68DE9E80-AD09-469D-8A37-088422BFBC36), which is for HTTP-or browser-based services. The following code finishes the bindingTemplates definition for SkatesTown: <bindingTemplates> <bindingTemplate bindingKey="" serviceKey="" <description xml:lang="en">This is a web based (http) online catalog </description> <accessPoint URLType="http"> http://www.skatestown.com/services/catalog</accessPoint> <tModelInstanceDetails> <tModelInstanceInfo tModelKey="UUID:68DE9E80-AD09-469D-8A37-088422BFBC36D"> <description xml:lang="en">HTTP Address</description> </tModelInstanceInfo> </tModelInstanceDetails> </bindingTemplate> </bindingTemplates> The save_service OperationSimilar to publishing a business entity structure with the save_business message, a business service can be published along with its binding templates using the save_service message. In this instance, we need to construct a save_service SOAP message containing a save_service structure in the body element of the SOAP envelope, and the businessService structure contained within (see Figure 7.21). Figure 7.21. The save_service message structure.save_service has this message signature: <save_service generic="1.0" xmlns="urn:uddi-org:api"> <authInfo/> <businessService/> [<businessService/>...] </save_service> Putting It Together: save_service ExampleWe will now register the simple online catalog service for SkatesTown using the save_service message. Notice that we supply the businessKey for SkatesTown but leave the serviceKey and bindingKey attributes empty to indicate these are new entries. Again, we have omitted the required step of getting an authentication token. Here is the save_service message for the SkatesTown online catalog (example: business). <save_service generic="1.0"> <authInfo>5BA16322-B5ED-D300-8F2F-420DA3A212D2</authInfo> <businessService serviceKey="" businessKey="55BB30D8-565A-4EF9-BA2E-83118AED644D"> <name>Online Catalog</name> <description>This is the SkatesTown online retail catalog. You can use it to buy equipment from us</description> <bindingTemplates> <bindingTemplate bindingKey=""> <description>This is a web based (http) online catalog</description> <accessPoint URLType="http"> http://www.skatestown.com/services/catalog</accessPoint> <tModelInstanceDetails> <tModelInstanceInfo tModelKey="UUID:68DE9E80-AD09-469D-8A37-088422BFBC36D"> <description>HTTP Address</description> </tModelInstanceInfo> </tModelInstanceDetails> </bindingTemplate> </bindingTemplates> <categoryBag> <keyedReference keyName="Sporting and Athletic Goods Manufacturing" keyValue="33992" tModelKey="UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2"/> </categoryBag> </businessService> </save_service> The registry returns a businessService structure with the serviceKey and bindingKey assigned to the new service and binding, respectively. Next, we will construct and register a service to allow customers to check the status of their orders, as defined by the SEMC IeBS Order Management specification. This service will have two bindings, one browser-based, and another SOAP-based. First, we will register the new service with just the browser-based binding. Here is the SkatesTown checkOrderStatus save_service message: <save_service generic="1.0"> <authInfo>5BA16322-B5ED-D300-8F2F-420DA3A212D2</authInfo> <businessService serviceKey="" businessKey="55BB30D8-565A-4EF9-BA2E-83118AED644D"> <name>Check Order Status</name> <description>Check your order status online. You can use a browser or SOAP messages</description> <bindingTemplates> <bindingTemplate bindingKey="" serviceKey=""> <description>This is a web based (http) order status service </description> <accessPoint URLType="http"> http://www.skatestown.com/services/orderStatus</accessPoint> <tModelInstanceDetails> <tModelInstanceInfo tModelKey="UUID:68DE9E80-AD09-469D-8A37-088422BFBC36D"> <description>HTTP Address</description> </tModelInstanceInfo> </tModelInstanceDetails> </bindingTemplate> </bindingTemplates> <categoryBag> <keyedReference keyName="Sporting and Athletic Goods Manufacturing" keyValue="33992" tModelKey="UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2"/> <keyedReference keyName="SEMC: IeBS V1.2" keyValue="OM1.5" tModelKey="6E986185-3937-442F-8916-209DA01DF837"/> </categoryBag> </businessService> </save_service> The UDDI registry returns a businessService structure business with the appropriate newly assigned serviceKey and bindingKey: <businessService serviceKey="4C379407-3E1E-DC97-B1C7-F68597DA4ABB" businessKey="55BB30D8-565A-4EF9-BA2E-83118AED644D"> <name>Check Order Status</name> <description>Check your order status online. You can use a browser or SOAP messages</description> <bindingTemplates> <bindingTemplate bindingKey="C2BC244D-B4DD-A779-8CD8-45753760D055" serviceKey="4C379407-3E1E-DC97-B1C7-F68597DA4ABB"> ... </bindingTemplate> </bindingTemplates> <categoryBag> ... </categoryBag> </businessService> The next step illustrates the need for a separate save_binding message. It involves registering a new binding to an existing service, in this case a new SOAP binding to the Check Order Status service. Publishing a Binding Using the save_binding OperationThe save_binding message can be used to add a new binding to an existing service by passing business a non-blank serviceKey, or to update an existing binding by passing a non-blank bindingKey. It can also be used to move an existing binding from one service to another by passing non-blank serviceKeys and bindingKeys. Being part of the authenticated Publishing API, it requires an authInfo element, and it takes one or more bindingTemplate elements as the new bindings to be added to existing services (see Figure 7.22): <save_binding generic="1.0" xmlns="urn:uddi-org:api"> <authInfo/> <bindingTemplate/> [<bindingTemplate/>...] </save_binding> Figure 7.22. The save_binding message structure.In the next step of the example, SBC has convinced SkatesTown to implement a programmatic method for customers to check their order status through a SOAP interface. This is a new binding to the existing Check Order Status service, and can be added to the existing businessService entry with the save_binding message. By passing the serviceKey, this message indicates to the registry that this binding should be contained within the existing Check Order Status businessService for SkatesTown. The tModel for the SEMC Order Management specification can be used as a reference to the necessary data formats, parameters, authentication, and all other invocation details for customers who want to use this service. Here is the SkatesTown SOAP Check Order Status save_binding message: <save_binding generic="1.0"> <authInfo>2E6BAE12-04E3-DBC2-90DB-A96E21406F79</authInfo> <bindingTemplate bindingKey="" serviceKey="4C379407-3E1E-DC97-B1C7-F68597DA4ABB"> <description>This is a SOAP based order status service</description> <accessPoint URLType="https"> https://www.skatestown.com:7000/SEMC/getOrderStatus </accessPoint> <tModelInstanceDetails> <tModelInstanceInfo tModelKey="UUID:68DE9E80-AD09-469D-8A37-088422BFBC36D"> <description>SOAP Order Status service</description> </tModelInstanceInfo> <tModelInstanceInfo tModelKey="UUID:6E986185-3937-442F-8916-209DA01DF837"> <description>SEMC Order Management V1.5</description> </tModelInstanceInfo> </tModelInstanceDetails> </bindingTemplate> </save_binding> The Delete OperationsThe API provides four delete operations, one for each of the core data structures. The delete operations are fairly straightforward. They all require an authentication token for the authInfo element and are passed the keys to the structures to be deleted. The only exception to the pattern has to do with deleting a tModel: It is important to note that if a registered owner uses the delete_tModel operation to delete a tModel, the tModel will not actually be removed from the registry, but will only be marked as hidden. It would still be available to the registered user but will not be returned by any find operation. The registered owner can reinstate the tModel by using the save_tModel call and passing the original tModel key. delete_tModel has this message signature: <delete_tModel generic="1.0" xmlns="urn:uddi-org:api"> <authInfo/> <tModelKey/> [ <tModelKey/> ...] </delete_tModel> delete_business has this message signature: <delete_business generic="1.0" xmlns="urn:uddi-org:api"> <authInfo/> <businessKey/> [ <businessKey/> ...] </delete_ business> delete_service has this message signature: <delete_service generic="1.0" xmlns="urn:uddi-org:api"> <authInfo/> <serviceKey/> [ <serviceKey/> ...] </delete_service> delete_binding has this message signature: <delete_binding generic="1.0" xmlns="urn:uddi-org:api"> <authInfo/> <bindingKey/> [ <bindingKey/> ...] </delete_binding> What would happen if SkatesTown were to attempt to delete an entry that it does not control? Let's try to send the following message: <delete_tModel generic="1.0"> <authInfo>D2BD49A6-1A1F-B8C9-8F4B-CDCE210AE072</authInfo> <tModelKey>UUID:68DE9E80-AD09-469D-8A37-088422BFBC36</tModelKey> </delete_tModel> This message attempts to delete the uddi-org:http tModel, one of the core UDDI tModels used to categorize HTTP-based Web services. Because SkatesTown does not own or control that tModel, this is obviously a bad thing to do. The next section explores some of the details of error handling in UDDI. Error Handling in the UDDI APIAs you'd expect, the UDDI API only specifies application-level error handling, leaving the SOAP errors to be handled by the SOAP messaging infrastructure. The main container structure for UDDI application level errors is the dispositionReport structure, which is returned within a SOAP Fault response message (see Figure 7.23). Figure 7.23. The dispositionReport structure.If SkatesTown tried to delete a core UDDI, as we started doing in the previous section, or any tModel that it does not control, the following message would be returned: <Fault> <faultcode>Client</faultcode> <faultstring>Client Error</faultstring> <detail> <dispositionReport generic="1.0" operator="UDDIOperator" xmlns="urn:uddi-org:api"> <result errno="10130"> <errInfo errCode="E_operatorMismatch">E_operatorMismatch (10130) Cannot change data that was mastered at another Operator site. tModel=UUID:68DE9E80-AD09-469D-8A37-088422BFBC36 </errInfo> </result> </dispositionReport> </detail> </Fault> The UDDI API V1 specification lists 19 different error codes, listed in the specification available at the UDDI site. It is the calling application's responsibility to intercept and interpret these codes. Finding Information in a UDDI RegistryAs we saw in the section "The UDDI Usage Model," in addition to the Publication API, the UDDI specification provides for an Inquiry API. The Inquiry API has two types of operations that are associated with the core UDDI data types: find operations and get_Details operations. The find operations, in general, are used in what is considered browsing or searching mode, and their purpose is similar to database search operations that can return several hits based on a set of search criteria. All find operations can take an optional maxRows attribute whose value is used to instruct the UDDI Operator to limit the number of results returned. All find operations can also include an optional findQualifiers element as a container for findQualifier elements that can be used to modify the search behavior. The current specification lists six qualifiers, with self-evident names: exactNameMatch, caseSensitiveMatch, sortByNameAsc, sortByNameDesc, sortByDateAsc, and sortByDateDesc. The following sections will give some examples of search qualifiers, but the complete description of the qualifiers and their rules of precedence can be found in the UDDI Programmer's API 1.0 document available from the UDDI site. find operations, except for the find_binding operation, return List structures. List structures contain Info elements, which can contain a set of references if the search is successful, or are empty otherwise. We will explore the results in more detail in the next sections. The find_business OperationIn a typical scenario, you might be looking for a business entry, if you know its name, in order to get information about the services they provide, or you might be looking for a business based on a combination of products or services you need and a geographic location, or you might be looking for a business that conforms to a certain industry standard set of tModels. The find_business operation allows you to find business entities that match a set of search criteria (see Figure 7.24): <find_business generic="1.0" [ maxRows="nn" ] xmlns="urn:uddi-org:api"> [<findQualifiers/>] <name/> | <identifierBag/> | <categoryBag/> | <tModelBag/> | <discoveryURLs> </find_business> Figure 7.24. The find_business message structure.In addition to the findQualifiers element, the find_business structure might contain only one of the following elements:
The find_business operation returns a businessList structure (see Figure 7.25) that contains a set of businessInfo elements if the search is successful. Otherwise, it is empty. If the Operator site deems the number of hits too large, the businessList set is truncated and the truncated attribute is set to true. Note that the businessInfo structure also contains the serviceInfos element, which will be covered in the next section. Figure 7.25. The businessList structure.The following example shows one of the most basic searches in UDDI. We are searching for the latest (sortByDateDesc) two (maxRows=2) businesses that registered, and whose name starts with the letter S. Note that the businessInfo elements contain serviceInfos elements (we'll ignore them for now; they will be covered in the next section): <find_business generic="1.0" maxRows="2" xmlns="urn:uddi-org:api"> <findQualifiers> <findQualifier>sortByDateDesc</findQualifier> </findQualifiers> <name>S</name> </find_business> <businessList generic="1.0" operator="UDDIOperator" truncated="false" xmlns="urn:uddi-org:api"> <businessInfos> <businessInfo businessKey="0B345610-57A4-11D5-A554-AB7D0DF538B6"> <name>SEMC</name> <description xml:lang="en">Sports Equipment Manufacturing Consortium </description> <serviceInfos> ... </serviceInfos> </businessInfo> <businessInfo businessKey="D7B8D630-59E7-11D5-9675-95373BEF0080"> <name>SkatesTown</name> <description xml:lang="en">Provides the best skate products in the world</description> <serviceInfos> ... <serviceInfos> </businessInfo> </businessInfos> </businessList> Another search method is to query for businesses that belong to a certain category, using the categoryBag parameter. In the next example, potential SkatesTown customers are looking for the latest business to register under code 33992 in the NAICS taxonomy (Sporting and Athletic Goods Manufacturing). This is done by passing the keyValue (33992) and the NAICS tModel as namespace (uuid:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2). Here is an example find_business message using a categoryBag: <find_business generic="1.0" maxRows="1" xmlns="urn:uddi-org:api"> <findQualifiers> <findQualifier>sortByDateDesc</findQualifier> </findQualifiers> <categoryBag> <keyedReference keyName="Sporting and Athletic Goods Manufacturing" keyValue="33992" tModelKey="uuid:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2"/> </categoryBag> </find_business> <businessList generic="1.0" operator="UDDIOperator" truncated="false" xmlns="urn:uddi-org:api"> <businessInfos> <businessInfo businessKey="D7B8D630-59E7-11D5-9675-95373BEF0080"> <name>SkatesTown</name> <description xml:lang="en">Provides the best skate products in the world</description> <serviceInfos> ... <serviceInfos> </businessInfo> </businessInfos> </businessList> In this last example, a potential SkatesTown customer has been given SkatesTown's D-U-N-S number, and is searching for the company's UDDI entry by supplying that value in a keyedReference, with the D-U-N-S tModel key as namespace. Here is a find_business message using identifierBag: <find_business generic="1.0" maxRows="2" xmlns="urn:uddi-org:api"> <identifierBag> <keyedReference keyName="" keyValue="00-111-1111" tModelKey="UUID:8609C81E-EE1F-4D5A-B202-3EB13AD01823"/> </identifierBag> </find_business> <businessList generic="1.0" operator="UDDIOperator" truncated="false" xmlns="urn:uddi-org:api"> <businessInfos> <businessInfo businessKey="D7B8D630-59E7-11D5-9675-95373BEF0080"> <name>SkatesTown</name> <description xml:lang="en">Provides the best skate products in the world</description> <serviceInfos> ... <serviceInfos> </businessInfo> </businessInfos> </businessList> The find_service OperationThe find_service operation is somewhat different in spirit from the find_business operation. It assumes that you have already found a business and have its businessKey either through the find_business operation or by outside means. Having found a potential business partner, you might be looking for any services they offer within a certain category of products and services using one of the standard taxonomies, or you might be looking for services that conform to a set of industry tModels. Given a businessKey value as an attribute, this operation will retrieve all the services provided by that business that meet the given search criteria. The find_service parameters passed in the contained elements are similar in intent to the ones found in the find_business call (see Figure 7.26): <find_service businessKey="uuid_key" generic="1.0" [ maxRows="nn" ] xmlns="urn:uddi-org:api"> [<findQualifiers/>] <name/> | <categoryBag/> | <tModelBag/> </find_service> Figure 7.26. The find_service message structure.This operation will return a serviceList structure (see Figure 7.27) that contains a set of serviceInfo elements if the search is successful. Otherwise, it is empty. If the Operator site deems the number of hits too large, the serviceList set is truncated and the truncated attribute is set to true. Figure 7.27. The serviceList structure.As a potential customer, we now have the businessKey for SkatesTown (obtained through any one of the example find_business messages we saw in the previous section). We are next looking to see if they offer a service to check order status online, according to the SEMC specification. To perform a strict name query (querying for a service with a known name), a simple call would be: <find_service businessKey="D7B8D630-59E7-11D5-9675-95373BEF0080" generic="1.0" xmlns="urn:uddi-org:api"> <name>Check Order Status</name> </find_service> <serviceList generic="1.0" operator="UDDIOperator" truncated="false" xmlns="urn:uddi-org:api"> <serviceInfos> <serviceInfo businessKey="D7B8D630-59E7-11D5-9675-95373BEF0080" serviceKey="BFEF1360-5A1F-11D5-8DC6-B0C1144E197E"> <name>Check Order Status</name> </serviceInfo> </serviceInfos> </serviceList> The next listing shows the message to send if we were looking for SkatesTown services that conform to the SEMC Order Management V1.5 (in this case, it turns out, there is just one, the Check Order Status service): <find_service businessKey="D7B8D630-59E7-11D5-9675-95373BEF0080" generic="1.0" xmlns="urn:uddi-org:api"> <categoryBag> <keyedReference keyName="SEMC: IeBS V1.2" keyValue="OM1.5" tModelKey="6E986185-3937-442F-8916-209DA01DF837"/> </categoryBag> </find_business> <serviceList generic="1.0" operator="UDDIOperator" truncated="false" xmlns="urn:uddi-org:api"> <serviceInfos> <serviceInfo businessKey="D7B8D630-59E7-11D5-9675-95373BEF0080" serviceKey="BFEF1360-5A1F-11D5-8DC6-B0C1144E197E"> <name>Check Order Status</name> </serviceInfo> </serviceInfos> </serviceList> The find_binding OperationUsually the last step in the browsing activity, the find_binding operation, is used to find binding templates within a business service (see Figure 7.28). The root service key, presumably found with a previous find_service call, is passed as an attribute. The tModelBag element, as in the other find calls, is a container for one or more tModelKey elements, and is used to pass a set of tModel references to be matched by the binding templates. Here is the find_binding message structure: <find_binding serviceKey="uuid_key" generic="1.0" [ maxRows="nn" ] xmlns="urn:uddi-org:api"> [<findQualifiers/>] <tModelBag/> </find_binding> Figure 7.28. The find_binding message structure.The find_binding operation returns a bindingDetail structure (see Figure 7.29) that contains a set of bindingTemplate elements if the search is successful. Otherwise, it is empty. This operation is slightly different in spirit from the other find operations in that its end result is a set of detailed information about the bindings, and not just references to the bindings. In other words, it returns a Detail structure and not a List structure. Another important consideration is that, because of the effect of the hostingRedirector element, the operation might return bindings that are not part of the business service that was passed as a parameter. This will happen if there are bindings that match the tModelBag references and that are not owned by the root business entity, because they are part of services being redirected to another hosting organization (maybe an aggregator or an ASP) using the hostingRedirector element. Figure 7.29. The bindingDetail structure.By drilling down, we have now found the service we are looking for (Check Order Status). We next need to know if SkatesTown has an HTTP binding for that service. We know the HTTP service tModel key because it's one of the core tModels. We can supply that tModel key as parameter to the find_binding message: <find_binding generic="1.0" serviceKey="BFEF1360-5A1F-11D5-8DC6-B0C1144E197E" maxRows="2" xmlns="urn:uddi-org:api">> <tModelBag> <tModelKey>uuid:68DE9E80-AD09-469D-8A37-088422BFBC36</tModelKey> </tModelBag> </find_binding> This will return the (at most two) bindingDetail structure containing the bindingTemplate for the Web-based binding of the Check Order Status service. The find_tModel OperationThe find_tModel operation is almost identical in all aspects to the find_business and find_service operations, both in terms of the parameters that it takes and the type of results it returns (see Figure 7.30): <find_tModel generic="1.0" [ maxRows="nn" ] xmlns="urn:uddi-org:api"> [<findQualifiers/>] <name/> | <identifierBag/> | <categoryBag/> </find_tModel> Figure 7.30. The find_tModel message structure.The operation returns a tModelList structure (see Figure 7.31), which follows the same principle as the other List structures. Consequently, the tModelInfos structure contains a set of tModelInfo elements if the search is successful, or is empty otherwise. If the Operator site deems the number of hits too large, the serviceList set is truncated and the truncated attribute is set to true. Figure 7.31. The tModelList structure.Getting Business and Service Details from a UDDI RegistryAs opposed to the find operations, the get_Details operations are generally used, as their name suggests, to retrieve detail information about specific entities, usually ones found after using the find operations. They are passed one or more unique reference keys as parameters and return the details of the corresponding entries in a Detail structure. The get_businessDetail OperationThe get_businessDetail operation takes a set of businessKey references and returns a businessDetail structure, which contains a set of businessEntity elements that correspond to the passed keys: <get_businessDetail generic="1.0" xmlns="urn:uddi-org:api"> <businessKey/> [ <businessKey/> ...] </get_businessDetail> For example, the following message <get_businessDetail generic="1.0" xmlns="urn:uddi-org:api"> <businessKey>D7B8D630-59E7-11D5-9675-95373BEF0080</businessKey> </get_businessDetail> returns the same businessDetail message shown previously. The get_serviceDetail OperationThe get_serviceDetail operation takes a set of serviceKey references and returns a serviceDetail structure, which contains a set of businessService elements that correspond to the passed keys: <get_serviceDetail generic="1.0" xmlns="urn:uddi-org:api"> <serviceKey/> [ <serviceKey/> ...] </get_serviceDetail> The get_bindingDetail OperationThe get_bindingDetail operation takes a set of bindingKey references and returns the same bindingDetail structure returned by the find_binding operation described earlier, which contains a set of bindingTemplate elements that correspond to the passed keys: <get_bindingDetail generic="1.0" xmlns="urn:uddi-org:api"> <bindingKey/> [ <bindingKey/> ...] </get_bindingDetail> The get_tModelDetail OperationThe get_tModelDetail operation takes a set of tModelKey references and returns a tModelDetail structure, which contains a set of tModel elements that correspond to the passed keys: <get_tModelDetail generic="1.0" xmlns="urn:uddi-org:api"> <tModelKey/> [ <tModelKey/> ...] </get_tModelDetail> Summarizing UDDI Version 1.0In this section, we have explored in detail the UDDI information model and the UDDI API from the perspective of SkatesTown and some of its customers or potential customers. So far, an implicit assumption has been that all operations have been performed on a public UDDI registry. This obviously need not be the case. The next section explores the concept and applications of private UDDI registries. |
![]() ![]() |