mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
Updates for 1.0 release
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@210045 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Caroline Maynard
parent
b192bcffaf
commit
e473248a91
1 changed files with 304 additions and 347 deletions
|
|
@ -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 @@ extension=sdo_das_xml.so
|
|||
</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 @@ extension=sdo_das_xml.so
|
|||
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 @@ extension=sdo_das_xml.so
|
|||
</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 @@ extension=sdo_das_xml.so
|
|||
</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 @@ extension=sdo_das_xml.so
|
|||
<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>
|
||||
|
|
@ -342,16 +261,6 @@ extension=sdo_das_xml.so
|
|||
It is not necessarily the case that these will all be added over time.
|
||||
Their inclusion will depend on community requirements.
|
||||
</para>
|
||||
<step>
|
||||
<para>
|
||||
Abstract types and type derivation.
|
||||
</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>
|
||||
Open types.
|
||||
</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>
|
||||
Bi-directional relationships.
|
||||
|
|
@ -368,13 +277,12 @@ extension=sdo_das_xml.so
|
|||
</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 @@ extension=sdo_das_xml.so
|
|||
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 @@ extension=sdo_das_xml.so
|
|||
<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 @@ sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
|
|||
]]>
|
||||
</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>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>
|
||||
|
||||
<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>
|
||||
|
||||
</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 @@ sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
|
|||
|
||||
<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,36 +412,72 @@ sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
|
|||
|
||||
<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>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.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" id="sdo.examples.mvaccess">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$ad_tech_dept = $company->departments[0];
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title>Many-valued Property Iteration</title>
|
||||
<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.
|
||||
|
|
@ -565,115 +500,78 @@ sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
|
|||
|
||||
<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" id="sdo.examples.mvaccess">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$ad_tech_dept = $company->departments[0];
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title>Nested Property Access</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.
|
||||
<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.nestedprop">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$dept_name = $company->departments[0]->name;
|
||||
$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 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.
|
||||
</para>
|
||||
<programlisting role="php" id="sdo.examples.simplexpath">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$company['name'] = 'UltraCorp';
|
||||
$eotm = $company['employeeOfTheMonth'];
|
||||
?>
|
||||
]]>
|
||||
</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 @@ sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
|
|||
|
||||
<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 @@ sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
|
|||
<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,12 +603,45 @@ sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
|
|||
|
||||
<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
|
||||
|
|
@ -732,6 +663,32 @@ sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
|
|||
</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">
|
||||
|
|
|
|||
Loading…
Reference in a new issue