Establish a connection between a JAXR client and JAXR provider

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:

import javax.xml.registry.*;
...
// Get an instance of ConnectionFactory object
ConnectionFactory connFactory = ConnectionFactory.newInstance();

// Define connection configuration properties
// Set URLs of the query service and publishing service
Properties props = new Properties();
props.setProperty("javax.xml.registry.queryManagerURL", "http://uddi.ibm.com/testregistry/inquiryapi");
props.setProperty("javax.xml.registry.lifeCycleManagerURL", "https://uddi.ibm.com/testregistry/protect/publishapi");	

// If JAXR client goes outside firewall for query, set up HTTP proxy
props.setProperty("com.sun.xml.registry.http.proxyHost", "myhost.mydomain");
props.setProperty("com.sun.xml.registry.http.proxyPort", "8080");

// If JAXR client goes outside firewall for update, set up HTTPS proxy
props.setProperty("com.sun.xml.registry.https.proxyHost", "myhost.mydomain");
props.setProperty("com.sun.xml.registry.https.proxyPort", "8080");

// Set up properties and create Connection object
connFactory.setProperties(props);
Connection connection = connFactory.createConnection();				
					

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. 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:

// Get RegistryService object
RegistryService rs = connection.getRegistryService();

// Get QueryManager and LifeCycleManager objects for
// JAXR Business API (Capability Level 0 - UDDI oriented)
BusinessQueryManager bqm = rs.getBusinessQueryManager(); 
BusinessLifeCycleManager blcm = rs.getBusinessLifeCycleManager();					
					

This example also demonstrates how to obtain the business-focused interfaces, 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 
	String queryURL = "http://localhost/RegistryServerServlet";
	String publishURL = "http://localhost/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();
		factory.setProperties(props);
		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();
		creds.add(passwdAuth);

		// Set credentials on the JAXR provider 
		connection.setCredentials(creds);
		System.out.println("Established security credentials");

		// Set communication preference
		connection.setSynchronous(true);

	} catch (Exception e) {
		e.printStackTrace();
		if (connection != null) {
			try {
				connection.close();
			} catch (JAXRException je) {
			}
		}
	}
}
					

Registry operation: execute queries to locate services

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.

JAXR defines top-level interface for query management called QueryManager. There are two extensions of QueryManager interface and they are called BusinessQueryManager and DeclarativeQueryManager. Interface BusinessQueryManager provides a simple business-level API that provides the ability to query for the most important high-level interfaces in the information model.

Interface DeclarativeQueryManager provides a more flexible generic API that provides the ability to perform ad hoc queries using a declarative query language syntax. Currently the only declarative syntax supported is SQL-92. In version 1 of JAXR, it is optional for a JAXR provider to provide support for SQL query syntax.

This example shows how to find all the organizations in the registry whose names begin with a specified string, qString, and to sort them in alphabetical order:

// Define find qualifiers. Sort by name.
Collection findQualifiers = new ArrayList();
findQualifiers.add(FindQualifier.SORT_BY_NAME_DESC);

// Define name patterns. Organization name begins with qString.
Collection namePatterns = new ArrayList();
namePatterns.add(qString);

// Find organizations using the name
BulkResponse response = bqm.findOrganizations(findQualifiers, namePatterns, null, null, null, null);
Collection orgs = response.getCollection();
					

Another example shows how to find all the organizations in the registry using case sensitive name pattern:

					
// Define find qualifiers. Do case sensitive search.
Collection findQualifiers = new ArrayList();
findQualifiers.add(FindQualifier.CASE_SENSITIVE_MATCH);

// Define name patterns. Organization name contains qString.
Collection namePatterns = new ArrayList();
namePatterns.add("%" + qString + "%");

// Find organizations using the name
BulkResponse response = bqm.findOrganizations(findQualifiers, namePatterns, null, null, null, null);
Collection orgs = response.getCollection();					

					

Steps for finding Organization by Classification:

To find organizations by classification, 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:

// Get classification scheme. Taxonomy is NAICS.
ClassificationScheme cScheme = bqm.findClassificationSchemeByName(null, "ntis-gov:naics");

// Build classifications
Classification classification = blcm.createClassification(cScheme, 
	"Snack and Nonalcoholic Beverage Bars", "722213");
Collection classifications = new ArrayList();
classifications.add(classification);

// Find organizations via Classification
BulkResponse response = bqm.findOrganizations(null, null, classifications, null, null, null);
Collection orgs = response.getCollection();					
					

