This Tech Tip reprinted with permission by

The Java API for XML Registries (JAXR) provides a convenient way to access standard business registries over the Internet. Business registries contain information that allows businesses to discover and use services provided by potential corporate partners. Typically, a business registers itself with a registry, or uses a registry to discover other businesses with which they might want to interact. This Tech Tip, which is based on a simple JAXR example provided in the Java Web Services Developer Pack 1.5 and also described in the J2EE 1.4 Tutorial, shows how the JAXR API can be used by a Java client application to access a business registry on the Internet.

A business registry is really a dedicated form of XML registry, it's a neutral third-party infrastructure that facilitates dynamic and loosely coupled business-to-business (B2B) interactions. These interactions typically follow one of two standards:

    • The ebXML Registry and Repository standard, which is sponsored by the Organization for the Advancement of Structured Information Standards (OASIS) and the United Nations Centre for the Facilitation of Procedures and Practices in Administration, Commerce and Transport (U.N./CEFACT).
    • The Universal Description, Discovery, and Integration (UDDI) project, which is being developed by a vendor consortium.

A registry provider is an entity that provides an implementation of a business registry that conforms to one of these standards.

JAXR Architecture

JAXR can be used on either side of a B2B interaction. The JAXR API consists of two entities:

      • JAXR client. This is a client application that uses the JAXR API to access a business registry through a JAXR provider.
      • JAXR provider. This is a server-side implementation of the JAXR API that provides access to a one or more registry providers that are based on a common specification.

A JAXR client uses special interfaces within the JAXR API to access the JAXR provider. The JAXR provider then communicates with a registry.


Note that the latest JAXR reference implementation (JAXR 1.0.7) which is available in the Java Web Services Developer Pack 1.5, contains a JAXR provider for UDDI registries only, not ebXML. If you want more information on UDDI, visit the OASIS UDDI website.

According to the JAXR specifications, a provider must implement key interfaces in two packages:

      • javax.xml.registry. This consists of the API interfaces and classes that define the registry access interface.
      • javax.xml.registry.infomodel. This consists of interfaces that define the information model for JAXR. These interfaces define the types of objects that reside in a registry and how they relate to each other. The basic interface in this package is the RegistryObject interface. Its subinterfaces include Organization, Service, and ServiceBinding.

The javax.xml.registry package is particularly important because it contains a number of useful client interfaces:

      • Connection. This interface represents a client session with a registry provider. The client must create a connection with the JAXR provider to use a registry.
      • RegistryService. The client obtains a RegistryService object from its connection. The RegistryService object enables the client to obtain the interfaces it uses to access the registry, such as BusinessQueryManager and BusinessLifeCycleManager.
      • BusinessQueryManager. An object that implements this interface allows the client to search a registry for information in accordance with the javax.xml.registry.infomodel interfaces.
      • BusinessLifeCycleManager. An object that implements this interface allows the client to modify or delete the information in a registry.

Making the JAXR Connection

A JAXR client starts by creating an instance of the abstract class ConnectionFactory:

  import javax.xml.registry.*;
   ConnectionFactory connFactory = 

Next, the client creates a set of properties that specify the URL or URLs of the registry or registries being accessed. For example, the following code provides the URLs of the query service and publishing service for the IBM test registry:

  Properties props = new Properties();

You can specify proxy host and port information for the network on which the client is running, if needed (for example, if behind a firewall). For queries, the client might need to specify only the HTTP proxy host and port. For updates, the client typically also needs to specify a HTTPS proxy host and port:


The client then sets the properties for the connection factory and creates the connection:

   Connection connection = connFactory.createConnection(); 

After creating the connection, the client uses the connection to obtain a RegistryService object. It then uses the RegistryService to get objects that implement the appropriate query interfaces:

    RegistryService rs = connection.getRegistryService();
   BusinessQueryManager bqm = rs.getBusinessQueryManager();
   BusinessLifeCycleManager blcm = 

If a client need to both read and write data to a registry, it should obtain both a BusinessQueryManager object and a BusinessLifeCycleManager object from the RegistryService object. If the client is only performing simple queries, it typically needs only a BusinessQueryManager object.

Querying a Registry

