Documentation des Web Services de Geoconcept Web  -  UGC Server

Intégration JEE

ugc-jee est un composant d’intégration à la plate-forme JEE, il offre un service de géocodage aux modules JEE déployés sur une serveur d’applications (au sens large, moteur de servlet type Tomcat compris).

Le module consommateur peut être de n’importe quel type (webapp, ejb, etc). De même à l’intérieur du module JEE le consommateur peut être de n’importe quel type (servlet, jsp, pojo, etc).

Mode d’accès

L’application utilisant le géocodeur référence le fournisseur via un nom logique de l’annuaire JNDI (Java Naming and Directory Interface) du serveur d’applications. La manière de monter le fournisseur sera décrite plus loin.

Traditionellement, le nom logique utilisé est « geoconcept/ugc/default » du contexte « java:comp/env » mais il est possible d’utiliser un autre nom, un autre contexte ou de monter plusieurs fournisseurs de types différents.

Par soucis de simplicité le cas d’utilisation le plus courant (un seul fournisseur primaire local avec nommage par défaut) sera décrit dans un premier temps.

Organisation du composant

Adaptation de ressource JEE et éléments externes

ugc-jee se compose de plusieurs parties. Pour des questions de performances et de réutilisation, le moteur (aussi appelé noyau) est écrit en C++ et est donc diffusé sous forme de librairies natives. La partie intégration (adaptateur de ressource) réalise le lien avec le moteur en gérant sa mise en oeuvre par chargement de ses librairies natives. En terme de déploiement de fichiers cela concerne donc deux arborescences distinctes :

En terme d’exécution les librairies natives seront chargées en mémoire dans le processus de l’instance du serveur d’application (ou sa partition éventuelle selon les modèles) au démarrage. La partie adaptateur de ressource expose une interface java et gère le moteur instancié en mémoire directement via JNI.

Autre type de fournisseur

L’adaptateur de ressource décrit précédemment correspond au type LocalDll, il s’agit du fournisseur primaire, celui qui est lié au moteur de géocodage et réalise concrètement le traitement.

Dans certaines situations (pour diverses raisons : frontal séparé, partage, architecture, isolation, etc, etc) il est souhaité que le module qui consomme le service ne soit pas déployé sur la même instance de serveur d’application que le fournisseur primaire ugc (par exemple chacun étant sur deux machines serveur différentes - remoting).

Dans ce cas il existe plusieurs possibilités :

Le dernier cas est transparent pour l’application consommatrice : que le fournisseur soit local ou distant son code source ne change pas, il ne s’agit que d’une question de déploiement et de configuration (il s’agit en quelque sorte du pattern Multiple business delegate).

Le protocole de transport utilisé dépend du couple module de publication / client choisi : cela peut être web service (http/soap) ou rmi.

Dans tous les cas, dans le cadre de la mise en oeuvre de ugc-jee en mode installé (c’est à dire non SAAS), il existe une instance de fournisseur de type LocalDll. Par ailleurs, dans la mesure où ce fournisseur est local (pas de transfert, de sérialisation, etc) il est le plus performant (latence, débit).

Un certain nombre de modules additionnels sont fournis dans ugc-jee. Aucun n’est indispensable au bon fonctionnement de l’adaptateur de ressource et leur déploiement est optionnel.

ugc-admin

ugc-admin est une webapp permettant la vérification de la bonne installation du produit, sa configuration et le test de bon fonctionnement.

ugc-ws

ugc-ws est une webapp publiant un web service de géocodage. Elle est basée sur spring-ws (elle publie au format document / encodage litteral).

ugc-axis-fusion

ugc-axis-fusion est une webapp publiant un web service de géocodage prédéployé sur Axis 1.4 (elle publie au format rpc / encodage soapenc).

ugc-remote

ugc-remote est une webapp publiant le service de geocodage via rmi. Elle est notamment utilisée pour le remoting en conjonction avec le fournisseur de type RmiClient.

Configuration de mise en oeuvre

Un référentiel constitué d’un ensemble de fichiers portant des extensions .ugc.xxi, publié constitue une source de données (datasource).

