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:
Decide on classification scheme (taxonomy)
Build a classification within a particular classification scheme
Specify the classification as an argument to the findOrganizations method
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:
A Name object
A Description object
A Key object, representing the ID by which the organization is known to the registry
A PrimaryContact object, which is a User object that refers to an authorized user of the registry. A User object normally includes a PersonName object and collections of TelephoneNumber and EmailAddress objects.
A collection of Classification objects
Service objects and their associated ServiceBinding objects
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:
Use BusinessQueryManager to find the taxonomy to which the organization wants to belong to
Create a classification using the classification scheme and a concept (a taxonomy element) within the classification scheme
Add the classification to the organization
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:
The North American Industry Classification System (NAICS)
http://www.census.gov/epcd/www/naics.html
Universal Standard Products and Services Classification (UNSPSC)
http://www.eccma.org/unspsc/
ISO 3166 country codes classification system maintained by the International Organization for Standardization (ISO)
http://www.iso.org/iso/en/prods-services/iso3166ma/index.html
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."); } }
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |