cvs: phpdoc /en/reference/sdo book.xml constants.xml examples.xml limitations.xml reference.xml setup.xml

From:	Hannes Magnusson	Date:	Wed, 26 Dec 2007 14:57:57 +0000
Subject:	cvs: phpdoc /en/reference/sdo book.xml constants.xml examples.xml limitations.xml reference.xml setup.xml
Groups:	php.doc.cvs
Request:	Send a blank email to doc-cvs+get-840@lists.php.net to get a copy of this message

bjori Wed Dec 26 14:57:57 2007 UTC Modified files: /phpdoc/en/reference/sdo book.xml examples.xml limitations.xml setup.xml constants.xml reference.xml Log: MFB: Upgrade to the new-reference-structure - (Created missing setup sections in setup.xml, if any) - Moved the intro to book.xml - Changed the intro ID from <extname>.intro to intro.<extname> - Moved the constants entity to book.xml - Changed constants.xml to be an appendix - Moved sdo.examples into its own chapter (examples.xml) NOTE: The orginal sdo.examples section ID was renamed to sdo.examples-basic Added title to the sdo.examples-basic section - Moved the requirements & installation sections to setup.xml - Moved sdo.limitations into its own chapter (limitations.xml) NOTE: The partintro still containts the sdo.das.table section and the classlisting

