[659] | 1 | .. _services-create: |
---|
| 2 | |
---|
| 3 | Create your own ZOO-Services |
---|
| 4 | ========================= |
---|
| 5 | |
---|
| 6 | :ref:`services_index` are quite easy to create once you have installed the ZOO Kernel and have |
---|
| 7 | chosen code (in the language of your choice) to turn into a ZOO service. Here are some |
---|
| 8 | HelloWorlds in Python, PHP, Java and JavaScript with links to their corresponding |
---|
| 9 | ``.zcfg`` files. |
---|
| 10 | |
---|
| 11 | |
---|
| 12 | General information |
---|
| 13 | ---------------------- |
---|
| 14 | |
---|
| 15 | The function of the process for each programming language take three arguments: the main |
---|
| 16 | configuration, 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 | |
---|
| 22 | Python |
---|
| 23 | ------ |
---|
| 24 | |
---|
| 25 | You'll find here information needed to deploy your own Python Services Provider. |
---|
| 26 | |
---|
| 27 | Python 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 | |
---|
| 34 | The ZCFG file should contain the following : |
---|
| 35 | |
---|
| 36 | |
---|
| 37 | serviceType |
---|
| 38 | Python |
---|
| 39 | serviceProvider |
---|
| 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 | |
---|
| 44 | Python Data Structure used |
---|
| 45 | ************************** |
---|
| 46 | The three parameters of the function are passed to the Python module as dictionaries. |
---|
| 47 | |
---|
| 48 | Following you'll find an example for each parameters |
---|
| 49 | |
---|
| 50 | Main configuration |
---|
| 51 | ^^^^^^^^^^^^^^^^^^^^^ |
---|
| 52 | Main configuration contains several informations, some of them are really useful to develop your service. |
---|
| 53 | Following 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 | |
---|
| 95 | Inputs |
---|
| 96 | ^^^^^^^^^^^^ |
---|
| 97 | The 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 | |
---|
| 108 | The access to the value you have to require for the ``value`` parameter, something like this :: |
---|
| 109 | |
---|
| 110 | yourVariable = inputs['variable_name']['value'] |
---|
| 111 | |
---|
| 112 | Outputs |
---|
| 113 | ^^^^^^^^^^^^^ |
---|
| 114 | The outputs data as a structure really similar to the inputs one :: |
---|
| 115 | |
---|
| 116 | { |
---|
| 117 | 'result': {'DataType': 'string', |
---|
| 118 | 'inRequest': 'true', |
---|
| 119 | } |
---|
| 120 | } |
---|
| 121 | |
---|
| 122 | There is no ``'value'`` parameter before you assign it :: |
---|
| 123 | |
---|
| 124 | inputs['result']['value'] = yourOutputDataVariable |
---|
| 125 | |
---|
| 126 | The return statement has to be an integer: corresponding to the service status code. |
---|
| 127 | |
---|
| 128 | To add a message for the wrong result you can add the massage to ``conf["lenv"]["message"]``, |
---|
| 129 | for example: |
---|
| 130 | |
---|
| 131 | .. code-block:: python |
---|
| 132 | |
---|
| 133 | conf["lenv"]["message"] = 'Your module return an error' |
---|
| 134 | |
---|
| 135 | Sample ZOO Python Services Provider |
---|
| 136 | *********************************** |
---|
| 137 | |
---|
| 138 | The following code represents a simple ZOO Python Services Provider which provides only one |
---|
| 139 | Service, 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 | |
---|
| 149 | PHP |
---|
| 150 | --- |
---|
| 151 | |
---|
| 152 | ZOO-API |
---|
| 153 | ******* |
---|
| 154 | |
---|
| 155 | The ZOO-API for the PHP language is automatically available from your |
---|
| 156 | service code. Tthe following functions are defined in the ZOO-API: |
---|
| 157 | |
---|
| 158 | int zoo_SERVICE_SUCCEEDED() |
---|
| 159 | return the value of SERVICE_SUCCEEDED |
---|
| 160 | int zoo_SERVICE_FAILED() |
---|
| 161 | return the value of SERVICE_FAILED |
---|
| 162 | string 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 | |
---|
| 166 | void zoo_UpdateStatus(Array conf,string message,int pourcent) |
---|
| 167 | update the status of the running service |
---|
| 168 | |
---|
| 169 | PHP ZCFG requirements |
---|
| 170 | ********************************** |
---|
| 171 | |
---|
| 172 | The ZCFG file should contain the following : |
---|
| 173 | |
---|
| 174 | serviceType |
---|
| 175 | PHP |
---|
| 176 | serviceProvider |
---|
| 177 | The name of the php script (ie. service.php) to use as a ZOO Service Provider. |
---|
| 178 | |
---|
| 179 | PHP Data Structure used |
---|
| 180 | ******************************** |
---|
| 181 | |
---|
| 182 | The three parameters are passed to the PHP function as |
---|
| 183 | `Arrays <php.net/manual/language.types.array.php>`__. |
---|
| 184 | |
---|
| 185 | Sample 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 | |
---|
| 198 | Java |
---|
| 199 | ---- |
---|
| 200 | |
---|
| 201 | Specifically for the Java support, you may add the following two |
---|
| 202 | sections to your ``main.cfg`` file: |
---|
| 203 | |
---|
[771] | 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``). |
---|
[659] | 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 | |
---|
| 231 | ZOO-API |
---|
| 232 | ******* |
---|
| 233 | |
---|
| 234 | Before you build your first ZOO-Service implemented in Java, it is |
---|
| 235 | recommended 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 | |
---|
| 239 | To build the ZOO.class of the ZOO-API for Java, use the following |
---|
| 240 | command: |
---|
| 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 | |
---|
[771] | 250 | You should copy the ``libZOO.so`` in a place Java can find it. In case you |
---|
| 251 | have 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 | |
---|
| 258 | The 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 | |
---|
[659] | 271 | Java 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 | |
---|
| 279 | The ZCFG file should contain the following : |
---|
| 280 | |
---|
| 281 | serviceType |
---|
| 282 | Java |
---|
| 283 | serviceProvider |
---|
| 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 | |
---|
| 288 | Java Data Structure used |
---|
| 289 | ******************************** |
---|
| 290 | |
---|
| 291 | The 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 | |
---|
| 294 | Sample 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 | |
---|
| 313 | Javascript |
---|
| 314 | ---------- |
---|
| 315 | |
---|
| 316 | ZOO API |
---|
| 317 | ********* |
---|
| 318 | |
---|
| 319 | If you need to use :ref:`ZOO API <api>` in your service, you have first to copy ``zoo-api.js`` |
---|
| 320 | and ``zoo-proj4js.js`` where your services are located (for example in Unix system probably in |
---|
| 321 | ``/usr/lib/cgi-bin/`` |
---|
| 322 | |
---|
| 323 | Javascript 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 | |
---|
| 330 | The ZCFG file should contain the following : |
---|
| 331 | |
---|
| 332 | serviceType |
---|
| 333 | JS |
---|
| 334 | serviceProvider |
---|
| 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 | |
---|
| 340 | Javascript Data Structure used |
---|
| 341 | ******************************** |
---|
| 342 | |
---|
| 343 | The three parameters of the function are passed to the JavaScript function as Object. |
---|
| 344 | |
---|
| 345 | Sample 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 | |
---|