.. _services-howtos:

How To Setup ZOO Services
=========================

:Authors: Nicolas Bozon, Gérald Fenoy, Jeff McKenna
:Last Updated: $Date: 2013-03-26 16:10:36 +0000 (Tue, 26 Mar 2013) $

ZOO Services are quite easy to create once you have installed the ZOO Kernel and have 
chosen code (in the language of your choice) to turn into a ZOO service. Here are some 
HelloWorlds in Python, PHP, Java  and JavaScript with links to their corresponding 
``.zcfg`` files.

.. contents:: Table of Contents
    :depth: 3
    :backlinks: top

Python
------

You'll find here information needed to deploy your own Python Services Provider.

Python ZCFG requirements
************************

.. Note:: For each Service provided by your ZOO Python Services Provider, the ZCFG File 
          must be named the same as the Python module function name (also the case of
          characters is important).

The ZCFG file should contain the following :


serviceType
    Python 
serviceProvider
    The name of the Python module to use as a ZOO Service Provider. For instance, if your 
    script, located in the same directory as your ZOO Kernel, was named ``my_module.py`` then 
    you should use ``my_module`` (the Python module name) for the serviceProvider value in ZCFG file. 

Python Data Structure used
**************************

The Python module's function to be used take three arguments: the main configuration, inputs and outputs.
All this values are passed to the Python module as dictionaries.

Following you'll find an example for each parameters

Main configuration
^^^^^^^^^^^^^^^^^^^^^
Main configuration contains several informations, some of them are really useful to develop your service.
Following an example ::

  {
  'main': {'lang': 'en-UK',
	   'language': 'en-US',
	   'encoding': 'utf-8',
	   'dataPath': '/var/www/tmp',
	   'tmpPath': '/var/www/tmp',
	   'version': '1.0.0',
	   'mapserverAddress': 'http://localhost/cgi-bin/mapserv',
	   'isSoap': 'false',
	   'tmpUrl': 'http://localhost/tmp/',
	   'serverAddress': 'http://localhost/zoo'
	  },
  'identification': {'keywords': 'WPS,GIS',
		     'abstract': 'WPS services for testing ZOO',
		     'fees': 'None',
		     'accessConstraints': 'none',
		     'title': 'testing services'
		    },
  'lenv': {'status': '0',
	   'soap': 'false',
	   'cwd': '/usr/lib/cgi-bin',
	   'sid': '24709'
	  },
  'env': {'DISPLAY': 'localhost:0'},
  'provider': {'addressCountry': 'it',
	       'positionName': 'Developer',
	       'providerName': 'Name of provider',
	       'addressAdministrativeArea': 'False',
	       'phoneVoice': 'False',
	       'addressCity': 'City',
	       'providerSite': 'http://www.your.site',
	       'addressPostalCode': '38122',
	       'role': 'Developer',
	       'addressDeliveryPoint': 'False',
	       'phoneFacsimile': 'False', 
	       'addressElectronicMailAddress': 'your@email.com',
	       'individualName': 'Your Name'
	      }
  }

Inputs
^^^^^^^^^^^^
The inputs are somethings like this ::

  {
  'variable_name': {'minOccurs': '1',
		    'DataType': 'string',
		    'value': 'this_is_the_value',
		    'maxOccurs': '1',
		    'inRequest': 'true'
		   }
  }

The access to the value you have to require for the ``value`` parameter, something like this ::

  yourVariable = inputs['variable_name']['value']

Outputs
^^^^^^^^^^^^^
The outputs data as a structure really similar to the inputs one ::

  {
  'result': {'DataType': 'string',
	     'inRequest': 'true',
	    }
  }

There is no ``'value'`` parameter before you assign it ::

  inputs['result']['value'] = yourOutputDataVariable

The return statement has to be an integer: corresponding to the service status code.

The module should **return 3 if the process successfully ended otherwise it should return 4**.
To add a message for the wrong result you can add the massage to ``conf["lenv"]["message"]``,
for example:

.. code-block:: python

  conf["lenv"]["message"] = 'Your module return an error'

Sample ZOO Python Services Provider
***********************************

The following code represents a simple ZOO Python Services Provider which provides only one 
Service, the HelloPy one.

.. code-block:: python

  import sys
  def HelloPy(conf,inputs,outputs):
     outputs["Result"]["value"]="Hello "+inputs["a"]["value"]+" from Python World !"
     return 3

PHP
---

.. code-block:: php

  <?
  function HelloPHP(&$main_conf,&$inputs,&$outputs){
     $outputs["Result"]["value"]="Hello ".$inputs[S][value]." from PHP world !";
     return 3;
  }
  ?>

Java
----

.. code-block:: java

  import java.util.*;
  public class HelloJava {
    public static int HelloWorldJava(HashMap conf,HashMap inputs, HashMap outputs) {
       HashMap hm1 = new HashMap();
       hm1.put("dataType","string");
       HashMap tmp=(HashMap)(inputs.get("S"));
       java.lang.String v=tmp.get("value").toString();
       hm1.put("value","Hello "+v+" from JAVA WOrld !");
       outputs.put("Result",hm1);
       System.err.println("Hello from JAVA WOrld !");
       return 3;
    }
  }

Javascript
----------

.. code-block:: javascript

  function hellojs(conf,inputs,outputs){
     outputs=new Array();
     outputs={};
     outputs["result"]["value"]="Hello "+inputs["S"]["value"]+" from JS World !";
     return Array(3,outputs);
  }