Tutorial - Grimoires Service

Introduction

This document contains a tutorial for the Grimoires service. It consists of a small execution scenario, illustrating the behaviour of the Grimoires. For each step in the scenario, we provide an input message sent to the registry, and the output message that is returned as a response. We refer the reader to the Tutorial on GShell client and the Tutorial on Java Client Side API for techniques by which such messages can be submitted to the registry.

UDDI Interface

Introduction

This section 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 section 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 section 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 WSDL file is located at http://xml.nig.ac.jp/wsdl/Blast.wsdl.

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

Create a new business entity

All services published in the Grimoires registry (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 registry 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. it 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. It 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 AddressBookImpl which implements an AddressBook interface. 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 JavaClassRepository. 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

Grimoires can also be used to publish descriptions of workflows, like a UDDI service. For instance, below, we publish this SCUFL workflow (SCUFL is the workflow notation supported by myGrid Taverna and Freefluo development environment and enactment engines). 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>workflowRepository</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 registry will respond 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>
   ......

WSDL Interface and Metadata Interface

Introduction

We will also publish the service's WSDL file, and attach a piece of metadata to a message part inside the WSDL description. The metadata describes the semantic type, i.e., a DNA sequence, of the message part, which is syntactically a string. Finally, we discover the message part based on the metadata. Given the message part, we can further discover which operation this message part belongs to, which WSDL description the operation belongs to, and which service has implemented the WSDL description. Following these steps, a service can be discovered by its metadata.

Publish the WSDL file

Publish a WSDL file which is located at http://xml.nig.ac.jp/wsdl/Blast.wsdl.

<addWSDLFileRequest xmlns="http:/www.grimoires.org/wsdl/type">
	http://xml.nig.ac.jp/wsdl/Blast.wsdl
</addWSDLFileRequest>

A WSDL key is returned.

<addWSDLFileResponse xmlns="http:/www.grimoires.org/wsdl/type">
	50999bee-a167-4380-9420-8ee12e7b178e
</addWSDLFileResponse>

Publish metadada

Attach a metadata to a message part. The metadata is of the type "http://www.grimoires.org/SemanticType", and has the value "DNA_Sequence". The message part has the name "param", and it belongs to the message "http://www.themindelectric.com/wsdl/Blast#searchParam0In". 

<addMetadataToEntity xmlns="http://www.grimoires.org/metadata.xsd">
	<entityReference entityType="http://www.grimoires.org/metadata.xsd#messagePartReference">
		<messagePartReference>
			<messageNamespace>http://www.themindelectric.com/wsdl/Blast/</messageNamespace>
			<messageName>searchParam0In</messageName>
			<messagePartName>param</messagePartName>
		</messagePartReference>
	</entityReference>
	<metadata>
		<metadataType>http://www.grimoires.org/SemanticType</metadataType>
		<metadataValue>
			<stringValue>DNA_Sequence</stringValue>
		</metadataValue>
	</metadata>
</addMetadataToEntity>

A piece of metadata information is returned.

<metadataInfo ns1:metadataKey="9e060eca-7642-4317-af6c-c203d292d86c"
		xmlns="http://www.grimoires.org/metadata.xsd"
		xmlns:ns1="http://www.grimoires.org/metadata.xsd">
	<metadataType>http://www.grimoires.org/SemanticType</metadataType>
	<metadataValue><stringValue>DNA_Sequence</stringValue></metadataValue>
	<date>Wed Sep 07 10:33:23 BST 2005</date>
</metadataInfo>

Inquire by metadata

Inquire for a message part attached with a metadata that is of the type "http://www.grimoires.org/SemanticType", and has the value "DNA_Sequence". 

<find_entityByMetadata xmlns="http://www.grimoires.org/metadata.xsd">
	<metadataQueryBag>
		<metadataQuery>
			<metadataType>http://www.grimoires.org/SemanticType</metadataType>
			<metadataValue>
				<stringValue>DNA_Sequence</stringValue>
			</metadataValue>
		</metadataQuery>
	</metadataQueryBag>
</find_entityByMetadata>

A matched message part is returned.

<entityReferenceList xmlns="http://www.grimoires.org/metadata.xsd">
	<entityReference entityType="http://www.grimoires.org/metadata.xsd#messagePartReference">
		<messagePartReference>
			<messageNamespace>http://www.themindelectric.com/wsdl/Blast/</messageNamespace>
			<messageName>searchParam0In</messageName>
			<messagePartName>param</messagePartName>
		</messagePartReference>
	</entityReference>
</entityReferenceList>