JBoss.orgCommunity Documentation

Apache jUDDI Client and GUI Guide

 

Alex O'Ree

Apache Software Foundation (ASF)
Apache Software Foundation (ASF), http://juddi.apache.org
Legal Notice

We’d like to dedicate this guide to Steve Viens and Andy Cutright who started this project back in 2003.

Table of Contents

Preface
1. Simple Publishing Using the jUDDI API
1.1. UDDI Data Model
1.2. jUDDI Additions to the Model
1.3. UDDI and jUDDI API
1.4. Getting Started
1.4.1. Simple Publishing Example
1.4.2. About UDDI Entity Keys
1.5. A few tips on adding Binding Templates
1.6. Conclusion
2. jUDDI Client Configuration Guide
2.1. Introduction
2.2. Client Settings
2.3. Nodes
2.3.1. Transport Options
2.4. Clerks
2.5. Clerk
2.6. Digital Signatures
2.7. Subscription Callbacks
2.8. XtoWsdl
2.9. Embedded jUDDI server
2.9.1. Requirements
2.9.2. Changes in configuration compared to non-embedded
3. Key Format Templates
3.1. UDDIv3 key format
3.2. jUDDI key format templates
3.2.1. Advantages of using a template
3.2.2. Default UDDIKeyConvention Key Templates
3.2.3. How to use the templates?
3.2.4. Where to define to properties?
4. Using the jUDDI GUI
4.1. Requirements
4.2. Tasks
4.2.1. Your first sign on
4.3. The Menu Bar
4.4. Logging in to UDDI Services
4.5. Logging Out
4.6. Discover (Browse UDDI)
4.6.1. Business Browser
4.6.2. Service Browser
4.6.3. tModel Browser
4.6.4. Search
4.7. Creating new Entities
4.7.1. Create a tModel
4.7.2. Create a tModek Key Generator (Partition)
4.7.3. Create a Business
4.7.4. Create a Service
4.7.5. Import from WSDL or WADL
4.8. Custody Transfers
4.9. Publisher Assertions
4.10. Subscriptions
4.10.1. Create a new subscription
4.10.2. View My Subscriptions
4.10.3. View the News Feed
4.11. Using Digital Signatures in juddi-gui
4.11.1. Sign a Business, Service or tModel
4.11.2. Verify a signed UDDI entity
4.12. Configuration
4.13. Language Codes
4.14. Switching Nodes
5. Mapping WSDL and WSDL to UDDI
5.1. Introduction
5.2. Use Case - WSDL
5.2.1. Sample Code
5.2.2. Links to sample project
5.3. Use Case - WADL
5.3.1. Sample Code
5.3.2. Links to sample project
6. Using UDDI Annotations
6.1. UDDI Service Annotation
6.2. UDDIServiceBinding Annotation
6.2.1. Java Web Service Example
6.2.2. Wiring it all together
6.3. .NET Web Service Example
6.3.1. Wiring it all together
6.4. CategoryBag Attribute
6.5. Considerations for clustered or load balanced web servers and automated registration
7. Using the UDDI v2 Services and Adapters
7.1. Introduction
7.2. Accessing UDDI v2 services using the jUDDI v3 Client
7.3. Accessing UDDI v2 services using UDDI v2 APIs
7.4. Accessing jUDDI v3 services from an existing UDDI v2 based client, plugin or tool
7.5. Additional Information
8. UDDI Migration and Backup Tool
8.1. Using the tool
8.1.1. Get help
8.1.2. Use case: basic import and export
8.1.3. Use case: Import and Export while preserving ownership information
9. Using the jUDDI REST Services
9.1. URL Patterns and methods
9.1.1. Endpoints
9.1.2. Methods
9.2. Example Output
9.2.1. XML
9.2.2. JSON
9.3. More information
10. jUDDI Client for NET
10.1. Procedure
11. Using the UDDI Technology Compatibility Kit
11.1. Using the TCK Runner
11.1.1. Configuration
11.1.2. Running the TCK Runner
11.2. Analyzing the Results
Index

List of Figures

4.1. Welcome to jUDDI, Please select a language.
4.2. Full menu bar for computers or large displays.
4.3. Tablet/Mobile menu bar for small displays.
4.4. The Menu Bar.
4.5. Login Warning.
4.6. Browse Options.
4.7. Browse Business.
4.8. Browse Business Zoomed in.
4.9. Service Browser.
4.10. tModel Browser.
4.11. Search.
4.12. Create a tModel Key Generator (Partition).
4.13. Create Business.
4.14. How to Add and Delete items.
4.15. Business Editor’s Section.
4.16. Add a Service via Business Browser.
4.17. Add a Service via Business Editor.
4.18. Importing a Service from WSDL or WADL.
4.19. Custody Transfer.
4.20. Publisher Assertion.
4.21. Create a Subscription, Specific Item or Search Results.
4.22. Create a Subscription, Add an item using the chooser.
4.23. Create a Subscription, Item Added.
4.24. Create a Subscription, Delivery Mechanism.
4.25. Create a Subscription, Options.
4.26. View Subscriptions.
4.27. Select an entity, then click Digitally Sign.
4.28. Java Plugin Warnings.
4.29. Select a Signing Certificate.
4.30. Certificate Details.
4.31. Signature Settings.
4.32. Valid Signed Entity.
4.33. Invalid Signed Entity.
4.34. Node Switcher.

