Comment utiliser les entrées/sorties RDF de Jena

Les principales méthodes d'entrée/sortie dans Jena utilisent InputStream et OutputStream. Ces méthodes se trouvent dans l'interface Model. Ce sont :

• Modelread(java.io.InputStream in, java.lang.String base)
  ajoute des déclarations à partir d'une sérialisation RDF / XML ;
• Modelread(java.io.InputStream in, java.lang.String base, java.lang.String lang)
  ajoute des déclarations RDF représentées dans la langue lang du modèle ;
• Modelread(java.lang.String url)
  ajoute les déclarations RDF à partir d'un document XML ;
• Modelwrite(java.io.OutputStream out)
  écrit le modèle comme un document XML ;
• Modelwrite(java.io.OutputStream out, java.lang.String lang)
  écrit une représentation sérialisée d'un modèle dans une langue spécifiée ;
• Modelwrite(java.io.OutputStream out, java.lang.String lang, java.lang.String base)
  écrit une représentation sérialisée d'un modèle dans une langue spécifiée.

Les langages intégrés sont : « RDF/XML », « RDF/XML-ABBREV », « N-TRIPLE», « N3 » et « TURTLE ». En plus, pour la sortie Turtle, la langue peut être spécifiée comme : « N3-PP », « N3-PLAIN » ou « N3-TRIPLE » qui contrôle le style de N3 produit.

Il y a aussi des méthodes qui utilisent Reader et Writer, mais à n'employer que si vous êtes sûr qu'il est correct de les utiliser. Dans les applications avancées, elles sont utiles (voir la suite ci-dessous) et l'objectif est bien de les maintenir. L'analyseur RDF/XML maintenant vérifie pour voir si les appels à Model.read(Reader…) sont abusifs, et dans ce cas, les sanctionne par les erreurs ERR_ENCODING_MISMATCH et WARN_ENCODING_MISMATCH. La plupart des utilisations incorrectes des Reader pour l'entrée RDF/XML se traduiront par ce genre d'erreur. Par contre, la plupart des utilisations incorrectes des Writer pour la sortie RDF/XML, produiront du XML correct en utilisant une déclaration XML appropriée donnant l'encodage - par exemple :

<?xml version='1.0'
    encoding='ISO-8859-15'?>

Cependant, un tel XML est moins portable qu'un XML en UTF-8. Utiliser les méthodes Model.write(OutputStream…) permet au code du système de Jena de choisir l'encodage UTF-8, qui est le meilleur choix.

I-A. RDF/XML, RDF/XML-ABBREV▲

I-B. Turtle▲

I-C. N-TRIPLE▲

I-D. N3▲

La meilleure méthode pour ne pas avoir besoin de lire ou de comprendre cette section est de toujours utiliser les InputStream et OutputStream avec Jena et de ne jamais utiliser les Reader et les Writer. Ainsi, Jena fera les bons choix pour la grande majorité des utilisateurs. Si vous avez du code hérité qui utilise des Reader et des Writer, ou si vous avez des besoins spéciaux avec le respect de l'encodage, alors cette section peut être utile. La dernière partie de cette section résume les encodages de caractères supportés par Jena.

L'approche de Java pour les encodages est conçue pour la facilité d'utilisation sur une seule machine, qui utilise un seul encodage ; celui-ci est souvent sur un octet, par exemple pour les langues européennes qui n'ont pas besoin de milliers de caractères différents.

L'approche XML est conçue pour le Web qui utilise de multiples encodages, et certains d'entre eux exigent des milliers de caractères.

Sur le Web, les fichiers XML, incluant les fichiers RDF/XML, sont par défaut encodés en « UTF-8 »  (Unicode). C'est toujours un bon choix pour la création de contenu, et c'est celui utilisé par Jena par défaut. D'autres encodages peuvent être utilisés, mais peuvent avoir une interopérabilité moins sûre . Ceux-ci doivent être nommés en utilisant le nom canonique inscrit à l'IANA, mais les systèmes n'ont pas d'obligation à les supporter. Seuls UTF-8 et UTF-16 sont standards (et, de ce fait, obligatoires).

Dans Java, les encodages apparaissent principalement avec les classes InputStreamReader et OutputStreamWriter, qui convertissent les octets en caractères utilisant un codage nommé, et avec leurs sous-classes, FileReader et FileWriter, qui convertissent les octets en caractères dans le fichier et les caractères utilisant l'encodage par défaut de la plate-forme. Il n'est pas possible de changer l'encodage utilisé par un Reader ou un Writer tant qu'il est en train d'être utilisé. L'encodage par défaut de la plate-forme dépend d'un large éventail de facteurs. Cet encodage par défaut peut être utile pour communiquer avec d'autres programmes sur la même plate-forme. Quelquefois, l'encodage par défaut n'est pas inscrit à l'IANA et,dans ce cas, les développeurs d'applications Jena ne doivent l'utiliser par défaut pour le contenu Web, mais utiliser UTF-8.

