Skip to topic | Skip to bottom
Grimoires
Grimoires.UserManual

Start of topic | Skip to actions

Grimoires Tutorial

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 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>
   ......

Metadata Interface

Introduction

The metadata interface allows users to annotate entities within the grimoires registry. Within this document xsd represents the namespace http://www.w3.org/2001/XMLSchema, meta is the namespace http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd

Data Models

metadata

Metadata represents the annotation that is attached to entities within Grimories. It is defined in XML schema as
  <xsd:element name="metadata"             type="meta:Metadata"/>
  <xsd:complexType name="Metadata">
    <xsd:sequence>
      <xsd:element ref="meta:metadataType"/>
      <xsd:element ref="meta:metadataValue"/>
    </xsd:sequence>
    <xsd:attribute ref="meta:metadataKey" use="required"/>
  </xsd:complexType>
Any metadata in Grimoires consists of three items:
  1. metadataKey: unique key assigned by Grimoires when you publish a new piece of annotation
  2. metadataType: URI representing the type of annotation
  3. metadataValue: the value of the annotation. Can be either a string, a URI or an RDF triple.

MetadataValue? is defined as

  <xsd:element name="metadataValue"         type="meta:MetadataValue"/>
  <xsd:complexType name="MetadataValue">
    <xsd:choice>
      <xsd:element ref="meta:triplesAssertion"/>
      <xsd:element ref="meta:stringValue"/>
      <xsd:element ref="meta:uriValue"/>
    </xsd:choice>
  </xsd:complexType>

The following is an example of specifying a metadata with a string value:

   <meta:metadata meta:metadataKey="">
      <meta:metadataType>http://www.hogwarts.edu#headmaster</meta:metadataType>
      <meta:metadataValue>
         <meta:stringValue>Albus Dumbledore</meta:stringValue>
      </meta:metadataValue>
   </meta:metadata>

Another example for a metadata with a URI value:

   <meta:metadata meta:metadataKey="">
      <meta:metadataType>http://www.harrypotter.org#dumbledore</meta:metadataType>
      <meta:metadataValue>
         <meta:uriValue>http://www.lordoftherings.org#gandalf</meta:uriValue>
      </meta:metadataValue>
   </meta:metadata>

A triples assertion is defined as:

  <xsd:element name="triplesAssertion"     type="meta:TriplesAssertion"/>
  <xsd:complexType name="TriplesAssertion">
    <xsd:sequence>
      <xsd:element name="triples"            type="xsd:string"/>
      <xsd:element name="resourceIdentifier" type="xsd:string"/>
      <xsd:element name="language"           type="xsd:string"/>
      <xsd:element name="base"               type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>

Add example of RDF triple here!

metadataInfo

This is a response message from Grimoires. In addition of all the elements and attributes of #MetaData, it contains information about the author (not implemented yet) and last edited date of the metadata. It is defined as
  <xsd:element name="metadataInfo"             type="meta:MetadataInfo"/>
  <xsd:complexType name="MetadataInfo">
    <xsd:sequence>
      <xsd:element ref="meta:metadataType"/>
      <xsd:element ref="meta:metadataValue"/>
      <xsd:element ref="meta:author"/>
      <xsd:element ref="meta:date"/>
    </xsd:sequence>
    <xsd:attribute ref="meta:metadataKey" use="required"/>
  </xsd:complexType>

entityReference

An entity reference is a reference to things stored within Grimories. This can be the serviceKey for a UDDI businessService, or a message part within a WSDL file.

An entity reference for a UDDI businessService with a serviceKey 123456 looks like this:

   <meta:entityReference entityType="http://www.uddi.org/schema/uddi_v2.xsd#serviceKey">
      <meta:stringKey>123456</meta:stringKey>
   </meta:entityReference>

The entity reference for a UDDI businessEntity looks similar:

   <meta:entityReference entityType="http://www.uddi.org/schema/uddi_v2.xsd#businessKey">
      <meta:stringKey>78901</meta:stringKey>
   </meta:entityReference>

