Interface inJAC-OAI
Installation

1. Pré-requis
2. Changements
3. Installation
  3.1. Déploiement
  3.2. Configuration générale
  3.3. Définition des formats exposés par fichier de mapping
    3.3.1. Mapping simple
    3.3.2. Mapping avancé
  3.4. Constitution de classification par ensembles (set)
  3.5. Paramètres de l'IHM
    3.5.1. Fichiers de configuration de l'IHM
    3.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. Changements

- Version 1.1

  - nouveau paramètre WebdavOAICatalog.setsFile pour le fichier de définition de sets

  - nouveaux paramètres upnode, renderURL et intDocs

  - URL de moteur de rendu inJAC pour les documents référencés (voir la description des fichiers de mapping pour la définition des formats exposés)

# 3. Installation

## 3.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.

## 3.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:/java/jakarta-tomcat-5.0.28/webapps/injac-oaicat)

L'emplacement de ce fichier doit être paramétré dans le fichier WEB-INF/web.xml, dans la balise :

      <param-name>properties</param-name>
      <param-value>/home/injac/tomcat/webapps/injac-oai/WEB-INF/injac-oaicat.properties</param-value>

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]

- WebdavOAICatalog.setsFile=[nom du fichier pour la définition des sets OAI] (à placer dans le répertoire WEB-INF/) La valeur par defaut est setspecs.xml.

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

- upnode, renderURL et intDocs : noeud racine inJAC, URL du moteur de rendu inJAC, et extensions des fichiers rendus en HTML. Ces paramètres servent à retourner une URL sur le moteur de rendu inJAC. Le paramètre intDocs ne doit pas être modifié, il doit rester en rapport avec le traitement des rendus pris en charge par le moteur de rendu. (Pour plus de détails sur l'utilisation des URL de rendu, voir la section suivante concernant les fichiers de mapping).

- 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

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

Le mapping défini ici répond à deux problèmatiques : la première consistant à mettre en correspondance des attributs stockés dans un serveur WEBDAV avec des éléments d'un format exposé par un entrepôt OAI. La deuxième problématique, qui en découle, est que ces attributs WEBDAV sont stockés en rateau et n'ont aucune profondeur ou imbrication, contrairement à certains des formats que l'on voudrait exposer via OAI, tel que LOM par exemple.

### 3.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é(le schéma xml pour validation est situé à l'emplacement injac-oai/schema/lomfr.xsd).

Pour rendre possible la validation pour ce dernier format, vous devez modifier l'URL définie par l'attribut schema de la balise <mapping>, exemple :

    schema="http://injac.esup.org/lomfr http://saroumane.enseeiht.fr:810/injac-oai/schemas/lomfr.xsd"

Dans le sous-répertoire WEB-INF/formats/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 la validation du jeu de métadonnées(Attention : ce schéma est utilisé par les moissonneurs pour valider les métadonnées transmises dans les réponses OAI. L'URL indiquée doit référencer un emplacement accessible et valide pour rendre possible cette 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)

  - <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é).

  - <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 pour l'attribut source des balises <mapping-attr> de cette balise sont

    - local-identifier : identifiant local de l'enregistrement OAI

    - webdavurl : l'URL Webdav du document

    - renderurl : l'URL vers le rendu du document produit par le moteur de rendu spécifié par le paramètre renderURL du fichier de propriétés.

### 3.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é :

## 3.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)

## 3.5. Paramètres de l'IHM

### 3.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.

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

Note : la version 1.1 permet de définir directement les liens sur le moteur de rendu par des paramètres du fichier de propriétés, et l'utilisation de la valeur "renderurl" dans les fichiers de mapping (voir section concernant ceux-ci). Le paramètrage du fichier XSL décrit ici ne vaut que si seules les URL WEBDAV sont utilisées.

Pour obtenir, dans la navigation que propose l'IHM, des liens sur un moteur de rendu inJac installé , dans le cas où seule l'URL WEBDAV est définie dans les fichiers de mapping des formats exposés, il faut renseigner les paramètres rendererURI et upnode du fichier ihm_main.xsl :