Generic Factory Service - Developer's Guide

Overview

This Developer's Guide is aimed at service provider's, that is, users of the Generic Factory Service who wish to provide a Grid Service access to their applications. This document will show you how to create a ServiceMap Document, either from an XML file or from a plain text ServiceMap file. You will then learn how to create a service with the ServiceMap Document and also how to access (test) your service.

Creating a ServiceMap Document

In order to create a service you must supply the Generic Factory Service with a description of your service and how to invoke it. In general, this description needs to include

The executable to be invoked, and
Any command line parameters that need to be passed to the executable.

For the Generic Factory Service, this description is an XML file called a ServiceMap Document. An example of a ServiceMap Document follows:

<ServiceMap xmlns="http://www.extreme.indiana.edu/namespaces/2004/01/GFac">
  <service>
    <serviceName>DummyService13</serviceName>
    <serviceDescription>This is a dummy service</serviceDescription>
  </service>
  <portType>
    <method>
      <methodName>Touch</methodName>
      <methodDescription>This method creates an empty file</methodDescription>
      <executable>/bin/touch1</executable>
      <inputParameters>
        <parameterName>Filename</parameterName>
        <parameterDescription>The name of the file to create</parameterDescription>   
      </inputParameters>
    </method>
    <method>
      <methodName>TraceRoute</methodName>
      <methodDescription>Traces the route to a host</methodDescription>
      <executable>/usr/sbin/traceroute</executable>
      <inputParameters>
        <parameterName>Hostname</parameterName>
        <parameterDescription>This is the destination host</parameterDescription>
      </inputParameters>
     </method>
  </portType>
  <creationParameters>
    <host>localhost</host>
    <port>0</port>
  </creationParameters>
</ServiceMap>

As can be seen, the ServiceMap Document has the root element of <ServiceMap>. The <ServiceMap> element must contain a <service> element and a <portType> element. The <service> element provides the name (via the <serviceName> sub element) of the service and optionally a description (via the <serviceDescription> sub element) of the service. The <portType> element contains one or more <method> elements. The <method> elements map a service's method name to a particular executable invocation. The <method> elements provides the method's name (via the <methodName> sub element), optionally the method's description (via the <methodDescription> sub element), the command line executable to be invoked (via the <executable> sub element), and zero or more command line parameters (via the <inputParameters> sub element(s)). Optionally, a <ServiceMap> element may contain a <creationParameters> sub element which specifies where this service may be created, by specifying the host and port via the <host> and <port> sub elements, respectively.

Creating a ServiceMap Document from a ServiceMap file

Another option for creating a ServiceMap Document is to create it from a plain text file called a ServiceMap file. The Generic Factory Service comes with a utility for generating a ServiceMap Document from a simple plain text description of the service. A ServiceMap file looks like:

# This is a comment
method Touch executable /bin/touch inputParameterNames Filename
method Traceroute executable /usr/sbin/traceroute inputParameterNames Hostname

A ServiceMap file has the following format. Each line contains a method. The first token on each line is the word method. The second token is the name of the method. The third token is the word executable. The fourth token is the path to the executable. The fifth token is the word inputParameterNames. The sixth and onwards tokens are parameter names.

To create a ServiceMap Document from a ServiceMap file, use the provided run.sh script as follows:

./run.sh util   --serviceName <service name for the new service> \
                --mapFile <path to the service-map file> \
                --docFile <path to the service-map document file>

For example,

./run.sh util   --serviceName MyNewService1 \
                --mapFile doc/ServiceMapDocument.txt \
                --docFile doc/ServiceMapDocument.xml

Note that the name of the service is not specified in the ServiceMap file, but is specified when you create a ServiceMap Document from a ServiceMap file.

Creating a New Service

Now that you have created a ServiceMap Document, you can now create a service with it by passing it to the Generic Service Factory. To do so, use the provided run.sh script as follows:

./run.sh client --serviceUrl <url of the "Generic Factory"> \
                --doc <path to the service-map document>

For example,

./run.sh client --serviceUrl http://localhost:1234 \
                --doc doc/ServiceMapDocument.xml

This will return the WSDL for the application factory that you just created.

Accessing a Service

After creating a new service, you can now access it with the same run.sh script. You'll need to specify the URL where the service is running, the name of the method you wish to invoke, and the input parameters to the method. Please note that the service URL is specified in the WSDL that was returned when creating the service. To access the service, run the following:

./run.sh client --serviceUrl <url of the newly created service> \
                --methodName <method name to access> \
                --params <parameters to pass to the method>

For example,

./run.sh client --serviceUrl http://localhost:56476 \
                --methodName touch \
                --params /tmp/sometestfile

This will return a SOAP message telling you whether the request was successful or not. Please note that the application factory will merely launch the application and does not provide information on its status while executing or upon completion. Thus, a successful request does not indicate that the application finished successfully, only that it was successfully launched.

Creating and Accessing a Service through the GFac Servlet

The above steps on creating and accessing a service from the command line can also be done from a web browser through the GFac Servlet. Simply point your browser at the servlet (e.g., http://my.tomcat.com/GFac/GFacServlet) and follow the instructions given.