Skip to topic | Skip to bottom
Grimoires
Grimoires.FunctionalSpecification

Start of topic | Skip to actions

Functional Specification

Introduction

A Grimoire is a magician's manual for invoking demons (Oxford English Dictionary). Likewise, the Grimoires registry hosts descriptions of services and workflows, which a scientist can use for forming their complex scientific experiments. However, service and workflow interfaces are sometimes underspecified and therefore difficult to use in an automated manner; hence, the myGrid registry augments their interfaces with metadata such as functionality, semantic information about their inputs and outputs, or various metrics (e.g. perceived quality of service, trust).

Grimoires has three web service interfaces, namely

  • UDDIv2 API: follow UDDIv2 specification
  • WSDL API: publication and inquiry of web service technical specification described by a WSDL file.
  • Metadata API: publication and inquiry of metadata that can be attached to UDDI entities or WSDL elements. Inquiry by metadata is also supported.

In the following sections, these interfaces will be described in turn.

In addition, we have a Feta interface which is provided to the myGrid project.

UDDI interface

The UDDI interface of Grimoires conforms to the UDDIv2 specification, as described in the following documentations:

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 structures

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>

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>

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.

<xsd:complexType name="EntityReference">
   <xsd:choice>
      <xsd:element name="stringKey"  type="xsd:string"/>
      <xsd:element ref="meta:metadataKey"/>
      <xsd:element ref="meta:messagePartReference"/>
      <xsd:element ref="meta:operationReference"/>
   </xsd:choice>
   <xsd:attribute name="entityType" type="anyURI" use="required"/>
</xsd:complexType>

<xsd:complexType name="MessagePartReference">
   <xsd:sequence>
     <xsd:element ref="meta:messageNamespace"/>
     <xsd:element ref="meta:messageName"/>
     <xsd:element ref="meta:messagePartName"/>
   </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="OperationReference">
  <xsd:sequence>
    <xsd:element name="portTypeNamespace" type="xsd:string"/>
    <xsd:element name="portTypeName"      type="xsd:string"/>
    <xsd:element name="operationName"     type="xsd:string"/>
  </xsd:sequence>
</xsd:complexType>

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.

faultDetail

Errors in the processing of metadata commands in Grimoires are communicated via faultDetail and faultDetailList elements within the SOAP Fault element.
<xsd:complexType name="FaultDetailList">
  <xsd:sequence>
    <xsd:element ref="meta:faultDetail" maxOccurs="unbounded"/>
  </xsd:sequence>
</xsd:complexType>
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.

addMetadataToEntity

Attach a piece of metadata to an Entity.

Syntax

  <xsd:complexType name="AddMetadataToEntity">
    <xsd:sequence>
      <xsd:element ref="meta:entityReference"/>
      <xsd:element ref="meta:metadata"/>
    </xsd:sequence>
  </xsd:complexType>

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

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

deleteMetadata

To delete a piece of metadata.

Syntax

 <xsd:complexType name="DeleteMetadata">
    <xsd:sequence>
      <xsd:element ref="meta:metadataKey"/>
    </xsd:sequence>
  </xsd:complexType>

Auguments

metadataKey: the key of the published metadata.

Returns

<xsd:element name="success" type="xsd:boolean"/>

TRUE represents for success, FALSE for failure.

Inquire_metadata interface

This section explains the operations of the inquire_metadata interface. There are three operations available at this interface: get_entityMetadata, get_metadataDetail and find_entityByMetadata.

get_entityMetadata

To retrieve metadata attached to entities in Grimoires using the get_entityMetadata message.

Syntax
  <xsd:complexType name="Get_entityMetadata">
    <xsd:sequence>
      <xsd:element ref="meta:entityReference"/>
    </xsd:sequence>
  </xsd:complexType>

Auguments
entityReference is described in #EntityReference.

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

get_metadataDetail

To retrieve the details of a piece of metadata using its metadataKey.

