Aggregate UDDI searches with Business Explorer for web services

Developers can radically simplify their web services searches with BE4WS

Many developers believe that web services will open up a world of interlocking business services that find each other over the Internet, thus integrating disparate code into useful programs. But if this vision is to come to pass, users must be able to find services out there on the vast public network. Current searching APIs are rudimentary at best, and a developer must write a lot of code in order to find the web services he or she desires. Business Explorer for Web Services (BE4WS) is an alphaWorks technology, based on the Java programming language and XML, that aims to simplify Universal Description, Discovery, and Integration (UDDI) searches for developers and users alike. Liang-Jie Zhang and Qun Zhou walk you through some example code to show you how it's done -- and show you how you can a build a Web-based application that will allow users to find web services without writing any code at all.


Liang-Jie Zhang (, Researcher, IBM T.J. Watson Research Center

Liang-Jie Zhang is a research staff member at the IBM T.J. Watson Research Center, where he has been actively working on B2B integration using Web services. He is the lead author of Business Explorer for Web Services (BE4WS). His other research interests include Web services-oriented business process outsourcing technologies and broadband-media commerce. He is the session chair of Web Services Computing at IC'02. You can reach Liang-Jie at

Qun Zhou (, Software Engineer, IBM Software Group

Qun Zhou is a software engineer at the IBM Software Group, where she has been working on media search and cataloging. She is also looking into Web services and their applications in media content distribution and search. You can reach Qun at

01 March 2002

Web services are typically published to a public or private UDDI registry. The design of UDDI allows simple forms of searching and allows trading partners to publish data about themselves and their advertised web services to voluntarily provide categorization data. In general, UDDI can locate businesses whose identities are well known; and users can find out what services those businesses offer and how to interface with them electronically. The current UDDI search mechanism can only focus on a single search criterion, such as business name, business location, business category, or service type by name, business identifier, or discovery URL.

From an e-business application developer's point of view, it would be ideal to send a few sequential or programmed search commands to the UDDI registry for information aggregation. Potential information sources could include multiple UDDI registries and other searchable sources. Obviously, there is a need to dramatically extend the current search capability for web services to improve efficiency and performance.

All existing UDDI search engines only support a single UDDI registry. For example, Microsoft's UDDI search technology only allows users to search its UDDI registry, and those searches can only use a single search query, based on one of the following categories: business name, business location, business category, and service type by name, business identifier, or discovery URL. The known taxonomy types include NAICS, UNSPSC, SIC, or a geographic code (GEO); the known identifier types include D-U-N-S, Thomas Registry numbers, and US Tax ID.

In this article, we will introduce a newly released technology, BE4WS, an XML-based UDDI-exploring engine that provides developers with standard interfaces for efficiently searching business and service information in individual or multiple UDDI registries. BE4WS is written in Java programming language; it uses information in UDDI Search Markup Language (USML) documents to direct UDDI clients like UDDI4J to conduct complex UDDI searches. You can build BE4WS into your Java programs, or invoke it from a servlet and create a BE4WS web application or web service.

With BE4WS, you can interact with XML representations of a UDDI exploring mechanism; this process takes place of the usual programming model, which involves working directly with UDDI4J or some other UDDI client. With BE4WS, the same programming model can be used regardless of how your lower-level UDDI clients are implemented.

We have defined a UDDI Search Markup Language (USML; see Resources for more information) for business applications to efficiently search UDDI registries. We've also proposed a framework of an advanced UDDI search engine to conduct the searching process (see Resources). In this article, we will use sample Java application code, JSP code, and servlet code to illustrate the use of BE4WS as an advanced UDDI search portal deployed on WebSphere Application Server (WAS) 4.0, although BE4WS will work with other application servers such as Apache Tomcat, as well. You'll see some screenshots, including JSP pages and the BE4WS SOAP service page. But first, let's examine how BE4WS works with existing UDDI clients, and examine the BE4WS APIs.

BE4WS and UDDI clients

A UDDI client like the UDDI4J provides lower-level APIs for searching the UDDI registry. BE4WS provides higher-level APIs to take advantage of UDDI4J or other clients, such as the Web Services Inspection Language (WS-Inspection) search tool, to define a script-based search request, aggregate search results, and explore multiple UDDI registries concurrently. For example, a single USML request in BE4WS can include multiple queries, different UDDI sources, and an aggregation operator. The returned result is aggregated from different UDDI registries or other sources according to search criteria. If you are using UDDI4J alone, you must write your own code to send out multiple search queries to different UDDI registries and then try to aggregate the data yourself. Obviously, this is a time-consuming process and an advanced UDDI search engine can help you better handle such requests.

Moreover, BE4WS can incorporate not only different web service discovery technical layers (such as UDDI for Java technology or other similar UDDI client packages), but also different sources (such as standard UDDI registries, an enhanced UDDI registry, or such other sources as an LDAP directory, the Web, Web Service Inspection documents, and so on). So BE4WS enables you to interact with XML representations of a UDDI exploring mechanism instead of working directly with UDDI for Java technology and other UDDI clients. With BE4WS, you can use the same programming model regardless of how your web services discovery clients are implemented. BE4WS could emerge as a standard as an efficient and effective exploring mechanism and common interface for UDDI registries and other sources.


Business Explorer for Web Services provides two types of APIs for business application developers: a regular Java API and a web services interface. Any e-business application developer can use these APIs to easily find desired business entities, services, and service types (tModels) from different UDDI registries using one single Java or SOAP call. The only input parameter for these calls is a USML request string or a location of a USML document. The returned result is also a USML document. Thus, BE4WS can be easily deployed as a central UDDI search portal. All authorized e-business applications can take advantage of this service to explore business and service information across multiple UDDI registries.

Regular Java API

Three public functions are provided in a Java programming language class (

  • public String searchByString(String inputUSMLString): This function takes the string containing the desired search criteria as input and returns a USML response document. The parameter inputUSMLString is a USML request string.

  • public String searchByURL(String inputUSML_URL): This function takes the string containing the desired USML URL as input and returns a USML response document. The parameter inputUSML_URL is the URL of the appropriate USML file.

  • public String searchByFileName(String inputUSMLFileName): This function takes a file containing the desired search criteria as input and returns a USML response document. The parameter inputUSMLFileName is the name of the file containing the USML request.

To use these functions in your own Java applications, follow these steps:

  1. Create a USML script with all the search criteria.
  2. Write a Java application that includes the BE4WS package.
  3. Invoke the appropriate method.
  4. Parse the USML response from BE4WS.

Note that the current BE4WS package on alphaWorks does not include a USML response parser. Currently, developers need to modify the sample parsing code in Listing 5 for their own purposes. A generic USML response parser will be released in version 3.1 of alphaWorks' Web Services Toolkit (WSTK; see Resources).

Any e-business application developer can use this Java API to easily find business entities and services from different UDDI registries using a single search request. In the BE4WS installation package (see Resources) you can find three sample Java programs to illustrate the usages of the above Java API.

Web services API

Once a BE4WS web service is published in a private or public UDDI registry, any application can find this useful UDDI search service and invoke it through a WSDL interface. The installed BE4WS SOAP service can work as an advanced UDDI search portal that allows any SOAP clients to easily and effectively find information on business and service information from multiple UDDI registries.

There are two methods in the BE4WS SOAP service: searchByString and searchByURL. The SOAP service ID is urn:uddisearch-service. The provider class is

Figure 1 shows an installed BE4WS SOAP service on running on WAS 4.0.1. It is a regular Java application that was packaged as an enterprise application using WebSphere Application Assembly Tool (AAT). You can stop or start it using the WAS admin control console. Furthermore, you can assign access roles and set a certain security level for BE4WS if required. The BE4WS SOAP service provides this web service interface so that all SOAP clients can easily access it.

Figure 1. BE4WS SOAP service installed on WAS 4.0
BE4WS SOAP service installed on WAS 4.0

Sample application integration using BE4WS

Let's see how BE4WS can be used to efficiently search multiple UDDI registries using a single USML request with multiple queries. Our example will deploy BE4WS as a Web application and will take as parameters two URLs: one for a USML document that describes the search we want to conduct, and one for a JSP template that provides a format for our output. We'll look at an example USML document, along with presentation JSP code, servlet code, and a USML response parser. We will illustrate how BE4WS simplifies the exploring process across multiple UDDI registries. The developer doesn't need to write any Java code to access a UDDI client such as UDDI4J; the only thing he or she needs to do is to construct a simple XML-based USML script and parse the response. Actually, based on this sample application, a Web-based search tool can be easily developed to let the user enter all the search criteria; backend serve-side code generates the USML, parses the response, and returns the result to the user in the form of a Web page.

The following example shows how a Web application invokes a BE4WS SOAP service and parses/presents the response to a Web page. Figure 2 shows an aggregation example page using configurable BE4WS. It is a regular HTML page which includes a form field to specify the URL of your USML script and another form field to define your desired presentation template implemented as a JSP page. These parameters, USMLFileURL and ReturnURL, are passed to the BE4WS invocation servlet. The complete HTML source for this page is shown in Listing 1.

Figure 2. Sample Web application page using BE4WS (before invocation)
Sample Web application page using BE4WS (before invocation)
Listing 1. HTML for the BE4WS invocation servlet

<font size="5"><b><font face="Rockwell">
The Aggregation of Configurable BE4WS</font><br>

<form action="" method="POST">
<table border="1" width="50%" bordercolor="#800000">
    <td width="45%"><font color="#000080"><b>1. Specify the URL of Your USML 
(Search Criteria)</b><br>
      <INPUT TYPE="text" name="USMLFileURL" 
      <p><font color="#000080"><b>2. Select Your Presentation Template <br>
<input type="text" name="ReturnURL" 
      <p><font color="#000080"><b>3. Invoke Business Explorer for 
Web Services<br>
      <INPUT TYPE="Submit" Value="BE4WS">
    <td width="32%" bgcolor="#CCFF99"> 


The USML script in Listing 2 is at the URL used as our first input parameter. It indicates that the user wants to search in two private UDDI registries, wsbi10 and wsbi5. We want to get all the service providers with names starting with "UPS" from wsbi10 or with names including "KEPEX" from wsbi5. You should be able to get a sense of how USML works just by examining the code in Listing 2; you can find links to information about the DTD for USML and instructions for writing USML documents in the Resources section.

Listing 2. USML script for searching two UDDI registries
<?xml version="1.0"?>
<!DOCTYPE Search SYSTEM "UDDISearch.dtd">
    <Source>Private UDDI</Source>
    <Source>Public UDDI</Source>

After creating a USML script, you can use the general invocation servlet in Listing 3 to invoke the BE4WS SOAP service, which in our example is deployed on WebSphere Application Server 4.0. Note that the behavior of BE4WS can be modified by using a different USML script. The location of the USML script can be dynamically changed by assigning a different value for USMLFileURL (see Figure 2).

Listing 3. BE4WS invocation servlet
public class BE4WS extends javax.servlet.http.HttpServlet {
  public void performTask(
    javax.servlet.http.HttpServletRequest request,
    javax.servlet.http.HttpServletResponse response) {
    String USMLresponse = null;
    String USMLFileURL = request.getParameter("USMLFileURL");
    String ReturnURL = request.getParameter("ReturnURL");
    try {
      // Construct a URL, you need to modify it
      //USML_URL = "";
      String encodingStyleURI = Constants.NS_URI_SOAP_ENC;
      // provides your own URL of RPC Router Servlet
      URL url = new URL("");
      // Construct the SOAP call.
      Call call = new Call();
      Vector params = new Vector();
      params.addElement(new Parameter("meth1_inType1",String.class,USML_URL,null));
      // Invoke a SOAP service
      Response resp = call.invoke(url, "");
      // Parse the response.
      if (resp.generatedFault()) {Fault fault = resp.getFault();
    } else {
      Parameter result = resp.getReturnValue();
      USMLresponse = (String) result.getValue();
      System.out.println("The USML Response is:\n" + USMLresponse);}
      HttpSession session = request.getSession(true);
      session.setAttribute("USMLresponse", USMLresponse);
      // set the results page URL
      String url2 = null;
      if (ReturnURL != null) {url2 = ReturnURL;
      } else {
        url2 = "";}
        } catch (Throwable theException) {theException.printStackTrace();}

The BE4WS invocation servlet is called from the Web page shown in Figure 2. Of course, this general invocation servlet can be used in any Java applications or Windows applications by sending out a URL request. The response from BE4WS is a USML document containing the aggregated results, shown in Listing 4. From this response, you can get the basic information about the available business entities. If you want to get more details, you can fetch the content using the URL specified in the URL tag. For example, the location of a WSDL document can be retrieved in the same manner. Then you can construct a web service call based on the retrieved WSDL.

Listing 4. USML response from BE4WS
<?xml version="1.0"?>
        <Description>USA. UPS, or United Parcel Service Inc., is a 93-year-old 
			company whose history spans the bicycle to the Internet. Today the 
			largest express carrier and largest package carrier in the world, 
			UPS continues to develop the frontiers of logistics.
        <BusinessName>KEPEX Fulfillment Center</BusinessName>

To parse this USML document, use the parsing code in Listing 5. Here, we use IBM XML parser for Java code, but the code can be easily modified to use other parsers. You can adapt this code for your own applications.

Listing 5. Parsing code for USML response
String USMLresponse = (String) session.getAttribute("USMLresponse");
Vector nameVec = new Vector();
Vector keyVec = new Vector();
Vector descriptionVec = new Vector();
Vector urlVec = new Vector();
Vector operatorVec = new Vector();
try {
  byte[] USMLresByteArray = USMLresponse.getBytes();
  String stest = new String(USMLresByteArray);
  ByteArrayInputStream bstream = new ByteArrayInputStream(USMLresByteArray);
  InputSource is = new InputSource((InputStream) bstream);
  NonValidatingTXDOMParser nvparser = new NonValidatingTXDOMParser();
  Document doc = nvparser.getDocument();
  NodeList storylist = doc.getElementsByTagName("USMLResponse");
  for(int at =0; at < storylist.getLength(); at++) {
    TXElement entryEle = (TXElement) storylist.item(at);
    NodeList contEle = entryEle.getElementsByTagName("Business");
    for(int i=0; i<contEle.getLength(); i++) {
      TXElement AttrEle = (TXElement) contEle.item(i);
      NodeList nameEle = AttrEle.getElementsByTagName("BusinessName");
      for(int j=0; j<nameEle.getLength(); j++) {
        TXElement AttrNameEle = (TXElement)nameEle.item(j);
        String sContent = AttrNameEle.getText();
      NodeList keyEle = AttrEle.getElementsByTagName("BusinessKey");
      for(int j=0; j<keyEle.getLength(); j++) {
        TXElement AttrKeyEle = (TXElement)keyEle.item(j);
        String sContent = AttrKeyEle.getText();
      NodeList descriptionEle = AttrEle.getElementsByTagName("Description");
      for(int j=0; j<descriptionEle.getLength(); j++){
        TXElement AttrDesEle = (TXElement)descriptionEle.item(j);
        String sContent = AttrDesEle.getText();
      NodeList urlEle = AttrEle.getElementsByTagName("URL");
      for(int j=0; j<urlEle.getLength(); j++){
        TXElement AttrURLEle = (TXElement)urlEle.item(j);
        String sContent = AttrURLEle.getText();
      NodeList operatorEle = AttrEle.getElementsByTagName("Operator");
      for(int j=0; j<operatorEle.getLength(); j++) {
        TXElement AttrOperatorEle = (TXElement)operatorEle.item(j);            
        String sContent = AttrOperatorEle.getText();
}catch (Exception e) {
  System.out.println("Exception in parser : " + e.getMessage());

The JSP code in Listing 6 will create a human-readable business entity list based on the USML response from BE4WS. The USML response (Listing 4) to the invocation servlet in Listing 3 is passed to this JSP, which then invokes the parsing code in Listing 5 to parse the USML response and present the final result in a structured way. Remember, we specified this JSP by entering its URL as the second of our two parameters in Figure 2 above. Figure 3 shows the output of the JSP code.

Listing 6. JSP code for creating a business list
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<%@ page language="java" import="java.util.Vector" %>
<%@ page import="java.util.*" %>
<%@ page import="*" %>
<%@ page import="java.lang.*" %>
<%@ page import="org.xml.sax.*" %>
<%@ page import="org.w3c.dom.*" %>
<%@ page import="*" %>
<%@ page import="*" %>
<%@ page import="*" %>
<META name="GENERATOR" content="IBM WebSphere Page Designer">
<META http-equiv="Content-Style-Type" content="text/css">
<title>BE4WS Aggregation Result</title></head>
<body bgcolor="#FFFFFF" text="#000000" link="#000099" 
  vlink="#000099" alink="#CC0000">
// See Listing 5
<B><FONT face="Verdana, Arial, Helvetica, sans-serif" 
  color="#000099" size="3">
BE4WS Aggregation Result-> Business List<p></FONT></B><p>
<TABLE border="1" cellspacing="1" cellpadding="1">
<TD bgcolor="#FFCC00"><b>Business:</b>     </TD>  
<TD bgcolor="#FFCC00"><b>Description:</b>     </TD>  
<TD bgcolor="#FFCC00"><b>Key:</b>     </TD>  
<TD bgcolor="#FFCC00"><b>Operator:</b>     </TD>  
System.out.println("size" + keyVec.size());
for(int i=0; i<keyVec.size(); i++)
  String sName = (String)nameVec.elementAt(i);
  String sKey = (String)keyVec.elementAt(i);
  String sDescription = (String)descriptionVec.elementAt(i);
  String sURL = (String)urlVec.elementAt(i);
  String sOperator = (String)operatorVec.elementAt(i);
<TD> <%=sName%></TD>
<TD> <%=sDescription%></TD>
<TD><a href="<%=sURL%>"> <%=sKey%></a> </TD>
<TD> <%=sOperator%></TD>
<% } // for loop %>
Figure 3. Sample Web application page using BE4WS (after invocation)
Sample Web application page using BE4WS (after invocation)


With the emergence of interoperable web services published in the UDDI registry, businesses with the means to describe their services in a global environment to potential trading partners should have a way to discover and interact with each other. Users must be able to find proper web services with less effort than currently required. UDDI Search Markup Language (USML) aids in an efficient search by considering multiple queries for the desired search from individual or multiple business registries. We propose this XML-based language to make uniform the UDDI search query format and dramatically reduce request times in a search. A USML-based search request incorporates multiple search queries, UDDI sources, and an aggregation operator. We hope that USML and BE4WS make using web services easier and will free developers to unlock the potential of web services technology.


  • Download the BE4WS distribution from alphaWorks and try out the easier samples. This will give you a first-hand example of the different search criteria supported by BE4WS and its advantages over UDDI4J or other UDDI clients.
  • The BE4WS package includes instructions for writing USML; you can also find that information at the XML Cover Pages site.
  • Future versions of the Web Services Toolkit will include a USML parser; check this site for updates.
  • Take a look at UDDI4J, which provides full support of version 2 of the UDDI specification.
  • Learn more about Web Services Inspection Language, which provides an XML format for assisting in the inspection of a site for available services and a set of rules that define inspection-related information should be made available for consumption.
  • IBM hosts a UDDI version 2 registry with a graphical user interface and conformant APIs for public use.
  • The IBM WebSphere UDDI Registry enables developers to explore the possibilities of building web services registries -- both within and across enterprises.
  • Know more about the SOAP specification.


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into SOA and web services on developerWorks

Zone=SOA and web services
ArticleTitle=Aggregate UDDI searches with Business Explorer for web services