UDDI Utility Tools

The UDDI Utility Tools is a suite of functions that can be used to migrate, move or copy UDDI V2 entities, including child entities and their respective V2 entity keys, into a V3 UDDI Registry.

Note: The UDDI V3 publish API supports publisher assigned keys (the V2 API did not) and promotion of entities between V3 registries can be achieved using normal API functions. UDDI Utility Tools supplied in this release is functionally equivalent to the version supplied in WebSphere Application Server 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 V2 representation of the UDDI Entity key) and import into the V3 registry, using Version 2 API types. Entities from a V3 registry are exported as V2 entities and, as such, elements such as digital signatures will not be present. See section Saving Version 3 entities with a supplied key for an example on how to use the Version 3 API to assign your 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 (V2) 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

The UDDI Utility Tools can be used by running the UDDIUtilityTools.jar file. This file is located in the install_root/UDDIReg/scripts directory. Alternatively, all of the functions of UDDI Utility Tools can be invoked 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. We can 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.

Note: 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:

Setting 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 the install_root/UDDIReg/scripts directory.

The most important property to set is the classpath, and this should include the current directory (.) and the UDDIUtilityTools.jar itself, plus all the dependent jars, most of which are located in the WebSphere AppServer lib directory. The classpath must include the database driver jar (for example db2java.zip). The other properties are well commented in the example properties file.

Below is an example properties file as distributed:

 

Example

##############################################
# Runtime environment                        #
# (if invoking via java -jar...)             #
# "X Y" required around paths with spaces    #
# Replace WAS_HOME with your WAS home path.  #
# db2java.zip is for DB2 - replace this with #
# appropriate database driver file.          #
##############################################
classpath=.;WAS_HOME/UDDIReg/scripts/UDDIUtilityTools.jar;WAS_HOME/lib/soap.jar;WAS_HOME/lib/uddi4jv2.jar;WAS_HOME/lib/j2ee.jar;"C:/Program Files/IBM/SQLLIB/java/db2java.zip"

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

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

##############################################
# UDDI Registry user information             #
#                                            #
# 

Note: 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:uddi20
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=c:/websphere/appserver/etc/DummyClientTrustFile.jks

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

##############################################
# 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)
# 

Note: 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=C:/definitions/entities01.xml

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

Prerequisites

To run the UDDI Utility Tools use the IBM Development Kit for Java that is supplied with WebSphere Application Server. This Development Kit is located in install_root/java/bin. You must also ensure that the following .jar files are available to the UDDI Utility Tools. The locations of the .jar files should 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 install_root/UDDIReg/scripts.

uddi4jv2.jar

This file contains the UDDI4J classes and is located in install_root/lib.

j2ee.jar

This file contains some required J2EE classes and is located in install_root/lib.

soap.jar

This is the Apache SOAP implementation and is located in install_root/lib.

DbDriver

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

  DB2 Cloudscape Oracle
DBDriverLocation for classpath DB2_HOME/db2java.zip install_root/cloudscape/lib/otherJars/db2jcc.jar, install_root/cloudscape/lib/db2jcc_license_c.jar ORACLE_HOME/jdbc/lib/ojdbc14.jar
Driver COM.ibm.db2.jdbc.app.DB2Driver com.ibm.db2.jcc.DB2Driver oracle.jdbc.OracleDriver
URL jdbc:db2:database_name jdbc:db2j:net://host:1527/database_name (see note below) jdbc:oracle:thin:@host:1521:database_name
where

  • install_root is the directory location of WebSphere Application Server

  • 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 your database. For Cloudscape, make sure that database_name includes the path to the database, for example install_root/profiles/AppSrv01/databases/com.ibm.uddi/UDDI30

If you are using Cloudscape, make the database network enabled so that it can handle multiple connections. See Configuring Cloudscape V5.1.60x for details on how to do this.

If you are using DB2, add DB2_HOME/jcc/lib to your LD_LIBRARY_PATH and LIBPATH environment variables.

