How to publish a web service to jUDDI


Our last post talked about How to install jUDDI on Tomcat by yourself. It described an alternative installation procedure if you have already had a Tomcat instance installed in your machine and don’t want to have another Tomcat (the one that comes with the jUDDI bundle). On this post we will publish a web service‘s WSDL to that jUDDI.

What we will do is to make use of two jUDDI’s web services: Publish and Inquiry. While the Publish webservice is responsible to register the many “entities” to the jUDDI, the Inquiry is used to discover those “entities”. But which “entities” are we talking about?

Well, the UDDI standard includes the following 4 core data structures:

  • businessEntity: Represents the provider of web services. It contains information about the company itself, including contact information, industry categories, business identifiers;
  • businessService: It represents an individual web service provided by a businessEntity. Its description includes information on how to bind to the web service, what type of web service it is, and what taxonomical categories it belongs to;
  • bindingTemplate: It is the technical description of the web services represented by abusinessService. It is the representation of the actual implementation of a web service;
  • tModel: It stands for “technical model”. It is the representation of any abstract concept such as a WSDL port type .
Figure 1 - UDDI core data structures
Figure 1 - UDDI core data structures

Now that you know what are the data structures of UDDI you are able to understand the operations and the services provided by jUDDI. When you install jUDDI you will be able to access the Apache jUDDI‘s welcome screem at http://localhost:8080/juddiv3/. This screem has a link named “View service listing which takes you the the list of all web services provides by jUDDI.

Since our intention in this post is to understand how to publish a web service to jUDDI, we will call its web services through SoapUI, an GUI to manually consume and unit test SOAP and REST web services. Please refer to the SoapUI website to download  and installation instructions.

How to publish a businessEntity

After creating a project in SoapUI for the jUDDI’s Publish web service at http://localhost:8080/juddiv3/services/publish?wsdl, we’ll be able to call the “save_business” operation which is the one responsible for publishing a businessEntity. The following SOAP messages represent an example request  on how to register a Business.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:urn="urn:uddiorg:api_v3"
      xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
<soapenv:Header/>
<soapenv:Body>
<urn:save_business>
    <urn:authInfo>authtoken:c9c74230-ae21-4546-87c3-35514d6fcee7</urn:authInfo>
    <urn:businessEntity>
    <urn:name xml:lang="en">My Company</urn:name>
    <urn:description xml:lang="en">The company which is mine</urn:description>
    <urn:contacts>
        <urn:contact useType="CTO">
            <urn:personName xml:lang="en">Marcelo Carvalho Fernandes</urn:personName>
            <urn:phone useType="voice">+55 21-1111-1111</urn:phone>
            <urn:email useType="email">mcf2000@gmail.com</urn:email>
        </urn:contact>
    </urn:contacts>
    </urn:businessEntity>
</urn:save_business>
</soapenv:Body>
</soapenv:Envelope>

You will see that the standard “save_business” message request permits much more data structures than the one we used on the message above. Take your time to explore and understand the other possibilities and find out what you really need.

Every call you make to jUDDI’s web services must have an authorization token such as <urn:authInfo>authtoken:xxxx</urn:authInfo>. Let’s see how to have an authToken.

Getting an authorization token

The “get_authToken” operation from the “UDDI_Security” (http://localhost:8080/juddiv3/services/security?
wsdl) is the one that provides an authToken. The following SOAP request message is responsible to pick an authToken.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:urn="urn:uddiorg:api_v3">
<soapenv:Header/>
<soapenv:Body>
    <urn:get_authToken userID="root" cred="root"/>
</soapenv:Body>
</soapenv:Envelope>

See how to have an userID and cred to use the get_authToken operation.

Publishing a tModel

The “save_tModel” operation in the “UDDI_Publication” (http://localhost:8080/juddiv3/services/
publish?wsdl) web service is responsible for publishing a tModel. The following SOAP request message is responsible to do that.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:urn="urn:uddiorg:api_v3"
      xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
<soapenv:Header/>
<soapenv:Body>
<urn:save_tModel>
   <urn:authInfo>authtoken:c9c74230-ae21-4546-87c3-35514d6fcee7</urn:authInfo>
   <urn:tModel>
      <urn:name>Service name</urn:name>
      <urn:description xml:lang="en">A description of the service</urn:description>
      <urn:overviewDoc>
         <urn:overviewURL useType="wsdlInterface">http://127.0.0.1:8080/axis2/services/someservice?wsdl</
urn:overviewURL>
         <urn:description xml:lang="pt">Some description</urn:description>
      </urn:overviewDoc>
   <urn:categoryBag>
      <urn:keyedReference tModelKey="UUID:C1ACF26D-9672-4404-9D70-39B756E62AB4" keyName="uddiorg:
types" keyValue="wsdlSpec"/>
   </urn:categoryBag>
</urn:tModel>
</urn:save_tModel>
</soapenv:Body>
</soapenv:Envelope>

Linking a tModel to a Service

