Obtenir des informations à partir d'enregistrements correspondants

La forme la plus simple de la méthode fetch prend quatre arguments :

• flag
• offset

  Ensemble, les arguments flag et offset définissent la position de départ du bloc d’enregistrements à récupérer. L’argument flag est un String et doit être l’un des suivants :

  • start
  • current
  • end

  Les indicateurs start et end font référence au premier et au dernier enregistrement du jeu de résultats. L’indicateur current fait référence à la position du dernier enregistrement récupéré lors de l’appel précédent à la méthode fetch. Si la méthode fetch n’a pas été appelée, current fait référence au premier enregistrement du jeu de résultats.

  L’argument offset est un int. Il ajuste la position de départ par rapport à la valeur de l’argument flag. Une valeur positive pour offset indique un début après la position spécifiée par flag et une valeur négative indique un début avant la position spécifiée par flag.

  Par exemple, appeler fetch avec un flag de start et un offset de 3 renverra les enregistrements à partir du quatrième enregistrement du jeu de résultats. Spécifier un flag de end et un offset de -8 renverra les enregistrements à partir du neuvième enregistrement en partant de la fin du jeu de résultats.

  Pour récupérer l’enregistrement suivant après le dernier renvoyé lors de l’appel précédent à fetch, il convient de passer un flag de current et un offset de 1.

• count

  L’argument count spécifie le nombre maximum d’enregistrements à récupérer.

  Passer une valeur count de 0 est valide. Cela amène fetch à modifier l’enregistrement en cours sans récupérer réellement les données.

  L’utilisation d’une valeur négative pour count est également valide. Cela amène fetch à renvoyer tous les enregistrements du jeu de résultats à partir de la position de départ (spécifiée par flag et offset).

• columns

  L’argument columns est utilisé pour spécifier quelles colonnes doivent être incluses dans les enregistrements renvoyés. L’argument peut être un String, un String[] ou un ArrayList<String>. Dans sa forme la plus simple, chaque String contient un seul nom de colonne, ou plusieurs noms de colonnes séparés par des points-virgules ou des virgules.

  La valeur de l’argument columns peut être autre chose que de simples noms de colonnes. Voir Spécification des colonnes pour plus de détails.

Il existe un certain nombre de variantes de la méthode fetch. Consultez la documentation de référence pour plus de détails sur chacune d’entre elles.

Par exemple :

1. Récupérer le premier enregistrement à partir du début du jeu de résultats :

    Module parties = new Module("eparties", session) ; Colonnes de chaîne = "NamFirst ; NamLast" ; parties.fetch("start", 0, 1, colonnes) ; 

   L’argument columns peut également être spécifié comme un String[] :

    Module parties = new Module("eparties", session) ; String[] columns = { "NamFirst", "NamLast" } ; parties.fetch("start", 0, 1, colonnes) ; 

2. Récupérer tous les résultats d’un jeu de résultats :

    Module parties = new Module("eparties", session) ; String[] columns = { "NamFirst", "NamLast" } ; ModuleFetchResult result = parties.fetch("start", 0, -1, colonnes) ; 

3. Définir l’enregistrement en cours sur l’enregistrement suivant du jeu de résultats sans récupérer de données :

    parties.fetch("current", 1, 0) ; 

4. Récupérer le dernier enregistrement à partir de la fin du jeu de résultats :

    Module parties = new Module(« eparties », session) ; String[] columns = { "NamFirst", "NamLast" } ; ModuleFetchResult result = parties.fetch("end", 0, 1, colonnes) ; 

La méthode fetch retourne les enregistrements demandés dans un objet ModuleFetchResult. Il contient trois propriétés en lecture seule :

• count

  Un int (accessible à l’aide de la méthode getCount) spécifiant le nombre d’enregistrements renvoyés par la requête fetch.

