Indexing - Développement

Retrouvez ici tous les points importants destinés aux développeurs de ce module.

Les champs de l'index

Ajouter un champ dans l'index

1) Ajouter le champ dans le fichier schema.xml de Solr (ATTENTION : il existe deux fichiers distincts, un pour les tests et un pour la production, ne pas oublier de modifier les deux).

2) Ensuite tout dépend s'il s'agit d'un champ commun à tous les formats (exemple md-ori-oai-id qui représente l'identifiant de la fiche) ou s'il est spécifique à un format donné.

a) Commun à tous les formats

  • Ajouter une entrée dans applicationContext.xml au niveau de la balise <property name="oriOaiCommonMetadata">.
  • Modifier ConfigurationService ainsi que ConfigurationServiceInterface de façon à lui ajouter le getter correspondant au nouveau champ.

Exemple :

@Override
public String getRecordStatusMetadata() {
    return oriOaiCommonMetadata.get("recordStatus");
}
  • Ajouter une propriété dans la classe IndexRecord du module ORI-OAI commons

  • Charger la propriété dans la méthode getOneRecord de SolrSearchService, par exemple :

    indexRecord.setInternalRecord(Boolean.valueOf((String)doc.getFieldValue(configService.getInternalRecordMetaData())));

b) Spécifique à chaque format

  • Ouvrir le fichier fieldsConfig.xml et ajouter le champ en spécifiant le xPath correspondant à la balise de la fiche XML (ATTENTION : il y en a deux : un pour les tests, un pour la production).
  • L'attribut sera chargé automatiquement (s'il est demandé) dans les méthodes concernées de la classe SolrSearchService.

Ajouter un attribut à un champ

1) Ouvrir le fichier fieldsConfig.xml (ATTENTION : il y en a deux : un pour les tests, un pour la production) et ajouter les attributs nécessaires :
Exemple :

<field name="foo" *boost*="2"/>

(où boost est le nouvel attribut).

2) Ajouter les getter et setter dans Field.java.

3) Ouvrir le fichier FieldsConfigDigester.java et ajouter une ligne afin que l'attribut soit interprété, par exemple :

digester.addSetProperties("index/xml/xmlFile", "boost", "boost");

Conditions pour que l'indexation et le gestionnaire de documents externes soient exécutés

Conditions d'indexation et de récupération du plein texte

  • La classe responsable de ce traitement est ExternalDocumentService.
  • Les paramètres de configuration sont définis dans la définition du bean externalDocumentService dans le fichier commonBeans.xml.

Indexation du plein texte

Il existe un processus de "crawling" qui permet d'explorer différentes URL à partir d'une URL de départ. L'étendue de l'exploration est définie dans le fichier configIndexing.xml.
Pour chaque URL explorée on récupère le plein texte associé, sous-certaines conditions définies ci-après :

1) Le gestionnaire de documents externes doit être activé.

2) L'indexation du plein texte doit être autorisé (INDEXING_FULL_TEXT=true dans common-parameters.properties).

3) Le type mime de l'URL doit être autorisé dans le fichier configIndexing.xml.

3) Ensuite il doit satisfaire l'une des conditions suivantes :

  • On demande explicitement la réindexation du plein texte d'une fiche (par l'interface d'administration de l'indexing).
  • Le document n'a jamais été indexé OU sa dernière indexation date de plus de recheckURLsAfter jours (défini dans le fichier configIndexing.xml).

Conditions d'indexation dans SOLR

Pour qu'une fiche soit (ré)indexée, une des conditions ci-dessous doit être vérifiée :

  • Demande explicite par un web service.
  • Suite à la récupération du plein texte, la fiche est réindexée afin que les données du plein texte puissent être retrouvées.
  • Dans le cas où la fiche n'avait pu être que partiellement transformée par le Vocabulary, une ré-indexation est effectuée afin de tenter une nouvelle transformation.
  • Si l'état "definitive dead link" a changé (car cette information est stockée dans l'index pour pouvoir filtrer lors de la recherche).

Traitement a posteriori des enregistrements (fiches)

  • Le traitement des enregistrements a posteri consiste à générer le vocabulaire dans les fiches et en assurer la tratuction.
  • La classe en charge de ce traitement est PostProcessRecordService.java.
  • C'est un processus qui est itératif car il est possible qu'à un instant donné l'intégralité de la fiche ne puisse être transformée (si le vocabulaire concerné n'est pas disponible)
  • Il est lancé par un "cron" défini dans le bean postProcessRecordCronTrigger du fichier applicationContext.xml.
  • Les fiches examinées sont :
    • celles qui n'ont pu être transformées en intégralité et qui sont locales (viennent du workflow).
    • celles qui n'ont pu être transformées en intégralité et dont la date de dernière examination a dépassé un certain délai (attribut du bean postProcessRecordService dans le fichier commonBeans.xml).
  • Le processus de transformation peut être forcé depuis l'interface d'administration de l'Indexing.

Tests

Les classes de tests

Tests unitaires

