Changeset 262


Ignore:
Timestamp:
Jul 15, 2011, 8:03:05 PM (13 years ago)
Author:
jmckenna
Message:

fix formatting of workshop files

Location:
trunk/docs/workshop/2010
Files:
5 edited

Legend:

Unmodified
Added
Removed
  • trunk/docs/workshop/2010/building_wps_client_using_ol.txt

    r256 r262  
    22
    33Building a WPS client using OpenLayers
    4 ###############################
     4######################################
    55
    66.. contents:: Table of Contents
     
    88    :backlinks: top
    99
    10 The next step of our workshop is to connect to the OGR Services we have created from an OpenLayers map. This will allow to apply single or multiple geometries processes on user-selected polygons and to display the new generated geometries.
     10The next step of our workshop is to connect to the OGR Services we have created
     11from an OpenLayers map. This will allow to apply single or multiple geometries
     12processes on user-selected polygons and to display the new generated geometries.
    1113
    1214Creating a simple map showing the dataset as WMS
    13 ******************************************************
    14 
    15 OpenLayers is also included in OSGeoLive default distribution, so it is convenient to use it for our needs. Please open ``/var/www/zoo-ogr.html`` using your favorite text editor and paste the following HTML snippet:
     15************************************************
     16
     17OpenLayers is also included in OSGeoLive default distribution, so it is convenient
     18to use it for our needs. Please open ``/var/www/zoo-ogr.html`` using your favorite
     19text editor and paste the following HTML snippet:
    1620
    1721.. code-block:: guess
     
    3236    </html>
    3337
    34 The following JavaScript code must then be added in a ``<script></script>`` section within the ``<head>`` one. This will setup a map showing the japanese regions data as WMS.
     38The following JavaScript code must then be added in a ``<script></script>`` section within the
     39``<head>`` one. This will setup a map showing the japanese regions data as WMS.
    3540
    3641.. code-block:: guess
     
    6570    }
    6671
    67 Once done, please save your HTML file as ``zoo-ogr.html`` in your workshop directory, then copy it in ``/var/www`` and visualize it with your favorite Web browser using this link :  ``http://localhost/zoo-ogr.html``. You should obtain a map centered on the Japan with the WMS layer activated.
     72Once done, please save your HTML file as ``zoo-ogr.html`` in your workshop directory,
     73then copy it in ``/var/www`` and visualize it with your favorite Web browser using this link : 
     74``http://localhost/zoo-ogr.html``. You should obtain a map centered on the Japan with the WMS layer activated.
    6875
    6976.. image:: ./images/OL-JP-1.png
     
    7380
    7481Fetching the data layer as WFS and adding selection controls
    75 ****************************************************************
    76 
    77 Before accessing the displayed data via WFS, you first have to create new vector layers dedicated to host the several interactions we are going to create. Please add the following lines within the ``init()`` function, and do not forget to add the newly created layer in the map.addLayers method:
     82************************************************************
     83
     84Before accessing the displayed data via WFS, you first have to create new vector layers
     85dedicated to host the several interactions we are going to create. Please add the following
     86lines within the ``init()`` function, and do not forget to add the newly created layer in
     87the map.addLayers method:
    7888
    7989.. code-block:: guess
     
    96106    map.addLayers([layer, select, hover, multi]);
    97107
    98 Then, you can now access the data by creating new controls to select polygons, as the following. Please note that ``OpenLayers.Protocol.WFS.fromWMSLayer`` is used to access geometries and that several state of selection are declared and append to the control variable.
     108Then, you can now access the data by creating new controls to select polygons, as the
     109following. Please note that ``OpenLayers.Protocol.WFS.fromWMSLayer`` is used to access
     110geometries and that several state of selection are declared and append to the control variable.
    99111
    100112.. code-block:: guess
     
    122134    control.activate();
    123135
    124 Please save your HTML file again. You should now be able to select a polygon only by clicking on it. The selected polygon should appear in blue color.
     136Please save your HTML file again. You should now be able to select a polygon only by
     137clicking on it. The selected polygon should appear in blue color.
    125138
    126139.. image:: ./images/OL-JP-2.png
     
    130143
    131144Calling the single geometry services from JavaScript
    132 *******************************************************
    133 
    134 Now that everything is setup, we can go on and call our OGR ZOO services with JavaScript. Please add the following lines after the ``init()`` function, which will call the single geometry processes. You can notice that we use a specific ``parseMapServerId`` function which let us remove the unecessary white space returned as fid value.
     145****************************************************
     146
     147Now that everything is setup, we can go on and call our OGR ZOO services with JavaScript.
     148Please add the following lines after the ``init()`` function, which will call the single
     149geometry processes. You can notice that we use a specific ``parseMapServerId`` function
     150which let us remove the unecessary white space returned as fid value.
    135151
    136152.. code-block:: guess
     
    175191
    176192
    177 Then, some specific buttons must be added in the HTML, in order to be able to call the different processes we just declared. You can add them on top of the map by writing the following lines before the ``<div id="map"></div>``.
     193Then, some specific buttons must be added in the HTML, in order to be able to call
     194the different processes we just declared. You can add them on top of the map by writing
     195the following lines before the ``<div id="map"></div>``.
    178196
    179197.. code-block:: guess
     
    198216    </div>
    199217
    200 Save your HTML file again. You should now be able to select a polygon and to launch a Buffer, ConvexHull, Boundary or Centroid on it by clicking one of the button. The result of the process should appear as GeoJSON layer on the map, in orange color.
     218Save your HTML file again. You should now be able to select a polygon and to launch a Buffer,
     219ConvexHull, Boundary or Centroid on it by clicking one of the button. The result of the
     220process should appear as GeoJSON layer on the map, in orange color.
    201221
    202222.. image:: ./images/OL-JP-3.png
     
    206226
    207227Calling the multiples geometries processes from JavaScript
    208 **************************************************************
    209 
    210 Using the same technique, you can now write a function dedicated to the multiple geometries processes. Please add the following lines after the ``simpleProcessing()`` function, we will guide you during the exercise in section 5 on how to create such a function.
     228**********************************************************
     229
     230Using the same technique, you can now write a function dedicated to the multiple geometries
     231processes. Please add the following lines after the ``simpleProcessing()`` function, we will
     232guide you during the exercise in section 5 on how to create such a function.
    211233
    212234.. code-block:: guess
     
    261283    }
    262284
    263 Note that this time we didn't use the GET method to request the ZOO Kernel but a XML POST. We did that because if you use the GET method you will get error due to the HTTP GET method limitation based on the length of your request. Using JSON string representing the geometry will make your request longer.
    264 
    265 Once you get the functions to call your multiple geometries processes, you' must add some buttons to fire the request call. Here is the HTML code to add to your current ``zoo-ogr.html`` file :
     285Note that this time we didn't use the GET method to request the ZOO Kernel but a XML POST.
     286We did that because if you use the GET method you will get error due to the HTTP GET method
     287limitation based on the length of your request. Using JSON string representing the geometry
     288will make your request longer.
     289
     290Once you get the functions to call your multiple geometries processes, you' must add some
     291buttons to fire the request call. Here is the HTML code to add to your current ``zoo-ogr.html`` file :
    266292
    267293.. code-block:: guess
     
    283309    </ul>
    284310
    285 Please reload the page. You should then be able to run your multiple geometries services and you should get results displayed in red as shown by the following screenshots :
     311Please reload the page. You should then be able to run your multiple geometries services and
     312you should get results displayed in red as shown by the following screenshots :
    286313
    287314
     
    299326   :height: 140px
    300327   
    301 It seems that something is missing in your Services Provider to get the same results … The multiple geometries Services ! This is what we are going to do together in the next section.
     328It seems that something is missing in your Services Provider to get the same results …
     329The multiple geometries Services ! This is what we are going to do together in the next section.
  • trunk/docs/workshop/2010/exercise.txt

    r256 r262  
    22
    33Exercise
    4 #######
     4########
    55
    6 You know everything now about writting zcfg matadata files and get short pieces of code in ``service.c`` or ``ogr_service_provider.py`` depending if you choosen C or Python programming language respectively.
     6You know everything now about writting zcfg matadata files and get short pieces
     7of code in ``service.c`` or ``ogr_service_provider.py`` depending if you choosen
     8C or Python programming language respectively.
    79
    810The goal of this exercise is to implement the following multiple geometries services :
     
    1416
    1517C version
    16 **********
     18*********
    1719
    18 Your are now invited to edit the source.c file you have created during this workshop to add the multiple geometries, using the following OGR C-API functions :
     20Your are now invited to edit the source.c file you have created during this workshop
     21to add the multiple geometries, using the following OGR C-API functions :
    1922
    2023  - `OGR_G_Intersection <http://www.gdal.org/ogr/ogr__api_8h.html#5a271b5c7b72994120e7a6bbc7e7e5cb>`__ (OGRGeometryH, OGRGeometryH)
     
    2326  - `OGR_G_SymmetricDifference <http://www.gdal.org/ogr/ogr__api_8h.html#d6dacf495617a230c6f19950bc415f17>`__ (OGRGeometryH, OGRGeometryH)
    2427
    25 You can use the ``Boundary.zcfg`` file as example, rename the InputPolygon input to ``InputEntity1`` and add a similar input named ``IntputEntity2``. You are invited to update other values in the ZOO Metadata File to set the proper metadata informations.
     28You can use the ``Boundary.zcfg`` file as example, rename the InputPolygon input
     29to ``InputEntity1`` and add a similar input named ``IntputEntity2``. You are
     30invited to update other values in the ZOO Metadata File to set the proper
     31metadata informations.
    2632
    2733Python Version
    28 ****************
     34**************
    2935
    30 Your are invited to edit the ``ogr_ws_service_provider.py`` file you created during this workshop to add the multiple geometries using the following ``osgeo.ogr`` Geometry methods applied on the first Geometry instance :
     36Your are invited to edit the ``ogr_ws_service_provider.py`` file you created
     37during this workshop to add the multiple geometries using the following
     38``osgeo.ogr`` Geometry methods applied on the first Geometry instance :
    3139
    3240  - Intersection(Geometry)
     
    3543  - SymmetricDifference(Geometry)
    3644
    37 You can once again use the ``Boundary.zcfg`` file as example, rename the ``InputPolygon`` input to ``InputEntity1`` and add a similar input named ``IntputEntity2``. You are invited to update other values in the ZOO metadata file to set the proper metadata informations.
     45You can once again use the ``Boundary.zcfg`` file as example, rename the ``InputPolygon``
     46input to ``InputEntity1`` and add a similar input named ``IntputEntity2``. You are
     47invited to update other values in the ZOO metadata file to set the proper metadata
     48informations.
    3849
    3950Testing your services
    40 ***********************
     51*********************
    4152
    42 Once the multiple geometries Services are deployed on your local environment, please reload the ``zoo-ogr.html`` file created during the previous section from your browser and test your brand new ZOO Services.
     53Once the multiple geometries Services are deployed on your local environment,
     54please reload the ``zoo-ogr.html`` file created during the previous section
     55from your browser and test your brand new ZOO Services.
    4356
  • trunk/docs/workshop/2010/introduction.txt

    r256 r262  
    22
    33Introduction
    4 ##########
     4############
    55
    66.. contents:: Table of Contents
     
    99
    1010What is ZOO ?
    11 ***************
     11*************
    1212
    1313ZOO is a WPS (Web Processing Service) open source project recently released under a `MIT/X-11 <http://zoo-project.org/trac/wiki/Licence>`__ style license. It provides an OGC WPS compliant developer-friendly framework to create and chain WPS Web services. ZOO is made of three parts:
     
    1717  - `ZOO API <http://zoo-project.org/trac/wiki/ZooWebSite/ZOOAPI/Introduction>`__ : A server-side JavaScript API able to call and chain the ZOO Services, which makes the development and chaining processes easier.
    1818
    19 ZOO is designed to make the service development easier by providing a powerful system able to understand and execute WPS compliant queries. It supports several programming languages, thus allowing you to create Web Services in your favorite one and from an already existing code. Further information on the project is available on the  `ZOO Project official website <http://www.zoo-project.org/>`__ .
     19ZOO is designed to make the service development easier by providing a powerful system
     20able to understand and execute WPS compliant queries. It supports several programming
     21languages, thus allowing you to create Web Services in your favorite one and from an
     22already existing code. Further information on the project is available on the 
     23`ZOO Project official website <http://www.zoo-project.org/>`__ .
    2024
    2125How does ZOO works ?
    22 ************************
     26********************
    2327
    24 ZOO is based on a 'WPS Service Kernel' which constitutes the ZOO's core system (aka ZOO Kernel). The latter is able to load dynamic libraries and to handle them as on-demand Web services. The ZOO Kernel is written in C language, but supports several common programming languages for creating ZOO Services.
     28ZOO is based on a 'WPS Service Kernel' which constitutes the ZOO's core system
     29(aka ZOO Kernel). The latter is able to load dynamic libraries and to handle them
     30as on-demand Web services. The ZOO Kernel is written in C language, but supports
     31several common programming languages for creating ZOO Services.
    2532
    26 A ZOO Service is a link composed of a ZOO metadata file (.zcfg) and the code for the corresponding implementation. The metadata file describes all the available functions which can be called using a WPS Exec Request, as well as the desired input/output. Services contain the algorithms and functions, and can now be implemented in C/C++, Fortran, Java, Python, Perl, PHP and JavaScript.
     33A ZOO Service is a link composed of a ZOO metadata file (.zcfg) and the code for
     34the corresponding implementation. The metadata file describes all the available
     35functions which can be called using a WPS Exec Request, as well as the desired
     36input/output. Services contain the algorithms and functions, and can now be
     37implemented in C/C++, Fortran, Java, Python, Perl, PHP and JavaScript.
    2738
    28 ZOO Kernel works with Apache and can communicate with cartographic engines and Web mapping clients. It simply adds the WPS support to your spatial data infrastructure and your Web mapping application. It can use every GDAL/OGR supported formats as input data and create suitable vector or raster output for your cartographic engine and/or your web-mapping client application.
     39ZOO Kernel works with Apache and can communicate with cartographic engines and
     40Web mapping clients. It simply adds the WPS support to your spatial data infrastructure
     41and your Web mapping application. It can use every GDAL/OGR supported formats as input
     42data and create suitable vector or raster output for your cartographic engine and/or
     43your web-mapping client application.
    2944
    3045What are we going to do in this workshop?
    31 *********************************************
     46*****************************************
    3247
    33 This workshop aims to present the ZOO Project and its features, and to explain its capabilities regarding the  `OGC WPS 1.0.0 specification <http://www.opengeospatial.org/standards/wps>`__. The participants will learn in 3 hours how to use ZOO Kernel, how to create ZOO Services and their configuration files and finally how to link the created Service with a client-side webmapping application. A pre-compiled ZOO 1.0 version is provided inside OSGeoLive, the OSGeo official Live DVD. For the sack of simplicity, an OSGeoLive Virtual Machine image disk is already installed on your computers. This will be used during this workshop, so the participants won't have to compile and install ZOO Kernel manually. Running and testing ZOO Kernel from this OSGeoLive image disk is thus the first step of the workshop, and every participants should get a working ZOO Kernel in less than 30 minutes.
     48This workshop aims to present the ZOO Project and its features, and to explain its
     49capabilities regarding the  `OGC WPS 1.0.0 specification <http://www.opengeospatial.org/standards/wps>`__.
     50The participants will learn in 3 hours how to use ZOO Kernel, how to create
     51ZOO Services and their configuration files and finally how to link the created
     52Service with a client-side webmapping application. A pre-compiled ZOO 1.0 version
     53is provided inside OSGeoLive, the OSGeo official Live DVD. For the sack of simplicity,
     54an OSGeoLive Virtual Machine image disk is already installed on your computers.
     55This will be used during this workshop, so the participants won't have to compile
     56and install ZOO Kernel manually. Running and testing ZOO Kernel from this OSGeoLive
     57image disk is thus the first step of the workshop, and every participants should
     58get a working ZOO Kernel in less than 30 minutes.
    3459
    35 Once ZOO Kernel will be tested from a Web browser using GetCapabilities requests, participants will be invited to create an OGR based ZOO Service Provider aiming to enable simple spatial operations on vector data. Participants will first have to choose whether they will create the service using C or Python language. Every programming step of the ZOO Service Provider and the related Services will be each time detailed in C and Python. Once the ZOO Services will be ready and callable by ZOO Kernel, participants will finally learn how to use its different functions from an  OpenLayers simple application. A sample dataset was providen by Orkney and included in the OSGeoLiveDVD, data are available trough OGC WMS/WFS WebServices using  MapServer and will be displayed on a simple map and used as input data by the ZOO Services. Then, some specific selection and execution controls will be added in the JavaScript code in order to execute single and multiple geometries on the displayed polygons.
     60Once ZOO Kernel will be tested from a Web browser using GetCapabilities requests,
     61participants will be invited to create an OGR based ZOO Service Provider aiming to
     62enable simple spatial operations on vector data. Participants will first have to
     63choose whether they will create the service using C or Python language. Every programming
     64step of the ZOO Service Provider and the related Services will be each time detailed in
     65C and Python. Once the ZOO Services will be ready and callable by ZOO Kernel, participants
     66will finally learn how to use its different functions from an  OpenLayers simple application.
     67A sample dataset was providen by Orkney and included in the OSGeoLiveDVD, data are
     68available trough OGC WMS/WFS WebServices using  MapServer and will be displayed on a
     69simple map and used as input data by the ZOO Services. Then, some specific selection
     70and execution controls will be added in the JavaScript code in order to execute single
     71and multiple geometries on the displayed polygons.
    3672
    37 Once again, the whole procedure will be organized step-by-step and detailed with numerous code snippets and their respective explanations. The instructors will check the ZOO Kernel functioning on each machine and will assist you while coding. Technical questions are of course welcome during the workshop.
     73Once again, the whole procedure will be organized step-by-step and detailed with
     74numerous code snippets and their respective explanations. The instructors will check
     75the ZOO Kernel functioning on each machine and will assist you while coding. Technical
     76questions are of course welcome during the workshop.
    3877
    3978Usefull tips for reading :
  • trunk/docs/workshop/2010/ogr_base_vect_ops.txt

    r256 r262  
    22
    33Creating OGR based Web Services
    4 ##########################
     4###############################
    55
    66.. contents:: Table of Contents
     
    99
    1010Introduction
    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
     13In this part, we are going to create a ZOO ServicesProvider containing several Services
     14based on the OGR C API or on the OGR Python module, which have also been placed in the
     15ZOO installation on OSGeoLive. The intended goal is to use OGR and its GEOS based simple
     16spatial functions as WPS Services.
     17
     18We will first start with the Boundary spatial function, which will be explained, codded
     19and tested gradually as a ZOO Service. The same procedure will then be used to enable
     20the Buffer, Centroid and Convex Hull functions. Once done, some multiple geometries processes
     21such as Intersection, Union, Difference and Symetric Difference will be implemented through
     22an `exercise <./exercise.html>`__ at the end of the workshop.
     23
     24As already said in the introduction, you have the choice to code your service in C or
     25Python (or both!) during this workshop. Explanations will be based on the C part, but
     26will be very helpful for those who will choose Python. Please decide according to your
     27habits and preferences and tell your choice to the instructors. The results will be the
     28same in both case.
    1829
    1930Preparing 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
     33A ZOO Service is a combination of a ZOO metadata file (``.zcfg``) and the runtime module
     34for the corresponding implementation, which is commonly called ZOO Service Provider. We
     35will first prepare a ``.zcfg`` file step-by-step. Please open your preferred text editor
     36and edit a file named ``Boundary.zcfg`` in your ``/home/user/zoows/sources/zoo-services/ws_sp``
     37directory. First, you need to name the service between brackets at the top of the file, as the
     38following
    2339
    2440::
     
    2642[Boundary]
    2743
    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:
     44This name is very important, it is the name of the Service and so the name of the function
     45defined in the Services Provider. A title and a brief abstract must then be added to inform
     46clients on what the service can do:
    2947
    3048.. code-block:: guess
     
    3553Such metadata informations will be returned by a GetCapabilities request.
    3654
    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 :
     55You can also add other specific informations like the ``processVersion``. You can set if
     56your ZOO Service can store its results, by setting the ``storeSupported`` parameter to
     57true or false. You can also decide if the function can be run as a background task and
     58inform on its current status, according to the ``statusSupported`` value :
    3859
    3960.. code-block:: guess
     
    5576    serviceType=C
    5677
    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.
     78In this case you will get an ``ogr_ws_service_provider.zo`` shared library containing
     79the Boundary function, placed in the same directory than ZOO Kernel.
    5880
    5981Python ServicesProvider Example :
     
    7496    </MetaData>
    7597
    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.
     98The main metadata informations have been declared, so you can now define data input
     99which will be used by the ZOO Service. You can define any input needed by the Service.
     100Please note that you can request ZOO Kernel using more data input than defined in
     101the ``.zcfg`` file without any problem, those values will be passed to your service
     102without filtering. In the Boundary Service example, a single polygon will be used as
     103input, the one on which to apply the Boundary function.
     104
     105The data input declarations are included in a DataInputs block. They use the same
     106syntax as the Service itself and the input name is between brackets. You can also
     107fill a title, an abstract and a MetaData section for the input. You must set values
     108for the ``minOccurs`` and ``maxOccurs`` parameters, as they will inform ZOO Kernel
     109which parameters are required to be able to run the Service function.
    79110
    80111.. code-block:: none
     
    90121
    91122
    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.
     123The metadata defines what type of data the Service supports. In the Boundary example,
     124the input polygon can be provided as a GML file or as a JSON string. Next step is
     125thus to define the default and supported input formats. Both formats should be declared
     126in a LitteralData or ComplexData block depending on their types. For this first example
     127we will use ComplexData blocks only.
    93128
    94129.. code-block:: guess
     
    130165
    131166
    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 :
     167Once the ZOO metadata file is modified, you have to copy it in the same directory
     168than your ZOO Kernel (so in your case ``/usr/lib/cgi-bin``). Then you should be
     169able to run the following request :
    133170
    134171http://localhost/zoo/?Request=DescribeProcess&Service=WPS&Identifier=Boundary&version=1.0.0
     
    141178   :align: center
    142179
    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 :
     180Please note that the GetCapabilities and DescribeProcess only need a ``.zcfg``
     181file to be completed. Simple, isn't it ? At this step, if you request ZOO Kernel
     182for an Execute, you will get an ExceptionReport document as response, looking as the following :
    144183
    145184.. image:: ./images/Practical-introduction-to-ZOO-6.png
     
    157196
    158197Implementing 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
     200In order to learn the Services Provider creation and deployement step-by-step,
     201we will first focus on creating a very simple one dedicated to the Boundary function.
     202Similar procedure will then be used for the Buffer, Centroid and ConvexHull implementation.
     203
     204Your metadata is now ok, so you now must create the code of your Service. The most
     205important thing you must be aware of when coding ZOO Services is that the function
     206corresponding to your Service takes three parameters (internal maps datatype or 
     207`Python dictionaries  <http://docs.python.org/tutorial/datastructures.html#dictionaries>`__)
     208and returns an integer value representing the status of execution (SERVICE_FAILED or SERVICE_SUCCEEDED):
    164209
    165210  -  ``conf`` : The main environment configuration (corresponding to the ``main.cfg`` content)
     
    168213
    169214Boundary
    170 ======
     215========
    171216
    172217C 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
     220As explained before, ZOO Kernel will pass the parameters to your Service function
     221in a specific datatype called maps. In order to code your Service in C language,
     222you also need to learn how to access this datatype in read/write mode.
     223
     224The maps are simple map named linked list containing a name, a content map and a
     225pointer to the next map in the list (or NULL if there is no more map in the list).
     226Here is the datatype definition as you can find in the zoo-kernel/service.h file:
    178227
    179228.. code-block:: c
     
    185234    } maps;
    186235
    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:
     236The map included in the maps is also a simple linked list and is used to store Key
     237Value Pair values. A map is thus a couple of name and value and a pointer to the
     238next map in the list. Here is the datatype definition you can find in the zoo-kernel/service.h file:
    188239
    189240.. code-block:: guess
     
    196247
    197248
    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.
     249As partially or fully filled datastructures will be passed by the ZOO Kernel to
     250your Services, this means that you do not need to deal with maps creation but
     251directly with existing map, in other words the content of each maps. The first
     252function you need to know is getMapFromMaps (defined in the zoo-kernel/service.h file)
     253which let you access to a specific map of a maps.
    199254
    200255This function takes three parameters listed bellow:
     
    204259  - ``key`` : a specific key in the map named name
    205260
    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:
     261For example, the following syntax will be used to access the InputPolygon value
     262map of a maps named inputs, your C code should be:
    207263
    208264.. code-block:: guess
     
    217273    tmp->value
    218274
    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 :
     275As you know how to read and access the map fields from a maps, you can now learn
     276how to write in such a datastructure. This is done by using the simple setMapInMaps
     277function once again defined in zoo-kernel/service.h. The setMapInMaps function takes four parameters :
    220278
    221279  - ``m`` : a maps pointer you want to update,
     
    233291
    234292
    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 :
     293Please note that the setMapInMaps function is able to create or update an existing map.
     294Indeed, if a map called « value » allready exists, then its value will be updated automatically.
     295
     296Even if you will mainly use map from maps during this workshop, you can also add or
     297update values in a map directly using the addToMap function defined in zoo-kernel/service.h.
     298The addToMap function take three paramters :
    238299
    239300  - ``m`` : a map pointer you want to update,
     
    241302  - ``v`` : the value you want to set in this map.
    242303
    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):
     304This datatype is really important cause it is used in every C based ZOO Services. It is
     305also the same representation used in other languages but using their respectives datatypes.
     306For Example in Python, the dictionaries datatype is used, so manipulation is much easier.
     307
     308Here is an example of the correspoding maps datatype used in Python language (this is a
     309summarized version of the main configaration maps):
    246310
    247311.. code-block:: guess
     
    264328As you know how to deal with maps and map, you are ready to code the first ZOO Service by using the OGR Boundary function.
    265329
    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.
     330As already said in introduction we will use the MapServer WFS server available on
     331OSGeoLive, so full WFS Response will be used as inputs values. As we will use the
     332simple OGR Geometry functions like  `OGR_G_GetBoundary <http://www.gdal.org/ogr/ogr__api_8h.html#a797af4266c02846d52b9cf3207ef958>`__,
     333only the Geometry object will be used rather than a full WFS Response. The first
     334thing to do is to write a function which will extract the geometry definition
     335from the full WFS Response. We will call it createGeometryFromWFS.
    267336
    268337Here is the code of such a function:
     
    306375
    307376
    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:
     377The only thing we will focus on is the call to the errorException function used
     378in the function body. This function is declared in the zoo-kernel/service_internal.h
     379and defined in zoo-kernel/service_internal.c file. It takes three parameters as follow:
    309380
    310381  - the main environment maps,
     
    312383  - a char* representing the error code (as defined in the WPS specification – Table 62).
    313384
    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:
     385In other words, if the WFS response cannot be parsed properly, then you will return
     386an ExceptionReport document informing the client that a problem occured.
     387
     388The function to extract the geometry object from a WFS Response is written, so you
     389can now start defining the Boundary Service. Here is the full code for the Boundary Service:
    317390
    318391.. code-block:: guess
     
    363436      geometry=createGeometryFromWFS(conf,tmp->value);
    364437
    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.
     438Basicaly, if we get an input with a mimeType set to application/json, then we will
     439use our ``OGR_G_CreateGeometryFromJson`` in other case, our ``createGeometryFromWFS`` local function.
     440
     441Please note that in some sense the data inputs are not really of the same kind.
     442Indeed as we used directly ``OGR_G_CreateGeometryFromJson`` it means that the JSON
     443string include only the geometry object and not the full GeoJSON string. Nevertheless,
     444you can easily change this code to be able to use a full GeoJSON string, simply by
     445creating 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
     448Once you can access the input geometry object, you can use the  ``OGR_G_GetBoundary``
     449function and store the result in the res geometry variable. Then, you only have to
     450store the value in the right format : GeoJSON per default or GML as we declared it as a supported output format.
     451
     452Please note that ZOO Kernel will give you pre-filled outputs values, so you will
     453only have to fill the value for the key named value, even if in our example we
     454override 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
     456format requested by the client (or the default one) we will provide JSON or GML representation of the geometry.
    372457
    373458.. code-block:: guess
     
    386471      }
    387472
    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:
     473The Boundary ZOO Service is now implemented and you need to compile it to produce
     474a 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
     476same requirement is needed to be able to use the ``errorException`` function declared
     477in ``zoo-kernel/service_internal.h``, you also must link your service object file to
     478the ``zoo-kernel/service_internal.o`` in order to use ``errorException`` on runtime.
     479You must then include the required files to access the libxml2 and OGR C-API.
     480
     481For the need of the Shared Library, you have to put your code in a block declared as
     482extern "C". The final Service code should be stored in a service.c file located in
     483the root of the Services Provider directory (so in ``/home/zoows/sources/zoo-services/ws_sp``).
     484It should look like this:
    391485
    392486.. code-block:: guess
     
    402496    }
    403497
    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:
     498The full source code of your Service is now ready and you must produce the corresponding
     499Service Shared Object by compiling the code as a Shared Library. This can be done using the following command:
    405500
    406501.. code-block:: guess
     
    410505Please note that the ``CFLAGS`` and ``LDFLAGS`` environment variables values must be set before.
    411506
    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.
     507The ``CFLAGS`` must contain all the requested paths to find included headers, so the
     508path to the directories where the ``ogr_api.h``, ``libxml2`` directory, ``service.h``
     509and ``service_internal.h`` files are located. Thanks to the OSGeoLive environment,
     510some 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
     513If 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
     515located in the ``../../zoo-kernel`` directory relatively to your current path (``/home/user/zoows/sources/zoo-services/ws_sp``).
     516Note that you can also use a full path to the ``zoo-kernel`` directory but using relative
     517path will let you move your sources tree somewhere else and keep your code compiling
     518using 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.
    415520
    416521The full ``CFLAGS`` definition should look like this:
     
    420525    CFLAGS=`gdal-config --cflags` `xml2-config --clfags` -I../../zoo-kernel/
    421526
    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 :
     527Once you get the included paths correctly set in your ``CFLAGS`` , it is time to concentrate
     528on the library we have to link against (defined in the ``LDFLAGS`` environment variable).
     529In order to link against the gdal and libxml2 libraries, you can use the same tools than
     530above using the ``--libs`` argument rather than ``--cflags``. The full ``LDFLAGS``
     531definition must look like this :
    423532
    424533.. code-block:: guess
     
    426535    LDFLAGS=`gdal-config --libs` `xml2-config --libs` ../../zoo-kernel/service_internal.o
    427536
    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:
     537Let's now create a ``Makefile`` which will help you compiling your code over the time.
     538Please write a short ``Makefile`` in the root of your ZOO Services Provider directory, containing the following lines:
    429539
    430540.. code-block:: guess
     
    440550
    441551
    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:
     552Using this ``Makefile``, you should be able to run ``make`` from your ZOO Service Provider
     553main directory and to get the resulting ``ogr_ws_service_provider.zo`` file located in the ``cgi-env`` directory.
     554
     555The metadata file and the ZOO Service Shared Object are now both located in the ``cgi-env``
     556directory. In order to deploy your new ServicesProvider, you only have to copy the ZOO
     557Service Shared Object and its corresponding metadata file in the directory where ZOO
     558Kernel is located, so in ``/usr/lib/cgi-bin``. You must use a ``sudo`` command to achieve this task:
    445559
    446560.. code-block:: guess
     
    448562    sudo cp ./cgi-env/* /usr/lib/cgi-bin
    449563
    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:
     564You should now understand more clearly the meannings of the ZOO Service Provider source tree !
     565The ``cgi-env`` directory will let you deploy your new Services or Services Provider in
     566an easy way , simply by copying the whole cgi-env content in your ``cgi-bin`` directory.
     567
     568Please 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:
    453570
    454571.. code-block:: none
     
    460577
    461578Python 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
     581For 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
     583Python is an interpreted language, you do not have to compile anything before deploying
     584your service which makes the deployement step much easier:
    465585
    466586.. code-block:: guess
     
    494614        return 3
    495615
    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.
     616We do not dicuss the functions body here as we already gave all the details before and
     617the code was volontary made in a similar way.
    497618
    498619As done before, you only have to copy the ``cgi-env`` files into your ``cgi-bin`` directory:
     
    513634
    514635Testing the Service using Execute Request
    515 ----------------------------------
     636-----------------------------------------
    516637
    517638The 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
     641Everybody should now get his own copy of the OGR Boundary Service stored as a ZOO
     642Services Provider called ``ogr_ws_service_provider`` and deployed in the ZOO Kernel
     643tree, so the following Execute request can be used to test the Service:
    521644
    522645`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>`__
     
    526649    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
    527650
    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:
     651As you can see in the url above, we use an URLEncoded WFS request to the MapServer
     652WFS server available on OSGeoLive as a ``xlink:href`` key in the DataInputs KVP value,
     653and set the ``InputPolygon`` value to Reference. The corresponding non encoded WFS request is as follow:
    529654
    530655::
     
    532657    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
    533658
    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.
     659Please note that you can add ``lineage=true`` to the previous request if you need
     660to get information about the input values used to run your Service. Furthermore,
     661you may need to store the ExecuteResponse document of your ZOO Service to re-use
     662it later. In this case you must add ``storeExecuteResponse=true`` to the previous
     663request. Note that is an important thing as the behavior of ZOO Kernel is not
     664exactly the same than when running without this parameter settled to true. Indeed,
     665in such a request, ZOO Kernel will give you an ExecuteResponse document which will
     666contain the attribute statusLocation, which inform the client where the ongoing
     667status or the final ExecuteResponse will be located.
    535668
    536669Here is an example of what the ExecuteResponse would look like in case ``storeExecuteResponse`` was set to true in the request:
     
    541674   :align: center
    542675
    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 :
     676Then, according to the statusLocation, you should get the ExecuteResponse as you get
     677before using the previous request. Note that can be really useful to provide some
     678caching system for a client application.
     679
     680You didn't specify any ResponseForm in the previous request, it is not requested
     681and should return a ResponseDocument per default using the application/json mimeType
     682as you defined in you zcfg file. Nevertheless, you can tell ZOO Kernel what kind of
     683data you want to get in result of your query adding the attribute ``mimeType=text/xml``
     684to your ``ResponseDocument`` parameter. Adding this parameter to the previous request
     685will give us the result as its GML representation :
    546686
    547687`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>`__
     
    551691    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
    552692
    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 :
     693As defined by the WPS specifications, you can also ask for a ``RawDataOutput`` to
     694get only the data without the full ``ResponseDocument``. To do that, you only have
     695to replace the ``ResponseDocument`` of your request by ``RawDataOutput``, like in
     696the following request :
    554697
    555698`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>`__
     
    559702    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
    560703
    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.
     704Please note that we go back to the default mimeType to directly obtain the JSON
     705string as we will use this kind of request to develop our client application in
     706the next section of this workshop.
     707
     708Now, you know how to ask ZOO Kernel to run service in background, ask for ``RawDataOutput``
     709specifying ``mimeType`` or any specific format to be returned by the Kernel. When you
     710ask for ``ResponseDocument``, you can also specify to the ZOO Kernel that you want the
     711result to be stored on the server side.
     712
     713To do such a thing, you have to set the attribute ``asReference`` as true and then the
     714resulting ExecuteResponse will contain a Reference node including the href attribute
     715to let you access the produced file. To be able to handle this, you have to add the
     716extension parameter in your ``DataOutputs`` node in the corresponding ZCFG file.
    566717
    567718Here is a sample url which provide such a result:
     
    581732
    582733Simplification 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
     736As you can see in the simple example we used since the begining of this workshop,
     737it is sometimes hard to write the Execute requests using the GET method as it
     738makes really long and complexe URLs. In the next requests examples, we will
     739thus use the POST XML requests. First , here is the XML request corresponding
     740to the previous Execute we used:
    586741
    587742.. code-block:: guess
     
    607762    </wps:Execute>
    608763
    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:
     764In 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
     766access it using the following link :  http://localhost/test_services.html.
     767
     768Please open this page in your browser, simply fill the XML request content into
     769the textarea field and click the « run using XML Request » submit button. You will
     770get exactly the same result as when running your Service using the GET request. The
     771screenshot above show the HTML form including the request and the ExecuteResponse
     772document displayed in the iframe at the bottom of the page:
    612773
    613774.. image:: ./images/Practical-introduction-to-ZOO-8.png
     
    616777   :align: center
    617778
    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 :
     779The xlink:href value is used in the simplest way to deal with such data input. Obviously,
     780you can also use a full JSON string of the geometry, as shown in the following XML Request example :
    619781
    620782.. code-block:: guess
     
    643805    </wps:Execute>
    644806 
    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.
     807If everything went well, you should get the Boundary of the JSON geometry passed as
     808argument, and so be sure that your Service support both GML and JSON as input data.
     809Note 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``
     811mimeType but passed as an ``application/json`` string directly. It is similar to add
     812``@mimeType=application/json`` as we discussed before.
    646813
    647814storeExecuteResponse 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
     817If you go in your local ``/home/user/zoows/sources/zoo-services/utils/status``, you'll
     818find the code for a ServiceProvider which will provide the GetStatus service and the
     819longProcess one. The last is a simple example to learn how to use the status variable
     820from lenv section of the main configuration maps and the updateStatus function you
     821have to call to take your status value into account. The main service provider is
     822the GetStatus one, it is able to give you information about the current status value
     823from a service running in background mode.
     824
     825You have to know that the ZOO Kernel will detect the presence of the GetStatus service
     826and if it is available it will then return the link the corresponding Execute request.
     827
     828So now you will deploy the GetStatus and longProcess service on your local environment.
     829As for each services, you shall be able to deploy the services simply by copying the
     830cgi-env directory into your Apache ``cgi-bin`` directory. You can use the following command :
    655831
    656832.. code-block:: guess
     
    658834    sudo cp ~user/zoows/sources/zoo-services/utils/status/cgi-env/*{zcfg,zo} /usr/lib/cgi-bin
    659835
    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.
     836For simple Services it is the right way to deploy Service Providers. But in this specific
     837case you'll have also to add some special parameter in the main section of you main
     838configuration file and to copy an xsl file used to replace on the fly in the ResponseDocument
     839the percentCompleted attribute of the ProcessStarted node returned by the GetStatus service.
    661840
    662841So first edit you ``main.cfg`` file to add the following lines in your main section :
     
    667846    dataPath=/var/www/data
    668847
    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 :
     848Here you define the path where the service is able to find the xsl file, specified in the
     849dataPath parameter. You also tell the ZOO Kernel that you want to use the rewriteUrl we
     850defined in the previous section.
     851
     852To finish your deployment, you'll have now to copy the xsl file in the defined dataPath
     853directory. You can use the following command :
    672854
    673855.. code-block:: guess
     
    686868   :align: center
    687869
    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.
     870If you poll the statusLocation url provider in the answer you'll then be able to view
     871the evolution of the percentCompleted attribute value growing, like you can see in the following screenshot.
    689872
    690873.. image:: ./images/Practical-introduction-to-ZOO-10.png
     
    697880
    698881Creating 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
     884As the Boundary sample service code is available, you can now easily add ConvexHull and
     885Centroid functions as they take exactly the same number of arguments : Only one geometry.
     886The details for implementing and deploying the ConvexHull Service are provided bellow,
     887and we will let you do the same thing for the Centroid one.
    702888
    703889C Version
    704 --------
     890---------
    705891
    706892Please add first the following code to the service.c source code :
     
    743929
    744930
    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:
     931This new code is exactly the same as for the Boundary Service. The only thing we modified
     932is the line where the  `OGR_G_ConvexHull <http://www.gdal.org/ogr/ogr__api_8h.html#7a93026cfae8ee6ce25546dba1b2df7d>`__
     933function is called (rather than the OGR_G_GetBoundary you used before). It is better to not copy
     934and paste the whole function and find a more generic way to define your new Services as the
     935function body will be the same in every case. The following generic function is proposed to make things simpler:
    746936
    747937.. code-block:: guess
     
    782972    }
    783973
    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:
     974Then, a function pointer called myFunc rather than the full function name can be used.
     975This way we can re-implement our Boundary Service this way:
    785976
    786977.. code-block:: guess
     
    790981    }
    791982
    792 Using this applyOne local function defined in the service.c source code, we can define other Services this way:
     983Using this applyOne local function defined in the service.c source code, we can define
     984other Services this way:
    793985
    794986.. code-block:: guess
     
    8181010    }
    8191011
    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.
     1012To deploy your Services, you only have to copy the ``Boundary.zcfg`` metadata file from
     1013your cgi-env directory as ``ConvexHull.zcfg`` and ``Centroid.zcfg``. Then, you must
     1014rename the Service name on the first line to be able to run and test the Execute request
     1015in the same way you did before. You only have to set the Identifier value to ConvexHull
     1016or Centroid in your request depending on the Service you want to run.
     1017
     1018Note here that the GetCapabilities and DescribeProcess requests will return odd results
     1019as we didn't modified any metadata informations, you can edit the ``.zcfg`` files to set
     1020correct values. By the way it can be used for testing purpose, as the input and output
     1021get the same name and default/supported formats.
    8231022
    8241023Python Version
    825 ------------
     1024--------------
    8261025
    8271026.. code-block:: guess
     
    8431042
    8441043
    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) :
     1044Once again, you can easily copy and paste the function for Boundary and simply modify
     1045the line where the Geometry method was called. Nevertheless, as we did for the C language
     1046we will give you a simple way to get things more generic.
     1047
     1048First of all, the first step which consists in extracting the InputPolygon Geometry as
     1049it will be used in the same way in each Service functions, so we will first create a
     1050function which will do that for us. The same thing can also be done for filling the
     1051output value, so we will define another function to do that automaticaly. Here is the
     1052code of this two functions (extractInputs and outputResult) :
    8481053
    8491054.. code-block:: guess
     
    9021107
    9031108Create 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
     1111We can now work on the Buffer Service, which takes more arguments than the other ones.
     1112Indeed, the code is a bit different from the one used to implement the Boundary, ConvexHull and Centroid Services.
     1113
     1114The Buffer service also takes an input geometry, but uses a BufferDistance parameter.
     1115It will also allow you to define LitteralData block as the BufferDistance will be
     1116simple integer value. The read access to such kind of input value is made using the
     1117same function as used before.
    9091118
    9101119C 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
     1122If you go back to the first Boundary Service source code, you should not find the
     1123following very complicated. Indeed, you simply have to add the access of the
     1124BufferDistance argument and modify the line whenthe  `OGR_G_Buffer <http://www.gdal.org/ogr/ogr__api_8h.html#1ca0bd5c0fcb4b1af3c3973e467b0ec0>`__
     1125must be called (instead of OGR_G_GetBoundary). Here is the ful lcode :
    9141126
    9151127.. code-block:: guess
     
    9501162    }
    9511163
    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.
     1164The new code must be inserted in your service.c file and need to be recompiled and
     1165replace the older version of your ZOO Service Provider in the /usr/lib/cgi-bin/ directory.
     1166You must of course place the corresponding ZOO Metadata File in the same directory.
     1167
     1168As we explained before, ZOO Kernel is permissive in the sense that you can pass more
     1169arguments than defined in you zcfg file, so let's try using a copy of the ``Boundary.zcfg``
     1170file renamed as ``Buffer.zcfg`` and containing the Buffer identifier. Then, please
     1171test your service using an Execute request as you did before. You will obtain the
     1172buffer result in a ResponseDocument.
     1173
     1174You may have noted that the above code check if a BufferDistance input was passed
     1175to the service. If not, we will use 1 as the default value, which explains why
     1176you do not have to use one more input to your previous queries.
     1177
     1178You can change the BufferDistance value used by your Service to compute Buffer
     1179of your geometry by adding it to the DataInputs value in your request. Note that
     1180using KVP syntaxe, each DataInputs are separated by a semicolon.
    9591181
    9601182So, the previous request:
     
    9701192    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
    9711193
    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.
     1194Setting BufferDistance value to 2 would give you a different result, then don't
     1195pass any other parameter as we defined 1 as the default value in the source code.
    9731196
    9741197Here you can find the same query in XML format to use from the  http://localhost/test_services.html HTML form :
     
    10031226
    10041227Python Version
    1005 ------------
    1006 
    1007 As we already defined the utility functions createGeometryFromWFS and outputResult, the code is as simple as this:
     1228--------------
     1229
     1230As we already defined the utility functions createGeometryFromWFS and outputResult,
     1231the code is as simple as this:
    10081232 
    10091233.. code-block:: guess
     
    10211245        return 3
    10221246
    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.
     1247We simply added the use of inputs["BufferDistance"]["value"] as arguments of the
     1248Geometry instance Buffer method. Once you get this code added to your ogr_ws_service_provider.py
     1249file, simply copy it in the ZOO Kernel directory (or type make install from your ZOO Service
     1250Provider root directory). Note that you also need the ``Buffer.zcfg`` file detailled in the next section.
    10241251
    10251252The 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
     1255You must add BufferDistance to the Service Metadata File to let clients know that
     1256this Service supports this parameter. To do this, please copy your orginal ``Boundary.zcfg``
     1257file as ``Buffer.zcfg`` and add the following lines to the DataInputs block :
    10291258
    10301259.. code-block:: none
     
    10461275     </LiteralData>
    10471276
    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.
     1277Note that as minOccurs is set to 0 which means that the input parameter is optional
     1278and don't have to be passed. You must know that ZOO Kernel will pass the default
     1279value to the Service function for an optional parameter with a default value set.
    10491280
    10501281You can get a full copy of the ``Buffer.zcfg`` file here :
  • trunk/docs/workshop/2010/using_zoo_from_osgeolivevm.txt

    r256 r262  
    22
    33Using ZOO from an OSGeoLive virtual machine
    4 #############################################
     4###########################################
    55
    66.. contents:: Table of Contents
     
    1111
    1212ZOO Kernel Installation
    13 ************************
     13***********************
    1414
    15 As already said in introduction, an OSGeoLive virtual machine image disk has been installed on your computer, allowing you to use ZOO Kernel in a development environment directly. Using a virtual machine image disk seems to be the simplest way to use ZOO Kernel and to develop ZOO Services locally, as we can ensure that everything requested for compiling C Services and running Python ones is available and ready to use. Every ZOO related material and source code have been placed in ``/home/user/zoows`` directory. We will work inside it during this workshop. As the binary version of ZOO Kernel is already compiled and stored in ``/home/user/zoows/sources/zoo-kernel``, you only have to copy two important files inside the ``/usr/lib/cgi-bin`` directory : ``zoo_loader.cgi`` and the ``main.cfg`` in order to make ZOO Kernel available, using the following commands :
     15As already said in introduction, an OSGeoLive virtual machine image disk has
     16been installed on your computer, allowing you to use ZOO Kernel in a development
     17environment directly. Using a virtual machine image disk seems to be the simplest
     18way to use ZOO Kernel and to develop ZOO Services locally, as we can ensure that
     19everything requested for compiling C Services and running Python ones is available
     20and ready to use. Every ZOO related material and source code have been placed in
     21``/home/user/zoows`` directory. We will work inside it during this workshop. As
     22the binary version of ZOO Kernel is already compiled and stored in ``/home/user/zoows/sources/zoo-kernel``,
     23you only have to copy two important files inside the ``/usr/lib/cgi-bin``
     24directory : ``zoo_loader.cgi`` and the ``main.cfg`` in order to make ZOO Kernel
     25available, using the following commands :
    1626
    1727.. code-block:: guess
     
    2131
    2232
    23 Please note that we will talk about ZOO Kernel or ``zoo_loader.cgi`` script without any distinction during this workshop.
     33Please note that we will talk about ZOO Kernel or ``zoo_loader.cgi`` script without
     34any distinction during this workshop.
    2435
    25 The ``main.cfg`` file contains metadata informations about the identification and provider but also some important settings. The file is composed of various sections, namely main, identification and provider per default. Obviously, you are free to add new sections to the file if you need them for a specific Service. Nevertheless, you have to know that the env and lenv sections name are used in a specific way.
     36The ``main.cfg`` file contains metadata informations about the identification and
     37provider but also some important settings. The file is composed of various sections,
     38namely main, identification and provider per default. Obviously, you are free to add
     39new sections to the file if you need them for a specific Service. Nevertheless, you
     40have to know that the env and lenv sections name are used in a specific way.
    2641
    27 The env section lets you define environment variables that your Service requires during its runtime. For instance, if your Service requires to access to a X server running on framebuffer, then you will have to set the ``DISPLAY`` environnement variably, in this case you would add ``DISPLAY=:1`` line in your env section.
     42The env section lets you define environment variables that your Service requires
     43during its runtime. For instance, if your Service requires to access to a X server
     44running on framebuffer, then you will have to set the ``DISPLAY`` environnement
     45variably, in this case you would add ``DISPLAY=:1`` line in your env section.
    2846
    29 As for the env section, there is the section lenv where specific informations about status informations of a running Service will be written by the ZOO Kernel or the ZOO Services. For instance, when your service failed, you can set the value for message in lenv to see it displayed in the Status node of the ExecuteResponse returned back to the client. If your service will take long time and can get informations about processing status, you can then set a value between 0 and 100 to status in lenv to represent the percentage completed of the running Service task, we will talk deeper about this later in this workshop.
     47As for the env section, there is the section lenv where specific informations about
     48status informations of a running Service will be written by the ZOO Kernel or the
     49ZOO Services. For instance, when your service failed, you can set the value for
     50message in lenv to see it displayed in the Status node of the ExecuteResponse
     51returned back to the client. If your service will take long time and can get
     52informations about processing status, you can then set a value between 0 and 100
     53to status in lenv to represent the percentage completed of the running Service task,
     54we will talk deeper about this later in this workshop.
    3055
    3156Please take a look to your local file ``main.cfg`` file. Three important parameters are commented bellow:
     
    4368    tmpUrl=../temp/
    4469
    45 You could have noticed that the tmpUrl is a relative url from ``serverAddress``, so it must be a directory. Even if ZOO Kernel can be used with the full url of the ``zoo_loader.cgi`` script, for better readability and fully functional ZOO Kernel, you have to modify the default Apache configuration in order to be able to use the  http://localhost/zoo/ url directly.
     70You could have noticed that the tmpUrl is a relative url from ``serverAddress``,
     71so it must be a directory. Even if ZOO Kernel can be used with the full url of
     72the ``zoo_loader.cgi`` script, for better readability and fully functional ZOO Kernel,
     73you have to modify the default Apache configuration in order to be able to use the 
     74http://localhost/zoo/ url directly.
    4675
    47 First, please create a ``zoo`` directory in the existing ``/var/www`` which is used by Apache as the ``DocumentRoot``. Then, please edit the ``/etc/apache2/sites-available/default`` configuration file and add the following lines after the ``Directory`` block related to ``/var/www`` directory :
     76First, please create a ``zoo`` directory in the existing ``/var/www`` which is
     77used by Apache as the ``DocumentRoot``. Then, please edit the ``/etc/apache2/sites-available/default``
     78configuration file and add the following lines after the ``Directory`` block related to ``/var/www`` directory :
    4879
    4980.. code-block:: none
     
    6596    RewriteRule (.*) /cgi-bin/zoo_loader.cgi [L,QSA]
    6697
    67 For this last file to be taken into account by Apache, you must activate the rewrite Apache module by copying a load file as bellow :
     98For this last file to be taken into account by Apache, you must activate the
     99rewrite Apache module by copying a load file as bellow :
    68100
    69101.. code-block:: guess
     
    84116
    85117
    86 Two other softwares form the OSGeoLive environment will be used during this workshop. MapServer will first be used to provide WFS input data for the ZOO Services we are going to develop. The MapServer dataset providen by Orkney (japanese regions polygons) will be passed to our service during `section 4 <http://zoo-project.org/trac/wiki/ZooWorkshop/FOSS4GJapan/CreatingOGRBasedWebServices#CallingthesinglegeometryservicesfromJavaScript>`__.
     118Two other softwares form the OSGeoLive environment will be used during this workshop.
     119MapServer will first be used to provide WFS input data for the ZOO Services we are
     120going to develop. The MapServer dataset providen by Orkney (japanese regions polygons)
     121will be passed to our service during `section 4 <http://zoo-project.org/trac/wiki/ZooWorkshop/FOSS4GJapan/CreatingOGRBasedWebServices#CallingthesinglegeometryservicesfromJavaScript>`__.
    87122
    88 OpenLayers library is also available on the OSGeoLive virtual machine image disk, and it will be used during `section 4 <http://zoo-project.org/trac/wiki/ZooWorkshop/FOSS4GJapan/CreatingOGRBasedWebServices#CallingthesinglegeometryservicesfromJavaScript>`__, for building a simple WPS client application able to query the newly developed ZOO Services.
     123OpenLayers library is also available on the OSGeoLive virtual machine image disk,
     124and it will be used during `section 4 <http://zoo-project.org/trac/wiki/ZooWorkshop/FOSS4GJapan/CreatingOGRBasedWebServices#CallingthesinglegeometryservicesfromJavaScript>`__, for building a simple WPS client application able to query the newly developed ZOO Services.
    89125
    90 As we planned to use OGR C-API and Python module of the GDAL library, we will need the corresponding header files, libraries and associated files. Hopefully everything was already available per default and so ready to use on the OSGeoLive packaging.
     126As we planned to use OGR C-API and Python module of the GDAL library, we will need
     127the corresponding header files, libraries and associated files. Hopefully everything
     128was already available per default and so ready to use on the OSGeoLive packaging.
    91129
    92130Testing the ZOO installation with GetCapabilities
    93 ***************************************************
     131*************************************************
    94132
    95133
     
    105143   :align: center
    106144
    107 Please note that no Process node is returned in the ProcessOfferings section, as no ZOO Service is available yet. You can also proceed to a GetCapabilities request from the command line, using the following command:
     145Please note that no Process node is returned in the ProcessOfferings section, as no
     146ZOO Service is available yet. You can also proceed to a GetCapabilities request from
     147the command line, using the following command:
    108148
    109149.. code-block:: none
     
    122162
    123163Preparing your ZOO Services Provider directory
    124 *************************************************
     164**********************************************
    125165
    126 In order to simplify the task, we will first comment the directory structure which should be used when creating a new Services Provider :
     166In order to simplify the task, we will first comment the directory structure which
     167should be used when creating a new Services Provider :
    127168
    128169  - The main Services Provider directory including :
Note: See TracChangeset for help on using the changeset viewer.

Search

Context Navigation

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png