he Universal Description, Discovery and Integration (UDDI) specification and protocol work together to form define messages, application programming interfaces (APIs), and data structures for building distributed registries of Web services and storing the business and technical information associated with these services. UDDI is an OASIS standard. There are fundamentally two types of UDDI registries: public registries and private registries. This article shows you how to implement a private registry. First, however, here’s a brief review of UDDI’s high-level architecture.

UDDI High-Level Architecture
UDDI uses Web services and Web protocol standards and technologies, such as HTTP, XML, and SOAP (see Figure 1). UDDI defines a Web service discovery protocol, which lets clients find Web services, and a Web service description format, which lets clients understand what the Web services that they find do. A UDDI registry typically contains metadata for a service embodied within a Web service Description Language (WSDL) document.

Figure 1. How UDDI Fits In: The diagram illustrates how UDDI fits into the layers of technologies and protocols currently used for Web services.

You can use the information provided in a UDDI registry to perform three types of searches:

1. A white pages search returns basic information such as address, contact, and identifiers about a company and its services.
2. A yellow pages topical search retrieves information according to industrial categorizations and taxonomies, such as the NAICS, ISO3166, and UNSPSC classification systems.
3. A green pages service search retrieves technical information about Web services, as well as information describing how to execute these services.

The UDDI Publication API
The UDDI publication API consists of operations for creating, reading, updating, and deleting the information exposed by the UDDI structures discussed above. A caller can use these operations to register and/or modify any number of businesses or services.

A UDDI registry must support the publication API calls shown in Table 1.

Table 1: Required Publication API Methods. The table lists thepublication methods that a UDDI registry must support.

The UDDI Authentication Model
The key operating principal for the UDDI Publishers’ API is to allow only authorized individuals to publish or change information within the UDDI business registry. Each individual implementation of the distributed UDDI business registry maintains a unique list of authorized parties and tracks which individuals create each businessEntity or tModel. Subsequent changes and deletions are allowed only if a change request (via API call) is made by the same individual who created the information.

The get_authToken message accommodates those implementations that desire a login step. Security schemes based on the convention of exchanging User ID and password credentials fall into this category. The get_authToken method provides an optional way to generate a temporary authentication token.

The UDDI Data Model
Registries are themselves implemented as Web services. A typical UDDI registry supports interactions surrounding the following components:

• Registry clients: programs or services that interact with a registry in order to browse or search for registered businesses and services.
• Registry entries: content residing inside a registry about a business or service.
• Entry metadata: content describing a registry entry and how to find the registry entry.

Registry entries and metadata are exposed as the following structures:

• businessEntity?this structure encapsulates information describing one or more business services, including their name, category, geographic location, contact information, etc
• businessService?this structure contains descriptive information about a group of related technical services including the group name, description, and category information. A businessService structure acts as a container for one or more bindingTemplates
• bindingTemplate?this structure contains information needed to invoke or bind to a specific service. This information includes the service URL, routing and load balancing facilities, and references to interface specifications contained in a corresponding tModel structure
• tModel?this structure encapsulates information about interfaces and other technical concepts for a given service

Figure 2 illustrates the relationships between these structures.

Figure 2. Relationships Between UDDI Structures: The figure illustrates the relationships between the various structures exposed in a UDDI repository.

The UDDI Invocation Model
To invoke a specific Web service using information from a UDDI registry a caller typically follows these steps:

1. Locates the businessEntity information registered for the business exposing the Web service.
2. Discovers additional details about the Web service by accessing the businessService structure contained within the businessEntity structure. From there, the caller selects the appropriate bindingTemplate to use.
3. Uses the technical information contained in the tModel corresponding to the selected bindingTemplate to build the client that will access the Web service.

The UDDI Inquiry API
The UDDI inquiry API consists of operations that enable you to browse a registry and to traverse a registry in order to obtain information about specific businesses and services. Table 2 shows the inquiry API calls that a UDDI registry must support.

Table 2: Required Inquiry API Methods: The table lists the inquiry methods that a UDDI registry must support.

The following sections discuss a particular framework?jUDDI? used to represent the structures of a UDDI registry and how you can use it to implement a private registry.

