Web services take float with JAXR

Use JAXR to find and register Web services

The job of cataloguing the world's species is straightforward, methodical, and slow. Taxonomists...add an average of 13,000 species a year to the list of known organisms. At that rate it would take centuries to complete the census. Because no central storehouse coordinates the results, even the number of species named so far—between 1.5 million and 1.8 million—is uncertain.

(Laura Tangley, "How Many Species Are There?"

US News and World Report

, August 1997)

How do you find what you are looking for? At home, you might organize things any way you like, provided you find what you need quickly. If you share your dwellings with others, you must all be able to find the things you mutually need. Of course, you can still organize your own desk in any manner, including—if you're like me—completely unorganized.

At your office, more people rely on the ability to locate commonly needed forms and other supplies with minimum effort. Administrative assistants label file cabinets and drawers with the names of their contents so other people can easily locate what they need. Even if you dislike that organization method, you would not rearrange those cabinets without first asking your colleagues. Since everyone depends on the ability to find needed office items, the desire for a shared organizational structure takes precedence over personal convenience.

The way we organize our computer files mirrors the office file cabinet example. When looking for the minutes from a year-old client meeting, you'd first find the folder with the client's name, look for the Meetings subfolder, and then perhaps sort that folder's contents by date. Of course, another person might organize it differently: he might have a Work folder, then a Meetings folder, inside which he would group items by client. That difference can be problematic when you're on vacation and your coworker urgently needs that meeting note. Thus, for important files, offices typically allocate shared directories, or network drives, and create policies on where and how you should save files.

The moral here is that we tend to name things and then categorize them, assigning each category a name, in turn. That hierarchical approach has served us for many a millennium in grasping what we know of the universe. Assigning names is how things enter our conceptual world, and that naming ability lets us have language. Indeed, "spoken words are the symbols of mental experience, and written words are the symbols of spoken words." (See Aristotle.) As we discover relationships between things, we categorize them according to those relationships. That categorization is a mental experience, and the symbol for that experience is the category name. A categorization system based on names is a taxonomy.

Web service registries

While file systems rely on naming and categorization for organizing files, naming and directory services extend that concept to the network. A directory suggests it contains a complete inventory of computing resources in the realm of things it categorizes. Just as a telephone directory aims to comprehensively include all lawyers, accountants, or art historians living in a city, a naming and directory service's usefulness is greatly affected by whether it contains all the printers, database servers, users, or administrators in an organization or department (domain). When a user wishes to log into a database, for example, that database might contact a directory server to determine the user's access privileges. If a directory contained only a partial list of authorized users, its usefulness to the organization would be questionable.

To ensure comprehensiveness, naming and directory services rely on system administrators to enter all known resources within their administrative domains. Since system administrators are typically employed by the organizations whose resources they must enter, an organization can expect that its administrators do a good job and that the directory remains up-to-date.

That expectation no longer holds when multiple organizations control the things we wish to name and categorize. In that case, we hope that each organization registers the resources it wants others to know about in publicly available registries. Web services are an example of such resources. When an organization wishes to expose a Web service, it registers that service in public Web service registries. As its name suggests, a registry is a special directory that not only points users to a resource, but also lets them register services with it.

Several public Web service registries are currently operational; however, they differ in how they characterize and categorize a Web service. Universal Description, Discovery, and Integration (UDDI) registries employ a popular Web service categorization mechanism; UDDI instances are operated by IBM, Hewlett-Packard (HP), Microsoft, SAP, and a growing list of other companies. ebXML directories provide another Web service category, aimed mainly at e-business transactions. Hong Kong University currently provides a public ebXML directory. Other public Web service registry efforts are based on standards, such as ISO (International Standards Organization) 11179, the eCo Framework, or OASIS (Organization for the Advancement of Structured Information Standards). (Refer to Metadata standards.)

Web service registries not only offer more capabilities than directories, they also offer more than simple naming services. Naming implies using words to describe things, a technique that does not scale to global proportions when words must assume exact and identical meanings in all contexts. As the renaissance Dutch painter Pieter Bruegel amiably depicts, since Biblical times, the multitude of human languages has derailed many efforts to build things that rely on exactitude (see Figure 1).

