Service Registry 3.1 Developer's Guide

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

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:

ebXML Registry Services and Protocols Version 3.0 (“ebXML RS”) defines the services and protocols for an ebXML Registry.
ebXML Registry Information Model Version 3.0 (“ebXML RIM”) defines the types of metadata and content that can be stored in an ebXML Registry.

Service Registry is based on an open source registry project developed at SourceForge.net. The web site for the SourceForge project contains a Wiki with additional information about ebXML registries, including an overview.

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 interfaces, classes, and methods that implement the ebXML specifications. These additional interfaces, classes, and 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. If you installed the developer bundle for the registry, a zip file containing these examples is in the file ServiceRegistry-base/samples.zip.

Copy this 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 Ant 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.

On a system where the Service Registry developer bundle is installed, the ant command is in the following directory:

On Solaris OS: /usr/sfw/bin

On Linux and HP-UX systems: /opt/sun/share/bin

This manual refers to this directory as Ant-base.

The ant command requires the JAVA_HOME environment variable to be set. Ordinarily, you set this variable to the following value:

/usr/jdk/entsys-j2se

Before you run the examples, you must edit the build.properties file in the directory INSTALL/registry-samples/common. This file is used by the Ant targets that run the examples.

The other properties file, JAXRExamples.properties, is a resource bundle that is used by the examples themselves. It contains strings that you can modify at any time. The Ant targets that run the examples always use the latest version of the file.

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.

Note –

You can find additional JAXR examples in the form of Junit tests at the SourceForge project web site. You can browse these examples online or follow the download instructions.

To Edit the `build.properties` File

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

On Solaris OS: /opt/SUNWsrvc-registry

On Linux and HP-UX systems: /opt/sun/srvc-registry

Set the property share.dir to the directory where the Java ES shared components are located.

On Solaris OS: /usr/share

On Linux and HP-UX systems: /opt/sun/share

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.

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

The file provides a default setting of localhost:6480 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.

Edit the alias and password properties to specify the values 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.