php-doc-en/reference/sdo_das_xml/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
<!-- Purpose: xml -->
<!-- Membership: pecl -->
<!-- State: experimental -->

<reference id="ref.sdo-das-xml">
 <title>SDO XML Data Access Service Functions</title>
 <titleabbrev>SDO DAS XML</titleabbrev>

 <partintro>
  <section id="sdo-das-xml.intro">
   &reftitle.intro;
   <para>
    <!-- This warns that the extension is experimental -->
    &warn.experimental;
   </para>
   <para>
    In order to use the XML Data Access Service for Service Data Objects,
    you will need to understand some of the concepts behind SDO:
    the data graph, the data object, XPath and property expressions,
    and so on.
    If you are not familiar with these ideas, you might want to look first at
    <link linkend='ref.sdo'>the section on SDO</link>.
   </para>
   <para>
    The job of the XML DAS is to move data between the
    application and an XML data source, which can be either a file or
    a URL. In order to do this it needs to be told the location of the 
    XML schema, which is passed as a parameter to the create
    method of the XML DAS. 
    The schema is used to ensure conformance
    of XML being written out, and also to ensure that
    modifications made to an SDO originating from XML
    follow the model described by the XML schema.
   </para>
  </section>

  <section id="sdo-das-xml.requirements">
   &reftitle.required;
   <para>
    The SDO XML Data Access Service requires PHP 5.1 or higher.
    It is packaged with the SDO extension and requires
    SDO to have been installed.
    See the
    <link linkend="sdo.installation">SDO installation instructions</link>
    for the details of how to do this.
   </para>
  </section>

  <section id="sdo-das-xml.installation">
   &reftitle.install;
   <para>
    The XML Data Access Service is packaged and installed as part of the
    <link linkend='ref.sdo'>SDO extension</link>. Please Refer 
    <link linkend="sdo.installation">SDO installation instructions</link>.
   </para>
  </section>
 

  <section id='sdo-das-xml.limitations'>
   <title>Limitations</title>
   <para>
    The
    <ulink url='&url.ibm.sdo;'>SDO 2.0 specification</ulink>
    defines the mapping between XML types and SDO types.
    With Java SDO, this mapping is implemented by the XMLHelper.
    With SDO for PHP, this mapping is implemented by the
    XML Data Access Services.
    The XML DAS implements the mapping described in the
    SDO 2.0 specification with the following restrictions:
   </para>

   <procedure id='sdo-das-xml.limitations.simpletypes'>
    <title>XML Simple Types</title>
    <step>
     <para>
      Simple Type with abstract="true"
      - no PHP support for SDO abstract types.
     </para>
    </step>
    <step>
     <para>
      Simple Type with sdoJava:instanceClass
      - no PHP equivalent provided.
     </para>
    </step>
    <step>
     <para>
      Simple Type with sdoJava:extendedInstanceClass
      - no PHP equivalent provided.
     </para>
    </step>
    <step>
     <para>
      Simple Type with list of itemType.
     </para>
    </step>
    <step>
     <para>
      Simple Type with union.
     </para>
    </step>
   </procedure>

   <procedure id='sdo-das-xml.limitations.complextypes'>
    <title>XML Complex Types</title>
    <step>
     <para>
      Complex Type with abstract="true"
      - no PHP support for SDO abstract types.
     </para>
    </step>
    <step>
     <para>
      Complex Type with sdo:aliasName
      - no PHP support for SDO Type aliases.
     </para>
    </step>
    <step>
     <para>
      Complex Type with open content
      - no PHP support for SDO open types.
     </para>
    </step>
    <step>
     <para>
      Complex Type with open attribute
      - no PHP support for SDO open types.
     </para>
    </step>
   </procedure>

   <procedure id='sdo-das-xml.limitations.attribute'>
    <title>XSD Attribute</title>
    <step>
     <para>
      Attribute with sdo:aliasName
      - no PHP support for SDO property aliases.
     </para>
    </step>
    <step>
     <para>
      Attribute with default value
      - no PHP support for SDO property defaults.
     </para>
    </step>
    <step>
     <para>
      Attribute with fixed value
      - no PHP support for SDO read-only properties or default values.
     </para>
    </step>
    <step>
     <para>
      Attribute reference.
     </para>
    </step>
    <step>
     <para>
      Attribute with sdo:string
      - no support for sdo:string="true".
     </para>
    </step>
    <step>
     <para>
      Attribute referencing a DataObject with
      sdo:propertyType - no support for sdo:propertyType="...".
     </para>
    </step>
    <step>
     <para>
      Attribute with bi-directional property to a DataObject with
      sdo:oppositeProperty and sdo:propertyType
      - no PHP support for SDO opposite.
     </para>
    </step>
   </procedure>

   <procedure id='sdo-das-xml.limitations.elements'>
    <title>XSD Elements</title>
    <step>
     <para>
      Element with sdo:aliasName
      - no PHP support for SDO property aliases.
     </para>
    </step>
    <step>
     <para>
      Element reference.
     </para>
    </step>
    <step>
     <para>
      Element with nillable.
     </para>
    </step>
    <step>
     <para>
      Element with substitution group.
     </para>
    </step>
   </procedure>

   <procedure id='sdo-das-xml.limitations.elementsimpletype'>
    <title>XSD Elements with Simple Type</title>
    <step>
     <para>
      Element of SimpleType with default
      - no PHP support for SDO defaults
     </para>
    </step>
    <step>
     <para>
      Element of SimpleType with fixed value
      - no PHP support for SDO read-only properties or default values.
     </para>
    </step>
    <step>
     <para>
      Element of SimpleType with sdo:string
      - no support for sdo:string="true".
     </para>
    </step>
    <step>
     <para>
      Element referencing a DataObject with
      sdo:propertyType  - no support for sdo:propertyType="..."
     </para>
    </step>
    <step>
     <para>
      Element with bi-directional reference to a DataObject with
      sdo:oppositeProperty and sdo:propertyType
      - no PHP support for SDO opposite.
     </para>
    </step>
   </procedure>
  </section>


  <section id='sdo-das-xml.examples'>
   &reftitle.examples;
   <para>
    The following examples are based on the
    <link linkend="sdo.sample.sequence">letter example</link>
    described in the
    <link linkend="ref.sdo">SDO documentation</link>.
    The examples assume the XML Schema for the letter is contained in a file
    <filename>letter.xsd</filename>
    and the letter instance is in the file
    <filename>letter.xml</filename>.
    These two files are reproduced here:
   </para>
   <para>
    <programlisting role="xml">