Syntax
  <xsd:complexType name="Get_metadataDetail">
    <xsd:sequence>
      <xsd:element ref="meta:metadataKey"/>
    </xsd:sequence>
  </xsd:complexType>

Auguments
metadataKey: the key of the published metadata.

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

#find_entityByMetadata

find_entityByMetadata

To search for entities containing specific pieces of metadata.

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

Auguments
metadataQuery is defined in #MetadataQuery.

Returns
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

find_service

This operation adds a #MetadataQueryBag to the normal UDDIv2 find_service function.

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

Auguments
Please refer to UDDI data structure reference.

Returns
On success, a UDDIv2 ServiceList? is returned.

WSDL specific operations

A collection of WSDL specifc operation are available at the inquire_wsdlMetadata interface.

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.

Syntax
  <xsd:complexType name="Find_interfaceByMessagePartMetadata">
    <xsd:sequence>
      <xsd:element ref="meta:metadataQueryBag"/>
    </xsd:sequence>
  </xsd:complexType>

Auguments
They are as same as those of #find_entityByMetadata.

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

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.

Syntax
  <xsd:complexType name="Find_interfaceByOperationMetadata">
    <xsd:sequence>
      <xsd:element ref="meta:metadataQueryBag"/>
    </xsd:sequence>
  </xsd:complexType>

Auguments
They are as same as those of #find_entityByMetadata.

Returns
On success, a #UriBag is returned.

WSDL interface

Introduction

This document describes the WSDL interface of Grimoires. Grimoires extends standard UDDI registry in that it not only provides UDDI publication and inquiry interface, but also provides other interfaces, for example, the WSDL interface.

Through WSDL interface, users can publish, update, delete, and retrieve a WSDL file in Grimoires, as well as inquire a service implementing a specified WSDL file.

In UDDI data model, the WSDL url of a web service is represented by a TModel. A UDDI service entity contains one or more binding templates, which refer to some TModel. However, UDDI specification lacks the capability to register the content of WSDL file.

The benefits of registering the content of WSDL file are, (1) we can attach metadata to entities inside WSDL files, (2) we can reason on the semantics of entities inside WSDL files based on some ontology information.

The WSDL file of the WSDL interface

Operations

addWSDLFile

Add a WSDL file to the registry.

Syntax
<element name="addWSDLFileRequest" type="string" />

Auguments
A string representing the url of the wsdl file.

Returns
<element name="addWSDLFileResponse" type="string" />
A string representing the WSDL key, which is the UUID for this WSDL file.

addWSDLFileAdvert

Add a WSDL file with content to the registry.

Syntax
<complexType name="addWSDLFileAdvertRequest">
  <sequence>
    <element name="url" type="string" />
    <element name="content" type="string" />
  </sequence>
</complexType>

Auguments

url: the url of the wsdl file.

content: the content of wsdl file.

Returns
<element name="addWSDLFileAdvertResponse" type="string" />
A string representing the WSDL key, which is the UUID for this WSDL file.

getWSDLAdvertContent

Return the WSDL content of the advert identified by the given key.

Syntax
<element name="getWSDLAdvertContentRequest" type="string" />

Auguments
WSDL key.

Returns
<element name="getWSDLAdvertContentResponse" type="string" />
the content of WSDL file.

getWSDLAdvertContentByURL

Return the WSDL content of the advert identified by the url of WSDL.

Syntax
<element name="getWSDLAdvertContentByURLRequest" type="string" />

Auguments
The url of WSDL file.

Returns
<element name="getWSDLAdvertContentByURLResponse" type="string" />
the content of WSDL file.

removeWSDLFile

Remove a WSDL file from the repository.

Syntax
<element name="removeWSDLFileRequest" type="string" />

Auguments

The url of WSDL file.

Returns
<element name="removeWSDLFileResponse" type="boolean" />
True or false indicating whether the deletion operation is successful.