List of Tables

6.1. UDDIService attributes
6.2. UDDIServiceBinding attributes

The jUDDI client framework facilitates interaction with any UDDI v3 compliant registry. In addition to providing a client framework for both Java and .NET, it also provides a self proclaimed Technical Compatilibity Test (TCK) Suite. The jUDDI community encourages collabration of other vendors on the TCK or on the client framework in general.

One of the most common requests we get on the message board is "How do I publish a service using jUDDI?" This question holds a wide berth, as it can result anywhere from not understanding the UDDI data model, to confusion around how jUDDI is set up, to the order of steps required to publish artifacts in the registry, to general use of the API - and everything in between. This article will attempt to answer this "loaded" question and, while not going into too much detail, will hopefully clear some of the confusion about publishing into the jUDDI registry.

Before you begin publishing artifacts, you need to know exactly how to break down your data into the UDDI model. This topic is covered extensively in the specification, particularly in section 3, so I only want to gloss over some for details. Readers interested in more extensive coverage should most definitely take a look at the UDDI specification.

Below is a great diagram of the UDDI data model (taken directly from the specification): http://juddi.apache.org/docs/3.x/userguide/html/images/uddi_core_datastructures.gif As you can see, data is organized into a hierarchical pattern. Business Entities are at the top of the pyramid, they contain Business Services and those services in turn contain Binding Templates. TModels (or technical models) are a catch-all structure that can do anything from categorize one of the main entities, describe the technical details of a binding (ex. protocols, transports, etc), to registering a key partition. TModels won’t be covered too much in this article as I want to focus on the three main UDDI entities.

The hierarchy defined in the diagram is self-explanatory. You must first have a Business Entity before you can publish any services. And you must have a Business Service before you can publish a Binding Template. There is no getting around this structure; this is the way UDDI works.

Business Entities describe the organizational unit responsible for the services it publishes. It generally consist of a description and contact information. How one chooses to use the Business Entity is really dependent on the particular case. If you’re one small company, you will likely just have one Business Entity. If you are a larger company with multiple departments, you may want to have a Business Entity per department. (The question may arise if you can have one uber-Business Entity and multiple child Business Entities representing the departments. The answer is yes, you can relate Business Entities using Publisher Assertions, but that is beyond the scope of this article.)

Business Services are the cogs of the SOA landscape. They represent units of functionality that are consumed by clients. In UDDI, there’s not much to a service structure; mainly descriptive information like name, description and categories. The meat of the technical details about the service is contained in its child Binding Templates.

Binding Templates, as mentioned above, give the details about the technical specification of the service. This can be as simple as just providing the service’s access point, to providing the location of the service WSDL to more complicated scenarios to breaking down the technical details of the WSDL (when used in concert with tModels). Once again, getting into these scenarios is beyond the scope of this article but may be the subject of future articles.

Out of the box, jUDDI provides some additional structure to the data model described in the specification. Primarily, this is the concept of the Publisher.

The UDDI specification talks about ownership of the entities that are published within the registry, but makes no mention about how ownership should be handled. Basically, it is left up to the particular implementation to decide how to handle "users" that have publishing rights in the registry.

Enter the jUDDI Publisher. The Publisher is essentially an out-of-the-box implementation of an identity management system. Per the specification, before assets can be published into the registry, a "publisher" must authenticate with the registry by retrieving an authorization token. This authorization token is then attached to future publish calls to assign ownership to the published entities.

jUDDI’s Publisher concept is really quite simple, particularly when using the default authentication. You can save a Publisher to the registry using jUDDI’s custom API and then use that Publisher to publish your assets into the registry. jUDDI allows for integration into your own identity management system, circumventing the Publisher entirely if desired. This is discussed in more detail in the documentation, but for purposes of this article, we will be using the simple out-of-the-box Publisher solution.

Tip

In UDDI, ownership is essentially assigned to a given registry entity by using its "authorizedName" field. The "authorizedName" field is defined in the specification in the operationalInfo structure which keeps track of operational info for each entity. In jUDDI, the authorizedName field translates to the person’s username, also know as the publisher id,

Knowing the UDDI data model is all well and good. But to truly interact with the registry, you need to know how the UDDI API is structured and how jUDDI implements this API. The UDDI API is covered in great detail in chapter 5 of the specification but will be summarized here.

UDDI divides their API into several "sets" - each representing a specific area of functionality. The API sets are listed below:

  • Inquiry - deals with querying the registry to return details on entities within
  • Publication - handles publishing entities into the registry
  • Security - open-ended specification that handles authentication
  • Custody and Ownership Transfer - deals with transferring ownership and custody of entities
  • Subscription - allows clients to retrieve information on entities in a timely manner using a subscription format
  • Subscription Listener - client API that accepts subscription results
  • Value Set (Validation and Caching)- validates keyed reference values (not implemented by jUDDI)
  • Replication - deals with federation of data between registry nodes (not implemented by jUDDI) The most commonly used APIs are the Inquiry, Publication and Security APIs. These APIs provide the standard functions for interacting with the registry.

