Skip to topic | Skip to bottom
Grimoires
Home

Create personal sidebar

Grimoires.UDDIUserGuide
Start of topic | Skip to actions

User Guide

Introduction

This document describes the publication and discovery of web services in the Grimoires. Examples will be in the form of UDDI messages, so basic familiarity with UDDI is assumed. For more information on UDDI, consult the UDDI.org website.

The first part of this document details how to publish a sample service. This includes creating a business entity, a tModel, and lastly a business service. The second part of this document decribes how to query the Grimoires about published services. Examples include finding services by name, by business entities and by tModels.

Publication of services

SOAP web services

In this section, we will publish the BLAST service from the DNA Data Bank of Japan (DDBJ). The service is described using WSDL as the description language. The endpoint is located at http://xml.nig.ac.jp/wsdl/Blast.wsdl. (The WSDL file is replicated here for reference).

All the UDDI messages listed in the section should be sent to the publish URL of your Grimoires server.

Create a new business enitity

All services published in the Grimoires (and all UDDI registries) must be owned by a business entity. Therefore, we will need to create a new business entity for the DDBJ first. This is achieved using the save_business message. 

<save_business xmlns="urn:uddi-org:api_v2" generic="2.0"> 
   <businessEntity businessKey="">
       <name>DDBJ</name>
   </businessEntity>
</save_business>

The Grimoires will reply with a business detail message. This reply message reflects the information supplied in the save_business call. It will also contain the businessKey assigned to the newly registered business entity by the Grimoires. This businessKey will be used later in this UserGuide, will be referred to as $your business key$. (In this example, $your business key$ = 5f3a6bb1-3d2c-4568-9510-229ba6ba5f6e, but your Grimoires installation will assign you a different value). 

<businessDetail xmlns="urn:uddi-org:api_v2">    
   <businessEntity businessKey="5f3a6bb1-3d2c-4568-9510-229ba6ba5f6e">     
       <name>DDBJ</name> 
   </businessEntity>   
</businessDetail>

It is possible to supply more information about the business entity besides its name in the save_business call. The following example creates a business entity for DDBJ with a name, a description and some contact information (email, phone and address). 

<save_business xmlns="urn:uddi-org:api_v2" generic="2.0">
   <authInfo/>
     <businessEntity businessKey="">     
     <name>DDBJ</name>     
     <description>DNA Data Bank of Japan</description>     
        <contacts>       
           <contact>
              <description>Inquiry</description>         
              <email>ddbj@ddbj.nig.ac.jp</email>
              <phone>+81-55-981-6849</phone>
              <address>
                 <addressLine>Center for Information Biology and DNA Data Bank
                              of Japan</addressLine>                  
                 <addressLine>National Institute of Genetics</addressLine>
                 <addressLine>1111 Yata, Mishima, 411-8540, Japan</addressLine>
              </address>                      
          </contact>     
      </contacts>   
  </businessEntity>
</save_business>

Create a new tModel

TModels provide information about technical interfaces. Since WSDL service interface definitions are intended to describe service instances, it is therefore consequently natural to register them as tModels. This is also the recommendation made by the Web Services Interoperability Organisation.

The save_tModel function is used to publish a tModel in a UDDI registry: 

<save_tModel generic="2.0" xmlns="urn:uddi-org:api_v2" >
   <authInfo/>
   <tModel>
       <name/>
       <description/>
       <overviewDoc/>
       <categoryBag/>
   </tModel>
</save_tModel>

To assert that a tModel uses WSDL as its technical interface, we classify it using the uddi-org:types taxonomy, as being of type "wsdlSpec". 

<categoryBag>
   <keyedReference keyName="uddi-org:types" keyValue="wsdlSpec"
       tModelKey="uuid:C1ACF26D-9672-4404-9D70-39B756E62AB4"/>
</categoryBag>

We must also specify an overviewDoc whose overviewURL points to the relevant WSDL document: 

<overviewDoc>
   <overviewURL>http://xml.nig.ac.jp/wsdl/Blast.wsdl</overviewURL>
</overviewDoc>