Le fichier service.xml situé dans %ugc%/conf définit la configuration générale du fournisseur de service de géocodage. Celui ci contient notamment une configuration par défaut pour les sources de données (default‑datasource). Il est possible de définir une configuration spécifique à une source de données.

Pour définir une configuration particulière pour une source de données il est recommandé d’utiliser la webapp ugc‑admin (rubrique DataSourcesConfiguration puis configuration > create). Il est aussi possible d'éditer directement le fichier service.xml.

Si aucune configuration spécifique n’a été définie alors la configuration par défaut s’applique à la mise en oeuvre de cette source de données.

Par ailleurs il est possible de définir certains paramètres lors de l’appel (via findAddressOptions). Ainsi la valeur concrète que prend un paramètre (comme par exemple discrepancy) peut provenir (dans l’ordre) :

Configuration détaillée d’une source de données

Il est possible de définir la configuration de mise en oeuvre d’un référentiel de manière très détaillée.

Cette définition peut répondre à des besoins particuliers, elle n’est pas indispensable car la configuration par défaut convient pour la grande majorité des cas.

Certains paramètres sont définissables au moment de l’appel, d’autres sont fixés à la création de l’instance de source de données et non modifiables par la suite.

Les paramètres que l’on peut définir aussi au moment de l’appel seront décrits dans la section FindAddressOptions.

Datasource identification

Cette partie permet l’identification d’une source de données dans l’administration.

File : référentiel de géocodage utilisé. Elle est contenue dans %geoconcept%/ugc/reftables ou dans un sous-répertoire.

Name : alias de nom de la source de données (optionnel).

Publication information

Cette partie permet d’ajouter des informations sur la source de données.

Title : un titre pour la source de données.

Abstract : contient une courte description de la source de données.

Online ressource : lien HTTP donnant plus d’informations sur la source de données.

Reference table settings

Version : version du référentiel.

Zone meaning : sens de l’attribut "zone" de l’adresse. Exemple : Code postal.

UniqueId meaning : sens de l’identifiant de recherche uniqueId.

SecondaryZone meaning : sens de l’attribut secondaryZone de l’adresse. Exemple : Code IRIS.

StreetSectionId meaning : sens de l’attribut streetSectionId de l’adresse. Exemple : PID navteq.

Coordinate system : identifiant du système de coordonnées de référence pour la publication (cf norme OpenGIS).

Country : pays concerné.

Bounds : rectangle d’encombrement des données du référentiel

Run time settings

Cache : activation ou non du cache. Ce cache permet de garder en mémoire des villes du référentiel.

Max Cache Mem Size est utilisé uniquement si le cache est actif. Taille de la mémoire réservé pour le cache en Ko.

Min processors : nombre initial d’instances de géocodage.

Max processors : nombre maximum d’instances de géocodage.

Finder general settings

City scoring method : méthode de calcul à utiliser pour le score de la ville :

Street scoring method : méthode de calcul à utiliser pour le score de la rue :

Min streets : nombre de rues minimum pour qu’une ville soit considérée comme couverte. Utilisé pour la tolérance à la vill ( FindAddressResults.TOLERATE_TYPE_CITY ).

Stratégie de recherche :

Pour plus de détail sur les stratégies de recherche, se reporter au manuel d’utilisation de Universal Geocoder

Finder request defaults settings

Max candidates : nombre maximum de résultats renvoyés par un géocodage. Voir FindAddressOptions.candidateCount.

Score threshold : score au-delà duquel les résultats du géocodage sont conservés. Voir FindAddressOptions. ScoreThreshold.

Score threshold : seuil de proposition de candidats de type « rue ». Voir FindAddressOptions. ScoreThreshold.

Find type : type de géocodage souhaité. Voir FindAddressOptions.geocodingType.

Tolerate geocoding type : tolérance de géocodage souhaitée. Voir FindAddressOptions.tolerateGeocodingType.

Max meter error : erreur de placement maximale (en mètres) pour considérer un géocodage à la rue comme un géocodage au numéro. Voir FindAddressOptions.maxMeterError. Discrepency : décalage latéral. Voir FindAddressOptions.discrepency.

