Introduction

This document explains how to install and use GFac (Generic Application Service Factory). Gfac allows users to create Web Services by wrapping the command-line application as Web Services. Such a wrapper service is called an Application Service. Gfac provides a Web Service, called Factory Service that creates those Application Service on behalf of the user.

Diagram shows a typical installation of Gfac. Gfac includes two types of services, persistent and temporary services. Former are the services that suppose to be availible 24 * 7, and the latter are services that are created on demand, and if they are not used frequently they will shutdown themselves. Gfac installation includes two persistent services, the factory service and registry service, where former create temporary application services on demand, and latter keep the deployment (state) configuration.

User will connect to the Portlet provided by Gfac, and issue requests to add new service descriptions,create services instances or find and invoke existing service instances. A typical scenarios would be as follows

  1. User registers a new Service with Gfac via portlet, portlet registers the deployment descriptors with registry and invokes the factory service to create a new Service
  2. Factory service creates a new Application service in a given service host and registers the service with registry
  3. User shall find the running Application service and invoke the service
  4. Application Service run the wrapped application in a application host (which is typically a computing cluster), and return the results to the user

Each new Application service may be placed on a different host from Factory service and each application service may submit jobs to a remote application Host, which is usually a computing cluster. In the discussion that follows we will use following terms.

  1. Application Service - A Web service that wraps a command line application and provide a WSDL interface to the applications
  2. Service Host - host where the application service is running
  3. Application Host - Host where the command line application is installed, this could be different from service Host and jobs are submitted using Globus Gram
  4. GFAC_HOME - top directory of unzipped GFac installation

To create an application service, user needs to explain the application, the service host, and the service to application mapping using XML descriptors. However we provide a portlet Web interface that generates those XML document via a Web form. The same Web interface can register those documents with Gfac registry, therefore the process will be transparent to the end user to a great extent.

Installing GFac

GFac consists of following components and services, we will install each part in our installation. Gfac needs java JDK 1.5.

  1. XRegistry - This is registry for all deployment documents
  2. GFac Factory - This is a persistent service, and it create Application Services is user's behalf
  3. GFac portlets
  4. GFac runtime - This needs to be installed in every Service Host

