Forum und email
Référence des fonctions
PHP Manual

Fonctions de Service d'Accès de Données SDO XML

Introduction

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.

Pré-requis

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.

Installation

Le Service d'Accès de Données et empaqueté et installé avec l'extension SDO. Référez-vous à instructions d'installation SDO.

Exemples

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 : 

<xsd:schema xmlns:xsd="https://www.w3.org/2001/XMLSchema"
  xmlns:lettre="https://lettreSchema"
  targetNamespace="https://lettreSchema">
  <xsd:element name="lettres" type="lettre:FormLettre"/>
  <xsd:complexType name="FormLettre" mixed="true">
    <xsd:sequence>
      <xsd:element name="date" minOccurs="0" type="xsd:string"/>
      <xsd:element name="prenom" minOccurs="0" type="xsd:string"/>
      <xsd:element name="nomFamille" minOccurs="0" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>


<lettre:lettres xmlns:lettre="https://lettreSchema">
  <date>1er Mars 2005</date>
  Mutual of Omaha
  Wild Kingdom, USA
  Chère
  <prenom>Casy</prenom>
  <nomFamille>Crocodile</nomFamille>
  S'il vous plaît, achetez plus de requin imperméable.
  Votre prime est passée date.
</lettre:lettres>

Example#1 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. 

<?xml version="1.0" encoding="UTF-8"?>
<FormLetter xmlns="https://letterSchema" xsi:type="FormLetter" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
 <date>September 03, 2004</date>
 Mutual of Omaha
 Wild Kingdom, USA
 Dear
 <firstName>Anantoju</firstName>
 <lastName>Madhu</lastName>
 Please buy more shark repellent.
 Your premium is past due.
</FormLetter>

Example#2 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é) : 

<?xml version="1.0" encoding="UTF-8"?>
<FormLetter xmlns="https://letterSchema" xsi:type="FormLetter" 
            xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
 <date>April 09, 2005</date>
 Acme Inc. United Kingdom. 
 Dear
 <firstName>Tarun</firstName>
 <lastName>Nayar</lastName>
 Please note that your order number 12345 has been 
 dispatched today. Thanks for your business with us.
</FormLetter>

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

<?xml version="1.1" encoding="ISO-8859-1"?>
.../...

Example#4 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 : 

<schema
         xmlns="https://www.w3.org/2001/XMLSchema">
 <element name="jungle">
  <complexType>
   <sequence>
    <any minOccurs="0" maxOccurs="unbounded"/>
   </sequence>
  </complexType>
 </element>
</schema>

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 : 

<schema xmlns= "https://www.w3.org/2001/XMLSchema">

 <complexType name="snakeType">
  <sequence>
   <element name= "name" type="string"/>
   <element name= "length" type="positiveInteger" />
  </sequence>
 </complexType>

 <complexType name="bearType">
  <sequence>
   <element name= "name" type="string"/>
   <element name= "weight" type="positiveInteger" />
  </sequence>
 </complexType>

 <complexType name="pantherType">
  <sequence>
   <element name= "name" type="string"/>
   <element name= "colour" type="string" />
  </sequence>
 </complexType>

</schema>

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 : 

  <?xml version="1.0" encoding="UTF-8"?>
  <jungle xsi:type="jungle" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
  <bear xsi:type="bearType">
  <name>Baloo</name>
  <weight>800</weight>
 </bear>
 <panther xsi:type="pantherType">
  <name>Bagheera</name>
  <colour>inky black</colour>
 </panther>
 <snake xsi:type="snakeType">
  <name>Kaa</name>
  <length>25</length>
 </snake>
</jungle>

Example#5 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. 

<xsd:schema xmlns:xsd="https://www.w3.org/2001/XMLSchema"
xmlns:letter="https://letterSchema"
targetNamespace="https://letterSchema">

<xsd:element name="letters" type="letter:FormLetter"/>

<xsd:complexType name="FormLetter" mixed="true">
.../...

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.

  • https://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.

