Discover and publish Web services with JAXR

The Java API for XML Registries allows registry operations over diverse registry providers

A registry allows organizations to publish and discover Web services. Currently, two registry standards dominate: UDDI (Universal Description, Discovery, and Integration) and ebXML. With either of these, businesses can publish a set of Web services so their internal or external business partners can discover them. However, integrating Web services' discovery and registration regardless of the supported registry standard can prove challenging for businesses. For example, suppose some of the ACME company's multiple business partners published their services in a UDDI registry, while others published in an ebXML registry. How does an ACME Web service application discover those services published by all its business partners? What if ACME wants to publish its services to both UDDI and ebXML registries from within a single Web service application?

JAXR, the Java API for XML Registries, provides a standard API for publication and discovery of Web services through underlying registries. Currently, JAXR is included in the Java Web Services Developer Pack (JWSDP) 1.0 and the recently released Java XML Pack, Summer 02 Release. Additionally, JAXR will play an integral part in J2EE (Java 2 Platform, Enterprise Edition) 1.4. Scheduled for release in early 2003, J2EE 1.4 will be the platform of choice for Web services development and deployment, and compliant vendors will need to provide this API's implementation as an integrated feature in their applications.

In this article, we describe JAXR's architecture and programming models through example code. We explain important registry operations such as publication and discovery of Organizations, Services, usage of ServiceBindings, and ClassificationSchemes. Note: We give special attention to UDDI programmers.

Registry overview

Most business-to-business interactions are collaborations between two parties who engage in a partnership. These business partners share a registry, often in the form of a Web-based service. A registry typically functions as electronic Yellow Pages, where information about businesses and the products and services they offer are published and discovered. A registry can also serve as a database or store shared information, information that can encompass anything. A registry can also work as an electronic bulletin board in which the partners share information in a dynamic and ad hoc fashion. As described in the JAXR specification, information examples include generic event notification, price changes, discounts, and promotions.

What typical operations do registry-service clients perform? Submitting and storing shared information are important registry operations. Clients also need to complete various registry management operations, such as identifying, naming, describing, classifying, associating, grouping, and annotating registry metadata. Finally, clients also must be able to query, discover, and retrieve shared information from the registry and expect that a typical registry support most of these operations.

What is JAXR?

JAXR does not define a new registry standard. Instead, this standard Java API performs registry operations over a diverse set of registries and defines a unified information model for describing registry contents. Regardless of the registry provider accessed, your programs use common APIs and a common information model. The JAXR specification defines a general-purpose API, allowing any JAXR client to access and interoperate with any business registry accessible via a JAXR provider. In this sense, JAXR provides a Write Once, Run Anywhere API for registry operations, simplifying Web services development, integration, and portability.

JAXR's expert group wanted the API to support a union of the best features of UDDI and ebXML, rather than intersect common features. As described in the specification, JAXR is not a least common denominator API.

JAXR architecture

The JAXR architecture defines three important architectural roles:

  • A registry provider implements an existing registry standard, such as the OASIS (Organization for the Advancement of Structured Information)/ebXML Registry Services Specification 2.0.
  • A JAXR provider offers an implementation of the JAXR specification approved by the Java Community Process (JCP) in May 2002. You can implement a JAXR provider as its own JAXR-compliant registry provider. However, you would more likely implement a JAXR provider as a façade around an existing registry provider, such as a UDDI or ebXML registry provider. Currently, the JAXR reference implementation 1.0 offers a JAXR UDDI provider implementation. A group of developers are developing an open source JAXR ebXML provider implementation at
  • A JAXR client is a Java program that uses JAXR to access the registry provider via a JAXR provider. A JAXR client can be either a standalone J2SE (Java 2 Platform, Standard Edition) application or J2EE components, such as EJBs (Enterprise JavaBeans), Java Servlets, or JSPs (JavaServer Pages). The JAXR reference implementation also supplies one form of a JAXR client, a Swing-based registry browser application.

Figure 1 illustrates how diverse JAXR clients interoperate with diverse registries using JAXR. Architecturally, JAXR clients use the API to perform registry operations, while JAXR providers implement the API. Because JAXR offers a standard API for accessing diverse registry providers and a unified information model to describe registry contents, JAXR clients, whether HTML browsers, J2EE components, or standalone J2SE applications, can uniformly perform registry operations over various registry providers.

Figure 1. JAXR interoperability with any client to any registry. Source: Sun Microsystems

Figure 2 shows a high-level view of the JAXR architecture. The JAXR provider shown is a JAXR pluggable provider with underlying implementations of a UDDI-specific JAXR provider and an ebXML-specific provider. The JAXR provider exposes capability-specific methods to the JAXR client via the RegistryService interface. The JAXR client queries the RegistryService and discovers the provider capability level via the CapabilityProfile interface. We discuss capabilities in the following section.

Figure 2. JAXR architecture. Source: Sun Microsystems