Figure 1. Pieter Bruegel's The Tower of Babel (circa 1563. Museum Boijmans Van Beuningen, Rotterdam). Human language has proven an imprecise communication medium in large-scale, global engineering projects.

So that Web services don't remain another unfulfilled vision, Web service registries allow a service provider to associate formal descriptions with a Web service. Such descriptions utilize a syntax that precisely defines a Web service. Precision extends both to a service's categorization, as well as its specification; for example, how other Web services might interact with it programmatically.

In categorization, the formalized semantics and syntax define a Web service registry's information model; while Web service description languages define a service's specification on how to invoke it. An example of the former is the structure and specification of UDDI or ebXML registries; an example of the latter is the Web Services Description Language (WSDL). Following, I will show you how to interact with registry information models from a Java program and how to categorize your Web service so that others can find it. (In an upcoming column, I will discuss service description languages, including WSDL.)

Mass-market system integration

Let's revisit our imaginary friend, whom you met in the previous Web Services column, as she sets out to construct a cruise ship reservation Web service for the Magellan Travel Agency. As you might recall, she must integrate diverse information sources from cruise lines and offer her customers a seamless search and reservation experience. As you'll see, Web services do not offer irreplaceable capabilities for such a system, but they do make large-scale integration tasks manageable and feasible.

In its initial form, Magellan Travel's system needs to do the following:

  • Manage an up-to-date cruise inventory and let customers search that inventory database
  • Allow a customer to reserve a cruise vacation through a set of Webpages; once a reservation is made, automatically enter that reservation into the appropriate cruise line's system

Figure 2 depicts these requirements and how various entities must interact to support Magellan Travel's application.

Figure 2. Interaction between Web service components in support of a cruise ship reservation network

Without Web services, our friend could look up cruise line operators in a telephone directory, telephone them, and arrange a suitable protocol for interoperation with them. For each customer, that process would typically involve lengthy meetings and discussions with its technical staff. With limited developer resources, some cruise lines might not be able to make their senior developers—those with the most system knowledge—readily available for the project; thus, jeopardizing our friend's success. Given the cost involved, that offline integration process suggests that only the largest travel agencies and reservation systems can list cruise vacations from the most significant cruise companies. Since customers prefer reservation systems with the biggest selection, the largest companies would grow even larger, while those with less financial resources would effectively become obsolete.

Our friend needs a way to automatically discover cruise companies, including the exact specifications of those companies' network services. In addition, Magellan also needs to advertise its reservation service, letting cruise ship operators update Magellan's database whenever they change their schedules. If discovering and publishing exact technical specifications can reduce integration costs, Magellan Travel, and many smaller companies like it, could obtain and maintain the same information its larger competitors rely on.

This could lead to a benefit similar to what the hardware world has experienced for the past two decades: as PCs have simultaneously reached extraordinary computing power and mass-market prices, any business today can afford vast computing resources; whereas, two decades prior, running gigabyte databases, data mining applications, desktop publishing, or video editing were only the wealthiest corporations' exclusive domain. By bringing the ability to assemble large-scale systems out of network-bound components within the reach of mass-market consumers, Web services have the potential to commoditize software development and integration.

Web service development cycle

Just as a PC won't do your work for you (though we wish it did), Web services do not put large-scale system integration on autopilot. Rather, they suggest a software development cycle specific to Web service development. Our friend's path illustrates that cycle:

  1. Investigate existing standards. To ensure that her reservation service interoperates with cruise ship companies, hotels, and other business partners, she first must investigate what standards exist in those respective industries. Many Web-centric interoperation standards already exist, such as RosettaNet (manufacturing), StarStandard (automotive retailing), and the Open Travel Alliance (OTA), that aim to standardize information exchange in the travel industry. (I will survey the different standards efforts under way in a future column.)
  2. Build a standards-compliant implementation. Since our friend at Magellan Travel is starting from scratch, legacy integration won't be an issue. However, if you already have your own internal system, you should consider exposing that system's functionality via standards-based interfaces.
  3. Register her implementation with Web service registries. She names and categorizes her service according to the classification mechanism that each Web service registry offers. Later, a code example registers Magellan Travel's Web services with both UDDI and ebXML registries.
  4. Query Web service registries for the types of companies she wants to do business with. In addition, she might narrow her queries to those companies that implement the exact software specifications her system handles. You will shortly see an example of that query capability.
  5. Download a prospective business's detailed software specifications as well as any software component necessary to access its systems. She obtains that information from the Web service registries. This article's concluding section highlights how that works.
  6. Make, if necessary, a business arrangement with the newly integrated partner company. A vibrant effort is under way in the research and business communities to figure out how an organization can make money from Web services. Keep checking this column for a future article on electronic contracts as well as economics-based service provisioning mechanisms.

