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

Last change on this file since 613 was 613, checked in by djay, 8 years ago

Fix typo and update the Java part of the documentation.

  • 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: 9.9 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-03-13 14:24:44 +0000 (Fri, 13 Mar 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
206Specifically for the Java support, you may add the following two
207sections to your ``main.cfg`` file:
208
209:[javaxx]:
210   This section is used to pass -XX:* parameters to the JVM  created by the
211   ZOO-Kernel to handle your ZOO-Service (see `ref. 1
212   <http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html#BehavioralOptions>`__
213   or `ref. 2
214   <http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html#PerformanceTuning>`__
215   for sample available).
216   For each map ``a = b`` available in the ``[javaxx]`` section, the
217   option ``-XX:a=b`` will be passed to the JVM. In case of a map ``a =
218   minus`` (respectively ``a=plus``) then the option ``-XX:-a``
219   (respectivelly ``-XX:+a``) will be passed.
220:[javax]:
221   The section is used to pass -X* options to the JVM (see
222   `ref. <http://docs.oracle.com/cd/E22289_01/html/821-1274/configuring-the-default-jvm-and-java-arguments.html>`__). For
223   each map ``a = b`` available in the ``[javax]`` section, the option
224   ``-Xab`` will be passed to the JVM (ie. set ``mx=2G`` to pass
225   ``-Xmx2G``).
226
227ZOO-API
228*******
229
230Before you build your first ZOO-Service implemented in Java, it is
231recommended that you first build the ZOO class of the Java ZOO-API.
232
233.. Note:: You should build ZOO-Kernel prior to follow this instructions.
234
235To build the ZOO.class of the ZOO-API for Java, use the following
236command:
237
238.. code-block:: guess
239
240  cd zoo-api/java
241  make
242  cp ZOO.class libZOO.so /usr/lib/cgi-bin
243
244.. Note:: running the previous commands will require that both
245          ``javac`` and ``javah`` are in your PATH.
246
247Java ZCFG requirements
248**********************************
249
250.. Note:: For each Service provided by your ZOO Java Services Provider
251          (your corresponding Java class), the ZCFG File should have
252          the name of the Java public method corresponding to the
253          service (case-sensitive).
254
255The ZCFG file should contain the following :
256
257serviceType
258    Java
259serviceProvider
260    The name of the Java class to use as a ZOO Service Provider. For instance, if your
261    java class, located in the same directory as your ZOO-Kernel, was
262    named ``HelloJava.class`` then you should use ``HelloJava``.
263
264Java Data Structure used
265********************************
266
267The three parameters are passed to the Java function as
268`java.util.HashMap <http://docs.oracle.com/javase/8/docs/api/java/util/HashMap.html>`__.
269
270Sample ZOO Java Services Provider
271******************************************
272
273.. code-block:: java
274
275  import java.util.*;
276  public class HelloJava {
277    public static int HelloWorldJava(HashMap conf,HashMap inputs, HashMap outputs) {
278       HashMap hm1 = new HashMap();
279       hm1.put("dataType","string");
280       HashMap tmp=(HashMap)(inputs.get("S"));
281       java.lang.String v=tmp.get("value").toString();
282       hm1.put("value","Hello "+v+" from JAVA WOrld !");
283       outputs.put("Result",hm1);
284       System.err.println("Hello from JAVA WOrld !");
285       return ZOO.SERVICE_SUCCEEDED;
286    }
287  }
288
289Javascript
290----------
291
292ZOO API
293*********
294
295If you need to use :ref:`ZOO API <api>` in your service, you have first to copy ``zoo-api.js``
296and ``zoo-proj4js.js`` where your services are located (for example in Unix system probably in
297``/usr/lib/cgi-bin/``
298
299Javascript ZCFG requirements
300**********************************
301
302.. Note:: For each Service provided by your ZOO Javascript Services Provider, the ZCFG File
303          must be named the same as the Javascript function name (also the case of
304          characters is important).
305
306The ZCFG file should contain the following :
307
308serviceType
309    JS
310serviceProvider
311    The name of the JavaScript file to use as a ZOO Service Provider. For instance, if your
312    script, located in the same directory as your ZOO Kernel, was named ``my_module.js`` then
313    you should use ``my_module.js``.
314
315
316Javascript Data Structure used
317********************************
318
319The three parameters of the function are passed to the JavaScript function as Object.
320
321Sample ZOO Javascript Services Provider
322******************************************
323
324.. code-block:: javascript
325
326  function hellojs(conf,inputs,outputs){
327     outputs=new Array();
328     outputs={};
329     outputs["result"]["value"]="Hello "+inputs["S"]["value"]+" from JS World !";
330     return Array(3,outputs);
331  }
332
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