Red Hat Training

A Red Hat training course is available for JBoss Enterprise SOA Platform

Chapter 4. Simple Publishing via the API

4.1. UDDI Data Model

UDDI organises data into the following hierarchy:
Business entities
Business entities are at the top of the pyramid. They contain business services.
Business services
Business services contain end-point references.
To model your data in a form consistent with this hierarchy, you must first create a business entity before you can publish any services and you must create a business service before you can publish any binding templates.

4.2. Business Entity

Business Entities are the organisational units responsible for the services. They contain information (consisting of a description and contact information) about the parties who are publishing services. How you choose to use the business entities depends on your situation. If you have a small company, you may only need one entity. If you are a larger company with multiple departments, you may want to have one entity per department.
Another possibility is to have one overarching entity with multiple child entities representing the departments. To do so, you create relationships between the entities by using publisher assertions.

4.3. Business Service

Business services represent units of functionality that are consumed by clients. In UDDI, a service mainly consists of descriptive information such as a name, a description and categories. The technical details about the service are actually contained in its binding templates instead.

4.4. End-Point Reference

An end-point reference (EPR) contains the address information and technical specifications for a service. Indeed, all ESB-aware services are identified using end-point references. It is through these references that services are contacted. The are stored in the registry. Services add their end-point references to the registry when they are launched and should automatically remove them when they terminate. A service may have multiple end-point references. End-point references are also known as binding templates.
End-point references can contain links to the tModels designating the interface specifications for a particular service.

4.5. UDDI and the jUDDI API

In order to use the UDDI API, you must understand how it is structured. It is divided into several sets. Each set represents a specific area of functionality:
  • Inquiry handles queries to the Registry for details about entities.
  • Publication handles the registration of entities.
  • Security is an open-ended specification that handles authentication.
  • Custody and Ownership Transferhandles the transference of ownership of entities.
  • Subscription allows clients to retrieve information about entities using a subscription format.
  • Subscription Listener is a client API for accepting subscription results.
  • Value Set (Validation and Caching) validates keyed reference values. (This set is not yet available for the jUDDI.)
  • Replication allows you to federate data between registry nodes. (This set is not yet available for the jUDDI.)
The sets you will use most frequently are Inquiry, Publication and Security. They provide the standard functions you need for interacting with the Registry.
The jUDDI server implements each of these sets as a JAX-WS-compliant web service. (Each method defined in a set is simply a method in the corresponding web service.)
The jUDDI provides a client module that uses a transport class to define how each call is to be made. (The default transport uses JAX-WS but there are several alternative ways to make calls to the API.)
Finally, the jUDDI also defines its own API set. This API set contains methods that deal with handling Publishers and other maintenance functions, mostly related to the jUDDI’s subscription model. This API set is specific to jUDDI and does not conform to the UDDI specification.

4.6. jUDDI Additions to the UDDI Model

Introduction

The jUDDI Registry's implementation provides the data model with some additional structure beyond that described in the specification. Prime amongst this is the concept of the publisher.

The UDDI specification mentions the ownership of the entities that are published within the registry, but makes no mention of how this ownership should be implemented. It is left up to the individual implementation.
Publisher is an identity management system that provides this functionality for the jUDDI Registry.
Before assets can be added to the jUDDI, the Registry authenticates the publisher by allowing it to retrieve an authorisation token. This token is attached to subsequent publish calls to assign ownership to the published entities.
You can save a publisher to the jUDDI Registry by using the latter's custom API.
The Publisher is an out-of-the-box implementation of an identity management system. jUDDI also allows for integration into your own identity management system, circumventing the Publisher entirely if desired. In this guide, we will be using the simple out-of-the-box Publisher solution.

4.7. Tutorial: Use the Service Registry for the First Time

This tutorial steps you through the a simple example. In this example, after retrieving an authentication token, a Publisher, a BusinessEntity and a BusinessService are registered in the jUDDI.