The jUDDI server implements each of these API sets as a JAX-WS compliant web service and each method defined in the API set is simply a method in the corresponding web service. The client module provided by jUDDI uses a "transport" class that defines how the call is to be made. The default transport uses JAX-WS but there are several alternative ways to make calls to the API. Please refer to the documentation for more information.

One final note, jUDDI defines its own API set. This API set contains methods that deal with handling Publishers as well as other useful maintenance functions (mostly related to jUDDI’s subscription model). This API set is obviously proprietary to jUDDI and therefore doesn’t conform to the UDDI specification.

Now that we’ve covered the basics of the data model and API sets, it’s time to get started with the publishing sample. The first thing that must happen is to get the jUDDI server up and running. Please refer to this http://apachejuddi.blogspot.com/2010/02/getting-started-with-juddi-v3.html article that explains how to start the jUDDI server.

We will now go over the "simple-publish" examples. These examples expand upon the HelloWorld example in that after retrieving an authentication token, a BusinessEntity and BusinessService are published to the registry. There are two examples:

  • simple-publish-portal - This is how to perform the publish operations in a way that’s portable, meaning that the code logic should apply to any UDDIv3 client application library.
  • simple-publish-clerk - This shows you how to perform the same actions using the helper functions in jUDDI’s Client library, which greatly reduces the code required and makes things simple. This uses the UDDIClerk’s functions.

The complete source for this example can be found here: - Portable http://svn.apache.org/repos/asf/juddi/trunk/juddi-examples/simple-publish-portable/

        public SimplePublishPortable() {
                try {
                        // create a client and read the config in the archive;
                        // you can use your config file name
                        UDDIClient uddiClient = new UDDIClient("META-INF/uddi.xml");
                        // a UddiClient can be a client to multiple UDDI nodes, so
                        // supply the nodeName (defined in your uddi.xml.
                        // The transport can be WS, inVM, RMI etc which is defined in the uddi.xml
                        Transport transport = uddiClient.getTransport("default");
                        // Now you create a reference to the UDDI API
                        security = transport.getUDDISecurityService();
                        publish = transport.getUDDIPublishService();
                } catch (Exception e) {
                        e.printStackTrace();
                }
        }

The constructor uses the jUDDI client API to retrieve the transport from the default node. You can refer to the documentation if you’re confused about how clerks and nodes work. Suffice it to say, we are simply retrieving the default client transport class which is designed to make UDDI calls out using JAX-WS web services.

Once the transport is instantiated, we grab the two API sets we need for this demo: 1) the Security API set so we can get authorization tokens and 2) the Publication API set so we can actually publish entities to the registry.

All the magic happens in the publish method. We will look at that next.

Here are the first few lines of the publish method:

                        // Login aka retrieve its authentication token
                        GetAuthToken getAuthTokenMyPub = new GetAuthToken();
                        getAuthTokenMyPub.setUserID("bob");                    //your username
                        getAuthTokenMyPub.setCred("bob");                          //your password
                        AuthToken myPubAuthToken = security.getAuthToken(getAuthTokenMyPub);
                        System.out.println(getAuthTokenMyPub.getUserID() + "'s AUTHTOKEN = " + "******* never log auth tokens!");

Important

Don’t log authentication tokens. In addition, whenever you’re done with it, it should be discarded. Think of it as a logout function.

This code simply gets the authorization token for the bob user.

Tip

jUDDI includes two reserved usernames, uddi and root. Root acts as the "administrator" for jUDDI API calls. Additionally, the root user is the owning publisher for all the initial services installed with jUDDI. You may be wondering what those "initial services" are. Well, since the UDDI API sets are all implemented as web services by jUDDI, every jUDDI node actually registers those services inside itself. This is done per the specification. The user uddi owns the remaining preinstalled data.

Now that we have Bob’s authorization, we can start publishing.

Tip

You’ll note that no credentials have been set on both authorization calls. This is because we’re using the default authenticator (which is for testing purposes doesn’t require credentials). Most UDDI servers will require authentication.

            // 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...
            // <snip> We removed some stuff here to make the example shorter, check out the source for more info</snip>

            // 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);

            //and we're done, don't forget to logout!
            security.discardAuthToken(new DiscardAuthToken(myPubAuthToken.getAuthInfo()));

To summarize, here we have created and saved a BusinessEntity and then created and saved a BusinessService. We’ve just added the bare minimum data to each entity. Obviously, you would want to fill out each structure with greater information, particularly with services. However, this is beyond the scope of this article, which aims to simply show you how to programmatically publish entities.

The complete source for this example can be found here: - Clerk http://svn.apache.org/repos/asf/juddi/trunk/juddi-examples/simple-publish-clerk/

