Afin d'utiliser le Service d'Accès de Données XML pour les Objets de Service de Données, vous aurez besoin de comprendre certains concepts derrière le SDO : les graphiques de données, les objets de données, XPath et ses expressions, et ainsi de suite. Si vous n'êtes pas familier avec ces idées, vous devriez jeter un oeil sur la section sur SDO.
Le travail de XML DAS est de déplacer les données entre l'application et un fichier source XML, qui peut être soit un fichier ou une adresse URL. SDO est créé et maintenu en accord avec un modèle qui définit les types des noms et quels noms de propriétés chaque type doit avoir. Pour les données qui proviennent d'un fichier XML, le modèle SDO est construit depuis un fichier de schéma écrit dans un langage XML (un fichier xsd). Ce schéma est habituellement passé à la méthode créée lorsque l'objet XMLDAS est initialisé. La » spécification SDO 2.0 définit le lien entre les types XML et les types SDO. Il y a quelques limitations dans le support PHP - tout ce qui se trouve dans la spécification ne peut pas être fait - et ces limitations sont énumérées dans une section suivante.
Le Service d'Accès de Données requiert PHP 5.1.0 ou supérieur. Il est fonctionnel avec l'extension SDO et requiert que SDO soit installée. Voyez les instructions d'installation SDO pour plus de détails sur comment faire cela.
Le Service d'Accès de Données et empaqueté et installé avec l'extension SDO. Référez-vous à instructions d'installation SDO.
La plupart des exemples suivants sont basés sur l'exemple de la lettre décrite dans la documentation SDO. Les exemples assument que le Schéma XML pour la lettre est contenu dans un fichier lettre.xsd et que l'instance de la lettre est dans le fichier lettre.xml. Ces deux fichiers sont reproduits ici :
Exemple 2357. Chargement, modification et sauvegarde d'un document XML
L'exemple suivant montre comment un document XML peut être chargé provenant d'un fichier, altéré et récrit.
<?php
/**
* Charge, met à jour et sauvegarde un document XML
*/
try {
$xmldas = SDO_DAS_XML::create("letter.xsd");
$document = $xmldas->loadFile("letter.xml");
$root_data_object = $document->getRootDataObject();
$root_data_object->date = "September 03, 2004";
$root_data_object->firstName = "Anantoju";
$root_data_object->lastName = "Madhu";
$xmldas->saveFile($document, "letter-out.xml");
echo "Nouveau fichier écrit :\n";
print file_get_contents("letter-out.xml");
} catch (SDO_Exception $e) {
print($e->getMessage());
}
?>
Une instance du XML DAS est la première obtenue de la méthode
SDO_DAS_XML::create() qui est une méthode statique de
la classe SDO_DAS_XML.
L'emplacement du xsd est passé en paramètre.
Une fois que nous avons une instance de XML DAS initialisée avec un
schéma donné, nous pouvons l'utiliser pour charger l'instance du document
en utilisant la méthode loadFile().
Il y a aussi la méthode loadString() si vous
voulez charger une instance de document XML provenant d'une chaîne de
caractères.
Si l'instance du document se charge correctement, un objet de type
SDO_DAS_XML_Document sera retourné sur lequel vous
pourrez appeler la méthode getRootDataObject() pour
obtenir l'objet de données SDO qui est la racine de votre graphique de
données SDO. Vous pouvez alors utiliser les opérations SDO pour changer
le graphique SDO. Dans cet exemple, nous modifions les propriétés
date, prenom et
nomFamille.
Ensuite, nous utilisons la méthode
saveFile() pour écrire les changements dans
un fichier système.
La méthode saveFile a un argument optionnel qui, s'il est spécifié,
fera que le XML DAS formatera le XML en utilisant cet argument pour indenter
chaque changement dans le niveau du document.
This will write the following to letter-out.xml.
Exemple 2358. Création d'un nouveau document XML
L'exemple précédent charge le document depuis un fichier. Cet exemple montre comment créer un graphique de données SDO en mémoire. Dans cet exemple, il est sauvegardé dans une chaîne XML. En outre, vu que la lettre contient à la fois du contenu structuré et non-structuré, on utilise l'API séquence pour assigner les propriétés pour construire le graphique des données.
<?php
/**
* Création d'un document XML
*/
try {
$xmldas = SDO_DAS_XML::create("letter.xsd");
try {
$doc = $xmldas->createDocument();
$rdo = $doc->getRootDataObject();
$seq = $rdo->getSequence();
$seq->insert("April 09, 2005", NULL, 'date');
$seq->insert("Acme Inc. ", NULL, NULL);
$seq->insert("United Kingdom. ");
$seq->insert("Dear", NULL, NULL);
$seq->insert("Tarun", NULL, "firstName");
$seq->insert("Nayaraaa", NULL, "lastName");
$rdo->lastName = "Nayar";
$seq->insert("Please note that your order number ");
$seq->insert(12345);
$seq->insert(" has been dispatched today. Thanks for your business with us.");
print($xmldas->saveString($doc));
} catch (SDO_Exception $e) {
print($e);
}
} catch (SDO_Exception $e) {
print("Problème lors de la création du document XML : " . $e->getMessage());
}
?>
La méthode createDocument() du XLM DAS retourne un objet document avec une donnée racine simple correspondant à un élément du document vide. Le nom de l'élément du document est connu du fichier de schéma. S'il y a le moindre doute quant à la valeur de l'élément du document, par exemple lorsque plus d'un schéma a été chargé dans le même XML DAS, le nom de l'élément et l'URI de l'espace de noms peuvent être passés à la méthode createDocument().
Ceci affichera (les retours à la ligne ont été insérés pour une meilleure lisibilité) :
Exemple 2359. Définission des propriétés du document XML
Ce troisième exemple montre comment définir la version XML ainsi que l'encodage de l'objet document. Ceci sera utilisé lors de l'écriture du document XML. Si aucune déclaration XML n'est désirée (peut-être voulez-vous générer du XML sous la forme d'une chaîne à incorporer quelque part), alors, vous pouvez utiliser la méthode setXMLDeclaration() pour supprimer la déclaration.
<?php
/**
* Illustration des appels qui contrôlent la déclaration XML
*/
$xmldas = SDO_DAS_XML::create("letter.xsd");
$document = $xmldas->loadFile("letter.xml");
$document->setXMLVersion("1.1");
$document->setEncoding("ISO-8859-1");
print($xmldas->saveString($document));
?>
La version et l'encodage du XML sont définis dans la déclaration XML en haut du document XML.
Exemple 2360. Utilisation d'un type ouvert
Ce quatrième exemple illustre l'utilisation d'un type ouvert SDO ainsi que l'utilisation de la méthode createDataObject(). Pour cet exemple, nous utilisons les deux schémas suivants :
Notez la présence de l'élément any dans la définission. Ce premier schéma définit le type complexe jungle qui contient une séquence de n'importe quel autre type. Les autres types que cet exemple utilise, sont définis dans un second fichier de schéma :
Voici l'exemple de code PHP qui utilise ces deux fichiers de schéma :
<?php
/**
* Illustration de types ouverts et de l'utilisaton de la méthode addTypes()
*/
$xmldas = SDO_DAS_XML::create();
$xmldas->addTypes("jungle.xsd"); // ceci est un type ouvert, i.e. la xsd spécifiée peut contenir le type "any"
$xmldas->addTypes('animalTypes.xsd');
$baloo = $xmldas->createDataObject('','bearType');
$baloo->name = "Baloo";
$baloo->weight = 800;
$bagheera = $xmldas->createDataObject('','pantherType');
$bagheera->name = "Bagheera";
$bagheera->colour = 'inky black';
$kaa = $xmldas->createDataObject('','snakeType');
$kaa->name = "Kaa";
$kaa->length = 25;
$document = $xmldas->createDocument();
$do = $document->getRootDataObject();
$do->bear = $baloo;
$do->panther = $bagheera;
$do->snake = $kaa;
print($xmldas->saveString($document,2));
?>
Ces deux fichiers de schéma sont chargés dans le XML DAS avec les méthodes create() et addTypes(). La méthode createDataObject() est utilisée pour créer les trois objets de données. Dans chaque cas, l'URI de l'espace de noms et le nom du type sont passés à la méthode createDataObject() : dans cet exemple, l'URI de l'espace de nom est vide car aucun espace de noms n'est utilisé dans ce schéma. Une fois que les trois objets - représentant un ours, une penthère et un serpent - ont été créés, un objet document est créé avec la méthode createDocument(). Dans ce cas, il n'y a aucune ambiguité sur l'élément document - vu que le second fichier de schéma définit uniquement des types complexes, l'élément document ne peut être que l'élément global jungle défini dans le premier schéma. Ce document aura un objet racine simple correspondant à un élément document jungle vide. Vu que c'est un type ouvert, les propriétés peuvent y être ajoutées. Lorsque le premier assignement est effectué sur $do->bear, une propriété bear est ajoutée à l'objet racine : de la même façon que pour les deux assignements suivants. Lorsque le document est écrit via la méthode saveString(), le document résultant sera :
Exemple 2361. Trouver ce que vous voulez dans un document
Cet exemple illustre comment trouver un nom d'élément et l'espace de noms d'un élément du document depuis un objet XML Document, le type SDO et l'espace de noms depuis l'élément racine de données XML. Ceci peut être difficle à comprendre car il y a 4 méthodes à appeler : deux peuvent être exécutées sur l'objet Document, et deux sur n'importe quelle donnée y compris l'objet racine. Parceque les règles qui définissent la façon dont le modèle SDO est dérivé du modèle XML, lorsque l'objet de données concerné est l'objet racine qui représente l'objet document pour le document, seulement trois valeurs possibles peuvent revenir de l'appels des quatres méthodes.
Les deux appels de méthodes qui peuvent être exécutés sur le document sont getRootElementName() et getRootEelementURI(). Elles retournent respectivement le nom de l'élément et l'espace de noms de l'élément document.
Les deux appels de méthodes qui peuvent être exécutés sur tous les objets de données sont getTypeName() et getTypeNamespaceURI(). Elles retournent respectivement le nom du type SDO et l'espace de noms du type de l'objet de données.
Dans tous les cas, l'appel à la méthode getRootElementURI() sur l'objet document retournera la même valeur que l'appel à la méthode getNamespaceURI() sur l'objet racine. Les informations sont toutes dérivées depuis les premières lignes du fichier schéma, où il y a trois sortes distinctes d'informations. Pour illustrer ceci, voici les premières lignes du fichier letter.xsd qui nous avons utilisé plus haut.
Les trois valeurs importantes sont :
letters, le nom de l'élément document
FormLetter, le nom du type complexe de l'élément document. C'est également le nom du type SDO de l'objet racine.
http://letterSchema, l'espace de noms auquel l'élément document appartient. C'est également l'URI de l'espace de noms du type SDO de l'objet racine.
Le programme suivant charge le document lettre et vérifie les valeurs retournées de chaque des quatres appels.
<?php
$xmldas = SDO_DAS_XML::create("letter.xsd");
$document = $xmldas->loadFile("letter.xml");
$root_do = $document->getRootDataObject();
/**
* Le "root element name" est le nom de l'élément de l'élément document
* dans ce cas 'letters'
* Ceci correspond à l'attribut 'name' de l'élément document dans le fichier xsd et correspond
* au nom de l'élément depuis le XML
*/
echo "Le nom de l'élément document est " . $document->getRootElementName() . "\n";
assert($document->getRootElementName() == 'letters'); // une propriété du document
/**
* Le "root element URI" est l'espace de noms du nom de l'élément de l'élément document
* dans ce cas 'http://letterSchema' vu que 'letters' est dans l'espace de noms.
* Il est récupéré depuis le xsd et correspond à l'espace de noms récupéré du XML
*/
echo "L'élément document est dans l'espace de noms " . $document->getRootElementURI() . "\n";
assert($document->getRootElementURI() == 'http://letterSchema'); // une propriété du document
/**
* Le nom du type est récupéré depuis le modèle SDO
* Les règles XML-SDO utilisées pour cela sont :
* Le nom du type complexe s'il existe (ici, c'est le cas)
* Le nom de l'élément document s'il n'y a pas de type complexe
* Il est récupéré depuis le xsd
*/
echo "Le nom du type de l'objet racine est " . $root_do->getTypeName() . "\n";
assert($root_do->getTypeName() == 'FormLetter');
/**
* Le type de l'espace de noms est récupéré depuis le modèle SDO
* Les règles XML-SDO assurent que ce sera toujours le même que l'URI de
* l'espace de noms de l'élément document
*/
echo "L'URI de l'espace de noms de l'objet racine est " . $root_do->getTypeNamespaceURI() . "\n";
assert($root_do->getTypeNamespaceURI() == 'http://letterSchema');
?>
Ce programme affichera :
Exemple 2362. Affichage du modèle SDO
Le XML DAS fournit une signification simple pour voir quels types et propriétés ont été chargés. L'instruction PHP "print" ou "echo" affichera les types et les propriétés.
<?php
/**
* Affichage du modèle
*/
$xmldas = SDO_DAS_XML::create("letter.xsd");
print $xmldas;
?>
L'affichage de ce programme sera :
Le XML DAS fournit deux classes principales. La première est SDO_DAS_XML qui est la classe principale utilisée pour récupérer les données depuis le source XML et utilisée pour écrire les données. La seconde est la classe SDO_DAS_XML_Document qui représente les données du document XML.
Il y a également quelques classes d'exceptions qui peuvent être lançées si des erreurs sont trouvées lors d'une recherche ou de l'analyse du fichier xsd ou du fichier XML.
C'est la classe principale de XML DAS, qui est utilisée pour récupérer les données depuis le source XML mais également pour écrire les données.
create C'est une méthode statique disponible dans la classe SDO_DAS_XML. Utilisée pour construire l'objet SDO_DAS_XML.
addTypes Fonctionne de la même manière que la méthode create() mais utilisée pour ajouter de contenu d'un second fichier schéma dans un XML DAS qui a déjà été créé.
createDataObject Peut être utilisée pour construire l'objet de données SDO d'un type donnée.
createDocument Peut être utilisée pour construire l'objet Document XML.
loadFile Charge une instance XML depuis un ficiher. Ce fichier peut être en local ou sur un hôte distant.
loadString la même chose que la méthode ci-dessus. Charge l'instance XML qui est disponible sous la forme d'une chaîne de caractères.
saveFile sauvegarde l'objet SDO_DAS_XML_Document en tant qu'un fichier XML.
saveString sauvegarde l'objet SDO_DAS_XML_Document en tant qu'une chaîne de caractères.
Cette classe peut être utilisée pour récupérer le nom et l'espace de noms de l'élément document et pour récupérer l'objet racine du document. De plus, elle peut également être utilisée pour définir la version XML et l'encodage du document de sortie.
getRootDataObject récupère l'objet racine DataObject.
getRootElementName récupère le nom de l'objet racine DataObject.
getRootElementURI récupère l'URI de l'objet racine DataObject.
setEncoding définit l'encodage en fonction de la valeur fournie.
setXMLDeclaraion pour définir/supprimer la déclaration XML.
setXMLVersion définit la version XML en fonction de la valeur fournie.
Est une sous classe de
SDO_Exception.
Lançée pour toutes les erreurs d'analyse lors du chargement
des fichiers xsd/xml.
Les » spécifications SDO 2.0 définissent la concordance entre les types XML et les types SDO. Avec Java SDO, la concordance est implémentée par le XMLHelper. Avec SDO pour PHP, cette concordance est implémentée par les Services d'Accès de Données XML. Le XML DAS implémente la concordance décrite dans les spécifications SDO 2.0 avec les restrictions suivantes :
Procédure 10. Types Simples XML
Type Simple avec sdoJava:instanceClass - aucun support PHP fourni
Type simple avec sdoJava:extendedInstanceClass - aucun support PHP fourni
Type Simple avec une liste de itemType.
Type Simple avec union.
Procédure 11. Types Complex XML
Type complexe avec sdo:aliasName - aucun support PHP pour ces types d'alias SDO.
Procédure 12. Attribut XSD
Attribut avec sdo:aliasName - aucun support PHP pour les alias des propriétés SDO.
Attribut avec une valeur par défaut - aucun support PHP pour les propriétés par défaut SDO.
Attribut avec une valeur fixe - aucun support PHP pour les propriétés SDO en lecture-seules ou les valeurs par défaut.
Attribut référençant un DataObject avec sdo:propertyType - aucun support pour sdo:propertyType="...".
Attribut avec des propriétés bi-directionnelles d'un DataObject avec sdo:oppositeProperty et sdo:propertyType - aucun support PHP pour l'opposition SDO.
Procédure 13. Éléments XSD
Élément avec sdo:aliasName - aucun support PHP pour les alias de propriétés SDO.
Élément avec un groupe de substitution.
Procédure 14. Éléments XSD avec un type simple
Élément de SimpleType avec une valeur par défaut - aucun support PHP pour les valeurs par défaut SDO
Élément de SimpleType avec une valeur fixe - aucun support PHP pour les propriétés en lecture-seules SDO ou les valeurs par défaut.
Élément de SimpleType avec sdo:string - aucun support pour sdo:string="true".
Élément référençant un objet DataObject avec sdo:propertyType - aucun support pour sdo:propertyType="..."
Élément avec une référence bi-directionnelle pour un object DataObject avec sdo:oppositeProperty et sdo:propertyType - aucun support PHP pour l'opposition SDO.