Procedure 4.1. Task

  1. Instantiate the SimplePublish class. Here is the constructor:
          public SimplePublish() 
    {
        try 
        {
            String clazz = UDDIClientContainer.getUDDIClerkManager(null).
                getClientConfig().getUDDINode("default").getProxyTransport();
            Class<?> transportClass = ClassUtil.forName(clazz, Transport.class);
            if (transportClass!=null) 
            {
                Transport transport = (Transport) transportClass.
                    getConstructor(String.class).newInstance("default");
    
                security = transport.getUDDISecurityService();
                juddiApi = transport.getJUDDIApiService();
                publish = transport.getUDDIPublishService();
            }	
        } 
        catch (Exception e) 
        {
            e.printStackTrace();
        }	
    }
    
    This constructor uses the jUDDI client API to retrieve the transport from the default node. In this example, it is simply retrieving the default client transport class which is designed to make UDDI calls out using JAX-WS web services.
  2. Obtain the three API sets needed for the example:
    • the Security API set, so you can obtain authorisation tokens,
    • the proprietary jUDDI API set so you can save a publisher,
    • the Publication API set so that you can register entities in the jUDDI.
    Here are the first few lines of the publish method:
     // Setting up the values to get an authentication token for the 'root' user 
    // ('root' user has admin privileges and can save other publishers).
    GetAuthToken getAuthTokenRoot = new GetAuthToken();
    getAuthTokenRoot.setUserID("root");
    getAuthTokenRoot.setCred("");
    
    // Making API call that retrieves the authentication token for the 'root' user.
    AuthToken rootAuthToken = security.getAuthToken(getAuthTokenRoot);
    System.out.println ("root AUTHTOKEN = " + rootAuthToken.getAuthInfo());
    
    This code simply retrieves the authorisation token for the root user.
  3. Add a publisher:
    // Creating a new publisher that we will use to publish our entities to.
    Publisher p = new Publisher();
    p.setAuthorizedName("my-publisher");
    p.setPublisherName("My Publisher");
    
    // Adding the publisher to the "save" structure, using the 'root' user authentication 
    // info and saving away. 
    SavePublisher sp = new SavePublisher();
    sp.getPublisher().add(p);
    sp.setAuthInfo(rootAuthToken.getAuthInfo());
    juddiApi.savePublisher(sp);
    
    The code above uses the jUDDI API to save a publisher with authorised name, my-publisher. Note that the authorisation token for the root user is utilised.
  4. Obtain the authorisation token for this new publisher:
     // Our publisher is now saved, so now we want to retrieve its authentication token
    GetAuthToken getAuthTokenMyPub = new GetAuthToken();
    getAuthTokenMyPub.setUserID("my-publisher");
    getAuthTokenMyPub.setCred("");
    AuthToken myPubAuthToken = security.getAuthToken(getAuthTokenMyPub);
    System.out.println ("myPub AUTHTOKEN = " + myPubAuthToken.getAuthInfo());
    
    Note that no credentials have been set on either of the authorisation calls. This is because, by using the default authenticator, you do not have to provide any.
  5. Publish:
    // Creating the parent business entity that will contain our service.
    BusinessEntity myBusEntity = new BusinessEntity();
    Name myBusName = new Name();
    myBusName.setValue("My Business");
    myBusEntity.getName().add(myBusName);
    
    // Adding the business entity to the "save" structure, using our publisher's 
    // authentication info and saving away.
    SaveBusiness sb = new SaveBusiness();
    sb.getBusinessEntity().add(myBusEntity);
    sb.setAuthInfo(myPubAuthToken.getAuthInfo());
    BusinessDetail bd = publish.saveBusiness(sb);
    String myBusKey = bd.getBusinessEntity().get(0).getBusinessKey();
    System.out.println("myBusiness key:  " + myBusKey);
    
    // Creating a service to save.  Only adding the minimum data: the parent 
    // business key retrieved from saving the business above and a single name.
    BusinessService myService = new BusinessService();
    myService.setBusinessKey(myBusKey);
    Name myServName = new Name();
    myServName.setValue("My Service");
    myService.getName().add(myServName);
    // Add binding templates, etc...
    
    // Adding the service to the "save" structure, using our publisher's 
    // authentication info and saving away.
    SaveService ss = new SaveService();
    ss.getBusinessService().add(myService);
    ss.setAuthInfo(myPubAuthToken.getAuthInfo());
    ServiceDetail sd = publish.saveService(ss);
    String myServKey = sd.getBusinessService().get(0).getServiceKey();
    System.out.println("myService key:  " + myServKey);
    

    Note

    There are some important things to note with regard to the use of entity keys. Version three of the specification allows for publishers to create their own keys but also instructs implementers to have default methods.
    Red Hat has chosen the default implementation approach by leaving each entity’s key field blank in the save call. The jUDDI’s default key generator simply takes the node’s partition and appends a GUID to it.
    In a default installation, it will look something like this: uddi:juddi.apache.org:<GUID>
    (You can, of course, customise all of this if you wish.)
    The second important point is that when the BusinessService is saved, its parent business key (retrieved from previous call saving the business) is set explicitly. This is a necessary step when the service is saved in an independent call like this because, otherwise, you would encounter an error as the jUDDI will not know where to find the parent entity.
Result

In this example you have created and saved a BusinessEntity and then created and saved a BusinessService. You have added the bare minimum of data to each entity (and, in fact, have not added any BindingTemplates to the service).

In a real life scenario, you will obviously want to fill out each structure with greater information, particularly with regard to services. However, this will prove a useful starting point.