UDDI (Universal Description, Discovery, and Integration) plays the pivotal role of matchmaking between service provider and service requester. Sophisticated publish and inquiry capabilities allow providers to describe their offerings, and seekers to locate them. The quality and depth of a service description is critical to how easily that service can be found by interested parties. Likewise, result sets from find operations can be unmanageable if search criteria are imprecise.

Services can be described in UDDI in terms of contact information (White Pages), classification (Yellow Pages), and invocation details (Green Pages). Support for taxonomic classification of all entities in UDDI helps users find and register Web services in a standard way. Default taxonomies such as NAICS, UNSPSC, and ISO 3166 in UDDI v2-compliant registries enable classifications in broad terms such as industry type and geographic location. These, however, may not be sufficiently precise for describing a given Web service - and waiting for the underlying standardized taxonomies to change may not be an option. Also, organizations may need to classify entities in accordance with their own schemes to meet internal standards, e.g., corporate standards. These issues can be addressed through the use of user-defined taxonomies.

The IBM WebSphere UDDI Registry in WebSphere 5.0.2 and WebSphere Studio 5.1 (Application and Site Developer editions) and above provides support for user-defined taxonomies. Users can create their own taxonomies and make them available for use with the registry. This article will show you how to create and test a user-defined taxonomy in the Unit Test environment in IBM WebSphere Studio 5.1.

User-Defined UDDI Taxonomies in the WebSphere UDDI Registry
UDDI registries use taxonomies to classify entities in a consistent manner. In order to do this, taxonomies are typically "checked," that is, the category value assigned to a particular UDDI entity must be one of a set of valid values. The WebSphere UDDI Registry has several "internal" taxonomies, and with the tools presented in this article you can easily add your own.

A taxonomy data file contains the valid values, along with additional data that identifies the taxonomy the value belongs to, a description of the value, and the parent category of the value. The "#" character is the default delimiter.

The first few lines of the example data file show the required format:

procclas#10.00#Create Customer & Business Value#10.00
procclas#10.05#Understand and Choose Value#10.00
procclas#10.10#Create and Extract Value#10.00
procclas#10.15#Communicate and Deliver Value#10.00
procclas#15.00#Manage Relationships#15.00

Each row represents a separate category in the taxonomy. The first value in the row, "procclas", is the taxonomy name. This can be 1-8 characters, and is the same for every row of data in the taxonomy.

The second value, up to 32 characters in length, represents the unique code within the taxonomy that is used to check that keyedReference key values are valid.

To describe a taxonomy value, the third field takes up to 128 characters of text. UDDI does not require the description for publishing entities, but it is a useful hint about the meaning of the key value. For example, "15.00" doesn't mean much, but with "Manage Relationships" it's clearer.

The last value in the row is the parent code. Like the code value, it must be 1-8 characters in length. The parent code allows you to give the taxonomy hierarchical structure using categories and subcategories. For example, consider a food types taxonomy in which one of the values is:

foodtype#fruit#Fruits#food

You could define "citrus" as being a subcategory of "fruit", and "lemon" as a subcategory of "citrus" by defining two new values as:

foodtype#citrus#Citrus Fruits#fruit
foodtype#lemon#Lemon#citrus

The parent code value of "fruit" is a reference to the previous code value of "fruit". WebSphere Studio Web Services Explorer and the user console in the WebSphere UDDI Registry both use the parent code value to help render a tree view of taxonomies.

The taxonomy data file should be in UTF-8 encoding, without the "byte order mark" header. The next section explains how to create a taxonomy data file.

Create a User-Defined UDDI Taxonomy in WebSphere Studio
Let's create a taxonomy to describe a Web service that acts as a customer address book for a fictitious corporation. The corporation already has a taxonomy data file, process.tax (available for download from www.sys-con.com/websphere/sourcec.cfm), that incorporates its corporate standards.

Looking at process.tax, one category that this Web service might fit into is Manage Customer Relationships, with a key value of 15.05. However, it would be more precise to have a subcategory under this one to refer to the action of managing customer addresses. Let's add a new subcategory called Manage Customer Addresses, with a key value of 15.05.05. Before you begin, ensure that TCP/IP port 9080 or 7080 is free if you are using WebSphere Studio Application Developer or Site Developer editions, respectively. To create the taxonomy, perform the following steps:

1. Launch WebSphere Studio with a new workspace and note its location (<workspace directory>).
2. Select the main menu item Window > Preferences to open the Preferences dialog.
3. In the left pane of the Preferences dialog, expand the Workbench node and select the Editors node. In the resulting right pane, select the radio button labeled "Other", select UTF-8 in the adjacent dropdown menu, and then press OK.
4. From the main menu, select File > New > Project... to open the New Project wizard.
5. In the New Project wizard, select Simple in the left pane followed by Project in the right and press Next.
6. Enter "taxonomy" for the project name and press Finish.
7. Select the main menu item File > New > Other... to bring up the list of New wizards.
8. In the list of New wizards, select "Simple" followed by "File" in the left and right tree views, respectively, and press Next.
9. Select "taxonomy" in the tree view, enter "process1.tax" for the file name, and press Finish.
10. Open the process.tax file in a text editor and paste its contents to process1.tax in the right edit pane. Locate the line

procclas#15.05#Manage Customer Relationships#15.00

and add the new line

procclas#15.05.05#Manage Customer Addresses#15.05

after it. Save the file by pressing CTRL+S. The end result should look something like Figure 1.

Now Manage Customer Addresses is a subcategory of the more generic Manage Customer Relationships parent. The taxonomy data file is saved under <workspace directory>/taxonomy. You will now use the Unit Test UDDI Wizard to deploy a UDDI registry with this taxonomy:

1. Select main menu item File > New > Other... to open the list of New wizards. In the resulting dialog, select "Web Services" in the left pane, followed by Unit Test UDDI in the right, and then press Next to proceed to the Unit Test UDDI Registry Configuration page.
2. Select the "Deploy the Unit Test UDDI Registry" radio button and "Private UDDI Registry For WAS v5 with Cloudscape" in the Private UDDI Registry type dropdown and press Next to proceed to the Unit Test UDDI Registry with Cloudscape Configuration page.
3. Press the Add... button adjacent to the User Defined Categories table to bring up the Add a New Category dialog.
4. Enter "process" for the Name. For the File field, use the Browse... button to navigate to the directory <workspace>/taxonomy and pick the process1.tax file. Ensure that the "Checked" checkbox is selected. The final dialog and wizard page should look similar to Figure 2.
    

5. Press OK to dismiss the dialog and add the taxonomy to the User-defined categories table. Back in the wizard, press Finish.

The wizard will configure and run an instance of the WebSphere UDDI Registry in the WebSphere Test Environment and then launch the Web Services Explorer. The Web Services Explorer will show the details of the registry, including the user-defined taxonomy, in its "User Defined Categories" section. We will test the user-defined taxonomy using the Web Services Explorer in the next section.

Test the User-Defined UDDI Taxonomy in WebSphere Studio
WebSphere Studio provides a tool called the Web Services Explorer for working with UDDI registries. That provides functions for UDDI publication and discovery. You can use the tool to publish the customer address book Web service with the new Manage Customer Addresses subcategory from the process taxonomy and later find it using this subcategory. Before you can begin, you need to deploy the Web service.

1. Select main menu item File > New > Other... to bring up the list of New wizards and then select Web in the left pane, followed by Dynamic Web Project in the right pane, and then press Next to proceed to the Dynamic Web Project page.
2. Enter "AddressWP" in the project name field and then press Finish. You do not need to switch to the Web perspective when prompted to do so.
3. In the Navigator view, Expand AddressWP, select the JavaSource folder, and then select main menu item File > Import... to bring up the list of Import wizards. Select "File system" as the input source and then press Next to open the File System Import wizard.
4. Use the Browse... button to navigate to and then select the directory <WebSphere Studio installdirectory>/wstools/eclipse/plugins/com.ibm.etools.webservice_5.1.0/samples/JavaBean_example. Back in the wizard, expand the "JavaBean_example" node in the left pane, select the checkbox beside the "webservice" node and press Finish to import the customer address book Web service's JavaBean code and dismiss the wizard.
5. Back in the Navigator view, expand AddressWP's JavaSource folder, followed by its webservice and addressbook children. Right-click on AddressBook.java and select Web Services > Deploy as Web Service to launch the Deploy as Web Service wizard.
6. In the wizard, press the Finish button to deploy the customer address book Web service.

