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.
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
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 |
If you are using Cloudscape, make the database network enabled so that it can handle multiple connections. See Configuring Cloudscape Version 5.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 Utility Tools use UDDI Version 2 SOAP inquiry and publish interfaces. These APIs are protected as described in Access control for UDDI Registry interfaces. 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
<?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:
set PATH=install_root\java\bin;%PATH%
On Unix and Linux platforms:
export PATH=install_root/java/bin:$PATH
. /$DB2_HOME/db2profile
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:
java -jar UDDIUtilityTools.jar -export -business 28B8B928-2B2E-4EC9-A647-1E40651E4752
java -jar UDDIUtilityTools.jar -export -keysFile C:/myKeyFiles/keyFile01.txt
java -jar UDDIUtilityTools.jar -export -keysFile C:/myKeyFiles/keyFile02.txt -v
java -jar UDDIUtilityTools.jar -import
java -jar UDDIUtilityTools.jar -import -importReferenced
java -jar UDDIUtilityTools.jar -import -definitionFile C:/myEDFs/entities01.xml
java -jar UDDIUtilityTools.jar -import -overwrite -importReferenced
java -jar UDDIUtilityTools.jar -promote -service 67961D67-330F-4F14-8210-E74A58E710F3
-properties C:/UUT/myUUTProps.properties
java -jar UDDIUtilityTools.jar -promote -keysFile C:/myKeyFiles/keyFile03.txt
java -jar UDDIUtilityTools.jar -promote -keysFile C:/myKeyFiles/keyFile04.txt -overwrite
java -jar UDDIUtilityTools.jar -promote -keysFile C:/myKeyFiles/keyFile05.txt -importReferenced
java -jar UDDIUtilityTools.jar -promote -keysFile C:/myKeyFiles/keyFile06.txt -definitionFile C:/myEDFs/entities02.xml
java -jar UDDIUtilityTools.jar -delete -tModel UUID:1E2B9D1E-E53D-4D36-9D46-6CCC176C466A
java -jar UDDIUtilityTools.jar -delete -keysFile C:/myKeyFiles/keyFile04.txt
A keys file example
# # 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
Should you need to update a referencedTModel, you must manually move the referencedTModel definition to the tModels section in the entity definition file and set overwrite to true.
Content of the log files
[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.
[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
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 Version 5.1.60x.
Saving Version 3 entities with a supplied key
An example of saving a Version 3 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
Workaround: After the user has promoted the businesses that are related, he must recreate the publisherAssertion relationship.
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.
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.
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.
Workaround: Add the referenced bindingTemplate to the EDF.
Workaround: Import the referenced business into the target registry before importing the tModel that references it.