Web Services

Digg This!

UDDI allows providers to publish information about their services in a common registry. A key part of this process is to describe services in an accurate and consistent way so potential users can easily find them using UDDI inquiry functions. Classifying services with user-defined taxonomies is an effective way to improve search results.

Part 1 of this series, "Create and Test a User-Defined Taxonomy in WebSphere Studio" [WJ, Vol. 3, issue 1], described how you can define and test taxonomies for UDDI in IBM WebSphere Studio's Unit Test environment. This article explains how to deploy and use user-defined taxonomies with WebSphere UDDI Registry in WebSphere Application Server Network Deployment Edition (version 5.0.2 and above). To try the examples you must have IBM WebSphere UDDI Registry deployed and started.

Deploy the User-Defined Taxonomy to a WebSphere UDDI Registry
Deploying a new taxonomy to a WebSphere UDDI Registry takes two easy steps: load the data in the UDDI registry database, and publish a categorization tModel. Before loading the taxonomy data, let's look at a row from the file created in Part 1 (actually the row you added in Part 1) to see how its data fits in with the examples that follow.

procclas#15.05.05#Manage Customer
Addresses#15.05

With a delimiter of "#", "procclas" is the taxonomy name, "15.05.05" is the value, "Manage Customer Addresses" is the description for that value, and 15.05 is the parent code for the 15.05.05 value.

To load taxonomy data into WebSphere UDDI Registry you will use the UDDITaxonomyTools.jar command-line tool. It's worth taking the time to configure the tool correctly for your UDDI Registry installation. Typically, you need only do this once. We'll assume an IBM DB2 database setup, with the driver classes located at c:/Program Files/SQLLIB/java12/db2java.zip. Adjust the instructions accordingly for your environment.

1. Locate the UDDITaxonomyTools.jar file. You will find it in the <installed location of deployment manager>/UDDIReg/scripts directory.
2. Copy UDDITaxonomyTools.jar to a convenient location. For this example, we'll assume the JAR file is stored in c:\tools and the taxonomy data files are in c:\taxonomies.
3. Create a configuration properties file, also in the c:\taxonomies directory, and call it "userTaxonomy.properties".
4. Edit the configuration file and complete the details as follows, changing them where necessary to suit your environment (using forward slashes in file paths):

classpath="c:/Program Files/SQL
LIB/java12/db2java.zip;c:/tools/
UDDITaxonomyTools.jar"
database.driver.className=COM.ibm
.db2.jdbc.app.DB2Driver
database.url=jdbc:db2:UDDI20
database.userName=db2admin
database.password=db2admin
column.delimiter=#
string.delimiter=\"

This example is for a DB2 version 7 setup. If you are using DB2 version 8, the classpath will be similar to:

classpath="c:/Program Files/IBM/
SQLLIB/java/db2java.zip;C:/
tools/UDDITaxonomyTools.jar"

For Cloudscape, the classpath would be something like (assuming the WebSphere lib directory is under c:/websphere/appserver):

classpath="c:/websphere/appserver/
lib/db2j.jar;c:/tools/UDDITaxonomyTools.jar"

Take care to get the database driver JAR correct in the properties file, as the Cloudscape db2j.jar is easily confused as belonging to DB2! The database.driver.className for Cloudscape would be:

database.driver.className=com.ibm.db2j.jdbc.DB2jDriver

Also note that for Cloudscape, the database.url value will be "jdbc:db2j:<directory of UDDI database>", and that database.userName and database.password are ignored.

Remember to enclose the classpath property in double quotes if the path includes space characters. If using the tool on a Linux platform, replace the semi-colons with colons. The classpath must include the UDDITaxonomy Tools.jar filepath.

Each property name should be self-explanatory. The last one, string.delimiter, allows you to include values that contain the column delimiter. For example, if you had a category value of "01" with a description of "service standard #1", you would need to surround the description value in the data file with double quotes:

mytax#01#"service standard #1"#00

See the information center for WebSphere Application Server Network Deployment for more detail about how to configure and use user-defined taxonomies in WebSphere UDDI Registry. (Search for "Custom Taxonomy Support".)

Now that the configuration file is set up, load the taxonomy data file:

1. At the command line, change the directory to the location of the JAR file (c:\tools).
2. Enter the following (all on the same line):

   java -jar UDDITaxonomyTools.jar
   -load c:/taxonomies/process1.tax
   -properties c:/taxonomies/userTaxonomy.properties

3. The tool reports:

   Loaded 51 lines of data file for taxonomy name procclas.

The -properties argument allows you to have several configurations that you can switch between easily, say one for Cloudscape and one for a DB2 database. You can choose a default configuration by renaming or copying the properties file to "customTaxonomy.properties" and storing it in the same directory as the UDDITaxonomyTools.jar file. You then don't need to specify the properties argument, so the earlier example would become simply:

java -jar UDDITaxonomyTools.jar
-load c:/taxonomies/process1.tax

If you were to try entering the above line after you've already loaded the taxonomy data, the tool will report that a taxonomy with the name "procclas" already exists.

The taxonomy name in the example is "procclas" and that's what's been inserted into the UDDI registry database. What if we don't like that name or realize it's a mistake? Use the tool's rename function to rename the taxonomy as "process1":

1. Enter the following (assuming you created a default properties file called "customTaxonomy.properties" in the c:\tools directory as described earlier):

   java -jar UDDITaxonomyTools.jar
   -rename procclas process1

2. The tool reports the number of rows updated:

   Renamed 51 taxonomy name values from procclas to process1.

An important point to make is that naics, geo, unspsc, unspsc7, other, and udditype are reserved taxonomy names for the default internal taxonomies used by the WebSphere UDDI Registry. If you attempt to perform load, rename, or unload functions using these taxonomy names, the taxonomy tool issues a warning to say that the internal taxonomy exists, and offers an additional "override" argument to allow you to proceed with the operation. While it is possible to force the change in the database, we strongly recommend you leave the reserved taxonomy data as it is, to prevent possible data corruption with invalid values and to avoid breaking standards.

The taxonomy data is now in the registry database. The next step is to publish a categorization tModel that corresponds to the set of valid values in your new taxonomy. There are several ways to publish entities in WebSphere UDDI Registry and we'll show you two: using a SOAP message containing a UDDI publish request, and using the browser-based UDDI user console.

A categorization tModel must have a name (strictly, this should be a URI), ideally a description, and a categoryBag containing at least the keyedReference to the uddi-org:types categorization tModel (tModel key UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4) with a key value of "categorization". Typically, category values used to describe a UDDI entity are validated against the set of valid values in the taxonomy. To indicate this in a categorization tModel, another keyedReference to the uddi-org:types tModel is present in the categoryBag, with a value of "checked".

With this information, you can publish the categorization tModel shown in Listing 1. However, there is one crucial bit of information missing - how does the UDDI registry associate the categorization tModel with the set of valid values that we loaded earlier? In addition, if registry users are using the UDDI user console to choose category values for their inquiry and publish operations, it is helpful to have a succinct, user-friendly name in the taxonomy tree display.