II-A. Encodages supportés par Jena 2.2 et ultérieurs▲

Rarement.

Malgré les problèmes d'encodage de caractères, il est encore parfois approprié d'utiliser les Reader et les Writer avec les entrées/sorties Jena. Un bon exemple est d'utiliser les Reader et les Writer dans les StringBuffer en mémoire. Ceux-là n'ont pas besoin d'être encodés et décodés ; ainsi la spécification d'un quelconque encodage est inutile. Autre exemple : un utilisateur avancé souhaite explicitement contrôler correctement l'encodage.

• Modelread(java.io.Reader reader, java.lang.String base)
  utiliser cette méthode est souvent une erreur ;
• Modelread(java.io.Reader reader, java.lang.String base, java.lang.String lang)
  utiliser cette méthode est souvent une erreur ;
• Modelwrite(java.io.Writer Writer)
  attention ! écrit le modèle comme un document XML ;
• Modelwrite(java.io.Writer Writer, java.lang.String lang)
  attention ! écrit une représentation sérialisée d'un modèle dans une langue spécifiée ;
• Modelwrite(java.io.Writer Writer, java.lang.String lang, java.lang.String base)
  Attention ! écrit une représentation sérialisée d'un modèle dans une langue spécifiée.

Une utilisation incorrecte de ces méthodes read(Reader…) aboutit à des avertissements et des erreurs avec RDF/XML et RDF/XML-ABBREV (sauf dans quelques cas où l'utilisation incorrecte ne peut être automatiquement détectée). L'utilisation incorrecte des méthodes write(Writer…) aboutit à de curieuses déclarations XML comme <?xml version="1.0" encoding="WINDOWS-1252"?>. Cela refléterait que l'encodage de caractères que vous utilisiez (probablement sans le réaliser) dans votre Writer est inscrit auprès de l'IANA sous le nom de « Windows-1252 ». Le XML résultant est de portabilité réduite en conséquence.

Depuis que UTF-8 et UTF-16 sont les seuls encodages susceptibles d'être compris par tous les processeurs XML conformes, même l'ISO-8859-1 serait techniquement sur un terrain glissant. Néanmoins, du fait qu'il soit très largement répandu, chaque processeur XML raisonnable le supporte. Avec N-TRIPLE une utilisation incorrecte est habituellement bénigne puisque N-TRIPLE est basé sur ASCII.

Les problèmes d'encodage de caractères de N3 ne sont pas bien définis, d'où l'utilisation de ces méthodes qui peuvent exiger des changements dans le futur. L'utilisation des méthodes InputStream et OutputStream permettra à votre code - quel qu'il soit - de fonctionner avec les futures versions de Jena. Actuellement, les méthodes OutputStream utilisent l'encodage UTF-8.

L'entrée et la sortie RDF/XML sont configurables. Toutefois, pour les configurer, il est nécessaire d'accéder à un objet RDFReader ou RDFWriter qui reste caché dans la plus simple interface au dessus.

Les quatre appels vitaux dans l'interface Model sont :

• RDFReadergetReader()
  retourne une instance de RDFReader pour la langue de sérialisation par défaut ;
• RDFReadergetReader(java.lang.String lang)
  retourne une instance de RDFReader pour la langue de sérialisation spécifiée ;
• RDFWritergetWriter()
  retourne une instance de RDFWriter pour la langue de sérialisation par défaut ;
• RDFWritergetWriter(java.lang.String lang)
  retourne une instance de RDFWriter pour la langue de sérialisation spécifiée.

Chacun de ces appels retourne un RDFReader ou un RDFWriter qui peut être utilisé pour lire ou écrire n'importe quel Model (et pas seulement celui qui l'a créé). Aussi bien que les méthodes nécessaires read et write, ces interfaces fournissent :

• RDFErrorHandlersetErrorHandler(RDFErrorHandler errHandler)
  définit un gestionnaire d'erreur pour le module de lecture ;
• java.lang.ObjectsetProperty(java.lang.String propName, java.lang.Object propValue)
  règle la valeur d'une propriété du module de lecture.

Définir les propriétés, ou le gestionnaire d'erreur, sur un RDFReader ou un RDFWriter permet au programmeur d'accéder au comportement qui n'est pas celui par défaut. Par ailleurs, depuis le RDFReader et le RDFWriter le développeur n'est pas lié à un Model spécifique. Un idiome typique est créé par les RDFReader ou les RDFWriter à l'initialisation du système, pour définir les propriétés appropriées de sorte qu'il se comporte exactement comme requis dans votre application, et ensuite pour faire toutes les subséquentes entrées/sorties à travers lui.

