source: trunk/docs/kernel/mapserver.txt @ 436

.. _kernel-mapserver:
    
How To Use the Internal MapServer W*S support
=============================================

:Authors: Nicolas Bozon, Gérald Fenoy, Jeff McKenna
:Last Updated: $Date$ 

The key idea of the MapServer W*S support implementation is that it
doesn't require to change a single line of the service source code to
activate the automatic publication of your result as WMS/WFS or WCS
ressource. You simply need to modify the ``zcfg`` file corresponding
to your service to make it working.

Here is an overview of the way to install the MapServer W*S support, the
configuration required and the internal mechanisms. 

.. contents:: Table of Contents
    :depth: 3
    :backlinks: top

How to make it working ?
------------------------

Requirement
**************

   * last ZOO-Kernel trunk version
   * MapServer version >= 6.0.1

Installation steps
********************

First download lastest zoo-kernel directory available on the svn, do that from the directory of your previous checkout (so where zoo-api, zoo-services and zoo-kernel directories are available), we will use ``<PREV_SVN_CO>`` here for this directory:

.. code-block:: guess

    cd <PREV_SVN_CO>
    svn checkout http://svn.zoo-project.org/svn/trunk/zoo-kernel zoo-kernel-ms

Uncompress the MapServer archive (ie. ``mapserver-6.0.1.tar.bz2``) into ``/tmp/zoo-ms-src``, then compile MapServer using the following command:

.. code-block:: guess

     cd /tmp/zoo-ms-src/mapserver-6.0.1
     ./configure --with-ogr=/usr/bin/gdal-config --with-gdal=/usr/bin/gdal-config \
                    --with-proj --with-curl --with-sos --with-wfsclient --with-wmsclient \
                    --with-wcs --with-wfs --with-postgis --with-kml=yes --with-geos \
                    --with-xml --with-xslt --with-threads --with-cairo
     make
     cp mapserv /usr/lib/cgi-bin

Autotools was updated to add the ``--with-mapserver`` configure option. From your ZOO-Project SVN trunk directory, compile the ZOO-Kernel using the following command:

.. code-block:: guess

     cd zoo-kernel-ms
     autoconf
     ./configure --with-python --with-mapserver=/tmp/zoo-ms-src/mapserver-6.0.1
     make
     cp zoo_loader.cgi /usr/lib/cgi-bin

Configuration steps
*************************

Main configuration file
^^^^^^^^^^^^^^^^^^^^^^^

Add the following content to your ``/usr/lib/cgi-bin/main.cfg`` file
 in the ``[main]`` section:

.. code-block:: guess

      dataPath = /var/www/temp/
      mapserverAddress=http://localhost/cgi-bin/mapserv

The ``dataPath`` directory should exists and be writable by apache user. In this directory, a ``symbols.sym`` file have to be present, containing the following:

.. code-block:: guess

      SYMBOLSET
      SYMBOL
        NAME "circle"
        TYPE ellipse
        FILLED true
        POINTS
          1 1
        END
      END
      END

Only one symbol definition is required with any name, used for WMS service output.

Now, your ZOO-Kernel get the MapServer support ready to be used. Note that if you don't add the ``mapserverAddress`` then it imply the ZOO-Kernel will segfault (checking ``NULL`` value should correct this behavior).

Here you can optionally add a ``msOgcVersion`` parameter to specify which version of the OGC WebService you want to use for each services. For example, if you want to force to version 1.0.0, you can set the following in the ``[main]`` section of your ``main.cfg`` file:

.. code-block:: guess

     msOgcVersion=1.0.0

Service configuration file
^^^^^^^^^^^^^^^^^^^^^^^^^^

To activate MapServer WebServices output for a service, you have to add a specific parameter in the ``<Default>`` or ``<Supported>`` block: ``useMapserver``. This can take the value true or should not appear. If true, it means that the output result is an OGR / GDAL compatible datasource and you want it to be outputted as an OGC web server instance (WMS/WFS/WCS).

You get an optional parameter, to use a custom MapServer style block (used for vector datasource only): msStyle. For example:

.. code-block:: guess

     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END

You get the same optional parameter ``msOgcVersion`` as for the ``main.cfg``. This will specify that this is the specific protocol version the service want to use (so you may set also locally to service rather than globally).

When you add useMapserver option to an output ``<Default>`` or ``<Supported>`` block, then you have to know what are the sensible mimeType:

   * text/xml: will imply that the output data will be accessible through a WFS GetFeature request (default protocol version 1.1.0)
   * image/tiff: will imply that the output data will be accessible through a WCS GetCoverage request (default protocol version 2.0.0)
   * any other mimeType coupled with useMapserver option: will imply that the output data will be accessible trhough a WMS GetMap request (you have to limit yourself to what your MapServer installation support, GetCapabilities? request give information of supported output mimeType) (default protocol version 1.3.0) 

How does it work ?
---------------------

Whatever your service return as default output ``mimeType``, this one will be used when one output including the ``useMapserver`` option was found.

So if you get the following ``<Default>`` and ``<Supported>`` blocks in the ZOO Configuration File of your service:

.. code-block:: guess

    <Default>
     mimeType = text/xml
     encoding = UTF-8
     schema = http://schemas.opengis.net/gml/3.1.0/base/feature.xsd
    </Default>
    <Supported>
     mimeType = image/png
     useMapserver = true
    </Supported>

