[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-02-25 12:32:55 +0000 (Wed, 25 Feb 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 | |
---|
[406] | 21 | The function of the process for each programming language take three arguments: the main |
---|
| 22 | configuration, inputs and outputs. |
---|
| 23 | |
---|
[399] | 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 | |
---|
[348] | 27 | Python |
---|
| 28 | ------ |
---|
| 29 | |
---|
| 30 | You'll find here information needed to deploy your own Python Services Provider. |
---|
| 31 | |
---|
| 32 | Python ZCFG requirements |
---|
| 33 | ************************ |
---|
| 34 | |
---|
| 35 | .. Note:: For each Service provided by your ZOO Python Services Provider, the ZCFG File |
---|
[396] | 36 | must be named the same as the Python module function name (also the case of |
---|
| 37 | characters is important). |
---|
[348] | 38 | |
---|
| 39 | The ZCFG file should contain the following : |
---|
| 40 | |
---|
| 41 | |
---|
| 42 | serviceType |
---|
| 43 | Python |
---|
| 44 | serviceProvider |
---|
[406] | 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. |
---|
[348] | 48 | |
---|
| 49 | Python Data Structure used |
---|
| 50 | ************************** |
---|
[406] | 51 | The three parameters of the function are passed to the Python module as dictionaries. |
---|
[348] | 52 | |
---|
[396] | 53 | Following you'll find an example for each parameters |
---|
[348] | 54 | |
---|
[396] | 55 | Main configuration |
---|
| 56 | ^^^^^^^^^^^^^^^^^^^^^ |
---|
| 57 | Main configuration contains several informations, some of them are really useful to develop your service. |
---|
| 58 | Following an example :: |
---|
[348] | 59 | |
---|
[396] | 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 | } |
---|
[348] | 99 | |
---|
[396] | 100 | Inputs |
---|
| 101 | ^^^^^^^^^^^^ |
---|
| 102 | The inputs are somethings like this :: |
---|
[348] | 103 | |
---|
[396] | 104 | { |
---|
| 105 | 'variable_name': {'minOccurs': '1', |
---|
| 106 | 'DataType': 'string', |
---|
| 107 | 'value': 'this_is_the_value', |
---|
| 108 | 'maxOccurs': '1', |
---|
| 109 | 'inRequest': 'true' |
---|
| 110 | } |
---|
[348] | 111 | } |
---|
| 112 | |
---|
[396] | 113 | The access to the value you have to require for the ``value`` parameter, something like this :: |
---|
| 114 | |
---|
| 115 | yourVariable = inputs['variable_name']['value'] |
---|
| 116 | |
---|
| 117 | Outputs |
---|
| 118 | ^^^^^^^^^^^^^ |
---|
| 119 | The outputs data as a structure really similar to the inputs one :: |
---|
| 120 | |
---|
| 121 | { |
---|
| 122 | 'result': {'DataType': 'string', |
---|
| 123 | 'inRequest': 'true', |
---|
| 124 | } |
---|
| 125 | } |
---|
| 126 | |
---|
| 127 | There is no ``'value'`` parameter before you assign it :: |
---|
| 128 | |
---|
| 129 | inputs['result']['value'] = yourOutputDataVariable |
---|
| 130 | |
---|
| 131 | The return statement has to be an integer: corresponding to the service status code. |
---|
| 132 | |
---|
| 133 | To add a message for the wrong result you can add the massage to ``conf["lenv"]["message"]``, |
---|
| 134 | for example: |
---|
| 135 | |
---|
| 136 | .. code-block:: python |
---|
| 137 | |
---|
| 138 | conf["lenv"]["message"] = 'Your module return an error' |
---|
| 139 | |
---|
[348] | 140 | Sample ZOO Python Services Provider |
---|
| 141 | *********************************** |
---|
| 142 | |
---|
| 143 | The following code represents a simple ZOO Python Services Provider which provides only one |
---|
| 144 | Service, the HelloPy one. |
---|
| 145 | |
---|
| 146 | .. code-block:: python |
---|
| 147 | |
---|
[586] | 148 | import zoo |
---|
[348] | 149 | import sys |
---|
| 150 | def HelloPy(conf,inputs,outputs): |
---|
| 151 | outputs["Result"]["value"]="Hello "+inputs["a"]["value"]+" from Python World !" |
---|
[586] | 152 | return zoo.SERVICE_SUCCEEDED |
---|
[348] | 153 | |
---|
| 154 | PHP |
---|
| 155 | --- |
---|
| 156 | |
---|
[586] | 157 | ZOO-API |
---|
| 158 | ******* |
---|
| 159 | |
---|
| 160 | The ZOO-API for the PHP language is automatically available from your |
---|
| 161 | service code. Tthe following functions are defined in the ZOO-API: |
---|
| 162 | |
---|
| 163 | int zoo_SERVICE_SUCCEEDED() |
---|
| 164 | return the value of SERVICE_SUCCEEDED |
---|
| 165 | int zoo_SERVICE_FAILED() |
---|
| 166 | return the value of SERVICE_FAILED |
---|
| 167 | string 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 | |
---|
| 171 | void zoo_UpdateStatus(Array conf,string message,int pourcent) |
---|
| 172 | update the status of the running service |
---|
| 173 | |
---|
| 174 | PHP ZCFG requirements |
---|
| 175 | ********************************** |
---|
| 176 | |
---|
| 177 | The ZCFG file should contain the following : |
---|
| 178 | |
---|
| 179 | serviceType |
---|
| 180 | PHP |
---|
| 181 | serviceProvider |
---|
| 182 | The name of the php script (ie. service.php) to use as a ZOO Service Provider. |
---|
| 183 | |
---|
| 184 | PHP Data Structure used |
---|
| 185 | ******************************** |
---|
| 186 | |
---|
| 187 | The three parameters are passed to the PHP function as |
---|
| 188 | `Arrays <php.net/manual/language.types.array.php>`__. |
---|
| 189 | |
---|
| 190 | Sample ZOO PHP Services Provider |
---|
| 191 | ****************************************** |
---|
| 192 | |
---|
[348] | 193 | .. code-block:: php |
---|
| 194 | |
---|
| 195 | <? |
---|
| 196 | function HelloPHP(&$main_conf,&$inputs,&$outputs){ |
---|
[586] | 197 | $tmp="Hello ".$inputs[S][value]." from PHP world !"; |
---|
[596] | 198 | $outputs["Result"]["value"]=zoo_Translate($tmp); |
---|
[586] | 199 | return zoo_SERVICE_SUCCEEDED(); |
---|
[348] | 200 | } |
---|
| 201 | ?> |
---|
| 202 | |
---|
| 203 | Java |
---|
| 204 | ---- |
---|
| 205 | |
---|
[528] | 206 | ZOO-API |
---|
| 207 | ******* |
---|
| 208 | |
---|
| 209 | Before you build your first ZOO-Service implemented inn Java, it is |
---|
| 210 | recommended that you first build the ZOO class of the Java ZOO-API. |
---|
| 211 | |
---|
| 212 | .. Note:: You should build ZOO-Kernel prior to follow this instructions. |
---|
| 213 | |
---|
| 214 | To build the ZOO.class of the ZOO-API for Java, use the following |
---|
| 215 | command: |
---|
| 216 | |
---|
| 217 | .. code-block:: guess |
---|
| 218 | |
---|
| 219 | cd zoo-api/java |
---|
| 220 | make |
---|
| 221 | cp ZOO.class libZOO.so /usr/lib/cgi-bin |
---|
| 222 | |
---|
| 223 | .. Note:: running the previous commands will require that both |
---|
| 224 | ``javac`` and ``javah`` are in your PATH. |
---|
| 225 | |
---|
| 226 | Java ZCFG requirements |
---|
| 227 | ********************************** |
---|
| 228 | |
---|
| 229 | .. Note:: For each Service provided by your ZOO Java Services Provider |
---|
| 230 | (your corresponding Java class), the ZCFG File must be |
---|
| 231 | named the same as the Java public method name (also the |
---|
| 232 | case of characters is important). |
---|
| 233 | |
---|
| 234 | The ZCFG file should contain the following : |
---|
| 235 | |
---|
| 236 | serviceType |
---|
| 237 | Java |
---|
| 238 | serviceProvider |
---|
| 239 | The name of the Java class to use as a ZOO Service Provider. For instance, if your |
---|
| 240 | java class, located in the same directory as your ZOO-Kernel, was |
---|
| 241 | named ``HelloWorld.class`` then you should use ``HelloWorld``. |
---|
| 242 | |
---|
| 243 | Java Data Structure used |
---|
| 244 | ******************************** |
---|
| 245 | |
---|
[586] | 246 | The three parameters are passed to the Java function as |
---|
| 247 | `java.util.HashMap <http://docs.oracle.com/javase/8/docs/api/java/util/HashMap.html>`__. |
---|
[528] | 248 | |
---|
| 249 | Sample ZOO Java Services Provider |
---|
| 250 | ****************************************** |
---|
| 251 | |
---|
[348] | 252 | .. code-block:: java |
---|
| 253 | |
---|
| 254 | import java.util.*; |
---|
| 255 | public class HelloJava { |
---|
| 256 | public static int HelloWorldJava(HashMap conf,HashMap inputs, HashMap outputs) { |
---|
| 257 | HashMap hm1 = new HashMap(); |
---|
| 258 | hm1.put("dataType","string"); |
---|
| 259 | HashMap tmp=(HashMap)(inputs.get("S")); |
---|
| 260 | java.lang.String v=tmp.get("value").toString(); |
---|
| 261 | hm1.put("value","Hello "+v+" from JAVA WOrld !"); |
---|
| 262 | outputs.put("Result",hm1); |
---|
| 263 | System.err.println("Hello from JAVA WOrld !"); |
---|
[528] | 264 | return ZOO.SERVICE_SUCCEEDED; |
---|
[348] | 265 | } |
---|
| 266 | } |
---|
| 267 | |
---|
| 268 | Javascript |
---|
| 269 | ---------- |
---|
| 270 | |
---|
[406] | 271 | ZOO API |
---|
| 272 | ********* |
---|
| 273 | |
---|
| 274 | If you need to use :ref:`ZOO API <api>` in your service, you have first to copy ``zoo-api.js`` |
---|
| 275 | and ``zoo-proj4js.js`` where your services are located (for example in Unix system probably in |
---|
| 276 | ``/usr/lib/cgi-bin/`` |
---|
| 277 | |
---|
| 278 | Javascript ZCFG requirements |
---|
| 279 | ********************************** |
---|
| 280 | |
---|
| 281 | .. Note:: For each Service provided by your ZOO Javascript Services Provider, the ZCFG File |
---|
| 282 | must be named the same as the Javascript function name (also the case of |
---|
| 283 | characters is important). |
---|
| 284 | |
---|
| 285 | The ZCFG file should contain the following : |
---|
| 286 | |
---|
| 287 | serviceType |
---|
| 288 | JS |
---|
| 289 | serviceProvider |
---|
| 290 | The name of the JavaScript file to use as a ZOO Service Provider. For instance, if your |
---|
| 291 | script, located in the same directory as your ZOO Kernel, was named ``my_module.js`` then |
---|
| 292 | you should use ``my_module.js``. |
---|
| 293 | |
---|
| 294 | |
---|
| 295 | Javascript Data Structure used |
---|
| 296 | ******************************** |
---|
| 297 | |
---|
| 298 | The three parameters of the function are passed to the JavaScript function as Object. |
---|
| 299 | |
---|
| 300 | Sample ZOO Javascript Services Provider |
---|
| 301 | ****************************************** |
---|
| 302 | |
---|
[348] | 303 | .. code-block:: javascript |
---|
| 304 | |
---|
| 305 | function hellojs(conf,inputs,outputs){ |
---|
| 306 | outputs=new Array(); |
---|
| 307 | outputs={}; |
---|
| 308 | outputs["result"]["value"]="Hello "+inputs["S"]["value"]+" from JS World !"; |
---|
| 309 | return Array(3,outputs); |
---|
| 310 | } |
---|
[406] | 311 | |
---|