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

Last change on this file since 771 was 771, checked in by djay, 4 years ago

Remove the default java.library.path definition and use an optional [java] section instead (where the key java.library.path, amongst other, may be defined). Change _ function name to translate in the Java ZOO-API. Use a ogr.zoo_project package containing the ZOO class. Fix the hello-java service and update doc consequently

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