JBoss.orgCommunity Documentation

Apache jUDDI 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

1. Universal Description, Discovery and Integration (UDDI)
1.1. UDDI Protocol, Specification
1.2. UDDI Registry
1.3. jUDDI Project
2. Getting Started
2.1. Prerequisites
2.2. What should I Download?
2.3. Running jUDDI
2.4. Using the jUDDI Administrative Interface
2.5. Using jUDDI Web Services
2.6. Using jUDDI GUI to create your keygenerator and business
2.7. Running the demos in the disto
2.8. Examples on the jUDDI blog
2.9. What is new in jUDDI 3.2?
3. jUDDI Architecture
3.1. jUDDI Server
3.1.1. UDDI API layer uddi-ws using JAX-WS
3.1.2. Core UDDI juddi-core using JPA
3.1.3. Relational Databases
3.1.4. Servlet Containers
3.2. jUDDI GUI juddi-gui.war
4. Administration
4.1. Changing the Web Server Listen Port
4.2. Administering Users and Access Control
4.2.1. Administrative Users
4.2.2. End Users
4.3. Configuration Database Connections
4.3.1. Derby Out-of-the-Box
4.3.2. Switching to another Database
4.3.3. Switch to MySQL on Tomcat using OpenJPA
4.3.4. Switch to Postgres on Tomcat using OpenJPA
4.3.5. Switch to Postgres on JBoss using Hibernate
4.3.6. Switch to Oracle on Tomcat using Hibernate
4.3.7. Switch to HSQL on Tomcat using Hibernate
4.3.8. Switch to other db
4.3.9. Override persistence properties in the juddiv3.xml
4.4. Logging
4.5. Administering the GUI (juddi-gui.war)
4.6. Task: Signing the Digital Signature Applet jar file
4.7. Administrating your jUDDI Instance using the Administrative Console
4.8. Configure jUDDI
4.8.1. Enabling Remote Access
4.9. Monitoring the Status and Statistics
4.9.1. Statistics
4.9.2. Status
4.10. Accessing the jUDDIv3 API
4.11. Security Guidance
4.11.1. jUDDI Server
4.11.2. jUDDI Client (and developers)
4.11.3. jUDDI GUI (Web user interface)
4.12. Backups, Upgrading and Data Migration
4.12.1. Database Backups
4.12.2. Config Backup
4.13. Upgrading jUDDI
4.14. Scaling jUDDI and Federation
4.14.1. Scaling the jUDDI Services (multiple servers)
4.14.2. Limitations of jUDDI
5. jUDDI Server Configuration (juddiv3.xml)
5.1. Authentication
5.2. Startup
5.3. Email
5.4. Query Properties
5.5. RMI Proxy
5.6. Key Generation and Cryptography
5.7. Subscription
5.8. Custody Transfer
5.9. Validation
5.10. Logging
5.11. Performance
5.12. Replication
5.13. Deploying two or more jUDDI server on the same application server
5.14. jUDDI GUI Configuration
5.15. jUDDI Client uddi.xml Settings
5.16. Encryption Keys
5.17. Customizing the juddi-gui
6. Replication Services
6.1. Introduction
6.2. UDDIv3 Replication Overview
6.2.1. UDDIv3 Replication Topology
6.2.2. Conflict handling
6.3. Configuring your jUDDI Node for replication
6.3.1. Changing the Node ID
6.3.2. Setting up CLIENT-CERT authentication
6.3.3. Setting the Replication Configuration
6.3.4. Performing Custody Transfer between nodes
6.3.5. What’s Supported and What’s Not
7. UDDI Seed Data
7.1. Seed Data Files
7.2. Tokens in the Seed Data
7.3. Customer Seed Data
8. How to deploy jUDDI To?
8.1. Tomcat
8.1.1. OpenJPA and CXF
8.1.2. Hibernate and CXF
8.1.3. OpenJPA and Axis2
8.2. JBoss
8.2.1. JBossAS 6.0.0.GA
8.2.2. JBossAS 7.x/JBossEAP-6.x
8.3. Deploying to Glassfish
8.3.1. Glassfish jars
8.3.2. Configure the JUDDI datasource
8.3.3. Add juddiv3-cxf.war
8.3.4. Run jUDDI
9. Extending UDDI
9.1. Authentication modules
9.2. Subscription Notification Handlers
9.3. KeyedReference Value Set Validation Services
9.4. Cryptographic Providers
9.5. jUDDI Client Transport
10. Digital Signatures
10.1. Requirements
10.2. Using Digital Signatures using the jUDDI GUI
10.3. Frequently Asked Questions
11. Troubleshooting jUDDI
11.1. jUDDI Web Services, juddiv3.war
11.1.1. Enable debugging logging
11.2. jUDDI GUI, juddi-gui.war
11.3. jUDDI Client Java
11.3.1. Enable debugging logging
11.4. jUDDI Client .NET
11.5. Getting help
12. Contributing to jUDDI
12.1. License guidance
12.2. SVN access
12.3. Project structure
12.4. Building and testing jUDDI
12.4.1. All Java Components
12.4.2. .NET
12.5. Other ways to Contribute to jUDDI
12.5.1. Bug Reports
12.5.2. Internationalization
12.5.3. Contributing Source code
12.5.4. Releases
12.6. What the?

List of Figures

1.1. Invocation Pattern using the UDDI Registry
2.1. jUDDI welcome page
2.2. jUDDI admin
2.3. Happy jUDDI.
2.4. Form login
2.5. Add Publisher
2.6. jUDDI Services
2.7. Getting an authToken using SoapUI
2.8. Create Key Generator
2.9. Create Business
3.1. jUDDI Architecture
3.2. jUDDI Client and Console Architecture
3.3. jUDDI Console Architecture
4.1. jUDDI Server Configuration Page.
4.2. jUDDI Server Statistics.
4.3. jUDDI MBeans.
4.4. jUDDI Server Status.
4.5. jUDDI API.

List of Tables