To find WSDL Specification Instances: use classification scheme of "uddi-org:types". In JAXR, a concept is used to hold information about a WSDL specification. JAXR client must find the specification concepts first, then the organizations that use those concepts. Once you get organizations, you can then get services and bindingTemplates:

// Get classification scheme. Taxonomy is uddi-org:types.
String schemeName = "uddi-org:types";
ClassificationScheme uddiOrgTypes = bqm.findClassificationSchemeByName(null, schemeName);

// Create a classification, specifying the scheme
// and the taxonomy name and value defined for WSDL
// documents by the UDDI specification.
Classification wsdlSpecClassification = blcm.createClassification(uddiOrgTypes, "wsdlSpec", "wsdlSpec");
Collection classifications = new ArrayList();
classifications.add(wsdlSpecClassification);

// Find concepts
BulkResponse br = bqm.findConcepts(null, null, classifications, null, null);

// Display information about the concepts found
Collection specConcepts = br.getCollection();
Iterator iter = specConcepts.iterator();
if (!iter.hasNext()) { 
	System.out.println("No WSDL specification concepts found");
} else {
	while (iter.hasNext()) {
		Concept concept = (Concept) iter.next();
		String name = getName(concept);
		Collection links = concept.getExternalLinks();
		System.out.println("Specification Concept: Name: " + name +
			"Key: " + concept.getKey().getId() + "Description: " + getDescription(concept));
		if (links.size() > 0) {
			ExternalLink link = (ExternalLink) links.iterator().next();
			System.out.println("URL of WSDL document: '" + link.getExternalURI() + "'");
		}
		
		// Find organizations that use this concept
		Collection specConcepts1 = new ArrayList();
		specConcepts1.add(concept);
		br = bqm.findOrganizations(null, null, null, specConcepts1, null, null);
		// Display information about organizations
		...
	}
}
					

Finding Services and Service Bindings from Organization:

Iterator orgIter = orgs.iterator();
while (orgIter.hasNext()) {
	Organization org = (Organization) orgIter.next();
	Collection services = org.getServices();
	Iterator svcIter = services.iterator();
	while (svcIter.hasNext()) {
		Service svc = (Service) svcIter.next();
		Collection serviceBindings = svc.getServiceBindings();
		Iterator sbIter = serviceBindings.iterator();
		while (sbIter.hasNext()) {
			ServiceBinding sb = (ServiceBinding) sbIter.next();
		}
	}
}					
					

