User-defined value set support in the UDDI registry

 

The UDDI V3 registry provides the structure and modeling tools to find information within a registry effectively. Users can define multiple value sets and add custom value sets. In UDDI V2, this functionality was called custom taxonomy support.

Data is worthless if it is lost within a mass of other data and cannot be distinguished or discovered. If a client of UDDI cannot effectively find information within a registry, the purpose of UDDI is considerably compromised. Providing the structure and modeling tools to address this problem is at the heart of UDDI's design. The verification of data within UDDI is core to its mission of description, discovery and integration. It achieves this by several means.

It allows users to define multiple value sets that can be used in UDDI. In such a way, multiple classification schemes can be overlaid on a single UDDI entity. This capability allows organizations to extend the set of such systems UDDI registries support. One is not tied to a single system, but can rather employ several different classification systems simultaneously.

While default value sets are shipped with the product, the UDDI V3 registry provides tools enabling 'custom' value sets to be added, potentially enabling UDDI entities to be more specifically categorized when published and further enhancing the capability of client to find specific data. These value sets can be either checked or unchecked, and this is indicated via a keyedReference in the categoryBag of the tModel that represents a value set (a "categorization tModel"). These keyedReferences have the tModel key for uddi-org:types and are added to the categoryBag to further describe the behavior of the categorization tModel, as follows:

checked

Marking a tModel with this classification asserts that it represents a categorization, identifier, or namespace tModel that has a validation service to check that category values are present in a specified value set.

unchecked

Marking a tModel with this classification asserts that it represents a categorization, identifier, or namespace tModel that does not have a validation service.

The procedure defined below describes how to add additional user-defined value sets, and display their allowed values in the UDDI user console value set tree display. Rational Application Developer has a Web Services Explorer user interface that also allows addition and display of custom checked value sets. The publisher of a value set categorization tModel may specify a 'display name' for use in UDDI user console implementations.

 

Procedure for adding a user defined value set

To add a user defined value set to the UDDI registry, perform the following tasks:

1. Publish a categorization tModel

2. Load the user defined value set data

3. Set the value set to supported status using the Administrative console. To do this be a user in an administrative role. This means that user defined value sets cannot be added to the UDDI registry without administrator permission.

The checked value set will only be referenced when the above tasks are complete. Value set data must be provided for validating checked value sets.

Value set data may also be used by user consoles for unchecked value sets, but it is not a requirement and is usually only used for presentation of deprecated value sets, such as unspc-org:unspc and back-level compatibility.

If the value set is checked, any publish requests that have a categoryBag containing keyedReferences with the new categorization tModel will be validated. If there is value set data corresponding to the categorization tModel in the registry database, only valid values will be accepted. If there is no value set data in the database all values will be rejected, and the publish request will fail. If the categorization tModel is unchecked, all values will be allowed, regardless of whether there is a corresponding value set present in the UDDI registry database. The value set tModel is not available for use until the administrator enables support for it using the console, or the JMX interface.

 

Suggested approach

To introduce a new value set:

1. Publish the categorization tModel with a keyedReference of type 'uddi-org:categorization:types' with a key value of categorization, a keyedReference of type 'uddi-org:categorization:types' with a Key Name of 'Checked value set' and a Key Value of 'checked', or a Key Name of 'Unchecked value set' and a Key Value of 'unchecked' and a keyedReference of type 'uddi-org:categorization:general_keywords' supplying the value set display name (as described below).

2. Load user defined value set data into the UDDI registry database using the UDDIUserDefinedValueSet utility (described below).

3. Use the administrative Console to set the status of the value set to supported (as described in Value set settings). This can also be achieved directly using the JMX interface.

The SOAP and EJB interfaces will be able to make use of categorization tModels as soon as they are published. However, the UDDI registry user console will require a restart of the UDDI application because it currently gathers its list of categorizations for use in the value set tree display when the application starts.

 

Publishing a Checked Categorization tModel

This section describes how to publish a checked categorization tModel with the 'Checked value set' Key Name for use by a user defined value set. Publish a tModel to the UDDI registry with a categoryBag containing keyedReferences as follows:

Note	tModelKey	KeyName	KeyValue
1	uddi:uddi-org:categorization:types In the UDDI registry user interface this tModelKey can be chosen by selecting the category type of UDDI Types	categorization	categorization
2	uddi:uddi-org:categorization:types In the UDDI registry user interface this tModelKey can be chosen by selecting the category type of UDDI Types	Checked value set	checked
3	uddi:uddi-org:categorization:general_keywords In the UDDI registry user interface this tModelKey can be chosen by selecting the category type of categorization:general_keywords	urn:x-ibm:uddi:customTaxonomy:displayName	<User Defined Value Set displayName>

1. Indicates this tModel is a categorization tModel (required).