Discrepancy along street : décalage longitudinal. Voir FindAddressOptions.discrepency.

Favor city match element : orienter la recherche de la ville avec un élément descriptif de la ville. Voir FindAddressOptions.favorCityMatchElement.

Zone match digits : prise en compte de n premiers caractères de l’attribut zone de l’adresse. Voir FindAddressOptions.zoneMatchDigits.

Tests / Troubleshooting pour AXIS 1.4

Vérifier le bon chargement de l’adaptateur de ressource au démarrage de Tomcat. Vous pouvez utiliser la webapp ugc-admin pour valider l’installation.

Dans le cas de l’utilisation du Web Service, vérifier la présence du service AddressFinder dans axis :

Lorsque le fournisseur est utilisé directement à l’intérieur de la plate-forme java (via des objets java simples ou « POJO »), l’appel prend la forme suivante :

La fonction findAddress a la forme simplifiée suivante :

FindAddressResults findAddress(Address, FindAddressOptions);

C’est à dire que l’appel prend en entrée une adresse et des options et renvoie en sortie un certain nombre de candidats.

La décomposition précise est donnée ci-après.

Package com.geoconcept.ugc.service

Class CodingProvider

Méthode getConnection :

Cette méthode permet d’ouvrir une connexion sur le fournisseur de géocodage. Une connexion doit être par la suite fermée par sa méthode Close.

Prototype :

Connection getConnection() throws ResourceException;

Valeur retournée :

Connexion sur le fournisseur de service de géocodage.

Class Connection

Méthode findAddress :

Cette méthode permet de géocoder une adresse avec d'éventuelles options de géocodage.

Prototype

FindAddressResults findAddress(Address address, FindAddressOptions options)

throws InvalidDataSourceException , InternalErrorException;

Paramètre Description

address Adresse à géocoder

options Options de géocodage

Valeur retournée

Liste résultat du géocodage.

Package com.geoconcept.common.geo

class Location

Cette classe contient les coordonnées trouvées lors d’un géocodage.

Membres

Package com.geoconcept.ugc

class Address

Cette classe contient la description d’une adresse.

Membres

class FindAddressOptions

Cette classe contient le paramétrage d’un géocodage.

Tous les éléments, à part dataSourceName sont optionnels. Si ils ne sont pas affectés ils prennent leur valeur par défaut qui est optimale dans la grande majorité des cas.

Class FindAddressResults

Classe qui contient les résultats d’un géocodage, classés par score.

Membres

Constantes

class FindAddressResult

Classe qui contient le résultat d’un géocodage.

Membres

Principe d’utilisation

Pour réaliser un géocodage il faut effectuer les opérations suivantes :

Exemple

Connection au fournisseur de service de géocodage

import com.geoconcept.ugc.service.CodingProvider;
import com.geoconcept.ugc.service.Connection;

/*
*Open a connection on the geocoding server
*/
public Connection getConnection() throws Exception
{
        Connection connection = null;
        try
        {
                // get context
                Context initCtx = new InitialContext();
                Context envCtx = (Context) initCtx.lookup("java:comp/env");

                // retrieves the geocoding server form the logical name
                CodingProvider codingProvider = (CodingProvider) envCtx.lookup("geoconcept/ugc/default");
                connection = codingProvider.getConnection();
        }
        catch (Exception e) { e.printStackTrace(); }
        return connection;
}

Construction de l’adresse à géocoder

import com.geoconcept.ugc.Address;

/*
*Construct an adress to geocode
*@param  addressLine address number + address  way type + address  way name. Sample : "25 rue de Tolbiac"
*@param   zone adress sone. Sample : "75013"
*@param  cityName city name. Sample : "Paris"
*@param  uniqueId city unique identifier. Sample : "75113000"
*
*/
public Address getAddressToGeocode(String  addressLine, String  zone,String cityName,String uniqueId)
throws Exception
{
        Address address = new Address();
        address.addressLine = addressLine;
        address.zone = zone;
        address.cityName = cityName;
        address.uniqueId = uniqueId;
        return  address;
}

