Chapter 1 Overview of JAXR

This section provides a brief overview of the Java^TM API for XML Registries (JAXR). The section covers the following topics:

• About Registries and Repositories

• About JAXR

• JAXR Architecture

• About the Examples

About Registries and Repositories

An XML registry is an infrastructure that enables the building, deployment, and discovery of web services. It is a neutral third party that facilitates dynamic and loosely coupled business-to-business (B2B) interactions. A registry is available to organizations as a shared resource, normally in the form of a web-based service.

Currently, several specifications for XML registries exist. These specifications include

• The ebXML Registry and Repository standard, which is sponsored by the Organization for the Advancement of Structured Information Standards (OASIS) and the United Nations Centre for the Facilitation of Procedures and Practices in Administration, Commerce and Transport (U.N./CEFACT). ebXML stands for Electronic Business using eXtensible Markup Language.

• The Universal Description, Discovery, and Integration (UDDI) protocol, which is developed by a vendor consortium.

A registry provider is an implementation of a registry that conforms to a specification for XML registries.

While a UDDI registry stores information about businesses and the services they offer, an ebXML registry has a much wider scope. It is a repository as well as a registry. A repository stores arbitrary content as well as information about that content. In other words, a repository stores data as well as metadata. The ebXML Registry standard defines an interoperable Enterprise Content Management (ECM) API for web services.

An ebXML registry and repository is to the web what a relational database is to enterprise applications: it provides a means for web services and web applications to store and share content and metadata.

An ebXML registry can be part of a registry federation, an affiliated group of registries. For example, the health ministry of a country in Europe could operate a registry, and that registry could be part of a federation that included the registries of other European health ministries.

Service Registry implements version 3.0 of the ebXML Registry and Repository specification. The specification is in two parts:

• The ebXML Registry Services and Protocols Specification (“ebXML RS”) defines the services and protocols for an ebXML Registry.

• The ebXML Registry Information Model Specification (“ebXML RIM”) defines the types of metadata and content that can be stored in an ebXML Registry.

You can find the latest public versions of these specifications by going to the OASIS web site and following the links to ebXML RIM V3.0 and ebXML RS V3.0.

About JAXR

JAXR enables Java software programmers to use a single, easy-to-use abstraction API to access a variety of XML registries. A unified JAXR information model describes content and metadata within XML registries.

JAXR gives developers the ability to write registry client programs that are portable across various target registries. JAXR also enables value-added capabilities beyond those of the underlying registries.

The current version of the JAXR specification includes detailed bindings between the JAXR information model and the ebXML Registry specifications. You can find the latest version of the JAXR specification at http://java.sun.com/xml/downloads/jaxr.html. The API documentation for JAXR is part of the API documentation for Java 2 Platform, Enterprise Edition (J2EE platform).

Service Registry includes a JAXR provider that implements the level 1 capability profile, which allows full access to ebXML registries. The ebXML specifications and the JAXR specification are not in perfect alignment, because the ebXML specifications have advanced beyond the JAXR specification. For this reason, the JAXR provider for the Registry includes some additional implementation-specific methods that implement the ebXML specifications. These additional methods are likely to be included in the next version of the JAXR specification.

JAXR Architecture

The high-level architecture of JAXR consists of the following parts:

• A JAXR client: This is a client program that uses the JAXR API to access a registry through a JAXR provider.

• A JAXR provider: This is an implementation of the JAXR API that provides access to a specific registry provider or to a class of registry providers that are based on a common specification. This guide does not describe how to implement a JAXR provider.

A JAXR provider implements two main packages:

• javax.xml.registry, which consists of the API interfaces and classes that define the registry access interface.

• javax.xml.registry.infomodel, which consists of interfaces that define the information model for JAXR. These interfaces define the types of objects that reside in a registry and how they relate to each other. The basic interface in this package is the RegistryObject interface.

The most basic interfaces in the javax.xml.registry package are

• Connection. The Connection interface represents a client session with a registry provider. The client must create a connection with the JAXR provider in order to use a registry.

