UDDI Utility Tools

The UDDI Utility Tools is a suite of functions that we can use to migrate, move, or copy UDDI V2 entities, including child entities and their respective V2 entity keys, into a Version 3 UDDI registry.

The UDDI V3 publish API supports publisher assigned keys (the V2 API did not) and promotion of entities between Version 3 registries can be achieved using normal API functions. UDDI Utility Tools supplied in this release is functionally equivalent to the version supplied in WAS 5.1. However, it is important to know that all UDDI Utility Tools functions in this release are performed using the UDDI V2 API. We can export from V2 and 3 registries (supplying only the Version 2 representation of the UDDI Entity key) and import into the Version 3 registry, using V2 API types. Entities from a V 3 registry are exported as V2 entities and, as such, elements such as digital signatures will not be present. See section Saving V3 entities with a supplied key for an example on how to use the V 3 API to assign our own keys to V3 entities. Other uses of the tool include:

• Search and select entities from a source UDDI registry by specifying Version 2 keys or search criteria

• Publishing canonical tModels in a UDDI registry, including child entities

• Persist UDDI (Version 2) entities in an intermediate XML representation that can be used to customize and copy those entities to multiple target UDDI Registries, by specifying V2 Keys

• Update existing entities in a target UDDI registry, including child entities

• Delete selected entities from a target UDDI registry by specifying Version 2 keys

Use the UDDI Utility Tools by running the UDDIUtilityTools.jar file. This file is located in...

APP_ROOT/UDDIReg/scripts

Alternatively, we can invoke all of the functions of UDDI Utility Tools through the supplied public Java API. There are five main functions in UDDI Utility Tools:

Export

Given an entity type and key, or a list of entity types and keys, UDDI Utility Tools gets the UDDI entities from the specified registry and writes them to the UDDI Entity Definition File. The entity type for each key can be one of business, service, bindingTemplate or tModel. The Entity Definition File contains XML that exactly describes each of the specified entities, according to the UDDI Utility Tools schema (which includes the UDDI V2 schema). The UDDI Entity Definition File separates entities by type, and automatically detects and records tModels referenced by the specified entities. Use the 'referenced tModels' section of the file to ensure a target registry includes any referenced tModels before you try to import new entities to that registry.

Import

Given a list of UDDI entities (which can be supplied using the UDDI Entity Definition File generated by the export function, possibly with additional editing, or programmatically in a container object), the import function detects if the entities already exist in the target registry and, if they do not, creates a minimal entity ("stub") with the specified key. The entities are then published updating the stubs with the supplied data and overwriting, or ignoring, existing entities as specified by the user. Note that the original key is maintained throughout.

Promote

Combines the export and import steps such that the specified entities are extracted (by key) from the source registry and then imported into the target registry in a single logical step. The generation of a UDDI Entity Definition File is optional for this function.

Delete

Deletes the specified entities from the target UDDI registry. The entities to delete are specified as an entity type, or a list of entity types, and keys, in the same way as for the export function.

Find Matching Entities

Takes as input search criteria in the form of UDDI Inquiry API objects for each of the various entity types. The set of entities that match the search criteria are used to generate a list of entity keys, and this in turn can be used as input to the export, promote and delete functions.

This function is available only through the programmatic API.

The relationship between the functions, their input and output, and the source and target UDDI Registries is shown in this conceptual overview diagram:

Set up the configuration file

Configuration data for UDDI Utility Tools resides in a configuration properties file, which describes the runtime environment, UDDI and database locations and access information, logging information, security configuration, entity definition file location, and other flags to control whether referenced entities are to be imported and/or overwritten. UDDI Utility Tools is distributed with a sample configuration properties file (UDDIUtilityTools.properties) and this is searched for by default in the current directory if no properties path is specified. By default, this file is located in...

APP_ROOT/UDDIReg/scripts

Modify the file, according to the following list, and specify this modified file when running the utility tools.

• Set the classpath, which must include the current directory (.) and the UDDIUtilityTools.jar itself, plus all the dependent jars, which are listed in the Prerequisites section later on in this topic. The classpath must include the database driver jar (for example db2java.zip).

  If we are configuring a JSSE provider, add to the classpath the .jar file that contains the provider. The configuration of a JSSE provider is optional and is performed by setting the jsse.provider property. The default value is com.ibm.jsse.IBMJSSEProvider. To specify the FIPS JSSE provider set the value of the jsse.provider property to com.ibm.fips.jsse.IBMJSSEFIPSProvider.