Another 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();
	findQualifiers.add(FindQualifier.SORT_BY_NAME_DESC);

	// 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(
		findQualifiers, "iso-ch:3166:1999");

	// 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();
	classifications.add(computerSystemsDesign);
	classifications.add(us);

	// 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	");
		System.out.println("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 RegistryObject instances 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 findXXX(...) methods, any RegistryObjects found are contained in the BulkResponse collection.

For the above findOrganization() method, the BulkResponse contains a collection of Organization objects found in the registry provider that match the classifications passed as parameters to the method. However, these Organization objects provide limited information about the Organization and its Service objects 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 getXXX() methods on the JAXR information model interfaces. The getOrganizationDetail() method demonstrates how a JAXR client would obtain full Organization details:

public void getOrganizationDetail(BulkResponse bulkResponse) throws JAXRException {

  // Get a collection of Organizations from BulkResponse
  Collection organizations = bulkResponse.getCollection();
	
  // Iterate through the collection to get an individual Organization
  Iterator orgIter = organizations.iterator();
	
  while (orgIter.hasNext()) {
    Organization organization = (Organization) orgIter.next();
	
    // Get a collection of Services from an Organization
    Collection services = organization.getServices();
	
    // Iterate through the collection to get an individual Service
    Iterator serviceIter = services.iterator();
	
    while (serviceIter.hasNext()) {
      Service service = (Service) serviceIter.next();

      // Get a collection of ServiceBindings from a Service
      Collection serviceBindings = service.getServiceBindings();
	
      // Iterate through the collection to get an individual ServiceBinding
      Iterator sbIter = serviceBindings.iterator();
      while (sbIter.hasNext()) {
        ServiceBinding serviceBinding = (ServiceBinding) sbIter.next();

        // Get URI of the service.  You can access the service through this URI.
        String accessURI = serviceBinding.getAccessURI();
        System.out.println("Access the service " + service.getName().getValue() 
          + " at this URI " + accessURI);

        // Get a collection of SpecificationLinks from a ServiceBinding. 
        // SpecificationLinks provide further technical details needed to access the service.
        Collection specificationLinks = serviceBinding.getSpecificationLinks();
	
        // Iterate through the collection to get an individual SpecificationLink
        Iterator linkIter = specificationLinks.iterator();
        while (linkIter.hasNext()) {
          SpecificationLink specificationLink = (SpecificationLink) linkIter.next();

          // Get a collection of ExternalLinks from SpecificationLink 
          // An ExternalLink points to technical detail necessary to invoke the service
          Collection externalLinks = specificationLink.getExternalLinks();
	
          // Iterate through the collection to get an ExternalLink
          Iterator elinkIter = externalLinks.iterator();
          while (elinkIter.hasNext()) {
            ExternalLink externalLink = (ExternalLink) elinkIter.next();
            
            // The externalURI is the pointer to the technical details 
            // necessary to invoke the service
            String externalURI = externalLink.getExternalURI();
            System.out.println(
              " Use the technical detail at this URI,	" 
              + externalURI + " to invoke the service, "  +
              + service.getName().getValue());
          
          }

          // Obtain usage description
          InternationalString usageDescription = specificationLink.getUsageDescription();
          
          // Any parameters necessary to invoke service are in usageParameter collection
          Collection usageParameters = specificationLink.getUsageParameters();
          
          // Get the specification concept from the specification link
          // This specificationConcept is equivalent to the tModel registered as 
          // the technical specification
          Concept specificationConcept = (Concept) specificationLink.getSpecificationObject();
        }
      }
    }
  }
}					
					

Registry operation: publish or update information about a business service

The JAXR client also publishes Web services, another important registry operation. In addition to discovering partner organization information and services, an organization will want to register its information and services in the registry for partner use. If a JAXR client wishes to publish an organization and its services to a registry, the client uses the LifeCycleManager or the more focused BusinessLifeCycleManager. Clients familiar with UDDI should use the BusinessLifeCycleManager, which provides methods for saving information to the registry provider. Since this is a privileged operation, the user must set authentication information on the JAXR connection. Note that the JAXR provider, not the JAXR client, performs authentication with the registry provider. The JAXR provider negotiates this authentication with the registry provider on an as-needed basis, and the authentication is completely transparent to the JAXR client.

JAXR specification defines two interfaces – LifeCycleManager interface and BusinessLifeCycleManager interface. LifeCycleManager interface provides complete support for all life cycle management needs using a generic API. BusinessLifeCycleManager interface defines a simple business-level API for life cycle management of some important high-level interfaces in the information model. This interface provides no new functionality beyond that of LifeCycleManager. The goal of defining this interface is to provide an API similar to that of the publisher’s API in UDDI. The intent is to provide a familiar API to UDDI developers.

Before it can submit data, the client must send its username and password to the registry in a set of credentials. The following code fragment shows how to do this:

// Set userid/password
String username = "myUserName";
String password = "myPassword";

// Create authentication object
PasswordAuthentication passwdAuth = new PasswordAuthentication(username, password.toCharArray());

// Set the credential with registry provider
Set creds = new HashSet();
creds.add(passwdAuth);
connection.setCredentials(creds);					
					

The client creates the organization and populates it with data before saving it. An Organization object is one of the more complex data items in the JAXR API. It normally includes the following:

Creating an Organization:

// Create organization name and description
Organization org = blcm.createOrganization("The Coffee Break");
InternationalString s = blcm.createInternationalString("Purveyor of the finest coffees");
org.setDescription(s);

// Create primary contact, set name
User primaryContact = blcm.createUser();
PersonName pName = blcm.createPersonName("Jane Doe");
primaryContact.setPersonName(pName);

// Set primary contact phone number
TelephoneNumber tNum = blcm.createTelephoneNumber(); 
tNum.setNumber("(800) 555-1212");
Collection phoneNums = new ArrayList();
phoneNums.add(tNum); 
primaryContact.setTelephoneNumbers(phoneNums);

// Set primary contact email address
EmailAddress emailAddress = blcm.createEmailAddress("jane.doe@TheCoffeeBreak.com");
Collection emailAddresses = new ArrayList();
emailAddresses.add(emailAddress); 
primaryContact.setEmailAddresses(emailAddresses);

// Set primary contact for organization
org.setPrimaryContact(primaryContact);					
					

Steps of Adding Classification:

Example of Adding Classification to Organization:

// Set classification scheme to NAICS
ClassificationScheme cScheme = bqm.findClassificationSchemeByName(null, "ntis-gov:naics");

// Create and add classification
Classification classification = blcm.createClassification(cScheme, "Snack and Nonalcoholic Beverage Bars", "722213");
Collection classifications = new ArrayList();
classifications.add(classification);
org.addClassifications(classifications);					
					

JAXR Provider Must Provide Taxonomies of:

Suppose the organization "Fly Away Airline Travel Agents" has a Web-based airline reservation service that its partner travel agencies must be able to use. The following code creates such a business and saves it to the registry. The business has contact information, a set of services it offers, and technical information for accessing those services:

public void saveOrganization() throws JAXRException {

	// Create Organization in memory
	Organization org = businessLifeCycleManager.createOrganization("Fly Away Airline Travel Agents");

	// Create User -- maps to Contact for UDDI
	User user = businessLifeCycleManager.createUser();
	PersonName personName = businessLifeCycleManager.createPersonName("Marie A Traveler");

	TelephoneNumber telephoneNumber = businessLifeCycleManager.createTelephoneNumber();
	telephoneNumber.setNumber("781-333-3333");
	telephoneNumber.setType("office");
	Collection numbers = new ArrayList();
	numbers.add(telephoneNumber);

	EmailAddress email = businessLifeCycleManager.createEmailAddress("marieb@airlinetravel.com", "office");
	Collection emailAddresses = new ArrayList();
	emailAddresses.add(email);

	user.setPersonName(personName);
	Collection telephoneNumbers = new ArrayList();
	telephoneNumbers.add(telephoneNumber);
	user.setTelephoneNumbers(telephoneNumbers);
	user.setEmailAddresses(emailAddresses);
	org.setPrimaryContact(user);

	// Create service with service name and description
	Service service = businessLifeCycleManager.createService("Fly Away Airline Reservation Service");
	service.setDescription(businessLifeCycleManager.createInternationalString("Flight Reservation Service"));

	// Create serviceBinding
	ServiceBinding serviceBinding = businessLifeCycleManager.createServiceBinding();
	serviceBinding.setDescription(businessLifeCycleManager.
		createInternationalString("Information for airline reservation service access"));

	//Turn validation of URI off
	serviceBinding.setValidateURI(false);
	serviceBinding.setAccessURI("http://www.airlinetravel.com:8080/services.reservations.html ");

	// Create the SpecificationLink information
	SpecificationLink specificationLink = businessLifeCycleManager.createSpecificationLink();

	// Set usage description
	specificationLink.setUsageDescription(businessLifeCycleManager.
		createInternationalString("Search for Reservations when prompted"));
	String usageParameter = "Enter travel agent id when prompted";
	Collection usageParameters = new ArrayList();
	usageParameters.add(usageParameter);

	// Set usage parameters
	specificationLink.setUsageParameters(usageParameters);

	// Set specificationConcept on the specificationLink
	Concept httpSpecificationConcept = 
		(Concept) businessLifeCycleManager.createObject(businessLifeCycleManager.CONCEPT);
	Key httpSpecificationKey = 
		businessLifeCycleManager.createKey("uuid:68de9e80-ad09-469d-8a37-088422bfbc36");
	httpSpecificationConcept.setKey(httpSpecificationKey);
	specificationLink.setSpecificationObject(httpSpecificationConcept);

	// Add the specificationLink to the serviceBinding
	serviceBinding.addSpecificationLink(specificationLink);

	// Add the serviceBinding to the service
	service.addServiceBinding(serviceBinding);

	// Add the service to the organization
	org.addService(service);

	// Add classifications to the organization
	ClassificationScheme naics = 
		businessQueryManager.findClassificationSchemeByName(null, "ntis-gov:naics");
	Classification classification = 
		businessLifeCycleManager.createClassification(naics, "Air Transportation", "481");
	org.addClassification(classification);
	Collection orgs = new ArrayList();
	orgs.add(org);

	// Save organization and whole tree of related objects
	BulkResponse br = businessLifeCycleManager.saveOrganizations(orgs);
	
	if (br.getStatus() == JAXRResponse.STATUS_SUCCESS) {
		System.out.println("Successfully saved the organization  to the registry provider.");
	}
}