Now we are able to create a businessService and a bindingTemplate to link the tModel to the existing businessEntity.

The “save_service” operation in the “UDDI_Publication” (http://localhost:8080/juddiv3/services/
publish?wsdl) web service is responsible for doing it. The following SOAP request message does that.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:urn="urn:uddiorg:api_v3"
      xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
<soapenv:Header/>
<soapenv:Body>
<urn:save_service>
   <urn:authInfo>authtoken:c9c74230-ae21-4546-87c3-35514d6fcee7</urn:authInfo>
   <urn:businessService businessKey="uddi:juddi.apache.org:1df873b5-66ba-4be0-af86-0e97f675f02d">
   <urn:name xml:lang="en">Service name</urn:name>
   <urn:description xml:lang="pt">Service description</urn:description>
   <urn:bindingTemplates>
      <urn:bindingTemplate>
      <urn:description xml:lang="en">Binding name</urn:description>
      <urn:accessPoint useType="endPoint">http://127.0.0.1:8080/axis2/services/someservice</
urn:accessPoint>
      <urn:tModelInstanceDetails>
         <urn:tModelInstanceInfo tModelKey="uddi:juddi.apache.org:fdf6a723-cbd2-480a-a308- 15426020f95c">
         <urn:description xml:lang="en">tmodel description</urn:description>
      <urn:instanceDetails>
         <urn:overviewDoc>
            <urn:overviewURL useType="wsdlInterface">http://127.0.0.1:8080/axis2/services/someservice? wsdl</urn:overviewURL>
            <urn:description xml:lang="en">Description</urn:description>
         </urn:overviewDoc>
      </urn:instanceDetails>
</urn:tModelInstanceInfo>
</urn:tModelInstanceDetails>

That’s all. Now we’ll take a look at how search for a web service.

How to discover a web service

We have to use another jUDDI’s web service in order to query the register for an existing web service. We will resort to the “find_tModel” operantion in the “UDDI_Inquiry” jUDDI’s service at http://localhost:8080/juddiv3/services/inquiry?wsdl. The following request query the jUDDI for all services with the word “service” in its “name” attribute.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:urn="urn:uddiorg:api_v3">
<soapenv:Header/>
<soapenv:Body>
<urn:find_tModel>
   <urn:authInfo>authtoken:c9c74230-ae21-4546-87c3-35514d6fcee7</urn:authInfo>
   <urn:findQualifiers>
      <urn:findQualifier>approximateMatch</urn:findQualifier>
   </urn:findQualifiers>
   <urn:name>%service%</urn:name>
</urn:find_tModel>
</soapenv:Body>
</soapenv:Envelope>

Note that it’s possible to query jUDDI by using the SQL ANSI 92 wildcards such as the “%”. In the previous example that is possible because we used the “findQualifier” named approximateMatch.

Important notes

It’s important to know that the SOA request examples provided in this post should be considered as really just exemples. That is because there is a proper way to map a WSDL to the UDDI data structures. Please refer to the following links to find out more information about that:

Another important thing to know is that in the same way there are people comparing REST and SOAP+WSDL services, you’ll find people advocating some different approaches to deal with a web service registry. These different approach usually uses RSS feeds and Restful services. Some tools that do it are:
For more information about UDDI go to http://uddi.org/pubs/uddi_v3.htm

How to install jUDDI on Tomcat by yourself


Hi!

This week I had to install Apache jUDDI for the purpose of the “Knowledge Organization and WEB 3.0” class which is one of my Master’s degree disciplines at PPGI-UFRJ.

When I went to jUDDI‘s web site I discovered that jUDDI have a embeded Apache Tomcat within it. No problem if I hadn’t already installed Tomcat.

Since I wouldn’t like to have 2 running Tomcat installations I decided to install and deploy jUDDI in my existing Tomcat installation. After a few searches in Google I could not find someone who have already done it. That’s why I decided to write this (not so comprehensive) instructions.

Well, since I have already had a running Tomcat installation you will have to install it. It’s very easy. You can find a lot of HOW TOs around. Therefore, I consider the following prerequisites for my step-by-step installation instructions of jUDDI.

Prerequisites:

Having properly installed and configured Java and Tomcat we can now start with the other jUDDI‘s prerequisites.

Step 1 – Install MySQL and create a database for jUDDI
  1. Download and install MySQL Community Server 5.5.14. Choose the MSI installer version;
  2. Now let’s create a user and a database for jUDDI…
  3. Execute the MySQL Command Line Client (It’s in Windows’ Program menu);
  4. Execute these 3 commands: “CREATE USER ‘juddi’@’localhost’ IDENTIFIED BY ‘juddi’;“, “CREATE DATABASE juddi;” and “GRANT ALL PRIVILEGES ON juddi.* TO ‘juddi’@’localhost’;“;
