Functional Specification - Grimoires

Functional Specification - Grimoires

Introduction

Grimoires is a UDDIv2 compliant registry for Web Services. Grimoires itself is implemented as a Web Service. The clients interact with Grimoires through sending and receiving SOAP messages. In addition to the UDDIv2 interface, Grimoires also provides some other interfaces, such as metadata and WSDL, which allow clients to publish and inquire metadata and WSDL-related data, respectively. An access control layer within Grimoires can enforce fine-grained access control for published entities. All the data published through various interfaces are represented as RDF triples internally, which can be queried and reasoned over in a uniform way. The published data, i.e., the RDF triples, can reside in a database, a file, or simply in memory, to allow deployers to balance persistence with performance.

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.

UDDI interface

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

UDDI Version 2.04 API Specification, Dated 19 July 2002 http://uddi.org/pubs/ProgrammersAPI-V2.04-Published-20020719.htm
UDDI Version 2.03 Data Structure Reference, Dated 19 July 2002 http://uddi.org/pubs/DataStructure-V2.03-Published-20020719.htm
UDDI Schema: http://uddi.org/schema/uddi_v2.xsd
UDDI publish wsdl: http://uddi.org/wsdl/publish_v2.wsdl
UDDI inquire wsdl: http://uddi.org/wsdl/inquire_v2.wsdl

Metadata interface

Introduction

The metadata interface was designed to be integrated with the UDDI interface, so that UDDI function could be extended with minor modifications. The metadata interface allows users to annotate entities within the grimoires registry. In Grimoires release, under "wsdl/" directory, you will find the following files related to the metadata interface:

metadata.xsd: describes the general data models of the metadata interface.
metadata_wsdl.xsd: describes the WSDL specific data models.
metadata_uddi.xsd: describes the UDDI specific data models.
publish_metadata.wsdl: defines the metadata publication interface.
inquire_metadata.wsdl: defines the general metadata inquiry interface.
inquire_wsdlMetadata.wsdl: defines the WSDL specific metadata inquiry interface.
inquire_uddiMetadata.wsdl: defines the UDDI specific metadata inquiry interface.

Below xsd represents the namespace http://www.w3.org/2001/XMLSchema, meta is the namespace http://www.grimoires.org/metadata.xsd, and the default namespace is http://www.grimoires.org/metadata.xsd.

Data structures

metadata

Metadata represents the annotation that is attached to entities within Grimoires. 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:

metadataKey: unique key assigned by Grimoires when a new piece of annotation is published.
metadataType: URI representing the type of annotation.
metadataValue: the value of the annotation, which 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>

where

triples: a string representation of RDF statements.
resourceIdentifer: a resource which the "triples" element is describing.
language: the representation language used in the the "triples" element, which could be either "RDF/XML", "N-TRIPLE" or "N3".
base: the base URI to be used with the relative URIs.

metadataInfo

This is a response message from Grimoires. In addition of all the elements and attributes of MetaData, it contains information about the author 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 entities stored within Grimoires. This can be a unique key for an entity, a message part within a WSDL file, or an operation 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>

We use MessagePartReference and OperationReference to uniquely identify a message part or an operation within a WSDL file, respectively.

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.

  <xsd:element name="metadataQuery" type="meta:MetadataQuery"/> 
  <xsd:complexType name="MetadataQuery">
    <xsd:sequence>
      <xsd:element ref="meta:findQualifiers" minOccurs="0"/>
      <xsd:element ref="meta:metadataType"/>
      <xsd:element ref="meta:metadataValue"/>
      <xsd:element ref="meta:author" minOccurs="0"/>
      <xsd:element ref="meta:date" minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>

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.

addMetadataToEntity

This operation attaches a piece of metadata to an Entity.

Syntax

  <addMetadataToEntity>
    <entityReference/>
    <metadata/>
  </addMetadataToEntity>

The corresponding XML schema is:

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

Arguments

The addMetadataToEntity message contains two elements --- EntityReference and MetaData.

Returns

If the operation is successful, grimoires return a MetadataInfo message.

deleteMetadata

This operation deletes a piece of metadata.

Syntax

 <deleteMetadata>
    <metadataKey/>
    [<metadataKey/> ...]
 </deleteMetadata>

The corresponding XML schema is:

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

Arguments

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

This operation retrieves metadata attached to entities in Grimoires using the get_entityMetadata message.

Syntax

  <get_entityMetadata>
    <entityReference/>
    [<entityReference/> ...]
  </get_entityMetadata>

The corresponding XML schema is:

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

Arguments

entityReference is described in EntityReference.

Returns

On success, a metadataInfos message is returned. It is a list of zero or more MetadataInfo.

get_metadataDetail

This operation retrieves the details of a piece of metadata using its metadataKey.

Syntax

  <get_metadataDetail>
    <metadataKey/>
    [<metadataKey/> ...]
  </get_metadataDetail>

The corresponding XML schema is:

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

Arguments

metadataKey: the key of the published metadata.

Returns

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

find_entityByMetadata

This operation searches for entities containing specific pieces of metadata.

Syntax

