Discover and publish Web services with JAXR

The Java API for XML Registries allows registry operations over diverse registry providers

1 2 3 Page 2
Page 2 of 3

Also specializations of the RegistryObject interface, the concrete interfaces Organization, Service, ServiceBinding, Concept, and ClassificationScheme provide additional state information. For example, the Organization interface defines a collection of Services, and Service defines a collection of ServiceBindings. A ServiceBinding might contain a collection of SpecificationLinks. UDDI developers should be familiar with these concrete interfaces; they map quite well to the five major UDDI data types shown in the table below.

UDDI-to-JAXR information model mappings
JAXR Information ModelUDDI Data Model
Organization BusinessEntity
Service BusinessService
ServiceBinding BindingTemplate
ClassificationScheme TModel
Concept TModel
Association PublisherAssertion

The JAXR specification defines the following information model interfaces:

  • Organization instances are RegistryObjects that provide information on an organization that has been published to the underlying registry.
  • Service instances are RegistryObjects that provide information on services (e.g., Web services) offered by an Organization. An Organization can have a set of Services.
  • ServiceBinding instances are RegistryObjects that represent technical information on how to access a specific interface offered by a Service instance. A Service can have a collection of ServiceBindings.
  • A SpecificationLink links a ServiceBinding with its technical specifications that describe how to use the service. For example, a ServiceBinding might have SpecificationLink instances that describe how to access the service using a technical specification in the form of a WSDL (Web Services Description Language) document or a CORBA IDL (interface definition language) document.
  • A ClassificationScheme instance represents a taxonomy that you can use to classify or categorize RegistryObject instances.
  • Classification instances classify a RegistryObject instance using a classification scheme. Because classification facilitates rapid discovery of RegistryObjects within the registry, the ability to classify RegistryObjects in a registry is one of the registry's most significant features.
  • A Concept instance represents an arbitrary notion, or concept. It can be virtually anything.
  • Association instances define many-to-many associations between objects in the information model.
  • RegistryPackage instances group together logically related RegistryObjects. A RegistryPackage might contain any number of RegistryObjects, and a RegistryObject can be a member of any number of RegistryPackages.
  • ExternalIdentifier instances provide identification information to a RegistryObject. You can base such identification on well-known identification schemes such as DUNS (D&B's Data Universal Numbering System) number and social security number.
  • ExternalLink instances provide a link to content managed outside the registry using a URI (uniform resource identifier).
  • Slot instances dynamically add arbitrary attributes to RegistryObject instances at runtime, an ability that enables extensibility within the information model.
  • Most interfaces in the JAXR information model implement the ExtensibleObject interface. It provides methods that allow the addition, deletion, and lookup of Slot instances.
  • AuditableEvent instances are RegistryObjects that provide an audit trail for RegistryObjects.
  • Affiliated with Organizations, User instances are RegistryObjects that provide information about registered users within the registry. You use User objects in a RegistryObject's audit trail.
  • PostalAddress defines a postal address's attributes. Currently, it provides address information for a User and an Organization.

Develop with JAXR

Now that you've learned the technical details, let's start developing with the API. In the following sections, we present several coding examples that complete the following tasks:

  • Establish a connection between a JAXR client and JAXR provider
  • Registry operation: Find an organization
  • Registry operation: Get organization details
  • Registry operation: Publishing

Establish a connection between a JAXR client and JAXR provider

As mentioned previously, the JAXR client must first connect to the JAXR provider. This connection contains the client state and preference information used when the JAXR provider invokes methods on the registry provider.

Before executing any registry operation, a JAXR client connects with a JAXR provider as shown in the following code. If the JAXR client wishes to submit data to the registry, the client must set authentication information on the connection. Note that the establishment of this authentication information with the registry provider is registry-provider specific and negotiated between the registry provider and the publishing user, often in the form of a Web-based interface. Note: The user does not use the JAXR API to negotiate and establish an account with the registry provider. After establishing a connection, the JAXR client can obtain RegistryService interfaces for Web services discovery and publishing. Those familiar with UDDI will recognize that this example obtains the business-focused APIs, the BusinessLifeCycleManager and the BusinessQueryManager, to perform registry operations shown in later examples:

/** * Establish a connection to a JAXR provider.
 *         Set authentication information, communication preference.
 *         Get business-focused discovery and publish interfaces. 
public void makeConnection() {
   // URLs for RegistryServer included in Java Web Services Developer Pack
   String queryURL ="http://localhost:8080/registry-server/RegistryServerServlet";
   String publishURL ="http://localhost:8080/registry-server/RegistryServerServlet";
   * Define connection configuration properties.
   * For simple queries, you need the query URL.
   * To use a life-cycle manager, you need the publish URL.
   Properties props = new Properties();
   props.setProperty("javax.xml.registry.queryManagerURL", queryUrl);
   props.setProperty("javax.xml.registry.lifeCycleManagerURL", publishUrl);
   try {
        // Create the connection, passing it the configuration properties
       ConnectionFactory factory = ConnectionFactory.newInstance();
       connection = factory.createConnection();
       System.out.println("Created connection to registry");
       // Get registry service and managers
       RegistryService rs = connection.getRegistryService();
       // Get the capability profile
       CapabilityProfile capabilityProfile = registryService.getCapabilityProfile();
       if (capabilityProfile.getCapabilityLevel() == 0)
 System.out.println("Capability Level 0, Business Focused API");
       // Get manager capabilities from registry service
       BusinessQueryManager bqm = rs.getBusinessQueryManager();
       BusinessLifeCycleManager blcm = rs.getBusinessLifeCycleManager();
       System.out.println("Got registry service, query " + "manager, and lifecycle manager");
       // Set client authorization information for privileged registry operations
       PasswordAuthentication passwdAuth = new PasswordAuthentication(username, password.toCharArray());
       Set creds = new HashSet();
       // Set credentials on the JAXR provider 
       System.out.println("Established security credentials");
      // Set communication preference
  } catch (Exception e) {
      if (connection != null) {
         try {
         } catch (JAXRException je) {}

Registry operation: Find an organization

Now that the JAXR client has established a connection with the JAXR provider and obtained the BusinessQueryManager and BusinessLifeCycleManager from the RegistryService interface, the client can now invoke methods on these interfaces. Often, a JAXR client will wish to discover the services an organization offers. To do so, the JAXR client would invoke methods on the BusinessQueryManager. An example use case might be the following:

A user browsing the UDDI registry wishes to find an organization that provides services of the NAICS (North American Industry Classification System) type Computer Systems Design and Related Services in the United States. To perform this query with JAXR, the user would invoke a findOrganization() method with classification listed under the well-known taxonomies NAICS and ISO 3166 Geographic Code System (ISO 3166). As JAXR provides a taxonomy service for these classifications, the client can easily access the classification information needed to be passed as findOrganization() parameters. A sample of this query to the taxonomy service and registry follows below:

public void findOrganizations()
throws JAXRException {
    // Search criteria -- Organizations found will return in this sort order
    Collection findQualifiers = new ArrayList();
    // Query the JAXR taxonomy service
    ClassificationScheme naics =      businessQueryManager.findClassificationSchemeByName(findQualifiers, "ntis-gov:naics:1997"); 
    // Create the classification that will be a parameter to findOrganization() method
    Classification computerSystemsDesign = businessLifeCycleManager.createClassification
(naics, "Computer Systems Design and Related Services", "5415");
    // Query the taxonomy service
    ClassificationScheme geography = businessQueryManager.findClassificationSchemeByName
    // Create the classification passed as a parameter to findOrganization() method.
    Classification us = businessLifeCycleManager.createClassification(geography, 
"United States", "US"); 
    // Add classifications to the classifications collection parameter
    Collection classifications = new ArrayList();
    // Invoke the findOrganizations() method on BusinessQueryManager
    BulkResponse bulkResponse = businessQueryManager.findOrganizations(findQualifiers, null, classifications, null, null, null);
    if (bulkResponse.getStatus() == JAXRResponse.STATUS_SUCCESS) {
             System.out.println("Found Organization located in the United States 
categorized Computer Systems Design and Related Service");

Most calls invoked on the registry provider via the JAXR provider return a BulkResponse that contains any registry exceptions encountered and a collection of concrete RegistryObjects or RegistryObject keys. To ensure that a registry invocation always returns a response, any exceptions generated by the registry provider are wrapped in a RegistryException and stored in the BulkResponse's exceptions collection. In the case of find methods, any RegistryObjects found are contained in the BulkResponse collection.

Registry operation: Get organization details

For the above findOrganization() method, the BulkResponse contains a collection of Organizations found in the registry provider that match the classifications passed as parameters to the method. However, these Organizations provide limited information about the Organization and its Services such as key, name, and description. Another value-added feature of JAXR is the incremental loading of RegistryObject details. For instance, in the case of a JAXR UDDI provider, a JAXR findOrganization() method transforms to a UDDI find_Business request. After invocation, the find_Business request returns minimal business and service information such as ID, name, and description. Using UDDI APIs, a UDDI client would need to make an additional call such as get_BusinessDetail() to retrieve the organization details. With JAXR, the JAXR UDDI provider performs this invocation to the registry provider on an as-needed basis. The JAXR client can access Organization and other RegistryObject details by using the get methods on the JAXR information model interfaces. The getOrganizationDetail() method demonstrates how a JAXR client would obtain full Organization details:

1 2 3 Page 2
Page 2 of 3