• Set other properties, which are commented in the sample UDDIUtilityTools.properties file as shown below.

• Change localhost to the name of the server.

• Change the port number 9082 to the internal HTTP port.

(Windows)

Use forward slashes in paths. Back slashes can be interpreted as escape sequences such as tab spaces. For example,

C:\temp\definitions\entities01.xml

becomes

C:  emp\definitions\entities01.xml

 

Example

##############################################
# Runtime environment                        #
# (if invoking using java -jar...)           #
# "X Y" required around paths with spaces.   #
# Replace WAS_HOME with the WAS home path.  #
# Replace DB2_HOME with the locations of DB2 #
#                                            #
# db2java.zip is for DB2 - replace this with #
# appropriate database driver file.          #
############################################## classpath=.;WAS_HOME/UDDIReg/scripts/UDDIUtilityTools.jar;WAS_HOME/plugins/com.ibm.ws.runtime.jar; WAS_HOME/plugins/com.ibm.uddi.jar;WAS_HOME/lib/j2ee.jar;"DB2_HOME/SQLLIB/java/db2java.zip"

##############################################
# SOAP entry points for source UDDI          #
##############################################  fromInquiryURL=http://localhost:9082/uddisoap/inquiryapi fromGetURL=http://localhost:9082/uddisoap/get

##############################################
# SOAP entry points for target UDDI          #
##############################################  toInquiryURL=http://localhost:9082/uddisoap/inquiryapi toPublishURL=http://localhost:9082/uddisoap/publishapi

##############################################
# UDDI Registry user information             #
#                                            #
# 
 this must match the user information #
# that was used to publish the entities on   #
# the target UDDI registry.                  #
##############################################  userID=UNAUTHENTICATED password=NONE

##############################################
# Configuration for destination UDDI DB      #
##############################################  dbDriver=COM.ibm.db2.jdbc.app.DB2Driver dbUrl=jdbc:db2:uddi30 dbUser=db2admin dbPasswd=db2admin

##############################################
# Security provider configuration            #
##############################################
# Indicates whether security is required on the target registry secure.connection=true

# The location of the truststore if security is required trustStore.fileName=TrustFile.jks

# The password for the trust store trustStore.password=WebAS

# The JSSE Provider class name jsse.provider=com.ibm.jsse.IBMJSSEProvider

##############################################
# Trace and message logging configuration    #
############################################## 
# detail level of message output (all functions) verbose=true

# detail level of trace output.
# 1: severe
# 2: normal
# 3: detail traceLevel=3

# path to message log file (relative or absolute) messageLogFileName=logs/messages.log

# path to trace log file (relative or absolute) traceLogFileName=logs/trace.log

############################################## 
# Miscellaneous Options                      #
############################################## 
# indicates if existing entities are overwritten (import/promote)
# 
 tModels in referencedTModels section are never overwritten, 
#       regardless of this setting. To overwrite tModels, they must 
#       be present in the tModels section. overwrite=false   

# indicates if referenced entities will be imported (import/promote) importReferencedEntities=true

# location of entity definition file, used for (export/import) UddiEntityDefinitionFile=definitions/entities01.xml

# namespace prefix to use in definition file (export) namespacePrefix=promote

 

Prerequisites

(Windows) To run the UDDI Utility Tools use the IBM Development Kit for Java code that is supplied with WAS. This Development Kit is located in APP_ROOT/java/bin. Verify the following .jar files are available to the UDDI Utility Tools. The locations of the .jar files must be specified in the classpath property in the UDDI Utility Tools properties file:

UDDIUtilityTools.jar

This is the tools JAR itself and is located in APP_ROOT/UDDIReg/scripts.

com.ibm.uddi.jar

This file contains the UDDI4J classes and is located in APP_ROOT/plugins.

j2ee.jar

This file contains some required Java platform for enterprise apps classes, and is located in APP_ROOT/lib.

com.ibm.ws.runtime.jar