<![CDATA[
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:letter="http://letterSchema"
  targetNamespace="http://letterSchema">
  <xsd:element name="letters" type="letter:FormLetter"/>
  <xsd:complexType name="FormLetter" mixed="true">
    <xsd:sequence>
      <xsd:element name="date" minOccurs="0" type="xsd:string"/>
      <xsd:element name="firstName" minOccurs="0" type="xsd:string"/>
      <xsd:element name="lastName" minOccurs="0" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>
]]>
    </programlisting>
   </para>
 
   <para>
    <programlisting role="xml">
<![CDATA[
<letter:letters xmlns:letter="http://letterSchema">
  <date>March 1, 2005</date>
  Mutual of Omaha
  Wild Kingdom, USA
  Dear
  <firstName>Casy</firstName>
  <lastName>Crocodile</lastName>
  Please buy more shark repellent.
  Your premium is past due.
</letter:letters>
]]>
    </programlisting>
   </para>
    
   <example>
    <title>Loading, altering, and saving an XML document</title>
    <para>
     The following example shows how an XML document can be loaded from a file,
     altered, and written back. 
    </para>
    <programlisting role="php" id="sdo-das-xml.examples.loadfromfile">
     <![CDATA[
<?php
try {
    $xmldas = SDO_DAS_XML::create("letter.xsd");
    $xdoc = $xmldas->loadFromFile("letter.xml");
    $do = $xdoc->getRootDataObject();
    $do->date = "September 03, 2004";
    $do->firstName = "Anantoju";
    $do->lastName = "Madhu";
    $xmldas->saveDocumentToFile($xdoc, "letter-out.xml");
} catch (SDO_TypeNotFoundException $e) {
    print("Type is not defined in the xsd file");
} catch (SDO_DAS_XML_ParserException $e) {
    print("Problem while parsing");
}
?>
]]>
    </programlisting>
    <para>
     An instance of the XML DAS is first obtained from the 
     <function>SDO_DAS_XML::create</function>
     method, 
     which is a static method of the 
     <classname>SDO_DAS_XML</classname>
     class.
     The location of the xsd is passed as a parameter. 
     Once we have an instance of the XML DAS initialised
     with a given schema,
     we can use it to load the instance document using the 
     <function>loadFromFile</function>
     method.
     There is also a 
     <function>loadFromString</function>
     method if you want to load an XML 
     instance document from a string.
     If the instance document loads successfully, 
     you will be returned an object of type 
     <classname>SDO_DAS_XML_Document</classname>,
     on which you can call the 
     <function>getRootDataObject</function>
     method to get the SDO data object which is the root
     of the SDO data graph. 
     You can then use SDO operations to change the graph. 
     In this example we alter the 
     <varname>date</varname>, 
     <varname>firstName</varname>, and
     <varname>lastName</varname> properties.
     Then we use the 
     <function>saveDocumentToFile</function>
     method to write the changed document back to the file system.
    </para>
    <para>
     This will write the following to <filename>letter-out.xml</filename>.
    </para>
    <programlisting role="xml" id="sdo-das-xml.examples.loadfromfile.output">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<FormLetter xmlns="http://letterSchema" xsi:type="FormLetter" xmlns:xsi="http://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>     
]]>
   </programlisting>
    
   </example>
   <example>
    <title>Creating a new XML document</title>
    <para>
     The previous example loaded the document from a file. 
     This example shows how to create an SDO data graph in memory.
     In this example it is then saved to an XML string.
     Furthermore, because the letter contains both structured and 
     unstructured content, it uses
     <link linkend="sdo.sample.sequence">the Sequence API</link>
     as well assignments to properties to construct the data graph.
    </para>
    <programlisting role="php" id="sdo-das-xml.examples.create">
     <![CDATA[
<?php 
try {
    $xmldas = SDO_DAS_XML::create("letter.xsd");
    try {
        $letter = $xmldas->createDataObject("http://letterSchema", "FormLetter");
        $letter_seq = $letter->getSequence();
        $letter_seq->insert("April 09, 2005", NULL, 'date');
        $letter_seq->insert("Acme Inc. ", NULL, NULL);
        $letter_seq->insert("United Kingdom. ");
        $letter_seq->insert("Dear", NULL, NULL);
        $letter_seq->insert("Tarun", NULL, "firstName");
        $letter_seq->insert("Nayaraaa", NULL, "lastName");
        $letter->lastName = "Nayar";
        $letter_seq->insert("Please note that your order number ");
        $letter_seq->insert(12345);
        $letter_seq->insert(" has been dispatched today. Thanks for your business with us.");
        print($xmldas->saveDataObjectToString($letter, "http://letterSchema", "FormLetter"));
    } catch (SDO_Exception $e) {
        print($e);
    }
} catch (SDO_TypeNotFoundException $e) {
    print("Type is not defined in the xsd file");
} catch (SDO_DAS_XML_ParserException $e) {
    print("Problem while parsing");
}
?>
]]>
    </programlisting>
   </example>
   <para>
    This will emit the following output (line breaks have been inserted for readability):
   </para>
   <programlisting role="xml" id="sdo-das-xml.examples.create.output">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<FormLetter xmlns="http://letterSchema" xsi:type="FormLetter" 
