Interface inJAC-OAI
Installation

1. Pré-requis
2. Installation
  2.1. Déploiement
  2.2. Configuration générale
  2.3. Définition des formats exposés par fichier de mapping
    2.3.1. Mapping simple
    2.3.2. Mapping avancé
  2.4. Constitution de classification par ensembles (set)
  2.5. Paramètres de l'IHM
    2.5.1. Fichiers de configuration de l'IHM
    2.5.2. Ajout de liens sur le moteur de rendu

# 1. Pré-requis

Ce module d'inJac nécessite l'accès à un serveur Webdav doté d'un espace racine inJac.

Sur la machine de déploiement doivent être installés un environnement Java (JRE ou JDK), version 1.4.2 ou supérieur, ainsi qu'un moteur de servlet/jsp (TOMCAT 5.0.28 ou supérieur).

Pour lire ce document, il n'est pas inutile d'avoir une connaissance préalable minimale du protocole OAI-PMH , ou des principes de fonctionnement généraux de sa mise en oeuvre.

# 2. Installation

## 2.1. Déploiement

Pour déployer l'interface inJAC-OAI, il suffit de décompresser l'archive dans un moteur de servlet. Pour Tomcat, l'application peut être déployée dans le répertoire /webapps.

## 2.2. Configuration générale

Cette application est basée sur le projet OAICAT, d'OCLC Online Computer Library Center, dont la documentation contient une description du fichier original de configuration.

Pour la configuration d'inJac-OAI, tout se passe dans le fichier [$OAICAT_HOME]/WEB-INF/injac-oaicat.properties : (où [$OAICAT_HOME] représente le chemin d'installation de l'application, ex. : E:/Tests/jakarta-tomcat-5.0.28/webapps/injac-oaicat)

Voici les paramètres à renseigner qui sont propres à inJac (les autres étant décris dans la documentation dont le lien est indiqué plus haut) :

- OAIHandler.styleSheet=/injac-oaicat/xsl/injac-oaicat.xsl --> Commenter ou décommenter (insert une balise <?doctype?> en entête de la réponse xml)

- WebdavOAICatalog.maxListSize=1000 --> longueur de liste max renvoyée par requête (ListSets, ListRecords, ListIdentifiers)

- WebdavOAICatalog.url=http://saroumane.enseeiht.fr:8083/slide/files/injacRoot/Racine --> url de l'espace webdav

- WebdavOAICatalog.login=user --> login et mot de passe d'accès webdav WebdavOAICatalog.password=trusted

- WebdavOAICatalog.baseDir=[$OAICAT_HOME]

- WebdavRecordFactory.repositoryIdentifier=oaicat.injac.org --> identifiant du dépôt(doit être unique)

- Injac.Crosswalk.mapFiles=dcmapping.xml,etdmsmapping.xml,lom_fr_mapping.xml --> fichiers de mapping des formats exposés

- Injac.Crosswalk.mapDir=[$OAICAT_HOME]/WEB-INF/formats

## 2.3. Définition des formats exposés par fichier de mapping

### 2.3.1. Mapping simple

Le répertoire dont l'emplacement est défini par la propriété injac.Crosswalk.mapDir contient les fichiers définissant la conversion des métadonnées du serveur Webdav dans un format exposé par l'entrepôt OAI. Trois fichiers sont fournis dans le package :

- dcmapping.xsl définit un mapping pour le format Dublin Core

- etdmsmapping.xsl pour le format ETDMS (Electronic Thesis and Dissertations Metadata Set)

- lom_fr_mapping.xml pour un format LOM (Learning Object Model) francisé et simplifié.

Dans le sous-répertoire channel_profils se trouve un fichier de configuration pour la saisie des métadonnées dans le Canal de stockage au format LOM FR simplifié : lomfr_simple.xml (voir la documentation du Canal, section inJac).

La structure de ces fichiers de mapping se présente comme suit :

    <mapping
      metadata-prefix="oai_dc"
      root-tag="dc"
      metadata-namespace="http://www.openarchives.org/OAI/2.0/oai_dc/"
      schema="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd">
      <namespaces>
        <namespace prefix="dc" uri="http://purl.org/dc/elements/1.1/"/>
      </namespaces>
      <nativeItem>
        <mapping-attr
          source="webdavurl"
          dest="dc:source"/>
      </nativeItem>
      <webdav-metadata>
        <mapping-attr
          source="injac:title"
          dest="dc:title"/>
        <mapping-attr
          source="injac:author"
          dest="dc:creator"/>

Dans ce cas précis, il s'agit d'un mapping simple, où typiquement une métadonnée inJac (attribut source) correspond à un élément simple du format exposé (attribut dest).

Le formalisme de ce fichier est le suivant :