<find_entityByMetadata>
  <metadataQueryBag>
    <metadataQuery/>
    [<metadataQuery/> ...]
  </metadataQueryBag>
</find_entityByMetadata>

Arguments

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

This section contains UDDI inquiry operations that have been extended to support metadata based searching.

find_service

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

Syntax

  <meta:find_service [businessKey="uuid_key"] [maxRows="nn"] generic="2.0" xmlns:uddi="urn:uddi-org:api_v2">
    [<meta:findQualifiers/>]
    [<uddi:name/> [<uddi:name/>]¡]
    [<uddi:categoryBag/>]
    [<uddi:tModelBag/>]
    [<meta:metadataQueryBag/>]
  </meta:find_service>

The corresponding XML schema is:

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

Arguments

Please refer to the UDDI specification for the UDDI find_service operation. metadataQueryBag is defined in MetadataQueryBag.

Returns

On success, a UDDIv2 ServiceList is returned.

WSDL specific operations

A collection of WSDL specifc operation are available at the inquire_wsdlMetadata interface. They are used to inquire over WSDL elements by metadata.

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

  <find_interfaceByMessagePartMetadata>
    <metadataQueryBag/>
    [<metadataQueryBag/> ...]
  </find_interfaceByMessagePartMetadata>

The corresponding XML schema is:

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

Arguments

metadataQueryBag is defined at MetadataQueryBag.

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

  <find_interfaceByOperationMetadata>
    <metadataQueryBag/>
    [<metadataQueryBag/> ...]
  </find_interfaceByOperationMetadata>

The corresponding XML schema is:

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

Arguments

Please refer to find_entityByMessagePartMetadata.

Returns

On success, a UriBag is returned.

WSDL interface

Introduction

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

In Grimoires release, under "wsdl/" directory, you can find the following files related to the WSDL interface:

wsdl.wsdl: defines the WSDL interface and related data models.

Below the default name space is "http://www.grimoires.org/wsdl".

Operations

addWSDLFile

This operation publishes a WSDL file to the registry.

Syntax

<addWSDLFileRequest/>

The corresponding XML schema is:

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

Arguments

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

This operation publishes a WSDL file with content to the registry.

Syntax

<addWSDLFileAdvertRequest>
  <url/>
  <content/>
</addWSDLFileAdvertRequest>

The corresponding XML schema is:

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

Arguments

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

This operation retrieves the WSDL content of the advert identified by the given key.

Syntax

<getWSDLAdvertContentRequest/>

The corresponding XML schema is:

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

Arguments

WSDL key.

Returns

<element name="getWSDLAdvertContentResponse" type="string" />

the content of WSDL file.

getWSDLAdvertContentByURL

This operation retrieves the WSDL content of the advert identified by the url of WSDL.

Syntax

<getWSDLAdvertContentByURLRequest/>

The corresponding XML schema is:

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

Arguments

The url of WSDL file.

Returns

<element name="getWSDLAdvertContentByURLResponse" type="string" />

the content of WSDL file.

removeWSDLFile

This operation deletes a WSDL file from the repository.

Syntax

<removeWSDLFileRequest/>

The corresponding XML schema is:

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

Arguments

The url of WSDL file.

Returns

<element name="removeWSDLFileResponse" type="boolean" />

True or false indicating whether the deletion operation is successful.

findServicesByInterface

This operation retrieves all UDDI services that are registered as implementing the WSDL interface at the given url.

Syntax

<findServicesByInterfaceRequest/>

The corresponding XML schema is:

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

Arguments

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

This operation retrieves the URLs of all WSDL adverts registered in Grimoires.

Syntax

<getAllWSDLFilesRequest/>

The corresponding XML schema is:

<complexType name="getAllWSDLFilesRequest"/>

Arguments

Null.

Returns

<complexType name="getAllWSDLFilesResponse">
  <sequence>
    <element maxOccurs="unbounded" minOccurs="0" name="url" type="string" />
  </sequence>
</complexType>

the urls of all registered WSDLs.

getOperationsByURL

This operation retrieves the names of all operations in a WSDL file.

Syntax

<getOperationsByURLRequest/>

The corresponding XML schema is:

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

Arguments

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

These operations retrieve the input, output, or fault message information for a certain operation, respectively.

Syntax

<getInputMessageOfOperationRequest/>
<getOutputMessageOfOperationRequest/>
<getFaultMessageOfOperationRequest/>

The corresponding XML schema is:

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

Arguments

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

This operation seraches an WSDL interface by one of its operation.

Syntax

<findInterfaceByOperationRequest/>

The corresponding XML schema is:

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

Arguments

An OperationDetail object describing a certain operation.

Returns

<element name="findInterfaceByOperationResponse" type="string" />

The url of the found WSDL.

findOperationByMessagePart

This operation searches an operation by one of its message part.

Syntax

<findOperationByMessagePartRequest>
  <messageNamespace/>
  <messageName/>
  <partName/>
</findOperationByMessagePartRequest>

The corresponding XML schema is:

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

Arguments

An messagePartDetail describes a message part.

Returns

<element name="findOperationByMessagePartResponse" type="tns:operationDetail" />

The found operation.