Figure 3 illustrates the Web service development lifecycle. You might note that I extended the business requirements from Figure 2 to include interaction with Web service registries to support service discovery.

Figure 3. Web service development cycle

Figure 3 also illustrates the participants in Web service registration and discovery:

  • Registry operator: An organization that provides public Web service registries. As noted earlier, examples include IBM, Microsoft, HP, SAP, and Ariba for UDDI-based registries, and at least one publicly accessible ebXML registry operated by Hong Kong University.
  • Submitting organization: The business that registers its services with public registries. It retains ownership over the information it submits to a registry.
  • Content submitter: The person or software performing the registry submission for a submitting organization.
  • Registry guest: A user (human or software) that browses or searches a registry's contents.

To submit information to a registry, an organization must first establish an account with a registry operator, using a Web-based form similar to the one in Figure 4. Once you obtain content-submitter privileges with a registry operator, you can use the username and password established with that provider as credentials when submitting your Web service information. Registry guests don't need an account.

Figure 4. A UDDI registry operator's sign-up form. Sign-up requires that you specify both the submitting organization and a content submitter. Click on thumbnail to view full-size image. (Source: IBM Website)

Registry elements

While you can use Web-based forms to register new services and manage your existing registrations, Web service registries allow programmatic interaction: Registries are Web services themselves. From the programmatic viewpoint, you will deal with the following components:

  • Registry provider: A Web service implementation of a registry specification, i.e., the registry itself.
  • Registry client: A program that interacts with a registry provider, whether browsing/searching a registry's content or managing Web service registrations.
  • Repository item: A content piece that resides inside a registry. This might be an XML Web service description file, a code chunk needed to interact with your service, or a specification document. You submit this when registering a new Web service, and others can download that content directly from a registry.
  • Registry entry: Metadata about a registry item. It catalogues the registry item and thus facilitates finding that content. A registry entry relates to a repository item as a library card relates to a book: The card classifies a book according to a library classification scheme and thus, helps you find that book. It is not concerned with a book's actual content, such as its chapter count or layout.

A library analogy helps distinguish a registry from a repository: A registry corresponds to the library card catalogue, while a repository resembles the bookshelves. A registry is not concerned with what a content piece consists of or how it is stored—it might delegate persistent storage to another component. When you register a repository item, you act as the librarian cataloguing a newly acquired book; you must specify what categories, or taxonomies, that content belongs to. Web service registries provide access to their content only through their registry interfaces.

Enter JAXR

Each Web service registry standard specifies a registry interface specific to that registry's information model. The Java API for XML Registries (JAXR) abstracts those different registry interfaces by providing an information model superset of several Web service registry models. If you interact with Web service registries via JAXR, you should be concerned with JAXR's information model only; JAXR translates elements of that model to specific registry model elements.

Using JAXR to access registries means that your program calls JAXR's client API. Those calls invoke objects on a JAXR provider. A JAXR implementation then maps registry information models to a specific registry's requirements and communicates with a registry provider under the covers. Figure 5 illustrates how JAXR offers a high abstraction level when interacting with Web service registries from a Java program.

Figure 5. JAXR's role: A client API calls a JAXR provider. Communication might take place via XML RPC (remote procedure calls) or XML messages.

As Figure 5 suggests, JAXR provides a pluggable architecture. As new Web service registry standards evolve, a JAXR provider can incorporate mappings to those new information models. Clients are shielded from that change, since they interact only with JAXR's model. Another JAXR benefit is that a client can interact with multiple registry types in one JAXR session. Once a client specifies a service in accord with JAXR's information model, it can request to map to and register with that model with several registry types.