Model m = Modelfactory.createDefaultModel();
RDFWriter writer = m.getRDFWriter();
m = null; // m n'est plus nécessaire.
writer.setErrorHandler(myErrorHandler);
writer.setProperty("showXmlDeclaration","true");
writer.setProperty("tab","8");
writer.setProperty("relativeURIs","same-document,relative");
…
Model marray[];
…
for (int i=0; i<marray.length; i++) {
&#8230;
    OutputStream out = new FileOutputStream("foo" + i + ".rdf");
    writer.write(marray[i],
                       out,
      "http://example.org/");
    out.close();
}

Notez que toutes les implémentations courantes sont synchronisées, de sorte qu'un RDFReader spécifique ne peut être en train de lire deux documents différents au même moment. Dans une application en "multithreading" cela peut suggérer un besoin pour un groupement de RDFReaders et/ou de RDFWriter, ou alternativement de les créer, les initialiser, les utiliser et les jeter si nécessaire.

Pour le N-TRIPLE il n'y a actuellement pas de propriétés supportées pour soit le RDFReader, soit le RDFWriter. D'où il découle que l'idiome ci-dessus n'est pas très utile, et simplement utiliser la méthode Model.write() peut se révéler plus facile.

Pour le RDF/XML et le RDF/XML-ABBREV, il y a de nombreuses options à la fois dans le RDFReader et le RDFWriter. N3 fournit des options sur le RDFWriter. Ces options sont détaillées ci-dessous. Pour RDF/XML elles sont également présentes dans la javadoc pour JenaReader.setProperty(String, Object) et RDFXMLWriterI.setProperty(String, Object).

Pour accéder à ces fonctionnalités avancées, d'abord obtenir un objet RDFReader qui est une instance d'un analyseur ARP, en utilisant la méthode getReader() sur n'importe quel Model. Il est alors configuré en utilisant la méthode setProperty(String, Object). Cela change les propriétés pour analyser le RDF/XML. Beaucoup de propriétés modifient l'analyseur RDF, certaines modifient l'analyseur XML. L'analyseur RDF/XML de Jena, ARP, implémente la grammaire RDF sur un analyseur XML Xerces2-J. Cependant, changer les caractéristiques et les propriétés de l'analyseur XML n'est pas susceptible d'être utile, mais était facile à implémenter.

setProperty(String, Object) peut être utilisée pour définir et obtenir ce qui suit.

• Les propriétés ARP
  Ces propriétés permettent un contrôle fin sur les capacités de rapport d'erreur étendue de ARP, et sont détaillées directement ci-dessous.
• Les fonctionnalités SAX2
  Voir les fonctionnalités SAX2. La valeur doit être donnée comme une chaîne de caractères « true » ou « false » ou un booléen.
• Les propriétés SAX2
  Voir les propriétés SAX2.
• Les fonctionnalités Xerces
  Voir les fonctionnalités Xerces. La valeur doit être donnée comme une chaîne de caractères « true » ou « false» ou un booléen.
• Les propriétés Xerces
  Voir les propriétés Xerces.

V-A. Les propriétés ARP▲

Model m = Modelfactory.createDefaultModel();
RDFReader arp = m.getReader();
m = null; // m n'est plus nécessaire.
// initialise arp
// ne pas avertir sur l'utilisation d'attributs RDF non qualifiés.
arp.setProperty("WARN_UNQUALIFIED_RDF_ATTRIBUTE","EM_IGNORE");

...

InputStream in = new FileInputStream(fname);
arp.read(m,in,url);
in.close();

...
 arp.setProperty("error-mode", "strict" );
 arp.setProperty("IGN_DAML_COLLECTION","EM_IGNORE");
 ...

...
 arp.setProperty("IGN_DAML_COLLECTION","EM_IGNORE");
 arp.setProperty("error-mode", "strict" );
 ...

InputStream in = ... ;
String baseURI = ... ;
Model model = Modelfactory.createDefaultModel();
RDFReader r = model.getReader("RDF/XML");
r.setProperty("iri-rules", "strict") ;
r.setProperty("error-mode", "strict") ; // les warnings seront des erreurs.

// Alternative au "error-mode" ci-dessus  : définit un warning spécifique pour être une erreur.
//r.setProperty( "WARN_MALFORMED_URI", ARPErrorNumbers.EM_ERROR) ;
r.read(model, in, baseURI) ;
in.close();

ARPOptions.setIRIFactoryGlobal(IRIFactory.iriImplementation());

V-B. Interruption de ARP▲