Construction des options de géocodage

import com.geoconcept.ugc.FindAddressOptions;

/*
*Retrieves geocoding options from the data source defined in administration
*@param  datasource Name of a data source
*/
public FindAddressOptions  getOptions(String datasource) throws Exception
{
        FindAddressOptions options = new com.geoconcept.ugc.FindAddressOptions("myDataSource");
     return  options;
}

Exécution du géocodage

import com.geoconcept.ugc.service.Connection;
import com.geoconcept.ugc.Address;
import com.geoconcept.ugc.FindAddressOptions;
import com.geoconcept.ugc.FindAddressResults;

/*
*Launch geocode process and retrieves results
*@param  connection Connection to the geocode server
*@param  address Address to geocode
*@param   options Geocoding options
*/
public FindAddressResults  findGeocode(Connection connection, Address address , FindAddressOptions options) throws Exception
{
        FindAddressResults findAddressResults  = connection.findAddress(address, options);
        return  findAddressResults;
}

Exploitation du résultat

import com.geoconcept.ugc.FindAddressResults;
import com.geoconcept.ugc.FindAddressResult;
/*
*Browse geocoding results and display result
*@param  findAddressResults  Results of geocode process
*/
public void displayResult(FindAddressResults findAddressResults) throws Exception
{
        // if at least one found result
        if (findAddressResults.results.length > 0)
        {
                // Display colunm name
                system.out.println("Found results : ");
                system.out.println( "N°"+ "\t"
                                + "Geocoding Type"+ "\t"
                                + "Score"+ "\t"
                                + "Address line"+ "\t"
                                + "Zone"+ "\t"
                                + "City Name"+ "\t"
                                + "City Unique Identifier"+ "\t"
                                + "Adress Secondary Zone"+ "\t"
                                + "Coordinates (Coordinates System)");

                // For each found results
                for (int i = 0; i < findAddressResults.results.length; i++)
                {
                // get next found result
                       FindAddressResult findAddressResult = found.results[i];

                String  coordinateSystem = null;
                if (findAddressResult.location.coordinateSystem != null)
                {
                        coordinateSystem = findAddressResult.location.coordinateSystem;
                }
                else
                        coordinateSystem = "(Unknown)";

                        // Display result
                system.out.println( i + "\t"
                                + findAddressResult.address.type + "\t"
                                + findAddressResult.address.score + "\t"
                                + findAddressResult.address.addressLine + "\t"
                                + findAddressResult.address.zone + "\t"
                                + findAddressResult.address.cityName + "\t"
                                + findAddressResult.address.uniqueId + "\t"
                                + findAddressResult.address.secondaryZone + "\t"
                                + findAddressResult.location.x + ","+ findAddressResult.location.y
                                + "( + coordinateSystem + ")");
                }
        }
        else
        {
                system.out.println("No found result.");
        }
}

Déconnexion du fournisseur de service de géocodage

import com.geoconcept.ugc.FindAddressResult;
import com.geoconcept.ugc.service.Connection;
/*
*Disconnection of the geocode server
*@param  connection  Connection to the geocode server
*/
public void closeConnection(Connection connection) throws Exception
{
         connection.close();
}

Exemple complet

import com.geoconcept.ugc.service.CodingProvider;
import com.geoconcept.ugc.service.Connection;
import com.geoconcept.ugc.Address;
import com.geoconcept.ugc.FindAddressOptions;
import com.geoconcept.ugc.FindAddressResults;
public void geocodingSample()
{
        try
        {
                // Open connection
                Connection connection = getConnection();
                // Construct the address to geocode
                Address address = getAddressToGeocode("25 rue de Tolbiac","75013","Paris","");
                // retrieves geocode options
                FindAddressOptions options = getOptions("myDataSource");
                // launch geocode process
                FindAddressResults findAddressResults = findGeocode(connection, address , options);
                // print geocoding result.
                displayResult(findAddressResults);
                // disconnection
                closeConnection(connection);
        }
        catch(Exception e)
        {
                // geocoding problem
        }
}