To annotate a WSDL file, you will first need to publish it in Grimoires. This is done via the WSDL interface. For more information, consult the WSDLInterfaceGuide. Using the BlastnWSDL as an example, to refer to the message part with name in0, you will need the message namespace, message name, and the message part name of the message part:

  <meta:entityReference entityType="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd#messagePartReference">
    <meta:messagePartReference>
      <meta:messageNamespace>http://www.ebi.ac.uk/alignment::blastn_ncbi::derived</meta:messageNamespace>
      <meta:messageName>runRequest1</meta:messageName>
      <meta:messagePartName>in0</meta:messagePartName>
    </meta:messagePartReference>
  </meta:entityReference>

To refer the operation run, you'll need its port type name, port type namespace, and operation name:

  <meta:entityReference entityType="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd#operationReference">
    <meta:operationReference>
      <meta:portTypeNamespace>http://www.ebi.ac.uk/alignment::blastn_ncbi::derived</meta:portTypeNamespace>
      <meta:portTypeName>AnalysisWSAppLabImpl</meta:portTypeName>
      <meta:operationName>run</meta:operationName>
    </meta:operationReference>
  </meta:entityReference>

metadataQuery

The metadataQuery and metadataQueryBag structures are used in query operations in the metadata interface. The metadataQueryBag is a sequence of 1 or more metadataQuery structures:
  <xsd:element name="metadataQueryBag" type="meta:MetadataQueryBag"/>
  <xsd:complexType name="MetadataQueryBag">
    <xsd:sequence>
      <xsd:element ref="meta:metadataQuery" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

Each metadataQuery specifies a metadataType and a metadataValue to search on. An optional findQualifiers can be used. Currently, only two findQualifier (wildCardSearch and caseSensitiveSearch) are supported for string based metadataValues. By default string comparisons are done as exact string matches.

An example of a metadataQuery for a URI metadataValue:

  <meta:metadataQuery>
    <meta:metadataType>http://www.harrypotter.org#dumbledore</meta:metadataType>
    <meta:metadataValue>
       <meta:uriValue>http://www.lordoftherings.org#gandalf</meta:uriValue>
    </meta:metadataValue>
  </meta:metadataQuery>

Another example of a metadataQuery, this time using the wildCardSearch findQualifier:

  <meta:metadataQuery>
    <findQualifiers>
      <findQualifier>wildCardSearch</findQualifier>
    </findQualifiers>
    <meta:metadataType>http://www.hogwarts.edu#headmaster</meta:metadataType>
    <meta:metadataValue>
      <meta:stringValue>Albus</meta:stringValue>
    </meta:metadataValue>
  </meta:metadataQuery>
This metadata query specifies a search all for strings that contains Albus.

faultDetail

Errors in the processing of metadata commands in Grimoires are communicated via faultDetail and faultDetailList elements within the SOAP Fault element. Here is an example of an error:
<soapenv:Fault>
  <faultcode>soapenv:Server.generalException</faultcode>
  <faultstring/>
  <detail>
    <ns1:faultDetailList xmlns:ns1="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd">
      <ns1:faultDetail errorCode="E_invalidKeyPassed" errorNumber="10210">
        <errorMessage>entityReference did not match with any known entity</errorMessage>
      </ns1:faultDetail>
    </ns1:faultDetailList>
    ....
  </detail>
</soapenv:Fault>
The detail of the error can be found within the errorMessage element.

Publish_metadata interface

This section introduces the interface for publishing metadata to existing entities in Grimoires. Entities supported for annotation includes UDDI businessEntities, businessServices, tModel and bindingTemplates, and WSDL message parts and operations. Publishing UDDIv2 entities in Grimoires is exactly like publishing in other UDDI registries (see UDDIUserGuide). To publish WSDL files, consult the WSDLInterfaceGuide.

Assuming that your Grimoires is installed at http://localhost:8080/grimoires, then this interface is available at http://localhost:8080/grimoires/services/publish_metadata. Two operations are present in this interface: addMetadataToEntity and deleteMetadata.

addMetadataToEntity

