Apache jUDDI Guide

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

jUDDI is written in Java and minimally requires

optionally

The versions mentioned above are minimal versions and it is recommended to use the latest version available. By default jUDDI ships and uses a Derby database. After evaluation you probably want to move to a more full featured database.

After downloading and unpacking of the juddi-distro, you can start the preconfigured tomcat server by going into the juddi-distro-<version> directory and running startup

$ cd apache-tomcat-<version>/bin
$ ./startup.sh

By popular demand we brought back the happy jUDDI!' page. Just click on Status and Statistics page. By default we run on CXF, so it is normal if says the AxisServlet is not found. There should be no other red on this page.

By default jUDDI ships with 2 publishers: root and uddi. Root is the owner of the repository, while the uddi user is the owner of all the default tmodels and categorizations. Please use the root user to log into the form login in the admin console.

You will now be able to do more then simple browsing. Navigate to the Administration and select save_publisher from the dropdown. This will allow you to add your own publisher.

Here’s the change log for version 3.2

The jUDDI GUI is also a Web Archive that is deployed along side the juddiv3 server in the same servlet container. The GUI uses the juddi-client to communicate to the UDDI API Endpoints. It can use a SOAP, RMI or an inVM transport protocol, so the GUI can be deployed in a different location then the server as long as it can connect to the UDDI SOAP API.

You may have a jUDDI v3 Server for each type of environment (Dev, QA and Prod) and you would only need one console to connect to each one of them.

If you want to change the port Tomcat listens on to something non-standard (something other than 8080), use the following guidance.

jUDDI Server (Tomcat) - This assumes you are using the jUDDI server bundled with Apache Tomcat. For other application servers, consult their documentation, however the juddiv3.xml must still be altered.

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

The jUDDI codebase uses the commons-logging-api, and log4j as the default logging implementation. The juddiv3/WEB-INF/classes/commons-logging.properties sets the logging to log4j. The default log4j configuration logs to a juddi.log file in the tomcat/logs directory. The log4j configuration lives in the juddiv3/WEB-INF/classes/log4j.properties file, which is referenced in the web.xml

<context-param>
    <param-name>log4jConfigLocation</param-name>
    <param-value>/WEB-INF/classes/log4j.properties</param-value>
</context-param>

The commons-logging and log4j jars are shipped in the juddiv3/WEB-INF/lib directory.

If you are using CXF for the webservice stack you can log the request/response xml by adding

log4j.category.org.apache.cxf=INFO

to your log4j.properties and the cxf.xml file should contains this:

<cxf:bus>
    <cxf:features>
        <cxf:logging/>
    </cxf:features>
</cxf:bus>

The jUDDI beans.xml specifies the location of this file at META-INF/cxf/cxf.xml.

There are a few things worth mentioning for administering the jUDDI Graphical User Interface. The first is user authentication, which is covered in the authentication chapter. The other the the Digital Signature Applet. This applet enables users to digitally signed UDDI entities via the GUI. There are a number of requirements in order for this to work.

jarsigner -keystore your.keystore -storepass yourpass -keypass keypass <pathto>/juddi-gui.war/applets/juddi-gui-dsig-all.jar

Note: Jarsigner comes with most JDKs and has many command line options.

Your instance of the jUDDI (juddiv3.war) can be managed via the administration console. It can be access url the following URL:

http://localhost:8080/juddiv3/admin

By default, only users with the role "uddiadmin" are allowed to access this page. In addition, it must be accessed from the same computer hosting juddiv3.war (this can be changed if needed). When accessing the URL, you should be prompted for login via username/password (this can also be changed to another mechanism).

After authenticating, you will be prompted with a very similar interface to the juddi-gui.war. From here, you can perform a number of tasks.

*Why is there another login required for the jUDDIv3 API functions?

The answer is because the admin console will be directly accesses a web service and it requires a user account with juddi admin rights. This may be the same username you use to access the admin console (juddiv3.war/admin) but unfortunately, this double login is unavoidable.

