JAXR, the Java API for XML Registries, provides a standard API for publication and discovery of Web services through underlying registries.
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.
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.
When publication or discovery of Web services is required, UDDI is the mechanism the WS-I Basic Profile has adopted to describe Web service providers and the Web services they provide.
NOTE, because WS-I BP sanctions the use of UDDI, not ebXML, we MUST use JAXR level 0 profile.
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 (we MUST use this interface according to WS-I BP 1.1)
LifeCycleManager - for level 1 (we MUST NOT use this interface according to WS-I BP 1.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 (we MUST use this interface according to WS-I BP 1.1)
DeclarativeQueryManager - for level 1 (we MUST NOT use this interface according to WS-I BP 1.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 Organization, Service, ServiceBinding, ClassificationScheme, and Concept. 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 Classification, ExternalIdentifier, ExternalLink, and Association objects. The BusinessQueryManager often uses those collections as parameters in its find methods.
Also specializations of the RegistryObject interface, the concrete interfaces Organization, Service, ServiceBinding, Concept, and ClassificationScheme provide additional state information. For example, the Organization interface defines a collection of Service objects, and Service defines a collection of ServiceBinding objects. A ServiceBinding might contain a collection of SpecificationLink objects. UDDI developers should be familiar with these concrete interfaces; they map quite well to major UDDI data types shown in the table below:
Table 6.1. UDDI-to-JAXR information model mappings
|JAXR Information Model||UDDI Data Model|
A business, such as a corporation whose data is contained in the registry, is represented by an Organization instance. An Organization can have multiple Organizations under it or can refer to another organization as a parent. An Organization can offer one or more services, represented by Service objects which can be accessed via Collection Organization.getServices() method.
The businessEntity structure contains information about a particular business organization and holds references to the services it offers. businessEntity is the highest in the hierarchy and contains descriptive information. Each businessEntity is identified by its businessKey. If its businessKey is not specified at publication time, the registry will automatically generate a key.
Each Service can have multiple ServiceBinding objects that specify the details about the protocol binding information for that service.
businessService entry indicates a logical service and holds descriptive information about a Web service in business terms. A businessService is a child of a businessEntity that provides the service. Information about how a businessService can be instantiated is contained within a bindingTemplate. Each businessService is has a unique identifier - serviceKey. This value is assigned by each UDDI operator and cannot be edited by the publisher. It also contains the key to its parent businessEntity - businessKey.
ServiceBinding has attributes that describe the location where the service can be accessed. A ServiceBinding is associated with one or more SpecificationLink objects that point to the technical specifications defining the service (e.g., a WSDL file for the Web service). ServiceBinding instances are RegistryObject objects that represent technical information on a specific way to access a specific interface offered by a Service instance. A ServiceBinding may have a set of SpecificationLink instances. Maps to a bindingTemplate in UDDI.
A bindingTemplate contains information necessary for a client to invoke a service. It specifies the information for a particular Web service and provides the URL of the service where it can be invoked. The bindingTemplate also contains references to tModels as well as service-specific settings. A bindingTemplate is a child of a businessService.
A ClassificationScheme instance represents a taxonomy that may be used to classify or categorize RegistryObject instances. The classification scheme, or taxonomy, can be internal or external to the registry, meaning that the structure of the taxonomy is defined internal to the registry or is represented somewhere outside the registry and is represented by a ClassificationScheme interface. A good example of an external taxonomy for e-business is that of North American Industry Classification System (NAICS) devised by the U.S. Census Bureau. NAICS is a classification scheme used to classify businesses and services by the industry to which they belong and the business processes they follow.
The Concept interface is used to represent taxonomy elements and their structural relationship with each other in order to describe an internal taxonomy. Concept instances are used to define tree structures where the root of the tree is a ClassificationScheme instance and each node in the tree is a Concept instance. As any RegistryObject, a Concept may be classified and also associated with a set of external identifiers and links.
A RegistryObject instance may be associated with zero or more RegistryObject instances. The information model defines an Association interface, an instance of which may be used to associate any two RegistryObject instances. An Association instance represents an association between a source RegistryObject and a target RegistryObject. These are referred to as sourceObject and targetObject for the Association instance. It is important which object is the sourceObject and which is the targetObject as it determines the directional semantics of an Association. Each Association must have an associationType attribute that identifies the type of that association. The associationType attribute is a reference to an enumeration Concept as defined by the predefined associationType ClassificationScheme in the JAXR specification. An association may need to be confirmed by the parties whose objects are involved in that Association.
ExternalLink instances model a named URI to content that may reside outside the registry. RegistryObject may be associated with any number of ExternalLink instances to annotate a RegistryObject with external links to external content. Consider the case where a Submitting Organization submits a repository item (e.g. a DTD) and wants to associate some external content to that object (e.g. the Submitting Organization's home page). The ExternalLink enables this capability.
The Classification interface is used to classify RegistryObject instances. A RegistryObject may be classified along multiple dimensions by adding zero or more Classification instances to the RegistryObject. For example, an Organization may be classified by its industry, by the products it sells and by its geographical location. In this example the RegistryObject would have at least three Classification instances added to it. The RegistryObject interface provides several addClassification methods to allow a client to add Classification instances to a RegistryObject.
|keyedReference (in categoryBag)|
ExternalIdentifier instances provide the additional identifier information to RegistryObject such as DUNS number, Social Security Number, or an alias name of the organization. The attribute name inherited from RegistryObject is used to contain the identification scheme (Social Security Number, etc), and the attribute value contains the actual information. Each RegistryObjects may have 0 or more association(s) with ExternalIdentifier.
|keyedReference (in identifierBag)|
|Collection of ExternalIdentifier instances||identifierBag|
|Collection of Classification instances||categoryBag|
A SpecificationLink provides the linkage between a ServiceBinding and one of its technical specifications that describes how to use the service using the ServiceBinding. For example, a ServiceBinding may have a SpecificationLink instance that describes how to access the service using a technical specification in form of a WSDL document. It serves the same purpose as the union of tModelInstanceInfo and instanceDetails in UDDI.
The union of tModelInstanceInfo and instanceDetails
UDDI Example Mapped to JAXR:
Table 6.2. Mapping of UDDI Inquiry API Calls To JAXR (BusinessQueryManager)
|UDDI Method||BusinessQueryManager Method|
|get_bindingDetail||Not needed. Handled transparently by JAXR provider|
|get_businessDetail||Not needed. Handled transparently by JAXR provider|
|get_businessDetailExt||Unsupported. Use RegistryService.makeRegistrySpecificRequest|
|get _serviceDetail||Not needed. Handled transparently by JAXR provider|
|get_tModelDetail||Not needed. Handled transparently by JAXR provider|
Table 6.3. Mapping of UDDI Publisher API Calls to JAXR (BusinessLifeCycleManager)
|UDDI Method||BusinessLifeCycleManager Method|
|add_publisherAssertions||saveAssociations(associations, replace), Association.confirm|
NOTE, In UDDI delete_tModel does not delete the tModel. It simply hides it from find_tModel calls. The QueryManager.getRegistryObject calls will still return the deleted tModel after a deleteConcepts or deleteClassificationSchemes call.
|discard_authToken||Not needed. Handled transparently by JAXR provider|
|get_assertionStatusReport||findAssociations(findQulifiers, associationTypes, sourceObjectConfirmed, targetObjectConfirmed)|
|get_authToken||Not needed. Handled transparently by JAXR provider|
The JAXR specification defines the following information model interfaces:
Organization instance is a RegistryObject that provides information on an organization that has been published to the underlying registry.
Service instance is a RegistryObject that provides information on services (e.g., Web Service) offered by an Organization. An Organization can have a set of Service objects.
ServiceBinding instance is a RegistryObject that represents technical information on how to access a specific interface offered by a Service instance. A Service can have a collection of ServiceBinding objects.
SpecificationLink links a ServiceBinding with its technical specifications that describe how to use the service. For example, a ServiceBinding might have SpecificationLink instances that describe how to access the service using a technical specification in the form of a WSDL (Web Services Description Language) document.
ClassificationScheme instance represents a taxonomy that you can use to classify or categorize RegistryObject instances.
Classification instances classify a RegistryObject instance using a classification scheme. Because classification facilitates rapid discovery of RegistryObject instances within the registry, the ability to classify RegistryObject instances in a registry is one of the registry's most significant features.
Concept instance represents an arbitrary notion, or concept. It can be virtually anything.
Association instances define many-to-many associations between objects in the information model.
RegistryPackage instances group together logically related RegistryObject instances. A RegistryPackage might contain any number of RegistryObject instances, and a RegistryObject can be a member of any number of RegistryPackage objects.
ExternalIdentifier instances provide identification information to a RegistryObject. You can base such identification on well-known identification schemes such as DUNS (D&B's Data Universal Numbering System) number and social security number.
ExternalLink instances provide a link to content managed outside the registry using a URI (uniform resource identifier).
Slot instances dynamically add arbitrary attributes to RegistryObject instances at runtime, an ability that enables extensibility within the information model.
Most interfaces in the JAXR information model extend the ExtensibleObject interface. It provides methods that allow the addition, deletion, and lookup of Slot instances.
AuditableEvent instances are RegistryObject instances that provide an audit trail for RegistryObject instances.
Affiliated with Organization, User objects are RegistryObject instances that provide information about registered users within the registry. You use User objects in a RegistryObject's audit trail.
PostalAddress defines a postal address's attributes. Currently, it provides address information for a User and an Organization.