The Security provider configuration section in the above properties file shows the location of the default DummyClientTrustFile.jks file. If you are using your own truststore, ensure that the location is placed here.

The UDDI Entity Definition File

You generate this file by the export and promote functions, or one 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.

Note: 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 you are using the correct level of java by setting the PATH statement
to the level of java supplied with WebSphere. For example, from the command
line, type:


On Windows



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







On Unix and Linux platforms:



export PATH=install_root/java/bin:$PATH




If you are 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




Note: In the above
example, notice that the '.' is followed by a single space character.


Note: On
Unix and Linux platforms 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 which processes command line arguments
for UDDI Utility Tools, sets up configuration and invokes the appropriate
function.





Note: Before executing UDDIUtilityTools.jar from the command
line, ensure that you have edited the UDDIUtilityTools.properties file. If
you have saved this properties file in a different directory from the directory
containing the UDDIUtilityTools.jar file, make sure you 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 entites 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






Below are a set of UDDI Utility Tools command line examples.
The examples use the Windows file system:


To 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





As above but this time using a keys file to specify the entities to
be exported
java -jar UDDIUtilityTools.jar -export -keysFile C:/myKeyFiles/keyFile01.txt





As
above but also specifying verbose output to appear on the command line


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






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


java -jar UDDIUtilityTools.jar -import






As above but also specifying that referenced tModels should be
imported into the target  registry


java -jar UDDIUtilityTools.jar -import -importReferenced






To 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 file system.
java -jar UDDIUtilityTools.jar -import -definitionFile C:/myEDFs/entities01.xml






To 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 should be overwritten


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





To
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






To promote a set of entities specified in a keys file


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





As above
but specifying that existing entities in the target registry get overwritten


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





To
promote a set of entities specified in a keys file including referenced tModels


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





To
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





To
logically delete a single tModel.  Note that  it is not possible to physically
delete tModels


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





To
delete all the entities specified in the keys file.  Note that  with the exception
tModels all other entities will be physically deleted from the target registry


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









A keys file example


Below is an example of 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
#
# 

Note: keys must be comma separated and on SAME line
# 

Note: 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







Note: 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.



Should
we need to 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


Below shows examples
of contents of two of the log files produced by running the tool. Note that 
some comments have been added in square brackets and in italic to highlight
important points within 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-4834-9f5d-8f8c878f5d6e].
[29/07/04 17:39:57:531 BST] CWUDU0122I: Created service minimal entity with serviceKey [0af2a30a-be70-401f-a027-331a6c332712].
[29/07/04 17:39:57:531 BST] CWUDU0122I: Created service minimal entity with serviceKey [61012761-d02c-4c70-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-4e81-88a7-e26bfbe2a7f1].
[29/07/04 17:39:57:531 BST] CWUDU0122I: Created service minimal entity with serviceKey [003d2b00-f6c0-4071-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-4099-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:9080/uddisoap/
  fromInquiryURL=http://yottskry:9080/uddisoap/inquiryAPI

ImportConfiguration: 
  overwrite=true
  uddiEntityDefinitionFile=C:\temp/MigToolFiles/Results/Promote_api_EDF_1.xml
  importReferencedEntities=true

PublishConfiguration: 
  toInquiryURL=http://davep:9080/uddisoap/inquiryAPI
  toPublishURL=http://yottskry:9080/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.




The "low-level"
API classes and methods have been deprecated in this release. Refer to the Javadoc welcome page for details.




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 Cloudscape Restriction




The
'export' and 'delete' functions when referencing a source registry with an
embedded Cloudscape 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 Cloudscape
database. To allow the 'promote' and 'import' functions to work, the embedded
Cloudscape database needs to be made network enabled, see Configuring Cloudscape V5.1.60x.





 
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, it should be placed
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.




  • The JSSE provider class is not configurable; it must be com.ibm.jsse.IBMJSSEProvider.



  • 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.