All UDDI registries provide a special taxonomy, uddi-org:general_keywords (with tModel key UUID:A035A07C-F362-44DD-8F95-E2B134BF43B4). It is special in that any keyedReference to it can take any key name/value pair (it's an unchecked taxonomy). See the Resources section for more information about the General Keywords taxonomy. Unlike other keyedReferences, the keyName is meaningful and should be represented as a URN (Uniform Resource Name). The WebSphere UDDI Registry uses this special taxonomy tModel to associate user-defined categorization tModels with taxonomy data loaded by the user, and optionally, to allow taxonomy publishers to specify a short name for use in user interfaces.

The following keyedReference is required to define the association between our new categorization tModel and the taxonomy data we loaded:

<keyedReference tModelKey=
"UUID:A035A07C-F362-44DD-
8F95-E2B134BF43B4"
keyName="urn:x-ibm:uddi:customTaxonomy:key"
keyValue="process1"/>

In this case the keyName value is a URN specific to the IBM WebSphere UDDI Registry, which specifies that the corresponding keyValue value is the user-defined taxonomy key in the taxonomy table of the registry's database, in this case "process1". The tModel key is that of the uddi-org:general_keywords taxonomy.

Similarly, if we want to specify a user-friendly name for user interfaces to exploit (including the user console of WebSphere UDDI Registry, and Web Services Explorer in WebSphere Studio), we also need a keyedReference to the special general keywords tModel, specifying a display name:

<keyedReference tModel
Key="UUID:A035A07C-F362-
44DD-8F95-E2B134BF43B4"
keyName="urn:x-ibm:uddi
:customTaxonomy:display
Name" keyValue="corporate
processes"/>

With these two additional keyedReference entities in our tModel, we can publish the tModel using SOAP, with the message shown in Listing 2.

Figure 1 shows the relationship between the taxonomy data file, the categorization tModel, and its keyedReferences, and how the taxonomy appears in the UDDI user console's taxonomy tree display. Note that the customTaxonomy:key key value has the same restriction as when loading user-defined taxonomy data files - you cannot specify reserved key names for naics, geo, unspsc, unspsc7, other, or udditype. Similarly, if a customTaxonomy:key key value for the taxonomy already exists, attempts to add a duplicate value are rejected.

If you prefer to use the UDDI user console to publish your categorization tModel, perform the following steps (which assume WebSphere security is not active):

1. In a browser window, go to the UDDI user console home page. By default this is http://<hostname>:9080/uddigui.
2. Click the Publish tab, and then choose "Add a technical model" from the dropdown menu.
3. Enter "mycompany:processes:2003.11" in the Name field.
4. In the Descriptions section, enter "This tModel specifies a taxonomy for describing corporate processes." in the Description field, leave English as the selected language, and click the Add button.
5. In the Locator section, click on "Show category tree".
6. A tree of existing taxonomies displays in the left navigation frame. Expand the udditype taxonomy so that the Categorization (taxonomy) value [categorization] is visible (see Figure 2).
    
7. Click on "Categorization (taxonomy) [categorization]". The key name and key value appear in the Locator section. Click on Add to add this key name and key value to the list of categories for this tModel. Adding this value indicates this tModel is a taxonomy tModel.
8. In the taxonomy tree frame, click on "Checked value set [checked]". The key value and key name appear in the tModel's Locator section. Click on Add to add this key name and key value to the tModel's categoryBag. This value indicates this taxonomy is checked.
9. Still in the Locator section, on the New Category line, choose "other" in the pulldown list of taxonomies. "other" is the shorthand name used for the uddi-org:general_keywords taxonomy.
10. For the keyName value, enter "urn:x-ibm:uddi:customTaxonomy:key".
11. For the keyValue value, enter "process1" and click Add to add this keyedReference.
12. On the New Category line, "other" should already be selected in the pulldown list; if it isn't, select it now.
13. For the keyName value, enter "urn:x-ibm:uddi:customTaxonomy:displayName".
14. For the keyValue value, enter "corporate processes" and click Add to add this keyedReference. At this point the Locator section should look like that in Figure 2.
15. Click on "Publish Technical Model".

Now that the categorization tModel is published, the user-defined taxonomy is immediately available for use by SOAP requests. To use the taxonomy in the user console you will need to stop and restart the UDDI application (restart the EAR). This makes the taxonomy appear in the taxonomy tree and pulldown list of taxonomies the next time you use the user console for publish and inquiry operations.

It is important to note that the user-defined taxonomy you've deployed is an internal taxonomy rather than an external taxonomy service. As such, it behaves exactly like any of the default taxonomies, such as NAICS and UNSPSC7, that are supplied with the WebSphere UDDI Registry.

Verify the Deployed Taxonomy
We published a user-defined taxonomy to allow us to better describe and precisely locate UDDI entities. First, we will publish two services with categories from different taxonomies. To publish services, you need to publish businesses to contain them. Using the UDDI user console:

1. If the taxonomy tree is still showing in the left frame, click on Publish in the top frame.
2. From the Publish tab, click on "Add a business".
3. In the Business Name section, enter "business 01" for the new name field, leave the English as the selected language, and click on Add.
4. Click on "Publish Business".
5. Repeat Steps 1 through 3, this time using a name of "business 02".

Add a Service to the First Business

1. From the Publish tab, click on "Show owned entities". The Registered Businesses section will list your two businesses, as shown in Figure 3.
    
2. For business 01, click on Add service to display the Publish Service page.
3. In the Service Name section, enter "address service 01" for the new name field, leave English as the selected language, and click on Add.
4. In the Locator section (you might need to scroll down), click on "Show category tree". A tree of all internal taxonomies will display in the left frame, including the user-defined taxonomy labeled "corporate processes".
5. In the taxonomy tree frame, expand the corporate processes taxonomy so that the nodes for Manage Relationships [15.00], Manage Customer Relationships [15.05], and Manage Customer Addresses [15.05.05] are visible. Resize the left frame if necessary.
6. Click on Manage Relationships [15.00]. This copies the values to the key name and key value fields in the Locator section. Click on Add to add that keyedReference.
7. Repeat Step 6, this time selecting Manage Customer Relationships [15.05].
8. Repeat Step 6 again to add the Manage Customer Addresses [15.05.05] reference to the Locator section of the service.
9. Now expand the "geo" taxonomy in the tree so that Canada [CA] and Ontario [CA-ON] are visible.
10. Follow Step 6 again to add keyName and keyValue values for Canada [CA] and Ontario [CA-ON] to the Locator section. Your Locator section should now look like that shown in Figure 4.
     
11. Click on Publish Service.

To complete the example, create a second service under business 02, with the same references to the user-defined taxonomy, and the service located in England, UK:

1. Click on Publish in the top frame to display the Publish tab.
2. In the Publish tab, click on "Show owned entities". The Registered Businesses section will show your two businesses.
3. For business 02, click Add service to display the Publish Service page.
4. Now repeat Steps 3 through 8 of the previous instructions, this time substituting "address service 02" for "address service 01".
5. Now expand the geo taxonomy in the tree so that United Kingdom [GB] and England [GB-ENG] are visible.
6. Repeat Step 6 (from the previous sequence) to add keyName and keyValue values for United Kingdom [GB] and England [GB-ENG] to the Locator section. For the second service, the Locator section should look like Figure 5.
    
7. Click on Publish Service.

This example shows how the new taxonomy might be used to describe two separate services, both with the Manage Relationships category reference and subcategories. One service is applicable to the Ontario, Canada region, and the other to England, UK. Notice that for the location references, the categoryBag includes both the region and the country values. Similarly, the services specify values in the user-defined taxonomy of "15.00", "15.05", and "15.05.05". This technique helps service seekers who might begin their search looking only at services based in Canada, for example, before they narrow their criteria. Having the detailed value and one or more levels of parent values gives inquirers a better chance of locating a particular service.

An interesting aspect of user-defined taxonomies in UDDI comes into play when users start seeking entities of specific interest to them. To search for all businessService entities that have category references to "Manage Customer Addresses" (value 15.05.05) from the user-defined taxonomy and are located in Canada or England, UK, perform an inquiry as follows:

1. Click on Find in the top frame to display the Find tab.
2. From the Find tab, click on Find Services. The Find Services page displays.
3. In the Locator section, click on "Show category tree".
4. In the taxonomy tree frame, expand the corporate processes taxonomy so "Manage Customer Addresses [15.05.05]" is visible.
5. Click on "Manage Customer Addresses [15.05.05]" and then on Add in the Locator section to add that reference.
6. Expand the geo taxonomy and use the same technique as in Step 5 to add two category references, one for "Canada [CA]" and one for "England [GB-ENG]". Your Locator section should look like Figure 6.
    
7. In the Search Modifiers section, select the "OR like keys" radio button (see Figure 7).
    
8. Click on Find Services. The results should contain both address services, as shown in Figure 8.
    

The "OR like keys" find qualifier causes category references in the same namespace (same taxonomy) to be OR'ed together rather than AND'ed. If you wanted only services for "Manage Customer Addresses" based in Canada you would leave the search modifier set to the default "AND all keys" and remove the reference to "England".

Conclusion
In this article, we created new category data, loaded it into the IBM WebSphere UDDI Registry, published a corresponding categorization tModel, and demonstrated how to use the taxonomy in publishing and finding UDDI entities. User-defined taxonomy support in the WebSphere UDDI Registry offers additional levels of detail with which to define services, as well as offering users a more effective way to pinpoint the services they want.

Resources

UDDI specifications: www.uddi.org

UDDI tModels - Classification Schemes, Taxonomies, Identifier Systems, and Relationships, Version 2.04: http://uddi.org/taxonomies/UDDI_Taxonomy_tModels.htm

WebSphere Application Server Version 5.1 information center: http://publib.boulder.ibm.com/infocenter/ws51help/index.jsp