If the WSDL document includes multiple bindings, we can refer to a single binding (Blast in this case) by: 

<overviewDoc>
  <overviewURL>
    http://xml.nig.ac.jp/wsdl/Blast.wsdl#xmlns(wsdl=http://schemas.xmlsoap.org/wsdl/)xpointer(//wsdl:binding[@name='Blast'])
  </overviewURL>
</overviewDoc>

Now we are ready to publish the WSDL as a tModel using the save_tModel message. The following example publishes a tModel with a name, 4 descriptions, and the overviewDoc and categoryBag as described before: 

<save_tModel generic="2.0" xmlns="urn:uddi-org:api_v2">
   <authInfo/>
   <tModel tModelKey="">
      <name>DNA Databank of Japan: Blast</name>
      <description>SHORT DESCRIPTION: Execute BLAST specified with program,
         database and query.</description>
      <description>DETAILED DESCRIPTION: For more information on the DNA
         Databank of Japan, please see http://www.ddbj.nig.ac.jp/intro-e.html</description>
      <description>USAGE NOTES: Please see the service homepage for more
         information.</description>
      <description>HOMEPAGE URL:http://xml.nig.ac.jp/doc/Blast.txt</description>
      <overviewDoc>
         <description>wsdl link</description>
         <overviewURL>http://xml.nig.ac.jp/wsdl/Blast.wsdl</overviewURL>
      </overviewDoc>
      <categoryBag>
         <keyedReference keyName="uddi-org:types" keyValue="wsdlSpec"
            tModelKey="uuid:C1ACF26D-9672-4404-9D70-39B756E62AB4"/>
      </categoryBag>
   </tModel>
</save_tModel>

The Grimoires will reply with a tModel detail message. This reply message reflects the information supplied in the save_tModel call. It will also contain the tModelKey assigned to the newly registered tModel by the Grimoires. This tModelKey will be used later in this UserGuide, will be referred to as $your tModel key$. (In this example, $your tModel key$ = e78ed689-9e32-4e81-b90b-86ac806051dc, but your Grimoires installation will assign you a different value). 

<tModelDetail xmlns="urn:uddi-org:api_v2">    
   <tModel tModelKey="e78ed689-9e32-4e81-b90b-86ac806051dc">     
      <name>DNA Databank of Japan: Blast</name>
      ....
   </tModel>   
</tModelDetail>

Create a new business service

A business service is published with the save_service message: 

<save_service generic="2.0" xmlns="urn:uddi-org:api_v2" >
   <authInfo/>
   <businessService>
      <name/>
      <description/>
      <bindingTemplates>
         <bindingTemplate>
            <accessPoint/>
            <tModelInstanceDetails/>
         </bindingTemplate>
      </bindingTemplates>
   </businessService>
</save_service>

UDDI represents Web service instances as bindingTemplate elements. The accessPoint refers to the network address of the access point of the service. Assuming that the address specified for the service/port (soap:address) in the WSDL document is http://xml.nig.ac.jp/xddbj/Blast, then 

<accessPoint URLType="http">
   http://xml.nig.ac.jp/xddbj/Blast
</accessPoint>

The tModelInstanceInfo refers to the tModels that are relevent to the service end point being described. Here, $your tmodel key$ is the tModelKey you obtained from the reply message from save_tModel. 

<tModelInstanceDetails>
   <tModelInstanceInfo tModelKey="$your tmodel key$"/>
</tModelInstanceDetails>

Together with the businessKey created earlier (replace $your business key$ with that), we can publish the BLAST service as 

<save_service generic="2.0" xmlns="urn:uddi-org:api_v2">
   <authInfo/>
   <businessService serviceKey="" businessKey="$your business key$">
      <name>DNA Databank of Japan: Blast</name>
      <description>Endpoint for service</description>
      <description>IMPLEMENTATION: apachesoap</description>
      <bindingTemplates>
         <bindingTemplate bindingKey="">
            <accessPoint URLType="http">http://xml.nig.ac.jp/xddbj/Blast
            </accessPoint>
            <tModelInstanceDetails>
              <tModelInstanceInfo tModelKey="$your tmodel key$"/>
            </tModelInstanceDetails>
         </bindingTemplate>
      </bindingTemplates>
    </businessService>
