UDDI

The Universal Description, Discovery and Integration (UDDI) specification defines a way to publish and discover information about web services. UDDI relies on a distributed registry of different businesses and the descriptions of their services implemented using a common XML format. This framework allows you to access public UDDI sites and search for information on the available web services. This information includes the technical programming interfaces (i.e., the WSDL) for interfacing with the business. The details about what kind of information you should store in a UDDI registry and the APIs that can be used to access this registry are documented in the specification, which can be found by visiting http://www.uddi.org/.

WebLogic implements the UDDI 2.0 specification. In fact, it comes equipped with three UDDI features:

• A UDDI registry runs on every WebLogic instance, and can be used to store references to any web service.
• A web-based UDDI Directory Explorer is distributed with your WebLogic installation. The UDDI Explorer lets you search and browse any UDDI registry on the Web, including any private UDDI registries running on WebLogic. Authorized users also can publish new services over WebLogic's UDDI registry.
• WebLogic provides a set of client APIs that allow you to programmatically publish and inquire about information stored in a UDDI registry.

19.9.1 The UDDI Registry

WebLogic's UDDI registry is deployed automatically when the server starts. It provides a public interface that lets you query and publish web services. A client can access this private registry through the URL http://host:port/uddi/uddilistener, where host and port refer to the listen address and port of a running WebLogic instance. Generally you won't access the UDDI registry directly from a browser. Later, in Section 19.9.3, we examine how to use the client API to interact with UDDI registries.

19.9.2 The UDDI Directory Explorer

The UDDI Directory Explorer is a web-based utility that lets you search UDDI registries for published web services and advertise your own web services over the local UDDI registry. In order to invoke the UDDI Explorer, you need to point your browser to the following address: http://host:port/uddiexplorer, where host and port refer to the listen address and port of a running WebLogic instance. Here you can use the console to browse and/or manipulate the configured UDDI registries.

19.9.2.1 Public registries

The UDDI Directory Explorer can be configured with a number of public UDDI directories. Select the Setup UDDI Directory Explorer option from the UDDI Explorer to add a new public registry. In order to configure a new registry, you simply need to specify a name and the URL for the registry. In fact, the UDDI Explorer comes preconfigured with a number of public registries. This configuration page also lets you set up the default address of the private registry for publishing and inquiring about web services. By default, the UDDI Explorer uses the private UDDI registry running on the local server, so its value will be a URL similar to http://10.0.10.10:8001/uddi/uddilistener.

Once you have configured the public registries, select the "Search public registries" option from the UDDI Explorer to search an existing public registry. You can search the selected public registry using various search options: the business name, a service key, or the value of a specified registry field such as the business location, t-Model name, business URL, or D-U-N-S number. After executing the search, the UDDI Explorer returns a list of web services that match the query. You then can select any of the search results to further explore the web service and discover more information about the access points and the WSDL.

19.9.2.2 Private registries

The UDDI Explorer also lets you search private WebLogic registries. If you select the Search Private Registry option, you can locate specific web services that match search criteria. The search query can be built using the name of the service, department, or project. Alternatively, you can simply list all of the web services published over the private registry.

Select the Modify Private Registry Details option to modify or create a registry entry. After the system ensures that you are an authentic WebLogic user equipped with the necessary privileges, you are presented with a list of projects/departments and options to create, remove, or edit a registry entry. You also can click a project to further drill down into its contact and service information, changing or adding to any of the details along the way.

You can use the Publish to Private Registry option to create a new registry entry. In either case, you need to supply a project name, service name, the URL for the WSDL, and a service description. In case you wish to publish the WebLogic web service that we developed earlier, the WSDL URL for the registry entry http://10.0.10.10:8001/myWar/Simple?wsdl.

19.9.3 The Client API

WebLogic's UDDI registry also can be accessed programmatically. In fact, WebLogic provides two types of APIs for UDDI clients: a publisher's API for storing and manipulating data in the registry, and an inquiry API for accessing the registry for information about published web services. These API functions actually are exposed as SOAP messages over HTTP. However, all publisher API calls must be made over HTTPS. You should refer to the online JavaDoc for a detailed coverage of the API. WebLogic's API for interfacing with UDDI registries can be found in the set of packages rooted at weblogic.uddi.client.*.

Let's now look at how a client can programmatically publish a web service over the private UDDI registry. Here is the main entry point for our client UDDIPublish:

UDDIPublish x = new UDDIPublish( );
// default to WebLogic's SSL implementation
System.setProperty("java.protocol.handler.pkgs", "weblogic.net");
// authenticate the client
Publish p = new Publish( );
p.setURL(LISTEN_URL);
AuthInfo ai = x.doLogin(p, "system", "pssst123");
// publish the web service over the private registry 
x.pub(ai, p, "businessName", "businessDescription", "serviceName", 
 "serviceDescription", "http://10.0.10.10:8001/myWar/Simple?wsdl");
