Functional Specification - GShell

Product description

The Grimoires Shell (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 shell environment to interact with Grimoires service, within which a group of commands can be invoked for users to publish/inquire business/service/wsdl/metadata.

There are two ways to use GShell:

• Through the shell environment. In the shell, the following built-in utilities are available:
  • help: display a help message.
  • ls: list all available commands. A command performs a single task on the registry, e.g., publishing a service.
  • run command_name: invoke a command. Each command has an interactive wizard to direct user to finish the task.
  • exit: exit GShell.

  GShell also provides the facility of "environment variables". 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.

   

•  Invoke the commands directly. Each command is implemented as a Java class with a public main method. It can be invoked directly without using GShell. So all commands can be used in a batch mode.

Use case

In this use case, a user publish a "gcode" service owned by Univ. of Southampton, and annotate its input message that is a string syntactically, with a semantic type "nucleotide_sequence". "gcode" is used in bioinformatics to "group encoding" sequences, e.g., a nucleotide sequence.

Firstly, the user publish a business (the UDDI terminology of an organization) called "Univ. of Southamtpon", then publish a service belonging to the previous published business. The user will also 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.

Now the user can inquire all the published business/service/WSDL/metadata.

List of commands

There are two modes to invoke a command: an interactive mode and a batch mode. An interactive mode is used when invoking commands in the GShell environment. A batch mode is used when invoking commands directly.

Publish a business

Publish a business. A business is the UDDI's terminology for an organization.

Arguments

The business name.

The business description.

Returns

The business key, which is the unique identifier of the published business.

Batch mode usage

java PubishBusinessCommand Grimoires_URL business_name business_description

Grimoires_URL is where Grimoires is deployed. For instance, if the Grimoires UDDIv2 publish service is deployed at http://hostname:18080/grimoires/services/publish, then Grimoires_URL is http://hostname:18080/grimoires/services.

Inquire business by name

Inquire business by name.

Arguments

The business name.

Returns

The name, description, and keys of all businesses whose names match.

Batch mode usage

java InquireBusinessCommand Grimoires_URL business_name

Publish a service

Publish a service.

Arguments

The service name.

The service description.

The business key: specify which business this service belongs to.

The service access point: where the service is located.

The service WSDL URL.

Returns

The service key, which is the unique identifier of the published service.

Batch mode usage

java PublishServiceCommand Grimoires_URL name description business_key access_point WSDL_URL

Inquire a service

Inquire a service by name.

Arguments

The service name.

Returns

The service name.

The service key.

The business key of the business that this service belongs to.

The service access point.

The WSDL URL.

Batch mode usage

java InquireServiceCommand Grimoires_URL service_name

Publish WSDL

Publish a WSDL file.

Arguments

The WSDL URL.

Returns

The WSDL key, which is the unique identifier of the published WSDL.

Batch mode usage

java PublishWSDLCommand Grimoires_URL WSDL_URL

Inquire WSDL

Inquire a WSDL by its registered key.

Arguments

The WSDL key.

Returns

The WSDL content.

Batch mode usage

java InquireWSDLCommand Grimoires_URL wsdlKey

Publish metadata

Publish a piece of metadata to a message part, an operation, or a UDDI entity.

Arguments

To annotate a message part, the message namespace, the message name, and the message name part, are required.

To annotate an operation, the porttype namespace, the porttype name, and the operation name, are required.

To annotate a UDDI entity, the entity key, and the key type, e.g., a business key or a service key, are required.

The metadata type that must be a URI and metadata value that can be either a URI or a string, are required in all cases.

Returns

The metadata key.

Batch mode usage

java PublishMetadataCommand Grimoires_URL -m message_namespace message_name message_part_name metadata_type metadata_value

or

java PublishMetadataCommand Grimoires_URL -o porttype_namespace porttype_name operation_name metadata_type metadata_value

or

java PublishMetadataCommand Grimoires_URL -k [business|service] key metadata_type metadata_value

Inquire metadata

Inquire an entity that has the specified annotation.

Arguments

The metadata type and the metadata value.

Returns

The detailed information of the entities that have been attached with this metadata.

Batch mode usage

java InquireMetadataCommand Grimoires_URL metadataType metadataValue

List all services

List all services published in the registry.

Arguments

Null.

Returns

The detailed information of all services, including the service name, the service key, the business key of the business that this service belongs to, the service access point, and the WSDL URL.

Batch mode usage

java ListAllServicesCommand Grimoires_URL

Delete an entity

Delete an entity, which can be a UDDI service, a UDDI business, a metadata, or a WSDL description.

Arguments

The entity key.

The entity type: one of business, service, metadata or wsdl.

Returns

Null.

Batch mode usage

java DeleteEntityCommand Grimoires_URL key type

Get the metadata attached to an entity

Get the metadata attached to an entity.

Arguments

The entity key.

The entity type: either business or service.

Returns

The detailed information of the metadata that have been attached with this entity, including the metadata key, the metadata type, and the metadata value.

Batch mode usage

java GetEntityMetadataCommand Grimoires_URL key type

Send a soap message

Send a soap message to a Web Service endpoint.

Arguments

The target Web Service endpoint. E.g., a Grimoires UDDIv2 publish WS endpoint could be http://fantasio.ecs.soton.ac.uk:8080/grimoires/services/publish.

The XML filename whose content constructs the SOAP message body.

Returns

The response SOAP message.

Batch mode usage

java SendSoapMessageCommand endpoint filename

Delete an entity

Delete an entity. An entity can be a business, a service, a metadata, or a WSDL.

Arguments

The entity type (business, service, metadata, or wsdl).

The entity key or the URL when the entity is a WSDL.

Returns

Batch mode usage

java DeleteEntityCommand Grimoires_URL entity_type entity_key