SCDJWS Study Guide: JAXR

Printer-friendly version | Mail this to a friend

Build a JAXR Client

The javax.xml.registry package contains the interfaces and classes for access to a registry through a JAXR provider:

ConnectionFactory : This is an abstract base class for factory classes that create a JAXR connection. Two important methods in ConnectionFactory are setProperties which is used to set the properties of a connection, and createConnection, which creates a connection.
Connection : This class represents a connection between a JAXR client and a JAXR provider.
RegistryService : This is the principal interface implemented by a JAXR provider. A registry client can get this interface through a Connection object. The RegistryService provides the methods that a JAXR client uses to discover various capability-specific interfaces implemented by the JAXR provider, such as the BusinessLifeCycleManager and BusinessQueryManager interfaces.
LifeCycleManager : This interface provides methods to perform "life cycle" operations on information in the registry, as modeled by objects in the information model. For example, the method createOrganization creates a new Organization object, and the method createService creates a new Service object.
BusinessLifeCycleManager : This is a subinterface of the LifeCycleManager interface. It provides a way to request life cycle management operations that mimic the UDDI interface. For example, the method saveOrganizations saves a collection of Organization objects in the registry, and the method deleteServices removes a collection of Service objects from a registry.
BusinessQueryManager : This interface provides methods to query the registry. For example, the method findOrganizations searches the registry for all organizations that match criteria specified in the method call.

Step 1: Obtain authorization for updates to the registry

Registry providers typically require a user to have proper authorization in order to update the contents of a registry. This means that a user typically needs to obtain a user ID and password from the registry provider, and then supply this authorization information before attempting to do things like register a service. (Note that the Java WSDP Registry Server, which is an implementation of a UDDI registry, does not require a user ID and password for access.)

Any user of a JAXR client may perform queries on a registry. In order to add data to the registry or to update registry data, however, a user must obtain permission from the registry to access it. To register with one of the public UDDI version 2 registries, go to one of the following Web sites and follow the instructions:

http://uddi.microsoft.com/ (Microsoft)
http://uddi.ibm.com/testregistry/registry.html (IBM)
http://udditest.sap.com/ (SAP)

These UDDI version 2 registries are intended for testing purposes. When you register, you will obtain a user name and password. You will specify this user name and password for some of the JAXR client example programs.

Step 2: Connect to the registry provider

Create/Lookup Connection Factory: To access a registry, a JAXR client needs to establish a connection with a registry provider. To do that, the client uses the createConnection method of the provider's ConnectionFactory class. Each registry provider can make available one or more ConnectionFactory classes that are configured in a specific way. If a registry provider does make a configured ConnectionFactory class available, it also needs to register it with a naming service such as one that is based on the Java Naming and Directory Interface (JNDI) interface. So a good way for a JAXR client to find a configured ConnectionFactory class is through JNDI.

A client creates a connection from a connection factory. A JAXR provider may supply one or more preconfigured connection factories that clients can obtain by looking them up using the Java Naming and Directory Interface (JNDI) API.

The JAXR 1.0 EA 1 Reference Implementation provides a ConnectionFactory class. If a JAXR client uses the Reference Implementation to connect to a registry, the client needs to use the newInstance method in the ConnectionFactory class to create an instance of the object, for example:

ConnectionFactory factory = ConnectionFactory.newInstance();

Set Properties for the Connection: To create a connection, a client first creates a set of properties that specify the URL or URLs of the registry or registries being accessed for the created ConnectionFactory instance. Some of these properties are standard to JAXR, others can be defined by a JAXR provider. The standard properties are:

javax.xml.registry.queryManagerURL : This is a string that specifies the URL for the query manager service of the registry provider. This is the URL of the API for querying the registry.
javax.xml.registry.lifeCycleManagerURL : This is a string that specifies the URL for the life cycle manager service of the registry provider. This is the URL of the API for updating the registry.
javax.xml.registry.factoryClass : This is a string that is the fully-qualified class name for the ConnectionFactory class of a registry-specific JAXR provider. A registry-specific JAXR provider is a JAXR provider that implements the JAXR API in a registry-specific way, and plugs into a JAXR pluggable provider that implements features of the JAXR API in a registry-independent way.