xmlns:xsi="http://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>
]]>
   </programlisting>
   <example>
    <title>Setting XML document properties</title>
    <para>
     This third example shows you how to use the SDO_DAS_XML_Document class.
     SDO_DAS_XML_Document class is provided to get and set
     properties of the XML declaration such as version, schema location, 
     encoding and so on. 
    </para>
    <programlisting role="php" id="sdo-das-xml.examples.sdo_das_xml_document">
     <![CDATA[
<?php
try {
    $xmldas = SDO_DAS_XML::create("letter.xsd");
    $xdoc = $xmldas->loadFromFile("letter.xml");
    print("Encoding is set to : " . $xdoc->getEncoding() . "\n");
    print("XML Version : " . $xdoc->getXMLVersion() . "\n");
    $xdoc->setXMLVersion("1.1");
    print($xmldas->saveDocumentToString($xdoc));
} catch (SDO_TypeNotFoundException $e) {
    print("Type is not defined in the xsd file");
} catch (SDO_DAS_XML_ParserException $e) {
    print("Problem while parsing");
}
?>
]]>
    </programlisting>
   <para>
    The first three lines of output show how the encoding and
    XML version has been obtained from the document, 
    and how the XML version has been set in the XML header.
   </para>
   <programlisting role="xml" id="sdo-das-xml.examples.sdo_das_xml_document.output">