1.1. Supported UDDI Interfaces
1.2. jUDDI Features
1.3. Supported Sort Orders
1.4. Supported Find Qualifiers
4.1. Hibernate properties that can be referenced in the juddiv3.xml file
5.1. Authentication properties that can be referenced in the juddiv3.xml file
5.2. Startup properties that can be referenced in the juddiv3.xml file
5.3. Query properties that can be referenced in the juddiv3.xml file
5.4. UDDI Key generation properties that can be referenced in the juddiv3.xml file.
5.5. Subscription properties that can be referenced in the juddiv3.xml file.
5.6. Transfer properties that can be referenced in the juddiv3.xml file.
5.7. These settings are for validating the data that users store in jUDDI. They can be referenced in the juddiv3.xml file.
5.8. jUDDI GUI Configuration

The jUDDI project maintains a UDDIv3 registry that can be deployed to most modern JEE application servers. The jUDDI project is part of the Apache Software Foundation and encourages participation. It is easy to participate and if you discover a simple typo or would like to contribute to this guide in general please read the README page (add link).

The UDDI Registry implements the UDDI specification . UDDI is a Web-based distributed directory that enables businesses to list themselves on the Internet (or Intranet) and discover each other, similar to a traditional phone book’s yellow and white pages. The UDDI registry is both a white pages business directory and a technical specifications library. The Registry is designed to store information about Businesses and Services and it holds references to detailed documentation.

In step 1 of Figure 1.1, “Invocation Pattern using the UDDI Registry” it is shown how a business publishes services to the UDDI registry. In step 2, a client looks up the service in the registry and receives service binding information. Finally in step 3, the client then uses the binding information to invoke the service. The UDDI APIs are SOAP based for interoperability reasons. In this example we’ve three APIs specified in the UDDI v3 specification, Security, Publication and Inquiry. The UDDI v3 specification defines 9 APIs:

  1. UDDI_Security_PortType, defines the API to obtain a security token. With a valid security token a publisher can publish to the registry. A security token can be used for the entire session.
  2. UDDI_Publication_PortType, defines the API to publish business and service information to the UDDI registry.
  3. UDDI_Inquiry_PortType, defines the API to query the UDDI registry. Typically this API does not require a security token.
  4. UDDI_CustodyTransfer_PortType, this API can be used to transfer the custody of a business from one UDDI node to another.
  5. UDDI_Subscription_PortType, defines the API to register for updates on a particular business of service.
  6. UDDI_SubscriptionListener_PortType, defines the API a client must implement to receive subscription notifications from a UDDI node.
  7. UDDI_Replication_PortType, defines the API to replicate registry data between UDDI nodes.
  8. UDDI_ValueSetValidation_PortType, by nodes to allow external providers of value set validation. Web services to assess whether keyedReferences or keyedReferenceGroups are valid.
  9. UDDI_ValueSetCaching_PortType, UDDI nodes may perform validation of publisher references themselves using the cached values obtained from such a Web service.

Apache jUDDI is server and client-side implementation of the UDDI v3 specification. The server side is the UDDI Registry, the client side are the juddi-client libraries. There is a Java as well as a C# version of the client libraries. The jUDDI GUI uses the client libraries to connect to a UDDI Registry. For more details please see the Chapter 2, Getting Started.

The following is a list of all supported UDDI interfaces provided by this release of jUDDI

The following is a list of other features of interest that was either defined in the UDDI specifications or in technical notes.

UDDI defines a number of sorting mechanisms.

UDDI also defines a number of Find Qualifiers, which modify the default search behavior of the Inquiry Find* APIs.

The jUDDI project is an open source implementation of the UDDI specification. The registry implementation is a WebArchive (war) juddiv3.war which is deployable to any JEE container. The application exposes a WebService API which can be accessed using any generic SOAP client, the juddi-gui or, if you are looking to integrate the UDDI api in your application, the Java or .NET version of the juddi-client.

At the jUDDI download page http://juddi.apache.org/releases.html, you have the chioce of two distributions; the juddi-client distro or the juddi-distro, where the latter includes both client and server. Each distribution contains signed binaries, source, examples and documentation. It you are not sure which distribution to download, then take the juddi-distro since it contains everything which is by far the easiest way to get going.

Navigate to http://localhost:8080/juddi-gui/ to get to the jUDDI-GUI. Please use the Form Login and use the credentials of the publisher you created above. You can browse around, but really the first thing that needs to be done is to create a Key Generator or Partition at http://localhost:8080/juddi-gui/tmodelPartitions.jsp. A Key Generator is needed to save human readable, universally unique UDDIv3 keys. Please read more about UDDI v3 formatted keys, but the short story is that UDDI v3 keys are formatted like: uddi:<domain>:name. For example, if you wanted a tModel defined as "uddi:www.mycompany.com:serviceauthenticationmethod", you would first have to create a tModel key generator with value "uddi:www.mycompany.com:keygenerator".

Next create your business using the key generator format you just registered. For example in Figure 2.9, “Create Business” we use a businessKey of uddi:www.mycompany.com:mybusiness.

See the Client and GUI Guide [stam-oree] for more details on how to use the GUI.

The jUDDI blog at http://apachejuddi.blogspot.com/ has examples as well as screencasts. This can be a useful resource to learn about some new feature or to simply get started.

The jUDDI Architecture leverages well known frameworks to minimize the codebase we need to maintain. The API layer uses JAX-WS, while the persistence layer uses JPA. The entire server is packages as a war archive that can be deployed to different servlet containers with minimal configuration changes. The JPA layer uses JDBC to communicate to a relational database. Figure 3.1, “jUDDI Architecture” shows the different components, where the implementation providers marked with a blue dot are the implementations we use by default.

As of version 3.2, jUDDI Authentication is handled from two perspectives, administrator and end user access.

Administrative users have special access to juddi-gui’s remote configuration page at http://localhost:8080/juddi-gui/settings.jsp and to the Administrative Console at http://localhost:8080/juddiv3/admin. Access to both of these is configured at the container level (i.e. Jboss, Tomcat, etc). By default, users that need to access these pages need to have the "uddiadmin" role (which is defined in the WEB-INF/web.xml of both web application archives). When you are running on tomcat this configuration can be found in the <tomcat>/conf/tomcat-users.conf file.