Since JAXR's information model defines a superset of other registry models' capabilities, not every registry supports all JAXR features. Thus, JAXR's capabilities are grouped into profiles, and each method in the JAXR API is assigned a profile level. A JAXR provider declares its supported capability level via the CapabilityProfile interface. Higher capability levels support lower-level functionality as well.

A provider that supports a capability level must implement all methods that compose that level. If a client invokes a method not part of a provider's capability level, that method will throw an UnsupportedCapabilityException. At the time of this writing, Sun Microsystems bundles a capability-level 0 JAXR provider with its Java Web Service Developer Pack (JWSDP). (Check out "Supplement: The Adventures of JWSDP.") A capability-level 0 provider supports UDDI 2.0 registries. An open source development effort is under way to produce a capability-level 1 JAXR provider; that provider will interact with ebXML registries as well.

JAXR's client API serves both submitting organizations and registry guests. In other words, the API's two functionalities relate to managing registry objects—adding, editing, and removing Web service registrations or lifecycle management—and querying registries. The API occupies two packages: javax.xml.registries contains interfaces and classes related to lifecycle management and querying, while javax.xml.registries.infomodel includes the JAXR information model's classes.

Registry communication via JAXR

Using JAXR, our friend can quickly register her travel agency via the following five-step process:

  1. Connect to Web service registries. JAXR connections are created via the ConnectionFactory class. You can use the javax.xml.registry.ConnectionFactoryClass property to specify what factory class to use when creating a registry connection. If you specify a factory class that belongs to a capabilities 1 JAXR provider, you can connect to registries supported by that level API; if you specify one that supports level 0 only, you can interact only with UDDI registries. The JAXR specification suggests that you obtain your registry ConnectionFactory via a naming and directory service lookup; alternatively, you might create a new factory via a static creational method. JAXR also lets you simultaneously converse with multiple registry providers by requesting a FederatedConnection from the connection factory. Queries perform in a distributed manner via a federated connection.
  2. Prepare the connection. Associate attributes with the connection—the most common attributes being your credentials. You need to specify credentials for lifecycle management-related activities; you don't if you wish only to query a registry.
  3. Query or update the registry. Once you have a connection open to one or more registries, you obtain a reference to an abstraction for the registry via the RegistryService interface. If you decide to query the registry, you obtain from RegistryService a BusinessQueryManager or a DeclarativeQueryManager, depending on how you wish to search (more on searching later). For lifecycle management tasks, you would request the registry's LifeCycleManager.
  4. The registry's response to both queries and updates transmit to the client in the form of JAXRResponse objects. BulkResponse is a JAXRResponse type and contains a Collection object whose elements correspond to query replies. Or, if you tried to update the registry and the update failed, BulkResponse also lets you obtain a set of JAXRException objects telling you what went wrong.
  5. Close the connection.

The following code snippet illustrates these steps:

try {
     //1. Obtain a connection factory, either by creating a new instance, 
     //or from a naming and directory service.
     ConnectionFactory cFac = ConnectionFactory.newInstance();
     //Set up properties for the connection factory.
     Properties prop = new Properties();
     //Factory class to use.
     prop.setProperty("javax.xml.registry.factoryClass",
           "com.sun.xml.registry.uddi.ConnectionFactoryImpl");
     //Query URL.
     prop.setProperty("javax.xml.registry.queryManagerURL",
           "http://www-3.ibm.com/services/uddi/v2beta/inquiryapi");
     
     //Lifecycle manager URL. Note the use of SSL. 
     prop.setProperty("javax.xml.registry.lifeCycleManagerURL",
           "https://www-3.ibm.com/services/uddi/v2beta/protect/publishapi");
     cFac.setProperties(prop);
     Connection con = cFac.createConnection();
     //2. Set the properties for the connection. This is only needed for
     //   lifecycle management tasks. Use the username and password you 
     //   established with the registry operator.
     String userName = "testuser";
     String password = "testuser";
     PasswordAuthentication pw =
          new PasswordAuthentication(userName, password.toCharArray());
     Set cSet = new HashSet();
     cSet.add(pw);
     con.setCredentials(creds);
     
     //3. Obtain the registry service, and from that object, obtain the 
     // JAXR provider's BusinessQueryManager or LifeCycleManager objects.
     RegistryService regService = con.getRegistryService();
     BusinesQueryManager qm = regService.getBusinessQueryManager();
     BusinessLifeCycleManager lcm  = regService.getBusinessLifeCycleManager();
     //Perform either queries or updates. See below for each activity's code.
     .......
     //4. Handle the appropriate response. See below.
     .......
     //5. Close connection.
     con.close();
} catch (JAXRException e) {
     ....
}