This is the Apache SOAP implementation and is located in APP_ROOT/plugins.

DbDriver

This is the driver needed to allow the UDDIUtilityTool to connect to the target database. See the table below for the values specify for the chosen database:

Table 1. DbDriver values for databases

	DB2	Apache Derby	Oracle
DBDriverLocation for classpath on distributed, Windows and IBM i platforms	DB2_HOME/db2java.zip	APP_ROOT/derby/lib/derbyclient.jar	ORACLE_HOME/jdbc/lib/ojdbc6.jar
Driver on distributed, Windows and IBM i platforms	COM.ibm.db2.jdbc.app.DB2Driver, or com.ibm.db2.jcc.DB2Driver if we are using a remote DB2 database (we can also set up a local alias to the remote database using the DB2 client)	com.ibm.db2.jcc.DB2Driver	oracle.jdbc.OracleDriver
URL on distributed, Windows and IBM i platforms	jdbc:db2: //host:database_name	jdbc:db2j:net: //host:1527/database_name (see note below)	jdbc:oracle:thin:@host:1521: database_name

where

• APP_ROOT is the directory location of WAS.

• DB2_HOME is the directory location of DB2, for example c:\Program Files\SQLLIB\java12\

• ORACLE_HOME is the directory location of Oracle, for example c:\oracle\ora92\

• database_name is the name of the database. For Apache Derby, make sure that database_name includes the path to the database, for example $WP_PROFILE/databases/com.ibm.uddi/UDDI30

Notes:

• If using Apache Derby, make the database network enabled so that it can handle multiple connections. For further details, refer to the section about managing the Derby Network Server in the Derby Server and Administration Guide.

• If using DB2, add DB2_HOME/sqllib/lib to the LD_LIBRARY_PATH and LIBPATH environment variables.

The Security provider configuration section in the properties file described previously shows the location of the default DummyClientTrustFile.jks file. If using the own truststore, verify the location is placed here.

The UDDI Utility Tools use UDDI V2 SOAP inquiry and publish interfaces. These APIs are protected.

The UDDI Utility Tools also access the UDDI registry database through the database driver, and access to the database is controlled by the database management system.

The UDDI Entity Definition File You generate this file by the export and promote functions, or we can choose to create it (either by hand, or by modifying a version of the file output by UDDI Utility Tools specifying the export function). It is the input to the import function.

The extension to the uddi:tModel type to add a 'deleted' attribute is not currently used in UDDI Utility Tools. The file is validated for well formedness and that it complies with the UDDI Utility Tools schema, shown here.

<?xml version="1.0" encoding="UTF-8" ?>
<xsd:schema id="uddiPromote" attributeFormDefault="unqualified" elementFormDefault="qualified"
 targetNamespace="http://www.ibm.com/
    xmlns/prod/WebSphere/UDDIUtilityTools" 
    xmlns:xsd="http://www.w3.org
                  /2001/XMLSchema" 

    xmlns:uddi="urn:uddi-org:api_v2" 
    xmlns="http://www.ibm.com/
    xmlns/prod/WebSphere/UDDIUtilityTools" 

    xmlns:promote="http://www.ibm.com/
    xmlns/prod/WebSphere/UDDIUtilityTools">

  <xsd:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="xml.xsd" />
  <xsd:import namespace="urn:uddi-org:api_v2" schemaLocation="uddi_v2.xsd" />

  <!-- define a type to represent state of a tModel -->
  <xsd:simpleType name="tModelDeleted">
    <xsd:restriction base="xsd:NMTOKEN">
      <xsd:enumeration value="true" />
      <xsd:enumeration value="false" />
    </xsd:restriction>
  </xsd:simpleType>

  <!-- extend tModel with additional attribute of type tModelDeleted -->
  <!-- This is restricted to values true or false -->
  <xsd:complexType name="tModel">
    <xsd:complexContent>
      <xsd:extension base="uddi:tModel">
        <xsd:attribute name="deleted" type="promote:tModelDeleted" use="optional" />
      </xsd:extension>
    </xsd:complexContent>
  </xsd:complexType>


  <!-- Top level element definitions -->
  <xsd:element name="uddiEntities" type="promote:uddiEntities" />
  <xsd:complexType name="uddiEntities">
    <xsd:sequence>
      <xsd:element ref="promote:tModels" minOccurs="0" maxOccurs="1" />
      <xsd:element ref="promote:businesses" minOccurs="0" maxOccurs="1" />
      <xsd:element ref="promote:services" minOccurs="0" maxOccurs="1" />
      <xsd:element ref="promote:bindings" minOccurs="0" maxOccurs="1" />
      <xsd:element ref="promote:referencedTModels" minOccurs="0" maxOccurs="1" />
    </xsd:sequence>
  </xsd:complexType>

  <xsd:element name="businesses" type="promote:businesses" />
  <xsd:complexType name="businesses">
    <xsd:sequence>
      <xsd:element ref="uddi:businessEntity" minOccurs="0" maxOccurs="unbounded" />
    </xsd:sequence>
  </xsd:complexType>

  <xsd:element name="tModels" type="promote:tModels" />
  <xsd:complexType name="tModels">
    <xsd:sequence>
      <xsd:element ref="uddi:tModel" minOccurs="0" maxOccurs="unbounded" />
    </xsd:sequence>
  </xsd:complexType>

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

  <xsd:element name="bindings" type="promote:bindings" />
  <xsd:complexType name="bindings">
    <xsd:sequence>
      <xsd:element ref="uddi:bindingTemplate" minOccurs="0" maxOccurs="unbounded" />
    </xsd:sequence>
  </xsd:complexType>

  <xsd:element name="referencedTModels" type="promote:referencedTModels" />
  <xsd:complexType name="referencedTModels">
    <xsd:sequence>
      <xsd:element ref="uddi:tModel" minOccurs="0" maxOccurs="unbounded" />
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

