Home TOC Index

JAXR

The Java API for XML Registries (JAXR) provides a convenient way to access standard business registries over the Internet. Business registries are often described as electronic yellow pages because they contain listings of businesses and the products or services the businesses offer. JAXR gives developers writing applications in the Java programming language a uniform way to use business registries that are based on open standards (such as ebXML) or industry consortium-led specifications (such as UDDI).

Businesses can register themselves with a registry or discover other businesses with which they might want to do business. In addition, they can submit material to be shared and search for material that others have submitted. Standards groups have developed schemas for particular kinds of XML documents, and two businesses might, for example, agree to use the schema for their industry's standard purchase order form. Because the schema is stored in a standard business registry, both parties can use JAXR to access it.

Registries are becoming an increasingly important component of Web services because they allow businesses to collaborate with each other dynamically in a loosely coupled way. Accordingly, the need for JAXR, which enables enterprises to access standard business registries from the Java programming language, is also growing.

Using JAXR

The following sections give examples of two of the typical ways a business registry is used. They are meant to give you an idea of how to use JAXR rather than to be complete or exhaustive.

Registering a Business

An organization that uses the Java platform for its electronic business would use JAXR to register itself in a standard registry. It would supply its name, a description of itself, and some classification concepts to facilitate searching for it. This is shown in the following code fragment, which first creates the RegistryService object rs and then uses it to create the BusinessLifeCycleManager object lcm and the BusinessQueryManager object bqm. The business, a chain of coffee houses called The Coffee Break, is represented by the Organization object org, to which The Coffee Break adds its name, a description of itself, and its classification within the North American Industry Classification System (NAICS). Then org, which now contains the properties and classifications for The Coffee Break, is added to the Collection object orgs. Finally, orgs is saved by lcm, which will manage the life cycle of the Organization objects contained in orgs.

RegistryService rs = connection.getRegistryService();
 
BusinessLifeCycleManager lcm =
          rs.getBusinessLifeCycleManager();
BusinessQueryManager bqm = 
          rs.getBusinessQueryManager();
 
Organization org = lcm.createOrganization("The Coffee Break");
org.setDescription(
  "Purveyor of only the finest coffees. Established 1895");
 
ClassificationScheme cScheme = 
  bqm.findClassificationSchemeByName("ntis-gov:naics");
 
Classification classification = 
  (Classification)lcm.createClassification(cScheme, 
  "Snack and Nonalcoholic Beverage Bars", "722213");
 
Collection classifications = new ArrayList();
classifications.add(classification);
 
org.addClassifications(classifications);
Collection orgs = new ArrayList();
orgs.add(org);
lcm.saveOrganizations(orgs);
 

Searching a Registry

A business can also use JAXR to search a registry for other businesses. The following code fragment uses the BusinessQueryManager object bqm to search for The Coffee Break. Before bqm can invoke the method findOrganizations, the code needs to define the search criteria to be used. In this case, three of the possible six search parameters are supplied to findOrganizations; because null is supplied for the third, fifth, and sixth parameters, those criteria are not used to limit the search. The first, second, and fourth arguments are all Collection objects, with findQualifiers and namePatterns being defined here. The only element in findQualifiers is a String specifying that no organization be returned unless its name is a case-sensitive match to one of the names in the namePatterns parameter. This parameter, which is also a Collection object with only one element, says that businesses with "Coffee" in their names are a match. The other Collection object is classifications, which was defined when The Coffee Break registered itself. The previous code fragment, in which the industry for The Coffee Break was provided, is an example of defining classifications.

BusinessQueryManager bqm = rs.getBusinessQueryManager();
 
//Define find qualifiers
Collection findQualifiers = new ArrayList();
findQualifiers.add(FindQualifier.CASE_SENSITIVE_MATCH);
Collection namePatterns = new ArrayList();
namePatterns.add("%Coffee%"); // Find orgs with name containing 
//'Coffee'
 
//Find using only the name and the classifications
BulkResponse response = bqm.findOrganizations(findQualifiers,
    namePatterns, null, classifications, null, null);
Collection orgs = response.getCollection();
 

JAXR also supports using an SQL query to search a registry. This is done using a DeclarativeQueryManager object, as the following code fragment demonstrates.

DeclarativeQueryManager dqm = rs.getDeclarativeQueryManager();
Query query = dqm.createQuery(Query.QUERY_TYPE_SQL,
"SELECT id FROM RegistryEntry WHERE name LIKE %Coffee% " +
  "AND majorVersion >= 1 AND " +
  "(majorVersion >= 2 OR minorVersion >= 3)");
BulkResponse response2 = dqm.executeQuery(query);
 

The BulkResponse object response2 will contain a value for id (a uuid) for each entry in RegistryEntry that has "Coffee" in its name and that also has a version number of 1.3 or greater.

To ensure interoperable communication between a JAXR client and a registry implementation, the messaging is done using JAXM. This is done completely behind the scenes, so as a user of JAXR, you are not even aware of it.

Home TOC Index

This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.

All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.