Before a JAXR client can invoke capability-level methods on the JAXR provider, it must connect to the provider. First the client obtains a ConnectionFactory instance using the static method ConnectionFactory.newInstance(). The ConnectionFactory interface lets the client create the Connection using its createConnection() method. Note that the JAXR client connects with the JAXR provider, not the registry provider. The JAXR provider acts as a proxy on the client's behalf, directing and invoking methods on the appropriate registry provider. The connection maintains client state. In addition, the JAXR client dynamically sets its authentication information and communication preference on the connection any time during the connection's lifetime. Please refer to the code demonstrating how a JAXR client connects to a JAXR provider in the development examples later in the article.

After the JAXR client invokes JAXR capability-level methods, the JAXR provider transforms these methods into registry-specific methods and executes requests to the underlying registry providers. After the registry providers process the requests and return registry-specific results to the JAXR provider, the JAXR provider transforms the information into JAXR information model RegistryObjects and returns them to the JAXR client. The RegistryObject interface is an abstract interface that provides the common information such as key, name, and description for the more specialized JAXR information model interfaces. Note that the communication protocol between a JAXR provider and a registry provider is registry provider-specific and transparent to the JAXR client. For example, a JAXR provider communicates with the UDDI registry provider by exchanging basic SOAP messages, while the JAXR provider communicates with the ebXML registry provider through SOAP messaging or ebXML message service.

Capability profiles

Because some diversity exists among registry provider capabilities, the JAXR expert group decided to provide multilayer API abstractions through capability profiles. Each method of a JAXR interface is assigned a capability level, and those JAXR methods with the same capability level define the JAXR provider capability profile.

Currently, JAXR defines only two capability profiles: level 0 profile for basic features and level 1 profile for advanced features. Level 0's basic features support so-called business-focused APIs, while level 1's advanced features support generic APIs. At the minimum, all JAXR providers must implement a level 0 profile. A JAXR client application using only those methods of the level 0 profile can access any JAXR provider in a portable manner. JAXR providers for UDDI must be level 0 compliant.

JAXR providers can optionally support the level 1 profile. The methods assigned to this profile provide more advanced registry capabilities needed by more demanding JAXR clients. Support for the level 1 profile also implies full support for the level 0 profile. JAXR providers for ebXML must be level 1 compliant. A JAXR client can discover the capability level of a JAXR provider by invoking methods on the CapabilityProfile interface. If the client attempts to invoke capability level methods unsupported by the JAXR provider, the provider will throw an UnsupportedCapabilityException.

RegistryService interfaces

As mentioned in the previous section, the JAXR provider supports capability profiles that group the methods on JAXR interfaces by capability level. RegistryService exposes the JAXR provider's key interfaces, that is, Web services discovery and registration. The JAXR client can obtain an instance of the RegistryService interface by invoking the getRegistryService() method on the connection established between the JAXR client and JAXR provider. Once the JAXR client has the RegistryService, it can obtain the primary registry interfaces and perform life-cycle management and query management through the JAXR provider.

The JAXR specification defines two life-cycle management interfaces:

  • BusinessLifeCycleManager for level 0
  • LifeCycleManager for level 1

BusinessLifeCycleManager defines a simple business-level API for life-cycle management. This interface resembles the publisher's API in UDDI, which should prove familiar to the UDDI developer. For its part, LifeCycleManager interface provides complete support for all life-cycle management needs using a generic API.

Life-cycle management includes creating, saving, updating, deprecating, and deleting registry objects. In addition, the LifeCycleManager provides several factory methods to create JAXR information model objects. In general, life-cycle management operations are privileged, while a user can use query management operations for browsing the registry.

JAXR's top-level interface for query management, QueryManager, has two extensions:

  • BusinessQueryManager for level 0
  • DeclarativeQueryManager for level 1

Query management deals with querying the registry for registry data. A simple business-level API, the BusinessQueryManager interface provides the ability to query for the most important high-level interfaces in the information model, such as Organizations, Services, ServiceBindings, ClassificationSchemes, and Concepts. Alternatively, the DeclarativeQueryManager interface provides a more flexible, generic API, enabling the JAXR client to perform ad hoc queries using a declarative query language syntax. Currently, the only declarative syntaxes JAXR supports are SQL-92 and OASIS/ebXML Registry Filter Queries. As noted in the JAXR specification, ebXML registry providers optionally support SQL queries. If a registry provider does support SQL queries, the JAXR ebXML provider will throw an UnsupportedCapabilityException on DeclarativeQueryManager methods.

JAXR information model

Invoking life-cycle and query management methods on the JAXR provider requires the JAXR client to create and use the JAXR information model objects. The JAXR information model resembles the one defined in the ebXML Registry Information Model 2.0, but also accommodates the data types defined in the UDDI Data Structure Specification. Although developers familiar with the UDDI information model might face a slight learning curve, once understood, the JAXR information model will provide a more intuitive and natural interface to most developers.

Most JAXR information-model interfaces are derived from the abstract RegistryObject interface, which defines the common state information, called attributes, that all registry objects share. Example attributes include key, name, and description. The InternationalString interface defines attributes that must be internationalization compatible, such as name and description. The InternationalString interface contains a collection of LocalizedStrings, where each LocalizedString defines locale, character set, and string content.

The RegistryObject interface also defines collections of Classifications, ExternalIdentifiers, ExternalLinks, and Associations. The BusinessQueryManager often uses those collections as parameters in its find methods.

1 2 3 Page 1
Page 1 of 3