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

Last change on this file since 728 was 725, checked in by djay, 9 years ago

Fix issue with rst files displayed from Trac. Fix strings to be translated. Always use the same string in all messages.

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