Using the jUDDI Registry Framework
To set up your own UDDI registry using Java, you will need to install a:

• Java 2 SDK?I used Sun’s Java 2 SDK SE, version 1.4.2_04.
• J2EE build and runtime environment?I used Sun Java 2 Enterprise Edition (J2EE) 1.3.1.
• Web server and/or servlet container?I used Apache Tomcat, version 5.0.24.
• SOAP processing framework?I used the version of Apache Axis that ships with jUDDI.
• Data storage mechanism?I used the MySQL relational database, version 4.0.19.
• UDDI registry framework?I used the registry framework jUDDI.

jUDDI is an open source Java implementation that complies with version 2.0 of the UDDI specification for Web services. You can use jUDDI with existing authentication technologies, and with virtually any relational database including MySQL, DB2, Sybase, and others.

jUDDI Implementation Details
Functions handle the actual logic for each UDDI invocation message. The org.apache.juddi.function package defines the function classes?one for each logical UDDI invocation message.

The org.apache.juddi.registry.RegistryEngine class uses the org.apache.juddi.function.FunctionMaker class to lookup functions, based on the class name of the function. FunctionMaker keeps a cache of instances of the maker classes.

jUDDI uses Apache Axis to handle SOAP messaging. Axis defines a transparent transport framework that allows different transport protocols to be used. For the HTTP protocol, any servlet derived from the org.apache.axis.transport.http.AxisServlet class is a candidate for handling HTTP requests. In jUDDI, three servlets extend the AxisServlet class:

Figure 3. Request Process Flow Diagram: The diagram illustrates the process flow for a typical request in jUDDI.

1. org.apache.juddi.transport.axis.AdminServlet
2. org.apache.juddi.transport.axis.PublishServlet
3. org.apache.juddi.transport.axis.InquiryServlet

This all seems quite straightforward, however, there is a slight twist?jUDDI registers these three classes as servlets with an application server, but only uses them to determine the type of request that is made. The actual processing is handled by the org.apache.juddi.transport.axis.AxisHandler class which must be registered with the Axis handler-chain. Figure 3 shows a flowchart that illustrates the process for a typical request.

jUDDI Data Structures
jUDDI encapsulates the primary UDDI data structures (businessEntity, businessService, bindingTemplate and tModel) in classes following the ValueObject pattern. The classes are found subordinate to the org.apache.juddi.datatype package as follows:

• org.apache.juddi.datatype.business.BusinessEntity
• org.apache.juddi.datatype.service.BusinessService
• org.apache.juddi.datatype.binding.BindingTemplate
• org.apache.juddi.datatype.tmodel.TModel

Instances of each of these classes (along with all other UDDI data types) are acted on by jUDDI handlers and functions in order to process client requests, as shown in Figure 4

Figure 4. Process Flow for a Save_Business Request: The diagram illustrates the class instances and process flow for a save_business request:

Handling Publication Requests with jUDDI
The jUDDI framework dispatches request messages through an Axis handler object?aptly named AxisHandler. The AxisHandler class uses the services of the RegistryEngine class to do the actual request processing. A URL mapping for a specific child of AxisServlet is used to classify inquiry requests, publish requests, and admin requests.

The framework classifies each request according to the property value set in the request’s MessageContext object for the transport.http.servlet key. Thus, the framework maps the following URL to the PublishServlet:

   http://localhost:8080/juddi/publish

After receiving a request, the RegistryEngine class converts the XML-based UDDI request to Java objects (a process called unmarshalling), invokes the appropriate Java objects, and converts Java objects to XML-based responses (called marshalling).

Handling Inquiry Requests with jUDDI
As with a publish request, a URL mapping for a specific child of AxisServlet is used to classify inquiry requests. The transport.http.servlet property of the request’s MessageContext object will return an instance of the InquiryServlet class and therefore be routed accordingly. Thus, jUDDI will map the following URL to the InquiryServlet:

   http://localhost:8080/juddi/inquiry

