Chapter 6. Using UDDI Annotations

Conventionally Services (BusinessService) and their EndPoints (BindingTemplates) are registered to a UDDI Registry using a GUI, where an admin user manually adds the necessary info. This process tends to make the data in the Registry rather static and the data can grow stale over time. To make the data in the UDDI more dynamic it makes sense to register and EndPoint (BindingTemplate) when it comes online, which is when it gets deployed. The UDDI annotations are designed to just that: register a Service when it get deployed to an Application Server. There are two annotations: UDDIService, and UDDIServiceBinding. You need to use both annotations to register an EndPoint. Upon undeployment of the Service, the EndPoint will be de-registered from the UDDI. The Service information stays in the UDDI. It makes sense to leave the Service level information in the Registry since this reflects that the Service is there, however there is no EndPoint at the moment ("Check back later"). It is a manual process to remove the Service information. The annotations use the juddi-client library which means that they can be used to register to any UDDIv3 registry.

6.1. UDDI Service Annotation

The UDDIService annotation is used to register a service under an already existing business in the Registry. The annotation should be added at the class level of the java class.

Table 6.1. UDDIService attributes

attribute	description	required
serviceName	The name of the service, by default the clerk will use the one name specified in the WebService annotation	no
description	Human readable description of the service	yes
serviceKey	UDDI v3 Key of the Service	yes
businessKey	UDDI v3 Key of the Business that should own this Service. The business should exist in the registry at time of registration	yes
lang	Language locale which will be used for the name and description, defaults to "en" if omitted	no
categoryBag	Definition of a CategoryBag, see below for details	no

6.2. UDDIServiceBinding Annotation

The UDDIServiceBinding annotation is used to register a BindingTemplate to the UDDI registry. This annotation cannot be used by itself. It needs to go along side a UDDIService annotation.

Table 6.2. UDDIServiceBinding attributes

attribute	description	required
bindingKey	UDDI v3 Key of the ServiceBinding	yes
description	Human readable description of the service	yes
	accessPointType UDDI v3 AccessPointType, defaults to wsdlDeployment if omitted	no
accessPoint	Endpoint reference	yes
lang	Language locale which will be used for the name and description, defaults to "en" if omitted	no
tModelKeys	Comma-separated list of tModelKeys key references	no
categoryBag	Definition of a CategoryBag, see below for further details	no

6.2.1. Java Web Service Example

The annotations can be used on any class that defines a service. Here they are added to a WebService, a POJO with a JAX-WS WebService annotation.

package org.apache.juddi.samples;

import javax.jws.WebService;
import org.apache.juddi.v3.annotations.UDDIService;
import org.apache.juddi.v3.annotations.UDDIServiceBinding;

@UDDIService(
  businessKey="uddi:myBusinessKey",
  serviceKey="uddi:myServiceKey",
  description = "Hello World test service")
@UDDIServiceBinding(
  bindingKey="uddi:myServiceBindingKey",
  description="WSDL endpoint for the helloWorld Service. This service is used for "
				  + "testing the jUDDI annotation functionality",
  accessPointType="wsdlDeployment",
  accessPoint="http://localhost:8080/juddiv3-samples/services/helloworld?wsdl")
@WebService(
  endpointInterface = "org.apache.juddi.samples.HelloWorld",
  serviceName = "HelloWorld")

public class HelloWorldImpl implements HelloWorld {
    public String sayHi(String text) {
        System.out.println("sayHi called");
        return "Hello " + text;
    }
}

On deployment of this WebService, the juddi-client code will scan this class for UDDI annotations and take care of the registration process. The configuration file uddi.xml of the juddi-client is described in the chapter, Using the jUDDI-Client. In the clerk section you need to reference the Service class org.apache.juddi.samples.HelloWorldImpl:

<clerk name="BobCratchit" node="default" publisher="sales" password="sales">
     <class>org.apache.juddi.samples.HelloWorldImpl</class>
</clerk>

which means that Bob is using the node connection setting of the node with name "default", and that he will be using the "sales" publisher, for which the password it "sales". There is some analogy here as to how datasources are defined.

6.2.2. Wiring it all together

The mechanism that triggers the automated registration is the UDDIClient. For each class you annotation, the class needs to be listed in the jUDDI Client Configuration file. When the client reads in the configuration, it will read the uddi.xml config file for the following location:

client/clerks/clerk[].class

In addition, the following flag must be set to true.

client/clerks@registerOnStartup="true"

Here’s a full example

<clerks registerOnStartup="false" >
    <clerk name="default" node="default" publisher="userjoe" password="******" cryptoProvider="" isPasswordEncrypted="false">
        <class>com.mybiz.services.Service1</class>
    </clerk>
</clerks>

The next step is to automate the "starting" and "stopping" of UDDIClient. In Java, anything that runs in a servlet container and use the following servlet class:

org.apache.juddi.v3.client.config.UDDIClerkServlet

It will automatically handle registration on start up and it will remove binding Templates on shutdown (this ensuring clients that discover the endpoint won’t find a dead link).

Clients that run elsewhere simply need to "start" the UDDIClient.

//start up
UDDIClient clerkManager = new UDDIClient("META-INF/uddi.xml");
// register the clerkManager with the client side container
UDDIClientContainer.addClient(clerkManager);
clerkManager.start(); //will create business/services/bindings as necessary

//shutdown down
clerkManager.stop(); //will unregister binding templates

<categoryBag>
    <keyedReference tModelKey="uddi:uddi.org:categorization:types"
     keyName="uddi-org:types:wsdl" keyValue="wsdlDeployment" />
    <keyedReference tModelKey="uddi:uddi.org:categorization:types"
     keyName="uddi-org:types:wsdl2" keyValue="wsdlDeployment2" />
</categoryBag>

can be put in like

categoryBag="keyedReference=keyName=uddi-org:types:wsdl;keyValue=wsdlDeployment;" +
            "tModelKey=uddi:uddi.org:categorization:types," +
                     "keyedReference=keyName=uddi-org:types:wsdl2;keyValue=wsdlDeployment2;" +
            "tModelKey=uddi:uddi.org:categorization:types2",

6.5. Considerations for clustered or load balanced web servers and automated registration

Most production environments have primary and failover web servers and/or an intelligent load balancer that routers traffic to whichever server is online. When using automated registration with the jUDDI client, care must be taken when enabling automated registration.