• hits

  Un long (accessible à l’aide de la méthode getHits) spécifiant le nombre estimé de correspondances dans le jeu de résultats. Ce nombre est renvoyé pour chaque fetch car l’estimation peut diminuer à mesure que les enregistrements du jeu de résultats sont traités par la méthode fetch.

• rows

  Un Map[] contenant le jeu d’enregistrements demandés. Chaque Map contient des entrées pour chaque colonne demandée.

Note: La classe IMu Map est une sous-classe de la classe standard HashMap de Java. Il définit son type de clé comme étant String. Il fournit également des méthodes pratiques pour convertir les types des éléments stockés dans la map.

Par exemple, les propriétés count et hits sont récupérées et tous les enregistrements renvoyés sont parcourus à l’aide de la propriété rows :

 String[] columns = { "NamFirst", "NamLast" }; ModuleFetchResult result = parties.fetch("start", 0, 2, columns); int count = result.getCount(); long hits = result.getHits(); Map[] rows = result.getRows(); System.out.format("Count: %d%n", count); System.out.format("Hits: %d%n", hits); System.out.println("Rows:"); for (int i = 0; i < rows.length; i++) { Map row = rows[i]; int rowNum = row.getInt("rownum"); long irn = row.getLong("irn"); String firstName = row.getString("NamFirst"); String lastName = row.getString("NamLast"); System.out.format(" %d. %s, %s (%d)%n", rowNum, lastName, firstName, irn); }

Cela génère des résultats similaires à ceux qui suivent :

Count: 2 Hits: 4 Rows: 1. ECCLES-SMITH, Kate (100573) 2. SMITH, Ian (100301)

Il s’agit par exemple de simples noms de colonnes du type déjà mentionné :

 NamFirst 

