Technical documentation of Geoportal API

  • FR
  • UK

Index / Documentation / Technical documentation

Access to datasets not located on the API server

2D Web Javascript API

Forewords

This chapter being quite technical before further reading, it is worth noting in which case your application is :

  • your web application and the data you want to access to are located on the same web server : cool, it is the simple case : just enter the path to data ! For instance, your web site is 'http://your.web.site/yourAppli.html', a KML file is located there 'http://your.web.site/kml/yourLayer.kml', you just have to create a layer with './kml/yourLayer.kml' as url.
  • your web application and the data you want to access to are not located on the same web server : bad luck, you need a proxy (and then read this page). In order to load the data, OpenLayers (and then the API) uses Ajax. Security rules prevent to access data from another web site the web page came from. To get data, you then need a service that your web site will ask for from them : it is the proxy (a kind of waiter handing over to you the data). This proxy must be running on your web site. For instance, your proxy url will be 'http://your.web.site/proxy/myProxy.asp' (or .php, ...). You have to set your proxy up :
    myMap.setProxyUrl('http://your.web.site/proxy/myProxy.asp');

    Where to find such a proxy service ? for instance there. You could also copy-paste the source code found on this page.

Introduction

In order to load a remote layer, a proxy service is required in order to retrieve data for the end-user. Basically, all data needed to be processed by the Javascript library on the client needs this functionality. So, layers like WFS, KML, GPX, OpenLS, ... (written differently, all XML responses from remote services) are ruled by this "proxyfication". OpenLayers add the URL to proxy to the proxy URL. The examples found below use the GET method with the url parameter to pass the target url.

Why using a proxy ?

OpenLayers uses AJAX request to retrieve data from various services. For security reasons, it is not possible to make such AJAX requests to services located in a different domain name (FQDN) than the API server (client of the those services). Therefore, it is not possible to access services from a server distinct from the API server (where the API is loaded).

This restriction can be suppressed via the use of a proxy located on the API server (the one that brings the map to the end-users). The hint is to send the AJAX request to the map server directly where the proxy runs, instead of the targetted service. The former forwards the requests to the targetted service, receives the responses and forwards them back to the OpenLayers clients.

The Geoportal API is based on that principal. The Geoportal.Map class supports setProxyUrl() method that takes one argument representing the proxy's URL to query as a characters string. In order to use layers not located on the API server, it is then mandatory to have a proxy service running along with this server. Its URL will be transmitted via a call to instance.setProxyUrl().

JSP proxy

The Geoportal API used to expose a JSP proxy and now use a servlet called xmlProxy. If you run a servlets engine at your API server side, you just may copy this JSP proxy into your servlets engine directory.

On the other hand, the servlets engine JVM (tomcat or other engine) might be set to use a proxy Lan to Wan service. For that, one has to use the following options :

-Dhttp.proxyHost=<proxy_address>  -Dhttp.proxyPort=<proxy_port>.

When using Eclipse environment, these options are found in the Window/Preferences menu, Tomcat item, JVM parameters, add parameters to the JVM.

PHP proxy

Using a PHP proxy is also possible for webmasters that don't use servlets engine. The following code shows how to set up such a proxy :

ASP proxy

Using an ASP proxy is also feasible. The following code uses the Coalesys (http://www.coalesys.com/products/httpclient/features/default.asp) component :

CGI proxy

It is also possible to use proxies developed in other languages (Unix Shells, Python, Perl, ...) via CGI. OpenLayers delivers such a proxy written in Python. With Perl, the following URL http://search.cpan.org/~book/HTTP-Proxy/lib/HTTP/Proxy.pm delivers a library to set up ones own proxy.

Here is a Perl example using the cURL library again.

How to set the proxy ?

Just call the setProxyUrl() method as follows :

function initGeoportalMap() {
    ...
    viewer= new Geoportal.Viewer.Default('viewerDiv', OpenLayers.Util.extend(
        options,
        // API keys configuration variable set by
        // <Geoportal.GeoRMHandler.getConfig>
        // variable contenant la configuration des clefs API remplie par
        // <Geoportal.GeoRMHandler.getConfig>
        window.gGEOPORTALRIGHTSMANAGEMENT===undefined? {'apiKey':'apikey'} : gGEOPORTALRIGHTSMANAGEMENT)
    );
    
    // maintenant maCarte est définie :
    viewer.getMap().setProxyUrl(Proxyurl);
    ...
}

We can also specify the proxy on the viewer's options :

function initGeoportalMap() {
        //options for creating viewer:
    var options= {
        // default value
        // valeur par défaut
        //mode:'normal',
        // default value
        // valeur par défaut
        //territory:'FXX',
        // default value
        // valeur par défaut
        //displayProjection:'IGNF:RGF93G'
        // only usefull when loading external resources
        // utile uniquement pour charger des resources externes */
        proxy:'proxyurl?url='
    };

    // viewer creation of type <Geoportal.Viewer>
    // création du visualiseur du type <Geoportal.Viewer>
    //                                       HTML div id, options
    viewer= new Geoportal.Viewer.Default('viewerDiv', OpenLayers.Util.extend(
        options,
        // API keys configuration variable set by
        // <Geoportal.GeoRMHandler.getConfig>
        // variable contenant la configuration des clefs API remplie par
        // <Geoportal.GeoRMHandler.getConfig>
        window.gGEOPORTALRIGHTSMANAGEMENT===undefined? {'apiKey':'apikey'} : gGEOPORTALRIGHTSMANAGEMENT)
    );
    ...
}

In the upcoming release of the Geoportal's API, most of the services will support the JSONP protocol when practicable, allowing to get JSON response embedding XML answers.