The BusinessQueryManager interface supports a number of methods that allow clients to search for data. Many of these methods return a BulkResponse (a collection of objects) that meets a set of criteria specified in the method arguments. The most useful of these methods are:

      • findOrganizations. This method returns a list of organizations that meet the specified criteria--often a name pattern or a classification within a classification scheme.
           public BulkResponse findOrganizations(
                                               Collection findQualifiers,
                                               Collection namePatterns,
                                               Collection classifications,
                                               Collection specifications, 
                                               Collection externalIdentifiers,
                                               Collection externalLinks)
                                        throws JAXRException
      • findServices. This method returns a set of services offered by a specified organization.
           public BulkResponse findServices(Key orgKey,
                                                  Collection findQualifiers,
                                                  Collection namePatterns,
                                                  Collection classifications,
                                                  Collection specifications)
                                           throws JAXRException
      • findServiceBindings. This method returns the service bindings (information about how to access the service) that are supported by a specified service.
          public BulkResponse findServiceBindings(Key serviceKey,
                                                    Collection findQualifiers,
                                                    Collection classifications,
                                                    Collection specifications)
                                             throws JAXRException

To search for organizations by name, use a combination of find qualifiers and name patterns. The findOrganizations() method takes a collection of findQualifier objects as its first argument, and a collection of namePattern objects as its second argument. A client can use percent signs (%) to specify that the query string can occur anywhere within the organization name. For example, the following code fragment performs a case-sensitive search for organizations whose names contain the characters contained in qString:

  ArrayList qualifiers = new ArrayList();

   ArrayList names = new ArrayList();
   names.add("%" + qString + "%");

   BulkResponse response =
             qualifiers, names, null, null, null, null);

   Collection orgs = response.getCollection(); 

You can also find organizations by classification. To do that, you need to establish the classification within a particular classification scheme, and then specify the classification as an argument to the findOrganizations() method. The following code fragment finds all organizations that correspond to a particular classification within the North American Industry Classification System (NAICS) taxonomy.

ClassificationScheme cScheme =
   Classification classification =
       "Snack and Nonalcoholic Beverage Bars", "722213");
   Collection classifications = new ArrayList();
   BulkResponse response = bqm.findOrganizations(null,
     null, classifications, null, null, null);
   Collection orgs = response.getCollection(); 

After a client locates an organization, it can find that organization's services. There can be several ways to invoke a business service, and each invocation is described in UDDI by a binding template. ServiceBinding instances are RegistryObjects that map to UDDI binding templates, and represent technical information on how to invoke a service.

 Iterator orgIter = orgs.iterator();

   while (orgIter.hasNext()) {

     Organization org = (Organization);

     Collection services = org.getServices();

     Iterator svcIter = services.iterator();
     while (svcIter.hasNext()) {

       Service svc = (Service);
       Collection serviceBindings = 

       Iterator sbIter = serviceBindings.iterator();
        while (sbIter.hasNext()) {
         ServiceBinding sb = 


At this point, the source code must follow the standards for the registry type in question. So to continue the UDDI example, the developer could access the tModel information for the ServiceBinding and use it to obtain exact information on how to invoke the service.

For more information, about:

      • JAXR: see the JAXR page.
      • UDDI: see and the registry finder page. The servers that are listed on the registry finder page as "Inquiry API" and "Publish API" are the URLs that you would enter into the properties file in the source code to perform a successful JAXR connection. Note that you might have to register to obtain a username and password with the company hosting the UDDI server. This is also a good site to get information on low-level UDDI web service constructs, such as tModels.
      • EbXML: the EbXML Page.

Sample Code

The sample code for this Tech Tip uses JAXR to query a registry for organizations whose name matches the name pattern "%USA%".

To run the sample code:

      1. Download the sample archive for this Tech Tip.
      2. Download and install the JWSDP 1.5.
      3. Change to the directory where you downloaded the sample archive. Uncompress the JAR file for the sample archive as follows:
             jar xvf ttmar2005jaxr.jar 
      4. Add the following JWSDP 1.5 libraries to your CLASSPATH environment variable. The locations are given relative to the base directory (jwsdp-1.5):
      5. Compile the file.
      6. If you are behind a firewall, be sure to enter the appropriate proxy information inside the source code. Otherwise, the JAXR API will not be able to connect to the outside server.
      7. Run BusinessQueryTest:
                    java BusinessQueryTest
        You should see results that begin like this:
                  Successfully queried the registry for organization matching
                  the name pattern: "%USA%"
                  Results found: 3
                  Organization Name: USA-Works
                  Organization Key: 8cd1668c-64fa-4aa5-a053-bd0be4bd53f5
                  Organization Description: Liberty and Freedom
                       Service Name: Federal Government Service
                       Service Key: 056b2905-3999-4912-89de-fe79cbfedea0
                       Service Description: Services of the Federal Government

Copyright (c) 2004-2005 Sun Microsystems, Inc.
All Rights Reserved.