The sample consists of only one class: SimplePublishPortable. Let’s start by taking a look at the constructor:

        public SimplePublishClerk() {
                try {
                        // create a client and read the config in the archive;
                        // you can use your config file name
                        UDDIClient uddiClient = new UDDIClient("META-INF/uddi.xml");
                        //get the clerk
                        clerk = uddiClient.getClerk("default");
                        if (clerk==null)
                                throw new Exception("the clerk wasn't found, check the config file!");
                } catch (Exception e) {
                        e.printStackTrace();
                }
        }

Notice that this is already much more streamlined than the previous example. In this scenario, all configuration settings and credentials are stored in "META-INF/uddi.xml".

Tip

The configuration file used by clients can be overridden via the system property "uddi.client.xml". E.g. java -Duddi.client.xml=/usr/local/uddi.xml -jar MyCoolProgram.jar

UDDIClient’s job is to read the configuration file and initialize the data structures for working with 1 or more UDDI nodes (or servers). It also handles automatic registration of endpoints using WSDL documents or using class annotations. UDDIClerk’s job is to manage credentials and to perform a number of common tasks. Feel free to use them in your programs and help you simplify things.

The UDDIClerk also handle credentials and authentication to UDDI for you. If you didn’t want to store credentials (it can be encrypted) then you can specify them at runtime very easily.

Moving on, the next function is Publish. Here’s the short short version.

public void publish() {
              try {
                        // 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);
                        //<snip>we removed a bunch of useful stuff here, see the full example for the rest of it</snip>

                        //register the business, if the return value is null, something went wrong!
                        BusinessEntity register = clerk.register(myBusEntity);
                        //don't forget to log out!
                        clerk.discardAuthToken();
                        if (register == null) {
                                System.out.println("Save failed!");
                                System.exit(1);
                        }
                        // Now you have a business and service via
                        // the jUDDI API!
                        System.out.println("Success!");

                } catch (Exception e) {
                        e.printStackTrace();
                }
        }

The UDDIClerk has a register and unregister function for nearly everything for UDDI. Between the UDDIClient and UDDIClerk, there’s enough helper functions to significantly reduce the amount of code needed to work with UDDI. Here’s a quick list of things they can do for you:

  • Create a tModel Partition, also know as a Key Generator
  • Resolve endpoints from WSDLs, Hosting directors, and other binding template references from Access Points http://uddi.org/pubs/uddi-v3.0.2-20041019.htm#_Toc85908385
  • Get Bindings by Version
  • Add REST or SOAP tModels to a binding template
  • Setup asynchronous callbacks for subscriptions
  • Compare the values of a tModel Instance Info, such as Quality of Service Metrics
  • Create and register services using a WADL or WSDL document
  • And more…

We’re also looking for the next thing to add to the client library. Have an idea? Please open a ticket on jUDDI’s Issue Tracker at https://issues.apache.org/jira/browse/JUDDI.

At least one node is required per client. A node represents a one logical UDDI server (or cluster of servers). Each UDDI node should host at least the inquiry service. A client using the jUDDI client package can be configured to access multiple nodes at the same time.

<!-- if isHomeJUDDI is true, then this node is loaded by default, when no node is specified in client code -->
uddi/client/nodes[]/node@isHomeJUDDI=true/false
<!-- the name of the node is referenced in client code -->
uddi/client/nodes[]/node/name
<!-- the description of the node -->
uddi/client/nodes[]/node/description
<!-- the properties section defines HTTP style credentials and a runtime tokenizer for URLs -->
uddi/client/nodes[]/node/properties
<!-- The transport represents the class name of the transport mechanism that the client will use to connect
to the UDDI node. The most commonly used is org.apache.juddi.v3.client.transport.JAXWSTransport, however
RMITransport, InVMTransport and JAXWSv2TranslationTransport are also defined -->
uddi/client/nodes[]/node/proxyTransport

<!-- endpoint URLs -->
uddi/client/nodes[]/node/custodyTransferUrl
uddi/client/nodes[]/node/inquiryUrl
uddi/client/nodes[]/node/publishUrl
uddi/client/nodes[]/node/securityUrl
uddi/client/nodes[]/node/subscriptionUrl
uddi/client/nodes[]/node/subscriptionListenerUrl
<!-- note: this is for jUDDI v3.x servers only and is not part of the UDDI standard -->
uddi/client/nodes[]/node/juddiApiUrl

The Signature section contains settings that map to the Digital Signature Utility that makes working with UDDI digital signatures simple. The section contains all of the settings for both signing and validating signatures.