Suppose a UDDI service named STRING_CONCAT is published in Grimoires with a serviceKey 12345. You want to add a comment that the service can only be accessed in the US. To publish this metadata, the addMetadataToEntity operation of the publish_metadata interface is used:
<meta:addMetadataToEntity 
      xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api"
      xmlns:uddi="urn:uddi-org:api_v2">
   <meta:entityReference entityType="http://www.uddi.org/schema/uddi_v2.xsd#serviceKey">
      <meta:stringKey>12345</meta:stringKey>
   </meta:entityReference>
   <meta:metadata meta:metadataKey="">
      <meta:metadataType>http://purl.org/dc/terms/accessRights</meta:metadataType>
      <meta:metadataValue>
         <meta:stringValue>service is only available within US</meta:stringValue>
      </meta:metadataValue>
   </meta:metadata>
</meta:addMetadataToEntity>

The addMetadataToEntity message contains two elements --- #EntityReference and #MetaData. To annotate a different entity or to publish a different metadata, construct a suitable #EntityReference and #MetaData according to the guidelines described earlier in this article.

In this example, we use accessRights defined by the Dublin Core Metadata Initiative as our metadataType. The metadataKey is left empty, indicating this is a new piece of metadata. If a metadataKey is specified, the existing metadata with the specified key will be replaced.

If the operation is successful, grimoires return a #MetadataInfo message:

<metadataInfo ns1:metadataKey="67890"
              xmlns="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd" 
              xmlns:ns1="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd">
  <metadataType>http://purl.org/dc/terms/accessRights</metadataType>
  <metadataValue>
    <triplesAssertion xsi:nil="true"/>
    <stringValue>service is only available within US</stringValue>
    <uriValue xsi:nil="true"/>
  </metadataValue>
  <author xsi:nil="true"/>
  <date>Mon Jan 31 11:58:53 GMT 2005</date>
</metadataInfo>

Here, the metadataKey 67890 is assigned to the metadata attached to the STRING_CONCAT service.

deleteMetadata

To delete the metadata published in the example in #AddMetadataToEntity, you will need its metadataKey (67890 here):
<meta:deleteMetadata xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api">
   <meta:metadataKey>67890</meta:metadataKey>
</meta:deleteMetadata>

Inquire_metadata interface

This section explains the operations of the inquire_metadata interface. Assuming that your Grimoires is installed at http://localhost:8080/grimoires, then this interface is available at http://localhost:8080/grimoires/services/inquire_metadata. There are three operations available at this interface: get_entityMetadata, get_metadataDetail and find_entityByMetadata.

get_entityMetadata

You can retrieve metadata attached to entities in Grimoires using the get_entityMetadata message. To retrieve metadata attached to the STRING_CONCAT service in the previous example:
<meta:get_entityMetadata 
        xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api"
        xmlns:uddi="urn:uddi-org:api_v2">
  <meta:entityReference entityType="http://www.uddi.org/schema/uddi_v2.xsd#serviceKey">
    <meta:stringKey>12345</meta:stringKey>
  </meta:entityReference>
</meta:get_entityMetadata>

On success, a metadataInfos message is returned. This is a list of zero or more #MetadataInfo:

<metadataInfos xmlns="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd">
  <metadataInfo ns1:metadataKey="98d60e47-53f8-477b-9608-9c0cfd2cb986"
                xmlns:ns1="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd">
    <metadataType>http://purl.org/dc/terms/accessRights</metadataType>
    <metadataValue>
      <stringValue>service is only available within US</stringValue>
    </metadataValue>
    <date>Mon Jan 31 11:58:53 GMT 2005</date>
  </metadataInfo>
</metadataInfos>

get_metadataDetail

The operation retrieves the details of a piece of metadata using its metadataKey. Assuming the metadataKey is 67890:
<meta:get_metadataDetail xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api">
   <meta:metadataKey>67890</meta:metadataKey>
</meta:get_metadataDetail>

If the operation is successful, a #MetadataInfo message is returned.

find_entityByMetadata

This operations allows you to search for entities containing specific pieces of metadata using #MetadataQuery:
<meta:find_entityByMetadata xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api">
  <meta:metadataQueryBag>
    <meta:metadataQuery/>
    [<meta:metadataQuery/> ...]
  </meta:metadataQueryBag>
</meta:find_entityByMetadata>

On success, Grimoires returns an entityReferenceList containing #EntityReferences that are annotated with the specified metadata. The format of the entityReferenceList is

  <xsd:element name="entityReferenceList"          type="meta:EntityReferenceList"/>
  <xsd:complexType name="EntityReferenceList">
    <xsd:sequence>
      <xsd:element ref="meta:entityReference" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