The JAXR information model

At the heart of JAXR's information model is the RegistryObject; everything inside the registry is a RegistryObject. (Recall that registry objects represent metadata and differ from repository objects, which contain the actual content.) RegistryObject itself is defined as an attribute collection or Slots. You can dynamically add or remove attributes from a RegistryObject.

When you register your company with a registry provider, you create a RegistryObject subtype called Organization. An Organization can have any number of child organizations and Users associated with it. You can also assign TelephoneNumber and PostalAdress values to an Organization.

Most important, the services offered by an Organization are assigned to it in the form of Service objects. Each Service, in turn, might define several ServiceBindings. If the service is accessible via the Web—which is the case for Web services—a ServiceBinding would specify an access URI (Uniform Resource Identifier) for that service. As well, a service might also provide a SpecificationLink that points to the technical specification needed to invoke the service via the access URL. That specification link would point back to another RegistryObject representing the specification itself. The actual specification content—stored in a repository beneath the registry or at an external location—might be a WSDL document, a CORBA IDL (interface definition language) file, a Java RMI (Remote Method Invocation) stub, or even a Jini service template. Figure 6 illustrates the relationship between an organization and its services.

Figure 6. Organization-related classification of registry objects in the JAXR information model

If you looked for a specific organization's services (for instance, Sun's or IBM's), you would only need the relationship hierarchy I just described. Based on the organization's name, you would obtain the services it provides, and then retrieve any of those services' specification and access the URI. With that information, you would then invoke the service.

However, our friend at Magellan Travel has a slightly more ambitious aim: to discover all services offered by companies in a given industry, such as hotels and cruise lines. Therefore, she must classify registry objects (companies and their services) according to industry-specific, and even geographic, taxonomies.

JAXR's information model lets you classify a registry object according to any taxonomy. For instance, the Magellan Travel Agency would want to advertise that it is a travel agency. Based on that information, cruise lines could then locate Magellan's Organization; retrieve Magellan's services, a service to update cruise travel information, for instance; and invoke those services. Therefore, Magellan would need to classify its Organization registry object in accordance with an industry-specific taxonomy, preferably a standard one shared by businesses worldwide.

Similarly, a cruise company would describe itself as belonging to the cruise industry. Magellan would periodically contact Web services registries via JAXR, and query those registries based on an industry-specific taxonomy. Further, suppose that Magellan only offered cruises in the South Pacific. In that case, it would also want to query the registries along geographic taxonomy lines. For that to work, cruise companies must be able to classify themselves according to multiple taxonomies. JAXR provides these capabilities.

JAXR taxonomy

A taxonomy in JAXR's information model corresponds to a set of Classifications—a ClassificationScheme. You can represent the taxonomy's elements internal to the registry—those elements would then themselves be registry objects. Alternatively, you might classify registry objects according to taxonomies external to the registry. Regardless of whether you use internal or external Classifications, you'd call RegistryObject's addClassification() method to link the classification with the registry object.

Only capability-level 1 JAXR providers support internal taxonomies (internal ClassificationSchemes). Internal classification schemes are defined as a Concept hierarchy. When a registry stores classification information internally, it can perform validation whenever it classifies a registry object. External classifications don't offer that capability; instead of Concepts, they rely on String values to build a hierarchy under a classification scheme. Figure 7 illustrates a travel-related industry taxonomy based on the North American Industry Classification System (NAICS).

Figure 7. Internal and external classifications in a JAXR registry. Click on thumbnail to view full-size image.

The following code segment adds Magellan Travel to Web service registries via JAXR. After creating the organization, JAXR classifies Magellan as a travel agency, or code 56151 according to the NAICS (an external taxonomy):

