source: branches/branch-1.6/docs/services/howtos.rst @ 960

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

Add the initial C# language support.

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