UDDI Entity Definition File example for canonical tModels

The example Entity Definition File following shows the five main sections for tModels, businesses, services, bindings and referencedTModels:

UDDI Utility Tools can be used to create new UDDI entities in a target UDDI registry. A typical example of this is to introduce a new canonical tModel, which has a publicly known tModel key.

 

Example

<?xml version="1.0" encoding="UTF-8"?>
<promote:uddiEntities 
    xmlns="urn:uddi-org:api_v2" 
    xmlns:promote="http://www.ibm.com/
    xmlns/prod/WebSphere/
                      UDDIUtilityTools">

  <!-- tModels -->
  <promote:tModels>

    <tModel tModelKey="uuid:ee3966a8-faa5-416e-9772-128554343571" > 
      <name>http://schemas.xmlsoap.org/ws/2002/07/policytmodel</name> 
      <description>WS-PolicyAttachment policy expression</description>
    </tModel> 

    <tModel tModelKey="uuid:ad61de98-4db8-31b2-a299-a2373dc97212" >
      <name>uddi-org:wsdl:address</name>
  <description xml:lang="en"> This tModel is used to specify the URL fact that the address must be obtained from the WSDL deployment  file.
      </description>
      <overviewDoc>
        <overviewURL> http://www.oasis-open.org/committees/uddi-spec/doc/tn/uddi-spec-tc-tn-wsdl-v2.htm#Address 
        </overviewURL>
      </overviewDoc>
    </tModel>

  </promote:tModels>

  <!-- businesses -->
  <promote:businesses>
  </promote:businesses>

  <!-- services -->
  <promote:services>
  </promote:services>

  <!-- bindings -->
  <promote:bindings>
  </promote:bindings>

  <!-- referenced tModels -->
  <promote:referencedTModels>
  </promote:referencedTModels>

</promote:uddiEntities>

 

Starting UDDI Utility Tools at a command prompt

Ensure that we are using the correct level of Java code by setting the PATH statement to include the Java code that is supplied with WAS. For example, from the command line, type:

(Windows)

set PATH=APP_ROOT\java\bin;%PATH%

[AIX] [HP-UX] [Linux] [Solaris]

export PATH=APP_ROOT/java/bin:$PATH

[AIX] [HP-UX] [Linux] [Solaris]

If using DB2 on UNIX and Linux platforms, run the db2profile script before issuing the java command to start UDDI Utility Tools. This script is located within the DB2 instance home directory under sqllib and is invoked by typing:

. /$DB2_HOME/db2profile

In the previous example, notice that the '.' is followed by a single space character.

