User Guide - GShell

User Guide - GShell

Introduction

GShell is a simple client that supports some of the functionality of the Grimoires service in interactive mode or batch mode. Full Grimoires functionality may be accessed either by the Java Programming Client Side API or by the SOAP message submission facility. GShell provides a group of utilities for users to publish/inquire business/service/wsdl/metadata.

The shell environment

After the GShell is started, you will see a prompt sign ">".

Type "help", you will see a help message.

Type "ls", you will see all available commands. A command is a utility that performs a single task on the registry.

Type "run command_name" to run a command.

Type "exit" to exit the GShell.

When you see [$n]=VALUE (where n is an integer) in the output, it means the a variable, with name n, is recorded in GShell and you may reuse them by typing "$n" to denote VALUE.

A use scenario

In this scenario, we demonstrate how to publish/inquire a gcode service owned by Univ. of Southampton, and how to annotate its input message with some semantic type. The service is called "gcode" and is used to recode bioinformatic sequences using different groupings of the alphabet. We will publish a business (the UDDI terminology of an organization), publish a service belonging to the previous published business, publish a WSDL which defines the technical fingerprint of the service, and publish a metadata annotating the semantic type of an input message in the WSDL. We will also inquire all the published business/service/WSDL/metadata.

Publish a business

Publish a business called "Univ. of Southampton". A business is the UDDI's terminology for an organization. You will get a business key. On the screen, you will see:

>run PublishBusiness
==== Publish a business ====
Input the business name:
Univ. of Southampton
Input the business description:
University
Business key[$1]: ca5bdb5b-cf1c-4054-8626-65862727b9ff

NOTE:

A. the lines in bold font, e.g.,

run PublishBusiness

are typed by users.

B. $1 in "Business key[$1]" refers to a recorded variable. Later, $1 can be used to refer to the key "ca5bdb5b-cf1c-4054-8626-65862727b9ff".

Inquire a business

Inquire a business by name. On the screen, you will see:

>run InquireBusiness
==== Inquire a business ====
Input the business name:
Univ. of Southampton
==== Business No. 0 ====
Business name: Univ. of Southampton
Business description: University
Business key: ca5bdb5b-cf1c-4054-8626-65862727b9ff

Publish a service

Publish a service called "gcode". On the screen, you will see:

>run PublishService
==== Publish a service ====
Input the service name:
gcode
Input the service description:
group encoding
Input the business key:
$1
Input the service access point:
http://www.ecs.soton.ac.uk/gcode
Input the service WSDL URL:
http://www.ecs.soton.ac.uk/~wf/grimoires/wsdl/gcode.wsdl
Service key[$3]: 09017faa-0d2e-4bdd-aea3-6e76084504cf

NOTE:

A. The service access point is where the service is located.

B. The WSDL URL will be recorded in UDDI tModel, but a standard UDDI registry will not register this WSDL file.

Inquire a service

Inquire a service by name. On the screen, you will see:

>run InquireService
==== List all services ====
Input the service name:
gcode
==== Service No. 0 ====
Service name: gcode
Service key: dc64b224-02cf-44cd-92aa-0037a44d4da1
Business key: 9f6d4816-dfa4-46df-b330-c4108b361d94
Access point in binding template: http://www.ecs.soton.ac.uk/gcode
tModel: http://www.ecs.soton.ac.uk/~wf/grimoires/wsdl/gcode.wsdl

Publish WSDL

Publish a WSDL file, whose URL is http://www.ecs.soton.ac.uk/~wf/grimoires/wsdl/gcode.wsdl On the screen, you will see:

>run PublishWSDL
==== Publish a WSDL file ====
Input the WSDL URL:
http://www.ecs.soton.ac.uk/~wf/grimoires/wsdl/gcode.wsdl
WSDL key[$4]: 35708376-4092-464c-b364-80459d81400f

NOTE: this is a Grimoires' extension to the UDDI specification.

Inquire WSDL

Inquire a WSDL by its registered key. On the screen, you will see:

>run InquireWSDL
==== Inquire a WSDL file ====
Input the WSDL Key:
$4

<?xml version="1.0" encoding="UTF-8"?>
<definitions targetNamespace="http://test/gcode" xmlns:tns="http://test/gcode" x
mlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.xmlsoap.org/ws
dl/">
  <message name="response">
    <part name="recoded" type="xsd:string"/>
  </message>
  <message name="request">
    <part name="sample" type="xsd:string"/>
    <part name="groups" type="xsd:string"/>
  </message>
  <portType name="DefaultPort">
    <operation name="DefaultOperation">
      <input message="tns:request"/>
      <output message="tns:response"/>
    </operation>
  </portType>
</definitions>

Publish metadata

Publish a piece of metadata to a message part of the gcode service to describe its semantic type. On the screen, you will see:

>run PublishMetadata
What type of entity to annotate (keyedEntity, operation, or messagePart):
messagePart
==== Publish a metadata to a message part ====
Input the message namespace:
http://test/gcode
Input the message name:
request
Input the message part name:
sample
Input the type (URI) of the metadata to describe the message part:
http://www.grimoires.org/SemanticType
Input the value of the metadata to describe the message part:
nucleotide_sequence
Metadata key[$5]: 32529811-d841-45c5-bf5b-892e2815966c

In a WSDL file, a message is identified as a QName, i.e., the message namespace plus the message name. A message can consist of multiple message parts. Therefore, the triple (message namespace, message name, message part name) unambiguously identifies a message part in a WSDL file.

Inquire metadata

Inquire an entity that has the specified annotation. On the screen, you will see:

>run InquireMetadata
==== Inquire a metadata ====
Input the metadata type (URI):
http://www.grimoires.org/SemanticType
Input the metadata value:
nucleotide_sequence
==== Entity No. 0 ====
Found a message part with this metedata:
	(http://www.grimoires.org/SemanticType, nucleotide_sequence)
Message namespace: http://test/gcode
Message name: request
Message part name: sample

Send a soap message

Send a soap message to a Web Service endpoint. On the screen, you will see:

>run SendSoapMessage
==== Send a SOAP message to a Web Service endpoint ====
Input the Web Service endpoint:
http://fantasio:8080/grimoires/services/publish
Input the XML filename whose content consructs the SOAP message body:
data/save_business_1.xml

<soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><busines
sDetail xmlns="urn:uddi-org:api_v2"><businessEntity businessKey="4ba1b168-5766-4
0fd-bc6d-3be1b6047121"><name>abc business</name></businessEntity></businessDetai
l></soapenv:Body>run InquireMetadata

Run commands in a batch mode

All commands can be run in a batch mode.

E.g., after setting up the proper classpath, "java InquireBusinessCommand Grimoires_URL business_name" will inquire a business.

And "java InquireBusinessCommand" will show the usage of the command.