To install Gfac please follow these directions carefully.

  1. Install XRegistry, please refer to Xregistry User Guide for more information. You need a MySQL data base to perform this step.
  2. Install Gridsphere portlet Containier (Recommended version is 2.2). This link might help.
  3. Service Factory Installation

    1. Download Gfac binary installation
    2. unzip Gfac binary to given location, we call this GFAC_HOME
    3. change directory to unzipped directory
    4. Run chmod 755 *.sh
    5. export GFAC_HOME=. (or equivalent if you are not using bash)
    6. factory.properties provides configurations of the factory. If you are running registry, factory and gridsphere in same machine things should work without any changes. However you can have more control by editing these properties. Look at the inline comments for details.
    7. ./factory.sh factory.properties will start a new Service Factory
    8. When a service is started, it prints service URL and WSDL, and hangs waiting for connections. When you are done using it, you can kill the service by Ctrl + C. If you want to restart gfac, just run ./factory.sh factory.properties from same directory.
  4. Installing Gfac Portlet

    1. You can find the gfac portlets inside the gfac installation, it is called smapgen.war.
    2. Portlets depends on Service Factory and registry. They must be running when you try the portlets.
    3. If you are using gridsphere 2.2, and Xregistry, factory and gridsphere are running in same machine , the war file should work out of the box. To use a other version of gridsphere, or configure gfac portlets, please refer to FAQ.
    4. Copy smapgen.war to webapps of the tomcat where gridsphere is running, and install it as a portlet. You should restart gfac and use the gridsphere admin interface to install the gfac portet.

  5. Installing Gfac Runtime on Service Hosts

    For the same host where factory is running, do the following. If you are using the Gfac remote installation. You must do this for every service host. If you are happy with a local installation, you may use localhost in place of the host Name.

    1. Download Gfac binary installation
    2. unzip Gfac binary to given location, we call this GFAC_HOME
    3. Run chmod 755 *.sh inside Gfac home
    4. Register the Host Using Gfac portlets. Pay special attention to GFAC_HOME as the Gfac path in the portlet.
      1. Click on Add new Hosts link
      2. Fill up the information, you must provide a host name (your host's real name), java 1.5 location and GFac location. GFac location must be same as GFAC_HOME. It is very important that this is correctly, this is the location of unzipped gfac distribution and if you pick it right,location will have two files run.sh and run_async.sh.
      3. Click Add Host
  6. The Installation is Complete!, Read next section how you can wrap a appilcation using gfac.

Creating a Application Service from your Command line Application

To create a new application Service, GFac require following information.

  1. Information about Host, the application will be running. As Gfac will be using Globus Tool Kit to invoke the services. So any non-standard Globus configurations need to explained.
  2. Information about the application, including executable and the name of host it it installed
  3. Information about the service you need to create out of the application, e.g. Service and the operation Name

Even though GFac expect them to be XML configuration files, We provide a portlet which would collect data from the user, create and register the configuration files in GFac Registry. Service to application mapping is defined with three deployment descriptors. You can use Gfac portlets to create them. To create a application service pleas follow steps below.

  1. Register All your application Hosts

    Decide on your application, and which host to run it. Register the application host using gfac portlets. For each Application Host, do the following. If you have already registered this host as a service host you can skip this step.

      1. Click on Add new Hosts link
      2. Fill up the information, you must provide a host name (your host's real name), java 1.5 location. If you are not using this host to run services, you may leave the Gfac location blank.
      3. Click Add Host
  2. Design your application

    You should decide how command line arguments and outputs (to Stdout or files) maps to input and output parameters of the corresponding Application Service. While invoking a Application GFac does the following.

    1. Read the parameters from SOAP messages and convert them to Gfac internal types
    2. Gfac will execute the application in temporary directory in application host, We call this $APP_DIR
    3. If inputs has file types (URI, LEADFileType), Gfac stage the those files to $APP_DIR/inputData directory, and update the parameter list to point to staged files
    4. Gfac invokes application passing the parameter list as arguments
    5. Gfac detected the output by searching stdouts for outputparameter-name=outputparameter-values pairs.

    Gfac does not support optional parameters and therefore it is not good idea to try make options input parameters. Consider for an instance you want to run a md5 checksum as the application. Recommended approach is to wrap your application with a shell script to simplify the command run on the command line. For an example following shell script wraps a md5 verification application

    				#/bin/bash
    				md5sum -c $1 > $outputData/results.txt
    				echo "md5result=$outputData/results.txt"
    			

    If you application has options you should hard code the options in wrapping shell script or pass them as parameters and convert them to options via your shell scripts. The line echo "md5result=$outputData/results.txt" is how you tell Gfac about outputs of your application. Result of your applications MUST be printed as name value pairs to stdout, where name is Output parameter name(s) of your Application service. If you have more than one parameter, you should add a a echo statement for each of them. If output is of array type it should be printed as paramname=[val1 val2 val3 ....]

    Check list

    1. Decide on application and where it should run. Install the Application and register Application host using gfac portlets
    2. Wrap the application using a shell script, use simplest form possible
    3. For every output parameter pint the name and result to stdout as name value pairs
  3. Register a New Application Service

    This step describes your application and it's mapping to a Service. This is an abstract description of the service, and you may create a concrete instance of the service using this description. Creating service instances will be explained in next section

    1. Click on Register a New Service, following screen will appear
    2. Fill up the information, you must provide a unique Service Name, and a method name. Name must not contain spaces or special characters.
    3. You must create or choose a application your service will be based on. The Application Name field list all the available applications registered so far. You could also create a new application by selecting New and fill up the application fields. Most of the time you will be creating a new application if you do not know what to do, choose New. If you choose a existing application, the Application fields will be disabled.
    4. If you choose to add a new application, you must provide a Application name, executable path and choose a host name. While providing a executable path make sure you provide a absolute path, and it is readable to the user, under who's account the factory service is running. For lead applications this is drlead. See Writing Application Description for more information. Path must not contain ~ and it Must be absolute unix path, starting with /
    5. Add inputs, provide name and choose the type of the inputs. You may add new inputs by clicking on the "AddInput" button. Most probably you will be using String, URI or URI array as the data type.
    6. Add outputs, provide name and choose the type of the outputs. You may add new outputs by clicking on the "AddInput" button. Your application must list outputs as name value pairs against names given as outputs. Unfortunately there is no way factory could check does one of them is available, as a result unless it is specified the service will fail at the execution time
    7. Click register new Service to register the service in registry
    8. If you want to lean more details read Writing a Service Map document to learn more about the values we used.
  4. Create New Service Instance

    Last section you have described the service and application to Gfac, and using these descriptions you can create a running instance of the service. Also you may, create more than one instance of the service if needed.

    1. You can create a new Service instance using existing Service service description you registered at step 3. Click on CreateService to get started
    2. Initial form let you search existing service description. To see all services click Search without filing anything
    3. Each result will have a "Create Service" button to the left. Choose the service you need and click the associate button
    4. Next window show you the service name, choose the host where you want to create the service. If you can not see the host you need to create on the list, you have not added it at the instillation. Follows directions in here to register you host. Click create Service.
    5. The portlet will contact the factory and create a service. Service creation might take some time. Please be patient
  5. Invoking a Service

    Now you have successfully created the service, and you can test it by invoking it via the portlet. This is for testing and most probably you would use the service with in a workflow.

    1. Go to Link "InvokeWS"
    2. You will see a search for running service instances, empty String will return all the running instances.
    3. Find the service you need to invoke and click invoke
    4. Click invoke, then following screen appear
    5. The next screen will present you a form to fill, which will have a input parameters for each parameter of your service.
    6. Fill in the parameters and invoke, the portlet will print the results for the service invoked.
  6. Seraching and Editing Documents

    Gfac allows users to search for documents using following interface.

    You should select document type from popup manu and provide a query strings. Empty query string will return all the results. If you are the owner of the document you will given options to edit, delete and share the documents. If you just have read permission to the document, it will be shown as readonly. However if your document is of type service map, you may copy it under different name.

    When you follow the share link, portlet will provides following screen

    You can edit the authorizations for the resource by adding or removing actors(users and groups) by selecting a actor and using movement buttons. You must click update Capability button to make your changes permanent.

  7. Supported Data Types

      Further Reading

      Last section walked you through creating a Application Service. Following are few documents that Might provide you more details

      1. If have a question, please check FAQ page first
      2. To Learn more about the format of Gfac Deployment discryptors and how to edit them at XML level, please refer to Guide to Gfac Deployment Discryptors.
      3. To Invoke a Web Service using command line or Java, please refer to Invoking a GFac Web Service.
      4. To start a applcation service standalone without using a factory service, please refer to Starting a Standalone Service.
      5. To learn aboout options supported by Gfac at different levels, please refer to Reference Manual.
      6. Schema files for Deployment Discyptors can be found here

      Copyright © 2002-2007 The Trustees of Indiana University. All rights Reserved.

      TypesDescription
      String, Integer, Float, Double, Boolean, QName Basic Data types
      StringArray, IntegerArray, FloatArray, DoubleArray, BooleanArray Basic Array Types
      URI,LEADFileID, LEADFileIDArray, URIArray File types, if you choose this types inputs will be automatically staged by Gfac and Gfac will search for output in output data directory.
      LEADNameListFileLocation of LEAD Namelist file used with this invocation.
      LEADNameListPropertiesFileUpdates to Namelist files from it's template Namelist files
      LeadCrosscutParametersUpdates to Namelist files from it's template Namelist files, in XML format
      XmlElement Xml element
      DataID, DataIDArray To use this type, DAMN service must need to be enabled. If this type is used, a Data ID is used in the place of physical name of the file.