The Web service is now deployed and ready to be published to a UDDI registry. As required by UDDI, you must first publish a business entity to own this service.

1. Scroll down the Web Services Explorer's Actions pane to the Publish link near the bottom. Click on the Publish link to load the Publish Form into the Actions pane.
2. Enter any user ID and password. Note: You must use the same ID and password to modify or unpublish previously published items.
3. Enter "My Business" in the Name field and press Go to publish the business. The Status pane will display a message reflecting the outcome of the operation. It should state that the operation was successful and the Actions pane should load the details of the business.
4. Scroll down to the bottom of the Actions pane and click on the Publish Service link to load the Publish Service form.
5. Select Advanced for the Publication format.
6. Click on the Browse... link adjacent to the WSDL URL field to open the WSDL Browser. In the browser, select AddressWP as the Web Project and ensure that the WSDL URL dropdown points to http://localhost: <port>/AddressWP/wsdl/webservice/addressbook/AddressBook.wsdl and then press Go to transfer the WSDL URL selection to the form and dismiss the dialog.
7. Click the Add link in the Names section of the form to add a new name for the UDDI service. The name will appear in the Names section inside a table. There are two columns: Language and Name. Enter "Customer AddressBook" in the Name field.
8. Scroll to the bottom of the form and click on the Add link beside the Categories label to add a category to this service. The category added to the Categories section of the form consists of a Type (taxonomy), Key name, and Key value. For a known taxonomy, there is a Browse... action to display a user-friendly tree view from which a particular category or subcategory can be chosen.
9. In the newly added category, change the type to "process" and click on the Browse... link to open the Categories browser for the process taxonomy.
10. The Categories browser displays categories and subcategories sorted according to their key value. Expand the [15.00] Manage Relationships category, followed by the [15.05] Manage Customer Relationships subcategory, and then select the subcategory: [15.05.05] Manage Customer Addresses. Figure 3 shows the Web Services Explorer and the Categories browser with the subcategory underlined. After selecting the subcategory, the Categories browser should close and the key name and key value fields of the new category should match those of the selection. You can add multiple categories and subcategories.
     

11. Click Go to publish the service.

The Status pane should provide feedback on the result. If successful, you will see Manage Customer Addresses in the Categories table of the Service's details in the Actions pane. It should look similar to the Actions pane in Figure 4.

To complete verification of the user-defined taxonomy, perform a UDDI inquiry, including a category in the search criteria:

1. Select the registry node immediately underneath UDDI Main in the Navigator pane of the Web Services Explorer. The Publish form should load.
2. Select the third icon from the right of the Actions pane toolbar (a flashlight) to load the Find form.
3. The Find form will appear in the Actions pane. In the "Search for" dropdown, select Services and then choose the "Advanced" radio button for the Type of search.
4. Scroll down the form until you see the Categories heading. Click the "Add" link to add a category for the search. The new category appears as a new row in the table inside the Categories section.
5. For the new category, change the type to "process" and click on the Browse... link in the Actions pane. Follow Step 10 of the publish procedure to select the Manage Customer Addresses subcategory and then press Go at the bottom of the form.

When the search operation completes, the Status pane will inform you that one service was discovered. This should be the Customer AddressBook service. Figure 4 shows the expected results.

Conclusion
Defining your own taxonomies gives you a better vocabulary to describe any UDDI entity and offers users a richer set of search criteria. In Part 1 of this series we set out to show how you can create taxonomies for UDDI registries and try them out in the WebSphere Studio test environment. In Part 2 we'll demonstrate how to deploy the same taxonomy in the IBM WebSphere UDDI Registry, and offer more useful tips on publishing and using taxonomies.

Resources

Universal Description, Discovery, and Integration: www.uddi.org

North American Industry Classification System: www.census.gov/epcd/www/naics.html

United Nations Standard Products and Services Code: www.unspsc.org

ISO 3166 Maintenance agency: www.iso.ch/iso/en/prods-services/iso3166ma/index.html

• Source Code (zip file)