The DB2 user must have a db2profile at $HOME/sqllib/db2profile.

UDDI Utility Tools can be started using:

java - jar UDDIUtilityTools.jar <function> [options]

using a specified properties file that sets up classpath and other parameters, or it can be called using:

java CommandLineProcessor

where CommandLineProcessor is the class that processes command line arguments for UDDI Utility Tools, sets up configuration and invokes the appropriate function.

Before you run UDDIUtilityTools.jar from the command line, ensure that we have edited the UDDIUtilityTools.properties file. If we have saved this properties file in a different directory from the directory containing the UDDIUtilityTools.jar file, make sure specify the location of the properties file as part of the command line arguments. See the Setting up the configuration file section earlier in this topic for more details.

The usage is as follows:

 

Example

 Usage: java -jar UDDIUtilityTools.jar {function} [options]
 function:
  -promote <entity source>   Promote entities between registries
  -export <entity source>    Extract entities from registry to XML
  -delete <entity source>    Delete entities from registry
  -import                    Create entities from XML to registry
 where <entity source> is one of:
  -tmodel|-business|-service|-binding <key> Specify single entity type and key
  -keysFile | -f <filename>  Specify file containing entity types and keys
 options:
  -properties <filename>     Specify path to configuration file
  -overwrite | -o            Overwrite an entity if it already exists
  -log | -v                  Output verbose messages
  -definitionFile <filename> Specify path to UDDI entity definition file
  -importReferenced          Import entities referenced by source entities
 
The following options override property settings in configuration file:
  -overwrite
  -log
  -definitionFile
  -importReferenced
 Example: java -jar UDDIUtilityTools.jar -promote -keysFile C:/uddikeys.txt

The following examples are UDDI Utility Tools command line examples. The examples use the Windows operating systems file system: Export a single business to the EDF file specified in a properties file in the current directory.

java -jar UDDIUtilityTools.jar -export -business 28B8B928-2B2E-4EC9-A647-1E40651E4752

Export a single business to the EDF file specified in a properties file in the current directory and use a keys file to specify the entities to be exported.

java -jar UDDIUtilityTools.jar -export -keysFile C:/myKeyFiles/keyFile01.txt

Export a single business to the EDF file specified in a properties file in the current directory and use a keys file to specify the entities to be exported. Also, display verbose output on the command line.

java -jar UDDIUtilityTools.jar -export -keysFile C:/myKeyFiles/keyFile02.txt -v

Import the contents of the default EDF specified in a UDDIUtilitiyTools.properties file in the current directory.

java -jar UDDIUtilityTools.jar -import

Import the contents of the default EDF specified in a UDDIUtilitiyTools.properties file in the current directory and import referenced tModels into the target registry.

java -jar UDDIUtilityTools.jar -import -importReferenced

Import the entities from an EDF at the specified location. Note the use of forward slashes even though this is an example on a Windows operating systems file system.

java -jar UDDIUtilityTools.jar -import -definitionFile C:/myEDFs/entities01.xml

Import the entities from the default EDF including referenced tModels. Overwrite specifies that any entities excluding referenced tModels that are found in the target registry are overwritten.

java -jar UDDIUtilityTools.jar -import -overwrite -importReferenced

Promote a single service from a source to a target registry using the properties file at a specified location.

java -jar UDDIUtilityTools.jar -promote -service 67961D67-330F-4F14-8210-E74A58E710F3 
-properties C:/UUT/myUUTProps.properties

Promote a set of entities specified in a keys file.

java -jar UDDIUtilityTools.jar -promote -keysFile C:/myKeyFiles/keyFile03.txt

Promote a set of entities specified in a keys file and overwrite existing entities in the target registry.

java -jar UDDIUtilityTools.jar -promote -keysFile C:/myKeyFiles/keyFile04.txt -overwrite

Promote a set of entities specified in a keys file including referenced tModels.

java -jar UDDIUtilityTools.jar -promote -keysFile C:/myKeyFiles/keyFile05.txt -importReferenced

Promote a set of entities specified in a keys file but also create an EDF containing the promoted entities.

java -jar UDDIUtilityTools.jar -promote -keysFile C:/myKeyFiles/keyFile06.txt 
-definitionFile C:/myEDFs/entities02.xml