Ils portent le nom de la classe qu'ils testent, suffixés par "Test" (exceptés ceux cités dans le paragraphe suivant). Par exemple la classe DbRecordTest exécute les tests de la classe DbRecord.

Tests transversaux

  • GenericDAOTest pour la partie générique de la base de donnés : ajout, suppresion, lecture de données. Elle vérifie que la base de données fonctionne correctement.
  • IndexerTest pour la partie indexation pure : elle vérifie que le moteur d'indexation fonctionne (filtre sur les champs, recherches avec accents, récupération des facettes, ...).
  • GlobalIndexingTest pour le processus d'indexation dans son ensemble : elle vérifie que la base de données et l'indexation fonctionnent.

Exécution des tests

  • Une base de données doit exister : elle doit avoir obligatoirement le nom de la base de production suffixé par "_test", par exemple "orioai_indexing_test".
  • Le type de base de données utilisée par défaut est hsqldb qui s'exécute en mémoire et est donc plus rapide qu'une base de données classique.
  • Les tests peuvent s'exécuter depuis la racine du projet ou dans le module indexingCore.

  • Ils s'exécutent par la commande :

    mvn clean test
  • Il est possible de n'exécuter qu'une partie des tests (dans ce cas on doit être dans le répertoire du module qui contient la classe de test) :

    • Une classe, par exemple :

      mvn -Dtest=IndexerTest clean test

    • Une méthode, par exemple :

      mvn -Dtest=IndexerTest#changeRecordSet clean test

  • Il est possible de spécifier une autre base de données en utilisant un profil Maven :

    mvn -P mysqlTests clean test # Pour MySQL
mvn -P pgTests clean test # Pour PostgreSQL

Remarque : pour la classe ExternalDocumentServiceTest on utilise Jetty, qui fait office de serveur web local. Le port est défini dans le fichier pom.xml du module indexingCore, au niveau de la balise :

<test.http.server.port>9090</test.http.server.port>

Dépendances requises pour exécuter les tests

Si aucun déploiement n'a été effectué depuis la racine du projet et qu'on souhaite par exemple exécuter les tests dans le module indexingCore il faut d'abord s'assurer que les modules solrAdmin et crawler ont été installés dans le dépôt local de Maven. Pour ce faire, il suffit d'aller dans chacun des modules et d'exécuter :

mvn clean install

Ignorer les tests

Par exemple pour exécuter la phase "install" de Maven sans les tests, saisir la ligne suivante :

mvn -DskipTests=true clean install

Quelques conseils

  • Exécuter très régulièrement les tests.
  • En cas de modification au niveau de la base de données, penser à exécuter les tests avec le type de base qui sera en production (grâce au profil Maven décrit plus haut).

SOLR

Configuration

  • Toute la configuration de Solr (aussi bien la partie production que la partie test) se trouve dans le répertoire
    src/main/resources/solr_home du module indexingCore.
  • Solr est séparé en deux coeurs (cores) qui sont définis au niveau du fichier solr.xml :
    • Un coeur est utilisé pour les test : test_public
    • L'autre est utilisé pour la production : prod_public

Administration

Module d'administration

Le module qui permet d'accéder à l'interface d'administation est solrAdmin. Il s'agit donc d'une webapp à part entière qui est installée lorsqu'on effectue le déploiement depuis la racine de l'indexing (ant all).

Ce module, lorsqu'il est déployé, a accès à la configuration de Solr grâce au fichier tomcat/conf/Catalina/localhost/ori-oai-indexing.xml qui contient les éléments suivants :

<?xml version="1.0" encoding="UTF-8"?>
<Context displayName="ORI-OAI Indexing (Core)" docBase="ori-oai-indexing" path="/ori-oai-indexing" debug="5">
    <!-- Used to access over http to the Solr administration interface -->
    <Environment name="solr/home" type="java.lang.String" value="/home/projets/uvhc/ori_oai/bin/tomcat/webapps/ori-oai-indexing/WEB-INF/classes/solr_home" override="true" />
</Context>

Grâce à la variable d'environement solr/home, le module solr-admin peut savoir où se trouve la configuration de Solr.

Ce fichier ori-oai-indexing.xml est généré au moment du déploiement grâce au fichier src/main/webapp/META-INF/context.xml.

Accès à l'interface d'administration

Pour accéder au module administration fournie par le module Solr, il existe deux possiblités :

  • Lorsque le module indexing est déployé : http://<adresse>/solr-admin

  • Avec Jetty : depuis le module solr-admin lancer :

    mvn jetty:run

    L'accès se fait ensuite (par défaut) par http://localhost:9090/solr-admin. Attention dans ce dernier cas, si vous effectuez des modifications dans la configuration de Solr (solrconfig.xml, schema.xml...) qui se trouve dans le module ori-oai-indexing il faut veiller à effectuer un mvn clean compile dans ce module. En effet Solr a pour "home" le chemin ../indexingCore/target/classes/solr_home (voir définition du plugin maven-jetty-plugin dans le pom.xml.

L'utilitaire Luke