Handling Authentication Requests with jUDDI
jUDDI uses the org.apache.juddi.auth.AuthenticatorFactory object to create the desired Authenticator instance in order to authenticate a client. AuthenticatorFactory is an implementation of the Factory pattern. You use it to create an implementation of the org.apache.juddi.auth.Authenticator interface. You retrieve the name of the specific Authenticator implementation to create from the “juddi.auth” property value. If you pass a null value then the AuthenticatorFactory creates a default Authenticator implementation “org.apache.juddi.auth.DefaultAuthenticator.” The DefaultAuthenticator class applies no restrictions; therefore, it allows all requests.

Production systems should supply an implementation of the Authenticator interface that can authenticate callers against an existing authentication system. The Authenticator implementation class is registered in the juddi.properties file.

Creating the Registry
jUDDI installs as a Web application (.ear file or .war file) with a context of http://:/juddi so you can deploy it to almost any up-to-date application server or servlet engine.

To install the jUDDI Web application, following these steps:

• Copy the Web.xml file from the /conf directory to the /webapps/juddi/WEB-INF directory
• Copy the /webapps/juddi directory into your application server’s webapps directory
• Copy the juddi.properties file from the /conf directory to the /webapps/juddi/WEB-INF/classes directory
• Edit the juddi.properties file. jUDDI ships configured with a default JDBC driver for MySQL, in the com.mysql.jdbc.Driver package. If you are using another database or if your MySQL JDBC driver has a different package name, you will have to change the reference to it in the juddi.properties file located in the /conf directory. For jUDDI to use the database, add the following lines to the end of the juddi.properties file:

   # required JDBC DataSource properties   juddi.dataSource = java:comp/env/jdbc/juddiDB      # required JDBC Driver properties   juddi.useConnectionPool = true   juddi.jdbcDriver        = com.mysql.jdbc.Driver   juddi.jdbcURL           = jdbc:mysql://localhost/juddi   juddi.jdbcUser          = juddi   juddi.jdbcPassword      = juddi

• Edit the server.xml file to configure the jUDDI Web application for your specific application server, if needed.

Creating the Data Store
The default implementation for the jUDDI data store uses JDBC. The setup process is fairly straightforward. Generically, you start by creating a new jUDDI database using one of the database schemas included with the jUDDI download, and then configure a JNDI Datasource named ‘juddiDB‘ in the application server or servlet engine to which you’re deploying.

Here’s a specific example using MySQL. After installing MySQL and creating a root user, create a new database called “juddi” using the MySQL command-line as follows:

   mysql> create database juddi

After successfully creating the database, you must tell MySQL to use the juddi database by typing the following on the MySQL command line:

   mysql> use juddi

Now, you can populate the database using the SQL script that ships with jUDDI by typing the following on the MySQL command-line:

   mysql> . dbscriptsjuddi_mysql.sql

Replace the fragment in the preceding command with the path to your local jUDDI installation.

Create a new user called juddi that will be used by jUDDI for accessing the UDDI database. Make sure this user has permission to connect to, read from, and write to the UDDI database.

   mysql> grant all privileges on juddi.* to juddi@"%"       -> identified by 'juddi';   mysql> grant all privileges on juddi.* to juddi@"localhost"       -> identified by 'juddi';

Now add a jUDDI publisher with a PUBLISHER_ID representing the ID a publisher uses when authenticating, as follows:

   mysql> INSERT INTO PUBLISHER (PUBLISHER_ID,PUBLISHER_NAME,ADMIN)       -> VALUES ('juddi','John Doe','false');

Finally, add the MySQL JDBC driver to the classpath of the jUDDI Web application by creating a WEB-INF/lib directory structure under the /webapps/juddi directory.

Running the Registry
To test your jUDDI installation, start your Web server and/or application server and point your browser to:

   http://:/juddi/happyjuddi.jsp

This should take you to the “jUDDI happiness page.” You should see a list of jUDDI dependencies, resource files, properties files, class files, etc. Your registry is now ready to handle UDDI request messages. The jUDDI installation includes samples that you can use to send requests to the registry.

The Universal Description, Discovery and Integration (UDDI) specification and protocol work together to form one of the primary components of a complete Web services infrastructure. jUDDI is an open source Java implementation of the UDDI specification for Web services. By following the steps shown in this article, you can use jUDDI to create a private UDDI registry that handles publication, authentication, and inquiry requests.