Logically delete a single tModel. We cannot physically delete tModels.

java -jar UDDIUtilityTools.jar -delete -tModel UUID:1E2B9D1E-E53D-4D36-9D46-6CCC176C466A

Delete all the entities specified in the keys file. Except for tModels, all other entities are physically deleted from the target registry.

java -jar UDDIUtilityTools.jar -delete -keysFile C:/myKeyFiles/keyFile04.txt

 

A keys file example

The following example shows the keys that are to be exported, promoted, or deleted from the target registry:

#
# Keys of entities to be exported, promoted from source registry or deleted from target registry
#
# 
 keys must be comma separated and on SAME line
# 
 property names are case sensitive. ('tmodels=' will be ignored)
 businesses=97C77097-AC6C-4CA0-A6C4-452F7045C470, 4975E949-581F-4FCA-AD5F-E08280E05F9F services=BB3864BB-1578-4833-8179-14391F14791F bindings= tModels=273F1727-7BFF-4FB5-A1FD-BA5C45BAFD9C

If the importReferenced property is set to true, the list of tModels in the referencedTModels section is imported to the target registry. Minimal entities are created if the referencedTModel is new. If the referencedTModel already exists it is never overwritten, regardless of the overwrite property value. This is so that commonly referenced tModels such as categorization tModels do not keep being updated unnecessarily.

If update a referencedTModel, manually move the referencedTModel definition to the tModels section in the entity definition file and set overwrite to true.

Content of the log files

The following examples show the contents of two of the log files that are produced by running the tool. Some comments have been added in square brackets and in italic to highlight important points in the log file. The first is the messages.log, which shows successful and unsuccessful operations for export, import and delete functions:

[29/07/04 17:39:57:531 BST] CWUDU0002I: ********** Starting UDDI Utility Tools ********** [timestamp and
 eyecatcher indicate when tool is run]
[29/07/04 17:39:57:531 BST] CWUDU0009I: Exporting entities...
[29/07/04 17:39:57:531 BST] CWUDU0015I: Exported 14 entities.
[29/07/04 17:39:57:531 BST] CWUDU0029I: Serializing...
[29/07/04 17:39:57:531 BST] CWUDU0030I: Serialized entities.
[29/07/04 17:39:57:531 BST] CWUDU0016I: Importing entities...
[29/07/04 17:39:57:531 BST] CWUDU0124I: Created tModel minimal entity with tModelKey [uuid:667e2766-4781-
4151-b3a0-809f7180a096].
[29/07/04 17:39:57:531 BST] CWUDU0121I: Created business minimal entity with businessKey [263f5526-8708-4
834-9f5d-8f8c878f5d6e].
[29/07/04 17:39:57:531 BST] CWUDU0122I: Created service minimal entity with serviceKey [0af2a30a-be70-401 f-a027-331a6c332712].
[29/07/04 17:39:57:531 BST] CWUDU0122I: Created service minimal entity with serviceKey [61012761-d02c-4c7
0-ae98-435ffd4398f9].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with bindingKey [f97af9f9
-7cb7-47bd-8b90-b55e4db590df].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with bindingKey [17e4c017
-d273-43ec-af4a-f9b841f94a30].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with bindingKey [9e2c239e
-3b30-40a9-9c25-ce64edce25b9].
[29/07/04 17:39:57:531 BST] CWUDU0121I: Created business minimal entity with businessKey [49bb6949-4b0e-4 e81-88a7-e26bfbe2a7f1].
[29/07/04 17:39:57:531 BST] CWUDU0122I: Created service minimal entity with serviceKey [003d2b00-f6c0-407
1-8b84-f235a2f28445].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with bindingKey [df1019df
-2d2f-4f32-bf18-4f21274f1835].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with bindingKey [b229aeb2
-f2b1-4115-a06f-536753536f10].
[29/07/04 17:39:57:531 BST] CWUDU0122I: Created service minimal entity with serviceKey [84d8e584-2510-409
9-9b2a-6023f1602a0a].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with bindingKey [62a9a762
-7fff-4f7a-8463-af0c79af63ee].
[29/07/04 17:39:57:531 BST] CWUDU0123I: Created binding template minimal entity with bindingKey [e08654e0
-b212-42c0-bcf3-655e9765f392].
[29/07/04 17:39:57:531 BST] CWUDU0115I: Imported 7 entities and 0 referenced entities. [this kind of  message indicates the operation worked!]
[29/07/04 17:39:57:531 BST] CWUDU0002I: ********** Starting UDDI Utility Tools **********
[29/07/04 17:39:57:531 BST] CWUDU0023I: Deleting entities...
[29/07/04 17:39:57:531 BST] CWUDU0028I: Deleted 7 entities.