To specify the properties, a JAXR client supplies them as parameters to the setProperties method of the ConnectionFactory:

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");
factory.setProperties(props);

After the client sets the properties for the connection factory then client can create the connection from the connection factory:

Connection connection = factory.createConnection();

You can also create a FederatedConnection which can be used to query several different registries at the same time. To create a FederatedConnection you would first create two or more regular JAXR connections as above, then use those Connection objects to create a FedereatedConnection as following:

set connections = HashSet();
Connection con1 = factory1.createConnection();
connections.add(con1);
Connection con2 = factory2.createConnection();
connections.add(con2);
FederatedConnection federatedCon = factory3.createFederatedConnection(connections);

Once you have a FederatedConnection, search operations will be executed against all of the registries represented by the FederatedConnection – you will be searching multiple registries at once.

The implementation of JAXR in the Java WSDP allows you to set a number of properties on a JAXR connection. Some of these are standard properties defined in the JAXR specification. Other properties are specific to the implementation of JAXR in the Java WSDP. Table 13-1 and Table 13-2 list and describe these properties.

Table 13-1 Standard JAXR Connection Properties

Property Name and Description	Data Type	Default Value
javax.xml.registry.queryManagerURL Specifies the URL of the query manager service within the target registry provider	String	None
javax.xml.registry.lifeCycleManagerURL Specifies the URL of the life cycle manager service within the target registry provider (for registry updates)	String	Same as the specified queryManagerURL value
javax.xml.registry.semanticEquivalences Specifies semantic equivalences of concepts as one or more tuples of the ID values of two equivalent concepts separated by a comma; the tuples are separated by vertical bars: id1,id2\|id3,id4	String	None
javax.xml.registry.security.authenticationMethod Provides a hint to the JAXR provider on the authentication method to be used for authenticating with the registry provider	String	None; UDDI_GET_AUTHTOKEN is the only supported value
javax.xml.registry.uddi.maxRows The maximum number of rows to be returned by find operations. Specific to UDDI providers	Integer	None
javax.xml.registry.postalAddressScheme The ID of a ClassificationScheme to be used as the default postal address scheme. See Specifying Postal Addresses for an example	String	None

Table 13-2 Implementation-Specific JAXR Connection Properties

Property Name and Description	Data Type	Default Value
com.sun.xml.registry.http.proxyHost Specifies the HTTP proxy host to be used for accessing external registries. If you specified a proxy host and port when you installed the Java WSDP, the values you specified are in the file <JWSDP_HOME>/conf/jwsdp.properties.	String	Proxy host value specified in <JWSDP_HOME>/conf/jwsdp.properties
com.sun.xml.registry.http.proxyPort Specifies the HTTP proxy port to be used for accessing external registries; usually 8080	String	Proxy port value specified in <JWSDP_HOME>/conf/jwsdp.properties
com.sun.xml.registry.https.proxyHost Specifies the HTTPS proxy host to be used for accessing external registries	String	Same as HTTP proxy host value
com.sun.xml.registry.https.proxyPort Specifies the HTTPS proxy port to be used for accessing external registries; usually 8080	String	Same as HTTP proxy port value
com.sun.xml.registry.http.proxyUserName Specifies the user name for the proxy host for HTTP proxy authentication, if one is required	String	None
com.sun.xml.registry.http.proxyPassword Specifies the password for the proxy host for HTTP proxy authentication, if one is required	String	None
com.sun.xml.registry.useCache Tells the JAXR implementation to look for registry objects in the cache first and then to look in the registry if not found	Boolean, passed in as String	True
com.sun.xml.registry.useSOAP Tells the JAXR implementation to use Apache SOAP rather than the Java API for XML Messaging; may be useful for debugging	Boolean, passed in as String	False

Step 3: Provide Authorization Information (not for you only need to query information)