Il s'agit d'un utilitaire permettant d'explorer le détail d'un index local (contenu, statistiques...). Pour le lancer, remonter à la racine du projet et excécuter :

cd utils
java -jar <nom_archive_luke.jar>

Mise à jour

Note : ceci est la procédure qui a été suivie pour la mise à jour vers Solr 4.0.

  • Télécharger Solr et le décompacter.
  • Remplacer le contenu de src/main/webapp du module solrAdmin par celui se trouvant dans example/solr-webapp/webapp de la nouvelle version de Solr.
  • A la racine du projet, ouvrir le fichier pom.xml et changer le no. de version existant solr.version par le no. souhaité.
  • Relancer les tests (mvn clean test) dans le module indexingCore.

Jetty

Le serveur d'application Jetty est utilisé, dans le module indexingCore, à deux niveaux :

  • En tant que serveur web local, notamment lors de l'exécution des tests de la classe ExternalDocumentServiceTest.

  • En tant que serveur d'application léger pour accéder à l'application. Pour ce faire, dans le module indexingCore,  exécuter :

    mvn [clean] jetty:run

    L'accès s'effectue ensuite par l'URL : http://localhost:9090/ori-oai-indexing. Jetty fonctionne en mode "inplace" c'est à dire qu'il utilise les classes se trouvant dans le répertoire target du module indexingCore. Ce répertoire est automatiquement généré lors de l'exécution de la commande. L'avantage d'utiliser Jetty en phase de développement est qu'il est très rapide à se lancer et donc évite un déploiement par Tomcat.

Base de données

L'application utilise Hibernate pour communiquer avec la base de données.

Fichiers de configuration

  • src/main/resources/indexing-dao.xml : définit les différents services DAO qui permettent d'accéder aux éléments de la base de données
  • src/main/resources/spring/common/dao/dao.xml : définit les différents paramètres d'accès à la base de données. Il existe le même fichier au niveau des tests : src/test/resources/spring/common/dao/dao.xml.

Architecture

Il existe un mapping objet Java - table. Ce mapping est défini sous forme d'annotations directement dans la classe Java. Il existe quatre entités qui permettent le stockage des données en base (voir commentaires dans le code pour le détail) :

  • DbRecord.java
  • DbRecordFormat.java
  • DbRecordFormatLang.java
  • DbRecordUrl.java

Chacune de ces entités dispose d'un service DAO qui permet de manipuler les données en conséquence :

  • RecordDAO.java
  • RecordFormatDAO.java
  • RecordFormatLangDAO.java
  • RecordUrlDAO.java

Ajout / modification d'un attribut dans l'index et dans la base de données

DbRecord.java vs IndexRecord.java

  • DbRecord.java (et ses objets associés) contient les données issues de la base de données. Cette classe fait partie du module indexingCore.
  • IndexRecord.java (et ses objets associés) contient les données issues de l'index. Cette classe fait partie du module orioai-commons (commun à tous les modules d'ORI-OAI).

Ces deux classes (et les classes associées) sont très proches dans leur structure mais pas totalement identiques (ce qui est stocké dans la base ne l'est pas pas forcément dans l'index et vice-versa, cependant il existe de nombreuses données en commun). Si un attribut commun doit être ajouté il faut alors effectuer des adaptations dans les méthodes fromIndexRecordFormat et toIndexRecordFormat de la classe DbRecordFormat.java.

Compilation - Installation

Général

Comme pour tous les autres modules d'ORI-OAI, le déploiement de l'application se fait par un :

ant all

.
Il doit se faire à la racine du projet. Le fichier build.xml utilisé par Ant fait appel à Maven qui à son tour appelle Maven pour les sous-modules (indexingCore, solrAdmin, crawler).

orioai-commons

Ce module, commun à toutes les parties d'ORI-OAI, doit être redéployé lorsque des modifications y sont effectuées (par exemple dans la classe IndexRecord.java).

Avant le déploiement

Changer le no. de version dans le fichier pom.xml.

Déploiement

  • Installation dans le dépôt local de Maven :

    mvn clean install

  • Déploiement sur le serveur Source Sup :

    mvn clean deploy

    . Pour ce dernier vous devez avoir les droits correspondants sur le serveur Source Sup. Il faut alors dans le fichier de configuration de Maven .m2/settings.xml ajouter les lignes suivantes :

    <servers>
...
    <server>
        <id>mvn.esup-portail.org</id>
        <username>votreNomUtilisateur</username>
        <password>votreMotDePasse</password>
    </server>
...
</servers>

Après le déploiement

Dans le fichier pom.xml du module indexingCore, il faut mettre à jour le numéro de version dans la déclaration de la dépendance à orioai-commons.

indexingCore

Si aucun déploiement n'a été effectué depuis la racine du projet et qu'on souhaite par exemple exécuter les tests dans le module indexingCore il faut d'abord s'assurer que les modules solrAdmin et crawler ont été installés dans le dépôt local de Maven. Pour ce faire, il suffit d'aller dans chacun des modules et d'exécuter :

mvn clean install
  • No labels