The second log file shows a typical trace log file entry for an export:

[29/07/04 17:39:57:531 BST] ********** Starting UDDI Utility Tools ********** [eyecatcher and timestamp
 indicate when tool is run]
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.PromoterAPI.setUddiEntities()  [the '>' indicates  entry to the constructor of this class]
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.export.KeyFileReader() 
[29/07/04 17:39:57:531 BST]   com.ibm.uddi.promoter.export.KeyFileReader() loaded tModel keys
[29/07/04 17:39:57:531 BST]   com.ibm.uddi.promoter.export.KeyFileReader() loaded business keys TransformConfiguration: 
  nameSpacePrefix=promote
  uddiEntityDefinitionFile=C:\temp/MigToolFiles/Results/Promote_api_EDF_1.xml
 ExportConfiguration: 
  fromGetURL=http://yottskry:9082/uddisoap/
  fromInquiryURL=http://yottskry:9082/uddisoap/inquiryAPI
 ImportConfiguration: 
  overwrite=true
  uddiEntityDefinitionFile=C:\temp/MigToolFiles/Results/Promote_api_EDF_1.xml
  importReferencedEntities=true
 PublishConfiguration: 
  toInquiryURL=http://davep:9082/uddisoap/inquiryAPI
  toPublishURL=http://yottskry:9082/uddisoap/publishAPI
  userID=Publisher1
  trustStoreFileName=C:\WebSphere600/AppServer/etc/DummyClientTrustFile.jks
  secureConnection=false
 DatabaseConfiguration: 
  dbDriver=COM.ibm.db2.jcc.DB2Driver
  dbURL=jdbc:db2:LOC1
  dbUser=db2admin
 LoggerConfiguration: 
  messageStream=null
  messageLogFileName=C:\temp/MigToolFiles/logs/message.log
  traceLogFileName=C:\temp/MigToolFiles/logs/trace.log
  traceLevel=3
  verbose=true


[29/07/04 17:39:57:531 BST] < com.ibm.uddi.promoter.PromoterAPI() 
[29/07/04 17:39:57:531 BST] ********** Starting UDDI Utility Tools **********
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.PromoterAPI.setUddiEntities() 
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.export.KeyFileReader() 
[29/07/04 17:39:57:531 BST]   com.ibm.uddi.promoter.export.KeyFileReader() loaded tModel keys [ log  entries without a '>' or '<' are status messages only ]
[29/07/04 17:39:57:531 BST]   com.ibm.uddi.promoter.export.KeyFileReader() loaded business keys
[29/07/04 17:39:57:531 BST]   com.ibm.uddi.promoter.export.KeyFileReader() loaded service keys
[29/07/04 17:39:57:531 BST]   com.ibm.uddi.promoter.export.KeyFileReader() loaded binding keys
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.UddiEntityKeys() 
[29/07/04 17:39:57:531 BST] < com.ibm.uddi.promoter.UddiEntityKeys() [the '<' indicates exit from the  constructor]
[29/07/04 17:39:57:531 BST]   com.ibm.uddi.promoter.export.KeyFileReader() removed duplicate, empty  and null keys
[29/07/04 17:39:57:531 BST] < com.ibm.uddi.promoter.export.KeyFileReader() 
[29/07/04 17:39:57:531 BST] < com.ibm.uddi.promoter.PromoterAPI.setUddiEntities() 
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.PromoterAPI.deleteEntities() 
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.publish.EntityDeleter() 
[29/07/04 17:39:57:531 BST] < com.ibm.uddi.promoter.publish.EntityDeleter() 
[29/07/04 17:39:57:531 BST] > com.ibm.uddi.promoter.UDDIClient() 
[29/07/04 17:39:57:531 BST]   com.ibm.uddi.promoter.UDDIClient() client type: 1