C'est une partie des règles XML-SDO qui, lorsque le modèle SDO est construit depuis le fichier schéma, sont utilisé pour récupérer le nom du type et l'URI de l'espace de noms des types SDO pour l'élément racine pour les types complexes de l'élément document, lorsqu'ils existent. Dans cet exemple, le nom du type de l'objet racine est FormLetter. Dans le cas où il n'y a pas de définission de type complexe séparé pour l'élément document, lorsque le type est défini en ligne et qu'il est anonyme, le nom du type SDO sera le même que le nom de l'élément.

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 'https://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() == 'https://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() == 'https://letterSchema'); 

?>

Ce programme affichera : 

Le nom de l'élément document est letters
L'élément document est dans l'espace de noms https://letterSchema
Le nom du type de l'objet racine est FormLetter
L'URI de l'espace de noms de l'objet racine est https://letterSchema

Example#6 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 : 

object(SDO_XML_DAS)#1 {
18 types have been defined. The types and their properties are::
1. commonj.sdo:BigDecimal
2. commonj.sdo:BigInteger
3. commonj.sdo:Boolean
4. commonj.sdo:Byte
5. commonj.sdo:Bytes
6. commonj.sdo:ChangeSummary
7. commonj.sdo:Character
8. commonj.sdo:DataObject
9. commonj.sdo:Date
10. commonj.sdo:Double
11. commonj.sdo:Float
12. commonj.sdo:Integer
13. commonj.sdo:Long
14. commonj.sdo:Short
15. commonj.sdo:String
16. commonj.sdo:URI
17. https://letterSchema:FormLetter
- date (commonj.sdo:String)
- firstName (commonj.sdo:String)
- lastName (commonj.sdo:String)
18. https://letterSchema:RootType
- letters (https://letterSchema:FormLetter)

Classes pré-définies

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.

SDO_DAS_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.

Méthodes

  • 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.

SDO_DAS_XML_Document

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.

Méthodes

SDO_DAS_XML_ParserException

Est une sous classe de SDO_Exception. Lançée pour toutes les erreurs d'analyse lors du chargement des fichiers xsd/xml.

SDO_DAS_XML_FileException

Est une sous classe de SDO_Exception. Lançée par toutes les méthodes qui chargent des données depuis un fichier, lorsque le fichier ne peut être trouvé.

Limitations avec la spécification SDO 2.0

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 :

Types Simples XML

  1. Type Simple avec sdoJava:instanceClass - aucun support PHP fourni

  2. Type simple avec sdoJava:extendedInstanceClass - aucun support PHP fourni

  3. Type Simple avec une liste de itemType.

  4. Type Simple avec union.

Types Complex XML

  1. Type complexe avec sdo:aliasName - aucun support PHP pour ces types d'alias SDO.

Attribut XSD

  1. Attribut avec sdo:aliasName - aucun support PHP pour les alias des propriétés SDO.

  2. Attribut avec une valeur par défaut - aucun support PHP pour les propriétés par défaut SDO.

  3. Attribut avec une valeur fixe - aucun support PHP pour les propriétés SDO en lecture-seules ou les valeurs par défaut.

  4. Attribut référençant un DataObject avec sdo:propertyType - aucun support pour sdo:propertyType="...".

  5. Attribut avec des propriétés bi-directionnelles d'un DataObject avec sdo:oppositeProperty et sdo:propertyType - aucun support PHP pour l'opposition SDO.

Éléments XSD

  1. Élément avec sdo:aliasName - aucun support PHP pour les alias de propriétés SDO.

  2. Élément avec un groupe de substitution.

Éléments XSD avec un type simple

  1. Élément de SimpleType avec une valeur par défaut - aucun support PHP pour les valeurs par défaut SDO

  2. É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.

  3. Élément de SimpleType avec sdo:string - aucun support pour sdo:string="true".

  4. Élément référençant un objet DataObject avec sdo:propertyType - aucun support pour sdo:propertyType="..."

  5. É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.

Table of Contents

Référence des fonctions
PHP Manual