source: trunk/docs/services/howtos.rst @ 967

Last change on this file since 967 was 967, checked in by djay, 11 months ago

Add support for the two inputs / outputs syntaxes discussed in SWG in both the ZOO-Kernel and the HTML basic UI. Update documentation, add a section for the ZOO-API in Python language section. Rename variables in service.c to ease readabiliy.

  • Property svn:keywords set to Date Author
  • Property svn:mime-type set to text/plain
File size: 16.3 KB
Line 
1.. _services-create:
2
3Create your own ZOO-Services
4=========================
5
6:ref:`services_index` are quite easy to create once you have installed the ZOO Kernel and have
7chosen code (in the language of your choice) to turn into a ZOO service. Here are some
8HelloWorlds in Python, PHP, Java, C#  and JavaScript with links to their corresponding
9``.zcfg`` files.
10
11
12.. contents:: :depth: 3
13
14
15General information
16----------------------
17
18The function of the process for each programming language take three arguments: the main
19configuration, inputs and outputs.
20
21.. note:: The service must return **3** if the process run successfully
22         
23.. note:: The service must return **4** if the process ended with an error
24
25Python
26------
27
28You'll find here information needed to deploy your own Python Services Provider.
29
30ZOO-API
31*******
32
33From your python module where you define your services, you can access
34the ZOO-API by importing the ``zoo`` module. No need to install
35anything here, the module will be automatically created from the
36ZOO-Kernel code at runtime.
37
38The following attributes are available from the ZOO-API :
39
40SERVICE_SUCCEEDED
41    Value to return in case your service end successfully.
42SERVICE_FAILED
43    Value to retrun in case of failure.
44   
45
46The following functions are defined in the ZOO-API:
47
48_(strToTranslate)
49    return the translated string (using the "zoo-service" `textdomain
50    <http://www.gnu.org/software/libc/manual/html_node/Locating-gettext-catalog.html#index-textdomain>`__)
51
52update_status(dictConf,iPourcent)
53    update the status of the running service
54
55Python ZCFG requirements
56************************
57
58.. Note:: For each Service provided by your ZOO Python Services Provider, the ZCFG File
59          must be named the same as the Python module function name (also the case of
60          characters is important).
61
62The ZCFG file should contain the following :
63
64
65serviceType
66    Python
67serviceProvider
68    The name of the Python module to use as a ZOO Service Provider. For instance, if your
69    script, located in the same directory as your ZOO Kernel, was named ``my_module.py`` then
70    you should use ``my_module`` (the Python module name) for the serviceProvider value in ZCFG file.
71
72Python Data Structure used
73**************************
74The three parameters of the function are passed to the Python module as dictionaries.
75
76Following you'll find an example for each parameters
77
78Main configuration
79^^^^^^^^^^^^^^^^^^^^^
80Main configuration contains several informations, some of them are really useful to develop your service.
81Following an example ::
82
83  {
84  'main': {'lang': 'en-UK',
85           'language': 'en-US',
86           'encoding': 'utf-8',
87           'dataPath': '/var/www/tmp',
88           'tmpPath': '/var/www/tmp',
89           'version': '1.0.0',
90           'mapserverAddress': 'http://localhost/cgi-bin/mapserv',
91           'isSoap': 'false',
92           'tmpUrl': 'http://localhost/tmp/',
93           'serverAddress': 'http://localhost/zoo'
94          },
95  'identification': {'keywords': 'WPS,GIS',
96                     'abstract': 'WPS services for testing ZOO',
97                     'fees': 'None',
98                     'accessConstraints': 'none',
99                     'title': 'testing services'
100                    },
101  'lenv': {'status': '0',
102           'soap': 'false',
103           'cwd': '/usr/lib/cgi-bin',
104           'sid': '24709'
105          },
106  'env': {'DISPLAY': 'localhost:0'},
107  'provider': {'addressCountry': 'it',
108               'positionName': 'Developer',
109               'providerName': 'Name of provider',
110               'addressAdministrativeArea': 'False',
111               'phoneVoice': 'False',
112               'addressCity': 'City',
113               'providerSite': 'http://www.your.site',
114               'addressPostalCode': '38122',
115               'role': 'Developer',
116               'addressDeliveryPoint': 'False',
117               'phoneFacsimile': 'False',
118               'addressElectronicMailAddress': 'your@email.com',
119               'individualName': 'Your Name'
120              }
121  }
122
123Inputs
124^^^^^^^^^^^^
125The inputs are somethings like this ::
126
127  {
128  'variable_name': {'minOccurs': '1',
129                    'dataType': 'string',
130                    'value': 'this_is_the_value',
131                    'maxOccurs': '1',
132                    'inRequest': 'true'
133                   }
134  }
135
136The access to the value you have to require for the ``value`` parameter, something like this ::
137
138  yourVariable = inputs['variable_name']['value']
139
140Outputs
141^^^^^^^^^^^^^
142The outputs data as a structure really similar to the inputs one ::
143
144  {
145  'result': {'dataType': 'string',
146             'inRequest': 'true',
147            }
148  }
149
150There is no ``'value'`` parameter before you assign it ::
151
152  inputs['result']['value'] = yourOutputDataVariable
153
154The return statement has to be an integer: corresponding to the service status code.
155
156To add a message for the wrong result you can add the massage to ``conf["lenv"]["message"]``,
157for example:
158
159.. code-block:: python
160
161  conf["lenv"]["message"] = 'Your module return an error'
162
163Sample ZOO Python Services Provider
164***********************************
165
166The following code represents a simple ZOO Python Services Provider which provides only one
167Service, the HelloPy one.
168
169.. code-block:: python
170
171  import zoo
172  import sys
173  def HelloPy(conf,inputs,outputs):
174     outputs["Result"]["value"]="Hello "+inputs["a"]["value"]+" from Python World !"
175     return zoo.SERVICE_SUCCEEDED
176
177PHP
178---
179
180ZOO-API
181*******
182
183The ZOO-API for the PHP language is automatically available from your
184service code. The following functions are defined in the ZOO-API:
185
186int zoo_SERVICE_SUCCEEDED()
187    return the value of SERVICE_SUCCEEDED
188int zoo_SERVICE_FAILED()
189    return the value of SERVICE_FAILED
190string zoo_Translate(string a)
191    return the translated string (using the "zoo-service" `textdomain
192    <http://www.gnu.org/software/libc/manual/html_node/Locating-gettext-catalog.html#index-textdomain>`__)
193
194void zoo_UpdateStatus(Array conf,string message,int pourcent)
195    update the status of the running service
196
197PHP ZCFG requirements
198**********************************
199
200The ZCFG file should contain the following :
201
202serviceType
203    PHP
204serviceProvider
205    The name of the php script (ie. service.php) to use as a ZOO Service Provider.
206
207PHP Data Structure used
208********************************
209
210The three parameters are passed to the PHP function as
211`Arrays <php.net/manual/language.types.array.php>`__.
212
213Sample ZOO PHP Services Provider
214******************************************
215
216.. code-block:: php
217
218  <?
219  function HelloPHP(&$main_conf,&$inputs,&$outputs){
220     $tmp="Hello ".$inputs[S][value]." from PHP world !";
221     $outputs["Result"]["value"]=zoo_Translate($tmp);
222     return zoo_SERVICE_SUCCEEDED();
223  }
224  ?>
225
226Java
227----
228
229Specifically for the Java support, you may add the following three
230sections to your ``main.cfg`` file:
231
232:[java]:
233   This section is used to pass -D* parameters to the JVM  created by the
234   ZOO-Kernel to handle your ZOO-Service (see `ref. 1
235   <http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html#BehavioralOptions>`__
236   or `ref. 2
237   <http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html#PerformanceTuning>`__
238   for sample available).
239   For each map ``a = b`` available in the ``[java]`` section, the
240   option ``-Da=b`` will be passed to the JVM.
241:[javax]:
242   The section is used to pass -X* options to the JVM (see
243   `ref. <http://docs.oracle.com/cd/E22289_01/html/821-1274/configuring-the-default-jvm-and-java-arguments.html>`__). For
244   each map ``a = b`` available in the ``[javax]`` section, the option
245   ``-Xab`` will be passed to the JVM (ie. set ``mx=2G`` to pass
246   ``-Xmx2G``).
247:[javaxx]:
248   This section is used to pass -XX:* parameters to the JVM  created by the
249   ZOO-Kernel to handle your ZOO-Service (see `ref. 1
250   <http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html#BehavioralOptions>`__
251   or `ref. 2
252   <http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html#PerformanceTuning>`__
253   for sample available).
254   For each map ``a = b`` available in the ``[javaxx]`` section, the
255   option ``-XX:a=b`` will be passed to the JVM. In case of a map ``a =
256   minus`` (respectively ``a=plus``) then the option ``-XX:-a``
257   (respectivelly ``-XX:+a``) will be passed.
258
259ZOO-API
260*******
261
262Before you build your first ZOO-Service implemented in Java, it is
263recommended that you first build the ZOO class of the Java ZOO-API.
264
265.. Note:: You should build ZOO-Kernel prior to follow this instructions.
266
267To build the ZOO.class of the ZOO-API for Java, use the following
268command:
269
270.. code-block:: guess
271
272  cd zoo-api/java
273  make
274
275.. Note:: running the previous commands will require that both
276          ``javac`` and ``javah`` are in your PATH.
277
278You should copy the ``libZOO.so`` in a place Java can find it. In case you
279have defined the ``java.library.path`` key as ``/usr/lib/cgi-bin``
280(in the ``[java]`` section), then you should copy it there.
281
282.. code-block:: guess
283
284  cp libZOO.so /usr/lib/cgi-bin
285
286The ZOO-API provides the following functions:
287
288:String translate(String s):
289   This function call the internal ZOO-Kernel function responsible for
290   searching a translation of ``s`` in the zoo-services dictionary.
291
292:void updateStatus(Hashmap conf,String pourcent,String message):
293   This function call the updateStatus ZOO-Kernel function responsible
294   for updating the status of the running service (only usefull when
295   the service has been called asynchronously).
296
297
298
299Java ZCFG requirements
300**********************************
301
302.. Note:: For each Service provided by your ZOO Java Services Provider
303          (your corresponding Java class), the ZCFG File should have
304          the name of the Java public method corresponding to the
305          service (case-sensitive).
306
307The ZCFG file should contain the following :
308
309serviceType
310    Java
311serviceProvider
312    The name of the Java class to use as a ZOO Service Provider. For instance, if your
313    java class, located in the same directory as your ZOO-Kernel, was
314    named ``HelloJava.class`` then you should use ``HelloJava``.
315
316Java Data Structure used
317********************************
318
319The three parameters are passed to the Java function as
320`java.util.HashMap <http://docs.oracle.com/javase/8/docs/api/java/util/HashMap.html>`__.
321
322Sample ZOO Java Services Provider
323******************************************
324
325.. code-block:: java
326
327  import java.util.*;
328  public class HelloJava {
329    public static int HelloWorldJava(HashMap conf,HashMap inputs, HashMap outputs) {
330       HashMap hm1 = new HashMap();
331       hm1.put("dataType","string");
332       HashMap tmp=(HashMap)(inputs.get("S"));
333       java.lang.String v=tmp.get("value").toString();
334       hm1.put("value","Hello "+v+" from JAVA WOrld !");
335       outputs.put("Result",hm1);
336       System.err.println("Hello from JAVA WOrld !");
337       return ZOO.SERVICE_SUCCEEDED;
338    }
339  }
340
341C#
342----
343
344Specifically for the C# support, you should add the following
345section to your ``main.cfg`` file.
346
347
348:[mono]:
349   This section is used to define both ``libPath`` and ``etcPath``
350   required by the Mono .NET Framework.
351
352ZOO-API
353*******
354
355Before you build your first ZOO-Service implemented in Mono, you
356should first build the ``ZMaps.dll`` containing the Mono ZOO-API.
357
358.. Note:: You should build ZOO-Kernel prior to follow this instructions.
359
360.. code-block:: guess
361
362  cd zoo-api/mono
363  make
364
365Then you should copy the ``ZMaps.dll`` in your ``servicePath`` or in
366the directory where your ``zoo_loader.cgi`` file is stored.
367
368The ZOO-API is available from a C# class named ZOO_API and provides
369the following static variables:
370
371:int SERVICE_SUCCEEDED:
372   Value to return in case your service end successfully.
373:int SERVICE_FAILED:
374   Value to retrun in case of failure.
375
376The ZOO-API provides the following static functions:
377
378:string Translate(String s):
379   This function call the internal ZOO-Kernel function responsible for
380   searching a translation of ``s`` in the zoo-services dictionary.
381
382:void UpdateStatus(ZMaps conf,String pourcent,String message):
383   This function call the updateStatus ZOO-Kernel function responsible
384   for updating the status of the running service (only usefull when
385   the service has been called asynchronously).
386
387
388C# ZCFG requirements
389**********************************
390
391.. Note:: For each Service provided by your ZOO Mono Services Provider
392          (your corresponding Mono class), the ZCFG File should have
393          the name of the Mono public static function corresponding to the
394          service (case-sensitive).
395
396The ZCFG file should contain the following :
397
398serviceType
399    Mono
400serviceProvider
401    The full name of the C# dll containing the ZOO-Service Provider
402    (including ``.dll``).
403serviceNameSpace
404    The namespace of the C# class containing the ZOO-Service Provider.
405serviceClass
406    The name of the C# class containing the ZOO-Service Provider definition.
407
408C# Data Structure used
409********************************
410
411The three parameters of the function are passed to the Mono static
412function as ``ZMaps`` which are basically
413``Dictionary<String,_ZMaps>``.
414
415Sample ZOO C# Services Provider
416******************************************
417
418.. literalinclude:: ../../zoo-project/zoo-services/hello-mono/test.cs
419   :language: csharp
420   :lines: 24-100
421
422Javascript
423----------
424
425ZOO API
426*********
427
428If you need to use :ref:`ZOO API <api>` in your service, you have first to copy ``zoo-api.js``
429and ``zoo-proj4js.js`` where your services are located (for example in Unix system probably in
430``/usr/lib/cgi-bin/``
431
432Javascript ZCFG requirements
433**********************************
434
435.. Note:: For each Service provided by your ZOO Javascript Services Provider, the ZCFG File
436          must be named the same as the Javascript function name (also the case of
437          characters is important).
438
439The ZCFG file should contain the following :
440
441serviceType
442    JS
443serviceProvider
444    The name of the JavaScript file to use as a ZOO Service Provider. For instance, if your
445    script, located in the same directory as your ZOO Kernel, was named ``my_module.js`` then
446    you should use ``my_module.js``.
447
448
449Javascript Data Structure used
450********************************
451
452The three parameters of the function are passed to the JavaScript function as Object.
453
454Sample ZOO Javascript Services Provider
455******************************************
456
457.. code-block:: javascript
458
459  function hellojs(conf,inputs,outputs){
460     outputs=new Array();
461     outputs={};
462     outputs["result"]["value"]="Hello "+inputs["S"]["value"]+" from JS World !";
463     return Array(3,outputs);
464  }
465
466
467R
468----------
469
470ZOO API
471*********
472
473For using the R language from the ZOO-Project, you have first to copy
474``minimal.r`` in the same directory as the ZOO-Kernel.
475
476The ZOO-API is available from a R script and provide access to a
477global zoo environment which contains both static variables and also
478the dictionaries for outputs and conf:
479
480:int zoo[["SERVICE_SUCCEEDED"]]:
481   Value to return in case your service end successfully.
482:int zoo[["SERVICE_FAILED"]]:
483   Value to retrun in case of failure.
484
485The ZOO-API provides the following functions:
486
487:string ZOOTranslate(String s):
488   This function call the internal ZOO-Kernel function responsible for
489   searching a translation of ``s`` in the zoo-services dictionary.
490
491:void ZOOUpdateStatus(ZMaps conf,String pourcent):
492   This function call the updateStatus ZOO-Kernel function responsible
493   for updating the status of the running service (only usefull when
494   the service has been called asynchronously).
495
496
497R ZCFG requirements
498**********************************
499
500.. Note:: For each Service provided by your ZOO R Services Provider,
501          the ZCFG File must be named the same as the R function name
502          (it is case-sensitive).
503
504The ZCFG file should contain the following :
505
506serviceType
507   R
508serviceProvider
509    The name of the R file to use as a ZOO Service Provider. For instance, if your
510    script, located in the same directory as your ZOO Kernel, was named ``my_module.r`` then
511    you should use ``my_module.r``.
512
513
514R Data Structure used
515********************************
516
517The three parameters of the function are passed to the R function as
518R dictionaries.
519
520The specificity of the R language make that it was easier to use
521global variales than passing parameters by reference as we do in
522other progamming languages. It is the reason why you will have to
523access outpus by using the global variable as for the main
524configuration dictionary.
525
526Sample ZOO R Services Provider
527******************************************
528
529.. code-block:: javascript
530
531    source("minimal.r")
532               
533    hellor <- function(a,b,c) {
534        # Set the result
535        zoo[["outputs"]][["Result"]][["value"]] <<- ZOOTranslate(paste("Hello",b[["S"]][["value"]],"from the R World!",sep=" "))
536        # Return SERVICE_SUCCEEDEED
537        return(zoo[["SERVICE_SUCCEEDEED"]])
538    }
539
Note: See TracBrowser for help on using the repository browser.

Search

Context Navigation

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