Starting UDDI Utility Tools through the API UDDI Utility Tools provides a public API to functions for exporting, importing, promoting, finding and deleting UDDI entities. All of these functions can be invoked by using the PromoterAPI class. Usage of this class to perform these functions is typically to:

1. Create a Configuration object and populate it from a Properties object or from a configuration properties file.

2. Create a PromoterAPI object passing the Configuration in the constructor.

3. For keys based functions (export, delete and promote), set the keys by supplying a UDDIEntityKeys object, the location of the keys file, or, for one entity, by specifying an entity type and a key value.

4. Invoke the corresponding method for the function required: exportEntities, promoteEntities(boolean), importEntities, deleteEntities or extractKeysFromInquiry(FindTModel, FindBusiness, FindService, FindBinding, FindRelatedBusinesses).

There is some sample code for UDDI Utility Tools, demonstrating usage of the API classes, available from Samples Central.

Deprecated feature: The low-level UDDI Utility Tools API classes and methods, such as BusinessStub and ServiceStub, are deprecated in WAS V6.0. These APIs are replaced with the high-level PromoterAPI interface in the com.ibm.uddi.promoter package. Refer to the API documentation for details.depfeat

Known limitations with UDDI Utility Tools and workarounds

There are some known limitations with UDDI Utility Tools and a workaround for each. See UDDI troubleshooting tips for more information.

Embedded Apache Derby Restriction

The 'export' and 'delete' functions when referencing a source registry with an embedded Apache Derby database are supported. However, the 'import' and 'promote' functions are not supported when referencing a target registry because of a limitation with the UDDI registry when working with an embedded Apache Derby database. To allow the 'promote' and 'import' functions to work, the embedded Apache Derby database needs to be made network enabled. For information about configuring network Apache Derby, refer to the section about managing the Derby Network Server in the Derby Server and Administration Guide.

 

Saving V3 entities with a supplied key

An example of saving a V3 business with a defined key is shown below.

<?xml version="1.0" encoding="UTF-8"?>
<Envelope 
    xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
    <save_business 
    xmlns="urn:uddi-org:api_v3">
      <authInfo>a399c4a3-6387-47cd-a1bd-91f7bb91bdd7</authInfo>
      <businessEntity businessKey="uddi:mycompany-p1.com:computers">
        <name xml:lang="en">WithKey</name>
      </businessEntity>
    </save_business>
  </Body>
</Envelope>

Known limitations with UDDI Utility Tools and workarounds There are known limitations with the UDDI Utility Tools and a workaround for each:

• PublisherAssertions are not supported and will not be promoted.

  Workaround: After the user has promoted the businesses that are related, he must recreate the publisherAssertion relationship.

• Referenced businesses in service projections are not added automatically to the EDF in the same manner as referenced tModels.

  Workaround: Add the referenced business that will 'own' the projected service to the EDF. If the business is not present in the target registry, place it before the service's owning business in the EDF.

• Cycle detection for service projections are not detected in the same manner as for referenced tModels.

  Workaround: If a circular reference is present between two or more service projections, break the cycle by removing one of the projections temporarily, perform the import and update the changed entity to reestablish the cycle in the target registry.

• tModels that were deleted (in the logical sense) in the source registry are imported and promoted as undeleted in the target registry. This is because, in the UDDI V2 specification, the deleted state of tModels is not exposed as API calls.

  Workaround: After importing the tModel, perform a delete. This is done using the UDDI Utility Tools delete function, or any other UDDI registry API access method.

• BindingTemplates referenced by hostingRedirectors are not added automatically to the EDF in the same manner as referenced tModels.

  Workaround: Add the referenced bindingTemplate to the EDF.

• Businesses referenced by an 'owningBusiness' keyedReference are not automatically added to the EDF.

  Workaround: Import the referenced business into the target registry before importing the tModel that references it.

• A few combinations of command line arguments are not validated and prevented, for example, it is possible to specify -import with -keysFile <path to file> in the same command, although the -keysFile is ignored.

---

 

Related tasks

Use the UDDI registry
Migrate the UDDI registry

 

Related

UDDI registry management interfaces