From the browser, it is possible to configure jUDDI’s web services via the web browser. All of the settings available from the chapter on configuring jUDDI can be set there.

The Statistics and Status page provides valuable information to administrators and developers looking to trouble shoot or debug problems with jUDDI.

The jUDDI API is a web service that extends the UDDI specification. It provides various functions for both configuring the jUDDI server and for performing administrative functions, such as authorizing a new username as a publisher, user rights assignment and so on. This page will let you access the functions from the web browser.

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

There are several different strategies for managing your jUDDI backups.

Sometimes, the jUDDI development team has no choice but to alter the database schema. In many cases, OpenJPA or Hibernate (both Java Persistence API provides) will automatically alter database columns when a new version is installed. In some cases, there may actually be data loss.

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

These properties are used to bring up RMI server socket. The settings allow for registering this service to JNDI.  RMI Proxy properties that can be referenced in the juddiv3.xml file and is only used by RMITransport.

The jUDDI GUI (juddi-gui.war) has one place for configuration settings, the jUDDI Client config file.

Defined in WEB-INF/classes/META-INF/uddi.xml, there are many settings to configure. All of these are clearly defined by the jUDDI Client Configuration Guide. The juddi-gui, uses things a bit differently, so here are the relevant parts to use. Note: this is xpath notation.

In addition, there a special section added just for the juddi-gui.war

By default, the juddi-gui will use a randomly generated AES encryption key to help protect user credentials stored in the session object. This key is generated using the "StartupServlet" defined in the web.xml file of juddi-gui.war/WEB-INF/web.xml and then it is stored at the path juddi-gui.war/META-INF/config.properties@key.

If the start up servlet fails to start, any authenticate operation of the juddi-gui will fail.

The juddi-gui has a mechanism that you can use to alter the appearance of every page. This is typically used for organizations that require legal notifications, banners or warnings on every page for one reason or another. To add your own html to every page, edit the file in

juddi-gui/user/banner.jsp

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

<publisher>_Publisher.xml
<publisher>_tModelKeyGen.xml
<publisher>_BusinessEntity.xml
<publisher>_tModels.xml

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>
    <isAdmin>true</isadmin>
</publisher>

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">
    <name>uddi-org:keyGenerator</name>
    <description>Root domain key generator</description>
    <overviewDoc>
        <overviewURL useType="text">
        http://uddi.org/pubs/uddi_v3.htm#keyGen
        </overviewurl>
    </overviewdoc>
    <categoryBag>
        <keyedReference tModelKey="uddi:uddi.org:categorization:types"
            keyName="uddi-org:types:keyGenerator"
            keyValue="keyGenerator" />
    </categorybag>
</tmodel>

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>
  <discoveryURLs>
    <!-- This discovery URL should point to the home installation URL of jUDDI -->
    <discoveryURL useType="home">${juddi.server.baseurl}/juddiv3</discoveryURL>
  </discoveryURLs>
  <categoryBag>
    <keyedReference tModelKey="uddi:uddi.org:categorization:nodes" keyValue="node" />
  </categoryBag>
  <businessServices>
    <!-- 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>
      <bindingTemplates>
        <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>
          <tModelInstanceDetails>
            <tModelInstanceInfo tModelKey="uddi:uddi.org:v3_inquiry">
              <instanceDetails>
                <instanceParms>
                <![CDATA[
                  <?xml version="1.0" encoding="utf-8" ?>
                  <UDDIinstanceParmsContainer xmlns="urn:uddi-org:policy_v3_instanceParms">
                    <defaultSortOrder>
                      uddi:uddi.org:sortorder:binarysort
                    </defaultSortOrder>
                  </UDDIinstanceParmsContainer>
                ]]>
                </instanceParms>
              </instanceDetails>
            </tModelInstanceInfo>
          </tModelInstanceDetails>
          <categoryBag>
            <keyedReference keyName="uddi-org:types:wsdl" keyValue="wsdlDeployment" tModelKey="uddi:uddi.org:categorization:types"/>
          </categoryBag>
        </bindingTemplate>
      </bindingTemplates>
    </businessService>