Step 2 – Deploy Apache jUDDI
  1. Download jUDDI portal bundle 3.0.4 and unzip it. Although this zip have an embeded Tomcat installation we won’t use it. We’ll need jus some webapps inside it.
  2. Copy the juddiv3, pluto and juddi-portlets folders (they are located inside the webapps folder in the zip file) to Tomcat‘s webapps folder. Again, just as a reference my webapps folder is in C:\Program Files\apache-tomcat-6.0.29\webapps;
  3. Also copy the following libraries from your zip’s juddi-portal-bundle-3.0.4\lib folder to your existing C:\Program Files\apache-tomcat-6.0.29\webapps folder:
    • castor-1.1.1.jar
    • commons-discovery-0.2.jar
    • commons-logging-1.1.jar
    • pluto-container-1.1.7.jar
    • pluto-descriptor-api-1.1.7.jar
    • pluto-descriptor-impl-1.1.7.jar
    • pluto-taglib-1.1.7.jar
    • portlet-api-1.0.jar
    • log4j-1.2.13.jar
Step 3 – Configure MySQL JNDI Resources in Tomcat
  1. Download MySQL Connector/J 5.1.17 (the official JDBC driver for MySQL) and unzip it. Find the mysql-connector-java-5.1.17-bin.jar file and copy it to the lib folder of your existing Tomcat installation. My Tomcat‘s lib is in C:\Program Files\apache-tomcat-6.0.29\lib;
  2. Open the file C:\Program Files\apache-tomcat-6.0.29\webapps\juddiv3\META-INF\context.xml with any text editor and edit it in order to look like this…
      • <?xml version=”1.0″ encoding=”UTF-8″?>
      • <Context>
      • <WatchedResource>WEB-INF/web.xml</WatchedResource>
      • <Resource
      • name=”jdbc/juddiDB
      • auth=”Container” 
      • type=”javax.sql.DataSource” 
      • username=”juddi” 
      • password=”juddi” 
      • driverClassName=”com.mysql.jdbc.Driver” 
      • url=”jdbc:mysql://localhost:3306/juddi”
      • />
      • </Context>
  3. Now a very important thing. There are 3 other files that must be in synch with the context.xml. The resource name juddiDB must be present in the following files relative to C:\Program Files\apache-tomcat-6.0.29\webapps\juddiv3\WEB-INF\:
    • .\web.xml: Set the value of <res-ref-name> as jdbc/juddiDB;
    • .\classes\juddiv3.properties: Set the property juddi.persistenceunit.name with value juddiDB;
    • .\classes\META-INF\persistence.xml: Set the persistence-unit‘ name to juddiDB, set <non-jta-data-source> value to java:comp/env/jdbc/juddiDB and make sure there is a <property name=”openjpa.jdbc.DBDictionary” value=”mysql“/> element in it.

Step 4 – Add users and roles to Tomcat

  1. Open C:\Arquivos de programas\apache-tomcat-6.0.32\conf\tomcat-users.xml and make sure it looks like this one:

<?xml version=’1.0′ encoding=’utf-8′?>
<tomcat-users>
<role rolename=”pluto“/>
<role rolename=”tomcat”/>
<role rolename=”manager”/>
<user username=”root” password=”root” roles=”pluto,tomcat,manager”/>
<user username=”uddi” password=”uddi” roles=”pluto,tomcat,manager”/>
<user username=”sales” password=”sales” roles=”pluto,tomcat,manager”/>
<user username=”marketing” password=”marketing” roles=”pluto,tomcat,manager”/>
<user username=”tomcat” password=”tomcat” roles=”manager”/>
</tomcat-users>

Step 5 – Enjoy your brand new Registry

Now start Tomcat and open your web browser at http://localhost:8080/juddiv3/. You should see a Apache jUDDI‘s welcome page like this one…
The Apache jUDDI's welcome page
The Apache jUDDI's welcome page

…or like the following one if you click on the jUDDI Portal link

Pluto: The jUDDI portal
Pluto: The jUDDI portal

Now you may for example connect to juddi MySQL database and execute the command “show tables;” just to list all tables created by the jUDDI installation process.

Some very important notes:

  • Of course the instructions on this post are not perfect for a production environment. I installed everything in my windows development sandbox. If you are installing it for a production environment I strongly recommend you not to use the same password as the login name of the MySQL user. Another thing is to change the default jUDDI Authentication.
  • It’s possible to do the same thing for a Linux environment. Just follow the instructions having Linux on your mind;

I’ll talk more about Apache jUDDI Registry on a next post.

Stay away from trouble!

Update at 2011-07-23 23:17

After logging in at Pluto you probably will see that the portlets don’t work. It may print some strack trace errors inside the portlet windows or a javascript alert “erro:null” is shown. To solve this problem you’ll have to do the following:

Make sure the file juddiv3.properties of webapps/juddiv3 and webapps/uddi-portlets have the same configurations. Therefore, copy webapps/juddiv3/WEB-INF/classes/juddiv3.properties to webapps/uddi-portlets/WEB-INF/classes/juddiv3.properties.