ARP a = new ARP();
final Thread arpt = Thread.currentThread();
Thread killt = new Thread(new Runnable() {
     public void run() {
       try {
      Thread.sleep(tim);
       } catch (InterruptedException e) {
       }
       arpt.interrupt();
     }
  });
killt.start();
try {
  in = new FileInputStream(fileName);
  a.load(in);
  in.close();
  fail("Thread was not interrupted.");
} catch (SAXParseException e) {
}

La première question sur la sortie RDF/XML est de savoir si on doit utiliser le module d'écriture « RDF/XML » ou « RDF/XML-ABBREV ». Alors qu'une partie du code est partagée, ces deux modules d'écriture sont vraiment très différents, provoquant une sortie différente, mais équivalente. RDF/XML-ABBREV est plus lent, mais devrait produire du XML plus lisible.

Pour accéder aux fonctionnalités avancées, d'abord obtenir un objet RDFWriter, de la langue appropriée, par l'utilisation de getWriter("RDF/XML") ou getWriter("RDF/XML-ABBREV") sur n'importe quel Model. Il est alors configuré en utilisant la méthode setProperty(String, Object). Cela change les propriétés pour écrire du RDF/XML.

VI-A. Les propriétés pour contrôler la sortie RDF/XML▲

w.setProperty("prettyTypes",
         new Resource[]{
              DAML_OIL.Ontology,
              DAML_OIL.Class,
              DAML_OIL.Datatype,
              DAML_OIL.Property,
              DAML_OIL.ObjectProperty,
              DAML_OIL.DatatypeProperty,
              DAML_OIL.TransitiveProperty,
              DAML_OIL.UnambigousProperty,
              DAML_OIL.UniqueProperty,
              });

RDFWriter w = m.getWriter("RDF/XML-ABBREV");
w.setProperty("attribtueQuoteChar","'");
w.setProperty("showXMLDeclaration","true");
w.setProperty("tab","1");
w.setProperty("blockRules",
  "daml:collection,parseTypeLiteralPropertyElt,"
  +"parseTypeResourcePropertyElt,parseTypeCollectionPropertyElt");

L'affichage N3 amélioré (qui est utilisé par défaut) et le module d'écriture ordinaire N3 fournissent un grand nombre de propriétés pour contrôler leur sortie. Les propriétés commencent toutes par : http://jena.hpl.hp.com/n3/properties/. Le nom utilisé peut être le nom complet, en commençant avec cette chaîne de caractères, ou juste la forme courte du nom ci-dessous. Toutes les valeurs sont des chaînes de caractères ; elles peuvent être interprétées comme entier, booléen ou chaîne de caractères comme défini ci-dessous.

VII-A. Les sorties N3 avancées▲

L'entrée/sortie RDF/XML s'efforce de se conformer avec la recommandation de la syntaxe RDF.

L'analyseur doit être défini sur le mode strict. Notez que le comportement conforme aux rdf:parseType="daml:collection" est de transformer silencieusement "daml:collection" en "Literal".

Le module d'écriture RDF/XML est conforme, mais n'exerce pas une grande partie de la grammaire.

Le module d'écriture RDF/XML-ABBREV exerce toute la grammaire et est conforme, sauf qu'il utilise la construction daml:collection pour les ontologies DAML. Ce comportement non conforme peut être désactivé en utilisant la propriété blockRules.

Pour optimiser la vitesse d'écriture du RDF/XML il est suggéré que tous les traitements d'URI soient désactivés. Aussi n'utilisez pas RDF/XML-abbrev. Il est difficile de savoir si l'attribut longId est plus rapide ou plus lent ; les identifiants courts doivent être générés à la volée et un tableau maintenu durant l'écriture. Les identifiants plus longs prennent plus de temps à écrire. Ce qui suit crée un module d'écriture plus rapide :

Model m;
...
...
RDFWriter fasterWriter = m.getWriter("RDF/XML");
fasterWriter.setProperty("allowBadURIs","true");
fasterWriter.setProperty("relativeURIs","");
fasterWriter.setProperty("tab","0");

Lors de la lecture de RDF/XML, la vérification pour la réutilisation de rdf:ID impose une surcharge de mémoire, qui peut être significative pour les très gros fichiers. Dans ce cas, cette vérification peut être supprimée en disant à ARP d'ignorer cette erreur.

Model m;
...
...
RDFReader bigFileReader = m.getReader("RDF/XML");
bigFileReader.setProperty("WARN_REDEFINITION_OF_ID","EM_IGNORE");
?

Cet article est la traduction de Jena RDF I/O How-To.

Merci à ALT, ClaudeLeloup, jacques_jean et _Max_ pour leur relecture orthographique ainsi qu'à Thibaut Cuvelier pour ses conseils.