cem Fri Mar 24 15:46:38 2006 UTC
Modified files:
/phpdoc/en/reference/sdo reference.xml
Log:
Updates for 1.0 release
http://cvs.php.net/viewcvs.cgi/phpdoc/en/reference/sdo/reference.xml?r1=1.21&r2=1.22&diff_format=u
Index: phpdoc/en/reference/sdo/reference.xml
diff -u phpdoc/en/reference/sdo/reference.xml:1.21
phpdoc/en/reference/sdo/reference.xml:1.22
--- phpdoc/en/reference/sdo/reference.xml:1.21 Fri Feb 24 18:36:41 2006
+++ phpdoc/en/reference/sdo/reference.xml Fri Mar 24 15:46:38 2006
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.21 $ -->
+<!-- $Revision: 1.22 $ -->
<!-- Purpose: database.abstract -->
<!-- Membership: pecl -->
<!-- State: experimental -->
@@ -10,12 +10,7 @@
<partintro>
<section id="sdo.intro">
- &reftitle.intro;
- <para>
- <!-- This warns that the extension is experimental -->
- &warn.experimental;
- </para>
-
+ &reftitle.intro;
<para>
Service Data Objects (SDOs) enable PHP applications to work with
data from different sources (like a database query, an XML file,
@@ -28,7 +23,7 @@
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).
+ to a data source, typically the same one.
</para>
<para>
See the
@@ -40,10 +35,10 @@
Access Services Interface</link> for more details).
</para>
<para>
- This extension is derived from concepts taken from the
- <ulink url='&url.ibm.sdo;'>
- Service Data Objects specification
- </ulink>
+ This extension is derived from concepts taken from the
+ <ulink url="&url.ibm.sdo;">Service Data Objects specification</ulink>.
+ It includes a version of the
+ <ulink url="&url.apache.tuscany;">Apache Tuscany</ulink> SDO 2.0 for C++
project.
</para>
<section id="sdo.intro.structure">
@@ -54,16 +49,10 @@
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.
- Deleting a data object which has a containment relationship to another
- data object will also delete the contained data object. For example,
- deleting the Company data object will also delete 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. Deleting a data object
- which has a non-containment reference to another data object does
- not delete the referenced data object.
+ <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
@@ -71,187 +60,115 @@
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 id="sdo.requirements">
&reftitle.required;
- <para>
- The SDO extension requires PHP 5.1 or higher.
- </para>
- <para>
- SDO <link linkend="ref.sdo-das-xml">XML Data Access Service</link>,
- which is built as part of this extension, requires libxml2
- (Tested with libxml2 2.6.19) which can be downloaded from
+ <para> The SDO extension requires PHP 5.1 or higher. It also requires the
libxml2 library.
+ Normally libxml2 will already be installed, but if not, it can be
downloaded from
<ulink url='&url.libxml;'>&url.libxml;</ulink>.
</para>
</section>
<section id="sdo.installation">
&reftitle.install;
- <para>
- There are several options, depending on whether you are installing on
- Windows or Linux, and depending on whether you are installing a released
- version (a .tgz file from the PECL site) or the latest from CVS.
- The Relational DAS also needs special attention as it is written in
- PHP.
- </para>
- <para> The instructions are likely to change as PHP 5.1 progresses in
status from beta to
- stable release. The instructions here were correct on 6th October 2005,
when PHP
- 5.1.0RC1 was the current release candidate for PHP, and 0.5.2 was the
current beta
- release of SDO.
- </para>
- <para>
- The options are summarised in the following table:
- <informaltable>
- <tgroup cols='3'>
- <thead>
- <row>
- <entry>latest/Release</entry>
- <entry>Windows</entry>
- <entry>Linux</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- latest CVS
- </entry>
- <entry>
- <itemizedlist>
- <listitem>
- <para>
- The latest DLLs for the SDO core and the XML DAS can be
- downloaded from
- <ulink url='&url.pecl.win.ext;php_sdo.dll'>php_sdo</ulink> and
- <ulink url='&url.pecl.win.ext;php_sdo_das_xml.dll'>php_sdo_das_xml
- </ulink> respectively.
- </para>
- </listitem>
- <listitem>
- <para>
- Check out the Relational DAS from CVS to somewhere on the
- PHP
- <link linkend="ini.include-path">include_path</link>.
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- <entry>
- <itemizedlist>
- <listitem>
- <para>
- Check out the SDO core and the XML DAS from CVS
- and build according to the instructions
- below for building on Linux.
- </para>
- </listitem>
- <listitem>
- <para>
- Check out the Relational DAS from CVS to somewhere on the
- PHP
- <link linkend="ini.include-path">include_path</link>.
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- <row>
- <entry>
- Release
- </entry>
- <entry>
- <itemizedlist>
- <listitem>
- <para>
- There is currently no way provided for building the release
- version of the SDO core and XML DAS on a user's machine.
- You will only be able to pick up the latest DLLs from the
- snaps site (see previous row of this table).
- </para>
- </listitem>
- <listitem>
- <para>
- The Relational DAS can be downloaded and installed with
- the command:
- </para>
- <para>
- <command>
- pear install -B <package name and level>
- </command>
- </para>
- <para>
- Substitute the desired package name and level, for example
- <varname>sdo-0.5.2</varname>, in the command above.
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- <entry>
- <itemizedlist>
- <listitem>
- <para>
- You can download and install all three SDO components - the
- SDO core, the XML DAS and the Relational DAS - with the
- command:
- </para>
- <para>
- <command>
- pear install <package name and level>
- </command>
- </para>
- <para>
- Substitute the desired package name and level, for example
- <varname>sdo-0.5.2</varname>, in the command above.
- </para>
- <para>
- This command will build the SDO and XML shared libraries as well
- as installing the PHP files that make the Relational DAS.
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Regardless of which platform or which level of the code you have installed
- you will need add the two extension libraries to your &php.ini; file.
- On Windows, add:
- <programlisting role="php" id="sdo.installation.ini.windows">
-<![CDATA[
-extension=php_sdo.dll
-extension=php_sdo_das_xml.dll
-]]>
- </programlisting>
- On Linux, add:
- <programlisting role="php" id="sdo.installation.ini.linux">
+ <procedure id='sdo.install.unix'>
+ <title>Unix systems</title>
+ <step>
+ <para> You can download and install the latest stable release of all
three SDO
+ components - the SDO core, the XML DAS and the Relational DAS - with
the command:
+ <screen> <![CDATA[
+pear install sdo
+]]>
+ </screen>
+ </para>
+ <para> This command will build the SDO and XML shared libraries as well
as installing
+ the PHP files that make the Relational DAS.
+ </para>
+ <para>
+ If you want to use the latest beta version, then instead run:
+ <screen>
<![CDATA[
+pear install sdo-beta
+]]>
+ </screen>
+ </para>
+ </step>
+ <step>
+ <para> The
+ <command>pear</command> command automatically installs the SDO and
SDO_DAS_XML
+ modules into your PHP extensions directory. To enable the SDO extensions
you must add
+ the following lines to &php.ini;:
+ <screen> <![CDATA[
extension=sdo.so
extension=sdo_das_xml.so
]]>
- </programlisting>
- You may also need to update your
- <link linkend="ini.extension-dir">extension_dir</link>
- in &php.ini; to point to the location of these libraries.
- </para>
+ </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 id='sdo.install.win32'>
+ <title>Windows</title>
+ <step>
+ <para>
+ The latest DLLs for the SDO core and the XML DAS can be
+ downloaded from
+ <ulink url='&url.pecl.win.ext;php_sdo.dll'>php_sdo.dll</ulink> and
+ <ulink
url='&url.pecl.win.ext;php_sdo_das_xml.dll'>php_sdo_das_xml.dll</ulink>
respectively.
+ </para>
+ <para>
+ Note that currently the <ulink url='&url.pecl.win;'>pecl4win</ulink>
site does not provide
+ these binaries at the current release level; you can only download the
latest level.
+ </para>
+ </step>
+ <step>
+ <para> The
+ <command>pear</command> command automatically installs the SDO and
SDO_DAS_XML
+ modules into your PHP extensions directory. To enable the SDO extensions
you must add
+ the following lines to &php.ini;:
+ <screen>
+ <![CDATA[
+extension=php_sdo.dll
+extension=php_sdo_das_xml.dll
+]]>
+ </screen>
+ </para>
+ </step>
+ <step>
+ <para> The Relational DAS can be downloaded and installed with the
command:
+ <screen>
+ <![CDATA[
+pear 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>
- <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>
<procedure 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.
- Currently 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> 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>
@@ -267,8 +184,8 @@
</step>
<step>
<para>
- Next, run <command>./configure; make; make install</command>. Please
- note, you may need to login as root to install the extension.
+ Next, run <command>./configure; make; make install</command>.
+ Please note, you may need to login as root to install the extension.
</para>
</step>
<step>
@@ -276,7 +193,7 @@
Make sure that these modules are loaded by PHP, by adding
<command>extension=sdo.so</command> and
<command>extension=sdo_das_xml.so</command> to your
- <filename>php.ini</filename> file in the same order.
+ &php.ini; file in the same order.
</para>
</step>
</procedure>
@@ -301,8 +218,7 @@
</entry>
<entry>
An XML Data Access Service supporting reading/writing
- SDOs as XML documents or via a Web URL to supporting things like
- RSS feeds.
+ SDOs as XML documents.
</entry>
</row>
<row>
@@ -311,7 +227,7 @@
</entry>
<entry>
A PDO-based Data Access Service supporting reading/writing SDO
- to relational data sources.
+ to relational databases.
Implements an optimistic concurrency policy for updates.
</entry>
</row>
@@ -331,6 +247,9 @@
<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>
@@ -344,16 +263,6 @@
</para>
<step>
<para>
- Abstract types and type derivation.
- </para>
- </step>
- <step>
- <para>
- Open types.
- </para>
- </step>
- <step>
- <para>
Bi-directional relationships.
</para>
</step>
@@ -368,13 +277,12 @@
</para>
</step>
<step>
- <para>
- XMLHelper/XSDHelper (the XML DAS provides a lot of this functionality)
- </para>
- </step>
- <step>
- <para>
- TypeHelper (the SDO_DAS_DataFactory provides this functionality)
+ <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>
@@ -387,14 +295,32 @@
and instance information shown below, using the XML Data Access Service.
</para>
<para>
- The schema describes a company data object.
- The company contains department data objects, and
- each department contains employee data objects.
- Each data object has a number of primitive properties to describe things
- like name, serial number, etc.
- Finally, the company data object also has a non-containment reference
- to one of the employee data objects to identify them as the
- 'employeeOfTheMonth'.
+ 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">
@@ -409,15 +335,16 @@
<xsd:complexType name="CompanyType">
<xsd:sequence>
<xsd:element name="departments" type="company:DepartmentType"
- maxOccurs="unbounded"/>
+ maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string"/>
<xsd:attribute name="employeeOfTheMonth" type="xsd:IDREF"
-sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
+ sdoxml:propertyType="company:EmployeeType"/>
+ </xsd:complexType>
<xsd:complexType name="DepartmentType">
<xsd:sequence>
<xsd:element name="employees" type="company:EmployeeType"
- maxOccurs="unbounded"/>
+ maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string"/>
<xsd:attribute name="location" type="xsd:string"/>
@@ -432,52 +359,32 @@
]]>
</programlisting>
</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="#/departments.0/employees.1">
- <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>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 id="sdo.sample.getset">
<title>Setting and Getting Property Values</title>
- <para>
- The following examples assume <command>$company</command> is a data
- object created from the schema and instance document shown above.
+ <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 names</title>
+ <title>Access via property name</title>
<para>
Data object properties can be accessed using the object property
- access syntax. The following gets the list of departments
- (containing a single department), and sets the company name to 'Acme'.
+ access syntax. The following sets the company name to 'Acme'.
</para>
<programlisting role="php" id="sdo.examples.propname">
<![CDATA[
<?php
- $departments = $company->departments;
$company->name = 'Acme';
?>
]]>
@@ -487,24 +394,16 @@
<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 departments element
- is the first company property defined and the company name attribute
- is the second company property (the SDO interface makes no distinction
- between XML attributes and elements).
- The following gets the list of departments (containing a single
- department), and sets the company name to 'Acme'.
+ <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" id="sdo.examples.propindex">
+ <programlisting role="php" id="sdo.examples.simplexpath">
<![CDATA[
<?php
- $departments = $company[0];
- $company[1] = 'Acme';
+ $company['name'] = 'UltraCorp';
+ $eotm = $company['employeeOfTheMonth'];
?>
]]>
</programlisting>
@@ -513,59 +412,55 @@
<para>
<example>
- <title>Data Object Iteration</title>
+ <title>Data Object iteration</title>
<para>
We can iterate over the properties of a data object using foreach.
- The following iterates over the company properties; name,
- departments and employeeOfTheMonth.
+ The following iterates over the properties of the employee of the month.
</para>
<programlisting role="php" id="sdo.examples.doiter">
<![CDATA[
<?php
- foreach ($company as $name => $value) {
- // ...
+ $eotm = $company->employeeOfTheMonth;
+ foreach ($eotm as $name => $value) {
+ echo "$name: $value\n";
}
?>
]]>
</programlisting>
- <para>
- For the first iteration, $name will be 'name' and $value
- will be 'Acme'. For the second iteration, $name will be
- 'departments' and $value will be an SDO_List (because departments is a
- many-valued property (stated <command>maxOccurs="unbouded"</command>
- in the schema)) containing a single data object of type DepartmentType.
- For the third iteration, $name will be 'employeeOfTheMonth' and $value
- will be a data object of type EmployeeType.
+ <para>
+ which will output:
+ </para>
+ <programlisting 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>Many-valued Property Iteration</title>
- <para>
- Many-valued properties can also be iterated over using
- foreach. The following iterates over the company's departments.
+ <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" id="sdo.examples.mvpiter">
+ <programlisting role="php" id="sdo.examples.mvpname">
<![CDATA[
<?php
- foreach ($company->departments as $department) {
- // ...
- }
+ $departments = $company->departments;
?>
]]>
</programlisting>
- <para>
- Each iteration will assign the next department in the
- list to the variable <command>$department</command>.
- </para>
</example>
</para>
-
+
<para>
<example>
- <title>Many-valued Element Access</title>
+ <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.
@@ -582,98 +477,101 @@
<para>
<example>
- <title>Nested Property Access</title>
+ <title>Many-valued property iteration</title>
<para>
- We can use nested property access to navigate the data object
- instance structure. The following gets and sets the name of the first
- department.
+ Many-valued properties can also be iterated over using
+ foreach. The following iterates over the company's departments.
</para>
- <programlisting role="php" id="sdo.examples.nestedprop">
+ <programlisting role="php" id="sdo.examples.mvpiter">
<![CDATA[
<?php
- $dept_name = $company->departments[0]->name;
- $company->departments[0]->name = 'Emerging Technologies';
+ 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>Simple XPath support</title>
- <para>
- We can access properties using XPath-like (an augmented
- sub-set of XPath) expressions, the simplest form of which is the
- property name.
- The following sets the company name and gets the employeeOfTheMonth.
+ <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" id="sdo.examples.simplexpath">
+ <programlisting role="php" id="sdo.examples.nestedprop">
<![CDATA[
<?php
- $company['name'] = 'UltraCorp';
- $eotm = $company['employeeOfTheMonth'];
+ $company->departments[0]->name = 'Emerging Technologies';
+ $dept_name = $company->departments[0]->name;
?>
]]>
</programlisting>
- </example>
- </para>
-
- <para>
- <example>
- <title>Simple XPath support</title>
- <para>
- We can use chained array access calls to navigate the data
- object instance structure. The following gets and sets the name of the
- first department.
- </para>
+ <para>Using the associative array syntax, this is equivalent to</para>
<programlisting role="php" id="sdo.examples.chainarray">
<![CDATA[
<?php
- $dept_name = $company['departments'][0]['name'];
$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>
+ <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>
- We can use XPath expressions to navigate the data object
- instance structure. Two forms of indexing into many-valued
- properties are supported.
+ 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 following both get the second employee from the
- first department.
+ starting at zero. The standard syntax is:
</para>
- <programlisting role="php" id="sdo.examples.xpathnav">
+ <programlisting role="php" 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" 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>
+ <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" id="sdo.examples.xpathquery">
-<![CDATA[
+ <![CDATA[
<?php
$ad_tech_mgr =
- $company["departments[name=\"Advanced
Technologies\"]/employees[manager=\"true\"]"];
+ $company["departments[name='Advanced
Technologies']/employees[manager=true]"];
?>
]]>
</programlisting>
@@ -682,7 +580,7 @@
<para>
<example>
- <title>Creating child data object</title>
+ <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.
@@ -692,7 +590,7 @@
<programlisting role="php" id="sdo.examples.create">
<![CDATA[
<?php
- $ad_tech_dept = $company["departments[name=\"Advanced Technologies\"]"];
+ $ad_tech_dept = $company["departments[name='Advanced Technologies']"];
$new_hire = $ad_tech_dept->createDataObject('employees');
$new_hire->name = 'John Johnson';
$new_hire->SN = 'E0005';
@@ -705,13 +603,46 @@
<para>
<example>
- <title>Unset referenced data object</title>
+ <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" 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" 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
@@ -732,6 +663,32 @@
</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" 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 id="sdo.sample.sequence">