Les valeurs des colonnes atomiques sont renvoyées sous forme String :

 String[] columns = { "NamFirst" }; ModuleFetchResult result = parties.fetch("start", 0, 1, columns); Map[] rows = result.getRows(); for (int i = 0; i < rows.length; i++) { Map row = rows[i]; String first = row.getString("NamFirst"); // ⋯ } 

Les tables imbriquées sont des colonnes qui contiennent une liste de valeurs. Elles sont spécifiées de la même manière que les colonnes atomiques :

 NamRoles_tab 

Les valeurs des tables imbriquées sont renvoyées sous la forme String[]. Chaque membre du tableau est une String qui correspond à une ligne de la table imbriquée :

 String[] columns = { "NamRoles_tab" }; ModuleFetchResult result = parties.fetch("start", 0, 1, columns); Map[] rows = result.getRows(); for (int i = 0; i < rows.length; i++) { Map row = rows[i]; String[] roles = row.getStrings("NamRoles_tab"); for (int j = 0; j < roles.length; j++) { String role = roles[j]; // ⋯ } } 

Une pièce jointe est un lien entre un enregistrement dans un module et un enregistrement dans le même module ou dans un autre. Les colonnes d’un enregistrement joint peuvent être spécifiées en spécifiant d’abord la colonne de fichier joint, puis la colonne à récupérer à partir de l’enregistrement joint :

 SynSynonymyRef_tab.SummaryData 

Plusieurs colonnes peuvent être spécifiées à partir de l’enregistrement joint :

 SynSynonymyRef_tab.(NamFirst,NamLast) 

Les valeurs renvoyées pour les colonnes provenant d’enregistrements joints dépendent du type de la colonne de fichier joint. Si la colonne de fichier joint est atomique, les valeurs de la colonne sont renvoyées sous forme Map. Si la colonne de fichier joint est une table imbriquée, les valeurs sont renvoyées sous forme Map[]. Chaque Map contient les valeurs de colonne demandées pour chaque enregistrement joint :

 String[] columns = { "SynSynonymyRef_tab.(NamFirst,NamLast)" }; ModuleFetchResult result = parties.fetch("start", 0, 1, columns); Map[] rows = result.getRows(); for (int i = 0; i < rows.length; i++) { Map row = rows[i]; Map[] synonymies = row.getMaps("SynSynonymyRef_tab"); for (int j = 0; j < synonymies.length; j++) { Map synonymy = synonymies[j]; String first = synonymy.getString("NamFirst"); String last = synonymy.getString("NamLast"); // ⋯ } } 

Un fichier joint inversé permet de spécifier des colonnes provenant d’autres enregistrements du même module ou d’autres modules auxquels l’enregistrement en cours est rattaché par l’intermédiaire d’une colonne spécifiée.

Par exemple :

1. Récupérez la colonne TitMainTitle (Titre principal) pour tous les enregistrements Catalogue qui ont l’enregistrement Personnes / Organisations en cours joint à leur colonne CreCreatorRef_tab (Créateur) :

    <ecatalogue :CreCreatorRef_tab>. TitMainTitle 

2. Récupérez la colonne NarTitle (Titre) pour tous les enregistrements Narrations qui ont l’enregistrement Narration en cours joint à leur colonne HieChildNarrativesRef_tab (Narrations enfants) :

    <enarratives :HieChildNarrativesRef_tab>. NarTitle 

Plusieurs colonnes peuvent être spécifiées à partir de l’enregistrement de fichier joint inversé :

 <ecatalogue:CreCreatorRef_tab>.(TitMainTitle,TitObjectCategory) 

Les fichiers joints inversés sont renvoyés sous forme Map[]. Chaque Map contient les valeurs de colonne demandées pour chaque enregistrement du module spécifié (le module Catalogue dans l’exemple ci-dessous) qui a l’enregistrement en cours joint à la colonne spécifiée (la colonne CreCreatorRef_tab dans l’exemple ci-dessous) :

 String[] columns = { "<ecatalogue:CreCreatorRef_tab>.(TitMainTitle,TitObjectCategory)" }; ModuleFetchResult result = parties.fetch("start", 0, 1, columns); Map[] rows = result.getRows(); for (int i = 0; i < rows.length; i++) { Map row = rows[i]; Map[] objects = row.getMaps("ecatalogue:CreCreatorRef_tab"); for (int j = 0; j < objects.length; j++) { Map object = objects[j]; String title = object.getString("TitMainTitle"); String category = object.getString("TitObjectCategory"); // ⋯ } } 

Un ensemble de colonnes de table imbriquées peut être regroupé en les spécifiant entre crochets.

Par exemple, pour regrouper les Contributeurs et leur rôle à partir du module Narrations :

 [NarContributorRef_tab.SummaryData,NarContributorRole_tab] 

Chaque ensemble de lignes correspondantes des tables imbriquées fournies est renvoyé sous la forme d’une seule ligne dans les résultats. Par défaut, le groupe reçoit le nom group1, group2 et ainsi de suite. Ce nom de groupe peut être changé en préfixant les colonnes groupées avec un nom alternatif :

 contributors=[NarContributorRef_tab.SummaryData,NarContributorRole_tab] 

Les tables imbriquées groupées sont renvoyées sous forme Map[]. Chaque Map contient les valeurs de colonne demandées pour les lignes correspondantes des tables imbriquées :

 String[] columns = { "[NarContributorRef_tab.SummaryData,NarContributorRole_tab]" }; ModuleFetchResult result = narratives.fetch("start", 0, 1, columns); Map[] rows = result.getRows(); for (int i = 0; i < rows.length; i++) { Map row = rows[i]; Map[] groupedRows = row.getMaps("group1"); for (int j = 0; j < groupedRows.length; j++) { Map groupedRow = groupedRows[j]; // NarContributorRef_tab is an attachment column. Map contributor = groupedRow.getMap("NarContributorRef_tab"); String name = contributor.getString("SummaryData"); String role = groupedRow.getString("NarContributorRole_tab"); // ⋯ } } 

Les colonnes virtuelles sont des colonnes qui n’existent pas réellement dans la table EMu à laquelle on accède. Au lieu de cela, le serveur IMu interprète la requête concernant la colonne et génère une réponse adaptée. Certaines colonnes virtuelles ne peuvent être utilisées que dans certains modules, comme indiqué ci-dessous :

Les colonnes virtuelles suivantes peuvent être utilisées dans n’importe quel module EMu :

• insertedTimeStamp

  Renvoie la date et l'heure d'insertion de l'enregistrement au format YYYY-MM-DDThh:mm:ss, par exemple 1999-12-31T23:59:59 Ce format est similaire au format de date ISO8601, à l’exception de l’indicateur de fuseau horaire qui n’est pas inclus.

• modifiedTimeStamp

  Renvoie la date et l'heure de modification de l'enregistrement au format YYYY-MM-DDThh:mm:ss.

 String[] columns = { "insertedTimeStamp", "modifiedTimeStamp" }; ModuleFetchResult result = parties.fetch("start", 0, 1, columns); Map[] rows = result.getRows(); for (int i = 0; i < rows.length; i++) { Map row = rows[i]; String inserted = row.getString("insertedTimeStamp"); String modified = row.getString("modifiedTimeStamp"); // ⋯ } 

Les colonnes virtuelles suivantes peuvent être utilisées dans n’importe quel module EMu, à l’exception du module Multimédia :

• application

  Renvoie des informations sur le multimédia d’application préféré associé à un enregistrement.

  Note: Actuellement, le multimédia d’application préféré correspond à la première entrée de la liste renvoyée par la colonne virtuelle applications. Toutefois, les futures versions d’EMu pourraient permettre de désigner d’autres multimédias comme préférés ; dans ce cas, la colonne application renverra les informations relatives au multimédia d’application préféré plutôt qu’au premier de la liste.

• applications

  Renvoie des informations sur tous les multimédias d’application associés à un enregistrement.

• audio

  Renvoie des informations sur le multimédia audio préféré associé à un enregistrement.

• audios

  Renvoie des informations sur tous les multimédias audio associés à un enregistrement.

• image

  Renvoie des informations sur le multimédia image préféré associé à un enregistrement.

• images

  Renvoie des informations sur tous les multimédias image associés à un enregistrement.

• multimedia

  Renvoie des informations sur tous les multimédia associés à un enregistrement.

• video

  Renvoie des informations sur le multimédia video préféré associé à un enregistrement.

• videos

  Renvoie des informations sur tous les multimédias video associés à un enregistrement.

Pour plus d’informations, consultez Multimédia.

Les colonnes virtuelles suivantes ne peuvent être utilisées que dans le module Multimédia :

• master

  Retourne des informations sur le fichier multimédia principal.

• resolutions (résolutions)

  Renvoie des informations sur toutes les résolutions multimédia.

• resource (ressource)

  Renvoie des informations minimales sur le fichier multimédia principal, notamment un descripteur de fichier ouvert pointant vers une copie temporaire de ce fichier multimédia.

• resources (ressources)

  Identique à la colonne virtuelle ressource, sauf que des informations et des descripteurs de fichiers sont fournis pour tous les fichiers multimédias.

• supplementary (supplémentaire)

  Renvoie des informations sur tous les fichiers multimédias supplémentaires.

• thumbnail (vignette)

  Renvoie des informations sur le multimédia vignette.

Pour plus d’informations, consultez Multimédia.

La colonne virtuelle suivante ne peut être utilisée que dans le module Narrations :

• trails

  Renvoie des informations sur la position de l’enregistrement actuel dans la hiérarchie du module Narrations.

La colonne virtuelle suivante ne peut être utilisée que dans le module Descriptions des collections :

• extUrlFull_tab

Un ensemble Fetch permet de préenregistrer un groupe de colonnes sous un nom unique. Ce nom peut ensuite être passé à la méthode fetch pour récupérer les colonnes spécifiées.

Les ensembles Fetch sont utiles si la méthode fetch est appelée plusieurs fois avec le même ensemble de colonnes, car :

• Les colonnes requises n’ont pas besoin d’être spécifiées à chaque fois que la méthode fetch est appelée. Ceci est utile pour maintenir l'état.
• Chaque fois que la méthode fetch est appelée, le serveur IMu doit analyser les colonnes fournies et les comparer au schéma EMu. Pour les ensembles de colonnes complexes, en particulier ceux impliquant plusieurs références ou références inverses, cela peut prendre du temps.

La méthode de classe Module addFetchSet est utilisée pour enregistrer un ensemble de colonnes. Cette méthode prend deux arguments :

• name

  Le nom à utiliser pour l’ensemble de colonnes. La valeur de cet argument peut être passée à n’importe quel appel à la méthode fetch et l’ensemble des colonnes spécifié par l’argument columns sera renvoyé.

• columns

  L’ensemble des colonnes à associer à l’argument name.

La méthode de classe Module addFetchSets est similaire, sauf que plusieurs ensembles peuvent être enregistrés en même temps.

Les résultats sont renvoyés comme si vous aviez fourni les colonnes directement à la méthode fetch.

Par exemple :

1. Ajouter un ensemble Fetch unique en utilisant la méthode addFetchSet :

    String[] columns = { "NamFirst", "NamLast", "NamRoles_tab" } ; parties.addFetchSet("person_details", colonnes) ; 

2. Ajouter plusieurs ensembles Fetch à l’aide de la méthode addFetchSets :

   Map sets = new Map() ; sets.put("person_details", "NamFirst ; NamLast ; NamRoles_tab") ; sets.put("organisation_details", "NamOrganisation ; NamOrganisationAcronym") ; parties.addFetchSets(sets) ; 

3. Récupérer un ensemble Fetch à l’aide de la méthode fetch :

    ModuleFetchResult result = parties.fetch("start", 0, 1, "person_details") ; Map[] rows = résultat.getRows() ;  for (int i = 0 ; i < rows.length ; i++) { Map row = rows[i] ; Chaîne d’abord = ligne.getString("NamFirst") ; Chaîne en dernier = ligne.getString("NamLast") ; String[] roles = row.getStrings("NamRoles_tab") ; for (int j = 0 ; j < rôles.length ; j++) { String role = roles[j] ; // ⋯ } } 

Avertissement

Le nom du set fetch doit être la seule valeur transmise comme argument columns de la méthode Fetch. Cela pourrait être modifié dans une future version de l’API IMu.

Les colonnes peuvent être renommées dans les résultats renvoyés en les préfixant d’un autre nom :

 first_name=NamFirst 

La valeur de la colonne spécifiée est désormais renvoyée sous le nom alternatif :

 String[] columns = { "first_name=NamFirst" }; ModuleFetchResult result = parties.fetch("start", 0, 1, columns); Map[] rows = result.getRows(); for (int i = 0; i < rows.length; i++) { Map row = rows[i]; String first = row.getString("first_name"); // ⋯ } 

D’autres noms peuvent également être fournis pour d’autres spécifications de colonnes :

 roles=NamRoles_tab 

 synonyms=SynSynonymyRef_tab.(NamFirst,NamLast) 

 objects=<ecatalogue:CreCreatorRef_tab>.(TitMainTitle,TitObjectCategory) 

D’autres noms peuvent également être utilisés pour toutes les colonnes spécifiées entre parenthèses ou crochets :

 SynSynonymyRef_tab.(first_name=NamFirst,last_name=NamLast) 

 contributors=[contributor=NarContributorRef_tab.SummaryData,role=NarContributorRole_tab] 

D’autres noms peuvent également être fournis dans les ensembles Fetch :

 String[] columns = { "first_name=NamFirst", "last_name=NamLast", "roles=NamRoles_tab" }; parties.addFetchSet("person_details", columns);