uddi/client/signature/signingKeyStorePath
uddi/client/signature/signingKeyStoreFilePassword
uddi/client/signature/signingKeyStoreFilePassword@isPasswordEncrypted
uddi/client/signature/signingKeyStoreFilePassword@cryptoProvider
uddi/client/signature/signingKeyPassword
uddi/client/signature/signingKeyPassword@isPasswordEncrypted
uddi/client/signature/signingKeyPassword@cryptoProvider
uddi/client/signature/signingKeyAlias
uddi/client/signature/canonicalizationMethod
uddi/client/signature/signatureMethod=(default RSA_SHA1)
uddi/client/signature/XML_DIGSIG_NS=(default http://www.w3.org/2000/09/xmldsig#)
uddi/client/signature/trustStorePath
uddi/client/signature/trustStoreType
uddi/client/signature/trustStorePassword
uddi/client/signature/trustStorePassword@isPasswordEncrypted
uddi/client/signature/trustStorePassword@cryptoProvider
<!-- checks signing certificates for timestamp validity -->
uddi/client/signature/checkTimestamps
<!-- checks signing certificates for trust worthiness -->
uddi/client/signature/checkTrust
<!-- checks signing certificates for revocation -->
uddi/client/signature/checkRevocationCRL
uddi/client/signature/keyInfoInclusionSubjectDN
uddi/client/signature/keyInfoInclusionSerial
uddi/client/signature/keyInfoInclusionBase64PublicKey
<!-- default is http://www.w3.org/2000/09/xmldsig#sha1 -->
uddi/client/signature/digestMethod

jUDDI has the ability to run in embedded mode. This means that the jUDDI services can operate without a web servlet container, such as Tomcat or JBoss. Typically, this is something that application developers would use for more advanced scenarios and for operation without network connectivity.

The jUDDI client has taken the key format approach one step further so the name part of the key actually helps you understand what the key is for, or even better in the case of a binding template what server registered the key.

Starting with jUDDI v3.2, a nearly full featured UDDI v3 compliant web user interface is included called the jUDDI Graphical User Interface, or jUDDI GUI. It is also referred to as the jUDDI Console, or jUDDI User Console. The jUDDI GUI is a web application that can run in most web servlet containers, such as Tomcat and can be deployed along side of the jUDDI Web Services war (juddiv3.war). From the jUDDI GUI, users can browse, search, create, update, digitally sign and delete most UDDI entities, as well as preform custody transfers, configure subscriptions.

As of version 3.2, the jUDDI GUI supports the complete functionality of the following UDDI services

  • Inquiry
  • Publish
  • Security
  • Custody Transfer
  • Subscription

The following sections detail how to perform basic tasks using the jUDDI GUI. Hopefully, the user interface is intuitive enough that thorough guidance isn’t necessary.

All of the Browse pages support pagination, that is you can flip through the pages of the database, as if it were a phone book.

In addition, search results can be filtered by language. On each Discover page, you will see the following


Click on "Click to Edit", enter your desired language code, then either press enter, or click "Ok" and the results will be filtered automatically. See "Language Codes" for more information.

The jUDDI GUI has the ability to create and register new UDDI entities.

Important

If you want to create your own UDDI keys (recommended) rather than use the not so user friendly server generated GUID values, then you’ll have to make a Key Generator first! Read on!

A tModel Key Generator is a special kind of tModel that enables you to define your own keys (for anything in UDDI) for your own "domain". A "domain" is similar to the Domain Name System used by the Internet to resolve user friendly names, such as www.apache.org, to an IP address. This effectively allows you to define any arbitrary UDDI key prefix that you want. For example, if you wanted a UDDI key defined as "uddi:www.mycompany.com:salesbusiness1", you would first have to create a tModel key generator (partition) with the value of "uddi:www.mycompany.com:keygenerator". TModel keys must start with "uddi:" and end with ":keygenerator". This is part of the UDDI specification and acts as a governance mechanism. You can also create a tModel Key Generator by using the Create tModel menu option and by adding the appropriate settings (assuming you know the secret sauce) or you can simply click on the word Create from the top navigation bar and select tModel Partition (Key Generator).


Tip

You can also use nested partitions such as "uddi:www.mycompany.com:keygenerator" and "uddi:www.mycompany.com:sales:keygenerator". UDDI uses the colon ":" as a separator for partitions. This will enable you to make UDDI keys such as "uddi:www.mycompany.com:biz1" and "uddi:www.mycompany.com:sales:biz2".

Tip

UDDI key names can be at MOST 255 characters long!

The UDDI Business entity enables you to define and advertise your business with a variety of ways. To create a new business, simply click on the word Create from the top navigation bar and select Business.

Tip

The "Create", "Business" page is also the same page to use when editing an existing business.


Businesses in UDDI only require you to define at least one name. All of fields are optional. Business entities can have 0 or more of just about everything. For now, let’s just make a Name, give it a Value and then save our new business. To add a new Name, click the "+" button next to the "Name". Then click on "Click to edit" next to "Value". If you make a mistake or wish to remove the "Name" or any other element, click on the trash can.


If you read the previous section on tModel Key Generators, then you know all about UDDI keys. This is your one and only chance to get it right. Once your done, click "Save". Congrats! You’ve just made your first UDDI business!

Important

When working with UDDI entities, you cannot change the UDDI key after it has been created.

The Business Editor/Creator web page, along with the other editor/creator pages, has a ton of other interesting things that you can do. Since there’s way too much stuff to look at, we broke them up into logical sections.


In case you can’t see the picture above:

  • General - Names and Descriptions
  • Discovery URLs - Usually a link to a web page
  • Contacts - Points of Contact, such as Sales, Tech Support, etc
  • Categories - These reference tModels and act as a way to categorize your business.
  • Identifiers - Can be used for Tax IDs, DUNS Number, or anything else that you can think of.
  • Services - This is the meat and potatoes of UDDI, advertising all the great services that your business provides.
  • Signatures - Digital Signatures prevent tampering
  • Operational Info - Who created it and when
  • Related Businesses - This is where people can find out if you have a business relationship with someone else. It’s also called Publisher Assertions.

Tip

Clicking on each tab will supply additional information.

Tip

If a business, service, or tModel is signed, the juddi-gui will automatically attempt to validate the signature. You’ll see a thumbs up or thumbs down icon to let you know.

Subscriptions in UDDI are used to easily detect when changes are made to a UDDI node.

To create a new subscription, you must first be logged in. Click on Home, then Create Subscription.

Subscriptions can either be for a set of specific items or for search results.


In our example, we’ve selected a set of specific items.

Create a Subscription, Select Items.  image::images/juddi-gui-subscription2.png[Create a Subscription, Select Items

To add an item to the list, click on Add. The item chooser will appear. Check each item to add them to the list. To remove, select the item, then click remove.


Specific items are added by entity keys.


Next is the delivery mechanism. The UDDI node can deliver the notifications to you if you have your own implementation of the UDDI Subscription Listener service. (The juddi-client contains this for you if you were looking to develop a solution). In addition, the UDDI node can email the results to you (in XML format).

The other option is to periodically poll the UDDI server and get your subscription results (see the News Feed).

Here, we’ve selected the, I’ll pick them up, option.


The final slider provides subscription options. * Expiration - a date where the subscription expires * Notification Interval - this is only used when the UDDI node sends the notifications to you via the Subscription Listener Service * Brief - If true, the UDDI node will only tell you which items have changed, not what the change was.


The juddi-gui makes working with digital signatures simple and enables you do digitally sign and protect entities right from the web browser. It allows you to sign business, services and tModels.

Tip

Digital signatures are performed using the jUDDI Digital Signature Applet which requires a Java plugin for your web browser, as well as a digital certificate (X509).

Tip

You also need to have an X509 Certificate installed in either your Windows My/Current User Certificate Store or your MacOS Key Chain certificate store.

OASIS published a technical article which describes the recommended way to map the entries from a WSDL (Web Service Description Language) document into UDDI (https://www.oasis-open.org/committees/uddi-spec/doc/tn/uddi-spec-tc-tn-wsdl-v202-20040631.htm). The jUDDI-client provides a convenient mechanism for this mapping. In addition, the jUDDI team provides a similar API for mapping a WADL (Web Application Description Language) document to UDDI. This guide will help you use the APIs to register a WSDL or WADL document that describes a service within a UDDI registry.

The most basic use case is that we have one or more SOAP/WSDL based services from a 3rd party that was just stood up on our network and we wish to now advertise to our user base that this service exists. We could manually punch in the information, but what fun is that? Let’s import it using some code! This can be expanded to import services in bulk.

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.

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.


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.

The UDDI Migration and Backup Tool can be used to perform a number of administrative tasks such as

  • Backup the contents of a UDDI server (business, services, binding templates and tModels)
  • Import contents into a UDDI server (business, services, binding templates and tModels)

In addition, the migration tool has a few features that serve as job aids.

  • Ability to remove digital signatures on Import or Export
  • Ability to maintain ownership properties of UDDI entries
  • Ability to export and import Publishers (jUDDI only)
  • Automatically skip an item on import if the entity key already exists

The UDDI Migration and Backup Tool is Command Line Interface program and has a number of use cases such as:

  • Copying data from one registry to another
  • Migrating from one vendor to another
  • Periodic backups
  • Upgrades to jUDDI

Tip

The migration tool will not overwrite data when importing.

There are many configuration options and settings for the migration tool. This tool is distributed with the uddi client distribution package.

>java -jar juddi-migration-tool-3.2.0-SNAPSHOT-jar-with-dependencies.jar
This tool is used to export and import UDDI data from a UDDI v3 registry
Random TIP: Without the preserveOwnership flag, all imported data will be owned by the username that imported it.

usage: java -jar juddi-migration-tool-(VERSION)-jar-with-dependencies.jar
 -business <arg>      Im/Export option, file to store the business data,
                      default is 'business-export.xml'
 -config <arg>        Use an alternate config file default is 'uddi.xml'
 -credFile <arg>      Import option with -preserveOwnership, this is a
                      properties file mapping with user=pass
 -export              Exports data into a UDDIv3 registry
 -import              Imports data into a UDDIv3 registry
 -isJuddi             Is this a jUDDI registry? If so we can in/export
                      more stuff
 -mappings <arg>      Im/Export option, file that maps keys to owners,
                      default is 'entityusermappings.properties'
 -myItemsOnly         Export option, Only export items owned by yourself
 -node <arg>          The node 'name' in the config, default is 'default'
 -pass <arg>          Password, if not defined, those is uddi.xml will be
                      used
 -preserveOwnership   Im/Export option, saves owership data to the
                      'mappings' file
 -publishers <arg>    jUDDI only - In/Export option, file to store
                      publishers, default is 'publishers-export.xml'
 -stripSignatures     Im/Export option, removes digital signatures from
                      all signed items, default is false
 -tmodel <arg>        Im/Export for tmodels, file to store tmodel data,
                      default is 'tmodel-export.xml'
 -user <arg>          Username, if not defined, those is uddi.xml will be
                      used

jUDDI includes a Inquiry API adapter that exposes some of the basic functionality of UDDI via REST. Data can be retrieved in both XML and JSON encoding for all methods.

  1. All jUDDI Inquiry REST service are accessible via HTTP GET.
  2. Authentication is not yet supported. This also implies that the Inquiry API must be configured for anonymous access (i.e. do not turn on Inquiry Authentication Required).
  3. The jUDDI Inquiry REST service is not currently portable as an adapter to other UDDI instances (but it could be adapted to it in the future)

All endpoints must be prefixed with http(s)://server:port/juddicontext/ where juddicontext is typically juddiv3.

WADL Document: http://localhost:8080/juddiv3/services/inquiryRest?_wadl

Tip

All of the examples in this document reference JSON encoded messages. To switch to XML messages, just replace the JSON with XML in the URL. That’s it!

Each method is accessible using the following pattern:

http://localhost:8080/juddiv3/services/inquiryRest/{encoding}/{method}/{parameters}
//or
http://localhost:8080/juddiv3/services/inquiryRest/{encoding}/{method}?{name=value}

Notes

  • Encoding - Can be XML or JSON
  • Methods - See below
  • Parameters - usually a unique UDDI key

The output of JSON encoded messages is obviously different than XML. The following is an example of what it looks like.

{
    "businessEntity": {
        "@businessKey": "uddi:juddi.apache.org:businesses-asf",
        "discoveryURLs": {
            "discoveryURL": {
                "@useType": "homepage",
                "$": "http://localhost:8080/juddiv3"
            }
        },
        "name": {
            "@xml.lang": "en",
            "$": "An Apache jUDDI Node"
        },
        "description": {
            "@xml.lang": "en",
            "$": "This is a UDDI v3 registry node as implemented by Apache jUDDI."
        },
        "businessServices": {
            "businessService": [
                {
                    "@serviceKey": "uddi:juddi.apache.org:services-custodytransfer",
                    "@businessKey": "uddi:juddi.apache.org:businesses-asf",
                    "name": {
                        "@xml.lang": "en",
                        "$": "UDDI Custody and Ownership Transfer Service"
                    },
                    "description": {
                        "@xml.lang": "en",
                        "$": "Web Service supporting UDDI Custody and Ownership Transfer API"
                    },
                    "bindingTemplates": {
                        "bindingTemplate": [
                            {
                                "@bindingKey": "uddi:juddi.apache.org:servicebindings-custodytransfer-ws",
                                "@serviceKey": "uddi:juddi.apache.org:services-custodytransfer",
                                "description": "UDDI Custody and Ownership Transfer API V3",
                                "accessPoint": {
                                    "@useType": "wsdlDeployment",
                                    "$": "http://localhost:8080/juddiv3/services/custody-transfer?wsdl"
                                },
                                "tModelInstanceDetails": {
                                    "tModelInstanceInfo": {
                                        "@tModelKey": "uddi:uddi.org:v3_ownership_transfer",
                                        "instanceDetails": {
                                            "instanceParms": "\n                \n                <?xml version=\"1.0\" encoding=\"utf-8\" ?>\n                <UDDIinstanceParmsContainer\n                 xmlns=\"urn:uddi-org:policy_v3_instanceParms\">\n                  <authInfoUse>required</authInfoUse>\n                </UDDIinstanceParmsContainer>\n                \n                "
                                        }
                                    }
                                },
                                "categoryBag": {
                                    "keyedReference": {
                                        "@tModelKey": "uddi:uddi.org:categorization:types",
                                        "@keyName": "uddi-org:types:wsdl",
                                        "@keyValue": "wsdlDeployment"
                                    }
                                }
                            },
                            {
                                "@bindingKey": "uddi:juddi.apache.org:servicebindings-custodytransfer-ws-ssl",
                                "@serviceKey": "uddi:juddi.apache.org:services-custodytransfer",
                                "description": "UDDI Custody and Ownership Transfer API V3 SSL",
                                "accessPoint": {
                                    "@useType": "wsdlDeployment",
                                    "$": "https://localhost:8443/juddiv3/services/custody-transfer?wsdl"
                                },
                                "tModelInstanceDetails": {
                                    "tModelInstanceInfo": [
                                        {
                                            "@tModelKey": "uddi:uddi.org:v3_ownership_transfer",
                                            "instanceDetails": {
                                                "instanceParms": "\n                \n                <?xml version=\"1.0\" encoding=\"utf-8\" ?>\n                <UDDIinstanceParmsContainer\n                 xmlns=\"urn:uddi-org:policy_v3_instanceParms\">\n                  <authInfoUse>required</authInfoUse>\n                </UDDIinstanceParmsContainer>\n                \n                "
                                            }
                                        },
                                        {
                                            "@tModelKey": "uddi:uddi.org:protocol:serverauthenticatedssl3"
                                        }
                                    ]
                                },
                                "categoryBag": {
                                    "keyedReference": {
                                        "@tModelKey": "uddi:uddi.org:categorization:types",
                                        "@keyName": "uddi-org:types:wsdl",
                                        "@keyValue": "wsdlDeployment"
                                    }
                                }
                            }
                        ]
                    }
                }
            ]
        },
        "categoryBag": {
            "keyedReference": {
                "@tModelKey": "uddi:uddi.org:categorization:nodes",
                "@keyName": "",
                "@keyValue": "node"
            }
        }
    }
}

Since 3.2, the majority of the functions in the jUDDI Client for Java have been ported to .NET. This guide will show you how to use it and integrate it with your own .NET based applications.

  1. Add a reference to jUDDI-Client.NET.dll
  2. Add a reference to System.Web.Services
  3. Add a reference to System.ServiceModel
  4. Add a reference to System.Xml
  5. Add a reference to System.Runtime.Serialization
  6. Add a reference to System.Configuration
  7. Add a reference to System.Security
  8. Add a copy of the sample uddi.xml file. Modify it to meet your environment and operational needs.
  9. Note, many of the settings are identical to the Java jUDDI-client. The APIs are also nearly identical, so example code should be easily portable from one language to another.

Sample Code

/*
 * Copyright 2001-2013 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */
using org.apache.juddi.v3.client;
using org.apache.juddi.v3.client.config;
using org.apache.juddi.v3.client.transport;
using org.uddi.apiv3;
using System;
using System.Collections.Generic;
using System.Text;


namespace juddi_client.net_sample
{
    class Program
    {
        static void Main(string[] args)
        {
            UDDIClient clerkManager = new UDDIClient("uddi.xml");
            UDDIClientContainer.addClient(clerkManager);
            Transport transport = clerkManager.getTransport("default");

            org.uddi.apiv3.UDDI_Security_SoapBinding security = transport.getUDDISecurityService();
            org.uddi.apiv3.UDDI_Inquiry_SoapBinding inquiry = transport.getUDDIInquiryService();

            UDDIClerk clerk = clerkManager.getClerk("default");


            find_business fb = new find_business();
            fb.authInfo = clerk.getAuthToken(security.Url);
            fb.findQualifiers = new string[] { UDDIConstants.APPROXIMATE_MATCH };
            fb.name = new name[1];
            fb.name[0] = new name(UDDIConstants.WILDCARD, "en");
            businessList bl = inquiry.find_business(fb);
            for (int i = 0; i < bl.businessInfos.Length; i++)
            {
                Console.WriteLine(bl.businessInfos[i].name[0].Value);
            }
            Console.Read();

        }
    }
}

The sample code above should print out a list of all businesses currently registered in the registry. If credentials are stored in the uddi.xml file and are encrypted, they will be decrypted automatically for you.

Within the jUDDI Source Tree, there are many different examples of how to use the jUDDI Client for .NET. They are available here: http://svn.apache.org/repos/asf/juddi/trunk/juddi-client.net/juddi-client.net-sample/

Since UDDI is a specification with many complex rules in it, we (the jUDDI team) have had to write test cases to exercise each of the rules and restrictions in UDDI. Knowing that there are a number of open source and commercial UDDI v3 implementations, the jUDDI team took this as an opportunity to create a reusable benchmark for testing the compatibility of UDDI v3 implementations.

Important

Although the TCK covers a large number of test cases, the UDDI specification is long and complex. It’s more than possible that we missed a few scenarios or test cases. If you run across any, please let us know.

The TCK Runner requires a few files to operate:

  1. juddi-tck-runner-version.jar - This is the executable
  2. uddi.xml - This file sets the location of the UDDI services
  3. tck.properties - This file controls what tests are ran.
  4. truststore and keystore.jks - These files are for digital signature tests
  • Edit the uddi.xml file and update all of the UDDI endpoint locations for all supported endpoints of UDDI server being tested. Ignore all credentials and other settings
  • Edit tck.properties and update the usernames and passwords of the test users. Enable or disable tests based on the whether or not the UDDI server supports the optional listed capabilities.

Tip

Do not use usernames and passwords that already have data associated with it.

A few of the test cases, such as RMI transport, are not identified by the UDDI specification, therefore the results may be skewed if unsupported tests are attempted. In addition, the UDDI specification identifies a number of APIs and features that are considered optional.

Although it is possible to run the TCK against a UDDIv2 registry using the UDDIv2 transport adapters, this is not supported. The TCK’s test cases and rules apply to the business rules defined in UDDIv3. Unsupported and unmapped functions defined in UDDIv3 that are not supported in UDDIv2 fail ultimately fail.