</save_service>

Service from java classes

The java binding provided by the Web Services Invocation Framework (WSIF) allows functionality in a WSDL service description to be mapped to the functionality provided by a Java class directly. In other words, a Java class can be described using WSDL, and can be accessed as a WSDL-described service through WSIF.

In this section, we will publish the service provided by the function addEntry within a java class addressbook.wsiftypes.AddressBook. A WSDL description has been written for this function using the WSIF extension.

Create a new business entity

Similar to the SOAP web service example, the published service has to be owned by a business entity. We will create a business entity called my java classes. This business entity can be used to publish all the functionalities provided by all your local java classes. 

<save_business xmlns="urn:uddi-org:api_v2" generic="2.0"> 
   <businessEntity businessKey="">
       <name>my java classes</name>
   </businessEntity>
</save_business>

Create a new tModel

A tModel is created for the WSDL interface in this WSDL description. In the following example, the WSDL file is available on the local hard disk at c:\My Documents\AddressBook.wsdl. 

<save_tModel generic="2.0" xmlns="urn:uddi-org:api_v2">
   <authInfo/>
   <tModel tModelKey="">
      <name>addressbook.wsiftypes.AddressBook::addEntry</name>
      <description>Add entry to an address book</description>
      <overviewDoc>
         <description>wsdl link</description>
         <overviewURL>file://c:/my%20documents/addressbook.wsdl</overviewURL>
      </overviewDoc>
      <categoryBag>
         <keyedReference keyName="uddi-org:types" keyValue="wsdlSpec"
            tModelKey="uuid:C1ACF26D-9672-4404-9D70-39B756E62AB4"/>
      </categoryBag>
   </tModel>
</save_tModel>

For a UNIX path name (eg /home/luser/Address.wsdl) 

         <overviewURL>file:///home/luser/Addressbook.wsdl</overviewURL>

