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.
This tutorial demonstrates three ways to use GShell to publish and discover a service to a Grimoires registry:
Please refer to the GShell installation guide on how to compile and run GShell. And please refer to the GShell user guide on its general usage.
Following the same scenario as in the Grimoires service tutorial, we show how to 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. We assume the BLAST service is deploy at http://xml.nig.ac.jp/xddbj/Blast.
In this tutorial, 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.
In GShell, run the PublishBusiness command to publish a business called "DDBJ", which stands for "DNA Data Bank of Japan". A business is the UDDI's terminology for an organization. You will get a business key. On the screen, you will see (The lines in bold font are what you type):
>run PublishBusiness ==== Publish a business ==== Input the business name: DDBJ Input the business description: DNA Data Bank of Japan Business key[$0]: 7cb387a9-88fd-4c7a-820f-ce63c2145133
>run PublishService ==== Publish a service ==== Input the service name: Blast Input the service description: A DDBJ Web Service Input the business key: $0 Input the service access point: http://xml.nig.ac.jp/xddbj/Blast Input the service WSDL URL: http://xml.nig.ac.jp/wsdl/Blast.wsdl Service key[$1]: 12aef140-1227-4762-8bd1-85a9c3af1051
In GShell, run the InquireService command to inquire a service called "Blast". You will get the service information.
>run InquireService ==== List all services ==== Input the service name: Blast Service name: Blast Service key: 12aef140-1227-4762-8bd1-85a9c3af1051 Business key: 7cb387a9-88fd-4c7a-820f-ce63c2145133 Service description: A DDBJ Web Service Access point in binding template: http://xml.nig.ac.jp/xddbj/Blast tModel: http://xml.nig.ac.jp/wsdl/Blast.wsdl
In GShell, run the PublishWSDL command to publish the WSDL file of the Blast service, which is located at http://xml.nig.ac.jp/wsdl/Blast.wsdl. You will get the WSDL key.
>run PublishWSDL ==== Publish a WSDL file ==== Input the WSDL URL: http://xml.nig.ac.jp/wsdl/Blast.wsdl WSDL key[$0]: 50999bee-a167-4380-9420-8ee12e7b178e
In GShell, run the PublishMetadata command to publish a piece of metadata, which describes the semantic type of a message part in the previously published WSDL file. The message part is syntactically a string, and is semantically a DNA sequence. You will get the metadata key.
>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://www.themindelectric.com/wsdl/Blast/ Input the message name: searchParam0In Input the message part name: param Input the type (URI) of the metadata to describe the message part: http://www.grimoires.org/SemanticType Input the metadata to describe the semantic type of the message part: DNA_Sequence Metadata key[$1]: 9e060eca-7642-4317-af6c-c203d292d86c
In GShell, run the InquireMetadata command to discover a message part annotated with the specified metadata. You will get the message part detail.
>run InquireMetadata ==== Inquire a metadata ==== Input the metadata: DNA_Sequence Found a message part with this metedata: (http://www.grimoires.org/SemanticType, DNA_Sequence) Message namespace: http://www.themindelectric.com/wsdl/Blast/ Message name: searchParam0In Message part name: param
Run uk.ac.soton.ecs.grimoires.shell.PublishBusinessCommand to publish a business entity called "DDBJ".
java uk.ac.soton.ecs.grimoires.shell.PublishBusinessCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires DDBJ "DNA Data Bank of Japan"
Its usage is:
java uk.ac.soton.ecs.grimoires.shell.PubishBusinessCommand Grimoires_URL business_name business_description
It returns a business key.
Business key[$0]: 8409b2d1-cc13-457e-89cf-340ee4b9ce7d
Run uk.ac.soton.ecs.grimoires.shell.PublishServiceCommand to publish a business service called "Blast".
java uk.ac.soton.ecs.grimoires.shell.PublishServiceCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires Blast "A DDBJWeb Service" 8409b2d1-cc13-457e-89cf-340ee4b9ce7d http://xml.nig.ac.jp/xddbj/Blast http://xml.nig.ac.jp/wsdl/Blast.wsdl
Its usage is:
java uk.ac.soton.ecs.grimoires.shell.PublishServiceCommand Grimoires_URL name description business_key access_point WSDL_URL
It returns a service key.
Service key[$0]: c33601a4-ed9f-4ed3-b335-a767c188b76c
Run uk.ac.soton.ecs.grimoires.shell.InquireServiceCommand to discover a business service called "Blast".
java uk.ac.soton.ecs.grimoires.shell.InquireServiceCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires Blast
Its usage is:
java uk.ac.soton.ecs.grimoires.shell.InquireServiceCommand Grimoires_URL service_name
It returns the service information.
Service name: Blast Service key: c33601a4-ed9f-4ed3-b335-a767c188b76c Business key: 8409b2d1-cc13-457e-89cf-340ee4b9ce7d Service description: A DDBJWeb Service Access point in binding template: http://xml.nig.ac.jp/xddbj/Blast tModel: http://xml.nig.ac.jp/wsdl/Blast.wsdl
Run uk.ac.soton.ecs.grimoires.shell.PublishWSDLCommand to publish the WSDL file of the Blast service, which is located at http://xml.nig.ac.jp/wsdl/Blast.wsdl.
java uk.ac.soton.ecs.grimoires.shell.PublishWSDLCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires http://xml.nig.ac.jp/wsdl/Blast.wsdl
Its usage is:
java uk.ac.soton.ecs.grimoires.shell.PublishWSDLCommand Grimoires_URL WSDL_URL
It returns the WSDL key.
WSDL key[$0]: 50999bee-a167-4380-9420-8ee12e7b178e
Run uk.ac.soton.ecs.grimoires.shell.PublishMetadataCommand to publish a piece of metadata, which describes the semantic type of a message part in the previously published WSDL file. The message part is syntactically a string, and is semantically a DNA sequence.
java uk.ac.soton.ecs.grimoires.shell.PublishMetadataCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires -m http://www.themindelectric.com/wsdl/Blast/ searchParam0In param http://www.grimoires.org/SemanticType DNA_Sequence
Its usage is:
java uk.ac.soton.ecs.grimoires.shell.PublishMetadataCommand Grimoires_URL -m message_namespace message_name message_part_name metadataType metadataValue
You will get the metadata key.
Metadata key[$0]: 9e060eca-7642-4317-af6c-c203d292d86c
Run uk.ac.soton.ecs.grimoires.shell.InquireMetadataCommand to discover a message part annotated with the specified metadata.
java uk.ac.soton.ecs.grimoires.shell.InquireMetadataCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires http://www.grimoires.org/SemanticType DNA_Sequence
Its usage is:
java uk.ac.soton.ecs.grimoires.shell.InquireMetadataCommand Grimoires_URL metadataType metadataValue
You will get the message part detail.
Found a message part with this metedata: (http://www.grimoires.org/SemanticType, DNA_Sequence) Message namespace: http://www.themindelectric.com/wsdl/Blast/ Message name: searchParam0In Message part name: param
GShell provides a SendSoapMessage command, which is able to send a request soap message to the Grimoires registry, and to get the corresponding response soap message. By sending and receiving soap messages, we can invoke Grimoires service.
As same as the other commands, the SendSoapMessage command can also be run either in an interactive mode or in a batch mode.
It is assumed that Grimoires is deployed at http://fantasio.ecs.soton.ac.uk:8080/grimoires.
Prepare a "tutorial_save_business.xml" file under the "GShell/data" directory, which has the following content:
<save_business xmlns="urn:uddi-org:api_v2"> <authInfo>AUTHINFO</authInfo> <businessEntity> <name>DDBJ</name> <description>DNA Data Bank of Japan</description> </businessEntity> </save_business>
In GShell, run the SendSoapMessage command:
>run SendSoapMessage ==== Send a SOAP message to a Web Service endpoint ==== Input the Web Service endpoint: http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/publish Input the XML filename whose content constructs the SOAP message body: data/tutorial_save_business.xml <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><busines sDetail xmlns="urn:uddi-org:api_v2"><businessEntity businessKey="e9aa95e8-adbd-4 631-8f5a-f91540b2b57d"><name>DDBJ</name><description>DNA Data Bank of Japan</des cription></businessEntity></businessDetail></soapenv:Body>
In the replied soap message, we can see that the published business is assigned a business key "e9aa95e8-adbd-4631-8f5a-f91540b2b57d".
To run the SendSoapMessage command in a batch mode:
java uk.ac.soton.ecs.grimoires.shell.SendSoapMessageCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/publish
data/tutorial_save_business.xml
Its usage is:
java uk.ac.soton.ecs.grimoires.shell.SendSoapMessageCommand endpoint xmlfile
Prepare a "tutorial_save_service.xml" file under the "GShell/data" directory, which has the following content:
<save_service generic="2.0" xmlns="urn:uddi-org:api_v2"> <authInfo>AUTHINFO</authInfo> <businessService businessKey="e9aa95e8-adbd-4631-8f5a-f91540b2b57d"> <name>Blast</name> <description>A DDBJ Web Service</description> <bindingTemplates> <bindingTemplate> <accessPoint>http://xml.nig.ac.jp/xddbj/Blast</accessPoint> <tModelInstanceDetails> <tModelInstanceInfo> <instanceDetails> <overviewDoc> <overviewURL>http://xml.nig.ac.jp/wsdl/Blast.wsdl</overviewURL> </overviewDoc> </instanceDetails> </tModelInstanceInfo> </tModelInstanceDetails> </bindingTemplate> </bindingTemplates> </businessService> </save_service>
Make sure the business key is the value returned in the response soap message when publishing the business previously.
In GShell, run the SendSoapMessage command:
>run SendSoapMessage ==== Send a SOAP message to a Web Service endpoint ==== Input the Web Service endpoint: http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/publish Input the XML filename whose content constructs the SOAP message body: data/tutorial_save_service.xml <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><servic Detail xmlns="urn:uddi-org:api_v2"><businessService businessKey="e9aa95e8-adbd- 631-8f5a-f91540b2b57d" serviceKey="ad64d00a-e4aa-4f56-bad0-d9ae52709620"><name> last</name><description>A DDBJ Web Service</description><bindingTemplates><bind ngTemplate bindingKey="b6f62ea6-66ce-4fc7-9523-597a0473157b" serviceKey="ad64d0 a-e4aa-4f56-bad0-d9ae52709620"><accessPoint>http://xml.nig.ac.jp/xddbj/Blast</a cessPoint><hostingRedirector xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/X LSchema-instance"/><tModelInstanceDetails><tModelInstanceInfo><instanceDetails> overviewDoc><overviewURL>http://xml.nig.ac.jp/wsdl/Blast.wsdl</overviewURL></ov rviewDoc></instanceDetails></tModelInstanceInfo></tModelInstanceDetails></bindi gTemplate></bindingTemplates></businessService></serviceDetail></soapenv:Body>
The replied soap message contains the detail of the saved service.
To run the SendSoapMessage command in a batch mode:
java uk.ac.soton.ecs.grimoires.shell.SendSoapMessageCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/publish
data/tutorial_save_service.xml
Prepare a "tutorial_find_service.xml" file under the "GShell/data" directory, which has the following content:
<find_service generic="2.0" maxRows="100" xmlns="urn:uddi-org:api_v2"> <name>Blast</name> </find_service>
In GShell, run the SendSoapMessage command:
>run SendSoapMessage ==== Send a SOAP message to a Web Service endpoint ==== Input the Web Service endpoint: http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/inquire Input the XML filename whose content constructs the SOAP message body: data/tutorial_find_service.xml <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><service List xmlns="urn:uddi-org:api_v2"><serviceInfos><serviceInfo businessKey="e9aa95e 8-adbd-4631-8f5a-f91540b2b57d" serviceKey="ad64d00a-e4aa-4f56-bad0-d9ae52709620" ><name>Blast</name></serviceInfo></serviceInfos></serviceList></soapenv:Body>
The replied soap message contains the key of the service whose name is "Blast".
Prepare a "tutorial_get_servicedetail.xml" file under the "GShell/data" directory, which has the following content:
<get_serviceDetail generic="2.0" xmlns="urn:uddi-org:api_v2"> <serviceKey>ad64d00a-e4aa-4f56-bad0-d9ae52709620</serviceKey> </get_serviceDetail>
Make sure the service key is the key returned in the replied soap message when finding service.
In GShell, run the SendSoapMessage command:
>run SendSoapMessage ==== Send a SOAP message to a Web Service endpoint ==== Input the Web Service endpoint: http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/inquire Input the XML filename whose content constructs the SOAP message body: data/tutorial_get_servicedetail.xml <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><service Detail xmlns="urn:uddi-org:api_v2"><businessService businessKey="e9aa95e8-adbd-4 631-8f5a-f91540b2b57d" serviceKey="ad64d00a-e4aa-4f56-bad0-d9ae52709620"><name>B last</name><description>A DDBJ Web Service</description><bindingTemplates><bindi ngTemplate bindingKey="b6f62ea6-66ce-4fc7-9523-597a0473157b" serviceKey="ad64d00 a-e4aa-4f56-bad0-d9ae52709620"><accessPoint>http://xml.nig.ac.jp/xddbj/Blast</ac cessPoint><hostingRedirector xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XM LSchema-instance"/><tModelInstanceDetails><tModelInstanceInfo><instanceDetails>< overviewDoc><overviewURL>http://xml.nig.ac.jp/wsdl/Blast.wsdl</overviewURL></ove rviewDoc></instanceDetails></tModelInstanceInfo></tModelInstanceDetails></bindin gTemplate></bindingTemplates></businessService></serviceDetail></soapenv:Body>
The replied soap message contains the service detail.
To run the SendSoapMessage command in a batch mode:
java uk.ac.soton.ecs.grimoires.shell.SendSoapMessageCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/inquire data/tutorial_find_service.xml java uk.ac.soton.ecs.grimoires.shell.SendSoapMessageCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/inquire data/tutorial_get_servicedetail.xml
Prepare a "tutorial_publish_wsdl.xml" file under the "GShell/data" directory, which has the following content:
<addWSDLFileRequest xmlns="http:/www.grimoires.org/wsdl/type"> http://xml.nig.ac.jp/wsdl/Blast.wsdl </addWSDLFileRequest>
In GShell, run the SendSoapMessage command:
>run SendSoapMessage ==== Send a SOAP message to a Web Service endpoint ==== Input the Web Service endpoint: http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/wsdl Input the XML filename whose content constructs the SOAP message body: data/tutorial_publish_wsdl.xml <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><addWSDL FileResponse xmlns="http:/www.grimoires.org/wsdl/type">4abf8f73-2da1-4a05-ae50-b 1701ab16eac</addWSDLFileResponse></soapenv:Body>
In the replied soap message, we can see that the published WSDL is assigned a WSDL key "4abf8f73-2da1-4a05-ae50-b1701ab16eac".
To run the SendSoapMessage command in a batch mode:
java uk.ac.soton.ecs.grimoires.shell.SendSoapMessageCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/wsdl
data/tutorial_publish_wsdl.xml
Prepare a "tutorial_attach_metadata.xml" file under the "GShell/data" directory, which has the following content:
<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>
Make sure the business key is the value returned in the response soap message when publishing the business previously.
In GShell, run the SendSoapMessage command:
>run SendSoapMessage ==== Send a SOAP message to a Web Service endpoint ==== Input the Web Service endpoint: http://fantasio:8080/grimoires/services/publish_metadata Input the XML filename whose content constructs the SOAP message body: data/tutorial_attach_metadata.xml <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><metadat aInfo ns1:metadataKey="dbbbcc88-e14d-45b0-8740-79bec8a3a73e" xmlns="http://www.g rimoires.org/metadata.xsd" xmlns:ns1="http://www.grimoires.org/metadata.xsd"><me tadataType>http://www.grimoires.org/SemanticType</metadataType><metadataValue><s tringValue>DNA_Sequence</stringValue></metadataValue><date>Wed Sep 07 11:49:16 B ST 2005</date></metadataInfo></soapenv:Body>
The replied soap message contains the detail of the metadata.
To run the SendSoapMessage command in a batch mode:
java uk.ac.soton.ecs.grimoires.shell.SendSoapMessageCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/publish_metadata
data/tutorial_attach_metadata.xml
Prepare a "tutorial_inquire_metadata.xml" file under the "GShell/data" directory, which has the following content:
<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>
In GShell, run the SendSoapMessage command:
>run SendSoapMessage ==== Send a SOAP message to a Web Service endpoint ==== Input the Web Service endpoint: http://fantasio:8080/grimoires/services/inquire_metadata Input the XML filename whose content constructs the SOAP message body: data/tutorial_inquire_metadata.xml <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><entityR eferenceList xmlns="http://www.grimoires.org/metadata.xsd"><entityReference enti tyType="http://www.grimoires.org/metadata.xsd#messagePartReference"><messagePart Reference><messageNamespace>http://www.themindelectric.com/wsdl/Blast/</messageN amespace><messageName>searchParam0In</messageName><messagePartName>param</messag ePartName></messagePartReference></entityReference><entityReference entityType=" http://www.grimoires.org/metadata.xsd#messagePartReference"><messagePartReferenc e><messageNamespace>http://www.themindelectric.com/wsdl/Blast/</messageNamespace ><messageName>searchParam0In</messageName><messagePartName>param</messagePartNam e></messagePartReference></entityReference></entityReferenceList></soapenv:Body>
The replied soap message contains the detailed information of the message part attached with the metadata.
To run the SendSoapMessage command in a batch mode:
java uk.ac.soton.ecs.grimoires.shell.SendSoapMessageCommand http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/inquire_metadata
data/tutorial_inquire_metadata.xml