<![CDATA[
Encoding is set to : UTF-8
XML Version : 1.0
<?xml version="1.1" encoding="UTF-8"?>
...
]]>
   </programlisting>
    
   </example>
  </section>


  <!-- class definition section -->
  <section id='sdo-das-xml.classes'>
  &reftitle.classes;
   <para>
    The XML DAS provides three classes.
    The SDO_DAS_XML which is the main class used to fetch the
    data from the XML source and also can used to write the data back.
    The next one is SDO_DAS_XML_Document class,
    which is basically useful to get/set the XML declarations such as
    encoding, version etc.
    And the last class is SDO_DAS_XML_ParserException which will
    be thrown for any parser exceptions while loading xsd/xml file.
   </para>

   <section id='sdo-das-xml.class.sdo_das_xml'>
    <title>
     <classname>SDO_DAS_XML</classname>
    </title>
    <para>
     This is the main class of XML DAS,
     which is used fetch the data from the xml source
     and also used to write the data back.
     Other than the methods to load and save xml files,
     it also has a method called createDataObject
     which can be used to create an empty DataObject of a given type.
    </para>
    <section id='sdo-das-xml.class.SDO_DAS_XML.methods'>
     &reftitle.methods;
     <itemizedlist>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-create'>create</link>
        This is the only static method available in SDO_DAS_XML class.
        Used to construct SDO_DAS_XML object.
       </para>
      </listitem>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-createDataObject'>createDataObject</link>
        Can be used to construct the DataObject of a given type.
       </para>
      </listitem>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-loadFromFile'>loadFromFile</link>
        Loads the xml instance document from a file.
        This file can be at local file system or it can be on a remote host.
       </para>
      </listitem>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-loadFromString'>loadFromString</link>
        same as the above method.
        Loads the xml instance which is available as string.
       </para>
      </listitem>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-saveDataObjectToFile'>saveDataObjectToFile</link>
        save SDO_DataObject to a file.
       </para>
      </listitem>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-saveDataObjectToString'>saveDataObjectToString</link>
        save SDO_DataObject to a string.
       </para>
      </listitem>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-saveDocumentToFile'>saveDocumentToFile</link>
        save SDO_DAS_XML_Document object as a xml file.
       </para>
      </listitem>

      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-saveDocumentToString'>saveDocumentToString</link>
        save SDO_DAS_XML_Document object as a xml string.
       </para>
      </listitem>

     </itemizedlist>
    </section>
   </section>


   <section id='sdo-das-xml.class.sdo_das_xml_document'>
    <title>
     <classname>SDO_DAS_XML_Document</classname>
    </title>
    <para>
     This class can be used to get/set XML Declarations such as encoding,
     schema location etc.
    </para>
    <section id='sdo-das-xml.class.SDO_DAS_XML_Document.methods'>
     &reftitle.methods;
     <itemizedlist>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-getEncoding'>getEncoding</link>
        gets the encoding string.
       </para>
      </listitem>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-getNoNamespaceSchemaLocation'>getNoNamespaceSchemaLocation</link>
        gets the no namespace schema location.
       </para>
      </listitem>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-getRootDataObject'>getRootDataObject</link>
        gets the root DataObject.
       </para>
      </listitem>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-getRootElementName'>getRootElementName</link>
        gets the root DataObject's name.
       </para>
      </listitem>

      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-getRootElementURI'>getRootElementURI</link>
        gets the root DataObject's URI.
       </para>
      </listitem>

      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-getSchemaLocation'>getSchemaLocation</link>
        gets schema location.
       </para>
      </listitem>

      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-getXMLDeclaration'>getXMLDeclaration</link>
        gets whether xml declaration is set ot not.
       </para>
      </listitem>
      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-getXMLVersion'>getXMLVersion</link>
        gets the xml version.
       </para>
      </listitem>

      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-setEncoding'>setEncoding</link>
        sets the encoding string with the given value.
       </para>
      </listitem>

      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-setNoNamespaceSchemaLocation'>setNoNamespaceSchemaLocation</link>
        sets the no namespace schema location with the given value.
       </para>
      </listitem>

      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-setSchemaLocation'>setSchemaLocation</link>
        sets the schema location with the given value.
       </para>
      </listitem>

      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-setXMLDeclaration'>setXMLDeclaraion</link>
        to set/unset the xml declaration.
       </para>
      </listitem>
 


      <listitem>
       <para>
        <link linkend='function.SDO-DAS-XML-Document-setXMLVersion'>setXMLVersion</link>
        sets the xml version with the given value.
       </para>
      </listitem>
     </itemizedlist>
    </section>
   </section>

   <section id='sdo-das-xml.class.sdo_das_xml_parserexception'>
    <title>
     <classname>SDO_DAS_XML_ParserException</classname>
    </title>
    <para>
     Is a subclass of
     <classname>SDO_Exception</classname>.
     Thrown for any parser errors while loading the xsd/xml file.
    </para>
   </section>
  </section>

 </partintro>
 &reference.sdo-das-xml.functions;
</reference>

<!--
     Please note that this example uses a company schema((
     <link linkend="sdo.examples">company.xsd</link>
     )) as defined in SDO samples section.
    </para>
    <programlisting role="php" id="sdo-das-xml.examples.createDataObject">
     <![CDATA[
<?php
$xmldas = SDO_DAS_XML::create("company.xsd");
$do = $xmldas->createDataObject("companyNS", "CompanyType");
$do->name = "Acme Inc";
$dept1 = $do->createDataObject("departments");
$dept1->name = "sales";
$emp1 = $dept1->createDataObject("employees");
$emp1->name = "Fred";
$emp1->manager = FALSE;
$dept2 = $do->createDataObject("departments");
$emp2 = $dept2->createDataObject("employees");
$emp2->name = "Neil";
$emp2->manager = TRUE;
print($xmldas->saveDataObjectToString($do, "companyNS", "CompanyType"));
var_dump($do);
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Working with the SDO_DAS_XML Class</title>
    <para>
     This example shows you how to create the DataObject and use

-->

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->