• RegistryService. The client obtains a RegistryService object from its connection. The RegistryService object in turn enables the client to obtain the interfaces it uses to access the registry.

The primary interfaces, also part of the javax.xml.registry package, are

• QueryManager and BusinessQueryManager, which allow the client to search a registry for information in accordance with the javax.xml.registry.infomodel interfaces. An optional interface, DeclarativeQueryManager, allows the client to use SQL syntax for queries. The ebXML provider for the Registry implements DeclarativeQueryManager.

• LifeCycleManager and BusinessLifeCycleManager, which allow the client to modify the information in a registry by either saving the information (updating it) or deleting it.

For more details, and for a figure that illustrates the relationships among these interfaces, see the API documentation for the javax.xml.registry package at http://java.sun.com/j2ee/1.4/docs/api/javax/xml/registry/package-summary.html.

When an error occurs, JAXR API methods throw a JAXRException or one of its subclasses.

Many methods in the JAXR API use a Collection object as an argument or a returned value. Use of a Collection object allows operations on several registry objects at a time.

Figure 1–1 illustrates the architecture of JAXR. For the Registry, a JAXR client uses the capability level 0 and level 1 interfaces of the JAXR API to access the JAXR provider, which is an ebXML provider. The JAXR provider in turn accesses the Registry, an ebXML registry.

Figure 1–1 JAXR Architecture

About the Examples

Many sample client programs that demonstrate JAXR features are described in this manual. To obtain these examples, go to the following URL: http://www.sun.com/products/soa/registry/#faq/. A zip file that contains the examples is available in the Resources section.

Download the zip file to any convenient location on your file system. After you unzip the file, the example source code is in the directory <INSTALL>/registry/samples, where <INSTALL> is the directory where you unzipped the examples.

Each example or group of examples has a build.xml file that allows you to compile and run each example using the asant tool. Each build.xml file has a compile target and one or more targets that run the example or examples. Some of the run targets take command-line arguments.

The asant command is in the Sun Java System Application Server bin directory, which is usually /opt/SUNWappserver/appserver/bin/ in the Solaris^TM Operating System and /opt/sun/appserver/bin on Linux systems.

Before you run the examples, you must edit two files in the directory <INSTALL>/registry/samples/common. The file build.properties is used by the asant targets that run the programs. The file JAXRExamples.properties is a resource bundle that is used by the programs themselves.

In addition, a targets.xml file in the <INSTALL>/registry/samples/common directory defines the classpath for compiling and running the examples. It also contains a clean target that deletes the build directory created when each example is compiled. You do not need to edit this file.

To Edit the build.properties File

Steps

1. Set the property container.home to the location of the container where the Registry is deployed.

   This is the location of your installation of the Sun Java System Application Server Enterprise Edition 8.1. By default, this location is /opt/SUNWappserver on Solaris systems and /opt/sun/appserver on Linux systems.

2. Set the property registry.home to the directory where the Registry is installed.

   This directory is /opt/SUNWsoar on Solaris systems and /opt/sun/SUNWsoar on Linux systems.

3. Set the property registry.domain.home to the directory where the Registry domain is installed.

   This directory is /var/opt/SUNWsoar/domains/registry on Solaris systems and /var/opt/sun/SUNWsoar/domains/registry on Linux systems.

4. Set the property proxyHost to the name of the system through which you access the Internet, if you are behind a firewall.

   If you are not sure what the value should be, consult your system administrator or another person with that information. The proxyPort value is set to 8080, the typical value; change this value if necessary.

To Edit the JAXRExamples.properties File

Steps

1. Edit the properties query.url and publish.url to specify the URL of the Registry.

   The file provides a default setting of localhost:6060 for the host and port. Change this setting to another host or port if the Registry is installed on a remote server or at a non-default port.

2. Edit security properties to specify the properties that are required for publishing to the Registry. Make these edits after you use the User Registration Wizard of the Web Console. See Getting Access to the Registry for details.

3. Feel free to change any of the data in the remainder of the file as you experiment with the examples.

   The asant targets that run the client examples always use the latest version of the file.