- <mapping> l'élément racine englobant

  - attribut metadata-prefix : préfixe utilisé comme paramètre OAI pour le paramètre metadataPrefix.

  - attribut root-tag : élément racine placé sous l'élément <metadatas> de la réponse OAI.

  - attribut metadata-namespace : nom d'espace pour ce format exposé.

  - attribut schema : URL du schéma XML pour ce format exposé (pour validation)

  - <namespaces> : élément englobant optionnel qui définit des noms d'espaces secondaires à intégrer à l'entête de la réponse OAI.

    - <namespace> définit un nom d'espace(attribut uri) et son préfixe(attribut prefix)

  - <nativeItem> : (optionnel) définit un mapping entre un élément interne de la représentation du document et un élément du format exposé. Les valeurs disponibles sont local-identifier(identifiant local de l'enregistrement OAI) et webdavurl(l'URL Webdav du document).

  - <webdav-metadata> : élément englobant obligatoire listant l'ensemble des correspondances entre les métadonnés inJac et les éléments du format exposé.

    - <mapping-attr> : le mapping proprement dit. L'attribut source est le nom de la métadonnées inJac, l'attribut dest est l'élément du format exposé. Trois autres attributs permettent de faire du mapping plus évolué(voir section Mapping avancé).

### 2.3.2. Mapping avancé

Des fonctionnalités de mapping supplémentaires sont accessibles à travers trois attributs de l'élément <mapping-attr> :

- multiparse définit un séparateur permettant de générer plusieurs fois la même balise en parsant la valeur de la métadonnées.

- required="yes" stipule que cette métadonnées est requise faute de quoi le document associé ne sera pas disséminé sous ce format.

- attributes permet de parser la valeur de la métadonnées pour y chercher la ou les valeur(s) d'un ou plusieurs attributs à ajouter à l'élément du format exposé(entre crochet).

Voici pour illustrer un exemple de mapping avancé :

## 2.4. Constitution de classification par ensembles (set)

Le fichier WEB-INF/setspecs.xml définit une classification par ensembles hiérarchisés à partir des métadonnées inJac associées aux documents. Par exemple, si on souhaite qu'un document possédant la métadonnée keyword=math soit classé comme appartenant à un ensemble "Mathématiques", il faut définir ainsi un élément <set> dans le fichier setspecs.xml :

    <ListSets>
     <set>
      <setSpec>math</setSpec>
      <setName>Mathematiques</setName>
      <setDescription>Ensemble de ressources de mathematiques enseignees dans l'etablissement.</setDescription>
      <metadata-matching match="any-of">
       <webdav-attr name="injac:keywords" multivalue="true" delimiter=",">
        <match-regexp>math</match-regexp>
       </webdav-attr>
      </metadata-matching>
     </set>
     ...

Pour chaque ensemble que l'on souhaite définir, il faut crée un élément <set> à l'intérieur de la balise englobante <ListSets>.

Chaque <set> contient à son tour trois éléments obligatoires et uniques :

- <setSpec> est le nom identifiant l'ensemble conformément au protocole OAI. Pour définir une hiérarchie les deux points servent de séparateur entre élements père et éléments fils, en lisant de gauche à droite, par exemple :

  - <setSpec>info</setSpec> ensemble de niveau 1

  - <setSpec>info:protocole</setSpec> ensemble de niveau 2 fils de l'ensemble "info"

- <setName> est le nom lisible utilisé pour être affiché.

- <setDescription> est la description de l'ensemble.

Aprés ces éléments, il faut définir un élément <metadata-matching>, lui-même composé d'un ou plusieurs éléments <webdav-attr>.

- <metadata-matching> contient une liste d'un ou plusieurs éléments <webdav-attr>, lesquels définissent les conditions d'appartenance à un ensemble.

  L'attribut match avec la valeur "any-of" stipule que le document appartient à l'ensemble dés qu'une des conditions définies dans les balises <webdav-attr> est remplie. Tout autre valeur de cet attribut est comprise comme "all", c'est-à-dire requiert la satisfaction de l'ensemble des conditions réunies pour que le document appartiennent à l'ensemble.

- <webdav-attr> définit une condition d'appartenance d'un document à un ensemble :

  - l'attribut name définit la métadonnée inJac dont la valeur est testée.

  - l'élément <match-regexp> est l'expression régulière servant à tester la valeur de la métadonnée

  - l'attribut optionnel multivalue="true" indique qu'il faut "parser" les valeurs multiples de la métadonnée à l'aide de l'attribut delimiter. Si ces attributs sont définis définis, chacune de ces valeurs est testée séparémment avec l'expression régulière.

Note : les expressions régulières suivent le format utilisé par le package java.util.regex (voir tutorial de Sun)

## 2.5. Paramètres de l'IHM

### 2.5.1. Fichiers de configuration de l'IHM

L'IHM d'inJac-OAI permet de visualiser le contenu exposé par l'entrepôt, en listant les ensembles(set) et formats disponibles.

La façon dont sont affichées les réponses est définie dans les fichiers :

- xsl/ihm_main.xsl (génération HTML pour la disposition en tableau) .

- css/style_1.css pour le style (couleurs, fontes...)

A moins de vouloir modifier l'apparence de l'IHM, aucune modification n'est nécessaire pour ce dernier fichier.

### 2.5.2. Ajout de liens sur le moteur de rendu

L'IHM propose par défaut des liens sur les documents du serveur Webdav, mais on peut également avoir des liens sur un moteur de rendu inJac.

Pour obtenir ces liens sur un moteur de rendu inJac installé, en plus des liens directs sur le serveur Webdav, il faut renseigner les paramètres rendererURI et upnode du fichier ihm_main.xsl :