Or, if you have put the WSDL up on your personal webspace (eg http://www.example.com/~abc/AddressBook.wsdl) 

         <overviewURL>http://www.example.com/~abc/AddressBook.wsdl</overviewURL>

Create a new business service

Now we are ready to publish the addEntry service. 

<save_service generic="2.0" xmlns="urn:uddi-org:api_v2">
   <authInfo/>
   <businessService serviceKey="" businessKey="$your business key$">
      <name>AddEntry to AddressBook</name>
      <bindingTemplates>
         <bindingTemplate bindingKey="">
            <accessPoint URLType="other">addressbook.wsiftypes.AddressBook
            </accessPoint>
            <tModelInstanceDetails>
              <tModelInstanceInfo tModelKey="$your tmodel key$"/>
            </tModelInstanceDetails>
         </bindingTemplate>
      </bindingTemplates>
    </businessService>
</save_service>

Workflows

In this example, we will publish this workflow as a UDDI service. A WSDL description is created for this workflow: 

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="CandidateGeneAnalysis" targetNamespace="http://www.mygrid.org.uk" 
             xmlns:tns="http://www.mygrid.org.uk" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
             xmlns="http://schemas.xmlsoap.org/wsdl/">
  <message name="WholeWorkflowRunResponse">
    <part name="outfile_emblEntryWithSNPs" type="xsd:string"/>
  </message>
  <message name="WholeWorkflowRunRequest">
    <part name="probeSetId" type="xsd:string"/>
  </message>
  <portType name="WholeWorkflowIO">
    <operation name="WholeWorkflowRun">
      <input name="WholeWorkflowRunInput" message="WholeWorkflowRunRequest"/>
      <output name="WholeWorkflowRunOutput" message="WholeWorkflowRunResponse"/>
    </operation>
  </portType>
</definitions>

Create a new business entity

We will create a business entity that owns all the local workflows. 
<save_business xmlns="urn:uddi-org:api_v2" generic="2.0"> 
   <businessEntity businessKey="">
       <name>my workflows</name>
   </businessEntity>
</save_business>

Create a new tModel

A tModel is created for the WSDL interface of the workflow. We will assume that the WSDL file is available on the local hard disk at c:\My Documents\workflow.wsdl. 

<save_tModel generic="2.0" xmlns="urn:uddi-org:api_v2">
   <authInfo/>
   <tModel tModelKey="">
      <name>a workflow</name>
      <overviewDoc>
         <overviewURL>file://c:/my%20documents/workflow.wsdl</overviewURL>
      </overviewDoc>
      <categoryBag>
         <keyedReference keyName="uddi-org:types" keyValue="wsdlSpec"
            tModelKey="uuid:C1ACF26D-9672-4404-9D70-39B756E62AB4"/>
      </categoryBag>
   </tModel>
</save_tModel>

Create a new business service

Lastly, we can publish the workflow as a service. 

<save_service generic="2.0" xmlns="urn:uddi-org:api_v2">
   <authInfo/>
   <businessService serviceKey="" businessKey="$your business key$">
      <name>a simple workflow</name>
      <bindingTemplates>
         <bindingTemplate bindingKey="">
            <accessPoint URLType="other">file://c:/my%20documents/workflow.scufl
            </accessPoint>
            <tModelInstanceDetails>
              <tModelInstanceInfo tModelKey="$your tmodel key$"/>
            </tModelInstanceDetails>
         </bindingTemplate>
      </bindingTemplates>
    </businessService>
</save_service>

Discovery of services

This section demonstrates a few different ways to query about the BLAST service created previously. All the UDDI messages here should be sent to the inquiry endpoint of the Grimoires.

You can search for a service with its name using find_serivce. The following message searches for all businessServices called DNA Databank of Japan: Blast from all business entities registered with the server. 

<find_service xmlns="urn:uddi-org:api_v2" generic="2.0" businessKey="">    
   <name>DNA Databank of Japan: Blast</name>
</find_service>

The Grimoires replies with a serviceList message, which contains a list of businessService elements that matches the search criterion.

If you know the businessKey of the businessEntity that provides the service, you can limit the search to the specific business entity instance. 

<find_service xmlns="urn:uddi-org:api_v2" generic="2.0" businessKey="$your business key$">    
   <name>DNA Databank of Japan: Blast</name>
</find_service>

Wildcard searches are also possible. % is the wildcard character for UDDI. The following message searches for all services that contain the word blast in its name. 

<find_service xmlns="urn:uddi-org:api_v2" generic="2.0" businessKey="">    
   <name>%Blast%</name>
</find_service>

Alternatively, with the find_business message, you can retrieve all services provided by a given business. (Wildcard searches with % are allowed). 

<find_business xmlns="urn:uddi-org:api_v2" generic="2.0">   
   <name>DDBJ</name>
</find_business>

The Grimoires will repsond with a businessList message. This structure contains information about each matching business, including summaries of the businessServices exposed.

If you have the tModelKey, you can also search for services that are defined with a specific WSDL document (tModel). 

<find_service xmlns="urn:uddi-org:api_v2" generic="2.0" businessKey="">
   <tModelBag>
      <tModel tModelKey="$your tModel key$">
   </tModelBag>
</find_service>

Appendix: SOAP Messages

All the XML messages in this document are shown without their SOAP envelopes. The full SOAP message for 

<find_business xmlns="urn:uddi-org:api_v2" generic="2.0">   
   <name>DDBJ</name>
</find_business>

is 

<?xml version='1.0' ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header />
   <SOAP-ENV:Body>
      <find_business xmlns="urn:uddi-org:api_v2" maxRows="5" generic="2.0">   
         <name>DDBJ</name>
      </find_business>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This is then placed in the body of a HTTP POST request: 

POST /services/grimoires/inquire HTTP/1.1
Host: grimoires.hosted.here
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: ""

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header />
   <SOAP-ENV:Body>
   ......

to top
End of topic
Skip to action links | Back to top

Edit | Attach image or document | Printable version | Raw text | More topic actions
Revisions: | r1.1 | Total page history | Backlinks
You are here: Grimoires > UDDIUserGuide

to top

Copyright © 2004 by the University of Southampton