<!-- snip -->
</businessService>

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.

You may have noticed the tokens in the root_BusinessEntity.xml file (${juddi.server.baseurl}. The value of this tokens can set in the juddiv3.xml file. The value substitution takes place at runtime, so that different nodes can do the substitution with their own value if needed.

In your deployment you probably do not want to use the Seed Data shipped with the default jUDDI install. The easiest way to overwrite this data is to add it to a directory call juddi_custom_install_data in the juddiv3.war/WEB-INF/classes/ directory. That way you don’t have to modify the juddi-core-3.x.jar. Additionally if your root publisher is not called "root" you will need to set the juddi/root/publisher property in the juddiv3.xml file to something other then

juddi/root/publisher=root

The juddiv3.war ships with two example data directory. One for the Sales Affiliate, and one for the Marketing Affiliate. To use the Sales Seed Data, in the juddiv3.war/WEB-INF/classes/, rename the directory

*nix
mv RENAME4Sales_juddi_custom_install_data juddi_custom_install_data
Win*
ren RENAME4Sales_juddi_custom_install_data juddi_custom_install_data

before you start jUDDI the first time. It will then use this data to populate the database. If you want to rerun you can trash the database it created and restart tomcat. Don’t forget to set the tokens in the juddiv3.xml file.

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

Authentication modules are used when the UDDI’s AuthToken is utilized on the Security web service. It’s function is to point to some kind of user credential store to validate users. See the User Guide for details on what’s available out of the box.

All of the provided classes implement the interface .org.apache.juddi.v3.auth.Authenticator.. So, if you wanted something a bit more functional than what’s provided out of the box. you’ll need to implement your own Authenticator. To wire it in, edit the juddiv3.xml file, specifying your class name as the value to the property "juddi/auth/authenticator/class" and then add the class or jar containing your implementation to juddiv3.war/WEB-INF/classes or judiv3.war/WEB-INF/lib respectively.

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.

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.

Reserved for future discussion for jUDDI v3.3

jUDDI provides cryptographic functions via (Java) juddi-client.jar/org.apache.juddi.v3.client.cryptor and implement the Cryptor interface which provides two simple functions, encrypt and decrypt. (Note: .NET has similar functionality).

The juddi-client’s Transport class is an abstract class that you can you alter the transport mechanism used by jUDDI’s client APIs. Included is what would be used in most cases, such as JAXWS, RMI, and InVM (Embedded mode). This can be extended to use whatever you may need.

UDDI supports both the XML Digital Signature specification, which effectively means that you can use PGP Keys and X509 certificates. jUDDI provides out of the box support for X509 certificates and the Public Key Infrastructure (PKI). If you require direct PGP signing support, please open a JIRA ticket.

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

Components based on jUDDI’s Client for the .NET Framework can configure logging from their application’s config file. This is usually app.config or web.config. To configure logging, the following three settings must appear in the configuration/appSetttings section.

	<!-- DEBUG, INFO, WARN, ERROR -->
	<add key="org.apache.juddi.v3.client.log.level" value="INFO" />
    <!-- options are CONSOLE, EVENTLOG, FILE multiple values can be specified, comma delimited.
		Notes for EVENTLOG, you must run the juddi-installer as admin before running-->
    <add key="org.apache.juddi.v3.client.log.target" value="CONSOLE" />
	<!-- only used when target=FILE -->
    <add key="org.apache.juddi.v3.client.log.logger.file" value="pathToOutputFile" />

If nothing is defined, the default log level is "WARN" and the target is "CONSOLE" which is standard out.

There are many different ways to get help with your jUDDI instance. Please refer to the following URLs for more information.

jUDDI, from a developer’s perspective, is divided into a number of smaller, more manageable modules. In general, each module contains all of the necessary unit tests in order to ensure functionality.

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

There are many ways you can contribute to jUDDI. We welcome all kinds and types contributions.

Having ran into a number of strange issues when developing with jUDDI, we decided to write a few of them down.