As mentioned earlier, registry providers typically require a user to have proper authorization, in the form of a valid user ID and password, to update the contents of a registry. In particular, registry specifications such as UDDI require authentication for certain requests. For example, the UDDI specification requires that a UDDI registry authenticate requests that use UDDI's Publish API. In JAXR terms, this means that a UDDI registry provider needs to authenticate a request from a JAXR provider to do things like publish a Web service to the registry or remove a Web service registration.

Specify Credentials: JAXR provides a way to pass authentication information to a JAXR provider, and subsequently on to a registry provider. In JAXR, authentication information is passed as a set of credentials. The credential concept is the same as that used in the Java Authentication and Authorization Service (JAAS) that is part of the Java 2 Platform, Standard Edition (J2SE). To hold the credentials for registry access, a JAXR client needs to first create a PasswordAuthentication object. The PasswordAuthentication is in the java.net package in the Java 2 Platform. When the client creates the PasswordAuthentication object, it specifies the user name (as a string), and the password (as a character array):

import java.util.*;

String userName = "...";
String password = "...";
PasswordAuthentication passwdAuth = new PasswordAuthentication(userName,
password.toCharArray());

To set the credentials, a JAXR client uses the setCredentials method in the Connection object. The credentials are specified as a hashed set:

Set credentials = new HashSet();
credentials.add(passwdAuth);
connection.setCredentials(credentials);

If a client has authorization to do so, it can submit data to a registry, modify it, and remove it. It uses the BusinessLifeCycleManager interface to perform these tasks.

Registries usually allow a client to modify or remove data only if the data is being modified or removed by the same user who first submitted the data.

Step 4. Register the Services

To register a service, a JAXR client needs to:

Get the <registryService.
Use the registryService to get a LifeCycleManager.
Use the LifeCycleManager to create objects for inclusion in the registry.

Get the registryService : In JAXR, all operational requests, such as publishing to a registry or querying a registry, are made using the registryService interface. What this means is that after it gets a connection, a JAXR client needs to get the registryService interface that is associated with that connection.

A client uses the getRegistryService method to get the registryService interface:

RegistryService rs = connection.getRegistryService();

Get the LifeCycleManager: After a JAXR client gets the getRegistryService interface, it uses it to make a specific registry request. In JAXR, the term "Life Cycle management" describes activities such as registering a business or updating a Web service registration, in other words, activities that typically require authentication. A JAXR provider implements an interface, LifeCycleManager that a JAXR client uses to request life cycle management activities such as creating new objects for inclusion in a registry. The LifeCycleManager interface presents a generic API. A LifeCycleManager subinterface, called the BusinessLifeCycleManager, provides a more business-oriented API. To get the interfaces, JAXR provides the getLifeCycleManager and getBusinessLifeCycleManager methods:

LifeCycleManager lifeCycleManager = rs.getLifeCycleManager();
BusinessLifeCycleManager businessLifeCycleManager= rs.getBusinessLifeCycleManager();

Create Objects for Inclusion in the Registry: The LifeCycleManager interface includes various factory methods, that create new objects for inclusion in a registry. These methods have the name createInterface, where Interface is the name of an interface in the JAXR information model. Some of these methods are:

createOrganization
createService
createUser
createPersonName
createTelephoneNumber
createEmailAddress
createClassification

As mentioned previously, an Organization maps to a businessEntity data structure in a UDDI registry. Like a businessEntity, an Organization is associated with other information such as service offerings, contacts, and business classifications. This related information is contained in objects in the information model. The createInterface methods are used to create these objects. For example, the following code creates an Organization, and adds a description to it. Notice the method createInternationalString. This method creates a string that is internationalized to several Locales.

BusinessLifeCycleManager lifeCycleManager = null;
...
Organization org = lifeCycleManager.createOrganization("MyBusiness");
InternationalString orgDesc = lifeCycleManager.createInternationalString(
"An excellent business");
org.setDescription(orgDesc);

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) {
      }
    }
}
}

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

An example of 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);

All JAXR providers support at least the following taxonomies for classifications:

