Friday, November 13, 2009

UDDI Annotations - How do I self-register my service?

So you just installed jUDDI, and you're all proud you managed to get it up and running, but now you're asking yourself: "How do I register my own services?". You have a few options actually.

  • 1. You can do it programmatically using the juddi-client UDDIv3 API library, check out the code in the TckBusinessService class for some inspiration.
  • 2. You can do it programmatically using the JAXR API. Apache Scout supports both the v2 and v3 UDDI protocols.
  • 3. You can use a console, although the current jUDDI-portal based console only supports browsing at the moment, but you could pretty easily extend it and contribute it back.
  • 4. You can use annotations, jUDDI v3 introduces annotations that can be used to register a (web-)service at deploy time. I think that this is by far the easiest way to go about it. This is what I'm going to discuss in the blog post.

Annotations on (Web)Services Example

Let's start with an example: the HelloWorldService. Using the JAX-WS WebService annotation the simplest implementation of this class would look like:

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;

and when using CXF the beans.xml would need the following entry

<jaxws:endpoint id="helloworld" implementor="org.apache.juddi.samples.HelloWorldImpl"
address="/helloworld" />

to bring it up under the http://localhost:8080/juddiv3-samples/helloworld if you deploy the juddiv3-samples war.
To enable registration at deploy time of this service you can use two UDDI annotations; one to register the service and one to register the endpoint, UDDIService and UDDIServiceBinding respectively. For example the annotations may look like

description = "Hello World test service")
description="WSDL endpoint for the hello${department} Service. This service is used for testing the jUDDI annotation functionality",

Next you need to instruct a clerk to do the registration at deploy time. A clerk is UDDI publisher that can work from the back office, by candle light, no heat, you get the picture. We call him "BobCratchit". Bob needs to know which UDDI registry to publish to and under what UDDI publisher. All of this is defined in the META-INF/uddi.xml file.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<manager name="example-manager">
<description>Sales jUDDI node</description>
<property name="serverName" value="sales"/>
<property name="serverPort" value="8080"/>
<property name="keyDomain" value=""/>
<property name="department" value="sales" />
<clerks registerOnStartup="true">
<clerk name="BobCratchit" node="default" publisher="sales" password="sales">

A uddi.xml file can contain only one manager entry and the manager should have a name that is unique to your deployment environment. Within the manager you can specific as many nodes and clerks as you want. Each node contains the UDDI v3 endpoints of the UDDIv3 internal services. Each clerk must reference a node, and it must be supplied with the credentials of the publisher account. In this example we have:

<clerk name="BobCratchit" node="default" publisher="sales" password="sales">

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. Finally you reference the class that contains the annotations in the clerk block. Make sure to have the juddi-client and uddi-ws jars on your classpath and you should be good to go.
Note that the juddiv3-samples.war ships with jUDDI-3.0.0 for you to get started.


serviceNameThe name of the service, by default the clerk will use the one name specified in the WebService annotation.optional
descriptionHuman readable description of the servicerequired
serviceKeyUDDI v3 Key of the Servicerequired
businessKeyUDDI v3 Key of the Business that should own this Service. The business should exist in the registry at time of registrationrequired
langLanguage locale which will be used for the name and description, defaults to "en" if omittedoptional
categoryBagDefinition of a CategoryBag, see below for detailsoptional


The UDDIServiceBinding annotation cannot be used by itself at the moment. It needs to go along side a UDDIService annotation.

bindingKeyUDDI v3 Key of the ServiceBindingrequired
descriptionHuman readable description of the servicerequired
accessPointTypeUDDI v3 AccessPointType, defaults to wsdlDeployment if omittedoptional
accessPointEndpoint referencerequired
langLanguage locale which will be used for the name and description, defaults to "en" if omittedoptional
tModelKeysComma-separated list of tModelKeys key referenceoptional
categoryBagDefinition of a CategoryBag, see below for detailsoptional


The CategoryBag is an optional element in both the UDDIService and UDDIServiceBinding annotation. Represented as XML a CategoryBag can contain a list of keyedReferences, for example
<keyedReference tModelKey="" keyName="uddi-org:types:wsdl" keyValue="wsdlDeployment" />
<keyedReference tModelKey="" keyName="uddi-org:types:wsdl2" keyValue="wsdlDeployment2" />

in the annotation this would look like
categoryBag="keyedReference=keyName=uddi-org:types:wsdl;keyValue=wsdlDeployment;," +

For a complete example you can check one of the unittests.
If you now check the jUDDI portal, in the browser you should see the HelloWorld Service

Dynamic Runtime Properties

The downside of using annotations is that after your class is compiled it is hard to change the values set in the annotations. In particular when a field contains runtime dependent value like the hostname and port this becomes a problem. Therefor we added support to define custom properties in the 'node' section of the uddi.xml.