findServicesByInterface

Return all UDDI services that are registered as implementing the WSDL interface at the given url.

Syntax
<element name="findServicesByInterfaceRequest" type="string" />   

Auguments

The url of wsdl file.

Returns
<complexType name="findServicesByInterfaceResponse">
  <sequence>
     <element maxOccurs="unbounded" minOccurs="0" name="serviceKey" type="string" />
  </sequence>
</complexType>
The UDDI service keys.

getAllWSDLFiles

Return the URLs of all WSDL adverts registered in Grimoires.

Syntax
<complexType name="getAllWSDLFilesRequest"/>

Auguments

Null.

Returns
<complexType name="getAllWSDLFilesResponse">
  <sequence>
    <element maxOccurs="unbounded" minOccurs="0" name="url" type="string" />
  </sequence>
</complexType>
the urls of all registered WSDLs.

getOperationsByURL

Get the names of all operations in a WSDL file.

Syntax
<element name="getOperationsByURLRequest" type="string" />

Auguments

The url of the WSDL.

Returns
<complexType name="getOperationsByURLResponse">
  <sequence>
    <element maxOccurs="unbounded" minOccurs="0" name="operationDetail" type="tns:operationDetail" />
  </sequence>
</complexType>

<complexType name="operationDetail">
  <sequence>
    <element name="portTypeNamespace" type="string"/>
    <element name="portTypeName" type="string"/>
    <element name="operationName" type="string"/>
  </sequence>
</complexType>
an array of OperationDetail? that describes the names of all operations defined in this WSDL. Each OperationDetail? unambiguously describes the name of an operation.

getInputMessageOfOperation

getOutputMessageOfOperation

getFaultMessageOfOperation

Get the input, output, or fault message information for a certain operation.

Syntax
<element name="getInputMessageOfOperationRequest" type="tns:operationDetail" />
<element name="getOutputMessageOfOperationRequest" type="tns:operationDetail" />
<element name="getFaultMessageOfOperationRequest" type="tns:operationDetail" />

Auguments
An OperationDetail? object describing a certain operation.

Returns
<element name="getInputMessageOfOperationResponse" type="tns:messageDetail" />
<element name="getOutputMessageOfOperationResponse" type="tns:messageDetail" />
<element name="getFaultMessageOfOperationResponse" type="tns:messageDetail" />

<complexType name="messageDetail">
  <sequence>
    <element name="messageNamespace" type="string"/>
    <element name="messageName" type="string"/>
    <element name="partsName" type="tns:partsName"/>
  </sequence>
</complexType>

<complexType name="partsName">
  <sequence>
    <element maxOccurs="unbounded" minOccurs="0" name="name" type="string" />
  </sequence>
</complexType>
An MessageDetail? object that gives the information for an input, output, or fault message: the namespace of the message, the name of the message, and the names of all parts of the message.

findInterfaceByOperation

Find an WSDL interface by one of its operation.

Syntax
<element name="findInterfaceByOperationRequest" type="tns:operationDetail" />

Auguments

An OperationDetail? object describing a certain operation.

Returns
<element name="findInterfaceByOperationResponse" type="string" />
The url of the found WSDL.

findOperationByMessagePart

Find an operation by one of its message part.

Syntax
<element name="findOperationByMessagePartRequest" type="tns:messagePartDetail" />

<complexType name="messagePartDetail">
  <sequence>
    <element name="messageNamespace" type="string"/>
    <element name="messageName" type="string"/>
   <element name="partName" type="string"/>
  </sequence>
</complexType>

Auguments
An messagePartDetail describes a message part.

Returns
<element name="findOperationByMessagePartResponse" type="tns:operationDetail" />
The found operation.

-- WeijianFang - 17 May 2005
to top


You are here: Grimoires > SoftwareReleases > GrimoiresRelease101 > FunctionalSpecification

to top

Copyright 2004 by the University of Southampton