The North American Industry Classification System (NAICS). See http://www.census.gov/epcd/www/naics.html for details.
The Universal Standard Products and Services Classification (UNSPSC). See http://www.eccma.org/unspsc/ for details.
The ISO 3166 country codes classification system maintained by the International Organization for Standardization (ISO). See http://www.iso.org/iso/en/prods-services/iso3166ma/index.html for details.

You also can delete an organization created by your own from the registry. The delete request must include the organization's key. The following program creates a Key object to hold the key and then passes it as part of a collection to the BusinessLifeCycleManager method deleteOrganizations:

javax.xml.registry.infomodel.Key key = lifeCycleManager.createKey( keyString);
String id = key.getId();
System.out.println("Deleting organization with id " + id);
Collection keys = new ArrayList();
keys.add(key);
BulkResponse response = blcm.deleteOrganizations(keys);
Collection exceptions = response.getException();
if (exceptions == null) {
System.out.println("Organization deleted");
Collection retKeys = response.getCollection();
Iterator keyIter = retKeys.iterator();
javax.xml.registry.infomodel.Key orgKey = null;
if (keyIter.hasNext()) {
    orgKey =
        (javax.xml.registry.infomodel.Key) keyIter.next();
    id = orgKey.getId();
    System.out.println("Organization key was " + id);
}
}

A client can use a similar mechanism to delete services and service bindings. A registry allows you to remove from the registry any data that you have submitted to it. You use the key returned by the registry as an argument to one of the BusinessLifeCycleManager delete methods: deleteOrganizations, deleteServices, deleteServiceBindings, and others.

Step 5. Query Registry Information

The simplest way for a client to use a registry is to query it for information about the organizations that have submitted data to it. To search a registry for a service, a JAXR client needs to:

Get the registryService. (see above how to get registryService)
Use the registryService to get a QueryManager.
Use the QueryManager to issue search requests.

Get the QueryManager: In the above, the LifeCycleManager interface and the BusinessLifeCycleManager subinterface is used to make its registry requests. But searching a registry is not a Life Cycle management activity. Instead, it's an activity that is part of what JAXR terms "Query Management". JAXR provides a QueryManager interface for Query Management, and defines two subinterfaces: BusinessQueryManager and DeclarativeQueryManager. The BusinessQueryManager interface provides methods for searching a registry based on criteria such as classification. The DeclarativeQueryManager provides methods for issuing an ad-hoc query, which is a query whose format is based on immediate need. A JAXR provider implements these interfaces. To get the interfaces, JAXR provides the getQueryManager, getBusinessQueryManager, and getDeclarativeQueryManager methods:

BusinessQueryManager businessQueryManager = rs.getBusinessQueryManager();
DeclarativeQueryManager declarativeQueryManager = rs.getDeclarativeQueryManager();

The BusinessQueryManager interface supports a number of find methods that allow clients to search for data using the JAXR information model. 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, which returns a list of organizations that meet the specified criteria--often a name pattern or a classification within a classification scheme
findServices, which returns a set of services offered by a specified organization
findServiceBindings, which returns the service bindings (information about how to access the service) that are supported by a specified service

To search for organizations by name, you normally use a combination of find qualifiers (which affect sorting and pattern matching) and name patterns (which specify the strings to be searched). The findOrganizations method takes a collection of findQualifier objects as its first argument and a collection of namePattern objects as its second argument. The following fragment 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 and name patterns
Collection findQualifiers = new ArrayList();
findQualifiers.add(FindQualifier.SORT_BY_NAME_DESC);
Collection namePatterns = new ArrayList();
namePatterns.add(qString);

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

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

Collection findQualifiers = new ArrayList();
findQualifiers.add(FindQualifier.CASE_SENSITIVE_MATCH);
Collection namePatterns = new ArrayList();
namePatterns.add("%"+ qString + "%");

// Find orgs with name containing qString
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();
        }
      }
    }
}
}

Note: All of the BusinessLifeCycleManager save and delete methods return the BulkResponse type. So do most of the BusinessQueryManager type’s findXXX() methods.

Reference

The Java Web Services Developer Pack