2. Indicates use of the tModel will be checked against a list of valid data (required). (Omitting this keyedReference, or explicitly specifying a value of 'unchecked' will indicate this categorization is unchecked).

3. Indicates special use of the general keywords value set, with a proprietary uniform resource name (URN) as the keyName value, defines a name for the user-defined value set that is intended for use in user console implementations where the full tModel name might be too long. The value can be 1-255 characters (inclusive) long.

The displayName is intended to provide a way to label a value set such that, when the UDDI user console displays it in a value set tree or in a pull-down list of available value sets, the meaning is clear to the user without being restricted to 8 characters and without needing to be the same as the published tModelName, which could be as long as 255 characters. An example is shown below:

The urn:x-ibm:customTaxonomy:displayName should be unique if only to avoid confusion when displayed in user interfaces but this is not validated. To publish a new categorization tModel using SOAP, the message would be:

<save_tModel generic="3.0" xmlns="urn:uddi-org:api_v3">    
  <authInfo></authInfo>>
  <tModel tModelKey="">
    <name>Natural Foods tModel</name>
    <categoryBag>
      <keyedReference tModelKey="uddi:uddi.org:categorization:types" keyName="categorization"  
                      keyValue="categorization"/>
      <keyedReference tModelKey="uddi:uddi.org:categorization:types" keyName="Checked value set" 
                      keyValue="checked"/>
      <keyedReference tModelKey="uddi:uddi.org:categorization:general_keywords" 
                      keyName="urn:x-ibm:uddi:customTaxonomy:displayName" keyValue="Natural Foods"/>
    </categoryBag>
  </tModel>  
</save_tModel>

to specify an unchecked categorization substitute the key name 'Checked value set' with 'Unchecked value set' and 'checked' Key Value with 'unchecked' or, more simply, omit the keyedReference completely.

 

Loading User Defined Value Set Data

User Defined Value Set Data File Format Value set data is identified by a unique code value, an optional description and a parent code that specifies its relationship with other code values. Value set data must adhere to this format:

Column name	Maximum length	Description of use
Code	765	Unique value within the value set used for validation
description	765	Typically used by UDDI user consoles and optionally in the keyedReference as the keyName value
parentcode	765	Indicates which existing code is the logical parent of this one, and is used in tree displays

Typically columns are delimited in the value set data file by '#' characters as in this example:

00#Food#00
10#Fruit#00
101#Apples#10
102#Oranges#10
103#Pears#10
1031#Anjou#103
1032#Conference#103
1033#Bosc#103
104#Pomegranates#10
20#Vegetables#00
201#Carrots#20
202#Potatoes#20
203#Peas#20
204#Sprouts#20

In the example, 'Food' is the description for the root node with child nodes of 'Fruit' and 'Vegetables' (both of these have parentcode values the same as the code value for 'Food'). The value set data in the example file could then be rendered in a tree like this:

Food
  Fruit
    Apples
    Oranges
    Pears
      Anjou
      Conference
      Bosc
    Pomegranates
  Vegetables
    Carrots
    Potatoes
    Peas
    Sprouts

The file must be saved in UTF-8 format.

Custom Taxonomy files used in UDDI V2 are also supported by the utility.

UDDIUserDefinedValueSet

A utility is provided to load value set data into the UDDI registry, assign existing value set data to another tModel and unload existing value set data. This utility uses the UDDI registry's JMX interface and therefore requires a number of connection parameters.

Usage: UDDIUserDefinedValueSet[.sh|.bat] '{'function'}' [options]

function:
-load <path> <key>         Load value set data from specified file
-newKey <oldKey> <newKey>  Move value set to a new tModel
-unload <key>              Unload existing value set
 options:
-properties <path>         Specify location of configuration file
-host <host name>          Application Server or Deployment Manager host
-port <port>               SOAP Lister port number -node <node name>          Node running a UDDI server
-server <server name>      Server with UDDI deployed
-columnDelimiter <delim>   Character delimiter to denote field end
-stringDelimiter <delim>   Character delimiter to denote strings


Connector security parameters

-userName <name>
-password <password>
-trustStore <path>
-trustStorePassword <password>
-keyStore <name>
-keyStorePassword <password>

Ensure that the command window from which the UDDIUserDefinedValueSet is run is using a suitable codepage and font for displaying the characters contained in the value set name. Use of an incorrect codepage/font may result in unclear messages on a successful load, and create difficulty using the -unload and -newKey options.

The UDDIUserDefinedValueSet script is located in the app_server_root/bin directory.

If no connection parameters are supplied a connection is sought on the local host using the default SOAP port number of the deployment manager, or, if there is no deployment manager running, the default Application Server SOAP port number.

Command arguments are case insensitive.

Usage examples

Load a value set data for a tModel on the local UDDI registry using the percent sign as a column marker in the valuesetdata.txt file.

UDDIUserDefinedValueSet.xxx -load valuesetdata.txt uddi:a708b8a7-35b5-451c-aafc-718ae071fcfe -columnDelimi ter %

where .xxx is .bat for Windows operating systems or .sh for UNIX and Linux platforms.

Move value set data from one checked tModel to another on a UDDI registry in a network deployment configuration.

UDDIUserDefinedValueSet.xxx –newKey uddi:a708b8a7-35b5-451c-aafc-718ae071fcfe uddi:b819c9b8-46c6-562d-bb
0d-829bf1820d0f –host depmanagerhost.ibm.com –port 8879 –node uddinode –server uddiserver -override

where .xxx is .bat for Windows operating systems or .sh for UNIX and Linux platforms.

Unload a value set from a tModel from a server with security turned on supplying the connection and security parameters in myproperties.properties file, but supplying the server and password arguments on the command line (which augment or override those contained in the properties file).

UDDIUserDefinedValueSet.xxx –unload uddi:b819c9b8-46c6-562d-bb0d-829bf1820d0f –server uddiserver 
–properties myproperties.properties –password myrealpassword 

where .xxx is .bat for Windows operating systems or .sh for UNIX and Linux platforms.

The configuration file, if specified by the optional -properties parameter, determines a number of optional parameters. These parameters can be specified on the command line and, if so, override the values in the properties file. These parameters are largely JMX connection parameters and security parameters.

The string.delimiter is typically used where a description value contains the same character as the column delimiter character. For example, if the column.delimiter was set to ',' (a comma), and there was a value set description value of 'Fruits, citrus', you could include this in the value set data file by setting the string.delimiter to " (double quote) and enclosing the description in quotes: 'Fruits, citrus'. Note that the quote character is escaped with a backslash ('\') to indicate the literal character is to be used. If an attempt is made to load a value set to a tModel that has existing value set data, a warning message is given. To override this error provide the -override argument. This argument is also required if moving value set data to a new tModel using -newKey where the tModel is checked, and also unloaded value set data for a checked tModel.

Command line arguments and example data	Property and example data	Comments
-columnDelimiter #	column.delimiter=#	The column delimiter that is used in value set data files
-stringDelimiter \"	string.delimiter=\"	The field delimiter (this value must be different to the column.delimiter value)
-host ibm.com	host=ibm.com	The host name of the system that is running the deployment manager or appserver
-port 8880	port=8880	The SOAP port number of the deployment manager or appserver
-node ibmNode	node=ibmNode	The name of the node that is running the server with the UDDI registry
-server server1	server=server1	The server that is running the UDDI registry
-userName ibmuser	security.username=ibmuser	The user name. This value is required if WebSphere Application Server security is turned on
-password mypassword	security.password=mypassword	The password
-trustStore /TrustStoreLocation	security.truststore=/TrustStoreLocation	The truststore file location
-keyStore ibmkeystore	security.keystore=ibmkeystore	The keystore name
-trustStorepassword trustpass	security.truststore.password=trustpass	The truststore password
-keyStorePassword keypass	security.keystore.password=keypass	The keystore password

 

Set the value set to supported

Use the administrative console to set the value set to supported by:

• Click UDDI Nodes > <node> and Value Sets (under Additional Properties on the right of the screen)

• Select the Value Set (by checking the box next to it)

• Click Enable Support above the list of Value Sets

 

Validation and Error Handling

The UDDI registry user console performs validation while a save tModel request is being built, that is, before the publish occurs. For example, if the user tries to add two customTaxonomy:displayName keyedReferences the following message is displayed:

Advice: Only one 'urn:x-ibm:uddi:customTaxonomy:displayName' key name is allowed for the 'Other' taxonomy.

If a keyedReference containing a keyName value that starts with 'urn:x-ibm:uddi:customTaxonomy:' is followed by anything other than 'displayName', the following message is displayed:

Advice: Only key name values of 'urn:x-ibm:uddi:customTaxonomy:displayName' are supported.

For requests where the save_tModel message may have multiple tModels, if any one of the tModels is a categorization tModel and it fails validation, the request fails with a UDDIInvalidValueException (plus additional information explaining the likely cause), and none of the tModels is published. For example:

E_invalidValue (20200) A value that was passed in a keyValue attribute did not pass validation.  
This applies to checked categorizations, identifiers and other validated code lists. The error  text will clearly indicate the key and value combination that failed validation. Invalid 'custo mTaxonomy:dbKey' keyValue [naics] in keyedReference. KeyValue already in use by tModelKey[UUID:
C0B9FE13-179F-413D-8A5B-5004DB8E5BB2]

---

 

Related tasks

Use the UDDI registry

 

Related Reference

UDDI registry management interfaces

 

Reference topic