try {
     Organization org =
          businessLifeCycleManager.createOrganization("Magellan Travel");
     InternationalString str =
          businessLifeCycleManager.createInternationalString("A cruise ship reservation system");
     org.setDescription(str);
     //Primary contact
     User primaryContact = businessLifeCycleManager.createUser();
     PersonName pName = businessLifeCycleManager.createPersonName("Fernando Magellan");
     primaryContact.setPersonName(pName);
     TelephoneNumber tNum = businessLifeCycleManager.createTelephoneNumber();
     tNum.setNumber("213-747-5516");
     Collection phoneNumbers = new ArrayList();
     phoneNumbers.add(tNum);
     primaryContact.setTelephoneNumbers(phoneNumbers);
     EmailAddress emailAddress =
          businessLifeCycleManager.createEmailAddress("fernando@magellan.com");
     Collection emailAddresses = new ArrayList();
     emailAddresses.add(emailAddress);
     primaryContact.setEmailAddresses(emailAddresses);
     org.setPrimaryContact(primaryContact);
     //Assign classification scheme
     ClassificationScheme sc =
          businessQueryManager.findClassificationSchemeByName("ntis-gov:naics");
     Classification classification =
          (Classification)businessLifeCycleManager.createClassification(sc, 
            "Travel Agencies", "56151");
     Collection classifications = new ArrayList();
     classifications.add(classification);
     org.addClassifications(classifications);
     //Save new organization
     Collection orgs = new ArrayList();
     orgs.add(org);
     BulkResponse response = businessLifeCycleManager.saveOrganizations(orgs);
     Collection exceptions = response.getException();
     if (exceptions == null) {
          System.out.println("Organization saved");
      } else {
          for (Iterator iterator = exceptions.iterator(); iterator.hasNext();) {
              JAXRException e = (JAXRException) iterator.next();
               System.out.println(e.getMessage());
          }
           System.out.println("Couldn't save organization.");
       }
} catch (JAXRException e) {
     e.printStackTrace();
}

The final code example finds all companies belonging to the deep-sea passenger transportation industry (or code 483112 in the NAICS taxonomy):

try {
     //Searching by classification
     String schemeName = "uddi-org:types";
     ClassificationScheme uddiOrgType =
          businessQueryManager.findClassificationSchemeByName(schemeName);
     Classification classification =
          businessLifeCycleManager.createClassification(uddiOrgType,
          "Deep sea passenger transportation", "483112");
     Collection classifications = new ArrayList();
     classifications.add(classification);
     BulkResponse res = businessQueryManager.findOrganizations(
           null,
           null,
           classifications,
           null,
           null,
           null);
     Collection orgs = res.getCollection();
     Iterator it = orgs.iterator();
     while (it.hasNext()) {
          Organization o = (Organization)it.next();
          System.out.println("Organization name: " + o.getName().getValue());
     }
} catch (JAXRException e) {
     e.printStackTrace();
}

Additional benefits

The JAXR API has several additional capabilities Magellan Travel will find useful, including context-aware classifications. Consider a cruise line that classifies itself via a geographic taxonomy under Japan. From that information alone, you cannot tell whether the cruise line offers trips to Japan, operates ships inside Japan, or has its fleet under Japanese registration. By adding an extra link and classifying that geographic classification itself, you easily clarify this situation. (Recall that Classification is just another RegistryItem; thus, you can call addClassification() on it too.)

Another important JAXR feature lets you create associations between registry objects. If a cruise line has partner arrangements with local vendors, for instance, Magellan Travel would consider those pre-existing relationships when making business arrangements. Figure 8 shows how a JAXR-based registry browser displays those business associations.

Figure 8. A JAXR registry browser displaying registry object associations, showing how companies associate in a business relationship. Click on thumbnail to view full-size image.

Once Magellan Travel discovers a cruise line of interest, it would like to initiate a business relationship with that company. In my next column, I will focus on how the Web service specifications and access URIs published in registries lets Magellan's programmers make remote method invocations to a newly discovered cruise company's Web service via JAX/RPC (Java API for XML-based RPC).

Learn more about this topic

Join the discussion
Be the first to comment on this article. Our Commenting Policies