source: trunk/docs/services/howtos.txt @ 587

Last change on this file since 587 was 586, checked in by djay, 10 years ago

Add the PHP ZOO-API, fix issue if ZTS is not defined, correct loading of the PHP script depending of the ZOO-Kernel location, use a ZEND_HANDLE_FD rather than the ZEND_HANDLE_FP used before, correct location of the hello.php service.

  • Property svn:eol-style set to native
  • Property svn:keywords set to HeadURL Date Author Id Rev
  • Property svn:mime-type set to text/plain
File size: 8.8 KB
Line 
1.. _services-howtos:
2
3How To Setup ZOO Services
4=========================
5
6:Authors: Nicolas Bozon, Gérald Fenoy, Jeff McKenna, Luca Delucchi
7:Last Updated: $Date: 2015-02-16 21:45:52 +0000 (Mon, 16 Feb 2015) $
8
9ZOO Services are quite easy to create once you have installed the ZOO Kernel and have
10chosen code (in the language of your choice) to turn into a ZOO service. Here are some
11HelloWorlds in Python, PHP, Java  and JavaScript with links to their corresponding
12``.zcfg`` files.
13
14.. contents:: Table of Contents
15    :depth: 3
16    :backlinks: top
17
18Common informations
19----------------------
20
21The function of the process for each programming language take three arguments: the main
22configuration, inputs and outputs.
23
24.. Note:: The service has to **return 3 if the process run successfully instead it
25          return 4** if the process end with an error.
26
27Python
28------
29
30You'll find here information needed to deploy your own Python Services Provider.
31
32Python ZCFG requirements
33************************
34
35.. Note:: For each Service provided by your ZOO Python Services Provider, the ZCFG File
36          must be named the same as the Python module function name (also the case of
37          characters is important).
38
39The ZCFG file should contain the following :
40
41
42serviceType
43    Python
44serviceProvider
45    The name of the Python module to use as a ZOO Service Provider. For instance, if your
46    script, located in the same directory as your ZOO Kernel, was named ``my_module.py`` then
47    you should use ``my_module`` (the Python module name) for the serviceProvider value in ZCFG file.
48
49Python Data Structure used
50**************************
51The three parameters of the function are passed to the Python module as dictionaries.
52
53Following you'll find an example for each parameters
54
55Main configuration
56^^^^^^^^^^^^^^^^^^^^^
57Main configuration contains several informations, some of them are really useful to develop your service.
58Following an example ::
59
60  {
61  'main': {'lang': 'en-UK',
62           'language': 'en-US',
63           'encoding': 'utf-8',
64           'dataPath': '/var/www/tmp',
65           'tmpPath': '/var/www/tmp',
66           'version': '1.0.0',
67           'mapserverAddress': 'http://localhost/cgi-bin/mapserv',
68           'isSoap': 'false',
69           'tmpUrl': 'http://localhost/tmp/',
70           'serverAddress': 'http://localhost/zoo'
71          },
72  'identification': {'keywords': 'WPS,GIS',
73                     'abstract': 'WPS services for testing ZOO',
74                     'fees': 'None',
75                     'accessConstraints': 'none',
76                     'title': 'testing services'
77                    },
78  'lenv': {'status': '0',
79           'soap': 'false',
80           'cwd': '/usr/lib/cgi-bin',
81           'sid': '24709'
82          },
83  'env': {'DISPLAY': 'localhost:0'},
84  'provider': {'addressCountry': 'it',
85               'positionName': 'Developer',
86               'providerName': 'Name of provider',
87               'addressAdministrativeArea': 'False',
88               'phoneVoice': 'False',
89               'addressCity': 'City',
90               'providerSite': 'http://www.your.site',
91               'addressPostalCode': '38122',
92               'role': 'Developer',
93               'addressDeliveryPoint': 'False',
94               'phoneFacsimile': 'False',
95               'addressElectronicMailAddress': 'your@email.com',
96               'individualName': 'Your Name'
97              }
98  }
99
100Inputs
101^^^^^^^^^^^^
102The inputs are somethings like this ::
103
104  {
105  'variable_name': {'minOccurs': '1',
106                    'DataType': 'string',
107                    'value': 'this_is_the_value',
108                    'maxOccurs': '1',
109                    'inRequest': 'true'
110                   }
111  }
112
113The access to the value you have to require for the ``value`` parameter, something like this ::
114
115  yourVariable = inputs['variable_name']['value']
116
117Outputs
118^^^^^^^^^^^^^
119The outputs data as a structure really similar to the inputs one ::
120
121  {
122  'result': {'DataType': 'string',
123             'inRequest': 'true',
124            }
125  }
126
127There is no ``'value'`` parameter before you assign it ::
128
129  inputs['result']['value'] = yourOutputDataVariable
130
131The return statement has to be an integer: corresponding to the service status code.
132
133To add a message for the wrong result you can add the massage to ``conf["lenv"]["message"]``,
134for example:
135
136.. code-block:: python
137
138  conf["lenv"]["message"] = 'Your module return an error'
139
140Sample ZOO Python Services Provider
141***********************************
142
143The following code represents a simple ZOO Python Services Provider which provides only one
144Service, the HelloPy one.
145
146.. code-block:: python
147
148  import zoo
149  import sys
150  def HelloPy(conf,inputs,outputs):
151     outputs["Result"]["value"]="Hello "+inputs["a"]["value"]+" from Python World !"
152     return zoo.SERVICE_SUCCEEDED
153
154PHP
155---
156
157ZOO-API
158*******
159
160The ZOO-API for the PHP language is automatically available from your
161service code. Tthe following functions are defined in the ZOO-API:
162
163int zoo_SERVICE_SUCCEEDED()
164    return the value of SERVICE_SUCCEEDED
165int zoo_SERVICE_FAILED()
166    return the value of SERVICE_FAILED
167string zoo_Translate(string a)
168    return the translated string (using the "zoo-service" `textdomain
169    <http://www.gnu.org/software/libc/manual/html_node/Locating-gettext-catalog.html#index-textdomain>`__)
170
171void zoo_UpdateStatus(Array conf,string message,int pourcent)
172    update the status of the running service
173
174PHP ZCFG requirements
175**********************************
176
177The ZCFG file should contain the following :
178
179serviceType
180    PHP
181serviceProvider
182    The name of the php script (ie. service.php) to use as a ZOO Service Provider.
183
184PHP Data Structure used
185********************************
186
187The three parameters are passed to the PHP function as
188`Arrays <php.net/manual/language.types.array.php>`__.
189
190Sample ZOO PHP Services Provider
191******************************************
192
193.. code-block:: php
194
195  <?
196  function HelloPHP(&$main_conf,&$inputs,&$outputs){
197     $tmp="Hello ".$inputs[S][value]." from PHP world !";
198     $outputs["Result"]["value"]=zoo_Translate($tmp)
199     return zoo_SERVICE_SUCCEEDED();
200  }
201  ?>
202
203Java
204----
205
206ZOO-API
207*******
208
209Before you build your first ZOO-Service implemented inn Java, it is
210recommended that you first build the ZOO class of the Java ZOO-API.
211
212.. Note:: You should build ZOO-Kernel prior to follow this instructions.
213
214To build the ZOO.class of the ZOO-API for Java, use the following
215command:
216
217.. code-block:: guess
218
219  cd zoo-api/java
220  make
221  cp ZOO.class libZOO.so /usr/lib/cgi-bin
222
223.. Note:: running the previous commands will require that both
224          ``javac`` and ``javah`` are in your PATH.
225
226Java ZCFG requirements
227**********************************
228
229.. Note:: For each Service provided by your ZOO Java Services Provider
230          (your corresponding Java class), the ZCFG File must be
231          named the same as the Java public method name (also the
232          case of characters is important).
233
234The ZCFG file should contain the following :
235
236serviceType
237    Java
238serviceProvider
239    The name of the Java class to use as a ZOO Service Provider. For instance, if your
240    java class, located in the same directory as your ZOO-Kernel, was
241    named ``HelloWorld.class`` then you should use ``HelloWorld``.
242
243Java Data Structure used
244********************************
245
246The three parameters are passed to the Java function as
247`java.util.HashMap <http://docs.oracle.com/javase/8/docs/api/java/util/HashMap.html>`__.
248
249Sample ZOO Java Services Provider
250******************************************
251
252.. code-block:: java
253
254  import java.util.*;
255  public class HelloJava {
256    public static int HelloWorldJava(HashMap conf,HashMap inputs, HashMap outputs) {
257       HashMap hm1 = new HashMap();
258       hm1.put("dataType","string");
259       HashMap tmp=(HashMap)(inputs.get("S"));
260       java.lang.String v=tmp.get("value").toString();
261       hm1.put("value","Hello "+v+" from JAVA WOrld !");
262       outputs.put("Result",hm1);
263       System.err.println("Hello from JAVA WOrld !");
264       return ZOO.SERVICE_SUCCEEDED;
265    }
266  }
267
268Javascript
269----------
270
271ZOO API
272*********
273
274If you need to use :ref:`ZOO API <api>` in your service, you have first to copy ``zoo-api.js``
275and ``zoo-proj4js.js`` where your services are located (for example in Unix system probably in
276``/usr/lib/cgi-bin/``
277
278Javascript ZCFG requirements
279**********************************
280
281.. Note:: For each Service provided by your ZOO Javascript Services Provider, the ZCFG File
282          must be named the same as the Javascript function name (also the case of
283          characters is important).
284
285The ZCFG file should contain the following :
286
287serviceType
288    JS
289serviceProvider
290    The name of the JavaScript file to use as a ZOO Service Provider. For instance, if your
291    script, located in the same directory as your ZOO Kernel, was named ``my_module.js`` then
292    you should use ``my_module.js``.
293
294
295Javascript Data Structure used
296********************************
297
298The three parameters of the function are passed to the JavaScript function as Object.
299
300Sample ZOO Javascript Services Provider
301******************************************
302
303.. code-block:: javascript
304
305  function hellojs(conf,inputs,outputs){
306     outputs=new Array();
307     outputs={};
308     outputs["result"]["value"]="Hello "+inputs["S"]["value"]+" from JS World !";
309     return Array(3,outputs);
310  }
311
Note: See TracBrowser for help on using the repository browser.

Search

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png