Changeset 262 for trunk/docs/workshop/2010/ogr_base_vect_ops.txt
- Timestamp:
- Jul 15, 2011, 8:03:05 PM (13 years ago)
- File:
-
- 1 edited
-
trunk/docs/workshop/2010/ogr_base_vect_ops.txt (modified) (55 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/docs/workshop/2010/ogr_base_vect_ops.txt
r256 r262 2 2 3 3 Creating OGR based Web Services 4 ########################## 4 ############################### 5 5 6 6 .. contents:: Table of Contents … … 9 9 10 10 Introduction 11 ************* 12 13 In this part, we are going to create a ZOO ServicesProvider containing several Services based on the OGR C API or on the OGR Python module, which have also been placed in the ZOO installation on OSGeoLive. The intended goal is to use OGR and its GEOS based simple spatial functions as WPS Services. 14 15 We will first start with the Boundary spatial function, which will be explained, codded and tested gradually as a ZOO Service. The same procedure will then be used to enable the Buffer, Centroid and Convex Hull functions. Once done, some multiple geometries processes such as Intersection, Union, Difference and Symetric Difference will be implemented through an `exercise <./exercise.html>`__ at the end of the workshop. 16 17 As already said in the introduction, you have the choice to code your service in C or Python (or both!) during this workshop. Explanations will be based on the C part, but will be very helpful for those who will choose Python. Please decide according to your habits and preferences and tell your choice to the instructors. The results will be the same in both case. 11 ************ 12 13 In this part, we are going to create a ZOO ServicesProvider containing several Services 14 based on the OGR C API or on the OGR Python module, which have also been placed in the 15 ZOO installation on OSGeoLive. The intended goal is to use OGR and its GEOS based simple 16 spatial functions as WPS Services. 17 18 We will first start with the Boundary spatial function, which will be explained, codded 19 and tested gradually as a ZOO Service. The same procedure will then be used to enable 20 the Buffer, Centroid and Convex Hull functions. Once done, some multiple geometries processes 21 such as Intersection, Union, Difference and Symetric Difference will be implemented through 22 an `exercise <./exercise.html>`__ at the end of the workshop. 23 24 As already said in the introduction, you have the choice to code your service in C or 25 Python (or both!) during this workshop. Explanations will be based on the C part, but 26 will be very helpful for those who will choose Python. Please decide according to your 27 habits and preferences and tell your choice to the instructors. The results will be the 28 same in both case. 18 29 19 30 Preparing ZOO metadata file 20 ****************************** 21 22 A ZOO Service is a combination of a ZOO metadata file (``.zcfg``) and the runtime module for the corresponding implementation, which is commonly called ZOO Service Provider. We will first prepare a ``.zcfg`` file step-by-step. Please open your preferred text editor and edit a file named ``Boundary.zcfg`` in your ``/home/user/zoows/sources/zoo-services/ws_sp`` directory. First, you need to name the service between brackets at the top of the file, as the following 31 *************************** 32 33 A ZOO Service is a combination of a ZOO metadata file (``.zcfg``) and the runtime module 34 for the corresponding implementation, which is commonly called ZOO Service Provider. We 35 will first prepare a ``.zcfg`` file step-by-step. Please open your preferred text editor 36 and edit a file named ``Boundary.zcfg`` in your ``/home/user/zoows/sources/zoo-services/ws_sp`` 37 directory. First, you need to name the service between brackets at the top of the file, as the 38 following 23 39 24 40 :: … … 26 42 [Boundary] 27 43 28 This name is very important, it is the name of the Service and so the name of the function defined in the Services Provider. A title and a brief abstract must then be added to inform clients on what the service can do: 44 This name is very important, it is the name of the Service and so the name of the function 45 defined in the Services Provider. A title and a brief abstract must then be added to inform 46 clients on what the service can do: 29 47 30 48 .. code-block:: guess … … 35 53 Such metadata informations will be returned by a GetCapabilities request. 36 54 37 You can also add other specific informations like the ``processVersion``. You can set if your ZOO Service can store its results, by setting the ``storeSupported`` parameter to true or false. You can also decide if the function can be run as a background task and inform on its current status, according to the ``statusSupported`` value : 55 You can also add other specific informations like the ``processVersion``. You can set if 56 your ZOO Service can store its results, by setting the ``storeSupported`` parameter to 57 true or false. You can also decide if the function can be run as a background task and 58 inform on its current status, according to the ``statusSupported`` value : 38 59 39 60 .. code-block:: guess … … 55 76 serviceType=C 56 77 57 In this case you will get an ``ogr_ws_service_provider.zo`` shared library containing the Boundary function, placed in the same directory than ZOO Kernel. 78 In this case you will get an ``ogr_ws_service_provider.zo`` shared library containing 79 the Boundary function, placed in the same directory than ZOO Kernel. 58 80 59 81 Python ServicesProvider Example : … … 74 96 </MetaData> 75 97 76 The main metadata informations have been declared, so you can now define data input which will be used by the ZOO Service. You can define any input needed by the Service. Please note that you can request ZOO Kernel using more data input than defined in the ``.zcfg`` file without any problem, those values will be passed to your service without filtering. In the Boundary Service example, a single polygon will be used as input, the one on which to apply the Boundary function. 77 78 The data input declarations are included in a DataInputs block. They use the same syntax as the Service itself and the input name is between brackets. You can also fill a title, an abstract and a MetaData section for the input. You must set values for the ``minOccurs`` and ``maxOccurs`` parameters, as they will inform ZOO Kernel which parameters are required to be able to run the Service function. 98 The main metadata informations have been declared, so you can now define data input 99 which will be used by the ZOO Service. You can define any input needed by the Service. 100 Please note that you can request ZOO Kernel using more data input than defined in 101 the ``.zcfg`` file without any problem, those values will be passed to your service 102 without filtering. In the Boundary Service example, a single polygon will be used as 103 input, the one on which to apply the Boundary function. 104 105 The data input declarations are included in a DataInputs block. They use the same 106 syntax as the Service itself and the input name is between brackets. You can also 107 fill a title, an abstract and a MetaData section for the input. You must set values 108 for the ``minOccurs`` and ``maxOccurs`` parameters, as they will inform ZOO Kernel 109 which parameters are required to be able to run the Service function. 79 110 80 111 .. code-block:: none … … 90 121 91 122 92 The metadata defines what type of data the Service supports. In the Boundary example, the input polygon can be provided as a GML file or as a JSON string. Next step is thus to define the default and supported input formats. Both formats should be declared in a LitteralData or ComplexData block depending on their types. For this first example we will use ComplexData blocks only. 123 The metadata defines what type of data the Service supports. In the Boundary example, 124 the input polygon can be provided as a GML file or as a JSON string. Next step is 125 thus to define the default and supported input formats. Both formats should be declared 126 in a LitteralData or ComplexData block depending on their types. For this first example 127 we will use ComplexData blocks only. 93 128 94 129 .. code-block:: guess … … 130 165 131 166 132 Once the ZOO metadata file is modified, you have to copy it in the same directory than your ZOO Kernel (so in your case ``/usr/lib/cgi-bin``). Then you should be able to run the following request : 167 Once the ZOO metadata file is modified, you have to copy it in the same directory 168 than your ZOO Kernel (so in your case ``/usr/lib/cgi-bin``). Then you should be 169 able to run the following request : 133 170 134 171 http://localhost/zoo/?Request=DescribeProcess&Service=WPS&Identifier=Boundary&version=1.0.0 … … 141 178 :align: center 142 179 143 Please note that the GetCapabilities and DescribeProcess only need a ``.zcfg`` file to be completed. Simple, isn't it ? At this step, if you request ZOO Kernel for an Execute, you will get an ExceptionReport document as response, looking as the following : 180 Please note that the GetCapabilities and DescribeProcess only need a ``.zcfg`` 181 file to be completed. Simple, isn't it ? At this step, if you request ZOO Kernel 182 for an Execute, you will get an ExceptionReport document as response, looking as the following : 144 183 145 184 .. image:: ./images/Practical-introduction-to-ZOO-6.png … … 157 196 158 197 Implementing single geometry services 159 ***************************************** 160 161 In order to learn the Services Provider creation and deployement step-by-step, we will first focus on creating a very simple one dedicated to the Boundary function. Similar procedure will then be used for the Buffer, Centroid and ConvexHull implementation. 162 163 Your metadata is now ok, so you now must create the code of your Service. The most important thing you must be aware of when coding ZOO Services is that the function corresponding to your Service takes three parameters (internal maps datatype or `Python dictionaries <http://docs.python.org/tutorial/datastructures.html#dictionaries>`__) and returns an integer value representing the status of execution (SERVICE_FAILED or SERVICE_SUCCEEDED): 198 ************************************* 199 200 In order to learn the Services Provider creation and deployement step-by-step, 201 we will first focus on creating a very simple one dedicated to the Boundary function. 202 Similar procedure will then be used for the Buffer, Centroid and ConvexHull implementation. 203 204 Your metadata is now ok, so you now must create the code of your Service. The most 205 important thing you must be aware of when coding ZOO Services is that the function 206 corresponding to your Service takes three parameters (internal maps datatype or 207 `Python dictionaries <http://docs.python.org/tutorial/datastructures.html#dictionaries>`__) 208 and returns an integer value representing the status of execution (SERVICE_FAILED or SERVICE_SUCCEEDED): 164 209 165 210 - ``conf`` : The main environment configuration (corresponding to the ``main.cfg`` content) … … 168 213 169 214 Boundary 170 ====== 215 ======== 171 216 172 217 C Version 173 -------- 174 175 As explained before, ZOO Kernel will pass the parameters to your Service function in a specific datatype called maps. In order to code your Service in C language, you also need to learn how to access this datatype in read/write mode. 176 177 The maps are simple map named linked list containing a name, a content map and a pointer to the next map in the list (or NULL if there is no more map in the list). Here is the datatype definition as you can find in the zoo-kernel/service.h file: 218 --------- 219 220 As explained before, ZOO Kernel will pass the parameters to your Service function 221 in a specific datatype called maps. In order to code your Service in C language, 222 you also need to learn how to access this datatype in read/write mode. 223 224 The maps are simple map named linked list containing a name, a content map and a 225 pointer to the next map in the list (or NULL if there is no more map in the list). 226 Here is the datatype definition as you can find in the zoo-kernel/service.h file: 178 227 179 228 .. code-block:: c … … 185 234 } maps; 186 235 187 The map included in the maps is also a simple linked list and is used to store Key Value Pair values. A map is thus a couple of name and value and a pointer to the next map in the list. Here is the datatype definition you can find in the zoo-kernel/service.h file: 236 The map included in the maps is also a simple linked list and is used to store Key 237 Value Pair values. A map is thus a couple of name and value and a pointer to the 238 next map in the list. Here is the datatype definition you can find in the zoo-kernel/service.h file: 188 239 189 240 .. code-block:: guess … … 196 247 197 248 198 As partially or fully filled datastructures will be passed by the ZOO Kernel to your Services, this means that you do not need to deal with maps creation but directly with existing map, in other words the content of each maps. The first function you need to know is getMapFromMaps (defined in the zoo-kernel/service.h file) which let you access to a specific map of a maps. 249 As partially or fully filled datastructures will be passed by the ZOO Kernel to 250 your Services, this means that you do not need to deal with maps creation but 251 directly with existing map, in other words the content of each maps. The first 252 function you need to know is getMapFromMaps (defined in the zoo-kernel/service.h file) 253 which let you access to a specific map of a maps. 199 254 200 255 This function takes three parameters listed bellow: … … 204 259 - ``key`` : a specific key in the map named name 205 260 206 For example, the following syntax will be used to access the InputPolygon value map of a maps named inputs, your C code should be: 261 For example, the following syntax will be used to access the InputPolygon value 262 map of a maps named inputs, your C code should be: 207 263 208 264 .. code-block:: guess … … 217 273 tmp->value 218 274 219 As you know how to read and access the map fields from a maps, you can now learn how to write in such a datastructure. This is done by using the simple setMapInMaps function once again defined in zoo-kernel/service.h. The setMapInMaps function takes four parameters : 275 As you know how to read and access the map fields from a maps, you can now learn 276 how to write in such a datastructure. This is done by using the simple setMapInMaps 277 function once again defined in zoo-kernel/service.h. The setMapInMaps function takes four parameters : 220 278 221 279 - ``m`` : a maps pointer you want to update, … … 233 291 234 292 235 Please note that the setMapInMaps function is able to create or update an existing map. Indeed, if a map called « value » allready exists, then its value will be updated automatically. 236 237 Even if you will mainly use map from maps during this workshop, you can also add or update values in a map directly using the addToMap function defined in zoo-kernel/service.h. The addToMap function take three paramters : 293 Please note that the setMapInMaps function is able to create or update an existing map. 294 Indeed, if a map called « value » allready exists, then its value will be updated automatically. 295 296 Even if you will mainly use map from maps during this workshop, you can also add or 297 update values in a map directly using the addToMap function defined in zoo-kernel/service.h. 298 The addToMap function take three paramters : 238 299 239 300 - ``m`` : a map pointer you want to update, … … 241 302 - ``v`` : the value you want to set in this map. 242 303 243 This datatype is really important cause it is used in every C based ZOO Services. It is also the same representation used in other languages but using their respectives datatypes. For Example in Python, the dictionaries datatype is used, so manipulation is much easier. 244 245 Here is an example of the correspoding maps datatype used in Python language (this is a summarized version of the main configaration maps): 304 This datatype is really important cause it is used in every C based ZOO Services. It is 305 also the same representation used in other languages but using their respectives datatypes. 306 For Example in Python, the dictionaries datatype is used, so manipulation is much easier. 307 308 Here is an example of the correspoding maps datatype used in Python language (this is a 309 summarized version of the main configaration maps): 246 310 247 311 .. code-block:: guess … … 264 328 As you know how to deal with maps and map, you are ready to code the first ZOO Service by using the OGR Boundary function. 265 329 266 As already said in introduction we will use the MapServer WFS server available on OSGeoLive, so full WFS Response will be used as inputs values. As we will use the simple OGR Geometry functions like `OGR_G_GetBoundary <http://www.gdal.org/ogr/ogr__api_8h.html#a797af4266c02846d52b9cf3207ef958>`__, only the Geometry object will be used rather than a full WFS Response. The first thing to do is to write a function which will extract the geometry definition from the full WFS Response. We will call it createGeometryFromWFS. 330 As already said in introduction we will use the MapServer WFS server available on 331 OSGeoLive, so full WFS Response will be used as inputs values. As we will use the 332 simple OGR Geometry functions like `OGR_G_GetBoundary <http://www.gdal.org/ogr/ogr__api_8h.html#a797af4266c02846d52b9cf3207ef958>`__, 333 only the Geometry object will be used rather than a full WFS Response. The first 334 thing to do is to write a function which will extract the geometry definition 335 from the full WFS Response. We will call it createGeometryFromWFS. 267 336 268 337 Here is the code of such a function: … … 306 375 307 376 308 The only thing we will focus on is the call to the errorException function used in the function body. This function is declared in the zoo-kernel/service_internal.h and defined in zoo-kernel/service_internal.c file. It takes three parameters as follow: 377 The only thing we will focus on is the call to the errorException function used 378 in the function body. This function is declared in the zoo-kernel/service_internal.h 379 and defined in zoo-kernel/service_internal.c file. It takes three parameters as follow: 309 380 310 381 - the main environment maps, … … 312 383 - a char* representing the error code (as defined in the WPS specification – Table 62). 313 384 314 In other words, if the WFS response cannot be parsed properly, then you will return an ExceptionReport document informing the client that a problem occured. 315 316 The function to extract the geometry object from a WFS Response is written, so you can now start defining the Boundary Service. Here is the full code for the Boundary Service: 385 In other words, if the WFS response cannot be parsed properly, then you will return 386 an ExceptionReport document informing the client that a problem occured. 387 388 The function to extract the geometry object from a WFS Response is written, so you 389 can now start defining the Boundary Service. Here is the full code for the Boundary Service: 317 390 318 391 .. code-block:: guess … … 363 436 geometry=createGeometryFromWFS(conf,tmp->value); 364 437 365 Basicaly, if we get an input with a mimeType set to application/json, then we will use our ``OGR_G_CreateGeometryFromJson`` in other case, our ``createGeometryFromWFS`` local function. 366 367 Please note that in some sense the data inputs are not really of the same kind. Indeed as we used directly ``OGR_G_CreateGeometryFromJson`` it means that the JSON string include only the geometry object and not the full GeoJSON string. Nevertheless, you can easily change this code to be able to use a full GeoJSON string, simply by creating a function which will extract the geometry object from the GeoJSON string (using the json-c library for instance, which is also used by the OGR GeoJSON Driver). 368 369 Once you can access the input geometry object, you can use the ``OGR_G_GetBoundary`` function and store the result in the res geometry variable. Then, you only have to store the value in the right format : GeoJSON per default or GML as we declared it as a supported output format. 370 371 Please note that ZOO Kernel will give you pre-filled outputs values, so you will only have to fill the value for the key named value, even if in our example we override the mimeType using the text/plain value rather than the application/json (to show that we can also edit other fields of a map). Indeed, depending on the format requested by the client (or the default one) we will provide JSON or GML representation of the geometry. 438 Basicaly, if we get an input with a mimeType set to application/json, then we will 439 use our ``OGR_G_CreateGeometryFromJson`` in other case, our ``createGeometryFromWFS`` local function. 440 441 Please note that in some sense the data inputs are not really of the same kind. 442 Indeed as we used directly ``OGR_G_CreateGeometryFromJson`` it means that the JSON 443 string include only the geometry object and not the full GeoJSON string. Nevertheless, 444 you can easily change this code to be able to use a full GeoJSON string, simply by 445 creating a function which will extract the geometry object from the GeoJSON string 446 (using the json-c library for instance, which is also used by the OGR GeoJSON Driver). 447 448 Once you can access the input geometry object, you can use the ``OGR_G_GetBoundary`` 449 function and store the result in the res geometry variable. Then, you only have to 450 store the value in the right format : GeoJSON per default or GML as we declared it as a supported output format. 451 452 Please note that ZOO Kernel will give you pre-filled outputs values, so you will 453 only have to fill the value for the key named value, even if in our example we 454 override the mimeType using the text/plain value rather than the application/json 455 (to show that we can also edit other fields of a map). Indeed, depending on the 456 format requested by the client (or the default one) we will provide JSON or GML representation of the geometry. 372 457 373 458 .. code-block:: guess … … 386 471 } 387 472 388 The Boundary ZOO Service is now implemented and you need to compile it to produce a Shared Library. As you just used functions defined in service.h (``getMapFromMaps``, ``setMapInMaps`` and ``addToMap``), you must include this file in your C code. The same requirement is needed to be able to use the ``errorException`` function declared in ``zoo-kernel/service_internal.h``, you also must link your service object file to the ``zoo-kernel/service_internal.o`` in order to use ``errorException`` on runtime. You must then include the required files to access the libxml2 and OGR C-API. 389 390 For the need of the Shared Library, you have to put your code in a block declared as extern "C". The final Service code should be stored in a service.c file located in the root of the Services Provider directory (so in ``/home/zoows/sources/zoo-services/ws_sp``). It should look like this: 473 The Boundary ZOO Service is now implemented and you need to compile it to produce 474 a Shared Library. As you just used functions defined in service.h (``getMapFromMaps``, 475 ``setMapInMaps`` and ``addToMap``), you must include this file in your C code. The 476 same requirement is needed to be able to use the ``errorException`` function declared 477 in ``zoo-kernel/service_internal.h``, you also must link your service object file to 478 the ``zoo-kernel/service_internal.o`` in order to use ``errorException`` on runtime. 479 You must then include the required files to access the libxml2 and OGR C-API. 480 481 For the need of the Shared Library, you have to put your code in a block declared as 482 extern "C". The final Service code should be stored in a service.c file located in 483 the root of the Services Provider directory (so in ``/home/zoows/sources/zoo-services/ws_sp``). 484 It should look like this: 391 485 392 486 .. code-block:: guess … … 402 496 } 403 497 404 The full source code of your Service is now ready and you must produce the corresponding Service Shared Object by compiling the code as a Shared Library. This can be done using the following command: 498 The full source code of your Service is now ready and you must produce the corresponding 499 Service Shared Object by compiling the code as a Shared Library. This can be done using the following command: 405 500 406 501 .. code-block:: guess … … 410 505 Please note that the ``CFLAGS`` and ``LDFLAGS`` environment variables values must be set before. 411 506 412 The ``CFLAGS`` must contain all the requested paths to find included headers, so the path to the directories where the ``ogr_api.h``, ``libxml2`` directory, ``service.h`` and ``service_internal.h`` files are located. Thanks to the OSGeoLive environment, some of the provided tools can be used to retrieve those values : ``xml2-config`` and ``gdal-config``, both used with the ``--cflags`` argument. They will produce the desired paths for you. 413 414 If you follow the instructions to create your ZOO Services Provider main directory in ``zoo-services``, then you should find the ZOO Kernel headers and source tree which is located in the ``../../zoo-kernel`` directory relatively to your current path (``/home/user/zoows/sources/zoo-services/ws_sp``). Note that you can also use a full path to the ``zoo-kernel`` directory but using relative path will let you move your sources tree somewhere else and keep your code compiling using exactly the same command line. So you must add a ``-I../../zoo-kernel`` to your ``CFLAGS`` to make the compiler able to find the ``service.h`` and ``service_internal.h`` files. 507 The ``CFLAGS`` must contain all the requested paths to find included headers, so the 508 path to the directories where the ``ogr_api.h``, ``libxml2`` directory, ``service.h`` 509 and ``service_internal.h`` files are located. Thanks to the OSGeoLive environment, 510 some of the provided tools can be used to retrieve those values : ``xml2-config`` and 511 ``gdal-config``, both used with the ``--cflags`` argument. They will produce the desired paths for you. 512 513 If you follow the instructions to create your ZOO Services Provider main directory in 514 ``zoo-services``, then you should find the ZOO Kernel headers and source tree which is 515 located in the ``../../zoo-kernel`` directory relatively to your current path (``/home/user/zoows/sources/zoo-services/ws_sp``). 516 Note that you can also use a full path to the ``zoo-kernel`` directory but using relative 517 path will let you move your sources tree somewhere else and keep your code compiling 518 using exactly the same command line. So you must add a ``-I../../zoo-kernel`` to your 519 ``CFLAGS`` to make the compiler able to find the ``service.h`` and ``service_internal.h`` files. 415 520 416 521 The full ``CFLAGS`` definition should look like this: … … 420 525 CFLAGS=`gdal-config --cflags` `xml2-config --clfags` -I../../zoo-kernel/ 421 526 422 Once you get the included paths correctly set in your ``CFLAGS`` , it is time to concentrate on the library we have to link against (defined in the ``LDFLAGS`` environment variable). In order to link against the gdal and libxml2 libraries, you can use the same tools than above using the ``--libs`` argument rather than ``--cflags``. The full ``LDFLAGS`` definition must look like this : 527 Once you get the included paths correctly set in your ``CFLAGS`` , it is time to concentrate 528 on the library we have to link against (defined in the ``LDFLAGS`` environment variable). 529 In order to link against the gdal and libxml2 libraries, you can use the same tools than 530 above using the ``--libs`` argument rather than ``--cflags``. The full ``LDFLAGS`` 531 definition must look like this : 423 532 424 533 .. code-block:: guess … … 426 535 LDFLAGS=`gdal-config --libs` `xml2-config --libs` ../../zoo-kernel/service_internal.o 427 536 428 Let's now create a ``Makefile`` which will help you compiling your code over the time. Please write a short ``Makefile`` in the root of your ZOO Services Provider directory, containing the following lines: 537 Let's now create a ``Makefile`` which will help you compiling your code over the time. 538 Please write a short ``Makefile`` in the root of your ZOO Services Provider directory, containing the following lines: 429 539 430 540 .. code-block:: guess … … 440 550 441 551 442 Using this ``Makefile``, you should be able to run ``make`` from your ZOO Service Provider main directory and to get the resulting ``ogr_ws_service_provider.zo`` file located in the ``cgi-env`` directory. 443 444 The metadata file and the ZOO Service Shared Object are now both located in the ``cgi-env`` directory. In order to deploy your new ServicesProvider, you only have to copy the ZOO Service Shared Object and its corresponding metadata file in the directory where ZOO Kernel is located, so in ``/usr/lib/cgi-bin``. You must use a ``sudo`` command to achieve this task: 552 Using this ``Makefile``, you should be able to run ``make`` from your ZOO Service Provider 553 main directory and to get the resulting ``ogr_ws_service_provider.zo`` file located in the ``cgi-env`` directory. 554 555 The metadata file and the ZOO Service Shared Object are now both located in the ``cgi-env`` 556 directory. In order to deploy your new ServicesProvider, you only have to copy the ZOO 557 Service Shared Object and its corresponding metadata file in the directory where ZOO 558 Kernel is located, so in ``/usr/lib/cgi-bin``. You must use a ``sudo`` command to achieve this task: 445 559 446 560 .. code-block:: guess … … 448 562 sudo cp ./cgi-env/* /usr/lib/cgi-bin 449 563 450 You should now understand more clearly the meannings of the ZOO Service Provider source tree ! The ``cgi-env`` directory will let you deploy your new Services or Services Provider in an easy way , simply by copying the whole cgi-env content in your ``cgi-bin`` directory. 451 452 Please note that you can add the following lines to your ``Makefile`` to be able to type ``make install`` directly and to get your new Services Provider available for use from ZOO Kernel: 564 You should now understand more clearly the meannings of the ZOO Service Provider source tree ! 565 The ``cgi-env`` directory will let you deploy your new Services or Services Provider in 566 an easy way , simply by copying the whole cgi-env content in your ``cgi-bin`` directory. 567 568 Please note that you can add the following lines to your ``Makefile`` to be able to type 569 ``make install`` directly and to get your new Services Provider available for use from ZOO Kernel: 453 570 454 571 .. code-block:: none … … 460 577 461 578 Python Version 462 ------------ 463 464 For those using Python to implement their ZOO Services Provider, the full code to copy in ``ogr_ws_service_provider.py`` in ``cgi-env`` directory is shown bellow. Indeed, as Python is an interpreted language, you do not have to compile anything before deploying your service which makes the deployement step much easier: 579 -------------- 580 581 For those using Python to implement their ZOO Services Provider, the full code to copy in 582 ``ogr_ws_service_provider.py`` in ``cgi-env`` directory is shown bellow. Indeed, as 583 Python is an interpreted language, you do not have to compile anything before deploying 584 your service which makes the deployement step much easier: 465 585 466 586 .. code-block:: guess … … 494 614 return 3 495 615 496 We do not dicuss the functions body here as we already gave all the details before and the code was volontary made in a similar way. 616 We do not dicuss the functions body here as we already gave all the details before and 617 the code was volontary made in a similar way. 497 618 498 619 As done before, you only have to copy the ``cgi-env`` files into your ``cgi-bin`` directory: … … 513 634 514 635 Testing the Service using Execute Request 515 ---------------------------------- 636 ----------------------------------------- 516 637 517 638 The simple and unreadable way 518 ^^^^^^^^^^^^^^^^^^^^^^^^^ 519 520 Everybody should now get his own copy of the OGR Boundary Service stored as a ZOO Services Provider called ``ogr_ws_service_provider`` and deployed in the ZOO Kernel tree, so the following Execute request can be used to test the Service: 639 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 640 641 Everybody should now get his own copy of the OGR Boundary Service stored as a ZOO 642 Services Provider called ``ogr_ws_service_provider`` and deployed in the ZOO Kernel 643 tree, so the following Execute request can be used to test the Service: 521 644 522 645 `link <http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Boundary&DataInputs=InputPolygon=Reference@xlink:href=http%3A%2F%2Flocalhost%2Fcgi-bin%2Fmapserv%3Fmap%3D%2Fvar%2Fwww%2Fwfs.map%26SERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dregions%26SRS%3DEPSG%3A4326%26FeatureID%3Dregions.3192>`__ … … 526 649 http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Boundary&DataInputs=InputPolygon=Reference@xlink:href=http%3A%2F%2Flocalhost%2Fcgi-bin%2Fmapserv%3Fmap%3D%2Fvar%2Fwww%2Fwfs.map%26SERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dregions%26SRS%3DEPSG%3A4326%26FeatureID%3Dregions.3192 527 650 528 As you can see in the url above, we use an URLEncoded WFS request to the MapServer WFS server available on OSGeoLive as a ``xlink:href`` key in the DataInputs KVP value, and set the ``InputPolygon`` value to Reference. The corresponding non encoded WFS request is as follow: 651 As you can see in the url above, we use an URLEncoded WFS request to the MapServer 652 WFS server available on OSGeoLive as a ``xlink:href`` key in the DataInputs KVP value, 653 and set the ``InputPolygon`` value to Reference. The corresponding non encoded WFS request is as follow: 529 654 530 655 :: … … 532 657 http://localhost/cgi-bin/mapserv?map=/var/www/wfs.map&SERVICE=WFS&REQUEST=GetFeature&VERSION=1.0.0&typename=regions&SRS=EPSG:4326&featureid=regions.3192 533 658 534 Please note that you can add ``lineage=true`` to the previous request if you need to get information about the input values used to run your Service. Furthermore, you may need to store the ExecuteResponse document of your ZOO Service to re-use it later. In this case you must add ``storeExecuteResponse=true`` to the previous request. Note that is an important thing as the behavior of ZOO Kernel is not exactly the same than when running without this parameter settled to true. Indeed, in such a request, ZOO Kernel will give you an ExecuteResponse document which will contain the attribute statusLocation, which inform the client where the ongoing status or the final ExecuteResponse will be located. 659 Please note that you can add ``lineage=true`` to the previous request if you need 660 to get information about the input values used to run your Service. Furthermore, 661 you may need to store the ExecuteResponse document of your ZOO Service to re-use 662 it later. In this case you must add ``storeExecuteResponse=true`` to the previous 663 request. Note that is an important thing as the behavior of ZOO Kernel is not 664 exactly the same than when running without this parameter settled to true. Indeed, 665 in such a request, ZOO Kernel will give you an ExecuteResponse document which will 666 contain the attribute statusLocation, which inform the client where the ongoing 667 status or the final ExecuteResponse will be located. 535 668 536 669 Here is an example of what the ExecuteResponse would look like in case ``storeExecuteResponse`` was set to true in the request: … … 541 674 :align: center 542 675 543 Then, according to the statusLocation, you should get the ExecuteResponse as you get before using the previous request. Note that can be really useful to provide some caching system for a client application. 544 545 You didn't specify any ResponseForm in the previous request, it is not requested and should return a ResponseDocument per default using the application/json mimeType as you defined in you zcfg file. Nevertheless, you can tell ZOO Kernel what kind of data you want to get in result of your query adding the attribute ``mimeType=text/xml`` to your ``ResponseDocument`` parameter. Adding this parameter to the previous request will give us the result as its GML representation : 676 Then, according to the statusLocation, you should get the ExecuteResponse as you get 677 before using the previous request. Note that can be really useful to provide some 678 caching system for a client application. 679 680 You didn't specify any ResponseForm in the previous request, it is not requested 681 and should return a ResponseDocument per default using the application/json mimeType 682 as you defined in you zcfg file. Nevertheless, you can tell ZOO Kernel what kind of 683 data you want to get in result of your query adding the attribute ``mimeType=text/xml`` 684 to your ``ResponseDocument`` parameter. Adding this parameter to the previous request 685 will give us the result as its GML representation : 546 686 547 687 `link <http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Boundary&DataInputs=InputPolygon=Reference@xlink:href=http%3A%2F%2Flocalhost%2Fcgi-bin%2Fmapserv%3Fmap%3D%2Fvar%2Fwww%2Fwfs.map%26SERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dregions%26SRS%3DEPSG%3A4326%26FeatureID%3Dregions.3192&ResponseDocument=Result@mimeType=text/xml>`__ … … 551 691 http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Boundary&DataInputs=InputPolygon=Reference@xlink:href=http%3A%2F%2Flocalhost%2Fcgi-bin%2Fmapserv%3Fmap%3D%2Fvar%2Fwww%2Fwfs.map%26SERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dregions%26SRS%3DEPSG%3A4326%26FeatureID%3Dregions.3192&ResponseDocument=Result@mimeType=text/xml 552 692 553 As defined by the WPS specifications, you can also ask for a ``RawDataOutput`` to get only the data without the full ``ResponseDocument``. To do that, you only have to replace the ``ResponseDocument`` of your request by ``RawDataOutput``, like in the following request : 693 As defined by the WPS specifications, you can also ask for a ``RawDataOutput`` to 694 get only the data without the full ``ResponseDocument``. To do that, you only have 695 to replace the ``ResponseDocument`` of your request by ``RawDataOutput``, like in 696 the following request : 554 697 555 698 `link <http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Boundary&DataInputs=InputPolygon=Reference@xlink:href=http%3A%2F%2Flocalhost%2Fcgi-bin%2Fmapserv%3Fmap%3D%2Fvar%2Fwww%2Fwfs.map%26SERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dregions%26SRS%3DEPSG%3A4326%26FeatureID%3Dregions.3192&RawDataOutput=Result@mimeType=application/json>`__ … … 559 702 http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Boundary&DataInputs=InputPolygon=Reference@xlink:href=http%3A%2F%2Flocalhost%2Fcgi-bin%2Fmapserv%3Fmap%3D%2Fvar%2Fwww%2Fwfs.map%26SERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dregions%26SRS%3DEPSG%3A4326%26FeatureID%3Dregions.3192&RawDataOutput=Result@mimeType=application/json 560 703 561 Please note that we go back to the default mimeType to directly obtain the JSON string as we will use this kind of request to develop our client application in the next section of this workshop. 562 563 Now, you know how to ask ZOO Kernel to run service in background, ask for ``RawDataOutput`` specifying ``mimeType`` or any specific format to be returned by the Kernel. When you ask for ``ResponseDocument``, you can also specify to the ZOO Kernel that you want the result to be stored on the server side. 564 565 To do such a thing, you have to set the attribute ``asReference`` as true and then the resulting ExecuteResponse will contain a Reference node including the href attribute to let you access the produced file. To be able to handle this, you have to add the extension parameter in your ``DataOutputs`` node in the corresponding ZCFG file. 704 Please note that we go back to the default mimeType to directly obtain the JSON 705 string as we will use this kind of request to develop our client application in 706 the next section of this workshop. 707 708 Now, you know how to ask ZOO Kernel to run service in background, ask for ``RawDataOutput`` 709 specifying ``mimeType`` or any specific format to be returned by the Kernel. When you 710 ask for ``ResponseDocument``, you can also specify to the ZOO Kernel that you want the 711 result to be stored on the server side. 712 713 To do such a thing, you have to set the attribute ``asReference`` as true and then the 714 resulting ExecuteResponse will contain a Reference node including the href attribute 715 to let you access the produced file. To be able to handle this, you have to add the 716 extension parameter in your ``DataOutputs`` node in the corresponding ZCFG file. 566 717 567 718 Here is a sample url which provide such a result: … … 581 732 582 733 Simplification and readability of request 583 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 584 585 As you can see in the simple example we used since the begining of this workshop, it is sometimes hard to write the Execute requests using the GET method as it makes really long and complexe URLs. In the next requests examples, we will thus use the POST XML requests. First , here is the XML request corresponding to the previous Execute we used: 734 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 735 736 As you can see in the simple example we used since the begining of this workshop, 737 it is sometimes hard to write the Execute requests using the GET method as it 738 makes really long and complexe URLs. In the next requests examples, we will 739 thus use the POST XML requests. First , here is the XML request corresponding 740 to the previous Execute we used: 586 741 587 742 .. code-block:: guess … … 607 762 </wps:Execute> 608 763 609 In order to let you easily run the XML requests, a simple HTML form called ``test_services.html`` is available in your ``/var/www`` directory. You can access it using the following link : http://localhost/test_services.html. 610 611 Please open this page in your browser, simply fill the XML request content into the textarea field and click the « run using XML Request » submit button. You will get exactly the same result as when running your Service using the GET request. The screenshot above show the HTML form including the request and the ExecuteResponse document displayed in the iframe at the bottom of the page: 764 In order to let you easily run the XML requests, a simple HTML form called 765 ``test_services.html`` is available in your ``/var/www`` directory. You can 766 access it using the following link : http://localhost/test_services.html. 767 768 Please open this page in your browser, simply fill the XML request content into 769 the textarea field and click the « run using XML Request » submit button. You will 770 get exactly the same result as when running your Service using the GET request. The 771 screenshot above show the HTML form including the request and the ExecuteResponse 772 document displayed in the iframe at the bottom of the page: 612 773 613 774 .. image:: ./images/Practical-introduction-to-ZOO-8.png … … 616 777 :align: center 617 778 618 The xlink:href value is used in the simplest way to deal with such data input. Obviously, you can also use a full JSON string of the geometry, as shown in the following XML Request example : 779 The xlink:href value is used in the simplest way to deal with such data input. Obviously, 780 you can also use a full JSON string of the geometry, as shown in the following XML Request example : 619 781 620 782 .. code-block:: guess … … 643 805 </wps:Execute> 644 806 645 If everything went well, you should get the Boundary of the JSON geometry passed as argument, and so be sure that your Service support both GML and JSON as input data. Note that in the previous request, we added a ``mimeType`` attribute to the ``ComplexData`` node to specify that the input data is not in the default ``text/xml`` mimeType but passed as an ``application/json`` string directly. It is similar to add ``@mimeType=application/json`` as we discussed before. 807 If everything went well, you should get the Boundary of the JSON geometry passed as 808 argument, and so be sure that your Service support both GML and JSON as input data. 809 Note that in the previous request, we added a ``mimeType`` attribute to the 810 ``ComplexData`` node to specify that the input data is not in the default ``text/xml`` 811 mimeType but passed as an ``application/json`` string directly. It is similar to add 812 ``@mimeType=application/json`` as we discussed before. 646 813 647 814 storeExecuteResponse parameter and GetStatus Service 648 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 649 650 If you go in your local ``/home/user/zoows/sources/zoo-services/utils/status``, you'll find the code for a ServiceProvider which will provide the GetStatus service and the longProcess one. The last is a simple example to learn how to use the status variable from lenv section of the main configuration maps and the updateStatus function you have to call to take your status value into account. The main service provider is the GetStatus one, it is able to give you information about the current status value from a service running in background mode. 651 652 You have to know that the ZOO Kernel will detect the presence of the GetStatus service and if it is available it will then return the link the corresponding Execute request. 653 654 So now you will deploy the GetStatus and longProcess service on your local environment. As for each services, you shall be able to deploy the services simply by copying the cgi-env directory into your Apache ``cgi-bin`` directory. You can use the following command : 815 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 816 817 If you go in your local ``/home/user/zoows/sources/zoo-services/utils/status``, you'll 818 find the code for a ServiceProvider which will provide the GetStatus service and the 819 longProcess one. The last is a simple example to learn how to use the status variable 820 from lenv section of the main configuration maps and the updateStatus function you 821 have to call to take your status value into account. The main service provider is 822 the GetStatus one, it is able to give you information about the current status value 823 from a service running in background mode. 824 825 You have to know that the ZOO Kernel will detect the presence of the GetStatus service 826 and if it is available it will then return the link the corresponding Execute request. 827 828 So now you will deploy the GetStatus and longProcess service on your local environment. 829 As for each services, you shall be able to deploy the services simply by copying the 830 cgi-env directory into your Apache ``cgi-bin`` directory. You can use the following command : 655 831 656 832 .. code-block:: guess … … 658 834 sudo cp ~user/zoows/sources/zoo-services/utils/status/cgi-env/*{zcfg,zo} /usr/lib/cgi-bin 659 835 660 For simple Services it is the right way to deploy Service Providers. But in this specific case you'll have also to add some special parameter in the main section of you main configuration file and to copy an xsl file used to replace on the fly in the ResponseDocument the percentCompleted attribute of the ProcessStarted node returned by the GetStatus service. 836 For simple Services it is the right way to deploy Service Providers. But in this specific 837 case you'll have also to add some special parameter in the main section of you main 838 configuration file and to copy an xsl file used to replace on the fly in the ResponseDocument 839 the percentCompleted attribute of the ProcessStarted node returned by the GetStatus service. 661 840 662 841 So first edit you ``main.cfg`` file to add the following lines in your main section : … … 667 846 dataPath=/var/www/data 668 847 669 Here you define the path where the service is able to find the xsl file, specified in the dataPath parameter. You also tell the ZOO Kernel that you want to use the rewriteUrl we defined in the previous section. 670 671 To finish your deployment, you'll have now to copy the xsl file in the defined dataPath directory. You can use the following command : 848 Here you define the path where the service is able to find the xsl file, specified in the 849 dataPath parameter. You also tell the ZOO Kernel that you want to use the rewriteUrl we 850 defined in the previous section. 851 852 To finish your deployment, you'll have now to copy the xsl file in the defined dataPath 853 directory. You can use the following command : 672 854 673 855 .. code-block:: guess … … 686 868 :align: center 687 869 688 If you poll the statusLocation url provider in the answer you'll then be able to view the evolution of the percentCompleted attribute value growing, like you can see in the following screenshot. 870 If you poll the statusLocation url provider in the answer you'll then be able to view 871 the evolution of the percentCompleted attribute value growing, like you can see in the following screenshot. 689 872 690 873 .. image:: ./images/Practical-introduction-to-ZOO-10.png … … 697 880 698 881 Creating Services for other functions (ConvexHull and Centroid) 699 ======================================== 700 701 As the Boundary sample service code is available, you can now easily add ConvexHull and Centroid functions as they take exactly the same number of arguments : Only one geometry. The details for implementing and deploying the ConvexHull Service are provided bellow, and we will let you do the same thing for the Centroid one. 882 =============================================================== 883 884 As the Boundary sample service code is available, you can now easily add ConvexHull and 885 Centroid functions as they take exactly the same number of arguments : Only one geometry. 886 The details for implementing and deploying the ConvexHull Service are provided bellow, 887 and we will let you do the same thing for the Centroid one. 702 888 703 889 C Version 704 -------- 890 --------- 705 891 706 892 Please add first the following code to the service.c source code : … … 743 929 744 930 745 This new code is exactly the same as for the Boundary Service. The only thing we modified is the line where the `OGR_G_ConvexHull <http://www.gdal.org/ogr/ogr__api_8h.html#7a93026cfae8ee6ce25546dba1b2df7d>`__ function is called (rather than the OGR_G_GetBoundary you used before). It is better to not copy and paste the whole function and find a more generic way to define your new Services as the function body will be the same in every case. The following generic function is proposed to make things simpler: 931 This new code is exactly the same as for the Boundary Service. The only thing we modified 932 is the line where the `OGR_G_ConvexHull <http://www.gdal.org/ogr/ogr__api_8h.html#7a93026cfae8ee6ce25546dba1b2df7d>`__ 933 function is called (rather than the OGR_G_GetBoundary you used before). It is better to not copy 934 and paste the whole function and find a more generic way to define your new Services as the 935 function body will be the same in every case. The following generic function is proposed to make things simpler: 746 936 747 937 .. code-block:: guess … … 782 972 } 783 973 784 Then, a function pointer called myFunc rather than the full function name can be used. This way we can re-implement our Boundary Service this way: 974 Then, a function pointer called myFunc rather than the full function name can be used. 975 This way we can re-implement our Boundary Service this way: 785 976 786 977 .. code-block:: guess … … 790 981 } 791 982 792 Using this applyOne local function defined in the service.c source code, we can define other Services this way: 983 Using this applyOne local function defined in the service.c source code, we can define 984 other Services this way: 793 985 794 986 .. code-block:: guess … … 818 1010 } 819 1011 820 To deploy your Services, you only have to copy the ``Boundary.zcfg`` metadata file from your cgi-env directory as ``ConvexHull.zcfg`` and ``Centroid.zcfg``. Then, you must rename the Service name on the first line to be able to run and test the Execute request in the same way you did before. You only have to set the Identifier value to ConvexHull or Centroid in your request depending on the Service you want to run. 821 822 Note here that the GetCapabilities and DescribeProcess requests will return odd results as we didn't modified any metadata informations, you can edit the ``.zcfg`` files to set correct values. By the way it can be used for testing purpose, as the input and output get the same name and default/supported formats. 1012 To deploy your Services, you only have to copy the ``Boundary.zcfg`` metadata file from 1013 your cgi-env directory as ``ConvexHull.zcfg`` and ``Centroid.zcfg``. Then, you must 1014 rename the Service name on the first line to be able to run and test the Execute request 1015 in the same way you did before. You only have to set the Identifier value to ConvexHull 1016 or Centroid in your request depending on the Service you want to run. 1017 1018 Note here that the GetCapabilities and DescribeProcess requests will return odd results 1019 as we didn't modified any metadata informations, you can edit the ``.zcfg`` files to set 1020 correct values. By the way it can be used for testing purpose, as the input and output 1021 get the same name and default/supported formats. 823 1022 824 1023 Python Version 825 ------------ 1024 -------------- 826 1025 827 1026 .. code-block:: guess … … 843 1042 844 1043 845 Once again, you can easily copy and paste the function for Boundary and simply modify the line where the Geometry method was called. Nevertheless, as we did for the C language we will give you a simple way to get things more generic. 846 847 First of all, the first step which consists in extracting the InputPolygon Geometry as it will be used in the same way in each Service functions, so we will first create a function which will do that for us. The same thing can also be done for filling the output value, so we will define another function to do that automaticaly. Here is the code of this two functions (extractInputs and outputResult) : 1044 Once again, you can easily copy and paste the function for Boundary and simply modify 1045 the line where the Geometry method was called. Nevertheless, as we did for the C language 1046 we will give you a simple way to get things more generic. 1047 1048 First of all, the first step which consists in extracting the InputPolygon Geometry as 1049 it will be used in the same way in each Service functions, so we will first create a 1050 function which will do that for us. The same thing can also be done for filling the 1051 output value, so we will define another function to do that automaticaly. Here is the 1052 code of this two functions (extractInputs and outputResult) : 848 1053 849 1054 .. code-block:: guess … … 902 1107 903 1108 Create the Buffer Service 904 ================ 905 906 We can now work on the Buffer Service, which takes more arguments than the other ones. Indeed, the code is a bit different from the one used to implement the Boundary, ConvexHull and Centroid Services. 907 908 The Buffer service also takes an input geometry, but uses a BufferDistance parameter. It will also allow you to define LitteralData block as the BufferDistance will be simple integer value. The read access to such kind of input value is made using the same function as used before. 1109 ========================= 1110 1111 We can now work on the Buffer Service, which takes more arguments than the other ones. 1112 Indeed, the code is a bit different from the one used to implement the Boundary, ConvexHull and Centroid Services. 1113 1114 The Buffer service also takes an input geometry, but uses a BufferDistance parameter. 1115 It will also allow you to define LitteralData block as the BufferDistance will be 1116 simple integer value. The read access to such kind of input value is made using the 1117 same function as used before. 909 1118 910 1119 C Version 911 -------- 912 913 If you go back to the first Boundary Service source code, you should not find the following very complicated. Indeed, you simply have to add the access of the BufferDistance argument and modify the line whenthe `OGR_G_Buffer <http://www.gdal.org/ogr/ogr__api_8h.html#1ca0bd5c0fcb4b1af3c3973e467b0ec0>`__ must be called (instead of OGR_G_GetBoundary). Here is the ful lcode : 1120 --------- 1121 1122 If you go back to the first Boundary Service source code, you should not find the 1123 following very complicated. Indeed, you simply have to add the access of the 1124 BufferDistance argument and modify the line whenthe `OGR_G_Buffer <http://www.gdal.org/ogr/ogr__api_8h.html#1ca0bd5c0fcb4b1af3c3973e467b0ec0>`__ 1125 must be called (instead of OGR_G_GetBoundary). Here is the ful lcode : 914 1126 915 1127 .. code-block:: guess … … 950 1162 } 951 1163 952 The new code must be inserted in your service.c file and need to be recompiled and replace the older version of your ZOO Service Provider in the /usr/lib/cgi-bin/ directory. You must of course place the corresponding ZOO Metadata File in the same directory. 953 954 As we explained before, ZOO Kernel is permissive in the sense that you can pass more arguments than defined in you zcfg file, so let's try using a copy of the ``Boundary.zcfg`` file renamed as ``Buffer.zcfg`` and containing the Buffer identifier. Then, please test your service using an Execute request as you did before. You will obtain the buffer result in a ResponseDocument. 955 956 You may have noted that the above code check if a BufferDistance input was passed to the service. If not, we will use 1 as the default value, which explains why you do not have to use one more input to your previous queries. 957 958 You can change the BufferDistance value used by your Service to compute Buffer of your geometry by adding it to the DataInputs value in your request. Note that using KVP syntaxe, each DataInputs are separated by a semicolon. 1164 The new code must be inserted in your service.c file and need to be recompiled and 1165 replace the older version of your ZOO Service Provider in the /usr/lib/cgi-bin/ directory. 1166 You must of course place the corresponding ZOO Metadata File in the same directory. 1167 1168 As we explained before, ZOO Kernel is permissive in the sense that you can pass more 1169 arguments than defined in you zcfg file, so let's try using a copy of the ``Boundary.zcfg`` 1170 file renamed as ``Buffer.zcfg`` and containing the Buffer identifier. Then, please 1171 test your service using an Execute request as you did before. You will obtain the 1172 buffer result in a ResponseDocument. 1173 1174 You may have noted that the above code check if a BufferDistance input was passed 1175 to the service. If not, we will use 1 as the default value, which explains why 1176 you do not have to use one more input to your previous queries. 1177 1178 You can change the BufferDistance value used by your Service to compute Buffer 1179 of your geometry by adding it to the DataInputs value in your request. Note that 1180 using KVP syntaxe, each DataInputs are separated by a semicolon. 959 1181 960 1182 So, the previous request: … … 970 1192 DataInputs=InputPolygon=Reference@xlink:href=http%3A%2F%2Flocalhost%2Fcgi-bin%2Fmapserv%3FSERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dregions%26SRS%3DEPSG%3A4326%26FeatureID%3Dregions.3192;BufferDistance=2 971 1193 972 Setting BufferDistance value to 2 would give you a different result, then don't pass any other parameter as we defined 1 as the default value in the source code. 1194 Setting BufferDistance value to 2 would give you a different result, then don't 1195 pass any other parameter as we defined 1 as the default value in the source code. 973 1196 974 1197 Here you can find the same query in XML format to use from the http://localhost/test_services.html HTML form : … … 1003 1226 1004 1227 Python Version 1005 ------------ 1006 1007 As we already defined the utility functions createGeometryFromWFS and outputResult, the code is as simple as this: 1228 -------------- 1229 1230 As we already defined the utility functions createGeometryFromWFS and outputResult, 1231 the code is as simple as this: 1008 1232 1009 1233 .. code-block:: guess … … 1021 1245 return 3 1022 1246 1023 We simply added the use of inputs["BufferDistance"]["value"] as arguments of the Geometry instance Buffer method. Once you get this code added to your ogr_ws_service_provider.py file, simply copy it in the ZOO Kernel directory (or type make install from your ZOO Service Provider root directory). Note that you also need the ``Buffer.zcfg`` file detailled in the next section. 1247 We simply added the use of inputs["BufferDistance"]["value"] as arguments of the 1248 Geometry instance Buffer method. Once you get this code added to your ogr_ws_service_provider.py 1249 file, simply copy it in the ZOO Kernel directory (or type make install from your ZOO Service 1250 Provider root directory). Note that you also need the ``Buffer.zcfg`` file detailled in the next section. 1024 1251 1025 1252 The Buffer MetadataFile file 1026 ---------------------- 1027 1028 You must add BufferDistance to the Service Metadata File to let clients know that this Service supports this parameter. To do this, please copy your orginal ``Boundary.zcfg`` file as ``Buffer.zcfg`` and add the following lines to the DataInputs block : 1253 ---------------------------- 1254 1255 You must add BufferDistance to the Service Metadata File to let clients know that 1256 this Service supports this parameter. To do this, please copy your orginal ``Boundary.zcfg`` 1257 file as ``Buffer.zcfg`` and add the following lines to the DataInputs block : 1029 1258 1030 1259 .. code-block:: none … … 1046 1275 </LiteralData> 1047 1276 1048 Note that as minOccurs is set to 0 which means that the input parameter is optional and don't have to be passed. You must know that ZOO Kernel will pass the default value to the Service function for an optional parameter with a default value set. 1277 Note that as minOccurs is set to 0 which means that the input parameter is optional 1278 and don't have to be passed. You must know that ZOO Kernel will pass the default 1279 value to the Service function for an optional parameter with a default value set. 1049 1280 1050 1281 You can get a full copy of the ``Buffer.zcfg`` file here :
Note: See TracChangeset
for help on using the changeset viewer.
