Ce document présente les étapes d’installation du logiciel Universal Geocoder Server. Le choix des composants à installer est nécessaire lors de l’installation, parmi :
- UGC JEE,
- UGC Command Line,
- UGC .NET. (non disponible avec Geoconcept Web)
Ces composants sont indépendants entre eux et répondent à des problématiques différentes. Par exemple, le composant UGC JEE est nécessaire pour le widget « Geocoder » dans les portails.
Ce document décrit également le montage de d’adaptateur de ressource UGC en fonction du serveur d’application cible.
Enfin, l’installation des fichiers nécessaires à l’autocomplétion est décrite dans ce document. Pour utiliser le web service d’autocomplétion, merci de vous reporter à la partie API et Web Services de Geoconcept Web.
La procédure suivante ne concerne pas Geoconcept Web cas son installateur se charge d’installer et de paramétrer le composant UGC JEE.
Après avoir dézippé le dossier téléchargé, vous trouvez deux répertoires : un pour l’installateur 32 bits et un pour l’installateur 64 bits. Choisissez celui qui convient à votre architecture.
![[Astuce]](images/community/docbook/tip.png) |
Astuce |
|---|---|
|
Dans le cas d’utilisation de UGC JEE, la version 32 bits ou 64 bits est à choisir en fonction de votre architecture Java et Apache Tomcat :
Ce choix a son importance avec les DLL utilisées pour faire fonctionner UGC Server. Un UGC JEE 32 bits déployé sur un environnement 64 bits ne fonctionnera pas, et réciproquement. Nous recommandons d’installer la version 64 bits. |
Lancer l’installateur setup.exe, puis suivre les différentes étapes proposées par l’assistant d’installation.
Vous devez choisir les composants que vous souhaitez installer, en fonction de l’utilisation que vous souhaitez mettre en place :
- Composant .NET,
- Composant JEE,
- Composant CommandLine.
|
Astuce |
|---|---|
|
Les fichiers du référentiel de géocodage, portant des extensions .ugc.xxi, sont à placer dans le répertoire « <UGC_HOME> »\JEE\ugc\reftables
(répertoire par défaut) ou dans un répertoire spécifique de type D:\TableRef. Ce répertoire spécifique devra être paramétré
dans le fichier |
Ce chapitre décrit le montage de l’adaptateur de ressource UGC. Le mode de déploiement dépend du Serveur d’application cible.
|
Astuce |
|---|---|
|
L’utilisation du serveur d’application Apache Tomcat dans le cadre de l’installation de Geoconcept Web est décrite dans le manuel de Geoconcept Web. |
La suite de ce paragraphe décrit la configuration dans un cadre autre que Geoconcept Web. Certains éléments peuvent être similaires à une utilisation faite dans le cadre de Geoconcept Web.
Le répertoire dans lequel est installé Tomcat est noté par la suite %tomcat%.
Common Lib
Dans %tomcat%/common/lib, copier les fichiers stockés dans %livrable%/tomcat/lib :
- ugc.jar : librairie principale de l’adaptateur de ressource ugc-jee,
- jdom.jar : manipulation de documents XML,
- activation.jar : nécessaire, le copier s’il n’est pas présent,
- javax-resource.jar : nécessaire pour l’adaptateur de ressources.
Configuration server.xml
Au niveau du fichier de configuration principal de Tomcat, il faut déclarer le fournisseur de service primaire en lui associant un nom logique (JNDI) : dans tomcat%/conf/server.xml, éditez le tag GlobalNamingResources et ajoutez :
- pour Tomcat 7 et 8 :
<Resource
name="geoconcept/ugc/default"
type="com.geoconcept.ugc.connect.tomcat.ConnectionFactory"
scope="Shareable"
description="UGC connection factory - local dll"
auth="Container"
RootDirectory="%geoconcept%\ugc\"
factory="com.geoconcept.ugc.connect.tomcat.ConnectionFactory"
ConnectionMode="LocalDll"
/>
|
Astuce |
|---|---|
|
Pour toutes les versions de Tomcat, le paramètre RootDirectory doit correspondre à la racine de l’arborescence ugc externe au serveur d’application (contenant les répertoires conf, native et reftables). |
|
Astuce |
|---|---|
|
Vous pouvez ajouter le paramètre |
Dans la section Server, il est nécessaire d’ajouter :
<Listener className="com.geoconcept.ugc.connect.tomcat.LifeCycleListener" resource="geoconcept/ugc/default" />
|
Astuce |
|---|---|
|
L’ajout du Dans le cas où le nom logique utilisé n’est pas celui par défaut (geoconcept/ugc/defaut) adapter la configuration. |
Création des liens ressources / webapps dans Tomcat
Pour Tomcat, il est nécessaire, pour les webapps qui utilisent une ressource, de la déclarer au niveau du descripteur de contexte de webapp. Pour Tomcat 7 et 8 les fichiers de configuration de webapp peuvent être externalisés de conf/server.xml et être placés dans conf/catalina/localhost (par défaut).
Donc pour chaque webapp utilisant le fournisseur primaire (référencé via JNDI), comme ugc-admin ou ugc-samples, des fichiers de contexte sont fournis (pour Tomcat 7 et 8), de ce fait pour chaque webapp devant être déployée il faut :
- copier le war dans /webapps
- copier le fichier xml de description de contexte dans /conf/catalina/localhost
De même, si vous créez votre propre webapp qui utilise le fournisseur primaire, vous devez déclarer ce lien :
- par un fichier séparé pour Tomcat 7 et 8
Pour Tomcat 7 et 8 :
- Copier le fichier ugc-admin.xml qui est dans %livrable%\tomcat\conf dans le répertoire %tomcat%/conf/catalina/localhost ;
- Copier le fichier axis.xml qui est dans %livrable%\tomcat\webapps dans le répertoire %tomcat%/conf/catalina/localhost (utile uniquement pour utiliser Universal Geocoder JEE est mode d’accès distant).
|
Astuce |
|---|---|
|
Pour définir d’autres fichiers de contexte (fichier.xml) pour d’autres applications web, il est nécessaire d’ajouter les lignes suivantes : |
<ResourceLink
global="geoconcept/ugc/default"
name="geoconcept/ugc/default"
type="com.geoconcept.ugc.connect.tomcat.ConnectionFactory"
/>
Axis
Cette partie de l’installation est utile uniquement pour utiliser Universal Geocoder JEE en mode d’accès distant.
Copier le répertoire axis qui est dans install\tomcat\webapps dans le répertoire %tomcat%\webapps.
|
Astuce |
|---|---|
|
La documentation d’installation axis est accessible : http://ws.apache.org/axis/java/install.html#webapp. Pour tester axis, appeler http://localhost:8080/axis puis valider. HappyAxis est un auto-test. Vérifier qu’il n’indique pas de problème de librairies. |
Les librairies optionnelles manquantes ne sont pas gênantes ( mail, attachements, xml security, etc ).
Installation AddressFinderService
Dans %tomcat%/webapps/axis/WEB-INF/lib, copier le fichier ugc-axis.jar qui est dans install\tomcat\axis-std.
Déploiement du service AddressFinder :
- Lancer Tomcat,
- Ouvrir une fenêtre ligne de commande dans le répertoire \install\tomcat\axis-std puis exécuter deploy (si le port du serveur n’est pas 8080, modifier le fichier deploy.bat. Faire de même pour l’hôte si ce n’est pas localhost).
|
Astuce |
|---|---|
|
Les librairies Axis doivent être dans le CLASSPATH. |
Si le service est déployé correctement, le serveur répond :
... Processing file AddressFinderServiceAxis.wsdd <Admin>Done processing</Admin>
Dans le cas contraire, il indique une erreur.
Il existe deux modes de déploiement :
- Soit l’adaptateur de ressource est déployé en standalone (seul) et dans ce cas le service est accessible à tout autre module déployé sur la même instance Jboss,
- Soit l’adaptateur de ressource est déployé dans une application d’entreprise qui contiens des modules de publication et dans ce cas le service n’est pas accessible à un autre module déployé sur la même instance Jboss (il s’agit en quelque sorte d’un pré-déploiement complet).
Adaptateur standalone
- Copier le fichier ugc.rar qui est dans %livrable%\jboss\standalone\ra\deploy dans le répertoire %jboss%/deploy,
- Copier le fichier ugc-ds.xml qui est dans %livrable%\jboss\standalone\ra\deploy dans le répertoire %jboss%/deploy ; puis éditez le afin de modifier la valeur de RootDirectory,
- Copier le fichier ugc-common.jar qui est dans %livrable%\jboss\standalone\ra\lib dans le répertoire %jboss%/lib.
Sous forme d’archive d’application d’entreprise (EAR)
- Copier le fichier ugc-all.ear qui est dans %livrable%\jboss\standalone\ra\deploy dans le répertoire %jboss%/deploy,
- Copier le fichier ugc-ds.xml qui est dans %livrable%\jboss\standalone\ra\deploy dans le répertoire %jboss%/deploy ; puis editez le afin de modifier la valeur de RootDirectory.
L’adaptateur de ressource (ugc.rar) se déploie en mode standalone (seul), le service est accessible à tout autre module déployé sur la même instance Jboss (qu’il s’agisse d’un module fourni comme ugc-admin ou ugc-ws ou un module spécifique écrit par l’utilisateur).
La procédure de déploiement et de configuration suit les préconisations Jonas : il faut modifier la configuration du module puis le déployer via une des méthodes proposées par Jonas.
Livrable
Si le livrable est sous la forme d’une archive (.zip ou .tar.gz) il faut l’extraire dans un répertoire de travail (par exemple via « tar xvfz ugc-jee-5.0.112.tar.gz » sous linux), si il sous forme explosée le recopier dans un répertoire de travail.
Modifier la configuration de ugc.rar pour l’adapter à l’installation locale
Il est nécessaire de modifier la configuration de l’adaptateur de ressource UGC (ugc.rar situé dans jonas/standalone/ra/deploy) afin d’indiquer le chemin d’installation local.
Pour ce faire, la procédure Jonas est la suivante : il faut extraire le fichier jonas-ra.xml de l’archive (.rar) puis le modifier et enfin mettre à jour l’archive avec le fichier modifié. L’outil RAConfig de Jonas permet de générer le fichier jonas-ra.xml à partir du fichier ra.xml standard, mais içi cela n’a pas d’intérêt car le fichier jonas-ra.xml est fourni. Donc l’outil jar du jdk java suffit pour extraire et mettre à jour l’archive. Si JAVA_HOME/bin n’est pas dans le PATH il faut l’ajouter temporairement (ou bien invoquer l’outil jar en incluant ce répertoire, eg /etc/java/jdk1.5.0_22/bin/jar)
- Extraction du fichier jonas-ra.xml : jar xvf ugc.rar META-INF/jonas-ra.xml. Cela permet de créer le sous-répertoire META-INF et le fichier jonas-ra.xml à l’intérieur,
- Edition du fichier jonas-ra.xml : modifier le fichier jonas-ra.xml extrait afin d’indiquer dans la valeur de la propriété RootDirectory le répertoire dans lequel UGC a été installé. Si vous souhaitez utiliser un répertoire de tables de référence différent du répertoire par défaut (%ugc%/reftables) indiquez le dans la propriété optionelle RefTablesDirectory, sinon ce n’est pas nécessaire.
- Mise à jour de l’archive (.rar) : jar uvf ugc.rar META-INF/jonas-ra.xml
L’archive mise à jour est prête a être déployée sur une instance Jonas.
Déploiement sur Jonas 4.x
Le service ressource de Jonas doit être configuré et démarré au lancement (ce qui est le cas dans la configuration par défaut). C’est à dire que dans le fichier jonas.properties la valeur ressource doit être présente dans la liste des valeurs de la propriété jonas.services.
Il existe plusieurs façons de déployer un fichier RAR sur une instance Jonas :
- modifier les valeurs de jonas.service.resource.resources property du fichier jonas.properties : pour y ajouter ugc (le suffixe .rar n’est pas obligatoire).Exemple : jonas.service.resource.resources ugc,
- placer le fichier dans le répertoire autoload des connecteurs, qui par défaut est $JONAS_BASE/rars/autoload,
- en ligne de commande via la commande jonas admin -a ugc.rar,
- en utilisant la console d’administration web (jonasAdmin) accessible par défaut via http://localhost:9000/jonasAdmin,
![[Avertissement]](images/community/docbook/warning.png) |
Avertissement |
|---|---|
|
Pour plus de détails consulter http://jonas.ow2.org/JOnAS_4_7/doc/PG_Connector.html#PG_Connector-Use |
Le déploiement via le répertoire rars/autoload et le déploiement via jonasAdmin sont décrits ci-après.
- Déploiement par le répertoire rars/autoload : copier le fichier ugc.rar préparé dans $JONAS_BASE/rars/autoload et de relancer Jonas.
-
Déploiement via jonasAdmin
- Sélectionner Deployment > Ressource Adapter Modules (RAR) dans l’arborescence ,
- Sélectionner l’onglet Uplodad,
- Uploader le fichier depuis l’endroit où il a été préparé sur le disque. Cocher upload into the autoload directory sinon le déploiement n’aura lieu que pour la session courante de l’instance Jonas. Puis valider via le bouton Upload.
Cela aura pour effet de copier ugc.rar dans le répertoire JONAS_BASE/rars/autoload.
Le module est maintenant « deployable ».
- D) Ajouter ugc.rar aux modules déployés et confirmer.
Le module est désormais déployé. Au niveau de l’arborescence du serveur (à droite) il apparaît dans Services/Resource :
Déploiement de ugc-admin (optionnel) :
ugc-admin est une webapp d’administration qui permet (entre autres) de tester le bon fonctionnement d’ugc-jee. Son déploiement est optionnel. Le principe du déploiement est le même que pour l’adaptateur de ressource (ugc.rar) si ce n’est qu’il s’agit ici de la section Web Modules (WAR) et que ce module ne nécessite pas de configuration.
Puis déploiement :
La webapp est déployée.
Montage d’un fournisseur client web service sur Jonas 4.x
Jonas 4.x ne fournissant pas d’implémentation saaj 1.3, il est nécessaire de placer la librairie saaj-impl-1.3.2.jar (qui peut être prise dans redist/providers-libs/ws-saas-client-saaj13/libs) ou une version plus récente dans JONAS_BASE/libs/apps.
Exemple de configuration de fournisseur de type client web service saas basé sur saaj (extrait du fichier jonas-ra.xml) :
<jonas-config-property>
<jonas-config-property-name>ConnectionMode</jonas-config-property-name>
<jonas-config-property-value>WssClient</jonas-config-property-value>
</jonas-config-property>
<jonas-config-property>
<jonas-config-property-name>ServerUri</jonas-config-property-name>
<jonas-config-property-value>http://owss.geoconcept.com:2010/service/soap11</jonas-config-property-value>
</jonas-config-property>
<jonas-config-property>
<jonas-config-property-name>Key</jonas-config-property-name>
<jonas-config-property-value>123456</jonas-config-property-value>
</jonas-config-property>
Déploiement sur Jonas 5.x
Le déploiement est identique à Jonas 4.x excepté le fait que le répertoire $JONAS_BASE/deploy remplace les répertoires différenciés ($JONAS_BASE/rars/autoload, $JONAS_BASE/webapps/autoload) pour le déploiement.
L’environnement de déploiement décrit est Borland Enterprise Server, AppServer Edition version 5.2.1.
L’adaptateur de ressource (ugc.rar) et un ensemble de modules de publication (ugc-admin.war, ugc-samples.war, ugc-axis-fusion.war, etc ) se déploient sous la forme d’une application d’entreprise (archive .ear) : ugc-all.ear.
Configuration de ugc-all.ear : avant de déployer ugc-all.ear, il est nécessaire de le configurer pour mettre à jour les chemins d’installation locaux.
Pour ce faire le plus simple est d’utiliser Borland Deployment Descriptor Editor (DDEditor).
- Exécutez ddeditor et ouvrez ugc-all.ear
- Sélectionnez le module adaptateur de ressource (rar) dans l’archive d’application d’entreprise (ear)
- Sélectionnez l’onglet config properties du module adaptateur de ressource
- Indiquez le répertoire d’installation des fichiers externes au serveur d’application
- Sauvegarder les modifications effectuées
Déploiement de l’application d’entreprise (ugc-all.ear) dans Borland Management Console
Sélectionnez la partition sur laquelle vous voulez déployer :
|
Avertissement |
|---|---|
|
VisiConnect doit être activé dans les PartitionServices de la partition cible. |
Effectuez un clic droit sur la partition et choisissez « Deploy modules … »
Sélectionnez le fichier ugc-all.ear que vous avez modifié à l'étape précédente et validez :
Sélectionner finish et le déploiement se termine :
L’application ugc-all apparaît maintenant dans la liste des modules déployés pour la partition sélectionnée :
L’environnement de déploiement décrit est IBM WebSphere Application Server version 8.5.
L’adaptateur de ressource (ugc.rar) et un ensemble de modules de publication optionnels (ugc-admin.war, ugc-samples.war, ugc-axis-fusion.war, etc ) se déploient sous la forme de modules séparés (standalone). Les modalités de déploiement d’un module utilisateur qui consommerait les services de l’adaptateur de ressource ugc.rar sont les mêmes que ceux des modules optionnels fournis. Aussi le déploiement du module optionel ugc-admin sera décrit içi.
ugc-admin est un module optionel mais il permet en outre de valider le bon déploiement de l’adaptateur de ressource.
Il exite de nombreuses manieres de réaliser des déploiements dans WebSphere Application Server (par scripting, programmatiquement, par fichiers de propriétés, via wsadmin, etc), içi le processus de déploiement décrit sera celui de WebSphere Integrated Solutions Console (aussi appelé administrative console).
- Déploiement de l’adaptateur de ressource (ugc.rar) : se logger sur WebSphere Integrated Solutions Console
Aller dans Resources > Resource Adapters > Resource adapters (menu à gauche).
|
Avertissement |
|---|---|
|
Dans notre cas, Preferences/"show built-in resources" est coché (c’est pour cette raison qu’on voit les adaptateurs built-in). |
Cliquer sur "Install RAR" et sélectionner le fichier "ugc.rar" situé dans le sous répertoire websphere/standalone/ra/deploy du livrable
Puis « next » ; dans le champ « name », remplacer geoconcept/ugc/default par ugc-ra1 et validez.
ugc-ra1 apparait désormais dans la liste des adaptateurs de ressource déployés, cliquer dessus dans la liste
Dans la colonne Additional properties (à droite) cliquer sur " J2C connection factories"
Dans le champ Name, entrez ugc-connectionFactory, et dans le champ JNDI name, entrez geoconcept/ugc/default, puis « Apply ». Dans la colonne Additional properties (à droite), cliquer sur Custom properties.
Editez la valeur de RootDirectory pour lui donner le répertoire dans lequel sont les fichiers externes ugc, puis validez.
Sauvegardez (Save directly to the master configuration)
La connection factory est désormais déployée.
- Déploiement d’un module optionnel : nous allons maintenant déployer un module optionnel fourni, ici la webapp ugc-admin (un war), qui va consommer les services de l’adaptateur de ressources.
Le principe est le même pour n’importe quel module (fourni ou développé spécifiquement) consommant les services de l’adaptateur de ressources.
En outre ugc-admin permet de valider le déploiement de l’adaptateur de ressources.
Dans le menu à gauche aller dans Applications > New Application
Choisir New Enterprise Application.
Cliquer parcourir et sélectionner le fichier ugc-admin.war situé dans le sous répertoire websphere/standalone/webapps du livrable puis cliquer sur Next.
Laisser par défaut fastpath et cliquer Next.
Step 1 : laisser tout par défaut, puis Next.
Step 2 : laisser tout par défaut, puis Next.
Step 3 : entrer geoconcept/ugc/default dans Target Resource JNDI Name.
Un warning est indiqué, cliquez sur « continue ».
Step 4 : laisser tout par défaut, puis Next.
Step 5 : entrer le context root /ugc-admin (il propose / par défaut)
Step 6 : résumé (valider par Finish)
La console présente le statut de déploiement et indique Application ugc-admin_war installed successfull
Démarrer la webapp (cocher ugc-admin.war et cliquer sur Start)
La console indique "ugc-admin_war on server server1 and node sidrotNode01 started successfully. The collection may need to be refreshed to show the current status."
- Vérification du déploiement avec ugc-admin
Cliquer sur Check provider access
La page doit indiquer All tests succeeded.
Revenir à la page d’accueil de ugc-admin et cliquer sur Provider general status
|
Avertissement |
|---|---|
|
La page indique des informations de version et de runtime de l’instance du fournisseur et son environnement |
Revenir à la page d’accueil de ugc-admin et cliquer sur DataSources Configuration
La page liste les tables de référence disponibles. Cliquer sur test pour une des tables de référence listée. Cliquer sur Search
La page doit afficher un résultat correct, ce qui valide le déploiement.
Si le web service d’autocomplétion fourni par Geoconcept Web est utilisé, il est nécessaire de disposer et d’installer les fichiers de référence correspondants (copie simple des fichiers dans un répertoire).
Il est nécessaire de suivre les étapes suivantes pour un bon fonctionnement du web service d’autocomplétion :
-
Dans le répertoire
reftablesprésents dans UGC, créer un répertoire autocomp, - Copier le répertoire fourni par Geoconcept dans ce répertoire : le répertoire fourni par Geoconcept contient les fichiers de référence. Vous devez avoir l’architecture suivante :
Le nom du répertoire dans lequel se trouvent les fichiers de référence est important. Ce nom sera renseigné dans les paramètres à sauvegarder dans l’administration de Geoconcept Web (cf. Manuel de Geoconcept Web, Installation, Paramètres d’UGC). Merci de vous y reporter pour voir les paramètres à renseigner pour faire fonctionner le web service d’autocomplétion.
|
Avertissement |
|---|---|
|
Il est fortement déconseillé d’activer les logs UGC lors de l’utilisation du web service d’autocomplétion. En effet, ces logs sont alimentés à chaque requête d’un utilisateur et atteindront des volumétries considérables en quelques minutes d’une utilisation en production. De plus, les performances sont bien moindres avec les logs activés. |