It means that per default, your service return GML 3.1 Feature. When the client request for ``mimeType=image/png``, then the ZOO-Kernel will detect that this ``mimeType`` get the ``useMapServer`` option set to true so it will:

    1) execute the service using the ``<Default>`` block definition (this should be understandable by GDAL/OGR)

    2) store the result of the service on disk (in the ``[main]`` > ``dataPath`` directory)

    3) write a Mapfile (in the ``[main]`` > ``dataPath`` directory) using the MapServer C-API to setup both WMS and WFS services.

.. Note:: even if you don't ask for this, the resulting Mapfile includes both configuration for WMS and WFS in case of Vector datasource.

If your service output a raster file, then the behavior is quite the same except that the ZOO-Kernel will setup both WMS and WCS services for the result of the service. Here you cannot define your own style. Nevertheless, when one band raster is returned then the ZOO-Kernel can use its own default style definitions to classify the raster using equivalent intervals (you can easily see that in the outputed Mapfile), this classification is specific to WMS protocol. You should add a ``msClassify`` parameter and set it to ``true`` in your output ComplexData ``<Default>`` or ``<Supported>`` node to activate this classification.
Special note for client implementers

Note that depending on the request, the ZOO-Kernel can return a location header.

Differente request types:

    * ResponseDocument=XXXX@asReference=true - in this case, the Kernel will return the GetMap/GetFeature/GetCoverage request in KVP in the href of the result.
    * ResponseDocument=XXXX@asReference=false - in this case, the Kernel will return the result he get using the GetMap/GetFeature/GetCoverage request in KVP used for the href in previous case.
    * RawDataOutput=XXXX@asReference=true/false - in this case, the Kernel will return the GetMap/GetFeature/GetCoverage request in KVP in the specific location header, which imply that the browser should follow and request MapServer directly. 

Simple sample use cases
-----------------------

Consider the existing BufferPy service from zoo-services/ogr-base-vect-ops-py. Set the following content to your local BufferPy.zcfg file in the Result output definition, then copy it to /usr/lib/cgi-bin/:

.. code-block:: guess

    <Default>
     mimeType = text/xml
     encoding = UTF-8
     schema = http://schemas.opengis.net/gml/3.1.0/base/feature.xsd
     useMapserver = true
    </Default>
    <Supported>
     mimeType = image/png
     useMapserver = true
     asReference = true
     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
    </Supported>
    <Supported>
     mimeType = image/tif
     useMapserver = true
     asReference = true
     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
    </Supported>
    <Supported>
     mimeType = application/vnd.google-earth.kmz
     useMapserver = true
     asReference = true
     msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
    </Supported>

This modifications make your service ready to return result as WMS GetMap or WFS GetFeature requests. Note that some bug occurs locally using the application/vnd.google-earth.kmz output.
Raster

Using the following simple service code we get a service capable to output any kind of internet files (useful for testing this functionality):

.. code-block:: guess

    import zoo
    def HelloPy(conf,inputs,outputs):
            outputs["Result"]["value"]=inputs["a"]["value"]
            return zoo.SERVICE_SUCCEEDED

Define the ``[Result]`` output in your ``HelloPy.zcfg`` file with the following ComplexData block content:

.. code-block:: guess

    <Default>
     mimeType = image/png
     useMapServer = true
    </Default>
    <Supported>
     mimeType = image/tiff
     useMapServer = true
    </Supported>
    <Supported>
     mimeType = text/xml
     useMapServer = true
    </Supported>

It means that the default output ``mimeType`` is ``image/png``, so a WMS GetMap request will be returned, or the resulting ``image/tiff`` will be returned as WCS GetCoverage request.

With this simple service you can test the new capabilities to output result as WebServices for each mimeTypes. Note, that you'll probably get wrong ``mimeType``, as the default was set to ``image/png``.

There is a support for Zipped ShapeFile but I doubt it is really
useful. Anyway, as it is present you can test it easily by passing a
zip file in ``xlink:href`` for the ``a`` value of the ``HelloPy``
service.

Testings
***********

Using the simple ``HelloPy`` service code, you can use the following urls, note it supposes that you get an available http://localhost/data/data.zip file containing a ShapeFile and a http://localhost/data/demo.tif:

Test 1: Accessing a remote Zipped Shapefile as WFS GetFeatures Request
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: guess

     http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=HelloPy&DataInputs=a=Reference@xlink:href=http://localhost/data/data.zip&ResponseDocument=Result@asReference=true@mimetype=text/xml

Test 2: Accessing a remote Zipped Shapefile as WMS GetMap Request
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: guess

     http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=HelloPy&DataInputs=a=Reference@xlink:href=http://localhost/data/data.zip&ResponseDocument=Result@asReference=true@mimetype=image/png

Test 3: Accessing a remote tiff as WMS GetMap Request:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: guess

     http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=HelloPy&DataInputs=a=Reference@xlink:href=http://localhost/data/data.tiff&ResponseDocument=Result@asReference=true@mimetype=image/png

Test 4: Accessing a remote tiff as WCS GetMap Request:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: guess

     http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=HelloPy&DataInputs=a=Reference@xlink:href=http://localhost/data/data.tiff&ResponseDocument=Result@asReference=true@mimetype=image/tiff