// log out after you're done 
x.doLogout(p, ai);

The doLogin( ) method establishes the client's identity and allows WebLogic to later ensure that it is authorized to create or modify entries in the local UDDI registry. The following excerpt illustrates the implementation for the doLogin( ) method:

// Log in
private AuthInfo doLogin(Publish p, String username, String password) 
 throws Exception {
 GetAuthToken gat = new GetAuthToken( );
 gat.setUserID(username);
 gat.setCred(password);
 AuthToken at = p.getAuthToken(gat);
 return at.getAuthInfo( );
}

When the client is authenticated successfully, it acquires an authentication token that it can subsequently use whenever it needs to interact with the UDDI registry. The doLogout( ) method simply releases the authentication token and is invoked once the client has finished manipulating the UDDI registry. The following code sample shows how to discard the authentication token obtained after login:

// Log out
private void doLogout(Publish p, AuthInfo ai) throws Exception {
 DiscardAuthToken dat = new DiscardAuthToken( );
 dat.setAuthInfo(ai);
 p.discardAuthToken(dat);
}

Let's now examine the pub( ) method, which performs the bulk of the work. It publishes a new service over the private registry. Its signature accepts parameters that allow the client to configure the new web service i.e., the name and description of the business, the name and description of the service, and a URL that points to the WSDL for the web service:

public void pub (AuthInfo ai, Publish p, String businessName, String 
businessDescription, String serviceName, String serviceDesc, String serviceWSDL)
throws Exception {

First, you need to create a new business entity and publish it over the private registry:

// Publish a new business entity
BusinessEntity be = new BusinessEntity( );
be.setBusinessKey("");
be.setName(businessName);
be.addDescription(businessDescription);
Vector vbe = new Vector( );
vbe.add(be);
SaveBusiness sb = new SaveBusiness( );
sb.setAuthInfo(ai);
sb.setBusinessEntityVector(vbe);
BusinessDetail bdtls = p.saveBusiness(sb);

// Now access the business entity and retrieve its key
be = (BusinessEntity) bdtls.getBusinessEntityVector( ).elementAt(0);
String key = be.getBusinessKey( );

Once you create the new business entity, you can attach a new service to the business entity:

BusinessService bs = new BusinessService( );
bs.setBusinessKey(key);
bs.setServiceKey("");
bs.setName(new Name(serviceName));
bs.addDescription(serviceDesc);

// provide information about the technical entry point
BindingTemplate btemp = new BindingTemplate( );
btemp.addDescription("");
btemp.setBindingKey("");
btemp.setAccessPoint(new AccessPoint(serviceWSDL, "http"));
BindingTemplates btemps = new BindingTemplates( );
TModelInstanceDetails tmidls = new TModelInstanceDetails( );
btemp.setTModelInstanceDetails(tmidls);
btemps.addBindingTemplate(btemp);
bs.setBindingTemplates(btemps);

Finally, you are ready to publish the business service over the private registry:

Vector bss = new Vector( );
bss.add(bs);
SaveService ss = new SaveService( );
ss.setAuthInfo(ai);
ss.setBusinessServiceVector(bss);
ServiceDetail sd = p.saveService(ss);

Once you publish the web service, a client can inquire about the web service. For example, using the same business key created earlier, we can search for the business service given its name:

BusinessKey businessKey = new BusinessKey(key);
// define the search parameters -- i.e., name and find qualifiers
Name name = new Name(serviceName);
FindQualifiers fqs = new FindQualifiers( );
fqs.addFindQualifier("sortByNameDesc");
fqs.addFindQualifier("caseSensitiveMatch");
// build the search query using the business key, service name, and find qualifiers
FindService fs = new FindService( );
fs.setBusinessKey(businessKey.getValue( ));
fs.setFindQualifiers(fqs);
fs.setName(name);
// execute the query and inspect the list of services that match the query
Inquiry i = new Inquiry( );
i.setURL(LISTEN_URL);
ServiceList rServiceList = i.findService(fs);
ServiceInfos rServiceInfos = rServiceList.getServiceInfos( );
// iterate through the list of services and process each
Vector rServiceInfoVector = rServiceInfos.getServiceInfoVector( );
ServiceInfo rServiceInfo;
for (int x = 0; x < rServiceInfoVector.size( ); x++) {
 rServiceInfo = (ServiceInfo) rServiceInfoVector.elementAt(x);
 System.out.println("Found service " + rServiceInfo.getName( ).getValue( ));
}

These client APIs provide a complete way of interacting with the UDDI registry, allowing you to mimic the capabilities of the UDDI Directory Explorer.