Documentation

UDDI4J Overview

The UDDI (Universal Description, Discovery and Integration) Project is a comprehensive, open industry initiative enabling businesses to (I) discover each other, and (II) define how they interact over the internet and share information in a global registry architecture. UDDI is the building block which will enable businesses to quickly, easily and dynamically find and transact with one another via their preferred applications.

UDDI4J Structure

UDDI4J is a Java class library that provides an API that is can be used to interact with a UDDI registry. This class library generates and parses messages sent to and received from a UDDI server.

The central class in this set of APIs is org.uddi4j.client.UDDIProxy. It is a proxy for the UDDI server that is accessed from client code. Its methods map to the UDDI Version 2.0 API Specification.

The classes within org.uddi4j.datatype represent data objects used to send or receive UDDI information. and in the, business, service, tmodel subpackages represent data objects that are sent on calls or received from the server.

The subpackage org.uddi4j.request contains messages sent to the server. These classes are typically not used directly, rather the UDDIProxy class uses these classes.

Similarly, the subpackage org.uddi4j.response represents response messages from a UDDI server.

Pluggable transports are supported by the package org.uddi4j.transport.

Error Handling:

UDDIException is thrown when errors are received from the UDDI proxy when invoking UDDIProxy inquiry methods. UDDIException can contain a DispositionReport with information about the error.

APIs that do not return a data object return a disposition report directly.

TransportException is thrown if a communication error occurs or if the resulting data cannot be properly parsed as a valid SOAP message. This new exception class is required since the previous use of SOAPException created a dependency on Apache SOAP. TransportException wrappers any communications exception thrown by the underlying SOAP transport implementation (Axis, SOAP, HP-SOAP). The native exception is available, and a stack trace will indicate where the TransportException was thrown as well as the native exceptions stack trace.

Prerequisites

• A SOAP transport. Supported transports include:
  • Apache Axis. Available from xml.apache.org/axis. Currently supports Axis alpha 3 release.
  • Apache SOAP 2.2, available from xml.apache.org/soap
  • HP SOAP, available from hp.com/go/webservices
  Each transport has additional prerequisites. Consult the SOAP transport documentation for prerequisite information.
• JDK version 1.2.2 or later.
• Ant is required to build UDDI4J. Ant is available at the Apache ANT website.

Configuration

UDDI4J uses a variety of properties to configure behavior. These properties may be set in a variety of ways.

The order of precedent for each method is as follows with the highest precedence first.

1. java.util.Properties object passed to UDDIProxy(Properties) constructor
2. System properties
3. uddi4j.properties file (located on the classpath)
4. Default properties (currently the org.uddi4j.TransportClassName property is the only property with a default)

SOAP transport specific properties:

Please note that the HP-SOAP transport will only read System properties and will ignore properties passed to the UDDIProxy(Properties) constructor or set in a uddi4j.properties file.

Usage

The user can set these properties at startup time

C:> java –Dorg.uddi4j.TransportClassName=org.uddi4j.transport.HPSOAPTransport
        
-Dorg.uddi4j.logEnabled=true SomeUDDIClient

The user can set these properties at run time

System.setProperty (“hpsoap.logDirectory”,“/tmp”);
        
System.setProperty (“hpsoap.logFileName”,“uddi4j.log”);
        
System.setProperty (“org.uddi4j.logEnabled”,“true”);
        
UDDIProxy uddiProxy = new UDDIProxy ();

Using UDDI4J

To run a program referencing UDDI4J,

• Include uddi4j.jar in the classpath
• Include the chosen SOAP transport in the classpath, i.e. axis.jar
• Select the transport to use by setting system property org.uddi4j.transportClassName to the appropriate value as defined in the Configuration section.
• If using the publish API, include an implementation of JSSE in the classpath. JSSE can be configured by editing the jre/lib/security/security.policy file within the JDK.
• or, can be configured within the client program. The examples illustrate a method for configuring the security provider.

Building UDDI4J

• Obtain ANT, SOAP, JDK as listed in the prerequisites.
• Include at least one SOAP transport implementation in the classpath. The build will check for the presence of known SOAP transports in the classpath and build the associated support into the resulting jar file. Only those transports available at compile time will be supported by the resulting jar file.
• Set required environment variables, including, JAVA_HOME, ANT_HOME.
• From the root directory of UDDI4J (where build.xml is located), run

  ant target

  where target is one of the following:
  • compile: Compiles the API
  • samples: Compiles the samples
  • javadocs: Builds the javadoc
  • srcdist: Creates the source distribution zip file.
  • dist: Creates the binary distribution zip file.
  • clean: Removes built files.
  • all: Cleans, creates source and binary distribution zip files.

Samples:

A set of samples is provided to illustrate the basics of using the inquiry api, publish api, and error handling.

• FindExample: The hello world of UDDI programs. Provides the simplest useful sample of a UDDI API.
• SaveBusinessExample: A simple example using the publish API. Logs into the server using the get_authToken method, then attempts to save a business.
• DeleteBusinessExample: Searches for a particular business using the inquiry API, finds the associated businesskey, logs into the server, then attempts to delete the business found.

How to run samples:

The samples require several pieces of information including the following:

• InquiryURL: The URL of the UDDI server to run inquiries against must be specified.
• PublishURL: The URL of the UDDI server to run publish requests. This is typically an SSL connection.
• Userid: When publishing a userid is required for authentication.
• Password: Password for the referenced userid. Refered to as a credential in UDDI speak.

A property file is used by the samples to read values that may need to be modified. This property file includes the values listed above, as well as a convenient way to set the system properties used by UDDI4J as described in Configuration.

To run the examples, set the classpath as described above, invoke java or jre with the desired sample program name. Example:

java FindBusinessExample

Reference:

• The UDDI API is described in the UDDI Version 2.0 API Specification available on the UDDI.org web site.
• The UDDI Version 2.0 Data Structure Reference is also available at the same site.
• Javadoc for the UDDI Java API classes
• IBM UDDI web site

IBM is a registered trademark of IBM, HP is a registered trademark of Hewlett-Packard Company

Copyright© IBM Corporation 2001, All rights reserved.