<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % cartoweb SYSTEM "../../cartoweb.ent" >
  %cartoweb;
  ]>
<sect1 id="dev.soapcalls.examples">
  <title>Examples</title>
  <para>The following examples show simple SOAP calls using PHP.</para>
  <para>To use these examples with your &cartoweb; server, you'll have to modify 
    the map ID and the layer names. Please note that in these examples, access 
    to resources uses symbolic links (see <xref linkend="user.config" 
    />).</para>  <sect2 id="dev.soapcalls.examples.getmapinfo">
    <title>Retrieving Server Configuration</title>
    <para>First thing to do is to declare the SOAP client. Class SoapClient 
      will need the WSDL code dynamically generated by script 
      cartoserver.wsdl.php.<programlisting><![CDATA[
<?php

$client = new SoapClient("http://url.to/server/cartoserver.wsdl.php"
                         . "?mapId=swiss_project.swiss");       
...]]></programlisting> Method only needs map ID as argument.<programlisting><![CDATA[
try{
    $result = $client->getMapInfo("swiss_project.swiss");
    print_r($result);    
} catch (SoapFault $fault) {
    print $fault->faultstring;
}
            
?>]]></programlisting> </para>
    <para> Result is shown below. It includes server configuration for the 
      corresponding project and mapfile.<programlisting><![CDATA[
stdClass Object
(
  [timeStamp] => 1107043488
  [mapLabel] => Switzerland
  [keymapGeoDimension] => stdClass Object
    (
      [dimension] => stdClass Object
        (
          [width] => 100
          [height] => 100
        )
      [bbox] => stdClass Object
        (
          [minx] => 485000
          [miny] => 65000
          [maxx] => 835000
          [maxy] => 298000
        )
    )
  [initialMapStates] => Array
    (
      [0] => stdClass Object
        (
          [id] => default
          [location] => stdClass Object
            (
              [bbox] => stdClass Object
                (
                  [minx] => 470000
                  [miny] => 50000
                  [maxx] => 860000
                  [maxy] => 320000
                )
            )
          [layers] => Array
            (
              [0] => stdClass Object
                (
                  [id] => swiss_layer_1
                  [hidden] => 
                  [frozen] => 
                  [selected] => 1
                  [unfolded] => 
                )
              [1] => stdClass Object
                (
                  [id] => swiss_layer_2
                  [hidden] => 1
                  [frozen] => 
                  [selected] => 1
                  [unfolded] => 
                )
            )
        )
    )
  [layersInit] => stdClass Object
  (
  [notAvailableIcon] => gfx/icons/swiss_project/swiss/na.png
  [notAvailablePlusIcon] => gfx/icons/swiss_project/swiss/nap.png
  [notAvailableMinusIcon] => gfx/icons/swiss_project/swiss/nam.png
  [layers] => Array
    (
      [0] => stdClass Object
        (
          [className] => LayerGroup
          [id] => root
          [label] => root
          [children] => Array
            (
              [0] => swiss_layer_1
              [1] => swiss_layer_2
            )
          [minScale] => 0
          [maxScale] => 0
          [icon] => 
          [link] => 
          [aggregate] => 
          [rendering] => 
          [metadata] => Array
            (
              [0] => foo=bar
            )
        )
      [1] => stdClass Object
        (
          [className] => Layer
          [id] => swiss_layer_1
          [label] => Swiss Layer 1
          [children] => Array
            (
            )
          [minScale] => 0
          [maxScale] => 0
          [icon] => gfx/icons/swiss_project/swiss/icon_1.png
          [link] => 
          [metadata] => Array
            (
            )
        )
      [2] => stdClass Object
        (
          [className] => Layer
          [id] => swiss_layer_2
          [label] => Swiss Layer 2
          [children] => Array
            (
            )
          [minScale] => 1
          [maxScale] => 20
          [icon] => 
          [link] => 
          [metadata] => Array
            (
            )
        )
    )
  [locationInit] => stdClass Object
    (
      [className] => LocationInit
      [scales] => Array
        (
          [0] => stdClass Object
            (
              [label] => 1/50000
              [value] => 50000
            )
          [1] => stdClass Object
            (
              [label] => 1/100000
              [value] => 100000
            )
          [2] => stdClass Object
            (
              [label] => 1/500000
              [value] => 500000
            )
        )
      [minScale] => 25000
      [maxScale] => 1000000
      [shortcuts] => Array
        (
          [0] => stdClass Object
            (
              [label] => Romandie
              [bbox] => stdClass Object
                (
                  [minx] => 475000
                  [miny] => 65750
                  [maxx] => 670000
                  [maxy] => 212000
                )
            )
        )
    )
)
]]></programlisting></para>
  </sect2>
  <sect2 id="dev.soapcalls.examples.pointscale">
    <title>Getting a Map Using a Point and a Scale</title>
    <para>The simpliest way to obtain a map from &cartoweb; server is to send an 
      X-Y location and a scale.</para>
    <para>First thing to do is to declare the SOAP client. Class SoapClient 
      will need the WSDL code dynamically generated by script 
      cartoserver.wsdl.php.<programlisting><![CDATA[
<?php

$client = new SoapClient("http://url.to/server/cartoserver.wsdl.php"
                         . "?mapId=swiss_project.swiss");       
...]]></programlisting> The map ID is required also in the request object. 
      <programlisting><![CDATA[
$request->mapId = 'swiss_project.swiss';
...]]></programlisting> In this example, only main map and scale bar are 
      requested. So key map's isDrawn attribute is set to false. 
      <programlisting><![CDATA[
$request->imagesRequest->className = 'ImagesRequest';

$request->imagesRequest->mainmap->isDrawn = true;
$request->imagesRequest->mainmap->path = '';
$request->imagesRequest->mainmap->width = 500;
$request->imagesRequest->mainmap->height = 500;
$request->imagesRequest->mainmap->format = '';

$request->imagesRequest->keymap->isDrawn = false;
$request->imagesRequest->keymap->path = '';
$request->imagesRequest->keymap->width = 0;
$request->imagesRequest->keymap->height = 0;
$request->imagesRequest->keymap->format = '';

$request->imagesRequest->scalebar->isDrawn = true;
$request->imagesRequest->scalebar->path = '';
$request->imagesRequest->scalebar->width = 100;
$request->imagesRequest->scalebar->height = 100;
$request->imagesRequest->scalebar->format = '';
...]]></programlisting> Two layers are displayed. Resolution attribute is set 
      to null to keep standard Mapserver resolution. <programlisting><![CDATA[
$request->layersRequest->className = 'LayersRequest';

$request->layersRequest->layerIds = array('swiss_layer_1',
                                          'swiss_layer_2');
$request->layersRequest->resolution = null;
...]]></programlisting>In this case, the location request object is of type 
      zoom-point, and zoom type is set to ZOOM_SCALE. Bbox is unused but is 
      required. <programlisting><![CDATA[
$request->locationRequest->className = 'LocationRequest';

$request->locationRequest->locationType = 'zoomPointLocationRequest';
$request->locationRequest
        ->zoomPointLocationRequest->bbox->minx = 500000;
$request->locationRequest
        ->zoomPointLocationRequest->bbox->miny = 100000;
$request->locationRequest
        ->zoomPointLocationRequest->bbox->maxx = 600000;
$request->locationRequest
        ->zoomPointLocationRequest->bbox->maxy = 200000;
$request->locationRequest
        ->zoomPointLocationRequest->point->x = 550000;
$request->locationRequest
        ->zoomPointLocationRequest->point->y = 150000;
$request->locationRequest
        ->zoomPointLocationRequest->zoomType = 'ZOOM_SCALE';
$request->locationRequest
        ->zoomPointLocationRequest->scale = 200000;
...]]></programlisting> Now request object is ready, SOAP method is 
      called.<programlisting><![CDATA[
try{
    $result = $client->getMap($request);
    print_r($result);    
} catch (SoapFault $fault) {
    print $fault->faultstring;
}
            
?>]]></programlisting> </para>
    <para> Result is shown below. It includes relative paths to generated 
      images and new bounding box computed from requested scale.<programlisting><![CDATA[
stdClass Object
(
  [timestamp] => 1107925732
  [serverMessages] => Array
    (
    )
  [imagesResult] => stdClass Object
    (
      [className] => ImagesResult
      [mainmap] => stdClass Object
        (
          [isDrawn] => 1
          [path] => images/110839565198671.jpg
          [width] => 500
          [height] => 500
          [format] => 
        )
      [keymap] => stdClass Object
        (
          [isDrawn] => 
          [path] => 
          [width] => 
          [height] => 
          [format] => 
        )
      [scalebar] => stdClass Object
        (
          [isDrawn] => 1
          [path] => images/110839565198672.png
          [width] => 300
          [height] => 31
          [format] => 
        )
    )
  [locationResult] => stdClass Object
    (
      [className] => LocationResult
      [bbox] => stdClass Object
        (
          [minx] => 536770.840477
          [miny] => 136770.840477
          [maxx] => 563229.159523
          [maxy] => 163229.159523
        )
      [scale] => 200000
    )
)]]></programlisting> </para>
  </sect2>
  <sect2 id="dev.soapcalls.examples.query">
    <title>Executing a Query</title>
    <para>The following code shows how to use queries to display hilighted 
      selection and to retrieve corresponding attributes.</para>
    <para>First thing to do is to declare the SOAP client. Class SoapClient 
      will need the WSDL code dynamically generated by script 
      cartoserver.wsdl.php. <programlisting><![CDATA[
<?php

$client = new SoapClient("http://url.to/server/cartoserver.wsdl.php"
                         . "?mapId=swiss_project.swiss");       
...]]></programlisting> The map ID is required also in the request 
      object.<programlisting><![CDATA[
$request->mapId = 'swiss_project.swiss';
...]]></programlisting> In this example, only main map and key map are 
      requested. So scale bar's isDrawn attribute is set to false. 
      <programlisting><![CDATA[
$request->imagesRequest->className = 'ImagesRequest';

$request->imagesRequest->mainmap->isDrawn = true;
$request->imagesRequest->mainmap->path = '';
$request->imagesRequest->mainmap->width = 500;
$request->imagesRequest->mainmap->height = 500;
$request->imagesRequest->mainmap->format = '';

$request->imagesRequest->keymap->isDrawn = true;
$request->imagesRequest->keymap->path = '';
$request->imagesRequest->keymap->width = 100;
$request->imagesRequest->keymap->height = 100;
$request->imagesRequest->keymap->format = '';

$request->imagesRequest->scalebar->isDrawn = false;
$request->imagesRequest->scalebar->path = '';
$request->imagesRequest->scalebar->width = 0;
$request->imagesRequest->scalebar->height = 0;
$request->imagesRequest->scalebar->format = '';
...]]></programlisting> Two layers are displayed. Resolution attribute is set 
      to null to keep standard Mapserver resolution.<programlisting><![CDATA[
$request->layersRequest->className = 'LayersRequest';

$request->layersRequest->layerIds = array('swiss_layer_1',
                                          'swiss_layer_2');
$request->layersRequest->resolution = null;
...]]></programlisting> In this case, the location request object is of type 
      bbox. Only new bounding box is required. <programlisting><![CDATA[
$request->locationRequest->className = 'LocationRequest';

$request->locationRequest->locationType = 'bboxLocationRequest';
$request->locationRequest->bboxLocationRequest->bbox->minx = 550000;
$request->locationRequest->bboxLocationRequest->bbox->miny = 100000;
$request->locationRequest->bboxLocationRequest->bbox->maxx = 600000;
$request->locationRequest->bboxLocationRequest->bbox->maxy = 150000;
...]]></programlisting> The query will be performed on a rectangle, on all 
      selected layers (ie. layers defined in layers request object). IDs and 
      attributes will be returned.<programlisting><![CDATA[
$request->queryRequest->className = 'QueryRequest';

$request->queryRequest->shape->className = 'Bbox';
$request->queryRequest->shape->minx = 570000;
$request->queryRequest->shape->miny = 120000;
$request->queryRequest->shape->maxx = 580000;
$request->queryRequest->shape->maxy = 130000;
$request->queryRequest->queryAllLayers = true;
$request->queryRequest->defaultMaskMode = false;
$request->queryRequest->defaultTableFlags->returnAttributes = true;
$request->queryRequest->defaultTableFlags->returnTable = true;
$request->queryRequest->querySelections = array();
...]]></programlisting> Now request object is ready, SOAP method is 
      called.<programlisting><![CDATA[
try{
    $result = $client->getMap($request);
    print_r($result);    
} catch (SoapFault $fault) {
    print $fault->faultstring;
}
            
?>]]></programlisting> </para>
    <para>Result is shown below. It includes relative paths to generated images 
      and new scale computed from requested bounding box.</para>
    <para>Query results include one table per layer. No results were found in 
      layer swiss_layer_1 and two results in swiss_layer_2. As requested, 
      attributes (here attribute_3 and attribute_4) are returned for each 
      row.<programlisting><![CDATA[
stdClass Object
(
  [timestamp] => 1107925732
  [serverMessages] => Array
    (
    )
  [imagesResult] => stdClass Object
    (
      [className] => ImagesResult
      [mainmap] => stdClass Object
        (
          [isDrawn] => 1
          [path] => images/110846607738541.jpg
          [width] => 500
          [height] => 500
          [format] => 
        )
      [keymap] => stdClass Object
        (
          [isDrawn] => 1
          [path] => images/110846607738542.png
          [width] => 150
          [height] => 99
          [format] => 
        )
      [scalebar] => stdClass Object
        (
          [isDrawn] => 
          [path] => 
          [width] => 
          [height] => 
          [format] => 
        )
    )
  [locationResult] => stdClass Object
    (
      [className] => LocationResult
      [bbox] => stdClass Object
        (
          [minx] => 550000
          [miny] => 100000
          [maxx] => 600000
          [maxy] => 150000
        )
      [scale] => 377952.96
    )
  [queryResult] => stdClass Object
    (
      [className] => QueryResult
      [tableGroup] => stdClass Object
        (
          [groupId] => query
          [groupTitle] => Query
          [tables] => Array
            (
              [0] => stdClass Object
                (
                  [tableId] => swiss_layer_1
                  [tableTitle] => swiss_layer_1
                  [numRows] => 0
                  [totalRows] => 0
                  [offset] => 0
                  [columnIds] => Array
                    (
                    )
                  [columnTitles] => Array
                    (
                    )
                  [noRowId] => 
                  [rows] => Array
                    (
                    )
                )
              [1] => stdClass Object
                (
                  [tableId] => swiss_layer_2
                  [tableTitle] => swiss_layer_2
                  [numRows] => 2
                  [totalRows] => 0
                  [offset] => 0
                  [columnIds] => Array
                    (
                      [0] => attribute_3
                      [1] => attribute_4
                    )
                  [columnTitles] => Array
                    (
                      [0] => attribute_3
                      [1] => attribute_4
                    )
                  [noRowId] => 
                  [rows] => Array
                    (
                      [0] => stdClass Object
                        (
                          [rowId] => 123
                          [cells] => Array
                            (
                              [0] => Foo
                              [1] => 84.98
                            )
                        )
                      [1] => stdClass Object
                        (
                          [rowId] => 456
                          [cells] => Array
                            (
                              [0] => Bar
                              [1] => 32.47
                            )
                        )
                    )
                )
            )
        )
    )
)]]></programlisting> </para>
  </sect2>
</sect1>