UDDI specific operations

Services from this interface is available at http://localhost:8080/grimoires/services/inquire_uddiMetadata.

find_service

This operation adds a #MetadataQueryBag to the normal UDDIv2 find_service function. It is defined as:
  <xsd:element name="find_service" type="meta:Find_service"/>
  <xsd:complexType name="Find_service">
    <xsd:sequence>
      <xsd:element ref="meta:findQualifiers" minOccurs="0"/>
      <xsd:element ref="uddi:name" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element ref="uddi:categoryBag" minOccurs="0"/>
      <xsd:element ref="uddi:tModelBag" minOccurs="0"/>
      <xsd:element ref="meta:metadataQueryBag" minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="generic" type="string" use="required"/>
    <xsd:attribute name="maxRows" type="int" use="optional"/>
    <xsd:attribute name="businessKey" type="uddi:businessKey" use="optional"/>
  </xsd:complexType>

For example, you want to search for a service with the name "Great Service" and created by "John Smith" (ie metadataType = http://purl.org/dc/elements/1.1/creator, metadataValue = John Smith):

<meta:find_service generic="2.0"
                   uddi:businessKey=""
                   xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api"  
                   xmlns:uddi="urn:uddi-org:api_v2">
   <uddi:name>Great Service</uddi:name>
   <meta:metadataQueryBag>
     <meta:metadataQuery>
       <meta:metadataType>http://purl.org/dc/elements/1.1/creator</meta:metadataType>
       <meta:metadataValue>
          <meta:stringValue>John Smith</meta:stringValue>
       </meta:metadataValue>
     </meta:metadataQuery>
   </meta:metadataQueryBag>
</meta:find_service>

On success, a UDDIv2 ServiceList? is returned.

WSDL specific operations

A collection of WSDL specifc operation are available at the inquire_wsdlMetadata interface. Assuming that your Grimoires is installed at http://localhost:8080/grimoires, this interface is available at http://localhost:8080/grimoires/services/inquire_wsdlMetadata.

find_interfaceByMessagePartMetadata

This opertion searches all WSDL files published in Grimoires to find those that have certain metadata attached to their message parts. The search criteria is specified using a #MetadataQueryBag. Following is an example:

<meta:find_interfaceByMessagePartMetadata xmlns:meta="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata_api">
  <meta:metadataQueryBag>
    <meta:metadataQuery>
      <meta:metadataType>http://www.harrypotter.org#dumbledore</meta:metadataType>
      <meta:metadataValue><meta:uriValue>http://www.lordoftherings.org#gandalf</meta:uriValue></meta:metadataValue>
    </meta:metadataQuery>
  </meta:metadataQueryBag>
</meta:find_interfaceByMessagePartMetadata>

On success, a #UriBag is returned. It is defined as:

  <xsd:element name="uriBag"          type="meta:uriBag"/>
  <xsd:element name="uri" type="xsd:anyURI"/>
  <xsd:complexType name="uriBag">
    <xsd:sequence>
      <xsd:element ref="meta:uri" minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>

An example:

<uriBag xmlns="http://www.ecs.soton.ac.uk/~lavm/ontologies/metadata.xsd">
   <uri> http://www.ecs.soton.ac.uk/~sm/blastn.wsdl</uri>
</uriBag>

find_interfaceByOperationMetadata

This opertion searches all WSDL files published in Grimoires to find those that have certain metadata attached to their operations. The search criteria is specified using a #MetadataQueryBag. It has a similar syntax to find_interfaceByMessagePartMetadata:
  <xsd:element name="find_interfaceByOperationMetadata" type="meta:Find_interfaceByOperationMetadata"/>
  <xsd:complexType name="Find_interfaceByOperationMetadata">
    <xsd:sequence>
      <xsd:element ref="meta:metadataQueryBag"/>
    </xsd:sequence>
  </xsd:complexType>

On success, a #UriBag is returned. -- WeijianFang - 17 May 2005
to top


You are here: Grimoires > SoftwareReleases > GrimoiresRelease101 > UserManual

to top

Copyright 2004 by the University of Southampton