End users typically will either access jUDDI’s services directly at http://localhost:8080/juddiv3/ or via the user interfaces http://localhost:8080/juddi-gui. In both cases, authentication is handled via jUDDI’s Authentication providers which is configured in juddiv3.war/WEB-INF/classes/juddiv3.xml.

In order to enforce proper write access to jUDDI, each request to jUDDI needs a valid authToken. Note that read access is not restricted (by default, but can be enabled) and therefore queries into the registries are not restricted.

To obtain a valid authToken a getAuthToken() request must be made, where a GetAuthToken object is passed. On the GetAuthToken object a userid and credential (password) needs to be set.

org.uddi.api_v3.GetAuthToken ga = new org.uddi.api_v3.GetAuthToken();
org.uddi.api_v3.AuthToken token = securityService.getAuthToken(ga);

The property juddi/auth/* in the juddiv3.xml configuration file can be used to configure how jUDDI is going to check the credentials passed in on the GetAuthToken request. By default jUDDI uses the JUDDIAuthenticator implementation. You can provide your own authentication implementation or use any of the ones mention below. The implementation needs to implement the org.apache.juddi.auth.Authenticator interface, and juddi/auth/authenticator/class property should refer to the implementation class.

There are two phases involved in Authentication. The authenticate phase and the identify phase. Both of these phases are represented by a method in the Authenticator interface.

The authenticate phase occurs during the GetAuthToken request as described above. The goal of this phase is to turn a user id and credentials into a valid publisher id. The publisher id (referred to as the "authorized name" in UDDI terminology) is the value that assigns ownership within UDDI. Whenever a new entity is created, it must be tagged with ownership by the authorized name of the publisher. The value of the publisher id can be completely transparent to jUDDI - the only requirement is that one exists to assign to new entities. Thus, the authenticate phase must return a non-null publisher id. Upon completion of the GetAuthToken request, an authentication token is issued to the caller.

In subsequent calls to the UDDI API that require authentication, the token issued from the GetAuthToken request must be provided. This leads to the next phase of jUDDI authentication - the identify phase.

The identify phase is responsible for turning the authentication token (or the publisher id associated with that authentication token) into a valid UddiEntityPublisher object. The UddiEntityPublisher object contains all the properties necessary to handle ownership of UDDI entities. Thus, the token (or publisher id) is used to "identify" the publisher.

The two phases provide compliance with the UDDI authentication structure and grant flexibility for users that wish to provide their own authentication mechanism. Handling of credentials and publisher properties can be done entirely outside of jUDDI. However, jUDDI provides the Publisher entity, which is a sub-class of UddiEntityPublisher, to persist publisher properties within jUDDI. This is used in the default authentication and is the subject of the next section.

Is it possible to hook up to third party credential stores. If for example jUDDI is deployed to the JBoss Application server it is possible to hook up to it’s authentication machinery. The JBossAuthenticator class is provided in the docs/examples/auth directory. This class enables jUDDI deployments on JBoss use a server security domain to authenticate users.

To use this class you must add the following properties to the juddiv3.xml file:


The juddi/auth/authenticator/class property plugs the JbossAuthenticator class into the jUDDI the Authenticator framework. The juddi/sercuityDomain, configures the JBossAuthenticator class where it can lookup the application server’s security domain, which it will use to perform the authentication. Note that JBoss creates one security domain for each application policy element on the $JBOSS_HOME/server/default/conf/login-config.xml file, which gets bound to the server JNDI tree with name java:/jaas/<application-policy-name></application-policy-name>. If a lookup refers to a non existent application policy it defaults to a policy named other.

By default jUDDI uses an embedded Derby database. This allows us to build a downloadable distribution that works out-of-the-box, without having to do any database setup work. We recommend switching to an enterprise-level database before going to production. JUDDI uses the Java Persistence API (JPA) in the back end and we’ve tested with both OpenJPA and Hibernate. To configure which JPA provider you want to use, you will need to edit the configuration in the juddiv3.war/WEB-INF/classes/META-INF/persistence.xml. The content of this file is pretty standard between JPA implementations, however there can be slight differences. To make it easy we created different versions for different JPA implementations and target platforms. All JPA implementation have an enhancement phase, where the persistence model classes are enhanced. Hibernate does this at runtime, OpenJPA prefers doing this at compile time. This is the reason we ship two versions of juddi-core, where the juddi-core-openjpa.jar contains classes (byte-code) enhanced by OpenJPA. This is the reason this jar is larger then the juddi-core.jar.

For Hibernate, for testing the content of this file looks like

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
    <persistence-unit name="juddiDatabase" transaction-type="RESOURCE_LOCAL">
        <!-- entity classes -->

            <property name="hibernate.archive.autodetection" value="class"/>
            <property name="hibernate.hbm2ddl.auto" value="update"/>
            <property name="hibernate.show_sql" value="false"/>
            <property name="hibernate.dialect" value="org.hibernate.dialect.DerbyDialect"/>

For OpenJPA the persistence.xml looks like

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
  <persistence-unit name="juddiDatabase" transaction-type="RESOURCE_LOCAL">
    <!-- entity classes -->
      <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(SchemaAction='add')"/>
      <property name="openjpa.Log" value="DefaultLevel=WARN, Tool=INFO"/>
      <property name="openjpa.jdbc.UpdateManager" value="operation-order"/>
      <property name="openjpa.jdbc.DBDictionary" value="derby"/>
      <!-- dialects: derby, postgres, mysql, oracle, sybase, sqlserver
           for a complete list check the OpenJPA documentation -->
      <property name="openjpa.RuntimeUnenhancedClasses" value="warn"/>
      <property name="openjpa.Compatibility" value="CheckDatabaseForCascadePersistToDetachedEntity=true"/>

In this case we reference a jta-data-source called java:comp/env/jdbc/JuddiDS. Datasource deployment is Application Server specific. If you are using Tomcat, then the datasource is defined in juddi/META-INF/context.xml which by default looks like

<?xml version="1.0" encoding="UTF-8"?>
    <Resource name="jdbc/JuddiDS" auth="Container"
        type="javax.sql.DataSource" username="" password=""

By default the juddiv3.war is configured to be used on Tomcat using OpenJPA. However the download bundle lets you specify different target platforms resulting in a different setup. In all cases it will point to the embedded Derby database.

This was written from a JBoss - jUDDI perspective. Non-JBoss-users may have to tweak this a little bit, but for the most part, the files and information needed is here. Logged in as postgres user, access psql:

postgres= CREATE USER juddi with PASSWORD 'password';
postgres= CREATE DATABASE juddi;
postgres= GRANT ALL PRIVILEGES ON DATABASE juddi to juddi;

Note, for this example, my database is called juddi, as is the user who has full privileges to the database. The user juddi has a password set to password. Next edit the juddi-ds.xml datasource file with the settings for the postgres connection info:

        <!-- sql to call when connection is created.  Can be anything,
        select 1 is valid for PostgreSQL
        <new-connection-sql>select 1</new-connection-sql>
        <!-- sql to call on an existing pooled connection when it is obtained
        from pool.  Can be anything, select 1 is valid for PostgreSQL
        <check-valid-connection-sql>select 1</check-valid-connection-sql>
        <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml -->
            <type-mapping>PostgreSQL 8.0</type-mapping>

In persistence.xml, reference the correct JNDI name of the datasource and remove the derby Dialect and add in the postgresql Dialect, for Hibernate on JBoss use:

<property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect"/>

Be sure to have postgresql-8.3-604.jdbc4.jar in the lib folder.

This guide contains general security guidelines to ensure that your jUDDI server and jUDDI Client based application are relatively safe and to prevent authorized users.

This section is broken down into guidance for the jUDDI server and for the jUDDI Client

  • Always use SSL or TLS for connections to and from the jUDDI server, especially connections where authentication is used. Use encrypted connections to the database server when possible. client configs (uddi.xml), database (juddiv3/WEB-INF/classes/META-INF/persistence.xml)
  • If the juddi-gui web app is not on the same server as the juddiv3 web services web app, use SSL or TLS. (juddi-gui/WEB-INF/classes/META-INF/uddi.xml)
  • Use UDDI Digital Signatures where appropriate. Enable all validation options. Java/.NET Clients + juddi-gui, uddi.xml uddi/client/signatures, checkTimestamps,checkTrust,checkRevocationCRL
  • Require authentication for Inquiry API. (config/juddi/auth/Inquiry=true)
  • Use a LDAP user store and set passwords to expire regularly. Enforce the usage of strong passwords of sufficient length and SSL for LDAP connections. (config/juddi/auth/token/authenticator)
  • Encrypt all stored credentials (database, key stores, email, etc) with the highest possible encryption available. (config/juddi/cryptor=org.apache.juddi.v3.client.cryptor.AES256Cryptor or AES128)
  • Configure Auth Tokens to expire with relatively short intervals. This should meet all automatic logout requirements and help reduce the risk that an intercepted auth token can’t be reused by a 3rd party. (config/juddi/auth/token/Expiration) and (config/juddi/auth/token/Timeout)
  • Configure Auth Tokens to require Same IP Enforcement. This is a mitigation factor for when a token is intercepted and attempted to be reused from another source. (config/juddi/auth/token/enforceSameIPRule=true)
  • Configure Custody Transfer Tokens to expire with relatively short intervals. (config/juddi/transfer/expiration/days)
  • Disable sending authentication tokens to subscription notifications (config/juddi/notification/sendAuthTokenWithResultList=false)
  • If you’re using the replication services, configure your application server to use mutual certification authentication for that deployment (per the specification’s recommendation).
  • Enable automatic logouts (WEB-ING/classes/META-INF/uddi.xml)
  • All cached credentials are encrypted in the session tokens using an AES key that is generated at boot up time of the juddi-gui instance.
  • Use SSL or TLS when connecting using your web browser to juddi-gui.
  • The juddi-gui uses cookies to store user preferences, such as language and the current node.
  • The juddi-gui makes heavy use of JavaScript using Jquery and JqueryUI. Without a JavaScript enabled browser that supports AJAX, the juddi-gui will not be functional. This usually implies Firefox 1.6 or higher, IE 6, Chrome/Chromium (nearly all versions), Opera v8 or higher, and Safari v2 or higher.
  • The juddi-gui uses a Java applet that is used for Digital Signature support. This runs within your web browser. The Java plugin for your web browser must be enabled in order to use this functionality. In addition, the applet itself must be digitally signed (usually performed by the administrator, see article on this).
  • The juddi-gui has built in validation for digital signatures. This requires a trusted key store. Ensure that the passwords are encrypted using the highest available crypto class and that the validation settings are enabled.
  • The juddi-gui has a settings pages for altering the uddi.xml configuration file. By default, this is only accessible from the same machine running juddi-gui (i.e. localhost). This behavior can be changed by either using the setting page from localhost or by manually editing the uddi.xml page. Unless required, the recommended setting is to prevent remote configuration changes. If the settings page isn’t required, it can be removed.
  • The juddi-gui has a settings page that is password protected to prevent unauthorized changes. Use the strongest available mechanism to protect credentials. The default configuration is for HTTP BASIC. It is recommended to use this with SSL/TLS and/or switch to DIGEST based authentication. If the settings page isn’t required, it can be removed.

The capabilities and components provided by jUDDI are designed to scale. The following will describe the options and known limitations of jUDDI.

jUDDI will look for a juddiv3.xml file on the root of the classpath. In the juddiv3.war you can find it in juddiv3.war/WEB_INF/classes/juddiv3.xml.

Since 3.2 the jUDDI server now uses an XML file for configuration. Previous versions uses a properties file.


When referring to configuration properties, we are really referencing the XPath to specified setting.

Table 5.2. Startup properties that can be referenced in the juddiv3.xml file

Property NameDescriptionRequiredDefault Value or [Example Value]


Token that can be accessed in accessPointURLs and resolved at runtime. Currently this is only used during the Installation process (seeding root data)




The username for the jUDDI root publisher. This is usually just set to "root".




Forces seeding of the jUDDI data. This will re-apply all files with the exception of the root data files. Note that this can lead to losing data that was added to the entities that are re-seeded, since data is not merged.




This token is referenced in the install data. Note that you can use any tokens, and that their values can be set here or as system parameters..




This token is referenced in the install data. Note that you can use any tokens, and that their values can be set here or as system parameters..




The Node ID uniquely identifies this server. Use caution when changing the Node ID after jUDDI has been started, you may not be able to edit any existing entities! ..




This property allows you to cancel loading of the jUDDI install data.




The default local to use. This currently is not used.




The UDDI Operator Contact Email Address. This currently is not used.




The persistence name for the jUDDI database that is specified in the persistence.xml file.




The time in milliseconds in which juddiv3.xmlis polled for changes.




Take caution in changing the jUDDI Node ID. (Updated at 3.3) jUDDI can now change Node IDs via the Admin console. However care must be taken to prevent changes to data while the rename is in progress. It is recommended to use the Admin console to change the Node ID. It will automatically update the database and the juddiv3.xml configuration file.

As of 3.1.5, jUDDI supports Email delivery options for Subscription API functions. Email properties can be referenced in the juddiv3.xml file.  Starting with 3.2.1, jUDDI can now send a test email via the juddiv3.war/admin console.

Property NameDescriptionRequiredDefault Value or [Example Value]


The Operator’s Email address




The hostname of the SMTP server




The portname of the SMTP server




If set, specifies the name of a class that implements the javax.net.SocketFactory interface. This class will be used to create SMTP sockets.




If set to true, failure to create a socket using the specified socket factory class will cause the socket to be created using the java.net.Socket class. Defaults to true.




f true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. Note that an appropriate trust store must configured so that the client will trust the server’s certificate. Defaults to false.




Specifies the port to connect to when using the specified socket factory. If not set, the default port will be used.




If true, attempt to authenticate the user using the AUTH command. Defaults to false.




Username used to authenticate to the SMTP server

Y, if juddi/mail/smtp/auth is true



Username used to authenticate to the SMTP server

Y, if juddi/mail/smtp/auth is true



If the password is encrypted, the setting juddi/cryptor is the Cryptographic provider used to decrypt at runtime.

Y, if juddi/mail/smtp/auth is true


Table 5.3. Query properties that can be referenced in the juddiv3.xml file

Property NameDescriptionRequiredDefault Value or [Example Value]


The maximum number of UDDI Businesses that can be registered per publisher. A value of -1 indicates any number of businesses is allowed (These values can be overridden at the individual publisher level)




The maximum number of UDDI BusinessServices allowed per Business. A value of -1 indicates any number of artifacts is valid (These values can be # overridden at the individual publisher level).




The maximum number of UDDI TemplateBindings allowed per BusinessService. A value of -1 indicates any number of artifacts is valid (These values can be overridden at the individual publisher level).




The maximum number of TModels allowed per publisher. A value of -1 indicates any number of artifacts is valid (These values can be overridden at the individual publisher level).




The maximum number of "IN" clause parameters. Some RDMBS limit the number of parameters allowed in a SQL "IN" clause.




The maximum name size and maximum number of name elements allows in several of the FindXxxx and SaveXxxx UDDI functions




The maximum name size of name elements




The maximum number of rows returned in a find* operation. Each call can set this independently, but this property defines a global maximum. This is related to the maxInClause setting (the same?).



Table 5.7. These settings are for validating the data that users store in jUDDI. They can be referenced in the juddiv3.xml file.

Property NameDescriptionRequiredDefault Value or [Example Value]


As of 3.1.5 This setting will force referential integrity for all tModels (except keyGenerators), category bags, bindingTemplate/AccessPoint/hostingRedirector (referencing another host), tModelInstanceParms and anything else that references a KeyName default value is true. Set to false for backwards compatibility or for a more lax registry.




Enables or Disables the validation of signatures when a publisher attempts to save an entity




Path to the trust store. Can be overridden via system properties. If not specified, the Windows trust store will be used, else the default JRE trust store will be used.




The type of store to use




The clear text or encrypted password to the trust store








A cryptographic provider, representing the one that was used to encrypt



If true, certificates are checked against the time validity




If true, the certificates trust chain is validated against the trust store




The UDDIv3 replication API defines a number of web service methods that are used to manage and replicate UDDI data. Each node is responsible for maintaining a record of all changes made both locally and at all remote nodes. Everytime a Business, Service, Binding, tModel, or Publisher Assertion changes, all nodes are notified of the change. Once receiving the notification of the change, all nodes are then responsible to obtain the change set, apply it locally, and then retransmit (if needed and based on topology). The topology is configured via the Replication Configuration. With jUDDI, this is configured using the adminstration console.

There’s one important note to remember. Each piece of data in UDDI is owned by a given node.


  1. Each node must have a unique ID associated with it.
  2. Each node must have the UDDI v3 Replication service (juddiv3replication.war) deployed and configured for CLIENT-CERT authentication using SSL/TLS.
  3. Each node must have a configured JKS key store and trust store.

Since a registry can be corrupted via the replication endpoint, it is important to provide adequate security. The UDDI spec recommends using mutual certificate authentication. This is somtimes returned to as "CLIENT-CERT", certificate based authentication, or two-way SSL. All of these terms really refer to the same thing. jUDDI comes prebundled with Apache Tomcat that is configured for mutal certificate authentication out of the box (with self signed certificates). To setup CLIENT-CERT authentication, please see the documentation for your web application server.

For each certificate that is used by a jUDDI node to authenticate to another, you’ll have to map the Subject DN of the certificate to a user with the role "replication". In our example, we’ll use tomcat’s tomcat-users.xml file.

<user username="CN=localhost, OU=jUDDI Test, O=Apache Software Foundation, L=Anytown, ST=MD, C=US" password="null" roles="replication"/>

In this example, we’ve added our test certificate’s subject DN to the role of "replication".


If you run into issues getting things working, try adding the following to the startup parameters for tomcat: -Djavax.net.debug=all


Besides mapping the certificates to the replication role, either the certificate itself or the issuer of the certificate must be in the trust store used by the application server.

Since dealing with certificates can be confusing, consider the following configuration.

  • Node 1 sends updates to Node 2
  • Node 2 sends updates to Node 1

Then the certificates must be setup as follows (assuming that each node’s SSL cert is used for authentication to the other node(s))

  • Node 1’s public key must be trusted by Node 2 (in Node 2 app server’s trust store)
  • Node 2’s public key must be trusted by Node 1 (in Node 1 app server’s trust store)
  • Node 1 must have Node 2’s certificate’s Subject DN mapped to the replication role
  • Node 2 must have Node 1’s certificate’s Subject DN mapped to the replication role
  • Node 1’s public and private keys must be in a keystore on Node 1 (and the Java -D properties set)
  • Node 2’s public and private keys must be in a keystore on Node 2 (and the Java -D properties set)

To set the replication configuration, you’ll need to go to http://localhost:8080/juddiv3/admin then click on "Admin" in the top navigation bar and login. Once logged in, select "set_ReplicationNodes" from the drop down menu. The text entry field is actually resizable, so you’ll probably want to make it bigger. This text box should be pre-populated with an example replication configuration. Edit the replication as needed, then click the "Go!" button to save it.

Note: when saving the configuration, several of the fields (time stamp, serial number) will be overwritten by the server. This is normal.

Additional notes: jUDDI doesn’t currently support maximumTimeToSyncRegistry, maximumTimeToGetChanges, and controlledMessage. Due to the way the specification was written, these fields are mandatory (they must be in the Replication Configuration XML), but jUDDI wont’t respect them.

When using jUDDI’s Admin console to set the replication config, here’s a few things to keep in mind (using xpath notation).

  • replicationConfiguration/operator() - All nodes in the replication graph must be listed in the Operator section, including all directed graph nodes
  • replicationConfiguration/registryContact - Must have at least one contact. If one is specified for the node’s root business, then jUDDI will include that with the default config.
  • replicationConfiguration/communicationGraph - Must be specified with all nodes listed as identified by the NodeID in replicationConfiguration/operator/operatorNodeID.
  • replicationConfiguration/communicationGraph/controlledMessage must be specified. jUDDI uses a * to represent all messages.
  • replicationConfiguration/maximumTimeToSyncRegistry isn’t used and jUDDI will always set it to 1
  • replicationConfiguration/maximumTimeToGetChanges - isn’t used and jUDDI will always set it to 1
  • replicationConfiguration/serialNumber - jUDDI will always set this to the time stamp when the configuration was last changed (time since epoch)
  • replicationConfiguration/timeOfConfigurationUpdate - jUDDI will always set this to the time stamp when the configuraiton was last changed in a human readable form. The UDDI specification doesn’t state what format it should be in, so we used ISO 8601 as the format.

Everytime the configuration changes, an audit log is required in jUDDI log file.

Here’s an example default configuration

<?xml version="1.0" encoding="UTF-8"?><replicationConfiguration xmlns="urn:uddi-org:repl_v3" xmlns:ns2="urn:uddi-org:api_v3" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#">

Here’s an example non-directed replicaton graph. In this example, all changes perform on all nodes get set to all the other nodes.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<replicationConfiguration xmlns="urn:uddi-org:repl_v3" xmlns:ns2="urn:uddi-org:api_v3" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#">
        <ns2:contact useType="admin">
            <ns2:personName xml:lang="en">bob</ns2:personName>
        <ns2:contact useType="admin">
            <ns2:personName xml:lang="en">mary</ns2:personName>

In this example, we have a directed graph where Node 1 sends to Node2, Node 2 to Node 3, and Node 3 to Node 1. Note the addition of the replicationConfiguration/communicationGraph/edge() that defines this interaction pattern. Again all nodes defined in edges must also be defined both in the communicationGraph and as operator() XML elements.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<replicationConfiguration xmlns="urn:uddi-org:repl_v3" xmlns:ns2="urn:uddi-org:api_v3" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#">
        <ns2:contact useType="admin">
            <ns2:personName xml:lang="en">bob</ns2:personName>
        <ns2:contact useType="admin">
            <ns2:personName xml:lang="en">mary</ns2:personName>
        <ns2:contact useType="admin">
            <ns2:personName xml:lang="en">mary</ns2:personName>

One last point of interest, Edge’s can have a list of alternate message receivers and it is supported by jUDDI.

This information is relevant for both understanding how jUDDI’s default data is set when jUDDI first runs (i.e. to a new database). It’s also useful for scripting or automating the deployment of a jUDDI server within your organization which will enable you to prepopulate the data.

As of UDDI v3, each registry need to have a "root" publisher. The root publisher is the owner of the UDDI services (inquiry, publication, etc). There can only be one root publisher per node. JUDDI ships some default seed data for the root account. The default data can be found in the juddi-core-3.x.jar, under juddi_install_data/. By default jUDDI installs two Publishers: "root" and "uddi". Root owns the root partition, and uddi owns all the other seed data such as pre-defined tModels.

For each publisher there are four seed data files that will be read the first time you start jUDDI:


For example the content of the root_Publisher.xml looks like

<publisher xmlns="urn:juddi-apache-org:api_v3" authorizedName="root">
    <publisherName>root publisher</publishername>

Each publisher should have its own key generator schema so that custom generated keys cannot end up being identical to keys generated by other publishers. It is therefor that the each publisher need to define their own KenGenerator tModel. The tModel Key Generator is defined in the file root_tModelKeyGen.xml and the content of this file is

<tModel tModelKey="uddi:juddi.apache.org:keygenerator" xmlns="urn:uddi-org:api_v3">
    <description>Root domain key generator</description>
        <overviewURL useType="text">
        <keyedReference tModelKey="uddi:uddi.org:categorization:types"
            keyValue="keyGenerator" />

This means that the legal format of keys used by the root publisher need to be in the form uddi:juddi.apache.org:<text-of-chioce></text-of-chioce> The use of other types of format will lead to an illegal key error. The root publisher can only own one KeyGenerator while any other publisher can own more then one KeyGenerator. KeyGenerators should not be shared unless there is a good reason to do so. If you want to see your publisher with more then just the one KeyGenerator tModel, you can use the <publisher></publisher>_tModels.xml file. Finally, in the <publisher></publisher>_BusinessEntity.xml file can be used to setup Business and Service data. In the root_BusinessEntity.xml we specified the ASF Business, and the UDDI services; Inquiry, Publish, etc.:

<businessEntity xmlns="urn:uddi-org:api_v3" xmlns:xml="http://www.w3.org/XML/1998/namespace" businessKey="uddi:juddi.apache.org:businesses-asf">
  <!-- Change the name field to represent the name of your registry -->
  <name xml:lang="en">An Apache jUDDI Node</name>
  <!-- Change the description field to provided a brief description of your registry -->
  <description xml:lang="en">This is a UDDI v3 registry node as implemented by Apache jUDDI.</description>
    <!-- This discovery URL should point to the home installation URL of jUDDI -->
    <discoveryURL useType="home">${juddi.server.baseurl}/juddiv3</discoveryURL>
    <keyedReference tModelKey="uddi:uddi.org:categorization:nodes" keyValue="node" />
    <!-- As mentioned above, you may want to provide user-defined keys for these (and the services/bindingTemplates below.  Services that you
    don't intend to support should be removed entirely -->
    <businessService serviceKey="uddi:juddi.apache.org:services-inquiry" businessKey="uddi:juddi.apache.org:businesses-asf">
      <name xml:lang="en">UDDI Inquiry Service</name>
      <description xml:lang="en">Web Service supporting UDDI Inquiry API</description>
        <bindingTemplate bindingKey="uddi:juddi.apache.org:servicebindings-inquiry-ws" serviceKey="uddi:juddi.apache.org:services-inquiry">
          <description>UDDI Inquiry API V3</description>
          <!-- This should be changed to the WSDL URL of the inquiry API.  An access point inside a bindingTemplate will be found for every service
          in this file.  They all must point to their API's WSDL URL -->
          <accessPoint useType="wsdlDeployment">${juddi.server.baseurl}/services/inquiry?wsdl</accessPoint>
            <tModelInstanceInfo tModelKey="uddi:uddi.org:v3_inquiry">
                  <?xml version="1.0" encoding="utf-8" ?>
                  <UDDIinstanceParmsContainer xmlns="urn:uddi-org:policy_v3_instanceParms">
            <keyedReference keyName="uddi-org:types:wsdl" keyValue="wsdlDeployment" tModelKey="uddi:uddi.org:categorization:types"/>
<!-- snip -->

Note that the seeding process only kicks off if no publishers exist in the database. So this will only work with a clean database, unless you set juddi/seed/always to true. Then it will re-apply all files with the exception of the root data files. Note that this can lead to losing data that was added to entities that are re-seeded, since data is not merged.

The jUDDI distribution ships preconfigured on Tomcat - it runs out of the box. All you have to do in go into the juddi-distro-<version>/juddi-tomcat-<version>/bin directory and start up Tomcat. All of this just as described in Chapter 2, Getting Started.

By default the juddiv3.war is configured to use OpenJPA and CXF. If you want to change your JPA or WS provider, or you’d like to run on a different container then this chapter may come in handy, as there a number of scripted profiles to change the configuration and dependencies in the juddiv3.war. To run these maven based scripts you need to go into juddi-distro-<version>/juddiv3-war directory.

This section describes how to deploy juddi to JBoss 6.0.0.GA.

First, download jboss-6.0.0.GA - the zip or tar.gz bundle may be found at http://www.jboss.org/jbossas/downloads/. Download the bundle and uncompress it.

Target platform JBoss-6.x and HSQL using Hibernate and JBossWS-cxf. The juddiv3.war relies on Hibernate and JBossWS-cxf in the appserver.

mvn clean package -P hibernate-jbossws-cxf


Issue 1
15:14:37,275 SEVERE [RegistryServlet] jUDDI registry could not be started. org.apache.commons.configuration.ConfigurationException: java.util.zip.ZipException: error in opening zip file: org.apache.commons.configuration.ConfigurationException: org.apache.commons.configuration.ConfigurationException: java.util.zip.ZipException: error in opening zip file

Workaround: deploy juddiv3.war as a directory (not a zip file).

Issue 2

JBoss-5.x Note that configuration 3 and 4 will also run on JBoss-5.x, but you may run into the following

ERROR [org.jboss.ws.metadata.wsdl.xmlschema.JBossXSErrorHandler] (main) [domain:http://www.w3.org/TR/xml-schema-1]::[key=src-resolve]::Message=src-resolve: Cannot resolve the name ns1:Signature to a element declaration component.

Workaround: Unzip the deployers/jbossws.deployer/jbossws-native-core.jar and add the xmldsig-core-schema.xsd in the schema directory,

10293 Fri May 27 14:40:40 EDT 2011 schema/xmldsig-core-schema.xsd

Edit the file META-INF/jbossws-entities.properties by adding a line at the bottom saying:


Copy juddiv3.war to server/default/deploy and unpack it.

Insert jboss-web.xml into the juddiv3.war/WEB-INF directory , should look like the following :

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE jboss-web PUBLIC
	"-//JBoss//DTD Web Application 2.3V2//EN"




The first step for configuring a datasource is to copy your JDBC driver into the classpath. Copy your JDBC driver into ${jboss.home.dir}/server/${configuration}/lib, where configuration is the profile you wish to start with (default, all, etc.). Example :

cp mysql-connector-java-5.0.8-bin.jar /opt/jboss-5.1.0.GA/server/default/lib

Next, configure a JBoss datasource file for your db. Listed below is an example datasource for MySQL :

<?xml version="1.0" encoding="UTF-8"?>

   <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->

Next, make a few changes to the juddiv3.war/classes/META-INF/persistence.xml. Change the "hibernate.dialect" property to match the database you have chosen for persistence. For MySQL, change the value of hibernate.dialect to "org.hibernate.dialect.MySQLDialect". A full list of dialects available can be found in the hibernate documentation (https://www.hibernate.org/hib_docs/v3/api/org/hibernate/dialect/package-summary.html). Next, change the <jta-data-source> tags so that it reads <non-jta-data-source>, and change the value from java:comp/env/jdbc/JuddiDS to java:/JuddiDS.

This section describes how to deploy juddi to Glassfish 2.1.1. These instructions will use CXF as a webservice framework.

First, download the glassfish-v2.1.1 installer JAR. Once downloaded,install using the JAR and then run the ant setup script :

java -jar glassfish-installer-v2.1.1-b31g-linux.jar
cd glassfish
ant -f setup.xml

jUDDI has extensively uses the Interface/Factory pattern to enable configuration runtime options and to provide you, the developer easy insertion points to customize the behavior of jUDDI. The remaining sections of this chapter outline the different technology insertion points.

Subscription Notification Handlers are used to asynchronously notify users that something has changed in UDDI. In order to do this, a UDDI Subscription is created that references a specific Binding Template key which represents the service that will be called whens something changes. jUDDI comes with support for Email delivery and the UDDI Subscription Listener Web Service (HTTP) delivery. In addition, jUDDI comes with an example for publishing to an Apache Qpid AMQP pub/sub server, which can be used to further disseminate the change. The following is an exert from the jUDDI Blog posting on this.

  1. Make a new Java library projects in your IDE of choice. Reference the juddi-core, and uddi-ws projects or JAR files or the Maven dependency equivalent
  2. Create a class of your own within the following package name: org.apache.juddi.subscription.notify
  3. The class name MUST follow this pattern: PROTOCOLNotifier Where PROTOCOL is the prefix of whatever URL you want users to be able to use. Here’s an example using Apache Qpid. Example URL: amqp://guest:guest@client1/development?brokerlist=tcp://localhost:5672 Class Name: AMQPNotifier. The Notification class basically takes the protocol of the Access Point’s value, splits it on the character ":" and then grabs the first token "amqp" and converts to upper case. Using this pattern you should be able to insert anything you want.
  4. Our new shinny class, AMQPNotifier, must implement the interface org.apache.juddi.subscription.notify.Notifier. From there, all you need to do is to add in the jars necessary for your transport mechanism and wire in your own code.
  5. Deployment is simple. Add your PROTOCOLNotifier jar and its dependencies to the juddiv3.war/WEB-INF/lib folder.

Note: be careful and watch for conflicting jar file versions. In general, usually moving up a version is ok, but moving down may cause the services to fail unexpectedly.

To test, create a Service with the BindingTemplate’s Access Point’s value equal to whatever you need. Next, setup a subscription and reference the BindingTemplate key that represents your call back handler’s end point. Finally, change an item that is covered by the subscription’s filter and monitor the log files. Hopefully, you won’t see an unexpected errors.

Users of UDDI can use digital signatures to ensure that no unauthorized users alter the content of UDDI. We’re sure that one of the first questions one would ask is "can’t access control rules handle this problem for us?" The answer is yes, however it does not mitigate the risk of a number of opportunities for electronic attack.

Doesn’t UDDI access control rules prevent alteration of the content?
Yes, however it does not mitigate the man in the middle attack vectors. Since UDDI is used to determine the location of the thing you want, it’s possible that falsified endpoints can be interjected in transport. The target service requires authentication, then the end user’s credentials could be compromised without their knowledge.
How can I sign a business, service, tModel or binding?
Use the juddi-gui’s digital signature applet by first located the item in the juddi-gui interface, then click on the "Sign" button. You need write access to the entity.
The digital signature applet doesn’t run. Now what?
The applet requires the Java browser plugin. Unfortunately, due to recent (2013) security vulnerabilities, many places of business have heeded Oracle’s advice and have disabled the browser plugin. There are other options, however.
What other tools can I use to sign a UDDI entity?
What is a signature?
It’s basically a cryptographic (a fancy math equation) using a set a keys (one is public and everyone can see/know it, the other only is held by the owner) that proves that the owner signed a piece of data.
How is a signature verified?
There’s a few ways, we can prove mathematically that the signature is valid (the content hasn’t been modified). From there we can also verify that the signing key is valid.
How do we know the signing key is valid?
Most certificates (key pairs) have some kind of mechanism in it to verify if the certificate has been revoked. If your certificate has it, it will be labeled with something like OCSP or CRL. Both of these are supported in both .NET and Java juddi-clients as well as via the juddi-gui.

Here are some tips to help you troubleshoot problems with jUDDI, jUDDI-GUI, jUDDI Client and more.

Problem: Can’t authentication from juddi-gui’s top right hand side login box to juddiv3.war services Solutions:

We welcome contributions to jUDDI. Visit the jUDDI web set at http://juddi.apache.org for more information.

jUDDI has a number of components, however it is mostly Java based. The following sections describe the particulars for each language.


  1. Acquire a Subversion client.
  2. Execute svn co https://svn.apache.org/viewvc/juddi/trunk/
  3. Acquire a JDK5 or higher and setup the JAVA_HOME environment variable.
  4. Acquire Apache Maven. Known working version: 3.0.4
  5. Setup an environment variable, MAVEN_OPTS=-Xmx768m -XX:MaxPermSize=512m
  6. Make sure the Maven/bin folder and the JDK/bin folders are in the current path
  7. Execute "mvn clean install"

This will build, test and package all of the Java components of jUDDI. This includes the Technical Conformance Kit (TCK), a live Tomcat server, the user interfaces, and more.

For additional build output, add -Ddebug-true for Java.

To prepare a deployable jUDDI war for an alternate deployment scenario (other than Tomcat with CXF and OpenJPA), use the following procedure:

  1. Execute "mvn clean package -P<packageName>"

Where <packageName> is one of the following

  1. openjpa-jboss7up for EAP 6 and up, GA 7 and up
  2. hibernate-jbossws-native for EAP 5, Jboss GA 6 and down with the JbossWS Native soap stack
  3. hibernate-jbossws-cxf for EAP 5, Jboss GA 6 and down with the JbossWS Native soap stack
  4. hibernate (includes CXF in the war, used for Tomcat)
  5. openjpa (includes CXF in the war, used for Tomcat)
  6. axis2 (includes Axis2 in the war)


When altering the TCK based modules, make sure you clean install in the root check out location. Due to the build order, you may end up with strange results when just executing the tests, even with clean install.


To attach the debugger to the build process try "mvn -Dmaven.surefire.debug clean install". It listens on port 5005 by default. More info on debugging maven projects is here http://maven.apache.org/surefire/maven-surefire-plugin/examples/debugging.html


registry, UDDI Registry


specification, UDDI Registry


registry, UDDI Registry
specification, UDDI Registry