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