http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sdo/book.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/sdo/book.xml diff -u /dev/null phpdoc/en/reference/sdo/book.xml:1.2 --- /dev/null Wed Dec 26 14:57:57 2007 +++ phpdoc/en/reference/sdo/book.xml Wed Dec 26 14:57:57 2007 @@ -0,0 +1,101 @@ +<?xml version="1.0" encoding="utf-8"?> + + + + +<book xml:id="book.sdo" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>SDO</title> + +  + <preface xml:id="intro.sdo"> + &reftitle.intro; + <para> + Service Data Objects (SDOs) enable PHP applications to work with + data from different sources (like a database query, an XML file, + and a spreadsheet) using a single interface. + </para> + <para> + Each different kind of data source requires a Data Access Service + (DAS) to provide access to the data in the data source. + In your PHP application, you use a DAS to create an SDO + instance that represents some data in the data source. You can then + set and get values in the SDO instance using the standard SDO + interface. Finally, you use a DAS to write the modified data back + to a data source, typically the same one. + </para> + <para> + See the + <link linkend="sdo.das.table">list of Data Access Services</link> + for details on those + currently available. In addition to the provided DASs, SDO also + provides interfaces to enable others to be implemented + (see the section on <link linkend="sdo.class.sdo-das-spis">SDO Data + Access Services Interface</link> for more details). + </para> + <para> + This extension is derived from concepts taken from the + <link xlink:href="&url.ibm.sdo;">Service Data Objects specification</link>. + It includes a version of the + <link xlink:href="&url.apache.tuscany;">Apache Tuscany</link> SDO for C++ project. + </para> + <section xml:id="sdo.intro.structure"> + <title>The Structure of a Service Data Object</title> + <para> + A Service Data Object instance is made up of a tree of data objects. + The tree is defined by containment relationships between the data + objects. For example, a Company data object might consist of a number + of Department data objects and therefore the Company would have + a containment relationship to the Departments. + </para> + <para> An SDO may also have non-containment references between data objects in the + tree. For example, one Employee data object might reference another Employee to + identify a career mentor. + </para> + <para> + As well as data objects referencing each other, they can also have + primitive properties. For example, the Company data object might + have a property called "name" of type string, for holding the name + of the company (for example, "Acme"). + </para> + <para> Each of these properties of a data object - containment relationships, + non-containment references, or primitive properties - may be many-valued or + single-valued. In the above examples, Departments is many-valued and + the Company name is single-valued. + </para> + <para> In PHP, each SDO data object is represented as a PHP object. The properties of the + data object can be accessed using either object syntax or associative array syntax. + We'll see some examples of this later. + </para> + </section> + </preface> +  + + &reference.sdo.setup; + &reference.sdo.constants; + &reference.sdo.limitations; + &reference.sdo.examples; + &reference.sdo.reference; + +</book> + + + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sdo/examples.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/sdo/examples.xml diff -u /dev/null phpdoc/en/reference/sdo/examples.xml:1.2 --- /dev/null Wed Dec 26 14:57:57 2007 +++ phpdoc/en/reference/sdo/examples.xml Wed Dec 26 14:57:57 2007 @@ -0,0 +1,810 @@ +<?xml version="1.0" encoding="utf-8"?> + + +<chapter xml:id="sdo.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + &reftitle.examples; + <section xml:id='sdo.examples-basic'> + <title>Basic Usage</title> + <para> + The examples below assume an SDO created with the schema + and instance information shown below, using the XML Data Access Service. + </para> + <para> + The instance document below describes a single company, + called 'MegaCorp', which contains a single department, + called 'Advanced Technologies'. + The Advanced Technologies department contains three employees. + The company employeeOfTheMonth is referencing the second employee, + 'Jane Doe'. + </para> + <para> + <programlisting role="xml"> +<![CDATA[ +<?xml version="1.0" encoding="UTF-8" ?> +<company xmlns="companyNS" name="MegaCorp" + employeeOfTheMonth="E0003"> + <departments name="Advanced Technologies" location="NY" number="123"> + <employees name="John Jones" SN="E0001"/> + <employees name="Jane Doe" SN="E0003"/> + <employees name="Al Smith" SN="E0004" manager="true"/> + </departments> +</company> +]]> + </programlisting> + </para> + <para> The root element of the schema is a company. The company contains departments, and + each department contains employees. Each element has a number of attributes to store + things like name, serial number, and so on. Finally, the company also has an IDREF + attribute which identifies one of the employees as the 'employeeOfTheMonth'. + </para> + <para> + <programlisting role="xml"> +<![CDATA[ +<xsd:schema + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + xmlns:sdo="commonj.sdo" + xmlns:sdoxml="commonj.sdo/xml" + xmlns:company="companyNS" + targetNamespace="companyNS"> + <xsd:element name="company" type="company:CompanyType"/> + <xsd:complexType name="CompanyType"> + <xsd:sequence> + <xsd:element name="departments" type="company:DepartmentType" + maxOccurs="unbounded"/> + </xsd:sequence> + <xsd:attribute name="name" type="xsd:string"/> + <xsd:attribute name="employeeOfTheMonth" type="xsd:IDREF" + sdoxml:propertyType="company:EmployeeType"/> + </xsd:complexType> + <xsd:complexType name="DepartmentType"> + <xsd:sequence> + <xsd:element name="employees" type="company:EmployeeType" + maxOccurs="unbounded"/> + </xsd:sequence> + <xsd:attribute name="name" type="xsd:string"/> + <xsd:attribute name="location" type="xsd:string"/> + <xsd:attribute name="number" type="xsd:int"/> + </xsd:complexType> + <xsd:complexType name="EmployeeType"> + <xsd:attribute name="name" type="xsd:string"/> + <xsd:attribute name="SN" type="xsd:ID"/> + <xsd:attribute name="manager" type="xsd:boolean"/> + </xsd:complexType> +</xsd:schema> +]]> + </programlisting> + </para> + <para>The XML Data Access Service maps the schema to an SDO. Attributes such as "name" + become primitive properties, the sequence of employees becomes a many-valued + containment relationship, and so on. Note that the containment relationships are + expressed as one complex type within another, whereas non-containment references are + expressed in terms of ID and IDREF, with a special + <command>sdoxml:propertyType</command> attribute specifying the type of the + non-containment reference. + </para> + </section> + + <section xml:id="sdo.sample.getset"> + <title>Setting and Getting Property Values</title> + <para> The following examples assume + <command>$company</command> is the root of a tree of data objects created from the + schema and instance document shown above. + </para> + <para> + <example> + <title>Access via property name</title> + <para> + Data object properties can be accessed using the object property + access syntax. The following sets the company name to 'Acme'. + </para> + <programlisting role="php" xml:id="sdo.examples.propname"> +<![CDATA[ +<?php +$company->name = 'Acme'; +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Access via property name as array index</title> + <para>We can also access properties using associative array syntax. The simplest + form of this uses the property name as the array index. For example, the following sets + the company name and gets the employeeOfTheMonth. + </para> + <programlisting role="php" xml:id="sdo.examples.simplexpath"> +<![CDATA[ +<?php +$company['name'] = 'UltraCorp'; +$eotm = $company['employeeOfTheMonth']; +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Data Object iteration</title> + <para> + We can iterate over the properties of a data object using foreach. + The following iterates over the properties of the employee of the month. + </para> + <programlisting role="php" xml:id="sdo.examples.doiter"> +<![CDATA[ +<?php + $eotm = $company->employeeOfTheMonth; + foreach ($eotm as $name => $value) { + echo "$name: $value\n"; + } +?> +]]> + </programlisting> + <para> + which will output: + </para> + <programlisting xml:id="sdo.examples.doiter-output"> +<![CDATA[ +name: Jane Doe +SN: E0003 +]]> + </programlisting> + <para> + The 'manager' property is not output, because it has not been set. + </para> + </example> + </para> + + <para> + <example> + <title>Access many-valued property by name</title> + <para> Many-valued data object properties can also be accessed using the object + property name syntax. The following gets the list of departments. + </para> + <programlisting role="php" xml:id="sdo.examples.mvpname"> +<![CDATA[ +<?php +$departments = $company->departments; +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Many-valued element access</title> + <para> + We can access individual elements of many-valued properties using array + syntax. The following accesses the first department in the company. + </para> + <programlisting role="php" xml:id="sdo.examples.mvaccess"> +<![CDATA[ +<?php +$ad_tech_dept = $company->departments[0]; +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Many-valued property iteration</title> + <para> + Many-valued properties can also be iterated over using + foreach. The following iterates over the company's departments. + </para> + <programlisting role="php" xml:id="sdo.examples.mvpiter"> +<![CDATA[ +<?php + foreach ($company->departments as $department) { + // ... + } +?> +]]> + </programlisting> + <para> + Each iteration will assign the next department in the + list to the variable <command>$department</command>. + </para> + </example> + </para> + + <para> + <example> + <title>Chained property access</title> + <para> We can chain property references on a single line. + The following sets and gets the name of the first department. + </para> + <programlisting role="php" xml:id="sdo.examples.nestedprop"> +<![CDATA[ +<?php + $company->departments[0]->name = 'Emerging Technologies'; + $dept_name = $company->departments[0]->name; +?> +]]> + </programlisting> + <para>Using the associative array syntax, this is equivalent to</para> + <programlisting role="php" xml:id="sdo.examples.chainarray"> +<![CDATA[ +<?php + $company['departments'][0]['name'] = 'Emerging Technologies'; + $dept_name = $company['departments'][0]['name']; +?> +]]> + </programlisting> + <para> In either case, the dept_name variable is set to 'Emerging Technologies'. + </para> + </example> + </para> + + <para> + <example> + <title>XPath navigation</title> + <para> The associative array index can be an XPath-like expression. Valid + expressions are defined by an augmented sub-set of XPath. + </para> + <para> + Two forms of indexing into many-valued properties are supported. + The first is the standard XPath array syntax with the indexing + starting at one, the second is an SDO extension to XPath with an index + starting at zero. The standard syntax is: + </para> + <programlisting role="php" xml:id="sdo.examples.xpath1nav"> +<![CDATA[ +<?php + $jane_doe = $company["departments[1]/employees[2]"]; +?> +]]> + </programlisting> + <para>and the SDO XPath extension syntax is:</para> + <programlisting role="php" xml:id="sdo.examples.xpath0nav"> +<![CDATA[ +<?php + $jane_doe = $company["departments.0/employees.1"]; +?> +]]> + </programlisting> + <para> + Both these examples get the second employee from the first department. + </para> + </example> + </para> + + <para> + <example> + <title>XPath querying</title> + <para> + We can use XPath to query and identify parts of a data object based + on instance data. The following retrieves the manager from the + 'Advanced Technologies' department. + </para> + <programlisting role="php" xml:id="sdo.examples.xpathquery"> +<![CDATA[ +<?php + $ad_tech_mgr = + $company["departments[name='Advanced Technologies']/employees[manager=true]"]; +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Creating child data objects</title> + <para> + A data object can be a factory for its child data objects. + A child data object is automatically part of the data graph. + The following add a new employee to the 'Advanced Technologies' + department. + </para> + <programlisting role="php" xml:id="sdo.examples.create"> +<![CDATA[ +<?php + $ad_tech_dept = $company["departments[name='Advanced Technologies']"]; + $new_hire = $ad_tech_dept->createDataObject('employees'); + $new_hire->name = 'John Johnson'; + $new_hire->SN = 'E0005'; + $new_hire->manager = false; +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Unset a primitive property</title> + <para> + We can use the <function>isset</function> and + <function>unset</function> functions to test and remove items + from the data object. + </para> + <para> + The following clears the name of the first department. + </para> + <programlisting role="php" xml:id="sdo.examples.unsetprim"> +<![CDATA[ +<?php + unset($company->departments[0]->name); +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Unset a data object</title> + <para> + unset can also be used to remove a data object from the tree. + The following example shows John Jones leaving the company. + </para> + <programlisting role="php" xml:id="sdo.examples.unsetdo"> +<![CDATA[ +<?php + unset($company->departments[0]->employees[0]); +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Unset a referenced data object</title> + <para> + The following removes the 'employeeOfTheMonth' from the company. + If this were a containment relationship then the + employee would be removed from the company + (probably not a good idea to sack your best employee each month!), + but since this is a non-containment reference, + the employee being referenced will remain in the + department in the company, + but will no longer be accessible via the employeeOfTheMonth property. + </para> + <programlisting role="php" xml:id="sdo.examples.unsetrefdo"> +<![CDATA[ +<?php + if (isset($company->employeeOfTheMonth)) { + unset($company->employeeOfTheMonth); + } +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Access via property index</title> + <para> Data object properties can be accessed via their property index using array + syntax. The property index is the position at which the property's definition + appears in the model (in this case the xml schema). We can see from the schema listing + above that the company name attribute is the second company property (the SDO + interface makes no distinction between XML attributes and elements). The following + sets the company name to 'Acme', with the same result as + <link linkend="sdo.examples.propname">Access via property name</link> + </para> + <programlisting role="php" xml:id="sdo.examples.propindex"> +<![CDATA[ +<?php + $company[1] = 'Acme'; +?> +]]> + </programlisting> + <para> Using the index directly in this way is likely to be fragile. Normally the + property name syntax should be preferred, but the property index may be required + in special cases. + </para> + </example> + </para> + + </section> + + <section xml:id="sdo.sample.sequence"> + <title>Working with Sequenced Data Objects</title> + <para> + Sequenced data objects are SDOs which can track property + ordering across the properties of a data object. They can also + contain unstructured text elements (text element which do not + belong to any of the SDO's properties). Sequenced data objects are + useful for working with XML documents which allow unstructured text (i.e. + mixed=true) or if the elements can be interleaved ( + <![CDATA[<A/><B/><A/>]]>). This can occur for example when + the schema defines maxOccurs>1 on a + element which is a complexType with a choice order indicator. + </para> + <para> + The examples below assume an SDO created with the following schema + and instance information, using the XML Data Access Service. + </para> + <para> + The schema below describes the format of a letter. The letter can + optionally contain three properties; date, firstName, and lastName. + The schema states <command>mixed="true"</command> which means that + unstructured text can be interspersed between the three properties. + </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> + The following is an instance letter document. It contains the + three letter properties; date, firstName and lastName, and has + unstructured text elements for the address and letter body. + </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> + <para> + When loaded, the letter data object will have the sequence and + property indices shown in the table below: + <informaltable> + <tgroup cols='3'> + <thead> + <row> + <entry>Sequence Index</entry> + <entry>Property Index:Name</entry> + <entry>Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>0</entry> + <entry>0:date</entry> + <entry>March 1, 2005</entry> + </row> + <row> + <entry>1</entry> + <entry>-</entry> + <entry>Mutual of Omaha</entry> + </row> + <row> + <entry>2</entry> + <entry>-</entry> + <entry>Wild Kingdom, USA</entry> + </row> + <row> + <entry>3</entry> + <entry>-</entry> + <entry>Dear</entry> + </row> + <row> + <entry>4</entry> + <entry>1:firstName</entry> + <entry>Casy</entry> + </row> + <row> + <entry>5</entry> + <entry>2:lastName</entry> + <entry>Crocodile</entry> + </row> + <row> + <entry>6</entry> + <entry>-</entry> + <entry>Please buy more shark repellent.</entry> + </row> + <row> + <entry>7</entry> + <entry>-</entry> + <entry>Your premium is past due.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + + <para> + To ensure sequence indices are maintained, sequenced data objects + should be manipulated through the SDO_Sequence interface. + This allows the data object's instance data to be manipulated + in terms of the sequence index as opposed to the property index + (shown in the table above). + The following examples assume the letter instance has been + loaded into a data object referenced by the variable + <command>$letter</command>. + <example> + <title>Getting the SDO_Sequence interface</title> + <para> + We obtain a data object's sequence using the + <function>getSequence</function> + method. The follow gets the + sequence for the letter data object. + </para> + <programlisting role="php" xml:id="sdo.examples.seqinterface"> +<![CDATA[ +<?php + $letter_seq = $letter->getSequence(); +?> +]]> + </programlisting> + </example> + </para> + <para> + All subsequent examples assume that the + <command>$letter_seq</command> + variable has been assigned the sequence for the letter data object. + </para> + + <para> + <example> + <title>Get/set sequence values</title> + <para> + We can get and set individual values (including unstructured text) + using the sequence index. + The following sets the firstName to 'Snappy' and gets the last + sequence values (the unstructured text, 'Your premium is past due.'). + </para> + <programlisting role="php" xml:id="sdo.examples.getsetseq"> +<![CDATA[ +<?php + $letter_seq[4] = 'Snappy'; + $text = $letter_seq[count($letter_seq) - 1]; +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Sequence iteration</title> + <para> + We can iterate through the individual sequence values using foreach. + The following runs through the individual values in sequence order. + </para> + <programlisting role="php" xml:id="sdo.examples.seqiter"> +<![CDATA[ +<?php +foreach ($letter->getSequence() as $value) { + // ... +} +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Sequence versus Data Object</title> + <para> + Setting values through the data object interface may result in the + value not being part of the sequence. A value set through the data + object will only be accessible through the sequence if the property was + already part of the sequence. The following example sets the + lastName through the data object and gets it through the sequence. + This is fine because lastName already exists in the sequence. If + it had not previously been set, then lastName would be set to + 'Smith', but would not be part of the sequence. + </para> + <programlisting role="php" xml:id="sdo.examples.seqvsdo"> +<![CDATA[ +<?php + $letter[2] = 'Smith'; + $last_name = $letter_seq[5]; +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Adding to a sequence</title> + <para> + We can add new values to a sequence using the + <link linkend='function.SDO-Sequence-insert'><function>SDO_Sequence::insert</function></link> + method. The following examples assume that the 'firstName' and + 'lastName' properties are initially unset. + </para> + <programlisting role="php" xml:id="sdo.examples.seqadd"> +<![CDATA[ +<?php + // Append a firstName value to the sequence + // value: 'Smith' + // sequence index: NULL (append) + // propertyIdentifier: 1 (firtName property index) + $letter_seq->insert('Smith', NULL, 1); + + // Append a lastName value to the sequence + // value: 'Jones' + // sequence index: NULL (append) + // propertyIdentifier: 'lastName' (lastName property name) + $letter_seq->insert('Jones', NULL, 'lastName'); + + // Append unstructured text + // value: 'Cancel Subscription.' + // sequence index: absent (append) + // propertyIdentifier: absent (unstructured text) + $letter_seq->insert('Cancel Subscription.'); + + // Insert new unstructured text. Subsequent sequence values + // are shifted up. + // value: 'Care of:' + // sequence index: 1 (insert as second element) + // propertyIdentifier: absent (unstructured text) + $letter_seq->insert('Care of:', 1); +?> +]]> + </programlisting> + </example> + </para> + + <para> + <example> + <title>Removing from a sequence</title> + <para> + We can use the <function>isset</function> and + <function>unset</function> functions to test and remove items + from the sequence (Note: <function>unset</function> currently + leaves the values in the data object, but this behaviour is + likely to change to also remove the data from the data object). + A sequence behaves like a contiguous list; therefore, removing + items from the middle will shift entries at higher indices + down. The following example tests to see if the first sequence + element is set and unsets it if is. + </para> + <programlisting role="php" xml:id="sdo.examples.seqremove"> +<![CDATA[ +<?php + if (isset($letter_seq[0])) { + unset($letter_seq[0]); + } +?> +]]> + </programlisting> + </example> + </para> + + </section> + + + <section xml:id="sdo.sample.reflection"> + <title>Reflecting on Service Data Objects</title> + <para> + SDOs have a knowledge of the structure they have been created to + represent (the model). For example, a Company SDO created using + <link linkend="sdo.examples">the Company XML schema</link> above + would only be permitted to contain DepartmentType data objects + which in turn could only contain EmployeeType data objects. + </para> + <para> + Sometimes it is useful to be able to access this model information at + runtime. For example, this could be used to automatically generate + a user interface for populating a data object. The model information + is accessed using reflection. + </para> + + <para> + <example> + <title>Reflecting on a Data Object</title> + <para> + The following example shows how we can reflect on an empty Employee + data object. + </para> + <programlisting role="php" xml:id="sdo.examples.reflection"> +<![CDATA[ +<?php + // Create the employee data object (e.g. from an XML Data Access Service) + $employee = ...; + $reflection = new SDO_Model_ReflectionDataObject($employee); + print($reflection); +?> +]]> + </programlisting> + &example.outputs; + + <screen> +<![CDATA[ +object(SDO_Model_ReflectionDataObject)#4 { - ROOT OBJECT - Type { +companyNS:EmployeeType[3] { commonj.sdo:String $name; +commonj.sdo:String $SN; commonj.sdo:Boolean $manager; } } +]]> + </screen> + <para> + Using print on the SDO_Model_ReflectionDataObject writes out the data + object's model. We can see from the output how the type + companyNS:EmployeeType has three properties and we can see the names + of the properties along with their types. Note, the primitive types + are listed as SDO types (e.g. commonj.sdo namespace, String type). + It is worth noting that this is the SDO model and when these are + surfaced to an application they can be treated as the PHP equivalent + types (e.g. string and boolean). + </para> + </example> + </para> + + <para> + <example> + <title>Accessing the type information</title> + <para> + We can query the type information of a data object using reflection. + The following example checks the type corresponds to a data object + rather than a primitive and then iterates through the properties of + the type, writing out the name of each property ($type and $property + are SDO_Model_Type and SDO_Model_Property objects, respectively). + </para> + <programlisting role="php" xml:id="sdo.examples.reflection.type"> +<![CDATA[ +<?php + // Create the employee data object (e.g. from an XML Data Access Service) + $employee = ...; + $reflection = new SDO_Model_ReflectionDataObject($employee); + $type = $reflection->getType(); + if (! $type->isDataType()) { + foreach ($type->getProperties() as $property) { + print $property->getName() . "\n"; + } + } +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +name +SN +manager +]]> + </screen> + </example> + </para> + + </section> +</chapter> + + + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sdo/limitations.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/sdo/limitations.xml diff -u /dev/null phpdoc/en/reference/sdo/limitations.xml:1.2 --- /dev/null Wed Dec 26 14:57:57 2007 +++ phpdoc/en/reference/sdo/limitations.xml Wed Dec 26 14:57:57 2007 @@ -0,0 +1,73 @@ +<?xml version="1.0" encoding="utf-8"?> + + +<chapter xml:id='sdo.limitations'> + <title>Limitations</title> + <procedure xml:id='sdo.limitations.implementation'> + <title>Implementation Limitations</title> + <para> + The following are limitations in the current SDO implementation: + </para> + <step> + <para> + There is no support for multi-byte character sets. + This will be considered, depending on community requirements, + in the Unicode-enabled version of PHP. + See <link linkend="ref.unicode">Unicode Functions</link>. + </para> + </step> + </procedure> + <procedure xml:id='sdo.limitations.sdo'> + <title>SDO Limitations</title> + <para> + The following SDO 2.0 concepts are not supported in the current + PHP implementation. + It is not necessarily the case that these will all be added over time. + Their inclusion will depend on community requirements. + </para> + <step> + <para> + Bi-directional relationships. + </para> + </step> + <step> + <para> + Type and property alias names. + </para> + </step> + <step> + <para> + Read-only properties. + </para> + </step> + <step> + <para> + The Helper classes defined in SDO 2.0 are not directly implemented. + However equivalent function is provided in a more natural way for PHP. + For example the function of <command>CopyHelper::copy()</command> + is provided by applying the PHP + <link linkend='language.oop5.cloning'>clone</link> keyword to a data object. + </para> + </step> + </procedure> +</chapter> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sdo/setup.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/sdo/setup.xml diff -u /dev/null phpdoc/en/reference/sdo/setup.xml:1.2 --- /dev/null Wed Dec 26 14:57:57 2007 +++ phpdoc/en/reference/sdo/setup.xml Wed Dec 26 14:57:57 2007 @@ -0,0 +1,208 @@ +<?xml version="1.0" encoding="utf-8"?> + + +<chapter xml:id="sdo.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + &reftitle.setup; + +  + <section xml:id="sdo.requirements"> + &reftitle.required; + <para> + The SDO extension requires PHP 5.1.0 or higher. It also requires the + libxml2 library. Normally libxml2 will already be installed, but if + not, it can be downloaded from + <link xlink:href='&url.libxml;'>&url.libxml;</link>. + </para> + </section> +  + +  + <section xml:id="sdo.installation"> + &reftitle.install; + <note> + <para> + Earlier versions of the SDO extension required a separate shared + library for the XML DAS. This is now obsolete and any references to + <filename>php_sdo_das_xml.dll</filename> + or + <filename>sdo_das_xml.so</filename> + should be removed from your &php.ini;. + </para> + </note> + <procedure xml:id='sdo.install.unix'> + <title>Unix systems</title> + <step> + <para> + The three SDO components - the SDO core, the XML DAS and the + Relational DAS - are packaged together with Service Component + Architecture (SCA) into one PECL project, SCA_SDO, so you can + download SCA and all three parts of SDO with the command: + <screen> +<![CDATA[ +pecl install SCA_SDO +]]> + </screen> + </para> + <para> + This command will build the SDO shared library as well as + installing the PHP files that make up SCA and the SDO + Relational DAS. + </para> + <para> + If you want to use the latest beta version, then instead run: + <screen> +<![CDATA[ +pecl install SCA_SDO-beta +]]> + </screen> + </para> + </step> + <step> + <para> + The + <command>pecl</command> + command automatically installs the SDO module into your PHP + extensions directory. To enable the SDO extension you must add the + following line to + &php.ini;: + <screen> +<![CDATA[ +extension=sdo.so +]]> + </screen> + </para> + <para> + For more information about building PECL packages, consult the + <link linkend="install.pecl">PECL installation</link> + section of the manual. + </para> + </step> + </procedure> + + <procedure xml:id='sdo.install.win32'> + <title>Windows</title> + <step> + <para> + The latest SDO DLL can be downloaded from + <link xlink:href='&url.pecl.win.ext;php_sdo.dll'>php_sdo.dll</link> + . + </para> + <para> + Note that currently the + <link xlink:href='&url.pecl.win;'>pecl4win</link> + site does not provide this binary at the current release level; + you can only download the latest level. + </para> + </step> + <step> + <para> + The + <command>pecl</command> + command automatically installs the SDO module into your PHP + extensions directory. To enable the SDO extension you must add the + following line to + &php.ini;: + <screen> +<![CDATA[ +extension=php_sdo.dll +]]> + </screen> + </para> + </step> + <step> + <para> + The Relational DAS can be downloaded and installed with the + command: + <screen> +<![CDATA[ +pecl install -B sdo +]]> + </screen> + </para> + <para> + The Relational DAS is written in PHP. You may need to update your + <link linkend="ini.include-path">include_path</link> + in + &php.ini; + to point to the directory that contains + <filename>sdo/DAS/Relational</filename>. + </para> + </step> + </procedure> + + <procedure xml:id='sdo.build.linux.steps'> + <title>Building SDO on Linux</title> + <para> + This section describes how to build the SDO core and XML DAS on + Linux. You would only need to know how to do this if you wish to + build a recent version that you have checked out of CVS. + </para> + <step> + <para> + Change to the main extension directory: + <command>cd < wherever your sdo code is ></command> + </para> + </step> + <step> + <para> + Run + <command>phpize</command> + , which will set up the environment to compile SDO. + </para> + </step> + <step> + <para> + Next, run + <command>./configure; make; make install</command> + . Please note, you may need to login as root to install the + extension. + </para> + </step> + <step> + <para> + Make sure that the module is loaded by PHP, by adding + <filename>extension=sdo.so</filename> + to your &php.ini; file. + </para> + </step> + </procedure> + </section> +  + +  + <section xml:id="sdo.configuration"> + &reftitle.runtime; + &no.config; + </section> +  + +  + <section xml:id="sdo.resources"> + &reftitle.resources; + &no.resource; + </section> +  + +</chapter> + + + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sdo/constants.xml?r1=1.3&r2=1.4&diff_format=u Index: phpdoc/en/reference/sdo/constants.xml diff -u phpdoc/en/reference/sdo/constants.xml:1.3 phpdoc/en/reference/sdo/constants.xml:1.4 --- phpdoc/en/reference/sdo/constants.xml:1.3 Wed Jun 20 22:25:19 2007 +++ phpdoc/en/reference/sdo/constants.xml Wed Dec 26 14:57:57 2007 @@ -1,7 +1,7 @@ <?xml version='1.0' encoding='iso-8859-1'?> - +  -<section xml:id="sdo.constants" xmlns="http://docbook.org/ns/docbook"> +<appendix xml:id="sdo.constants" xmlns="http://docbook.org/ns/docbook"> &reftitle.constants; &extension.constants; <variablelist> @@ -50,7 +50,7 @@ </listitem> </varlistentry> </variablelist> -</section> +</appendix>  - - + <reference xml:id="ref.sdo" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> - <title>SDO Functions</title> - <titleabbrev>SDO</titleabbrev> + <title>SDO &Functions;</title> <partintro> - <section xml:id="sdo.intro"> - &reftitle.intro; - <para> - Service Data Objects (SDOs) enable PHP applications to work with - data from different sources (like a database query, an XML file, - and a spreadsheet) using a single interface. - </para> - <para> - Each different kind of data source requires a Data Access Service - (DAS) to provide access to the data in the data source. - In your PHP application, you use a DAS to create an SDO - instance that represents some data in the data source. You can then - set and get values in the SDO instance using the standard SDO - interface. Finally, you use a DAS to write the modified data back - to a data source, typically the same one. - </para> - <para> - See the - <link linkend="sdo.das.table">list of Data Access Services</link> - for details on those - currently available. In addition to the provided DASs, SDO also - provides interfaces to enable others to be implemented - (see the section on <link linkend="sdo.class.sdo-das-spis">SDO Data - Access Services Interface</link> for more details). - </para> - <para> - This extension is derived from concepts taken from the - <link xlink:href="&url.ibm.sdo;">Service Data Objects specification</link>. - It includes a version of the - <link xlink:href="&url.apache.tuscany;">Apache Tuscany</link> SDO for C++ project. - </para> - - <section xml:id="sdo.intro.structure"> - <title>The Structure of a Service Data Object</title> - <para> - A Service Data Object instance is made up of a tree of data objects. - The tree is defined by containment relationships between the data - objects. For example, a Company data object might consist of a number - of Department data objects and therefore the Company would have - a containment relationship to the Departments. - </para> - <para> An SDO may also have non-containment references between data objects in the - tree. For example, one Employee data object might reference another Employee to - identify a career mentor. - </para> - <para> - As well as data objects referencing each other, they can also have - primitive properties. For example, the Company data object might - have a property called "name" of type string, for holding the name - of the company (for example, "Acme"). - </para> - <para> Each of these properties of a data object - containment relationships, - non-containment references, or primitive properties - may be many-valued or - single-valued. In the above examples, Departments is many-valued and - the Company name is single-valued. - </para> - <para> In PHP, each SDO data object is represented as a PHP object. The properties of the - data object can be accessed using either object syntax or associative array syntax. - We'll see some examples of this later. - </para> - </section> - </section> - - <section xml:id="sdo.requirements"> - &reftitle.required; - <para> - The SDO extension requires PHP 5.1.0 or higher. It also requires the - libxml2 library. Normally libxml2 will already be installed, but if - not, it can be downloaded from - <link xlink:href='&url.libxml;'> - &url.libxml; - </link> - . - </para> - </section> - - <section xml:id="sdo.installation"> - &reftitle.install; - <note> - <para> - Earlier versions of the SDO extension required a separate shared - library for the XML DAS. This is now obsolete and any references to - <filename>php_sdo_das_xml.dll</filename> - or - <filename>sdo_das_xml.so</filename> - should be removed from your - &php.ini; - . - </para> - </note> - <procedure xml:id='sdo.install.unix'> - <title>Unix systems</title> - <step> - <para> - The three SDO components - the SDO core, the XML DAS and the - Relational DAS - are packaged together with Service Component - Architecture (SCA) into one PECL project, SCA_SDO, so you can - download SCA and all three parts of SDO with the command: - <screen> - <![CDATA[ -pecl install SCA_SDO -]]> - </screen> - </para> - <para> - This command will build the SDO shared library as well as - installing the PHP files that make up SCA and the SDO - Relational DAS. - </para> - <para> - If you want to use the latest beta version, then instead run: - <screen> - <![CDATA[ -pecl install SCA_SDO-beta -]]> - </screen> - </para> - </step> - <step> - <para> - The - <command>pecl</command> - command automatically installs the SDO module into your PHP - extensions directory. To enable the SDO extension you must add the - following line to - &php.ini; - : - <screen> - <![CDATA[ -extension=sdo.so -]]> - </screen> - </para> - <para> - For more information about building PECL packages, consult the - <link linkend="install.pecl">PECL installation</link> - section of the manual. - </para> - </step> - </procedure> - - <procedure xml:id='sdo.install.win32'> - <title>Windows</title> - <step> - <para> - The latest SDO DLL can be downloaded from - <link xlink:href='&url.pecl.win.ext;php_sdo.dll'>php_sdo.dll</link> - . - </para> - <para> - Note that currently the - <link xlink:href='&url.pecl.win;'>pecl4win</link> - site does not provide this binary at the current release level; - you can only download the latest level. - </para> - </step> - <step> - <para> - The - <command>pecl</command> - command automatically installs the SDO module into your PHP - extensions directory. To enable the SDO extension you must add the - following line to - &php.ini; - : - <screen> - <![CDATA[ -extension=php_sdo.dll -]]> - </screen> - </para> - </step> - <step> - <para> - The Relational DAS can be downloaded and installed with the - command: - <screen> - <![CDATA[ -pecl install -B sdo -]]> - </screen> - </para> - <para> - The Relational DAS is written in PHP. You may need to update your - <link linkend="ini.include-path">include_path</link> - in - &php.ini; - to point to the directory that contains - <filename>sdo/DAS/Relational</filename> - . - </para> - </step> - </procedure> - - <procedure xml:id='sdo.build.linux.steps'> - <title>Building SDO on Linux</title> - <para> - This section describes how to build the SDO core and XML DAS on - Linux. You would only need to know how to do this if you wish to - build a recent version that you have checked out of CVS. - </para> - <step> - <para> - Change to the main extension directory: - <command>cd < wherever your sdo code is ></command> - </para> - </step> - <step> - <para> - Run - <command>phpize</command> - , which will set up the environment to compile SDO. - </para> - </step> - <step> - <para> - Next, run - <command>./configure; make; make install</command> - . Please note, you may need to login as root to install the - extension. - </para> - </step> - <step> - <para> - Make sure that the module is loaded by PHP, by adding - <filename>extension=sdo.so</filename> - to your - &php.ini; - file. - </para> - </step> - </procedure> - </section> - <section xml:id="sdo.das.table"> <title>Data Access Services</title> <para> @@ -280,843 +43,7 @@ </para> </section> - <section xml:id='sdo.limitations'> - <title>Limitations</title> - <procedure xml:id='sdo.limitations.implementation'> - <title>Implementation Limitations</title> - <para> - The following are limitations in the current SDO implementation: - </para> - <step> - <para> - There is no support for multi-byte character sets. - This will be considered, depending on community requirements, - in the Unicode-enabled version of PHP. - See <link linkend="ref.unicode">Unicode Functions</link>. - </para> - </step> - </procedure> - <procedure xml:id='sdo.limitations.sdo'> - <title>SDO Limitations</title> - <para> - The following SDO 2.0 concepts are not supported in the current - PHP implementation. - It is not necessarily the case that these will all be added over time. - Their inclusion will depend on community requirements. - </para> - <step> - <para> - Bi-directional relationships. - </para> - </step> - <step> - <para> - Type and property alias names. - </para> - </step> - <step> - <para> - Read-only properties. - </para> - </step> - <step> - <para> - The Helper classes defined in SDO 2.0 are not directly implemented. - However equivalent function is provided in a more natural way for PHP. - For example the function of <command>CopyHelper::copy()</command> - is provided by applying the PHP - <link linkend='language.oop5.cloning'>clone</link> keyword to a data object. - </para> - </step> - </procedure> - </section> - - <section xml:id='sdo.examples'> - &reftitle.examples; - <para> - The examples below assume an SDO created with the schema - and instance information shown below, using the XML Data Access Service. - </para> - <para> - The instance document below describes a single company, - called 'MegaCorp', which contains a single department, - called 'Advanced Technologies'. - The Advanced Technologies department contains three employees. - The company employeeOfTheMonth is referencing the second employee, - 'Jane Doe'. - </para> - <para> - <programlisting role="xml"> -<![CDATA[ -<?xml version="1.0" encoding="UTF-8" ?> -<company xmlns="companyNS" name="MegaCorp" - employeeOfTheMonth="E0003"> - <departments name="Advanced Technologies" location="NY" number="123"> - <employees name="John Jones" SN="E0001"/> - <employees name="Jane Doe" SN="E0003"/> - <employees name="Al Smith" SN="E0004" manager="true"/> - </departments> -</company> -]]> - </programlisting> - </para> - <para> The root element of the schema is a company. The company contains departments, and - each department contains employees. Each element has a number of attributes to store - things like name, serial number, and so on. Finally, the company also has an IDREF - attribute which identifies one of the employees as the 'employeeOfTheMonth'. - </para> - <para> - <programlisting role="xml"> -<![CDATA[ -<xsd:schema - xmlns:xsd="http://www.w3.org/2001/XMLSchema" - xmlns:sdo="commonj.sdo" - xmlns:sdoxml="commonj.sdo/xml" - xmlns:company="companyNS" - targetNamespace="companyNS"> - <xsd:element name="company" type="company:CompanyType"/> - <xsd:complexType name="CompanyType"> - <xsd:sequence> - <xsd:element name="departments" type="company:DepartmentType" - maxOccurs="unbounded"/> - </xsd:sequence> - <xsd:attribute name="name" type="xsd:string"/> - <xsd:attribute name="employeeOfTheMonth" type="xsd:IDREF" - sdoxml:propertyType="company:EmployeeType"/> - </xsd:complexType> - <xsd:complexType name="DepartmentType"> - <xsd:sequence> - <xsd:element name="employees" type="company:EmployeeType" - maxOccurs="unbounded"/> - </xsd:sequence> - <xsd:attribute name="name" type="xsd:string"/> - <xsd:attribute name="location" type="xsd:string"/> - <xsd:attribute name="number" type="xsd:int"/> - </xsd:complexType> - <xsd:complexType name="EmployeeType"> - <xsd:attribute name="name" type="xsd:string"/> - <xsd:attribute name="SN" type="xsd:ID"/> - <xsd:attribute name="manager" type="xsd:boolean"/> - </xsd:complexType> -</xsd:schema> -]]> - </programlisting> - </para> - <para>The XML Data Access Service maps the schema to an SDO. Attributes such as "name" - become primitive properties, the sequence of employees becomes a many-valued - containment relationship, and so on. Note that the containment relationships are - expressed as one complex type within another, whereas non-containment references are - expressed in terms of ID and IDREF, with a special - <command>sdoxml:propertyType</command> attribute specifying the type of the - non-containment reference. - </para> - </section> - - <section xml:id="sdo.sample.getset"> - <title>Setting and Getting Property Values</title> - <para> The following examples assume - <command>$company</command> is the root of a tree of data objects created from the - schema and instance document shown above. - </para> - <para> - <example> - <title>Access via property name</title> - <para> - Data object properties can be accessed using the object property - access syntax. The following sets the company name to 'Acme'. - </para> - <programlisting role="php" xml:id="sdo.examples.propname"> -<![CDATA[ -<?php - $company->name = 'Acme'; -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Access via property name as array index</title> - <para>We can also access properties using associative array syntax. The simplest - form of this uses the property name as the array index. For example, the following sets - the company name and gets the employeeOfTheMonth. - </para> - <programlisting role="php" xml:id="sdo.examples.simplexpath"> -<![CDATA[ -<?php - $company['name'] = 'UltraCorp'; - $eotm = $company['employeeOfTheMonth']; -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Data Object iteration</title> - <para> - We can iterate over the properties of a data object using foreach. - The following iterates over the properties of the employee of the month. - </para> - <programlisting role="php" xml:id="sdo.examples.doiter"> -<![CDATA[ -<?php - $eotm = $company->employeeOfTheMonth; - foreach ($eotm as $name => $value) { - echo "$name: $value\n"; - } -?> -]]> - </programlisting> - <para> - which will output: - </para> - <programlisting xml:id="sdo.examples.doiter-output"> -<![CDATA[ -name: Jane Doe -SN: E0003 -]]> - </programlisting> - <para> - The 'manager' property is not output, because it has not been set. - </para> - </example> - </para> - - <para> - <example> - <title>Access many-valued property by name</title> - <para> Many-valued data object properties can also be accessed using the object - property name syntax. The following gets the list of departments. - </para> - <programlisting role="php" xml:id="sdo.examples.mvpname"> -<![CDATA[ -<?php - $departments = $company->departments; -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Many-valued element access</title> - <para> - We can access individual elements of many-valued properties using array - syntax. The following accesses the first department in the company. - </para> - <programlisting role="php" xml:id="sdo.examples.mvaccess"> -<![CDATA[ -<?php - $ad_tech_dept = $company->departments[0]; -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Many-valued property iteration</title> - <para> - Many-valued properties can also be iterated over using - foreach. The following iterates over the company's departments. - </para> - <programlisting role="php" xml:id="sdo.examples.mvpiter"> -<![CDATA[ -<?php - foreach ($company->departments as $department) { - // ... - } -?> -]]> - </programlisting> - <para> - Each iteration will assign the next department in the - list to the variable <command>$department</command>. - </para> - </example> - </para> - - <para> - <example> - <title>Chained property access</title> - <para> We can chain property references on a single line. - The following sets and gets the name of the first department. - </para> - <programlisting role="php" xml:id="sdo.examples.nestedprop"> -<![CDATA[ -<?php - $company->departments[0]->name = 'Emerging Technologies'; - $dept_name = $company->departments[0]->name; -?> -]]> - </programlisting> - <para>Using the associative array syntax, this is equivalent to</para> - <programlisting role="php" xml:id="sdo.examples.chainarray"> -<![CDATA[ -<?php - $company['departments'][0]['name'] = 'Emerging Technologies'; - $dept_name = $company['departments'][0]['name']; -?> -]]> - </programlisting> - <para> In either case, the dept_name variable is set to 'Emerging Technologies'. - </para> - </example> - </para> - - <para> - <example> - <title>XPath navigation</title> - <para> The associative array index can be an XPath-like expression. Valid - expressions are defined by an augmented sub-set of XPath. - </para> - <para> - Two forms of indexing into many-valued properties are supported. - The first is the standard XPath array syntax with the indexing - starting at one, the second is an SDO extension to XPath with an index - starting at zero. The standard syntax is: - </para> - <programlisting role="php" xml:id="sdo.examples.xpath1nav"> -<![CDATA[ -<?php - $jane_doe = $company["departments[1]/employees[2]"]; -?> -]]> - </programlisting> - <para>and the SDO XPath extension syntax is:</para> - <programlisting role="php" xml:id="sdo.examples.xpath0nav"> -<![CDATA[ -<?php - $jane_doe = $company["departments.0/employees.1"]; -?> -]]> - </programlisting> - <para> - Both these examples get the second employee from the first department. - </para> - </example> - </para> - - <para> - <example> - <title>XPath querying</title> - <para> - We can use XPath to query and identify parts of a data object based - on instance data. The following retrieves the manager from the - 'Advanced Technologies' department. - </para> - <programlisting role="php" xml:id="sdo.examples.xpathquery"> - <![CDATA[ -<?php - $ad_tech_mgr = - $company["departments[name='Advanced Technologies']/employees[manager=true]"]; -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Creating child data objects</title> - <para> - A data object can be a factory for its child data objects. - A child data object is automatically part of the data graph. - The following add a new employee to the 'Advanced Technologies' - department. - </para> - <programlisting role="php" xml:id="sdo.examples.create"> -<![CDATA[ -<?php - $ad_tech_dept = $company["departments[name='Advanced Technologies']"]; - $new_hire = $ad_tech_dept->createDataObject('employees'); - $new_hire->name = 'John Johnson'; - $new_hire->SN = 'E0005'; - $new_hire->manager = false; -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Unset a primitive property</title> - <para> - We can use the <function>isset</function> and - <function>unset</function> functions to test and remove items - from the data object. - </para> - <para> - The following clears the name of the first department. - </para> - <programlisting role="php" xml:id="sdo.examples.unsetprim"> -<![CDATA[ -<?php - unset($company->departments[0]->name); -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Unset a data object</title> - <para> - unset can also be used to remove a data object from the tree. - The following example shows John Jones leaving the company. - </para> - <programlisting role="php" xml:id="sdo.examples.unsetdo"> -<![CDATA[ -<?php - unset($company->departments[0]->employees[0]); -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Unset a referenced data object</title> - <para> - The following removes the 'employeeOfTheMonth' from the company. - If this were a containment relationship then the - employee would be removed from the company - (probably not a good idea to sack your best employee each month!), - but since this is a non-containment reference, - the employee being referenced will remain in the - department in the company, - but will no longer be accessible via the employeeOfTheMonth property. - </para> - <programlisting role="php" xml:id="sdo.examples.unsetrefdo"> -<![CDATA[ -<?php - if (isset($company->employeeOfTheMonth)) { - unset($company->employeeOfTheMonth); - } -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Access via property index</title> - <para> Data object properties can be accessed via their property index using array - syntax. The property index is the position at which the property's definition - appears in the model (in this case the xml schema). We can see from the schema listing - above that the company name attribute is the second company property (the SDO - interface makes no distinction between XML attributes and elements). The following - sets the company name to 'Acme', with the same result as - <link linkend="sdo.examples.propname">Access via property name</link> - </para> - <programlisting role="php" xml:id="sdo.examples.propindex"> -<![CDATA[ -<?php - $company[1] = 'Acme'; -?> -]]> - </programlisting> - <para> Using the index directly in this way is likely to be fragile. Normally the - property name syntax should be preferred, but the property index may be required - in special cases. - </para> - </example> - </para> - - </section> - - <section xml:id="sdo.sample.sequence"> - <title>Working with Sequenced Data Objects</title> - <para> - Sequenced data objects are SDOs which can track property - ordering across the properties of a data object. They can also - contain unstructured text elements (text element which do not - belong to any of the SDO's properties). Sequenced data objects are - useful for working with XML documents which allow unstructured text (i.e. - mixed=true) or if the elements can be interleaved ( - <![CDATA[<A/><B/><A/>]]>). This can occur for example when - the schema defines maxOccurs>1 on a - element which is a complexType with a choice order indicator. - </para> - <para> - The examples below assume an SDO created with the following schema - and instance information, using the XML Data Access Service. - </para> - <para> - The schema below describes the format of a letter. The letter can - optionally contain three properties; date, firstName, and lastName. - The schema states <command>mixed="true"</command> which means that - unstructured text can be interspersed between the three properties. - </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> - The following is an instance letter document. It contains the - three letter properties; date, firstName and lastName, and has - unstructured text elements for the address and letter body. - </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> - <para> - When loaded, the letter data object will have the sequence and - property indices shown in the table below: - <informaltable> - <tgroup cols='3'> - <thead> - <row> - <entry>Sequence Index</entry> - <entry>Property Index:Name</entry> - <entry>Value</entry> - </row> - </thead> - <tbody> - <row> - <entry>0</entry> - <entry>0:date</entry> - <entry>March 1, 2005</entry> - </row> - <row> - <entry>1</entry> - <entry>-</entry> - <entry>Mutual of Omaha</entry> - </row> - <row> - <entry>2</entry> - <entry>-</entry> - <entry>Wild Kingdom, USA</entry> - </row> - <row> - <entry>3</entry> - <entry>-</entry> - <entry>Dear</entry> - </row> - <row> - <entry>4</entry> - <entry>1:firstName</entry> - <entry>Casy</entry> - </row> - <row> - <entry>5</entry> - <entry>2:lastName</entry> - <entry>Crocodile</entry> - </row> - <row> - <entry>6</entry> - <entry>-</entry> - <entry>Please buy more shark repellent.</entry> - </row> - <row> - <entry>7</entry> - <entry>-</entry> - <entry>Your premium is past due.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - - <para> - To ensure sequence indices are maintained, sequenced data objects - should be manipulated through the SDO_Sequence interface. - This allows the data object's instance data to be manipulated - in terms of the sequence index as opposed to the property index - (shown in the table above). - The following examples assume the letter instance has been - loaded into a data object referenced by the variable - <command>$letter</command>. - <example> - <title>Getting the SDO_Sequence interface</title> - <para> - We obtain a data object's sequence using the - <function>getSequence</function> - method. The follow gets the - sequence for the letter data object. - </para> - <programlisting role="php" xml:id="sdo.examples.seqinterface"> -<![CDATA[ -<?php - $letter_seq = $letter->getSequence(); -?> -]]> - </programlisting> - </example> - </para> - <para> - All subsequent examples assume that the - <command>$letter_seq</command> - variable has been assigned the sequence for the letter data object. - </para> - - <para> - <example> - <title>Get/set sequence values</title> - <para> - We can get and set individual values (including unstructured text) - using the sequence index. - The following sets the firstName to 'Snappy' and gets the last - sequence values (the unstructured text, 'Your premium is past due.'). - </para> - <programlisting role="php" xml:id="sdo.examples.getsetseq"> -<![CDATA[ -<?php - $letter_seq[4] = 'Snappy'; - $text = $letter_seq[count($letter_seq) - 1]; -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Sequence iteration</title> - <para> - We can iterate through the individual sequence values using foreach. - The following runs through the individual values in sequence order. - </para> - <programlisting role="php" xml:id="sdo.examples.seqiter"> -<![CDATA[ -<?php - foreach ($letter->getSequence() as $value) { - // ... - } -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Sequence versus Data Object</title> - <para> - Setting values through the data object interface may result in the - value not being part of the sequence. A value set through the data - object will only be accessible through the sequence if the property was - already part of the sequence. The following example sets the - lastName through the data object and gets it through the sequence. - This is fine because lastName already exists in the sequence. If - it had not previously been set, then lastName would be set to - 'Smith', but would not be part of the sequence. - </para> - <programlisting role="php" xml:id="sdo.examples.seqvsdo"> -<![CDATA[ -<?php - $letter[2] = 'Smith'; - $last_name = $letter_seq[5]; -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Adding to a sequence</title> - <para> - We can add new values to a sequence using the - <link linkend='function.SDO-Sequence-insert'><function>SDO_Sequence::insert</function></link> - method. The following examples assume that the 'firstName' and - 'lastName' properties are initially unset. - </para> - <programlisting role="php" xml:id="sdo.examples.seqadd"> -<![CDATA[ -<?php - // Append a firstName value to the sequence - // value: 'Smith' - // sequence index: NULL (append) - // propertyIdentifier: 1 (firtName property index) - $letter_seq->insert('Smith', NULL, 1); - - // Append a lastName value to the sequence - // value: 'Jones' - // sequence index: NULL (append) - // propertyIdentifier: 'lastName' (lastName property name) - $letter_seq->insert('Jones', NULL, 'lastName'); - - // Append unstructured text - // value: 'Cancel Subscription.' - // sequence index: absent (append) - // propertyIdentifier: absent (unstructured text) - $letter_seq->insert('Cancel Subscription.'); - - // Insert new unstructured text. Subsequent sequence values - // are shifted up. - // value: 'Care of:' - // sequence index: 1 (insert as second element) - // propertyIdentifier: absent (unstructured text) - $letter_seq->insert('Care of:', 1); -?> -]]> - </programlisting> - </example> - </para> - - <para> - <example> - <title>Removing from a sequence</title> - <para> - We can use the <function>isset</function> and - <function>unset</function> functions to test and remove items - from the sequence (Note: <function>unset</function> currently - leaves the values in the data object, but this behaviour is - likely to change to also remove the data from the data object). - A sequence behaves like a contiguous list; therefore, removing - items from the middle will shift entries at higher indices - down. The following example tests to see if the first sequence - element is set and unsets it if is. - </para> - <programlisting role="php" xml:id="sdo.examples.seqremove"> -<![CDATA[ -<?php - if (isset($letter_seq[0])) { - unset($letter_seq[0]); - } -?> -]]> - </programlisting> - </example> - </para> - - </section> - - - <section xml:id="sdo.sample.reflection"> - <title>Reflecting on Service Data Objects</title> - <para> - SDOs have a knowledge of the structure they have been created to - represent (the model). For example, a Company SDO created using - <link linkend="sdo.examples">the Company XML schema</link> above - would only be permitted to contain DepartmentType data objects - which in turn could only contain EmployeeType data objects. - </para> - <para> - Sometimes it is useful to be able to access this model information at - runtime. For example, this could be used to automatically generate - a user interface for populating a data object. The model information - is accessed using reflection. - </para> - - <para> - <example> - <title>Reflecting on a Data Object</title> - <para> - The following example shows how we can reflect on an empty Employee - data object. - </para> - <programlisting role="php" xml:id="sdo.examples.reflection"> -<![CDATA[ -<?php - // Create the employee data object (e.g. from an XML Data Access Service) - $employee = ...; - $reflection = new SDO_Model_ReflectionDataObject($employee); - print($reflection); -?> -]]> - </programlisting> - &example.outputs; - - <screen> -<![CDATA[ -object(SDO_Model_ReflectionDataObject)#4 { - ROOT OBJECT - Type { -companyNS:EmployeeType[3] { commonj.sdo:String $name; -commonj.sdo:String $SN; commonj.sdo:Boolean $manager; } } -]]> - </screen> - <para> - Using print on the SDO_Model_ReflectionDataObject writes out the data - object's model. We can see from the output how the type - companyNS:EmployeeType has three properties and we can see the names - of the properties along with their types. Note, the primitive types - are listed as SDO types (e.g. commonj.sdo namespace, String type). - It is worth noting that this is the SDO model and when these are - surfaced to an application they can be treated as the PHP equivalent - types (e.g. string and boolean). - </para> - </example> - </para> - - <para> - <example> - <title>Accessing the type information</title> - <para> - We can query the type information of a data object using reflection. - The following example checks the type corresponds to a data object - rather than a primitive and then iterates through the properties of - the type, writing out the name of each property ($type and $property - are SDO_Model_Type and SDO_Model_Property objects, respectively). - </para> - <programlisting role="php" xml:id="sdo.examples.reflection.type"> -<![CDATA[ -<?php - // Create the employee data object (e.g. from an XML Data Access Service) - $employee = ...; - $reflection = new SDO_Model_ReflectionDataObject($employee); - $type = $reflection->getType(); - if (! $type->isDataType()) { - foreach ($type->getProperties() as $property) { - print $property->getName() . "\n"; - } - } -?> -]]> - </programlisting> - &example.outputs; - <screen> -<![CDATA[ -name -SN -manager -]]> - </screen> - </example> - </para> - - </section> - - - - +   <section xml:id='sdo.classes'> @@ -1718,8 +645,6 @@ </section> </section> - &reference.sdo.constants; - </partintro> &reference.sdo.entities.functions;