Mappings

Par défaut, le mapping des champs Darwin Core aux colonnes du Catalogue nécessite l'ajout d'un préfixe Dar au nom du champ Darwin Core. Par exemple :

Champ Darwin Core	devient	Colonne EMu
CatalogNumber	=>	DarCatalogNumber
ScientificName	=>	DarScientificName

La seule exception à cette règle est le champ Darwin Core DateLastModified, qui nécessite des handlers spéciaux - voir TexQL & Value handlers.

Au moment de la rédaction de ce document (octobre 2008) les versions suivantes Darwin Core sont supportées dans le mapping par défaut :

• 1.2
• 1.21
• 1.3
• 1.4
• 1.4 extensions
• OBIS extensions
• PALEO extensions (peut être!)

Le mapping par défaut peut être modifié (ou un nouveau mapping spécifié) en implémentant la fonction clientDigirProvider::getMappings(). Si cette fonction existe, elle est appelée et on lui transmet l'objet mapping par défaut lors du traitement de chaque requête. Il est ensuite possible d'utiliser la fonction Mapping::setMapping() pour ajouter ou modifier des plans.

Tous les mappings par défaut peuvent être effacés en utilisant la fonction Mapping::clearMappings().

Il n'est pas nécessaire que les colonnes EMu spécifiées dans le mapping existent réellement dans le back-end du client. Lors du traitement de chaque requête, l'existence de toutes les colonnes demandées (telles que renvoyées par leurs plans de champs) est vérifiée dans le back-end du client. Si elles n'existent pas, elles sont supprimées de la requête et un diagnostic d'avertissement est généré. Si la colonne fait partie d'un filtre de requête ou s'il s'agit du champ d'inventaire d'une requête d'inventaire, la demande échoue et un diagnostic d'erreur est généré.

Cela signifie qu'il est seulement nécessaire de définir les colonnes qui sont importantes pour le client. Cela généralement signifie définir toutes les colonnes pour une ou plus des versions officielles de Darwin Core.

Le concept de champs obligatoires est défini dans la norme Darwin Core mais mal supporté par le protocole DiGIR. L'idée est qu'un enregistrement Darwin Core (l'ensemble des champs Darwin Core spécifiés par la version Darwin Core) est uniquement valide s'il contient des valeurs pour ces champs (nillable=false dans la version du schéma Darwin Core). S'il ne contient pas de valeurs pour ces champs, l'enregistrement n'est pas valide et ne devrait pas être inclus dans l'ensemble des enregistrements retourné pour une requête DiGIR.

Malheureusement, différentes versions du protocole Darwin Core spécifient différents champs obligatoires, et les requêtes dans le protocole DiGIR n'ont pas besoin de spécifier quelle version de la norme Darwin Core est utilisée (en fait, les requêtes ne sont pas du tout liées aux versions Darwin Core, n'importe quelle combinaison de champ Darwin Core peut être utilisée). Les champs obligatoires par défaut sont ceux communs à toutes les versions Darwin Core :

• ScientificName
• CatalogNumber
• CollectionCode
• InstitutionCode

Les champs obligatoires peuvent être supprimés ou ajoutés si nécessaire.

• Utiliser la fonction Mapping::clearMandatory() de l'objet mapping pour supprimer tous les champs obligatoires.
• Utiliser la fonction Mapping::setMandatory() pour ajouter un champ obligatoire.

Étant donné la nature quelque peu fluide de la norme Darwin Core, il est possible que le nom d'un champ Darwin Core dans une version de la norme ait changé depuis une version antérieure, mais que le concept (c.-à-d. les données) est resté le même.

Si un client supporte plusieurs versions Darwin Core et le nom du champ Darwin Core change entre les versions, il est possible d'indiquer que nous voulons que le nouveau nom fasse référence à l'ancien champ, nécessitant ainsi la création d'une seule colonne dans le back end du client. C'est essentiellement la même chose que la mise à jour du mapping par défaut existant (ou la création d'un nouveau mapping) avec toutes les mêmes valeurs que celles de l'ancien mapping (sauf, bien sur, le nom du champ).

Note: Voir Darwin CoreVersions pour de nombreux exemples de changements de noms entre les versions.

Les références de mapping peuvent être spécifiées en utilisant la fonction Mapping::setMappingRef(). Aucune référence de mapping n'est spécifiée par défaut. Les références de mapping devraient être établies après que toutes les autres opérations de mapping aient été effectuées.

Les handlers TexQL et de Valeur fournissent un mécanisme pour récupérer les données à partir d'une base de données et pour construire ces données pour la présentation dans la réponse DiGIR au-delà d'un mapping simple d'un champ Darwin Core à une colonne EMu.

Les handlers TexQL et de Valeur sont établis pour chaque champ. Typiquement il est nécessaire de spécifier un handler TexQL et un handler de Valeur pour le même champ Darwin Core, mais dans quelques situations, il se peut qu'il soit nécessaire de spécifier seulement l'un ou l'autre (voir ci-dessous).

Les handlers TexQL désignent :

• Les colonnes à récupérer à partir de la base de données (partie de la déclaration TexQL select) quand un champ Darwin Core particulier est requis (c.-à-d. quand le champ est inclus dans la requête DiGIR structure).
• La déclaration TexQL where pour générer quand ce champ Darwin Core particulier est recherché dans la requête DiGIR (i.e. quand le champ est inclus dans la requête DiGIR filter).

Les handlers de Valeur désignent :

• Comment construire la valeur du champ Darwin Core dans la réponse à la requête DiGIR.

Le mapping par défaut spécifie seulement un handler TexQL et de Valeur pour le champ Darwin Core DateLastModified.

Voir ~/ web/webservices/digir/Mapping.php pour cet exemple.

Le but des handlers pour ce champ est d'utiliser les colonnes EMu existantes AdmDateModified et AdmTimeModified plutôt que de créer une nouvelle colonne. L'utilisation des colonnes EMu existantes permet de profiter des sceaux de plages de valeurs de ces colonnes pour des requêtes sur une fourchette de dates du champ Darwin Core DateLastModified.

Les handlers TexQL et de Valeur sont spécifiés en utilisant Mapping::setTexqlHandler() et Mapping:: setValueHandler() respectivement.

La principale raison pour définir les handlers TexQL et de Valeur est de pouvoir exécuter quelques post-traitements sur un champ Darwin Core.

Une raison pour appliquer un post-traitement à un champ est que le champ contient des données qui n'existent pas dans la base de données EMu. Un exemple est le champ Darwin Core RecordURL. Il spécifie l'URL requise pour localiser l'enregistrement. Comme la plupart de cette information n'est probablement pas stockée dans le Catalogue EMu et que l'URL peut changer avec le temps, ce champ est un bon candidat pour un post-traitement.

Voici un exemple simple des handlers qui peuvent être utilisés pour le champ Darwin Core RecordURL (ce code se trouverait dans clientDigirProvider) :

fonction
getMappings($map)
{
    $this->baseRecordURL = "http://servername/webdir/pages/nmnh/iz/Display.php?irn=";
    La fonction #### sera appelée comme ceci
    ### function($field, $operator, $value, $data)
    ### where/>    ### $field = "RecordURL"
    ### $operator & $value dépendent de la requête DiGIR
    ### $data = $this->baseRecordURL
    ###
    $code =
    '
        if ($operator == \'=\')
        {
            if (preg_match("/^$data(\d+)$/", $value, $match))
                return "irn $operator $match[1]";
        }
        else if ($operator == \'<>\')
        {
            if (preg_match("/^$data(\d+)$/", $value, $match))
                return "irn $operator $match[1]";
            else
                return \'TRUE\';
        }
        else
        {
            return null;
        }
        return \'FALSE\';

, 
    $map->setTexqlHandler('RecordURL', 'irn_1', $code, $this->baseRecordURL);
    
    La fonction #### sera appelée comme ceci
    ### function($field, $record, $data)
    ### where
    ### $field = "RecordURL"
    ### $record est un hashage de toutes les données requises récupérées de la base de données indexées par le nom de la colonne EMu
    ### $data = $this->baseRecordURL
    ###
    $code =
    '
        if (empty($record[\'irn_1\']))
            return \'\';
        return $data . $record[\'irn_1\'];
        ';
    $map->setValueHandler('RecordURL', $code, $this->baseRecordURL);
    
    return $map;
}

Les handlers TexQL doivent retourner le correcte TexQL pour chaque opération qu'ils supportent (certaines opérations sont trop difficiles pour être gérées entièrement avec du code et ne devraient pas être supportées).

Prenez l'exemple de la requête "=" ci-dessus; puisque le NEI (IRN) est la seule portion du champ RecordURL qui est stockée dans le Catalogue EMu, il est nécessaire de déterminer si l'autre portion (base URL) rassemblée à partir de la requête DiGIR correspond à la base URL que nous avons définie :

• Si la base URL correspond, il est nécessaire de générer le TexQL pour déterminer si le NEI correspond aux valeurs dans la base de données.
• Si la base URL ne correspond pas, nous retournons la valeur TexQL FALSE ; parce que la valeur de la requête DiGIR ne correspond pas à notre base URL elle ne devrait pas récupérer des valeurs à partir de la base de données.

Les handlers de Valeur devraient utiliser les valeurs requises récupérées de la base de données avec des données prédéfinies pour générer la valeur correcte à afficher dans la réponse DiGIR.

La façon la plus simple d'indiquer que le client ne supporte pas (c.-à-d. ne fournit pas de données) pour un champ spécifique Darwin Core est de ne rien faire. Les colonnes non existantes spécifiées dans le mapping sont gérées par le Provider DiGIR – voir Relation entre les champs Darwin Core et les colonnes.

D'autre part, si une colonne spécifiée dans la mapping a été implémentée dans le back end et il est nécessaire de la désactiver, utilisez la fonction Mapping::setNoMapping().