<property name="serverName" value="sales"/>
<property name="serverPort" value="8080"/>

These properties are then referenced in the annotation like:



jUDDI-3.0.0 introduces a client side library which contain annotations for self-registration of a service and its binding at deployment time, and unregistration of the serviceBinding at undeploy time. This library can be used with any UDDI v3 compliant Registry.

Thursday, October 29, 2009

jUDDI-3.0.0 Released!

I'm proud to announce that jUDDI-3.0.0 is released! jUDDI now supports all the required UDDIv3 APIs. jUDDI-3.0.0 has a lot of new and exiting features, some of which are
  • Implements all the UDDIv3 required APIs.
  • Plugin architecture for Cryption and Authentication.
  • Flexible way of seeding your UDDI node.
  • Using the following specifications to keep the jUDDI code base small
    • JPA (tested with OpenJPA and Hibernate) and
    • JAXB (tested with SUNs implementation, and native JDK6)
    • JAX-WS (tested with CXF)
  • Annotations to Self-Register/UnRegister your services and their Bindings.
  • Support for multi-node UDDI setups using the client and server-side Subscription APIs.
  • Introduction of the "UDDI Clerk" concept to support cross registration of UDDI entities.
  • UDDI Console with GWT based portlets
    • Browse portlet
    • Search portlet
    • Subscription portlet
    • Publisher portlet
  • Ready-to-go bundles: juddi-tomcat and juddi-portal.
  • Run in Embedded mode, RMI or SOAP.
  • Tested to work with Scout-1.2 (JAXR).
  • Integrated into JBossESB.
  • In production for the past 6 months at eSigma.
  • Tested with both SUN and OpenJDK JDKs.
  • Tested under load using XLT test suite.
Each of these bullet-points really needs its own blog post! Until then please check out the User Guide for more details.


the jUDDI team

Friday, October 23, 2009

Release of Scout-1.2 adds UDDI v3 support

The Scout team is proud to announce the release of Scout-1.2, Scout is an implementation of the JAXR specification (Java API for XML Registries). The Scout-1.2 release adds UDDI v3 support. To find out more you can visit the Scout Project.

The Scout team wants to know if you are using JAXR for anything but communicating to a UDDI registry. Are you interested in support for ebXML?



Thursday, October 15, 2009

Release jUDDI 3.0.0.rc1

Last week we got to a Release Candidate for 3.0.0, which has been through some pretty rigorous load testing performed by Xceptance Software Technologies, Inc and Global Quality Partners, LLC. The 3.0 codebase has been running in production at eSigma for the better half of a year now, and the JBossESB project has recently integrated the 3.0.0.rc1 into their trunk. An interesting detail there is that the integration uses JAXR (Java API for XML Registries) and Apache Scout-1.2 now supports both the UDDIv2 and the UDDIv3 spec in the back end.

We've been working hard and any day now we will start a vote for 3.0.0 final.



Wednesday, October 14, 2009

jUDDI IRC channel

If you want to talk UDDI come look us up on IRC using #juddi. At least you will find our juddi-bot there reporting on the status of the integration builds :). The integration builds are now running on Buildbot. The IRC logs can be found here:


Tuesday, August 11, 2009

jUDDI 2.0.1 released

The SQL scripts provided with the jUDDI v2 release where updated.



Tuesday, July 28, 2009

Release jUDDI v2 - Thank you Steve Viens

The release of jUDDI v2 marks the beginning of a new era.

jUDDI is the brainchild of Steve Viens, who led the project from the inception year of 2003 to 2007. jUDDI started as project on SourceForge and was into the Apache Incubator in Oct 8, 2003. The project graduated to the Apache Web Services Project in March 24, 2004. In 2004 the project pushed to get to a 1.0 release, and the jUDDI-0.9rc3 release turned out to be a strong candidate. The move to Apache gave the project more visibility and the different 0.9 release candidates have been bundled with many Application Servers. Thank you Steve for building a UDDI community and for all the hard work to get jUDDI where it is now!

Recently we changed the major release version to 2, this to line up the jUDDI version with the UDDI spec version she implements.

jUDDIv2 implements the UDDIv2 specification
jUDDIv3 implements the UDDIv3 specification

To easiest way to get started with jUDDI is to download the juddi-tomcat-2.0.0 bundle. This is a ready to go jUDDI server running on Tomcat. Once this is running you can read up on how to switch from the embedded Derby database to let's say MySQL. If you have question please browse through the answers given on the jUDDI mailing lists. If you don't find one, simply get involved and ask your own question.

What's next?

With jUDDIv2 released we can now fully focus on implementing the UDDI v3 specification. More on that later.